Table 18-11 describes the OCI type information accessor functions that are described in this section.
Table 18-11 Type Information Accessor Functions
| Function | Purpose |
|---|---|
|
Get an array of TDOs when given an array of object names |
|
|
Get an array of TDOs when given an array of object references |
|
|
Get a TDO when given an object name |
|
|
Get a TDO when given an object reference |
sword OCITypeArrayByName ( OCIEnv *envhp,
OCIError *errhp,
const OCISvcCtx *svc,
ub4 array_len,
const OraText *schema_name[],
ub4 s_length[],
const OraText *type_name[],
ub4 t_length[],
const OraText *version_name[],
ub4 v_length[],
OCIDuration pin_duration,
OCITypeGetOpt get_option,
OCIType *tdo[] );
The OCI environment handle initialized in object mode. See the descriptions of OCIEnvCreate(), OCIEnvNlsCreate(), and OCIInitialize() (deprecated) for more information.
The OCI error handle. If there is an error, it is recorded in err, and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
OCI service handle.
Number of schema_name or type_name or version_name entries to be retrieved.
Array of schema names associated with the types to be retrieved. The array must have array_len elements if specified. If 0 is supplied, the default schema is assumed; otherwise, schema_name must have array_len number of elements. Zero (0) can be supplied for one or more of the entries to indicate that the default schema is desired for those entries.
Array of schema_name lengths with each entry corresponding to the length of the corresponding schema_name entry in the schema_name array in bytes. The array must either have array_len number of elements or it must be 0 if schema_name is not specified.
Array of the names of the types to retrieve. This must have array_len number of elements.
Array of the lengths of type names in the type_name array in bytes.
The version name is ignored and the latest version of the requested type is returned. Because type evolution was available starting in release 9.0, pre-9.0 applications attempting to access an altered type generate an error. These applications must be modified, recompiled, and relinked using the latest type definition.
Array of the version names of the types to retrieve corresponding. This can be 0 to indicate retrieval of the most current versions, or it must have array_len number of elements.
If 0 is supplied, the most current version is assumed, otherwise it must have array_len number of elements. Zero (0) can be supplied for one or more of the entries to indicate that the current version is desired for those entries.
Array of the lengths of version names in the version_name array in bytes.
Pin duration (for example, until the end of the current transaction) for the types retrieved. See oro.h for a description of each option.
Option for loading the types. It can be one of two values:
OCI_TYPEGET_HEADER (only the header is loaded)
OCI_TYPEGET_ALL (TDO and all ADO and MDOs are loaded)
Output array for the pointers to each pinned type in the object cache. It must have space for array_len pointers. Use OCIObjectGetObjectRef() to obtain the CREF to each pinned type descriptor.
Gets pointers to the existing types associated with the schema or type name array.
You can use the get_option parameter to control the portion of the TDO that gets loaded for each round-trip.
This function returns an error if any of the required parameters is NULL or any object types associated with a schema or type name entry do not exist.
To retrieve a single type, rather than an array, use OCITypeByName().
Note:
The TDO (array of TDOs or table definition) obtained by this function belongs to the logical partition of the cache corresponding to the service handle (connection) passed in. If TDOs or tables are used across logical partitions, then the behavior is not known and may change between releases.
sword OCITypeArrayByRef ( OCIEnv *envhp,
OCIError *errhp,
ub4 array_len,
const OCIRef *type_ref[],
OCIDuration pin_duration,
OCITypeGetOpt get_option,
OCIType *tdo[] );
The OCI environment handle initialized in object mode. See the descriptions of OCIEnvCreate(), OCIEnvNlsCreate(), and OCIInitialize() (deprecated) for more information.
The OCI error handle. If there is an error, it is recorded in err, and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Number of schema_name or type_name or version_name entries to be retrieved.
Array of OCIRef * pointing to the particular version of the type descriptor object to obtain. The array must have array_len elements if specified.
Pin duration (for example, until the end of the current transaction) for the types retrieved. See oro.h for a description of each option.
Option for loading the types. It can be one of two values:
OCI_TYPEGET_HEADER (only the header is loaded)
OCI_TYPEGET_ALL (TDO and all ADO and MDOs are loaded)
Output array for the pointers to each pinned type in the object cache. It must have space for array_len pointers. Use OCIObjectGetObjectRef() to obtain the CREF to each pinned type descriptor.
Gets pointers to the existing types with the schema or type name array.
This function returns an error if:
Any of the required parameters is NULL
One or more object types associated with a schema or type name entry does not exist
To retrieve a single type, rather than an array of types, use OCITypeByRef().
Note:
The TDO (array of TDOs or table definition) obtained by this function belongs to the logical partition of the cache corresponding to the service handle (connection) passed in. If TDOs or tables are used across logical partitions, then the behavior is not known and may change between releases.
sword OCITypeByName ( OCIEnv *env,
OCIError *err,
const OCISvcCtx *svc,
const OraText *schema_name,
ub4 s_length,
const OraText *type_name,
ub4 t_length,
const OraText *version_name,
ub4 v_length,
OCIDuration pin_duration,
OCITypeGetOpt get_option
OCIType **tdo );
The OCI environment handle initialized in object mode. See the descriptions of OCIEnvCreate(), OCIEnvNlsCreate(), and OCIInitialize() (deprecated) for more information.
The OCI error handle. If there is an error, it is recorded in err, and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
OCI service handle.
Name of schema associated with the type. By default, the user's schema name is used. This string must be all uppercase, or OCI throws an internal error and the program stops.
Length of the schema_name parameter, in bytes.
Name of the type to get. This string must be all uppercase, or OCI throws an internal error and the program stops.
Length of the type_name parameter, in bytes.
The version name is ignored and the latest version of the requested type is returned. Because type evolution was available starting in release 9.0, pre-9.0 applications attempting to access an altered type generate an error. These applications must be modified, recompiled, and relinked using the latest type definition.
User-readable version of the type. Pass as (text *)0 to retrieve the most current version.
Length of version_name in bytes.
Pin duration.
See Also:
"Object Duration"Option for loading the types. It can be one of two values:
OCI_TYPEGET_HEADER (only the header is loaded)
OCI_TYPEGET_ALL (TDO and all ADO and MDOs are loaded)
Pointer to the pinned type in the object cache.
This function gets a pointer to the existing type associated with the schema or type name. It returns an error if any of the required parameters is NULL, or if the object type associated with the schema or type name does not exist, or if version_name does not exist.
Note:
Schema and type names are case-sensitive. If they have been created with SQL, you must use strings in all uppercase, or the program stops.This function always makes a round-trip to the server. Therefore calling this function repeatedly to get the type can significantly reduce performance. To minimize the round-trips, the application can call the function for each type and cache the type objects.
To free the type obtained by this function, call OCIObjectUnpin() or OCIObjectPinCountReset().
An application can retrieve an array of TDOs by calling OCITypeArrayByName() or OCITypeArrayByRef().
Note:
The TDO (array of TDOs or table definition) obtained by this function belongs to the logical partition of the cache corresponding to the service handle (connection) passed in. If TDOs or tables are used across logical partitions, then the behavior is not known and may change between releases.
sword OCITypeByRef ( OCIEnv *env,
OCIError *err,
const OCIRef *type_ref,
OCIDuration pin_duration,
OCITypeGetOpt get_option,
OCIType **tdo );
The OCI environment handle initialized in object mode. See the descriptions of OCIEnvCreate(), OCIEnvNlsCreate(), and OCIInitialize() (deprecated) for more information.
The OCI error handle. If there is an error, it is recorded in err, and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
An OCIRef * pointing to the version of the type descriptor object to obtain.
Pin duration until the end of the current transaction for the type to retrieve. See oro.h for a description of each option.
Option for loading the type. It can be one of two values:
OCI_TYPEGET_HEADER (only the header is loaded)
OCI_TYPEGET_ALL (TDO and all ADO and MDOs are loaded)
Pointer to the pinned type in the object cache.
OCITypeByRef() returns an error if any of the required parameters is NULL.
Note:
The TDO (array of TDOs or table definition) obtained by this function belongs to the logical partition of the cache corresponding to the service handle (connection) passed in. If TDOs or tables are used across logical partitions, then the behavior is not known and may change between releases.