Programming a BEA Tuxedo ATMI Application Using C

Writing Conversational Clients and Servers

This topic includes the following sections:

Overview of Conversational Communication

Conversational communication is the BEA Tuxedo system implementation of a human-like paradigm for exchanging messages between ATMI clients and servers. In this form of communication, a virtual connection is maintained between the client (initiator) and server (subordinate) and each side maintains information about the state of the conversation. The connection remains active until an event occurs to terminate it.

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 a BEA Tuxedo ATMI application, consider the following example from an online banking application. In this example, a bank customer requests checking account statements for the past two months.

As with request/response communication, the BEA 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.

Conversational clients and servers have the following characteristics:

Conversational communication differs from request/response communication in the following ways:

Joining an Application

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.

Establishing a Connection

The tpconnect(3c) function sets up a conversation:

Use the following signature to call the tpconnect() function.

int
tpconnect(char *name, char *data, long len, long flags)

The following table describes the arguments to the tpconnect() function.

The BEA 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 BEA Tuxedo ATMI C Function Reference.

The following example shows how to use the tpconnect() function.

#include atmi.h
#define    FAIL    -1
int cd1;        /* Connection Descriptor */
main()
{
 if ((cd = tpconnect("AUDITC",NULL,0,TPSENDONLY)) == -1) {
    error routine
 }
}

Sending and Receiving Messages

Once the BEA 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.

Sending Messages

To send a message, use the tpsend(3c) function with the following signature:

int
tpsend(int cd, char *data, long len, long flags, long *revent)

The following table describes the arguments to the tpsend() function.

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 BEA 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.

The following example shows how to invoke the tpsend() function.

if (tpsend(cd,line,0,TPRECVONLY,revent) == -1) {
              (void)userlog("%s: tpsend failed tperrno %d",
                     argv[0],tperrno);
              (void)tpabort(0);
              (void)tpterm();
              exit(1);
        }

Receiving Messages

To receive data sent over an open connection, use the tprecv(3c) function with the following signature:

int
tprecv(int cd, char **data, long *len, long flags, long *revent)

The following table describes the arguments to the tprecv() function.

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.

The following example shows how to use the tprecv() function.

if (tprecv(cd,line,len,TPNOCHANGE,revent) != -1) {
           (void)userlog("%s: tprecv failed tperrno %d revent %ld",
                argv[0],tperrno,revent);
            (void)tpabort(0);
            (void)tpterm();
            exit(1);
}

Ending a Conversation

A connection can be taken down gracefully and a conversation ended normally through:

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

The first example shows how to terminate a simple conversation between two components. The second example illustrates a more complex scenario, with a hierarchical set of conversations.

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.

Example: Ending a Simple Conversation

The following diagram shows a simple conversation between A and B that terminates gracefully.

The program flow is as follows:

Example: Ending a Hierarchical Conversation

The following diagram shows a hierarchical conversation that terminates gracefully.

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.

In order to terminate both connections normally, an application must execute the following sequence:

Executing a Disorderly Disconnect

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).

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 BEA Tuxedo ATMI C Function Reference.

Building Conversational Clients and Servers

Use the following commands to build conversational clients and servers:

For conversational and request/response services, you cannot:

Understanding Conversational Communication Events

The BEA Tuxedo system recognizes five events in conversational communication. All five events can be posted for tprecv(); three can be posted for tpsend().

The following table lists the events, the functions for which they are returned, and a detailed description of each.