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


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  




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


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.


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.