The Retrieve Tape ID  command retrieves the heading information  from a
mounted tape.  Return variables are provided.

A typical command would be entered as:

           DCL       &VOLID *CHAR LEN(6)
           DCL       &OWNER *CHAR LEN(14)
            .
            .
           RTVTAPID  DEV(xxx) VOLID(&VOLID) OWNER(&OWNER)

RTVTAPID assumes the tape has been initialized.

If  the  tape  is  unlabeled,  blanks  will  be  returned  for  several
variables.  The density will be returned with the TYPE = NL or LTM.

If  the  tape has  no  files, the  Volume ID  will  be returned  and an
optional return value FILES which can be checked.

Command parameters                                    *CMD
------------------

   DEV           The tape device name where the tape is mounted.

   VOL           The tape  volume to  be  retrieved.   *MOUNTED is  the
                 default to  mean the volume  that is currently  on the
                 device.

                 A specific volume ID may be entered.

                 If  the device  specified is  a media  library device,
                 then the  volume  specified should  be  the  cartridge
                 identifier to be mounted and used.

   VOLID         The Volume  ID of the tape  that is mounted.   This is
                 a  return  variable  that must  be  declared  as *CHAR
                 LEN(6).   The  value will  be  blank if  the  tape  is
                 unlabeled.   The  value  will exist  if  there are  no
                 files on the tape.

   OWNER         The  owner of  the tape.   This  is a  return variable
                 that  must be  declared as  *CHAR LEN(14).   The value
                 will be  blank  if the  tape is  unlabeled  or has  no
                 files.

   DENSITY       The density  of the tape.   This is a  return variable
                 that  must be  declared as  *CHAR LEN(11).   The value
                 that  was   originally  specified   on  INZTAP   (e.g.
                 QIC120) will  be returned.   The  value will be  blank
                 if there are no files on the tape.

   CODE          The  code of  the  tape.   This is  a  return variable
                 that must  be declared  as *CHAR  LEN(7).   The  value
                 that will  be  returned is  *EBCDIC or  *ASCII if  the
                 tape  is labeled.    The value  will be  blank  if the
                 tape is unlabeled or has no files.

   TYPE          The  type  of the  tape.   This  is a  return variable
                 that must  be declared  as  *CHAR LEN(3).   The  value
                 that  will  be returned  is  SL  (standard label),  NL
                 (non-labeled),   or   LTM   (non-labeled   without   a
                 beginning tape  mark).   The value  returned will  not
                 have  a preceding  *.   The  value  will  be blank  if
                 there are no files on the tape.

   FILES         Whether  files exist on  the tape.   This is  a return
                 variable that must  be declared  as *CHAR  LEN(3).   A
                 *YES or *NO will be returned.

                 If  other return  variables such  as  CODE are  blank,
                 the FILES  parameter may be used  to determine whether
                 files exist on the tape.

Technique used
--------------

The  command  first does  a CHKTAP  to determine  the first  file name.
DSPTAP is then  used to create  an outfile of  the first file  found on
the tape.

Because of the technique used, the command is slow running.

Restrictions
------------

Because the  command returns  variables, it  can only be  used in  a CL
program.

Prerequisites
-------------

The following TAA Tools must be on your system

            SNDESCMSG     Send escape message

Implementation
--------------

None, the tool is ready to use.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   RTVTAPID      *CMD                   TAATAPH       QATTCMD
   TAATAPHC      *PGM       CLP         TAATAPHC      QATTCL