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:
1. Communicates with another system to determine its prepare vote for the UR
2. 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:
1. Initiate the prepare phase of a syncpoint operation.
2. Obtain the result from the prepare vote collection.
3. Delay and control the initiation of commit or backout processing.
4. 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 */
⋮