Change Commitment Options (QTNCHGCO) API

The Change Commitment Options (QTNCHGCO) API changes the current commitment options. This API will change the commitment options for the commitment definition associated with the activation group for the HLL program that called the API. Commitment options for any other commitment definition will not be affected.

These options affect the operation of the system during a two-phase commit operation. The OS/400 implementation of two-phase commit is based on the SNA LU 6.2 protocol. Beginning in Version 3 Release 7 Modification 0, the i5/OS (OS/400) implementation supports the presumed abort architecture and its optimizations that are described in the SNA LU 6.2 protocol. The details of this protocol and the relationships between locations that support the presumed abort architecture and those that support the presumed nothing architecture, should be understood before changing these options. See the Commitment control topic, LU 6.2 Reference: Peer Protocols, SC31-6808, and Transaction Programmer's Reference Manual for LU Type 6.2, GC30-3084, for detailed information.

Authorities and Locks

None.

Required Parameter Group

Commitment options

INPUT; CHAR(*)

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Commitment Options Format

Field Descriptions

Accept vote reliable. Whether this location accepts the vote reliable indicator if it is received from its agents during the prepare wave of a commit operation. The vote reliable indicator indicates that it is unlikely that a heuristic decision will be made at the agent if a failure occurs before the committed wave completes. If an agent sends the vote reliable indicator, and this location accepts it, performance is improved because one communications flow is eliminated and control is returned to the application before the committed wave is completed for that agent. However, if a heuristic decision that causes heuristic damage is made at that agent, the application at this location will not receive an error message if the Accept vote reliable commitment option is set to Y.

The valid options are:

When the commitment definition was started, the value for this option was set to Y.

Note: If the commitment definition has a Wait for outcome value of Y or wait, or inherits a value of wait, the value of the Accept vote reliable commitment option is ignored, and the system behaves as though the Accept vote reliable commitment option is No.

See the Commitment control topic for more information about the vote reliable indicator.

Action if ENDJOB. The action to take for changes associated with this logical unit of work when the job in which the logical unit of work is a part of is ended during a commit operation while the status of resources is in doubt.

The valid options are:

When the commitment definition was started, the value for this option was set to W.

Note: Setting this option to R or C may lead to inconsistencies in the database if a job is ended during a commit operation while the status of resources is in doubt.

Action if problems. The action to take if the system receives an unrecognized message or detects damage in the logical unit of work.

The valid options are:

When the commitment definition was started, the value for this option was set to R.

Last agent permitted. Whether a last agent can be selected when one is eligible to be selected during a commit operation. A last agent is eligible to be selected at the location that initiates a commit operation, and at locations that are selected as a last agent by the location that propagates the commit operation to that location.

Performance is usually enhanced when a last agent is selected because fewer interactions between this location and the last agent are required during a commit operation. However, if a communications failure occurs between a location and its last agent during a commit operation, the commit operation will not complete until resynchronization completes, regardless of the value of the Wait for outcome commitment option. Such a failure will be rare, but this option allows the application writer to consider the negative impact of causing the user to wait indefinitely for the resynchronization to complete when such a failure occurs. This should be weighed against the performance enhancement that is provided by last agent optimization during successful commit operations. This consideration would generally be more significant for interactive jobs than for batch jobs.

There is one case where performance is not enhanced when a last agent is selected. If no committable changes have been made at an agent, and the Vote read only permitted commitment option has been set to Y at that agent, then performance would actually be degraded by selecting that agent as a last agent. The decrease in performance occurs because fewer write operations to auxiliary storage are required when the vote read only optimization is used. Therefore, applications written such that no data is changed at all agents during most logical units of work should set the Last agent permitted option to N.

The valid options are:

When the commitment definition was started, the value for this option was set to S.

Note: The Last agent permitted commitment option cannot be changed to N if an API commitment resource that is specified to be called as the last agent has already been added to the commitment definition using the Add Commitment Resource (QTNADDCR) API.

OK to leave out. Whether this location indicates that it is OK to leave out during a commit operation initiated at another location. OK to leave out means that no communications flows are sent to this location during subsequent commit or rollback operations until a data flow is received from the initiator. Also, control is not returned to the application until the data flow is received. The length of the delay in regaining control depends on the application running at the initiator.

In a client/server environment, setting the OK to leave out to Y at all the servers provides improved performance if data is not sent to all servers during every logical unit of work (LUW). The OK to leave out value is communicated from a server to a client during commit operations. Therefore, changing the OK to leave out value from N to Y does not take effect until after the next commit operation. Likewise, changing the OK to leave out value from Y to N does not take effect until after the commit of the next LUW, during which data has been sent to the server. Note that the OK to leave out value is not communicated during rollback operations.

The valid options are:

When the commitment definition was started, the value for this option was set to N.

Structure length. The length of the input structure provided. The minimum valid structure length is 5. If the length indicates that one or more options are not passed, the current value for those options is not changed.

Vote read-only permitted. Whether this location can vote read-only in response to a commit operation initiated at another location. If this location does vote read-only, control is not returned to the application until this location gets a message from the initiating location that indicates a new logical unit of work has started. The indicator flows in the data sent from the initiator of the previous commit operation. The length of the delay in regaining control depends on the application running at the initiator.

See the Commitment control topic for more information about when a location will vote read-only.

The valid options are:

When the commitment definition was started, the value for this option was set to N.

Wait for outcome. Whether the system will wait for the outcome of commit or rollback operations.

The valid options are:

When the commitment definition was started, this option was set to Y.

Notes:

1. The Wait for outcome value has no effect when a failure occurs while a logical unit of work is in doubt if the failure is between this location and the location that owns the commit or rollback decision. This is the case if the LUW state is PREPARED and the failure occurs between this location and the initiator location, or if the LUW state is LAST AGENT PENDING and the failure occurs between this location and the last agent location. In this case, the system always waits for the resynchronization to complete regardless of the Wait for outcome value.
2. If the ENDJOB command is used to end a job while it is waiting for resynchronization to complete, the Wait for outcome value is changed to N so that the job is allowed to end quickly. However, if the logical unit of work is in doubt, the Action if ENDJOB commitment option controls whether the job will be allowed to end before resynchronization completes with the location that owns the commit or rollback decision.
3. Consider the following when setting the Wait for outcome value:
   • When the Wait for outcome value is N, the application will not learn about inconsistencies at other locations in the transaction program network. Inconsistencies can result only if a system operator takes manual intervention due to the failure that caused the resynchronization.
   • When the Wait for outcome value is Y, most of the performance benefits provided by the presumed abort protocol are lost.
   • The Wait for outcome value is most useful when the same value is used at all locations in the transaction program network. If the Wait for outcome value is Y at the initiator but N at an agent, the initiator may not learn the full outcome of the commit or rollback operation because the agent did not wait for it. If the Wait for outcome value is N at the initiator but Y at an agent, the initiator may be forced to wait for the outcome of resynchronization performed by the agent. Therefore, it is recommended that all locations in the transaction program network specify either L or U for the Wait for outcome value. This allows the entire tree to use a consistent value because the initiator's value will be inherited by all locations.
   • If the commitment definition has a Wait for outcome value of Y or wait, or inherits a value of Wait, the value of the Accept vote reliable commitment option is ignored, and the system behaves as though the Accept vote reliable commitment option is No.

Restrictions

You are prevented from changing the commitment options using this API when:

• Commitment control is not active for the program when making the request to change the commitment options.
• A commitment control operation is in progress for the current commitment definition whose options are to be changed.

Error Messages