ISGNQXITPREBATCH — ISGENQ / ENQ / DEQ Batch Preprocessing Exit

ISGNQXITPREBATCH provides the ability to reduce CPU consumption for ENQ, DEQ, ISGENQ or RESERVE requests that need to be processed by the ISGNQXITBATCH and ISGNQXITQUEUED1 exit points. The system calls the ISGNQXITPREBATCH exit point once for each ENQ, DEQ, ISGENQ or RESERVE resource with SCOPE=SYSTEM or SCOPE=SYSTEMS. If any of the ISGNQXITPREBATCH exit routines indicate that the resource should be processed by the ISGNQXITBATCHCND exit, then all of the resources in the current request will be presented to the ISGNQXITBATCHCND exit. Any ENQ or RESERVE request presented to the ISGNQXITBATCHCND exit will also be processed by the ISGNQXITQUEUED1 exit. See ENQ/DEQ Exits Installation in z/OS MVS Planning: Global Resource Serialization for the installation flow through ENQ/DEQ exits.

The ISGNQXITPREBATCH exit point also provides the ability to control future calls to this exit point. If the set of ISGNQXITPREBATCH exit routines indicates that this exit should no longer be called for a particular resource QNAME and scope, an entry for that QNAME is added to the GRS Exit Cache. Before calling the ISGNQXITPREBATCH exit point, GRS queries the GRS Exit Cache. If a matching entry is found and the entry indicates to NOT call the ISGNQXITPREBATCH exit point, this exit can be bypassed. Filtering the GRS Exit Cache is based on the QNAME, the original scope, the final scope, the original RESERVE state, and the final RESERVE state.

To restore processing of a resource through the ISGNQXITPREBATCH exit, the GRS Exit Cache must be cleared. For more information, see ISGGCECR, ClearCache call in z/OS MVS Programming: Callable Services for High-Level Languages.

This exit is invoked under the caller's unit of work on the system where the caller is running. For global resource requests, the exit is invoked only on the system where the request is made.

Note:

The ISGNQXITBATCH exit is not affected by the ISGNQXITPREBATCH exit.
After a call to ISGGCECR, the ISGNQXITPREBATCH exit can called again for all resources.
If an error occurs in the GRS Exit Cache, the cache will be disabled and all resources will again be processed by the ISGNQXITPREBATCH. You must do the IPL again to restore cache processing.

Note:

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

ISGNQXITPREBATCH 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 or with the local and CMSEQDQ locks held.
An FRR is held when locks are held, otherwise an ARR is in effect.

The routine can be invoked with an 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 ISGNQXITPREBATCH exit routine should provide its own recovery routine.
Exclusive use of EUT FRR recovery is the suggested recovery to be used because it can be used in all possible entry environments. ESTAE-like recovery is a worse performer and can be used only when locks are not held on entry. 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 ISGNQXITPREBATCH exit routine is invoked for every ENQ, DEQ, ISGENQ or RESERVE SCOPE=SYSTEM or SCOPE=SYSTEMS request issued for a resource. If any exit routines are defined to the dynamic exits facility, those routines are invoked after Resource Names List (RNL) processing.

By updating and using information in the parameter list, the exit routine indicates whether the ISGNQXITBATCHCND exit needs to be invoked or if the ISGNQXITPREBATCH exit will be called again for a resource.

Programming Considerations

Observe the following conventions when coding a Batch Preprocessing exit routine:

Every exit routine must be reentrant.
You should be aware while coding the exit routine, that 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 the NQPB parameter list to the exit routine.

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 (NQPB)
2-12: Not applicable
13: Address of a 72-byte save area
14: Return address
15: Entry point address of ISGNQXITPREBATCH

Parameter List Contents: Register 1 contains the address of the exit parameter (NQPB) that is mapped by macro ISGYNQPB. 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 ISGYNQPB data area.

Return Specifications

The pre-batch installation exit sets the appropriate request flag in the parameter list to indicate:

That ISGNQXITBATCHCND should be called
That the scope of the ENQ should be considered to be global. This indication will be reported through ISGQUERY and ISGENQ TEST for API users to determine the overall scope of their ENQ request.

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