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

`mtaEnqueueCopyMessage()`

Copy a queued message to a new message being enqueued.

Syntax

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

Arguments

Arguments	Description
`nq_ctx`	Message submission to copy the message data to. `nq_ctx` must be an enqueue context created by `mtaEnqueueStart()`.
`dq_ctx`	Queued message to copy the message data from. Must be a a dequeue context created by `mtaDequeueStart()`.
`rewind`	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.

Description

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	Description
`0`	Normal, successful completion.
`MTA_BADARGS`	This value is returned for one of the following reasons: A NULL value was supplied for either the `nq_ctx` or `dq_ctx` call arguments. Invalid contexts were passed for either or both of those call arguments.
`MTA_FCREATE`	Unable to create a temporary file to hold data for the new message being enqueued.
`MTA_FIO`	An I/O error occurred while attempting to write data to a message file.
`MTA_ORDER`	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()`.
`MTA_THREAD`	Simultaneous use of either the enqueue or dequeue context by two different threads was detected.

Example

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.

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