This section describes how application programs can use CPI Communications in conjunction with a resource recovery interface. A resource recovery interface provides access to services and facilities that use two-phase commit protocols to coordinate changes to distributed resources.
While CPI Communications' sync point functions can be used with other resource recovery interfaces, this book describes how CPI Communications works with the Systems Application Architecture* (SAA*) CPI Resource Recovery and X/Open TX resource recovery interfaces. For information about performing synchronization point processing with the SAA resource recovery interface, see SAA Common Programming Interface: Resource Recovery Reference (SC31-6821) and read the documentation for the appropriate operating environment. For information on using the X/Open TX resource recovery interface, see Distributed Transaction Processing: The TX (Transaction Demarcation) Specification, published by X/Open Company Limited, ISBN: 1-872630-65-0.
Notes:
A CPI Communications conversation can be used with a resource recovery interface only if its sync_level characteristic is set to CM_SYNC_POINT or CM_SYNC_POINT_NO_CONFIRM. This kind of conversation is called a protected conversation.
A program communicates with a resource recovery interface by establishing synchronization points, or sync points, in the program logic. A sync point is a reference point during transaction processing to which resources can be restored if a failure occurs. The program uses a resource recovery interface's commit call to establish a new sync point or a resource recovery interface's backout call to return to a previous sync point. The processing and the changes to resources that occur between one sync point and the next are collectively referred to as a transaction or a logical unit of work.
In turn, the resource recovery interface invokes a component of the operating environment called a sync point manager (SPM) or a transaction manager. The SPM coordinates the commit or backout processing among all the protected resources involved in the sync point transaction.
The commitment or backout of protected resources is done on a context basis. Only those changes to protected resources, including protected conversations, that belong to the program's current context when the commit or backout call is issued are committed or backed out. Therefore, prior to issuing the commit or backout call, the program must ensure that the current context is the context for which the commit or backout is intended.
For example, Program S in Figure 7 has two distinct contexts, one for Program D and one for Program E. If Program S decides to commit or back out the work that it has done for Program D, it must set the current context to ensure that only the resources associated with Program D will be affected. For more information on contexts, see "Contexts and Context Management".
When a program issues a Prepare, commit, or backout call, CPI Communications cooperates with the resource recovery interface by passing synchronization information to its conversation partner. This sync point information consists of take-commit and take-backout notifications.
When the program issues a Prepare or commit call, CPI Communications returns a take-commit notification to the partner program in the status_received parameter for a Receive call issued by the partner. The sequence of CPI Communications calls issued before the Prepare or resource recovery commit call determines the value of the take-commit notification returned to the partner program. In addition to requesting that the partner program establish a sync point, the take-commit notification also contains conversation state transition information.
Table 9 and Table 10
show the status_received
values that CPI Communications uses as take-commit notifications, the
conditions under which each of the values may be received,
and the state changes resulting from their receipt.
Table 9. Possible Take-Commit Notifications for Half-Duplex Conversations
| status_received Value | Conditions for Receipt |
|---|---|
| CM_TAKE_COMMIT | The partner program issued a commit call, or a Prepare call with the prepare_data_permitted conversation characteristic set to CM_PREPARE_DATA_NOT_PERMITTED, while its end of the conversation was in Send or Send-Pending state. The local program's end of the conversation is in Sync-Point state and will be placed back in Receive state once the local program issues a successful commit call. |
| CM_TAKE_COMMIT_SEND | The partner program issued a commit call, or a Prepare call with the prepare_data_permitted conversation characteristic set to CM_PREPARE_DATA_NOT_PERMITTED, while its end of the conversation was in Defer-Receive state. The local program's end of the conversation is in Sync-Point-Send state and will be placed in Send state once the local program issues a successful commit call. |
| CM_TAKE_COMMIT_DEALLOCATE | The partner program issued a commit call, or a Prepare call with the prepare_data_permitted conversation characteristic set to CM_PREPARE_DATA_NOT_PERMITTED, either while its end of the conversation was in Defer-Deallocate state or after issuing a Deferred_Deallocate call. The local program's end of the conversation is in Sync-Point-Deallocate state and will be placed in Reset state once the local program issues a successful commit call. |
| CM_TAKE_COMMIT_DATA_OK | The partner program issued a Prepare call with the prepare_data_permitted conversation characteristic set to CM_PREPARE_DATA_PERMITTED while its end of the conversation was in Send or Send-Pending state. The local program's end of the conversation is in Sync-Point state and will be placed back in Receive state once the local program issues a successful commit call. |
| CM_TAKE_COMMIT_SEND_DATA_OK | The partner program issued a Prepare call with the prepare_data_permitted conversation characteristic set to CM_PREPARE_DATA_PERMITTED while its end of the conversation was in Defer-Receive state. The local program's end of the conversation is in Sync-Point-Send state and will be placed in Send state once the local program issues a successful commit call. |
| CM_TAKE_COMMIT_DEALLOC_DATA_OK | The partner program issued a Prepare call with the prepare_data_permitted conversation characteristic set to CM_PREPARE_DATA_PERMITTED, either while its end of the conversation was in Defer-Deallocate state or after issuing a Deferred_Deallocate call. The local program's end of the conversation is in Sync-Point-Deallocate state and will be placed in Reset state once the local program issues a successful commit call. |
Table 10. Possible Take-Commit Notifications for Full-Duplex Conversations
| status_received Value | Conditions for Receipt |
|---|---|
| CM_TAKE_COMMIT | The partner program issued a commit call, or the conversation is using an LU 6.2 CRM and the partner program issued a Prepare call, while its end of the conversation was in Send-Receive state. The local program's end of the conversation is in Sync-Point state and will be placed back in Send-Receive state once the local program issues a successful commit call. |
| CM_TAKE_COMMIT_DEALLOCATE | The partner program issued a commit call, or the conversation is using an LU 6.2 CRM and the partner program issued a Prepare call, either while its end of the conversation was in Defer-Deallocate state or after issuing a Deferred_Deallocate call. The local program's end of the conversation is in Sync-Point-Deallocate state and will be placed in Reset state once the local program issues a successful commit call. |
| CM_TAKE_COMMIT_DATA_OK | The conversation is using an OSI TP CRM, and the partner program issued a Prepare call while its end of the conversation was in Send-Receive state. The local program's end of the conversation is in Sync-Point state and will be placed back in Send-Receive state once the local program issues a successful commit call. |
| CM_TAKE_COMMIT_DEALLOC_DATA_OK | The conversation is using an OSI TP CRM, and the partner program issued a Prepare call, either while its end of the conversation was in Defer-Deallocate state or after issuing a Deferred_Deallocate call. The local program's end of the conversation is in Sync-Point-Deallocate state and will be placed in Reset state once the local program issues a successful commit call. |
When the program issues a backout call, or when a system failure or a problem with a protected resource causes the SPM to initiate a backout operation, CPI Communications returns a take-backout notification to the partner program. CPI Communications returns this notification as one of the following values in the return_code parameter:
CPI Communications can return a take-backout notification on any of the following calls issued by the partner program:
Upon receipt of a take-backout notification on a protected conversation, the conversation's context is placed in the Backout-Required condition. This condition is not a conversation state, because it applies to all of the program's protected resources for that context, possibly including multiple conversations.
A context may be placed in the Backout-Required condition in one of the following ways:
When a context is placed in the Backout-Required condition, the program should issue a resource recovery backout call. Until it issues a backout call, the program will be unable to successfully issue any of the following CPI Communications calls for any of its protected conversations within that context. The CM_PROGRAM_STATE_CHECK return code will be returned if the program issues any of the following calls:
A program usually issues a commit or backout call in response to
a take-commit notification, and a backout call in response to a
take-backout notification.
In some cases, however, the program may respond to one of
these notifications with a CPI Communications call instead of a commit
or backout call.
Table 11 shows the calls a program can use
to respond to take-commit and take-backout
notifications, the result of issuing each call, and any further
action required by the program.
Table 11. Responses to Take-Commit and Take-Backout Notifications
| Notification Received | Possible Response | Reason for Response | Result of Response | Further Action Required |
| Take-Commit1 | Commit | The program agrees that it can commit (or has committed) all protected resources. | The commit request is spread to other programs in the transaction. | None |
| Backout | The program disagrees with the commit request. | A backout request is spread to other programs in the transaction, including the program that issued the original commit call. | None | |
| Deallocate (Abend)2 or Cancel_ Conversation | The program has detected an error condition that prevents it from continuing normal processing. | The conversation's context is placed in the Backout-Required condition. | The program should issue a resource recovery backout call. | |
| Send_Error3 | The program has detected an error in received data or some other error that may be correctable. | The SPM backs out the transaction, and both programs are informed of the backout. | Depends on the response from the partner program. | |
| Take-Backout | Commit | This is an error in program logic. | The commit call is treated as though it were a backout call, and the backout request is spread to other programs in the transaction. | None |
| Backout | The program agrees to the backout request. | The backout request is spread to other programs in the transaction. | None | |
| Deallocate (Abend)2 or Cancel_ Conversation | The program has detected an error condition that prevents it from continuing normal processing. | The conversation's context is placed in the Backout-Required condition. | The program should issue a resource recovery backout call. |
1 If the take-commit indicator ended in
*_DATA_OK, the partner may also send data before
making any of the other possible responses.
2 "Deallocate (Abend)" refers to the CPI Communications
Deallocate call with a deallocate_type of
CM_DEALLOCATE_ABEND.
3 The program can respond with a Send_Error call
only when using a half-duplex conversation.
When a program is using the X/Open TX resource recovery interface, it may choose when the next transaction is started after the current transaction ends. Specifically, if the TX Transaction_Control variable is set to:
For a conversation using an OSI TP CRM, the program that initializes a conversation may use the Set_Transaction_Control call to specify whether it wants to use chained or unchained transactions for the conversation. The remote program may determine whether chained or unchained transactions are being used for the conversation by issuing the Extract_Transaction_Control call. A conversation using an LU 6.2 CRM must use chained transactions.
In a conversation using chained transactions, if a commit call ends the current transaction and immediately begins the next transaction, the conversation is automatically included in that next transaction and is always a protected conversation. If the commit call does not immediately start the next transaction, the conversation is deallocated by the system, and the program is notified of the deallocation by a CM_RESOURCE_FAILURE_RETRY return code.
For a conversation using unchained transactions, when a commit call ends the current transaction, the conversation is not automatically included in the next transaction. Until the next transaction is started and the conversation is included in that transaction, the conversation is not a protected conversation, and any commit or backout processing does not apply to that conversation. After the next transaction is started, the conversation is included in that transaction, and becomes a protected conversation again, when the program requests that the partner program join the transaction.
The TX Transaction_Control variable and the CPI Communications transaction_control conversation characteristic are independent. There are four possible combinations:
- TX_CHAINED and CM_CHAINED_TRANSACTIONS
- TX_CHAINED and CM_UNCHAINED_TRANSACTIONS
- TX_UNCHAINED and CM_CHAINED_TRANSACTIONS
- TX_UNCHAINED and CM_UNCHAINED_TRANSACTIONS
For a conversation using chained transactions, when the local program issues an Allocate call after setting the sync_level to CM_SYNC_POINT or CM_SYNC_POINT_NO_CONFIRM and the remote program issues an Accept_Conversation or Accept_Incoming call, the remote program automatically joins the transaction.
For a conversation using unchained transactions, when a new transaction is started, the local program has the following two ways of requesting that the partner join the transaction.
In this case, when the local program issues the second CPI Communications call, the remote program receives a status_received value of CM_JOIN_TRANSACTION.
Note: If the local program is not in transaction when one of the above calls is made, the begin_transaction characteristic is ignored, and the partner program is not requested to join a transaction.
Normally, if the remote program receives the request to join the transaction, it joins automatically. When using the X/Open TX resource recovery interface, the program can issue a tx_info() call to see whether or not it is in transaction mode.
When using the X/Open TX resource recovery interface,
the program can
choose not to join automatically.
In this case, the program must issue
a Set_Join_Transaction call with join_transaction set to
CM_JOIN_EXPLICIT.
This call should be issued in the Initilize_Incoming
state,
so that it has an effect at the following Accept_Incoming call.
If a program uses CM_JOIN_EXPLICIT, it should extract the
transaction_control characteristic
after a successful Accept_Incoming call.
If the value is CM_CHAINED_TRANSACTIONS,
the program should join
the transaction by issuing a tx_begin() call.
If the value is
CM_UNCHAINED_TRANSACTIONS, the program is informed with a
CM_JOIN_TRANSACTION status_received value
if it is to join the transaction.
In any case, the program might first do any local work that is
not for inclusion in the remote program's transaction before joining
the transaction.
Instead of issuing a tx_begin() call, the program also might
reject the request to join the transaction by issuing a Deallocate
call with a deallocate_type of
CM_DEALLOCATE_ABEND or a
CM_DEALLOCATE_ABEND or a Cancel_Conversation call.
Table 12. Responses to the CM_JOIN_TRANSACTION Indication
| Notification Received | Possible Response | Reason for Response | Result of Response | Further Action Required |
|---|---|---|---|---|
| Join- Transaction | tx_begin | The program agrees to join the distributed transaction. | The local program is included in the distributed transaction. | None |
| Deallocate (Abend) 1
or Cancel_ Conversation | The program rejects the request to join the distributed transaction. | The local program is included in the distributed transaction. | None |
1 "Deallocate (Abend)" refers to the CPI Communications Deallocate call with a deallocate_type of CM_DEALLOCATE_ABEND.
The concept of superior and subordinate programs applies only for conversations with sync_level set to CM_SYNC_POINT or CM_SYNC_POINT_NO_CONFIRM that are are using an OSI TP CRM.
The superior program is the program that initiates the conversation (using the Initialize_Conversation call). A program that issues the Accept_Conversation or Accept_Incoming call is a subordinate of the superior program.
Figure 9 shows a commit tree with seven programs participating in the transaction.
Figure 9. Commit Tree with Program 1 as Root and Superior
In this example, Program 1 is the superior program in its conversations with Programs 2, 5, and 6, which are all its subordinates. Similarly, Program 2 is the superior in its conversations with Programs 3 and 4, and Program 6 is the superior in its conversation with Program 7.
Only the superior program that initiated the transaction (program 1 in this case) can issue the initial commit call to end the transaction. However, any of the superior programs in the transaction (in this example, Programs 1, 2, and 6) can issue the Deferred_Deallocate call to their subordinates (but not to their superiors).
In addition, the Include_Partner_In_Transaction, Prepare, Set_Begin_Transaction, and Set_Prepare_Data_Permitted calls may be issued only by the superior program. These calls return a CM_PROGRAM_PARAMETER_CHECK return code when they are issued by the subordinate.
Table 13. CPI Communications States for Protected Conversations
| State | Description |
|---|---|
| Defer-Receive |
The local program's end of the conversation
will enter Receive state after
a synchronization call completes successfully.
The synchronization call may be a resource recovery commit call or a
CPI Communications Flush or Confirm call.
A conversation enters Defer-Receive state when the local program issues a Prepare_To_Receive call with prepare_to_receive_type set to CM_PREP_TO_RECEIVE_SYNC_LEVEL and sync_level set to CM_SYNC_POINT or CM_SYNC_POINT_NO_CONFIRM, or when it issues a Send_Data call with send_type set to CM_SEND_AND_PREP_TO_RECEIVE, prepare_to_receive_type set to CM_PREP_TO_RECEIVE_SYNC_LEVEL, and sync_level set to CM_SYNC_POINT or CM_SYNC_POINT_NO_CONFIRM. Defer-Receive state is applicable
for half-duplex conversations only.
|
| Defer-Deallocate |
The local program has requested that the conversation
be deallocated after
a commit operation has completed; that is,
the conversation is included in a transaction, and
the program has issued
a Deallocate call with
deallocate_type set to
CM_DEALLOCATE_SYNC_LEVEL and
sync_level set to CM_SYNC_POINT
or CM_SYNC_POINT_NO_CONFIRM,
or it has issued a
Send_Data call with send_type set to
CM_SEND_AND_DEALLOCATE,
deallocate_type set to
CM_DEALLOCATE_SYNC_LEVEL, and
sync_level set to CM_SYNC_POINT
or CM_SYNC_POINT_NO_CONFIRM.
The conversation will not be deallocated until a successful
commit operation takes place.
|
| Prepared | The local program has issued a Prepare call to request that the remote program prepare its resources for commitment. |
| Sync-Point |
The local program issued a Receive call and was given a
return_code of CM_OK and a
status_received of CM_TAKE_COMMIT
or CM_TAKE_COMMIT_DATA_OK.
After a successful commit operation,
a half-duplex conversation
will return to Receive state,
while a full-duplex conversation will return to
Send-Receive state.
|
| Sync-Point-Send |
The local program issued a Receive call and was
given a return_code of CM_OK and a
status_received of CM_TAKE_COMMIT_SEND
or CM_TAKE_COMMIT_SEND_DATA_OK.
After a successful commit operation, the conversation
will be placed in Send state.
Sync-Point-Send state is applicable
for half-duplex conversations only.
|
| Sync-Point-Deallocate |
The local program issued a Receive call and was
given a return_code of CM_OK and a
status_received of
CM_TAKE_COMMIT_DEALLOCATE
or CM_TAKE_COMMIT_DEALLOC_DATA_OK.
After a successful commit operation, the conversation
will be deallocated and placed in Reset state.
|
A program must ensure that there are no outstanding operations on its protected conversations within a context before issuing a resource recovery call for that context. If a resource recovery call is issued while there is an outstanding operation on a protected conversation, the program receives from the resource recovery interface a return code indicating an error.
All protected conversations within a context must be in one of the following states for the program to issue a commit call for that context:
If a commit call is issued from any other conversation state, the program receives from the resource recovery interface a return code indicating an error. The program can also receive an error return code if the conversation was in Send or Send-Receive state when the commit call was issued, and the program had started but had not finished sending a basic conversation logical record.
A backout call can be issued in any state.
If the subordinate program uses the X/Open TX resource recovery interface and the join_transaction characteristic has the value CM_JOIN_IMPLICIT, the TX State Table, in the X/Open TX Specification, changes in the following ways:
The program can use the tx_info() call to determine if it is in transaction mode and to determine the value of the TX transaction_control characteristic.
(4) Deallocate(S) refers to a Deallocate call issued with the deallocate_type set to CM_DEALLOCATE_SYNC_LEVEL and the sync_level set to CM_SYNC_POINT or CM_SYNC_POINT_NO_CONFIRM.