- ATRSPSP2 is for AMODE(31) callers.
- ATR4SPSP is for AMODE(64) callers and allows parameters in 64
bit addressable storage.
A work manager calls the Set_Post_Sync_PET service to enable a
program to know when a syncpoint completes and receive information
about that syncpoint without actually expressing interest in a UR
or work context. The caller provides a pause element token (PET) to
be associated with a target UR. RRS will release the pause element
designated by the specified PET when the context the UR is associated
with can either be reused for a new UR or ended without RRS holding
up the process. This occurs when the UR reaches the
forgotten state,
except under the following circumstances:
- When the UR syncpoint is under the control of an SDSRM and circumstances
require the SDSRM to issue a Forget_Agent_UR_Interest call before
the UR can reach the forgotten state. In this case, RRS will
release the PET when the UR reaches the in-forget state.
- When a COMPLETION exit returned the ATRX_LATER_CONTINUE return
code and RRS is going to give control back to the application prior
to transitioning the UR to the forgotten state. In this case,
RRS will release the PET when the UR is in the in-completion state
when all exits finished or returned ATRX_LATER_CONTINUE.
- When RRS fails. RRS will ensure that the PET is released with
an appropriate release code. The state of the UR cannot be determined.
When RRS issues a release, it will specify a release code that
contains information about the results of the UR.
If you create cascaded transactions, you can also use the Set_Post_Sync_PET
service to determine when a cascaded transaction has completed.
Note: RRS will consider each PET associated with a UR as the equivalent
of an expression of interest when queried by the Retrieve_Interest_Count
service.
Because setting a post-syncpoint PET does not cause the UR state
to change from in-reset to in-flight, it is possible
for the transaction mode to change after the PET is associated with
a UR. The PET is released when the UR completes, regardless of the
transaction mode. In addition to normal syncpoint completion, a UR
in local transaction mode is considered complete when all resource
manager interests in it are deleted. The release code provides an
indication of the transaction mode at the time RRS releases the PET.
Environment
The requirements for the caller
are:
Minimum authorization: |
None |
Dispatchable unit mode: |
Task or SRB |
Cross memory mode: |
Any PASN, any HASN, any SASN |
AMODE: |
31 bit (ATRSPSP2)
64 bit (ATR4SPSP)
|
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: |
MVS™ standard 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
For the call, the UR state
must be in-reset or in-flight.
When the resource
manager issues the call in SRB mode, the call cannot specify a ur_token of
0, indicating information for the current UR.
A PKM 8–15 problem
state caller must specify a PET for a Pause Element allocated with auth_level=IEA_UNAUTHORIZED.
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 ATRSPSP2
|
(return_code
,UR_token
,pause_element_token)
|
CALL ATR4SPSP
|
(return_code
,UR_token
,pause_element_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 Set_Post_Sync_PET service.
- ,UR_token
- Supplied parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
Specifies the token of the UR to which the PET specified
by
pause_element_token is to be associated:
- 0: Binary zero specifies the current UR associated with the application's
task.
- token: The UR token of a particular
UR.
- ,pause_element_token
- Supplied parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
Specifies the pause element token to be associated with the
UR specified by the UR_token. When the UR
reaches the forgotten state (or one of the other conditions
specified in the description of this service call), RRS will release
the pause element specified by the pause_element_token.
Pause
element tokens are not preserved across system or RRS failures. Any
PETs that are associated with URs via the Set_Post_Sync_PET service
will be released if RRS terminates.
When the pause element
is released, RRS will place a set of flags in the release code. The
flags are:
Bit
Flag name
|
Meaning, if Bit is On |
---|
0
ATRRCODENORRS
|
RRS will always set this bit to 0. An application can release
the pause element with this bit set to indicate to the resource manager
that RRS did not release it. |
1
ATRRCODERRSFAILED
|
RRS terminated. Bits 2–23 have undefined contents. |
2–8 |
Reserved. |
9
ATRRCODETERMINATINGSYNCPOINT
|
The context is ending. RRS issued an implicit commit or backout
for the UR. There cannot be any more new URs for this context. |
10
ATRRCODERESOLVEDBYINSTALLATION
|
The installation used an RRS panel to commit or back out the
UR, which had been in an in-doubt state. |
11
ATRRCODEHEURISTICMIXED
|
RRS detected a heuristic-mixed condition for this UR. |
12
ATRRCODERESYNCINPROGRESS
|
RRS detected a resync in progress for this UR. |
13
ATRRCODEPREPARERESULTFORGET
|
The collected prepare vote was forget. |
14
ATRRCODEIMMEDIATEBACKOUT
|
Backout was requested by the application. |
15 |
Reserved. |
16
ATRRCODECOMMIT
|
If set, the overall vote for the UR is commit. If not set,
and ATRRCODEPREPARERESULTFORGET is not set, the overall vote for the
UR is backout. |
17–18 |
Reserved. |
19
ATRRCODECASCADEDUR
|
The UR is a cascaded UR. |
20
ATRRCODELOCALMODE
|
If set, the UR was in local transaction mode. If this bit is
set, then ATRRCODEGLOBALMODE cannot also be set. If neither is set,
then the UR was in hybrid-global transaction mode (ATRRCODEHYBRIDGLOBALMODE). |
21
ATRRCODEGLOBALMODE
|
If set, the UR was in global transaction mode. If this bit
is set, then ATRRCODELOCALMODE cannot also be set. If neither is set,
then the UR was in hybrid-global transaction mode (ATRRCODEHYBRIDGLOBALMODE). |
22–23 |
Reserved. |
ABEND codes
The call might result in an
abend X'5C4' with a reason code of either X'00200000' or X'00200001'.
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 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 specified
0 in UR_token, indicating the context associated
with the current UR, but the calling program is not in task 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 must 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 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.
|
3A3
ATR_UR_TOKEN_INV
|
Meaning: Program error. The UR token specified in
the UR_token parameter is not valid. The
system rejects the service call. Action: Check the calling
program for a probable coding error. Correct the program and rerun
it.
|
3A6
ATR_PET_INV
|
Meaning: Program error. The pause element token specified
in the pause_element_token parameter is
not valid. The system rejects the service call. Action:
Check the calling program for a probable coding error. Correct the
program and rerun it.
|
3A7
ATR_PET_OUTDATED
|
Meaning: Program error. The pause element token specified
in the pause_element_token parameter is
outdated. The system rejects the service call. Action:
Check the calling program for a probable coding error. Correct the
program and rerun it.
|
3A8
ATR_PET_AUTH_FAILURE
|
Meaning: Program error. The pause element token specified
in the pause_element_token parameter was
allocated with auth_level=IEA_AUTHORIZED,
and the caller is unauthorized. The system rejects the service call. Action:
Check the calling program for a probable coding error. Correct the
program and rerun it.
|
3A9
ATR_PET_SPACE_FAILURE
|
Meaning: Program error. The pause element token specified
in the pause_element_token parameter represents
a pause element belonging to another address space, and the caller
is unauthorized. The system rejects the service call. Action:
Check the calling program for a probable coding error. Correct the
program and rerun it.
|
731
ATR_UR_STATE_ERROR
|
Meaning: Program error. The UR specified by the UR_token is
not in a valid state for the service call. The UR must be in an in-reset or in-flight state.
The system rejects the service call. Action: Check the
resource manager for a probable coding error. Correct the resource
manager 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.
|
F06
ATR_WAS_NOT_AVAILABLE
|
Meaning: RRS was available to the resource manager,
but went down and came back up again. A commit or backout operation
may or may not have been in progress for the context under which the
Set_Post_Sync_PET was done at the time of the RRS failure. A new unit
of recovery can not be created until the current unit of recovery
is completed.
Action: The system rejects the service
request. Restart your resource manager, making sure to reset the resource
manager's exit routines with RRS.
The resource manager must
inform the application that one of the following actions must be taken
to complete the current unit of recovery: - If a commit or backout request was not active at the time of the
RRS failure, a commit or backout must be requested before a new unit
of recovery can begin.
- If a commit or backout request was active at the time of the RRS
failure, the context must be ended, via the CTXENDC service, before
a new unit of recovery can begin.
|
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 attempts to associate a UR a pause element token.
Storage for the call parameters has already been allocated.
⋮
CALL ATRSPSP2(RC, URTOKEN, PETOKEN)
⋮