Detecting ICSF serialization contention conditions

If a user task or address space holds an ENQ or latch for an extended period of time, it is likely hung and needs to be cancelled so that other work can obtain the ENQ or latch. Some applications might provide controls or document procedures for addressing situations in which the application appears to be gating the rest of the workload. The ICSF system programmer should consult the application's system programmer or administrator regarding actions to take for or against the application. Such action could include stopping or canceling the application.

ICSF requires Global Resource Serialization (GRS) ENQ resources to manage concurrent operations involving the key data sets (CKDS, PKDS and TKDS), and the ICSF ENQ scheme has ICSF itself obtaining any necessary data set ENQ, in a proxy fashion, on behalf of an application unit of work driving an ICSF API request requiring an ENQ. ICSF also manages any set of additional, different application requests that may be waiting for that same ENQ resource. For this reason, GRS always perceives only ICSF as a key data set ENQ resource owner or waiter, and a DISPLAY GRS,CONTENTION command would not illustrate key data set ENQ contention between two or more competing application requests within a single system scope. For sysplex scope ENQ contention, DISPLAY GRS,CONTENTION would, without any internal assistance, illustrate only ICSF itself as an ENQ holder or waiter, and would not reflect any client application identity or information associated with ICSF's ENQ resource usage.

ICSF provides an internal capability to embellish the DISPLAY GRS command output to illustrate the ICSF client applications for which ICSF is holding an ENQ resource, and on the general conditions involving client waiters for an ENQ resource. This enhanced capability is transparently provided and requires no additional ICSF or GRS installation or configuration action. The ICSF support to enhance the DISPLAY GRS output is relevant on a DISPLAY GRS,CONTENTION command only if GRS can detect contention, which is not the case when two or more ICSF client application requests are competing for the same ENQ resource within a single system scope. The ICSF support is relevant on a DISPLAY GRS,RES=(qname-rname) command whenever the ENQ resource specified in the qname-rname option is currently held, regardless of whether or not contention exists. For this reason, the DISPLAY GRS,RES=() command version is recommended as the reliable technique for obtaining information about ICSF key data set ENQ serialization conditions. The DISPLAY GRS command syntax for the various ICSF key data set ENQ resources can be summarized as follows:
Table 1. DISPLAY GRS command syntax ICSF key data set ENQ resources
This command: Displays ENQ information for the:
DISPLAY GRS,RES=(SYSZCKT.*) CKDS
DISPLAY GRS,RES=(SYSZPKT.*) PKDS
DISPLAY GRS,RES=(SYSZTKT.*) TKDS
Here is sample command output for the DISPLAY GRS,RES=(SYSZCKT.*) command:
ISG343I 12.01.33 GRS STATUS 360                             
S=SYSTEM  SYSZCKT  SYSZCKT                                  
SYSNAME        JOBNAME         ASID     TCBADDR   EXC/SHR   
                                                            
SY1       CSFJM70 /APPL107   0040/0045  007D8E88 EXCLUSIVE  
                                                            
ADDITIONAL RESOURCE INFORMATION FROM:  ICSF Managed ENQ     
Owner: APPL107  TTOKEN: 000001200000000300000003007FF050 Waiters: 005
In this example, the display command result illustrates that ICSF on system SY1 started under jobname CSFJM70 and executing in ASID 40, has obtained the CKDS ENQ resource exclusively on behalf of the client application running with a jobname of APPL107 and executing in ASID 45. Furthermore, the APPL107 application unit of work that caused ICSF to obtain this ENQ was the task identified by task token 000001200000000300000003007FF050, and there are five additional application requests on system SY1 that are awaiting access to this ENQ resource.

The DISPLAY GRS,RES=() command must be executed on (or routed to) all of the systems within the scope of a sysplex to obtain the comprehensive understanding of an ICSF key data set ENQ resource.

ICSF also exploits Global Resource Serialization (GRS) latches for serializing resources that are managed within the scope of a single system. In the case of ICSF latches, whenever a client application request requires an ICSF latch for serialization, the latch is obtained under the application's unit of work (not proxied like the ENQ), and therefore the DISPLAY GRS,CONTENTION command will always illustrate the application information for the current latch owner or owners.

The following operational steps are recommended when ICSF serialization contention is suspected as a cause for a workload slowdown or hang:

  1. Issue the DISPLAY GRS,CONTENTION command to illustrate sysplex scope contention on ICSF ENQ serialization resources, or system level contention on ICSF latch serialization resources. If the command result demonstrates latch contention, go to step 3. If the command result demonstrates ICSF key data set ENQ contention and discloses the ENQ owner client application information, go to step 3. If the command result does not demonstrate contention, or does not disclose the ENQ owner client application information, proceed to the next step.
  2. Issue the following commands as needed (depending on the key data sets you are using):
    DISPLAY GRS,RES=(SYSZCKT.*)
    DISPLAY GRS,RES=(SYSZPKT.*)Issue this command only if you are utilizing a PKDS
    DISPLAY GRS,RES=(SYSZTKT.*)Issue this command only if you are utilizing a TKDS

    The commands need to be executed either on all systems within a sysplex, or on the local system where the ENQ resource is known to be owned. The command result should disclose the ENQ owner client application information.

  3. Initiate an action for or against the client application to end the unit of work on behalf of which ICSF has obtained the ENQ resource. Such action could include stopping or canceling the application.