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

Example

The following sample code shows OCIHandleAlloc() being used to allocate a variety of handles at the beginning of an application:

OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &errhp, (ub4) 
     OCI_HTYPE_ERROR, 0, (dvoid **) &tmp);
OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &srvhp, (ub4) 
     OCI_HTYPE_SERVER, 0, (dvoid **) &tmp);
OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &svchp, (ub4) 
     OCI_HTYPE_SVCCTX, 0, (dvoid **) &tmp);

Related Functions

OCIHandleFree(), OCIEnvInit()