NetWorker command: stli
NAME
stli - Standard Tape Library Interface
DESCRIPTION
STLI is the documented interface for connecting tape libraries to Net-
Worker.
Tape libraries are often referred to as silos. Examples of tape
libraries are StorageTek ACSLS silos and the IBM 3494. Tape libraries
differ from other jukeboxes supported by NetWorker in two major points:
o The tape libraries have their own volume and slot management. The
volumes are accessed by NetWorker via their barcode labels. The
exact location of a given tape is unknown to NetWorker.
o The interface to the library for issuing requests like mount or
unmount of particular volumes differs from that of jukeboxes, which
are normally connected via a SCSI or V24 interface. Standard Tape
Library commands are transmitted to a Standard Tape Library server,
which receives these commands and invokes the appropriate library
actions. Usually, the connection between NetWorker and the Library
controller is over the network, although serial (RS-232) connections
are also used. The actual connection is hidden from NetWorker by the
STL library. NetWorker and other applications calling the STL server
are called library clients.
To keep applications independent of differing interfaces to various
tape library systems, an API called STLI (Standard Tape Library Inter-
face) has been defined, which is used by NetWorker to invoke library
requests. The STLI specifies a shared library with well defined func-
tions, that is dynamically linked to NetWorker. These STLI interface
libraries, which transform the STLI function calls to library-specific
calls to the proprietary tape library server, may be provided by Legato
or the manufacturers of the tape library.
Not all functions specified in this paper must be implemented in the
STLI library. These functions are the minimum necessary for a func-
tional library:
stl_open()
stl_close()
stl_mount()
stl_unmount()
Implementation of stl_error() is recommended for easier use of the
library and better troubleshooting.
If you wish to support dynamic device reservation these are the rele-
vant functions:
stl_reserve_dev()
stl_release_dev()
stl_dev_reservation()
Optional fucntions for added features:
stl_close()
Declaration:
int stl_close(char* stl);
Description:
Close the connection to the tape library.
<stl> is the handle returned by stl_open().
The return value on success is STL_ERR_NOERR. For error return
values see Appendix: Return Values.
stl_deposit_volume
Declaration:
int stl_deposit_volume(char *stl, char *volume, char *capname)
Description:
Causes the specified volume to be inserted into the library from
the specified cartridge access port (inport/export facility,
mailslot....)
<stl> is the handle returned by stl_open().
<volume> is the bar code of the volume to be deposited into the
library.
<capname> specifies the cartridge access port/inport-export
area/mailslot to be used to insert the volume into the library.
It is a character string, understood by the tape library as a
name for that device. This argument can be NULL, in which case
the default CAP will be used.
This function returns STL_ERR_NOERR if the volume is success-
fully inserted. STL_ERR_NOVOL is returned if the volume is not
present and was not inserted. Other return values are possible
if errors occur. See appendix for possible values.
NOTE: on some libraries, this function may not be needed.
o The IBM 3494 will automatically import any tapes placed into its
in/out area. There is no 'deposit' function in the 3494's API.
o StorageTek libraries with the CAP set to automatic mode behave the
same as the 3494. However, if their CAP is set to manual, then a
deposit call is required.
o On EMASS/Grau libraries, a single call to deposit one volume from the
EIF will deposit all available volumes. However, subsequent deposit
calls will return quickly and the error can be ignored.
stl_deposit_volumes
Declaration:
int stl_deposit_volumes(char *stl, char *volumes, char *capname)
with either a single volume specified or with a comma separated
list.
<stl> is the handle returned by stl_open().
<volumes> is a comma separated list of bar codes of the volumes
to be deposited into the library. There should be no extraneous
spaces added between the individual bar codes since the space
character (ASCII 32) is a valid bar code character itself.
<capname> specifies the cartridge access port/inport-export
area/mailslot to be used to insert the volume into the library.
It is a character string, which is understood by the tape
library as a name for that device. This argument can be NULL,
in which case the default CAP will be used.
This function returns STL_ERR_NOERR if the volume is success-
fully inserted. STL_ERR_NOVOL is returned if the volume is not
present and was not inserted. Other return values are possible
if errors occur. See Appendix: Return Values.
NOTE: on some libraries, this function may not be needed.
o The IBM 3494 will automatically import any tapes placed into its
in/out area. There is no 'deposit' function in the 3494's API.
o StorageTek libraries with the CAP set to automatic mode behave in the
same manner as the 3494. However, if their CAP is set to manual,
then a deposit call is required.
o On EMASS/Grau libraries, a single call to deposit one volume from the
EIF will in fact deposit all available volumes. However, subsequent
deposit calls will return quickly and the error can be ignored.
stl_dev_reservation()
Declaration:
int stl_dev_reservation(char *stl, char *device, int *state)
Description:
Get the reservation state of device <device>.
<stl> is the handle returned by stl_open().
<device> specifies from which device to get the reservation
state. It is a character string, understood by the tape library
as a name for that device.
*<state> returns the reservation state:
STL_DEV_FREE: Free
STL_DEV_RESERVED: Reserved for NetWorker's use
STL_DEV_OCCUPIED: Occupied by another host
The return value on success is STL_ERR_NOERR. For error return
values see appendix.
stl_error()
Declaration:
char *stl_error(void)
Description:
Gives a printable error message belonging to the preceding STLI
function call. The function returns the address of a buffer
which contains a message describing the status of the last STLI
function call. These messages can be constant strings, for
instance, the messages contained in stl.h for error codes less
than 100. But these messages can also be built up with actual
parameters, which exactly describe the error situation.
Error and other status information should be maintained in
global static variables in the library, as this call is made
without any parameters.
The function returns NULL if no message available. See Appendix:
Return Values.
stl_mount()
Declaration:
int stl_mount(char* stl, char* volume, char* device);
Description:
Move volume <volume> into drive <drive>.
<stl> is the handle returned by stl_open().
<volume> is the bar code of the volume to be mounted.
<device> specifies the device, on which the volume shall be
mounted. It is a character string, understood by the tape
library as a name for that device.
This call may not return until the volume is loaded into the
drive and the drive is ready. The exact sequence is dependent
on the library. It can take several minutes to complete.
The return value on success is STL_ERR_NOERR. See Appendix:
Return Values.
stl_open()
Declaration:
int stl_open(char* server, char** stl);
Description:
Connect to the tape library.
<server> is a character string which contains all information
necessary to establish a connection to the tape library. The
information in this string is proprietary to the special type of
tape library. Generally it should be of the form:
[<host>] [<par1>=<val1> [<par2>=<val2>]...]
be used to hold the required configuration information.
The return value on success is STL_ERR_NOERR. See Appendix:
Return Values.
stl_query_volume
Declaration:
int stl_query_volume(char *stl, char *volume)
Description:
Queries a silo to establish the presence of a volume. This
function is currently used to verify the presence of a volume
before allocating that volume for use with NetWorker.
<stl> is the handle returned by stl_open().
<volume> is the bar code of the volume to be mounted.
This function returns STL_ERR_NOERR if the volume is present, or
STL_ERR_NOVOL if the volume is not present.
Other return values are possible if errors occur. See Appendix:
Return Values.
stl_release_dev()
Declaration:
int stl_release_dev(char *stl, char *device);
Description:
Release device <device>, which has previously been reserved by
stl_reserve_dev().
<stl> is the handle returned by stl_open().
<device> specifies the device to be released. It is a character
string, understood by the tape library as a name for that
device.
The return value on success is STL_ERR_NOERR. See Appendix:
Return Values.
stl_reserve_dev()
Declaration:
int stl_reserve_dev(char *stl, char *device);
Description:
Reserves device <device> for NetWorker's use.
<stl> is the handle returned by stl_open().
<device> specifies the device to be reserved. It is a character
string, understood by the tape library as a name for that
device.
The return value on success is STL_ERR_NOERR. See Appendix:
Return Values.
stl_version()
Declaration:
int stl_version(void)
Description:
Returns STLI version information for the STL library
This function returns the version of the STL library * 10.
I.e., it returns a value of 12 for an STL library that supports
the functions for STLI version 1.2.
STLI version 1.0 specified the following calls:
stl_close()
stl_dev_reservation()
stl_mount()
stl_open()
stl_release_dev()
stl_reserve_dev()
stl_unmount()
STLI version 1.1 added the following calls:
stl_query_volume()
stl_version()
STLI version 1.2 added the following calls:
stl_deposit_volume()
stl_withdraw_volume()
STLI version 1.3 added the following calls:
stl_deposit_volumes()
stl_withdraw_volumes()
Note that stl_version does not return a value that can be inter-
preted as an 'STL_' error. Attempting to do so will result in
unpredictable results.
stl_unmount()
Declaration:
int stl_unmount(char* stl, char* volume, char* device);
Description:
Remove volume <volume> from drive <drive>.
<stl> is the handle returned by stl_open().
<volume> is the bar code of the volume to be removed.
<device> specifies the device, from which the volume shall be
removed. It is a character string, understood by the tape
library as a name for that device.
Either <volume> or <device> can be NULL. If both values are
specified, they must be consistent.
This call will not return until the volume is ejected from the
drive and returned to its slot by the library. It can therefore
take several minutes to complete.
The return value on success is STL_ERR_NOERR. See Appendix:
Return Values.
stl_withdraw_volume
Declaration:
int stl_withdraw_volume(char *stl, char *volume, char *capname)
Description:
Causes the specified volume to be ejected from the library
through the specified cartridge access port (inport/export
facility, mailslot...).
<stl> is the handle returned by stl_open().
<volume> is the bar code of the volume to be withdrawn.
<capname> specifies the cartridge access port/inport-export
area/mailslot to be used to remove the volume from the silo. It
is a character string, understood by the tape library as a name
for that device. This argument can be NULL, in which case the
default CAP will be used.
This function returns STL_ERR_NOERR if the volume is success-
fully withdrawn from the library. STL_ERR_NOVOL is returned if
the volume is not present. STL_ERR_VOLBUSY is returned if the
volume is currently in use and cannot be withdrawn.
Other return values are possible if errors occur. See Appendix:
Return Values.
stl_withdraw_volumes
Declaration:
int stl_withdraw_volumes(char *stl, char *volumes, char *cap-
name)
Description:
Causes the specified volume to be ejected from the library
through the specified cartridge access port (inport/export
facility, mailslot....) This function will be used instead of
stl_withdraw_volume() if it is defined and stl_version returns
1.3 or greater. Therefore, it should be capable of functioning
with either a single volume specified or with a comma separated
list.
<stl> is the handle returned by stl_open().
<volumes> is a comma separated list of bar codes of the volumes
to be deposited into the library. There should be no extraneous
spaces added between the individual bar codes since the space
character (ASCII 32) is a valid bar code character itself.
<capname> specifies the cartridge access port/inport-export
area/mailslot to be used to remove the volume from the silo. It
is a character string, understood by the tape library as a name
for that device. This argument can be NULL, in which case the
default CAP will be used.
This function returns STL_ERR_NOERR if the volume is success-
fully withdrawn from the library. STL_ERR_NOVOL is returned if
the volume is not present. STL_ERR_VOLBUSY is returned if the
volume is currently in use and cannot be withdrawn.
Other return values are possible if errors occur. See Appendix:
Return Values.
Appendix: Return Values
Return values 0 - 99 are reserved for common, library type independent
error codes. The header file stl.h defines the common return values
together with a short error message.
Return values greater 100 can be used by each STLI implementation for
proprietary error codes.
It is recommended, that a STLI implementation should map all error sit-
uations to the common STLI error codes and should provide the function
stl_error() for more detailed error messages. This allows NetWorker to
react on known error codes, but also to forward the more detailed error
messages via the user interface.
No proprietary error codes are allowed in situations, where the common
error codes STL_ERR_DEVEMPTY, STL_ERR_DEVFULL or STL_ERR_ALRDYMNTED
apply.
The currently defined return codes are:
Error value Meaning
-------------------------------------------------------
STL_ERR_NOERR
Successful call return - no error
STL_ERR_UNKNOWN
Error, no details available
STL_ERR_CONNECT
Cannot connect to tape library
STL_ERR_BUSY
Tape library busy, try later
STL_ERR_ACCESS
Permission denied (to access the library, the requested device,
volume or operation)
STL_ERR_NODEV
Device not known to the tape library or physically not available
STL_ERR_NOVOL
Volume not known to the tape library or physically not available
STL_ERR_DEVFULL
Device already loaded with another volume
STL_ERR_DEVEMPTY
Device empty
STL_ERR_DEVBUSY
Device busy
STL_ERR_ERRNO
Local UNIX error, see errno
STL_ERR_INVALID
Invalid parameter
STL_ERR_VOLBUSY
Volume already loaded in another drive or is otherwise occupied
STL_ERR_LIBRARY
Tape library internal error
STL_ERR_CONFIG
Request doesn't comply with tape library configuration
STL_ERR_DEVOCC
Device reserved by another host
STL_ERR_DEVRES
Device already reserved
STL_ERR_DEVNOTRES
Device not reserved
STL_ERR_NOTINST
STLI-Library is a dummy library
STL_ERR_NOTSUPP
Dummy function return
STL_ERR_ALRDYMNTED
Requested volume already mounted in requested device
SEE ALSO
nsrjb(8), nsr_jukebox(5), IBM_silo(8), EMASS_silo(8), STK_silo(8).
NetWorker 7.5.1 Mar 21, 09