- 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)
⋮