SETOAM keyword definitions for global level

If the Automated Tape Allocation Manager (ATAM) is in use, you might want to reduce the time that OAM makes retry attempts or to bypass retry processing entirely and issue CBR6400D immediately, so ATAM can start allocating a tape drive without having to wait for OAM retry processing. By automatically responding to allocation requests, ATAM reduces the need for operator intervention and enables more efficient use of tape drives. See IBM Tivoli Automated Tape Allocation Manager for z/OS User's Guide, SC23-9736, for more information on ATAM.

Valid values for minutes are 0, 1, 2, 3, 4, and 5. A value of 0 means no retry will be attempted and CBR6400D will be issued immediately. The default value is 5.

In an IBM tape library environment, specify the SETOAM DATACLASS parameter using a data class to request the desired media type or recording technology. To request tape data encryption in the tape library environment and in the stand-alone environment, use DATACLASS to request an encryption recording format; you can also specify the encryption key labels and encoding mechanisms using data class. In addition, you can specify DATACLASS to take advantage of performance scaling or performance segmentation in an IBM tape library environment and also in the stand-alone environment. Use the performance options in the data class to improve the random retrieval rate of primary objects in Object storage groups. For objects written to Object Backup storage groups, you can specify a data class that does not specify performance scaling, then you can use the full capacity of the volume.

Recommendation: Do not allow ACS routines to assign or change the data class assignment of an OAM tape volume. The data class for OAM tape volumes is determined by the SETOAM statement of the CBROAMxx PARMLIB member at MVS scratch tape allocation. The SETOAM statement provides this information at the storage group level or at the OAM global level, and it best suits the requirements for the tape volume that is being allocated. Allowing ACS routines to alter this specification could create unexpected consequences (for example, no compaction of the data when the SETOAM statement specified compaction). It is your installation's responsibility to write the ACS routines so as to not alter the data class construct for OAM tape volumes.

Once DSNWITHSGNAME is specified, all new OAM object tape data set names for all tape storage groups will have the storage group appended; however, the data sets written in the original data set name format can be retrieved and if the tape is not filled, new objects will be written on these tapes until filled.

Recommendation: Do not allow ACS routines to assign or change the data class assignment of an OAM tape volume. The data class for OAM tape volumes is determined by the SETOAM statement of the CBROAMxx PARMLIB member at MVS scratch tape allocation. The SETOAM statement provides this information at the storage group level or at the OAM global level, and it best suits the requirements for the tape volume that is being allocated. Allowing ACS routines to alter this specification can create unexpected consequences (for example, no compaction of the data when the SETOAM statement specifies compaction). It is your installation responsibility to write the ACS routines so as to not alter the data class construct for OAM tape volumes.

• OSREQ RETRIEVE requests, where the primary copy of the object being retrieved is stored on tape.
• OSREQ RETRIEVE requests, where VIEW=BACKUP or VIEW=BACKUP2 and the backup copy is on tape.
• Requests to read the primary copy of an object from tape during the OSMC storage management cycle.
• Requests to read a backup copy or the primary copy of an object from tape during the execution of the OSMC optical volume recovery utility.
• Single object recovery.
• OSREQ retrieve requests where the primary copy is on optical, but volume is not readable, access to backup is activated and the backup copy is on tape.

If one or more OAM applications are retrieving objects from multiple Object storage groups, and the primary copies of the objects are being retrieved from tape volumes, the number or tasks specified with this parameter should be greater than or equal to the maximum number of Object storage groups being read from concurrently. This parameter eliminates the need to constantly mount and demount tapes belonging to different Object storage groups to satisfy OSREQ RETRIEVE requests.

The default is 1, which allows at least one task to be attached for processing read requests from tape volumes. This default allows groups previously writing objects to tape, but no longer having an explicit SETOAM statement in the CBROAMxx member, to be able to retrieve their previously written objects if a CBROAMxx PARMLIB member was successfully processed during OAM initialization. A CBROAMxx PARMLIB member must be successfully processed during OAM initialization for OAM object tape storage to be active on the system.

• OSREQ STORE requests where the primary copy of the object is to be stored on tape.
• OSMC class transition processing where the primary copy of the object is to be stored on tape.
• Writing of backup copies of objects during the OSMC storage management cycle.
• Single object recovery.
• Producing backup copies if backups are directed to tape.
• MOVEVOL for backup copies if objects are directed to tape.

This parameter and the MAXTAPERETRIEVETASKS parameter control the maximum number of tape drives that can be concurrently allocated to the OAM address space. For tasks, specify a decimal number between 1 and 100. The number specified for tasks with the MAXTAPESTORETASKS parameter should be greater than the number of Object storage groups that OAM applications are using for storing objects to tape volumes. If the number is less than the number of Object storage groups for the OAM applications, OAM will be frequently mounting and demounting tape volumes belonging to different Object storage groups to satisfy OSREQ STORE requests. Also, if objects are being written to the Object Backup storage group during the storage management cycle for multiple storage groups, and the backup copies are being written to tape volumes, then the number of tasks specified with this parameter should encompass this activity. Specify the maximum number of concurrent storage groups by using MAXS= in the PARM field on the JCL EXEC statement in the OAM cataloged procedure. If the MAXTAPESTORETASKS parameter is not specified on any SETOAM statement, OAM sets the default to 1.

Guideline: You should verify that there are enough tape drives (specified in the TAPEUNITNAME keyword) available to handle the values assigned to the MAXTAPESTORETASKS and MAXTAPERETRIEVETASKS parameters of the SETOAM statement. How the drives are spread among the Object storage groups or the Object Backup storage group depends on the values assigned to the MAXTAPESTORETASKS, MAXTAPERETRIEVETASKS, TAPEDRIVESTARTUP, and the TAPEUNITNAME parameters for each Object and the Object Backup storage group. OAM drive allocations can exceed the value of MAXTAPERETRIEVETASKS (up to the total value of MAXTAPERETRIEVETASKS and MAXTAPESTORETASKS) due to DEMOUNTWAITTIME, even if no STOREs are being done. If there are not enough tape drives, and the recovery logic for allocation is not able to obtain a tape drive for this request, then the request fails. (See the discussion on page TAPEDRIVESTARTUP(threshold in megabytes) for details on TAPEDRIVESTARTUP.)

Recommendation: Issue the F OAM,DISPLAY,LOSTVOL command to determine the volume serial number of each lost volume, both tape and optical. See Displaying volumes that have LOSTFLAG set for further information on this command.

OAMSCRATCHSYNCH can be used to make such volumes eligible for reuse by enabling OAM to synchronize their OUNITNAM and DATACLAS fields with the UNITNAME and DATACLASS values associated with the storage group for the volume before it was returned to scratch.

Specify this parameter at the global level only.

Specify mode as either DISABLED or ENABLED:

DISABLED

OAM does not check for blank DATACLAS and OUNITNAM fields in the TAPEVOL table and does not alter those fields. OAM also does not modify the UNITNAME field in the TAPEVOL table that is associated with this tape volume. If you omit the OAMSCRATCHSYNCH parameter, DISABLED is the default.

ENABLED

OAM synchronizes blank DATACLAS and OUNITNAM fields in the TAPEVOL table that is associated with a tape volume that is being returned to OAM scratch status, as follows:

• If the DATACLAS field is blank, OAM sets DATACLAS to the same value as the DATACLASS that was associated with the storage group for the volume before it was returned to scratch. If the OUNITNAM field is blank and the value in UNITNAME is a generic device, OUNITNAM and UNITNAME are both set to the same value as the UNITNAME that is associated with the storage group for the volume. (Generic devices include the 3480, 3480x, 3490, or 3590-1.)
• If OUNITNAM is blank and the value in UNITNAME is an esoteric device name, both OUNITNAM and UNITNAME remain unchanged.

This parameter can take a number of subparameters. See SETOAM keyword definitions for STORAGEGROUP subparameters for descriptions of the STORAGEGROUP subparameters.

If you specify the TAPECAPACITY parameter as part of the SETOAM statement, but do not specify CST18, CST36, or ECCST, or do not enter valid generic or esoteric unit names, OAM does not start and issues message CBR0325I.

If you specify a 3480, 3480x, or 3490 unit name on this parameter, OAM accepts it, but considers it to be an esoteric unit name. Generally, the needs of these unit types are covered by the CST18, CST36, or ECCST keywords so they do not normally need to be specified. However, if they are specified, OAM accepts them and ensures that they are valid unit names. If the esoteric unit name used with this parameter matches the tapeunitname subparameter on the SETOAM STORAGEGROUP parameter, OAM uses the tape capacity associated with the tapeunitname subparameter instead of any equivalent CST18, CST36, or ECCST specification for this parameter.

Use this parameter at the OAM global level. However, you can specify a desired tape capacity at the storage group level by specifying an esoteric unit name on the tapeunitname subparameter on the SETOAM STORAGEGROUP parameter with the tapecapacity parameter.

Example: If esoteric TAPE1 is specified on the tapecapacity parameter (such as, TAPECAPACITY(TAPE1 5000000)), when the SETOAM STORAGEGROUP(storagegroupname TAPEUNITNAME(TAPE1) is used on the same SETOAM statement, the storage group uses the tape capacity of 5 000 000.

If the tape capacity value in the Tape Volume Table is different than that specified on the tapecapacity parameter of the SETOAM statement, the value of the SETOAM statement is used for the duration of the OAM session, or until changed or deleted on the SETOAM statement. The Tape Volume Table capacity is not changed after it is initially set during the first time the volume was written to. This is to avoid a changing capacity and a volume fluctuating between full or not full based on a differing capacity. If the capacity in the Tape Volume Table must be changed, you can use SPUFI to dynamically perform this update and OAM will accept it. The free space and percent full calculations for the volume are based on the updated capacity and are recalculated when the volume is written to again as a partial volume, or when OAM is restarted.

Restriction: With the support of the 3590 Model E and later devices, even if the device is in 3490E emulation mode, the capacity of the media is derived from the hardware; therefore, you do not need to specify the SETOAM TAPECAPACITY keyword. Also, specifying this keyword is not valid with a 3590 Model B or a device that emulates a 3590 Model B (3590-1).

If another read request for the currently mounted tape volume arrives within the delay interval, that unit of work will be dispatched immediately upon arrival. If no read request for the currently mounted volume arrives within the delay interval, another request for a different tape volume is dispatched.

• YYYY is a four-digit number that specifies a year from 1900 through 2155, and
• DDD is a three-digit number that specifies a day from 001 through 366.

The TAPEEXPIRATION date overrides the expiration date defined in the DATACLASS parameter for the data sets residing on the tape volume.

If you specify the TAPEEXPIRATION date for the data sets residing on the OAM object tape volume as the current date or a date preceding the current system date, the data sets are considered previously expired and are therefore eligible for immediate replacement. OAM issues the CBR0317I message to allow you to change the TAPEEXPIRATION value in the SETOAM statement in the CBROAMxx PARMLIB member being used if necessary.

RMM ADDVRS DSNAME('OAM.PRIMARY.DATA') COUNT(99999) LOCATION(HOME)
RMM ADDVRS DSNAME('OAM.BACKUP.DATA') COUNT(99999) LOCATION(HOME)
RMM ADDVRS DSNAME('OAM.BACKUP2.DATA') COUNT(99999) LOCATION(HOME)
RMM ADDVRS DSNAME('OPEN') JOBNAME(oamtaskname) COUNT(99999) LOCATION(HOME
RMM ADDVRS DSNAME('ABEND') JOBNAME(oamtaskname) COUNT(99999) LOCATION(HOME)

The above DSNAME examples are data set names without DSNWITHSGNAME specified in the SETOAM statement. If DSNWITHSGNAME were specified, the storage group name would be appended as the data set name's low level qualifier. The JOBNAME value is the name of the job and started task for the OAM address space that opens the tape data sets.

It is important to select a threshold value the allows tape volumes to be marked full in a consistent manner. Consider the size of the objects stored, and if the size of the objects is consistent, select a threshold value that is slightly larger than that size. If volumes are not being selected for new objects and they are not being marked full, increase the value of this parameter.

Restriction: If your tape management system does not allow overwriting tape volumes or data sets by another of the same name, you cannot use the GROUP or OAMSCRATCH option.

GROUP

Leaves the tape volume in the currently assigned Object or Object Backup storage group. OAM writes the CBR2166I message to the console log for each expired tape volume. If you omit the TAPERECYCLEMODE parameter, GROUP is the default.

The following record fields are reset for expired tape volumes in the DB2 TAPEVOL table:

• Expiration date is reset to 01-01-0001.
• Full status is set to N.
• Last block ID is reset to 0.
• Freespace is set to the volume's capacity.
• Percent full is reset to 0.
• Number of logical kilobytes written is reset to 0.
• Number of physical kilobytes written is reset to 0.
• Number of logical kilobytes deleted is reset to 0.
• Number of logical blocks written is reset to 0.
• Readable status is reset to Y.
• Writable status is reset to Y.
• Backup type is reset to the current backup type (1 or 2) if this is an object backup storage group.
• Dataset name format is set to blank.
• Tape sublevel is set to blank.
• Capacity overflow is reset to 0.
• Freespace overflow is reset to 0.
• Number of logical kilobytes written overflow is reset to 0.
• Number of physical kilobytes written overflow is reset to 0.
• Number of logical kilobytes deleted overflow is reset to 0.

MVSSCRATCH

Removes all knowledge of the tape volume from the OAM inventory and returns the tape volume to the MVS scratch pool. OAM writes the CBR2165I message to the console log for each expired tape volume that is purged from the OAM inventory. In an OAMplex, the OAM member that initially releases the tape volume issues CBR2165I. Then the other OAM members each issue a CBR7404I message indicating that the tape volume is no longer known to that member.

Guideline: Because OAM does not interface with the tape management system, you need to use message automation or manually return the tapes to MVS scratch status. For information on how DFSMSrmm releases tape volumes from OAM, see Deleting recycled tape and optical volumes from OAM.

OAMSCRATCH

Leaves the tape volume under OAM control as an available scratch tape volume to be reassigned to an Object or Object Backup storage group to be reused and rewritten from load point with new data. A message, CBR2164I, is written to the hardcopy console log for each tape volume that completes expiration processing and is reassigned to OAM scratch status. You can reassign this tape volume to any Object or Object Backup storage group that requires a scratch volume with the same attributes.

The following record fields are reset for expired tape volumes in the DB2 TAPEVOL table:

• Storage group name is set to *SCRTCH*.
• Volume type is set to S.
• Expiration date is reset to 01-01-0001.
• Full status is set to N.
• Last block ID is reset to 0.
• Freespace is set to the volume's capacity.
• Percent full is reset to 0.
• Number of logical kilobytes written is reset to 0.
• Number of physical kilobytes written is reset to 0.
• Number of logical kilobytes deleted is reset to 0.
• Number of logical blocks written is reset to 0.
• Tape compaction status is reset to blank.
• Device EPI value is reset to 0.
• Readable status is reset to Y.
• Writable status is reset to Y.
• Backup type is set to blank.
• Dataset name format is set to blank.
• Tape sublevel is set to blank.
• Volume Attributes Flag is reset to 0 for rewritable and to 1 for WORM
• Capacity overflow is reset to 0.
• Freespace overflow is reset to 0.
• Number of logical kilobytes written overflow is reset to 0.
• Number of physical kilobytes written overflow is reset to 0.
• Number of logical kilobytes deleted overflow is reset to 0.
• The unit name is reset as follows:
  • If the original unit name is non-blank, the unit name is reset to the value in the original unit name.
  • If the original unit name is blank, the unit name is reset according to the installation's specifications for SETOAM OAMSCRATCHSYNCH.
• The original unit name is reset as follows:
  • If the original unit name is non-blank, it is unchanged.
  • If the original unit name is blank, the unit name is reset according to the installation's specifications for SETOAM OAMSCRATCHSYNCH.
• The data class is reset as follows:
  • If the data class is non-blank, it is unchanged.
  • If the data class is blank, it is set according to the installation's specifications for SETOAM OAMSCRATCHSYNCH.

If, when the first object is written to a volume, TAPESDB is set to SMALL (or not set), the maximum block size for the volume is set to 32760.

See System-Determined Block Size inz/OS DFSMS Using Data Sets for details on how the optimal system-determined block size is calculated.

For all subsequent objects written to an OAM tape volume, the maximum block size is the one set for the volume when the first object was written, regardless of the current SETOAM TAPESDB setting and regardless of the size of the first object written.

OAM can read objects from volumes with maximum block sizes greater than 32760, even if TAPESDB is not set or is set to SMALL at the time the object is read.

If TAPESDB is set to LARGE at the time the first object is written to a volume, the volume cannot be read on a system running z/OS Version 1. If volumes are being shared with a z/OS Version 1 system, TAPESDB should be set to SMALL or not set.