During conversational communication, a half-duplex connection is established between the client and server. A half-duplex connection allows messages to be sent in only one direction at any given time. Control of the connection can be passed back and forth between the initiator and the subordinate. The process that has control can send messages; the process that does not have control can only receive messages.To understand how conversational communication works in an Oracle Tuxedo ATMI application, consider the following example in Figure 7‑1 from an online banking application. In this example, a bank customer requests checking account statements for the past two months.
2. The Account Records Storage System responds by sending the first month’s checking account statement followed by a More prompt for accessing the remaining month’s statement.
Note: As with request/response communication, the Oracle Tuxedo system passes data using typed buffers. The buffer types must be recognized by the application. For more information on buffer types, refer to “Overview of Typed Buffers” on page 2‑1.
• Both clients and servers use the tpsend() and tprecv() routines to send and receive data in conversations.
• A conversational client must join an application via a call to tpinit() before attempting to establish a connection to a service. For more information, refer to “Writing Clients” on page 4‑1.The tpconnect(3c) function sets up a conversation:Table 7‑1 describes the arguments to the tpconnect() function.
Table 7‑1 tpconnect( ) Function Arguments Character pointer to a conversational service name. If you do not specify name as a pointer to a conversational service, the call fails with a value of -1 and tperrno is set to the error code TPENOENT. Pointer to a data buffer. When establishing the connection, you can send data simultaneously by setting the data argument to point to a buffer previously allocated by tpalloc(). The type and subtype of the buffer must be types recognized by the service being called. You can set the value of data to NULL to specify that no data is to be sent.The conversational service being called receives the data and len pointers via the TPSVCINFO data structure passed to it by main() when the service is invoked. (A request/response service receives the data and len pointers in the same way.) For more information on the TPSVCINFO data structure, refer to “Defining a Service” on page 5‑9. Length of the data buffer. If the buffer is self-defining (for example, an FML buffer), you can set len to 0. Specifies the flag settings. For a complete list of valid flag settings, refer to tpconnect(3c) in the Oracle Tuxedo ATMI C Function Reference.The system notifies the called service through the flag members of the TPSVCINFO structure.The Oracle Tuxedo system returns a connection descriptor (cd) when a connection is established with tpconnect(). The cd is used to identify subsequent message transmissions with a particular conversation. A client or conversational service can participate in more than one conversation simultaneously. The maximum number of simultaneous conversations is 64.In the event of a failure, the tpconnect() function returns a value of -1 and sets tperrno to the appropriate error condition. For a list of possible error codes, refer to tpconnect(3c) in the Oracle Tuxedo ATMI C Function Reference.Listing 7‑1 Establishing a Conversational ConnectionOnce the Oracle Tuxedo system establishes a conversational connection, communication between the initiator and subordinate is accomplished using send and receive calls. The process with control of the connection can send messages using the tpsend(3c) function; the process without control can receive messages using the tprecv(3c) function.
Note: Initially, the originator (that is, the client) decides which process has control using the TPSENDONLY or TPRECVONLY flag value of the tpconnect() call. TPSENDONLY specifies that control is being retained by the originator; TPRECVONLY, that control is being passed to the called service.To send a message, use the tpsend(3c) function with the following signature:
Table 7‑2 tpsend( ) Function Arguments Specifies the connection descriptor returned by the tpconnect() function identifying the connection over which the data is sent. Pointer to a data buffer. When establishing the connection, you can send data simultaneously by setting the data argument to point to a buffer previously allocated by tpalloc(). The type and subtype of the buffer must be types recognized by the service being called. You can set the value of data to NULL to specify that no data is to be sent.The conversational service being called receives the data and len pointers via the TPSVCINFO data structure passed to it by main() when the service is invoked. (A request/response server receives the data and len pointers in the same way.) For more information on the TPSVCINFO data structure, refer to “Defining a Service” on page 5‑9. Length of the data buffer. If the buffer is self-defining (for example, an FML buffer), you can set len to 0. If you do not specify a value for data, this argument is ignored. Pointer to event value set when an error is encountered (that is, when tperrno(5) is set to TPEEVENT). For a list of valid event values, refer to tpsend(3c) in the Oracle Tuxedo ATMI C Function Reference. Specifies the flag settings. For a list of valid flag settings, refer to tpsend(3c) in the Oracle Tuxedo ATMI C Function Reference.In the event of a failure, the tpsend() function returns a value of -1 and sets tperrno(5) to the appropriate error condition. For a list of possible error codes, refer to tpsend(3c) in the Oracle Tuxedo ATMI C Function Reference.You are not required to pass control each time you issue the tpsend() function. In some applications, the process authorized to issue tpsend() calls can execute as many calls as required by the current task before turning over control to the other process. In other applications, however, the logic of the program may require the same process to maintain control of the connection throughout the life of the conversation.Listing 7‑2 Sending Data in Conversational ModeTo receive data sent over an open connection, use the tprecv(3c) function with the following signature:
Specifies the connection descriptor. If a subordinate program issues the call, the cd argument should be set to the value specified in the TPSVCINFO structure for the program. If the originator program issues the call, the cd argument should be set to the value returned by the tpconnect() function. Pointer to a data buffer. The data argument must point to a buffer previously allocated by tpalloc(). The type and subtype of the buffer must be types recognized by the service being called. This value cannot be NULL; if it is, the call fails and tperrno(5) is set to TPEINVAL.The conversational service being called receives the data and len pointers via the TPSVCINFO data structure passed to it by main() when the service is invoked. (A request/response service receives the data and len pointers in the same way.) For more information on the TPSVCINFO data structure, refer to “Defining a Service” on page 5‑9. Length of the data buffer. If the buffer is self-defining (for example, an FML buffer), you can set len to 0. This value cannot be NULL; if it is, the call fails and tperrno(5) is set to TPEINVAL. Pointer to event value set when an error is encountered (that is, when tperrno is set to TPEEVENT). Refer to tprecv(3c) in the Oracle Tuxedo ATMI C Function Reference for a list of valid event values. Specifies the flag settings. Refer to tprecv(3c) in the Oracle Tuxedo ATMI C Function Reference for a list of valid flags.Upon success, the *data argument points to the data received and len contains the size of the buffer. If len is greater than the total size of the buffer before the call to tprecv(), the buffer size has changed and len indicates the new size. A value of 0 for the len argument indicates that no data was received.Listing 7‑3 Receiving Data in Conversation
• 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.
Note: The tpreturn() function is described in detail in “Writing Request/Response Clients and Servers” on page 6‑1.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.Figure 7‑2 shows a simple conversation between A and B that terminates gracefully.Figure 7‑2 Simple Conversation Terminated Gracefully
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. Figure 7‑3 shows a hierarchical conversation that terminates gracefully.Figure 7‑3 Connection HierarchyIn 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.In order to terminate both connections normally, an application must execute the following sequence:
1.
2.
3.
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: Use the following signature to call the tpdiscon() function:int
tpdiscon(int cd)The cd argument specifies the connection descriptor returned by the tpconnect() function when the connection is established.The tpdiscon() function generates a TPEV_DISCONIMM event for the service at the other end of the connection, rendering the cd invalid. If a transaction is in progress, the system aborts it and data may be lost.If tpdiscon() is called from a service that was not the originator of the connection identified by cd, the function fails with an error code of TPEBADDESC.For a list and descriptions of all event and error codes, refer to tpdiscon(3c) in the Oracle Tuxedo ATMI C Function Reference.
• buildclient() as described in “Building Clients” on page 4‑8
• buildserver() as described in “Building Servers” on page 5‑30The Oracle Tuxedo system recognizes five events in conversational communication. All five events can be posted for tprecv(); three can be posted for tpsend().Table 7‑3 lists the events, the functions for which they are returned, and a detailed description of each.