TAA Tools
CRTVTP          CREATE VIRTUAL TAPE                    TAATAPN

The  Create  Virtual   Tape  tool  provides  a  simple   interface  for
creating,  displaying,  and deleting  a  virtual tape  structure.   The
intent  of  the CRTVTP  tool  is that  you  would create  or  replace a
virtual tape  structure  each  time you  need  to  use a  virtual  tape
function and replace or delete it after the tape media is written.

The system virtual tape support uses:

       - A virtual tape resource - a hardware resource
       - A virtual tape device - must be 'varied on'
       - An IFS directory - will contain the saved data in a STMF
       - An image catalog - must be kept in a 'ready' status
       - An image catalog entry - must be in a 'mounted' status

Any SAVxxx  command including  SAVLIB(*NONSYS) may be  used to  save to
virtual  tape.   The data  is saved  to the  IFS.   Since media  is not
involved during the save, an unattended save can occur.

The system DUPTAP  command is  used to  copy from the  virtual tape  to
actual media.

Virtual tape  can be used  with the SAVSYSBCH TAA  Tool.  Thus  you can
back  up the  entire system in  an unattended  manner from a  batch job
which can be scheduled for a specific time.

To use  the system  support directly,  you must  be familiar  with  the
concepts and functions.

The CRTVTP TAA  tool allows a simple  approach where the user  does not
directly use  most of the  functions.  CRTVTP  is intended to  create a
virtual  tape structure.  After creating  a structure, you would do the
following:

         SAVxxx
         DUPTAP
         RPLVTP

An alternative is to  also use RPLVTP command when the  process begins.
This ensures  that the device is varied  on, the image catalog  is in a
'ready'  state and  the required  storage is  at a  minimum.   Each use
would then be:

         RPLVTP
         SAVxxx
         DUPTAP
         RPLVTP

The overhead to  do RPLVTP is fairly  minimal.  If  you use the  RPLVTP
approach, the  basic structure  will remain using  about 300K  (most of
this is caused by the minimum amount of an image catalog).

If you  need to review and  control the status, the  TAA WRKVTP command
provides a work display with a variety of options and functions.

You must  be  authorized  to the  TAAVTP  and  TAACVTIFS  Authorization
lists to use most of the supplied commands:

  **   CRTVTP.  Creates a virtual tape structure.

  **   DLTVTP.   Deletes  a virtual  tape structure.    Only a  virtual
       tape structure created by CRTVTP may be deleted.

  **   DSPVTP.   Displays the  virtual tape  devices and  the available
       virtual tape resources.

  **   RDYVTP.   Ensures the image catalogs  created by CRTVTP are in a
       'ready' status and  the corresponding  devices are 'varied  on'.

  **   RPLVTP.    Replaces  the   structure  built  by  CRTVTP  to  its
       original values.

  **   WRKVTP.   Provides  a work display  to allow  review and control
       of any virtual tape structures created by CRTVTP.

  **   CRTVTPRSC.  Creates or describes  a virtual tape resource to  be
       used.

System virtual tape advantages and support
------------------------------------------

The system virtual  tape support allows an online save  from any SAVxxx
command to  a stream file in the IFS.   Multiple libraries may be saved
to the  same  virtual  tape  device with  a  single  command  including
SAVLIB LIB(*NONSYS).   When multiple  libraries are  saved on a  single
command,  the  system  overlaps  the  allocation  and  deallocation  of
resources.   This differs from *SAVF  objects which allow only a single
library per save file object and no overlap of allocation occurs.

The virtual tape  save function can occur  unattended.  The writing  to
offline  media occurs  by using  the DUPTAP  command which  copies from
the virtual tape device data to an actual tape device.

The  system  support requires  the  use  of a  tape  device description
which is defined with a resource  name of *VRT for virtual.  A  virtual
tape resource must  be named or be  created.  An image  catalog must be
created along with an entry describing the volume to be saved to.

To  use the  function at the  system level,  you must be  familiar with
several concepts and details.

Basics of virtual tape resources
--------------------------------

A virtual tape device must refer to a virtual tape resource.

A virtual  tape resource  is not  an  object type  on the  system,  but
rather a hardware resource.   There are no system  commands to directly
create or delete a virtual tape resource.

A  virtual  tape  resource  is  automatically  created  by  the  system
CRTDEVTAP  command  using  RSRCNAME(*VRT) when  no  available resources
exist.  The names TAPVRT01-TAPVRT9999  are used, but only 35  may exist
at  one time.   The  system solution  has a  tendency to  create excess
resources  rather than use an existing  resource.  An existing resource
will only  be  used  if  it  is  in a  'Not  detected'  status.    This
overlooks the 'Operational'  status which means a resource  is not tied
to  an  existing  device.    The  status  conditions are  described  in
further detail later.

Multiple tape device descriptions  may refer to  the same virtual  tape
resource, but only  one such device description  may be varied on  at a
time.

Virtual tape  resources require only  a small amount of  storage so the
space requirement is rarely a consideration.

Once  created, a  virtual tape  resource can  only be deleted  by using
the DST service tools at IPL or SST.  Its best to avoid doing this.

Getting started
---------------

  **   The TAA command  WRKVTP provides a  type of 'one stop  shopping'
       to  review  and  control   virtual  tape.    You  should  become
       familiar  with the command and its options.   You must have *USE
       authority to  the TAAVTP  and TAACVTIFS  authorization lists  to
       use WRKVTP  as well as  the other TAA  commands included  in the
       CRTVTP tool.

       WRKVTP has no parameters and would be entered as:

             WRKVTP

  **   If  no virtual tape  devices exist, the  error messages describe
       that you  should  use  F8  to  see  a  list  of  available  tape
       resources.   If  no  tape resource  exist,  you will  receive  a
       prompt  that   allows  you  to  create  10.     This  should  be
       sufficient for most usage.

       The  Available  Tape  Resource display  describes  any resources
       that are in a 'Not detected' or 'Operational' status.

       The 'Not detected' status  indicates that the resource  reported
       in  at a  previous IPL,  but is  not in  use now.   This  is the
       normal  status for  a resource  that has  not been  in use  to a
       virtual tape device since the last IPL.

       The 'Operational' status  indicates that  the resource has  been
       in use since  the last IPL, but  is not currently in  use.  This
       would  occur if  you just  created the resource  or if  you used
       the resource  with CRTVTP  and  then used  DLTVTP for  the  same
       virtual device.

       In order  to  create a  virtual tape  device  using CRTVTP,  you
       must  know  the  name   of  a  virtual  tape  resource  that  is
       available.

         --   If  the  Available Tape  Resources display  describes one
              or more tape  resources, you can  position the cursor  to
              one  and use F19.   This  will end  the display,  and the
              tape  resource you  selected  will appear  at the  top of
              the WRKVTP  display  (upper  right hand  corner)  and  is
              ready for use with CRTVTP.

         --   If you  do not  have any  virtual tape resources,  return
              to  the WRKVTP  display and use  F9.   This will  cause a
              virtual tape resource  to be  created (if  none exist  in
              the  'Not detected'  state)  and the  completion  message
              will describe  the resource name  that was created.   The
              name  of the resource will also  appear at the top of the
              display (upper right  hand corner) and  is ready for  use
              with CRTVTP.

  **   Before creating  a virtual tape device, you  must understand the
       CRTVTP DENSITY parameter.

       You  must ensure  that the  density (the  tape block  size) that
       will  eventually   be   written   to  tape   using   DUPTAP   is
       synchronized with  what is  specified on  CRTVTP (this  value is
       passed  thru to  the image  catalog entry).   To  understand the
       value to be  specified, you  must know  the block  size that  is
       written by a SAVxxx command using USEOPTBLK(*YES).

       Use F6 from WRKVTP  to prompt for the CRTVTP  command and review
       the  help   text  for  the  DENSITY  parameter   (or  the  later
       discussion of the command parameter).

       The  DUPTAP TODENSITY  parameter should normally  have this same
       value.  See the later section on 'DUPTAP command'.

       If you have a  single or identical tape devices on  your system,
       you can  set a  system wide default  with the  Application Value
       CRTVTP  in  TAASECURE.   Use EDTAPPVAL  TAASECURE/CRTVTP  to set
       your default.   This  will allow  the CRTVTP  command to  assume
       the system wide default.

  **   You are  now ready to  create a virtual  tape device.   The name
       VRT01 will be used in the following examples.

       From the WRKVTP display, use F6 to prompt for CRTVTP.

       Enter the values as:

            VRTTAP(VRT01)
            DENSITY - If you used EDTAPPVAL as described previously,
                        you should see the assigned value.
                        If not, enter a *VRTnnnK value.
            RSRCNAME(TAPVRTnn)

       Assuming  you had  selected a  resource,  the name  you selected
       would appear in the RSRCNAME parameter as the default.

       You should see the TEXT parameter  as 'Created by TAA CRTVTP  on
       xx/xx/xx'.   This value is  filled in  from the prompt  override
       program.

       Take the defaults for the other parameters which include:

         --   An option  exists to place the data in  an IASP.  See the
              ASP parameter.

         --   An  option to describe  the maximum storage  that will be
              allowed.  See the later discussion.

         --   The AUT parameter controls  access to the Virtual  Device
              and Image Catalog.   The default is *EXCLUDE.   This will
              prevent  any  user  from  saving  to  the  virtual device
              unless specifically authorized.

         --   The  DIRAUT  parameter   controls  access   to  the   IFS
              Directory  that  will   be  created.    It   defaults  to
              *EXCLUDE.   This  prevents a  user  from using  WRKLNK to
              access or work with the IFS object.

         --   The key  feature  of  controlling  security  for  Virtual
              Tape  is  authorization   to  the  Virtual   Tape  Device
              descriptions.   Only those users  you want to  be able to
              use  Virtual  Tape should  be  authorized to  the Virtual
              Tape Device  descriptions.  See  the later discussion  of
              'Virtual Tape Device Authorization'.

       After  Enter is pressed,  the WRKVTP  display will  be refreshed
       so you should see the device you created.

       You  should see  that the device  is 'varied  on'.   In order to
       save to a virtual tape  device, the device must be 'varied  on'.
       CRTVTP creates and  'varies on' the device.  The  device is also
       specified to 'vary on' at IPL.

       The  status of  the Image  Catalog is shown.   It  must be  in a
       'ready' status to allow a save.

       A size is shown from the size  of the *STMF in the IFS.   Before
       any data is saved  to the virtual tape, there is  a default size
       (varies per release).

  **   You are now  ready to save to the virtual  tape device.  End the
       WRKVTP  display and  return to  command entry.   Choose  a small
       library and enter:

           SAVLIB     LIB(xxx) DEV(VRT01)

  **   Use WRKVTP to review the status.

             WRKVTP

       You should  see  the size  has increased  and  will be  somewhat
       larger than the size of the library that was saved.

  **   Use WRKVTP  Option 7  (TAA DSPTAPLBL) to  review the  tape label
       information.   It  will describe  the date  the first  label (if
       any) was written or if any files exist.

  **   Use WRKVTP  Option 8  (TAA DSPSAVTAP)  to see  the objects  that
       were saved.

  **   To  write  from  the  virtual tape  device  to  an  actual  tape
       device, mount a tape and use DUPTAP such as:

           DUPTAP     FROMDEV(VRT01) TODEV(xxx) CHECK(*xxx)
                        TOENDOPT(*REWIND) TODENSITY(*VRTnnnK)

       A  CHECK(*NO) value allows  you to  write over the  first active
       file on the media.   Note that  the TOENDOPT parameter  defaults
       to  *UNLOAD, but  for  the test,  use  *REWIND.   The  TODENSITY
       value should  agree with what  was specified on  CRTVTP (see the
       section on DUPTAP).

  **   You  can use  DSPSAVTAP to review  what has been  written to the
       tape.  Specify the actual tape device:

            DSPSAVTAP  DEV(xxx)

       You should see the  same information that you saw with  Option 8
       from the WRKVTP display of the virtual tape device.

  **   An IPL  will reset  the image catalog  to a 'not  ready' status.
       The  device is created  with ONLINE(*YES) so it  is normally not
       necessary to vary on the device.

       You can simulate  the status of  an image catalog  after an  IPL
       by unloading  the image  catalog.  Return  to command  entry and
       enter:

             LODIMGCLG   IMGCLG(VRT01) DEV(VRT01) OPTION(*UNLOAD)

       Then  enter WRKVTP  again.  You  should see  that the  status is
       now '*NOTRDY'.

       A simple TAA command  (RDYVTP) exists to  ensure the device  and
       image catalog  are in the  proper status.   Use F7 (RDYVTP)  and
       check the results.

       The RDYVTP  command finds all  image catalogs created  by CRTVTP
       and  ensures they  are in a  'ready' status.   The corresponding
       devices are ensured to be 'varied on'.

  **   CRTVTP creates  an image  catalog of the  same name  as the  the
       virtual device.   Image catalogs are always  created in QUSRSYS.
       You  can review the  image catalog by using  Option 6 (WRKIMGCLG
       system command).

  **   Use Option  12  from the  WRKIMGCLG  display  to see  the  image
       catalog  entries associated  with  the  image catalog  that  was
       created   (this  could  also  be   accessed  directly  with  the
       WRKIMGCLGE command).

  **   You should see  that there  is only  one entry  and it  is in  a
       'mounted' status.   This  is the  required status  to perform  a
       save   or  DUPTAP   operation.     If   you  review   the  'help
       information'  for the  status field,  you can  see that  this is
       the actual  status only  if the image  catalog is  in a  'ready'
       status.   Keeping the  image catalog in  a 'ready'  status would
       not  be necessary  if you begin  each save  function with RPLVTP
       or RDYVTP.

       The other status value  you may see for  an image catalog  entry
       is 'loaded'  which means the entry  is available to  be mounted.

       An  analogy is  to consider  the  image catalog  as a  CD player
       with several slots for  CDs that can be  'loaded', but only  one
       can be played at  a time.  The one  you want to play must  be in
       a  'mounted' status.    There can  only  be one  in  a 'mounted'
       status.    The  'mounted' status  is  required to  use  a SAVxxx
       command or the DUPTAP command.

       Each  entry represents  one  volume  that  was saved  to.    You
       should see  the name VOL001.   If a save  operation exceeded the
       maximum  size,  an  additional  volume  would  be  automatically
       created with a  large maximum  size.   Generating an  additional
       volume   complicates  the   use   of  DUPTAP   (see  the   later
       discussion)  and therefore  the maximum size  (MAXSTG parameter)
       specified on CRTVTP  should be a  large value.   The default  is
       to assign a value  of 50% of the unused  space in ASP 1.   If an
       IASP  is described,  it is  the  unused space  in ASP  1  of the
       IASP.

       Use  F11  from the  Work Image  Catalog  Entries display  to see
       size information.   Unlike WRKVTP, only  the maximum size and  a
       percentage are shown.   You have to perform  a multiplication to
       determine  the size  in  MB.   Performing a  multiplication will
       not necessarily provide  an accurate  value because the  minimum
       percentage is  0.1 of the  maximum size.   If you saved  a large
       amount  of data,  the multiplication  will provide  a reasonable
       value.

       The size  shown on  WRKVTP  comes from  the  size of  the  *STMF
       associated with the virtual devices.

  **   Use WRKLNK to review the root as:

             WRKLNK   /

       Use Option 5 to  see the directories.  Rollup until  you see the
       TAAVTP directory.   This is  created automatically on  the first
       use of CRTVTP.

       Use   Option   5   for   the  TAAVTP   directory   to   see  the
       subdirectories of TAAVTP.   You should  see a sub-directory  for
       the name of your virtual tape device VRT01.

       Use Option 5  for the VRT01 sub-directory to  see the STMF which
       has a name of VOL001.

       Use  Option   8  for  the  VOL001  stream  file  to  review  the
       attributes which includes  the actual  size (rollup  to page  2)
       in the IFS.

  **   Return to the WRKVTP display.

       Enter Option 3  to replace a virtual tape structure.   This will
       delete  the existing  structure and re-create  it.   This causes
       the size to  be minimized and  ensures the device  is varied  on
       and the image catalog is in a 'ready' status.

  **   You  may use  Option  4  to  delete a  virtual  tape  structure.
       However, once  a structure is created, the  simplest solution is
       to   use  RPLVTP  (Option  3).    There  is  approximately  600K
       required to have an  empty virtual tape structure (most  of this
       is required for an empty image catalog).

Why replace the virtual tape structure after each usage
-------------------------------------------------------

The  recommended approach  avoids some  pitfalls and  tries to  make it
very simple.

It  is  possible to  re-use  the structure  you have  created  by doing
another save with  CLEAR(*ALL) or INZTAP (or  the TAA CLRTAP  command).

However, you are exposed to the following:

  **   If  you save  a  large amount  of data,  the  allocated size  is
       fixed in  the IFS.  Writing a smaller amount  of data or using a
       function like INZTAP does not change the allocated size.

  **   If you re-IPL,  the status  of the  image catalog  goes to  'not
       ready'.   You must use  RDYVTP or LODIMGCLG  or the load  option
       on WRKIMGCLG to place it in a 'ready' status.

  **   Attempting  to fully  understand the  intricacies of  the system
       support  when something  is in  error is  non-trivial.   You can
       spend a  good  deal  of time  attempting  to understand  how  it
       works and it is not easy to remember.

SAVxxx functions
----------------

As  with  saving  directly  to  media, you  may  have  multiple  SAVxxx
commands  and add  data to the  same virtual  tape device.   The SEQNBR
parameter defaults to *END.

Avoid specifying DTACPR(*YES) when saving to a virtual tape device.

The SAV command may be  used to save from  the IFS.  The DEV  parameter
would be entered as:

            SAV    DEV('/qsys.lib/vrt01.devd') OBJ(xxx)

Typical CRTVTP approach
-----------------------

The TAA solution  avoids the complexities of the system  solution.  The
intent  is  you would  create  a virtual  tape  structure,  perform the
save, do  DUPTAP to  offload the  data, and  then replace  the  virtual
tape structure  with RPLVTP.   With this approach,  you do not  have to
concern yourself with the complexities of the system approach.

A typical  approach would be two  CL programs.  You must  first use the
CRTVTP  function  to  create  a  virtual  tape  structure.    The first
program would contain:

             RPLVTP       VRTTAP(VRT01)
             SAVLIB       LIB(xxx ...) DEV(VRT01) ...
             CHKSAVRST    ERRORSONLY(*YES)

And a second program for:

             DUPTAP       FROMDEV(VRT01) TODEV(xxx)
                            CHECK(*xxx) TODENSITY(*VRTnnnK)
             RPLVTP       VRTTAP(VRT01)

While  there  is  some   overhead  in  using  RPLVTP,  it   avoids  the
complexities and keeps your online storage at a minimal amount.

If you  don't mind the amount  of storage required for  a save existing
on  your  system and  use  CLEAR(*ALL) on  the SAV  command,  you could
replace the  first RPLVTP  command with  RDYVTP which  will cause  less
overhead.  RDYVTP ensures the structure is ready to be used.

If you wanted to  do the whole function unattended  at a specific time,
you could  mount a tape and  combine the above functions  into a single
program.

  **   The  RPLVTP   command  deletes   the  existing   structure   and
       re-creates  it  using  an  internal  CRTVTP.     This  does  the
       following:

         --   Creates the device and varies it on.

         --   Creates an  image catalog in QUSRSYS by  the same name as
              the virtual tape device.

         --   Creates  the  /TAAVTP  directory if  it  does  not exist.
              The *PUBLIC user is given all rights.

         --   Creates a  sub  directory using  the  VRT01 name  in  the
              '/TAAVTP'  directory.   The  *PUBLIC  user  is given  all
              rights.

         --   Adds  an image  catalog entry with  a default  size.  The
              CRTVTP MAXSTG parameter  allows you  to specify a  value,
              but  defaults  to *DFT  which  means  50% of  the  unused
              storage  in the system  ASP.   This is not  the allocated
              size,  but  rather  the  size  used  by  the  system   to
              determine  when to  start  another virtual  tape  volume.
              The simplest  solution is to  allow a sufficient  size to
              avoid  having  the system  generate another  virtual tape
              volume.

              If the  amount  saved overflows  the  size specified,  it
              takes multiple  DUPTAP commands to output to  media.  See
              the later section on the 'DUPTAP' command.

         --   Loads the image catalog entry.

  **   The  SAVLIB command does a normal save  of one or more libraries
       to  the  virtual   tape  device.     You   should  not   specify
       DTACPR(*YES) as  this has an adverse  affect on save time.   The
       data is  placed in the '/TAAVTP/VRT01' directory  in the IFS.  A
       stream file is created.

  **   The TAA  CHKSAVRST  command nets  out  the job  log  information
       relative to the save.   This allows you to  easily determine any
       errors that may have occurred.

  **   The  DUPTAP command copies  the saved  data to a  specified tape
       device.   You  will need  to specify  CHECK(*NO) if there  is an
       active file on  the tape and  you want to  write over the  first
       file.  You  will need to ensure that  the TODENSITY parameter is
       the  same as that specified on  CRTVTP or can be  used.  See the
       section on the 'DUPTAP command'.

  **   The RPLVTP  command recreates  the structure  and minimizes  the
       amount of online storage.

DUPTAP command
--------------

The  system DUPTAP  command  is used  to write  from  an image  catalog
entry  to offline media.   Assume you  used CRTVTP to  create the VRT01
tape device and did a save operation to VRT01.

A simple DUPTAP command would be:

            DUPTAP    FROMDEV(VRT01) TODEV(TAP01) CHECK(*NO)
                        TODENSITY(*VRTnnnK)

This would copy  the data  from the image  catalog entry  to the  TAP01
device.  The CHECK(*NO)  entry would allow you to write  over an active
volume.

The  DUPTAP  command allows  identifying  the  volume identifier  which
would be needed if more than one catalog entry exists.

DUPTAP  also allows  a TODENSITY  parameter which  can be  defaulted in
some cases.   The  value should normally  be consistent  with what  was
used on CRTVTP.

Some  density differences  are valid,  but  the rules  vary per  device
type  and  media type.    If you  use different  densities  between the
CRTVTP command  and  the  DUPTAP command,  be  sure to  test  a  sample
restore.

Use F10 to see the additional parameters on DUPTAP.

If you  specified a  MAXSTG size  of 20 GB,  saved 15  GB and  a single
media  only holds  10 GB,  DUPTAP  will prompt  for another  tape mount
when needed.  Restore operations  will work normally from the  multiple
volumes.

If you  specified a  MAXSTG size  of 1GB  and saved more  than 1GB,  an
additional  volume  would  be  created  in  the  image  catalog.    The
additional  volume added would have a  large maximum size.  DUPTAP will
only write  one volume  per use  of the  command.   You  will need  the
WRKIMGCLGE command to  review the volume names generated  by the system
which must be specified on DUPTAP.

Use of other tape commands
--------------------------

After  a save command occurs,  you can review the  data with the DSPTAP
command or for a more convenient use, the DSPSAVTAP TAA command.

INZTAP may be used  or the TAA CLRTAP command.   These commands do  not
reset the allocated size  in the IFS.  The allocated size  can be reset
using the CHGIMGCLGE command with ALCSTG(*MIN).

However, for the simplest use, the RPLVTP command avoids confusion.

DUPTAP  may  be used  to  duplicate  from one  virtual  tape  device to
another.

Other TAA Tools  that operate  on tape devices  may also  be used  such
as:

            CVTDSPTAP
            CVTTAPSAVD
            DSPTAPLBL
            RTVTAPID
            RTVTAPLBL

DSPVTP data area
-----------------

The  DSPVTP command  supports  the  DTAARA  parameter which  allows  an
option  on the DSPVTP  to output the  TAAVTP data  area in QTEMP.   The
data  area will contain a list  of the available virtual tape resources
as seen on the listing  (this is the same information as seen  from the
WRKVTP F8 option for Available Resources).

You can access the first name in the list with the command:

                    RTVDTAARA   DTAARA(QTEMP/TAAVTP (1 10))
                                  RTNVAR(&xxx)

Or a  program could walk  thru the list  to see if a  specific resource
is available.

Automating the CRTVTP command
-----------------------------

CRTVTP  requires that the  virtual tape resource  that will  be used is
specified for the RSRCNAME parameter.

A simple  solution is to  create a  sufficient number  of virtual  tape
resources so you  can assign them to specific functions.   For example,
the  VRT05 tape device could  always be used with  the TAPVRT05 virtual
tape resource.

It is  possible to  write a  CL program  that will  allow the  resource
name to  be a  variable by  using the  DTAARA option on  DSPVTP.   This
creates  the TAAVTP  data  area in  QTEMP  which contains  the  list of
available  resources.   Assuming you  have some  available virtual tape
resources, you can access the data area and use the first name.

Note that  DSPVTP is preferred  over CRTVTPRSC  because CRTVTPRSC  will
add  a new  resource  if no  virtual  tape resources  are  in the  'Not
detected'  state.   In general,  you should  prevent creating  too many
resources.

The CL code could look as follows:

             DCL        &DTAARA *CHAR LEN(2000)
             DCL        &RSRCNAME *CHAR LEN(10)
             DSPVTP     DTAARA(*YES) OUTPUT(*PRINT)
             DLTSPLF    FILE(VRTTAP) SPLNBR(*LAST)
             RTVDTAARA  DTAARA(QTEMP/TAAVTP) RTNVAR(&DTAARA)
             CHGVAR     &RSRCNAME %SST(&DTAARA 1 10)
             IF         (&RSRCNAME *EQ ' ') DO
              .
              .         /* Your handling of none available */
              .
             ENDDO
             CRTVTP     VRTTAP(VRTnn) DENSITY(*VRTnnnK) +
                          RSRCNAME(&RSRCNAME)

Virtual Tape Device Authorization
----------------------------------

The  important  security  aspect  of  using  Virtual  Tape  is  who  is
authorized use to a Virtual Tape Device.

By default, a Virtual Device created by CRTVTP is *PUBLIC *EXCLUDE.

Any user  who has  *USE authority  to a  virtual device  is allowed  to
perform  a  SAVxxx  command (as  per  the  restrictions  of the  SAVxxx
command) and use  DUPTAP.   For example, if  the user  has the  special
authority  *SAVSYS,  any  SAV  command  may  be  used  on  any  object.
Without SAVSYS,  the user must have *OBJEXIST  authority to the objects
to be saved.

Even  though the  user may  not be authorized  to the  Image Catalog or
the IFS Directory, SAVxxx and DUPTAP may still be used.

CRTVTP Tool Authorization
--------------------------

Any  user   with   *USE  authority   to   the  TAAVTP   and   TAACVTIFS
Authorization  Lists may  use CRTVTP,  DLTVTP, DSPVTP,  RPLVTP, RDYVTP,
WRKVTP, or CRTVTPRSC.

The  following  programs adopt  the  QSECOFR user  profile,  but ensure
that the user is authorized  to the TAAVTP and TAACVTIFS  authorization
lists as required:

        TAATAPNC       Create Virtual Tape
        TAATAPNC2      Delete Virtual Tape
        TAATAPNC4      Display Virtual Tape
        TAATAPNC6      Ready Virtual Tape
        TAATAPNC7      Work Virtual Tape
        TAATAPNC11     Sub program for IFS functions

DLTVTP, RPLVTP, and  the various WRKVTP functions will  only operate on
a  virtual tape  structure created by  CRTVTP.   A user must  have *ALL
authority to the  device description  and the image  catalog to  delete
or replace a virtual tape structure.

Any directories created  are set according  to the DIRAUT  parameter on
CRTVTP  which defaults to  *PUBLIC DTAAUT(*EXCLUDE).   OBJAUT(*NONE) is
specified.     During  the  running  of  WRKVTP  and  DSPVTP,  the  TAA
SWPUSRPRF (Swap User  Profile) command is used  to swap to the  QSECOFR
user profile  which ensures that  any user authorized to  the TAACVTIFS
and  TAAVTP authorization  lists will have  access to  the IFS objects.
This performs as an adopted program for IFS functions.


Using SWPUSRPRF in a save operation
-----------------------------------

A user  with  only  *SAVSYS authority  will  not  be able  to  save  to
Virtual Tape unless  he is authorized for *RWX for  the directories and
stream  files.  You  may set  the *PUBLIC user  to these rights  or use
the SWPUSRPRF technique.

Because  program  adopt  does  not  allow  adoption  to  the  IFS,  the
SWPUSRPRF  command  may  be  used during  a  save  to  cause  the  same
function.    SWPUSRPRF  should  exist  in  a program  that  adopts  the
QSECOFR  profile and is authorized  to those users you  want to be able
to perform a specific save operation.

You must build up the command in a variable such as:

             DCL        &CMD *CHAR LEN(5000)
              .
             CHGVAR     &CMD ('SAVLIB LIB(LIB1 LIB2) +
                          DEV(VRT01) ...')
             SWPUSRPRF  USRPRF(QSECOFR) CMD(&CMD)

Permanent virtual tape devices
------------------------------

The  recommended approach  with  the  CRTVTP  tool is  to  replace  the
virtual tape structure  after the SAVxxx data has  been written to tape
with DUPTAP.

This  is  not a  requirement,  but is  the simplest  approach  to avoid
confusion and  ensure that  the space  required for  the  save data  is
cleaned up.

You  could have  multiple virtual  tape structures  for different  save
requirements.

It is  possible to have permanent virtual  tape structures in existence
that may be re-used.   However, you must  become familiar with  keeping
the image catalog 'ready'  and the image catalog entry  'mounted'.  See
the next section on 'Additional virtual tape resources'.

Additional virtual tape resources
---------------------------------

There are several  reasons why you may want to  have more than a single
virtual tape structure such as:

  **   Concurrent saves will be used.

  **   Multiple saves will occur before any use of DUPTAP.

  **   Individuals  may  want  their  own  virtual  tape  structure and
       determine when a SAVxxx should be run for their objects.

You may need  a unique virtual  tape device and  a unique virtual  tape
resource for each situation.

Use  the WRKVTP  command  with Option  8  to review  what virtual  tape
resources  exist.  If  you need additional virtual  tape resources, use
the WRKVTP F9 option (TAA  CRTVTPRSC command) as described  previously.
If a new resource  is not created, you may have to  create a sufficient
number  of virtual tape devices  with CRTVTP so that  all the available
virtual tape resources are used.  Then  CRTVTPRSC can be used to add  a
new resource.   The  completion message  will describe  if an  existing
virtual  tape  resource name  should  be  used or  a  new resource  was
created.

Performance considerations
--------------------------

Avoid specifying DTACPR(*YES) when saving to a virtual tape device.

Because  a SAVxxx command to virtual tape  is writing to disk (the IFS)
as  opposed  to  tape,  the  number  of  disk  arms  is  a  performance
consideration.   The more disk arms  that exist, the faster  the SAVxxx
will occur.

If  you have few  disk arms, you  may find that using  a SAVxxx command
directly to tape will provide better performance.

An option exists  to place the data  in an independent  ASP.  This  has
the advantage of  allowing you to dedicate  a disk arm for  the output.

Independent ASP Support
-----------------------

You  may create  a structure to  place the  IFS data on  an independent
ASP by specifying  a name on  the ASP  parameter of CRTVTP.   Using  an
independent ASP can be a significant performance advantage.

When using one  of the xxxVTP  supplied commands, you must  ensure that
the  independent ASP  is varied  on.   The  SAVxxx and  DUPTAP commands
have the same requirement.

WRKVTP  is tolerant of an ASP that does  not exist or is not varied on,
but the  full  information  cannot be  provided.    The ASP  name  will
appear in reverse image if not varied on.

Contrast with other TAA Tools
-----------------------------

  **   The SAVLIBSAVF  (Save Library  to Save File)  tool saves  one or
       more  libraries to save files in a  specified library.  There is
       very little  conceptual difference  between SAVLIBSAVF  and  the
       system  virtual  tape  support.     SAVLIBSAVF  saves  to  *SAVF
       objects  as opposed to a  stream file.  After  saving to offline
       media with  a  normal  SAVxxx command,  the  DLTLIBSAVF  command
       deletes the save files or you may clear the library.

       Significant differences exist with the virtual tape support:

         --   SAVLIBSAVF    cannot   be    used    for    LIB(*NONSYS).
              LIB(*ALLUSR) is supported.

         --   Saving  to a list  of save  files does not  allow overlap
              of allocation and deallocation.

         --   SAVLIBSAVF   does   not  support   saving   IFS  objects.
              However,  before saving  the  library to  offline  media,
              you could use  the SAV command to save to  a save file in
              the backup library.

         --   When  the backup library is saved  to offline media, save
              files are  saved  rather  than individual  objects.    To
              recover, you  would restore  one or  more save files  and
              then  use  normal  RST  commands  from  the  online  save
              files.    If  you  rarely   use  a  RSTxxx  command   for
              recovery, this can be a could tradeoff.

       SAVLIBSAVF   defaults  to   DTACPR(*YES)   which   significantly
       reduces  the size  required, but  will require  more CPU.   This
       may be a good tradeoff depending on your requirements.

  **   The  SRCARC (Source Archive)  tool is designed  for source files
       and allows  multiple online  versions  per source  member.   The
       UPDSRCARC command  will add new  versions to the  source archive
       based  on the last change  date of a source  member.  The SRCARC
       tool can eliminate or minimize  the need to restore source  from
       offline media.

  **   The SPLARC  (Spool Archive) tool  allows you to  archive spooled
       files.   Each spooled file  is converted to a  data base member.
       The spooled files are tracked  both online and offline based  on
       specified  retention days.   Re-printing  occurs  easily if  the
       data  base  file   containing  the  converted  spooled  file  is
       online.

  **   The  DTAARC (Data Archive)  tool allows you  to create duplicate
       files on  line and  have  multiple versions.   The  tool is  not
       intended to  replace normal saves, but rather  to provide online
       versions  which can  be reviewed  without restoring  from media.
       A similar  approach could  be done  with virtual  tape, but  you
       would have to manage the versions.

CRTVTP escape messages you can monitor for
-------------------------------------------

None.  Escape messages from based on functions will be re-sent.

DLTVTP escape messages you can monitor for
------------------------------------------

      TAA9894    No device, image catalog, or directory exists
      TAA9895    No device or image catalog exists.
                    A directory of the same name exists

Escape messages from based on functions will be re-sent.

DSPVTP escape messages you can monitor for
------------------------------------------

None.  Escape messages from based on functions will be re-sent.

RDYVTP escape messages you can monitor for
------------------------------------------

      TAA9891    Some failure occurred.

Escape messages from based on functions will be re-sent.

RPLVTP escape messages you can monitor for
------------------------------------------

None.  Escape messages from based on functions will be re-sent.

CRTVTPRSC escape messages you can monitor for
---------------------------------------------

None.  Escape messages from based on functions will be re-sent.

CRTVTP command parameters                             *CMD
-------------------------

   VRTTAP        The  name  of  the  virtual   tape  device  and  image
                 catalog to be created.

                 A  directory of  the same  name will  be created.   If
                 ASP(*SYSBAS) is used,  the /TAAVTP  directory will  be
                 created   if  it   does   not   already  exist.      A
                 sub-directory  /TAAVTP/xxxxx   will  also  be  created
                 where xxxxx is the VRTTAP value.

                 If  an ASP name is  entered, the /TAAVTP directory and
                 sub-directory will  be created in  the directory  with
                 the same  name as the  independent ASP.  The  ASP must
                 be  varied on to  perform any of  the xxxVTP commands.

   DENSITY       The density (optimum  block size)  of the tape  blocks
                 to be used.

                 The  default  is  *DFT  which is  valid  if  you  have
                 entered   a  system   wide  default   using  EDTAPPVAL
                 TAASECURE/CRTVTP.

                 The  valid   size  values   are  *VRT256K,   *VRT240K,
                 *VRT64K, or *VRT32K.

                 If a  *VRTnnnK density is  specified, it  should agree
                 with  the  block size  that  is  written  by a  SAVxxx
                 command  when  USEOPTBLK(*YES) is  specified.   If you
                 don't  know  the  size,  mount  one   of  your  SAVxxx
                 USEOPTBLK(*YES) written tapes and specify:

                     DSPTAP   DEV(xxx) DATA(*LABELS)

                 The  'Block  length'  description contains  the  block
                 size  in bytes  which is  the optimum block  size used
                 by the save.

                 The following  chart  should assist  you  in  entering
                 the density parameter.

                    Block length          DENSITY
                    in bytes              Parameter
                    ------------          ---------

                      262144              *VRT256K
                      245769              *VRT240K
                       65536              *VRT64K
                       32768              *VRT32K

                 The  special  value  *TAPDEV   may  be  entered  which
                 requires  a tape  device to  be  named for  the TAPDEV
                 parameter.   Specifying the  tape device  name  allows
                 CRTVTP  to determine  the  optimum  block size  to  be
                 used.   For  example, if  the tape  device is  a 6384,
                 the  optimum block  size is  *VRT256K and  will always
                 be used.

                 However, for  some  device  types, the  optimum  block
                 size  used is  determined by  the media  type  that is
                 mounted  when  the tape  is actually  written.   Since
                 the tape media  is normally  not mounted  when a  save
                 occurs  to virtual  tape,  you must  know the  optimum
                 block  size ahead of time.   If you are  not sure, use
                 DSPTAP  as   described   previously  and   specify   a
                 *VRTnnnK value.

                 If *TAPDEV is  specified, an informational  message is
                 sent  describing  the  *VRTnnnK  value  that  will  be
                 used.   This  should normally  agree with  the optimum
                 block size of the  block length of your save  tape and
                 the TODENSITY  parameter on DUPTAP.   Some differences
                 are valid, but be sure to check a sample restore.

   TAPDEV        The  tape device to  be used to  determine the optimum
                 block size.   The default is  *NONE meaning the  value
                 specified for the DENSITY parameter will be used.

                 If DENSITY(*TAPDEV)  is specified, you must  specify a
                 valid  tape  device  name.    This  allows  CRTVTP  to
                 determine the optimum  block density value.   See  the
                 previous  comments  for  the   DENSITY  parameter  for
                 whether you can use a device name.

                 Some  devices like  3490 support  two  different media
                 sizes  and you must  specify a *VRTnnnK  value for the
                 DENSITY parameter.

   RSRCNAME      The virtual tape resource name.

                 TAPVRTNN is the default when entered as

                 A  specific TAAVRTnn  name  must  be  entered  for  an
                 existing  available   virtual  tape  resource.     Use
                 DSPVTP   to  determine  any   available  virtual  tape
                 resources that  can  be used.    Any resource  in  the
                 section  'Available  Virtual Tape  Resources'  may  be
                 used.   If none exist, use CRTVTPRSC  to add a virtual
                 tape   resource.       The   system   assigns    names
                 TAPVRT01-TAPVRT9999 when  a new  resource is  created,
                 but only 35 may exist at a time.

   MAXSTG        The  maximum  storage in  GB.    The  default is  *DFT
                 which  means 50% of  the unused space in  ASP 1.  This
                 is not the  allocated size, but  rather the size  used
                 by  the  system support  to  determine  when to  start
                 another virtual tape volume.

                 If  the size specified  is not sufficient  to hold the
                 data to  be saved,  the system  automatically  creates
                 another  volume in  the  image  catalog with  a  large
                 maximum  size.   This complicates the  DUPTAP function
                 as you  must  do  a unique  DUPTAP  command  for  each
                 volume.

                 The  simplest  solution  is  to   allow  a  sufficient
                 maximum  size  to  avoid  having the  system  generate
                 another tape volume in the image catalog.

                 If  there  is only  one volume  in the  image catalog,
                 but DUPTAP  cannot write all  of the  saved data to  a
                 single  media volume, normal  prompting will  occur to
                 request  mounting  of additional  media.    Normal RST
                 commands can  be  used and  will request  mounting  of
                 additional media.

                 The  CRTVTP  completion  message   will  describe  the
                 amount  of storage  specified for the  volume.   If it
                 is too  low, use  DLTVTP and  re-enter CRTVTP  with  a
                 larger size.

   ASP           The ASP to place  the data in.  This  entry determines
                 the directory that will be used.

                 The  default  is *SYSBAS  which  means  ASP  1 of  the
                 system ASP.

                 A specific independent ASP name may be entered.

   TEXT          The  text description assigned to  the tape device and
                 image catalog.

                 *DFT is the default.   This will create  a description
                 of 'Created  by TAA CRTVTP  on xx/xx/xx'.   If command
                 prompting  is used,  the prompt override  program will
                 supply this value for the text description.

                 A specific text description may be entered.

                 The value of the ASP  parameter is stored in the  last
                 10  bytes  of  the  Image  Catalog  text  description.
                 This  data should be  left as  is to allow  the DLTVTP
                 command to clean up the data and directory entry.

   AUT           The authority to the  tape device description and  the
                 image catalog.

                 *EXCLUDE is  the default.   Only those users  you want
                 to be  able to use  a virtual tape  device should have
                 *USE authority to the device description.

                 *CHANGE, *USE, or *ALL may be specified.

   DIRAUT        The authority to the IFS directory.

                 *EXCLUDE is the default.

                 *RWX,  *RX, *RW, *WX, *R, *W,  or *X may be specified.

DLTVTP command parameters                             *CMD
-------------------------

   VRTTAP        The  name  of  the  virtual  tape  device   and  image
                 catalog that was created by CRTVTP.

                 Only  a  virtual  tape  device  that  was  created  by
                 CRTVTP  can  be  deleted.   The  user  must  have *ALL
                 authority to  both  the  tape  device  and  the  image
                 catalog.

                 Both the  virtual tape  device and  the image  catalog
                 will  be deleted  along with the  sub directory.   The
                 TAAVTP directory and  the virtual  tape resource  will
                 remain.

DSPVTP command parameters                              *CMD
-------------------------

   DTAARA        A *YES/*NO  value for  whether the  list as shown  for
                 the available  virtual tape resources  (those that are
                 not  assigned  to  a  virtual  tape  device)  will  be
                 output to the TAAVTP data area in QTEMP.

                 *NO is the default.  No data area will be created.

                 *YES may be specified  to create or change  the TAAVTP
                 data  area in  QTEMP with  the available  virtual tape
                 resource  names.    Each name  takes  10  bytes.   The
                 remaining area  will  be  blank.    If  no  names  are
                 available, the entire data area will be blank.

                 You can access the first name on the list with:

                    RTVDTAARA   DTAARA(QTEMP/TAAVTP (1 10))
                                  RTNVAR(&xxx)

   OUTPUT        How  to output  the  results.   *  is  the default  to
                 display  the  VRTTAP spooled  file if  the  command is
                 entered interactively.   The spooled  file is  deleted
                 after it is displayed.

                 If  the command  is  entered  in  batch or  *PRINT  is
                 specified,  the spooled file  is output  and retained.

RDYVTP command parameters                             *CMD
-------------------------

   IMGCLG        The  name  of the  image catalog  that was  created by
                 CRTVTP.  The  image catalog will  be ensured to be  in
                 a  'ready'  status  and  the corresponding  device  is
                 'varied on'.

                 *ALL  is the  default for  all image  catalogs created
                 by CRTVTP.

                 A specific  image  catalog created  by CRTVTP  may  be
                 specified.

RPLVTP command parameters                             *CMD
-------------------------

   VRTTAP        The  name  of  the   virtual  tape  device  and  image
                 catalog that was created by CRTVTP.

                 Only  a  virtual  tape  device  that  was  created  by
                 CRTVTP can  be  replaced.   The  user must  have  *ALL
                 authority  to  both  the tape  device  and  the  image
                 catalog.

                 The  current  attributes  are  extracted and  used  to
                 re-create  the structure.  Both  DLTVTP and CRTVTP are
                 used  internally.    If  you  have   not  changed  the
                 attributes  (eg  with  the  CHGIMGCLGE  command),  the
                 structure  will  look  the same  as  you  created with
                 CRTVTP.

                 The authorizations are  copied from  the current  tape
                 device and image catalog to the new objects.

WRKVTP command parameters                             *CMD
-------------------------

No parameters exist.

CRTVTPRSC command parameters                          *CMD
----------------------------

No parameters exist.

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

You   must  have   *USE   authority  to   the   TAAVTP  and   TAACVTIFS
Authorization Lists to use the commands.

Only  a virtual  tape structure  created  by CRTVTP  may be  deleted by
DLTVTP or replaced by RPLVTP.

The ASP  parameter value  specified on  CRTVTP is  placed in  positions
41-50 of the image  catalog text description.  This value  must be left
as is.

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

The following TAA Tools must be on your system:

     CHGOBJD2        Change object description 2
     CHKIFSE         Change IFS entry
     CVTOBJD         Convert object description
     CVTIMGCLG       Convert image catalog
     CVTIMGCLGE      Convert image catalog entries
     DSPTAPLBL       Display tape label
     RSNLSTMSG       Resend last message
     RTVDEVTAP       Retrieve device tape
     RTVSPCAUT       Retrieve special authority
     RTVSYSVAL3      Retrieve system value 3
     RTVTAPLBL       Retrieve tape label
     RTVVTPRSC       Retrieve virtual tape resource
     SNDCOMPMSG      Send completion message
     SNDDIAGMSG      Send diagnostic message
     SNDESCINF       Send escape information
     SNDESCMSG       Send escape message
     SNDLNGMSG       Send long message
     SWPUSRPRF       Swap user profile

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

None, the tool is ready to use.

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

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

   CRTVTP        *CMD                   TAATAPN       QATTCMD
   DLTVTP        *CMD                   TAATAPN2      QATTCMD
   CRTVTPRSC     *CMD                   TAATAPN3      QATTCMD
   DSPVTP        *CMD                   TAATAPN4      QATTCMD
   RPLVTP        *CMD                   TAATAPN5      QATTCMD
   RDYVTP        *CMD                   TAATAPN6      QATTCMD
   WRKVTP        *CMD                   TAATAPN7      QATTCMD
   TAATAPNC      *PGM       CLP         TAATAPNC      QATTCL
   TAATAPNC2     *PGM       CLP         TAATAPNC2     QATTCL
   TAATAPNC3     *PGM       CLP         TAATAPNC3     QATTCL
   TAATAPNC4     *PGM       CLP         TAATAPNC4     QATTCL
   TAATAPNC5     *PGM       CLP         TAATAPNC5     QATTCL
   TAATAPNC6     *PGM       CLP         TAATAPNC6     QATTCL
   TAATAPNC7     *PGM       CLP         TAATAPNC7     QATTCL
   TAATAPNC11    *PGM       CLP         TAATAPNC11    QATTCL
   TAATAPNC14    *PGM       CLP         TAATAPNC14    QATTCL
   TAATAPNC17    *PGM       CLP         TAATAPNC17    QATTCL
   TAATAPNC18    *PGM       CLP         TAATAPNC18    QATTCL
   TAATAPNR4     *PGM       RPG         TAATAPNR4     QATTRPG
   TAATAPND      *FILE      DSPF        TAATAPND      QATTDDS
   TAATAPNE      *FILE      DSPF        TAATAPNE      QATTDDS

The CRTVTP Application Value (*USRSPC) exists in TAASECURE.

Structure
---------

CRTVTP      Cmd
   TAATAPNC   CL pgm
     TAATAPNC11   CL pgm for prompt override

DLTVTP      Cmd
   TAATAPNC2  CL pgm

CRTVTPRSC   Cmd
   TAATAPNC3  CL pgm

DSPVTP      Cmd
   TAATAPNC4  CL pgm
     TAATAPNR4  RPG pgm
       TAATAPNC14   CL pgm

RPLVTP      Cmd
   TAATAPNC5  CL pgm

RDYVTP      Cmd
   TAATAPNC6  CL pgm

WRKVTP      Cmd
   TAATAPNC7  CL pgm
     TAATAPNR7  RPG pgm
       TAATAPNC14  CL pgm to access size
       TAATAPND  Dsp file
       TAATAPNC17   Sub pgm for options and F keys
         TAATAPNC18    Sub pgm for vary on of IASP
           TAATAPNE      Dsp file
					

Added to TAA Productivity tools July 15, 2006


Home Page Up to Top