sam_tplabel(3)

NAME
     sam_tplabel - Labels a tape on the specified device

SYNOPSIS
     cc [ flag  ... ] file  ... -L/opt/SUNWsamfs/lib  -lsamapi  [library ... ]

     #include "/opt/SUNWsamfs/include/samapi.h"

     int  sam_tplabel(ushort_t  eq_number,  char  *new_vsn,  char
     *old_vsn,  uint_t  ea,  int  modifier,  int  block_size, int
     erase, int wait_response);

DESCRIPTION
     sam_tplabel() labels a tape on  the  specified  device  with
     equipment  number  eq_number  and  the following sequence of
     labels is written:

          VOL1
          HDR1
          HDR2
          tapemark
          EOF1
          tapemark
          tapemark

     The labels conform to ANSI  X3.27-1987  File  Structure  and
     Labeling of Magnetic Tapes for Information Interchange.

     If the device is a robotic  media  changer,  a  ea  must  be
     specified.   If  old_vsn is specified as a NULL pointer, the
     media will be assumed to be not labeled and a new label will
     be  written.   A new_vsn must be specified.  The VSN must be
     one to six characters in length.  All characters in the  VSN
     must  be  selected  from  the  26 upper-case letters, the 10
     digits, and the following  special  characters:  !"%&'()*+,-
     ./:;<=>?_.

     block_size  specifies  the  blocksize  for  this  tape.   If
     nonzero, the value must be one of 16, 32, 64, 128, 256, 512,
     1024 or 2048 and represents the size of the  tape  block  in
     units of 1024.  This option overrides the default blocksize.

     If erase is specified as nonzero, the  media  is  completely
     erased before a label is written.

     The call will return immediately after issuing  the  command
     if  zero is specified for wait_response value.  Other values
     for wait_response will give undefined results.

RETURN VALUES
     Upon  succesful  completion  a  value  of  0  is   returned.

     Otherwise,  a  value  of  -1 is returned and errno is set to
     indicate the error.

ERRORS
     sam_tplabel() fails if one or  more  of  the  following  are
     true:

     ER_BLOCK_SIZE_TOO_LARGE
                         The specified block_size is greater than
                         the maximum block size allowed.

     ER_DEVICE_NOT_LABELED
                         The specified eq_number device is not  a
                         labeled device.

     ER_DEVICE_NOT_MANUAL_LOAD
                         The specified eq_number device is not  a
                         manual load type device.

     ER_DEVICE_NOT_THIS_TYPE
                         The specified eq_number  device  is  not
                         the correct media type.

     ER_FIFO_PATH_LENGTH The path and filename for the FIFO  pipe
                         is too long.

     ER_INVALID_BLOCK_SIZE
                         The specified block_size is not 16,  32,
                         64, 128, 256, 512, 1024 or 2048.

     ER_INVALID_MEDIA_TYPE
                         Invalid  media  type  specified  to   be
                         labeled.

     ER_INVALID_VSN_CHARACTERS
                         The specified new_vsn  or  old_vsn  con-
                         tains  invalid  characters to conform to
                         ANSI  X3.27-1987  File   Structure   and
                         Labeling  of Magnetic Tapes for Informa-
                         tion Interchange.

     ER_INVALID_VSN_LENGTH
                         The specified new_vsn or old_vsn is  not
                         from one to six characters in length.

     ER_MEDIA_VSN_NOT_OLD_VSN
                         The old_vsn does not match  the  current
                         VSN on the media.

     ER_NO_EQUIP_ORDINAL eq_number is  not  a  defined  equipment
                         number in this configuration.

     ER_NO_MASTER_SHM    No Sun  QFS  or  SAM-QFS  master  shared
                         memory  segment defined.  Check that the
                         Sun QFS and  SAM-QFS  file  systems  are
                         mounted.

     ER_NO_RESPONSE_FIFO Unable to create the response FIFO pipe.

     ER_NO_MASTER_SHM_ATT
                         No Sun  QFS  or  SAM-QFS  master  shared
                         memory  segment  found.   Check that the
                         Sun QFS and  SAM-QFS  file  systems  are
                         mounted.

     ER_NO_STAT_ROBOT_CATALOG
                         The  robot  media  changer  catalog  for
                         equipment  number  eq_number  cannot  be
                         accessed for status.

     ER_NOT_VALID_SLOT_NUMBER
                         ea specified  is  not  a  valid  element
                         address of the robotic media changer.

     ER_OLD_VSN_NOT_UNK_MEDIA
                         old_vsn not matching unknown media VSN.

     ER_OPERATOR_NOT_PRIV
                         Operator does  not  have  permission  to
                         label removable media.

     ER_ROBOT_CATALOG_MISSING
                         No robot catalog was found for equipment
                         number  eq_number  which is defined as a
                         robotic media changer.

     ER_ROBOT_DEVICE_REQUIRED
                         No devices were found to be defined  for
                         equipment   number  eq_number  which  is
                         defined as a robotic media changer.

     ER_SLOT_NOT_OCCUPIED
                         No media was found to occupy the element
                         address  in  the media changer at equip-
                         ment number eq_number

     ER_VSN_BARCODE_REQUIRED
                         new_vsn must be specified.

     ER_UNABLE_TO_MAP_CATALOG
                         The  catalog  for  the  removable  media
                         changer at equipment number eq_number is
                         unable to be mapped into memory.

FILES
     mcf                 The configuration file for Sun  QFS  and
                         SAM-QFS file systems.

SEE ALSO
     odlabel(1M), tplabel(1M).

     sam_odlabel(3).