Enduro/X Master/​doc/​api/​xatmi/​tpenqueue.adoc	Source navigation Diff markup Identifier search General search
	Latest: Master Revert   Change

 TPENQUEUE(3)
 ============
 :doctype: manpage
 
 
 NAME
 ----
 tpenqueue, tpenqueueex - Enqueue message to persistent storage
 
 
 SYNOPSIS
 --------
 #include <atmi.h>
 
 int tpenqueue (char *'qspace', char *'qname', TPQCTL *'ctl', char *'data', long 'len', long 'flags');
 
 int tpenqueueex (short 'nodeid', short 'srvid', char *'qname', TPQCTL *'ctl', char *'data', long 'len', long 'flags');
 
 
 For XATMI client link with '-latmiclt -latmi -lubf -lnstd -lpthread -lrt -lm'
 
 For XATMI server link with '-latmisrv|-latmisrvnomain|-latmisrvinteg -latmi -lubf -lnstd -lpthread -lrt -lm'
 
 DESCRIPTION
 -----------
 Enqueue message to transactional message queue. Queue subsystem (see *tmqueue(8)* 
 and *persistent_message_queues_overview(guides)*) must be configured before using 
 this function. 'qspace' is queue space name (logical queue sub-system name, 
 that can be shared between multiple *tmqueue* servers). 'qname' is queue name, 
 'ctl' is control structure that contains various details for message, how it 
 shall be enqueued. Also 'ctl' returns some diagnostics information. 'data'/'len' 
 pair is XATMI buffer containing the message that must be enqueued. *tpenqueueex()* 
 allows to specify exactly which *tmqueue* server will process the request, 
 by giving the Enduro/X cluster node id in 'nodeid' field and 'srvid' 
 from *ndrxconfig.xml(5).
 
 Functions are transactional and can participate in user's global transaction. 
 It is not possible to enqueue and dequeue message within same global transaction.
 
 In case of error, global transaction (if associated with current thread) is marked for
 abort, except if *TPNOABORT* flag was specified or particular error code
 indicates that global transaction is not marked for abort.
 
 *Valid flags*
 
 *TPNOTRAN* Do not run the enqueue in the users global transaction. 
 In this case *tmqueue(8)* will open it's own transaction, and will commit 
 transaction upon return.
 
 *TPSIGRSTRT* Restart the system call in progress if interrupted by signal handler.
 This affects only underlaying mq_* function calls.
 
 *TPNOTIME* Ignore timeout setting (*NDRX_TOUT* env variable). 
 Wait for reply for infinitely.
 
 *TPNOBLOCK* In case of queue server request, if request IPC queue is full, 
 do not wait on queue, but return error. The error code for this 
 situation is *TPEBLOCK*. This affects only request part of the call. 
 This flag does not affect waiting for response from the TMQ server.
 
 *TPNOABORT* Do not abort global transaction, even if queue failed.
 
 The *TPQCTL* structure is following:
 
 --------------------------------------------------------------------------------
 
 /* Queue support structure: */
 struct tpqctl_t 
 {
         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 diagmsg[NDRX_QDIAG_MSG_SIZE]; /* diagnostic message */
         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  */          
 };              
 typedef struct tpqctl_t TPQCTL;      
 
 --------------------------------------------------------------------------------
 
 Valid *'TPQCTL.flags'*
 
 *TPNOFLAGS* No flags set.
 
 *TPQCORRID* Use the correlator ID set in 'TPQCTL.corrid'. 
 Note that each byte in 'corrid' is significant. When working with corrid, it
 establishes sub-queue for given 'qname'. The message ordering settings are kept
 the same as for queue definition. Several messages with the same corrid can be
 enqueued in the same or different queues.
 
 *TPQREPLYQ* Use the 'replyqueue' for submitting response messages of services 
 which were invoked for automatic queues. If this flag is set, with 
 response buffer message will be enqueued to 'replyqueue'.
 
 *TPQFAILUREQ* Send the message to 'failurequeue' if *tpcall()* for 
 service invoke for automatic queues failed.
 
 *TPQTIME_ABS* Use absolute time to process message in time specified in `TPQCTL.deq_time` field.
 The `TPQCTL.deq_time` fiel in absolute time format generated by *time()* function.  
 `TPQCTL.deq_time` field is set in number of seconds since epoch (1970-01-01 00:00:00 +0000 (UTC)).
 
 *TPQTIME_REL* Use relative time to process message delayed by time specified in `TPQCTL.deq_time` field.
 The `TPQCTL.deq_time` field value set in number of seconds to delay the message processing.
 *TPQTIME_ABS* and *TPQTIME_REL* are mutually exclusive.
 
 Fields 'TPQCTL.priority', 'TPQCTL.urcode', 'TPQCTL.appkey', 
 'TPQCTL.delivery_qos', 'TPQCTL.reply_qos', 'TPQCTL.exp_time' are reserved 
 for future use. 'TPQCTL.cltid' is 
 automatically set by Enduro/X system when passing message to *tmqueue* server.
 
 RETURN VALUE
 ------------
 On success, *tpenqueue()* return 0; on error, -1 is returned, with 
 *tperrno* set to indicate the error. Also 'TPQCTL.diagnostic' and 
 'TPQCTL.diagmsg' will contain additional information.
 
 ERRORS
 ------
 Note that *tpstrerror()* returns generic error message plus custom message 
 with debug info from last function call.
 
 *TPEINVAL* 'data' is NULL, 'qspace' is NULL, or 'nodeid' and 'srvid' is 0. 
 Error can be generate in case if 'qname' is empty or NULL. 'ctl' is NULL or 
 'data' does not point to *tpalloc()* allocated buffer. Global transaction is 
 not marked for abort only, if one was associated with current thread.
 
 *TPENOENT* *tmqueue(8)* server is not available. Global transaction is 
 not marked for abort only, if one was associated with current thread.
 
 *TPETIME* Service did not reply in given time ('NDRX_TOUT'). 
 
 *TPEDIAGNOSTIC* More information is provided in 'TPQCTL.diagnostic' field.
 
 *TPESVCFAIL* *tmqueue(8)* Service returned 'TPFAIL'. This is application level failure.
 
 *TPESVCERR* *tmqueue(8)* service got system level failure. Server died during the 
 message presence in service queue.
 
 *TPESYSTEM* Enduro/X internal error occurred. See logs for more info.
 
 *TPEOS* System failure occurred during serving. See logs i.e. user log, or 
 debugs for more info.
 
 *TPEBLOCK* XATMI IPC Service request queue was full and *TPNOBLOCK* 
 flag was specified. Global transaction is not marked for abort only, 
 if one was associated with current thread.
 
 *TPETRAN* Failed to join global transaction.
 
 *Values for 'TPQCTL.diagnostic'*
 
 *QMEINVAL* Invalid request buffer / *TPQCTL*. Global transaction is 
 not marked for abort only, if one was associated with current thread.
 
 *QMEOS* Operating system problems. Might be insufficient memory.
 
 *QMESYSTEM* Enduro/X internal problems. Might be issues with saving 
 messages to disk.
 
 *QMEBADQUEUE* Queue not defined and default (@) queue settings are not defined too.
 Global transaction is not marked for abort only, if one was associated with current thread.
 
 
 EXAMPLE
 -------
 See *atmitest/test028_tmq/atmiclt28.c* for sample code.
 
 BUGS
 ----
 Report bugs to support@mavimax.com
 
 SEE ALSO
 --------
 *tpdequeue(3)* *tpdequeueex(3)* *tmqueue(8)* *persistent_message_queues_overview(guides)*
 
 COPYING
 -------
 (C) Mavimax, Ltd
 

This page was automatically generated by the 2.1.0 LXR engine. The LXR team