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

Error Status Codes

The following table lists the error status codes, with a generic interpretation of each. For usage-specific interpretations, refer to the specific MTA SDK routine descriptions in Chapter 6, MTA SDK Reference, and the mtaSend() item code descriptions in Chapter 8, mtaSend() Routine Specification.

Return Code  

Numeric Value  




Normal, successful completion. 



This error typically indicates that a site-supplied access mapping table has refused an envelope recipient address with a permanent error. These access mapping tables include: SEND_ACCESS, ORIG_SEND_ACCESS, MAIL_ACCESS, and ORIG_MAIL_ACCESS.

This error may also result when a mailing list has access controls which do not allow the attempted message submission to the list. 



A temporary processing error has occurred. A number of conditions may generate this error including connectivity problems to LDAP servers, virus scanners, spam scanners, as well as quota problems. 

When the error is the result of an attempt to add an envelope recipient address or to complete a message enqueue, additional information may be obtained by either enabling SDK diagnostics with mtaDebug() or using the MTA_REASON item code of mtaEnqueueTo() or mtaEnqueueFinish(). In the case of mtaEnqueueTo(), mtaEnqueueError() may also be used to obtain the extended information returned with the MTA_REASON item code.



Bad call arguments supplied to the called routine. Typically, this will be the result of passing an invalid context or a NULL value for a required parameter. 



End of data reached. When returned by mtaDequeueLineNext() or mtaDequeueRecipientNext(), this value does not indicate an error, but rather that there are, respectively, no more message lines or recipients to return.



Unable to create a disk file. Typically, this will be the result of insufficient disk space, insufficient access rights to the channel queue directories, or a file system error of some sort. The MTA SDK creates both temporary files and message files in the channel queue directories. The temporary files result when a message being submitted exceeds in size the value of the MTA option: MAX_INTERNAL_BLOCKS.



An error occurred while writing to a disk file. Typically, this will be the result of insufficient disk space or a file system error. This error is only reported when writing message files, either temporary files, or writing them in the channel queue directories. 



An error occurred while attempting to open a disk file. In regards to channel option files, this indicates that the channel option file exists but cannot be opened. Usually this is caused by insufficient access rights or a file system error. 

This error may also be returned when the MTA SDK is initialized and an MTA configuration file cannot be opened. Again, this usually indicates a problem with permissions or the file system. Use the imsimta test -rewrite utility to obtain additional diagnostic information. That utility often reports the name of the underlying configuration file associated with the error.



A network read or write error has occurred. This error is associated with message dequeue processing and indicates that a communication error has occurred while attempting to contact or exchange information with the MTA Job Controller. Ensure that the Job Controller is running. 



Generic error message. This error message is issued in a variety of situations. In all cases, it indicates that the attempted call has failed. Consult the routine’s description for an interpretation specific to the called routine. Also, consider enabling MTA SDK diagnostics with mtaDebug().



Insufficient virtual memory; cannot perform the requested operation. 



This error code is not presently used by the MTA SDK. In general, it is used to indicate that the requested operation was completed by doing nothing (for example, a message enqueued to zero envelope recipients is simply deleted). 



The specified channel name does not exist in the MTA configuration. The channel name may have been specified explicitly with a supplied call argument or implicitly with the PMDF_CHANNEL environment variable.



The MTA configuration lacks the necessary information to route the specified envelope recipient address. This error typically comes up when an unrecognized, top-level domain name is used. As such, this usually indicates a syntactically valid recipient address which specifies an invalid top-level domain name (for example, sue@siroe.siroe). Other addressing errors, including syntax errors, may elicit this status code.



An invalid item code was supplied. Either the supplied item code value does not represent a known item code or it is not an item code supported by the called routine. 



Routine called out of order. For example, an attempt to read the text of a queued message file was made before first reading the message’s entire recipient list. Or, an attempt was made to write the content of a message being submitted before first specifying the message’s recipients. Refer to the call order diagrams in for further details. 



The message being submitted cannot be enqueued: its size exceeds a site-configured size limit. Such limits are configured with a variety of options, including the MTA options BLOCK_LIMIT and LINE_LIMIT, as well as the channel keywords blocklimit and linelimit.



The supplied buffer was not large enough to receive the result string. The result string was truncated to fit. The result string is nonetheless NULL terminated. 



The supplied buffer was not larger enough to receive the result string. Truncating the result is not meaningful or has potential for causing problems or both. Alternatively, a supplied string was too long. 



Threading error detected. Specifically, the MTA SDK detected the simultaneous use of a single SDK context by two or more processing threads. This is not permitted. 



This error code is not presently used by the MTA SDK. In general, it is used to indicate a timeout related error.