tpdequeue() takes a message for processing from the queue named by
qname in the
qspace queue space.
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(). If a message is larger than the buffer passed to
tpdequeue, the buffer is increased in size to accommodate the message. To determine whether a message buffer changed in size, compare its (total) size before
tpdequeue() was issued with *
len. If *
len is larger, then the buffer has grown; otherwise, the buffer has not changed size. 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 message is dequeued in transaction mode if the caller is in transaction mode and the TPNOTRAN flag is not set. This has the effect that if
tpdequeue() returns successfully and the caller’s transaction is committed successfully, then the message is removed from the queue. If the caller’s transaction is rolled back either explicitly or as the result of a transaction timeout or some communication error, then the message will be left on the queue (that is, the removal of the message from the queue is also rolled back). It is not possible to enqueue and dequeue the same message within the same transaction.
When TPNOBLOCK is not set and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). This blocking condition does not include blocking on the queue itself if the
TPQWAIT option in
flags (of the
TPQCTL structure) is specified.
When this flag is set, the type of the buffer pointed to by *data is not allowed to change. By default, if a buffer is received that differs in type from the buffer pointed to by *
data, then *
data’s buffer type changes to the received buffer’s type so long as the receiver recognizes the incoming buffer type. That is, the type and subtype of the dequeued message must match the type and subtype of the buffer pointed to by *
data.
If tpdequeue() returns successfully, the application can retrieve additional information about the message using the
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 quality of service the message was delivered with, the quality of service any replies to the message should be delivered with; 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. These are described below.
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:
Note that each tpdequeue() request specifying the
TPQWAIT control parameter requires that a queue manager (
TMQUEUE) action object be available if a message satisfying the condition is not immediately available. If an action object is not available, the
tpdequeue() request fails. The number of available queue manager actions are specified when a queue space is created or modified. When a waiting dequeue request completes, the associated action object associated is made available for another request.
When a thread is non-destructively dequeuing a message using TPQPEEK, the message may not be seen by other non-blocking dequeuers for the brief time the system is processing the non-destructive dequeue request. This includes dequeuers using specific selection criteria (such as message identifier and correlation identifier) that are looking for the message currently being non-destructively dequeued.
On output from tpdequeue(), the following elements may be set in the
TPQCTL structure:
The following is a list of valid bits for the flags parameter controlling output information from
tpdequeue(). For any of these bits, if the flag bit is turned on when
tpdequeue() is called, the associated element in the structure is populated with the value provided when the message was queued, and the bit remains set. If a value is not available or the bit is not set when
tpdequeue() is called,
tpdequeue() completes with the flag turned off.
If this flag is set, the call to tpdequeue() is successful, and the message was queued with an explicit priority, then the priority is stored in
ctl−>priority. The priority is in the range 1 to 100, inclusive, and the higher the number, the higher the priority (that is, a message with a higher number is dequeued before a message with a lower number). For queues not ordered by priority, the value is informational.
If this flag is set and the call to tpdequeue() is successful, the message identifier is stored in
ctl−>msgid. The entire 32 bytes of the message identifier value are significant.
If this flag is set, the call to tpdequeue() is successful, and the message was queued with a correlation identifier, then the correlation identifier is stored in
ctl−>corrid. The entire 32 bytes of the correlation identifier value are significant. Any Oracle Tuxedo ATMI /Q provided reply to a message has the correlation identifier of the original request message.
If this flag is set, the call to tpdequeue() is successful, and the message was queued with a delivery quality of service, then the flag—
TPQQOSDEFAULTPERSIST,
TPQQOSPERSISTENT, or
TPQQOSNONPERSISTENT—is stored in
ctl‑>delivery_qos. If no delivery quality of service was explicitly specified when the message was queued, the default delivery policy of the target queue dictates the delivery quality of service for the message.
If this flag is set, the call to tpdequeue() is successful, and the message was queued with a reply quality of service, then the flag—
TPQQOSDEFAULTPERSIST,
TPQQOSPERSISTENT, or
TPQQOSNONPERSISTENT—is stored in
ctl‑>reply_qos. If no reply quality of service was explicitly specified when the message was queued, the default delivery policy of the
ctl‑>replyqueue queue dictates the delivery quality of service for any reply.
If this flag is set, the call to tpdequeue() is successful, and the message was queued with a reply queue, then the name of the reply queue is stored in
ctl−>replyqueue. Any reply to the message should go to the named reply queue within the same queue space as the request message.
If this flag is set, the call to tpdequeue() is successful, and the message was queued with a failure queue, then the name of the failure queue is stored in
ctl−>failurequeue. Any failure message should go to the named failure queue within the same queue space as the request message.
The following remaining bits for the flags parameter are cleared (set to zero) when
tpdequeue() is called:
TPQTOP,
TPQBEFOREMSGID,
TPQTIME_ABS,
TPQTIME_REL,
TPQEXPTIME_ABS,
TPQEXPTIME_REL, and
TPQEXPTIME_NONE. These bits are valid bits for the
flags parameter controlling input information for
tpenqueue().
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, if the call to tpdequeue() is successful,
ctl−>appkey is set to the 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.
Upon failure, tpdequeue() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpdequeue() sets
tperrno to one of the following values. (Unless otherwise noted, failure does not affect the caller’s transaction, if one exists.)
Cannot access the qspace because it is not available (that is, the associated
TuxMsgQ server is not available), or cannot start a global transaction due to the lack of entries in the Global Transaction Table (GTT).
If a transaction timeout has occurred, then, with one exception, any attempts to perform further conversational work, send new requests, or receive outstanding replies will fail with TPETIME until the transaction has been aborted. The exception is a request that does not block, expects no reply, and is not sent on behalf of the caller’s transaction (that is,
tpacall() with
TPNOTRAN,
TPNOBLOCK, and
TPNOREPLY set).
tpdequeue() was called improperly. There is no effect on the queue or the transaction.
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 an Oracle Tuxedo ATMI system server, the qname matches the name of a service provided by the server. The system provided server,
TMQFORWARDPLUS, 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 expects a reply, then the reply to the forwarded service request is stored on the originator’s queue, unless otherwise specified. 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 Oracle Tuxedo ATMI system processes (clients and/or servers). In this case, the queue name does not match a service name but some agreed upon name for transferring the message.
If data is non-NULL, it must point to a buffer previously allocated by
tpalloc() 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.
If the caller is within a transaction and the TPNOTRAN flag is not set, the message is queued in transaction mode. This has the effect that if
tpenqueue() returns successfully and the caller’s transaction is committed successfully, then the message is guaranteed to be available subsequent to the transaction completing. If the caller’s transaction is rolled back either explicitly or as the result of a transaction timeout or some communication error, then the message will be removed from the queue (that is, the placing of the message on the queue is also rolled back). It is not possible to enqueue then dequeue the same message within the same transaction.
When TPNOBLOCK is not set and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). If a timeout occurs, the call fails and
tperrno is set to
TPETIME.
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; an absolute or relative time when a message expires and is removed from the queue; the quality of service for delivering the message; the quality of service that any replies to the message should use; 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.
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:
If this flag is set, the message is made available after the time specified by ctl−>deq_time. The
deq_time is an absolute time value as generated by
time(2),
mktime(3), or
gp_mktime(3c) (the number of seconds since 00:00:00 Universal Coordinated Time—UTC, January 1, 1970).
TPQTIME_ABS and
TPQTIME_REL are mutually exclusive flags. The absolute time is determined by the clock on the machine where the queue manager process resides.
If this flag is set, the correlation identifier value specified in ctl−>corrid is available when a message is dequeued with
tpdequeue(). This identifier accompanies any reply or failure message that is queued so that an application can correlate a reply with a particular request. Note that the entire 32 bytes of the correlation identifier value are significant, so the value specified in
ctl−>corrid must be completely initialized (for example, padded with NULL characters).
If this flag is set, a reply queue named in ctl−>replyqueue is associated with the queued message. Any reply to the message will be queued to the named queue within the same queue space as the request message. This string must be NULL terminated (maximum 15 characters in length).
If this flag is set, a failure queue named in the ctl−>failurequeue is associated with the queued message. If (1) the enqueued message is processed by
TMQFORWARD(), (2)
TMQFORWARD was started with the
-d option, and (3) the service fails and returns a non-NULL reply, a failure message consisting of the reply and its associated
tpurcode is enqueued to the named queue within the same queue space as the original request message. This string must be NULL-terminated (maximum 15 characters in length).
If the TPQDELIVERYQOS flag is set, the flags specified by
ctl‑>delivery_qos control the quality of service for delivery of the message. In this case, one of three mutually exclusive flags—
TPQQOSDEFAULTPERSIST,
TPQQOSPERSISTENT, or
TPQQOSNONPERSISTENT—must be set in
ctl‑>delivery_qos. If
TPQDELIVERYQOS is not set, the default delivery policy of the target queue dictates the delivery quality of service for the message.
If the TPQREPLYQOS flag is set, the flags specified by
ctl‑>reply_qos control the quality of service for any reply to the message. In this case, one of three mutually exclusive flags—
TPQQOSDEFAULTPERSIST,
TPQQOSPERSISTENT, or
TPQQOSNONPERSISTENT—must be set in
ctl‑>reply_qos. The
TPQREPLYQOS flag is used when a reply is returned from messages processed by
TMQFORWARD. Applications not using
TMQFORWARD to invoke services may use the
TPQREPLYQOS flag as a hint for their own reply mechanism.
If TPQREPLYQOS is not set, the default delivery policy of the
ctl‑>replyqueue queue dictates the delivery quality of service for any reply. Note that the default delivery policy is determined when the reply to a message is enqueued. That is, if the default delivery policy of the reply queue is modified between the time that the original message is enqueued and the reply to the message is enqueued, the policy used is the one in effect when the reply is finally enqueued.
TPQEXPTIME_ABS,
TPQEXPTIME_REL, and
TPQEXPTIME_NONE are mutually exclusive flags. If none of these flags is set, the default expiration time associated with the target queue is applied to the message.
TPQEXPTIME_ABS,
TPQEXPTIME_REL, and
TPQEXPTIME_NONE are mutually exclusive flags. If none of these flags is set, the default expiration time associated with the target queue is applied to the message.
TPQEXPTIME_ABS,
TPQEXPTIME_REL, and
TPQEXPTIME_NONE are mutually exclusive flags. If none of these flags is set, the default expiration time associated with the target queue is applied to the message.
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:
The following is a valid bit for the flags parameter controlling output information from
tpenqueue(). If this flag is turned on when
tpenqueue() is called, the /Q server
TMQUEUE(5) populates the associated element in the structure with a message identifier. If this flag is turned off when
tpenqueue() is called,
TMQUEUE() does
not populate the associated element in the structure with a message identifier.
If this flag is set and the call to tpenqueue() is successful, the message identifier is stored in
ctl−>msgid. The entire 32 bytes of the message identifier value are significant, so the value stored in
ctl−>msgid is completely initialized (for example, padded with NULL characters). The actual padding character used for initialization varies between releases of the Oracle Tuxedo ATMI /Q component.
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.
Upon failure, tpenqueue() returns -1 and sets
tperrno to indicate the error condition. Otherwise, the message has been successfully queued when
tpenqueue() returns.
Upon failure, tpenqueue() sets
tperrno to one of the following values. (Unless otherwise noted, failure does not affect the caller’s transaction, if one exists.)
Cannot access the qspace because it is not available (that is, the associated
TMQUEUE(5) server is not available), or cannot start a global transaction due to the lack of entries in the Global Transaction Table (GTT).
tpqattach()—Connects an application program to the OTMQ message queuing space by attaching it to a message queue.
Table 1‑2 lists
tpqattach() supported arguments:
long flags; /* indicates which of the values are set */
long deq_time; /* absolute/relative time for dequeuing */
long priority; /* enqueue priority */
long diagnostic; /* indicates reason for failure */
char msgid[TMMSGIDLEN]; /* id of message before which to queue */
char corrid[TMCORRIDLEN];/* correlation id used to identify message */
char replyqueue[TMQNAMELEN+1]; /* queue name for reply message */
char failurequeue[TMQNAMELEN+1];/* queue name for failure message */
CLIENTID cltid; /* client identifier for originating client */
long urcode; /* application user-return code */
long appkey; /* application authentication client key */
long delivery_qos; /* delivery quality of service */
long reply_qos; /* reply message quality of service */
long exp_time; /* expiration time */
/* new members for TMQPlus */
long block; /* specify block mode: WF, AK, NN */
long DIP; /* specify the delivery interesting point:MEM, SAF, DQF,
DEQ, ACK,
CONF
*/
long uma; /* undelivered message action */
long msg_class; /* message class */
long msg_type; /* message type */
PSB status_block; /* message delivery control point and UMA status block */
long redeliver_count; /* the max count which the message can be redelivered */
long seq_number[2]; /* message seq number, which is decided in client side to
decrease the TMQ load */
long timeout; /* timeout value for block enq/deq operation */
char src_qspace[TMQSNAMELEN+1]; /* the source QSpace name. */
char src_qname[TMQNAMELEN+1]; /* the source queue name. */
char tgt_qspace[TMQSNAMELEN+1]; /* the source QSpace name. */
char tgt_qname[TMQNAMELEN+1]; /* the source queue name. */
char orig_src_qspace[TMQSNAMELEN+1];/* the original source QSpace name. */
char orig_src_qname[TMQNAMELEN+1]; /* the original source queue name. */
char orig_tgt_qspace[TMQSNAMELEN+1];/* the original target QSpace name. */
char orig_tgt_qname[TMQNAMELEN+1]; /* the original target queue name. */
char hops; /* net hops */
long opcode;
long filter_idx;
long user_tag;
long geta_idx; /* index of pending pams_get_msga requests */
long endian;
long receipt_msg_type; /*used for uma message*/
When TPNOBLOCK is not set and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). If a timeout occurs, the call fails and
tperrno is set to
TPETIME.
tpqdetach()—Detaches a selected message queue or all of the application message queues from the message queuing qspace.
Table 1‑3 lists
tpqdetach() supported arguments.
Supplies an array of int values used to control how the queue is detached. The predefined constants for this argument are:
Upon failure, tpqdetach() returns -1 and sets
tperrno to indicate the error condition. Otherwise, the queue has been successfully detached when
tpqdetach() returns.
tpqbind() —Dynamically associates a queue name to a queue reference at run-time.
Table 1‑4 lists the
tpqbind() supported arguments:
Note: pGroup and
pQueue values specified to this argument controls whether the queue name is bound or unbound:
If the queue pGroup and
pQueue are specified, this function binds it to a
pName. "If 0 is specified, this function unbinds the
pName from its queue name. The calling application must be bound to pName to set it back to zero.”
The name_space_list argument also controls the cache access as follows:
For TP APIs, scope and namespace_list arguments, If scope is NULL,
namespace_list must not NULL too, and if scope has a data value,
namespace_list will invalidate.
Upon failure, tpqbind() returns -1 and sets
tperrno to indicate the error condition. Otherwise, the queue alias has been successfully binded when
tpqbind() returns.
tpqbind() was called improperly. For example, invoke
tpqbind without invoke
tpqattach() first.
tpqlocate() —Locates the queue name for the specified queue name or queue alias.
Table 1‑5 lists
tpqlocate() supported arguments:
pGroup and
pQueue values specified to this argument controls whether the queue name is bound or unbound:
|
•
|
If the queue pGroup and pQueue are specified, this function binds it to a pName.
|
The name_space_list argument also controls the cache access as follows:
|
•
|
"OTMQ_WF_RESP (default setting)-The application issues the tpqlocate request and waits for the queue name to be returned.
|
|
•
|
"OTMQ_AK_RESP-The application issues the tpqlocate name and continues processing. When the search is completed, the queue name is returned to the application's primary queue in a LOCATE_Q_REP message. The response message can be redirected to an alternate queue name using the resp_q argument, The details of LOCATE_Q_REP message as next.
|
The name_space_list argument also controls the cache access as follows:
To lookup a global queue reference, specify OTMQ_TBL_BUS (or
OTMQ _TBL_BUS_LOW or
OTMQ _TBL_BUS_MEDIUM),
OTMQ _TBL_GRP and
OTMQ _TBL_PROC. This causes the process cache to be checked. Then, the group cache is checked before looking into the global name space.
For TP APIs scope and
namespace_list arguments, if scope is NULL,
namespace_list must not NULL too, and if scope has a data value,
namespace_list will invalidate.
Upon failure, tpqlocate() returns -1 and sets
tperrno to indicate the error condition. Otherwise, the queue has been successfully located when
tpqlocate () returns.
tpenqplus() —Locates the queue name for the specified queue name or queue alias.
If the caller is within a transaction and the TPNOTRAN flag is not set, the message is queued in transaction mode. This has the effect that if
tpenqplus() returns successfully and the caller transaction is committed successfully, then the message is guaranteed to be available subsequent to the transaction completing. If the caller transaction is rolled back either explicitly or as the result of a transaction timeout or some communication error, then the message will be removed from the queue (that is, the placing of the message on the queue is also rolled back). It is not possible to enqueue then dequeue the same message within the same transaction.
To use tpenqplus(), you must first invoke
tpqattach().
Table 1‑6 lists
tpenqplus() supported arguments:
On input to tpenqplus(), the following elements may be set in the TPQCTL structure:
OTMQ_DEL_sn-where sn is one of the following sender notification constants:
If you set OTMQ_DEL_WF and
OTMQ_DIP_ACK, the ACK message will be read in
tpenqplus, client do not need to call another API to read the ACK message.
Supplies the maximum amount of time the tpenqplus function waits for a message to arrive before returning control to the application. If the timeout occurs before a message arrives, the status code
OTMQ__TIMEOUT is returned. Specifying 0 as the timeout value sets the timeout to the default value of 30 seconds.
Supplies a q_name to use as the alternate queue for receiving response messages from the receiver program. The sender program must be attached to the queue specified in the
replyqueue argument to receive the response messages. To use
replyqueue, flags must address
TPQREPLYQ.
If the value of seq_number[0] or
seq_number[1] is not specified as "
(long)0", OTMQ will not generate unique number for this message.
If data is non-NULL, it must point to a buffer previously allocated by tpalloc() 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. Consult
tpalloc() for more details.
When TPNOBLOCK is not set and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). If a timeout occurs, the call fails and
tperrno is set to TPETIME.
Upon failure, tpenqplus() returns -1 and sets
tperrno to indicate the error condition. Otherwise, the message has been successfully enque when
tpenqplus() returns.
tpdeqplus()—Retrieves the next available message from a selected queue and moves it to the location specified in the data argument.
To use tpdepplus(), you must first invoke
tpqattach().
Table 1‑7 lists
tpdepplus() supported arguments:
The message is dequeued in transaction mode if the caller is in transaction mode and the TPNOTRAN flag is not set. This has the effect that if
tpdeqplus() returns successfully and the caller transaction is committed successfully, then the message is removed from the queue. If the caller's transaction is rolled back either explicitly or as the result of a transaction timeout or some communication error, then the message will be left on the queue (that is, the removal of the message from the queue is also rolled back). It is not possible to enqueue and dequeue the same message within the same transaction.
If set OTMQ_DIP_ACK and
OTMQ_DEL_WF, the ACK message will be read in
tpenqplus,_client do not need to call another API to read the ACK message.
Supplies the maximum amount of time the tpenqplus function waits for a message to arrive before returning control to the application. If the timeout occurs before a message arrives, the status code
OTMQ_TIMEOUT is returned. Specifying 0 as the timeout value sets the timeout to the default value of 30 seconds.
Supplies a q_name to use as the alternate queue for receiving response messages from the receiver program. The sender program must be attached to the queue specified in the
replyqueue argument to receive the response messages.The sender program cannot assign a response queue outside its qspace.
If data is non-NULL, it must point to a buffer previously allocated by tpalloc() 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. Consult
tpalloc() for more details.
When TPNOBLOCK is not set and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). If a timeout occurs, the call fails and
tperrno is set to
TPETIME.
Upon failure, tpdeqplus() returns -1 and sets tperrno to indicate the error condition. Otherwise, the queue has been successfully dequeued when
tpdeqplus() returns.
Upon failure, tpdeqplus() sets
tperrno to one of the following values. (Unless otherwise noted, failure does not affect the caller's transaction, if one exists.)
tpdeqplus() was called improperly. There is no effect on the queue or the transaction.
The caller uses tpqpublish() to publish a topic data. The topic is named by topic and data, if not NULL, points to the data. The topic and its data are dispatched by the Oracle Tuxedo ATMI EventBroker to all subscribers whose subscriptions successfully evaluate against topic and whose optional filter rules successfully evaluate against data.
Table 1‑9 lists
tpqpublish() supported arguments:
topicname is a NULL-terminated string of at most 31 characters and start with "
TMQ:<QNOT>:qspace name", such as"
TMQ:QNOT:QSPACE:usertopic". The first
topicname character cannot be a dot (".") as this character is reserved as the starting character for all events defined by the Oracle Tuxedo ATMI system itself. The topicname "
TMQ:QNOT: qspace name" is the suffix for all user topic and can not be used as user topic name alone."QNOT" is not an necessary string. But if topicname cotain "
QNOT", means the message which will be published is an
AVAIL/UNAVALI message.
If data is non-NULL, it must point to a buffer previously allocated by tpalloc() and len should specify the amount of data in the buffer that should be posted with the event. 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 the event is posted with no data.
If the publisher is within a transaction and the TPNOTRAN flag is not set, the publish topic goes to the EventBroker in transaction mode such that it dispatches the event as part of the publisher transaction. The broker dispatches transactional event notifications only to those service routine and stable-storage queue subscriptions that used the
TPEVTRAN bit setting in the ctl-? flags parameter passed to
tpqsubscribe(). Client notifications, and those service routine and stable-storage queue subscriptions that did not use the
TPEVTRAN bit setting in the
ctl-? flags parameter passed to
tpqsubscribe(), are also dispatched by the EventBroker but not as part of the publiser process transaction.
If the publisher is outside a transaction, tpqpublish() is a one-way publish topic with no acknowledgement when the service associated with the event fails. This occurs even when
TPEVTRAN is set for that event (using the ctl.flags parameter passed to
tpqsubscribe(). If the publisher is in a transaction, then
tpqpublish () returns
TPESVCFAIL when the associated service fails in the event.
Informs tpqpublish() not to wait for the EventBroker to process all subscriptions for topic before returning. When
TPNOREPLY is set,
tpurcode() is set to zero regardless of whether
tpqpublish() returns successfully or not. When the caller is in transaction mode, this setting cannot be used unless
TPNOTRAN is also set.
Upon failure, tpqpublish() returns -1 and sets
tperrno to indicate the error condition. Otherwise, the message has been successfully broadcasted when
tpqpublish() returns.
The caller uses tpqsubscribe() to subscribe to a topic. Topic is a NULL-terminated string of at most 255 characters containing a regular expression. If present, filter is a string containing a Boolean filter rule that must be evaluated successfully before the TMQEVT posts the topic. Upon receiving an topic to be published, the TMQEVT applies the filter rule, if one exists, to the publish topic string. If the data passes the filter rule, the TMQEVT invokes the notification method; otherwise, the broker does not invoke the associated notification method. The caller can subscribe to the same event multiple times with different filter rules.
Table 1‑10 lists
tpqsubscribe() supported arguments:
topic is a NULL-terminated string of at most 31 characters and starts with "TMQ:<QNOT>:qspace name" (for example"
TMQ:QNOT:QSPACE:usertopic"). The first topic character cannot be a dot (".") as this character is reserved as the starting character for all events defined by the Oracle Tuxedo ATMI system itself. The topic "
TMQ:QNOT: qspace name" is the suffix for all user topics and cannot be used as a user topic name alone."
QNOT" is not a necessary string. But if a topic contains "
QNOT", it indicates the published message is an
AVAIL/UNAVALI message.
Setting this flag indicates that the subscriber wants topic notifications to be enqueued to the queue space named in ctl->name1 and the queue named in ctl->name2. That is, when an topic name is published that evaluates successfully against topic, the TMQEVT tests the published data against the filter rule associated with topic. If the data passes the filter rule or if there is no filter rule for the topic, then the TMQEVT enqueues a message to the queue space named in
ctl->name1 and the queue named in
ctl->name2 along with any data published with the topic. The queue space and queue name can be any valid Oracle Tuxedo ATMI system queue space and queue name, either of which may or may not exist at the time the subscription is made.
ctl->qctl can contain options further directing the TMQEVT enqueuing of the published topic. If no options are specified, then
ctl->qctl.flags should be set to
TPNOFLAGS. Otherwise, options can be set as described in the "Control Parameter" subsection of
tpenqplus.
TPEVQUEUE are mutually exclusive flags. If
TPEVTRAN is also set in
ctl->flags, then if the process calling
tpqpublish() is in transaction mode, the TMQEVT enqueues the published topic and its data such that it will be part of the publisher transaction. The TMQEVT must belong to a server group that supports transactions (see UBBCONFIG for details). If
TPEVTRAN is not set in
ctl->flags, then the TMQEVT enqueues the published topic and its data such that it will not be part of the publisher transaction.
For subscriptions to stable-storage queues, the queue space, queue name, and correlation identifier are used, in addition to topic and filter, when determining matches. The correlation identifier can be used to differentiate among several subscriptions for the same topic expression and filter rule, destined for the same queue. Thus, if the caller has set ctl->flags to
TPEVQUEUE, and
TPQCOORID is not set in
ctl->qctl.flags, then
tpqsubscribe() fails if topic, filter, the queue space name set in
ctl->name1, and the queue name set in
ctl->name2 match those of a subscription (which also does not have a correlation identifier specified) already known to the TMQEVT. Further, if
TPQCOORID is set in
ctl->qctl.flags, then
tpqsubscribe() fails if
topic,
filter,
ctl->name1,
ctl->name2, and
ctl->qctl.corrid match those of a subscription (which has the same correlation identifier specified) already known to the TMQEVT.
If this flag is used with TPEVTRAN and the resource is not available at the time of event notification, then the
EventBroker will return to the poster such that its transaction must be aborted. That is, even though the subscription remains intact, the resource's unavailability will cause the poster's transaction to fail.
Upon failure, tpqsubscribe() returns -1 and sets
tperrno to indicate the error condition. Otherwise, the topic has been successfully subscribed when
tpqsubscribe() returns and returns a subscription handle.
Table 1‑11 lists
tpqunsubscribe() supported arguments:
subscription is an subscription handle returned by tpqsubscribe().Setting subscription to the wildcard value, -1, directs
tpqunsubscribe() to unsubscribe to all non-persistent subscriptions previously made by the calling process. Non-persistent subscriptions are those made without the
TPEVPERSIST bit setting in the
ctl-?flags parameter of
tpqsubscribe(). Persistent subscriptions can be deleted only by using the handle returned by
tpqsubscribe().
Upon failure, tpqunsubscribe() sets
tperrno to one of the following values. (Unless otherwise noted, failure does not affect the caller's transaction, if one exists.)
tpqconfirmmsg()—Confirms receipt of a message that requires explicit confirmation.
When a recoverable message is received, the application must call the tpqconfirmmsg function in order to delete it from the message recovery journal disk storage. If receipt of a recoverable message is not confirmed, the message continues to be stored by the recovery system and will be re-delivered if the application detaches and then reattaches to the queue.
To use tpqconfirmmsg(), you must first invoke
tpqattach().
|
Note:
|
tpqconfirmmsg() is an asynchronous invocation, when it returns, the recoverable message in the recoveray jounal disk storage may not have been deleted by the recovery system.
|
Table 1‑12 lists
tpqconfirmmsg() supported arguments:
Upon failure, tpqconfirmmsg() sets
tperrno to one of the following values. (Unless otherwise noted, failure does not affect the caller's transaction, if one exists.)
tpqsetselect()—Allows application developers to define complex selection criteria for message reception.
The tpqsetselect function creates an index handle that is used as the
sel_filter argument of OTMQ functions for reading the message. When a selection index handle is passed to
tpdeqplus, each message received is compared against comparison
key_1 and then comparison key_2. If the message matches both keys (a logical AND operation), the message is added to a set of matched messages. The order in which selected messages are delivered is determined by the order key.
To use tpqsetselect(), you must first invoke
tpqattach().
Table 1‑13 lists
tpqsetselect() supported arguments:
The selection_array_component_tp data structure has the following components:
Table 1‑15 specifies the valid values that can be applied to the arguments in this part of the
Select_Queue structure:
Table 1‑16 specifies the arguments and valid values that can be applied to this part of the
selection_array_component_tp structure:
The correlation ID is a 32-byte user-defined identifier associated with a message. If OTMQ_CORRELATION_ID is supplied as the value for either the key_1_offset or key_2_offset field, the correlation ID value is used to match messages with the specified correlation ID. Since there is a single correlation ID per message,
OTMQ_CORRELATION_ID should only be specified for one of the comparison keys; specifying the correlation ID for both keys results in a TPEINVAL error.
The index_handle is passed as the sel_filter argument of TPQCTL in
tpdeqplus,
tpqgetmsga , and
tpqcancelselect functions. OTMQ implementations offer up to 32767 index handles.
Upon failure, tpqsetselect() sets
tperrno to one of the following values.
tpqcancelselect()—Releases the selection array and index handle associated with a previously generated selection mask.
To use tpqcancelselect(), you must first invoke
tpqattach().
Table 1‑18 lists supported
tpqcancelselect() arguments:
Upon failure, tpqcancelselect() sets
tperrno to one of the following values.
tpqreadjrn()—Reads a message from an OTMQ local group journal.
For tpqreadjrn(), ctl->flags must contain OTMQ| TPQREADJRN.
Supplies the maximum amount of time the tpqreadjrn function waits for a message to arrive before returning control to the application. If the timeout occurs before a message arrives, the status code OTMQ_TIMEOUT is returned. Specifying 0 as the timeout value sets the timeout to the default value of 30 seconds.
Upon failure, tpqreadjrn() sets
tperrno to one of the following values. Otherwise, the successfully read messages when
tpqreadjrn() returns. you can use
tpqerrno() and
tpqstrerror() to get the detail OTMQ error number and detail string error message
tpdeqplus() was called improperly. There is no effect on the queue or the transaction.
tpqshowpending()—Requests the number of pending messages for a list of selected queues.
To use tpqshowpending(), you must first invoke
tpqattach().
|
Notes:
|
You must allocate the out_pend_list array. The number of queue that need to be listed is depend on "count", you must insure the array of queue list is properly allocated.
|
Table 1‑20 lists supported
tpqshowpending()arguments.
Upon failure, tpqshowpending() sets tperrno to one of the following values.You can use
tpqerrno() and
tpqstrerror() to get the detail OTMQ error number and detail string error message
tpqgetmsga()—Requests asynchronous notification of a message arrival.
Requests asynchronous notification of a message arrival. In OTMQ, the tpqgetmsga function is implemented using unsolicited message of Tuxedo. When calling
tpqgetmsga, it registers its own UNSOL message handler. When a message arrives in that queue that fits the selection condition of
tpqgetmsga, the message being dequeued will be sent through an UNSOL message to the application. Also if an UNSOL message has arrived, if the application setup its own message handling callback function, or an flag, the user callback function will be called, or the flag will be set to "1", to inform the application that an message has been dequeued by
tpqgetmsga.
To use tpqgetmsga(), you must first invoke
tpqattach().
Table 1‑21 lists supported
tpqgetmsga() arguments:
Upon failure, tpqgetmsga() returns -1 and sets
tperrno to indicate the error condition. you can use
tpqerrno() and
tpqstrerror() to get the detail OTMQ error number and detail string error message.
tpqgetmsga() sets
tperrno to one of the following values upon failure. (Unless otherwise noted, failure does not affect caller transaction, if one exists.)
tpqcancelget()—Cancels all pending tpqgetmsga requests that match the value specified in the sel_filter argument.
Cancels all pending tpqgetmsga requests that match the value specified in the sel_filter argument. When a pending tpqgetmsga request is canceled, the OTMQ Status Block (PSB) delivery status is set to
OTMQ__CANCEL and the specified action routine is queued. The tpqcancelget function waits until completion to allow for proper synchronization between the tpqcancelget function and the request for tpqgetmsga functions.
Any outstanding tpqgetmsga function requests are canceled by the tpqexit function or at image exit.
To use tpqcancelget(), must first invoke
tpqattach().
Table 1‑22 lists supported
tpqcancelget() arguments:
tpqerrno() is used to retrieve the error code of OTMQ system call.
Upon success, tpqstrerror() returns a pointer to a string that contains the error message text.
tpqexit()—Terminates all attachments between the application and the OTMQ queue service.
tpqstrerror()—Gets Oracle Tuxedo Message Queue error message string details.
tpqstrerror() is used to retrieve the text of an error message from TMQ_CAT. err is the error code set in
tperrno when an OTMQ system function call returns a -1 or other failure value.
Table 1‑23 lists
tpqstrerror()supported arguments:
Upon success, tpqstrerror() returns a pointer to a string that contains the error message text.
