|
|
|
|
|
|
MessageQ/TUXEDO Bridge Functions
TMQUEUE_BMQ
Name
TMQUEUE_BMQ - MessageQ / TUXEDO Messaging Bridge Server
Synopsis
TMQUEUE_BMQ
SRVGRP="identifier"
SRVID="number" CLOPT=" [ -A ] [ servopts options ] --
[-b bmq_bus_id] [-g bmq_group_id] [-t timeout]
[-U user] [-G group] [-E errorqueuename]"
Description
The MessageQ / TUXEDO messaging bridge manager is a System/T-supplied server that enqueues and dequeues messages from BEA MessageQ queues on behalf of programs calling tpenqueue(3c) and tpdequeue(3c), respectively. The server also performs the required data and semantic transformations between MessageQ and TUXEDO. The application administrator enables message enqueuing and dequeuing for the application by specifying this server as an application server in the *SERVERS section of the BEA TUXEDO ubbconfig file.
Messages originating from BEA TUXEDO have the MessageQ class of MSG_CLAS_TUXEDO. Reply messages from BEA TUXEDO have either the MessageQ class of MSG_CLAS_TUXEDO_TPSUCCESS or MSG_CLAS_TUXEDO_TPFAIL.
The location, server group, server identifier and other generic server related parameters are associated with the server using the already defined configuration file mechanisms for servers. The following is a list of additional command line options that are available for customization:
The TMQUEUE_BMQ server must be located on the same physical machine as the BEA MessageQ group from which it dequeues messages. The machine must be configured to run servers on behalf of a BEA TUXEDO application. TMQUEUE_BMQ may enqueue messages to any queue on any machine in the MessageQ group as long as a path exists between the group to which TMQUEUE_BMQ is attached and the target group.
A TMQUEUE_BMQ server is booted as part of a TUXEDO application to facilitate application access to its associated MessageQ bus and group. Any configuration condition that prevents the TMQUEUE_BMQ server from initiating its services will cause TMQUEUE_BMQ to fail at boot time with an error posted to the BEA TUXEDO user log (ULOG) file.
EXAMPLES
*GROUPS
TMQUEUE_BMQGRPHQMGR GRPNO=1
TMQUEUE_BMQGRPHQPLEBE GRPNO=2
TMQUEUE_BMQGRPREMOTENA GRPNO=3
TMQUEUE_BMQGRPREMOTEEUROPE GRPNO=4
*SERVERS
TMQUEUE_BMQ SRVGRP="TMQUEUE_BMQGRPHQMGR" SRVID=1000 RESTART=Y
GRACE=0 CLOPT="-s Payroll:TMQUEUE_BMQ -s
Promote:TMQUEUE_BMQ -- -b 5 -g 7"
TMQUEUE_BMQ SRVGRP="TMQUEUE_BMQGRPHQPLEBE" SRVID=1000 RESTART=Y
GRACE=0 CLOPT="-s Payroll:TMQUEUE_BMQ -s
Promote:TMQUEUE_BMQ -- -b 5 -g 10"
TMQUEUE_BMQ SRVGRP="TMQUEUE_BMQGRPREMOTENA" SRVID=2002 RESTART=Y
GRACE=0 CLOPT="-s Sales:TMQUEUE_BMQ -- -b 5 -g 42"
TMQUEUE_BMQ SRVGRP="TMQUEUE_BMQGRPREMOTEEUROPE" SRVID=2002
RESTART=Y GRACE=0 CLOPT="-s Sales:TMQUEUE_BMQ -- -b 12 -g 53"
*SERVICES
Payroll ROUTING="SALARYROUTE"
Payroll ROUTING="HAIRCOLORROUTE"
*ROUTING
SALARYROUTE FIELD=Salary BUFTYPE="FML32"
RANGES="MIN - 50000:TMQUEUE_BMQGRPPLEBE,50001
-MAX:TMQUEUE_BMQGRPHQMGR"
HAIRCOLORROUTE FIELD=Hair BUFTYPE="FML32"
RANGES="`Gray':TMQUEUE_BMQGRPHQMGR,*:TMQUEUE_BMQGRPPLEBE"
SEE ALSO
ubbconfig(5), servopts(5), buildserver(1), tpenqueue(3c), tpdequeue(3c), TMQFORWARD_BMQ(5), BEA TUXEDO Administrator's Guide, BEA TUXEDO Programmer's Guide, BEA MessageQ Introduction to Message Queueing, BEA MessageQ Programmer's Guide
TMQFORWARD_BMQ
Name
TMQFORWARD_BMQ - MessageQ / TUXEDO Forwarding Agent Server
Synopsis
TMQFORWARD_BMQ
SRVGRP="identifier"
SRVID="number" REPLYQ=N CLOPT=" [ -A ] [ servopts options ] --
-q queuename[,queuename] [-b bmq_bus_id] [-g bmq_group_id]
[-t timeout] [-i idletime] [-d] [-f delay][-U uid] [-G gid]
[-E errorqueuename] [-R retries]"
Description
The MessageQ / TUXEDO forwarding agent is a BEA TUXEDO managed server that forwards messages to BEA TUXEDO services from BEA MessageQ queues. The messages are placed on a BEA MessageQ queue using either pams_put_msg or tpenqueue. The server also performs the required data and semantic transformations between MessageQ and TUXEDO. The application administrator enables message processing for the application by specifying this server as an application server in the *SERVERS section of the BEA TUXEDO ubbconfig file.
Messages originating from BEA TUXEDO have the MessageQ class of MSG_CLAS_TUXEDO. Reply messages from BEA TUXEDO have either the MessageQ class of MSG_CLAS_TUXEDO_TPSUCCESS or MSG_CLAS_TUXEDO_TPFAIL.
The location, server group, server identifier and other generic server related parameters are associated with the server using the already defined configuration file mechanisms for servers. Note that REPLYQ=N must be specified, as shown in the synopsis. The following is a list of additional command line options that are available for customization:
The TMQFORWARD_BMQ server must be located on the same physical machine as the BEA MessageQ group from which it dequeues messages. The machine must be configured to run servers on behalf of a BEA TUXEDO application.
A TMQFORWARD_BMQ server is booted as part of a TUXEDO application to facilitate application access to its associated MessageQ bus and group.Any configuration condition that prevents the TMQFORWARD_BMQ server from initiating its services will cause TMQFORWARD_BMQ to fail at boot time with an error posted to the BEA TUXEDO user log (ULOG) file.
TMQFORWARD_BMQ forwards messages to a server providing a service whose name matches the queue name from which the message is read. The message priority is the priority specified when the message was enqueued. If the message is associated with a reply queue, then any reply from the service will be enqueued to the specified reply queue, along with the returned tpurcode. If the reply queue does not exist, the reply will be dropped.
EXAMPLES
*GROUPS
TMQUEUE_BMQGRPHQMGR GRPNO=1
*SERVERS
TMQFORWARD_BMQ SRVGRP="TMQUEUE_BMQGRP" SRVID=1001 RESTART=Y GRACE=0
CLOPT=" -- -qservice1,service2" REPLYQ=N
TMQUEUE_BMQ SRVGRP="TMQUEUE_BMQGRP" SRVID=1000 RESTART=Y GRACE=0
CLOPT="-s Payroll:TMQUEUE_BMQ -- -b 5 -g 7"
SEE ALSO
ubbconfig(5), servopts(5), buildserver(1), tpenqueue(3c), tpdequeue(3c), TMQUEUE_BMQ(5), BEA TUXEDO Administrator's Guide, BEA TUXEDO Programmer's Guide, BEA MessageQ Introduction to Message Queueing, BEA MessageQ Programmer's Guide
tpdequeue (3)
Name
tpdequeue - routine to dequeue a message from a queue
Synopsis
#include <atmi.h>
int tpdequeue(char *qspace, char *qname, TPQCTL *ctl, char **data,
long *len,long flags)
Description
tpdequeue() dequeues a message for processing from the queue named by qname in the qspace queue space.
By default, the message at the top of the queue is dequeued. The default order of messages on the queue is defined when the queue is created. The application can request a particular message for dequeuing by specifying its message identifier using the ctl parameter. ctl flags can also be used to indicate that the application wants to wait for a message, in the case where a message is not currently available. See the section below describing this parameter.
data is the address of a pointer to the buffer into which a message is read, and len points to the length of that message. *data must point to a buffer originally allocated by tpalloc(3c). To determine whether a message buffer changed in size, compare its (total) size before tpdequeue() was issued with *len. Note that *data may change for reasons other than the buffer's size increased. If *len is 0 upon return, then the message dequeued has no data portion and neither *data nor the buffer it points to were modified. It is an error for *data or len to be NULL.
The TPNOTRAN flag must be set when exchanging messages between BEA MessageQ and BEA TUXEDO, so messages are not dequeued in transaction mode. The message is dequeued in a separate transaction. If a communication error or a timeout occurs (either transaction or blocking timeout), the application will not know whether or not the message was successfully dequeued and the message may be lost.
Following is a list of valid flags.
If tpdequeue() returns successfully, the application can retrieve additional information about the message using ctl data structure. The information may include the message identifier for the dequeued message, a correlation identifier that should accompany any reply or failure message so that the originator can correlate the message with the original request, the name of a reply queue if a reply is desired, and the name of the failure queue on which the application can queue information regarding failure to dequeue the message. This is described below.
Control Parameter
The TPQCTL structure is used by the application program to pass and retrieve parameters associated with dequeuing the message. The flags element of TPQCTL is used to indicate what other elements in the structure are valid.
On input to tpdequeue(), the following elements may be set in the TPQCTL structure:
long flags; /* indicates which of the values
* are set */
char msgid[32]; /* id of message to dequeue */
char corrid[32]; /* correlation identifier of
* message to dequeue */
Following is a list of valid bits for the flags parameter controlling input information for tpdequeue().
On output from tpdequeue(), the following elements may be set in the TPQCTL structure:
long flags; /* indicates which of the values
* should be set */
long priority; /* enqueue priority */
char msgid[32]; /* id of message dequeued */
char corrid[32]; /* correlation identifier used to
* identify the message */
char replyqueue[16]; /* queue name for reply */
char failurequeue[16]; /* queue name for failure */
long diagnostic; /* reason for failure */
long appkey; /* application authentication client
* key */
long urcode; /* user-return code */
CLIENTID cltid; /* client identifier for originating
* client */
Following is a list of valid bits for the flags parameter controlling output information from tpdequeue(). If the flag bit is turned on when tpdequeue() is called, then the associated element in the structure is populated if available and the bit remains set. If the value is not available, the flag bit will be turned off after tpdequeue() completes.
If the call to tpdequeue() failed and tperrno is set to TPEDIAGNOSTIC, a value indicating the reason for failure is returned in ctl->diagnostic. The possible values are defined below in the DIAGNOSTICS section.
Additionally on output, ctl->appkey is set to application authentication key, ctl->cltid is set to the identifier for the client originating the request, and ctl->urcode is set to the user-return code value that was set when the message was enqueued.
If the ctl parameter is NULL, the input flags are considered to be TPNOFLAGS and no output information is made available to the application program.
Return Values
This function returns -1 on error and sets tperrno to indicate the error condition.
Errors
Under the following conditions, tpdequeue() fails and sets tperrno to one of the following (unless otherwise noted, failure does not affect the caller's transaction, if one exists):
Diagnostic
The following diagnostic values are returned during the dequeuing of a message.
See Also
tpalloc(3c), tpenqueue(3c), TMQUEUE_BMQ(5)
tpenqueue (3)
Name
tpenqueue - routine to enqueue a message
Synopsis
#include <atmi.h>
int tpenqueue(char *qspace, char *qname,
TPQCTL *ctl, char *data, long len, long flags)
Description
tpenqueue() stores a message on the queue named by qname in the qspace queue space. A queue space is a collection of queues, one of which must be qname.
When the message is intended for a System/T server, the qname matches the name of a service provided by a server. The system provided server, TMQFORWARD_BMQ(5), provides a default mechanism for dequeuing messages from the queue and forwarding them to servers that provide a service matching the queue name. If the originator expected a reply, then the reply to the forwarded service request is stored on the originator's (stable) queue. The originator will dequeue the reply message at a subsequent time. Queues can also be used for a reliable message transfer mechanism between any pair of System/T processes (clients and/or servers). In this case, the queue name does not match a service name but some agreed upon title for transferring the message.
If data is non-NULL, it must point to a buffer previously allocated by tpalloc(3c) and len should specify the amount of data in the buffer that should be queued. Note that if data points to a buffer of a type that does not require a length to be specified (for example, an FML fielded buffer), then len is ignored. If data is NULL, len is ignored and a message is queued with no data portion.
The message is queued at the priority defined for qspace unless overridden by a previous call to tpsprio(3c).
The TPNOTRAN flag must be set when exchanging messages between BEA MessageQ and BEA TUXEDO, so messages are not enqueued in transaction mode. The message is not queued in transaction mode if either the caller is not in transaction mode, or the TPNOTRAN flag is set. In this case, the queued message is stored on the queue in a separate transaction. Once tpenqueue() returns successfully, the submitted message is guaranteed to be available. If a communication error or a timeout occurs (either transaction or blocking timeout), the application will not know whether or not the message was successfully stored on the queue.
The order in which messages are placed on the queue is controlled by the application via ctl data structure as described below; the default queue ordering is set when the queue is created.
Following is a list of valid flags.
Additional information about queuing the message can be specified via ctl data structure. This information includes values to override the default queue ordering placing the message at the top of the queue or before an enqueued message; an absolute or relative time after which a queued message is made available; a correlation identifier that aids in correlating a reply or failure message with the queued message; the name of a queue to which a reply should be enqueued; and the name of a queue to which any failure message should be enqueued.
Control Parameter
The TPQCTL structure is used by the application program to pass and retrieve parameters associated with enqueuing the message. The flags element of TPQCTL is used to indicate what other elements in the structure are valid.
On input to tpenqueue(), the following elements may be set in the TPQCTL structure:
long flags; /* indicates which of the values
* are set */
long deq_time; /* absolute/relative for dequeuing */
long priority; /* enqueue priority */
long urcode; /* user-return code */
char msgid[32]; /* id of message before which to queue
* request */
char corrid[32]; /* correlation identifier used to
* identify the msg */
char replyqueue[16]; /* queue name for reply message */
char failurequeue[16]; /* queue name for failure message */
The following is a list of valid bits for the flags parameter controlling input information for tpenqueue().
Additionally, the urcode element of TPQCTL can be set with a user-return code. This value will be returned to the application that dequeues the message.
On output from tpenqueue(), the following elements may be set in the TPQCTL structure:
long flags; /* indicates which of the values
* are set */
char msgid[32]; /* id of enqueued message */
long diagnostic; /* indicates reason for failure */
Following is a list of valid bits for the flags parameter controlling output information from tpenqueue(). If the flag bit is turned on when tpenqueue() is called, then the associated element in the structure is populated if available and the bit remains set. If the value is not available, the flag bit will be turned off after tpenqueue() completes.
If set and the call to tpenqueue() was successful, the message identifier will be stored in ctl->msgid.
If the call to tpenqueue() failed and tperrno is set to TPEDIAGNOSTIC, a value indicating the reason for failure is returned in ctl->diagnostic. The possible values are defined below in the DIAGNOSTICS section.
If this parameter is NULL, the input flags are considered to be TPNOFLAGS and no output information is made available to the application program.
Return Values
This function returns -1 on error and sets tperrno to indicate the error condition. Otherwise, the message has been successfully queued when tpenqueue() returns.
Errors
Under the following conditions, tpenqueue() fails and sets tperrno to the following values (unless otherwise noted, failure does not affect the caller's transaction, if one exists):
Diagnostic
The following diagnostic values are returned during the enqueuing of a message.
See Also
gp_mktime(3c), tpacall(3c), tpalloc(3c), tpdequeue(3c), tpinit(3c), tpsprio(3c)TMQFORWARD_BMQ(5), TMQUEUE_BMQ(5),
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|