ISGADMIN — Global resource serialization administration service

Description

Interface for Global Resource Serialization Administration

The GRS Administration service routine is given control from the ISGADMIN macro to:

Change maximum ENQ limits for a specific address space.
Move an ENQ waiter to a different position in the request queue and to optionally change its control type from exclusive to shared.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	The caller must be authorized, although any one of the following attributes is sufficient: Supervisor State Key 0-7 APF-authorized
Dispatchable unit mode:	Task
Cross memory mode:	Any PASN, any HASN, any SASN Note: The updated ENQ limit is updated for the home address space.
AMODE:	31- or 64-bit If in AMODE 64, specify SYSSTATE AMODE64=YES before invoking this macro.
ASC mode:	Primary or access register (AR) If in Access Register ASC mode, specify SYSSTATE ASCENV=AR before invoking this macro.
Interrupt status:	Enabled for I/O and external interrupts
Locks:	The caller must not be locked.
Control parameters:	Control parameters must be in the primary address space or, for AR-mode callers, must be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL). The control parameters must be in the same key as the caller.

Programming requirements

The caller must include the ISGYCON macro to get the return and reason codes.

Restrictions

The caller must not have functional recovery routines (FRRs)

This macro supports multiple versions. Some keywords are unique to certain versions. See the PLISTVER parameter description.

Input register information

Before issuing the ISGADMIN macro, the caller does not have to place any information into any general purpose register (GPR) or access register (AR) unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0: Reason code if GPR15 is not 0
1: Used as a work register by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

When control returns to the caller, the ARs contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

Syntax

Note:


main diagram

>>-+------+--b--ISGADMIN--b------------------------------------->
   '-name-'                   

>--+-REQUEST--=--SETENQMAX--+-,--MAXTYPE--=--AUTHORIZED---+--,--MAXVALUE--=--maxvalue-+-->
   |                        '-,--MAXTYPE--=--UNAUTHORIZED-'                           |   
   +-REQUEST--=--RESETENQMAX--+-,--MAXTYPE--=--AUTHORIZED---+-------------------------+   
   |                          '-,--MAXTYPE--=--UNAUTHORIZED-'                         |   
   '-REQUEST--=--MOVEWAITER--|  |-----------------------------------------------------'   

>--+------------------------+--+------------------------+------->
   '-,--RETCODE--=--retcode-'  '-,--RSNCODE--=--rsncode-'   

   .-,--PLISTVER--=--IMPLIED_VERSION-.   
>--+---------------------------------+-------------------------->
   +-,--PLISTVER--=--MAX-------------+   
   +-,--PLISTVER--=--1---------------+   
   '-,--PLISTVER--=--2---------------'   

   .-,--MF--=--S--------------------------------------.   
>--+--------------------------------------------------+--------><
   |                               .-,--0D---.        |   
   +-,--MF--=--(--L--,--list addr--+---------+--)-----+   
   |                               '-,--attr-'        |   
   |                               .-,--COMPLETE-.    |   
   '-,--MF--=--(--E--,--list addr--+-------------+--)-'

Note:


parameters-1

>>-,--MOVINGWAITER--=--movingwaiter----------------------------->

   .-,--NEWCONTROL--=--EXCLUSIVE-.   
>--+-----------------------------+------------------------------>
   '-,--NEWCONTROL--=--SHARED----'   

     .-,--TOTHEEND--=--NO-.                                             
>--+-+--------------------+--,--BEFOREREQUESTER--=--beforerequester-+-><
   '-,--TOTHEEND--=--YES--------------------------------------------'

Parameters

The parameters are explained as follows:

name

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

,BEFOREREQUESTER=beforerequester

When TOTHEEND=NO and REQUEST=MOVEWAITER are specified, a required input parameter that is an ENQToken identifying the ENQ request that the MovingWaiter request precedes.

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

,MAXTYPE=AUTHORIZED

,MAXTYPE=UNAUTHORIZED

When REQUEST=SETENQMAX is specified, a required parameter.

,MAXTYPE=AUTHORIZED: Indicates a request to update the maximum ENQ limit for authorized requesters.
,MAXTYPE=UNAUTHORIZED: Indicates a request to update the maximum ENQ limit for unauthorized requesters.

,MAXTYPE=AUTHORIZED

,MAXTYPE=UNAUTHORIZED

When REQUEST=RESETENQMAX is specified, a required parameter.

,MAXTYPE=AUTHORIZED: Indicates a request to reset the maximum ENQ limit for authorized requesters.
,MAXTYPE=UNAUTHORIZED: Indicates a request to reset the maximum ENQ limit for unauthorized requesters.

,MAXVALUE=maxvalue

When REQUEST=SETENQMAX is specified, a required input parameter that is the requested value of the new maximum ENQ limit. The specified value must be greater than or equal to the absolute minimum described in ISGYCON, and up to 2?1-1 (2147483647).

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

,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.

,MOVINGWAITER=movingwaiter

When REQUEST=MOVEWAITER is specified, a required input parameter that is an ENQToken identifying the ENQ waiter.

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

,NEWCONTROL=EXCLUSIVE

,NEWCONTROL=SHARED

When REQUEST=MOVEWAITER is specified, an optional parameter. The default is NEWCONTROL=EXCLUSIVE.

,NEWCONTROL=EXCLUSIVE: Indicates that the requester represented by the MovingWaiter ENQToken should have its control remain Exclusive.
,NEWCONTROL=SHARED: Indicates that the request represented by the MovingWaiter ENQToken should have its control become Shared.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=1

,PLISTVER=2

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.
1, which supports all parameters except those specifically referenced in higher versions.
2, which supports both the following parameters and those from version 1:
- BEFOREREQUESTER
- MOVINGWAITER
- NEWCONTROL
- TOTHEEND

To code: Specify one of the following:

IMPLIED_VERSION
MAX
A decimal value of 1, or 2

REQUEST=SETENQMAX

REQUEST=RESETENQMAX

REQUEST=MOVEWAITER

A required parameter that indicates the type of ISGADMIN request.

REQUEST=SETENQMAX

Indicates a request to change the ENQ maximum for the home address space.

REQUEST=RESETENQMAX

Indicates a request to reset the ENQ maximum for the home address space back to the system default.

REQUEST=MOVEWAITER

Indicates a request to move an ENQ waiter to a different position in the request queue and to optionally change its control type through the NEWCONTROL keyword.

This request requires a version 2 parameter list.

Note: This function is intended to only be used by third party serialization products. Its misuse can result in deadlocks, incorrect serialization or loss of data integrity. The MOVEWAITER, TOTHEEND, and BEFOREREQUESTER keywords specify which requester should be moved and where to move it. The waiter will only be moved under the following conditions:

The MOVINGWAITER:
- Has a requested disposition of Exclusive
- Is not currently an owner of the resource
- Cannot result in any new owners as a result of the move
- Must be waiting for the same resource as the BEFOREREQUESTER (if specified)
The resource is NOT global or STEP in scope. Note that in GRS=NONE mode, the final scope can be SYSTEMS or SYSTEM. When in other GRS modes the scope must be SYSTEM.

,RETCODE=retcode

An optional output parameter into which the return code is to be copied from GPR 15. If you specify 15, GPR15, REG15, or R15 (within or without parentheses), the value will be left in GPR 15.

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

,RSNCODE=rsncode

An optional output parameter into which the reason code is to be copied from GPR 0. If you specify 0, 00, GPR0, GPR00, REG0, REG00, or R0 (within or without parentheses), the value will be left in GPR 0.

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

,TOTHEEND=NO

,TOTHEEND=YES

When REQUEST=MOVEWAITER is specified, an optional parameter. The default is TOTHEEND=NO.

,TOTHEEND=NO: Indicates that the requester represented by the MovingWaiter ENQToken should be moved to a position specified through the BEFOREREQUESTER keyword.
,TOTHEEND=YES: Indicates that the request represented by the MovingWaiter ENQToken should be moved to the end of the request queue.

ABEND codes

None

Return and reason codes

When the ISGADMIN macro returns control to your program:

GPR 15 (and retcode, when you code RETCODE) contains a return code.
When the value in GPR 15 is not zero, GPR 0 (and rsncode, when you code RSNCODE) contains a reason code.

Macro ISGYCON provides equate symbols for the return and reason codes.

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

Table 1. Return and Reason Codes for the ISGADMIN Macro
Return Code	Reason Code	Equate Symbol Meaning and Action
00	—	Equate Symbol: ISGADMINRc_OK Meaning: ISGADMIN request successful. Action: None required.
04	—	Equate Symbol: ISGADMINRc_Warn Meaning: Warning Action: Refer to action under the individual reason code.
04	xxxx0401	Equate Symbol: ISGADMINRsn_ENQMaxValueLow Meaning: For REQUEST=SETENQMAX. The specified maximum is less than or equal to the current system-wide maximum. This space-specific maximum has been set but has no immediate effect. Action: Ensure the specified MaxValue is accurate. If not, reissue the ISGADMIN service with a higher value.
04	xxxx0402	Equate Symbol: ISGADMINRsn_ResetENQMaxIgnored Meaning: For REQUEST=RESETENQMAX. The home address space did not have a specific maximum for that type of requester. Action: Ensure that the reset was desired, and issued for the appropriate requester type, authorized or unauthorized. Reissue the service with the correct requester type if appropriate.
08	—	Equate Symbol: ISGADMINRc_ParmError Meaning: ISGADMIN request specified parameters in error. Action: Refer to action under the individual reason code.
08	xxxx0801	Equate Symbol: ISGADMINRsn_BadPlistAddress Meaning: Unable to access parameter list. Action: Check that the parameter list is addressable. If in AR-mode, check that the ALET of the parameter list is correct. Note that if this macro is issued in AR-mode, SYSSTATE ASCENV=AR must be issued before this macro. Ensure that the storage is in the same key as the caller.
08	xxxx0802	Equate Symbol: ISGADMINRsn_BadPlistALET Meaning: Bad parameter list ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable Unit Access List (DU-AL), nor a valid entry for a common area data space. Action: Make sure that the ALET of the parameter list is valid. Its access register may not have been set up properly.
08	xxxx0803	Equate Symbol: ISGADMINRsn_BadPlistVersion Meaning: Bad parameter list version number. The ISGADMIN parameter list version is greater than the version supported by GRS on the current system or the ISGADMIN parameter list version is lower than the minimum required for parameters that were specified. Action: Check for possible storage overlay of the parameter list. Retry the request with the correct version number. Verify that your program was assembled with the correct macro library for the release of MVS on which your program is running.
08	xxxx0804	Equate Symbol: ISGADMINRsn_ReservedFieldNotNull Meaning: A reserved field in the parameter list is non-zero. Action: Check for possible storage overlay of the parameter list.
08	xxxx0805	Equate Symbol: ISGADMINRsn_BadRequest Meaning: Bad REQUEST parameter. Action: IBM suggests that the ISGADMIN macro is used when invoking the ISGADMIN service.
08	xxxx0806	Equate Symbol: ISGADMINRsn_ENQMaxValueTooLow Meaning: For REQUEST=SETENQMAX. The specified maximum is less than the smallest allowable maximum. Action: Check the smallest allowable maximum in macro ISGYCON. Reissue the ISGADMIN service with a higher value.
08	xxxx0807	Equate Symbol: ISGADMINRsn_BadMovingWaiterAddress Meaning: For REQUEST=MOVEWAITER. Unable to access the MovingWaiter ENQToken. Action: Make sure that the MovingWaiter ENQToken is addressable. If in AR-mode, this field is accessed through its address and ALET, check that both these values are correct. Ensure that the storage is in the same key as the caller.
08	xxxx0808	Equate Symbol: ISGADMINRsn_BadMovingWaiterAlet Meaning: For REQUEST=MOVEWAITER. Bad MovingWaiter ENQToken ALET. The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable Unit Access List (DU-AL), nor a valid entry for a common area data space. Action: Make sure that the ALET of the MovingWaiter ENQToken is valid. Its access register may not have been set up properly.
08	xxxx0809	Equate Symbol: ISGADMINRsn_BadMovingWaiter Meaning: For REQUEST=MOVEWAITER. The specified MovingWaiter ENQToken does not represent an ENQ on the current system. Action: Make sure that the specified MovingWaiter ENQToken is from a previous request that has not been subsequently released.
08	xxxx080A	Equate Symbol: ISGADMINRsn_BadBeforeRequesterAddress Meaning: For REQUEST=MOVEWAITER. Unable to access the BeforeRequester ENQToken. Action: Make sure that the BeforeRequester ENQToken is addressable. If in AR-mode, this field is accessed through its address and ALET, check that both these values are correct. Ensure that the storage is in the same key as the caller.
08	xxxx080B	Equate Symbol: ISGADMINRsn_BadBeforeRequesterAlet Meaning: For REQUEST=MOVEWAITER. Bad BeforeRequester ENQToken The ALET is neither zero nor is it associated with a valid public entry on the caller's Dispatchable Unit Access List (DU-AL), nor a valid entry for a common area data space. Action: Make sure that the ALET of the BeforeRequester ENQToken is valid. Its access register may not have been set up properly.
08	xxxx080C	Equate Symbol: ISGADMINRsn_BadBeforeRequester Meaning: For REQUEST=MOVEWAITER. The specified BeforeRequester ENQToken does not represent an ENQ on the current system. Action: Make sure that the specified BeforeRequester ENQToken is from a previous request that has not been subsequently released.
08	xxxx080D	Equate Symbol: ISGADMINRsn_SameRequester Meaning: For REQUEST=MOVEWAITER. The same ENQToken was specified for both MovingWaiter and BeforeRequester. Action: Make sure that the ENQTokens are distinct.
08	xxxx080E	Equate Symbol: ISGADMINRsn_InconsistentResource Meaning: For REQUEST=MOVEWAITER. The specified MovingWaiter and BeforeRequester ENQTokens do not represent ENQ requests for the same resource. Action: Make sure that the ENQTokens specified are against the same resource.
08	xxxx080F	Equate Symbol: ISGADMINRsn_BadScope Meaning: For REQUEST=MOVEWAITER. The resource associated with the specified MovingWaiter and BeforeRequester ENQTokens is not a valid local resource. The resource cannot be a global or a STEP resource. Note that in GRS=NONE mode, an acceptable local resource can have a final scope of SYSTEMS or SYSTEM. When in other GRS modes, the final scope can only be SYSTEM. Action: Make sure that the ENQTokens specified are against a valid local resource.
08	xxxx0810	Equate Symbol: ISGADMINRsn_BadControl Meaning: For REQUEST=MOVEWAITER. The specified MovingWaiter ENQToken represents a requester of shared control. Action: Make sure that the MovingWaiter ENQToken represents a requester of exclusive control.
08	xxxx0811	Equate Symbol: ISGADMINRsn_CannotMoveOwner Meaning: For REQUEST=MOVEWAITER. The specified MovingWaiter ENQToken represents a requester that owns the resource. Action: Make sure that the MovingWaiter ENQToken specified is for a waiting requester.
08	xxxx0812	Equate Symbol: ISGADMINRsn_AlreadyBeforeRequester Meaning: For REQUEST=MOVEWAITER, TOTHEEND=NO, BEFOREREQUESTER=. The specified MovingWaiter ENQToken represents a requester that is already queued just before the requester represented by the BeforeRequester ENQToken. The control was not changed. Action: Make sure that the MovingWaiter and BeforeRequester ENQTokens represent the correct requesters and that the queue is as expected.
08	xxxx0813	Equate Symbol: ISGADMINRsn_CannotMoveBeforeOwner Meaning: For REQUEST=MOVEWAITER. If granted, the requester represented by the MovingWaiter ENQToken would have become the owner of the resource because it would precede an owner. Action: Make sure that the BeforeRequester ENQToken represents a waiting requester.
08	xxxx0814	Equate Symbol: ISGADMINRsn_CannotMoveAfterSharedOwner Meaning: For REQUEST=MOVEWAITER, NEWCONTROL=SHARED. If granted, the requester represented by the MovingWaiter ENQToken would have become the owner of the resource because it would immediately follow a shared owner. Action: Make sure that the BeforeRequester ENQToken represents the requester that the moving waiter should precede.
08	xxxx0815	Equate Symbol: ISGADMINRsn_CannotMakeAnotherOwner Meaning: For REQUEST=MOVEWAITER. If granted, one or more requesters queued after the one represented by the MovingWaiter ENQToken would have become the owner of the resource. Action: Make sure that the MOVEWAITER request would not make any other waiting requesters the owner of the resource.
08	xxxx0816	Equate Symbol: ISGADMINRsn_AlreadyLastRequester Meaning: For REQUEST=MOVEWAITER, TOTHEEND=YES. The requester represented by the MovingWaiter ENQToken is already at the end of the request queue. Action: Make sure that the MovingWaiter ENQToken represents a requester at the correct position and that the request queue is as expected.
08	xxxx0817	Equate Symbol: ISGADMINRsn_CannotMoveMasidUser Meaning: For REQUEST=MOVEWAITER. The MovingWaiter ENQToken represents a MASID user. Action: Make sure that the MovingWatier ENQToken does not represent a MASID user.
08	xxxx0818	Equate Symbol: ISGADMINRsn_MasidControlConflict Meaning: For REQUEST=MOVEWAITER, NEWCONTROL=SHARED. The requester represented by the MovingWaiter ENQToken would create a bad MASID environment since a shared owner of the resource is a convert-to-exclusive MASID target. Action: Make sure that the requester represented by the MovingWaiter ENQToken would not need to move in the midst of a MASID convert-to-exclusive environment or that the moved requester could maintain a control of Exclusive.
0C	—	Equate Symbol: ISGADMINRc_EnvError Meaning: ISGADMIN request has an environment error. Action: Refer to action under the individual reason code.
0C	xxxx0C01	Equate Symbol: ISGADMINRsn_NotAuthorized Meaning: An unauthorized caller invoked the ISGADMIN service. Action: An ISGADMIN caller must be authorized.
0C	xxxx0C02	Equate Symbol: ISGADMINRsn_FRRHeld Meaning: The caller issued ISGADMIN when an FRR was established. Action: Avoid issuing ISGADMIN when using functional recovery routines.
0C	xxxx0C03	Equate Symbol: ISGADMINRsn_LockHeld Meaning: A lock was held upon entry. No locks may be held when calling ISGADMIN. Action: Avoid using ISGADMIN when locks are held.
0C	xxxx0C04	Equate Symbol: ISGADMINRsn_SrbMode Meaning: SRB mode. Action: SRB mode is not supported.
0C	xxxx0C05	Equate Symbol: ISGADMINRsn_NotEnabled Meaning: Not Enabled. Action: Avoid using ISGADMIN when not enabled.
0C	xxxx0C06	Equate Symbol: ISGADMINRsn_QueueDamage1 Meaning: The GRS resource queue structure for the target resource is damaged. Further processing against the queue is not allowed. Action: Prevent any further processing against the target resource.
0C	xxxx0C07	Equate Symbol: ISGADMINRsn_QueueDamage2 Meaning: The GRS resource queue structure for the target resource is damaged. Further processing against the queue is not allowed. Action: Prevent any further processing against the target resource.
10	—	Equate Symbol: ISGADMINRc_CompError Meaning: Component Error Action: Contact the IBM Support Center. Provide the reason code which contains diagnostic data.

Examples

    * ***********************************************************************
    *  Set the unauthorized ENQ maximum for the home address space                 
    * ***********************************************************************
 
             ISGADMIN REQUEST=SETENQMAX,                                   X
                MAXTYPE=UNAUTHORIZED,MAXVALUE=MYVALUE,                  X
                RETCODE=MYRC,RSNCODE=MYRSN

    * ***********************************************************************
    *  Reset the unauthorized ENQ maximum of the home address space              
    * ***********************************************************************
 
             ISGADMIN REQUEST=RESETENQMAX,                                 X
                MAXTYPE=UNAUTHORIZED,                                   X
                RETCODE=MYRC,RSNCODE=MYRSN

    * ***********************************************************************
    *  Move an ENQ Waiter                
    * ***********************************************************************
 
              ISGADMIN REQUEST=MOVEWAITER,                                  X
                 MOVINGWAITER=mywaiterENQToken,                             X
                 TOTHEEND=NO,                                               X
                   BEFOREREQUESTER=mybeforerequesterENQToken,               X
                 RETCODE=MYRC,RSNCODE=MYRSN

For more information about global resource serialization, see z/OS MVS Planning: Global Resource Serialization.