Forget_Agent_UR_Interest (ATRAFGT, ATR4AFGT)

ATRAFGT is for AMODE(31) callers.
ATR4AFGT 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 Forget_Agent_UR_Interest to tell RRS to delete the SDSRM's interest in the specified unit of recovery (UR) and, depending on the log_option value, delete any log entries that exist. The log_option can be set in several ways, such as through the Commit_Agent_UR service or the Backout_Agent_UR service, or implicitly by RRS. The SDSRM should issue Forget_Agent_UR_Interest only when the log_option is ATR_DEFER_EXPLICIT.

If the call to Forget_Agent_UR_Interest specifies ATR_IMMEDIATE, then, if there is a log record, RRS deletes the SDSRM's interest and logs the UR without the SDSRM's interest to ensure that, during any subsequent restart processing, it never returns the UR to the SDSRM.

If the UR state is in-forget, there are no longer any incomplete interests in the UR; Forget_Agent_UR_Interest deletes the UR. Otherwise, Forget_Agent_UR_Interest changes the UR state from in-forget to forgotten. The input ur_interest_token is no longer valid, and the SDSRM no longer has any processing obligation related to this unit of recovery. If log_option is not ATR_DEFER_EXPLICIT, however, the UR interest might be returned on restart.

RRS serializes Forget_Agent_UR_Interest processing so that resource manager interests are not deleted while resource manager exit routines are running.

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 the application backs out the UR through a call to the Backout_UR service or the Application_Backout_UR service.
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.

RRS changes the log_option 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 (ATRAFGT)
64 bit (ATR4AFGT)

ASC mode:

Primary or access register (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:

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-commit, in-backout, in-end, in-completion, or in-forget.

If you are coding an RRS exit routine, do not call this service to process the UR passed to the exit routine in the ur_interest_token exit routine parameter.

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 ATRAFGT

(return_code
,ur_interest_token,
,log_option
);

CALL ATR4AFGT

(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 Forget_Agent_UR_Interest 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

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

Constant in Hexadecimal (Decimal) Equate Symbol	Description
X'0' (0) ATR_DEFER	Meaning: RRS is to logically delete the log record when the unit of recovery state changes to Forgotten.
X'2' (2) ATR_IMMEDIATE	Meaning: Before returning control to the SDSRM, RRS must delete the SDSRM's interest from the UR. RRS hardens a new log record without the interest.

ABEND codes

The call might result in an abend X'5C4' with a reason code of either X'001C0000' or X'001C0001'. 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: The operation completed successfully. Action: Continue normal processing.
10 ATR_OK_NO_CONTEXT	Meaning: The operation completed successfully. The UR state was in-completion or in-forget, and there was no associated context. Action: Continue normal processing.
11 ATR_FORGET_NOT_REQUIRED	Meaning: The specified ur_interest_token represents a UR that does not require the Forget_Agent_UR service. Action: Continue normal processing.
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. The system rejects this service request. Action: Check the calling program for a probable coding error.
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 Forget_Agent_UR for this interest. Action: The system rejects this service request. Call Respond_to_Retrieved_Interest, then call Forget_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 tells RRS to forget the unit of recovery. Storage for the call parameters has been allocated.

⋮
URI_TOKEN = MY_URI_TOKEN
FTOPT=ATR_DEFER
CALL ATRAFGT(RC,URI_TOKEN,FTOPT)
⋮