Express_UR_Interest (ATREINT, ATREINT1, ATREINT2, ATREINT3, ATREINT4, ATREINT5, ATR4EINT)

A resource manager calls the Express_UR_Interest service to express an interest, either protected or unprotected, in a unit of recovery (UR). There are seven versions of Express_UR_Interest, each with different parameters.

ATREINT is for AMODE(31) callers and is the basic version of the service.
ATREINT1 is for AMODE(31) callers and adds support for XIDs.
ATREINT2 is for AMODE(31) callers and supports XIDs and cascaded transactions.
ATREINT3 is for AMODE(31) callers, supports XIDs and returns transaction mode information.
ATREINT4 is for AMODE(31) callers, supports XIDs, cascaded transactions, COMMIT exit tier priority and returns transaction mode information.
ATREINT5 is for AMODE(31) callers, supports XIDs, cascaded transactions, COMMIT exit tier priority and returns transaction mode information. ATREINT5 uses the interest_options parameter to specify various options that determine how RRS will process an interest. Earlier versions of the service use multiple parameters to specify specific options.
ATR4EINT is for AMODE(64) callers, allows parameters in 64 bit addressable storage, supports XIDs, cascaded transactions, returns transaction mode information, and COMMIT exit tier priority. ATREINT5 uses the interest_options parameter to specify various options that determine how RRS will process an interest. Earlier versions of the service use multiple parameters to specify specific options.

Code your resource manager to call the version that includes the support you need.

In response to the different versions of the call, RRS can return:

A return code.
A UR interest token for the interest. You need this token on many other RRS calls to identify a specific UR.
The current context token, if you specified binary zeros on context_token to indicate that RRS is to use the current context associated with the current dispatchable unit.
A UR identifier (URID).
A UR token. You need this token if you want to create a UR cascaded from the UR in which you are expressing interest. You can also use this token as input for some services instead of using a URI token.
If you make a conditional request and your resource manager already has an interest in the UR, the current nonpersistent interest data.
An indicator of the type of transaction in which interest has been expressed. The indicator will indicate one of the following:
- Local transaction mode: The transaction in which interest has been expressed is in local transaction mode. The resource manager should commit the resources it is managing for the transaction when asked to do so explicitly by the transaction or when told to do so by RRS.
  Note: A resource manager will only be allowed to express interest in a transaction that is in local transaction mode if it has indicated, through Set_Exit_Information, that it can participate in local mode transactions.
- Global transaction mode: The transaction in which interest has been expressed is in global transaction mode. The resource manager may commit its resources without involving RRS as long as it is the only resource manager involved in the transaction.
- Hybrid-global transaction mode: The transaction in which interest has been expressed is in hybrid-global transaction mode. The resource manager may commit its resources without involving RRS as long as it is the only resource manager involved in the transaction.
  Note: Hybrid-global transaction mode is the mode that all RRS managed transactions ran under prior to RRS support for local and global modes. See Local transactions for more information about local and global transaction modes.

When a UR involves changes to multiple databases, communications, or both, then multiple resource managers might be interested in the UR and issue Express_UR_Interest calls for the same UR.

A single resource manager can also issue multiple Express_UR_Interest calls for the same UR, perhaps one for each of the resource manager's databases or one for each conversation being handled for the UR by a communication resource manager. Note, however, that expressing multiple interests in a UR causes RRS to invoke multiple exit routines. You can provide a shorter path length by expressing only one interest in a UR and keeping track of the resources for the UR in a control block that the resource manager maintains. In contrast, a communication resource manager might find multiple interests more useful, outweighing the overhead of multiple exit routine invocations.

To avoid creating multiple interests in the same UR, your resource manager can issue Express_UR_Interest as a conditional request; RRS creates a UR interest only when one does not already exist for this resource manager.

Protected and unprotected interests: The call can express a protected or unprotected interest in a 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.

If an interest is a protected interest and the system, RRS, or the resource manager fails, RRS will inform the resource manager about the UR, if incomplete, when the resource manager restarts. The resource manager can then finish processing the UR.

Action for resource manager failure: On the Express_UR_Interest call, you can specify how RRS should process requests to commit the UR if your resource manager becomes:

Unregistered: Your resource manager is no longer registered as a resource manager. See Register_Resource_Manager (CRGGRM, CRG4GRM) for a description of how a resource manager can become unregistered.
Unset: Your resource manager's exit routines are no longer set with RRS.

RRS should react to a resource manager failure as follows:

Standard processing: RRS is to back out this 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 UR. You can specify this value only when interest_type or interest_options indicates that the interest is unprotected.

Action for subordinate system failure: On the Express_UR_Interest call, you can specify whether RRS should notify the coordinator UR of a sysplex cascaded transaction in the event of a failure of either RRS, any resource manager on the subordinate system, or the subordinate system itself:

Notify: RRS will drive the SUBORDINATE_FAILED exit to notify the resource manager that there is a breakage on the subordinate system for which the resource manager is the coordinator. RRS only drives this exit when the sysplex cascaded transaction was in-flight at the time of the failure.
Ignore: SUBORDINATE_FAILED exit will not be driven.

Two-phase commit protocol: An Express_UR_Interest call can specify the type of two-phase commit protocol to be used for the UR if the resource manager is restarting:

Presumed nothing: For a presumed nothing expression of interest in a protected UR, RRS hardens an in-prepare record, including the persistent interest data, in the RRS log before it invokes the PREPARE exit routines. If the last log record for a UR was an in-prepare record, RRS returns the UR as in_backout in response to a Retrieve_UR_Interest call during resource manager restart.
If one protected interest in a UR is presumed nothing, RRS uses the presumed nothing protocol. If there is only one presumed nothing protected interest in a UR and this interest is by a distributed syncpoint resource manager, RRS does not log an in-prepare record.
Presumed abort: When the UR state is in-prepare, RRS does not harden an in-prepare record in the RRS log. During restart, RRS cannot return such a UR in response to a Retrieve_UR_Interest call. The resource manager presumes the UR was backed out.

Automatic context termination: An Express_UR_Interest call can specify how RRS should process the work context associated with the UR when the UR is forgotten:

Standard processing: No changes are made to the work context.
End processing: RRS will end the work context when the UR is forgotten.
Note: IBM® strongly recommends that end processing only be specified by the resource manager that owns the work context.

XID processing: A resource manager can provide an XID for the UR in which interest is being expressed as long as the UR does not already have an XID assigned. The resource manager can tell RRS to use the XID with either:

Standard Processing, or
Use BQUAL without checking, and/or
Use FormatID without checking

The possible results are as follows:

Table 1. XID Processing results
Standard processing:
Interest being expressed in	XID specified	RRS action
An existing non-cascaded UR	No	The UR keeps the XID that it already has (if any).
An existing cascaded UR	No	The UR keeps the XID that it already has.
A new non-cascaded UR	No	The UR will not have any XID associated with it.
A new cascaded UR	No	The UR will be given an XID that has the same FormatID and GTRID as its parent and a new, unique BQUAL.
An existing non-cascaded UR	Yes	If the UR does not already have an XID, the specified XID will be associated with the UR. If the UR already has an XID, the call to Express_UR_Interest will be considered invalid and no expression of interest will be created.
An existing cascaded UR	Yes	The call to Express_UR_Interest will be considered invalid and no expression of interest will be created.
A new non-cascaded UR	Yes	The specified XID will be associated with the UR.
A new cascaded UR	Yes	If the specified XID has a FormatID and GTRID that are the same as its parent, the specified XID will be associated with the UR unless the caller request RRS not to check the specified FormatID. In this case, only the GTRID component will be validated.
Use BQUAL without checking:
Interest being expressed in	XID specified	RRS action
A new cascaded UR	Yes	RRS will assign the new cascaded UR an XID that has the same FormatID and GTRID as its parent. The BQUAL portion of the XID will be taken from the XID specified. The FormatID and GTRID portions of the XID will be ignored.

Persistent interest data: In the Express_UR_Interest call, your resource manager can provide persistent interest data for the protected interest. 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.

Your resource manager can also provide persistent interest data in a call to: Change _Interest_Type, Set_Persistent_Interest_Data, or Retain_Interest. Your resource manager can retrieve persistent interest data in a call to: Retrieve_UR_Interest or Retrieve_Interest_Data.

Nonpersistent Interest Data: The Express_UR_Interest call can also provide nonpersistent interest data. RRS passes nonpersistent 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.

One use of this data is to pass the exit routines the locations of resource manager structures that represent the resources being changed.

Your resource manager can also provide nonpersistent interest data in a call to: Respond_to_Retrieved_Interest or Retain_Interest. Your resource manager can retrieve it by calling the Retrieve_UR_Interest_Data service.

URID: Save the returned UR identifier (URID) with the information about the UR in your resource manager log. During restart processing after your resource manager, RRS, or the system fails, your resource manager obtains the URID for an incomplete UR from a Retrieve_UR_Interest call. Compare the URID from Retrieve_UR_Interest with the URIDs in your resource manager log to find the data for the incomplete UR.

Your resource manager can also obtain the URID from a call to: Change_Interest_Type, Retrieve_UR_Interest, Retrieve_UR_Data, or Retain_Interest.

XID: If the UR does not already have an XID, the resource manager can specify an XID. If specified, the XID will be used as a work identifier for the UR. XIDs are not supported by the ATREINT version of Express_UR_Interest. You must call ATREINT1, ATREINT2, ATREINT3, ATREINT4, ATREINT5, or ATR4EINT to specify an XID.

Creating cascaded units of recovery: A work manager may use Express_UR_Interest to make a cascaded UR. A work manager would do this when a single work request involves multiple work managers that require separate contexts, or when separate transactional pieces of an application need to execute in parallel. By using the Express_UR_Interest service to make a new UR associated with a new work context and cascading it from the original UR, a second work manager ensures that all of the resources changed while it was executing in its original environment. Cascaded URs are not supported by the ATREINT, ATREINT1, and ATREINT3 versions of Express_UR_Interest. You must call ATREINT2, ATREINT4, ATREINT5 or ATR4EINT to make a cascaded UR while expressing interest. For additional information about cascaded URs, see Create_Cascaded_UR (ATRCCUR2, ATRCCUR3, ATR4CCUR).

Multisystem cascaded units of recovery: When one work manager requests another work manager, residing on a different system, to become part of an existing work request, the requesting work manager is responsible for transferring all of the data needed by the new work manager, including the UR token representing the work request. The new work manager may then use the Express_UR_Interest service to create a new UR, associated with a new work context, to be cascaded from the received UR token.

As with normal (non-multisystem) cascaded transactions, a work manager that creates a multisystem cascaded transaction is responsible for informing RRS when the part of the application executing under a multisystem cascaded UR is complete by using the Set_Side_Information service to mark the UR as application-complete.

For additional information about multisystem cascaded transactions, see Multisystem cascaded transactions.

Local transactions: A resource manager may use Express_UR_Interest to express interest in a UR that is in local transaction mode. A resource manager must indicate that it supports local transactions via Set_Exit_Information before it can express interest in a local transaction mode UR. Calls to ATREINT3, ATREINT4, ATREINT5, or ATR4EINT return information about the UR's transaction mode. For additional information about local transactions, see Local transactions.

Commit exit tier priority: On the Express_UR_Interest 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 commit 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 (ATREINT, ATREINT1, ATREINT2, ATREINT3, ATREINT4, ATREINT5) 64 bit (ATR4EINT)

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

For the call, the UR must be in an in-reset or in-flight state. If the UR state is in-reset, a successful call changes the UR state to in-flight.

To call the service, the resource manager associated with the resource manager token specified in the call must be in run state.

When the resource manager issues the call in SRB mode, the call cannot specify a context_token of 0, indicating the current context.

Do not express interests in a given UR asynchronously. An asynchronous thread may be used to express interest in a given UR, but the contextual thread should be suspended until the completion of the service. Asynchronous expressions of interest can cause work managers to make incorrect decisions about optimized commit flows, causing some resources to be committed and some left uncommitted.

Cascaded transaction restrictions:

The following restrictions apply when using ATREINT2, ATREINT4 or ATREINT5 to work with cascaded transactions:

If either UR_family_option or interest_options indicates that a cascaded UR is to be created, the UR must be in the in-reset state.
When the resource manager issues the call in SRB mode, the call must not specify binary zero for context_token or parent_UR_token. When either UR_family_option or interest_options indicates that a cascaded UR is to be created, the call can specify binary zero for either context_token or parent_UR_token, but not both.
If either UR_family_option or interest_options indicates that a cascaded UR is to be created, an XID may be specified, but the specified XID must have the same FormatID and GTRID as the XID of the UR specified by parent_UR_token.
To express an interest that creates a cascaded UR, the parent UR state must be in-reset or in-flight and the parent UR must not be in local transaction mode. After successfully expressing interest in a cascaded UR, both the parent and the child UR are in in-flight state and in global transaction mode.
For multisystem cascaded transactions, parent_UR_token must specify a token from a system in the same logging group as this system.

Note: A call to the Retrieve_UR_Data service that does not specify ATR_EXTENDED_STATES for the states_option could cause a UR to go into an in-flight state. Once a UR has gone in-flight, it can no longer be made into a cascaded UR.

Local transaction restrictions

The following restrictions apply when working with local transactions:

Before Express_UR_Interest can set a UR to local transaction mode, the resource manager must indicate to RRS, on a call to Set_Exit_Information, that the resource manager supports local transaction mode.
URs in local transaction mode cannot participate in cascaded transactions.
You cannot set an XID for a UR that is in local transaction mode.

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

If possible, resource managers should use presume abort logging protocols in order to minimize log update activity.

Syntax

Write the appropriate call as shown in the syntax diagrams. You must code the parameters in the CALL statements as shown.

CALL ATREINT

(return_code
,resource_manager_token
,context_token
,ur_interest_token
,current_context_token
,ur_identifier
,multiple_interest_option
,interest_type
,failure_action
,two_phase_protocol
,nonpersistent_interest_data
,current_nonpersistent_interest_data
,persistent_interest_data_length
,persistent_interest_data)

CALL ATREINT1

CALL ATREINT2

CALL ATREINT3

CALL ATREINT4

CALL ATREINT5

(return_code
,resource_manager_token
,context_token
,ur_interest_token
,ur_token
,current_context_token
,ur_identifier
,interest_options
,nonpersistent_interest_data
,current_nonpersistent_interest_data
,persistent_interest_data_length
,persistent_interest_data
,xid_length
,xid
,parent_ur_token
,diag_area
,transaction_mode)

CALL ATR4EINT

Parameters

The parameters are explained as follows:

return_code

Returned parameter

Type: Integer
Character Set: N/A
Length: 4 bytes

Contains the return code from the Express_UR_Interest service.

,resource_manager_token

Supplied parameter

Type: Character string
Character Set: No restriction
Length: 16 bytes

Specifies the resource manager token that identifies the resource manager. Your resource manager received the token from the Register_Resource_Manager service.

,context_token

Supplied parameter

Type: Character string
Character Set: No restriction
Length: 16 bytes

Specifies the token for the context associated with the UR:

0: Binary zeros specify the current context associated with the application's task. Binary zero may be specified for either parent_UR_token or context_token, but not both.
token: The context token of a particular context.

Your resource manager might have received the context_token from the Begin_Context or Retrieve_Current_Context_Token services.

,ur_interest_token

Returned parameter

Type: Character string
Character Set: No restriction
Length: 16 bytes

Receives the UR interest token that uniquely represents this instance of the resource manager's interest in the UR.

If you specified conditional interest via multiple_interest_option or interest_options and the return code from the service is ATR_RM_ALREADY_HAS_INTEREST, then the token returned represents the resource manager's existing interest in the UR. If there are multiple existing interests, the one returned is not predictable.

,ur_token

Returned parameter

Type: Character string
Character Set: No restriction
Length: 16 bytes

On ATREINT5 calls, receives the UR token that uniquely identifies the unit of recovery in which interest has been expressed.

If you specified conditional interest via interest_options and the return code from the service is ATR_RM_ALREADY_HAS_INTEREST, then the token returned represents the unit of recovery for which the URI token is returned in URI_token.

,current_context_token

Returned parameter

Type: Character string
Character Set: No restriction
Length: 16 bytes

Receives the following from the service:

The token of the current context, if the call specifies zeros in the context_token parameter. The token is a 16-byte character string.
Undefined, if context_token specifies a token.

,ur_identifier

Returned parameter

Type: Character string
Character Set: No restriction
Length: 16 bytes

Receives a UR identifier (URID) from the service. The URID uniquely identifies the UR.

,interest_options

Supplied parameter

Type: Bit string
Character Set: N/A
Length: 4bytes

On ATREINT5 calls, 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
0–2	0	Reserved
3	00000000 ATR_UNCOND_ INT_MASK 10000000 ATR_CONDITIONAL_ INT_MASK	Multiple interests A resource manager specifies zero to express unconditional interest in the UR. RRS is to create a new interest, even if the resource manager already has an interest in the UR. A resource manager specifies one to express conditional interest in the UR. RRS is not to create a new interest if the resource manager already has an interest in the UR. Instead, RRS should return information about the resource manager's existing interest. Note: If the resource manager has more than one interest, information about only one interest will be returned.
4–6	0	Reserved
7	00000000 ATR_UNPROT_ INT_MASK 01000000 ATR_PROTECTED_ 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.
8–10	0	Reserved
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 UR.
12–13	0	Reserved
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.
15	00000000 ATR_PRESUME_ NOTHING_MASK 00010000 ATR_PRESUME_ ABORT_MASK	Two phase protocol A resource manager specifies zero when it wants RRS to treat this expression of interest as needing presume nothing logging. A resource manager specifies one when it wants RRS to treat this expression of interest as needing presume abort logging.
16–18	0	Reserved
19	00000000 ATR_CREATE_ STANDARD_ UR_MASK 00001000 ATR_CREATE_ CASCADED_ UR_MASK	UR family type A resource manager specifies zero when it wants RRS to create a normal (non-cascaded) UR. A resource manager specifies one when it wants RRS to create a cascaded UR. parent_UR_token specifies the UR token of the parent of the new cascaded UR. Note: To specify one, the UR in which interest is being expressed must be in in-reset state.
20–22	0	Reserved
23	00000000 ATR_DONT_END_ CONTEXT_MASK 00000100 ATR_END_ CONTEXT_MASK	Auto context termination A resource manager specifies zero when it does not want RRS to end the work context associated with the UR in which interest is being expressed when the UR completes. A resource manager specifies one when it wants RRS to end the work context associated with the UR in which interest is being expressed when the UR completes. Note: IBM strongly recommends that one only be specified by the resource manager that owns the work context.
24–26	0	Reserved
27	00000000 ATR_STANDARD_ XID_MASK 00000010 ATR_USE_ BQUAL_MASK	XID processing A resource manager specifies zero when it wants RRS to do its standard XID processing. A resource manager specifies one it wants RRS to assign the new UR an XID with the same FormatID and GTRID as its parent and a BQUAL equal to the BQUAL of the XID specified. Note: To specify one, the interest must be in a new cascaded UR and XID must be specified. RRS will only validate and use the BQUAL and BQUAL length fields in the specified XID.
28	00000000 ATR_STANDARD_ XID_MASK 00000008 ATR_USE_ FORMATID_MASK	XID processing A resource manager specifies zero when it wants RRS to do its standard XID processing. A Resource manager specifies one when it wants RRS to assign the new UR an XID with the same GTRID as its parent and a FormatID equal to the FormatID of the XID specified. Note: To specify one, the interest must be in a new cascaded UR and XID must be specified. RRS will use the FormatID in the specified XID.
29-30	0	Reserved.
31	00000000 ATR_IGNORE_ SUBORDINATE_ FAILURE_MASK 00200000 ATR_NOTIFY_ SUBORDINATE_ FAILURE_MASK	Subordinate Failure Action When zero is specified, the resource manager does not want RRS to drive the SUBORDINATE_FAILED exit. When 1 is specified, the resource manager wants RRS to drive its SUBORDINATE_FAILED exit to inform the resource manager that RRS or a resource manager on its subordinate system has failed or the subordinate system itself has terminated. The sysplex cascaded transaction for which this resource manager is the coordinator was in-flight at the time of the failure.

,multiple_interest_option

Supplied parameter

Type: Integer
Character Set: N/A
Length: 4 bytes

Indicates whether or not RRS is to create a new interest when the resource manager already has an interest in the UR. Specify one of the following:

Constant in: Hexadecimal (Decimal) Equate Symbol	Description
0 (0) ATR_UNCONDITIONAL	Unconditional: RRS is to create a new interest, even when the resource manager already has an interest in the UR.
1 (1) ATR_CONDITIONAL	Conditional: RRS is not to create a new interest when the resource manager already has an interest in the UR.

,interest_type

Supplied parameter

Type: Integer
Character Set: N/A
Length: 4 bytes

Indicates the type of interest the resource manager has in the 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.

When expressing interest in a UR in local transaction mode, RRS will not harden any data for a local transaction; therefore, the processing for both ATR_UNPROTECTED and ATR_PROTECTED is identical. You can specify either.

,failure_action

Supplied parameter

Type: Integer
Character Set: N/A
Length: 4 bytes

Defines how RRS is to process commit requests for the 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

,two_phase_protocol

Supplied parameter

Type: Integer
Character Set: N/A
Length: 4 bytes

Identifies the two-phase commit protocol RRS is to use for this UR. Specify one of the following:

Constant in: Hexadecimal (Decimal) Equate Symbol	Protocol
0 (0) ATR_PRESUMED_NOTHING	Presumed nothing
1 (1) ATR_PRESUMED_ABORT	Presumed abort

When expressing interest in a UR in local transaction mode, RRS will not harden any data for a local transaction; therefore, the syncpoint processing for both ATR_PRESUMED_NOTHING and ATR_PRESUMED_ABORT is identical. You can specify either.

,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.

,current_nonpersistent_interest_data

Returned parameter

Type: Character string
Character Set: No restriction
Length: 16 bytes

Receives from the service the current nonpersistent interest data when both of the following conditions occur together:

You specified conditional interest via multiple_interest_option or interest_options.
The return code is ATR_RM_ALREADY_HAS_INTEREST.

Otherwise, the field contains binary zeros.

The nonpersistent interest data is for the resource manager's interest represented by the UR interest token returned by the service.

,persistent_interest_data_length

Supplied parameter

Type: Integer
Character Set: N/A
Length: 4 bytes

Specifies, in hexadecimal, the length of the persistent interest data. Specify X'0' - X'1000' (0-4096) bytes. If either interest_options or interest_type indicates that the interest is 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.

When expressing interest in a UR in local transaction mode, RRS will not harden any data for a local transaction, including persistent interest data. If the caller knows a UR is in local transaction mode, it should set persistent_interest_data_length to binary zeros. If the calling program does not know the transaction mode of the UR, however, it should specify all of the data needed for any mode. It is not considered an error if a nonzero value is specified in local transaction mode.

,xid_length

Supplied parameter

Type: Integer
Character Set: N/A
Length: 4 bytes

On ATREINT1, ATREINT2, ATREINT3, ATREINT4 and ATREINT5 calls, specifies the length of the XID specified by xid as follows:

0: Binary zero specifies that no XID is provided. RRS ignores the contents of the xid parameter.
non-zero: The length of the value in the xid parameter. The value must be between ATR_MIN_XID_LENGTH (13) and ATR_MAX_XID_LENGTH (140), inclusive. This parameter is normally set to a non-zero value only by a communications resource manager that has received an inbound transactional request with an XID provided. To specify an XID, the UR state must be in-reset. After a resource manager successfully uses ATREINT1, ATREINT2, ATREINT3 or ATREINT4 to set an XID, the transaction mode is set to global.

,xid

Supplied parameter

Type: Character string
Character Set: No restriction
Length: Specified by the xid_length parameter

On ATREINT1, ATREINT2, ATREINT3, ATREINT4 and ATREINT5 calls, specifies the XID your resource manager wants to set for this unit of recovery. If xid_length is zero, the contents of this parameter are ignored.

An XID has the following format:

FORMATID: 4–byte format identifier
GTRID_length: 4–byte GTRID length
BQUAL_length: 4–byte BQUAL length
ID: 1–128 byte ID transaction identifier

The 1–128 byte ID field has the following format:

GTRID: 1–64 byte GTRID
BQUAL: 0–64 byte BQUAL

,ur_family_option

Supplied parameter

Type: Integer
Character Set: N/A
Length: 4 bytes

On ATREINT2 and ATREINT4 calls, indicates whether or not RRS is to make the UR in which the resource manager expresses interest into a cascaded UR. The parent UR is specified by the parent_UR_token. Specify one of the following:

Constant in: Hexadecimal (Decimal) Equate Symbol	Description
0 (0) ATR_NO_FAMILY	No family: The UR is not a cascaded UR.
1 (1) ATR_CASCADED	Cascaded: The UR is a cascaded UR. The parent UR is specified by parent_UR_token. This must be the first expression of interest in the UR.

,parent_UR_token

Supplied parameter

Type: Character string
Character Set: No restriction
Length: 16 bytes

On ATREINT2, ATREINT4 and ATREINT5 calls, specifies the token of the UR that is to be the parent of the UR specified by the context_token:

0: Binary zero specifies the current UR associated with the application's task active on the current system. Binary zero may be specified for either the parent_UR_token or the child_context_token, but not both.
token: The UR token of a particular UR. The UR token may be from another system in the same logging group.

Unless UR_family_option is ATR_CASCADED or interest_options indicates that the interest being expressed is being used to create a new cascaded UR, RRS ignores this parameter.

Your resource manager may have received the parent_UR_token from the Retrieve_UR_Data service or from a work manager from another system. If the UR token was received from another system, RRS will associate the new child UR, specified by child_context_token, with the top-level UR of the cascaded UR family that resides on the system where the work request originated.

,diag_area

Returned parameter

Type: Character string
Character Set: No restriction
Length: 32 bytes

On ATREINT3, ATREINT4 and ATREINT5 calls, contains diagnostic data from Express_UR_Interest to help IBM service determine the cause of an Express_UR_Interest failure. Be sure to log this data when recording any information about an Express_UR_Interest failure.

,transaction_mode

Returned parameter

Type: Integer
Character Set: N/A
Length: 4 bytes

On ATREINT3 and ATREINT4 calls, indicates the transaction mode of the UR that the resource manager is expressing interest in. RRS returns one of the following:

Constant in: Hexadecimal (Decimal) Equate Symbol	Description
1 (1) ATR_GLOBAL_MODE	The transaction mode for the UR is global.
2 (2) ATR_LOCAL_MODE	The transaction mode for the UR is local.
3 (3) ATR_HYBRID_GLOBAL_MODE	The transaction mode for the UR is hybrid-global.

ABEND codes

The call might result in an abend X'5C4' with a reason code of either X'00020000' or X'00020001'. 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.
8 ATR_RM_ALREADY_HAS_INTEREST	Meaning: For a conditional request, the resource manager already has an interest in the UR. The system accepts the service call and returns: The UR interest token The UR identifier The nonpersistent interest data for the existing interest The system might also return the current context token. 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 or parent_UR_token, 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 is running a version of RRS that supports this service call. Then rerun the resource manager.
301 ATR_RM_TOKEN_INV	Meaning: Program error. The resource manager token 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.
361 ATR_CONTEXT_TOKEN_INV	Meaning: Program error. The context token 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.
36A ATR_DU_TERMINATING	Meaning: Environmental error. The task or SRB associated with the context specified in the call is ending. The system rejects the service call. Action: None.
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.
375 ATR_TWO_PHASE_PROTOCOL_INV	Meaning: Program error. The two_phase_protocol 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 with 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 when either interest_type or interest_options indicates unprotected interest is being requested. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
391 ATR_MULTIPLE_INTEREST_ OPTION_INV	Meaning: Program error. The multiple interest option 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.
397 ATR_XID_DATA_INV	Meaning: Program error. The computed length of the XID does not match the specified length passed via the xid_length parameter. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
399 ATR_UR_FAMILY_ OPTION_INV	Meaning: Program error. The UR family 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 program and rerun it.
39A ATR_PARENT_UR_TOKEN_INV	Meaning: Program or environmental error. The UR token specified in the parent_UR_token parameter is not valid because one of the following is true: It was coded incorrectly The parent transaction failed The system it resided on failed The coordinator system failed The RRS running on that system failed The parent UR belongs to a system that is not in the same RRS logging group as this system If any of these conditions occurs, the system rejects the service call. Action: Check the calling program for a probable coding error. If it's a program error, correct the program and rerun it. If the work manager was creating a multisystem cascaded UR, the work manager must communicate the failure to the work manager originating the request. Installation Action: Ensure that the originating work manager and this work manager are in the same RRS logging group.
39C ATR_XID_LENGTH_INV	Meaning: Program error. The XID length 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 program and rerun it.
39D ATR_XID_INV	Meaning: Program error. The XID 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 program and rerun it.
39E ATR_PARENT_DU_ TERMINATING	Meaning: Environmental error. The task associated with the UR family specified by the parent_UR_token parameter is ending. The system rejects the service call. Action: None.
3A0 ATR_SAME_CURRENT_CONTEXT_INV	Meaning: Program error. The UR represented by the parent_UR_token and the UR associated with the context represented by the child_context_token are both 0. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it.
3A1 ATR_SAME_PARENT_ CONTEXT_INV	Meaning: Program error. The UR represented by the parent_UR_token, which may have been specified with a 0, and the UR associated with the context represented by the child_context_token are the same UR. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it.
3A2 ATR_SAME_CHILD_CONTEXT_INV	Meaning: Program error. The UR represented by the parent_UR_token and the UR associated with the context represented by the child_context_token, specified with a 0, are the same UR. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the 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. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
3A4 ATR_PARENT_AUTH_FAILURE	Meaning: Program error. The caller is PKM8-15 problem state, but specified a parent_UR_token of a UR associated with a context which: Does not belong to a PKM 8-15 problem state resource manager registered in the home address space. Is not a native context in the home address space. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it.
3A5 ATR_CHILD_AUTH_FAILURE	Meaning: Program error. The caller is PKM 8-15 problem state, but specified a child_context_token of a context which: Does not belong to a PKM 8-15 problem state resource manager registered in the home address space. Is not a native context in the home address space. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it.
3AC ATR_INTEREST_OPTIONS_INV	Meaning: Program error. The interest_options value specified on the call is not valid. Either reserved bits were nonzero or an unacceptable selection of options and parameters was specified. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it.
3B0 ATR_XID_EXISTS	Meaning: Program error. The resource manager specified an XID, but the UR already has an XID. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it.
3B1 ATR_SUBORDINATE_FAILED_ EXIT_NOT_DEFINED	Meaning: Program error. The resource manager requested to be notified, through the SUBORDINATE_FAILED exit, in the event of either RRS, RM, or system failure on a subordinate system. However, a SUBORDINATE_FAILED exit was not provided by the resource manager. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the program and rerun it.
3B2 ATR_DRV_SUBORDINATE_FAILED_ EXIT_INV	Meaning: Program error. The resource manager requested to be notified, through the SUBORDINATE_FAILED exit, in the event of subordinate failure, but the UR in which it is expressing interest is a cascaded UR. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the program 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 program 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 program and rerun it.
701 ATR_RM_STATE_ERROR	Meaning: Program error. The resource manager associated with the resource manager 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: RRS/MVS has unset the RRS/MVS exit routines for this resource manager. Action: The system rejects this service request. The resource manager must reset its RRS exit routine information and begin restart processing with RRS.
731 ATR_UR_STATE_ERROR	Meaning: Program error. Either the UR state or the transaction mode is not valid for the service call. You cannot call Express_UR_Interest when: Your resource manager is trying to set an XID, but the xid_length parameter specified is 0 The UR state is any other state but in-reset when either UR_family_option or interest_options indicates a new cascaded UR was to be created or the resource manager attempted to set an XID The UR state is beyond in-flight. A new expression of interest cannot be created if the UR state is beyond in-flight. The UR is in local transaction mode, or this expression of interest would change the UR transaction mode to local, but the resource manager has not called Set_Exit_Information to inform RRS that it supports local transaction mode. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
743 ATR_PARENT_UR_ STATE_ERROR	Meaning: Program error. The UR specified by the parent_UR_token is not in a valid state for the service call. The UR must be in an in-reset or in-flight state. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it.
744 ATR_CHILD_UR_STATE_ERROR	Meaning: Program error. The UR associated with the specified child_context_token is not in a valid state for the service call. The UR must be in an in-reset state. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program 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.
763 ATR_PARENT_LOCAL_TRAN _MODE_INV	Meaning: Program error. The parent UR is in local transaction mode. This service is valid only for a parent UR in global transaction mode. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the calling program and rerun it.
769 ATR_XID_NO_GLOBAL_MATCH	Meaning: Program error. The XID specified in the XID parameter does not have the same FormatID, GTRID_length and GTRID values as the parent UR's XID. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program 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 had been available to the resource manager but has gone down and come back up again. A commit or backout operation may or may not have been in progress for the context under which the Express_UR_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 with presume abort logging in a UR associated with the current context.

⋮
RM_TOKEN = MY_RM_TOKEN
C_TOKEN = 0
NON_P_DATA = ANCHOR1
P_DATA_LEN = LENGTH(MY_P_DATA)
P_DATA = MY_P_DATA
INT_OPTS = ATR_PROTECTED_INT_MASK + ATR_PRESUME_ABORT_MASK
PARENT = JUNK
XID_LEN = 0
XID = JUNK
CALL ATREINT5(RC,RM_TOKEN,C_TOKEN,URI_TOKEN,UR_TOKEN,CUR_C_TOKEN,
            URID,INT_OPTS,NON_P_DATA,C_NON_P_DATA,P_DATA_LEN,
            P_DATA,XID_LEN,XID,CASCADE_OPT,PARENT,TRAN_MODE)
IF RC = ATR_OK THEN
   MY_C_TOKEN = CUR_C_TOKEN
   MY_URTOKEN = URI_TOKEN
   MY_URID = URID
   MY_URTOKEN = UR_TOKEN
   MY_TRAN_MODE = TRAN_MODE
⋮