Description
The DEQ macro releases control of one or more serially reusable resources from the active task. A task ends abnormally if it either requests an unconditional release of a resource it does not control, or issues a request that contains incorrect parameters.
When you use DEQ to release control of a resource obtained through the ENQ macro, certain parameters on DEQ must match the parameters on the ENQ that assigned control to that resource. Similarly, when you use DEQ to release control of a resource obtained through the RESERVE macro, certain parameters on DEQ must match the parameters on the RESERVE that assigned control to that resource. In the cases where the parameters must match, the parameter descriptions note that fact.
A description of the DEQ macro also appears in z/OS MVS Programming: Assembler Services Reference ABE-HSP with the exception of the RMC, GENERIC, TCB, and UCB parameters. See the z/OS MVS Programming: Authorized Assembler Services Guide for information on using DEQ to release serialization of a resource.
Environment
The requirements for callers of DEQ are:
| Environmental factor | Requirement |
|---|---|
| Minimum authorization: | Problem state with any PSW key. For the RMC, TCB,
GENERIC=YES, and UCB (where UCB is not allocated to the requesting
task) or when the specified qname is ADRDFRAG,
ADRDSN, ARCENQG, BWODSN, SYSZ*, SYSCTLG, SYSDSN, SYSIEA01, SYSIEECT,
SYSIEFSD, SYSIGGV1, SYSIGGV2, SYSPSWRD, SYSVSAM, or SYSVTOC. 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 RMC=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. With the exception of TCB and UCB, all parameters can reside above 16 megabytes. |
Programming requirements
None.
Restrictions
The caller cannot have an EUT FRR established.
Input register information
Before issuing the DEQ 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
- 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=HAVE, if all return codes for the resources named in the DEQ 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.
- 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 DEQ macro is written as follows:
| Syntax | Description |
|---|---|
| name | name: symbol. Begin name in column 1. |
| ␢ | One or more blanks must precede DEQ. |
| DEQ | |
| ␢ | One or more blanks must follow DEQ. |
| ( | |
| qname addr | qname addr: A-type address, or register (2) - (12). |
| , | |
| ,rname addr | rname addr: A-type address, or register (2) - (12). |
| , | rname length: symbol, decimal digit, or register (2) - (12). |
| ,rname length | Note: rname length must be coded if a register is specified for rname addr. |
| , | Default: STEP |
| ,STEP | |
| ,SYSTEM | |
| ,SYSTEMS | |
| ) | |
| ,RET=NONE | Default: RET=NONE |
| ,RET=HAVE | |
| ,RMC=NONE | Default: RMC=NONE |
| ,RMC=STEP | |
| ,GENERIC=NO | Default: GENERIC=NO |
| ,GENERIC=YES | Note: If GENERIC=YES is specified, you must also specify RET=HAVE. |
| ,TCB=tcb addr | tcb addr: A-type address, or register (2) - (12). |
| Note: Do not specify TCB with RMC. | |
| ,UCB=ucb addr | ucb addr: A-type address, or register (2) - (12). |
| Note: Specify UCB only with SYSTEMS. | |
| ,LOC=BELOW | DEFAULT: LOC=BELOW |
| ,LOC=ANY | |
| ,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
characters. The qname must be the same name specified for the resource in an ENQ
or RESERVE macro. 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 and scope to represent the resource acquired by a previous ENQ or RESERVE macro. The name must be from 1 to 255 bytes long, can be qualified, and can contain any valid hexadecimal characters. The rname must be the same name specified for the resource in an ENQ or RESERVE macro.
- ,
- ,rname length
- Specifies the length of the rname. The length must have the same value as specified in the previous ENQ or RESERVE macro. If you omit this parameter, the system uses the assembled length of the rname. You can specify a value between 1 and 255 to override the assembled length, or you may specify a value of 0. If you specify 0, 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. If you used the ENQ macro to obtain control of the resource, the scope you specify on DEQ must match the scope specified on that ENQ. If you used the RESERVE macro to obtain control of the resource, you must specify SYSTEMS as the scope on DEQ.
- )
- Specifies the end of the resource description.
- 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, RMC, TCB, and RNL.
- ,RET=NONE
- ,RET=HAVE
- HAVE specifies that the request for releasing the resources named
in DEQ is to be honored only if the active task has been assigned
control of the resources or if the ECB parameter was specified on
the associated ENQ macro. A return code is set if the resource is
not held. NONE specifies an unconditional request to release all the
resources. RET=NONE is the default. The active task ends abnormally
if it has not been assigned control of the resources.
In either case, if the resources requested for release were originally queued with the ECB parameter specified, they are released with return code 0.
- ,RMC=NONE
- ,RMC=STEP
- RMC specifies that the reset must-complete function is not to
be used (NONE) or that the requesting task is to release the resources
and end the must-complete function (STEP). Do not specify RMC with
TCB or GENERIC. The NONE or STEP subparameter must agree with the
subparameter specified in the SMC parameter of the corresponding ENQ
macro. RMC=NONE is the default.
In either case, if the resources requested for release were originally queued with the ECB parameter specified, they are released with return code 0.
- ,GENERIC=NO
- ,GENERIC=YES
- Specifies whether or not (YES or NO) all resources with the specified qname are to be released. For the resource to be released, the task either must have control of the resource, or must be waiting for the system to post the ECB specified on the associated ENQ macro. If the task is waiting for a resource, but is not waiting for the ECB to be posted, the task remains queued and waiting. GENERIC=NO is the default.
- ,TCB=tcb addr
- 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 DEQ is to be done. The caller (not the directed task) ends
abnormally if the RET parameter is omitted and an attempt is made
to release a resource not requested or not owned by the directed task,
except when ECB was specified on the original ENQ. If ECB was specified
on the ENQ and the resource is not owned by the directed task, the
DEQ request releases the resources with a return code of 0 Note: The TCB resides in storage below 16 megabytes in the caller's home address space.
- ,UCB=ucb addr
- Specifies the address of a fullword that contains the address
of a UCB for a reserved device that is now being released. This parameter
is used to release a device reserved with the RESERVE macro and is
valid only with a scope of SYSTEMS. The UCB parameter is optional. Note: The UCB keyword might contain 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.
- ,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.
- ,RNL=YES
- ,RNL=NO
- Specifies whether the system is to perform RNL processing, which might change the scope value of a resource. You must specify the same RNL option as you used in the ENQ macro that requested the resource. The default is RNL=YES.
- ,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 can be any valid coding values.
- ,LINKAGE=SVC
- ,LINKAGE=SYSTEM
- Specifies the type of linkage the caller is using to invoke the
DEQ 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 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
- X'230'
- X'330'
- X'430'
- X'730'
- X'830'
- X'930'
See z/OS MVS System Codes for explanations and responses for these codes.
Return and reason codes
The return codes are placed in the parameter list resulting from the macro expansion in the same sequence as the resource names in the DEQ macro.
The return codes for the DEQ macro with the RET=HAVE parameter are described in Table 1.
| Hexadecimal Return Code | Meaning and Action |
|---|---|
| 0 | Meaning: The system has released the resource
(or resources, if you specified GENERIC=YES). Action: None. |
| 4 | Meaning: The resource (or resources, if
you specified GENERIC=YES) has been requested for the task, but the
task has not been assigned control of it. The task continues waiting.
(This return code might result if an exit routine, which received
control because of an interruption, issued the DEQ macro on behalf
of the task.) Action: None. |
| 8 | Meaning: Control of the resource (or resources,
if you specified GENERIC=YES) has not been requested by the active
task, or the resource has already been released. Action: None required. However, you might take some action based on your application. |
Example 1
DEQ (MAJOR1,MINOR1,8,STEP),RMC=STEPExample 2
DEQ (MAJOR2,MINOR2,4,SYSTEM),TCB=(R2),RET=HAVEExample 3
DEQ (MAJOR3,MINOR3,,SYSTEMS),UCB=(R3)Example 4
DEQ (MAJOR1,MINOR1,8,STEP),RET=HAVE