Table 21-4 lists the parameter manager interface functions that are described in this section.
Table 21-4 Parameter Manager Interface Functions
| Function | Purpose |
|---|---|
|
Process the keys and their values in the given file |
|
|
Generate a list of values for the parameter denoted by |
|
|
Process the keys and the their values in the given string |
|
|
Initialize the parameter manager |
|
|
Reinitialize memory |
|
|
Register information about a key with the parameter manager |
|
|
Inform the parameter manager of the number of keys that are to be registered |
|
|
Release all dynamically allocated storage |
|
|
Get the Boolean value for the specified key |
|
|
Get the integer value for the specified key |
|
|
Generate a list of parameters from the parameter structures that are stored in memory |
|
|
Get the number value for the specified key |
|
|
Get the string value for the specified key |
See Also:
Oracle Database Data Cartridge Developer's Guide for more information about using these functions
Purpose
Processes the keys and their values in the given file.
Syntax
sword OCIExtractFromFile( void *hndl,
OCIError *err,
ub4 flag,
OraText *filename );
Parameters
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err, and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
Zero or has one or more of the following bits set:
OCI_EXTRACT_CASE_SENSITIVE
OCI_EXTRACT_UNIQUE_ABBREVS
OCI_EXTRACT_APPEND_VALUES
A NULL-terminated file name string.
Comments
OCIExtractSetNumKeys() and OCIExtractSetKey() functions must be called to define all of the keys before this routine is called.
Returns
OCI_SUCCESS; OCI_INVALID_HANDLE; or OCI_ERROR.
Purpose
Generates a list of values for the parameter denoted by index in the parameter list.
Syntax
sword OCIExtractFromList( void *hndl,
OCIError *err,
uword index,
OraText **name,
ub1 *type,
uword *numvals,
void ***values );
Parameters
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err, and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
Which parameter to retrieve from the parameter list.
The name of the key for the current parameter.
Type of the current parameter:
OCI_EXTRACT_TYPE_STRING
OCI_EXTRACT_TYPE_INTEGER
OCI_EXTRACT_TYPE_OCINUM
OCI_EXTRACT_TYPE_BOOLEAN
Number of values for this parameter.
The values for this parameter.
Comments
OCIExtractToList() must be called prior to calling this routine to generate the parameter list from the parameter structures that are stored in memory.
Returns
OCI_SUCCESS; OCI_INVALID_HANDLE; or OCI_ERROR.
Purpose
Processes the keys and their values in the given string.
Syntax
sword OCIExtractFromStr( void *hndl,
OCIError *err,
ub4 flag,
OraText *input );
Parameters
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err, and this function returns OCI_ERROR. For diagnostic information call OCIErrorGet().
Zero or has one or more of the following bits set:
OCI_EXTRACT_CASE_SENSITIVE
OCI_EXTRACT_UNIQUE_ABBREVS
OCI_EXTRACT_APPEND_VALUES
A NULL-terminated input string.
Comments
OCIExtractSetNumKeys() and OCIExtractSetKey() functions must be called to define all of the keys before this routine is called.
Returns
OCI_SUCCESS; OCI_INVALID_HANDLE; or OCI_ERROR.
Purpose
Initializes the parameter manager.
Syntax
sword OCIExtractInit( void *hndl,
OCIError *err);
Parameters
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err, and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
Comments
This function must be called before calling any other parameter manager routine, and it must be called only once. The globalization support information is stored inside the parameter manager context and used in subsequent calls to OCIExtract functions.
Returns
OCI_SUCCESS; OCI_INVALID_HANDLE; or OCI_ERROR.
Purpose
Frees the memory currently used for parameter storage, key definition storage, and parameter value lists and reinitializes the structure.
Syntax
sword OCIExtractReset( void *hndl,
OCIError *err );
Parameters
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err, and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
Returns
OCI_SUCCESS; OCI_INVALID_HANDLE; or OCI_ERROR,
Purpose
Registers information about a key with the parameter manager.
Syntax
sword OCIExtractSetKey( void *hndl,
OCIError *err,
const text *name,
ub1 type,
ub4 flag,
const void *defval,
const sb4 *intrange,
const text *strlist );
Parameters
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err, and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
The name of the key.
The type of the key:
OCI_EXTRACT_TYPE_INTEGER
OCI_EXTRACT_TYPE_OCINUM
OCI_EXTRACT_TYPE_STRING
OCI_EXTRACT_TYPE_BOOLEAN
Set to OCI_EXTRACT_MULTIPLE if the key can take multiple values or 0 otherwise.
Set to the default value for the key. It can be NULL if there is no default. A string default must be a (text*) type, an integer default must be an (sb4*) type, and a Boolean default must be a (ub1*) type.
Starting and ending values for the allowable range of integer values; can be NULL if the key is not an integer type or if all integer values are acceptable.
List of all acceptable text strings for the key ended with 0 (or NULL). Can be NULL if the key is not a string type or if all text values are acceptable.
Comments
This routine must be called after calling OCIExtractSetNumKeys() and before calling OCIExtractFromFile() or OCIExtractFromStr().
Returns
OCI_SUCCESS; OCI_INVALID_HANDLE; or OCI_ERROR.
Purpose
Informs the parameter manager of the number of keys that are to be registered.
Syntax
sword OCIExtractSetNumKeys( void *hndl,
CIError *err,
uword numkeys );
Parameters
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err, and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
The number of keys that are to be registered with OCIExtractSetKey().
Comments
This routine must be called prior to the first call of OCIExtractSetKey().
Returns
OCI_SUCCESS; OCI_INVALID_HANDLE; or OCI_ERROR.
Purpose
Releases all dynamically allocated storage.
Syntax
sword OCIExtractTerm( void *hndl,
OCIError *err );
Parameters
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err, and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
Comments
This function may perform other internal bookkeeping functions. It must be called when the parameter manager is no longer being used, and it must be called only once.
Returns
OCI_SUCCESS; OCI_INVALID_HANDLE; or OCI_ERROR.
Purpose
Gets the Boolean value for the specified key. The valno'th value (starting with 0) is returned.
Syntax
sword OCIExtractToBool( void *hndl,
OCIError *err,
OraText *keyname,
uword valno,
ub1 *retval );
Parameters
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err, and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
Key name.
Which value to get for this key.
The actual Boolean value.
Returns
OCI_SUCCESS; OCI_INVALID_HANDLE; OCI_NO_DATA; or OCI_ERROR.
OCI_NO_DATA means that there is no valno'th value for this key.
Purpose
Gets the integer value for the specified key. The valno'th value (starting with 0) is returned.
Syntax
sword OCIExtractToInt( void *hndl,
OCIError *err,
OraText *keyname,
uword valno,
sb4 *retval );
Parameters
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err, and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
Keyname (IN).
Which value to get for this key.
The actual integer value.
Returns
OCI_SUCCESS; OCI_INVALID_HANDLE; OCI_NO_DATA; or OCI_ERROR.
OCI_NO_DATA means that there is no valno'th value for this key.
Purpose
Generates a list of parameters from the parameter structures that are stored in memory. Must be called before OCIExtractValues() is called.
Syntax
sword OCIExtractToList( void *hndl,
OCIError *err,
uword *numkeys );
Parameters
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err, and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
The number of distinct keys stored in memory.
Returns
OCI_SUCCESS; OCI_INVALID_HANDLE; or OCI_ERROR.
Purpose
Gets the OCINumber value for the specified key. The valno'th value (starting with 0) is returned.
Syntax
sword OCIExtractToOCINum( void *hndl,
OCIError *err,
OraText *keyname,
uword valno,
OCINumber *retval );
Parameters
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err, and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
Key name.
Which value to get for this key.
The actual OCINumber value.
Returns
OCI_SUCCESS; OCI_INVALID_HANDLE; OCI_NO_DATA; or OCI_ERROR.
OCI_NO_DATA means that there is no valno'th value for this key.
Purpose
Gets the string value for the specified key. The valno'th value (starting with 0) is returned.
Syntax
sword OCIExtractToStr( void *hndl,
OCIError *err,
OraText *keyname,
uword valno,
OraText *retval,
uword buflen );
Parameters
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err, and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
Key name.
Which value to get for this key.
The actual NULL-terminated string value.
The length of the buffer for retval.
Returns
OCI_SUCCESS; OCI_INVALID_HANDLE; OCI_NO_DATA; or OCI_ERROR.
OCI_NO_DATA means that there is no valno'th value for this key.