Miscellaneous Programming Considerations

This section covers miscellaneous topics of interest to programmer’s using the SDK:

• Retrieving Error Codes

• Writing Output From a Channel Program

• Considerations for Persistent Programs

Retrieving Error Codes

With few exceptions, all routines in the SDK return an integer-valued result with a value of zero (0) indicating success. When a non-zero value is returned, it is also saved in a per-thread data section, which may be retrieved with either the mtaErrno() function or the mta_errno C pre-processor macro.

The exceptional routines either return nothing (that is, always succeed), or return a string pointer, and signify an error with a return value of NULL.

Writing Output From a Channel Program

The C runtime library stdout input-output destination may be usurped by the SDK, depending upon the context under which a channel program has been invoked. As such, programs that will operate as channels should use the mtaLog() routine to write information to their log file. Such programs should never write output directly to stdout or stderr or other generic I/O destinations, such as Pascal’s output, or FORTRAN’s default output logical unit. There’s no telling where such output might go: it might go to the Job Controller’s log file, it might even go down a network pipe to a remote client or server.

The channel log file is a different file from the MTA log file. The mtaLog() and mtaAccountingLogClose() are unrelated routines.

Considerations for Persistent Programs

There are two main problems to consider when creating programs that persist over long periods of time (for weeks or months):

• Refreshing Stale Configuration Information

• Keeping the Log File Available For Update

Refreshing Stale Configuration Information

Some programs, once started, run indefinitely (for weeks or months). An example of this kind of program is a server that listens continually for incoming mail connections, enqueuing received messages. Site-specific configuration information is loaded at initialization. In the case of these long running programs, the information can become stale due to changes to configuration information, such as rewrite rules or channel definitions. Subsequent calls to mtaInit() do not accomplish this task. A program must exit and restart in order to ensure that all configuration information is reloaded.

Keeping the Log File Available For Update

A program that enqueues and dequeues messages may open the MTA log file, mail.log_current. For persistent programs, care should be taken that this log file is not left open during periods of inactivity. Otherwise, activities that require exclusive access to this file will be blocked. Before going idle, persistent programs should call mtaAccountingLogClose(). The log file will automatically reopened when needed.

The MTA log file, mail.log_current, is not the log written to by mtaLog().