|
|
 |
| e-docs > Tuxedo > Using the Tuxedo TOP END Domain Gateway with ATMI Applications > Conversational Mode Programming |
|
Using the Tuxedo TOP END Domain Gateway with ATMI Applications
|
Conversational Mode Programming
This topic includes the following sections:
Using Conversational Messaging with the TEDG
The BEA Tuxedo and BEA TOP END systems support different styles of conversational message passing:
The TEDG provides a mapping of BEA TOP END pseudo-conversations to the BEA Tuxedo conversation model. This mapping enables BEA Tuxedo clients to maintain context with BEA TOP END servers for multiple-step interactions. The reverse is also true for BEA TOP END clients that want to maintain context with BEA Tuxedo servers. Multiple-step interactions are routed to the same server until the conversation is terminated. Single-step interactions between conversational components are also allowed. If you need the same server to handle single-step and multiple-step interactions, then you must use conversational messaging.
See Also
How Messages Are Passed from BEA Tuxedo Clients to BEA TOP END Servers
BEA Tuxedo clients communicate conversationally with BEA TOP END services through the TEDG. Relative to a BEA Tuxedo client, the TEDG functions as a local conversational server. The TEDG advertises services specified in the SERVICE entries in the DM_REMOTE_SERVICES section of the DMCONFIG file. If a BEA TOP END server supports pseudo-conversations, then the BEA Tuxedo administrator must configure the services offered by that server as conversational by setting CONV=Y in the SERVICE entry in the DM_REMOTE_SERVICES section of the DMCONFIG file. If the SERVICE entry for a TEDG service is CONV=Y, then BEA Tuxedo clients may communicate with that service only in conversational mode. The BEA Tuxedo client uses the tpconnect(3c), tpsend(3c), tprecv(3c), and tpdiscon(3c) functions.
The TEDG uses the requested service name to locate the SERVICE entry in the DM_REMOTE_SERVICES section to determine the corresponding BEA TOP END product, function, MSR target and function qualifier for the mapped BEA TOP END request. Data marshalling is performed by the TEDG, as required, before the message is sent to the BEA TOP END system. The BEA TOP END system then routes the request to a server on a BEA TOP END node that has received the message. The BEA TOP END server response is unmarshalled, if necessary. The TEDG maps the status of the request and prepares the buffer for delivering the response to the BEA Tuxedo client.
The BEA TOP END server may use application context, on an ongoing basis, to determine whether to continue a conversation with a BEA Tuxedo client: as long as application context is present, the conversation is maintained; when the application context is absent, the conversation is ended.
How the TEDG Works with BEA Tuxedo Clients
The BEA Tuxedo client programmer uses tpconnect(3c) to establish a conversation with a BEA TOP END server. The server may respond conversationally or it may respond with a single response and end the conversation. Unlike clients participating in normal BEA Tuxedo conversations, clients accessing the BEA TOP END system must accept a response to each message. To prepare a client to receive a response to each request, set the TPRECVONLY flag on tpconnect() and subsequent tpsend(3c) calls. When this flag is set, the client waits to receive a message before sending another. The BEA Tuxedo tprecv(3c) function is used to receive replies from the BEA TOP END system. If TPRECVONLY is not specified or if the flags are set to TPSENDONLY, the TEDG rejects the request, logs an error, and returns a TPEV_SVCERR event to the client. The tpconnect() and tpsend() calls are mapped to the equivalent of a BEA TOP END tp_client_send(3T) call, regardless of whether or not there is any data. If there is no data, the server receives a zero-length message.
As a BEA Tuxedo client programmer, you need to know the following information:
If a BEA TOP END service supports FML32 input, the BEA Tuxedo client uses the BEA Tuxedo FML32 buffer type. FML32 is beneficial because the TEDG and the BEA TOP END system support data marshalling of these buffers when the buffers are transmitted between the TEDG and a BEA TOP END node of a different type.
A BEA TOP END service may support one or more of these buffer types.
Because BEA TOP END messages are limited to 30K bytes, the size of the client request may not exceed that limit. For an FML32 message, the limit applies after the FML index is stripped from the message.
How the TEDG Maps Clients Requests
A client request may be transactional or non-transactional. The following table shows how BEA Tuxedo client flags are mapped to a BEA TOP END request. All other flags (TPNOBLOCK, TPNOTIME, TPSIGRSTRT) either are local to the application or affect only client-TEDG interactions in the BEA Tuxedo system. By processing the following flags, the TEDG accomplishes tasks that are normally done in the BEA Tuxedo system.
The following table shows how tpconnect(3c) and tpsend(3c) flags are mapped.
A BEA Tuxedo client receives a server response and TEDG errors by calling tprecv(3c) in the normal way for a conversation. The TEDG maps the conversation status and error conditions to tperrno values or events that are returned with tprecv(). A BEA TOP END server may deliver a response in either a raw buffer or an FML32 buffer. A raw buffer is normally mapped by the TEDG to a CARRAY buffer unless the administrator configures it to map to an X_OCTET buffer. Additionally, the administrator may constrain the response buffer to one of three possible types (CARRAY, X_OCTET, or FML32). If the BEA TOP END service returns an incompatible buffer, the TEDG returns a tperrno of TPEOTYPE. If TP_APPL_CONTEXT is not set on the server response, the TEDG ends the conversation with the BEA Tuxedo client by calling a function that is equivalent to a tpreturn(3c) with the TPSUCCESS flag set. The client interprets the ending of the conversation as a TPEV_SVCSUCC event accompanied by data returned by the server. If TP_APPL_CONTEXT is set on the server response, the TEDG maintains the conversation with the BEA Tuxedo client by calling a function that is the equivalent of a tpsend() with the TPRECVONLY flag set. The client interprets this tpsend() call as a TPEV_SENDONLY event accompanied by data returned by the server. When the server returns errors (as a TP_RESET status), the TEDG ends the conversation with the BEA Tuxedo client by calling a function that is equivalent to a tpreturn() with the TPFAIL flag set. The client interprets this call as a TPEV_SVCFAIL event. Other errors are returned as a TPEV_SVCERR event. Note: tpurcode is not supported by the TEDG. When a TPEV_SVCERR or TPEV_SVCFAIL error is returned, the conversation ends. If the server has maintained context, the TEDG disconnects (TP_DISCONNECT) the BEA TOP END dialog. How the TEDG Works with BEA TOP END Servers Relative to a BEA TOP END server, the TEDG functions as a BEA TOP END client: it receives mapped BEA Tuxedo client conversational requests in the normal manner through tp_server_receive(3T). The buffer received is either a raw buffer or an FML32 buffer, depending on which buffer types are supported by the BEA Tuxedo client. The BEA TOP END server interprets the message as either a new request or part of a continuing conversation with the BEA Tuxedo client (TP_APPL_CONTEXT flag). The BEA TOP END server handles both types of requests according to standard BEA TOP END programming requirements. For mapped BEA Tuxedo client requests, the function_qualifier field cannot be used to indicate one step in a multiple-step conversation. That information must be embedded in the client message. Client requests may be transactional or non-transactional. How the TEDG Maps BEA TOP END Server Send Flags A BEA TOP END server responds to client requests in a normal fashion, using tp_server_send(3T). The response buffer may be either a raw buffer or an FML32 buffer, depending on which buffer types are supported by BEA TOP END system, the TEDG configuration, and the BEA Tuxedo client. This buffer is mapped to a BEA Tuxedo client buffer. The server ends the conversation by sending a tp_server_send(3T) response without the TP_APPL_CONTEXT flag. If a server is to maintain context, the TP_APPL_CONTEXT flag in that server is set in the tp_server_send(3T) response. This flag instructs the TEDG to continue the conversation and maintain the associated dialog in context mode. The BEA TOP END system routes subsequent messages from the TEDG conversation in the dialog to the same server. The server may indicate an error by resetting the dialog or by responding with an application-defined field value in the response buffer. The BEA Tuxedo client must be programmed to handle that error-reporting interface of the server. The following table shows how BEA TOP END tp_server_send(3T) flags are mapped. The output_format and attach_info parameters should not be used on responses to the TEDG; they are not supported.
When a TPEV_SVCERR or TPEV_SVCFAIL error is returned, the conversation ends. If the server has maintained context, the TEDG disconnects (TP_DISCONNECT) the BEA TOP END dialog. Error Values The following error values may be returned to a BEA Tuxedo client because problems exist in the TEDG, the BEA TOP END system, or the BEA TOP END server. Keep in mind that a single error value may be used to report any one of many possible causes of the error being reported. Because the TEDG does not advertise services based upon the actual availability of BEA TOP END services, a message may be routed to a BEA TOP END node where the services actually are unavailable, resulting in a TPEV_SVCERR error, while other routing decisions may result in successful requests. If a service is to be available on multiple nodes, the design of the BEA Tuxedo application, the BEA TOP END application, and the TEDG must take into account the possibility that this type of failure may occur. A well-designed application, that ensures that there are multiple, restartable copies of the servers, reduces the possibility of such errors occurring.
See Also
How Messages Are Passed from BEA TOP END Clients to BEA Tuxedo Servers
A BEA TOP END client sends requests to BEA Tuxedo servers in the conversational mode in the same way that it sends requests in request/response mode. The TEDG then manages the conversation with the server as shown in the following table.
How the TEDG Works with BEA TOP END Clients Client operations are programmed with the same functions used for any BEA TOP END client.
These functions are used in the normal manner when making a service request to a BEA Tuxedo server through the TEDG. As a BEA TOP END client programmer, you need to know the following information:
If a BEA Tuxedo service supports FML32 input, the BEA TOP END client must use the FML32 message type. FML32 is beneficial because the TEDG and the BEA TOP END system support data marshalling of these buffers when the buffers are transmitted between the TEDG and a BEA TOP END node of a different type.
A BEA Tuxedo service may support one or more of these buffer types.
How the TEDG Maps Client Requests
A client request may be transactional or non-transactional; it must require a response. The following table shows how BEA TOP END client flags are mapped. By mapping these flags, the TEDG accomplishes a task that is normally done in the BEA TOP END system. Do not use the input_format and attach_info parameters on requests to the TEDG; they are not supported.
The status and extended status values returned to the BEA TOP END client are standard values. For additional information about the mapping of error values, see Error Values. The TEDG maps the response from the BEA Tuxedo system or server to a response that the BEA TOP END client accesses through the tp_client_receive(3T) call. BEA Tuxedo servers should send responses in one of the following types of buffers: CARRAY, X_OCTET, or FML32. A CARRAY or X_OCTET buffer is mapped by the TEDG to a raw message; an FML32 buffer, to a BEA TOP END FML32 message. The administrator may constrain the response buffer to a specific type (CARRAY, X_OCTET, or FML32). If the BEA Tuxedo service returns an incompatible buffer, then the TEDG returns a TP_RESET status. How the TEDG Works with BEA Tuxedo Servers Relative to a BEA Tuxedo server, the TEDG functions as a conversational BEA Tuxedo client: it receives mapped BEA TOP END client requests in the normal manner. The TEDG always relinquishes control after one message is sent. As a result:
The buffer received is a CARRAY, X_OCTET, or FML32 buffer, depending on the message sent by the client. The BEA Tuxedo server processes the request in the normal manner. Client requests may be transactional or non-transactional.
A BEA Tuxedo server responds to client requests in the standard manner. If the conversation is being continued, it calls tpsend(3c) with the TPRECVONLY flag and data. In this case the server must then call tprecv(3c) to receive the next client message, an error indication, or an indication that the conversation was terminated (TPEV_DISCONIMM). To send the last message of a conversation, the server calls tpreturn(3c) with the TPSUCCESS flag. To terminate a conversation and indicate an error, a server calls tpreturn() with the TPFAIL flag. Reply messages are supported only with tpsend or TPSUCCESS. The application-defined return code, rcode, is not supported by the TEDG.
The BEA Tuxedo server buffer may be a CARRAY, X_OCTET, or FML32 buffer, depending on which types are supported by the BEA TOP END system, the TEDG configuration, and the BEA TOP END client. This buffer is mapped to a BEA TOP END message as described in How the TEDG Maps Client Requests. The server may indicate an error by calling TPFAIL or by responding with an application-defined field value in the reply buffer. The BEA TOP END client must be programmed accordingly. To terminate a conversation, the client ends the dialog by calling tp_client_signoff(3T) or invoking a function switch that calls a different service.
Because BEA TOP END messages are limited to 30K bytes, the BEA Tuxedo server reply may not exceed that limit. For an FML32 message, the limit applies after the FML index is stripped from the message.
How the TEDG Maps BEA Tuxedo Server Flags
The following table shows how the TEDG maps flags to tpsend(3c), the function that transmits BEA Tuxedo server responses. All other flags (TPNOBLOCK, TPNOTIME, TPSIGRSTRT) either are local to the application or affect only server-TEDG interactions in the BEA Tuxedo system.
Error Values In addition to regular BEA TOP END error status messages, a number of other status messages may be returned to a BEA TOP END client as a result of problems in the TEDG, the BEA Tuxedo system, or the BEA Tuxedo server. Keep in mind that a single error status value may be used to report any one of many possible causes of the error being reported. Because the TEDG does not advertise services based upon the actual availability of BEA Tuxedo services, a message may be routed to a BEA Tuxedo node where the services actually are unavailable, resulting in a TP_SERVICE error, while other routing decisions may result in successful requests. If a service is to be available on multiple nodes, the design of the BEA Tuxedo application, the BEA TOP END application, and the TEDG must take into account the possibility that this type of failure may occur. A well-designed application, that ensures that there are multiple, restartable copies of the servers, reduces the possibility of such errors occurring.
See Also
|
|
|
|
||
 |
|
|
 |
 |
 |
|
||
