Commit_Agent_UR (ATRACMT, ATR4ACMT)

ATRACMT is for AMODE(31) callers.
ATR4ACMT is for AMODE(64) callers and allows parameters in 64 bit addressable storage.

A resource manager that has taken the server distributed syncpoint resource manager (SDSRM) role calls Commit_Agent_UR to tell RRS to commit the unit of recovery (UR) associated with the specified UR interest. The SDSRM can invoke this service to resolve an in_doubt unit of recovery to in_commit.

Commit_Agent_UR changes the unit of recovery state to in_forget or forgotten.

If a resource manager with an interest in a UR has taken the SDSRM role, RRS will implicitly change the log_option to ATR_DEFER_EXPLICIT under any of the following conditions:

When an RRS panel or the ATRSRV macro is used to resolve an in-doubt UR.
When RRS re-creates 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 and allows the resource manager to safely prevote its BACKOUT and COMMIT exits.

Environment

Authorization:

Supervisor state, or PKM allowing keys 0-7

Dispatchable unit mode:

Task mode

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31 bit (ATRACMT)
64 bit (ATR4ACMT)

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 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:

Table 1. Commit_Agent_UR (ATRACMT, ATR4ACMT) Programming requirements
HLL definition	Description
ATRRASM	390 Assembler declarations
ATRRC	C/390 declarations

Restrictions

To use the service:

The resource manager state must be run.
The unit of recovery state must be in-doubt.

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 as they 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 ATRACMT

(return_code
,UR_interest_token
,log_option)

CALL ATR4ACMT

(return_code
,UR_interest_token
,log_option)

Parameters

The parameters are explained as follows:

return_code

Returned parameter

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

Contains the return code for the 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. The resource manager received the token from: Express_UR_Interest, Retrieve_UR_Interest, or Retain_Interest.

log_option

Supplied parameter

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

Specifies how RRS is to process log entries for the unit of recovery. Code one of the following values:

Table 2. Commit_Agent_UR (ATRACMT, ATR4ACMT)Parameters
Constant in Hexadecimal (Decimal) Equate Symbol	Description
X'0' (0) ATR_DEFER_IMPLICIT	Meaning: RRS is to logically delete the log record when the unit of recovery state changes to Forgotten. Your resource manager will not call the Forget_Agent_UR_Interest service.
X'1' (1) ATR_DEFER_EXPLICIT	Meaning: RRS must keep the log record for the unit of recovery 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. Your resource manager will call the Forget_Agent_UR_Interest service.
X'2' (2) ATR_IMMEDIATE	Meaning: RRS is to immediately delete from the log the interest the server distributed syncpoint manager (SDSRM) has in the UR. RRS hardens a new log record without the interest before driving any additional exit routines.

ABEND codes

The call might result in an abend X'5C4' with a reason code of either X'001B0000' or X'001B0001'. 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.

Table 3. Commit_Agent_UR (ATRACMT, ATR4ACMT) Return codes
Return Code in: Hexadecimal Equate Symbol	Meaning and action
0 ATR_OK	Meaning: The commit operation completed successfully. All protected resources have advanced to a consistent state. Action: Continue normal processing.
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. Action: Continue normal processing for a committed unit of recovery.
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. Action: Report the error to the other transactional participants.
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.
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.
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 request. If this service was called to resolve an in_doubt UR, the in-doubt condition might have already been resolved by operator action. 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.
750 ATR_RESPOND_CONTINUE_ REQUIRED	Meaning: The resource manager must call Respond_to_Retrieved_Interest before it can call Commit_Agent_UR for this interest. Action: The system rejects this service request. Call Respond_to_Retrieved_Interest, then call Commit_Agent_UR for this interest.
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.
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.
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 wants to commit the unit of recovery. Storage for the call parameters has been allocated.

⋮
URI_TOKEN = MY_URI_TOKEN
FTOPT=ATR_DEFER_IMPLICIT
CALL ATRACMT(RC,URI_TOKEN,FTOPT)
⋮