ISGENQ — Global resource serialization ENQ service

Description

Interface for Global Resource Serialization ENQ OBTAIN and RELEASE requests.

The GRS ENQ service routine is given control from the ISGENQ macro to:

Obtain a single or multiple ENQs with or without associated device reserves.
Change a single or multiple existing ENQs.
Release a single or multiple ENQs.
Test an obtain request.

This service is intended to replace ENQ, DEQ, and RESERVE.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state. Any PSW key To use OWNINGTTOKEN, ENQMAX, or when the specified QNAME is one of the authorized QNAMEs, authorization must be one of the following: Supervisor state, PSW key 0-7, or APF authorized. Note: When an authorized caller issues an OBTAIN request with an unauthorized QNAME, if COND=YES, the request is granted, but a warning return code and the reason ISGENQRsn_UnprotectedQName are given. This is to warn that an unauthorized caller may block the ENQ, or even release the ENQ if running under the owning task. If COND=NO, authorized callers cannot obtain an ENQ on an unprotected resource. The authorized QNAMES are: ADRDFRAG ADRDSN ARCENQG BWODSN SYSCTLG SYSDSN SYSIEA01 SYSIEECT SYSIEFSD SYSIGGV1 SYSIGGV2 SYSPSWRD SYSVSAM SYSVTOC SYSZ*
Dispatchable unit mode:	Task
Cross memory mode:	Any PASN, any HASN, any SASN Note: The resulting ENQ is associated with the owning task in the home address space.
AMODE:	31- or 64-bit If in AMODE 64, specify SYSSTATE AMODE64=YES before invoking this macro.
ASC mode:	Primary or access register (AR) If in access register ASC mode, specify SYSSTATE ASCENV=AR before invoking this macro.
Interrupt status:	Enabled for I/O and external interrupts
Locks:	The caller must not be locked.
Control parameters:	Control parameters must be in the primary address space or, for AR-mode callers, must be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL). The control parameters must be in the same key as the caller. The ECB specified must be in the caller's home address space or in common. The TCB of the owning task (the current task or specified by OWNINGTTOKEN) must be in the caller's home address space. If a captured UCB address is specified, the captured UCB must be in the caller's home address space.

Programming requirements

The caller must include the ISGYCON macro to get the return and reason codes.

The caller must include the ISGYENQ macro to get the mappings for the ISGYENQAA, ISGYENQRES, ISGYENQTOKEN, and ISGYENQRETURN tables.

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

Restrictions

The caller must not have functional recovery routines (FRRs).

This macro supports multiple versions. Some keywords are unique to certain versions. See the ,PLISTVER=IMPLIED_VERSION parameter description.

Input register information

Before issuing the ISGENQ macro, the caller does not have to place any information into any general purpose register (GPR) or access register (AR) 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 GPRs contain:

Register: Contents
0: Reason code if GPR15 is not 0
1: Used as a work register by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

When control returns to the caller, the 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

ISGENQ syntax

parameters-1

parameters-2

parameters-3

parameters-4

parameters-5

parameters-6

Parameters

The parameters are explained as follows:

name

An optional symbol, starting in column 1, that is the name on the ISGENQ macro invocation. The name must conform to the rules for an ordinary assembler language symbol.

,ANSAREA=ansarea

When TEST=YES and REQUEST=OBTAIN are specified, an optional output parameter, which contains the returned information. The area is a list of records mapped by ISGYENQAA in the ISGYENQ macro. For RESLIST=YES, the records are in the same order as the requests in the RESTABLE. ANSLEN is required if ANSAREA is specified.

Note: The answer area is returned only when RC=0 or RC=4.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,ENQMAX=YES

,ENQMAX=NO

When TEST=NO and REQUEST=OBTAIN are specified, an optional parameter that indicates whether ENQMAX checking should be done. This keyword tells global resource serialization whether a check is to be made to see if the limit for the number of concurrent resource requests has been exceeded. The default is ENQMAX=YES.

,ENQMAX=YES: Indicates ENQMAX checking should be done. IBM suggests that you use the default, ENQMAX=YES, to allow global resource serialization to perform this processing.
,ENQMAX=NO: Indicates that ENQMAX checking should not be used. Use ENQMAX=NO when you have a system-critical ENQ request that should be honored regardless of the concurrent number of resource requests made from the home address space.
Note: ENQMAX=NO can only be specified by an authorized requester and therefore can only override the maximum for authorized requesters.

See z/OS MVS Planning: Global Resource Serialization for more information.

,ANSLEN=anslen

,ANSLEN=NO_ANSLEN

When TEST=YES and REQUEST=OBTAIN are specified, an optional input parameter that is the length of the answer area provided. The answer area should be large enough to hold a ISGYENQAA record and an RNAME for each request (specified by NUMRES, or one if RESLIST=NO). The maximum size area needed to contain one RNAME is 256 bytes. ANSAREA is required if ANSLEN is specified. The default is NO_ANSLEN.

To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.

,COND=NO

,COND=YES

An optional parameter that indicates how the request is handled for unsuccessful processing. The default is COND=NO.

,COND=NO: Indicates that if the request is not successful, then ISGENQ should ABEND the caller. COND=NO is mutually exclusive with RETCODE, RSNCODE, RETURNTABLE, WAITTYPE=ECB, and with TEST=YES.
,COND=YES: Indicates that ISGENQ should always return to the caller and indicate via return and reason codes whether the request was successful. If COND=YES is specified, RETCODE and RSNCODE (and RETURNTABLE, if RESLIST=YES) are required keywords.
Note: When COND=YES, ISGENQ tries to provide return and reason codes for the errors occurred during the process, though in some cases abends might be issued.

,CONTENTIONACT=WAIT

,CONTENTIONACT=FAIL

When TEST=NO and REQUEST=OBTAIN are specified, an optional parameter that indicates the action that should be taken if there is contention for the requested resource.

Note that a reserve request (where UCB@ is specified) that is not converted to only a global ENQ (Systems) will consist of an ENQ resource and a hardware reserve. For more information on reserve processing, see the description of the ,SYNCHRES=SYSTEM keyword for more information on reserve processing. The default is CONTENTIONACT=WAIT.

,CONTENTIONACT=WAIT

Indicates that the caller waits until the ENQ resource is available and, if applicable, the synchronous reserve I/O (see SYNCHRES) is complete.

,CONTENTIONACT=FAIL

Indicates that if contention for the ENQ resource exists to cancel the ENQ obtain request and return to the caller.

Notes:

See CONTENTIONACT=WAIT with ECB@ as a means of timing the overall request.
For a reserve request (where UCB@ is specified), the ENQ resource is always obtained first. As such, CONTENTIONACT=FAIL indicates to cancel the entire request when there is contention on the ENQ resource. However, it does not apply to contention on the hardware reserve. See CONTENTIONACT=WAIT with WAITTYPE=ECB for information on how to manage or time hardware reserve contention.

,CONTROL=EXCLUSIVE

,CONTROL=SHARED

,CONTROL=VALUE

When RESLIST=NO and REQUEST=OBTAIN are specified, a required parameter that is the control type of the ENQ to be obtained. 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.

,CONTROL=EXCLUSIVE: Indicates that the request is for exclusive control of the resource.
,CONTROL=SHARED: Indicates that the request is for shared control of the resource.
,CONTROL=VALUE: the user provides a value, through the CONTROLVAL keyword, indicating the requested control.

,CONTROL=DO_NOT_OVERRIDE

,CONTROL=EXCLUSIVE

,CONTROL=SHARED

When RESLIST=YES and REQUEST=OBTAIN are specified, an optional parameter that is the type of control to be used for all resources specified in the resource table. This overrides any control specified in the resource table. 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. The default is CONTROL=DO_NOT_OVERRIDE.

,CONTROL=DO_NOT_OVERRIDE: Indicates that the control specified in the resource table should be used.
,CONTROL=EXCLUSIVE: Indicates that all requests are for exclusive control of the resources.
,CONTROL=SHARED: Indicates that all requests are for shared control of the resources.

,CONTROL=EXCLUSIVE

,CONTROL=SHARED

When RESLIST=NO and REQUEST=CHANGE are specified, control is an optional keyword input that is the control type to which the ENQ is to be changed. If the resource is modified 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. When RESLIST=YES is specified, all resources in the list will be changed to the specified scope. The default is CONTROL=EXCLUSIVE.

,CONTROL=EXCLUSIVE: Indicates that the request is to change to exclusive control of the resource.
,CONTROL=SHARED: Indicates that the request is to change to shared control of the resource.

,CONTROLVAL=controlval

When CONTROL=VALUE, RESLIST=NO and REQUEST=OBTAIN are specified, a required input parameter that contains a value indicating the desired control. The value provided must be equivalent to the constants provided in the ISGYENQ macro indicating the control. (See the ISGYENQ_kControl constants in the ISGYENQ macro for more information.)

To code: Specify the RS-type address, or address in register (2)-(12), of an one-byte field.

,ECB@=ecb@

When WAITTYPE=ECB, CONTENTIONACT=WAIT, TEST=NO and REQUEST=OBTAIN are specified, a required input parameter that contains the address of the ECB to be posted when the requested resource(s) is/are obtained.

The ECB must be in one of the following locations:

the home address space of the caller.
common space.
for unauthorized requesters, in the same storage key as the requester.

When the ISGENQ service returns to the caller, the return and reason codes specify for each resource whether the task has been given control of the resource or needs to wait for the ECB to be posted.

When the ECB is posted, it contains a return/reason code pair. Bits 8-23 contain the low-order halfword of the reason code and bits 24-31 contain the low-order byte of the return code. For a RESLIST=NO request, the ECB contains the return and reason code for the request. For a RESLIST=YES request, the ECB contains an overall return code.

To code: Specify the RS-type address, or address in register (2)-(12), of a pointer field.

,ENQTOKEN=enqtoken

When RESLIST=NO and REQUEST=OBTAIN are specified, a required output parameter that is a token that uniquely identifies the ENQ. The ENQTOKEN is used on subsequent REQUEST=RELEASE or CHANGE invocations to release or change the ENQ request.

To code: Specify the RS-type address, or address in register (2)-(12), of a 32-character field.

,ENQTOKEN=enqtoken

When RESLIST=NO and REQUEST=CHANGE are specified, a required input parameter that is an ENQ Token of the ENQ to be changed.

To code: Specify the RS-type address, or address in register (2)-(12), of a 32-character field.

,ENQTOKEN=enqtoken

When RESLIST=NO and REQUEST=RELEASE are specified, a required input parameter that is an ENQ Token of the ENQ to be released.

To code: Specify the RS-type address, or address in register (2)-(12), of a 32-character field.

,ENQTOKENTBL=enqtokentbl

When RESLIST=YES and REQUEST=OBTAIN are specified, a required output parameter that is a table of ENQ tokens. Mapped by ISGYENQToken in the ISGYENQ macro. To easily release any ENQs obtained by a REQUEST=OBTAIN use the same ENQToken table as input to a REQUEST=RELEASE.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,ENQTOKENTBL=enqtokentbl

When RESLIST=YES and REQUEST=CHANGE are specified, a required input parameter that is a table of ENQ Tokens. Mapped by ISGYENQToken in the ISGYENQ macro.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,ENQTOKENTBL=enqtokentbl

When RESLIST=YES and REQUEST=RELEASE are specified, a required input parameter that is a table of ENQ Tokens. Mapped by ISGYENQToken in the ISGYENQ macro.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,MF=S

,MF=(L,list addr)

,MF=(L,list addr,attr)

,MF=(L,list addr,0D)

,MF=(E,list addr)

,MF=(E,list addr,COMPLETE)

An optional input parameter that specifies the macro form.

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.

Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.

Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

,list addr: The name of a storage area to contain the parameters. For MF=S and MF=E, this can be an RS-type address or an address in register (1)-(12).
,attr: An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE: Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.

,NUMRES=numres

When RESLIST=YES and REQUEST=OBTAIN are specified, a required input parameter that is the number of resource entries in the resource table. The specified value can be in the range of 1 to 2?6-1 (65535).

To code: Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.

,NUMRES=numres

When RESLIST=YES and REQUEST=CHANGE are specified, a required input parameter that is the number of ENQ tokens in the ENQ token table. The specified value can be in the range of 1 to 2?6-1 (65535).

To code: Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.

,NUMRES=numres

When RESLIST=YES and REQUEST=RELEASE are specified, a required input parameter that is the number of ENQ tokens in the ENQ Token Table. The specified value can be in the range of 1 to 2?6-1 (65535).

To code: Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.

,OWNINGTTOKEN=owningttoken

,OWNINGTTOKEN=CURRENT_TASK

When WAITTYPE=ECB, CONTENTIONACT=WAIT, TEST=NO and REQUEST=OBTAIN are specified, an optional input parameter that is the task token (TToken) of the task on whose behalf the ENQ is to be obtained. The TToken must specify a task in the caller's home address space.

Note: Mutually exclusive with RESERVEVOLUME=YES. The default is CURRENT_TASK.

To code: Specify the RS-type address, or address in register (2)-(12), of a 16-character field.

,OWNINGTTOKEN=owningttoken

,OWNINGTTOKEN=CURRENT_TASK

When CONTENTIONACT=FAIL, TEST=NO and REQUEST=OBTAIN are specified, an optional input parameter that is the task token (TToken) of the task on whose behalf the ENQ is to be obtained. The TToken must specify a task in the caller's home address space.

Note: Mutually exclusive with RESERVEVOLUME=YES. The default is CURRENT_TASK.

To code: Specify the RS-type address, or address in register (2)-(12), of a 16-character field.

,OWNINGTTOKEN=owningttoken

,OWNINGTTOKEN=CURRENT_TASK

When TEST=YES and REQUEST=OBTAIN are specified, an optional input parameter that is the task token (TToken) of the task on whose behalf the test request is to be performed. The TToken must specify a task in the caller's home address space.

Note: Mutually exclusive with RESERVEVOLUME=YES. The default is CURRENT_TASK.

To code: Specify the RS-type address, or address in register (2)-(12), of a 16-character field.

,OWNINGTTOKEN=owningttoken

,OWNINGTTOKEN=CURRENT_TASK

When REQUEST=CHANGE is specified, an optional input parameter that is the task token (TToken) of the task that owns the ENQ that is to be changed. The TToken must specify a task in the caller's home address space. The default is CURRENT_TASK.

To code: Specify the RS-type address, or address in register (2)-(12), of a 16-character field.

,OWNINGTTOKEN=owningttoken

,OWNINGTTOKEN=CURRENT_TASK

When REQUEST=RELEASE is specified, an optional input parameter that is the task token (TToken) of the task that owns the ENQs that are to be released. The TToken must specify a task in the caller's home address space. The default is CURRENT_TASK.

To code: Specify the RS-type address, or address in register (2)-(12), of a 16-character field.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=1

,PLISTVER=2

An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:

IMPLIED_VERSION, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
MAX, if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
1, which supports all parameters except those specifically referenced in higher versions.
2, which supports both the following parameters and those from version 1: USERDATA

To code: Specify one of the following:

IMPLIED_VERSION
MAX
A decimal value of 1, or 2

,QNAME=qname

When RESLIST=NO and REQUEST=OBTAIN are specified, a required input parameter that is the QNAME of the resource. The QNAME can contain any character from X'00' to X'FF'. However, a unique readable value that identifies the functional area or a high level of what is being serialized is preferred. 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 must use a restricted QNAME (as described under Minimum authorization in the Environment section for this service ) to prevent interference from unauthorized programs.

For a list of QNAME (also known as major name) and RNAME (also known as minor name) ENQ or DEQ names and the resources that issue the ENQ or DEQ, see z/OS MVS Diagnosis: Reference.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,QNAME=qname

,QNAME=DO_NOT_OVERRIDE

When RESLIST=YES and REQUEST=OBTAIN are specified, an optional input parameter that is a common QNAME to be used for all resources in the resource table. This overrides any QNAMEs specified in the resource table. The QNAME can contain any character from X'00' to X'FF'. However, a unique readable value that identifies the functional area or a high level of what is being serialized is preferred. 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 must use a restricted QNAME (as described under Minimum authorization in the Environment section for this service ) to prevent interference from unauthorized programs.

For a list of QNAME (also known as major name) and RNAME (also known as minor name) ENQ or DEQ names and the resources that issue the ENQ or DEQ, see z/OS MVS Diagnosis: Reference.

The default is DO_NOT_OVERRIDE.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

REQUEST=OBTAIN

REQUEST=CHANGE

REQUEST=RELEASE

A required parameter that indicates the type of ISGENQ request.

REQUEST=OBTAIN: Indicates a request to obtain an ENQ for a resource.
REQUEST=CHANGE: Indicates a request to change the status an ENQ from shared to exclusive control.
REQUEST=RELEASE: Indicates a request to release (dequeue) the ENQ for a resource.

,RESERVEVOLUME=NO

,RESERVEVOLUME=YES

When RESLIST=NO and REQUEST=OBTAIN are specified, an optional parameter. The default is RESERVEVOLUME=NO.

,RESERVEVOLUME=NO: Indicates to issue a normal ENQ obtain and not a reserve.
,RESERVEVOLUME=YES: Indicates that after the ENQ resource is obtained that a reserve for the given device (shared DASD) is to be issued.
Note: RESERVEVOLUME=YES is mutually exclusive with OWNINGTTOKEN.

,RESLIST=NO

,RESLIST=YES

When REQUEST=OBTAIN is specified, an optional parameter, The default is RESLIST=NO.

,RESLIST=NO: Indicates to obtain an ENQ for a single resource.
,RESLIST=YES: Indicates to obtain ENQs for multiple resources specified in a resource table. Specifying multiple requests in a list ensures that they are processed atomically with respect to other ISGENQ requests. However, the order in which the requests are processed is unpredictable. Each request is treated as a separate request, and if COND=YES is specified, then the return code for each request should be checked.
Note: An easy way to release a list of ENQs is to use the output ENQTOKEN table from the OBTAIN request as input to a RELEASE request.

,RESLIST=NO

,RESLIST=YES

When REQUEST=CHANGE is specified, an optional parameter, The default is RESLIST=NO.

,RESLIST=NO: Indicates to change the control of a single ENQ.
,RESLIST=YES: Indicates to change the control for multiple ENQs.

,RESLIST=NO

,RESLIST=YES

When REQUEST=RELEASE is specified, an optional parameter, The default is RESLIST=NO.

,RESLIST=NO: Indicates to single ENQ RELEASE request.
,RESLIST=YES: Indicates to change the disposition for multiple ENQs.
Note: A easy way to release a list of ENQs is to use the output ENQTOKEN table from the OBTAIN request as input to a RELEASE request.

,RESTABLE=restable

When RESLIST=YES and REQUEST=OBTAIN are specified, a required input parameter that is a table specifying multiple ENQ requests. The resource table is mapped by ISGYENQRes in the ISGYENQ macro.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,RETCODE=retcode

An optional output parameter into which the return code is to be copied from GPR 15. If you specify 15, GPR15, REG15, or R15 (within or without parentheses), the value will be left in GPR 15.

To code: Specify the RS-type address of a fullword field, or register (2)-(12) or (15), (GPR15), (REG15), or (R15).

,RETURNTABLE=returntable

When RESLIST=YES and REQUEST=OBTAIN are specified, an optional output parameter that is a table that contains the return and reason codes. Mapped by ISGYENQReturn in the ISGYENQ macro. The return table is only valid when ISGENQRsn_NonZeroReturnCodes is returned in the RSNCODE. Mutually exclusive with COND=NO.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,RETURNTABLE=returntable

When RESLIST=YES and REQUEST=CHANGE are specified, an optional output parameter that is a table that contains the return and reason codes. Mapped by ISGYENQReturn in the ISGYENQ macro. The return table is only valid when ISGENQRsn_NonZeroReturnCodes is returned in the RSNCODE. Mutually exclusive with COND=NO.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,RETURNTABLE=returntable

When RESLIST=YES and REQUEST=RELEASE are specified, an optional output parameter that is a table that contains the return and reason codes. Mapped by ISGYENQReturn in the ISGYENQ macro. The return table is only valid when ISGENQRsn_NonZeroReturnCodes is returned in the RSNCODE. Mutually exclusive with COND=NO.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,RNAME=rname

When RESLIST=NO and REQUEST=OBTAIN are specified, a required input parameter that is the RNAME for the resource. The RNAME must be from 1 to 255 bytes long, and can contain any hexadecimal character from X'00' to X'FF'.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,RNAME=rname

,RNAME=DO_NOT_OVERRIDE

When RESLIST=YES and REQUEST=OBTAIN are specified, an optional input parameter that is the common RNAME to be used for all resources in the resource table. This overrides any RNAMEs specified in the resource table. The RNAME must be from 1 to 255 bytes long, and can contain any hexadecimal character from X'00' to X'FF'. The default is DO_NOT_OVERRIDE.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,RNAMELEN=rnamelen

When RESLIST=NO and REQUEST=OBTAIN are specified, a required input parameter that is the length of the given RNAME. The specified length can be in the range of 1 to 255.

To code: Specify the RS-type address, or address in register (2)-(12), of an one-byte field.

,RNAMELEN=rnamelen

,RNAMELEN=DO_NOT_OVERRIDE

When RESLIST=YES and REQUEST=OBTAIN are specified, an optional input parameter that is a common length to be used for all RNAMEs in the resource table, or if a common RNAME is specified, it is the length of the common RNAME. The specified length can be in the range of 1 to 255. This overrides any RNAMEs lengths specified in the resource table. The default is DO_NOT_OVERRIDE.

To code: Specify the RS-type address, or address in register (2)-(12), of an one-byte field.

,RNL=YES

,RNL=NO

When RESERVEVOLUME=NO, RESLIST=NO and REQUEST=OBTAIN are specified, an optional parameter that indicates whether the scope can be changed by global resource serialization resource name list (RNL) processing, installation exits, or alternate serialization products. The default is RNL=YES.

,RNL=YES: Indicates that global resource serialization RNL processing should be used, which can cause the scope of a resource to change. In general, IBM recommends that you use the default, RNL=YES, to allow global resource serialization to perform RNL processing and allow installation exits and alternate serialization products to alter, extend, or restrict the scope and other attributes, as needed.
,RNL=NO: Indicates that global resource serialization RNL processing should not be used. The scope of the resource is not changed by the RNLs, any installation exits, or alternate serialization product. Use RNL=NO when you are sure that you want the request to be processed only by GRS using only the specified scope or when an alternate serialization product or installation exit should be prevented from altering the scope or other attributes, extending the scope beyond the GRS serialization complex, or restricting the scope to systems other than all of those in the GRS complex.

,RNL=DO_NOT_OVERRIDE

,RNL=YES

,RNL=NO

When RESLIST=YES and REQUEST=OBTAIN are specified, an optional parameter that indicates whether the scope can be changed by global resource serialization resource name list (RNL) processing or the dynamic exits. This overrides any RNL processing specified in the resource table. The default is RNL=DO_NOT_OVERRIDE.

,RNL=DO_NOT_OVERRIDE: Indicates that the RNL specifications in the resource table should be used.
,RNL=YES: Indicates that global resource serialization RNL processing should be used, which can cause the scope of a resource to change. IBM suggests that you use the default, RNL=YES, to allow global resource serialization to perform RNL processing.
,RNL=NO: Indicates that global resource serialization RNL processing should not be used. The scope of the resource cannot be changed by the RNLs or any dynamic exits. 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 is ignored by alternative serialization products.

,RSNCODE=rsncode

An optional output parameter into which the reason code is to be copied from GPR 0. If you specify 0, 00, GPR0, GPR00, REG0, REG00, or R0 (within or without parentheses), the value will be left in GPR 0.

To code: Specify the RS-type address of a fullword field, or register (0) or (2)-(12), (00), (GPR0), (GPR00), REG0), (REG00), or (R0).

,SCOPE=STEP

,SCOPE=SYSTEM

,SCOPE=SYSTEMS

,SCOPE=SYSPLEX

,SCOPE=VALUE

When RESERVEVOLUME=NO, RESLIST=NO and REQUEST=OBTAIN are specified, a required parameter that is the scope of the resource.

,SCOPE=STEP: Indicates that the resource is serialized 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.
,SCOPE=SYSTEM: Indicates that the resource is serialized across all address spaces in a system.
,SCOPE=SYSTEMS: Indicates that the resource is serialized across all systems in a GRS Star or GRS Ring complex.
,SCOPE=SYSPLEX: Indicates that the resource is serialized across all systems in a GRS Star sysplex or GRS ring. (Same as scope SYSTEMS.)
,SCOPE=VALUE: the user provides a value, through the SCOPEVAL keyword, indicating the requested scope.

,SCOPE=DO_NOT_OVERRIDE

,SCOPE=STEP

,SCOPE=SYSTEM

,SCOPE=SYSTEMS

,SCOPE=SYSPLEX

When RESLIST=YES and REQUEST=OBTAIN are specified, an optional parameter that is the scope to be used for all resources in the resource table. This overrides any scopes specified in the resource table. The default is SCOPE=DO_NOT_OVERRIDE.

,SCOPE=DO_NOT_OVERRIDE: Indicates that the scope specified in the resource table should be used.
,SCOPE=STEP: Indicates that the resource is serialized 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.
,SCOPE=SYSTEM: Indicates that the resource is serialized across all address spaces in a system.
,SCOPE=SYSTEMS: Indicates that the resource is serialized across all systems in a GRS Star or GRS Ring complex.
,SCOPE=SYSPLEX: Indicates that the resource is serialized across all systems in a GRS Star sysplex or GRS ring. (Same as scope SYSTEMS.)

,SCOPEVAL=scopeval

When SCOPE=VALUE, RESERVEVOLUME=NO, RESLIST=NO and REQUEST=OBTAIN are specified, a required input parameter that contains a value indicating the desired scope. The value provided must be equivalent to the constants provided in the ISGYENQ macro indicating the scope. (See the ISGYENQ_ constants in the ISGYENQ macro for more information.)

To code: Specify the RS-type address, or address in register (2)-(12), of an one-byte field.

,SYNCHRES=SYSTEM

,SYNCHRES=YES

,SYNCHRES=NO

When RESERVEVOLUME=YES, RESLIST=NO and REQUEST=OBTAIN are specified, an optional parameter that specifies whether the request should issue a synchronous reserve. A synchronous reserve immediately reserves the volume instead of waiting for the first use.

Note that an RC=4 (ISGENQRc_Warn), RSC=0403 (ISGENQRsn_ECBWillBePosted) is presented for CONTENTIONACT=WAIT, WAITTYPE=ECB, reserve requests (where UCB@ is specified) when there is contention on the ENQ resource or there was no contention on the resource, and the reserve I/O was done synchronously. The default is SYNCHRES=SYSTEM.

,SYNCHRES=SYSTEM: Indicates that the installation system default SYNCHRES setting should be used.
,SYNCHRES=YES: Indicates to issue a synchronous reserve. In cases where the hardware reserve is performed (it was not converted to a Global/Systems ENQ), the caller is ensured that the reserve I/O is complete when the ISGENQ request has successfully completed.
,SYNCHRES=NO: Indicates that a synchronous reserve should be avoided when possible. Some devices require that the reserve must be done synchronously regardless of this setting. If the reserve I/O is not done synchronously, the reservce is done when the first I/O is done to the device after the reserve request is issued. For more information, see z/OS MVS Planning: Global Resource Serialization.

,SYNCHRES=DO_NOT_OVERRIDE

,SYNCHRES=SYSTEM

,SYNCHRES=YES

,SYNCHRES=NO

When RESLIST=YES and REQUEST=OBTAIN are specified, an optional parameter that specifies whether all requests specified in the resource table should issue a synchronous reserve. This overrides any SYNCHRES specified in the resource table. A synchronous reserve immediately reserves the volume instead of waiting for the first use. The default is SYNCHRES=DO_NOT_OVERRIDE.

,SYNCHRES=DO_NOT_OVERRIDE: Indicates that the SYNCHRES specified in the resource table should be used.
,SYNCHRES=SYSTEM: Indicates that the system default setting should be used.
,SYNCHRES=YES: Indicates to issue a synchronous reserve. In cases where the the hardware reserve is performed (it was not converted to a Global/Systems ENQ), the caller is ensured that the reserve I/O is complete when the request has successfully completed.
,SYNCHRES=NO: Indicates that a synchronous reserve should be avoided when possible. Some devices require that the reserve must be done synchronously regardless of this setting. If the reserve I/O is not done synchronously, the reserve is done when the first I/O is done to the device after the reserve request is issued. See z/OS MVS Planning: Global Resource Serialization for more information.

,TEST=NO

,TEST=YES

When REQUEST=OBTAIN is specified, an optional parameter. The default is TEST=NO.

,TEST=NO

Indicates that this is not a test request. The ENQ must be obtained.

,TEST=YES

Indicates that this is a test request. The ENQ must not be obtained. This parameter setting can be used to obtain information about how the given obtain request is processed and how a resource is currently held by the current task or a task specified by OWNINGTTOKEN.

Mutually exclusive with COND=NO.

For existing requests from the same task, which match the specified resource, the ENQToken of that request is returned.

See ISGQUERY SEARCH=BY_ENQTOKEN for information about outstanding ENQ requests.

The following return and reason codes can be used to determine if the resource is available and how it might be held by the OWNINGTTOKEN task:

ISGENQRc_ok
ISGENQRsn_NotImmediatelyAvailable
ISGENQRsn_TaskOwnsExclusive
ISGENQRsn_TaskOwnsShared
ISGENQRsn_TaskWaiting

,UCB@=ucb@

When RESERVEVOLUME=YES, RESLIST=NO and REQUEST=OBTAIN are specified, a required input parameter that contains the address of the UCB for the device to be reserved. For unauthorized callers, the UCB must be allocated to the job step before ISGENQ RESERVEVOLUME(YES) is issued.

Note: Authorized callers do not need to allocate the UCB to the job step before invoking ISGENQ, but the caller must serialize the UCB against dynamic I/O reconfiguration requests. The caller can accomplish this serialization by allocating or pinning the UCB. Such serialization ensures that a dynamic I/O reconfiguration request does not delete or reuse the UCB before the ISGENQ macro uses the address.

To code: Specify the RS-type address, or address in register (2)-(12), of a pointer field.

,UCB@=ucb@

,UCB@=DO_NOT_OVERRIDE

When RESLIST=YES and REQUEST=OBTAIN are specified, an optional input parameter that contains the address of the UCB@ for the device to be reserved for all resources in the resource table. This overrides any UCB addresses specified in the resource table. The default is DO_NOT_OVERRIDE.

To code: Specify the RS-type address, or address in register (2)-(12), of a pointer field.

,USERDATA=userdata

,USERDATA=NO_USERDATA

When TEST=NO and REQUEST=OBTAIN are specified, an optional input parameter that contains the userdata to be associated with this request. For information about using USERDATA as a filter, or making ISGQUERY return USERDATA for requests, see ISGQUERY — Global resource serialization query service.

Note that GRS has no interests in the contents of the USERDATA. Unlike the QNAME, RNAME, and SCOPE parameters, USERDATA has no meaning in the definition of the logically serialized resource identity. For example, exclusive requests with different user data and the same QNAME, RNAME, and SCOPE contend with each other.

This request requires a version 2 parameter list. The default is NO_USERDATA.

To code: Specify the RS-type address, or address in register (2)-(12), of a 32-character field.

,WAITTYPE=SUSPEND

,WAITTYPE=ECB

When CONTENTIONACT=WAIT, TEST=NO and REQUEST=OBTAIN are specified, an optional parameter that indicates the method by which the caller waits. The default is WAITTYPE=SUSPEND.

,WAITTYPE=SUSPEND

Indicates that the current task is suspended until the entire request is completed.

,WAITTYPE=ECB

Indicates that if contention for the ENQ resource exists or the device reserve is done synchronously (see ,SYNCHRES=SYSTEM), return to the caller, and post the ECB when the request is complete.

Mutually exclusive with COND=NO.

WAITTYPE=ECB in combination with setting a timer with ECB can be used to control the amount of time that you are willing to wait for either ENQ contention or a synchronous reserve to complete. If the request does not complete before the time expires you can do the following actions.

You can use the the ISGECA and ISGQUERY services to interrogate the overall state of the request and associated resource.
You can back out of the request using an ISGENQ REQUEST=RELEASE request."

ABEND codes

For REQUEST=OBTAIN and REQUEST=CHANGE requests the caller might encounter abend codes X'138', X'238', X'338', X'438', X'538', X'638', X'738', X'838', X'938'.

For REQUEST=RELEASE requests the caller might encounter abend codes X'130', X'230', X'330', X'430', X'530', X'630', X'730', X'830', X'930'.

For explanations and responses for these codes, see z/OS MVS System Codes.

Note that the ABEND reason codes correspond to the same reason codes listed in Table 1.

Return and reason codes

When the ISGENQ macro returns control to your program:

GPR 15 (and retcode, when you code RETCODE) contains a return code.
When the value in GPR 15 is not zero, GPR 0 (and rsncode, when you code RSNCODE) contains a reason code.

Macro ISGYCON provides equate symbols for the return and reason codes.

The following table identifies the hexadecimal return and reason codes and the equate symbol associated with each reason code. IBM support the xxxx value, where xxxx represent 4 hex digits. Note that when the xxxx value is 'E0F2' hexadecimal, it indicates a reason-code set by the ISGNQXITBATCH or ISGNQXITBATCHCND exits.

Table 1. Return and Reason Codes for the ISGENQ Macro
Return Code	Reason Code	Equate Symbol Meaning and Action
00	—	Equate Symbol: ISGENQRc_OK Meaning: ISGENQ request successful. Depending on the type of request, the ENQ is successfully obtained, changed to exclusive, or released. If RESLIST=YES is specified, all ENQ obtain, change, and release requests are successful. For REQUEST=OBTAIN, TEST=YES, the resource is immediately available. Action: None required.
04	—	Equate Symbol: ISGENQRc_Warn Meaning: Warning Action: Refer to action under the individual reason code.
04	xxxx0401	Equate Symbol: ISGENQRsn_NonZeroReturnCodes Meaning: A non-zero return code was issued for one or more entries in a RESLIST=YES request. The return table has the return and reason codes for each of the requests in the list. Action: See the return and reason codes returned in the RETURNTABLE.
04	xxxx0402	Equate Symbol: ISGENQRsn_RequestNotProcessed Meaning: For RESLIST=YES requests. One of the other requests in the RESTABLE failed such that this request was prevented from being processed. Note that requests in a RESTABLE are not necessarily processed in the order they appear in the RESTABLE. Note: This reason code returned only in the RETURNTABLE, not through the RSNCODE keyword. Action: Check the return and reason codes for all other requests in the RETURNTABLE to identify the problem.
04	xxxx0403	Equate Symbol: ISGENQRsn_ECBWillBePosted Meaning: For REQUEST=OBTAIN CONTENTIONACT=WAIT WAITTYPE=ECB, the OBTAIN request was successful, but the ENQ resource was not immediately available or the reserve I/O needed to be done synchronously (SYNCHRES). The ECB is posted when all requested resources are owned by the specified task, or when an error has occurred. The ENQToken for the request has been returned. Action: Wait on the ECB and check the return code in the ECB before using the requested resources.
04	xxxx0404	Equate Symbol: ISGENQRsn_NotImmediatelyAvailable Meaning: The ENQ of the resource was not immediately available. For REQUEST=OBTAIN CONTENTIONACT=FAIL, the requested resource is not obtained. For REQUEST=OBTAIN TEST=YES, the holder is a task other than OWNINGTTOKEN. Action: No action required.
04	xxxx0405	Equate Symbol: ISGENQRsn_TaskOwnsExclusive Meaning: For REQUEST=OBTAIN, including TEST=YES, the given task specified by OWNINGTTOKEN already owns the specified resource exclusively. The ENQToken for the owning request has been returned. Action: No action required.
04	xxxx0406	Equate Symbol: ISGENQRsn_TaskOwnsShared Meaning: For a REQUEST=OBTAIN, including TEST=YES, the given task specified by OWNINGTTOKEN already owns the specified resource shared. The ENQToken for the owning request has been returned. Action: No action required.
04	xxxx0407	Equate Symbol: ISGENQRsn_TaskWaiting Meaning: For a REQUEST=OBTAIN, including TEST=YES, the given task specified by OWNINGTTOKEN is already waiting for control of the specified resource. The ENQToken for the waiting request has been returned. Action: No action required.
04	xxxx0409	Equate Symbol: ISGENQRsn_OtherSharedOwners Meaning: For REQUEST=CHANGE. The control cannot be changed to exclusive. There are other shared owners of the resource. Action: No action required.
04	xxxx040A	Equate Symbol: ISGENQRsn_TaskDoesNotOwn Meaning: For REQUEST=CHANGE. The control cannot be changed to exclusive. The task does not yet own the resource. Action: No action required.
04	xxxx040B	Equate Symbol: ISGENQRsn_TaskSuspendedForResource Meaning: For REQUEST=RELEASE. The task that requested the ENQ obtain has not yet been assigned control of the resource The task continues waiting and the resource is not released. (This reason code might result in an exit routine, which received control because of an interruption, issued a RELEASE reqquest on behalf of the task.) Action: Correct the program so that the ISGENQ RELEASE request is issued only after the ISGENQ OBTAIN request has returned to the task. If possible, avoid issuing the RELEASE request in the exit routine.
04	xxxx040D	Equate Symbol: ISGENQRsn_UnprotectedQName Meaning: For REQUEST=OBTAIN. An authorized caller requested an ENQ with an unauthorized QNAME. For TEST=NO,COND=YES, the OBTAIN request completed successfully, an unauthorized caller under the same owning task might release the ENQ. The ENQToken has been returned. For TEST=NO, COND=NO, the requester was abended with a X'438' abend. The request might not have completed successfully For TEST=YES requests, the resource is currently available. Action: No action required. If the ENQ needs to be protected from unauthorized RELEASE requests or from unauthorized callers obtaining an ENQ to block this request, specifiy one of the authorized QNAMEs for the resource.
04	xxxx040E	Equate Symbol: ISGENQRsn_UnprotectedExitQNAME Meaning: For REQUEST=OBTAIN. An authorized caller requested an ENQ with a QNAME that a dynamic exit changed to an unauthorized QNAME. For TEST=NO, the OBTAIN request completed successfully, an unauthorized caller under the same owning task might release the ENQ. The ENQToken has been returned. For TEST=YES requests, the resource is currently available but the QNAME was changed by a dynamic exit to an unprotected QNAME. Action: No action required. Contact the system programmer, if the ENQ needs to be protected from unauthorized RELEASE requests or from unauthorized callers obtaining an ENQ to block this request. The system programmer should check the ISGNQXIT installation exits to ensure that they are not coded to specify an unauthorized QNAME for authorized requests.
04	xxxx040F	Equate Symbol: ISGENQRsn_ECBAtleastOneRequestFailed Meaning: For REQUEST=OBTAIN RESLIST=Yes with ECB@, at least one request failed to be processed. Some requests might have been processed unsuccessfully. The system might not backout any successfully processed requests. Note: This reason code is returned in a posted ECB, not through the RSNCODE or RETURNTABLE keywords. Action: The user should issue an ISGQUERY on the ENQTOKENs to see if they were obtained and take appropriate action. Alternately, the user can release all the ENQs with a ISGENQ REQUEST=RELEASE with ENQTOKENTBL and reissue the ISGENQ OBTAIN request.
08	—	Equate Symbol: ISGENQRc_ParmError Meaning: ISGENQ request specified parameters in error. Action: Refer to action under the individual reason code.
08	xxxx0801	Equate Symbol: ISGENQRsn_BadPlistAddress Meaning: Unable to access parameter list. Action: Check that the entire parameter list is addressable. If in AR-mode, check that the ALET of the parameter list is correct. Note that if this macro is issued in AR-mode, SYSSTATE ASCENV=AR must be issued before this macro. Ensure that the storage is in the same key as the caller.
08	xxxx0802	Equate Symbol: ISGENQRsn_BadPlistALET Meaning: Bad parameter list ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable Unit Access List (DU-AL), nor a valid entry for a common area data space. Action: Ensure that the ALET of the parameter list is valid. Its access register may not have been set up properly.
08	xxxx0803	Equate Symbol: ISGENQRsn_BadPlistVersion Meaning: Bad parameter list version number. The service level of GRS on which the caller is running does not support this version of the ISGENQ service, or the ISGENQ parameter list version is lower than the minimum required for parameters that were specified. Action: Check for possible storage overlay of the parameter list. Retry the request with the correct version number. Verify that your program was assembled with the correct macro library for the release of MVS on which your program is running.
08	xxxx0804	Equate Symbol: ISGENQRsn_ReservedFieldNotNull Meaning: A reserved field in the parameter list is non-zero. Action: Check for possible storage overlay of the parameter list.
08	xxxx0805	Equate Symbol: ISGENQRsn_MutuallyExclusive Meaning: Mutually exclusive keywords were specified. Action: Check for a possible storage overlay of the parameter list.
08	xxxx0806	Equate Symbol: ISGENQRsn_BadRequest Meaning: Bad REQUEST parameter. Action: IBM suggests that the ISGENQ macro is used when invoking the ISGENQ service.
08	xxxx0807	Equate Symbol: ISGENQRsn_BadContentionAct Meaning: Bad CONTENTIONACT parameter. Action: Check for possible storage overlay of the parameter list.
08	xxxx0808	Equate Symbol: ISGENQRsn_BadOwningTToken Meaning: The specified TToken does not represent a valid task. Action: Ensure that the task token (TToken) represents a valid task.
08	xxxx0809	Equate Symbol: ISGENQRsn_BadAnsAreaAddress Meaning: Unable to access the answer area. Action: Ensure that the entire answer area is addressable. If in AR-mode, this field is accessed via its address and ALET, check that both these values are correct. Check that the specified answer area length is correct. Ensure that the storage is in the same key as the caller.
08	xxxx080A	Equate Symbol: ISGENQRsn_BadAnsAreaALET Meaning: Bad answer area ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable Unit Access List (DU-AL), nor a valid entry for a common area data space. Action: Ensure that the ALET of the answer area is valid. Its access register may not have been set up properly.
08	xxxx080B	Equate Symbol: ISGENQRsn_AnsLenTooSmall Meaning: The specified answer area length was too small to return the requested information. Action: Invoke ISGENQ again with a larger answer area. The answer area length needed is dependent on the number of resource requests specified in NUMRES.
08	xxxx080C	Equate Symbol: ISGENQRsn_BadRNameAddress Meaning: Unable to access the RNAME. Action: Ensure that the entire RNAME is addressable. If in AR-mode, this field is accessed via its address and ALET, check that both these values are correct. Check that the specified RNAME length is correct. Ensure that the storage is in the same key as the caller.
08	xxxx080D	Equate Symbol: ISGENQRsn_BadRnameALET Meaning: Bad RNAME ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable Unit Access List (DU-AL), nor a valid entry for a common area data space. Action: Ensure that the ALET of the RNAME is valid. Its access register may not have been set up properly.
08	xxxx080E	Equate Symbol: ISGENQRsn_BadRNameLen Meaning: The RNAME length specified is not valid. Action: Ensure the RNAME length field contains a number in the range of 1-255.
08	xxxx080F	Equate Symbol: ISGENQRsn_BadScope Meaning: Bad SCOPE keyword parameter. Action: Check for possible storage overlay of the parameter list.
08	xxxx0810	Equate Symbol: ISGENQRsn_BadUCB@ Meaning: The storage specified by the UCB@ keyword does not map to a valid UCB. Action: Ensure that the UCB@ points to a valid UCB.
08	xxxx0811	Equate Symbol: ISGENQRsn_BadCond Meaning: Bad COND keyword parameter. Action: IBM suggests that the ISGENQ macro is used when invoking the ISGENQ service.
08	xxxx0812	Equate Symbol: ISGENQRsn_BadSynchRes Meaning: Bad SYNCHRES keyword parameter. Action: Check for possible storage overlay of the parameter list.
08	xxxx0813	Equate Symbol: ISGENQRsn_BadENQTokenAddress Meaning: Unable to access the ENQToken. Action: Ensure that the entire ENQToken is addressable. If in AR-mode, this field is accessed via its address and ALET, check that both these values are correct. Ensure that the storage is in the same key as the caller. Note: The ISGENQ request might not have completed.
08	xxxx0814	Equate Symbol: ISGENQRsn_BadENQTokenALET Meaning: Bad ENQToken ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable Unit Access List (DU-AL), nor a valid entry for a common area data space. Action: Ensure that the ALET of the ENQToken is valid. Its access register may not have been set up properly. Note: The ISGENQ request might not have completed.
08	xxxx0815	Equate Symbol: ISGENQRsn_BadENQToken Meaning: For REQUEST=RELEASE or REQUEST=CHANGE, the specified ENQToken does not represent an ENQ for the given task (current task or specified by OWNINGTTOKEN). Action: Ensure that the specified ENQToken is from a previous request for the given task, that has not been subsequently released.
08	xxxx0816	Equate Symbol: ISGENQRsn_BadNumRes Meaning: The NUMRES specified is not valid. Action: Ensure the NUMRES field contains a number in the range of 1-65535 (2?6-1)
08	xxxx0817	Equate Symbol: ISGENQRsn_BadResTableAddress Meaning: Unable to access the resource table. Action: Ensure that the entire resource table is addressable. If in AR-mode, this field is accessed via its address and ALET, check that both these values are correct. Check that the resource table length is correct. Ensure that the storage is in the same key as the caller.
08	xxxx0818	Equate Symbol: ISGENQRsn_BadResTableALET Meaning: Bad resource table ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable Unit Access List (DU-AL), nor a valid entry for a common area data space. Action: Ensure that the ALET of the resource table is valid. Its access register may not have been set up properly.
08	xxxx0819	Equate Symbol: ISGENQRsn_BadResTable Meaning: The RESTABLE specified is not valid. Action: Ensure that the resource table does not specify mutually exclusive parameters.
08	xxxx081A	Equate Symbol: ISGENQRsn_BadENQTokenTblAddress Meaning: Unable to access the ENQToken table. Action: Ensure that the entire ENQToken table is addressable. If in AR-mode, this field is accessed via its address and ALET, check that both these values are correct. Check that the ENQToken table length is correct. Ensure that the storage is in the same key as the caller. Note: The ISGENQ request might not have completed.
08	xxxx081B	Equate Symbol: ISGENQRsn_BadENQTokenTblALET Meaning: Bad ENQToken table ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable Unit Access List (DU-AL), nor a valid entry for a common area data space. Action: Ensure that the ALET of the ENQToken table is valid. Its access register may not have been set up properly. Note: The ISGENQ request might not have completed.
08	xxxx081C	Equate Symbol: ISGENQRsn_BadReturnTableAddress Meaning: Unable to access the return table. Action: Ensure that the entire return table is addressable. If in AR-mode, this field is accessed via its address and ALET, check that both these values are correct. Check that the return table length is correct. Ensure that the storage is in the same key as the caller. Note: The ISGENQ request might not have completed.
08	xxxx081D	Equate Symbol: ISGENQRsn_BadReturnTableALET Meaning: Bad return table ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable Unit Access List (DU-AL), nor a valid entry for a common area data space. Action: Ensure that the ALET of the return table is valid. Its access register may not have been set up properly. Note: The ISGENQ request might not have completed.
08	xxxx081E	Equate Symbol: ISGENQRsn_NotAuthorizedForQName Meaning: For REQUEST=OBTAIN. An unauthorized caller specified an authorized QNAME. Action: Unauthorized callers must avoid specifying the authorized QNAMEs listed in the ISGENQ macro prologue.
08	xxxx081F	Equate Symbol: ISGENQRsn_NotAuthorizedForExitQname Meaning: For REQUEST=OBTAIN. An ISGNQXIT exit specified an authorized QNAME for an unauthorized OBTAIN request. Action: Contact your system programmer. The system programmer should check the ISGNQXIT installation exits to ensure they are not coded to specify an authorized QNAME for unauthorized requests.
08	xxxx0821	Equate Symbol: ISGENQRsn_NotAuthorizedForOWNINGTTOKEN Meaning: An unauthorized caller specified OWNINGTTOKEN. Action: Unauthorized callers should avoid specifying OWNINGTTOKEN.
08	xxxx0822	Equate Symbol: ISGENQRsn_BadUserDataAddress Meaning: Unable to access the USERDATA. Action: Ensure that the entire USERDATA is addressable. If in AR-mode, this field is accessed via its address and ALET, check that both these values are correct. Ensure that the storage is in the same key as the caller.
08	xxxx0823	Equate Symbol: ISGENQRsn_BadUserDataAlet Meaning: Bad UserData ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable Unit Access List (DU-AL), nor a valid entry for a common area data space. Action: Ensure that the ALET of the userdata is valid. Its access register may not have been set up properly.
08	xxxx0824	Equate Symbol: ISGENQRsn_DeviceNotAllocated Meaning: For REQUEST=OBTAIN with RESERVEVOLUME=YES. An unauthorized caller specified a device that is not allocated to the requesting task. Action: Unauthorized callers should allocate the UCB to the job step before ISGENQ RESERVEVOLUME(YES) is issued.
08	xxxx0825	Equate Symbol: ISGENQRsn_ExitDeviceNotAllocated Meaning: For REQUEST=OBTAIN. An ISGNQXIT exit specified a UCB for a device that is not allocated to the requesting, unauthorized task. Action: Contact your system programmer. The system programmer should ensure that the installation exits do not modify the UCB to specify one that is not allocated to an unauthorized requests.
08	xxxx0826	Equate Symbol: ISGENQRsn_BadControl Meaning: Bad CONTROL keyword parameter. Action: Check for possible storage overlay of the parameter list.
08	xxxx0827	Equate Symbol: ISGENQRsn_BadExitUCB@ Meaning: The storage pointed to by the UCB address changed by a dynamic exit does not map to a valid UCB. Action: Contact your system programmer. The system programmer should ensure that the installation exits do not specify a bad UCB address.
08	xxxx0828	Equate Symbol: ISGENQRsn_NotAuthorizedForENQMAX Meaning: For REQUEST=OBTAIN, an unauthorized caller specified ENQMAX=NO. Action: Unauthorized callers should avoid specifying ENQMAX=NO.
0C	—	Equate Symbol: ISGENQRc_EnvError Meaning: ISGENQ request has an environment error. Action: Refer to action under the individual reason code.
0C	xxxx0C01	Equate Symbol: ISGENQRsn_RequestLimitExceeded Meaning: For REQUEST=OBTAIN, 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. For more information on concurrent count limits and how the system can be tuned when necessary, see z/OS MVS Planning: Global Resource Serialization.
0C	xxxx0C05	Equate Symbol: ISGENQRsn_AbendInExit Meaning: One of the GRS dynamic exits abended. Action: Retry the request one or more times. Contact your system programmer.
0C	xxxx0C0A	Equate Symbol: ISGENQRsn_TaskEnding Meaning: The task represented by the specified TToken was ending. The point was reached in task termination after which no ENQs can be obtained. Action: Determine why the task identified by the TToken was ending. Correct that error and retry the request.
0C	xxxx0C0B	Equate Symbol: ISGENQRsn_FRRHeld Meaning: The caller issued ISGENQ when an FRR was established. Action: Avoid issuing ISGENQ when using functional recovery routines.
0C	xxxx0C0C	Equate Symbol: ISGENQRsn_LockHeld Meaning: A lock was held upon entry. No locks can be held when calling ISGENQ. Action: Avoid using ISGENQ when locks are held.
0C	xxxx0C0D	Equate Symbol: ISGENQRsn_SrbMode Meaning: ISGENQ was issued while in SRB mode. Action: Avoid using ISGENQ in SRB mode.
0C	xxxx0C0E	Equate Symbol: ISGENQRsn_NotEnabled Meaning: ISGENQ was issued while not enabled. Action: Avoid using ISGENQ when not enabled.
0C	xxxx0C0F	Equate Symbol: ISGENQRsn_MasidTarget Meaning: The requester to be released is still the target of an ENQ with the MASID and MTCB options specified. The release does complete and the resource might be damaged. Action: The task that issued the ENQ macro instruction with MASID and MTCB should issue the DEQ before this requester does so.
0C	xxxx0C10	Equate Symbol: ISGENQRsn_UnsupportedMode. Meaning: The current GRS mode does not support this specific request. Action: Defer the usage of this particular type of request.
0C	xxxx0C11	Equate Symbol: ISGENQRsn_MasidNotSupported. Meaning: The resource that was the target of this REQUEST=CHANGE,CONTROL=SHARED request currently or at one time contained MASID users. REQUEST=CHANGE,CONTROL=SHARED is not supported for resources that involve MASID requestors. Action: Do not use REQUEST=CHANGE,CONTROL=SHARED on resources that involve MASID requestors.
10	—	Equate Symbol: ISGENQRc_CompError Meaning: Component Error. Action: Contact the IBM Support Center. Reason code that are not defined below contain internal diagnostic information.
10	xxxx1002	Equate Symbol: ISGENQRsn_CannotObtainHomeStorage Meaning: ISGENQ processing could not obtain storage in the home address space.
10	xxxx1003	Equate Symbol: ISGENQRsn_CannotObtainCommonStorage Meaning: ISGENQ processing could not obtain storage in the common area.
10	xxxx1004	Equate Symbol: ISGENQRsn_CannotObtainPrimaryAlet Meaning: ISGENQ processing could not obtain the ALET of the caller's primary address space.
10	xxxx1006	Equate Symbol: ISGENQRsn_SynchResFlushFailed Meaning: For REQUEST=OBTAIN, a synchronous reserve failed device state transition flushing.
10	xxxx1007	Equate Symbol: ISGENQRsn_ReserveStartFailed Meaning: For REQUEST=OBTAIN, reserve start processing failed.
10	xxxx1008	Equate Symbol: ISGENQRsn_ReserveCountOverflow Meaning: For REQUEST=OBTAIN, reserve processing detected an overflow when updating the reserve count.
10	xxxx1009	Equate Symbol: ISGENQRsn_CannotObtainDSQE Meaning: ISGENQ processing could not obtain a DSQE to suspend a request during an RNL change.
10	xxxx100A	Equate Symbol: ISGENQRsn_ReserveDoneFailed Meaning: For REQUEST=OBTAIN, synchronous reserve back end processing has failed; therefore, the reserve was never completed.
10	xxxx100B	Equate Symbol: ISGENQRsn_CannotObtainPrimaryStorage Meaning: ENQ/DEQ processing could not obtain storage in the primary address space.

Examples

Use these examples as a guide.

* **********************************************************************
*  Request exclusive control of a single resource                       
* **********************************************************************
                                                                        
         ISGENQ REQUEST=OBTAIN,QNAME=QNAM1,RNAME=RNAM1,RNAMELEN=RLEN1,  X
               SCOPE=SYSTEMS,CONTROL=EXCLUSIVE,ENQTOKEN=ENQT1           
                                                                        
* **********************************************************************
*  Release control of a single resource                                 
* **********************************************************************

         ISGENQ REQUEST=RELEASE,ENQTOKEN=ENQT1,COND=YES,                X
               RETCODE=(3),RSNCODE=(2)                                  

* ***********************************************************************
*  Conditionally request shared control of 3 resources                  
* ***********************************************************************
                                                                        
         ISGENQ REQUEST=OBTAIN,RESLIST=YES,NUMRES=3,RESTABLE=RSTBL,     X
               ENQTOKENTBL=ETTBL,RETURNTABLE=RTTBL,COND=YES,            X
               RETCODE=(3),RSNCODE=(2),PLISTVER=1                       
                                                                        
QNAM1    DC    CL8'QNAME1'                                              
RNAM1    DC    CL10'RNAME1'                                             
RLEN1    DC    AL1(L'RNAM1)                                             
RNAM2    DC    CL12'RNAME2'                                             
RNAM3    DC    CL14'RNAME3'                                             
         DS    0D                                                       
RSTBL    DS    0CL(3*ISGYENQRES_LEN)                                    
ENTRY1   DC    CL8'QNAME1'          QNAME                               
         DC    F'0'                 FIRST WORD OF RNAME ADDR            
         DC    A(RNAM1)             RNAME ADDR31                        
         DC    F'0'                 RNAME ALET                          
         DC    A(0)                 UCB@                                
         DC    AL1(L'RNAM1)         RNAME LENGTH                        
         DC    AL1(ISGYENQ_kSTEP)                                       
         DC    AL1(ISGYENQ_kCONTROLSHARED)                              
         DC    XL1'00'              FLAGS                               
         DC    XL4'00'              RESERVED                            
ENTRY2   DC    CL8'QNAME2'          QNAME                               
         DC    F'0'                 FIRST WORD OF RNAME ADDR            
         DC    A(RNAM2)             RNAME ADDR31                        
         DC    F'0'                 RNAME ALET                          
         DC    A(0)                 UCB@                                
         DC    AL1(L'RNAM2)         RNAME LENGTH                        
         DC    AL1(ISGYENQ_kSYSTEM)                                     
         DC    AL1(ISGYENQ_kCONTROLSHARED)                              
         DC    XL1'00'              FLAGS                               
         DC    XL4'00'              RESERVED                            
ENTRY3   DC    CL8'QNAME3'          QNAME                               
         DC    F'0'                 FIRST WORD OF RNAME ADDR            
         DC    A(RNAM3)             RNAME ADDR31                        
         DC    F'0'                 RNAME ALET                          
         DC    A(0)                 UCB@                                
         DC    AL1(L'RNAM3)         RNAME LENGTH                        
         DC    AL1(ISGYENQ_kSYSTEMS)                                    
         DC    AL1(ISGYENQ_kCONTROLSHARED)                              
         DC    XL1'00'              FLAGS                               
         DC    XL4'00'              RESERVED                            
                                                                        
DYNAREA  DSECT                                                          
ENQT1    DS    CL(ISGYENQTOKEN_LEN)                                     
ETTBL    DS    CL(3*ISGYENQTOKEN_LEN)                                   
RTTBL    DS    CL(3*ISGYENQRETURN_LEN)                                  
* ********************************************************************** 
* Request exclusive control of a single resource with userdata
* ********************************************************************** 
         ISGENQ REQUEST=OBTAIN,QNAME=QNAM1,RNAME=RNAM1,RNAMELEN=RLEN1, X 
               SCOPE=SYSTEMS,CONTROL=EXCLUSIVE,ENQTOKEN=ENQT1,         X
               USERDATA=UDATA1 

UDATA1  DC    CL32'MY USERDATA'

For more information on global resource serialization, see z/OS MVS Planning: Global Resource Serialization.