Monitoring contention changes
- Where the requester waits for the contention to complete before becoming an owner of the resource.
- Where the requester requested not to wait for the resource to become available. These result from RET=USE and RET=CHNG type ENQs when the resource was unavailable. Listeners can request to get control only for a specific type or for both types depending on the qualifiers that they specify.
ENFREQ ACTION=LISTEN
with one of the qualifier/qmask
combinations described in Table 1. In the table: - In qualifier values, the character 'x' indicates an arbitrary value ("don't-care" value).
- An incremental update might represent multiple changes in the state of contention (for instance, multiple new waiters, or multiple changes in ownership).
If you are monitoring contention for global resources, your listen request must specify XSYS=YES even if you are monitoring contention involving only the local system. Contention notifications may originate from another system that is involved in contention for a resource, or even from a system that is not involved in contention at all.
It is possible to receive duplicate notification, that is, two signals that represent the same contention data. For example, this can occur if an ENQ and DEQ happen in rapid succession, thereby causing and relieving contention. This could result in two notifications, both indicating that no contention exists.
Qualifier (hexadecimal) | QMASK | Result |
---|---|---|
None | NONE | All signal 51 events, including both contention and RNL change data. Qualifier value requests all contention data, including waitless contention resulting from RET=USE and RET=CHNG type ENQs. |
01xxxxxx | BYTE1 | All contention-related events, including waitless contention
resulting from RET=USE and RET=CHNG type ENQs. All contention-related
events. To correspond to a GQ SCAN request, specify the following:
|
01xxxx01 | BYTE1, BYTE4 | All contention-related events, including waitless contention
resulting from RET=USE and RET=CHNG type ENQs. Incremental
updates to contention information for local resources. Corresponds
to a GQSCAN request specifying:
|
01xxxx02 | BYTE1, BYTE4 | All contention-related events, including waitless contention
resulting from RET=USE and RET=CHNG type ENQs. Incremental
updates to contention information for global resources. Corresponds
to a GQSCAN request specifying:
|
01xxxx03 | BYTE1, BYTE4 | Contention-related recovery information, including removal of a system from the sysplex or limitation of contention notification capability. |
01xx00xx | BYTE1, BYTE3 | All contention data, excluding waitless contention resulting from RET=USE and RET=CHNG type ENQs. |
01xx0001 | BYTE1, BYTE3, BYTE4 | All contention data, excluding waitless contention resulting from RET=USE and RET=CHNG type ENQs. |
01xx0002 | BYTE1, BYTE3, BYTE4 | All contention data, excluding waitless contention resulting from RET=USE and RET=CHNG type ENQs. |
- Establish your ENF listen request.
- On return from ENF, record a timestamp (STCK).
- Issue GQSCAN SCOPE=LOCAL and/or GLOBAL, WAITCNT=1,XSYS=YES.
- In your listen exit, process and store any contention notifications accumulated during GQSCAN processing.
- On return from GQSCAN, apply the stored contention notifications to the GQSCAN output. Discard any notifications timestamped earlier than the recorded timestamp, and apply any notifications with a timestamp equal to or later than the recorded timestamp.
- Complete initialization and begin normal processing, applying contention notifications as they arrive.
If you are monitoring resource contention, you should define your listen exit to receive and process recovery signals identified by the X'01xxxx03' qualifier. The recovery signals are characterized further by the following flags in the ISGE51CN parameter list:
- ENF51C_SYSTEM_FAILURE
- If the ENF51C_SYSTEM_FAILURE flag is set, the system identified
by the ENF51C_FAILED_SYSTEM field has failed. If the ENF listener
is maintaining a database of contention information, it must be reinitialized
as described above. Note: Global resource serialization may not issue this event for all system failures. This flag is only set when global resource serialization cannot determine the effect of the system failure on contention already in existence.
- ENF51C_SYSTEM_ERROR
- If the ENF51C_SYSTEM_ERROR flag is set, contention information
has been lost due to a system error:
- In a global resource serialization ring complex, contention monitors on the system where the failure occurred will receive no further contention signals. Contention information relating to that system will be available via ENF signals on the other systems in the complex. The signal is only sent to listeners on the affected system.
- In a global resource serialization star complex, no further contention information for the system where the error occurred will be available via ENF signals to other systems in the complex. Global resource contention data is not valid on any system. Local resource contention data remains valid on systems other than the one suffering the error. The signal is sent to all systems in the sysplex.
The CVTGRSST field contains the following flags that describe the availability of ENF contention data on each system following the error:- CVTE51GN
- When this flag is set, global resource contention data is not available. ENF 51 listeners may receive signals for global resource contention, but the data will be incomplete.
- CVTE51LN
- When this flag is set, local resource contention data is not available. ENF 51 listeners will not receive signals for local resource contention.
- ENF51C_SYSTEM_ERROR_CLEARED
- If this flag is set, all systems that had suffered the error reported by the ENF51C_SYSTEM_ERROR signal have been partitioned from the sysplex. Global resource contention data is once again valid on all systems. This signal is sent to listeners on all systems in a star complex. (In a ring complex, the other systems were not affected by the original error.)