This section describes the parameter manager interface functions.
Table 19-5 Parameter Manager Interface Functions
Function/Page | Purpose |
---|---|
The keys and their values in the given file are processed. |
|
Generates a list of values for the parameter denoted by |
|
The keys and the their values in the given string are processed. |
|
Initializes the parameter manager. |
|
Re-initializes memory. |
|
Registers information about a key with the parameter manager. |
|
Informs the parameter manager of the number of keys that will be registered. |
|
Releases all dynamically allocated storage. |
|
Gets the boolean value for the specified key. |
|
Gets the integer value for the specified key. |
|
Generates a list of parameters from the parameter structures that are stored in memory. |
|
Gets the number value for the specified key. |
|
Gets the string value for the specified key. |
See Also:
For more information about using these functions, see Oracle Database Data Cartridge Developer's GuideThis function initializes the parameter manager.
sword OCIExtractInit( dvoid *hndl, OCIError *err);
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()
.
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.
OCI_SUCCESS
,
OCI_INVALID_HANDLE
,
OCI_ERROR
.
This function releases all dynamically allocated storage.
sword OCIExtractTerm( dvoid *hndl, OCIError *err );
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()
.
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.
OCI_SUCCESS
,
OCI_INVALID_HANDLE
,
OCI_ERROR
.
The memory currently used for parameter storage, key definition storage, and parameter value lists is freed and the structure is re-initialized.
sword OCIExtractReset( dvoid *hndl, OCIError *err );
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()
.
OCI_SUCCESS
,
OCI_INVALID_HANDLE
,
OCI_ERROR
.
Informs the parameter manager of the number of keys that will be registered.
sword OCIExtractSetNumKeys( dvoid *hndl, CIError *err, uword numkeys );
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 will be registered with OCIExtractSetKey()
.
This routine must be called prior to the first call of OCIExtractSetKey()
.
OCI_SUCCESS
,
OCI_INVALID_HANDLE
,
OCI_ERROR
.
Registers information about a key with the parameter manager.
sword OCIExtractSetKey( dvoid *hndl, OCIError *err, CONST text *name, ub1 type, ub4 flag, CONST dvoid *defval, CONST sb4 *intrange, CONST text *strlist );
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 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.
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.
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.
This routine must be called after calling OCIExtractNumKeys()
and before calling OCIExtractFromFile()
or OCIExtractFromStr()
.
OCI_SUCCESS
,
OCI_INVALID_HANDLE
,
OCI_ERROR
.
The keys and their values in the given file are processed.
sword OCIExtractFromFile( dvoid *hndl, OCIError *err, ub4 flag, text *filename );
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 filename string.
OCIExtractSetNumKeys()
and OCIExtractSetKey()
functions must be called to define all of the keys before calling this routine.
OCI_SUCCESS
, OCI_INVALID_HANDLE
, OCI_ERROR
.
The keys and their values in the given string are processed.
sword OCIExtractFromStr( dvoid *hndl, OCIError *err, ub4 flag, text *input );
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.
OCIExtractSetNumKeys()
and OCIExtractSetKey()
functions must be called to define all of the keys before calling this routine.
OCI_SUCCESS
, OCI_INVALID_HANDLE
, OCI_ERROR
.
Gets the integer value for the specified key. The valno
'th value (starting with 0) is returned.
sword OCIExtractToInt( dvoid *hndl, OCIError *err, text *keyname, uword valno, sb4 *retval );
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.
OCI_SUCCESS
, OCI_INVALID_HANDLE
, OCI_NO_DATA
, OCI_ERROR
.
OCI_NO_DATA
means that there is no valno'th value for this key.
Gets the boolean value for the specified key. The valno'th value (starting with 0) is returned.
sword OCIExtractToBool( dvoid *hndl, OCIError *err, text *keyname, uword valno, ub1 *retval );
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.
OCI_SUCCESS
, OCI_INVALID_HANDLE
, OCI_NO_DATA
, OCI_ERROR
.
OCI_NO_DATA
means that there is no valno'th value for this key.
Gets the string value for the specified key. The valno
'th value (starting with 0) is returned.
sword OCIExtractToStr( dvoid *hndl, OCIError *err, text *keyname, uword valno, text *retval, uword buflen );
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
.
OCI_SUCCESS
,
OCI_INVALID_HANDLE
,
OCI_NO_DATA
,
OCI_ERROR
.
OCI_NO_DATA
means that there is no valno'th value for this key.
Gets the OCINumber value for the specified key. The valno'th value (starting with 0) is returned.
sword OCIExtractToOCINum( dvoid *hndl, OCIError *err, text *keyname, uword valno, OCINumber *retval );
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.
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.
Generates a list of parameters from the parameter structures that are stored in memory. Must be called before OCIExtractValues()
is called.
sword OCIExtractToList( dvoid *hndl, OCIError *err, uword *numkeys );
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.
OCI_SUCCESS
,
OCI_INVALID_HANDLE
,
OCI_ERROR
.
Generates a list of values for the parameter denoted by index in the parameter list.
sword OCIExtractFromList( dvoid *hndl, OCIError *err, uword index, text **name, ub1 *type, uword *numvals, dvoid ***values );
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.
OCIExtractToList()
must be called prior to calling this routine to generate the parameter list from the parameter structures that are stored in memory.
OCI_SUCCESS
,
OCI_INVALID_HANDLE
,
OCI_ERROR
.