Reference: Cartridge Services Using C, 5 of 6

Cartridge Services -- Parameter Manager Interface

Table 13-16 OCI Parameter Manager Interface Functions Quick Reference

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

OCIExtractInit()

Purpose

This function initializes the parameter manager.

Syntax

sword OCIExtractInit( dvoid     *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 NLS information is stored inside the parameter manager context and used in subsequent calls to OCIExtract routines.

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.

Table 13-17 OCIExtractInit Keywords/Parameters

Keyword/Parameter	Meaning
`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`()

OCIExtractTerm()

Purpose

This function releases all dynamically allocated storage.

Syntax

sword OCIExtractTerm( dvoid     *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.

Table 13-18 OCIExtractTerm Keywords/Parameters

Keyword/Parameter	Meaning
`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`().

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( dvoid     *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.

Table 13-19 OCIExtractReset Keywords/Parameters

Keyword/Parameter	Meaning
`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`()

OCIExtractSetNumKeys()

Purpose

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

Syntax

sword OCIExtractSetNumKeys( dvoid   *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.

Table 13-20 OCIExtractSetNumKeys Keywords/Parameters

Keyword/Parameter	Meaning
`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`()

OCIExtractSetKey()

Purpose

Registers information about a key with the parameter manager.

Syntax

sword OCIExtractSetKey( dvoid       *hndl, 
                        OCIError    *err, 
                        CONST text  *name,
                        ub1         type, 
                        ub4         flag, 
                        CONST dvoid *defval, 
                        CONST sb4   *intrange, 
                        CONST text  *CONST *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 OCIExtractFromString().

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.

Table 13-21 OCIExtractSetKey Keywords/Parameters

Keyword/Parameter	Meaning
`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, or 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; 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

OCIExtractFromFile()

Purpose

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

Syntax

sword OCIExtractFromFile( dvoid    *hndl, 
                          OCIError *err, 
                          ub4      flag, 
                          text     *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() routines must be called to define all of the keys before calling this routine.

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.

Table 13-22 OCIExtractFromFile Keywords/Parameters

Keyword/Parameter	Meaning
`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`, or `OCI_EXTRACT_APPEND_VALUES`
filename (IN)	`NULL`-terminated filename string

OCIExtractFromStr()

Purpose

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

Syntax

sword OCIExtractFromStr( dvoid    *hndl, 
                         OCIError *err, 
                         ub4      flag, 
                         text     *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; 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,

or OCI_EXTRACT_APPEND_VALUES.

input (IN)

A null-terminated input string.

Comments

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

Returns

OCI_SUCCESS,

OCI_INVALID_HANDLE,

OCI_ERROR.

Table 13-23 OCIExtractFromStr Keywords/Parameters

Keyword/Parameter	Meaning
`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`, or `OCI_EXTRACT_APPEND_VALUES`
input (IN)	`NULL`-terminated input string

OCIExtractToInt()

Purpose

Gets the integer value for the specified key. The valno'th value (starting with 0) is returned.

Syntax

sword OCIExtractToInt( dvoid     *hndl, 
                       OCIError  *err, 
                       text      *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.

Table 13-24 OCIExtractToInt Keywords/Parameters

Keyword/Parameter	Meaning
`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 integer value

OCIExtractToBool()

Purpose

Gets the boolean value for the specified key. The valno'th value (starting with 0) is returned.

Syntax

sword OCIExtractToBool( dvoid     *hndl, 
                        OCIError  *err, 
                        text      *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.

Table 13-25 OCIExtractToBool Keywords/Parameters

Keyword/Parameter	Meaning
`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

OCIExtractToStr()

Purpose

Gets the string value for the specified key. The valno'th value (starting with 0) is returned.

Syntax

sword OCIExtractToStr( dvoid *hndl, 
                       OCIError *err, 
                       text *keyname, 
                       uword valno, 
                       text *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 value for this key.

Table 13-26 OCIExtractToStr Keywords/Parameters

Keyword/Parameter	Meaning
`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
`bufflen (IN)`	the length of the buffer for retval

OCIExtractToOCINum()

Purpose

Gets the OCINumber value for the specified key. The valno'th value (starting with 0) is returned.

Syntax

sword OCIExtractToOCINum( dvoid     *hndl, 
                          OCIError  *err, 
                          text      *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.

Table 13-27 OCIExtractToOCINum Keywords/Parameters

Keyword/Parameter	Meaning
`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` string value

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( dvoid     *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.

Table 13-28 OCIExtractToList Keywords/Parameters

Keyword/Parameter	Meaning
`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)	number of distinct keys stored in memory

OCIExtractFromList()

Purpose

Generates a list of values for the parameter denoted by index in the parameter list.

Syntax

sword OCIExtractFromList( dvoid       *hndl, 
                          OCIError    *err, 
                          uword       index, 
                          text        **name, 
                          ub1         *type, 
                          uword       *numvals, 
                          dvoid       ***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.

Table 13-29 OCIExtractFromList Keywords/Parameters

Keyword/Parameter	Meaning
`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)`	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`, or `OCI_EXTRACT_TYPE_BOOLEAN`)
`numvals (OUT)`	number of values for this parameter
`values (OUT)`	the values for this parameter