//stepname EXEC PGM=CTSSYNC,PARM='parm'
//STEPLIB DD DISP=SHR,DSN=CAI.CTAPLINK
//SYSPRINT DD SYSOUT=* *NOTES
//ERREPORT DD SYSOUT=* *NOTES
//EXPORT DD DSN=EXPORT.TAPE.LIST, *NOTES
UNIT=VTAPE,TRTCH=NOCOMP,DISP=(,CATLG)
//IMPORT DD DSN=IMPORT.TAPE.LIST, *NOTES
UNIT=VTAPE,TRTCH=NOCOMP,DISP=(,CATLG)
//SYSIN DD * *NOTES
(control statements here)
/*
Notes:
Do not specify 'VOL=(,RETAIN)' on this DD statement. Specifying VOL=(,RETAIN) causes the EXPORT list volume to remain on the tape drive. The robot does not consider the list volume available if it is mounted, so the EXPORT invoked by CTSSYNC fails.
Do not specify 'VOL=(,RETAIN)' on this DD statement. Specifying VOL=(,RETAIN) causes the IMPORT list volume to remain on the tape drive. The robot does not consider the list volume available if it is mounted, so the IMPORT invoked by CTSSYNC fails.
Control Statements
The CTSSYNC utility processes the following commands:
The VERIFY command instructs the system to verify whether the volume serial number is defined in the 3495/3494 LCS database before executing any further commands. If the NOVERIFY command is specified, the LCS commands are issued even if the cartridge does not reside in the 3495/3494 LCS database. The VERIFY command is the default.
The BULK command instructs any of the following EJECT commands to be sent to the bulk location. The NOBULK command instructs all of the following EJECT commands to be sent to the convenience location. If neither BULK nor NOBULK commands are specified prior to an EJECT command, the utility defaults to the bulk location.
The FORCE command instructs the program to execute any following SYNC commands unconditionally, regardless of the current use attribute in the TCDB. The NOFORCE command causes SYNC commands to be processed only if the use attribute in the TCDB does not match the volume status in the tape database, or if TCDB or Library Manager show an error indicator. NOFORCE is the default.
The EJECT command instructs the 3495/3494 robotic devices to eject the specified VOLSER(s). Depending on whether a BULK or NOBULK commands is specified prior to the EJECT command, the cartridge is ejected to either the bulk or the convenience location.
The PROTECT, SCRATCH, and PRIVATE commands all change the status of the specified VOLSER(s). The SCRATCH command changes the status to scratch, while the PROTECT and PRIVATE commands change the status to private within the 3495/3494 LCS database. This affects both cartridge(s) that are selected to satisfy SCRATCH requests, and cartridge(s) that are added to auto cartridge loaders (ACLs) located inside the 3495/3494 robotic devices. There is no difference between PROTECT and PRIVATE commands.
The SYNC command causes the specified VOLSER(s) to be synchronized between the tape management database and the 3495/3494 LCS database. If the status is different, the tape management database is assumed to be correct. This is the default if no specific command is specified.
The EXPORT command causes the specified LOGICAL VOLSER(s) to be written to the export list volume, a logical volume residing in the same library as the volumes to be exported. After all volumes have been written to the export list volume, the OAM LCS schedules the list to be exported.
This sub-parameter can only be included on the EXPORT control statement and is optional. If included, all virtual volumes with the same destination are stacked together on a single physical volume. If a list of 50 virtual volumes to be exported is supplied; and 25 has one destination and the other 25 has a different destination, then the first 25 would be stacked together on one set of physical volume(s) and the other 25 would be stacked on a different set of physical volume(s). However, this value is not sent to the CBRUXEJC exit during eject processing nor is it tracked in the TCDB or the tape management catalog.
The IMPORT command causes the specified LOGICAL VOLSER(s) to be written to the import list volume, a logical volume residing in the same library as the volumes to be imported. After all volumes have been written to the import list volume, the OAM LCS schedules the list to be imported.
Note: Only 1 EXPORT or IMPORT command can be scheduled at a time. Subsequent EXPORTs or IMPORTs are shown as errors by CTSSYNC utility.
One of these two optional sub-parameters can be included on the IMPORT command control statement. If the specific virtual volume(s) are specified, the default PRIVATE indicates that the specified virtual volume should be copied back into cache inside the 3494/VTS completely. The entire virtual volume is copied). If SCRATCH command is specified, then the specified virtual volume is assumed to be in scratch status and only the VOL1/HDR1/HDR2 records are copied back into cache. This process reduces the time needed to complete the IMPORT process. The virtual volumes cannot be made un-scratched, since the data on them no longer resides inside the 3494/VTS.
ABDLMT command is a keyword parameter that is used to set a return code limit at which CTSSYNC will ABEND. After CTSSYNC utility has completed all other processing and is about to terminate, the numeric value of ABDLMT is compared with the highest return code from any command. If that return code is greater than or equal to the ABDLMT, CTSSYNC utility abends with U0006 and a reason code equal to the return code. The default is ABDLMT=99. It can be in either the ABDLMT=nn or the ABDLMT(nn) form. It can be specified in the EXEC PARM field or in a SYSIN statement. It can be specified on a statement alone or with other commands. It can be specified multiple times, but only the last value is used.
Performs like the SYNC command but does not call to update the OAM. Both the TCDB (VOLCAT) and the Library Manager (LM) database are compared with the TMC too. If the status of the volume is not synchronized in all three data bases or catalogs, an error is reported to both the SYSPRINT and ERREPORT DD statements.
Performs like the EXPORT command except that the exported volumes are copied, not moved. List the VOLSERs to be exported below the COPY command in the SYSIN DD.
Note: Specify the POOL parameter before you export the volumes.
Specifies the physical volume pool that contains the logical volumes to export. This command is only used with the COPY command.
Examples of Specifying Commands to CTSSYNC
There are three methods of getting the commands or VOLSERs to the CTSSYNC utility: PARM= on the EXEC statement, through SYSIN control statements, or passed in a parameter list through Register 1. The easiest way to perform a single command is through use of the PARM statement on the EXEC command.
//STEP1 EXEC PGM=CTSSYNC,PARM='EJECT,123456'
This causes cartridge 123456 to be ejected from the 3495/3494 robotic device. The same value could have been used as input from the SYSIN control statements.
//SYSIN DD * EJECT,123456
The command can also be passed in a parameter list pointed by Register 1. This is used if another program, such as the security exit wants to call the synchronization program passing it the command. The format of the parameter list pointed by Register 1 is as follows:
R1 ==> A(addr1) ==> CL8'EJECT'
A(addr2) ==> CL8'123456'
It is possible to use the SYSIN control statement in addition to either of the two-parameter methods. For example;
//STEP1 EXEC PGM=CTSSYNC,PARM='BULK' //SYSIN DD * EJECT,123456 EJECT,100001 EJECT,001234
In this example, the BULK command applies to all subsequent commands. Therefore, the EJECT of tapes 123456, 100001, and 001234 are directed to the bulk location. If a volume command is issued without a VOLSER, all subsequent VOLSERs are then processed.
//STEP1 EXEC PGM=CTSSYNC //SYSIN DD * SYNC 100002 102030 100202
In this example, the three listed volumes (100002, 102030, and 100202) have their status synchronized between the tape management and 3495/3494 LCS database. This could just as easily be a list of tapes to be ejected to the BULK location, as a post process to the vaulting system for example.
//STEP1 EXEC PGM=CTSSYNC //EXPORT DD DSN=EXPORT.TAPE.LIST, // UNIT=VTAPE,TRTCH=NOCOMP,DISP=(,CATLG) //SYSIN DD * EXPORT,LV1234,OFFSITE1 /* comments */ EXPORT,LV2345,OFFSITE1
In this example, the logical volumes LV1234 and LV2345 are to be removed. An export list volume is created and the 3495/3494 LCS schedules the list to be exported. When the export function completes, logical volumes LV1234 and LV2345 are stacked on to a physical volume. The physical volume is put in export hold status, waiting to be removed from the 3495/3494.
//STEP1 EXEC PGM=CTSSYNC //IMPORT DD DSN=IMPORT.TAPE.LIST, // UNIT=VTAPE,TRTCH=NOCOMP,DISP=(,CATLG) //SYSIN DD * IMPORT,PV0001,LV1234 IMPORT,PV0001,LV2345-LV2348 /* range of logical volumes */
In this example, logical volumes LV1234 and LV2345 through LV2348 are imported from physical volume PV0001. An import list volume is created and the 3495/3494 LCS schedules the list to be imported.
//STEP1 EXEC PGM=CTSSYNC //IMPORT DD DSN=IMPORT.TAPE.LIST, // UNIT=VTAPE,TRTCH=NOCOMP,DISP=(,CATLG) //SYSIN DD * IMPORT,PV0001
In this example, all logical volumes on physical volume PV0001 are to be imported. An import list volume is created and the 3495/3494 LCS schedules the list to be imported.
Note: The CTE3495 member in CTAPECPB can be used to generate a list of VOLSERs as input to CTSSYNC.
//STEP1 EXEC PGM=CTSSYNC,PARM='SCRATCH,ABDLMT=12' //IMPORT DD DSN=IMPORT.TAPE.LIST, // UNIT=VTAPE,TRTCH=NOCOMP,DISP=(,CATLG) //SYSIN DD * 012345 /* SINGLE TAPE WITH COMMENT */ ABC017-ABC052 /* SCRATCH ALL TAPES IN THIS RANGE */ SYNC XYZ100-XYZ299
In this example, the EXEC PARM is used to set 'SCRATCH' as a global command and to ABEND CTSSYNC if the highest return code is greater than or equal to 12. The VOLSER 012345 and the range of VOLSERs ABC017 through ABC052 will be scratched using the global command. The tape management system will get synchronized with VOLSERs ranging from XYZ100 to XYZ299.
The FORCE command tells CTSSYNC to synchronize the VOLSER 123456 regardless of the current use attribute in the TCDB. The following examples show how to use the FORCE control statement:
Examples
//STEP1 EXEC PGM=CTSSYNC,PARM='FORCE' //SYSIN DD * SYNC,123456
or
//STEP1 EXEC PGM=CTSSYNC,PARM='SYNC' //SYSIN DD * FORCE,123456
These examples show how to use the FORCE control statement. The FORCE command tells CTSSYNC to sync the volser 123456 regardless of the current use attribuie in the TCDB.
Completion Codes:
CTSSYNC can complete with the following condition codes.
Successful completion: The requested commands performed successfully or commands were not processed because no VOLSER was provided.
Successful completion with redundant commands: In VERIFY mode, one or more ATL commands failed or could not be performed because the VOLSER was not defined in the 3495/3494 LCS database or for the SYNC command, synchronization of one or more volumes was bypassed, or a PRIVATE, PROTECT or SCRATCH command was issued for a volume, which was already in the requested status for LCS database.
Processing errors: One or more ATL commands failed or could not be performed because the VOLSER was not defined in the 3495/3494 LCS database, and NOVERIFY was specified, or no valid input command was found, or the tape management system was not active.
Incorrect job setup: A required DD statement is missing.
Invalid request: A schedule of both IMPORT and EXPORT operations was attempted.
User Abends:
A U0006 abend is issued when CTSSYNC finishes processing all control statements and is going to terminate with a condition code greater than the value specified in the abend limit PARM (ABDLMT=). For example: ABDLMT=8 will cause CTSSYNC to abend with a U0006-rc when the highest RC is greater than or equal to 8.
When the 3495/3494 LCS is unable to schedule an EXPORT or IMPORT, CTSSYNC abends with the following user abend codes:
EXPORT command could not be scheduled.
IMPORT command could not be scheduled.
Reason code from the 3495/3494 LCS services. It indicates why the EXPORT/IMPORT command could not be scheduled. The reason codes can be found in the LCS External Services Parameter List (LCSPL), mapped by IBM macro CBRLCSPL. This is used to pass parameters to the LCS external services, to pass return and reason codes and other information back to the caller. This macro can be found in SYS1.MACLIB. U0999 with a dump can be issued if internal logical errors occur.
CTSSYNC ATL RESPONSE LOG Report Sample:
MMMDD,YYYY 9:54:12 CTSSYNC ATL RESPONSE LOG PAGE 1 FUNCTION ------ATL ACTION --------------STATUS IN TAPE DATABASED PROTECT TDI001 SYNC PROCESS COMPLETE EDM/DYNAM CONTROLLED EJECT TDI002 EJECT COMPLETE SCRATCH TDI003 SYNC PROCESS COMPLETE PROTECT TDI004 SYNC PROCESS COMPLETE PROTECT TDI005 SYNC PROCESS COMPLETE PROTECT TDI006 SYNC PROCESS COMPLETE EDM/DYNAM CONTROLLED VERIFY VERIFY MODE INITIATED NOVERIFY VERIFY MODE TERMINATED BULK BULK-EJECT DOOR ACTIVE NOBULK CONVENIENCE DOOR ACTIVE PROTECT TDI016 SYNC PROCESS COMPLETE EDM/DYNAM CONTROLLED PROTECT TDI017 SYNC PROCESS COMPLETE EDM/DYNAM CONTROLLED PROTECT TDI018 SYNC PROCESS COMPLETE EDM/DYNAM CONTROLLED PROTECT TDI019 SYNC PROCESS COMPLETE VOL NOT IN SCRATCH STATUS SCRATCH TDI020 SYNC PROCESS COMPLETE VOL IN LIBRARY & SCRATCH PROTECT TDI021 SYNC PROCESS COMPLETE EDM/DYNAM CONTROLLED PROTECT TDI022 SYNC PROCESS COMPLETE EDM/DYNAM CONTROLLED PROTECT TDI028 SYNC PROCESS COMPLETE VOL NOT IN SCRATCH STATUS PROTECT TDI029 SYNC PROCESS COMPLETE VOL NOT IN SCRATCH STATUS SCRATCH TDI030 SYNC PROCESS COMPLETE VOL IN LIBRARY & SCRATCH SCRATCH TDI031 SYNC PROCESS COMPLETE VOL IN LIBRARY & SCRATCH SCRATCH TDI032 SYNC PROCESS COMPLETE VOL IN LIBRARY & SCRATCH ERROR(S)SYNC ABC001 ATL SYNCRONIZE BYPASSED VOL NOT DEFINED TO THE DATABASE ERROR(S)SYNC ABC002 ATL SYNCRONIZE BYPASSED VOL NOT DEFINED TO THE DATABASE ERROR(S)SYNC ABC003 ATL SYNCRONIZE BYPASSED VOL NOT DEFINED TO THE DATABASE ERROR(S)SYNC ABC004 ATL SYNCRONIZE BYPASSED VOL NOT DEFINED TO THE DATABASE ERROR(S)SYNC ABC005 ATL SYNCRONIZE BYPASSED VOL NOT DEFINED TO THE DATABASE SCRATCH TDI001 SYNC PROCESS COMPLETE SCRATCH TDI001 VOLUME IS ALREADY IN THAT STATUS SCRATCH TDI001 VOLUME NOT FOUND BY ATL ERROR(S)SCRATCH TDI001 REQUEST FAILED FROM LCS IMPORT TDI003 FROM XMIT10 WRITTEN TO IMPORT LIST VSN MVXE90 IMPORT TDI004 FROM XMIT10 WRITTEN TO IMPORT LIST VSN MVXE90 IMPORT TDI005 FROM XMIT10 WRITTEN TO IMPORT LIST VSNMVXE90 ERROR(S)EXPORT TDI006 BYPASSED MIXING IMPORT AND EXPORT ERROR(S)EXPORT TDI007 BYPASSED MIXING IMPORT ANDEXPORT QUERY DC0011 QUERY COMPLETE, VOLUME IN ROBOT SYNC DC0011 VOLUME WAS ALREADY IN THAT STATUS VOLUME NOT IN SCRATCH STATUS QUERY DC0012 QUERY COMPLETE, VOLUME IN ROBOT SYNC DC0012 VOLUME WAS ALREADY IN THAT STATUS VOLUME NOT IN SCRATCH STATUS QUERY DC0013 QUERY COMPLETE, VOLUME IN ROBOT ERROR(S) QUERY DC0013 OUT OF SYNC: TVIUSEA = S & TVILCAT = UN ---- END OF REPORT ----
The function or command or parameter that was passed to CTSSYNC. A SYNC command is broken down first into a QUERY type transaction, to find out whether the cartridge is in the robot and if so what is its status. Then, either a PROTECT command, to change its status from scratch to private or a SCRATCH command, to change its status from private to scratch or a SYNC command, meaning that it was already in the correct status is used.
A description of what the ATL has been asked to do and what its response was.
A description of the status of the cartridge is in the tape management database. This is used only for a SYNC command.
ATL ACTION messages and their meanings:
The VERIFY command had been issued and processed.
The NOVERIFY command had been issued and processed.
The NOBULK command was issued and the convenience door is used for any further EJECT commands.
The BULK command was issued and the bulk door will be used for any further EJECT commands.
An IMPORT command was issued, but the JCL did not contain an IMPORT DD statement.
An EXPORT command was issued, but the JCL did not contain an EXPORT DD statement.
An EXPORT command was issued and the volume to be exported was written to the export list created on virtual-volume vvvvvv.
An IMPORT command was issued and the volume to be imported was written to the import list created on virtual-volume vvvvvv.
A SYNC command was issued and the volume to be synchronized resides inside the robot.
A SYNC command has been issued, and the volume was already in the correct status.
Either a PROTECT, SCRATCH, PRIVATE command had been issued and the volume had its status successfully changed. The PROTECT or SCRATCH command may also have been issued because of a SYNC command when the initial QUERY found the tape was not in correct status.
The EXPORT command failed. The reason codes can be found in the LCS External Services Parameter List (LCSPL), mapped by IBM macro CBRLCSPL. This macro can be found in SYS1.MACLIB.
The IMPORT command failed. The reason codes can be found in the LCS External Services Parameter List (LCSPL), mapped by IBM macro CBRLCSPL. This macro can be found in SYS1.MACLIB.
The request (SCRATCH, PRIVATE, PROTECT, SYNC) failed with a return code of rc; and reason code of rsn. The return code and reason code combinations can be found in the LCS External Services Parameter List (LCSPL), mapped by IBM macro CBRLCSPL. This macro can be found in SYS1.MACLIB.
There was a syntax error on the specified control statement.
A range of volumes had been specified, but there was a syntax error in the format.
It is not allowed to perform both an IMPORT and an EXPORT command on the same execution.
No command was found on the PARM or in the SYSIN.
ATL software rejected a command as unsupported format.
The 3494/ATL was either not active or not available to communicate with CTSSYNC.
The SYNC command was bypassed for the specified reason.
The volume specified on the command is not defined in the ATL TCDB.
SYNC operation failed. The ATL TCDB status x and LM status yy are different. Use IBM ISPF panels to resolve the discrepancy.
Note: For more information about status settings, see the IBM document DFSMS Object Access Method Planning, Installation, and Storage Administration Guide for Tape Libraries.
The tape robot and tape management system both have different settings. This will be fixed if CTSSYNC was run with a PARM=‘SYNC’.
STATUS IN TAPE DATABASE messages and their meanings:
The requested volume was either full or part of a multi-volume chain or controlled by an external data manager. In either case, you can not mod onto it.
The requested volume is active (not in scratch status), but could have additional data MODed onto it or have additional files stacked upon it.
The requested volume is in scratch status.
The volume is not defined to the tape management system.
The tape management system is not currently active.
A SYNC command was issued for a volume that was created within the last 5-minutes; this volume was bypassed.
A SYNC command was issued for a tape that is either marked as BAD or as OUT-OF-SERVICE in the tape management database.
|
Copyright © 2013 CA Technologies.
All rights reserved.
|
|