3.3.6

Amanda::Taper::Scan modules list
Amanda::Taper modules list
Amanda modules list
List of All Modules
All Amanda Releases

Amanda::Taper::Scan


NAME

Amanda::Taper::Scan


SYNOPSIS

This is an abstract base class for taperscan algorithms.

  # open the taperscan algorithm specified in the config
  my $taperscan = Amanda::Taperscan->new(
        changer => $changer);
  my $result_cb = make_cb(result_cb => sub {
    my ($err, $reservation, $label, $access_mode, $is_new) = @_;
    die $err if $err;
    # write to $reservation->{'device'}, using label $label, and opening
    # the device with $access_mode (one of $ACCESS_WRITE or $ACCESS_APPEND)
    # $is_new is set to 1 if the volume is not already labeled.
    # ..
  });
  my $user_msg_fn = sub {
    print "$_[0]\n";
  };
  $taperscan->scan(result_cb => $result_cb, user_msg_fn => $user_msg_fn);
  # later ..
  $taperscan->quit(); # also quit the changer


OVERVIEW

Amanda::Taper::Scan subclasses represent algorithms used by Amanda::Taper::Scribe (see Amanda::Taper::Scribe) to scan for and select volumes for writing.

Call Amanda::Taperscan->new() to create a new taperscan algorithm. The constructor takes the following keyword arguments:

    changer       Amanda::Changer object to use (required)
    algorithm     Taperscan algorithm to instantiate
    tapelist      Amanda::Tapelist
    tapecycle
    labelstr
    autolabel
    meta_autolabel

The changer object must always be provided, but algorithm may be omitted, in which case the class specified by the user in the Amanda configuration file is instantiated. The remaining options will be taken from the configuration file if not specified. Default values for all of these options are applied before a subclass's constructor is called.

The autolabel option should look like the CNF_AUTOLABEL hash - see Amanda::Config.

Subclasses must implement a single method: scan. It takes only one mandatory parameter, result_cb:

  $taperscan->scan(
    result_cb => $my_result_cb,
    user_msg_fn => $fn,
    );

If user_msg_fn is specified, then it is called with user-oriented messages to indicate the progress of the scan.

The result_cb takes the following positional parameters:

  $error        an error message, or undef on success
  $reservation  Amanda::Changer::Reservation object
  $label        label to apply to the volume
  $access_mode  access mode with which to start the volume

The error message can be a simple string or an Amanda::Changer::Error object (see Amanda::Changer). The $label and $access_mode specify parameters for starting the device contained in $reservation.

To cleanly terminate an Amanda::Taper::Scan object:

  $taperscan->quit()

It also terminate the changer by caller $chg->quit().


SUBCLASS UTILITIES

There are a few common tasks for subclasses that are implemented as methods in the parent class. Note that this class assumes subclasses will be implemented as blessed hashrefs, and sets keys corresponding to the constructor arguments.

To read the tapelist, call read_tapelist. This method caches the result in $self->{'tapelist'}, which will be used by the other functions here. In general, call read_tapelist at most once per scan() invocation.

To see if a volume is reusable, call the is_reusable_volume method. This takes several keyword parameters:

    $self->is_reusable_volume(
        label => $label,         # label to check
        new_label_ok => $nlo,    # count newly labeled vols as reusable?
    );

Similarly, to calculate the oldest reusable volume, call oldest_reusable_volume:

    $self->oldest_reusable_volume(
        new_label_ok => $nlo,    # count newly labeled vols as reusable?
    );

user_msg_fn

This interface is temporary and will change in the next release.

Initiate a load by label:

  user_msg_fn(search_label => 1,
                   label        => $label);

The result of a load by label:

  user_msg_fn(search_result => 1,
                   res           => $res,
                   err           => $err);

Initiate the scan of the slot $slot:

  $self->user_msg_fn(scan_slot => 1,
                     slot      => $slot);

Initiate the scan of the slot $slot which should have the label $label:

  $self->user_msg_fn(scan_slot => 1,
                     slot      => $slot,
                     label     => $label);

The result of scanning slot $slot:

  $self->user_msg_fn(slot_result => 1,
                     slot        => $slot,
                     err         => $err,
                     res         => $res);

The result if the read label doesn't match the labelstr:

  user_msg_fn(slot_result             => 1,
                   does_not_match_labelstr => 1,
                   labelstr                => $labelstr,
                   slot                    => $slot,
                   res                     => $res);

The result if the read label is not in the tapelist:

  user_msg_fn(slot_result     => 1,
                   not_in_tapelist => 1,
                   slot            => $slot,
                   res             => $res);

The result if the read label can't be used because it is active:

  user_msg_fn(slot_result => 1,
                   active      => 1,
                   slot        => $slot,
                   res         => $res);

The result if the volume can't be labeled because autolabel is not set:

  user_msg_fn(slot_result => 1,
                   not_autolabel => 1,
                   slot          => $slot,
                   res           => $res);

The result if the volume is empty and can't be labeled because autolabel setting:

  user_msg_fn(slot_result => 1,
                   empty         => 1,
                   slot          => $slot,
                   res           => $res);

The result if the volume is a non-amanda volume and can't be labeled because autolabel setting:

  user_msg_fn(slot_result => 1,
                   non_amanda    => 1,
                   slot          => $slot,
                   res           => $res);

The result if the volume is in error and can't be labeled because autolabel setting:

  user_msg_fn(slot_result => 1,
                   volume_error  => 1,
                   err           => $err,
                   slot          => $slot,
                   res           => $res);

The result if the volume is in error and can't be labeled because autolabel setting:

  user_msg_fn(slot_result => 1,
                   not_success   => 1,
                   err           => $err,
                   slot          => $slot,
                   res           => $res);

The scan has failed, possibly with some additional information as to what the scan was looking for.

  user_msg_fn(scan_failed => 1,
              expected_label => $label, # optional
              expected_new => 1); # optional


ABOUT THIS PAGE

This page was automatically generated Wed Oct 1 11:07:14 2014 from the Amanda source tree, and documents the most recent development version of Amanda. For documentation specific to the version of Amanda on your system, use the 'perldoc' command.


3.3.6