|
The resource manager calls the Set_Side_Information service to
set side information for an interest in a unit of recovery (UR).
In response to the call, RRS returns a return code. There are
three versions of Set_Side_Information, each with different parameters. - ATRSUSI is for AMODE(31) callers and is the basic version of the
service. It must be called specifying a UR interest token.
- ATRSUSI2 is for AMODE(31) callers and can be called specifying
either a UR token or a UR interest token.
- ATR4SUSI 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 Set_Side_Information, 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. The side information, defined in
the side_info_id parameter, indicates the
following: - Heuristic-mixed condition
- Backout required
- Break tree
- Backout of next UR
- Resync in progress
- New LUWID presentation header (PSH) unacceptable
- Invoke completion exits
- Application complete
- Reset application complete
Your resource manager can call the Retrieve_Side_Information service
to retrieve side information.
Parameter Array: The side_info_id parameter
is an input array; each position provides side information to RRS.
The element_count parameter indicates the
number of positions in the array.
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 (ATRSUSI, ATRSUSI2)
64 bit (ATR4SUSI)
|
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 run,
which means it has registered, set its exit routines with RRS, and
completed restart.
For a UR in local transaction mode, the
only side_info_id you can specify is ATR_DRIVE_COMPLETION.
If
the resource manager returns ATRX_LATER_CONTINUE from its END_UR exit,
then this service cannot be called to set ATR_BREAK_TREE at any time
after that point for this expression of interest.
A caller
that is PKM 8–15 problem state must specify a UR_token for
a UR that is either: - Associated with a DU native context associated with a task in
the current home address space, or
- A private context owned by a PKM 8–15 problem state resource manager
registered in the home address space.
A caller that is PKM 8–15 problem state can only specify
ATR_APPL_COMPLETE or ATR_RESET_APPL_COMPLETE for side_info_id.
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 ATRSUSI
|
(return_code
,ur_interest_token
,element_count
,side_info_id)
|
CALL ATRSUSI2
|
(return_code
,ur_or_uri_token
,element_count
,side_info_id)
|
CALL ATR4SUSI
|
(return_code
,ur_or_uri_token
,element_count
,side_info_id)
|
Parameters The parameters are explained
as follows: - return_code
- Returned parameter
- Character Set: N/A
- Length: 4 bytes
Contains the return code from the Set_Side_Information service.
- ,ur_interest_token
- Supplied
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
For ATRSUSI callers, specifies a token that uniquely identifies
your resource manager's interest in the UR whose side information
you want to set. Your resource manager received the token from one
of the following services: Express_UR_Interest, Retain_Interest.
- ,ur_or_uri_token
- Supplied
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
For ATRSUSI2 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 set: - 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 parameter.
Specify a hexadecimal value from X'1' to X'8'
- ,side_info_id
- Supplied
parameter
- Type: Integer
- Length: 4 bytes
Specifies one or more identifiers that set the side information.
When you specify two or more identifiers, place the identifiers in
an array. For a UR in local transaction mode, the only identifier
you can specify is ATR_DRIVE_COMPLETION. The possible identifiers
are: 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 immediately (before control
returns to the caller), which will make the information available
on restart.
|
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 manger 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 at the next state
change, which will make the information available on restart.
|
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 set,
RRS will invoke any defined COMPLETION exit routines when the UR is
complete. 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 logging point.
|
21
(33)
ATR_APPL_COMPLETE
|
This identifier indicates completion of an individual UR in
a cascaded UR family. Setting this identifier informs RRS 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: You cannot specify
ATR_APPL_COMPLETE and ATR_RESET_APPL_COMPLETE on the same call to
Set_Side_Information.
|
22
(34)
ATR_RESET_APPL_COMPLETE
|
Application processing is not complete When this identifier
is used, RRS resets the ATR_APPL_COMPLETE identifier. 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: You cannot
specify ATR_APPL_COMPLETE and ATR_RESET_APPL_COMPLETE on the same
call to Set_Side_Information.
|
ABEND codes The call might result in an
abend X'5C4' with a reason code of either X'00130000' or X'00130001'.
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. The
system rejects the service call. 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.
|
3A8
ATR_AUTH_FAILURE
|
Meaning: Program error. The caller is PKM 8–15 problem
state and one of the following occurred: - The caller specified the UR token of a UR associated with a context
that neither belongs to a PKM 8–15 problem state resource manager
registered in the home address space, nor is it a native context in
the home address space.
- The caller specified a value for side_info_id other than ATR_APPL_COMPLETE
or ATR_RESET_APPL_COMPLETE.
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 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.
|
73C
ATR_AFTER_NEW_UR
|
Meaning: Program error. The resource manager called
the Set_Side_Information service to set ATR_BREAK_TREE,
but the application is already running under a new UR. The system
rejects the service call. Action: Check the resource manager
for a probable coding error. Correct the resource manager and rerun
it.
|
745
ATR_AFTER_IN_PREPARE
|
Meaning: Program error. The resource manager cannot
call the Set_Side_Information service to set ATR_BACKOUT_REQUIRED because
the UR state is beyond in-prepare. The system rejects the service
call. Action: Check the resource manager for a probable
coding error. Correct the resource manager and rerun it.
|
757
ATR_ID_CONFLICT
|
Meaning: Program error. Information identifiers specified
on the call conflict with each other. For example, ATR_APPL_COMPLETE
and ATR_RESET_APPL_COMPLETE. The system rejects the service call.
Action: Check the calling program for a probable coding
error. Correct the program and rerun it.
|
758
ATR_APPL_COMPLETE_INV
|
Meaning: Program error. The specified UR cannot be
set as ATR_APPL_COMPLETE. The Set_Side_Information service cannot
set a top-level UR ATR_APPL_COMPLETE or ATR_RESET_APPL_COMPLETE. The
system rejects the service call. Action: Check the calling
program for a probable coding error. Correct the program and rerun
it.
|
761
ATR_APPL_COMPLETE_INV
_STATE
|
Meaning: Program error. The specified UR cannot be
set as ATR_APPL_COMPLETE or not ATR_APPL_COMPLETE, because the UR
is not in a valid state. The system rejects the service call. Action:
Check the calling program for a probable coding error. Correct the
program and rerun it.
|
766
ATR_SIDE_INFO_ID
_LOCAL_INV
|
Meaning: Program error. The identifier (or one of the
identifiers) specified in the side_info_id array is not allowed
when the UR is in local transaction mode. The system rejects the service
call. Action: Check the calling program for a probable
coding error.
|
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
Set_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 set the side information for ATR_BACKOUT_REQUIRED.
⋮
URI_TOKEN = UR_INTEREST_TOKEN
COUNT = 1
ID = ATR_BACKOUT_REQUIRED
CALL ATRSUSI(RC,URI_TOKEN,COUNT,ID)
IF RC = ATR_OK THEN
⋮
|