Monitoring contention changes

There are two types of contention events:
To establish an ENF listen exit to be called when resource contention occurs, issue 
ENFREQ ACTION=LISTEN
with one of the qualifier/qmask combinations described in Table 1. In the table:

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.

Table 1. Qualifier / QMASK combinations for contention data
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: 
SCOPE=(Global,Local)
WAITCNT=1
XSYS=YES
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: 
RESNAME=resource name specified
on the ENQ or DEQ request
SCOPE=LOCAL
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: 
RESNAME=resource name specified
on the ENQ or DEQ request
SCOPE=GLOBAL
XSYS=YES
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.
If you are monitoring contention changes and are maintaining a database of current contention data, observe the following protocol to obtain a set of initial data:
  1. Establish your ENF listen request.
  2. On return from ENF, record a timestamp (STCK).
  3. Issue GQSCAN SCOPE=LOCAL and/or GLOBAL, WAITCNT=1,XSYS=YES.
  4. In your listen exit, process and store any contention notifications accumulated during GQSCAN processing.
  5. 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.
  6. 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.)
Parent topic: Listening for global resource serialization-related system events