TAPELIST: Listing volumes for pulling and mounting tapes

Explanation: TAPELIST is an optional parameter that can be used with the VERIFY or EXECUTE parameters (it is ignored if used with the DISPLAY parameter). When TAPELIST is used with the VERIFY parameter, it allows you to review the output while other RECYCLE commands can continue processing. When TAPELIST is used with the EXECUTE parameter, DFSMShsm produces the same lists as those produced by the VERIFY parameter, plus, you are given the option to continue the RECYCLE processing after the lists are produced.

The lists are dynamically allocated to either a SYSOUT data set or to the data set generated or specified by the TAPELIST PREFIX parameter or the TAPELIST FULLDSNAME parameter.

Subparameter	Explanation
PULLSIZE	PULLSIZE(nnn) allows you to select the number of tape volumes that is feasible to physically transport at one time from shelf storage to your tape drives (for example, on a cart) or the number of tape volumes that can be managed by an operator after they are brought to the vicinity of the tape drives. Specify a value between 1 and 999.
TOTAL	TOTAL(nnnn) allows you to select the total number of volumes (including empty volumes) to be listed in all pull groups for a given category of DFSMShsm tapes. If the EXECUTE parameter is specified, this restricts the total number of volumes that can be recycled for that category. Specify a value between 1 and 9999.
PREFIX	PREFIX(tapelist_prefix) is mutually exclusive with the FULLDSNAME parameter. This optional parameter is used to specify the name of the TAPELIST output. You can select the data set prefix to be used for that data set name. DFSMShsm generates a fully qualified data set name by appending the following qualifiers to tapelist_prefix: .BACKUP, .DAILY, .ML2, or .SPILL, depending on the category of tape volumes specified on the command date stamp .Dyyyyddd, where yyyy represents the year and ddd the day of the year time stamp .Thhmmss, where hh, mm, and ss represent the hour, minute, and second Because the maximum length of a data set name is 44 characters, the allowable length of tapelist_prefix is 20 characters, so that the generated data set name will be valid regardless of the volume category specified. When the PREFIX parameter is specified, DFSMShsm dynamically allocates and catalogs an output data set with the following characteristics: Data set name generated from tapelist_prefix Record format of FBA Logical record length of 121 Data set is system reblockable Primary allocation of 20 tracks Secondary allocation of 50 tracks Unit of SYSALLDA
FULLDSNAME	FULLDSNAME(tapelist_dsn) is mutually exclusive with the PREFIX parameter. This optional parameter is used to specify the name of the TAPELIST output. You can select the fully qualified name to be used for the TAPELIST output. If tapelist_dsn data set does not exist, DFSMShsm dynamically allocates and catalogs an output data set with the following characteristics: Data set name of tapelist_dsn Record format of FBA Logical record length of 121 Data set is system reblockable Primary allocation of 20 tracks Secondary allocation of 50 tracks Unit of SYSALLDA However, if tapelist_dsn does exist, this output data set must be available so that DFSMShsm can use it for output. This output data set must have the following characteristics: Cataloged and reside on DASD Record format of FBA Logical record length of 121 Data set is system reblockable Primary allocation of the user’s choice If the data set does not contain data, DFSMShsm starts writing output data at the beginning of the data set. If the data set contains data, DFSMShsm writes the output data after the existing data.

When DFSMShsm completes writing to the data set, DFSMShsm deallocates the data set allowing you to browse or print it. If you have specified the EXECUTE parameter, then before DFSMShsm allocates any tape drives, it issues a WTOR message to the tape operator:

   ARC0825D RECYCLE TAPE LIST CREATED, DSN=dsname. DO YOU WISH
   TO CONTINUE? REPLY 'N' TO STOP RECYCLE OR 'Y' WHEN READY TO
   MOUNT TAPES.

Replying Y causes recycle processing to select and allocate the first input tapes for as many recycle tasks as are defined. Replying ‘N’ ends recycle processing for that category of volumes.

Defaults

If the PULLSIZE parameter is not specified, DFSMShsm uses the value of 40.
When the TOTAL parameter is not specified, DFSMShsm lists pull groups for all the eligible volumes in the category being recycled and if the EXECUTE parameter is specified, recycles all of them.
When the PREFIX parameter and the FULLDSNAME parameter are not specified, DFSMShsm writes the TAPELIST output to the SYSOUT class specified by the SETSYS parameter.

Note:

If you specify the RECYCLE ALL command and do not specify the FULLDSNAME parameter, DFSMShsm creates two data sets: one for ML2 volumes and one for backup (daily and spill) volumes. If you also specify the EXECUTE parameter, DFSMShsm writes the ARC0825D message twice, following the deallocation of each of the two data sets. Your response need not be the same to each message. If the operator's response is to not continue with ML2 volumes, DFSMShsm later writes the ARC0825D message with the second data set name, allowing you to recycle backup volumes.
Because the volumes in a connected set are not split across pull groups, some pull groups may have fewer volumes than the PULLSIZE value.
Empty tapes are not mixed with nonempty tapes within a pull group.
If a connected set contains more volumes than the PULLSIZE value, that connected set is listed in a pull group by itself.
The TOTAL parameter specifies an upper bound on the number of volumes to be in the list and therefore recycled in a given category. The LIMIT parameter specifies an upper bound on the net number of volumes that can be returned to scratch status in a given category. In each case, the upper bounds are approximate, since a connected set is recycled completely or not at all. If the TOTAL value is too small, the LIMIT value may not be reached.
If you specify the RECYCLE ALL command, the total number of volumes pulled can be as much as twice the TOTAL value, one set of migration level 2 volumes and one set of backup volumes.
If you specify the RECYCLE ALL command with the TAPELIST(FULLDSNAME) parameter, DFSMShsm uses this specified data set for the TAPELIST of migration level 2 volumes followed by the lists of backup volumes. You should realize that the backup pass may fail if you have this data set in use after the L2 TAPELIST output is written and do not release it before the backup pass starts. Therefore, you should not use ALL and FULLDSNAME together unless you can be sure that the data set will be freed by the time RECYCLE processing requires it.
If you specify the TAPELIST parameter with the DISPLAY parameter or when specifying a single volume, DFSMShsm ignores the TAPELIST parameter.
If all of your tape volumes are in automated tape libraries, the output from the TAPELIST or VERIFY parameters will benefit you as a reporting tool.
You can use the PATCH command to change the unit name, primary allocation, and secondary allocation. Refer to the z/OS DFSMShsm Implementation and Customization Guide for a list of the available PATCH commands.