Parameter Manager Interface

The parameter manager provides a set of routines to process parameters from a file or a string. Routines are provided to process the input and to obtain key and value pairs. These key and value pairs are stored in memory and routines are provided which can access the values of the stored parameters.

The input processing routines match the contents of the file or the string against an existing grammar and compare the key names found in the input against the list of known keys that the user has registered. The behavior of the input processing routines can be configured depending on the bits that are set in the flag argument.

The parameters can be retrieved either one at a time or all at once by calling a function that iterates over the stored parameters.

Input Processing

Parameters consist of a key, or parameter name, type, and a value and must be specified in the following format:

key = value

Parameters can optionally accept lists of values which may be surrounded by parentheses. The following two formats are acceptable for specifying a value list:

key = (value1 value2 ... valuen)
key = value1 value2 ... valuen

A value can be a string, integer, OCINumber, or Boolean. A boolean value starting with 'y' or 't' maps to TRUE and a boolean value starting with 'n' or 'f' maps to FALSE. The matching for boolean values is case insensitive.

The parameter manager views certain characters as "special characters" which are not parsed literally. The special characters and their meanings are indicated below:

Table 9-1  Special Characters and their Meanings

Character	Meaning
#	Comment (only for files)
(	Start a list of values
)	End a list of values
"	Start or end of quoted string
'	Start or end of quoted string
=	Separator of keyword and value
\	Escape character

If a special character must be treated literally, then it must either be prefaced by the escape character or the entire string must be surrounded by single or double quotes.

A key string can contain alphanumeric characters only. A value can contain any characters. However, the value cannot contain special characters unless they are quoted or escaped.

Parameter Manager Behavior Flag

The routines to process a file or a string take a behavior flag that can alter certain default characteristics of the parameter manager. The following bits can be set in the flag to produce the new behavior:

• OCI_EXTRACT_CASE_SENSITIVE. All comparisons are case sensitive. The default is to use case insensitive comparisons.

• OCI_EXTRACT_UNIQUE_ABBREVS. Unique abbreviations are allowed for keys. The default is that unique abbreviations are not allowed.

• OCI_EXTRACT_APPEND_VALUES. If a value or values are already stored for a particular key, then any new values for this key should be appended. The default is to return an error.

Key Registration

Before invoking the input processing routines (OCIExtractFromFile or OCIExtractFromString), all of the keys must be registered by calling OCIExtractSetNumKeys followed by OCIExtractSetKey. OCIExtractSetKey requires the following information for each key:

• Name of the key

• Type of the key (integer, string, boolean, OCINumber)

• OCI_EXTRACT_MULTIPLE is set for the flag value if multiple values are allowed (default: only one value allowed)

• Default value to be used for the key (may be NULL)

• Range of allowable integer values given by the starting and ending value, inclusive (may be NULL)

• List of allowable string values (may be NULL)

Parameter Storage and Retrieval

The results of processing the input into a set of keys and values are stored. The validity of the parameters is checked before storing the parameters in memory. The values are checked to see if they are of the proper type. In addition, if you wish, the values can be checked to see if they fall within a certain range of integer values or are members of a list of enumerated string values. Also, if you do not specify that a key can accept multiple values, then an error will be returned if a key is specified more than once in a particular input source. Also, an error will be returned if the key is unknown.

After the processing is completed, the value(s) for a particular key can be queried. Separate routines are available to retrieve a string value, an integer value, an OCINumber value, and a boolean value.

It is possible to retrieve all parameters at once. The function OCIExtractToList must first be called to generate a list of parameters that is created from the parameter structures stored in memory. OCIExtractToList will return the number of unique keys stored in memory, and then OCIExtractFromList can be called to return the list of values associated with each key.

Parameter Manager Context

The parameter manager maintains its own context within the OCI environment handle. This context stores all the processed parameter information and some internal information. It must be initialized with a call to OCIExtractInit and cleaned up with a call to OCIExtractTerm.