ISGNQXITFAST — Fast ISGENQ / ENQ / DEQ Installation Exit

ISGNXITFAST is the IBM® recommended replacement for ISGNQXIT and should be used except where restrictions apply.

For each ENQ/DEQ/RESERVE request with SCOPE=SYSTEM or SCOPE=SYSTEMS, the system invokes the Fast ENQ/DEQ Installation Exit, ISGNQXITFAST. The exit routine can modify attributes of the request prior to Resource Name List (RNL) processing. See z/OS MVS Planning: Global Resource Serialization for the installation flow through ENQ/DEQ exits.

By altering the ISGNXITFAST exit parameter list, the exit can:

Alter the resource name (QNAME and/or RNAME).
Alter the resource scope. See restrictions as stated in the Note.
Alter the UCB address (for a RESERVE). See restrictions as stated in the Note.
Convert a RESERVE to an ENQ by setting the UCB to zero. See restrictions as stated in the Note.
Convert an ENQ to a RESERVE by adding a UCB specification. See restrictions as stated in the Note.
Indicate to bypass the RNL processing.

Note: The exit routine cannot change the scope nor UCB address of a request when the program issues the ENQ or ISGENQ macro with RNL=NO. The Nqxp_SF1_RnlEqNo bit passed in the parameter list indicates if RNL=NO was specified.

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:

This exit is intended to replace ISGNQXIT. Although it is possible to run with both the ISGNQXIT and ISGNQXITFAST exits on a system, it is not recommended as path length and processing time are increased.
If both the ISGNQXIT and ISGNQXITFAST exits are installed, because ISGNQXIT is called second, any changes requested by the ISGNQXIT exits will override any changes made by the ISGNQXITFAST exits.
Any changes made by ISGNQXITFAST are not honored for an ISGENQ CHANGE or RELEASE request. Instead, the original changes made by ISGNQXITFAST on the OBTAIN are used.

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

ISGNQXITFAST receives control in the following environment:

Enabled for interrupts.
In supervisor state with PSW key 0.
In primary mode with H not= P not= S or H=P=S.
In AMODE 31 and RMODE ANY.
With no locks held or with the local and CMSEQDQ locks held.
An FRR held when locks are held, otherwise an ARR is in effect.

Exit Recovery is as follows.

If an error occurs, ISGNQXITFAST provides its own recovery routine.
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 ISGNQXITFAST exit routine is invoked for every ISGENQ/ENQ/DEQ/RESERVE request issued for a resource. If any exit routines are defined to the dynamic exits facility, those routines are invoked before Resource Names List processing. If any ISGNQXIT exit routines are defined, these are run after the ISNGQXITFAST exit routines are run.

By updating and using information in the parameter list, the exit routine alters the following characteristics of the request:

Resource major name (QNAME).
Resource minor name (RNAME).
Resource scope. If the requestor specified RNL=NO, changes to this parameter are not honored.
Device UCB address (for RESERVE or DEQ with UCB requests). If the requestor specified RNL=NO, changes to this parameter are not honored. A UCB address can be deleted from a RESERVE request, converting the request from a RESERVE to an ENQ or a UCB address can be added to an ENQ, converting the request to a RESERVE.

The exit routine can also indicate that RNL processing can be bypassed.

Programming Considerations

Observe the following conventions when coding a Fast ISGENQ/ENQ/DEQ exit routine:

Every exit routine must be reentrant.
Because the exit is called for every ENQ, RESERVE, and DEQ 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 ISGENQ, ENQ, RESERVE, or DEQ macro.

Entry Specifications

The system passes a NQXP 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 (ISGYNQXP)
2-12: Not applicable
13: Address of a 72-byte save area
14: Return address
15: Entry point address of ISGNQXITFAST

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

Return Specifications

The ISGNQXITFAST installation exit sets the appropriate request flag and alters the value in the parameter list. For example, to change the major name, the exit sets Nqxp_RFI_ChangeQName to B'1' and Nqxp_CP_QNAME to the new major name.

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