- ATRSSPC is for AMODE(31) callers.
- ATR4SSPC is for AMODE(64) callers and allows parameters in 64
bit addressable storage.
A resource manager calls the Set_Syncpoint_Controls service in
a distributed environment. Set_Syncpoint_Controls defines the role
the resource manager will play in processing a UR. Your resource manager
can also use the call to set return codes for exit routines that you
want RRS to bypass. In response to the call, RRS returns a return
code.
A distributed syncpoint resource manager (DSRM) usually issues
this call in its STATE_CHECK or PREPARE exit routine. A server distributed
syncpoint resource manager (SDSRM) usually issues this call before
it initiates a syncpoint operation.
Resource Manager Role in UR Processing: The possible roles
for the resource manager for the specified interest in a unit of recovery
(UR) are:
- Distributed syncpoint resource manager (DSRM): The resource
manager becomes the DSRM and coordinator for the UR. RRS changes from
its usual role of coordinator for a UR into an agent of the coordinator.
RRS expects the DSRM to be using a peer-to-peer protocol.
When
it specifies this role, the Set_Syncpoint_Controls service enables
the resource manager's DISTRIBUTED_SYNCPOINT exit routine. When the
local interests in a UR vote to commit the UR, RRS gives control to
this routine. For the in-doubt UR, the DISTRIBUTED_SYNCPOINT
exit routine:
- Communicates with another system to determine its prepare vote
for the UR
- Returns the overall commit or backout vote to RRS
- Server distributed syncpoint resource manager (SDSRM):
The resource manager becomes the SDSRM and coordinator for the UR.
RRS changes from its usual role of coordinator for a UR into an agent
of the coordinator. RRS expects the SDSRM to be using a client/server
protocol.
When it specifies this role, the Set_Syncpoint_Controls
service disables the resource manager's ONLY_AGENT exit routine and
enables it to use the following services: Backout_Agent_UR, Commit_Agent_UR,
Forget_Agent_UR_Interest, and Prepare_Agent_UR. These services allow
the resource manager to:
- Initiate the prepare phase of a syncpoint operation.
- Obtain the result from the prepare vote collection.
- Delay and control the initiation of commit or backout processing.
- Control the deletion of its entries from log records.
See Protecting distributed resources for more information.
- Last agent participant: The resource manager becomes the
last agent for a distributed syncpoint operation. RRS continues its
usual role as coordinator.
For additional information about the
roles involved in a distributed syncpoint operation, see
SNA
Sync Point Services Architecture
- Participant: The resource manager takes part in the UR
interest; participant is the resource manager's usual role.
As
necessary, a resource manager that has assumed another role can reset
itself to participant. Also, any resource manager that wants to prevote
exit routines can call Set_Syncpoint_Controls to take the role of
participant. If a UR is in local transaction mode, participant
is the only role a resource manager can have.
When it hardens information for the interest in an RRS log, RRS
records the resource manager's role. However, if the UR state is in-prepare,
RRS might not record the role and options specified in the Set_Syncpoint_Controls
call.
Notes on changing roles: For
any interest in a particular UR, RRS prevents any resource manager
from successfully calling the Set_Syncpoint_Controls service
to request the DSRM, SDSRM, or last agent participant role if any
of the following are true:
- A resource manager already has the distributed syncpoint resource
manager (DSRM) role for the UR.
- A resource manager already has the server distributed syncpoint
resource manager (SDSRM) role for the UR.
- A resource manager already has the last agent participant role
for the UR.
- The UR is a cascaded UR.
A communication resource manager with multiple interests in a UR
can move a role from one of its interests to another. The movable
roles are:
- Distributed syncpoint resource manager
- Server distributed syncpoint resource manager
- Last agent participant
To move a role, the resource manager must call the Set_Syncpoint_Controls
service twice, in the following order;
- For one interest, reset its role to participant from its original
role.
- For the other interest, reset its role from participant to the
desired role.
The resource manager is responsible for serializing its processing
to make the resets in the correct order.
Once a syncpoint operation has started, the SDSRM role cannot be
changed.
Exit routine return codes: In
the call, you can specify whether or not RRS is to invoke each of
the following exit routines:
- PREPARE exit routine
- COMMIT exit routine
- BACKOUT exit routine
For an interest in a local transaction, a resource manager can
prevote only its COMMIT and BACKOUT exits.
If you want RRS to bypass an exit routine, you provide the exit
routine's return code on the call.
Note: Your resource manager might need to know whether an RRS panel
was used to resolve an in_doubt UR or when a resync for the
UR is in progress. If so, do not bypass the COMMIT and/or BACKOUT
exit routines unless you provide an END_UR exit routine.
Environment
The requirements for the caller
are:
Minimum authorization: |
PKM allowing key 0-7, or supervisor state |
Dispatchable unit mode: |
Task or SRB |
Cross memory mode: |
Any PASN, any HASN, any SASN |
AMODE: |
31 bit (ATRSSPC)
64 bit (ATR4SSPC)
|
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 restrictions for the call
are:
- The state of the resource manager associated with the specified
UR interest token must be run.
- The UR state must be in-flight, in-state-check,
or in-prepare. To change to or from the SDSRM role, the UR
state must be in-flight.
- The resource manager's interest must be a protected interest if
the requested role is distributed syncpoint resource manager, server
distributed syncpoint resource manager, or last agent participant.
- If the UR transaction mode is local, a resource manager cannot
change its role from ATR_PARTICIPANT.
- To set the role of DSRM, your resource manager needs a DISTRIBUTED_SYNCPOINT
exit routine.
If your resource manager calls the Set_Syncpoint_Controls
service asynchronously for a UR in an in-flight state, there
is no way to ensure that the service will be invoked before the application
issues a commit UR request or a backout UR request. In this case,
your resource manager must have a PREPARE or STATE_CHECK exit routine,
even if you expect to use the call to Set_Syncpoint_Controls to set
the return code for the PREPARE exit routine.
A better alternative
is either to call Set_Syncpoint_Controls from within a STATE_CHECK
exit routine or to call Set_Syncpoint-Controls before the application
code can get control.
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 ATRSSPC
|
(return_code
,ur_interest_token
,prepare_exit_code
,commit_exit_code
,backout_exit_code
,role)
|
CALL ATR4SSPC
|
(return_code
,ur_interest_token
,prepare_exit_code
,commit_exit_code
,backout_exit_code
,role)
|
Parameters
The parameters are explained
as follows:
- return_code
- Returned parameter
- Type: Integer
- Length: 4 bytes
Contains the return code from the Set_Syncpoint_Controls
service.
- ,ur_interest_token
- Supplied
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
Specifies the UR interest token that identifies an instance
of your resource manager's interest in a UR. Your resource manager
received the token from the Express_UR_Interest service or the Retain_Interest
service.
- ,prepare_exit_code
- Supplied parameter
- Type: Integer
- Length: 4 bytes
Specifies whether RRS is to invoke the PREPARE exit routine:
- To invoke your resource manager's PREPARE exit routine, specify ATR_DRIVE_PREPARE_EXIT.
- To bypass your resource manager's PREPARE exit, specify ATR_PREPARE_OK
or ATR_PREPARE_ABSTAIN to set the return code that the PREPARE exit
routine would have returned.
Note: If the UR state is in-prepare or if the
UR is in local transaction mode, RRS ignores the prepare_exit_code parameter.
Specify
one of the following:
Constant in:
Hexadecimal
(Decimal)
Equate Symbol
|
Invoke the PREPARE exit routine? |
PREPARE exit routine return code |
---|
0
(0)
ATR_PREPARE_OK
|
No |
ATRX_OK |
14
(20)
ATR_PREPARE_ABSTAIN
|
No |
ATRX_ABSTAIN To set this value, the resource manager should:
- Be the DSRM or SDSRM
- Have an END_UR exit routine
|
FFF
(4095)
ATR_DRIVE_PREPARE_EXIT
|
YES |
|
- ,commit_exit_code
- Supplied parameter
- Type: Integer
- Length: 4 bytes
Specifies whether RRS is to invoke the COMMIT exit routine:
- To invoke your resource manager's COMMIT exit routine, specify ATR_DRIVE_COMMIT_EXIT.
- To bypass your resource manager's exit routine, set the return
code for the COMMIT exit routine.
Specify one of the following:
Constant in:
Hexadecimal
(Decimal)
Equate Symbol
|
Invoke the COMMIT exit routine? |
COMMIT Exit routine return code |
---|
0
(0)
ATR_COMMIT_OK
|
No |
ATRX_OK |
FFF
(4095)
ATR_DRIVE_COMMIT_EXIT
|
Yes |
|
- ,backout_exit_code
- Supplied parameter
- Type: Integer
- Length: 4 bytes
Specifies whether the resource manager is to invoke the
BACKOUT exit routine:
- To invoke your resource manager's BACKOUT exit routine, specify ATR_DRIVE_BACKOUT_EXIT.
- To bypass your resource manager's exit routine, set the return
code for the BACKOUT exit routine.
Specify one of the following:
Constant in:
Hexadecimal
(Decimal)
Equate Symbol
|
Invoke the BACKOUT exit routine? |
BACKOUT exit routine return code |
---|
0
(0)
ATR_BACKOUT_OK
|
No |
ATRX_OK |
FFF
(4095)
ATR_DRIVE_BACKOUT_EXIT
|
Yes |
|
- ,role
- Supplied
parameter
- Type: Integer
- Length: 4 bytes
Defines the role your resource manager wants to take for
the specified UR interest. Specify one of the following:
Constant in:
Hexadecimal
(Decimal)
Equate Symbol
|
Description |
---|
0
(0)
ATR_PARTICIPANT
|
Participant: For this interest, the resource manager
is to be a participant. |
1
(1)
ATR_LAST_AGENT
|
Last-agent participant: For this interest, the resource
manger is to be the last-agent participant. Specify this role only
if the UR interest token represents a protected interest. |
2
(2)
ATR_DSRM
|
Distributed syncpoint resource manager: For this interest,
the resource manager is to be the distributed syncpoint resource manager.
Specify this role only if the UR interest token represents a protected
interest. |
3
(3)
ATR_SDSRM
|
Server distributed syncpoint resource manager: For
this interest, the resource manager is to be the server distributed
syncpoint resource manager. Specify this role only when the UR interest
token represents: - A protected interest
- A UR that is in-flight
|
ABEND codes
The call might result in an
abend X'5C4' with a reason code of either X'00120000' or X'00120001'.
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.
|
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 supports RRS. Then rerun the resource manager.
|
370
ATR_URI_TOKEN_INV
|
Meaning: Program error. The UR interest token specified
in the call is not one of the currently valid interests. The system
rejects the service call. Action: Check the resource manager
for a probable coding error. Correct the resource manager and rerun
it.
|
373
ATR_PREPARE_CODE_INV
|
Meaning: Program error. The prepare_exit_code value
specified in the call is 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.
|
374
ATR_COMMIT_CODE_INV
|
Meaning: Program error. The commit_exit_code value
specified in the call is 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.
|
387
ATR_PREPARE_CODE_INCORRECT
|
Meaning: Program error. The prepare_exit_code value
specified in the call is incorrect. Action: Check the
resource manager for a probable coding error. Correct the resource
manager and rerun it.
|
390
ATR_ROLE_INV
|
Meaning: Program error. The role specified in the
call in 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.
|
394
ATR_BACKOUT_CODE_INV
|
Meaning: Program error. The backout_exit_code value
specified in the call is 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.
|
701
ATR_RM_STATE_ERROR
|
Meaning: Program error. The resource manager associated
with the UR interest token specified in the call is not in a valid
state to issue the service call. The resource manager state must
be run. The system rejects the service call. Action:
Check the resource manager for a probable coding error. Correct
the resource manager and rerun it.
|
702
ATR_RM_EXITS_UNSET
|
Meaning: Program error. RRS has unset the RRS exit
routines for the resource manager. The system rejects the service
call. Action: Check the resource manager for a probable
coding error. Correct the resource manager and rerun it.
|
731
ATR_UR_STATE_ERROR
|
Meaning: Program error. The UR is not in a valid state
for the service call. The UR state must be in-flight, in-state-check,
or in-prepare. The system rejects the service call. Action:
Check the resource manager for a probable coding error. Correct
the resource manager and rerun it.
|
732
ATR_NO_DIST_SYNC_EXIT
|
Meaning: Program error. A resource manager that has
taken the DSRM role did not set a DISTRIBUTED_SYNCPOINT exit routine
with RRS. The system rejects the service call. Action:
Check the resource manager for a probable coding error. Correct
the resource manager and rerun it.
|
733
ATR_SSPC_ROLE_ERROR_DSRM
|
Meaning: Program error. A resource manager has already
obtained the distributed syncpoint resource manager role in a call
to Set_Syncpoint_Controls. This action prevents subsequent calls for
this UR to Set_Syncpoint_Controls for either the distributed syncpoint
resource manager role, the server distributed syncpoint manager role,
or the last agent role. The system rejects the service call. Action:
Check the resource manager for a coding error. Correct the resource
manager and rerun it.
If your resource manager does not have
a coding error, this problem may be beyond its control. Your resource
manager might need to take other actions, such as interacting with
the system operator, to indicate that this UR cannot be processed
successfully.
Another possible approach is to call the Set_Side_Information
service to set backout required for the UR.
|
734
ATR_SSPC_ROLE_ERROR_LAST_AGENT
|
Meaning: Program error. A resource manager has already
obtained the last agent role in a call to the Set_Syncpoint_Controls
service. This action prevents subsequent calls for this UR to the
Set_Syncpoint_Controls service for either the distributed syncpoint
resource manager role or the last agent role. The system rejects the
service call. Action: Check the resource manager for a
coding error. Correct the resource manager and rerun it.
If
your resource manager does not have a coding error, this problem may
be beyond control by the resource manager. Your resource manager
might need to take other actions, such as interacting with the system
operator, to indicate that this UR cannot be processed successfully.
Another
possible approach is to call the Set_Side_Information service to set
backout required for the UR.
|
746
ATR_ROLE_INCORRECT
|
Meaning: Program error. The interest for the ur_interest_token specified
in the call is not protected, or the UR is in local transaction mode.
The specified role (ATR_DSRM, ATR_LAST_AGENT,
or ATR_SDSRM) is valid only for a protected interest
in a global or hybrid-global mode transaction. The system rejects
the service call. Action: Check the resource manager for
a probable coding error. Correct the resource manager and rerun it.
|
74B
ATR_SSPC_ROLE_ERROR_SERVER_
DSRM
|
Meaning: Program error. A resource manager has already
obtained the server distributed syncpoint resource manager role in
a call to Set_Syncpoint_Controls. This action prevents subsequent
calls for this UR to Set_Syncpoint_Controls for either the distributed
syncpoint resource manager role, the server distributed syncpoint
manager role, or the last agent role. The system rejects the service
call. Action: Check the resource manager for a coding
error. Correct the resource manager and rerun it.
If your
resource manager does not have a coding error, this problem may be
beyond its control. Your resource manager might need to take other
actions, such as interacting with the system operator, to indicate
that this UR cannot be processed successfully.
Another possible
approach is to call the Set_Side_Information service to set backout
required for the UR.
|
74F
ATR_ROLE_CHANGE_AFTER_SYNC
|
Meaning: Program error. The resource manager tried
to set a role change after a syncpoint operation had begun. The system
rejects the service call. Action: Check the resource manager
for a probable coding error. Correct the resource manager and rerun
it.
|
759
ATR_ROLE_ERROR_CASCADED_UR
|
Meaning: Program error. The specified UR is a cascaded
UR. Only the participant role is valid for cascaded URs. 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_Syncpoint_Controls 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
resource manager issues a call to request the distributed syncpoint
resource manager role and bypass the exit routines.
⋮
URI_TOKEN = MY_URI_TOKEN
PREP_CODE = ATR_PREPARE_ABSTAIN
CMIT_CODE = ATR_COMMIT_OK
BACK_CODE = ATR_BACKOUT_OK
ROLE = ATR_DSRM
CALL ATRSSPC(RC,URI_TOKEN,PREP_CODE,CMIT_CODE,BACK_CODE,ROLE)
IF RC ≠ ATR_OK THEN
/* Handle error */
⋮