Backout_UR (ATRBACK, ATR4BACK)

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

A resource manager or application program calls the Backout_UR service to indicate that the changes for the unit of recovery (UR) are not to be made. In response, RRS requests that the resource managers return their resources to the values they had before the UR was processed, then issues a return code to the caller.

This call performs the same services as the Application_Backout_UR (SRRBACK) service, with one exception: Backout_UR provides return codes for many error conditions that cause Application_Backout_UR to abnormally end the calling program with abend code X'5C4'. For a description of Application_Backout_UR, see z/OS MVS Programming: Callable Services for High-Level Languages.

Environment

The requirements for the caller are:

Minimum authorization:

None

Dispatchable unit mode:

Task

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31 bit (ATRBACK)
64 bit (ATR4BACK)

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

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. Backout_UR (ATRBACK, ATR4BACK) Programming requirements
HLL Definition	Description
ATRRASM	390 Assembler declarations
ATRRC	C/390 declarations

Restrictions

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

The UR must not be 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

None.

Syntax

Write the call as shown in the syntax diagram. You must code the parameters in the CALL statement as shown.

CALL ATRBACK

(return_code)

CALL ATR4BACK

(return_code)

Parameters

The parameters are explained as follows:

return_code

Returned parameter:

Type: Integer
Character set: N/A
Length: Full word

Contains the return code from the Backout_UR service.

ABEND codes

The call might result in an abend X'5C4' with a reason code of either X'00170000' or X'00170001'. 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 2. Backout_UR (ATRBACK, ATR4BACK) Return Codes
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 calling program is disabled; the interrupt status must be enabled for I/O and external interrupts. The system rejects the service call. 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 calling program is holding one or more locks; no locks can be held. The system rejects the service call. 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 the service call. Action: Remove the calling program from the system, and install it on a system that supports RRS. Then rerun the calling program.
12D ATR_BACKED_OUT_OUTCOME_PENDING	Meaning: Environmental error. RRS requested that the resource managers back out the changes to the resources. The backout was not completed. The reason might be that: A resource manager failed with a protected interest in an incomplete UR. RRS failed before UR processing is completed. RRS cannot determine if one or more of the protected resources was backed out. 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 requested backout of changes was completed; however, one or more of the protected resources were changed. Action: Same as the action for return code 12D.
731 ATR_UR_STATE_ERROR	Meaning: Program error. The UR is not in a valid state or a valid transaction mode for the service call. The UR state must be in-reset or in-flight. The transaction mode must not be local. The system rejects the service call. Action: Check the calling program for a probable coding error or an application environment configuration error. Correct the calling 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.
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: 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 calling program backs out a UR.

⋮
CALL ATRBACK (RC)
⋮