 |
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.
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.
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. |
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,
or RET=HAVE: 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.
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 |
|
| |
|
| ,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.
- ,
- ,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.
You can code a value between 1 and 255. Also,
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 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.
- ,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.
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, or RET=HAVE; 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.
|
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. No tasks have
issued an ENQ request for the resource. 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.
|
Example 1
Unconditionally request exclusive control of one resource and shared
control of another. The system will return control to the requesting
program only when both resources are available. ENQ (MAJOR3,MINOR3,E,8,SYSTEM,MAJOR4,MINOR4,S,6,SYSTEM)
Example 2
Conditionally request shared control of a serially reusable resource
that is known only within the address space (STEP). The resource
is only to be obtained if immediately available. The resource will
be used for read-only purposes. The length of rname is
allowed to default. ENQ (MAJOR1,MINOR1,S,,STEP),RET=USE
Example 3
Unconditionally request exclusive control of three resources.
The scope of each resource differs (STEP, SYSTEM, and SYSTEMS, respectively).
The rname length of the first resource is 3 characters
and the rname length of the third resource is 8
characters. Allow the rname length of the second
resource to default to its assembled length. ENQ (MAJOR4,MINOR4,E,3,,MAJOR2,MINOR2,,,SYSTEM, X
MAJOR3,MINOR3,E,8,SYSTEMS)
|
z/OS MVS Programming: Assembler Services Reference ABE-HSP
Copyright IBM Corporation 1990, 2014