z/OS MVS Assembler Services Reference IAR-XCT

Chapter 86. RESERVE — Reserve a device (shared DASD)

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

“Accessing Unit Control Blocks (UCBs)” in z/OS MVS Programming: Assembler

Services Guide for information about using the UCBSCAN macro.

Environment

The requirements for the caller are:

Environmental factor

Minimum authorization

:

Dispatchable unit mode

:

Cross memory mode

:

AMODE

:

ASC mode

:

Interrupt status

:

Locks

:

Control parameters

:

Requirement

Problem state with any PSW key.

Task

For LINKAGE=SVC: PASN=HASN=SASN

For LINKAGE=SYSTEM: PASN=HASN=SASN or

PASN¬=HASN¬=SASN

24- or 31- or 64-bit

Primary

Enabled for I/O and external interrupts

No locks held

If the caller's AMODE is 24-bit, all parameters must reside below 16 megabytes.

Programming requirements

None.

Restrictions

If a task issues two RESERVE macros for the same device without an intervening

DEQ macro, an abnormal termination results unless the second RESERVE specifies the keyword parameter RET. (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

© Copyright IBM Corp. 1988, 2017

871

RESERVE macro

Syntax

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.

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

2-13

Used as work registers by the system

Unchanged

14

15

Used as a work register by the system

One of the following: v If you specify RET=TEST, RET=USE, or RET=HAVE: 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.

v Otherwise: used as a work register by the system.

When control returns to the caller, the ARs contain:

Register

Contents

0-1

2-13

Used as work registers by the system

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:

Description

�

name

name: symbol. Begin name in column 1.

One or more blanks must precede RESERVE.

RESERVE

� One or more blanks must follow RESERVE.

872

z/OS MVS Assembler Services Reference IAR-XCT

RESERVE macro

Syntax

,

,E

,S

qname addr

,rname addr

,

,rname length

)

,SYSTEMS

,RET=TEST

,RET=USE

,RET=HAVE

,RET=NONE

,UCB=ucb addr

,LOC=BELOW

,LOC=ANY

,RELATED=value

,LINKAGE=SVC

,LINKAGE=SYSTEM

Description

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

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

Default:

E

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

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

Default:

LOC=BELOW

value: any valid macro keyword specification.

DEFAULT

: LINKAGE=SVC

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.

Chapter 86. RESERVE — Reserve a device (shared DASD)

873

RESERVE macro

,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: v If you specify MASID and MTCB, you can code a value between 1 and 128.

v 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.

,UCB=ucb addr

Specifies the address of a fullword that contains the address of the UCB for the device to be reserved. The UCB must 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.

874

z/OS MVS Assembler Services Reference IAR-XCT

RESERVE macro

,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.

v 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: v X'238' v X'338' v X'438' v X'738' v X'838' v X'938'

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

Return and reason codes

The system provides return codes only if you specify RET=TEST, RET=USE, or

RET=HAVE; 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 4 on page 876.

Chapter 86. RESERVE — Reserve a device (shared DASD)

875

RESERVE macro

Address

Returned in

Register 15

0

1 2 3 4 12

BYTE 0

BYTE 1

BYTE 2

Return

Code

12

Figure 4. Return Code Area Used by RESERVE

The return codes for the RESERVE macro with the RET=TEST parameter are

described in Table 48.

Table 48. Return Codes for the RESERVE Macro with the RET=TEST Parameter

Hexadecimal

Return Code

0

Meaning and Action

Meaning

: The resource is immediately available.

4

8

14

Action

: None required. However, you might take some action based on your application.

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.

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 4. If bit 3 is off,

the task has exclusive control; If bit 3 is on, the task has shared control.

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.

The return codes for the RESERVE macro with the RET=USE parameter are

described in Table 49.

Table 49. Return Codes for the RESERVE Macro with the RET=USE Parameter

Hexadecimal

Return Code

0

Meaning and Action

Meaning

: The active task now has control of the resource.

Action

: None.

876

z/OS MVS Assembler Services Reference IAR-XCT

RESERVE macro

Table 49. Return Codes for the RESERVE Macro with the RET=USE Parameter (continued)

Hexadecimal

Return Code

4

Meaning and Action

Meaning

: The resource is not immediately available.

8

Action

: None required. However, you might take some action based on your application.

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.

14

18

To determine whether the task has exclusive control or shared control

of the resource, check bit 3 of Byte 0 as shown in Figure 4 on page 876.

If bit 3 is off, the task has exclusive control; If bit 3 is on, the task has shared control.

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.

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 50.

Table 50. Return Codes for the RESERVE Macro with the RET=HAVE Parameter

Hexadecimal

Return Code

0

Meaning and Action

Meaning

: The active task now has control of the resource.

8

Action

: None.

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.

14

To determine whether the task has exclusive control or shared control of the

resource, check bit 3 of Byte 0 as shown in Figure 4 on page 876. If bit 3 is off,

the task has exclusive control; If bit 3 is on, the task has shared control.

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.

Chapter 86. RESERVE — Reserve a device (shared DASD)

877

RESERVE macro

Table 50. Return Codes for the RESERVE Macro with the RET=HAVE

Parameter (continued)

Meaning and Action Hexadecimal

Return Code

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.

Example

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

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

RESERVE—List form

The list 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.

(

,

,E

,S

qname addr

,

,rname addr

,

,

,rname length

qname addr: A-type address.

rname addr: A-type address.

rname length: symbol or decimal digit.

878

z/OS MVS Assembler Services Reference IAR-XCT

RESERVE macro

)

Syntax

,SYSTEMS

,RET=TEST

,RET=USE

,RET=HAVE

,RET=NONE

,UCB=ucb addr

,LOC=BELOW

,LOC=ANY

,RELATED=value

,MF=L

Description

ucb addr: A-type address or 0.

Default:

LOC=BELOW

value: A-type address.

Parameters

The parameters are explained under the standard form of the RESERVE macro, with the following exception:

,MF=L

Specifies the list form of the RESERVE macro.

RESERVE - Execute form

The execute 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.

Note:

( and ) are the beginning and end of a parameter list. The entire list is optional. If nothing in the list is desired, the (, ), and all parameters between

( and ) should not be specified. If something in the list is desired, then (, ), and all parameters in the list should be specified as indicated at the left.

Chapter 86. RESERVE — Reserve a device (shared DASD)

879

RESERVE macro

Syntax

qname addr

,

,rname addr

,

,E

,S

,

,rname length

)

,

,SYSTEMS

,RET=TEST

,RET=USE

,RET=HAVE

,RET=NONE

,UCB=ucb addr

,LOC=BELOW

,LOC=ANY

,RELATED=value

,LINKAGE=SVC

,LINKAGE=SYSTEM

,MF=(E, list addr)

Description

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

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

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

Note:

rname length must be coded if a register is specified for rname addr above.

ucb addr: RX-type address, or register (2) - (12).

Default:

LOC=BELOW

value: any valid macro keyword specification.

DEFAULT

: LINKAGE=SVC

list addr: RX-type address, or register (1) - (12).

Parameters

The parameters are explained under the standard form of the RESERVE macro, with the following exception:

880

z/OS MVS Assembler Services Reference IAR-XCT

RESERVE macro

,MF=(E,ctrl addr)

Specifies the execute form of the RESERVE macro.

list addr specifies the area that the system uses to contain the parameters.

Chapter 86. RESERVE — Reserve a device (shared DASD)

881

RESERVE macro

882

z/OS MVS Assembler Services Reference IAR-XCT