This chapter covers the subject of conversational clients and services.
A conversational client differs in the following ways from a request/response client (described in Chapter 11, "Writing Client Programs,"):
Introduction
TPCONNECT rather than TPCALL or TPACALL.
A conversational service differs in the following ways from a request/response service (described in Chapter 12, "Writing Service Routines,"):
Both conversational clients and servers have the following characteristics:
TPSEND and TPRECV calls to send and receive data in conversations.
In the conversational mode of communication, a half-duplex connection is established between the client (or initiator) and a server. Control of the connection can be passed back and forth between the initiator and the subordinate server. At any point in the conversation, the process that has control can send messages; the process that does not have control can only receive. The connection remains up until an event occurs that tears it down. One event, A communications handle, Data is passed in typed records just as in request/response mode. The record types must be recognized by the application; they must be defined with ATMI routines as described in Chapter 11, "Writing Client Programs."
Conversational clients must join the application via a call to Data can be sent at the same time the connection is being established through the DATA-REC with the length of the data specified by As with other ATMI routines, the behavior of the called program can be controlled by settings of New valid settings are:
Conversational Mode
TPEV-SENDONLY, a setting of TPEVENT IN TPSTATUS-REC, notifies the receiving program that control of the connection has been passed to it and it can successfully call TPSEND. Other events are notifications that something significant has occurred; they have the result of either bringing the conversation to a normal conclusion or precipitating a disorderly disconnection.
The Communications Handle
COMM-HANDLE IN TPSVCDEF-REC, is returned 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 have more than one conversation active simultaneously. The maximum number is ten. A client process can have up to ten connections open, all outgoing. A service process can have one incoming connection and up to nine outgoing connections.
Record Management
Joining an Application
TPINITIALIZE before attempting to establish a connection to a service. The procedure for joining the application is described in Chapter 11, "Writing Client Programs."
Establishing a Connection
TPCONNECT is the ATMI routine used to set up a conversation. The syntax is
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.
SERVICE-NAME IN TPSVCDEF-REC must contain the name of a service posted in the bulletin board by a conversational server. If SERVICE-NAME is not a reference to a conversational service, the call fails and TP-STATUS IN TPSTATUS-REC is set to the error code TPENOENT. If the calling program has already reached the maximum number of active connections allowed, the call will fail with the error code TPELIMIT.
LEN IN TPTYPE-REC. The REC-TYPE and SUB-TYPE of the data contained in DATA-REC must be a type recognized by the service being called. If no data is being sent, REC-TYPE is SPACES, and DATA-REC and LEN are ignored. If the record is self-defining (for example, a VIEW record), LEN is ignored and can be set to 0. The conversational service being called receives the DATA-REC and LEN when the service is invoked. So far this should sound a lot like what happens when a request/response service is invoked, because it is. Differences begin to appear when we consider values for the settings.
Values for the Settings: TPCONNECT
TPCONNECT. Eight of the settings are identical to their use in TPCALL and are described in the section titled "Values for the Settings: TPCALL" in Chapter 11. They are:
TPNOTRAN TPNOBLOCK TPNOTIME TPSIGRSTRT
TPTRAN TPBLOCK TPTIME TPNOSIGRSTRT
TPSENDONLY
TPSENDONLY setting of TPSENDRECV-FLAG IN TPSVCDEF-REC; TPSENDONLY and TPRECVONLY are mutually exclusive; one or the other must be specified.
TPRECVONLY
TPRECVONLY setting of TPSENDRECV-FLAG IN TPSVCDEF-REC; TPSENDONLY and TPRECVONLY are mutually exclusive; one or the other must be specified.
As mentioned above, on successful completion TPCONNECT returns a COMM-HANDLE IN TPSVCDEF-REC that is used in all subsequent calls of the conversation. Your call to TPCONNECT should be coded something like that shown in Listing 13-1.
Listing 13-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-HANDLEis valid.
After the conversational connection is set up, communication between the client (or initiator) and the service is accomplished with send/receive calls. The connection is half-duplex. That means communication can be in only one direction at a time. The process that has control of the connection can send; the process that does not have control can receive. Initially, control is decided by the originator and is specified by the TPRECVONLY setting value of the TPCONNECT call; TPRECVONLY means control is given to the called service. After TPCONNECT returns successfully, data is sent across the open connection with the TPSEND routine.
The syntax of TPSEND is:
01TPSVCDEF-REC.
COPY TPSVCDEF.
01TPTYPE-REC.
COPY TPTYPE.
01DATA-REC.
COPY User Data.
01TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPSEND" USINGTPSVCDEF-REC TPTYPE-REC USER-DATA-REC TPSTATUS-REC.
COMM-HANDLE IN TPSVCDEF-REC is the communications handle returned by TPCONNECT or TPSVCSTART that identifies the connection over which to send the data. DATA-REC and LEN IN TPTYPE-REC are, respectively, a structure that contains the data and the length of the data to be sent. The same rules apply to DATA-REC and LEN that have been outlined earlier: the record must be of a type recognized by the program that receives it and length can be 0 if the record is self-defining. There is no requirement that data be sent.
There are eight valid settings for TPSEND. The following six settings have the same meanings described in "Values for the Settings: TPCALL" in Chapter 11.
TPNOBLOCK TPNOTIME TPSIGRSTRT
TPBLOCK TPTIME TPNOSIGRSTRT
The other settings are like ones that are used in TPCONNECT, but have added significance in this routine.
TPRECVONLY
TPSEND calls at the moment and to pass control of the connection over to the other side of the connection. When the called program receives the data, it also receives a TPEV-SENDONLY event. Either TPRECVONLY or TPSENDONLY must be set.
TPSENDONLY
TPRECVONLY or TPSENDONLY must be set.
It is not a requirement that control be passed each time the TPSEND call is made. The process authorized to make TPSEND calls on the connection can make as many calls as necessary before turning over control of the connection. In fact, the logic of the conversational program may be such that one side of the conversation retains control of the connection throughout the life of the conversation.
Listing 13-2 shows TPSEND used in a code fragment.
Listing 13-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 . . .
The routine used to receive data sent over an open connection is TPRECV. The syntax is:
01TPSVCDEF-REC.
COPY TPSVCDEF.
01TPTYPE-REC.
COPY TPTYPE.
01DATA-REC.
COPY User Data.
01TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPRECV" USINGTPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
If the routine is being issued from a subordinate program (that is, not the originator of the connection), COMM-HANDLE, the communications handle, is in the TPSVCDEF-REC structure for the program. If TPRECV is being issued by the originator, COMM-HANDLE is the handle returned by TPCONNECT. When the call is made, DATA-REC specifies where the data is to be placed, LEN IN TPTYPE-REC contains the maximum number of bytes and REC-TYPE IN TPTYPE-REC and SUB-TYPE IN TPTYPE-REC have the data's type and sub-type. LEN is not allowed to be 0 on input. If it is, the call fails and TP-STATUS is set to TPEINVAL.
Upon successful return, DATA-REC contains the data received and LEN contains the actual number of bytes moved. If the length of the message is greater than DATA-REC, DATA-REC will receive as much of the message as possible and set TPTRUNCATE. If LEN is 0, no data was received and DATA-REC remains unchanged.
If an event exists for COMM-HANDLE, TPRECV returns TP-STATUS set to TPEEVENT. The event type is returned in TPEVENT. With events TPESVCSUCC, TPESVCFAIL, and TPESENDONLY data can be received. A more complete discussion of events can be found in "Events and Their Significance" later in this chapter.
TPRECV has eight valid settings. Six are described in Chapter 11 (in the section called "Values for the Settings: TPCALL"). They are:
TPNOCHANGE TPNOTIME TPSIGRSTRT
TPCHANGE TPTIME TPNOSIGRSTRT
The last two valid settings are:
TPNOBLOCK
TPRECV gets the data and returns. If data is not available, the call fails and TP-STATUS is set to TPEBLOCK. TPNOBLOCK or TPBLOCK must be set.
TPBLOCK
TPNOBLOCK or TPBLOCK must be set.
Listing 13-3 shows a fragment of code using TPRECV.
Listing 13-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 . . .
There are three ways in which the connection can be taken down in an orderly fashion and the conversation ended normally. Figure 13-1 and Figure 13-2 show two scenarios that illustrate how conversations are ended when global transactions are not involved. (For a description of ending a conversation when a transaction is involved, see Chapter 14, "Global Transactions in the BEA TUXEDO System.")
Figure 13-1 shows a simple "A-to-B" conversation. The connection is set up initially with a call to TPCONNECT with the TPSENDONLY setting of the TPSENDRECV-FLAG IN TPSVCDEF-REC set. In due course, A turns control of the connection over to B by calling TPSEND with a valid setting of TPRECVONLY. This generates a TPEV-SENDONLY event. The next call by B to TPRECV returns TP-STATUS IN TPSTATUS-REC set to TPEEVENT and TPEVENT set to TPEV-SENDONLY. B knows from the TPEV-SENDONLY event that it now controls the connection. Subsequently, B calls TPRETURN with TP-RETURN-VAL IN TPSVCRET-REC set to TPSUCCESS. This generates a TPEV-SVCSUCC event setting for TPEVENT IN TPSTATUS-REC for A. The call to TPRETURN also brings down the connection. When A calls TPRECV and learns of the event, it recognizes that the conversation has been terminated. Data can be received on this call to TPRECV even if the event is TPEV-SVCFAIL. In this illustration, A can be either a client or a server; B can be only a server.
Figure 13-1 Simple SENDONLY Connection and Return
Figure 13-2 shows a hierarchy of connections. The scenario applies to a service in a conversation, B, that has initiated a connection to a second service, 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 will fail, a TPEV-SVCERR event setting for TPEVENT IN TPSTATUS-REC will be posted on all open connections and the connections will be closed in a disorderly manner. The proper sequence is for B to call TPSEND with the TPRECVONLY setting on the connection to C, turning control of the B-C connection over to C. C can then call TPRETURN with TP-RETURN-VAL IN TPSVCRET-REC set to TPSUCCESS, TPFAIL, or TPEXIT, as appropriate. B can then call TPRETURN, setting an event (either TPEV-SVCSUCC or TPEV-SVCFAIL) for A. Both connections are terminated normally.
Figure 13-2 Connection Hierarchy
It is an error to end a conversation with connections still open. Either TPCOMMIT or TPRETURN will fail in a disorderly manner.
To summarize the ways in which a conversation can be ended in an orderly manner:
TPRETURN. This is illustrated in Figure 13-1, above.
TPRETURN. The subordinate must have control of the connection and must make the call to TPRETURN before the originator does. This is illustrated in Figure 13-2, above.
There are five events recognized in conversational communication. All five can be posted for Events and Their Significance
TPRECV; three can be posted for TPSEND.Table 13-1 summarizes these events.
The name of the The syntax is simple:
The preferred way of bringing down a connection is for the subordinate to call There is nothing that prevents a conversational service from making request/response calls if it needs to communicate with another service. In the example of connection hierarchies shown earlier in Figure 13-2, the calls from B to C could have been made with Some parameters in the configuration file apply only to conversational processing. As noted in the "Configuration File" section of Chapter 10, "The BEA TUXEDO System Development Environment," the BEA TUXEDO system administrator normally is responsible for setting up the production version of the configuration file for the application, but you may need to set some parameters in your own development configuration.
You need to know about the following parameters:
Disorderly Disconnection
TPDISCON routine suggests that this routine is the opposite of TPCONNECT, but this is not the case; TPDISCON is really the equivalent of pulling the plug on the connection. It can be called only by the initiator of a conversation.
01
TPSVCDEF-REC.
COPY TPSVCDEF.01
TPSTATUS-REC.
COPY TPSTATUS.CALL "TPDISCON" USING
TPSVCDEF-REC TPSTATUS-REC.COMM-HANDLE IN TPSVCDEF-REC is the communications handle returned by TPCONNECT.
TPDISCON generates a TPEV-DISCONIMM event setting of TPEVENT IN TPSTATUS-REC for the service at the other end of the connection and the COMM-HANDLE is no longer valid. If a transaction is in progress, it is aborted. Data may be lost. If TPDISCON is called from a service that was not the originator of the connection identified by COMM-HANDLE, it fails with TP-STATUS set to [TPEBADDESC].
TPRETURN.
Request/Response Calls and Conversations
TPCALL or TPACALL instead of TPCONNECT. Remember, however, that conversational services are not permitted to make calls to TPFORWAR.
Configuration Parameters
MAXCONV
RESOURCES section for all machines in the configuration and can be overridden in the MACHINES section for each machine. For an application under development, the default value is probably adequate.
CONV = { Y | N }
SERVERS section. Connections can be made only to servers that have this value set to Y. If it is set to N or left unspecified, a TPCONNECT call to a service of the server will fail.
MIN & MAX
SERVERS section that specify the minimum and maximum number of occurrences of the server to be started by tmboot(1). If not specified, MIN defaults to 1 and MAX defaults to MIN. The same parameters are available for use with request/response servers. However, conversational servers are automatically spawned as needed. So if you set MIN = 1 and MAX = 10, for example, tmboot starts one initially. When a TPCONNECT call is made to a service offered by that server, the system starts up a second copy. As each copy is called a new one is spawned, up to a limit of ten.
MAXSERVERS
MAX values for all conversational servers. You probably won't need to worry about this for an application under development, but it could be something that needs attention when the application reaches the production stage. The parameter is in the RESOURCES section.
The utilities described in Chapters 11 and 12, buildclient and buildserver, are used for building conversational clients and servers.
Conversational servers must be built only with conversational services; that is, mixing of conversational services and request/response services in the same server is not allowed. Conversational services and request/response services cannot use the same name.