Register_Resource_Manager (CRGGRM, CRG4GRM)

CRGGRM is for AMODE(31) callers.
CRG4GRM is for AMODE(64) callers and allows parameters in 64 bit addressable storage.

A resource manager calls the Register_Resource_Manager service (CRGGRM) to register itself with the system. In response to the call, the system returns:

A return code
The resource manager token (RM_TOKEN)

A resource manager needs to register before it can issue the required calls to the Set_Exit_Information service to identify itself and its exit routines with exit managers. Note also that the exit routines the resource manager sets are invoked in the same key as the resource manager at the time it calls Set_Exit_Information.

Resource Manager Token: The resource manager token is a random value that is not preserved across restarts of the system, exit manager, or resource manager. Thus:

Do not use the resource manager token as an identifier in resource manager log records.
Do not try to discern the contents of the token or create any dependencies on the contents.

You need this token for calls to the following services: Begin_Context, Begin_Restart, End_Restart, Express_Context_Interest, Express_UR_Interest, Retrieve_UR_Interest, Retrieve_Log_Name, Set_Exit_Information, Set_Log_Name, and Unregister_Resource_Manager.

Resource Manager Global Data: Your resource manager can specify global data in the call to the Register_Resource_Manager service. Exit managers obtain the resource manager's global data from the system and pass this global data to all of the resource manager's exit routines. This data should provide the exit routines with an anchor or anchors to resource manager data structures.

A resource manager cannot change this data without unregistering and then registering again. Therefore, it is a good idea to use the data to identify data structures that the resource manager can modify rather than passing the contents of the structures.

The global data can be retrieved by a call to the Retrieve_Resource_Manager_Data service.

Environment

The requirements for the resource manager are:

Minimum authorization:

None

Dispatchable unit mode:

Task

Cross memory mode:

If PKM 8–15 problem state, PASN=HASN=SASN; otherwise, any PASN, any HASN, any SASN

AMODE:

31 bit (CRGGRM)
64 bit (CRG4GRM)

ASC mode:

Primary or access register (AR)

Interrupt status:

Enabled for I/O and external interrupts

Locks:

No locks held

Control parameters:

Control parameters must be in the primary address space

Linkage:

Standard MVS™ linkage conventions are used.

Programming requirements

Either link edit your object code with the linkable stub routine CRGCSS (31 bit) or CRG4CSS (64 bit) from SYS1.CSSLIB, or LOAD and CALL the service. The high level language (HLL) definitions for the callable service are:

Table 1. Register_Resource_Manager (CRGGRM, CRG4GRM) Programming requirements
HLL Definition	Description
CRGASM	390 Assembler declarations
CRGC	C/390 declarations

Restrictions

To call the service, the resource manager state must be unregistered. After a successful call, the resource manager state is registered.

Resource managers with a PKM allowing PSW key 0–7 or supervisor state must have a PSW key of 0–7 when invoking this service. Resource managers that are PKM 8–15 problem state may not specify CRG_UNREG_EOM for unregister_option.

PKM 8–15 problem state RMs must specify a resource manager name that ends in .UA, followed by enough trailing blanks to make the entire name 32 bytes long.

By default, a single address space may register a maximum of 256 PKM 8–15 problem state resource managers. This limit may be removed by the operator.

Input register information

Before issuing the call, the resource manager does not have to place any information into any register unless using it in register notation for the parameters, or using it as a base register.

Output register information

When control returns to the resource manager, the GPRs contain:

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

When control returns to the resource manager, 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 resource managers depend on register contents remaining the same before and after issuing a call. If the system changes the contents of registers on which the resource manager depends, the resource manager must save them before calling the service, and restore them after the system returns control.

Performance implications

None.

Syntax

Write the call as shown in the syntax diagram. You must code the parameters in the CALL statement as shown.

CALL CRGGRM

(return_code
,resource_manager_name
,resource_manager_token
,unregister_option
,resource_manager_global_data)

CALL CRG4GRM

(return_code
,resource_manager_name
,resource_manager_token
,unregister_option
,resource_manager_global_data)

Parameters

The parameters are explained as follows:

return_code

Returned parameter

Type: Integer
Character Set: N/A
Length: 4 bytes

Contains the return code from the Register_Resource_Manager service.

,resource_manager_name

Supplied parameter

Type: Character string
Character Set: See note
Length: 32 bytes

Specifies the name of the resource manager making the call. For RRS, the name must be unique across a sysplex. For context services, the name must be unique within a system. In either case, the resource manager must use the same name each time it registers.

PKM 8–15 problem state resource managers must specify a resource manager name that ends with the characters .UA and trailing blanks (if they are needed). For example, IEA.GENERAL.SERVER.IBM.UA would be a valid value.

Note: The name can consist of the following printable characters:

Alphanumeric characters: A-Z and 0-9
National characters: $ (X'5B'), # (X'7B'), @ (X'7C')
The period (.)
The underscore (_)
The trailing blank characters needed to fill the 32-byte field

The name may not start with a blank or contain embedded blanks. Lower case characters are folded to upper case characters.

Use the following conventions to avoid name conflicts:

IBM-provided PKM 0–7 or supervisor state programs use A-C or G-I as the first character and .IBM as the ending qualifier.
IBM-provided PKM 8–15 programs use A-C or G-I as the first character and .IBM.UA as the ending qualifier.
Other PKM 0–7 or supervisor state resource managers should begin the name with D-F or J-Z and end the name with a period and the company name or acronym.
Other PKM 8–15 resource managers should begin the name with D-F or J-Z and end the name with a period and the company name or acronym followed by .UA as the ending qualifier.

For example, PKM 0–7 or supervisor state names could be:

IEAV5.IBM
DATAMGR.VENDORCORP
RESMANAGER.GROWTHCOMPANY

PKM 8–15 problem state names could be:

IEAV5.IBM.UA
DATAMGR.VENDORCORP.UA
RESMANAGER.GROWTHCOMPANY.UA

The name specified in this call is also used in a call to the Retrieve_Resource_Manager data service.

,resource_manager_token

Returned parameter

Type: Character string
Character Set: No restriction
Length: 16 bytes

Receives the resource manager token that uniquely identifies the resource manager.

If the resource manager name is already registered, the system returns CRG_RM_NAME_REGISTERED as the return code and returns the token that is already associated with the resource manager name.

,unregister_option

Supplied parameter

Type: Integer
Character Set: N/A
Length: 4 bytes

Indicates how the system is to determine that the resource manager is ending unexpectedly. Specify the event as one of the following:

Table 2. Register_Resource_Manager (CRGGRM, CRG4GRM) unregister_option parameter
Constant in: Hexadecimal (Decimal) Equate Symbol	Description
0 (0) CRG_UNREG_CMRO	Cross memory resource-owning task ends: The system monitors for the ending of the cross memory resource-owning task (the top, or first, job step task in the address space). When the task ends, the system implicitly unregisters the resource manager.
1 (1) CRG_UNREG_CURRENT	Resource manager, which is the current task, ends: The system monitors for the ending of the current task. When it ends, the system implicitly unregisters the resource manager.
2 (2) CRG_UNREG_EOM	The resource manager's address space, which is the home address space, ends: The system monitors for the ending of the current address space. When it ends, the system implicitly unregisters the resource manager. Note: This option cannot be used by PKM 8–15 problem state callers.

,resource_manager_global_data

Supplied parameter

Type: Character string
Character Set: No restriction
Length: 16 bytes

Specifies the global data for the resource manager. The system passes this data to all exit routines for the resource manager.

ABEND codes

The call might result in an abend X'AC7' with a reason code of either X'00330000' or X'00330001'. See z/OS MVS System Codes for the explanations and actions.

Return codes

When the service returns control to the resource manager, GPR 15 and return_code contain a hexadecimal return code.

Table 3. Register_Resource_Manager (CRGGRM, CRG4GRM) Return codes
Return Code in: Hexadecimal Equate Symbol	Meaning and action
0 CRG_OK	Meaning: Successful completion. Action: None.
103 CRG_INTERRUPT_STATUS_INV	Meaning: Program error. The resource manager is disabled; the interrupt status must be enabled for I/O and external interrupts. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
104 CRG_MODE_INV	Meaning: Program error. The resource manager is not in task mode. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
105 CRG_LOCKS_HELD	Meaning: Program error. The resource manager is holding one or more locks; no locks must be held. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
107 CRG_UNSUPPORTED_RELEASE	Meaning: Environmental error. The system release does not support this service. The system rejects the service call. Action: Remove the resource manager from the system, and install it on a system that supports registration services. Then rerun the resource manager.
108 CRG_KEY_INV	Meaning: Program error. The resource manager is in supervisor state, but in an unauthorized key (8-F). The system rejects the service call because it could cause a system integrity exposure. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
10A CRG_XMEM_INV	Meaning: Environment error. The resource manager is PKM 8–15 problem state, but not PASN=HASN=SASN. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
300 CRG_RM_NAME_INV	Meaning: Program error. The resource manager name specified in the call is incorrect. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
302 CRG_UNREGOPT_INV	Meaning: Program error. The unregister_option value specified in the call is not valid, possibly because a PKM 8–15 problem state resource manager used the CRG_UNREG_EOM option. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
700 CRG_RM_NAME_REGISTERED	Meaning: Program error. The resource manager is already registered. The system rejects the service call. However, the system returns the resource manager token in the resource_manager_token field. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
F00 CRG_MAX_RM_EXCEEDED	Meaning: Environment error. There are already 256 PKM 8–15 problem state resource managers registered in the current home address space. The system rejects the service call. Action: Either allow additional resource managers or change your program so less than 256 resource managers are required.
FFF CRG_UNEXPECTED_ERROR	Meaning: System error. The service that was called encountered an unexpected error. The system rejects the service call. Action: Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM® Support Center.

Example

In the pseudocode example, the resource manager issues a call to register. To indicate if the system needs to implicitly unregister the resource manager, the call requests that the system monitor for the ending of the current task.

⋮
RM_NAME = MY_RM_NAME
RM_GL_DATA = MY_GLOBAL_DATA
UNREG_OPT = CRG_UNREG_CURRENT
CALL CRGGRM(RC,RM_NAME,RM_TOKEN,
            UNREG_OPT,RM_GL_DATA)
IF RC = CRG_OK THEN
  MY_RM_TOKEN = RM_TOKEN
⋮