Set_RM_Metadata (ATRSDTA, ATR4SDTA)

ATRSDTA is for AMODE(31) callers.
ATR4SDTA is for AMODE(64) callers, and allows parameters in 64 bit addressable storage.

A resource manager calls the Set_RM Metadata service to give up to 8K (8192) bytes of data to RRS. RRS will harden the data.

Environment

The requirements for the resource manager are:

Minimum authorization:

PKM allowing key 0-7, or supervisor state

Dispatchable unit mode:

Task or SRB

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31 bit (ATRSDTA)
64 bit (ATR4SDTA)

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

Linkage:

Standard MVS™ linkage conventions are used.

Programming requirements

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

HLL definition	Description
ATRRASM	390 Assembler declarations
ATRRC	C/390 declarations

Restrictions

The resource manager associated with the specified resource manager token must be in Run state, which means it has been registered, set its exit routines with RRS, and completed restart.

Input register information

Before issuing the call, the caller 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 caller, 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 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 call. If the system changes the contents of registers on which the caller depends, the caller 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 ATRSDTA

(return_code
,resource_manager_token
,rm_metadata_len
,rm_metadata)

CALL ATR4SDTA

(return_code
,resource_manager_token
,rm_metadata_len
,rm_metadata)

Parameters

The parameters are explained as follows:

return_code

Returned parameter

Type: Integer
Length: 4 bytes

Contains the return code from the Set_RM_Metadata service.

,resource_manager_token

Supplied parameter

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

Specifies the resource manager token that identifies the resource manager. Your resource manager received the token from the Register_Resource_Manager service.

,rm_metadata_len

Supplied parameter

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

Length of the data specified by the rm_metadata keyword. The maximum amount of metadata that can be given to RRS to store is 8192 bytes. If a length of zero is specified, RRS deletes the resource manager's metadata from the log stream.

,rm_metadata

Supplied parameter

Type: Character string
Character Set: No restriction
Length: Specified in rm_metadata_len

Specifies the resource manager's metadata you want RRS to store.

ABEND codes

The call might result in an abend X'5C4' with a reason code of either X'00280000' or X'00280001'. 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.

Return Code in: Hexadecimal Equate Symbol	Meaning and action
0 ATR_OK	Meaning: Successful completion. Action: None.
103 ATR_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 ATR_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 ATR_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.
301 ATR_RM_TOKEN_INV	Meaning: Program error. The resource manager token 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.
38A ATR_RM_METADATA_LEN_INV	Meaning: Program error. The length of the resource manager metadata specified in the call is not valid. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
38C ATR_RM_METADATA_LOG_ UNAVAILABLE	Meaning: The MetaData callable service failed since the resource manager MetaData log stream is not available. Action: Check SYSLOG for messages ATR132I or ATR172E that will further explain why the log is unavailable.
38D ATR_RM_8K_METADATA_NOT_ ALLOWED	Meaning: The resource manager did not set the ATR_8K_RM_METADATA_REQUESTED flag on Set Exit Information (CRGSEIF, CRGSEIF1,and CRG4SEIF) so the resource manager cannot set or retrieve 8K Meta Data. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
38E ATR_RM_METADATA_MISSING_DATA	Meaning: When reading from the RM Meta Data log stream, records were encountered that indicate there was a loss of data or a gap in the log stream. If Meta Data was stored for the RM, it cannot be found. Action: Check SYSLOG for messages ATR202D and ATR212I that will further explain the error and how to correct it.
701 ATR_RM_STATE_ERROR	Meaning: The resource manager associated with the resource manager token specified in the call is not in a valid state to issue the service call. The resource manager state must be run. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
702 ATR_RM_EXITS_UNSET	Meaning: Program error. RRS has unset the RRS exit routines for the resource manager. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
F00 ATR_NOT_AVAILABLE	Meaning: RRS is not available. Action: The system rejects the service request. Retry the request later. Before retrying the request, the resource manager must reset its RRS exit routine information and begin restart processing with RRS.
FFF ATR_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 give its RM Metadata to RRS.

.
.
.
RM_TOKEN = MY_RM_TOKEN 
META_LEN = MY_META_LEN 
META = MY_META
CALL ATRSDTA(RC,RM_TOKEN,META_LEN,META) 
IF RC=0 THEN 
.
.
.