- ATRIRRI is for AMODE(31) callers.
- ATR4IRRI is for AMODE(64) callers and allows parameters in 64
bit addressable storage.
The resource manager calls the Respond_to_Retrieved_Interest service
to tell RRS how to process an interest in an incomplete unit of recovery
(UR). During restart, your resource manager must retrieve its interests
in repetitive calls to the Retrieve_UR_Interest service; every call
that retrieves an interest must be followed by a Respond_to_Retrieved_Interest
call, which tells RRS that:
- RRS should continue processing the UR by invoking the resource
manager's exit routines.
- The resource manager has completed work for this interest in the
UR. RRS should delete this interest.
In response to the call, RRS returns a return code.
RRS Actions for Incomplete URs: If the response_code you
specify on the Respond_to_Retrieved_Interest call is ATR_RESPOND_CONTINUE,
RRS processing is summarized in Table 1.
The usual resource manager role is participant, but the Set_Syncpoint_Controls
call can specify a different role. The
action RRS takes for each incomplete UR depends on the UR state and
the resource manager role.
Table 1. Actions for Incomplete
URsUR state |
Resource manager role |
Response code |
RRS action for continue |
---|
In-doubt |
Participant |
Continue |
Invokes the COMMIT or BACKOUT exit routine after the UR state
is resolved |
In-doubt |
Distributed syncpoint resource manager |
Continue |
Invokes the DISTRIBUTED_SYNCPOINT exit routine to resolve the in-doubt UR
state |
In-doubt |
Server distributed syncpoint resource manager |
Continue |
Prepares for eventual Commit_Agent_UR or Backout_Agent_UR. |
In-commit |
Any |
Continue or complete |
For continue, RRS invokes the COMMIT exit routine. For complete,
it does not. |
In-backout |
Any |
Continue or complete |
For continue, RRS invokes the BACKOUT exit routine. For complete,
it does not. |
Note: If a resource manager calls
Respond_to_Retrieved_Interest in Restart state and specifies
ATR_RESPOND_CONTINUE, RRS does not invoke any exits for any of the
resource manager's interests until the resource manager calls the
End_Restart service.
|
The installation cannot resolve the in-doubt state of a
UR through RRS ISPF panels between the time when the resource manager
sets its RRS exit routines and the time when a resource manager responsible
for resolving the UR specifies ATR_RESPOND_CONTINUE. It is thus a
good idea to design the resource manager so that this time is as short
as possible.
Complete URs: Your resource manager should call the Respond_to_Retrieved_Interest
service with a response_code of ATR_RESPOND_COMPLETE
when a Retrieve_UR_Interest call returns a UR that your resource manager
has completed,
Nonpersistent Interest Data: The Respond_to_Retrieved_Interest
call can also provide nonpersistent interest data. RRS ignores nonpersistent
interest data if the call specifies ATR_RESPOND_COMPLETE. Otherwise,
RRS gives this data to each of the resource manager's exit routines
that it invokes for this interest. This data is not recorded in nonvolatile
storage and is not available at subsequent restarts.
Your resource manager can retrieve nonpersistent interest data
in a call to the Retrieve_UR_Interest_Data service.
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 (ATRIRRI)
64 bit (ATR4IRRI)
|
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 UR interest token specified in the call must be in either Restart state
or Run state.
The state of the specified UR must be in-doubt, in-commit,
or in-backout.
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 ATRIRRI
|
(return_code
,ur_interest_token
,response_code
,nonpersistent_interest_data)
|
CALL ATR4IRRI
|
(return_code
,ur_interest_token
,response_code
,nonpersistent_interest_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 Respond_to_Retrieved_Interest
service.
- ,ur_interest_token
- Supplied
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
Is the UR interest token that identifies your resource manager's
interest in the incomplete UR. Your resource manager received the
token from the Retrieve_UR_Interest callable service.
- ,response_code
- Supplied
parameter
- Type: Integer
- Character Set: N/A
- Length: 4 bytes
Indicates how RRS is to respond to the UR interest. Specify
one of the following:
Response Code in:
Hexadecimal
(Decimal)
Equate Symbol
|
Response |
---|
X'0'
(0)
ATR_RESPOND_CONTINUE
|
RRS should continue processing the UR by invoking the resource
manager's exit routines. If the resource manager is in Restart state,
RRS does not invoke the exit routines until the resource manager has
called the End_Restart service.
|
X'1'
(1)
ATR_RESPOND_COMPLETE
|
The resource manager has completed work for this interest in
the UR. RRS should delete this interest. You cannot choose this
response code for a UR that is in-doubt.
|
- ,nonpersistent_interest_data
- Supplied
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
Specifies the nonpersistent interest data for your resource
manager's interest. RRS provides this data to each exit routine it
invokes for the UR but does not record the data in nonvolatile storage.
If you specified a response_code of ATR_RESPOND_COMPLETE,
RRS ignores the data.
ABEND codes
The call might result in an
abend X'5C4' with a reason code of either X'00070000' or X'00070001'.
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.
|
370
ATR_URI_TOKEN_INV
|
Meaning: Program error. The UR interest token specified
in the call is not one of the currently valid interests. The system
rejects the service call. Action: Check the resource manager
for a probable coding error. Correct the resource manager and rerun
it.
|
384
ATR_RESPONSE_CODE_INV
|
Meaning: Program error. The response_code value
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.
|
385
ATR_RESPONSE_CODE_
INCORRECT
|
Meaning: Program error. The response_code value
specified in the call is not correct for the state of the UR or the
role of the resource manager or both. 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 UR interest token specified in the call is not in a valid
state to issue the service call. The resource manager must be in restart
or run state. 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: The resource manager must reset its RRS
exits and begin restart processing with RRS.
|
741
ATR_NOT_RETRIEVED_INTEREST
|
Meaning: Program error. The UR interest token specified
in the call is not for a retrieved interest. The system rejects the
service call. Action: Check the resource manager for a
probable coding error. Correct the resource manager and rerun it.
|
742
ATR_RESPONSE_NOT_PENDING
|
Meaning: Program error. RRS is not expecting a process
interest call for the UR interest token specified in the call.
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.
|
F06
ATR_WAS_NOT_AVAILABLE
|
Meaning: RRS was available to the resource manager,
but went down and came back up again. A commit or backout operation
may or may not have been in progress for the context under which the
Respond_to_Retrieved_Interest was done at the time of the RRS failure.
A new unit of recovery can not be created until the current unit of
recovery is completed.
Action: The system rejects the
service request. Restart your resource manager, making sure to reset
the resource manager's exit routines with RRS.
The resource
manager must inform the application that one of the following actions
must be taken to complete the current unit of recovery: - If a commit or backout request was not active at the time of the
RRS failure, a commit or backout must be requested before a new unit
of recovery can begin.
- If a commit or backout request was active at the time of the RRS
failure, the context must be ended, via the CTXENDC service, before
a new unit of recovery can begin.
|
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 respond to a retrieved interest.
The call requests that RRS invoke the resource manager's exit routines.
⋮
URI_TOKEN = UR_INTEREST_TOKEN
NON_P_DATA = ANCHOR1
RESPCOD = ATR_CONTINUE
CALL ATRIRRI(RC,URI_TOKEN,RESPCOD,NON_P_DATA)
IF RC ≠ ATR_OK THEN
/* Handle error */
⋮