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