- ATRSROI is for AMODE(31) callers.
- ATRSROI1 is for AMODE(31) callers and allows a resource manager
to request to have its COMMIT exit run at a tier one priority with
regards to other resource managers in the next UR.
- ATR4SROI is for AMODE(64) callers and allows parameters in 64
bit addressable storage and allows a resource manager to request to
have its COMMIT exit run at a tier one priority with regards to other
resource managers in the next UR.
A resource manager calls the Retain_Interest service to express
interest in the next unit of recovery (UR) for the current context
when the current UR completes.
While managing conversations for a work request, a communications
resource manager can use the Retain_Interest call to make sure it
is aware of all URs for the work request.
The new UR that the Retain_Interest service creates begins after
the current UR reaches in_completion state.
In response to the call, RRS returns:
- A return code.
- A new UR interest token for the interest in the next UR. You need
this token for many calls to RRS services.
- A UR identifier (URID) for the next UR, for both protected and
unprotected expressions of interest.
Once the current UR reaches
in_completion state, you can
obtain the LUWID for the UR created by Retain_Interest. To obtain
the LUWID, call the Set_Work_Identifier service:
- Specify the new_ur_interest_token that
Retain_Interest provides.
- Request the current LUWID.
Protected and unprotected interests: The
call can express a protected or unprotected interest in the next UR.
For a protected interest, RRS or a resource manager coordinates changes
to the resources, so that all changes are made or no changes are made.
Resources that can be protected are a database, a conversation between
two communications managers, or a product-specific resource.
Action for Resource Manager Failure: In the call, you can specify
how RRS should process requests to commit the next UR if the resource
manager becomes:
- Unregistered: Your resource manager is no longer registered
as a resource manager. See the Register_Resource_Manager callable
service for a description of the ways in which your resource manager
can become unregistered.
- Unset: Your resource manager's exit routines are no longer
set with RRS.
RRS can process requests as follows:
- Standard processing: RRS should back out the next UR, if
the state of the UR is in-reset, in-flight, in-state-check,
or in-prepare.
- Forget interest: RRS is to delete the resource manager's
interest in the next UR. You may specify this value only if the interest_type is
ATR_UNPROTECTED.
Persistent interest data: In
the Retain_Interest call, your resource manager can provide persistent
interest data if the interest is protected. When hardening information
for the interest in an RRS log, RRS records the persistent interest
data. Because the data is hardened, it will be available if your
resource manager restarts or if RRS restarts, forcing your resource
manager to restart.
In addition to using Retain_Interest, your resource manager can
also provide persistent interest data in a call to any of the following
services: Express_UR_Interest, Change_Interest_Type, or Set_Persistent_Interest_Data.
Your resource manager can retrieve the data in a call to the Retrieve_UR_Interest
service or the Retrieve_UR_Data service.
Nonpersistent interest data: The call can
also provide nonpersistent interest data. RRS gives this data to
each resource manager exit routine it invokes for this interest.
This data is not recorded in nonvolatile storage and is not available
at subsequent restarts.
Your resource manager can also provide nonpersistent interest data
for an interest in a call to the Express_UR_Interest service or the Respond_to_Retrieved_Interest service.
Your resource manager can retrieve it in a call to the Retrieve_Interest_Data
service.
URID: Your
resource manager should save the returned URID with the data for the
next UR in its resource manager log. During restart processing after
the resource manager, RRS, or system fails, your resource manager
obtains the URID for an incomplete UR from the Retrieve_UR_Interest
service. Compare the URID from the Retrieve_UR_Interest service with
URIDs in the resource manager's log to find the data for the incomplete
UR.
Your resource manager can also obtain the URID from a call to the
following services: Express_UR_Interest, Retrieve_UR_Interest, Retrieve_UR_Data,
or Change_Interest_Type.
Commit exit tier priority: On this call, you can specify
the tier priority at which RRS should invoke your COMMIT exit:
- Tier one priority: RRS will invoke the resource manager's
COMMIT exit before other resource managers. If multiple resource managers
request the tier one priority, the commits exits will be driven in
the order in which they expressed interest in the UR.
- No priority: The resource manager's exit will be driven
after tier one resource managers' commit exits, if any.
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 (ATRSROI, ATRSROI1)
64 bit (ATR4SROI)
|
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
There are restrictions related
to the current UR:
- The UR state must not be in_reset, in_flight, in_completion,
or in_forget.
- The current UR must not be in local transaction mode.
- The expression of interest must not be a restart expression of
interest (that is, an interest returned by the Retrieve_UR_Interest
service).
- No resource manager can have the server distributed syncpoint
resource manager role in the UR.
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.
Interest
cannot be retained in a cascaded UR, a UR with an SDSRM, or a UR whose
context is terminating.
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 ATRSROI
|
(return_code
,ur_interest_token
,new_ur_interest_token
,ur_identifier
,interest_type
,failure_action
,nonpersistent_interest_data
,persistent_interest_data_length
,persistent_interest_data)
|
CALL ATRSROI1
|
(return_code
,ur_interest_token
,new_ur_interest_token
,ur_identifier
,interest_options
,nonpersistent_interest_data
,persistent_interest_data_length
,persistent_interest_data )
|
CALL ATR4SROI
|
(return_code
,ur_interest_token
,new_ur_interest_token
,ur_identifier
,interest_options
,nonpersistent_interest_data
,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 Retain_Interest service.
- ,ur_interest_token
- Supplied
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
Specifies the UR interest token that identifies your resource
manager's interest in the current UR. Your resource manager received
the token from the Express_UR_Interest service.
Note that the
token cannot be for a UR interest returned by a Retrieve_UR_Interest
call during restart.
- ,new_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 next UR.
- ,ur_identifier
- Returned
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
Receives from the service the UR identifier (URID) that uniquely
identifies the next UR.
- ,interest_options
- Supplied
parameter
- Type: Bit string
- Character Set: N/A
- Length: 4bytes
Specifies various options that determine how RRS will process
this interest. Each of the bits in
interest_options is
either reserved or has a specific meaning. Each reserved bit must
be specified as zero. Each other bit can be specified as either zero
or one. The bit specifications are:
Bit positions |
Constant in:
Hexadecimal
Equate Symbol
|
Description |
---|
7 |
00000000
ATR_UNPROT_INT_MASK
|
Interest Type A resource manager specifies
zero to express an unprotected interest in the UR.
A resource
manager specifies one to express a protected interest in the UR.
|
11 |
00000000
ATR_STANDARD_FAIL_MASK
00100000
ATR_REMOVE_INT_ON_FAIL_MASK
|
Failure action A resource manager
specifies zero when it wants RRS to do its standard processing if
the resource manager fails.
A resource manager specifies one
when it wants RRS to remove its interest in the UR if the resource
manager fails. Note: One can only be specified if the resource manager
is expressing an unprotected interest in the next UR.
|
14 |
00000000
ATR_COMMIT_NO_PRIORITY
00020000
ATR_COMMIT_TIER_ONE_
PRIORITY
|
Commit exit tier priority When zero
is specified, the resource manager does not require RRS to drive its
COMMIT exit at a higher priority with regards to other resource managers
in the same UR.
When one is specified, the resource manager
wants RRS to drive its COMMIT exit first with respect to other resource
managers' exits.
|
- ,interest_type
- Supplied
parameter
- Type: Integer
- Length: 4 bytes
Indicates the type of interest the resource manager has
in the next UR. Specify one of the following:
Constant in:
Hexadecimal
(Decimal)
Equate Symbol
|
Description |
---|
0
(0)
ATR_UNPROTECTED
|
Unprotected: The resource manager is expressing an
unprotected interest in the UR. |
1
(1)
ATR_PROTECTED
|
Protected: The resource manager is expressing a protected
interest in the UR. |
- ,failure_action
- Supplied
parameter
- Type: Integer
- Length: 4 bytes
Defines how RRS is to process commit requests for the next
UR if the resource manager becomes unregistered or unset. Specify
one of the following:
Constant in:
Hexadecimal
(Decimal)
Equate Symbol
|
Action |
---|
0
(0)
ATR_FAIL_STANDARD
|
Standard processing |
2
(2)
ATR_FAIL_FORGET
|
Forget interest |
For the current UR, the failure action after this
call is ATR_FAIL_STANDARD.
- ,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 does not record this data in nonvolatile
storage.
- ,persistent_interest_data_length
- Supplied
parameter
- Type: Integer
- Length: 4 bytes
Specifies, in hexadecimal, the length of the persistent interest
data. Specify X'0' - X'1000' (0-4096) bytes. If
the interest type is ATR_UNPROTECTED, then this field must be binary
zeros.
- ,persistent_interest_data
- Supplied
parameter
- Type: Character string
- Character Set: No restriction
- Length: Specified in persistent_interest_data_length
The persistent interest data for your resource manager's
interest in the UR. RRS records this data in an RRS log. If persistent_interest_data_length is
binary zeros, RRS ignores this parameter.
ABEND codes
The call might result in an
abend X'5C4' with a reason code of either X'00110000' or X'00110001'.
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.
|
371
ATR_INTEREST_TYPE_INV
|
Meaning: Program error. The interest_type 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.
|
372
ATR_FAILURE_ACTION_INV
|
Meaning: Program error. The failure_action 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.
|
376
ATR_PERSISTENT_DATA_LEN_INV
|
Meaning: Program error. The length specified in the persistent_interest_data_len parameter
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.
|
386
ATR_FAILURE_ACTION_INCORRECT
|
Meaning: Program error. The failure action specified
in the call is not valid for the specified interest type. The system
rejects the service call. Action: Check the resource manager
for a probable coding error. Correct the resource manager and rerun
it.
|
389
ATR_PERSISTENT_DATA_NOT_
ALLOWED
|
Meaning: Program error. The persistent interest data
length specified in the call is not zero; zero is the only value valid
with the specified interest type of ATR_UNPROTECTED. The system rejects
the service call. Action: Check the resource manager for
a probable coding error. Correct the resource manager and rerun it.
|
3B3
ATR_COMMIT_TIER_ONE_SRB_INV
|
Meaning: Program error. The resource
manager specified a tier one request for an SRB Commit Exit routine.
The system rejects the service call. Action: Check the
resource manager for a probable coding error. Correct the resource
manager and rerun it.
|
3B7
ATR_COMMIT_TIER_ONE_MISMATCH
|
Meaning: Program error. The resource
manager expressed interest conditionally and an expression of interest
already exists. The tier level specified by the RM does not match
the tier level already set in that interest. 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 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.
|
731
ATR_UR_STATE_ERROR
|
Meaning: Program error. The current UR is not in a
valid state for the service call. The UR state must not be in_reset, in_flight, in_completion,
or in_forget. The system rejects the service call. Action:
Check the resource manager for a probable coding error. Correct
the resource manager and rerun it.
|
736
ATR_SROI_ALREADY_DONE
|
Meaning: Program error. The resource manager has already
successfully called the Retain_Interest service for this UR interest
token. 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 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.
|
73D
ATR_INV_FOR_RESTART_
INTEREST
|
Meaning: Program error. The current UR is a restart
UR. The retain interest service cannot be invoked for restart URs.
The system rejects the service call. Action: Check the
resource manager for a probable coding error. Correct the resource
manager and rerun it.
|
747
ATR_TERMINATING_SYNCPOINT
|
Meaning: Program error. RRS is processing a terminating
syncpoint so there cannot be any more new URs for this contact. The
system rejects the service call. Action: Check the resource
manager for a probable coding error. Correct the resource manager
and rerun it.
|
748
ATR_RM_IS_THE_SDSRM
|
Meaning: Environmental error. A resource manager has
taken the SDSRM role for this UR. Interest cannot be retained in a
UR with an SDSRM. The system rejects the service call. Action:
Check the resource manager for a probable coding error. Correct
the resource manager and rerun it.
|
749
ATR_MAX_UR_LOG_DATA_
EXCEEDED
|
Meaning: Environmental error. This request will exceed
the maximum amount of data that RRS can log for a UR. The system rejects
the service call. Action: Fail the client program request
or back out the UR. Verify that the space set up for logging is adequate.
|
760
ATR_CASCADED_UR
|
Meaning: Program error. The UR is a cascaded UR. Interest
cannot be retained in a cascaded UR. The system rejects the service
call. Action: Check the calling program for a probable
coding error. Correct the program and rerun it.
|
764
ATR_LOCAL_TRAN_MODE_INV
|
Meaning: Program error. The current UR is in local
transaction mode. This service is valid only for a UR in global transaction
mode. The system rejects the service call. Action: Check
the calling program for a probable coding error. If the caller is
a resource manager, it should not unset its exits with RRS.
|
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
Retain_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 express protected interest in the
next UR for the current context.
⋮
URI_TOKEN = MY_URI_TOKEN
NON_P_DATA = ANCHOR1
P_DATA_LEN = LENGTH(MY_P_DATA)
P_DATA = MY_P_DATA
INT_TYPE = ATR_PROTECTED
FAIL_ACT = ATR_FAIL_STANDARD
CALL ATRSROI(RC,URI_TOKEN,NEW_URI_TOKEN,URID,INT_TYPE,
FAIL_ACT,NON_P_DATA,P_DATA_LEN,P_DATA)
IF RC = ATR_OK THEN
MY_NEXT_URITOKEN = NEW_URI_TOKEN
⋮