ISGECA — GRS enhanced contention analysis service

The requirements for the caller are:

None

Before issuing the ISGECA macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Before issuing the ISGECA macro, the caller does not have to place any information into any access register.

None.

The parameters are explained as follows:

name

An optional symbol, starting in column 1, that is the name on the ISGECA macro invocation. The name must conform to the rules for an ordinary assembler language symbol.

,COUNT=count

A required input parameter describing the maximum number of relevant resources to be reported on by this ISGECA invocation. The maximum value that can be specified with the COUNT parameter is 99.

To code: Specify the RS-type address, or address in register (2)-(12), of an one-byte field.

,MF=S

,MF=(L,list addr)

,MF=(L,list addr,attr)

,MF=(L,list addr,0D)

,MF=(E,list addr)

,MF=(E,list addr,COMPLETE)

An optional input parameter that specifies the macro form.

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.

Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.

Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

,list addr

The name of a storage area to contain the parameters. For MF=S and MF=E, this can be an RS-type address or an address in register (1)-(12).

,attr

An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.

,COMPLETE

Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.

,NOTINCCT=notincct

An optional output parameter, to contain the number of systems reported in the NOTINCL area. Alternatively, this number of NOTINCL entries can be obtained from the 2-byte parameter list field at offset 58 (or X'3A').

To code: Specify the RS-type address, or address in register (2)-(12), of a halfword field.

,NOTINCL=notincl

A required input parameter that contains the address of a virtual storage output area to contain the list of systems for which RIBs and RIBEs are not included in the RIBOUT area. The NOTINCL area must begin on a doubleword boundary, and must reside within common storage subpool 231.

The length of the NOTINCL area, in bytes, must, minimally, be the number of systems currently executing in the sysplex multiplied by 10 (or X'0A'). The format of the NOTINCL area is as follows:

 +---------------------------+
 | System name | Reason Code |
 | System name | Reason Code |
 | System name | Reason Code |
 +---------------------------+

Each system name and reason code pair potentially reflects a system not included in waiter/blocker data returned in the RIBOUT area. The number of systems reported on in the NOTINCL area is returned in the NOTINCCT output parameter value.

Each NOTINCL system name field is an 8-byte field, and each reason code entry is a 2-byte field. Reason codes for the NOTINCL area are independent of ISGECA service invocation reason codes, and are only meaningful when the ISGECA return code is 4 or less. The NOTINCL reason codes and meanings are as follows:

Hex Reason Code

Meaning

0000

Ignore this NOTINCL area entry, including the system name value specified.

0001

The system described by the system name field is cannot process the ISGECA service.

0002

The system described by the system name field was not found to be participating in the current sysplex.

0003

The system described by the system name field did not respond to an XCF request to gather ISGECA report information.

To code: Specify the RS-type address, or address in register (2)-(12), of a pointer field.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=0

An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:

• IMPLIED_VERSION, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
• MAX, if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage that your program needs.

  If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.

• 0, if you use the currently available parameters.

To code: Specify one of the following:

• IMPLIED_VERSION
• MAX
• A decimal value of 0

REQUEST=WAITER

REQUEST=BLOCKER

A required parameter that indicates the type of ISGECA request.

REQUEST=WAITER

When you specify WAITER, the longest waiters and top blockers for each relevant resource are returned. For REQUEST=WAITER, the RIBOUT buffer area is formatted as follows:

 +-------------------+
 | RIB | RIBE | RIBE |
 | RIB | RIBE | RIBE |
 | RIB | RIBE | RIBE |
 +-------------------+

The number of RIBs collected in the RIBOUT area is returned in the RIBOUTCT parameter variable. Each RIB/RIBE/RIBE trio reports on the following:

• The RIB describes general information about the resource, including the QNAME, minor name and the numbers of waiters and blockers.
• The first RIBE describes the top blocking unit of work for this resource.
• The second RIBE describes the longest waiting unit of work for this resource.

REQUEST=BLOCKER

When you specify BLOCKER, the top blockers for each relevant resource is returned. For REQUEST=BLOCKER, the RIBOUT buffer area is formatted as follows:

 +------------+
 | RIB | RIBE |
 | RIB | RIBE |
 | RIB | RIBE |
 +------------+

The number of RIBs collected in the RIBOUT area is returned in the RIBOUTCT parameter variable. Each RIB/RIBE pair reports on the following items:

• The RIB describes general information about the resource, including the QNAME, minor name and the numbers of waiters and blockers.
• The RIBE describes the top blocking unit of work for this resource.

,RETCODE=retcode

An optional output parameter that will contain the return code.

To code: Specify the RS-type address of a fullword field, or register (2)-(12) or (15), (GPR15), (REG15), or (R15).

,RIBOUT=ribout

A required input parameter that contains the address of the virtual storage output area for this request. The RIBOUT area must reside in the invoker's primary address space, and contains the ISGECA report of RIBs and RIBEs for the request.

To code: Specify the RS-type address, or address in register (2)-(12), of a pointer field.

,RIBOUTCT=riboutct

An optional output parameter, to contain the number of RIBs collected in the RIBOUT area. Alternatively, this number of RIBs can be obtained from the 2-byte parameter list field at offset 56 (or X'38').

To code: Specify the RS-type address, or address in register (2)-(12), of a halfword field.

,RIBOUTLN=riboutln

A required input parameter describing the length, in bytes, of the RIBOUT virtual storage area.

The length of the RIBOUT area must be large enough to accomodate the maximum size ISGECA report for the request, and therefore must be of a magnitude that facilitates the COUNT parameter value and RIB/RIBE DSECT mapping sizes. Depending on the ISGECA request type, this relationship between these parameter values and DSECT sizes can be expressed as follows:

Waiter:

RIBOUTLN parameter value must equal or exceed the COUNT parameter value multiplied by 392 (or X'188').

Blocker:

RIBOUTLN parameter value must equal or exceed the COUNT parameter value multiplied by 344 (or X'158').

To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.

,RSNCODE=rsncode

An optional output parameter that will contain the reason code.

To code: Specify the RS-type address of a fullword field, or register (0) or (2)-(12), (00), (GPR0), (GPR00), REG0), (REG00), or (R0).

,SCOPE=SYSTEM

,SCOPE=SYSTEMS

A required parameter that indicates the request scope.

,SCOPE=SYSTEM

ISGECA is to only report on blockers and, potentially, waiters currently executing on a specific system within the current GRS complex.

,SCOPE=SYSTEMS

ISGECA is to report on blockers and, potentially, waiters across all of the systems in the current sysplex complex.

,SYSNAME=sysname

When SCOPE=SYSTEM is specified, a required input parameter string containing the system name of the single system on which ISGECA is to report.

SYSNAME is required when you specify SCOPE=SYSTEM. SYSNAME is not valid for SCOPE=SYSTEMS.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

None.

The following table identifies the hexadecimal return and reason codes. IBM support personnel may request the entire reason code, including the xxxx value.

Table 1. Return and Reason Codes for the ISGECA Macro

Return Code	Reason Code	Meaning and Action
00	–	Successful completion. The RIBOUT virtual storage area contains the waiter or blocker output report, and the NOTINCL virtual storage area describes system names and reason codes for systems not reported on in the RIBOUT area.
04	–	Request completed with exceptional circumstances.
04	xxxx0000	Meaning: The ISGECA service could not communicate with some systems in the sysplex, so the returned data is incomplete. This implies that such systems are non-responsive, such as when a system has been reset but has not been removed from the sysplex. Action: No suggested program action.
04	xxxx0001	Meaning: Not all systems in the current GRS complex that are relevant to the ISGECA request are participating in the current sysplex. Action: No suggested program action. The RIBOUT virtual storage area contains the waiter or blocker output report, and the NOTINCL virtual storage area describes system names and reason codes for systems not reported on in the RIBOUT area.
08	–	Request failed.
08	xxxx0000	Meaning: A GRS internal error occurred and the request could not be completed. Action: No suggested program action.
08	xxxx0001	Meaning: The ISGECA service routine was unable to obtain storage necessary to process the request. Action: Consider reducing the COUNT and RIBOUTLN parameter values to decrease the total number of resources to be reported, and re-invoke ISGECA. Alternatively, if this was a SCOPE(SYSTEMS) request, consider re-inovking ISGECA with SCOPE(SYSTEM) to, potentially, reduce the total number of resources to be reported.
08	xxxx0003	Meaning: A GRS internal error occurred and the request could not be completed. Action: No suggested program action.
08	xxxx0004	Meaning: The sysplex is in the process of migrating to GRS STAR mode, and therefore cannot process the request at this time. Action: Iteratively retry the ISGECA invocation, waiting a few seconds between attempts.
08	xxxx00FD	Meaning: The maximum number of relevant resources to be reported on, as specified by parameter COUNT, exceeds the service maximum value of 99. Action: Correct the COUNT parameter value and reinvoke ISGECA.
08	xxxx00FE	Meaning: The RIBOUT length specified in parameter RIBOUTLN was not large enough to process the number of resource requests specified by parameter COUNT. Action: Correct the RIBOUTLN or COUNT parameter values and reinvoke ISGECA.
08	xxxx00FF	Meaning: ISGECA is an unsupported service on this system. Action: No suggested program action. The system needs a service or release level upgrade before ISGECA can be successfully invoked.

The following examples do not show, but presume, the existence of appropriate assembler continuation characters in column 72. The examples also presume an appropriate assembler storage declaration for each instance of a named symbol ISGECA parameter.

            XR    2,2            Clear reg 2                         
            LHI   2,476          ISGECA parm list length into R2     
            STORAGE OBTAIN,LENGTH=(2),ADDR=(3),SP=231,COND=NO        
            GETWAIT  ISGECA REQUEST=WAITER,SCOPE=SYSTEM,             
                   SYSNAME=MYSYSNAME,RIBOUT=OUTAREA@,                
                   RIBOUTLN=MYOUTAREALEN,RIBOUTCT=MYRIBCT,           
                   COUNT=MYCOUNT,NOTINCL=NOTINCLAREA@,               
                   NOTINCCT=MYNOTCT,RETCODE=MYRETCODE,               
                   RSNCODE=MYRSNCODE,PLISTVER=MAX,                   
                   MF=(E,(3))                                        

For the above, subpool 231 storage is obtained and then passed through the MF= parameter for the ISGECA service routine parameter list.

Upon return from the service routine, the virtual storage area specified by OUTAREA@ contains the waiter report RIBs and RIBEs for up to MYCOUNT number of resources; while the virtual storage area specified by NOTINCLAREA@ contains the associated list of systems (with reasons) that are not included in the RIBOUT area report. The precise number of RIBs returned in the OUTAREA@ area is returned in the MYRIBCT program variable.

      GETBLOCK ISGECA REQUEST=BLOCKER,SCOPE=SYSTEMS,                
                   RIBOUT=OUTAREA@,RIBOUTLN=MYOUTAREALEN,           
                   RIBOUTCT=MYRIBCT,COUNT=MYCOUNT,                  
                   NOTINCL=NOTINCLAREA@,NOTINCCT=MYNOTCT,           
                   RETCODE=MYRETCODE,RSNCODE=MYRSNCODE,             
                   PLISTVER=MAX,MF=S                                

Parameter usage and results for this example are analogous to the previous example. In this case, upon return from the ISGECA service routine, the virtual storage area specified by OUTAREA@ contains the blocker report RIBs and RIBEs. Note that the program itself must reside in common area subpool 231, because the ISGECA invocation is using the standard macro format.