- 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)
⋮