Amanda::Changer -- interface to changer scripts
use Amanda::Changer;
my $chg = Amanda::Changer->new(); # loads the default changer; OR
$chg = Amanda::Changer->new("somechanger"); # references a defined changer in amanda.conf
$chg->load(
label => "TAPE-012",
res_cb => sub {
my ($err, $reservation) = @_;
if ($err) {
die $err->{message};
}
$dev = Amanda::Device->new($reservation->{device_name});
# use device..
});
# later..
$reservation->release(finished_cb => $start_next_volume);
This interface will change before the next release.
All operations in the module return immediately, and take as an argument a callback function which will indicate completion of the changer operation -- a kind of continuation. The caller should run a main loop (see the Amanda::MainLoop manpage) to allow the interactions with the changer script to continue.
A new object is created with the new function as follows:
my $chg = Amanda::Changer->new($changer);
to create a named changer (a name provided by the user, either specifying a changer directly or specifying a changer definition), or
my $chg = Amanda::Changer->new();
to run the default changer. This function handles the many ways a user can configure a changer.
A res_cb $cb is called back as:
$cb->($error, undef);
in the event of an error, or
$cb->(undef, $reservation);
with a successful reservation. res_cb must always be specified. A finished_cb
$cb is called back as
$cb->($error);
in the event of an error, or
$cb->(undef);
on success. A finished_cb may be omitted if no notification of completion is required.
Changers maintain a global concept of a ``current'' slot, for
compatibility with Amanda algorithms such as the taperscan. However, it
is not compatible with concurrent use of the same changer, and may be
inefficient for some changers, so new algorithms should avoid using it,
preferring instead to load the correct tape immediately (with load),
and to progress from tape to tape using the reservation objects'
next_slot attribute.
Load a volume with the given label. This may leverage any barcodes or other indices that the changer has created, or may resort to a sequential scan of media. If set_current is specified and true, then the changer's current slot should be updated to correspond to $slot. If not, then the changer should not update its current slot (but some changers will anyway - specifically, chg-compat).
Note that the changer tries to load the requested volume, but it's a mean world out there, and you may not get what you want, so check the label on the loaded volume before getting started.
Reserve the volume in the ``current'' slot. This is used by the sequential taperscan algorithm to begin its search.
Reserve the volume that follows the current slot. This may not be a very efficient operation on all devices.
Reserve the volume in the given slot. $slot must be a string that appeared in a reservation's 'next_slot' field at some point, or a string from the user (e.g., an argument to amtape).
Query the changer for miscellaneous information. Any number of keys may be
specified. The info_cb is called with $error as the first argument,
much like a res_cb, but the remaining arguments form a hash giving values
for all of the requested keys that are supported by the changer. The preamble
to such a callback is usually
info_cb => sub {
my $error = shift;
my %results = @_;
# ..
}
Supported keys are:
The total number of slots in the changer device. If this key is not present, then the device cannot determine its slot count (for example, an archival device that names slots by timestamp could potentially run until the heat-death of the universe).
A string describing the name and model of the changer device.
Reset the changer to a ``base'' state. This will generally reset the ``current'' slot to something the user would think of as the ``first'' tape, unload any loaded drives, etc. It is an error to call this while any reservations are outstanding.
Clean a drive, if the changer supports it. Drivename can be an empty string for devices with only one drive, or can be an arbitrary string from the user (e.g., an amtape argument). Note that some changers cannot detect the completion of a cleaning cycle; in this case, the user will just need to delay further Amanda activities until the cleaning is complete.
Eject the volume in a drive, if the changer supports it. Drivename is as
specified to clean. If possible, applications should prefer to eject a
reserved volume when finished with it ($res->release(eject => 1)), to
ensure that the correct volume is ejected from a multi-drive changer.
The user has changed something -- loading or unloading tapes,
reconfiguring the changer, etc. -- that may have invalidated the
database. $changed is a changer-specific string indicating what has
changed; if it is omitted, the changer will check everything.
The user has placed volumes in the import/export slots, and would like the changer to place them in storage slots. This is a very changer-specific operation, and $slots should be supplied by the user for verbatim transmission to the changer, and may specify which import/export slots, for example, contain the new volumes.
Place the indicated volume (by $label, or in $slot) into an available import/export slot. This, too, is a very changer-specific operation.
Move a volume between two slots in the changer. These slots are provided by the user, and have meaning for the changer.
This is the name of the device reserved by a reservation object.
This is the name of this slot. It is an arbitrary string which will
have some meaning to the changer's load() method. It is safe to
access this field after the reservation has been released.
This is the ``next'' slot after this one. It is safe to access this field, too, after the reservation has been released (and, in changers with only one ``drive'', this is the only way you will get to the next volume!)
This is how an Amanda application indicates that it no longer needs the reserved volume. The callback is called after any related operations are complete -- possibly immediately. Some drives and changers have a notion of ``ejecting'' a volume, and some don't. In particular, a manual changer can cause the tape drive to eject the tape, while a tape robot can move a tape back to storage, leaving the drive empty. If the eject parameter is given and true, it indicates that Amanda is done with the volume and has reason to believe the user is done with the volume, too -- for example, when a tape has been written completely.
A reservation will be released automatically when the object is destroyed, but in this case no finished_cb is given, so the release operation may not complete before the process exits. Wherever possible, reservations should be explicitly released.
This is how Amanda indicates to the changer that the volume in the device has been (re-)labeled. Changers can keep a database of volume labels by slot or by barcode, or just ignore this function and call $cb immediately. Note that the reservation must still be held when this function is called.
See the other changer packages, including:
- support loading by barcode, showing barcodes in reservations - support deadlock avoidance by returning more information in load errors - Amanda::Changer::Single
This page was automatically generated Fri Feb 5 19:41:21 2010 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.