Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
Tuxedo Doc Home   |   TOP END Domain Gateway   |   Topic List   |   Previous   |   Next   |   Contents

   Using the BEA Tuxedo TOP END Domain Gateway

BEA Tuxedo clients may enqueue messages to BEA TOP END RTQ queues by calling tpenqueue(3c).The BEA Tuxedo application routes the request to the TEDG based on the queue space (QSPACE) parameter specified in the call. The TEDG appears to the BEA Tuxedo client as if it is a TMQUEUE(5) server.

The BEA TOP END administrator must create an RTQ queue in the BEA TOP END system. (For details on creating an RTQ queue, see the BEA TOP END Recoverable Transaction Queuing Guide.) To advertise an RTQ queue as a BEA Tuxedo queue space, the TEDG must have a QSPACE entry for it in the DM_REMOTE_SERVICES section of the DMCONFIG file. The status of the RTQ queue in the BEA TOP END system (that is, whether the RTQ server for the queue is available) is not tracked while the connection is active. These TEDG-supported queue spaces are not defined using qmadmin, as queue spaces are defined for BEA Tuxedo /Q queues.

The TEDG uses the TE_RTQGROUP, TE_RTQNAME, and optional TE_TARGET parameters in the queue space entry to determine the corresponding BEA TOP END queue. The TEDG uses the queue name (qname) parameter from the tpenqueue() function to determine the name of the service for the RTQ request. The DM_REMOTE_SERVICES section is searched for a QNAME entry that matches the queue name. The values of four associated parameters-TE_PRODUCT, TE_FUNCTION, TE_TARGET, and TE_QUALIFIER-are retrieved and included in the message sent to the BEA TOP END system. To the BEA TOP END system, the TEDG appears to be making a tp_rtq_put request.

The TEDG returns TPENOENT if the queue space cannot be mapped successfully. A tpenqueue() return code of TPEDIAGNOSTIC and a diagnostic value of QMEBADQUEUE are returned if qname cannot be mapped. The status returned by the BEA TOP END system is mapped to a BEA Tuxedo return value and sent to the BEA Tuxedo client.

The message enqueued to the RTQ queue is scheduled by RTQ and the recipient server accesses the message in the standard way. The client identifier associated with the request is the TEDG local domain ID. As with all RTQ messages, the server responds to RTQ upon completion but it cannot return data. If the server needs to reply, the client and server must pass reply queue information within the actual client message to emulate the way that replies are handled by the /Q feature of the BEA Tuxedo system.

A BEA Tuxedo client programmer uses the tpenqueue() function to enqueue a message to a BEA TOP END RTQ queue using the TEDG.

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

• The queue space name assigned by the administrator, in the DMCONFIG file, to the BEA TOP END RTQ queue.

• The queue name (qname) assigned to the BEA TOP END service to which the message will be sent at the time scheduled by RTQ.

• The buffer type required by the BEA TOP END service. A BEA Tuxedo buffer type of CARRAY or X_OCTET is used to prepare the 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 tpenqueue() returns TPEDIAGNOSTIC and QMEINVAL errors.

Because BEA TOP END RTQ messages are limited to 30,000 bytes, the client request may not exceed that limit. For FML32 messages, the limit applies after the FML index is stripped from the message.

A client request may be transactional or non-transactional. The following table shows how the BEA Tuxedo client tpenqueue flags and associated parameters are mapped to a BEA TOP END RTQ request. By mapping the following flags and parameters, the TEDG performs a task that is normally done in the BEA Tuxedo system.

BEA Tuxedo Client Flag Mapping

BEA Tuxedo Client Flag	Action
TPQTIME_ABS	If set, the value in TPQCTL deq_time is the actual time the client wishes to have the message dequeued. The value is stored as a UNIX time type. The TEDG passes this time value to the RTQ server to be carried out as a client-relative, absolute-time value.
TPQTIME_REL	If set, the value in TPQCTL deq_time is the amount of time, in seconds, the client wishes to wait before the message can be dequeued. The TEDG maps this value to the RTQ schedule_time parameter (in R:HH:MM format).
TPNOTRAN	The TEDG preserves the fact that the tpenqueue request is excluded from the client transaction by the ATMI library.
TPQMSGID	If set, the RTQ request_id returned by RTQ is stored in the TPQCTL msgid field on a successful request.

All other tpenqueue() option flags, including those in the following list, are not supported by the TEDG. The urcode field in TPQCTL is also not supported.

• TPQTOP

• TPQBEFOREMSGID

• TPQPRIORITY

• TPQREPLYQ

• TPQFAILUREQ

• TPQCORRID

• TPQDELIVERYQOS

• TPQREPLYQOS

• TPQEXPTIME_ABS

• TPQEXPTIME_REL

• TPQEXPTIME_NEVER

• TPQOSDEFAULTPERSIST

• TPQOSPERSISTENT

• TPQOSNONPERSISTENT

The tperrno values returned to the BEA Tuxedo client on the tpenqueue() call are standard values. Because the TEDG acts as a TMQUEUE server, it maps many TEDG and RTQ related errors to both the TPEDIAGNOSTIC tperrno and a corresponding value for the TPQCTL diagnostic field.

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 the QSPACE based upon the actual availability of the BEA TOP END RTQ server that handles the queue, a message may be routed to a BEA TOP END node where the queue space actually is unavailable, resulting in a tperrno of TPENOENT, while other routing decisions may result in successful requests. If a queue space 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 Error	Cause
TPENOENT	No match was found on a QSPACE entry for the QSPACE parameter.
TPENOENT	The BEA TOP END system returned TP_SERVICE; the RTQ server for the queue is unavailable.
TPENOENT	An on-demand connection failed.
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.
TPEDIAGNOSTIC, QMEBADQUEUE	No match was found on a QNAME entry for qname parameter.
TPEDIAGNOSTIC, QMEINVAL	One of these unsupported flags was set: TPQREPLYQ, TPQFAILUREQ, TPQCORRID, TPQBEFOREMSGID, TPQTOP, TPQPRIORITY, TPQDELIVERYQOS, TPQREPLYQOS, TPQEXPTIME_ABS, TPQEXPTIME_REL, TPQEXPTIME_NEVER, TPQOSDEFAULTPERSIST, TPQOSPERSISTENT, TPQOSNONPERSISTENT
TPEDIAGNOSTIC, QMEINVAL	The user buffer type does not match the type specified in the INBUFTYPE field of the QNAME entry or it is not a type supported by the TEDG. (FML32, CARRAY, and X_OCTET buffer types are supported.)
TPEDIAGNOSTIC, QMEINVAL	The user buffer exceeds the maximum RTQ message size of 30,000 bytes (after the FML index is stripped for FML buffers).
TPEDIAGNOSTIC, QMEINVAL	The TPQTIME_REL flag is set and the value in TPQCTL deq_time is set to be greater than 86400 (that is, 24 hours).
TPEDIAGNOSTIC, QMENOSPACE	The BEA TOP END system returned TP_RTQ_EOF and TP_RTQ_NO_SPACE.
TPEDIAGNOSTIC, QMESYSTEM	The BEA TOP END system returned TP_RTQ_ERROR, TP_RTQ_MEMERR, and TP_RTQ_QDISABLED.
TPEDIAGNOSTIC, QMESYSTEM	The BEA TOP END system returned TP_RESET.

See Also

• tpenqueue(3c) in BEA Tuxedo C Function Reference