This topic includes the following sections:
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.
More
prompt for accessing the remaining month's statement.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. |
As with request/response communication, the BEA 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.
Conversational clients and servers have the following characteristics:
Conversational communication differs from request/response communication in the following ways:
TPCONNECT
rather than TPCALL
or TPACALL
.TPFORWAR
.
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 BEA Tuxedo ATMI Applications Using C.
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 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 BEA 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 TPCO
NNECT(3cbl) in the BEA Tuxedo ATMI COBOL Function Reference.
The following example shows how to use the TPCONNECT
routine.
. . .
* 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-HANDLEis valid
.
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 TPSEN D(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. |
To send a message, use the TPSEN D(3cbl) routine with the following signature:
01TPSVCDEF-REC
.
COPY TPSVCDEF.
01TPTYPE-REC
.
COPY TPTYPE.
01DATA-REC
.
COPY User Data.
01TPSTATUS-REC
.
COPY TPSTATUS.
CALL "TPSEND" USING TPSVCDEF-REC TPTYPE-REC USER-DATA-REC TPSTATUS-REC
.
Refer to
Defining a Service in Programming BEA Tuxedo ATMI Applications Using C for more information on the TPSVCDEF-REC
record, and refer to Defining Typed Records 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 TPS
END(3cbl) in the BEA 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.
. . .
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 . . .
To receive data sent over an open connection, use the TPR ECV(3cbl) routine with the following signature:
01TPSVCDEF-REC
.
COPY TPSVCDEF.
01TPTYPE-REC
.
COPY TPTYPE.
01DATA-REC
.
COPY User Data.
01TPSTATUS-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 for more information on the TPTYPE-REC
record.
The following example shows how to use the TPRECV
routine.
. . .
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 . . .
A connection can be taken down gracefully and a conversation ended normally through:
TPRETURN
in a simple conversation.TPRETURN
in a complex conversation based on a hierarchy of connections.Note: | The TPRETURN routine is described in detail in
Writing Request/Response Clients and Servers in Programming BEA 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.
The following diagram shows a simple conversation between A and B that terminates gracefully.
The program flow is as follows:
TPCONNECT
with TPSENDONLY
set, indicating that process B is on the receiving end of the conversation.TPSEND
with TPRECVONLY
set, resulting in the generation of a TPEV_SENDONLY
event.TPRECV
sets TP-STATUS
to TPEEVENT
, and returns TPEV_SENDONLY
in TPEVENT
, indicating that control has passed to B.TPRETURN
with TPRETURN-VAL IN TPSVCRET
set to TPSUCCESS
. This call generates a TPEV_SVCSUCC
event for A and gracefully brings down the connection. 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. |
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:
TPSEND
with the TPRECVONLY
flag set on the connection to C, transferring control of the B-to-C connection to C. TPRETURN
with TPRETURN-VAL IN TPSVCRET
set to TPSUCCESS
, TPFAIL
, or TPEXIT
, as appropriate.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 . |
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:
01TPSVCDEF-REC
.
COPY TPSVCDEF.
01TPSTATUS-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 TPDI SCON(3cbl) in the BEA Tuxedo ATMI COBOL Function Reference.
Use the following commands to build conversational clients and servers:
buildclient()
as described in "Building Clients" in Programming BEA Tuxedo ATMI Applications Using Cbuildserver()
as described in "Building Servers" in Programming BEA Tuxedo ATMI Applications Using CFor conversational and request/response services, you cannot:
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 routines for which they are returned, and a detailed description of each.