Retrieve_Resource_Manager_Data (CRGRRMD, CRG4RRMD)

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

A resource manager calls the Retrieve_Resource_Manager_Data service to obtain the global data related to a specified resource manager. In response to the call, the system returns:

A return code
The resource manager token
The resource manager global data, which was specified in a call to the Register_Resource_Manager service

Environment

The requirements for the resource manager are:

Minimum authorization:

None

Dispatchable unit mode:

Task or SRB

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31 bit (CRGRRMD)
64 bit (CRG4RRMD

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 and addressable by the resource manager.

Linkage:

Uses standard MVS™ linkage conventions.

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. Retrieve_Resource_Manager_Data (CRGRRMD, CRG4RRMD) Programming requirements
HLL Definition	Description
CRGASM	390 Assembler declarations
CRGC	C/390 declarations

Restrictions

The state of the resource manager associated with the specified resource manager name must be registered.

Resource managers that are PKM 8–15 problem state must register using the Register_Resource_Manager service from the home address space before invoking this service. They must specify a resource manager token of a key 8–15 problem state resource manager that registered from the home address space. Some exit managers may not permit unauthorized resource managers to set exits.

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 CRGRRMD

(return_code
,resource_manager_name
,resource_manager_token
,resource_manager_global_data)

CALL CRG4RRMD

(return_code
,resource_manager_name
,resource_manager_token
,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 Retrieve_Resource_Manager_Data 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. The name must match the name specified on a call to the Register_Resource_Manager service.

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.

,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. The token was assigned when the resource manager called the Register_Resource_Manager service.

,resource_manager_global_data

Returned parameter

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

Receives the global data the resource manager provided when it registered.

ABEND codes

The call might result in an abend X'AC7' with a reason code of either X'00350000' or X'00350001'. 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 2. Retrieve_Resource_Manager_Data (CRGRRMD, CRG4RRMD) 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.
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.
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.
701 CRG_RM_STATE_ERROR	Meaning: Program error. The resource manager is not in a valid state to issue the service call. The resource manager state must be registered. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
756 CRG_AUTH_FAILURE	Meaning: Program error. The resource manager is PKM 8–15 problem state and specified a resource manager token that does not belong to a PKM 8–15 problem state resource manager registered in the home address space. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the calling program and rerun it.
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 retrieve its global data. Storage for the call parameters has been allocated.

⋮
RM_TOKEN = MY_RM_TOKEN
CALL CRGRRMD(RC,RM_NAME,RM_TOKEN,RM_DATA)
⋮