 |
The resource manager calls the Retrieve_Side_Information service
to retrieve side information for an interest in a unit of recovery
(UR). In response to the call, RRS returns: - A return code
- The side information
There are three versions of Retrieve_Side_Information, each
with different parameters. - ATRRUSI is for AMODE(31) callers and is the basic version of the
service. It must be called specifying a UR interest token.
- ATRRUSI2 is for AMODE(31) callers and can be called specifying
either a UR token or a UR interest token.
- ATR4RUSI 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.
Code your resource manager to call the version that includes
the support you need.Side information: The side information is set
by RRS or, in a call to the Set_Side_Information service, by a resource
manager that is interested in the UR. Much of the side information
is set only by a resource manager that uses Systems Network Architecture
(SNA) Logical Unit (LU) 6.2 sync point architecture. See the Set_Side_Information
callable service for a description of side information.
Information about other resource managers: Your resource
manager can use a Retrieve_Side_Information call to obtain information
about another resource manager that is interested in the UR. For example,
if the service returns ATR_NEW_LUWID_PSH_UNACCEPTABLE,
your resource manager knows that an LU 6.2 communications resource
manager cannot send a new LUWID on any LU 6.2 conversation that it
is managing.
Parameter arrays: The side_info_id parameter
is an input array; each position identifies side information the resource
manager wants from RRS. The side_info_state parameter
is an output array; RRS places in each position the side information
requested by the corresponding position in the side_info_id array.
The element_count parameter indicates the
number of positions in both arrays.
For example, if the call specifies in the fourth position of side_info_id ATR_BACKOUT_REQUIRED,
the fourth position of side_info_state will
indicate if backout required is or is not set for the UR interest.
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 (ATRRUSI, ATRRUSI2)
64 bit (ATR4RUSI)
|
| 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 UR interest token must be: - Restart, which means it has registered, set its exit routines
with RRS, begun restart, and requested incomplete UR interests
- Run, which means it has registered, set its exit routines
with RRS, and completed 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 appropriate call as shown
in the syntax diagrams. You must code the parameters in the CALL
statement as shown.
| CALL ATRRUSI
|
(return_code
,ur_interest_token
,element_count
,side_info_id
,side_info_state)
|
| CALL ATRRUSI2
|
(return_code
,ur_or_uri_token
,element_count
,side_info_id
,side_info_state)
|
| CALL ATR4RUSI
|
(return_code
,ur_or_uri_token
,element_count
,side_info_id
,side_info_state)
|
Parameters The parameters are explained
as follows: - return_code
- Returned parameter
- Type: Integer
- Length: 4 bytes
Contains the return code from the Retrieve_Side_Information
service.
- ,ur_interest_token
- Supplied
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
For ATRRUSI callers, specifies a token that uniquely identifies
your resource manager's interest in the UR whose side information
you want to retrieve. Your resource manager received the token from
one of the following services: Express_UR_Interest, Retrieve_Interest_Data,
Retain_Interest.
- ,ur_or_uri_token
- Supplied
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
For ATRRUSI2 callers, specifies a token that uniquely identifies
either the UR, or your resource manager's interest in the UR, whose
side information you want to retrieve: - 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.
- ,element_count
- Supplied
parameter
- Type: Integer
- Length: 4 bytes
Specifies the number of elements in the array for the side_info_id and side_info_state parameters.
Both arrays must have the same number of elements. The maximum count
is 13.
- ,side_info_id
- Supplied
parameter
- Type: Integer
- Length: 4 bytes
Specifies one or more identifiers; each identifier requests
the state of side information that RRS or a resource manager might
have set. When you specify more than one identifier, you must define
an array, where element_count indicates
the number of identifiers. The positions of the identifiers in this side_info_id array
define the positions of the side information states to be returned
in the side_info_state array.
Specify
each identifier as one of the following: | Constant in:
Hexadecimal
(Decimal)
Equate Symbol
|
Identifier |
|---|
| 0
(0)
ATR_HEURISTIC_MIX
|
Heuristic-mixed condition A heuristic commit occurred while
the UR state was in_backout, a heuristic reset occurred while
the UR state was in_commit, or a resource manager of distributed
resources informed RRS of a heuristic-mixed condition. When this
information is initially set through a call to Set_Side_Information,
RRS will harden (or reharden) the UR state, including this identifier,
immediately.
|
| 1
(1)
ATR_BACKOUT_REQUIRED
|
Backout required When this identifier is initially set,
RRS will force the current UR to back out when a syncpoint occurs.
If a UR state has passed beyond in_prepare, RRS ignores this
identifier.
|
| 10
(16)
ATR_BREAK_TREE
|
Break tree When this identifier is initially set, RRS will
reset the logical unit of work identifier (LUWID) for the next UR.
|
| 11
(17)
ATR_DRIVE_BACKOUT
|
Backout of next UR When this identifier is initially set,
RRS will, if any resource manager has called Retain_Interest for the
next UR, complete backout for the next UR before returning control
to the application program. This processing ensures that the next
UR will be backed out.
|
| 12
(18)
ATR_RESYNC_IN_PROGRESS
|
Resync in progress A resync in progress condition has occurred.
If the UR state is before in_end when this identifier is initially
set, RRS will harden (or reharden) the UR state, including this identifier,
at the next state change.
|
| 13
(19)
ATR_NEW_LUWID_PSH_UNACCEPTABLE
|
New LUWID PSH unacceptable A communication resource manager
cannot accept a new LUWID presentation header (PSH). RRS takes no
action when this identifier is set.
|
| 14
(20)
ATR_DRIVE_COMPLETION
|
Invoke completion exit(s) When this identifier is initially
set, RRS will invoke all COMPLETION exit routines, if any exist, when
the UR state reaches in-completion. RRS will harden (or reharden)
the UR state, including this identifier, at the next logging point.
|
| 15
(21)
ATR_SDSRM_INITIATED
|
Syncpoint operation initiated by resource manager When
this identifier is set, the current syncpoint operation was initiated
by a resource manager that has taken the SDSRM role, then called Backout_Agent_UR
or Prepare_Agent_UR. RRS will harden (or reharden) this identifier
whenever it normally hardens (or rehardens) the UR state.
|
| 16
(22)
ATR_RESOLVED_BY_INSTALLATION
|
Installation resolved UR When this identifier is set, an in-doubt UR
has been resolved through the RRS panels or a program that issued
the ATRSRV macro. RRS will harden (or reharden) the UR state, including
this identifier, immediately.
|
| 17
(23)
ATR_TERM_SYNCPOINT
|
Terminating syncpoint When this identifier is set, the
UR is going through syncpoint processing because its context has ended.
(This condition is always true for URs created by restart. When
a resource manager is restarting when RRS has not failed, RRS might
"reconnect" the interest returned through Retrieve_UR_Interest to
an existing UR. In this case, the UR might not be marked for terminating
syncpoint processing.)
|
| 18
(24)
ATR_COMMITTED
|
Committed UR When this identifier is set, the outcome for
the current UR has been determined, and the result is a commit. RRS
always hardens this identifier when it hardens the commit.
|
| 20
(32)
ATR_IMMEDIATE_BACKOUT
|
Application requested backout The backout occurred because
the application, either implicitly or explicitly, requested it, not
because a resource manager could not commit its resources. RRS hardens
this identifier whenever it normally logs status for the UR.
|
| 21
(33)
ATR_APPL_COMPLETE
|
Application processing is complete This identifier indicates
completion of an individual UR in a cascaded UR family. RRS sets this
identifier when it is informed that the application executing for
this UR is complete. RRS will not commit a cascaded UR family until
RRS is informed that all of the individual cascaded URs in the family
are complete. Note: If RRS has not set this identifier, it does not
necessarily mean that the application execution is incomplete; it
just means RRS is unaware of the completion.
|
| 23
(35)
ATR_SI_LOCAL_MODE
|
Local transaction mode When this identifier is set, the
UR is in local transaction mode and ATR_SI_GLOBAL_MODE cannot be set.
When neither ATR_SI_LOCAL_MODE nor ATR_SI_GLOBAL_MODE is set, the
transaction mode is hybrid-global.
|
| 24
(36)
ATR_SI_GLOBAL_MODE
|
Implicit global transaction mode When this identifier is
set, the UR is in global transaction mode and ATR_SI_LOCAL_MODE cannot
be set. When neither ATR_SI_LOCAL_MODE nor ATR_SI_GLOBAL_MODE is set,
the transaction mode is hybrid-global.
|
- ,side_info_state
- Returned
parameter
- Type: Integer
- Length: 4 bytes
Receives one or more indicators from the service. Each
indicator shows whether or not its matching identifier is set in the
side information. This array must have the same number of positions
as the side_info_id array. For each identifier,
the service returns one of the following: | Constant in:
Hexadecimal
(Decimal)
Equate Symbol
|
State of the side information |
|---|
| 0
(0)
ATR_SIDE_VALUE_NOT_SET
|
Side value not set: The side information value is not
set. Neither RRS nor a resource manager has set it, or it has been
reset. |
| 1
(1)
ATR_SIDE_VALUE_SET
|
Side value set: Either RRS or a resource manager set
the side information value. |
ABEND codes The call might result in an
abend X'5C4' with a reason code of either X'000D0000' or X'000D0001'.
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 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.
|
| 383
ATR_SIDE_INFO_ID_INV
|
Meaning: Program error. The identifier for a side information
value in the side_info_id parameter 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.
|
| 392
ATR_ELEMENT_COUNT_INV
|
Meaning: The specified element count is not valid.
Action: Check the resource manager for a probable coding
error. Correct the resource manager 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_Side_Information 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 side information for an
interest in a UR. Storage for the call parameters has been allocated.
⋮
URI_TOKEN = UR_INTEREST_TOKEN
COUNT = 2
ID(1) = ATR_HEURISTIC_MIX
ID(2) = ATR_RESYNC_IN_PROGRESS
CALL ATRRUSI2(RC,URI_TOKEN,COUNT,ID,STATE)
IF RC = ATR_OK THEN
HM = STATE(1)
RIP = STATE(2)
⋮
|
z/OS MVS Programming: Resource Recovery
Copyright IBM Corporation 1990, 2014