Handle and Descriptor Functions

This section describes the OCI handle and descriptor functions.

Table 15-3 Handle and Descriptor Functions

Function	Purpose
`OCIAttrGet()`	Get the attributes of a handle
`OCIAttrSet()`	Set an attribute of a handle or descriptor
`OCIDescriptorAlloc()`	Allocate and initialize a descriptor or LOB locator
`OCIDescriptorFree()`	Free a previously allocated descriptor
`OCIHandleAlloc()`	Allocate and initialize a handle
`OCIHandleFree()`	Free a previously allocated handle
`OCIParamGet()`	Get a parameter descriptor
`OCIParamSet()`	Set parameter descriptor in COR handle

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, and so on. 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. Will be in the encoding specified by the charset parameter of a previous call to OCIEnvNlsCreate().

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:

See Also:

See Appendix A, "Handle and Descriptor Attributes", for a list of handle types and their readable attributes

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

OCIAttrSet()

Purpose

This call is used to set a particular attribute of a handle or a descriptor.

Syntax

sword OCIAttrSet ( dvoid       *trgthndlp,
                   ub4         trghndltyp,
                   dvoid       *attributep,
                   ub4         size,
                   ub4         attrtype,
                   OCIError    *errhp );

Parameters

trgthndlp (IN/OUT)

Pointer to a handle type whose attribute gets modified.

trghndltyp (IN/OUT)

The handle type.

attributep (IN)

Pointer to an attribute value. The attribute value is copied into the target handle. If the attribute value is a pointer, then only the pointer is copied, not the contents of the pointer. String attributes must be in the encoding specified by the charset parameter of a previous call to OCIEnvNlsCreate().

size (IN)

The size of an attribute value. This can be passed in as 0 for most attributes as the size is already known by the OCI library. For text* attributes, a ub4 must be passed in set to the length of the string in bytes, regardless of encoding.

attrtype (IN)

The type of attribute being set.

errhp (IN/OUT)

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

Comments

See Appendix A, "Handle and Descriptor Attributes", for a list of handle types and their writable attributes.

Related Functions

OCIAttrGet()

OCIDescriptorAlloc()

Purpose

Allocates storage to hold descriptors or LOB locators.

Syntax

sword OCIDescriptorAlloc ( CONST dvoid   *parenth,
                           dvoid         **descpp, 
                           ub4           type,
                           size_t        xtramem_sz,
                           dvoid         **usrmempp);

Parameters

parenth (IN)

An environment handle.

descpp (OUT)

Returns a descriptor or LOB locator of desired type.

type (IN)

Specifies the type of descriptor or LOB locator to be allocated:

OCI_DTYPE_SNAP - specifies generation of snapshot descriptor of C type OCISnapshot
OCI_DTYPE_LOB - specifies generation of a LOB value type locator (for a BLOB or CLOB) of C type OCILobLocator
OCI_DTYPE_FILE - specifies generation of a FILE value type locator of C type OCILobLocator.
OCI_DTYPE_ROWID - specifies generation of a ROWID descriptor of C type OCIRowid.
OCI_DTYPE_DATE - specifies generation of an ANSI DATE descriptor of C type OCIDateTime
OCI_DTYPE_TIMESTAMP - specifies generation of a TIMESTAMP descriptor of C type OCIDateTime
OCI_DTYPE_TIMESTAMP_TZ - specifies generation of a TIMESTAMP WITH TIME ZONE descriptor of C type OCIDateTime
OCI_DTYPE_TIMESTAMP_LTZ - specifies generation of a TIMESTAMP WITH LOCAL TIME ZONE descriptor of C type OCIDateTime
OCI_DTYPE_INTERVAL_YM - specifies generation of an INTERVAL YEAR TO MONTH descriptor of C type OCIInterval
OCI_DTYPE_INTERVAL_DS - specifies generation of an INTERVAL DAY TO SECOND descriptor of C type OCIInterval
OCI_DTYPE_COMPLEXOBJECTCOMP - specifies generation of a complex object retrieval descriptor of C type OCIComplexObjectComp.
OCI_DTYPE_AQENQ_OPTIONS - specifies generation of an Advanced Queuing enqueue options descriptor of C type OCIAQEnqOptions.
OCI_DTYPE_AQDEQ_OPTIONS - specifies generation of an Advanced Queuing dequeue options descriptor of C type OCIAQDeqOptions.
OCI_DTYPE_AQMSG_PROPERTIES - specifies generation of an Advanced Queuing message properties descriptor of C type OCIAQMsgProperties.
OCI_DTYPE_AQAGENT - specifies generation of an Advanced Queuing agent descriptor of C type OCIAQAgent.

xtramem_sz (IN)

Specifies an amount of user memory to be allocated for use by the application for the lifetime of the descriptor.

usrmempp (OUT)

Returns a pointer to the user memory of size xtramem_sz allocated by the call for the user for the lifetime of the descriptor.

Comments

Returns a pointer to an allocated and initialized descriptor, corresponding to the type specified in type. A non-NULL descriptor or LOB locator is returned on success. No diagnostics are available on error.

This call returns OCI_SUCCESS if successful, or OCI_INVALID_HANDLE if an out-of-memory error occurs.

See Also:

For more information about the xtramem_sz parameter and user memory allocation, refer to "User Memory Allocation"

Related Functions

OCIDescriptorFree()

OCIDescriptorFree()

Purpose

Deallocates a previously allocated descriptor.

Syntax

sword OCIDescriptorFree ( dvoid    *descp,
                          ub4      type );

Parameters

descp (IN)

An allocated descriptor.

type (IN)

Specifies the type of storage to be freed. The specific types are:

OCI_DTYPE_SNAP - snapshot descriptor
OCI_DTYPE_LOB - a LOB value type descriptor
OCI_DTYPE_FILE - a FILE value type descriptor
OCI_DTYPE_ROWID - a ROWID descriptor
OCI_DTYPE_DATE - an ANSI DATE descriptor
OCI_DTYPE_PARAM - a parameter descriptor
OCI_DTYPE_TIMESTAMP - a TIMESTAMP descriptor
OCI_DTYPE_TIMESTAMP_TZ - a TIMESTAMP WITH TIME ZONE descriptor
OCI_DTYPE_TIMESTAMP_LTZ - a TIMESTAMP WITH LOCAL TIME ZONE descriptor
OCI_DTYPE_INTERVAL_YM - an INTERVAL YEAR TO MONTH descriptor
OCI_DTYPE_INTERVAL_DS - an INTERVAL DAY TO SECOND descriptor
OCI_DTYPE_COMPLEXOBJECTCOMP - a complex object retrieval descriptor
OCI_DTYPE_AQENQ_OPTIONS - an AQ enqueue options descriptor
OCI_DTYPE_AQDEQ_OPTIONS - an AQ dequeue options descriptor
OCI_DTYPE_AQMSG_PROPERTIES - an AQ message properties descriptor
OCI_DTYPE_AQAGENT - an AQ agent descriptor

Comments

This call frees storage associated with a descriptor. Returns OCI_SUCCESS or OCI_INVALID_HANDLE. All descriptors may be explicitly deallocated, however the OCI will deallocate a descriptor if the environment handle is deallocated.

Related Functions

OCIDescriptorAlloc()

OCIHandleAlloc()

Purpose

This call returns a pointer to an allocated and initialized handle.

Syntax

sword OCIHandleAlloc ( CONST dvoid   *parenth,
                       dvoid         **hndlpp, 
                       ub4           type, 
                       size_t        xtramem_sz,
                       dvoid         **usrmempp );

Parameters

parenth (IN)

An environment handle.

hndlpp (OUT)

Returns a handle.

type (IN)

Specifies the type of handle to be allocated. The allowed types are:

OCI_HTYPE_AUTHINFO - specifies generation of a authentication information handle of C type OCIAuthInfo
OCI_HTYPE_COMPLEXOBJECT - specifies generation of a complex object retrieval handle of C type OCIComplexObject
OCI_HTYPE_SECURITY - specifies generation of a security handle of C type OCISecurity
OCI_HTYPE_CPOOL - specifies generation of a connection pooling handle of C type OCICPool
OCI_HTYPE_DIRPATH_CTX - specifies a generation of a direct path context handle of C type OCIDirPathCtx
OCI_HTYPE_DIRPATH_COLUMN_ARRAY - specifies a generation of a direct path column array handle of C type OCIDirPathColArray
OCI_HTYPE_DIRPATH_STREAM - specifies a generation of a direct path stream handle of C type OCIDirPathStream
OCI_HTYPE_ENV - specifies generation of an environment handle of C type OCIEnv
OCI_HTYPE_ERROR - specifies generation of an error report handle of C type OCIError
OCI_HTYPE_SVCCTX - specifies generation of a service context handle of C type OCISvcCtx
OCI_HTYPE_STMT - specifies generation of a statement (application request) handle of C type OCIStmt
OCI_HTYPE_DESCRIBE - specifies generation of a select list description handle of C type OCIDescribe
OCI_HTYPE_SERVER - specifies generation of a server context handle of C type OCIServer
OCI_HTYPE_SESSION - specifies generation of a user session handle of C type OCISession
OCI_HTYPE_TRANS - specifies generation of a transaction context handle of C type OCITrans
OCI_HTYPE_SPOOL - specifies generation of a session pool handle of type OCISPool
OCI_HTYPE_SUBSCR - specifies a generation of a subscription handle of C type OCISubscription
OCI_HTYPE_PROCESS - specifies a generation of a process handle of C type OCIProcess

xtramem_sz (IN)

Specifies an amount of user memory to be allocated.

usrmempp (OUT)

Returns a pointer to the user memory of size xtramem_sz allocated by the call for the user.

Comments

Returns a pointer to an allocated and initialized handle, corresponding to the type specified in type. A non-NULL handle is returned on success. All handles are allocated with respect to an environment handle which is passed in as a parent handle.

No diagnostics are available on error. This call returns OCI_SUCCESS if successful, or OCI_INVALID_HANDLE if an error occurs.

Handles must be allocated using OCIHandleAlloc() before they can be passed into an OCI call.

To allocate and initialize an environment handle, call OCIEnvInit().

See Also:

For more information about using the xtramem_sz parameter for user memory allocation, refer to "User Memory Allocation"

Related Functions

OCIHandleFree(), OCIEnvInit()

OCIHandleFree()

Purpose

This call explicitly deallocates a handle.

Syntax

sword OCIHandleFree ( dvoid     *hndlp,
                      ub4       type );

Parameters

hndlp (IN)

A handle allocated by OCIHandleAlloc().

type (IN)

Specifies the type of storage to be freed. The specific types are:

OCI_HTYPE_CPOOL - a connection pool handle
OCI_HTYPE_ENV - an environment handle
OCI_HTYPE_ERROR - an error report handle
OCI_HTYPE_SVCCTX - a service context handle
OCI_HTYPE_STMT - a statement (application request) handle
OCI_HTYPE_DESCRIBE - a select list description handle
OCI_HTYPE_SERVER - a server handle
OCI_HTYPE_SESSION - a user session handle
OCI_HTYPE_TRANS - a transaction handle
OCI_HTYPE_COMPLEXOBJECT - a complex object retrieval handle
OCI_HTYPE_SECURITY - a security handle
OCI_HTYPE_SUBSCR - a subscription handle
OCI_HTYPE_DIRPATH_CTX - direct path context handle
OCI_HTYPE_DIRPATH_COLUMN_ARRAY - direct path column array handle
OCI_HTYPE_DIRPATH_STREAM - direct path stream handle
OCI_HTYPE_PROCESS - process handle

Comments

This call frees up storage associated with a handle, corresponding to the type specified in the type parameter.

This call returns either OCI_SUCCESS or OCI_INVALID_HANDLE.

All handles may be explicitly deallocated. The OCI will deallocate a child handle if the parent is deallocated.

Related Functions

OCIHandleAlloc(), OCIEnvInit()

OCIParamGet()

Purpose

Returns a descriptor of a parameter specified by position in the describe handle or statement handle.

Syntax

sword OCIParamGet ( CONST dvoid       *hndlp,
                    ub4               htype,
                    OCIError          *errhp,
                    dvoid             **parmdpp,
                    ub4               pos );

Parameters

hndlp (IN)

A statement handle or describe handle. The OCIParamGet() function will return a parameter descriptor for this handle.

htype (IN)

The type of the handle passed in the hndlp parameter. Valid types are:

OCI_DTYPE_PARAM, for a parameter descriptor
OCI_HTYPE_COMPLEXOBJECT, for a complex object retrieval handle
OCI_HTYPE_STMT, for a statement handle

errhp (IN/OUT)

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

parmdpp (OUT)

A descriptor of the parameter at the position given in the pos parameter, of handle type OCI_DTYPE_PARAM.

pos (IN)

Position number in the statement handle or describe handle. A parameter descriptor will be returned for this position.

Note:

OCI_ERROR is returned if there are no parameter descriptors for this position.

Comments

This call returns a descriptor of a parameter specified by position in the describe handle or statement handle. Parameter descriptors are always allocated internally by the OCI library. They can be freed using OCIDescriptorFree(). For example, if you fetch the same column metadata for every execution of a statement, then the program will leak memory unless you explicitly free the parameter descriptor between each call to OCIParamGet().

See Also:

See Appendix A, "Handle and Descriptor Attributes", for more detailed information about parameter descriptor attributes.

Related Functions

OCIAttrGet(), OCIAttrSet(), OCIParamSet(), OCIDescriptorFree()

OCIParamSet()

Purpose

Used to set a complex object retrieval (COR) descriptor into a COR handle.

Syntax

sword OCIParamSet ( dvoid          *hndlp,
                    ub4            htype,
                    OCIError       *errhp,
                    CONST dvoid    *dscp,
                    ub4            dtyp,
                    ub4            pos );

Parameters

hndlp (IN/OUT)

Handle pointer.

htype (IN)

Handle type.

errhp (IN/OUT)

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

dscp (IN)

Complex object retrieval descriptor pointer.

dtyp (IN)

Descriptor type. The descriptor type for a COR descriptor is OCI_DTYPE_COMPLEXOBJECTCOMP.

pos (IN)

Position number.

Comments

The COR handle must have been previously allocated using OCIHandleAlloc(), and the descriptor must have been previously allocated using OCIDescriptorAlloc(). Attributes of the descriptor are set using OCIAttrSet().

See Also:

For more information about complex object retrieval, see "Complex Object Retrieval".

Related Functions

OCIParamGet()