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)

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.

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.

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.

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

Related Functions

OCITypeByRef(), OCITypeArrayByName(), OCITypeArrayByRef()