0001 TPDEQUEUE(3)
0002 ============
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 tpdequeue, tpdequeueex - Dequeue message form persistent storage (from manual queue)
0009
0010
0011 SYNOPSIS
0012 --------
0013 #include <atmi.h>
0014
0015 int tpdequeue (char *qspace, char *qname, TPQCTL *ctl, char **data, long *len, long flags);
0016
0017 int tpdequeueex (short nodeid, short srvid, char *qname, TPQCTL *ctl, char **data, long *len, long flags);
0018
0019 For XATMI client link with '-latmiclt -latmi -lubf -lnstd -lpthread -lrt -lm'
0020
0021 For XATMI server link with '-latmisrv|-latmisrvnomain|-latmisrvinteg -latmi -lubf -lnstd -lpthread -lrt -lm'
0022
0023 DESCRIPTION
0024 -----------
0025 Dequeue message from transactional persistent message queue. Message queue
0026 subsystem (see *tmqueue(8)* and *persistent_message_queues_overview(guides)*)
0027 must be configured before using this function. 'qspace' is queue space name
0028 (logical queue sub-system name, that can be shared between multiple *tmqueue* servers).
0029 'qname' is queue name, 'ctl' is control structure that contains various details
0030 for message, how it shall be dequeue and additional meta data. Also 'ctl'
0031 returns diagnostics information in case of error. 'data'/'len' pair is XATMI
0032 buffer to which dequeued message must be written. Buffer will be reallocated
0033 accordingly to match the message type in queue. *tpdequeueex()* allows to
0034 specify exactly which *tmqueue* server will process the request, by giving the
0035 Enduro/X cluster node id in 'nodeid' field and 'srvid' from *ndrxconfig.xml(5).
0036
0037 Functions are transactional and can participate in user's global transaction.
0038 It is not possible to enqueue and dequeue message within same global transaction.
0039
0040 In case of error, global transaction (if associated with current thread) is marked for
0041 abort, except if *TPNOABORT* flag was specified or particular error code
0042 indicates that global transaction is not marked for abort.
0043
0044 *Valid flags*
0045
0046 *TPNOTRAN* Do not run the equeue in the users global transaction. In this
0047 case *tmqueue* will open it's own transaction, and will commit transaction
0048 upon return.
0049
0050 *TPSIGRSTRT* Restart the system call in progress if interrupted by signal handler.
0051 This affects only underlying mq_* function calls.
0052
0053 *TPNOTIME* Ignore timeout setting (*NDRX_TOUT* env variable).
0054 Wait for reply for infinitely.
0055
0056 *TPNOCHANGE* Do not allow to change the buffer type if buffer type in
0057 message queue does not match the buffer type passed into 'data' field.
0058
0059 *TPNOBLOCK* In case of queue server request, if request IPC queue is full,
0060 do not wait on queue, but return error. The error code for this
0061 situation is *TPEBLOCK*. This affects only request part of the call.
0062 This flag does not affect waiting for response from the TMQ server.
0063
0064 The *TPQCTL* structure is following:
0065
0066 --------------------------------------------------------------------------------
0067
0068 /* Queue support structure: */
0069 struct tpqctl_t
0070 {
0071 long flags; /* indicates which of the values are set */
0072 long deq_time; /* absolute/relative time for dequeuing */
0073 long priority; /* enqueue priority */
0074 long diagnostic; /* indicates reason for failure */
0075 char diagmsg[NDRX_QDIAG_MSG_SIZE]; /* diagnostic message */
0076 char msgid[TMMSGIDLEN]; /* id of message before which to queue */
0077 char corrid[TMCORRIDLEN];/* correlation id used to identify message */
0078 char replyqueue[TMQNAMELEN+1]; /* queue name for reply message */
0079 char failurequeue[TMQNAMELEN+1];/* queue name for failure message */
0080 CLIENTID cltid; /* client identifier for originating client */
0081 long urcode; /* application user-return code */
0082 long appkey; /* application authentication client key */
0083 long delivery_qos; /* delivery quality of service */
0084 long reply_qos; /* reply message quality of service */
0085 long exp_time; /* expiration time */
0086 };
0087 typedef struct tpqctl_t TPQCTL;
0088
0089 --------------------------------------------------------------------------------
0090
0091 Valid *'TPQCTL.flags'*
0092
0093 *TPNOFLAGS* No flags set.
0094
0095 *TPQGETBYCORRID* Use the correlator ID in 'TPQCTL.corrid' to get the
0096 message by. Note that each byte in 'corrid' is significant. The corrid basically
0097 denotes the sub-queue for given 'qname'. If there are messages in queue, but
0098 not for given 'corrid', then standard *QMENOMSG* error code is returned. Message
0099 ordering is applies the same as for normal queue.
0100
0101 *TPQGETBYMSGID* Use the message ID in 'TPQCTL.msgid' to get the message by.
0102 Note that each byte in 'msgid' is significant.
0103
0104 *TPQPEEK* Return the message from queue by not actually removing it.
0105
0106 *TPNOABORT* Do not abort global transaction, even if queue failed (could be
0107 suitable in cases when for example polling on Q is done (request for next msg
0108 and queue is empty).
0109
0110 Fields 'TPQCTL.deq_time', 'TPQCTL.priority', 'TPQCTL.urcode', 'TPQCTL.appkey',
0111 'TPQCTL.delivery_qos', 'TPQCTL.reply_qos', 'TPQCTL.exp_time' are reserved for
0112 future use. 'TPQCTL.cltid' is set to client id string which enqueued the message.
0113
0114 RETURN VALUE
0115 ------------
0116 On success, *tpdequeue()* return 0; on error, -1 is returned, with *tperrno*
0117 set to indicate the error. Also 'TPQCTL.diagnostic' and 'TPQCTL.diagmsg'
0118 will contain additional information.
0119
0120 ERRORS
0121 ------
0122 Note that *tpstrerror()* returns generic error message plus custom message with
0123 debug info from last function call.
0124
0125 *TPEINVAL* 'data' is NULL, 'qspace' is NULL, or 'nodeid' and 'srvid' is 0.
0126 Error can be generate in case if 'qname' is empty or NULL. 'ctl' is NULL or
0127 'data' does not point to *tpalloc()* allocated buffer.
0128
0129 *TPENOENT* *tmqueue(8)* server is not available. Global transaction is not
0130 marked for abort only,if one was associated with current thread.
0131
0132 *TPETIME* Service did not reply in given time ('NDRX_TOUT').
0133
0134 *TPEDIAGNOSTIC* More information is provided in 'TPQCTL.diagnostic' field.
0135
0136 *TPESVCFAIL* *tmqueue(8)* Service returned 'TPFAIL'. This is application level failure.
0137
0138 *TPESVCERR* *tmqueue(8)* service got system level failure. Server died during the
0139 message presence in service queue.
0140
0141 *TPESYSTEM* Enduro/X internal error occurred. See logs for more info.
0142
0143 *TPEOS* System failure occurred during serving. See logs i.e. user log, or debugs for more info.
0144
0145 *TPEBLOCK* XATMI IPC Service request queue was full and *TPNOBLOCK*
0146 flag was specified. Global transaction is not marked for abort only,
0147 if one was associated with current thread.
0148
0149 *TPETRAN* Failed to join global transaction.
0150
0151 *Values for 'TPQCTL.diagnostic'*
0152
0153 *QMEINVAL* Invalid request buffer. Global transaction is not marked for abort only,
0154 if one was associated with current thread.
0155
0156 *QMEOS* Operating system problems. Might be insufficient memory.
0157
0158 *QMESYSTEM* Enduro/X internal problems. Might be issues with saving messages to disk.
0159
0160 *QMENOMSG* No messages in queue. Global transaction is not marked for abort only,
0161 if one was associated with current thread.
0162
0163 *QMEBADQUEUE* Queue not defined and default (@) queue settings are not defined too.
0164 Global transaction is not marked for abort only, if one was associated with current thread.
0165
0166 EXAMPLE
0167 -------
0168 See *atmitest/test028_tmq/atmiclt28.c* for sample code.
0169
0170 BUGS
0171 ----
0172 Report bugs to support@mavimax.com
0173
0174 SEE ALSO
0175 --------
0176 *tpenqueue(3)* *tpenqueueex(3)* *tmqueue(8)* *persistent_message_queues_overview(guides)*
0177
0178 COPYING
0179 -------
0180 (C) Mavimax, Ltd
0181
