Begin_Transaction (ATRBEG, ATR4BEG)

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

A work manager calls the Begin_Transaction service to begin a transaction and set the transaction mode. Begin_Transaction allows an application to clearly mark the beginning boundary of a transaction. The transaction mode, which affects resource managers within the boundaries of this transaction, can be local or global, as follows:

In local mode, resource managers within the transaction boundaries must behave independently: the application can use RM-specific functions to commit and roll back any connections it might have to resource managers. If the application has multiple connections to the same resource manager, the resource manager treats the resources affected via each connection as completely separate for the purposes of syncpoint processing. Committing or backing out the resources affected by one connection does not affect the resources affected by another connection. RRS prevents the use of any global commit functions that would act upon a UR that is in local transaction mode. Local URs begun with Begin_Transaction must be ended with a call to the End_Transaction service.
In global mode, resource managers are to accept two-phase commit cues from RRS, and all updates made through RRS-compliant resource managers are made atomically. In global mode, an application cannot determine two different outcomes for any of its connections under a global unit of recovery; the resource managers prevent the application from using RM-specific local commit functions.

Environment

The requirements for the caller are:

Minimum authorization:

Any

Dispatchable unit mode:

Task

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31 bit (ATRBEG)
64 bit (ATR4BEG)

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

The current UR state must be in-reset.

The current default environment setting for transaction mode must not be hybrid-global.

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 ATRBEG

(return_code
,diag_area
,transaction_mode
,ur_token
,ur_identifier)

CALL ATR4BEG

(return_code
,diag_area
,transaction_mode
,ur_token
,ur_identifier)

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

,diag_area

Returned parameter

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

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

,transaction_mode

Supplied parameter

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

Indicates the transaction mode of the transaction to be started. Specify one of the following:

Constant in: Hexadecimal (Decimal) Equate Symbol	Description
1 (1) ATR_GLOBAL_MODE	Set the transaction mode for the current UR to global, and set the UR state to In-Flight.
2 (2) ATR_LOCAL_MODE	Set the transaction mode for the current UR to local, and set the UR state to In-Flight.

,ur_token

Returned parameter

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

Receives the token that uniquely represents the new UR. UR tokens do not persist across restarts of the resource manager, RRS, or the system.

,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. URIDs returned for global URs persist across restarts of the resource manager, RRS, or the system. URIDs are also returned for local URs, but they do not persist across failures because RRS does not harden any information about local URs.

ABEND codes

The call might result in an abend X'5C4' with a reason code of either X'00023000' or X'00023001'. See z/OS MVS System Codes for the explanations and actions.

Return codes

When the service returns control to the resource manager, GPR 15 and return_code contain a hexadecimal return code.

Return Code in: Hexadecimal Equate Symbol	Meaning and action
0 ATR_OK	Meaning: Successful completion. Action: None.
103 ATR_INTERRUPT_STATUS_INV	Meaning: Program error. The resource manager is disabled; the interrupt status must be enabled for I/O and external interrupts. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
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 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.
363 ATR_TRAN_MODE_INV	Meaning: Program error. The transaction mode specified in the call was 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 associated with the context specified in the call is ending. The system rejects the service call. Action: None.
731 ATR_UR_STATE_ERROR	Meaning: Program error. The UR is not in a valid state for the service call. The UR must be in the in-reset state. RRS does not support nested transactions. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
804 ATR_HYBRID_GLOBAL_MODE_ERROR	Meaning: Program error. The current RRS default for transaction mode is ATR_HYBRID_GLOBAL_MODE; hybrid-global mode is not valid for this service. 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.
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 work manager issues a call to begin a local transaction.

⋮
TRAN_MODE = ATR_LOCAL_MODE
CALL ATRBEG(RC,DIAG_DATA,TRAN_MODE,UR_TOKEN,URID)
IF RC = ATR_OK THEN
⋮