mtaOptionStart()

Open, parse, and load into memory an MTA option file.

Syntax

int mtaOptionStart(mta_opt_t **opt_ctx,
                   const char *path,
                   size_t      len,
                   int         item_code);

Arguments

Description

MTA option files such as channel option files may be read, parsed, and loaded into memory with mtaOptionStart(). Once loaded into memory, the values of individual options may be retrieved with the routines shown in the table that follows:

These routines are designed such that if the requested option does not exist, then no value is returned. This allows code to assign to a variable an option’s default value, then attempt to retrieve an explicitly set value from the option file. During the retrieval, the address of the variable can be passed. If the option is specified in the option file, then the value of the variable will be replaced with the value from the option file. If the option is not specified, then the default value stored in the variable is left unchanged. Code examples of such usage are provided in the individual routine descriptions.

Once finished obtaining the values of any options, unload the options from memory and dispose of the option context with mtaOptionFinish().

When the underlying option file does not exist, mtaOptionStart() still returns a success status code. However, a NULL value is returned for the pointer to the option context. The other option routines accept a NULL value for an option context pointer and will behave as though the requested option is not specified in the option file. This behavior reflects the fact that MTA option files are considered optional. If a channel’s option file does not exist, then the channel is supposed to use its default settings for its options. This also simplifies coding, allowing programs not to have to worry about whether or not the option file exists and whether or not the option context pointer is NULL. If, however, the existence of an option file is mandatory, then a program can detect that the file does not exist by seeing if the returned value for the option context pointer is NULL as shown in the code example section that follows.

If an explicit option file path is specified with the path call argument, then the path can be a relative file path or an absolute file path. File paths can be prefixed with any of the symbolic MTA directory names specified in the imta_tailor file. For example, the entry shown in the following code fragment specifies a file named mmsc_gateway.cnf located in the nmsc subdirectory of the MTA configuration directory. Note that a colon separates the symbolic name from the remainder of the path.

IMTA_TABLE:/mmsc/mmsc_gateway.cnf

If no file path is specified, then the file specified with the PMDF_CHANNEL_OPTION environment variable will be opened and read. That environment variable is established by the Job Controller for the channel programs that it runs. It will always have the following format:

IMTA_TABLE:channel-name_option

where channel-name is the name of the channel being run. The following example demonstrates how the environment variable settings are effected for tcp_local channel:

PMDF_CHANNEL=tcp_local
PMDF_CHANNEL_OPTION=IMTA_TABLE:tcp_local_option

Return Values

Example

opt_ctx = NULL;
if (mtaOptionStart(&opt_ctx, NULL, 0, 0))
    /*
     * Error loading the option file
     */
else if (!opt_ctx)
    /*
     * Option file did not exist
     */