


STLI(8)                                                   STLI(8)


NNAAMMEE
       stli  - Standard Tape Library Interface

DDEESSCCRRIIPPTTIIOONN
       STLI  is  the  documented  interface  for  connecting tape
       libraries to NetWorker.
        Tape libraries are often referred to as silos.   Examples
       of tape libraries are StorageTek ACSLS silos, ABBA systems
       from Grau or 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  man-
         agement.       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 Net-
         Worker and the Library controller is over  the  network,
         although  serial  (RS-232)  connections  are  also used.
         Note that the actual connection is hidden from NetWorker
         by  the  STL  library.   Accordingly 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 (Stan-
       dard  Tape  Library  Interface) has been defined, which is
       used by NetWorker to invoke library  requests.   The  STLI
       specifies  a  shared  library with well defined functions,
       which 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 manufac-
       turers of the tape library.

       Not all functions specified in this paper must  be  imple-
       mented  in the STLI library. These functions are the mini-
       mum necessary for a functional library:

              stl_open()
              stl_close()
              stl_mount()
              stl_unmount()

       Implementation of stl_error() is  recommended  for  easier
       use of the library and better troubleshooting.




NetWorker rt_1998_4Q.Build.MMaJrFcehra0l8_,0021000                        1





STLI(8)                                                   STLI(8)


       If  you  wish  to support dynamic device reservation these
       are the relevant functions:

              stl_reserve_dev()
              stl_release_dev()
              stl_dev_reservation()

       Optional fucntions for added features:

              stl_query_volume()
              stl_withdraw_volume()
              stl_deposit_volume()


ssttll__cclloossee(())
       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.

ssttll__ddeeppoossiitt__vvoolluummee
       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  barcode  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 char-
              acter 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



NetWorker rt_1998_4Q.Build.MMaJrFcehra0l8_,0021000                        2





STLI(8)                                                   STLI(8)


              is   successfully   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  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.

ssttll__ddeevv__rreesseerrvvaattiioonn(())
       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  the device to get the reserva-
              tion state of.  It is a character string, which  is
              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.

ssttll__eerrrroorr(())
       Declaration:

              char *stl_error(void)



NetWorker rt_1998_4Q.Build.MMaJrFcehra0l8_,0021000                        3





STLI(8)                                                   STLI(8)


       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  describe
              more exactly the error situation.

              Error  and other status information should be main-
              tained in global static variables in  the  library,
              since this call is made without any parameters.

              The  function returns NULL if no message available.
              See appendix.

ssttll__mmoouunntt(())
       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  barcode  of  the  volume  to  be
              mounted.

              <device> specifies the device, on which the  volume
              shall  be  mounted. It is a character string, which
              is 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 has come  ready.   The
              exact sequence is dependent on the library.  It can
              therefore take several minutes to complete.

              The return value on success is  STL_ERR_NOERR.  For
              error return values see appendix.

ssttll__ooppeenn(())
       Declaration:

              int stl_open(char* server, char** stl);

       Description:




NetWorker rt_1998_4Q.Build.MMaJrFcehra0l8_,0021000                        4





STLI(8)                                                   STLI(8)


              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>]...]

              In  most  cases  the string contains merely <host>,
              the nodename of a library  server,  which  receives
              and serves the STLI requests over the network.

              *<stl>  is  a  handle returned for use by the other
              STLI functions.  This handle can be used  to  store
              internal  information  between  subsequent function
              calls.  For some libraries, the parameter  to  this
              call  may  or may not be used, as environment vari-
              ables may be used to hold the  required  configura-
              tion information.

              The  return  value on success is STL_ERR_NOERR. For
              error return values see appendix

ssttll__qquueerryy__vvoolluummee
       Declaration:

              int stl_query_volume(char *stl, char *volume)

       Description:

              Queries a silo to establish the presence of a  vol-
              ume.  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  barcode  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 for possible values.

ssttll__rreelleeaassee__ddeevv(())
       Declaration:

              int stl_release_dev(char *stl, char *device);




NetWorker rt_1998_4Q.Build.MMaJrFcehra0l8_,0021000                        5





STLI(8)                                                   STLI(8)


       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, which is understood by the
              tape library as a name for that device.

              The return value on success is  STL_ERR_NOERR.  For
              error return values see appendix.

ssttll__rreesseerrvvee__ddeevv(())
       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, which is understood  by  the
              tape library as a name for that device.

              The  return  value on success is STL_ERR_NOERR. For
              error return values see appendix.

ssttll__vveerrssiioonn(())
       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()



NetWorker rt_1998_4Q.Build.MMaJrFcehra0l8_,0021000                        6





STLI(8)                                                   STLI(8)


              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()

              Note that stl_version does not return a value  that
              can  be interpreted as an 'STL_' error.  Attempting
              to do so will result in unpredictable results.


ssttll__uunnmmoouunntt(())
       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  barcode  of  the  volume  to  be
              removed.

              <device> specifies the device, from which the  vol-
              ume  shall  be  removed.  It is a character string,
              which is 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. For
              error return values see appendix.

ssttll__wwiitthhddrraaww__vvoolluummee
       Declaration:

              int stl_withdraw_volume(char  *stl,  char  *volume,
              char *capname)



NetWorker rt_1998_4Q.Build.MMaJrFcehra0l8_,0021000                        7





STLI(8)                                                   STLI(8)


       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 barcode of the volume to be with-
              drawn.

              <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,  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  successfully  withdrawn   from   the   library.
              STL_ERR_NOVOL is returned if the volume is not pre-
              sent and 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 for possible values.


AAppppeennddiixx::   RReettuurrnn VVaalluueess
       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 imple-
       mentation for proprietary  error codes.

       It is recommended, that a STLI implementation  should  map
       all  error  situations  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



NetWorker rt_1998_4Q.Build.MMaJrFcehra0l8_,0021000                        8





STLI(8)                                                   STLI(8)


       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  other-
       wise
            occupied

       STL_ERR_LIBRARY
            Tape library internal error

       STL_ERR_CONFIG
            Request  doesn't  comply with tape library configura-
       tion

       STL_ERR_DEVOCC
            Device reserved by another host

       STL_ERR_DEVRES
            Device already reserved




NetWorker rt_1998_4Q.Build.MMaJrFcehra0l8_,0021000                        9





STLI(8)                                                   STLI(8)


       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



SSEEEE AALLSSOO
       nnssrrjjbb(8),  nnssrr__jjuukkeebbooxx(5),   IIBBMM__ssiilloo(8),   EEMMAASSSS__ssiilloo(8),
       SSTTKK__ssiilloo(8).








































NetWorker rt_1998_4Q.Build.MMaJrFcehra0l8_,0021000                       10


