 |
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: - 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 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. |
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
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=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.
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 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.
- ,
- ,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.
Notes on specifying multiple resources on one DEQ 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, 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
For only unconditional requests, the caller might encounter abend
code X'130' or X'530'. For unconditional and conditional
requests, the caller might encounter one of the following 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
Return codes are provided by the system only if RET=HAVE is designated.
If all of the return codes for the resources named in DEQ are 0,
register 15 contains 0. If any of the return codes are not 0, register
15 contains the address of a virtual storage area containing the return
codes as shown in Figure 1. Figure 1. Return Code Area Used by DEQ
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.
Table 1. Return
Codes for the DEQ Macro with the RET=HAVE Parameter| 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 2
Conditionally release control of the resource in Example 2 of ENQ. DEQ (MAJOR2,MINOR2,4,SYSTEM),TCB=(R2),RET=HAVE
Example 4
Release control of the resource in Example 1 of ENQ, if it has
been assigned to the current TCB. The length of the rname is explicitly
defined as 8 characters. DEQ (MAJOR1,MINOR1,8,STEP),RET=HAVE
|
z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN
Copyright IBM Corporation 1990, 2014