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.
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:
|
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. |
None.
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.
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.
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.
None.
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 | |
The parameters are explained as follows:
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 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.
See Return and reason codes for an explanation of the return codes for these requests.
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.
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.
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.
The default is LINKAGE=SVC.
See z/OS MVS System Codes for explanations and responses for these 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.
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.
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.
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.
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.
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:
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.
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:
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. |
ENQ (MAJOR1,MINOR1,E,8,STEP),SMC=STEP
ENQ (MAJOR2,MINOR2,S,4,SYSTEM),TCB=(R2),RET=USE