OCI Type Information Accessor Functions

This section describes the OCI type information accessor functions.

Table 17-12 Type Information Accessor Functions

Function/Page	Purpose
`OCITypeArrayByName()`	Get an array of TDOs given an array of object names
`OCITypeArrayByRef()`	Get an array of TDOs given an array of object references
`OCITypeByName()`	Get a TDO given an object name
`OCITypeByRef()`	Get a TDO given an object reference

OCITypeArrayByName()

Purpose

Get an array of types given an array of names.

Syntax

sword OCITypeArrayByName ( OCIEnv             *envhp,
                           OCIError           *errhp,
                           CONST OCISvcCtx    *svc,
                           ub4                array_len,
                           CONST text         *schema_name[],
                           ub4                s_length[],
                           CONST text         *type_name[],
                           ub4                t_length[],
                           CONST text         *version_name[],
                           ub4                v_length[],
                           OCIDuration        pin_duration,
                           OCITypeGetOpt      get_option,
                           OCIType            *tdo[] );

Parameters

envhp (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

errhp (IN/OUT)

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

svc (IN)

OCI service handle.

array_len (IN)

Number of schema_name/type_name/version_name entries to be retrieved.

schema_name (IN, optional)

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 it must have array_len number of elements. 0 can be supplied for one or more of the entries to indicate that the default schema is desired for those entries.

s_length (IN)

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.

type_name (IN)

Array of the names of the types to retrieve. This must have array_len number of elements.

t_length (IN)

Array of the lengths of type names in the type_name array in bytes.

version_name (IN)

The version name is ignored and the latest version of the requested type is returned. Because type evolution is available starting in release 9.0, pre-9.0 applications attempting to access an altered type will generate an error. These applications must be modified, re-compiled, and re-linked using the new 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. 0 can be supplied for one or more of the entries to indicate that the current version is desired for those entries.

v_length (IN)

Array of the lengths of version names in the version_name array in bytes.

pin_duration (IN)

Pin duration (for example, until the end of current transaction) for the types retrieved. See oro.h for a description of each option.

get_option (IN)

Options for loading the types. It can be one of two values:

OCI_TYPEGET_HEADER - for only the header to be loaded, or
OCI_TYPEGET_ALL - for the TDO and all ADO and MDOs to be loaded.

tdo (OUT)

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.

Comments

Gets pointers to the existing types associated with the schema/type name array.

The get_option parameter can be used 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/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 will belong 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.

Related Functions

OCITypeArrayByRef(), OCITypeByName(), OCITypeByRef()

OCITypeArrayByRef()

Purpose

Get an array of types given an array of references.

Syntax

sword OCITypeArrayByRef ( OCIEnv           *envhp,
                          OCIError         *errhp,
                          ub4              array_len,
                          CONST OCIRef     *type_ref[],
                          OCIDuration      pin_duration,
                          OCITypeGetOpt    get_option,
                          OCIType          *tdo[] );

Parameters

envhp (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

errhp (IN/OUT)

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

array_len (IN)

Number of schema_name/type_name/version_name entries to be retrieved.

type_ref (IN)

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

Pin duration (for example,until the end of current transaction) for the types retrieved. See oro.h for a description of each option.

get_option (IN)

Options for loading the types. It can be one of two values:

OCI_TYPEGET_HEADER - for only the header to be loaded
OCI_TYPEGET_ALL - for the TDO and all ADO and MDOs to be loaded.

tdo (OUT)

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.

Comments

Gets pointers to the with the schema/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/type name entry does not exist.

To retrieve a single type, rather than an array of types, use OCITypeByRef().

Note:

Related Functions

OCITypeArrayByName(), OCITypeByRef(), OCITypeByName()

OCITypeByName()

Purpose

Get the most current version of an existing type by name.

Syntax

sword OCITypeByName ( OCIEnv               *env,
                      OCIError             *err, 
                      CONST OCISvcCtx      *svc, 
                      CONST text           *schema_name,
                      ub4                  s_length, 
                      CONST text           *type_name, 
                      ub4                  t_length, 
                      CONST text           *version_name,
                      ub4                  v_length,
                      OCIDuration          pin_duration,
                      OCITypeGetOpt        get_option
                      OCIType              **tdo );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

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

svc (IN)

OCI service handle.

schema_name (IN, optional)

Name of schema associated with the type. By default, the user's schema name is used. This string must be all in upper-case, or else OCI throws an internal error and the program stops.

s_length (IN)

Length of the schema_name parameter, in bytes.

type_name (IN)

Name of the type to get. This string must be all in upper-case, or else OCI throws an internal error and the program stops.

t_length (IN)

Length of the type_name parameter, in bytes.

version_name (IN)

User-readable version of the type. Pass as (text *)0 to retrieve the most current version.

v_length (IN)

Length of version_name in bytes.

pin_duration (IN)

Pin duration.

See Also:

"Object Duration"

get_option ((IN)

Options for loading the types. It can be one of two values:

OCI_TYPEGET_HEADER for only the header to be loaded, or
OCI_TYPEGET_ALL for the TDO and all ADO and MDOs to be loaded.

tdo (OUT)

Pointer to the pinned type in the object cache.

Comments

This function gets a pointer to the existing type associated with schema/type name. It returns an error if any of the required parameters is NULL, or if the object type associated with schema/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 need to use strings all in upper-case, or the program will stop.

This function always makes a round trip to the server and hence calling this function repeatedly to get the type can significantly drag down performance. To minimize the round trips, the application may call the function for each type and cache the type objects.

To free the type obtained by this function, OCIObjectUnpin() or OCIObjectPinCountReset() may be called.

An application can retrieve an array of TDOs by calling OCITypeArrayByName(), or OCITypeArrayByRef().

Note:

Related Functions

OCITypeByRef(), OCITypeArrayByName(), OCITypeArrayByRef()

OCITypeByRef()

Purpose

Get a type given a reference.

Syntax

sword OCITypeByRef ( OCIEnv          *env,
                     OCIError        *err,
                     CONST OCIRef    *type_ref,
                     OCIDuration     pin_duration,
                     OCITypeGetOpt   get_option,
                     OCIType         **tdo );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

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

type_ref (IN)

An OCIRef * pointing to the version of the type descriptor object to obtain.

pin_duration (IN)

Pin duration until the end of current transaction for the type to retrieve. See oro.h for a description of each option.

get_option (IN)

Options for loading the type. It can be one of two values:

OCI_TYPEGET_HEADER - for only the header to be loaded, or
OCI_TYPEGET_ALL - for the TDO and all ADO and MDOs to be loaded.

tdo (OUT)

Pointer to the pinned type in the object cache.

Comments

OCITypeByRef() returns an error if any of the required parameters is NULL.

Note:

Related Functions

OCITypeByName(), OCITypeArrayByName(), OCITypeArrayByRef()