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

mtaEnqueueFinish()

Complete or cancel a message enqueue operation.

Syntax


int mtaEnqueueFinish(mta_nq_t *nq_ctx,
                     int       item_code, ...);

Arguments

Arguments  

Description  

nq_ctx

An enqueue context created by mtaEnqueueStart().

item_code

An optional list of item codes. See the description section that follows for a list of item codes. The list must be terminated with an integer argument with value 0.

Description

Call mtaEnqueueFinish() to complete an enqueue operation, submitting a new message to the MTA for transport and delivery. Alternatively, call mtaEnqueueFinish() with the MTA_ABORT item code to cancel an enqueue operation without submitting a new message. In either case, when mtaEnqueueFinish() is called the enqueue context passed to it, nq_ctx, is disposed of and may no longer be used regardless of whether a success or error status code is returned.

When completing an enqueue operation, the MTA does much of the actual enqueue work, such as, performing any configured header rewriting, content transformation, and actually writing the message copy or copies to the MTA channel queues. Consequently, errors returned by this routine are typically caused by either site imposed limits (that is, the message size exceeds a site configured limit), or file system related problems (for example, the disk is full, write errors to the disk).

When mtaEnqueueFinish() returns an MTA_NO error message, there is often extended error information available. This information may be retrieved with the MTA_REASON item code. This extended error information takes the form of a text string suitable for writing as diagnostic output.

Before calling mtaEnqueueFinish() to complete an enqueue operation, be sure that the envelope recipient list has been specified with mtaEnqueueTo() and any header lines and content have been written with mtaEnqueueWrite() or mtaEnqueueWriteLine().

When cancelling an enqueue operation, no message is submitted to the MTA, and any temporary files that may have been created are disposed of. To cancel an enqueue operation, specify the MTA_ABORT item code.

The following table lists the item codes for this routine, their additional arguments, and gives a description of each.

Item Codes  

Additional Arguments  

Description  

MTA_ABORT

None 

Cancel the current enqueue operation. The message represented by the enqueue context will not be enqueued to the MTA. 

MTA_ITEM_LIST

mta_item_list_t *item_list

Specify a pointer to an item list array. The item list array must be terminated with a final array entry with an item code value of zero. For further information on item list usage, see Item Codes and Item Lists.

MTA_REASON

const char **errmsg

size_t *errmsg_len

Provide the address of a string pointer to receive any extended error message information. In the event of an error associated with submitting the message to the MTA, then the MTA may return additional information. By providing this pointer, that additional information may be obtained for diagnostic purposes. 

This item code should be followed by two additional item codes: 

  1. The address of a pointer to receive the address of the NULL terminated error text.

  2. The address of a size_t to receive the length of that error text.

    A value of NULL may be passed for the errmsg_len argument.

Return Values

Return Values  

Description  

0

Normal, successful completion. 

MTA_BADARGS

This value is returned for one of the following reasons: 

  1. A NULL value was supplied for the nq_ctx call argument.

  2. An invalid enqueue context was supplied for nq_ctx.

  3. A required argument to an item code was NULL.

MTA_FCREATE

Insufficient disk space or other I/O error encountered while attempting to create or close a message file or a temporary file. 

MTA_FIO

An I/O error occurred while writing message files to the MTA channel queues or while reading from a temporary file. 

MTA_NO

Error terminating the message temporary file, there appears to be insufficient disk space to write the message copies, or there is a problem with a configured content scanner (for example, a virus or spam filter). 

MTA_NOSUCHITEM

An invalid item code was supplied. 

MTA_ORDER

The call was made out of order. Either no envelope recipient addresses have been specified or no message content has been provided. 

MTA_THREAD

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


Note –

In case of an error, the MTA_REASON item code can be used to receive extended error message information


As shown in the preceding table, in the case of an error, the MTA_REASON item code can be used to receive extended error message information

Example

See A Simple Example of Enqueuing a Message.