CA-1 Support of IBM 3494 and 3494/VTS Tape Library Data Server Full Support

Document ID : KB000027840
Last Modified Date : 14/02/2018
Show Technical Document Details

CA-1 release 12.6 and release 14.0 support the IBM 3494, and 3494/VTS. CA-1 scratch sub pooling is not supported for these devices, because the mount message is issued already marked as suppressed, so CA-1 does not see it. And OAM does not mount cartridges based on the mount message, so even if the mount message is changed by CA-1 it will not change the selection of which volume to mount.

CA-1 provides 3 exits to help communicate with the robot; they are CBRUXENT, CBRUXEJC, and CBRUXVNL. These are provided via USERMODS, CTSJUCBR, CTSJUCBX and CTSJUCBN.

CBRUXENT

This exit is used during the insertion of a physical tape, the definition of a virtual tape or the import of a virtual tape. It will determine the status of the tape within the TMC and then allow or disallow the entry of the tape, and set the status in the TCDB to scratch or private, same as found in the TMC. Within the TMC the ROBTY and ROBID will be updated to indicate the tape is in the ATL or VTS. By default we do not allow a foreign tape to be entered into the ATL, it will be left in "insert" status.

This exit will need to have the SMS name of each robot entered into a table. This modification will be required regardless of the environment and should always be made.

CBRUXEJC

This exit is used during the eject of a physical tape or the export of a virtual tape. For a physical tape it will clear the ROBTY and ROBID during an eject. During an export CA-1 will clear the OUTCODE, OUTDATE, SLOT and ROBID fields, the ACTVOL will be updated with the physical VOLSER and FLAG5 will be set to 20 (VTX). CA-1 will take the physical tape used during the export out of scratch or delete status, set the EXPDT to PERM, set the DSN to the pseudo data set name that you have specified in the exit, set FLAG3 to 20 (EDM), and set the CDATE to today's date. We will change the OUTCODE, and SLOT in the physical tape to match the vaulting data from the first VTS VOLSER that was exported. The OUTDATE will be set to the current date. You will then need to use the pseudo DSN for vaulting. TMSVMEDT has been changed to skip all volume records that have the VTX (volume exported bit x'20') on in FLAG5.

This exit will need to be modified if you are using the 3494/VTS with the import and export functions. A pseudo DSN will need to be added to the code so that CA-1 can track the physical tapes used during the export. If you are using a 3494/VTS without the import/export feature, or if you are using a 3494/ATL, then no modification is needed to the CA-1 supplied version. However, the CA-1 supplied exit should be installed so that the correct TMC fields are updated when a cartridge is ejected from the robot.

CBRUXVNL

This exit can be used to notify you that a tape is not in the ATL, so that you can insert it and then retry the allocation, without canceling the job. Please be aware that IBM code calls this exit for DASD that is offline and for all tapes (even round reels) not in an SMS managed IBM robot.

This exit is strictly optional; no updates are done to CA-1 or to OAM based on this exit. The only time you would need to install and use this exit is if you wanted to allow operations the chance to insert a cartridge (or import a virtual-volume) back into the 3494 and re-drive the allocation instead of simply allowing the job to have a JCL error or abend. If you have a 3494/ATL with similar devices both inside and outside the robot (so any tape can be mounted either inside or outside the 3494), then there is no need to use this exit. Likewise, if you have a 3494/VTS without the IMPORT/EXPORT feature there is no need to use this exit (since all virtual volumes will always be inside the robot).

Please look at the code and determine what you would like to have done if the tape you are requesting is not in the library. For example, if you have 3490 drives outside the 3494 and have only 3590 drives insice the 3494, you would want to un-comment out two lines that compare the CA-1 returned density with the value "3590". If you did not un-comment out these two lines, then ALL allocations for the 3494 would be driven through the CBRUXVNL exit.

CA-1 provides one other program CTSSYNC, and EARL programs to help drive communication with OAM during CA-1 daily processing. The EARL programs are TMEEJECT, TMEACTVL, TMEIMPRT, and TMEVTINV.

CTSSYNC

CTSSYNC is used to communicate with OAM, via LCS services. It is the main interface module between OAM and CA-1. It can be used to eject tapes for a physical ATL, or import/export tapes for a VTS. It can also be used to resynchronize the TCDB with the TMC.

When using CTSSYNC to import or export tapes from the VTS there are 2 DD statements (EXPORT DD and IMPORT DD) in the JCL that must point to a unit in the VTS. This is where we will record the VOLSERs that are to be imported or exported. Only one IMPORT or EXPORT can be run at a time. If you schedule another IMPORT or EXPORT when one is running, CTSSYNC will end with an error message.

Documentation on this program can be found in the CA-1 Utilities and Reports Reference Guide.

TMEEJECT will read the output from TMSVMVLT and produce EJECT or EXPORT control statements for the tapes in the ATL that are to be vaulted. The output from TMEEJECT can be used as input to CTSSYNC to do the EJECT of a physical tape or the EXPORT of a virtual tape.

TMEACTVL will list 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, (all virtual volumes have been imported or all virtual volumes have expired); it will produce TMSUPDTE control statements to help automate the scratching of the physical tape. Once the tape has been scratched you will need to manually insert the physical tape into the library as an eligible stacking volume. Information on how to do this can be found in the IBM manual, 3494/VTS User's Guide.

TMEIMPRT can be used to help produce the control statements for CTSSYNC to import all virtual volumes on a physical tape. You need to supply the VOLSER of the physical tape to be used in the import. If some of the virtual volumes are in scratch status, CA-1 will build the control statements so that the actual data on the virtual volume is not copied into cache.

TMEVTINV will list the physical tapes and the associated exported virtual tapes.

Recommendations and Procedures for ATL

Install usermods, CTSJUCBX or CTSJUCBR and CTSJUCBN. These will assemble and link CBRUXENT, CBRUXEJC, and CBRUXVNL.

In CTAPOPTN member TMOOPTxx set ROBSCR to YES, and set WRKFLS to NO.

If you have the YSVC option set to YES then give OAM update access to YSVCUNCD.

Procedures:

Run your normal daily CA-1 maintenance job. When TMSCLEAN runs it will notify the  ATL which tapes have been scratched. After your job for vault management, you will need to run TMEEJECT to build control statements for CTSSYNC to EJECT the cartridges from the ATL. As cartridges are returned from the vault you can insert them back into the  ATL.

Recommendations and Procedures for  VTS without IMPORT/EXPORT feature

Install usermods, CTSJUCBX or CTSJUCBN and CTSJUCBR. These will assemble and link  CBRUXENT, CBRUXEJC, and CBRUXVNL.

In CTAPOPTN member TMOOPTxx set ROBSCR to YES, and set WRKFLS to NO.

If you have the YSVC option set to YES then give OAM update access to YSVCUNCD.

Procedures:

Run your normal daily CA-1 maintenance job. When TMSCLEAN runs it will notify the 3494 ATL which tapes have been scratched.

Recommendations and Procedures for Peer to Peer

Install usermods, CTSJUCBX, or CTSJUCBN and CTSJUCBR. These will assemble and link CBRUXENT, CBRUXEJC, and CBRUXVNL.

In CTAPOPTN member TMOOPTxx set ROBSCR to YES, and set WRKFLS to NO.

Procedures:

Run your normal daily CA-1 maint job.

Note: If the elapsed run time of TMSCLEAN becomes to long, then set ROBSCR to NO and run CTSSYNC for the VOLSERs that were scratched to update the status in the device.

Recommendations and Procedures for VTS with IMPORT/EXPORT feature

Install usermods, CTSJUCBX or CTSJUCBN and CTSJUCBR. These will assemble and link CBRUXENT, CBRUXEJC, and CBRUXVNL.

In CTAPOPTN member TMOOPTxx set ROBSCR to YES, and set WRKFLS to NO.

If you have the YSVC option set to YES then give OAM update access to YSVCUNCD.

If you are vaulting data sets that are on virtual tapes and they go to different vaults you will need to make some changes to CBRUXEJC and TMEEJECT. In CBRUXEJC you will need to ad logic to compare the DSN or other data and set different pseudo DSN's for the physical tape. In TMEEJECT you will need to add logic to 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 the VOLSER to be exported and VLT1 and VLT2 could be the vault name or any other meaningful destination for your site.
When CTSSYNC is run with these control statements, all tapes with VLT1 will be exported together, and all tapes with VLT2 will be 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 offsite until it expires you do not need to add a vault pattern for the pseudo DSNs. If you need to keep them a number of days, then you need to have a new vault pattern with the pseudo DSN.

Procedure for vaulting when using the IMPORT/EXPORT feature:

    1. Run TMEACTVL to build control statements for TMSUPDTE to expire physical tapes when all virtual volumes stacked upon them have been imported or scratched.
    2. Run TMSUPDTE with the control statements from TMEACTVL. The volumes will be changed to "scratch" status the next time TMSCLEAN runs.
  1. Run your daily CA-1 job for vaulting (TMSVMEDT, TMSVMVLT, and TMSVMUPD).
    1. Run TMEEJECT to build the CTSSYNC control statements to eject the physical tapes in an ATL and export the virtual tapes.
    2. Run CTSSYNC to do the ejects and/or exports.
    1. 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
    2. Run CTSSYNC using the control statements from TMEIMPRT.

Sharing a ATL or VTS

There are two ways that a ATL or VTS can be attached to multiple systems. First is to "partition" the box (make it look like two separate box's, each section attached to a different system) or you can share the ATL or VTS with different systems. In fact, you can partition the box and have one partition shared between some systems and have the second partition shared between different systems.

Normally, when the ATL or VTS is going to be shared between different operating systems; the box is partitioned. So one partition is used by z/OS (most likely shared by a couple of z/OS systems) and one partition is used by the other operating system (z/VM for example). In a partition mode, the tape box operates as if there where two separate box's and tape volumes cannot be shared. So tapes created in one partition cannot be used in the other partition.

For more information on sharing or partitioning a ATL or VTS, it is strongly recommended that you review the DFSMS Object Access Method Planning, Installation, and Storage Administration Guide for Tape Libraries manual.

When sharing a ATL or VTS between z/OS systems there are 4 different ways to configure your CA-1 and OAM environment.

  1. Common CA-1 TMC and common OAM TCDB (Tape Catalog Database, also known as the VOLCAT)
  2. Separate CA-1 TMC's and separate OAM TCDB's
  3. Common CA-1 TMC and separate OAM TCDB's
  4. Separate CA-1 TMC's and a common OAM TCDB

Each of these presents slightly different requirements and may meet different needs. Below are some of the items within the CA-1 supplied exits that may need to be customized depending on your environment.

Common CA-1 TMC and common OAM TCDB

This is probably the most common way to share a ATL or VTS box. All z/OS systems share a common TMC and a common TCDB. In this environment, very few modifications to the CA-1 supplied entry and eject exits would need to be done. If you wanted to have the ability to enter foreign tapes into the robot (cartridges not defined to CA-1), you would have to change the entry (CBRUXENT) exit. In the CA-1 supplied exit (CTSUXENT in the CAISRC library) there is a small branch table after label "ASKCA"; where a branch to label's RC0, RC4, RC8, RC12, RC16 and RC20 is made. If you want to read foreign tapes inserted into the ATL, the easiest modification is to change the branch table so that in the case of a foreign tape the branch is made to RC8 instead of to RC16. So simply change "B RC16" to "B RC8" for foreign tapes. If you will not be reading foreign tapes inside the ATL (for example, if the VTS has no native-attached physical devices) then there is no need to modify either the entry or eject exits supplied with CA-1.

Separate CA-1 TMC's and separate OAM TCDB's

This is probably the second most common way to share a ATL or VTS when the device is not actually partitioned. It is almost the same as having the device partitioned, but gives the user more flexibility in terms of adjusting the size (number of volumes and/or number of devices) on each "side" without having to redefine the partitions. For basic operation, the CA-1 supplied entry and eject exits will not need to modified at all. However, if foreign tapes are going to be inserted into the device and used on one of the systems; then a more complicated version of the entry exit will be needed.

For an example, we will assume that CPUA and CPUB share a device with separate TMC's and TCDB's, and we want to allow foreign tapes to be used as input on CPUA. In this case, the entry and eject exits for CPUB would be unchanged. Since CPUA cartridges would foreign to CPUB, when CPUB is notified that a CPUA cartridge has been inserted it would simply ignore it. Then, when CPUA was notified it would assign the correct status (SCRATCH or PRIVATE) and take ownership of the cartridge.

However, in the same example the entry exit on CPUA would have to be modified and it would be more complicated. In the CA-1 supplied entry exit (CTSUXENT in the CAISRC library), there would have to be code added at label RC16. If the volume being inserted is defined to CPUB (which means a table would need to be created or a set of compares would need to be done to see if the volser matches those defined to CPUB), then the instruction "LA R15,UXEIGNOR" would need to be performed (followed by the branch to EXIT). However, if the tape is not defined to CPUB (again, based on the volser) then you would want to branch to label RC8 (which would put the foreign tape into PRIVATE status and take ownership of it on CPUA). Depending on the volser standards on CPUB, this could be very simple (look for a cartridge starting with "B0" or "B1") or very complicated.

Common CA-1 TMC and separate OAM TCDB's

This is not a recommended method to use, however it can be done. This gives the user the ability to logically partition the 3494 (with separate TCDB's) but have a common CA-1 TMC. The problem is that the entry exit (CTSUXENT in CTAPSAMP) would need to be modified on both systems AND there would need to be additional modification to the TMSXITS usermod (the SCRATCH exit in the TMSXITS CA-1 exit). The entry exit on CPUA would need to have all the CPUB cartridges defined to it, and not take ownership of them (even though they are defined to the TMC). This additional code would best be done PRIOR to the "ASKCA" label, since you know that all the cartridges are know to both systems (since they share a common TMC). So, on CPUA before the ASKCA label you would have to compare the volser and see if it is owned by CPUB. If so, then branch to label RC16 (leave it in insert status for CPUB to take ownership). Likewise on CPUB, the exit would have to look for CPUA cartridges and branch to label RC16 for them (so that CPUA could take ownership of its cartridges). If there is a desire to share a common exit on both systems, then the exit will need to be modified to look at the SMFID or SYSTEM-NAME and make the determination if the volser should be owned or not based on a combination of which system it is running on and which tape is being inserted.

Also, it would be best to disable the real-time scratch exit by setting ROBSCR=NO in the TMOOPTxx member. Instead, take the scratch list created by TMSCLEAN and break it into two separate lists. One would be a list of CPUA owned scratch tapes and one would be a list of CPUB owned scratch tapes. Then, on each system you would have to run CTSSYNC taking in the correct list of scratch tapes (CTSSYNC can be run with PARM=SYNC and the sysin would simply be a list of cartridges).

Separate CA-1 TMC's and common OAM TCDB

This is not a recommended method to use and should be avoided. Since CPUA and CPUB have a common OAM TCDB, then any tape could be mounted to satisfy a scratch request on either system. By having different categories defined on each system (this is done by modifying SYS1.PARMLIB members as explained in the OAM PISA manual), the problem of shared scratch pool could be removed. However, it would still be possible to request a specific-volume from either system for any volume. Since CA-1 would only know about it's tapes and not about the other systems tapes, they would appear as FOREIGN. So using EXPDT=98000 you could read (or update) active tapes from the other system. So in this case, you would have to tightly restrict the use of EXPDT=98000 processing. If not, then anyone that has access to EXPDT=98000 processing could request tapes from the other system and read and/or modify the existing data. Since full 44-character dataset name checking would NOT be available, external security rules would not be sufficient.

The entry and eject exits could be used as shipped with CA-1 without modification. And the real-time scratch processing performed with the CL05228 or CL05245 usermod could be run on both systems.