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

mtaOptionInt()

Interpret and return an option’s value as an integer number.

Syntax


int mtaOptionInt(mta_opt_t  *opt_ctx,
                 const char *name,
                 size_t      len,
                 int        *val);

Arguments

Arguments  

Description  

opt_ctx

An option context created by mtaOptionStart(). A NULL value is permitted for this argument. When a NULL is passed, then no option value is returned.

name

Name of the option to obtain the value for. The length of this string should not exceed ALFA_SIZE bytes. This string must be NULL terminated if a value of zero is passed for len.

len

Length in bytes, not including any NULL terminator, of the option name supplied with name. If a value of zero is supplied, then the option name string must be NULL terminated. 

val

Pointer to an integer of type int to receive the option’s value. If the option was not specified in the option file, then the value referenced by this pointer will be left unchanged.

Description

Use mtaOptionInt() to retrieve the value of an option, interpreting its value as an integer-valued number. If the option is specified in the option file and its value is a valid integer, then its value will be returned using the val call argument. If the option is not specified or its value does not correctly specify an integer, then no value is returned and the memory pointed at by val is left unchanged.

The routine can be called with a NULL value for the opt_ctx argument. When this is done, mtaOptionInt() immediately returns with a status code of zero and no value is returned.

This routine does not provide an indication of whether or not the option was specified in the option file. If it is important to know whether or not the option was specified, then use mtaOptionString() to test to see if the option was specified as shown in the code example.

Return Values

Return Values  

Description  

0

Normal, successful completion. 

MTA_STRTRUERR

The supplied option name is too long. Its length must not exceed ALFA_SIZE bytes.

Example

In the following code example, the value of an option named max_blocks is retrieved. Before calling mtaOptionInt(), a default value is set for the variable to receive the value of the option. If the option was not specified in the option file, then the variable will retain that default setting. If the option was specified, then the variable will assume the value set in the file.


blocks = 1024;
mtaOptionInt(opt, "max_blocks", 0, &blocks);

The following code example illustrates how upon return from mtaOptionString(), the code determines that the option was specified by whether or not the value of the buflen variable has changed.


char buf[1];
size_t buflen;

buflen = 0xffffffff;
mtaOptionString(opt, "max_blocks", 0, buf, &buflen, sizeof(buf));
blocks_specified = (buflen != 0xffffffff) ? 1 : 0;