SETOPT keyword definitions

The following keywords are defined as they pertain to the OAM SETOPT statement.

MOUNTWAITTIME

Specifies the amount of time (in minutes) that can pass while a volume is waiting to be mounted on an operator-accessible drive within an optical library. After this time has expired, message CBR4426D is issued to allow the operator to retry or to cancel the volume mount request.

This value can be any numeric value from 1 to 9999. If the operator retries the mount request, the value specified in the MOUNTWAITTIME parameter is used for the retry. The default value of this parameter is five minutes.

Because this parameter can be changed dynamically, the new value assigned to the MOUNTWAITTIME is used for any currently executing volume mount request. The time of the initial mount request is compared to the value specified in the MOUNTWAITTIME parameter and is deducted from the specified parameter value. For example, if a volume mount request has been waiting for one minute and the MOUNTWAITTIME is changed to indicate a wait time of two minutes from a previous value of three, the volume mount request has only have one more minute to finish before CBR4426D is issued. If a retry is requested after CBR4426D is issued, and the MOUNTWAITTIME is dynamically changed after the reply to retry the request, the minutes specified in the MOUNTWAITTIME parameter are compared to the time of the most recent reply to this message to determine the exact wait time.

OPTICALDISPATCHERDELAY

Specifies the number of seconds that the OAM optical dispatcher is to delay processing of certain requests to minimize flipping of optical disk cartridges in an automated optical storage library. The OAM optical dispatcher delays processing of a unit of work for a specific period of time, when ALL of the following conditions are true:

A read request for an object on a currently mounted optical disk volume has just been completed.
No request for the currently mounted optical disk volume is waiting to be processed on the OAM optical dispatcher queue.
The OAM optical dispatcher has found a read request for another optical disk volume (either the opposite side of the currently mounted volume or for an unmounted optical disk volume) and is about to dispatch this unit of work.
A nonzero optical dispatcher delay value has been specified with the OPTICALDISPATCHERDELAY keyword on the SETOPT statement in the CBROAMxx PARMLIB member.

In this situation, the OAM optical dispatcher delays the dispatching of this selected unit of work (for the number of seconds specified by the installation) expecting that another read request for the currently mounted optical disk volume will arrive within this delay interval. The OAM optical dispatcher delays dispatching of the selected unit of work for up to the number of seconds specified with the OPTICALDISPATCHERDELAY keyword on the SETOPT statement in the CBROAMxx PARMLIB member.

If another read request for the currently mounted optical disk volume arrives within the delay interval, that unit of work is dispatched immediately upon arrival. If no read request for the currently mounted optical disk volume arrives within the delay interval another request for a different optical disk volume (either the opposite side of the currently mounted optical disk volume or an unmounted optical disk volume) is dispatched.

You can use the OPTICALDISPATCHERDELAY value to circumvent a performance problem when IBM optical disk libraries (IBM 3995 optical libraries) are used with certain microfiche replacement applications. The problem involves the constant servicing of requests for data on both sides of an optical disk cartridge resulting in the cartridge being constantly flipped over to access data on the opposite side of the optical disk cartridge. This constant flipping of the cartridge results in longer response times for requests to read data from each side of the optical disk cartridge.

Valid value seconds specifies the number of seconds that the OAM optical dispatcher is to delay dispatching of specific units of work under the circumstances described above. Valid values for seconds is a decimal number between 1 and 60. If you need to use this parameter, use a low value between 1 and 5.

OPTICALREINITMODE

Specifies reinitialization mode for rewritable optical cartridges. The following values are valid:

GROUP: Expired rewritable optical cartridges remain assigned to the original Object or Object Backup storage group when reinitialized. This option is the default.
OAMSCRATCH: Expired rewritable optical cartridges revert to *SCRTCH* storage group when reinitialized. These cartridges are available to be reassigned to any Object or Object Backup storage group.

Use the OPTICALREINITMODE keyword to determine whether an optical cartridge at reinitialization should maintain its storage group affiliation or revert to a scratch storage group. A cartridge's reinitialization mode is set according to any OPTICALREINITMODE option in effect when OSMC Shelf Space Manager selects the cartridge for reinitialization, not according to the options in effect when the optical cartridge is physically reinitialized.

When the MOVEVOL command with the RECYCLE option completes and all of the objects have been successfully moved off of the optical volumes, the volumes are either assigned to their current Object or Object Backup storage group or returned to OAM scratch, depending on the SETOPT OPTICALREINITMODE statement that is specified in the CBROAMxx member of PARMLIB. When an optical volume is returned to OAM scratch, it is available to be reassigned to any Object or Object Backup storage group. Rewritable optical media is marked for reinitialization and the cartridge is physically reformatted the next time that the cartridge is mounted on a drive to reclaim the used space on the cartridge. WORM optical media is not physically reformatted because the used space cannot be reclaimed on WORM media.

To understand how the OPTICALREINITMODE keyword affects the optical volumes at reinitialization, it is important to understand the reinitialization process itself. The following information gives you a overview of the process.

An optical media cartridge contains two logical optical disk volumes, each optical volume is assigned a unique volume serial number (volser). The optical media types are either WORM or rewritable.

Shelf Space Manager (a component of OSMC) processes expired optical disk cartridges as follows:

For WORM cartridges:
- If all objects on both volsers have been deleted and both volsers are full and no objects have been written to this cartridge in the past 24 hours, then the cartridge is ejected if it is library-resident. Message CBR2153I is issued to inform the installation that all of the objects on the WORM cartridge were expired and the cartridge was removed from the OAM Configuration Database (OCDB). The WORM cartridge no longer contains valid data; you can dispose of it according to federal, state, and local laws.
For rewritable cartridges:
- If all objects on both volsers are deleted and no objects were written to this cartridge in the last 24 hours, then the volume empty (VOLEMPTY) indicators in the OAM volume table in the OCDB for both volsers contained in the cartridge are set to indicate that the cartridge is ready to be reinitialized. Message CBR2154I is issued to inform the installation that this rewritable cartridge will be reinitialized the next time it is mounted on an optical drive.
For all cartridges:
- The expiration date needs to be the current day or earlier.

Tip: You can use the MODIFY OAM,UPDATE,VOLUME command to update the volume expiration date. See Updating fields in the DB2 Volume Table and the Tape Volume Table for more information on this command.

When a rewritable optical cartridge that is selected by Shelf Space Manager for reinitialization is mounted, both sides of the cartridge are reformatted. The volumes on the reformatted cartridge retain their original volume serial numbers. With the SETOPT statements, you can specify whether the reinitialized cartridge should maintain its storage group affiliation (default) or revert to the scratch storage group.

SCRENTRYTHRESHOLD

Specifies the amount of free space, in KB, that will determine a WORM optical volume's eligibility to be assigned as a scratch volume. If a new WORM optical volume has less free space than specified, a message is issued to validate the entry or labeling of the volume as a scratch cartridge. The default value is 0.

UNLOADDRIVES

Specifies that the number of optical drives specified by n are desired to be empty, unloading drives if necessary, when the value of UNLOADTIMER has been reached. n is a numeric value from 1 to 6. This keyword can be specified at the global level only.

UNLOADTIMER

Specifies the period of inactivity, in seconds, to wait before unloading the optical drives specified in UNLOADDRIVES. ssss is a numeric value from 1 to 9999. This keyword can be specified at the global level only.

ABUNREAD

Specifies that when a retrieve for an object is attempted and the optical or tape volume on which the object resides is marked not readable, the specified backup copy of the object is retrieved.

Valid values for ABUNREAD are:

BACKUP1: Specifies that when a primary copy of an object that is read by an application is not available for the specified reason, and BACKUP1 is specified for ABUNREAD, an attempt is made to retrieve the object from the first backup copy of the object.
BACKUP2: When a primary copy of an object that is read by an application is not available for the specified reason, and BACKUP2 is specified for ABUNREAD, an attempt is made to retrieve the object from the second backup copy of the object.
INACTIVE: When a primary copy of an object that is read by an application is not available for the specified reason, and INACTIVE is specified, then automatic access to backup is disabled for ABUNREAD. No attempt is made to retrieve the object from either backup copy of the object and the retrieve will fail.

ABOFFLINE

Specifies that when a retrieve for an object is attempted and the optical or tape volume on which the object resides is in a library that is offline or pending offline, the specified backup copy of the object is retrieved.

Valid values for ABOFFLINE are:

BACKUP1: Specifies that when a primary copy of an object that is read by an application is not available for the specified reason, and BACKUP1 is specified for ABOFFLINE, an attempt is made to retrieve the object from the first backup copy of the object.
BACKUP2: When a primary copy of an object that is read by an application is not available for the specified reason, and BACKUP2 is specified for ABOFFLINE, an attempt is made to retrieve the object from the second backup copy of the object.
INACTIVE: When a primary copy of an object that is read by an application is not available for the specified reason, and INACTIVE is specified, then automatic access to backup is disabled for ABOFFLINE. No attempt is made to retrieve the object from either backup copy of the object and the retrieve will fail.

ABNOTOPER

Specifies that when a retrieve for an object is attempted and the optical or tape volume on which the object resides is in a library that is marked non-operational, the specified backup copy of the object is retrieved.

Valid values for ABNOTOPER are:

BACKUP1: Specifies that when a primary copy of an object that is read by an application is not available for the specified reason, and BACKUP1 is specified for ABNOTOPER, an attempt is made to retrieve the object from the first backup copy of the object.
BACKUP2: When a primary copy of an object that is read by an application is not available for the specified reason, and BACKUP2 is specified for ABNOTOPER, an attempt is made to retrieve the object from the second backup copy of the object.
INACTIVE: When a primary copy of an object that is read by an application is not available for the specified reason, and INACTIVE is specified, then automatic access to backup is disabled for ABNOTOPER. No attempt is made to retrieve the object from either backup copy of the object and the retrieve will fail.

ABDB2ERROR

Specifies that if a DB2 error occurs while OAM is retrieving object data from the 4 KB, 32 KB, or LOB storage table and the first or second backup copy exists, OAM retrieves the object data from the specified backup copy. This function allows access to backup copies of objects that reside on removable media (optical or tape) when the DB2 resident data is unavailable, such as during the recovery of DB2 tables.

Restriction: The object directory entry is necessary for OAM to proceed with any object request. If a DB2 error occurs while OAM attempts to retrieve the object directory entry, OAM does not retrieve the backup copy of the object. Without the object directory information, OAM cannot determine the primary or backup location of the object.

Valid values for ABDB2ERROR are:

BACKUP1: Specifies that when a primary copy of an object that is read by an application is not available for the specified reason, and BACKUP1 is specified for ABDB2ERROR, an attempt is made to retrieve the object from the first backup copy of the object.
BACKUP2: When a primary copy of an object that is read by an application is not available for the specified reason, and BACKUP2 is specified for ABDB2ERROR, an attempt is made to retrieve the object from the second backup copy of the object.
INACTIVE: When a primary copy of an object that is read by an application is not available for the specified reason, and INACTIVE is specified, then automatic access to backup is disabled for ABDB2ERROR. No attempt is made to retrieve the object from either backup copy of the object and the retrieve will fail.

ABLOST

Specifies that when a retrieve for an object is attempted and the optical or tape volume on which the object resides is marked lost or not-defined, the specified backup copy of the object is retrieved.

Valid values for ABLOST are:

BACKUP1: Specifies that when a primary copy of an object that is read by an application is not available for the specified reason, and BACKUP1 is specified for ABLOST, an attempt is made to retrieve the object from the first backup copy of the object.
BACKUP2: When a primary copy of an object that is read by an application is not available for the specified reason, and BACKUP2 is specified for ABLOST, an attempt is made to retrieve the object from the second backup copy of the object.
INACTIVE: When a primary copy of an object that is read by an application is not available for the specified reason, and INACTIVE is specified, then automatic access to backup is disabled for ABLOST. No attempt is made to retrieve the object from either backup copy of the object and the retrieve will fail.

ABFSERROR

Specifies that if an error occurs while OAM is retrieving an object from the file system and the first or second backup copy exists, OAM retrieves the object data from the specified backup copy. This function allows access to backup copies of objects that reside on removable media (optical or tape) when the file system data is unavailable, such as the file system being unmounted or otherwise unavailable such as for maintenance procedures including backup of the file system data.

Valid values for ABFSERROR are:

BACKUP1: Specifies that when a primary copy of an object that is read by an application is not available for the specified reason, and BACKUP1 is specified for ABFSERROR, an attempt is made to retrieve the object from the first backup copy of the object.
BACKUP2: When a primary copy of an object that is read by an application is not available for the specified reason, and BACKUP2 is specified for ABFSERROR, an attempt is made to retrieve the object from the second backup copy of the object.
INACTIVE: When a primary copy of an object that is read by an application is not available for the specified reason, and INACTIVE is specified, then automatic access to backup is disabled for ABFSERROR. No attempt is made to retrieve the object from either backup copy of the object and the retrieve will fail.

ABALL

Specifies that when a retrieve for an object is attempted and the optical or tape volume on which the object resides is not available for any of the above reasons, the specified backup copy of the object is retrieved.

Valid values for ABALL are:

BACKUP1: Specifies that when a primary copy of an object that is read by an application is not available for the specified reason, and BACKUP1 is specified for one of the above keywords for automatic access to backup, an attempt is made to retrieve the object from the first backup copy of the object.
BACKUP2: When a primary copy of an object that is read by an application is not available for the specified reason, and BACKUP2 is specified for one of the above keywords for automatic access to backup, an attempt is made to retrieve the object from the second backup copy of the object.
INACTIVE: When a primary copy of an object that is read by an application is not available for the specified reason, and INACTIVE is specified, then automatic access to backup is disabled for all of the above reasons. No attempt is made to retrieve the object from either backup copy of the object and the retrieve will fail.

Note: There are no default values for the automatic access to backup (AAB) CBROAMxx PARMLIB SETOPT keywords at the time of OAM initialization. If no AAB keywords are specified in the CBROAMxx PARMLIB SETOPT statement, then the preexisting values for each of the AAB reasons will be retained. If one or more AAB keywords are specified in the CBROAMxx PARMLIB SETOPT statement, then the associated AAB reasons will be set as specified, and all unspecified AAB reasons will be set to inactive. A system IPL will disable all AAB reasons.

MULTISYSENABLE

Specifies whether or not object and object backup storage groups can be enabled to more than one system in a non-OAMplex environment.

Valid values for MULTISYSENABLE are:

NO: Specifies that when a storage group has been encountered in a NON-OAMplex environment that is enabled to more than one system, the storage group will not be defined to the OAM address space. OSREQ requests for DB2 sublevel resident objects will be processed. No other OAM or OSREQ function will be honored for objects in the storage group. The default MULTISYSENABLE specification is NO.
YES: Specifies that when a storage group has been encountered in a non-OAMplex environment that is enabled to more than one system, the storage group will be defined to OAM.

Note: This is a global specification only and cannot be specified at the storage group level. Additionally, the SETOPT MULTISYSENABLE specification cannot be modified using the MODIFY OAM,UPDATE command, the MODIFY OAM,RESTART operator command, or an OAM restart resulting from an SCDS activation.

Attention: The SETOPT statement of CBROAMxx PARMLIB member provides the MULTISYSENABLE keyword at a global level to bypass OAM's default behavior and to instead allow object or object backup storage groups to be enabled to more than one system in a non-OAMplex SYSplex environment. This configuration consists of a shared SCDS, but non-shared DB2 and primarily allows for the same object or object backup storage group name to be used on multiple systems. If MULTISYSENABLE(YES) is specified in CBROAMxx PARMLIB, then message CBR0165I will be issued to warn the installation when a storage group has been encountered that is enabled to more than one system in a non-OAMplex environment and that the storage group(s) will be defined to OAM. This message will be issued only once per OAM initialization.

In a non-OAMplex environment, the SMS Storage Group Status panel is used to allow status to be specified for each system defined to SMS. Currently, you must specify an option other than NOTCON for the one system that will be running OAM and you must specify the NOTCON option for all other systems. If you specify more than one system as other than NOTCON for an object or object backup storagegroup, a CBR0162I message is issued during OAM initialization and the storage group is ignored by OAM.

In an OAMplex environment it is normal to have an object or object backup storage group defined as enabled to multiple systems. In fact, they are normally enabled to all the systems in the OAMplex. This is because the OAM members in the OAMplex share the same OAM tables in DB2 and it is desirable for all members of the OAMplex to have equal access to the same data.

In a non-OAMplex environment, instances of OAM on individual LPARs are independent of each other. They do NOT share common DB2 tables and therefore the object data accessible to OAM on one LPAR is not accessible to OAM on another LPAR. The default behavior is to not allow a given object or object backup storage group to be defined as enabled to more than one system when OAM is initialized in stand-alone (non-OAMplex) mode.

Some installations desire to have the same storage group name enabled on multiple systems even though not running in an OAMplex. These installations may have a given storage group name (GROUP22 for example) which contains ABC-payroll object data in the DB2 tables accessible to OAM running on LPAR #1, and contains XYZ-insurance policy object data in the DB2 tables accessible to the OAM running on LPAR #2.

The SETOPT MULTISYSENABLE keyword available in the CBROAMxx PARMLIB member provides the customer the option to define a given object or object backup storage group as enabled to more than one system in a non-OAMplex environment. In a non-OAMplex when MULTISYSENABLE(YES) is specified, then OAM will issue a CBR0165I informational message during OAM initialization if one or more object or object backup storage groups are defined as enabled to multiple systems in the active SMS configuration.

The MULTISYSENABLE option benefits installations with stand-alone (non-OAMplex) instances of OAM on multiple systems in an SMSplex, but desire to use a common object or object backup storage group name across systems.

Note: Even though the storage group name is defined as enabled for multiple systems, the DB2 tables are unique to each system and therefore the object data is different for each system.

STORAGEGROUP(name)

Specifies the name of an Object or Object Backup storage group that was previously defined using ISMF. The following subparameter can also be specified for this storage group:

OPTICALREINITMODE

Reinitialization mode for rewritable optical cartridges belonging to this Object or Object Backup storage group. If this keyword is not specified for a given storage group, the reinitialization mode for rewritable optical cartridges belonging to that storage group is set using the OPTICALREINITMODE set at the global level.

A cartridge’s reinitialization mode is set according to any OPTICALREINITMODE option in effect when OSMC Shelf Space Manager selects the cartridge for reinitialization—not according to the options in effect when the optical cartridge is physically reinitialized.

Valid values for the OPTICALREINITMODE option are:

GROUP: Expired rewritable optical cartridges remain assigned to the original Object or Object Backup storage group when reinitialized. This option is the default.
OAMSCRATCH: Expired rewritable optical cartridges belonging to this Object or Object Backup storage group revert to *SCRTCH* storage group when reinitialized. These cartridges are available to be reassigned to any Object or Object Backup storage group.