Description

ENQ assigns control of one or more serially reusable resources to a task. If any of the resources are not available, the task might be placed in a wait condition until all of the requested resources are available. Once control of a resource has been assigned to a task, it remains with that task until one of the programs running under that task issues a DEQ macro to release the resource or the task terminates.

You can request either shared or exclusive use of a resource. ENQ identifies the resource by a pair of names, the qname and the rname, and a scope value. The scope value determines what other tasks, address spaces, or systems can use the resource. All programs that share the resource must use the qname, rname, and scope value consistently.

Use ENQ with RET=TEST to determine the status of the resource. Return codes tell whether the resource is immediately available or in use, and whether control has been previously requested by the active task in another ENQ macro.

ENQ with the MASID and MTCB parameters allows a further conditional control of a resource. One task, called the “issuing task” can issue an ENQ macro for a resource specifying the ASID and TCB of another task, called the “matching task”. MTCB and MASID parameters are specified with RET=HAVE, RET=TEST, or ECB to provide additional return codes. If the issuing task does not receive control of the resource, it may receive a return code indicating that the resource is controlled by the matching task. Upon receiving this return code, the issuing task could use the resource, if serialization between itself and the matching task has been prearranged through a protocol.

Global resource serialization counts and limits the number of concurrent resource requests from an address space. If an unconditional ENQ (an ENQ that uses the RET=NONE option) causes the count of concurrent resource requests to exceed the limit, the caller ends abnormally with a system code of X'538'. For more information, see the topic on limiting concurrent requests for resources in z/OS MVS Programming: Assembler Services Guide.

Unless you specify otherwise, when a global resource serialization complex is initialized, global resource serialization searches the SYSTEM inclusion resource name list (RNL) and the SYSTEMS exclusion RNL for every resource specified with a scope of SYSTEM or SYSTEMS. A resource whose name appears on one of these RNLs might have its scope changed from the scope that appears on the macro. To prevent RNL processing, use the RNL=NO parameter. See z/OS MVS Planning: Global Resource Serialization for additional information about RNL processing.

The ENQ macro is also described in z/OS MVS Programming: Assembler Services Reference ABE-HSP, with the exception of the SMC, ECB, TCB, MASID, and MTCB parameters. For information on using the ENQ macro to serialize resources, see the z/OS MVS Programming: Authorized Assembler Services Guide.

Environment

The requirements for callers of ENQ are:

Environmental factor	Requirement
Minimum authorization:	Problem state with any PSW key. For the SMC, ECB, TCB, MASID, and MTCB parameters or when the specified `qname` is ADRDFRAG, ADRDSN, ARCENQG, BWODSN, SYSZ, SYSCTLG, SYSDSN, SYSIEA01, SYSIEECT, SYSIEFSD, SYSIGGV1, SYSIGGV2, SYSPSWRD, SYSVSAM, or SYSVTOC, the authorization must be 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: Any PASN, Any HASN, Any SASN For LINKAGE=SYSTEM with SMC=STEP: PASN=HASN, Any 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:	Control parameters must be in the primary address space. Except for the TCB, all parameters can reside above 16 megabytes.

Programming requirements

None.

Restrictions

See "Avoiding Interlock" in z/OS MVS Programming: Assembler Services Guide to ensure that you are following the protocols required to prevent the interlock.

Issuing two ENQ macros for the same resource without an intervening DEQ macro causes the task to end abnormally, unless the second ENQ designates RET=TEST, USE, CHNG, or HAVE. If the task ends, either normally or abnormally, while the task still has control of any serially reusable resources, all requests made by this task automatically have DEQ processing performed for them. If resource input addresses are incorrect, the task abnormally ends.

The caller cannot have an EUT FRR established.

There are some considerations to be aware of when using enclaves for tasks that serialize resources using the ENQ macro. For details, see “Using ENQ/DEQ or Latch Manager Services With Enclaves” in z/OS MVS Programming: Workload Management Services.

Input register information

Before issuing the ENQ 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 general purpose registers (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=CHNG, RET=HAVE, or ECB: If all return codes for the resources named in the ENQ 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 access registers (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.

Performance implications

None.

Syntax

The standard form of the ENQ macro is described as follows.

Syntax	Description

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

␢	One or more blanks must precede ENQ.

ENQ

␢	One or more blanks must follow ENQ.

(

`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). Default: assembled length of `rname` Note: Code `rname length` if `rname addr` is a register.

,
,STEP	Default: STEP
,SYSTEM
,SYSTEMS

)

,RET=CHNG	Default: RET=NONE
,RET=HAVE
,RET=TEST
,RET=USE
,RET=NONE

,SMC=NONE	Default: SMC=NONE
,SMC=STEP

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

,TCB=`tcb addr`	`tcb addr`: A-type address or register (2) - (12).
	Note: Do not specify ECB with RET. You can specify ECB and TCB together. If TCB is specified without ECB, you must specify RET=CHNG, TEST or USE.

,MASID=`matching-asid addr`	`matching-asid addr`: A-type address or register (2) - (12).
	Note: MTCB is required with MASID. Do not specify SMC or TCB with MASID.

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

,RNL=YES	Default: RNL=YES
,RNL=NO

,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 of an 8-character name. The name can contain any valid hexadecimal character. Every program issuing a request for a serially reusable resource must use the same qname, rname, and scope to represent the resource. Some names, such as those beginning with certain letter combinations (SYSZ for example), are used to protect system resources by requiring that the issuing program be in supervisor state, or system key, or APF-authorized. Authorized programs should use a restricted qname (as described under Minimum authorization in the Environment topic of this chapter) to prevent interference from unauthorized programs.

Note: See z/OS MVS Diagnosis: Reference for a list of major and minor ENQ/DEQ names and the resources that issue the ENQ/DEQ.

,

,rname addr

Specifies the address of the name used together with qname to represent a single resource. The name must be from 1 to 255 bytes long, can be qualified, and can contain any valid hexadecimal character.

,

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

,

,STEP

,SYSTEM

,SYSTEMS

Specifies the scope of the resource.

STEP specifies that the resource can be used only within an address space. If STEP is specified, a request for the same qname and rname from a program in another address space denotes a different resource.

SYSTEM specifies that the resource can be used by programs in more than one address space.

SYSTEMS specifies that the resource can be shared between systems.

STEP, SYSTEM, and SYSTEMS are mutually exclusive and do not refer to the same resource. If two macros specify the same qname and rname, but one specifies STEP and the other specifies SYSTEM or SYSTEMS, they are treated as requests for different resources.

)

Specifies the end of the resource description.

Notes on specifying multiple resources on one ENQ request:

Within a single set of parentheses, you can repeat the qname addr, rname addr, type of control, rname length, and the scope until there is a maximum of 255 characters, including the parentheses.
The following parameters apply to all the resources you specify on the request: RET, SMC, ECB, TCB, MASID, MTCB, and RNL.

,RET=CHNG

,RET=HAVE

,RET=TEST

,RET=USE

,RET=NONE

Specifies the type of request for the resources named on the ENQ request.

CHNG: The status of the resource specified is changed from shared to exclusive control. When RET=CHNG is specified, the exclusive|shared (E|S) parameter is overidden. This parameter ensures that the request will be exclusive regardless of the other parameter.
HAVE: Control of the resources is requested conditionally; that is, control is requested only if a request has not been made previously for the same task.
TEST: The availability of the resources is to be tested, but control of the resources is not requested.
USE: control of the resources is to be assigned to the active task only if the resources are immediately available. If any of the resources are not available, the active task is not placed in a wait condition.
NONE: Control of all the resources is unconditionally requested.

See Return and reason codes for an explanation of the return codes for these requests.

,SMC=NONE

,SMC=STEP

,ECB=ecb addr

,TCB=tcb addr

Specifies optional parameters available to the system programmer:

SMC specifies that the set must-complete function is not to be used (NONE) or that it is to set as non-dispatchable other tasks for the step until the requesting task has completed its operations on the resource (STEP).

See z/OS MVS Programming: Authorized Assembler Services Guide for a description of the set must-complete function.

Do not use SMC or RET with ECB.

When SMC=STEP is specified with RET=HAVE and the requesting task already has control of the resource, the SMC function is turned on and the task continues to control the resource.

SMC and TCB are mutually exclusive with the MASID parameter; therefore, hexadecimal return codes 20, 24, 28, and 44 will not be given by an ENQ using the SMC or TCB operands.

The return codes and status of the set must-complete function for the various RET specifications are as follows:

RET Parameter	Hexadecimal Code	SMC Status
RET=CHNG	0	on
RET=CHNG	4	off
RET=CHNG	8	off
RET=CHNG	14	off
RET=HAVE	0	on
RET=HAVE	8	on
RET=HAVE	14	off
RET=HAVE	18	off
RET=TEST	0	off
RET=TEST	4	off
RET=TEST	8	off
RET=TEST	14	off
RET=USE	0	on
RET=USE	4	off
RET=USE	8	off
RET=USE	14	off
RET=USE	18	off

ECB specifies the address of an ECB, and conditionally requests all of the resources named in the macro. If the return code for one or more requested resources is hexadecimal 4 or 24 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 or 24) are assigned to the requesting task.

If the ECB parameter is an A-type address, the address is the name of the fullword that is used as an ECB. If the operand is a register, then the register contains the address of the ECB.

Note: The ECB must reside in storage that is addressible from the caller's home address space.

TCB specifies a register that points to a TCB or specifies the address of a fullword on a fullword boundary that points to a TCB on whose behalf the ENQ is to be done. If TCB is specified, one of the following must also be specified:

RET=TEST
RET=USE
RET=CHNG
ECB

Note: The TCB resides in storage below 16 megabytes in the caller's address space.

,MASID=matching-asid addr

Specifies the matching task (by defining a matching ASID) for the ENQ, if it is used together with the MTCB parameter. MASID defines the ASID of a task that may be using a resource desired by the caller. If the MASID parameter is an A-type address, the address is the name of a fullword containing the ASID. If the operand is a register, then the register contains the ASID.

,MTCB=matching-tcb addr

Specifies the matching task (by defining a matching TCB) for the ENQ, if used together with the MASID parameter. MTCB defines the TCB of a task that may be using a resource desired by the caller. If the MTCB parameter is an A-type address, the address is the name of a fullword containing the TCB. If the operand is a register, then the register contains the TCB.

If the task specified by the MASID and MTCB parameters is not using the resource, global resource serialization gives control to the caller 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 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 the rname length for information about specifying rname length with MASID and MTCB.

,RNL=YES

,RNL=NO

Controls global resource serialization RNL processing, which can cause the scope value of a resource to change. IBM recommends that you use the default, RNL=YES, to allow global resource serialization to perform RNL processing. Use RNL=NO when you are sure that you want the request to be processed only by global resource serialization using only the specified scope. When RNL=NO is specified the ENQ request will be ignored by alternative serialization products. Refer to z/OS MVS Planning: Global Resource Serialization, RNL Processing, for more information about the use of RNL=NO.

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

,LINKAGE=SVC

,LINKAGE=SYSTEM

Specifies the type of linkage the caller is using to invoke the ENQ 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.
If TCB= is specified, then the specified TCB in the home address space is associated with the resource; otherwise, the TCB in the home address space making the request is associated with the resource.

The default is LINKAGE=SVC.

ABEND codes

For only unconditional requests, 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

The system provides a return code only if you specify RET=TEST, RET=USE, RET=CHNG, RET=HAVE, or ECB; otherwise, return of the task to the active condition indicates that control of the resource has been assigned or was previously assigned to the task. If all return codes for the resources named in the ENQ macro are 0, register 15 contains 0. For nonzero return codes, register 15 contains the address of a storage area containing the return codes, as shown in Figure 1.

Figure 1. Return Code Area Used by ENQ

The return codes are placed in the parameter list resulting from the macro expansion in the same sequence as the resource names in the ENQ macro.

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

Table 1. Return Codes for the ENQ 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. 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 flag byte 1 in the parameter list that identifies the owned resource. 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 ENQ macro with the RET=USE parameter are described in Table 2.

Table 2. Return Codes for the ENQ 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 flag byte 1 in the parameter list that identifies the owned resource. 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 ENQ macro with the RET=CHNG parameter are described in Table 3.

Table 3. Return Codes for the ENQ Macro with the RET=CHNG Parameter
Hexadecimal Return Code	Meaning and Action
0	Meaning: The status of the resource has been changed to exclusive. Action: None.
4	Meaning: The status of the resource cannot be changed to exclusive. Other tasks share the resource. Action: None required. However, you might take some action based on your application.
8	Meaning: The status of the resource cannot be changed to exclusive. Either no tasks have issued an ENQ request for the resource, or the task acquired the resource through the MASID parameter. Action: None required. However, you might take some action based on your application.
14	Meaning: The status of the resource cannot be changed to exclusive. 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 ENQ macro with the RET=HAVE parameter are described in Table 4.

Table 4. Return Codes for the ENQ 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 flag byte 1 in the parameter list that identifies the owned resource. 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 but that request has not yet been satisfied (such as an ENQ with RET=NONE which waits for the resource). 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 ENQ request.
28	Meaning: The caller cannot obtain exclusive control of the resource using the ENQ 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 ENQ request.
44	Meaning: The caller is violating a restriction of using the ENQ macro with the MASID and MTCB parameters in one or more of the following ways: Another task has already issued the ENQ 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 ENQ 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 ENQ macro with the ECB parameter are described in Table 5.

Table 5. Return Codes for the ENQ 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 active task does not have control of the resource yet. The ECB will be posted when the system assigns control to that task. Action: Wait on the ECB if your program cannot continue processing without control of the resource.
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 flag byte 1 in the parameter list that identifies the owned resource. 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 ENQ request.
24	Meaning: The caller that specifies the ENQ 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 ENQ request.
28	Meaning: The caller cannot obtain exclusive control of the resource using the ENQ 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 ENQ request.
44	Meaning: The caller is violating a restriction of using the ENQ macro with the MASID and MTCB parameters in one or more of the following ways: Another task has already issued the ENQ 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 ENQ 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 1

Unconditionally request exclusive control of a serially reusable resource that is known only within the address space (STEP), and set to non-dispatchable other tasks for the step until the requesting task has completed its operations on the resource.

ENQ  (MAJOR1,MINOR1,E,8,STEP),SMC=STEP

Example 2

Conditionally request control of a resource that can be shared on behalf of another task. The resource is known by more than one address space, and is only wanted if immediately available.

ENQ  (MAJOR2,MINOR2,S,4,SYSTEM),TCB=(R2),RET=USE