End_Transaction (ATREND, ATR4END)

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

End_Transaction commits or rolls back (backs out) the current transaction. An application program calls the End_Transaction service to indicate that the changes for the UR are either to be made permanent (committed) or undone (rolled back). To process the call, RRS informs the resource managers about the specified action, then issues a return code to the calling program.

End_Transaction performs the same service as the following services:

Application_Commit_UR
Commit_UR
Application_Backout_UR
Backout_UR

End_Transaction, however, provides return codes for many error conditions that cause Application_Commit_UR and Application_Backout_UR to abnormally end the calling program with ABEND code X'5C4'. For a description of Application_Commit_UR and Application_Backout_UR, see z/OS MVS Programming: Callable Services for High-Level Languages.

Typically, End_Transaction is called in local transaction mode when an application or work manager needs to ensure that all uncommitted local resources are placed in a consistent state, with all changes either committed or backed out, but not necessarily in an atomic manner with respect to each other. When the specified action is commit, and the transaction mode of the current UR is global or hybrid-global, then this service performs identically to the Commit_UR service. Similarly, when the specified action is rollback, and the transaction mode of the current UR is global, then this service performs identically to the Backout_UR service.

Environment

The requirements for the caller are:

Minimum authorization:

Any

Dispatchable unit mode:

Task mode

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31 bit (ATREND)
64 bit (ATR4END)

ASC mode:

Primary or 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

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

The UR state must be in-reset or in-flight.

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 ATREND

(return_code
,diag_area
,action
,current_ur_token)

CALL ATR4END

(return_code
,diag_area
,action
,current_ur_token)

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

,diag_area

Returned parameter

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

Contains diagnostic data from End_Transaction to help IBM® Service determine the cause of an End_Transaction failure. Be sure to log this data when recording any information about an End_Transaction failure.

,action

Supplied parameter

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

Indicates whether the uncommitted resources associated with the current UR are to be committed or rolled back. Specify one of the following:

Constant in: Hexadecimal (Decimal) Equate Symbol	Description
1 (1) ATR_COMMIT_ACTION	The resource managers are to commit any uncommitted resources associated with the current UR.
2 (2) ATR_ROLLBACK_ACTION	The resource managers are to roll back any uncommitted resources associated with the current UR.

,current_ur_token

Supplied parameter

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

Specifies the UR token that uniquely represents the current UR. Specify this token when you want RRS to verify that the UR specified is the current UR before performing any operation against it.

Specify binary zeros to indicate that RRS is to perform the requested action against the current UR, regardless of what UR is current.

ABEND codes

The call might result in an abend X'5C4' with a reason code of either X'00240000' or X'00240001'. 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. If you specified an action of ATR_COMMIT, all protected resources have been successfully committed. If you specified an action of ATR_ROLLBACK, all protected resources have been successfully rolled back. Action: Continue normal processing.
65 ATR_COMMITTED_OUTCOME_PENDING	Meaning: Environmental error. The commit operation completed. However, RRS cannot determine if all of the protected resources were changed. Action: The action by the calling program depends on the system environment. Some possible actions are: Display a warning message to the end user. Write an exception entry into an output log. Abnormally end the application because the resource manager will not allow any further changes to the resource until the situation is resolved.
66 ATR_COMMITTED_OUTCOME_MIXED	Meaning: Environmental error. The commit operation completed. However, one or more of the protected resources were not changed. Action: The action by the calling program depends on the system environment. Some possible actions are: Display a warning message to the end user. Write an exception entry into an output log. Abnormally end the application because the resource manager will not allow any further changes to the resource until the situation is resolved.
C8 ATR_PROGRAM_STATE_CHECK	Meaning: Environmental error. The commit operation failed. The resource managers may have rejected the commit because one of the following occurred: A communications interface conversation that is a protected resource is not in a required state: send, send pending, defer receive, defer allocate, sync_point, sync_point send, or sync_point deallocate state. A protected communications interface conversation is in send state. The program started sending the basic conversation logical record, but did not finish sending it. A resource on the same system as the application is not in a proper state for the commit. Action: Initiate an action by a resource manager to get its resource to a commitable state. Issue the call again. Note: This code is returned only when transaction mode is global or hybrid-global.
103 ATR_INTERRUPT_STATUS_INV	Meaning: Program error. The resource manager is disabled; the interrupt status must be enable for I/O and external interrupts. The system rejects this service request. Action: Check the calling program for a probable coding error. Correct the calling program and rerun it.
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: Program error. The caller is holding one or more locks; no locks must be held. The system rejects this service request. Action: Check the calling program for a probable coding error. Correct the calling program and rerun it.
107 ATR_UNSUPPORTED_RELEASE	Meaning: Environmental error. 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 this level of RRS. Then rerun the calling program.
12C ATR_BACKED_OUT	Meaning: Environmental error. The commit operation failed. All protected resources have been returned to the previous consistent state. Action: The action by the calling program depends on the system environment. Some possible actions are: Display a warning message to the end user. Write an exception entry into an output log. Abnormally end the application because the resource manager will not allow any further changes to the resource until the situation is resolved.
12D ATR_BACKED_OUT_OUTCOME_ PENDING	Meaning: Environmental error. The commit or rollback 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. Action: The action by the calling program depends on the system environment. Some possible actions are: Display a warning message to the end user. Write an exception entry into an output log. Abnormally end the application because the resource manager will not allow any further changes to the resource until the situation is resolved.
12E ATR_BACKED_OUT_OUTCOME_ MIXED	Meaning: Environmental error. The commit or rollback operation failed. The RRS decision was to return to the previous consistent state. However, one or more of the protected resources has changed. Action: The action by the calling program depends on the system environment. Some possible actions are: Display a warning message to the end user. Write an exception entry into an output log. Abnormally end the application because the resource manager will not allow any further changes to the resource until the situation is resolved.
3A3 ATR_UR_TOKEN_INV	Meaning: Program error. The specified current_UR_token does not identify a valid UR. The system rejects this service request. Action: Check the calling program for a probable coding error. Correct the calling program and rerun it.
36B ATR_ACTION_INV	Meaning: Program error. The specified action value is not valid. The system rejects this service request. Action: Check the calling program for a probable coding error. Correct the calling program and rerun it.
731 ATR_UR_STATE_ERROR	Meaning: Program error. The UR for the current task is not in a valid state for this service request. The UR state must be in-reset or in-flight. The system rejects the request. Action: Check the calling program for a probable coding error. Correct the calling program and rerun it.
805 ATR_CUR_UR_TOKEN_ NOT_CURRENT	Meaning: Program error. The current UR token specified in the call does not match the token of the current UR. Note: The system takes no action against the current UR, so it is therefore possible that the current UR can be committed at a later time. Action: Check the calling program for a probable coding error. Correct the calling program and rerun it.
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.
F05 ATR_UNEXPECTED_CTX_ERROR	Meaning: Environmental error. The service call encountered an unexpected error from a context services service. The system rejects the service call. Action: Examine the dump from context services and correct the problem, then rerun the calling program.
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, an application issues an End_Transaction call to tell RRS to commit a transaction. Storage for the call parameters has been allocated.

⋮
ACT = ATR_COMMIT
CUR = MY_CURRENT_UR
CALL ATREND(RC,DIAG_DATA,ACT,CUR)
⋮