How Messages Are Passed from BEA TOP END Clients to BEA Tuxedo Server


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Documentation \| Using the BEA Tuxedo TOP END Domain Gateway \| Local Topics \| Previous Topic \| Next Topic \| Contents

How Messages Are Passed from BEA TOP END Clients to BEA Tuxedo Servers

BEA TOP END clients communicate with BEA Tuxedo servers through the TEDG. If, in the DM_LOCAL_SERVICES section of the DMCONFIG file, the SERVICE entry for a TEDG service contains the setting CONV=N, then BEA TOP END clients may communicate with that service in only one mode: request/response. (CONV=N is the default value and does not need to be set.)

Relative to a BEA TOP END client, the TEDG functions as a BEA TOP END server on a remote BEA TOP END node. The TEDG receives a BEA TOP END client request and maps it to a corresponding BEA Tuxedo request. Note that the BEA Tuxedo system may route the request to a BEA Tuxedo server anywhere within the BEA Tuxedo configuration.

The process for passing messages in request/response mode from a BEA TOP END client to a BEA Tuxedo server is as follows:

When a network connection is made, the TEDG advertises services listed in the SERVICE entries in the DM_LOCAL_SERVICES section of the DMCONFIG file. The names of the advertised product, function, and MSR target are used in normal BEA TOP END routing and load-balancing algorithms to determine the destination node.
The message includes the following information: the names of the product, function, optional MSR target, and optional function qualifier. When the TEDG receives the message, it uses this information to search the SERVICE entries in the DMCONFIG file for the appropriate BEA Tuxedo service.
The TEDG performs any required unmarshalling of data.
The message is sent to the appropriate BEA Tuxedo service.
The BEA Tuxedo server response is mapped to a BEA TOP END status and buffer, marshalled (if necessary), and sent to the BEA TOP END client.

How the TEDG Works with BEA TOP END Clients

Client operations are programmed with the same functions used for any BEA TOP END client.

Use This API . . .	For . . .
tp_client_send	Making asynchronous requests
tp_client_signon	Making asynchronous requests
tp_client_receive	Receiving responses

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:

The product and function name assigned by the administrator, in the DMCONFIG file, to the BEA Tuxedo service.
If you are trying to match existing BEA TOP END programming, the function qualifier value, optionally assigned by the administrator.
The MSR target name, which may have been assigned by the administrator in the DMCONFIG file. (Assigning an MSR target is optional.) This MSR target name may be used:
- To match a configured BEA TOP END MSR routing strategy, or
- Directly by the BEA TOP END client application.
The buffer type required by the BEA Tuxedo service. A raw message must be sent if the BEA Tuxedo server requires either CARRAY or X_OCTET. By default a raw message is mapped to a CARRAY buffer. Buffers of these types have no data marshalling support when transmitted to the TEDG by a BEA TOP END node of a different type.
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.
Whether the administrator has required, in the DMCONFIG file, the exclusive use of one buffer type. If a buffer of a type that is inappropriate (due to the fact that it does not match either the configured type or any type supported by the TEDG) is sent to the TEDG, a tp_client_receive call returns a TP_RESET error.

How the TEDG Maps Client Requests

A client request may be transactional or non-transactional and it may or may not require a response. The following table shows how BEA TOP END client flags are mapped. By processing these flags, the TEDG accomplishes tasks that are 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.

BEA TOP END Client Flag Mapping

BEA TOP END Client Flag	Action
TP_DISSOLVE	The dialog is dissolved after the TEDG returns the BEA Tuxedo server response.
TP_NON_TRANSACT	The TEDG preserves the fact that the request is excluded from the client transaction by the CSI library.
TP_NO_RESPONSE	Mapped to TPNOREPLY by the TEDG. Like the BEA TOP END system, the TEDG responds to the BEA TOP END client with a routing status.
TP_FML_BUF	The TEDG passes the user data as an FML32 buffer.

The status and extended status values returned to the BEA TOP END client are standard values. Additional information on the mapping of error values is provided later in this topic.

The TEDG maps the response from the BEA Tuxedo system/server to a response that the BEA TOP END client accesses through the tp_client_receive(3T) call. A BEA Tuxedo server may deliver a response in a CARRAY, X_OCTET, or FML32 buffer. 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. Additionally, the administrator may constrain the response buffer to one of the following types: CARRAY, X_OCTET, or FML32. If the BEA Tuxedo service returns an incompatible buffer, 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 BEA Tuxedo client: it receives mapped BEA TOP END client requests in the normal manner. The type of the buffer it receives (CARRAY, X_OCTET, or FML32) depends on the message sent by the client. The BEA Tuxedo server processes the request in the normal manner. The request may be transactional or non-transactional. It may be a "no-reply" request.

A BEA Tuxedo server responds to a client request using tpreturn(3c). TPSUCCESS is mapped to a TP_OK BEA TOP END status. TPFAIL and TPEXIT, along with a number of other error conditions, are mapped to a TP_RESET BEA TOP END status. A reply message is supported only with TPSUCCESS.

Note: The application-defined return code, rcode, is not supported by the TEDG.

The BEA Tuxedo server may deliver a reply in a CARRAY, X_OCTET, or FML32 buffer, depending on which buffer types are supported by the BEA TOP END system, the TEDG configuration, and the BEA TOP END client. The reply buffer is mapped to a BEA TOP END message. The server may indicate an error by sending a TPFAIL error or by responding with an application-defined field value in the reply buffer. The BEA TOP END client must be programmed to handle that error reporting interface of the server.

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.

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.

Error Values Returned to a BEA TOP END Client

BEA TOP END Error Status	Cause
TP_SERVICE, TP_EXT_MSR_FAILURE	The TEDG SERVICE entry lookup failed: the target was not found.
TP_SERVICE, TP_EXT_NO_SUCH_SERV	The TEDG SERVICE entry lookup failed: the product or function was not found (ignoring entries for which RDOM does not have access).
TP_SERVICE, TP_EXT_NO_SUCH_SERV	TPENOENT was returned by the BEA Tuxedo system.
TP_RESET, TP_EXT_SERVER_APPL	The input buffer type does not match the type specified in the INBUFTYPE field of the SERVICE entry.
TP_RESET, TP_EXT_SERVER_APPL	The server response buffer type does not match the type specified in the OUTBUFTYPE field of the SERVICE entry or it is not a type supported by the TEDG. (The supported types are FML32, CARRAY, and X_OCTET.)
TP_RESET, TP_EXT_SERVER_APPL	The server response buffer exceeds the maximum message size of 30K bytes (after the FML index is stripped for FML buffers).
TP_RESET, TP_EXT_SERVER_APPL	TPESVCERR, TPESVCFAIL, and all other tperrno values.
TP_RESET, TP_EXT_SERVER_APPL	Error due to public/private key encryption: The client input was rejected by the BEA Tuxedo server because the BEA Tuxedo system is configured to require encryption and the TEDG could not decrypt the message before sending it to the BEA TOP END system.
TP_RESET, TP_EXT_SERVER_APPL	Error due to digital signature: The client input was rejected by the BEA Tuxedo server because the BEA Tuxedo system is configured to require digital signatures and the TEDG could not remove the digital signature from the message before sending the message to the BEA TOP END system.