BEA Home  |  Events  |  Solutions  |  Partners  |  Products  |  Services  |  Download  |  Developer Center  |  WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
Tuxedo Documentation   |   Programming BEA Tuxedo ATMI Applications Using C   |   Local Topics   |   Previous Topic   |   Next Topic   |   Contents

• A successful call to tpreturn() in a simple conversation.

• A series of successful calls to tpreturn() in a complex conversation based on a hierarchy of connections.

• Global transactions, as described in Writing Global Transactions.

Note: The tpreturn() function is described in detail in Writing Request/Response Clients and Servers.

The following sections describe two scenarios for gracefully terminating conversations that do not include global transactions in which the tpreturn() function is used.

If you end a conversation with connections still open, the system returns an error. In this case, either tpcommit() or tpreturn() fails in a disorderly manner.

The program flow is as follows:

1. A sets up the connection by calling tpconnect() with the TPSENDONLY flag set, indicating that process B is on the receiving end of the conversation.

2. A turns control of the connection over to B by calling tpsend() with the TPRECVONLY flag set, resulting in the generation of a TPEV_SENDONLY event.

3. The next call by B to tprecv() returns a value of -1, sets tperrno(5) to TPEEVENT, and returns TPEV_SENDONLY in the revent argument, indicating that control has passed to B.

4. B calls tpreturn() with rval set to TPSUCCESS. This call generates a TPEV_SVCSUCC event for A and gracefully brings down the connection.

5. A calls tprecv(), learns of the event, and recognizes that the conversation has been terminated. Data can be received on this call to tprecv() even if the event is set to TPEV_SVCFAIL.

In the preceding example, service B is a member of a conversation that has initiated a connection to a second service called C. In other words, there are two active connections: A-to-B and B-to-C. If B is in control of both connections, a call to tpreturn() has the following effect: the call fails, a TPEV_SVCERR event is posted on all open connections, and the connections are closed in a disorderly manner.

1. B calls tpsend() with the TPRECVONLY flag set on the connection to C, transferring control of the B-to-C connection to C.

2. C calls tpreturn() with rval set to TPSUCCESS, TPFAIL, or TPEXIT, as appropriate.

3. B can then call tpreturn(), posting an event (either TPEV_SVCSUCC or TPEV_SVCFAIL) for A.

Note: It is legal for a conversational service to make request/response calls if it needs to do so to communicate with another service. Therefore, in the preceding example, the calls from B to C may be executed using tpcall() or tpacall() instead of tpconnect(). Conversational services are not permitted to make calls to tpforward().

The only way in which a disorderly disconnect can be executed is through a call to the tpdiscon(3c) function (which is equivalent to "pulling the plug" on a connection). This function can be called only by the initiator of a conversation (that is, the client).

Note: This is not the preferred method for bringing down a conversation. To bring down an application gracefully, the subordinate (the server) should call the tpreturn() function.

The cd argument specifies the connection descriptor returned by the tpconnect() function when the connection is established.

For a list and descriptions of all event and error codes, refer to tpdiscon(3c) in the BEA Tuxedo ATMI C Function Reference.