- ATRIRNI is for AMODE(31) callers.
- ATR4IRNI is for AMODE(64) callers and allows parameters in 64
bit addressable storage.
When restarting, a resource manager calls the Retrieve_UR_Interest
service to retrieve information about its interest in an incomplete,
protected unit of recovery (UR). In response to the call, RRS returns:
- A return code.
- The context token for the current context of the incomplete UR.
- The UR interest token to identify the resource manager's interest
in the incomplete UR. You need this token for many calls to RRS services.
- The UR identifier (URID) for the incomplete UR.
- The role the resource manager has in the UR interest: participant,
last agent participant, distributed syncpoint resource manager, or
server distributed syncpoint manager. For a description of each role,
see Set_Syncpoint_Controls (ATRSSPC, ATR4SSPC).
- The state of the incomplete UR: in-doubt, in-commit,
or in-backout.
- The length of the persistent interest data.
- The persistent interest data.
Note: RRS does not return information about URs in local transaction
mode.
After the call, the resource manager should call the Respond_to_Retrieved_Interest
service to process the incomplete UR interest. If the resource manager
does not call the Respond_to_Retrieved_Interest service, RRS will
return the incomplete UR interest in a Retrieve_UR_Interest call each
time the resource manager restarts until the resource manager completes
processing of the UR interest or RRS undergoes a cold start.
URID: When your resource manager was
running at an earlier time, it saved, with the UR data in its resource
manager log, the URID returned by any of the following services: Express_UR_Interest,
Retrieve_UR_Data, Change_Interest_Type, or Retain_Interest. The Retrieve_UR_Interest
call provides your resource manager with the URID for an incomplete
UR. Compare the URID from the Retrieve_UR_Interest call with URIDs
in your resource manager log to find the data for the incomplete UR.
If your resource manager log includes a URID for
an incomplete UR that is not returned by any Retrieve_UR_Interest
call, do not make the UR's changes in the resource; treat the UR as
though its state was
in-backout. In contrast, if Retrieve_UR_Interest
returns an incomplete UR that is not in your resource manager log,
tell RRS that the UR interest is complete. After a successful Internal
Cold Start, in response to a log stream error against the RRS RM.DATA
log stream as identified by message:
ATR250E RRS LOGSTREAM ERROR FOUND. CORRECT THE ERROR OR OPTIONALLY REPLY
COLDSTART TO BEGIN A RRS INTERNAL COLD START.
complete
URs could be returned. If the UR is not in your resource manager log,
tell RRS that the UR interest is complete.
Specifying retrieve interest calls: Your resource manager
should call the Retrieve_UR_Interest service repeatedly to receive
UR data for all of its incomplete interests. If the resource manager
expressed protected interest multiple times for one UR, the Retrieve_UR_Interest
service returns each interest separately. When all UR interests have
been returned, the call returns the ATR_NO_MORE_INCOMPLETE_INTERESTS code.
Note: Retrieve_UR_Interest can be invoked in parallel. (It can be
called from multiple threads simultaneously.) If you exploit the parallel
retrieval of interests, then you should continue retrieving interests
until all parallel threads receive the ATR_NO_MORE_INCOMPLETE_INTERESTS return
code, not just the first thread.
UR states: The states given for the incomplete URs are:
- In-doubt: The state of the incomplete UR needs to be resolved.
- In-commit: The failure occurred after the UR was committed,
but before the log record was physically deleted from the RRS log.
The resource manager should change the resource.
- In-backout: The resource manager should not change the
resource because the UR was to be backed out.
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 (ATRIRNI)
64 bit (ATR4IRNI)
|
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 mode: |
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 state of the resource
manager associated with the specified resource manager token must
be restart, which means it has registered, set its exit routines
with RRS, and begun 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 ATRIRNI
|
(return_code
,resource_manager_token
,context_token
,ur_interest_token
,ur_identifier
,role
,ur_state
,persistent_interest_buffer_length
,persistent_interest_data_length
,persistent_interest_data)
|
CALL ATR4IRNI
|
(return_code
,resource_manager_token
,context_token
,ur_interest_token
,ur_identifier
,role
,ur_state
,persistent_interest_buffer_length
,persistent_interest_data_length
,persistent_interest_data)
|
Parameters
The parameters are explained
as follows:
- return_code
- Returned parameter
- Type: Integer
- Length: 4 bytes
Contains the return code from the Retrieve_UR_Interest 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.
- ,context_token
- Returned
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
Receives from the service the context token that identifies
the current context for the incomplete UR.
- ,ur_interest_token
- Returned
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
Receives from the service the UR interest token that identifies
your resource manager's interest in the incomplete UR.
- ,ur_identifier
- Returned
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
Receives from the service a UR identifier that uniquely
identifies the UR.
- ,role
- Returned
parameter
- Type: Integer
- Length: 4 bytes
Receives from the service the role of the resource manager
in the UR interest identified by the returned UR interest token. If
your resource manager is not a participant, your resource manager
specified its role through a Set_Syncpoint_Controls call. The role
is indicated by one of the following:
Constant in:
Hexadecimal
(Decimal)
Equate Symbol
|
Role |
---|
0
(0)
ATR_PARTICIPANT
|
Participant |
1
(1)
ATR_LAST_AGENT
|
Last-agent participant |
2
(2)
ATR_DSRM
|
Distributed syncpoint resource manager |
3
(3)
ATR_SDSRM
|
Server distributed syncpoint resource manager |
For more information about each role, see Set_Syncpoint_Controls (ATRSSPC, ATR4SSPC).
- ,ur_state
- Returned
parameter
- Type: Integer
- Length: 4 bytes
Receives from the service the state of the incomplete UR.
The UR state is indicated by one of the following:
Constant in:
Hexadecimal
(Decimal)
Equate Symbol
|
UR state |
---|
4
(4)
ATR_IN_DOUBT
|
In-doubt |
5
(5)
ATR_IN-COMMIT
|
In-commit |
6
(6)
ATR_IN-BACKOUT
|
In-backout |
- ,persistent_interest_buffer_length
- Supplied
parameter
- Type: Integer
- Length: 4 bytes
Specifies the length of the buffer that your resource manager
provides for the persistent interest data. The value can be X'0' -X'1000' (0
- 4096).
- ,persistent_interest_data_length
- Returned
parameter
- Type: Integer
- Length: 4 bytes
Receives from the service the actual length of the persistent
interest data. The value can range from X'0' to X'1000' (4096),
where 0 indicates that there is no data.
- ,persistent_interest_data
- Returned
parameter
- Type: Character string
- Character Set: No restriction
- Length: Specified on persistent_interest_buffer_length
Provides a buffer to receive persistent interest data from
the service. Your resource manager provided the data in a call to
one of the following services: Express_UR_Interest, Change_Interest_Type,
Set_Persistent_Interest_Data, or Retain_Interest.
Your resource
manager can also retrieve persistent interest data from the Retrieve_Interest_Data
(ATRRID) service (see the topic on Retrieve_Interest_Data (ATRRID, ATR4RID)).
ABEND codes
The call might result in an
abend X'5C4' with a reason code of either X'00060000' or X'00060001'.
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.
|
4
ATR_NO_MORE_INCOMPLETE_
INTERESTS
|
Meaning: Normal processing. RRS has no more incomplete
UR interests for your resource manager. The parameters do not contain
valid data. Action: Call the end restart service to complete
restart processing.
|
5
ATR_PARTIAL_PERSISTENT_DATA
|
Meaning: Program error. The persistent_interest_buffer_length value
is less than the actual length of the persistent interest data. The
system accepts the service call. RRS places in the buffer as many
characters of the data as will fit, starting at the left.
Action:
No action is required. If the result is not expected, check the
resource manager for a probable coding error; correct the resource
manager and rerun it.
|
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.
|
37D
ATR_PERSIS_DATA_BUF_LEN_INV
|
Meaning: Program error. The length specified for the
persistent interest buffer 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 a
valid state to issue the service call. The resource manager state
must be restart. 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 request its interest in an incomplete
UR. Storage for the call parameters has been allocated.
⋮
RM_TOKEN = MY_RM_TOKEN
PD_BUF_LEN = 256
DO UNTIL (RC=ATR_NO_MORE_INCOMPLETE_INTERESTS)
CALL ATRIRNI(RC,RM_TOKEN,C_TOKEN,URI_TOKEN,URID,ROLE,
UR_STATE,PD_BUF_LEN,PD_DATA_LEN,PD_DATA)
IF RC ≠ 0 THEN
/* Handle error */
END DO
⋮