IBM Virtual Tape Server (VTS)

This section documents how to configure
CA 1
to work with the IBM TotalStorage Virtual Tape Server (VTS). For information on the basic IBM ATL and a general introduction to
CA 1
robotics support, see sections TMC Fields Used to Track Tapes in Automated Tape Libraries and IBM Tape Library.
As with the IBM ATL, integration between
CA 1
and the IBM VTS is based on four exits/options that are used to communicate with the robot:
     -- IBM OAM Volume Entry
     -- IBM OAM Volume Eject
     -- IBM OAM Volume Not In Library
    ROBSCR -- 
    CA 1
    option (see member TMOOPTxx) to notify OAM when a tape volume is scratched
IBM VTS - CBRUXENT Volume Entry Exit
The OAM CBRUXENT exit is executed whenever a tape cartridge is inserted into the ATL, or when a virtual volume is imported from a physical tape or defined to the VTS. The CBRUXENT exit provided by
CA 1
determines the status of the tape within the TMC. CRBRUXENT then allows or disallows the entry of the tape and sets the status in the TCDB to scratch or private based on the status in the TMC. When installed, the CBRUXENT exit provided with
CA 1
updates TMC fields ROBTY and ROBID to indicate the tape is in the ATL. By default, a foreign tape may not be entered into the ATL. If this is attempted, the tape is left in insert status. This exit must be customized to specify the SMS name of each robot in an internal table for both ATL and VTS implementations.
For more information about
CA 1
provided CBRUXENT exits, see IBM ATL CBRUXENT Volume Entry Exit
IBM VTS - CBRUXEJC Volume Eject Exit
The CBRUXEJC exit is invoked when a physical tape is ejected and when a virtual tape is exported. Modify this exit if you are using the VTS with the import and export functions. A pseudo DSN needs to be added to the code so that
CA 1
can track the physical tapes used during the export. If you are using a VTS without the import/export feature, or if you are using an ATL, modification to the
CA 1
supplied version is not necessary.
During an export function, the following actions are taken on the virtual volumes that are being exported:
  • CA 1
    clears the OUTCODE, OUTDATE, SLOT, and ROBID fields
  • ACTVOL is updated with the physical VOLSER that the virtual volumes are being exported to
  • FLAG5 is set to 20 (VTX - Virtual Tape Exported)
The following actions are taken on the physical volume (also referred to as the container volume):
  • The physical tape is taken out of scratch or delete status
  • The EXPDT is set to PERM
  • The DSN is set to the pseudo data set name that you have specified in exit CBRUXEJC
  • FLAG3 is set to 20 (EDM - External Data Manager)
  • Creation date (CDATE) is set to today's date
  • The OUTCODE and SLOT in the physical tape are set to match the vaulting data from the first virtual volume that was exported to this physical volume
  • OUTDATE is set to the current date
The pseudo DSN that is assigned to the physical volume should be added to the Vault Pattern Data Set to define the vault movement that is desired for exported VTS volumes. The vault system utility TMSVMEDT has been changed to skip all volume records that have the VTX (volume exported bit x'20') on in FLAG5.
IBM VTS - CBRUXVNL Volume Not in Library
The OAM CBRUXVNL exit is invoked when a requested tape is not found in the ATL, providing an opportunity to insert the tape into the ATL and retry allocation without canceling the job. Use of this exit is strictly optional. If you select to use this exit, you should be aware that OAM also calls this exit for DASD that is offline and for all tapes (even round reels) not in an SMS managed IBM robot.
There are no
CA 1
OAM updates performed based on this exit.
This exit is only installed and used to allow operations an opportunity to insert a cartridge (or import a virtual volume) back into the ATL/VTS and re-drive the allocation rather than simply allowing a JCL error or abend to occur during the job. If you have a VTS without the IMPORT/EXPORT feature this exit is not necessary (all virtual volumes are always inside the robot.)
This exit must be customized for your environment. You must also determine what processing needs to be done if the tape you are requesting is not in the library. For example, if you have 3490 drives outside the ATL and have only 3590 drives inside the ATL, un-comment out two lines that compare the
CA 1
returned density with the value "3590". If you do not un-comment out these two lines, then ALL allocations for the ATL are driven through the CBRUXVNL exit.
CA 1
ROBSCR Support for the IBM VTS
Use the ROBSCR option in TMOOPTxx of 
.CTAPOPTN to indicate that the robotic (virtual) tape system should be notified when a tape volume has gone scratch. Which robotic or virtual tape system to notify is based on the TMROBTY field in the TMC.
If the ROBSCR option is set to YES, and the TMROBTY field in the TMC record for the scratched volume is set to x'01' or x'81', then OAM is called when that specific volume is scratched.
If ROBSCR is set to YES and
or Oracle/STK are used, the
or Oracle/STK library must be either link-listed in the system linklist or added as a STEPLIB in the TMSCLEAN proc (TMSCLEAN proc step).
CA 1
CTSSYNC Utility Support for the IBM VTS
Use the CTSSYNC utility to communicate with OAM using LCS services for the basic ATL and for the VTS. It is the main interface module between
CA 1
and OAM. CTSSYNC is used to eject tapes or to perform import/export functions for a VTS. It can also be used to synchronize the TCDB with the TMC.
When using CTSSYNC to import or export tapes from the VTS one of the following additional DD statements is required:
  • Export operations require you to specify an EXPORT DD
  • Import operations require you to specify an IMPORT DD
These DD statements must point to a unit in the VTS. The list of virtual volumes to be imported or exported is passed to the VTS by temporarily using a virtual volume in scratch status that is allocated with the EXPORT or IMPORT DD statement. For this reason, the virtual volume written on must reside in the same VTS that the volumes are being exported from or imported to. Only one IMPORT or EXPORT can be run at a time.
CTSSYNC can perform eject, export, import or synchronize functions on either a range of volsers or a list of volsers.
CA 1
provides the following
report members in 
.CTAPECPB to create control statements that can be processed by CTSSYNC:
    Creates export or eject control statements from the output of the vault management system.
    Creates import control statements for a specified physical volser you specify. If some of the virtual volumes are in scratch status,
    CA 1
    builds the control statements so that the actual data on the virtual volume is not copied to cache.
Two following
report members list VTS physical volumes and assist in creating TMSUPDTE transactions to manage scratching the physical volume when all virtual volumes have expired:
    Lists the physical tapes that have been used for export processing and the virtual tapes that have been put on each one. If the physical tape is no longer needed, (that is, if all virtual volumes have been imported or all virtual volumes have expired,) it produces TMSUPDTE control statements to help automate the scratching of the physical tape. Once the tape has been scratched you manually insert the physical tape into the library as an eligible stacking volume.
    For information, see 
    IBM VTS User Guide
    Lists the physical tapes and the associated exported virtual volumes.
Recommendations and Procedures for IBM VTS Without IMPORT/EXPORT
The following usermod must be installed to provide support for the IBM VTS without the IMPORT/EXPORT feature:
  • CTSJUCBX -- Applies your customized source to CBRUXENT, CBRUXEJC (and optionally CBRUXVNL) to your z/OS linklib
The following
CA 1
system parameters and procedures should also be set:
  • ROBSCR=YES -- Set in TMOOPTxx member of CTAPOPTN to enable real-time scratch processing.
  • WRKFLS=NO -- Set in TMOOPTxx member of CTAPOPTN. This causes
    CA 1
    to assign a 1 day retention to all work files.
  • If YSVC=YES you must update your security system to give OAM update access to resource YSVCUNCD.
Run your normal daily
CA 1
maintenance jobs and when TMSCLEAN runs, it notifies the VTS of which tapes have been scratched. All tapes (virtual volumes) remain within the VTS.
Recommendations and Procedures for IBM VTS with IMPORT/EXPORT
The following usermod must be installed to provide support for the IBM VTS in configurations where the IMPORT/EXPORT feature is used:
  • CTSJUCBX -- Applies your customized source to CBRUXENT, CBRUXEJC (and optionally CBRUXVNL) to your z/OS linklib.
The following
CA 1
system parameters and procedures should also be set:
  • ROBSCR=YES -- Set in TMOOPTxx member of CTAPOPTN
  • WRKFLS=NO -- Set in TMOOPTxx member of CTAPOPTN. This causes
    CA 1
    to assign a 1 day retention to all work files.
  • If YSVC=YES you must update your security system to give OAM update access to resource YSVCUNCD.
If you are vaulting data sets that are on virtual tapes and they go to different vaults, some changes to to CBRUXEJC and TMEEJECT need to be made. In CBRUXEJC, add logic to compare the DSN (and optionally other data fields) and set different pseudo DSNs for the physical tapes to be created. In TMEEJECT add a destination on the EXPORT control statements for CTSSYNC depending on the pseudo DSN that was set:
EXPORT,vvvvvv,VLT1 EXPORT,vvvvvv,VLT2
The vvvvvv is replaced with the VOLSER to be exported and VLT1 and VLT2 are examples of separate vaults you want physical volumes exported to. These names can be the vault name or any other meaningful destination for your site.
When CTSSYNC is run with these control statements, all tapes with VLT1 are exported together and all tapes with VLT2 are exported onto another tape. This gives you the separation so that you can have exported tapes going to different vaults. If you are going to keep the physical tape off-site until it expires you do not need to add a vault pattern for the pseudo DSNs. To keep them a number of days, have a new vault pattern with the pseudo DSN.
Use the following steps for Vaulting when using the IMPORT/EXPORT feature:
  1. Modify and run TMEACTVL to build control statements for TMSUPDTE to expire physical tapes when all virtual volumes stacked upon them have been imported or scratched. Set the value EXPIRE_DAYS to the number of days you currently have your TS77xx EXPIRATION TIME value set to.
  2. Run TMSUPDTE with the control statements from TMEACTVL. The volumes are changed so that they expire in xx days (based on your setting) and, once expired, are returned from the vault.
  3. Run your daily
    CA 1
    job for vaulting (TMSVMEDT, TMSVMVLT, and TMSVMUPD).
  4. Run TMEEJECT to build the CTSSYNC control statements to eject the physical tapes in an ATL and export the virtual tapes.
  5. Run CTSSYNC to do the ejects or exports.
  6. Run TMEIMPRT to build the CTSSYNC control statements to do the IMPORT for the tapes returned from the vault, after they have been received back in the library and are ready to be put back into the VTS
  7. Run CTSSYNC using the control statements from TMEIMPRT.
Exported Virtual Volume Considerations
Virtual volumes that have been exported or externalized to a physical volume are now processed by the vaulting system. Once the VTX bit x'20' FLAG5 has been turned on in the TMC record, virtual tapes continue to be moved according to the VPD rule, but slot assignment is bypassed. The slot number is set to a dummy value of 9,999,999 (a "virtual slot"). This virtual slot number of 9,999,999 will be displayed on any ISPF display or the TI display and the Vantage/GUI display.
These exported virtual volumes do not appear on picking or distribution list (there is no physical cartridge to move). They are displayed on the inventory list with the physical container volume (ACTVOL) in place of the slot number preceded by an asterisk (*). So, on the inventory list the slot number might be displayed as *C12345 when C12345 is the container volume that the virtual volume has been exported onto.