Description

The RESERVE macro reserves a device for use by a particular system; it must be issued by each task needing to reserve a device shared with one or more systems. The RESERVE macro protects the caller from interference by other tasks in the system and locks out other systems. The reserve actually occurs when the first I/O is done to the device after the RESERVE macro is issued. When the reserving program no longer needs the reserved device, it should issue a DEQ macro to release the resource. For information about the synchronous reserve feature, see z/OS MVS Planning: Global Resource Serialization and z/OS MVS Initialization and Tuning Guide.

For information about how to obtain the UCB address for a device, see the section “Finding the UCB Address for the RESERVE Macro” in z/OS MVS Programming: Authorized Assembler Services Guide.

If global resource serialization is active, the hardware RESERVE can be suppressed leaving a SYSTEMS ENQ depending on the contents of the resource name lists. See z/OS MVS Planning: Global Resource Serialization for information on resource name lists.

A RESERVE used with the MASID and MTCB operands provides a special form of the RESERVE macro that allows a further conditional control of a resource. One task, called the “issuing task” can issue a RESERVE macro for a resource specifying the ASID and TCB of another task, called the “matching task”.

The RESERVE macro is also described in z/OS MVS Programming: Assembler Services Reference ABE-HSP, with the exception of the MASID, MTCB, and ECB parameters.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state with any PSW key. For the MASID, MTCB, and ECB parameters, one of the following: Supervisor state PSW key 0-7 APF-authorized.
Dispatchable unit mode:	Task
Cross memory mode:	For LINKAGE=SVC: PASN=HASN=SASN For LINKAGE=SYSTEM: PASN=HASN=SASN or PASN¬=HASN¬=SASN
AMODE:	24- or 31- or 64-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	If the caller's AMODE is 24-bit, all parameters must reside below 16 megabytes.

Programming requirements

Before issuing the RESERVE macro with a UCB address, an authorized caller must serialize the UCB against dynamic I/O reconfiguration requests. The caller can accomplish this serialization by allocating or pinning the UCB. Such serialization ensures that a dynamic I/O reconfiguration request does not delete or reuse the UCB before the RESERVE macro uses the address.

Restrictions

If a task issues two RESERVE macros for the same device without an intervening DEQ macro, the task ends abnormally unless the second RESERVE specifies the keyword parameter RET or ECB. (If a restart occurs after the caller successfully issued the RESERVE macro for a resource, the system does not reserve the device again; the caller must reissue the RESERVE macro.) If a DEQ macro is not issued for a particular resource, the system releases the reserved resource when the task ends.

The system counts and limits the number of concurrent resource requests in an address space. If an unconditional RESERVE (a RESERVE macro with RET=NONE) causes the number of global resource serialization requests to exceed the limit, the caller is abnormally terminated with a system code of X'538'. For further information about limiting concurrent requests for resources, see in z/OS MVS Programming: Assembler Services Guide. For further information about limiting global resource serialization requests, see z/OS MVS Programming: Authorized Assembler Services Guide.

Input register information

Before issuing the RESERVE macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

When control returns to the caller, the GPRs contain:

Register

Contents

0-1

Used as work registers by the system

2-13

Unchanged

14

Used as a work register by the system

15

One of the following:

If you specify RET=TEST, RET=USE, RET=HAVE, or the ECB parameter:
If all return codes for the resources named in the RESERVE macro are 0, register 15 contains 0. If any of the return codes are not 0, register 15 contains the address of a storage area containing the return codes.
Otherwise: used as a work register by the system.

When control returns to the caller, the ARs contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Syntax

The standard form of the RESERVE macro is written as follows:

Syntax	Description

`name`	`name`: symbol. Begin `name` in column 1.

␢	One or more blanks must precede RESERVE.

RESERVE

␢	One or more blanks must follow RESERVE.

`qname addr`	`qname addr`: A-type address, or register (2) - (12).

`,rname addr`	`rname addr`: A-type address, or register (2) - (12).

,	Default: E
,E
,S

,
`,rname length`	`rname length`: symbol, decimal digit, or register (2) - (12).

,SYSTEMS
)

,RET=TEST
,RET=USE
,RET=HAVE
,RET=NONE

,ECB=`ecb addr`	`ecb addr`: A-type address, or register (2) - (12).

,UCB=`ucb addr`	`ucb addr`: A-type address, or register (2) - (12).

,LOC=BELOW	Default: LOC=BELOW
,LOC=ANY

,MASID=`matching-asid addr`	`matching-asid addr`: A-type address, or register (2) - (12).
,MTCB=`matching-tcb addr`	`matching-tcb addr`: A-type address, or register (2) - (12).

,RELATED=`value`	`value`: any valid macro keyword specification.

,LINKAGE=SVC	DEFAULT: LINKAGE=SVC
,LINKAGE=SYSTEM

Parameters

The parameters are explained as follows:

(

Specifies the beginning of the resource description.

qname addr

Specifies the address in virtual storage of an 8-character name. The name should not start with SYS, so that it will not conflict with system names. Every task issuing RESERVE against the same resource must use the same qname and rname to represent the resource.

,rname addr

Specifies the address in virtual storage of the name used together with qname to represent a single resource. The name can be qualified, and must be from 1 to 255 bytes long.

,

,E

,S

Specifies whether the request is for exclusive (E) or shared (S) control of the resource. If the resource is modified while under control of the task, the request must be for exclusive control; if the resource is not modified, the request should be for shared control.

,

,rname length

Specifies the length of the rname. If this parameter is omitted, the system uses the assembled length of the rname. To override the assembled length, specify this parameter; the value you can code depends on whether or not you also specify MASID and MTCB:

If you specify MASID and MTCB, you can code a value between 1 and 128.
If you do not specify MASID and MTCB, you can code a value between 1 and 255.

In either case, you can specify 0, which means that the length of the rname must be contained in the first byte at the rname addr.

,SYSTEMS

Specifies that the resource is shared among systems.

)

Specifies the end of the resource description.

,RET=TEST

,RET=USE

,RET=HAVE

,RET=NONE

RET=TEST, RET=USE, and RET=HAVE specify a conditional request for the resource named on the macro, as follows:

RET=TEST: The availability of the resource is to be tested, but control of the resource is not requested.
RET=USE: Control of the resource is to be assigned to the active task only if the resource is immediately available.
RET=HAVE: Control of the resource is requested only if the same task does not already control or have an outstanding request for the same resource.

RET=NONE specifies an unconditional request for the resource named on the macro.

,ECB=ecb addr

Specifies the address of an ECB, and conditionally requests the resource named in the macro. A return code of 4 is returned if contention on the ENQ resource exits or if the hardware reserve is done synchronously. The hardware reserve cannot be done if the request was converted to only a global ENQ.

If the return code for one or more requested resources is 4 and the request is not nullified by a corresponding DEQ, the ECB is posted when all the requested resources (specifically, those that initially received a return code of 4) are assigned to the requesting task.

Note:

The ECB must reside in storage that is addressable from the caller's home address space.
The ECB can also be used to measure the contention time on the ENQ or hardware resource. For more information, see "Timing Contention" section in z/OS MVS Programming: Authorized Assembler Services Guide.

See z/OS MVS Planning: Global Resource Serialization for more information about RESERVE conversion to global ENQs and synchronous (SYNCHRES) reserve processing.

,UCB=ucb addr

Specifies the address of a fullword that contains the address of the UCB for the device to be reserved. The UCB does not need to be allocated to the job step before RESERVE is issued.

Note: The UCB keyword might specify a UCB address for a UCB that resides in storage above or below 16 megabytes. If the UCB address might point to a UCB above 16 megabytes you must also specify LOC=ANY.

,MASID=matching-asid addr

Specifies the matching task (by defining a matching ASID) for the RESERVE. MASID defines the ASID of a task that may be using a resource desired by the issuer of the RESERVE macro.

Note: MASID can be specified only if MTCB is also specified.

,MTCB=matching-tcb addr

Specifies the matching task (by defining a matching TCB) for the RESERVE. MTCB defines the TCB of a task that may be using a resource desired by the issuer of the RESERVE macro.

Note: MTCB can be specified only if MASID is also specified.

If the task specified by the MASID and MTCB parameters is not using the resource, global resource serialization gives control to the issuer of the RESERVE and returns a return code indicating whether the resource can be used. If the task specified by MASID and MTCB parameters is using the resource, global resource serialization records a request for the resource, suspends the issuing task until the resource is available, or optionally returns a return code indicating that an ECB will be posted when the resource can be used.

The MASID and MTCB parameters are specified with the RET=HAVE, RET=TEST, or ECB parameters to elicit additional return codes that provide information about the owner of the resource.

See the description of rname length for information about specifying rname length with MASID and MTCB.

,LOC=BELOW

,LOC=ANY

Specifies the location of the input UCB address. ANY specifies that the input UCB address is to be treated as a 31-bit address. BELOW specifies that the input UCB address is to be treated as a 24-bit address. The default is LOC=BELOW.

,RELATED=value

Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user, and may be any valid values.

,LINKAGE=SVC

,LINKAGE=SYSTEM

Specifies the type of linkage the caller is using to invoke the RESERVE service.

For LINKAGE=SVC, the linkage is through an SVC instruction. This linkage is valid only when the caller is in primary mode and the primary, home, and secondary address spaces are the same.

For LINKAGE=SYSTEM, the linkage uses a non-SVC entry. This linkage is valid in cross memory mode or in non-cross memory mode. LINKAGE=SYSTEM is intended to be used by programs in cross memory mode.

If ECB= is specified, the ECB (not the address of the ECB) must be addressable from the home address space.

The default is LINKAGE=SVC.

ABEND codes

For unconditional requests only, the caller might encounter abend code X'138' or X'538'. For unconditional or conditional requests, the caller might encounter one of the following abend codes:

X'238'
X'338'
X'438'
X'738'
X'838'
X'938'

See z/OS MVS System Codes for explanations and responses for these codes.

Return and reason codes

Return codes are provided by the system only if you specify RET=TEST, RET=USE, RET=HAVE, or ECB; for RET=NONE, return to the task indicates that control of the resource has been assigned to the task. If the return code for the resource named in the RESERVE macro is 0, register 15 contains 0. If the return code is not 0, register 15 contains the address of a 12-byte storage area containing the return code, as shown in Figure 1.

Figure 1. Return Code Area Used by RESERVE

The return codes for the RESERVE macro with the RET=TEST parameter are described in Table 1.

Table 1. Return Codes for the RESERVE Macro with the RET=TEST Parameter
Hexadecimal Return Code	Meaning and Action
0	Meaning: The resource is immediately available. Action: None required. However, you might take some action based on your application.
4	Meaning: The resource is not immediately available or There might be contention on the reservethe hardware reserve is done synchronously. There might be contention on the reserve. Action: None required. However, you might take some action based on your application.
8	Meaning: A previous request for control of the same resource has been made for the same task. The task has control of the resource. Action: None required. However, you might take some action based on your application. To determine whether the task has exclusive control or shared control of the resource, check bit 3 of Byte 0 as shown in Figure 1. If bit 3 is off, the task has exclusive control; If bit 3 is on, the task has shared control.
14	Meaning: A previous request for control of the same resource has been made for the same task. The task does not have control of the resource. Action: None required. However, you might take some action based on your application.
20	Meaning: The matching task (the task specified in the MASID and MTCB parameters) owns the resource. Action: None required. However, you might take some action based on your application.

The return codes for the RESERVE macro with the RET=USE parameter are described in Table 2.

Table 2. Return Codes for the RESERVE Macro with the RET=USE Parameter
Hexadecimal Return Code	Meaning and Action
0	Meaning: The active task now has control of the resource. Action: None.
4	Meaning: The resource is not immediately available. Action: None required. However, you might take some action based on your application.
8	Meaning: A previous request for control of the same resource has been made for the same task. The task has control of the resource. Action: None required. However, you might take some action based on your application. To determine whether the task has exclusive control or shared control of the resource, check bit 3 of Byte 0 as shown in Figure 1. If bit 3 is off, the task has exclusive control; If bit 3 is on, the task has shared control.
14	Meaning: A previous request for control of the same resource has been made for the same task. The task does not have control of the resource. Action: None required. However, you might take some action based on your application.
18	Meaning: Environmental error. The limit for the number of concurrent resource requests has been reached. The task does not have control of the resource unless some previous ENQ or RESERVE request caused the task to obtain control of the resource. Action: Retry the request one or more times. If the problem persists, consult your system programmer, who might be able to tune the system so that the limit is no longer exceeded.

The return codes for the RESERVE macro with the RET=HAVE parameter are described in Table 3.

Table 3. Return Codes for the RESERVE Macro with the RET=HAVE Parameter
Hexadecimal Return Code	Meaning and Action
0	Meaning: The active task now has control of the resource. Action: None.
8	Meaning: A previous request for control of the same resource has been made for the same task. The task has control of the resource. Action: None required. However, you might take some action based on your application. To determine whether the task has exclusive control or shared control of the resource, check bit 3 of Byte 0 as shown in Figure 1. If bit 3 is off, the task has exclusive control; If bit 3 is on, the task has shared control.
14	Meaning: A previous request for control of the same resource has been made for the same task. The task does not have control of the resource. Action: None required. However, you might take some action based on your application.
18	Meaning: Environmental error. The limit for the number of concurrent resource requests has been reached. The task does not have control of the resource unless some previous ENQ or RESERVE request caused the task to obtain control of the resource. Action: Retry the request one or more times. If the problem persists, consult your system programmer, who might be able to tune the system so that the limit is no longer exceeded.
20	Meaning: The matching task (the task specified in the MASID and MTCB parameters) owns the resource. Action: The caller can use the resource, but it must ensure that the owning task does not terminate while the caller is using the resource. If the caller requested exclusive control, then this return code indicates that the matching task is the only task that currently owns the resource. If the caller requested shared control and the owning task requested shared control, this return code might indicate that a previous task had requested exclusive control. The caller must issue a DEQ macro to cancel this RESERVE request.
28	Meaning: The caller cannot obtain exclusive control of the resource using the RESERVE macro with the MASID and MTCB parameters. The matching task's involvement with other tasks precludes control by the caller. Action: This task must not issue a DEQ macro to cancel the RESERVE request.
44	Meaning: The caller is violating a restriction of using the RESERVE macro with the MASID and MTCB parameters in one or more of the following ways: Another task has already issued the RESERVE macro for this resource specifying the same values for the MASID and MTCB parameters The MASID and MTCB parameters specify a task that acquired control of the resource by using the RESERVE macro with the MASID and MTCB parameters The matching task requested ownership of the resource but has not yet been granted ownership. Action: Do not use the resource; the caller does not have control of it.

The return codes for the RESERVE macro with the ECB parameter are described in Table 4.

Table 4. Return Codes for the RESERVE Macro with the ECB Parameter
Hexadecimal Return Code	Meaning and Action
0	Meaning: The active task now has control of the resource. Action: Do not wait on the ECB; it will not be posted.
4	Meaning: The ENQ resource is not immediately available or the hardware reserve is done synchronously, so contention might exist on the reserve. Action: None required. However, you might take actions based on your application. To measure the time you want to wait for resolving the contention, you can set a timer with ECB and wait on both the RESERVE ECB and the timer ECB.
8	Meaning: A previous request for control of the same resource has been made for the same task. The task has control of the resource. Action: Do not wait on the ECB; it will not be posted. To determine whether the task has exclusive control or shared control of the resource, check bit 3 of Byte 0 as shown in Figure 1. If bit 3 is off, the task has exclusive control; If bit 3 is on, the task has shared control.
14	Meaning: A previous request for control of the same resource has been made for the same task. The task does not have control of the resource. Action: Do not wait on the ECB; it will not be posted.
18	Meaning: Environmental error. The limit for the number of concurrent resource requests has been reached. The task does not have control of the resource unless some previous ENQ or RESERVE request caused the task to obtain control of the resource. Action: Do not wait on the ECB; it will not be posted. Retry the request one or more times. If the problem persists, consult your system programmer, who might be able to tune the system so that the limit is no longer exceeded.
20	Meaning: The matching task (the task specified in the MASID and MTCB parameters) owns the resource. Action: Do not wait on the ECB; it will not be posted. The caller can use the resource, but it must ensure that the owning task does not terminate while the caller is using the resource. If the caller requested exclusive control, then this return code indicates that the matching task is the only task that currently owns the resource. If the caller requested shared control and the owning task requested shared control, this return code might indicate that a previous task had requested exclusive control. The caller must issue a DEQ macro to cancel this RESERVE request.
24	Meaning: The caller that specifies the RESERVE macro with the MASID and MTCB parameters will have exclusive control after the ECB is posted. Action: Wait on the ECB. Once the ECB is posted, the caller may use the resource, but must ensure that the matching task does not terminate while the caller is using the resource. The caller must issue a DEQ macro to cancel the RESERVE request.
28	Meaning: The caller cannot obtain exclusive control of the resource using the RESERVE macro with the MASID and MTCB parameters. The matching task's involvement with other tasks precludes control by the caller. Action: Do not wait on the ECB; it will not be posted. The caller must not issue a DEQ macro to cancel the RESERVE request.
44	Meaning: The caller is violating a restriction of using the RESERVE macro with the MASID and MTCB parameters in one or more of the following ways: Another task has already issued the RESERVE macro for this resource specifying the same values for the MASID and MTCB parameters The MASID and MTCB parameters specify a task that acquired control of the resource by using the RESERVE macro with the MASID and MTCB parameters The matching task requested ownership of the resource but has not yet been granted ownership. Action: Do not wait on the ECB; it will not be posted. Do not use the resource; the caller does not have control of it.

Example

Unconditionally reserve exclusive control of a device. The length of the rname is allowed to default.

RESERVE (MAJOR3,MINOR3,E,,SYSTEMS),UCB=(R3)