Macros used with shared DASD (RESERVE, EXTRACT, GETDSAB)

When using shared DASD, IBM® recommends that your application issue ISGENQ SCOPE=SYSTEMS RESERVEVOLUME=YES or ENQ SCOPE=SYSTEMS and define the resource name on which you are serializing, rather than use the RESERVE macro. However, to ensure successful serialization of shared DASD, you can use RESERVE if one of the following is true:

Global resource serialization is not active
- ISGENQ services are not available until the Global Resource Serialization address space is initialized. This is very unlikely and only true if your code runs very early in the IPL processing (prior to the Global Resource Serialization address space being initialized). The Global Resource Serialization address space is created and available in all Global Resource Serialization modes and therefore all z/OS® environments.
Your installation is not using SMS to manage the DASD.
- The RESERVE application programming interfaces, either through the RESERVE or ISGENQ macros, can result in a DASD RESERVE or an ENQ being obtained, or both. In all cases, an ENQ is obtained that is defined by the caller through the QNAME/RNAME. The scope of the ENQ and whether the hardware RESERVE is issued by the system is controlled by several factors:
  - A hardware RESERVE is not issued when one of the following is true:
    1. The volume is not defined as being SHARED through the IODF.
    2. The volume is mapped by Virtual I/O (VIO).
    3. The current Global Resource Serialization RNL indicates that the RESERVE should be converted to a SYSTEMS level ENQ (The resource does not match an entry in the SYSTEMS EXCLUSION RNL and does match an entry in the RESERVE Conversion RNL)
    4. The RESERVE is converted by the ISGNQXITBATCH exit, or ISGNQXITBATCHCND exit, or both.
  - The scope of the ENQ originates as SYSTEMS:
    1. If the above volume attributes indicate that the system should issue the hardware RESERVE, the associated ENQ can be changed to SYSTEM (local ENQ) when the QNAME/RNAME match an entry in the exclusion RNL. In general, this would be the case when the installation wants the RESERVE to occur and therefore does not require the associated SYSTEMS ENQ. The SYSTEM ENQ in this case would serialize the device across multiple users on the same system. The RESERVE serialized the device across systems.
    2. The ENQ can stay as a SYSTEMS ENQ in cases where the RESERVE is not issued due to the conversion RNL. In this case, the ENQ serializes the resource across z/OS systems.
  All of these factors are generally not a concern of the caller of the RESERVE service. The caller is using RESERVE because it supports serialization of the volume across systems through hardware reserve. The installation controls the factors defined above based on its requirements.

You can also use the ENQ, DEQ, EXTRACT, and GETDSAB macros when working with shared DASD.

To obtain the address of a task input/output table (TIOT) entry, from which you can obtain the unit control block (UCB) address of a device, you can use the GETDSAB macro or the EXTRACT macro. Your installation may have installed products that require the use of the GETDSAB macro to obtain the address of the product's TIOT entries. If you plan to use the EXTRACT macro, first check the documentation for the related product to ensure that the product does not require the use of the GETDSAB macro.

The RESERVE macro reserves a device for use by a particular system. You identify the device you want reserved by its symbolic resource name and UCB address. For a 31-bit address, you must specify the LOC=ANY parameter. Each task that needs exclusive use of a device must issue the RESERVE macro. When RESERVE is in effect for a device, MVS™ first ensures that the device is reserved for the appropriate system.
Note:
1. The set-must-complete (SMC) parameter of the ENQ macro can also be used with RESERVE.
2. If a checkpoint restart occurs when a RESERVE is in effect for devices, the system does not restore the RESERVE; the user's program must reissue the RESERVE.
The SYSDSN major name must be in the GRSRNL inclusion list. See z/OS MVS Planning: Global Resource Serialization for information about GRSRNL and dynamically changing GRSRNL. See z/OS MVS Initialization and Tuning Reference for information about the GRSRNL parmlib member.
When the task issues a DEQ for the resource named on the RESERVE macro, the system reduces the count in the UCB. When this count reaches zero, the system ensures that the device is unreserved.
If global resource serialization is active, ISGENQ, ENQ, and DEQ with SCOPE=SYSTEMS specified, can serialize on a particular shared DASD data set without reserving the entire device. See z/OS MVS Planning: Global Resource Serialization for details.
The EXTRACT macro returns the address of the task input/output table (TIOT) from which the UCB address can be obtained. Finding the UCB address for the RESERVE macro explains this procedure. EXTRACT provides information; it does not actually serialize a resource.
The GETDSAB macro returns the address of the data set association block (DSAB) associated with a DD name. The DSAB contains the address of the task input/output table (TIOT) entry for the DD name, from which the UCB address can be obtained. GETDSAB provides information; it does not actually serialize a resource.
The macro has been enhanced to include a LOC parameter. This controls whether the search for the address of the DSAB should be restricted to those which reside below the 16Mb line (LOC=BELOW) or should examine both above and below the line DSABs (LOC=ANY). The default is to restrict the search to below the 16 Mb line.