ISGNQXITQUEUED1 — ISGENQ / ENQ / DEQ First Queued Exit

ISGNQXITQUEUED1 is called when all the elements of an ENQ (not DEQ) request have completed local processing or have been queued to the global processor. The exit is called just prior to waiting (for unconditional requests that have not been granted) or returning to the ENQ requester. ISGNQXITQUEUED1 is called for both successful and unsuccessful cases. However it is not called at all if neither the batch nor batch conditional exits were called. See ENQ/DEQ Exits Installation in z/OS MVS Planning: Global Resource Serialization for the installation flow through ENQ/DEQ exits.

The parameter list passed to ISGNQXITQUEUED1 is mapped by ISGYNQQP (NQQP). The request data presented to ISGNQXITQUEUED1 are read only. Information contained in NQQP includes return codes that have been set for the local resources, the ABEND code if the request failed, and whether the request needs to be suspended for RNL processing.

Note:

This exit is intended for use by OEM serialization products.
If your installation is using an OEM serialization product to replace global resource serialization, you should NOT specify that any installation provided exits are to be called first (either with the FIRST parameter of the SETPROG command or the POS=FIRST parameter of the CSVDYNEX macro) when installing this exit.

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

ISGNQXITQUEUED1 receives control in the following environment:

Task mode (running under the requester's task).
Enabled for interrupts.
Supervisor state with PSW key 0.
Cross-memory mode with H=S=Requester's address space and P=Global Resource Serialization's address space.
AMODE 31 and primary ASC mode.
With no locks held.
An EUT FRR might be 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 ISGNQXITQUEUED1 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 ISGNQXITQUEUED1 exit point is called after the local resources in an ENQ/RESERVE rquest have been completed and the global resources have been queued to the global resource serialization address space for global processing. DEQ requests are not passed to ISGNQXITQUEUED1 exit routines. The exit routine is passed a NQQP (mapped by ISGYNQQP) which contains information about the request. If the request is going to ABEND, the ABEND code is indicated. An indicator is set if the request will be redriven due to a dynamic RNL change processing. Only SCOPE=SYSTEM and SYSTEMS resources are passed to the exit (STEP requests are not passed to the exit).

The NQQP is followed by one NQQPRSC entry for each resource in the request. Each NQQPRSC entry indicates the result for each local ENQ resource, or the fact that the request has been queued, for each global resource.

Programming Considerations

Most of the exits that are driven for a request are provided with a unique "request token". This token allows the exits to correlate any required user information between exit callers. For example, the Nqqp_RD_RequestToken will be the same as the Nqxp_RequestToken if both the ISGNQXITQUEUED1 and ISGNQXITFAST exits are driven for the same request.

Observe the following conventions when coding an ENQ/DEQ First Queued 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 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, RESERVE, or DEQ macro.
The ISGNQXITQUEUED1 exit point is called for all ENQ/RESERVE requests only when either the ISGNQXITBATCH or ISGNQXITBATCHCND exits are called. In other words, only if a batch exit is called, the queued exit is called.

Entry Specifications

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

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

Return Specifications

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