Sun Java System Messaging Server 6 2005Q4 MTA Developer's Reference


Copy a queued message to a new message being enqueued.


int mtaEnqueueCopyMessage(mta_nq_t *nq_ctx,
                          mta_dq_t *dq_ctx,
                          int       rewind);





Message submission to copy the message data to. nq_ctx must be an enqueue context created by mtaEnqueueStart().


Queued message to copy the message data from. Must be a a dequeue context created by mtaDequeueStart().


Supply a value of 1 to move the read point in the queued message file to the start of the message before commencing the copy operation. Supply a value of zero to leave the message read point unchanged before copying.


Intermediate processing channels often need to copy verbatim a message from a channel queue to a new message being enqueued. That is, intermediate processing channels often re-enqueue an existing, queued message. This verbatim copy can be accomplished with mtaEnqueueCopyMessage(). Using this routine is significantly faster than using mtaDequeueLineNext() and mtaEnqueueWriteLine() in a read and write loop.

When mtaEnqueueCopyMessage() is called, the copy begins at the current read point of the queued message file associated with the supplied dequeue context, dq_ctx. The message file from that point to its end is copied to the new message being enqueued. To start at the beginning of the queued message (that is, to start at the beginning of its outermost header), specify a value of 1 for the rewind call argument. So doing is equivalent to first calling mtaDequeueRewind() before mtaEnqueueCopyMessage().

Return Values

Return Values  



Normal, successful completion. 


This value is returned for one of the following reasons: 

  1. A NULL value was supplied for either the nq_ctx or dq_ctx call arguments.

  2. Invalid contexts were passed for either or both of those call arguments.


Unable to create a temporary file to hold data for the new message being enqueued. 


An I/O error occurred while attempting to write data to a message file. 


Call made out of order. Either no recipients have yet been specified for the new message with mtaEnqueueTo(), or the recipient list of the queued message has not been completely read with mtaDequeueRecipientNext().


Simultaneous use of either the enqueue or dequeue context by two different threads was detected. 


The following code fragment specifies starting at the beginning of the queued message by using the rewind call argument.

mtaEnqueueMessageCopy(nq_ctx, dq_ctx, 1);

The code fragment that follows illustrates a second, less efficient way of copying the message.

while (!mtaDequeueLineNext(dq_ctx, &line, &len))
   mtaEnqueueWriteLine(nq_ctx, line, len, NULL);