Reliable Queuing Programming

This topic includes the following sections:

• Using Reliable Queuing with the TEDG

• How BEA Tuxedo Clients Enqueue Messages to RTQ

• How BEA TOP END Clients Enqueue Messages to /Q

 

---

Using Reliable Queuing with the TEDG

The BEA Tuxedo and BEA TOP END systems support reliable queues that can pass messages between components. The BEA Tuxedo /Q facility and the BEA TOP END Recoverable Transaction Queuing (RTQ) facility allow messages to be passed using queues to store messages before processing. Both /Q and RTQ guarantee that once a message is successfully placed on a queue, it will be delivered to the server. Full transaction semantics are supported for both queuing and processing the message.

The TOP END Domain Gateway (TEDG) supports the enqueuing of messages between BEA Tuxedo and BEA TOP END systems. Transactional enqueuing of messages between systems is also supported. The queue itself is part of the native system on which it was created. All the administrative aspects of managing the queue and dequeuing messages are also part of the native system.

The TEDG does not support dequeuing from a queue in a remote system because the /Q and RTQ capabilities and interfaces on the dequeuing side are quite different. BEA Tuxedo /Q provides the tpdequeue(3c) function for explicitly dequeuing a message; there is no equivalent within RTQ. The RTQ facility dequeues messages automatically and delivers them to the intended BEA TOP END service. The destination service address is supplied as part of enqueuing the message (see tp_rtq_put(3T) in the BEA TOP END Programmer's Reference Manual).

The relationship between the queues and the services is arbitrary. /Q provides a system-supplied service, TMQFORWARD(5), that can be configured to dequeue messages automatically and forward them to standard BEA Tuxedo servers through the tpcall(3c) function. The destination service name must match the queue name. In a TEDG environment, the server to which these messages are sent after automatic dequeuing may be in the same system or a remote system, depending on the TEDG configuration and appropriate server programming.

We assume that you already have a BEA Tuxedo /Q queue or a BEA TOP END RTQ queue and the administrative tools and servers associated with the queue. The Using the ATMI /Q Component and the BEA TOP END Recoverable Transaction Queuing Guide describe the value of queuing, discuss the task of designing a system in which queuing is used, and explain how to set up and manage queues.

Common Queuing Capabilities Supported by the TEDG

While /Q and RTQ offer similar basic capabilities, each also offers several unique features. The capabilities offered by the TEDG represent the common subset of the features of the two systems:

• Non-transactional intersystem queuing

• Transactional intersystem queuing

• Scheduling time options

Unsupported BEA Tuxedo /Q Capabilities

The TEDG does not support the following BEA Tuxedo /Q features:

• Priorities

• Reply queue and failure queue

• Expiration time

• Quality of service

• Explicit dequeue (from an RTQ queue)

Unsupported BEA TOP END RTQ Capabilities

The TEDG does not support the following BEA TOP END RTQ features:

• Non-transactional scheduling

• Transaction key scheduling

• Initial held message status

• Tag text

• Large Message Architecture (LMA)

See Also

• "BEA Tuxedo /Q C Language Programming" on page 3-1 in Using the ATMI /Q Component

• BEA TOP END Recoverable Transaction Queuing Guide

 

---

How BEA Tuxedo Clients Enqueue Messages to RTQ

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.

How the TEDG Works with BEA Tuxedo Clients

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.

How the TEDG Maps Client Requests

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.

Table 14-1 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.

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 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.

Table 14-2 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 the BEA Tuxedo ATMI C Function Reference

 

---

How BEA TOP END Clients Enqueue Messages to /Q

BEA TOP END clients enqueue messages to BEA Tuxedo /Q queues by calling tp_rtq_put(3T). The queue_info parameter is used by the BEA TOP END system to route the request to the TEDG or another RTQ server. The queue_info parameter specifies the RTQ group, RTQ queue name, and RTQ target.

The BEA Tuxedo administrator must create the /Q queue space and create the queue names available within that QSPACE using qmadmin(1). To make the BEA Tuxedo /Q queue space available to the BEA TOP END system, a QSPACE entry for the queue space must be configured in the DM_LOCAL_SERVICES section of the DMCONFIG file and the TE_RTQGROUP, TE_RTQNAME, and TE_TARGET parameters must be specified. The TEDG advertises these parameters when a connection to the BEA TOP END system is established. The status of individual queue space availability in the BEA Tuxedo domain is not tracked while the connection is active.

When a request is received by the TEDG, the queue_info parameter (which defines the RTQ group, queue name, and target) is used to determine the proper queue space. If a target is not specified, none is included in the lookup. The tp_rtq_put service parameter is used to determine the /Q queue name. The TEDG searches the DM_LOCAL_SERVICES section looking for a QNAME entry that matches the product, function, target, and function qualifier from the message. The TEDG enqueues the message using the derived queue space and queue name parameters by calling a function equivalent to tpenqueue(3c). Default values are used as parameters to the tpenqueue options. For example, priority cannot be mapped from an RTQ request, so the default is used. After the message is enqueued, the BEA Tuxedo administrator may use qmadmin to modify attributes of the /Q queue and the messages in it.

The TEDG maps the status returned by the TMQUEUE(5) server and returns it to the BEA TOP END client. On successful enqueue requests, the TEDG assigns a unique RTQ request_id that is returned to the client. The request_id is provided only for tracking the status of requests; it cannot be used in any further administration of the request.

The recipient of the message enqueued to the /Q queue accesses the message in the standard way, depending on whether tpdequeue(3c) is called or TMQFORWARD(5) is used to turn the message into a service request. The buffer type received is determined by the message type sent and the DMCONFIG parameters. Fields on the TPQCTL structure are set to appropriate values, but features such as priority, correlation ID, reply queue, failure queue, and user-return code are not supported by the TEDG; they are either not set or they are set to default values. The appkey and cltid fields are set with the BEA Tuxedo user ID (the DOMAINID of the remote domain) of the client that sent the message.

How the TEDG Works with BEA TOP END Clients

The BEA TOP END client programmer uses the tp_rtq_put(3T) call to enqueue a message to a BEA Tuxedo /Q queue using the TEDG.

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

• The RTQ group, RTQ queue name, and RTQ target assigned to the BEA Tuxedo /Q queue. These parameters are defined by the administrator in the QSPACE entry in the DM_LOCAL_SERVICES section of the DMCONFIG file. These values are then specified in the queue_info parameter of the tp_rtq_put(3T) function.

• The product and function name for the BEA Tuxedo queue name for which the message is destined. These are assigned by the administrator in a QNAME entry in the DM_LOCAL_SERVICES section of the DMCONFIG file.

• 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 a name to the MSR target is optional). This 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 recipient BEA Tuxedo service. If the BEA Tuxedo server requires either CARRAY or X_OCTET, a raw message must be sent. By default a raw message is mapped to a CARRAY buffer.

  CARRAY and X_OCTET buffer 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 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 tp_rtq_put() returns a TP_RTQ_PARAMERR error.

To make a tp_rtq_put request, you must specify the product, function, MSR target (optional), and function qualifier (optional) associated with the desired BEA Tuxedo queue name in the service parameter.

How the TEDG Maps Client RTQ Requests

A client request may be transactional or non-transactional. The following table shows how BEA TOP END client RTQ flags and parameters are mapped. By mapping these flags and parameters, the TEDG performs a task that is normally done in the BEA TOP END system. The TP_RTQ_HELD and TP_RTQ_NON_TRANSACT_SCHED flags, the transaction key feature, and the tag_length, tag_text, input_format, and attach_info parameters should not be used on requests to the TEDG; they are not supported.

Table 14-3 BEA TOP END Client RTQ Flag and Parameter Mapping  

RTQ Flag or Parameter	Action
TP_RTQ_NON_TRANSACT_QUEUE	The TEDG preserves the fact that the RTQ request is excluded from the client transaction by the CSI library.
schedule_time (absolute, with respect to the server time zone in HH:MM format)	The value of the schedule_time parameter forms the hour and minute portion of the TPQCTL deq_time variable. If schedule_time has passed, a request is scheduled at schedule_time plus 1 day. The TPQTIME_ABS flag is set on. Note: The absolute time is mapped with respect to the TEDG time zone rather than the time on the /Q TMQUEUE(5) server. The TEDG time zone is used because tpenqueue(3c) does not offer an equivalent option for specifying time with respect to the time zone of the server.
schedule_time (relative in R:HH:MM format)	Mapped to the TPQCTL deq_time, this parameter converts the schedule_time from R:HH:MM format to the number of seconds to delay dequeuing. The TPQTIME_REL flag is set on.
schedule_time (with respect to the client time zone in L:HH:MM format)	Mapped to the TPQCTL deq_time. The TPQTIME_ABS flag is set on.
TP_RTQ_FML_BUF	The TEDG passes user data, as an FML buffer, in a tpenqueue(3c) call.

 

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 TMQUEUE server. Keep in mind that a single error status message may be used to report any one of many possible causes of the error being reported.

Because the TEDG does not advertise the RTQ queue based upon the actual availability of BEA Tuxedo queue space, a message may be routed to a BEA Tuxedo node where queue space actually is unavailable, resulting in an error status of TP_RTQ_UNAVAIL, while other routing decisions may result in successful requests. If an RTQ queue 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.

Table 14-4 Error Values Returned to a BEA TOP END RTQ Client  

BEA TOP END Error Status	Cause
TP_RTQ_UNAVAIL, TP_RTQ_EXT_MSR_FAILURE	The TEDG QSPACE entry lookup failed; the target was not found.
TP_RTQ_UNAVAIL, TP_RTQ_EXT_NOT_AVALIABLE	The TEDG QSPACE entry lookup failed; the RTQ group and queue names were not found. (Entries for services to which RDOM clients do not have access were ignored.)
TP_RTQ_UNAVAIL, TP_RTQ_EXT_NOT_AVAILABLE	TPENOENT was returned by the BEA Tuxedo system.
TP_RTQ_PARAMERR	The TEDG QNAME entry lookup failed.
TP_RTQ_PARAMERR	The input buffer type does not match the type specified in the INBUFTYPE parameter for the SERVICE entry.
TP_RTQ_PARAMERR	Unsupported RTQ flags TP_RTQ_HELD and TP_RTQ_NON_TRANSACT_SCHED were used.
TP_RTQ_PARAMERR	The BEA TOP END RTQ client specified a transaction key greater than zero; this is unsupported.
TP_RTQ_PARAMERR	The BEA Tuxedo TMQUEUE server returned TPEDIAGNOSTIC, QMEBADQUEUE because the queue name was not defined for the queue space. The queue name and queue space were determined by mapping the RTQ client request.
TP_RTQ_EOF	The BEA Tuxedo TMQUEUE server returned TPEDIAGNOSTIC, QMENOSPACE because there was no space on the queue for the message.
TP_RTQ_ERROR	All other errors.

 

See Also

• qmadmin(1) in the BEA Tuxedo Command Reference

• tpdequeue(3c) in the BEA Tuxedo ATMI C Function Reference

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

• tp_rtq_put(3T) in the BEA TOP END Programmer's Reference Manual