Begin_Restart (ATRIBRS, ATR4IBRS)

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

A resource manager calls the Begin_Restart service to begin resource manager restart. Before calling Begin_Restart, your resource manager should call the Retrieve_Log_Name service to check log names and tokens to make sure the restart logs are the same as the previous logs. After calling Begin_Restart, your resource manager should call the Retrieve_UR_Interest service repetitively to obtain your interests in incomplete units of recovery (URs).

In response to the Begin_Restart call, RRS issues a return code. If the code is ATR_HARDENED_DATA_LOST, some hardened data, which is stored in an RRS log on nonvolatile external storage, has been lost; the calls to the Retrieve_UR_Interest service might not return all of your interests in incomplete URs. In this case, your resource manager should not back out any URs that the Retrieve_UR_Interest service does not return.

Cold Starts: If hardened data was lost from an RRS log, this restart might appear as a cold start. Your resource manager can recognize a cold start when its call to the Retrieve_Log_Name service does not return the name of its previous resource manager log.

Your resource manager's first start is always a cold start.

Environment

The requirements for the caller 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 (ATRIBRS)
64 bit (ATR4IBRS)

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

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 resource manager token specified in the call must be in set state, which means it has registered and set its exit routines with RRS. After a successful Begin_Restart call, the resource manager enters the restart state.

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

Calls to the Begin_Restart service can significantly affect performance because two events must be serialized across the sysplex:

RRS initialization
Begin_Restart calls from other resource managers

Also, while processing the call, RRS might need to read one or more logs.

Syntax

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

CALL ATRIBRS

(return_code
,resource_manager_token)

CALL ATR4IBRS

(return_code
,resource_manager_token)

Parameters

The parameters are explained as follows:

return_code

Returned parameter

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

Is a fullword that receives an integer return code from the service.

,resource_manager_token

Supplied parameter

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

Is the resource manager token. The token is a 16-byte character string that identifies the resource manager. Your resource manager received the token from the Register_Resource_Manager service.

ABEND codes

The call might result in an abend X'5C4' with a reason code of either X'00030000' or X'00030001'. 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 RRS. Then rerun the resource manager.
301 ATR_RM_TOKEN_INV	Meaning: Program error. The resource manager token 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.
701 ATR_RM_STATE_ERROR	Meaning: Program error. The resource manager associated with the resource manager token specified in the call is not in set state. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
738 ATR_RM_ATTR_INC	Meaning: Program error. For the incomplete UR interests, the resource manager had not issued Set_Exit_Information calls to set all of the required exit routines. For example, if the resource manager has a distributed syncpoint role, a DISTRIBUTED_SYNCPOINT exit routine is required. However, the resource manager has not called Set_Exit_Information to set a DISTRIBUTED_SYNCPOINT exit routine. 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.
F01 ATR_HARDENED_DATA_LOST	Meaning: System error. RRS has lost some hardened data. The system accepts the Begin_Restart call, but following calls to the Retrieve_UR_Interest service might not return all of the incomplete UR interests. Action: The resource manager should process the incomplete URs obtained from the Retrieve_UR_Interest service. The resource manager should not, however, back out any URs that Retrieve_UR_Interest does not return.
F02 ATR_RESTART_WRONG_SYSTEM	Meaning: Environmental error. The resource manager is not restarting on the correct system. The resource manager's incomplete URs are on another system in the sysplex. The system rejects the service call. Action: Restart the resource manager on the correct system.
F07 ATR_RM_GROUP_RRS_DOWNLEVEL	Meaning: Environmental error. The restarting Resource Manager belongs to an RM group which has utilized an RRS function that is not supported by this version of RRS. The RRS on this system is downlevel and cannot honor the request to restart. The system rejects the service call. Action: Restart the resource manager on the correct system.
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 begin its restart.

⋮
RM_TOKEN = MY_RM_TOKEN
CALL ATRIBRS (RC,RM_TOKEN)
⋮