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


	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

BEA Tuxedo clients communicate with BEA TOP END services through the TEDG. Relative to a BEA Tuxedo client, the TEDG functions as a local server. The TEDG advertises services specified in the SERVICE entries in the DM_REMOTE_SERVICES section of the DMCONFIG file. Client programs make requests and receive responses using tpcall(3c) in the same way they use tpcall() to interact with local services. Asynchronous requests and responses are supported through the tpacall(3c) and tpgetrply(3c) functions. If, in the DM_REMOTE_SERVICES section of the DMCONFIG file, the SERVICE entry for a TEDG service contains the setting CONV=N, then BEA Tuxedo 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.)

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, Message Sensitive Routing (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.

How the TEDG Works with BEA Tuxedo Clients

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

Use this function . . .	For . . .
tpcall()	Synchronous requests and responses
tpacall()	Asynchronous requests and responses
tpgetreply()	Asynchronous requests and responses

These functions are programmed in the normal manner.

As a BEA Tuxedo client programmer, you need to know the following information:

The service name assigned by the administrator (in the DMCONFIG file) to the BEA TOP END service.
The buffer type required by the BEA TOP END service. A BEA Tuxedo buffer type of CARRAY or X_OCTET is used to prepare a raw buffer required by the BEA TOP END service. Buffers of these types have no data marshalling support when transmitted by the TEDG between BEA TOP END nodes of different types.
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.
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 call to tpcall() or tpgetrply() returns a TPESVCERR error (not a TPEITYPE error).

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 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 Tuxedo client flags are mapped to a BEA TOP END request. All other flags (TPNOCHANGE, TPNOBLOCK, TPNOTIME, TPSIGRSTRT) and the service priority (see tpsprio()) 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.

BEA Tuxedo Client Flag Mapping

BEA Tuxedo Client Flag	Action
TPNOTRAN	The TEDG preserves the fact that the request is excluded from the client transaction by the ATMI library.
TPNOREPLY	Passed as TP_NO_RESPONSE to the BEA TOP END system. The BEA TOP END routing status is not passed to the BEA Tuxedo client.

The tperrno values returned to the BEA Tuxedo client are standard values. Because the TEDG acts as a BEA Tuxedo server, it also returns TPESVCERR and TPESVCFAIL for certain conditions. The BEA Tuxedo client cannot interpret these messages as "application defined errors" exclusively:

TPESVCERR indicates delivery errors and other general errors.
TPESVCFAIL indicates that the BEA TOP END system/service reset the mapped dialog request. Reset is one method used by a BEA TOP END server to indicate that it received a request but cannot process it.

For additional information, see Error Values.

Note: tpurcode is not supported by the TEDG.

The TEDG maps the response from the BEA TOP END system/server to a response that the BEA Tuxedo client accesses through the tpcall parameters or the tpgetrply function. 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 the following types: CARRAY, X_OCTET or FML32. If the BEA TOP END service returns an incompatible buffer, the TEDG returns a tperrno of TPEOTYPE.

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 requests in the normal manner through tp_server_receive(3T). The buffer received is either a raw buffer or an FML32 buffer, depending on the message sent by the BEA Tuxedo client. The BEA TOP END server receives one of the following types of requests:

A normal request.
A "no-response" request—this type of request (in which the TP_NO_RESPONSE flag is set) is received when the BEA Tuxedo client sends a TPNOREPLY message.

The BEA TOP END server handles both types of requests according to standard BEA TOP END programming requirements. The client request may be transactional or non-transactional.

How the TEDG Maps BEA TOP END Server Send Flags

The BEA TOP END server responds to a client request using tp_server_send(3T). The response buffer may be either a raw buffer or an FML32 buffer, depending on what is supported by the BEA TOP END application, the TEDG configuration, and the BEA Tuxedo client. This buffer is mapped to a BEA Tuxedo client buffer as described in How the TEDG Maps Client Requests.

The following table shows how BEA TOP END tp_server_send(3T) flags are mapped. 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 respond appropriately. Do not use the output_format and attach_info parameters on responses to the TEDG; they are not supported.

BEA TOP END "Server Send" Flags

BEA TOP END Server Flag	Action
TP_RESET_DIALOG	TPESVCFAIL is returned to the BEA Tuxedo client.
TP_ROLLBACK_ONLY	The TEDG marks the state of the transaction associated with the request as "abort-only."
TP_DISSOLVE	A response is passed to the BEA Tuxedo client. Because the TEDG manages dialogs in a special manner, the results of setting the flag are the same as the results of not setting the flag.
TP_APPL_CONTEXT	Indicates that the server wants to initiate a conversation. This request for conversational mode is an error for request/response processing. TESVCERR is returned to the BEA Tuxedo client. The BEA TOP END server is disconnected (TP_DISCONNECT) by the TEDG.
TP_FML_BUF	The TEDG passes the user data as an FML32 buffer.

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 tperrno 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 tperrno of TPENOENT, 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 Tuxedo Client

BEA Tuxedo tperrno Value	Cause
TPENOENT	No match was found on the SERVICE entry.
TPENOENT	A tpcall or tpacall request was sent to a conversational service (CONV=Y).
TPENOENT	TP_SERVICE was returned by the BEA TOP END system.
TPESVCERR with an error detail of TPED_DOMAINUNREACHABLE	An on-demand connection failed.
TPESVCERR	The input buffer type does not match the one specified in the INBUFTYPE field of the SERVICE entry or it is not a type that is supported by the TEDG. (FML32, CARRAY, and X_OCTET are supported.)
TPESVCERR	The input buffer exceeds the maximum message size of 30K bytes (after the FML index is stripped for FML buffers).
TPESVCERR	The server returned TP_APPL_CONTEXT on a non-conversational SERVICE entry.
TPESVCFAIL	TP_RESET was returned by the BEA TOP END system.
TPEOTYPE	The buffer type of the server response does not match the type specified in the OUTBUFTYPE field of the SERVICE entry.
TPESYSTEM	Error due to public/private key encryption: The client input was rejected 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.
TPESYSTEM	Error due to digital signature: The client input was rejected 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.