|
The resource manager calls the Retrieve_UR_Data service to retrieve
data for a unit of recovery (UR). There are four versions of Retrieve_UR_Data,
each with different parameters. - ATRRURD is for AMODE(31) callers and is the basic version of the
service. It must be called specifying a UR interest token.
- ATRRURD1 is for AMODE(31) callers and can be called specifying
either a UR token or a UR interest token, and also supports the states
option parameter.
- ATRRURD2 is for AMODE(31) callers and can be called specifying
either a UR token or a UR interest token, supports the states option
parameter, and returns a UR token for a new unit of recovery.
- ATR4RURD is for AMODE(64) callers, allows parameters in 64 bit
addressable storage, and can be called specifying either a UR token
or a UR interest token, supports the states option parameter, and
returns a UR token for a new unit of recovery.
Code your resource manager to call the version that includes
the support you need. In response to the call, RRS returns: - A return code
- The UR identifier (URID)
- The UR state: in-reset, in-flight, in-state-check, in-prepare, in-doubt, in-commit, in-backout, in-end, in-only-agent, in-completion,
or in-forget.
- For ATRRURD2 calls, the UR token
For ATRRURD1, ATRURD2, and ATR4URD callers, the list
of returned states is dependent on the value specified in the states_option.
Environment The requirements for the caller
are:
Minimum authorization: |
None |
Dispatchable unit mode: |
Task or SRB |
Cross memory mode: |
Any PASN, any HASN, any SASN |
AMODE: |
31 bit (ATRRURD, ATRRURD1, ATRRURD2)
64 bit (ATR4RURD)
|
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 state of the resource
manager associated with the specified nonzero UR interest
token must be: - Restart, which means it has registered, set its exit routines
with RRS, begun restart, and requested incomplete UR interests. Because
Retrieve_UR_Data must supply a UR interest token as input, your resource
manager must have called the Retrieve_UR_Interest service to retrieve
this token for a restart UR interest.
- Run, which means it has registered, set its exit routines
with RRS, and completed restart
When the resource manager issues the call in SRB mode, the
call cannot specify a ur_interest_token or ur_or_uri_token of
0, indicating information for the current UR.
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 IBM® recommends using ATR_EXTENDED_STATES for
states_option when a neither a UR identifier nor a URI token is needed.
This will give you better performance and reduce use of system storage.
Syntax Write the appropriate call as shown
in the syntax diagrams. You must code the parameters in the CALL
statement as shown.
CALL ATRRURD
|
(return_code
,ur_interest_token
,ur_identifier
,ur_state)
|
CALL ATRRURD1
|
(return_code
,ur_or_uri_token
,ur_identifier
,ur_state
,states_option)
|
CALL ATRRURD2
|
(return_code
,ur_or_uri_token
,ur_identifier
,ur_state
,states_option
,ur_token)
|
CALL ATR4RURD
|
(return_code
,ur_or_uri_token
,ur_identifier
,ur_state
,states_option
,ur_token)
|
Parameters The parameters are explained
as follows: - return_code
- Returned parameter
- Type: Integer
- Length: 4 bytes
Contains the return code from the Retrieve_UR_Data service.
- ,ur_interest_token
- Supplied
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
For ATRRURD callers, specifies a token that uniquely identifies
your resource manager's interest in the UR whose data you want to
retrieve. Your resource manager received the token from one of the
following services: Express_UR_Interest, Retrieve_Interest_Data, Retain_Interest.
When
specifying the token, use one of the following: - 0: Binary zeros specify the UR data associated with the current
context of the current dispatchable unit.
- token: The UR interest token for an interest in a UR.
- ,ur_or_uri_token
- Supplied
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
For ATRRURD1 or ATRRURD2 callers, specifies a token that
uniquely identifies either the UR, or your resource manager's interest
in the UR, whose data you want to retrieve: - 0: Binary zero specifies the current UR associated with the application
task.
- UR token: The token for the UR.
- UR interest token: The UR interest token that identifies your
resource manager's interest in the UR.
Your resource manager received the token from one of the following
services: Express_UR_Interest, Retrieve_Interest_Data, Retain_Interest,
Create_Cascaded_UR, or Retrieve_UR_Data.
Because you may pass
two different types of tokens through this parameter, passing an invalid
token can generate either a ATR_URI_TOKEN_INV or a ATR_UR_TOKEN_INV
return code. For example, passing an invalid UR token might result
in an ATR_URI_TOKEN_INV return code. Even though a UR token was passed,
if it is invalid, then RRS may not understand what sort of token it
was supposed to be. For this reason, IBM recommends
callers check both return codes, even when they know what type of
token they intend to pass.
- ,ur_identifier
- Returned
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
If the returned UR_state is
not ATR_IN_RESET, receives from the service the UR identifier
(URID) that uniquely identifies the UR. If the returned UR_state is
ATR_IN_RESET, contains binary zero.
- ,ur_state
- Returned
parameter
- Type: Integer
- Length: 4 bytes
Receives from the service the state of the UR. The UR state
is indicated by one of the following: Constant in:
Hexadecimal
(Decimal)
Equate Symbol
|
UR state |
---|
0
(0)
ATR_IN_RESET
|
In-reset This value is only returned if states_option is
ATR_EXTENDED_STATES. |
1
(1)
ATR_IN_FLIGHT
|
In-flight |
2
(2)
ATR_IN_STATE_CHECK
|
In-state-check |
3
(3)
ATR_IN_PREPARE
|
In-prepare |
4
(4)
ATR_IN_DOUBT
|
In-doubt |
5
(5)
ATR_IN_COMMIT
|
In-commit |
6
(6)
ATR_IN_BACKOUT
|
In-backout |
7
(7)
ATR_IN_END
|
In-end |
8
(8)
ATR_IN_ONLY_AGENT
|
In-only-agent |
9
(9)
ATR_IN_COMPLETION
|
In-completion |
B
(11)
ATR_IN_FORGET
|
In-forget |
- ,states_option
- Supplied
parameter
- Type: Integer
- Length: 4 bytes
For ATRRURD1 or ATRRURD2 callers, defines what states RRS
may return for the specified UR. Specify one of the following: Constant in:
Hexadecimal
(Decimal)
Equate Symbol
|
UR state |
---|
0
(0)
ATR_STANDARD_STATES
|
One of the following states will be returned: In-flight, In-state-check, In-prepare, In-doubt, In-commit, In-backout, In-end, In-only-agent, In-completion,
or In-forget. A URID will always be returned in UR_state.
|
1
(1)
ATR_EXTENDED_STATES
|
One of the following states will be returned: In-reset, In-flight, In-state-check, In-prepare, In-doubt, In-commit, In-backout, In-end, In-only-agent, In-completion,
or In-forget. If In-reset is returned for UR state,
the value returned in UR_identifier will
always be binary zero (which is not a valid URID).
|
If ATR_STANDARD_STATES is specified and the UR was In-reset,
the UR is changed to the In-flight state. An In-flight UR
cannot be made into a cascaded UR.
- ur_token
- Returned parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
For ATRRURD2 callers, receives the UR token that uniquely
represents the new unit of recovery.
Note: UR tokens do not persist
across restarts of the resource manager, RRS, or the system.
ABEND codes The call might result in an
abend X'5C4' with a reason code of either X'000C0000' or X'000C0001'.
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.
|
104
ATR_MODE_INV
|
Meaning: Program error. The calling program specified
0 in context_token, indicating the current
context, but the calling program is not in task mode. The system rejects
the service call. Action: Check the calling program for
a probable coding error. Correct the calling program 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 does not identify one of the currently valid interests.
If the specified token is not a valid UR or URI token, RRS may return
this return code even if the resource manager was attempting to specify
a UR token. The system rejects the service call. Action:
Check the resource manager for a probable coding error. Correct
the resource manager and rerun it.
|
398
ATR_STATES_OPTION_INV
|
Meaning: Program error. The state option specified
in the call is not valid. The system rejects the service call. Action:
Check the calling program for a probable coding error. Correct the
calling program and rerun it.
|
3A3
ATR_UR_TOKEN_INV
|
Meaning: Program error. The UR token specified in the
call does not identify a valid UR. If the specified token is not a
valid UR or URI token, RRS may return this return code even if the
resource manager was attempting to specify a URI token. 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 state must be restart or 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.
|
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
Retrieve_UR_Data 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 request data about the current UR.
Storage for the call parameters has been allocated. ⋮
URI_TOKEN = 0
STATES_OPT = ATR_STANDARD_STATES
CALL ATRRURD2(RC,URI_TOKEN,URID,UR_STATE,STATES_OPT,
UR_TOKEN)
IF RC = ATR_OK THEN
CURRENT_URID = URID
CURRENT_STATE = UR_STATE
CURRENT_URTOKEN = UR_TOKEN
⋮
|