Cartridge Services — Parameter Manager Interface

This section describes the parameter manager interface functions.

Table 20-5 Parameter Manager Interface Functions

Function/Page	Purpose
OCIExtractFromFile()	The keys and their values in the given file are processed.
OCIExtractFromList()	Generates a list of values for the parameter denoted by `index` in the parameter list.
OCIExtractFromStr()	The keys and the their values in the given string are processed.
OCIExtractInit()	Initializes the parameter manager.
OCIExtractReset()	Re-initializes memory.
OCIExtractSetKey()	Registers information about a key with the parameter manager.
OCIExtractSetNumKeys()	Informs the parameter manager of the number of keys that will be registered.
OCIExtractTerm()	Releases all dynamically allocated storage.
OCIExtractToBool()	Gets the boolean value for the specified key.
OCIExtractToInt()	Gets the integer value for the specified key.
OCIExtractToList()	Generates a list of parameters from the parameter structures that are stored in memory.
OCIExtractToOCINum()	Gets the number value for the specified key.
OCIExtractToStr()	Gets the string value for the specified key.

OCIExtractInit()

Purpose

This function initializes the parameter manager.

Syntax

sword OCIExtractInit( void      *hndl,
                      OCIError  *err);

Parameters

hndl (IN/OUT): The OCI environment or user session handle.
err (IN/OUT): 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 only be called 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,

OCI_ERROR.

OCIExtractTerm()

Purpose

This function releases all dynamically allocated storage.

Syntax

sword OCIExtractTerm( void      *hndl, 
                      OCIError  *err );

Parameters

hndl (IN/OUT): The OCI environment or user session handle.
err (IN/OUT): 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 only be called once.

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.

OCIExtractReset()

Purpose

The memory currently used for parameter storage, key definition storage, and parameter value lists is freed and the structure is re-initialized.

Syntax

sword OCIExtractReset( void      *hndl, 
                       OCIError  *err );

Parameters

hndl (IN/OUT): The OCI environment or user session handle.
err (IN/OUT): 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,

OCI_ERROR.

OCIExtractSetNumKeys()

Purpose

Informs the parameter manager of the number of keys that will be registered.

Syntax

sword OCIExtractSetNumKeys( void    *hndl, 
                            CIError *err, 
                            uword   numkeys );

Parameters

hndl (IN/OUT): The OCI environment or user session handle.
err (IN/OUT): 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().
numkeys (IN): The number of keys that will be registered with OCIExtractSetKey().

Comments

This routine must be called prior to the first call of OCIExtractSetKey().

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.

OCIExtractSetKey()

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

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

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().

name (IN)

The name of the key.

type (IN)

The type of the key:

OCI_EXTRACT_TYPE_INTEGER,

OCI_EXTRACT_TYPE_OCINUM,

OCI_EXTRACT_TYPE_STRING,

OCI_EXTRACT_TYPE_BOOLEAN.

flag (IN)

Set to OCI_EXTRACT_MULTIPLE if the key can take multiple values or 0 otherwise.

defval (IN)

Set to the default value for the key. It may 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.

intrange (IN)

Starting and ending values for the allowable range of integer values; may be NULL if the key is not an integer type or if all integer values are acceptable.

strlist (IN)

List of all acceptable text strings for the key ended with 0 (or NULL). May 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 OCIExtractNumKeys() and before calling OCIExtractFromFile() or OCIExtractFromStr().

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.

OCIExtractFromFile()

Purpose

The keys and their values in the given file are processed.

Syntax

sword OCIExtractFromFile( void     *hndl, 
                          OCIError *err, 
                          ub4      flag, 
                          OraText  *filename );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

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().

flag (IN)

Zero or has one or more of the following bits set:

OCI_EXTRACT_CASE_SENSITIVE,

OCI_EXTRACT_UNIQUE_ABBREVS,

OCI_EXTRACT_APPEND_VALUES.

filename (IN)

A NULL-terminated filename string.

Comments

OCIExtractSetNumKeys() and OCIExtractSetKey() functions must be called to define all of the keys before calling this routine.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_ERROR.

OCIExtractFromStr()

Purpose

The keys and their values in the given string are processed.

Syntax

sword OCIExtractFromStr( void     *hndl, 
                         OCIError *err, 
                         ub4      flag, 
                         OraText  *input );

Parameters

hndl (IN/OUT)

The OCI environment or user session handle.

err (IN/OUT)

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().

flag (IN)

Zero or has one or more of the following bits set:

OCI_EXTRACT_CASE_SENSITIVE,

OCI_EXTRACT_UNIQUE_ABBREVS,

OCI_EXTRACT_APPEND_VALUES.

input (IN)

A NULL-terminated input string.

Comments

OCIExtractSetNumKeys() and OCIExtractSetKey() functions must be called to define all of the keys before calling this routine.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_ERROR.

OCIExtractToInt()

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

hndl (IN): The OCI environment or user session handle.
err (IN/OUT): 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): Keyname (IN).
valno (IN): Which value to get for this key.
retval (OUT): The actual integer value.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_NO_DATA, OCI_ERROR.

OCI_NO_DATA means that there is no valno'th value for this key.

OCIExtractToBool()

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

hndl (IN): The OCI environment or user session handle.
err (IN/OUT): 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): Key name.
valno (IN): Which value to get for this key.
retval (OUT): The actual boolean value.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_NO_DATA, OCI_ERROR.

OCI_NO_DATA means that there is no valno'th value for this key.

OCIExtractToStr()

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

hndl (IN): The OCI environment or user session handle.
err (IN/OUT): 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): Key name.
valno (IN): Which value to get for this key.
retval (OUT): The actual NULL-terminated string value.
buflen: The length of the buffer for retval.

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_NO_DATA,

OCI_ERROR.

OCI_NO_DATA means that there is no valno'th value for this key.

OCIExtractToOCINum()

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

hndl (IN): The OCI environment or user session handle.
err (IN/OUT): 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): Key name.
valno (IN): Which value to get for this key.
retval (OUT): 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.

OCIExtractToList()

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

hndl (IN): The OCI environment or user session handle.
err (IN/OUT): 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().
numkeys (OUT): The number of distinct keys stored in memory.

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.

OCIExtractFromList()

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

hndl (IN)

The OCI environment or user session handle.

err (IN/OUT)

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().

index (IN)

Which parameter to retrieve from the parameter list.

name (OUT)

The name of the key for the current parameter.

type (OUT)

Type of the current parameter:

OCI_EXTRACT_TYPE_STRING,

OCI_EXTRACT_TYPE_INTEGER,

OCI_EXTRACT_TYPE_OCINUM,

OCI_EXTRACT_TYPE_BOOLEAN.

numvals (OUT)

Number of values for this parameter.

values (OUT)

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,

OCI_ERROR.