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


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


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





On successful return, a pointer to an option context created by mtaOptionStart(). This option context represents the options read from the option file.


Optional file path to the option file to read. If not specified, then the path specified by the PMDF_CHANNEL_OPTION environment variable will be used. If a value of zero is supplied for len, and there is a non-NULL value for path, the value must be NULL terminated. The length of the file path, not including any NULL terminator, may not exceed ALFA_SIZE bytes.


Length in bytes, not including any NULL terminator, of the file path. This argument is ignored when a NULL is passed for path. When path is non-NULL and a value of zero is supplied for len, then the file path string must be NULL terminated.


Reserved for future use. A value of zero must be supplied for this call argument. 


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:

Routine Names  



Retrieve the value of a floating point valued option. 


Retrieve the value of an integer valued option. 


Retrieve the string representation of an options value. 

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.


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:


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:


Return Values

Return Values  



Normal, successful completion. 


A NULL value was supplied for the opt_ctx call argument.


Unable to open the option file. File access permissions are the likely cause for this error. 


An error occurred while reading or parsing the option file. 


Insufficient virtual memory. 


The supplied file path is too long. Its length must not exceed ALFA_SIZE bytes.


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