Delegate_Commit_Agent_UR (ATRADCT, ATRADCT1, ATR4ADCT)

A resource manager that has taken the server distributed syncpoint resource manager (SDSRM) role calls Delegate_Commit_Agent_UR to tell RRS to initiate and complete a syncpoint operation for the unit of recovery (UR) associated with the specified UR interest. This single call replaces a call to Prepare_Agent_UR, possibly followed by a call to either Commit_Agent_UR or Backout_Agent_UR.

There are three versions of Delegate_Commit_Agent_UR.

ATRADCT is for AMODE(31) callers and is the basic version of this service.
ATRADCT1 is for AMODE(31) callers and allows the specification of the commit_options mask option. This option allows RRS to delete the SDSRM interest prior to driving syncpoint processing, freeing RRS to perform exit optimization.
ATR4DCT is for AMODE(64) callers, allows parameters in 64 bit addressable storage, and allows the specification of the commit_options mask option. This option allows RRS to delete the SDSRM interest prior to driving syncpoint processing, freeing RRS to perform exit optimization.

When the SDSRM calls ATRADCT, RRS takes responsibility for making the commit or backout decision for the UR based on the collective prepare vote. The UR will bypass the in-doubt state and transition directly into in-commit or in-backout.

When the SDSRM calls ATRADCT1 or ATR4ADCT, if commit_options indicated that the SDSRM's interest is to be removed, RRS deletes the SDSRM's interest and lets other resource manager(s) take responsibility for making the commit or backout decision. If there is only one other Resource Manager with a single expression of interest, and it provides an Only_Agent exit, RRS will drive its Only_Agent exit. When the Only_Agent exit returns control, RRS considers the UR processing to be complete. If there is more than one Resource Manager or the only Resource Manager did not provide an Only_Agent exit, RRS will perform a two-phase commit processing for the UR, and commit or backout the UR based on the collective prepare vote. In this case, UR will bypass the in-doubt state and transition directly into in-commit or in-backout.

A successful call to Delegate_Commit_Agent_UR changes the UR state to either in-forget or forgotten, depending on the value of log_option specified on the call. If the return code is ATR_PROGRAM_STATE_CHECK, the UR state will remain unchanged.

RRS will implicitly change the log_option to ATR_DEFER_EXPLICIT under any of the following conditions:

When the application backs out the UR through a call to the Backout_UR service or the Application_Backout_UR service.
When RRS recreates a committed or backed-out UR during restart processing.

If any of these conditions has occurred, RRS returns the ATR_UR_STATE_ERROR return code. The UR might be in any state, but once it reaches in-forget, it will remain in that state until the Forget_Agent_UR service is called.

RRS waits for Forget_Agent_UR to ensure that the resource manager that has taken the SDSRM role is always informed of the results of the UR. This allows the resource manager to safely prevote its BACKOUT and COMMIT exits.

With ATRADCT1 or ATR4ADCT, if the Delete Interest option has been requested and a State Check Exit returns the ATRX_STATE_INCORRECT return code, the syncpoint will be backed out because the SDSRM's interest was deleted prior to the beginning of the syncpoint processing.

Environment

The requirements for the caller are:

Minimum authorization:

PKM allowing key 0-7, or supervisor state

Dispatchable unit mode:

Task mode

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31 bit (ATRADCT, ATRADCT1)
64 bit (ATR4ADCT)

ASC mode:

Primary or AR

Interrupt status:

Enabled for I/O and external interrupts

Locks:

No locks held

Control parameters:

All parameters must be in the primary address space and addressable by the caller.

Linkage:

Standard MVS™ linkage conventions

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

To use this service:

The resource manager state must be run, which means that the UR interest token specified in the call has registered, set its exit routines with RRS, and completed restart.
The unit of recovery state must be in-flight. With ATRADCT, after the call, subsequent references to the UR interest token will cause a logic error, unless the log_option was specified or changed to ATR_DEFER_EXPLICIT.

Caution: The resource manager must ensure that no application can be updating protected resources for the unit of recovery being committed. This is necessary to ensure that no resource manager taking part in the unit of recovery sees updates being made on behalf of a unit of recovery at the same time the updates are executing syncpoint processing.

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

CALL ATRADCT

(return_code
,ur_interest_token
,log_option);

CALL ATRADCT1

(return_code
,ur_interest_token
,log_option
,commit_options);

CALL ATR4ADCT

(return_code
,ur_interest_token
,log_option
,commit_options);

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 Delegate_Commit_Agent_UR service.

,ur_interest_token

Supplied parameter

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

Specifies the UR interest token that uniquely represents an instance of the resource manager's interest in the particular UR. This must be an interest in which the resource manager has taken the SDSRM role for the UR. The resource manager received the token from the Express_UR_Interest service or the Retain_Interest service.

,log_option

Supplied parameter

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

Indicates how RRS is to process log entries for the UR.

With ATRADCT1, if commit_options indicates to remove the SDSRM's interest, RRS ignores the log_option parameter.

Specify one of the following:

Constant in:
Hexadecimal
(Decimal)
Equate Symbol

Description

X'0'
(0)
ATR_DEFER_IMPLICIT

Meaning: RRS is to logically delete the log record when the UR state changes to forgotten.

Your resource manager will not call the Forget_Agent_UR service.

X'1'
(1)
ATR_DEFER_EXPLICIT

Meaning: If the UR is committed, RRS must keep the log record for the UR until your resource manager calls the Forget_Agent_UR_Interest service. The log_option specified on Forget_Agent_UR_Interest then determines how RRS processes the log entry for committed URs.

The Delegate_Commit_Agent_UR return codes document which return codes require your resource manager to call Forget_Agent_UR, as indicated by the final state of the UR being in-forget.

,commit_options

Supplied parameter

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

Specifies various options which determine how RRS is to perform the delegated_commit request. Each of the bits or set of bits in commit_options is either reserved or has a specific meaning. Each reserved bit must be specified as zero. Each of the other bits can be specified as zero or one.

The bit specifications are:

Bit Position	Constant in: Hexadecimal Equate Symbol	Description
0	00000000 ATR_STANDARD_COMMIT_MASK	When zero is specified, the SDSRM wants RRS to perform a normal delegated commit processing.
0	10000000 ATR_REMOVE_SDSRM_INTEREST_MASK	When one is specified, the SDSRM wants RRS to remove its interest in the UR and let other resource manager(s) take responsibility for making the commit or backout decision. In this case, RRS ignores the log_option value.
1-31	0 (None)	Reserved

ABEND codes

The call might result in an abend X'5C4' with a reason code of either X'00220000' or X'00220001'. 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. All protected resources advanced to a consistent state. The UR state is now in-forget if you specified a log_option of ATR_DEFER_EXPLICIT, or forgotten if you specified a log_option of ATR_DEFER_IMPLICIT. Action: Continue normal processing.
8 ATR_FORGET	Meaning: The commit operation completed successfully. The collective prepare vote allows the unit of recovery to be completed, and all resource managers voted to abstain or forget. The UR state is now forgotten. Action: Continue normal processing. Note: This return code is not valid when the Delete_SDSRM_Interest option has been specified.
65 ATR_COMMITTED_OUTCOME_PENDING	Meaning: The commit operation completed. The RRS decision was to advance to a consistent state. However, the state of one or more of the protected resources is not known. The UR state is now in-forget if you specified a log_option of ATR_DEFER_EXPLICIT, or forgotten if you specified a log_option of ATR_DEFER_IMPLICIT. Action: Continue normal processing for a committed UR.
66 ATR_COMMITTED_OUTCOME_MIXED	Meaning: The commit operation completed. The RRS decision was to advance to a consistent state. However, the state of one or more of the protected resources has been returned to the previous consistent state. The UR state is now in-forget if you specified a log_option of ATR_DEFER_EXPLICIT, or forgotten if you specified a log_option of ATR_DEFER_IMPLICIT. Action: Report the error to the other transactional participants.
C8 ATR_PROGRAM_STATE_CHECK	Meaning: The commit operation failed. The consistency state of the protected resources has not been altered. This return code indicates one of the following conditions has occurred: A protected resource, specifically a communications Interface conversation, is not in Send, Send Pending, Defer Receive, Defer Allocate, Sync_Point, Sync_Point Send, or Sync_Point Deallocate state. A protected resource, specifically a Communications Interface conversation, is in Send state, and the program started but did not finish sending a basic conversation logical record. A protected resource, specifically a local resource, is not in the proper state for a commit. The UR state is unchanged. Action: If possible, initiate a resource manager action to get the resources to a committable state and then invoke the Delegate_Commit_Agent_UR service again. Otherwise, issue Backout_Agent_UR to back out the transaction.
103 ATR_INTERRUPT_STATUS_INV	Meaning: The caller is disabled. The system rejects this service request. Action: Check the calling program for a probable coding error.
104 ATR_MODE_INV	Meaning: Program error. The calling program is not in task mode, which is the required 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: The caller is holding one or more locks. The system rejects this service request. Action: Check the calling program for a probable coding error.
107 ATR_UNSUPPORTED_RELEASE	Meaning: The system level does not support this service. The system rejects this service request. Action: Remove the calling program from the system, and install it on a system that supports RRS. Then rerun the calling program.
12C ATR_BACKED_OUT	Meaning: The commit operation failed. All protected resources have been returned to the previous consistent state. The UR state is now forgotten. Action: Continue normal processing for a backed out unit of recovery.
12D ATR_BACKED_OUT_OUTCOME_ PENDING	Meaning: The commit operation failed. The RRS decision was to return to the previous consistent state. However, the state of one or more of the protected resources is not known. The UR state is now forgotten. Action: Continue normal processing for a backed out unit of recovery.
12E ATR_BACKED_OUT_OUTCOME_ MIXED	Meaning: The commit operation failed. However, one or more of the protected resources has advanced to a new synchronization state. The UR state is now forgotten. Action: Report the error to the other transactional participants.
370 ATR_URI_TOKEN_INV	Meaning: The specified UR_interest_token does not represent a valid expression of interest. This condition can occur after RRS has terminated and restarted. The system rejects this service request. Action: Check the calling program for a probable coding error.
395 ATR_LOG_OPT_INV	Meaning: The specified log_option value is not valid. The system rejects this service request. Action: Check the calling program for a probable coding error.
3AE ATR_COMMIT_OPTIONS_INV	Meaning: The specified commit_options value is not valid. Either reserved bits were nonzero or an unacceptable selection of options and parameters was specified. The system rejects this service request. Action: Check the calling program for a probable coding error.
701 ATR_RM_STATE_ERROR	Meaning: The resource manager state is not valid for this request. The system rejects this service request. Action: Check the calling program for a probable coding error.
702 ATR_RM_EXITS_UNSET	Meaning: RRS has unset the RRS exit routines for this resource manager. The system rejects this service request. Action: The resource manager must reset its RRS exit routine information and begin restart processing with RRS.
731 ATR_UR_STATE_ERROR	Meaning: The UR state is not valid for this service request. The system rejects the request. The application might have already requested backout. Call Retrieve_UR_Data or Retrieve_Side_Information to obtain information about the state of the UR. If you receive this return code, you must call Forget_Agent_UR to complete processing for the UR. Action: Call Forget_Agent_UR to complete the processing of this UR.
74A ATR_NOT_SERVER_DSRM	Meaning: The resource manager does not have the server distributed syncpoint resource manager role for the unit of recovery. The system rejects this service request. Action: Check the calling program for a probable coding error.
762 ATR_PRESUMED_NOTHING_INVALID	Meaning: The specified UR interest has an invalid two-phase commit protocol selected. PRESUMED_NOTHING is not allowed. Action: Check the calling program for a probable coding error.
F00 ATR_NOT_AVAILABLE	Meaning: RRS is not available. The system rejects the service request. Action: Retry the request later. Before retrying the request, the resource manager must reset its RRS exit routine information and begin restart processing with RRS.
F04 ATR_UNEXPECTED_UR_ERROR	Meaning: System error. While processing the UR, RRS has encountered an unexpected error that might have damaged the UR. The system rejects the service call. Action: Contact the system programmer who maintains RRS at your installation. Manual intervention might be needed to restore consistent resources.
F06 ATR_WAS_NOT_AVAILABLE	Action: Refer to the documentation of this error under the description of the Delete_UR_Interest service.
FFF ATR_UNEXPECTED_ERROR	Meaning: This service routine encountered an unexpected error. The system rejects this service request. 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 tell RRS to initiate and complete a syncpoint operation for a UR. Storage for the call parameters has been allocated.

⋮
URI_TOKEN = MY_URI_TOKEN
LOGOPT = ATR_DEFER_IMPLICIT
CALL ATRADCT(RC,URI_TOKEN,LOGOPT)
⋮