Set_Syncpt_Options

Equivalent to:

LU 6.2 Set_Syncpt_Options
(No CPI equivalent)

Changes the default system values that govern APPC/MVS processing during its participation in the two-phase commit protocol for resource recovery processing. The following options and their default values are in effect for each TP that issues Commit calls, for all protected conversations in which the TP participates, from the time the TP begins processing until Set_Syncpt_Options is issued to change them:

Option: System Default Value
Vote_Read_Only_Permitted: NO
Wait_For_Outcome: YES
Action_If_Problems: BACKOUT

The TP must specify valid values for all parameters on each invocation of Set_Syncpt_Options service.

For a call to Set_Syncpt_Options to complete successfully, TP resources must be associated with the calling address space. TP resources are associated with the calling address space after:

A call to the CPI-C Initialize Conversation (CMINIT) service
A call to the LU 6.2 Allocate service
A call to the Register_for_Allocate service
A call to the Define_Local_TP service

A program may successfully call Set_Syncpt_Options in the following situations as well:

After an alternate transaction scheduler's XCF message user routine has received an Allocate TP request message for the TP
After an alternate transaction scheduler receives and processes an Allocate TP request, and the TP begins running
Before a call to either the Get_Conversation, or the CPI-C Accept_Conversation (CMACCP) service.

Requirements

Authorization:

Supervisor state or problem state, any PSW key

Dispatchable unit mode:

Task or SRB mode

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31-bit

ASC mode:

Primary or access register (AR)

Interrupt status:

Enabled for I/O and external interrupts

Locks:

The caller cannot hold any locks

Control parameters:

All parameters must be addressable by the caller and in the primary address space.

Format

Figure 1. ATBSSO4 - LU 6.2 Set_Syncpt_Options

CALL ATBSSO4(
        Vote_Read_Only_Permitted,
        Wait_For_Outcome,
        Action_If_Problems,
        Reason_code,
        Return_code
       );

Parameters

Vote_Read_Only_Permitted

Supplied parameter

Type: Integer
Char Set: N/A
Length: 32 bits

Vote_Read_Only_Permitted specifies whether the local LU may vote read only in a syncpoint operation, if:

The local LU has made no changes to protected resources, and
None of the resource managers subordinate to the local LU, in the distributed transaction, have made any changes.

Valid values for this parameter are:

Value: Meaning
0: Specifies that the current value for this parameter should remain in effect (no change to the current setting).
1: NO
Specifies that voting read-only in a syncpoint operation is not allowed.
2: YES
Specifies that voting read-only in a syncpoint operation is allowed.

Wait_For_Outcome

Supplied parameter

Type: Integer
Char Set: N/A
Length: 32 bits

Wait_For_Outcome specifies whether the outcome of the syncpoint operation, at all subordinate resources in the distributed transaction, must be known before control is returned to the program. If a failure occurs and the TP specified Wait_For_Outcome with a value of 1 (NO), the system might return control from the Commit call with a return code value of rr_*_outcome_pending. This return code value indicates that the outcome at one or more distributed partners is unknown.

If the TP specified Wait_for_Outcome with a value of 2 (YES), the system does not return control until the outcome of the syncpoint operation at all subordinate resources is known.

Note: Even if the local TP specifies a value of 2 (YES), the system might return control before the outcome is fully known, if other programs in the distributed transaction specified Wait_for_Outcome with 1 (NO).

Valid values for this parameter are:

Value: Meaning
0: Specifies that the current value for this parameter should remain in effect (no change to the current setting).
1: NO
Specifies that the TP does not need to wait for the outcome of the syncpoint operation before regaining control.
2: YES
Specifies that the TP must wait for the outcome of the syncpoint operation before regaining control.

Action_If_Problems

Supplied parameter

Type: Integer
Char Set: N/A
Length: 32 bits

Action_If_Problems specifies the action taken by APPC/MVS when a unit of recovery associated with the TP is in the IN-DOUBT state and APPC/MVS receives an unrecognized message (a protocol violation) from the partner (syncpoint initiator) that is supposed to instruct it to commit or backout the unit of recovery.

Valid values for this parameter are:

Value: Meaning
0: Specifies that the current value for this parameter should remain in effect (no change to the current setting).
1: Commit
Specifies that the LU should instruct the syncpoint manager to heuristically commit the unit of recovery because the overall decision of the syncpoint initiator is unknown.
2: Backout
Specifies that the LU should instruct the syncpoint manager to heuristically backout the unit of recovery because the overall decision of the syncpoint initiator is unknown.

Reason_code

Returned parameter

Type: Integer
Length: 32 bits

Reason_code contains additional information about the result of the call when the return_code parameter contains a nonzero value.

Table 1 lists the return and reason codes, their values, and meanings, associated with the Set_Syncpt_Options service return codes.

Table 1. Return and Reason Codes for Set_Syncpt_Options
Return Code (Decimal)	Reason Code (Decimal)	Value, Meaning, and Action
0	—	Value: atb_ok Meaning: The call completed successfully. System Action: The system continues processing. Application Programmer Response: None required.
20	All	Value: atb_product_specific_error Meaning: The service was unsuccessful. APPC/MVS detected an environmental error during the processing of this callable service. See Table 1 for the list of reason codes that accompany the product_specific_error return code. System Action: The system returns a product_specific_error (decimal 20) return code to the caller of the service. APPC/MVS writes a logrec data set record that describes the error. The system might request an SVC dump. Application Programmer Response: Contact the system programmer. System Programmer Response: Contact the IBM Support Center. Provide the logrec data set error record and the SVC dump (if one is available).
24	All	Value: atb_program_parameter_check Meaning: A user-supplied parameter was found to be in error. For example, a parameter contains characters not in the required character set. System Action: The system returns a program_parameter_check (decimal 24) return code to the caller. Application Programmer Response: See the value returned in the Reason_code parameter to determine the specific parameter that contained an invalid value. Supply a valid value and re-issue the service call.
24	1	Value: atb_invalid_vote_read_only Meaning: The specified Vote_read_only_permitted parameter does not contain a valid value. System Action: The system returns a program_parameter_check (decimal 24) return code to the caller. Application Programmer Response: Provide a valid value for the Vote_read_only_permitted parameter and re-issue the service call.
24	2	Value: atb_invalid_wait_for_outcome Meaning: The specified Wait_for_outcome parameter does not contain a valid value. System Action: The system returns a program_parameter_check (decimal 24) return code to the caller. Application Programmer Response: Provide a valid value for the Wait_for_outcome parameter and re-issue the service call.
24	3	Value: atb_invalid_action_if_problems Meaning: The specified Action_if_problems parameter does not contain a valid value. System Action: The system returns a program_parameter_check (decimal 24) return code to the caller. Application Programmer Response: Provide a valid value for the Action_if_problems parameter and re-issue the service call.
25	All	Value: atb_program_state_check Meaning: The local TP called a service while running in a state in which the call is not valid. System Action: The system returns a program_state_check (decimal 25) return code to the caller, and APPC/MVS might write a symptom record in the logrec data set, which provides further information about the program state check. Application Programmer Response: See the Application Programmer Response for the specific reason code that was returned on the service call.
25	4	Value: atb_extract_exit_not_specified Meaning: An APPC/MVS service was invoked in an address space that has more than one active TP. APPC/MVS could not associate the request with a TP because the transaction scheduler for the address space did not specify an extract exit. System Action: The system returns a program_state_check (decimal 25) return code to the caller. Application Programmer Response: Contact the system programmer. System Programmer Response: Contact the owner of the scheduler product. Ask the owner of the scheduler to ensure that the scheduler product specifies an extract exit. See the description of the Identify service in z/OS MVS Data Areas, Vol 1for information about how to establish an extract exit.
25	5	Value: atb_extract_exit_failed Meaning: A TP called an APPC/MVS conversation service in an address space where more than one TP was running. APPC/MVS called the transaction scheduler extract exit to identify the active TP. The exit returned a non-zero return code to APPC/MVS. System Action: The system returns a program_state_check (decimal 25) return code to the caller and APPC/MVS writes a symptom record in the logrec data set. Application Programmer Response: Contact the system programmer. System Programmer Response: See the symptom record in the logrec data set for a description of the error. Check the return code from the transaction scheduler extract exit in the scheduler extract control block (ATBSECB) in section 5 of the symptom record. The ATBSECB is in the first key-length-data structure in section 5. See z/OS MVS Data Areas, Vol 1for a description of the ATBSECB.
25	6	Value: atb_no_active_tp Meaning: The call for this service was performed prior to APPC/MVS allocating resources for the calling address space. System Action: The system returns a program_state_check (decimal 25) return code to the caller. Application Programmer Response: Issue the service call after issuing one of the following APPC/MVS services that will associate TP resources to the calling address space: CPI-C Initialize_Conversation (CMINIT) LU 6.2 Allocate Register_For_Allocates Define_Local_TP Ensure that all the conditions required for a call to this service are met. See Set_Syncpt_Options.
25	7	Value: atb_service_error Meaning: A TP called an APPC/MVS conversation service. An internal error occurred in APPC/MVS processing. System Action: The system returns a program_state_check (decimal 25) return code to the caller and APPC/MVS writes a symptom record in the logrec data set. The system might request an SVC dump. Application Programmer Response: Contact the system programmer. System Programmer Response: Contact the IBM Support Center. Provide the logrec data set error record and the SVC dump (if one is available).

Return_code

Returned parameter

Type: Integer
Char Set: N/A
Length: 32 bits

Return_code specifies the return code that is returned to the local program. The following table contains general descriptions of the possible return code values. See Table 1 for descriptions of possible reason codes.

Characteristics and Restrictions

Transaction programs that call the Set_Syncpt_Options service while in task mode should not have any enabled unlocked task (EUT) functional recovery routines (FRRs) established. For more information about EUT FRRs, see the section on providing recovery in z/OS MVS Programming: Authorized Assembler Services Guide.

Note: If a TP calls Set_Syncpt_Options while a syncpoint operation is in progress for the current context under which the TP is running, the Set_Syncpt_Options request might not complete before APPC/MVS needs to refer to the syncpoint options during the syncpoint operation. In this case, the option values will not be changed in time for APPC/MVS to use the new values. Instead, APPC/MVS uses the option values in effect before the TP issued the call to Set_Syncpt_Options. Whenever possible, design APPC/MVS programs to issue the call to Set_Syncpt_Options before a syncpoint operation begins.