Writing Conversational Clients and Servers

This topic includes the following sections:

•	Overview of Conversational Communication

•	Joining an Application

•	Establishing a Connection

•	Sending and Receiving Messages

•	Ending a Conversation

•	Building Conversational Clients and Servers

•	Understanding Conversational Communication Events

Overview of Conversational Communication

Conversational communication is the Oracle 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 an Oracle 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.

Figure 7‑1 Example of Conversational Communication in an Online Banking Application

1.	The customer requests the 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.

3.	The customer requests the second month’s account statement by selecting the More prompt.

Note:

The Account Records Storage System must maintain state information so it knows which account statement to return when the customer selects the More prompt.

4.	The Account Records Storage System sends the remaining month’s account statement.

As with request/response communication, the Oracle Tuxedo system passes data using typed records. The record types must be recognized by the application. For more information on record types, refer to “Overview of Typed Records” on page 3‑1.

Conversational clients and servers have the following characteristics:

•	The logical connection between them remains active until terminated.

•	Any number of messages can be transmitted across a connection between them.

•	Both clients and servers use the TPSEND and TPRECV routines to send and receive data in conversations.

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

•	A conversational client initiates a request for service using TPCONNECT rather than TPCALL or TPACALL.

•	A conversational client sends a service request to a conversational server.

•	The configuration file reserves part of the conversational server for addressing conversational services.

•	Conversational servers are prohibited from making calls using TPFORWAR.

Joining an Application

A conversational client must join an application via a call to TPINITIALIZE before attempting to establish a connection to a service. For more information, refer to “Writing Clients” in Programming Oracle Tuxedo ATMI Applications Using C.

Establishing a Connection

The TPCONNECT(3cbl) routine sets up a conversation:

Use the following signature to call the TPCONNECT routine.

01 TPSVCDEF-REC.
COPY TPSVCDEF.

01 TPTYPE-REC.
COPY TPTYPE.

01 DATA-REC.
COPY User Data.

01 TPSTATUS-REC.
COPY TPSTATUS.

CALL "TPCONNECT" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

Refer to “Defining a Service” for more information on the TPSVCDEF-REC record, and to “Defining Typed Records” on page 3‑6 for more information on the TPTYPE-REC record.

At the same time the connection is being established, data can be sent through the DATA-REC with the length of the data specified by LEN IN TPTYPE-REC. The REC-TYPE and SUB-TYPE of the data in DATA-REC must be types recognized by the service being called. If no data is being sent, the value of REC-TYPE is SPACES, and DATA-REC and LEN are ignored.

The Oracle Tuxedo system returns a communication handle, COMM-HANDLE IN TPSVCDEF-REC, when a connection is established with TPCONNECT or TPSVCSTART. COMM-HANDLE 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, TPCONNECT sets TP-STATUS to the appropriate error condition. For a list of possible error codes, refer to TPCONNECT(3cbl) in the Oracle Tuxedo ATMI COBOL Function Reference.

The following example shows how to use the TPCONNECT routine.

Listing 7‑1 Establishing a Conversational Connection

    . . .
* Prepare the record to send
  MOVE "HELLO" TO DATA-REC.
  MOVE 5 TO LEN.
  MOVE "STRING" TO REC-TYPE.
*
  SET TPBLOCK TO TRUE.
  SET TPNOTRAN TO TRUE.
  SET TPNOTIME TO TRUE.
  SET TPSIGRSTRT TO TRUE.
  SET TPSENDONLY TO TRUE.
*
  CALL "TPCONNECT" USING TPSVCDEF-REC
                   TPTYPE-REC
                   DATA-REC
                   TPSTATUS-REC.
  IF NOT TPOK
           error processing ...
  ELSE
      COMM-HANDLE is valid.

 

Sending and Receiving Messages

Once 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(3cbl) routine; the process without control can receive messages using the TPRECV(3cbl) routine.

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.

Sending Messages

To send a message, use the TPSEND(3cbl) routine with the following signature:

01 TPSVCDEF-REC.
COPY TPSVCDEF.

01 TPTYPE-REC.
COPY TPTYPE.

01 DATA-REC.
COPY User Data.

01 TPSTATUS-REC.
COPY TPSTATUS.

CALL "TPSEND" USING TPSVCDEF-REC TPTYPE-REC USER-DATA-REC TPSTATUS-REC.

Refer to “Defining a Service” in Programming Oracle Tuxedo ATMI Applications Using C for more information on the TPSVCDEF-REC record, and refer to “Defining Typed Records” on page 3‑6 for more information on the TPTYPE-REC record.

In the event of a failure, the TPSEND routine sets TP-STATUS to the appropriate error condition. For a list of possible error codes, refer to TPSEND(3cbl) in the Oracle Tuxedo ATMI COBOL Function Reference.

You are not required to pass control each time you issue the TPSEND routine. 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 routine.

Listing 7‑2 Sending Data in Conversational Mode

   . . .
   SET TPNOBLOCK TO TRUE.
   SET TPNOTIME TO TRUE.
   SET TPSIGRSTRT TO TRUE.
   SET TPRECVONLY TO TRUE.
*
   CALL "TPSEND" USING TPSVCDEF-REC
                    TPTYPE-REC
                    DATA-REC
                    TPSTATUS-REC.
   IF NOT TPOK
       error processing . . .

 

Receiving Messages

To receive data sent over an open connection, use the TPRECV(3cbl) routine with the following signature:

01 TPSVCDEF-REC.
COPY TPSVCDEF.

01 TPTYPE-REC.
COPY TPTYPE.

01 DATA-REC.
COPY User Data.

01 TPSTATUS-REC.
COPY TPSTATUS.

CALL "TPRECV" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

Refer to “Defining a Service” for more information on the TPSVCDEF-REC record. Refer to “Defining Typed Records” on page 3‑6 for more information on the TPTYPE-REC record.

The following example shows how to use the TPRECV routine.

Listing 7‑3 Receiving Data in Conversation

  . . .
  SET TPNOCHANGE TO TRUE.
  SET TPBLOCK TO TRUE.
  SET TPNOTIME TO TRUE.
  SET TPSIGRSTRT TO TRUE.
*
  MOVE LENGTH OF DATA-REC TO LEN.
*
  CALL "TPRECV" USING TPSVCDEF-REC
                   TPTYPE-REC
                   DATA-REC
                   TPSTATUS-REC.
  IF NOT TPOK
      error processing . . .

 

Ending a Conversation

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

•	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” in Programming Oracle Tuxedo ATMI Applications Using C.

Note:

The TPRETURN routine is described in detail in “Writing Request/Response Clients and Servers” in Programming Oracle Tuxedo ATMI Applications Using C.

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

Figure 7‑2 shows a simple conversation between A and B that terminates gracefully.

Figure 7‑2 Simple Conversation Terminating Gracefully

The program flow is as follows:

1.	A sets up the connection by calling TPCONNECT with TPSENDONLY 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 TPRECVONLY set, resulting in the generation of a TPEV_SENDONLY event.

3.	The next call by B to TPRECV sets TP-STATUS to TPEEVENT, and returns TPEV_SENDONLY in TPEVENT, indicating that control has passed to B.

4.	B calls TPRETURN with TPRETURN-VAL IN TPSVCRET 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.

Note:

In this example, A can be either a client or a server, but B must be a server.

Example: Ending a Hierarchical Conversation

Figure 7‑3 shows a hierarchical conversation that terminates gracefully.

Figure 7‑3 Connection Hierarchy

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:

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 TPRETURN-VAL IN TPSVCRET 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 TPFORWAR.

Executing a Disorderly Disconnect

The only way in which a disorderly disconnect can be executed is through a call to the TPDISCON(3cbl) routine (which is equivalent to “pulling the plug” on a connection). This routine 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 routine.

Use the following signature to call the TPDISCON routine:

01 TPSVCDEF-REC.
COPY TPSVCDEF.

01 TPSTATUS-REC.
COPY TPSTATUS.

CALL "TPDISCON" USING TPSVCDEF-REC TPSTATUS-REC.

The COMM-HANDLE argument specifies the communication handle returned by the TPCONNECT routine when the connection is established.

The TPDISCON routine generates a TPEV_DISCONIMM event for the service at the other end of the connection, rendering the COMM-HANDLE 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 COMM-HANDLE, the routine fails with an error code of TPEBADDESC.

For a list and descriptions of all event and error codes, refer to TPDISCON(3cbl) in the Oracle Tuxedo ATMI COBOL Function Reference.

Building Conversational Clients and Servers

Use the following commands to build conversational clients and servers:

•	buildclient() as described in “Building Clients” in Programming Oracle Tuxedo ATMI Applications Using C

•	buildserver() as described in “Building Servers” in Programming Oracle Tuxedo ATMI Applications Using C

For conversational and request/response services, you cannot:

•	Build both in the same server

•	Assign the same name to both

Understanding Conversational Communication Events

The 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‑1 lists the events, the routines for which they are returned, and a detailed description of each.

 

Table 7‑1 Conversational Communication Events

Event	Received By	Description
TPEV_SENDONLY	TPRECV	Control of the connection has been passed; this process can now call TPSEND.
TPEV_DISCONIMM	TPSEND, TPRECV, TPRETURN	The connection has been torn down and no further communication is possible. The TPDISCON routine posts this event in the originator of the connection, and sends it to all open connections when TPRETURN is called, as long as connections to subordinate services remain open. Connections are closed in a disorderly fashion. If a transaction exists, it is aborted.
TPEV_SVCERR	TPSEND	Received by the originator of the connection, usually indicating that the subordinate program issued a TPRETURN without having control of the connection.
	TPRECV	Received by the originator of the connection, indicating that the subordinate program issued a TPRETURN with TPSUCCESS or TPFAIL and a valid data record, but an error occurred that prevented the call from completing.
TPEV_SVCFAIL	TPSEND	Received by the originator of the connection, indicating that the subordinate program issued a TPRETURN without having control of the connection, and TPRETURN was called with TPFAIL or TPEXIT and no data.
	TPRECV	Received by the originator of the connection, indicating that the subordinate service finished unsuccessfully (TPRETURN was called with TPFAIL or TPEXIT).
TPEV_SVCSUCC	TPRECV	Received by the originator of the connection, indicating that the subordinate service finished successfully; that is, it called TPRETURN with TPSUCCESS.