Set_Syncpoint_Controls (ATRSSPC, ATR4SSPC)
- 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.
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) |
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 |
FOMURRC | z/OS HFS header files |
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
- 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
- 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 |
|
CALL ATR4SSPC |
|
Parameters
- 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 SymbolInvoke the PREPARE exit routine? PREPARE exit routine return code 0
(0)
ATR_PREPARE_OKNo ATRX_OK 14
(20)
ATR_PREPARE_ABSTAINNo 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_EXITYES - ,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 SymbolInvoke the COMMIT exit routine? COMMIT Exit routine return code 0
(0)
ATR_COMMIT_OKNo ATRX_OK FFF
(4095)
ATR_DRIVE_COMMIT_EXITYes - ,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 SymbolInvoke the BACKOUT exit routine? BACKOUT exit routine return code 0
(0)
ATR_BACKOUT_OKNo ATRX_OK FFF
(4095)
ATR_DRIVE_BACKOUT_EXITYes - ,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 SymbolDescription 0
(0)
ATR_PARTICIPANTParticipant: For this interest, the resource manager is to be a participant. 1
(1)
ATR_LAST_AGENTLast-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_DSRMDistributed 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_SDSRMServer 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: |
Meaning and action |
---|---|
0 |
Meaning: Successful completion. Action: None. |
103 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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:
|
FFF |
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
⋮
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 */
⋮