ISGNQXITBATCH— ISGENQ / ENQ / DEQ Batched Exit ISGNQXITBATCHCND — ISGENQ / ENQ / DEQ Conditional Batch Processing Exit

Both the ISGNQXITBATCH exit and the ISGNQXITBATCHCND exit can interrogate and alter an entire ENQ, DEQ, ISGENQ, or RESERVE request. In most cases, the ISGNQXITBATCH exit and the ISGNQXITBATCHCND exit can be used interchangeably.

The ISGNQXITBATCH or ISGNQXITBATCHCND exit is invoked after all of the resources in the request have been passed to the ISGNQXIT exit point, and the RNLs have been processed for each resource in the request. Only SCOPE=SYSTEM and SCOPE=SYSTEMS resources are passed to the ISGNQXITBATCH or ISGNQXITBATCHCND exit; STEP requests are not passed to the ISGNQXITBATCH or ISGNQXITBATCHCND exit. See ENQ/DEQ Exits Installation in z/OS MVS Planning: Global Resource Serialization for the installation flow through ENQ/DEQ exits.

The ISGNQXITBATCH and ISGNQXITBATCHCND exits can:

Set a return code for each resource in a conditional request. For example, make the request not happen.
Convert a RESERVE to an ENQ.
Set an ABEND for the request. For example, make the entire request not happen.

The parameter list passed to ISGNQXITBATCH (or ISGNQXITBATCHCND) exit is mapped by ISGYNQBP (NQBP). See ISGYNQBP macro in z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for more information.

An ISGNQXITBATCH (or ISGNQXITBATCHCND) exit routine can set its own non-zero return code for each resource in the request, overriding ENQ or RESERVE functionality, for all:

ENQ requests that specify a RET value or an ECB value
Conditional ISGENQ requests

In addition, the ISGNQXITBATCH (or the ISGNQXITBATCHCND) exit routine can optionally set its own non-zero reason code that accompanies the non-zero return code for conditional ISGENQ requests.

For all requests (ENQ, DEQ, ISGENQ, and RESERVE), an ISGNQXITBATCH (or ISGNQXITBATCHCND) exit routine can set a one-byte ABEND code and a half-word reason code for the request. The one-byte ABEND code is used to generate the ABEND code. For example, if the exit routine sets the ABEND code to 5 for an ENQ request, a X'538' ABEND will be generated by ENQ processing.

When you use the ISGNQXITBATCH and ISGNQXITBATCHCND exits, be aware of the following notes.

Note:

ISGNQXITBATCH and ISGNQXITBATCHCND exits are only used to interrogate and alter an entire ENQ, DEQ, ISGENQ, or RESERVE request. For any other changes, you must use the ISGNQXIT exit or the ISGNQXITFAST exit.
If your installation is using an OEM serialization product to replace global resource serialization, do not specify that the exit is to be called last, either with the LAST parameter of the SETPROG command or the POS=LAST parameter of the CSVDYNEX macro, when installing the exit.
If all ENQ, DEQ, ISGENQ, and RESERVE requests need to be processed, use the ISGNQXITBATCH exit; if only a subset of requests need to be processed, use the combination of the ISGNQXITPREBATCH and ISGNQXITBATCHCND exit for better performance. See ISGNQXITPREBATCH — ISGENQ / ENQ / DEQ Batch Preprocessing Exit for more information on the usage of ISGNQXITPREBATCH and ISGNQXITBATCHCND.
When both the ISGNQXITBATCH and ISGNQXITBATCHCND exits are installed, ISGNQXITBATCHCND is called second. Therefore, any actions requested by the ISGNQXITBATCHCND exits override any requests made by the ISGNQXITBATCH exits.

Replacing the Exit Routine

Unlike RNL changes, GRS does not know how an exit alters the resource identity of a request. Therefore, to maintain data integrity, do not make an exit change that alters the resource identity of any outstanding or in-flight ENQ or DEQ requests. The resource identity consists of the QNAME, RNAME, SCOPE, and hardware reserve status. When you make exit changes, first stop the programs that are currently using the resource, and do not resume the programs until all the exit changes in the GRS complex have completed.

For information regarding dynamic exit routine replacement, see Replacing a Dynamic Exit Routine.

Exit Routine Environment

ISGNQXITBATCH (or ISGNQXITBATCHCND) exit receives control in the following environment:

Task mode (running under the requester's task).
Enabled for interrupts.
In supervisor state with PSW key 0.
In primary ASC mode.
In cross-memory mode with H=Caller's home address space, S=Any space, and P=Global Resource Serialization’s address space.
In AMODE 31 and RMODE ANY.
With no locks held.
An EUT FRR is held when the exit routine is called.

The routine can be invoked in the cross-memory mode with an EUT FRR established that must remain in effect. Therefore, system services or instructions that do not allow FRRs to be active or cause FRRs to be removed cannot be used. This includes the SVC instruction.

Exit Recovery is as follows.

If an error occurs, the ISGNQXITBATCH (or ISGNQXITBATCHCND) exit should provide its own EUT FRR recovery routine.
An EUT FRR recovery is the only recovery type that can be used. ESTAE-like recovery can be established but it does not receive control because an EUT FRR is established on entry.
If no recovery exists, or the recovery continues with termination, GRS fails the request and continues processing. CSVDYNEX rules for the exit are used to determine whether the exit should be removed.
The unplanned removal of an exit can result in serialization changes. Therefore, it is important to provide recovery and to understand how CSVDYNEX determines when to remove an abend exit.
For more information about CSVDYNEX, see z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN.

Exit Routine Processing

The ISGNQXITBATCH (or ISGNQXITBATCHCND) exit point allows an exit routine to interrogate an ENQ, DEQ, ISGENQ, or RESERVE request as a single unit, rather that on an individual resource basis, as ISGNQXIT. The exit routine is passed a NQBP (mapped by ISGYNQBP) which contains information about the request.

The exit routine can affect processing in the following ways:

Set an ABEND code for the entire request. The requestor is ABENDed with this ABEND code, prepended to the appropriate SVC number. For example, if the exit indicated to use ABEND code 5 on an ENQ request, the caller would get ABENDed with a S538 ABEND code.
Set the return code for a conditional request. If the request specified RET=TEST, RET=HAVE, USE, CHNG, or ISGENQ COND=YES the exit routine can prevent normal ENQ/DEQ processing by indicating the return code to pass back to the caller. If this return code is set, the system will do no further processing on that resource. The list of acceptable return codes is as follows:
ENQ/RESERVE:
- RET=TEST RC=X'00',X'04',X'08',X'14',X'20'
- RET=USE RC=X'00',X'04',X'08',X'14',X'18'
- RET=CHNG RC=X'00',X'04',X'08',X'14'
- RET=HAVE RC=X'00',X'08',X'14',X'18'X'28',X'44'
- RET=ECB RC=X'00',X'08',X'14',X'18'X'28',X'44'
DEQ:
- RET=HAVE RC=X'00',X'04',X'08'
ISGENQ:
- RC=4 RSN=0402,0404,0405,0406,0407,0409,040A,040B
- RC=8 RSN=0815
- RC=C RSN=0C05
- RC=10 RSN=FFyy where yy are diagnostic bits set by the exit
Failure to use an acceptable return code may result in unexpected results for the request. Example of failure case:

On an ENQ RET=HAVE, when an exit sets a resource return code to X'20' GRS will not process the request. Instead GRS will pass the X'20' back to the ENQ caller. The ENQ caller will assume they have control of the resource because the return code X'20' indicates so. But GRS did not process the request so when the corresponding DEQ is issued for the resource, GRS will not find the resource on its queues, and therefore issue an ABEND130.
If the ISGNQXITBATCH (or ISGNQXITBATCHCND) exit is driven by an ISGENQ COND=YES request, and ISGNQXITBATCH (or ISGNQXITBATCHCND) specifies a return AND reason code, only the lower two bytes of the reason code will be set; the upper two bytes are reserved for system use.
Convert a RESERVE to an ENQ.

Programming Considerations

Observe the following conventions when you code a Batch ENQ exit routine. If you do not want to get control for all request instances but only for particular requests, the combined use of the ISGNQXITPREBATCH and ISGNQXITBATCHCND provides better performance over the ISGNQXITBATCH exit. See ISGNQXITPREBATCH — ISGENQ / ENQ / DEQ Batch Preprocessing Exit for more information.

Every exit routine must be reentrant.
Because the exit is called for every ENQ, DEQ, ISGENQ, and RESERVE request, an increased path length increases processor utilization and can degrade performance.
Do not code the exit routine to issue the WAIT macro or call a service, such as WTOR, that issues a WAIT.
Do not code the exit routine to issue another ENQ, DEQ, ISGENQ, or RESERVE macro.

Entry Specifications

The system passes a Batch Exit parameter list (NQBP) to the exit routine. The NQBP contains a header section describing the request and an entry (NQBPRSC) for each resource in the request.

Registers at Entry: The contents of the registers on entry to the exit are as follows.

Register: Contents
0: Not applicable
1: Address of the exit parameter list (ISGYNQBP)
2-12: Not applicable
13: Address of a 72-byte save area
14: Return address
15: Entry point address of ISGNQXITBATCH (or ISGNQXITBATCHCND)

Parameter List Contents: Register 1 contains the address of the exit parameter (NQBP) that is mapped by macro ISGYNQBP. Refer to z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for the mapping of the ISGYNQBP data area.

Return Specifications

At the completion of ISGNQXITBATCH (or ISGNQXITBATCHCND) processing, ISGYNQBP can indicate that an ABEND code or return code has been set, or that a RESERVE has been converted to an ENQ.

Registers at Exit: Upon return from the exit processing, the register contents must be as follows.

Register: Contents
0-14: Restored to contents on entry
15: 0