Retain_Interest (ATRSROI, ATRSROI1, ATR4SROI)

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

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.

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.

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
⋮