OCIAttrGet()

Purpose

This call is used to get a particular attribute of a handle.

Syntax

sword OCIAttrGet ( CONST dvoid    *trgthndlp,
                   ub4            trghndltyp,
                   dvoid          *attributep,
                   ub4            *sizep,
                   ub4            attrtype,
                   OCIError       *errhp );

Parameters

trgthndlp (IN)

Pointer to a handle type. The actual handle can be a statement handle, a session handle, etc. When this call is used to get encoding, users are allowed to check against either an environment or statement handle.

trghndltyp (IN)

The handle type. Valid types are:

• OCI_DTYPE_PARAM, for a parameter descriptor
• OCI_HTYPE_STMT, for a statement handle
• Any handle type in Table 2-1, "OCI Handle Types".

attributep (OUT)

Pointer to the storage for an attribute value. In OCI_UTF16 environment mode, the value of a string attribute will be returned as a UTF-16 string.

sizep (OUT)

The size of the attribute value, always in bytes because attributep is a dvoid pointer. This can be passed as null for most attributes because the sizes of non-string attributes are already known by the OCI library. For text* parameters, a pointer to a ub4 must be passed in to get the length of the string.

attrtype (IN)

The type of attribute being retrieved. The types are listed in this document at:

errhp (IN/OUT)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

Comments

This call is used to get a particular attribute of a handle. OCI_DTYPE_PARAM is used to do implicit and explicit describes. The parameter descriptor is also used in direct path loading. For implicit describes, the parameter descriptor has the column description for each select list. For explicit describes, the parameter descriptor has the describe information for each schema object we are trying to describe. If the top-level parameter descriptor has an attribute which is itself a descriptor, use OCI_ATTR_PARAM as the attribute type in the subsequent call to OCIAttrGet().

Use this call to get the Unicode information in an environment or statement handle.

A function closely related to OCIAttrGet() is OCIDescribeAny(), which is a generic describe call that describes existing schema objects: tables, views, synonyms, procedures, functions, packages, sequences, and types. As a result of this call, the describe handle is populated with the object-specific attributes which can be obtained through an OCIAttrGet() call.

Then an OCIParamGet() on the describe handle returns a parameter descriptor for a specified position. Parameter positions begin with 1. Calling OCIAttrGet() on the parameter descriptor returns the specific attributes of a stored procedure or function parameter or a table column descriptor as the case may be. These subsequent calls do not need an extra round-trip to the server because the entire schema object description is cached on the client side by OCIDescribeAny(). Calling OCIAttrGet() on the describe handle can also return the total number of positions.

In UTF-16 mode, particularly when executing a loop, try to reuse the same pointer variable corresponding to an attribute and copy the contents to local variables after OCIAttrGet() is called. If multiple pointers are used for the same attribute, a memory leak can occur.

Related Functions

OCIAttrSet()