Handle and descriptor functions|V1.2.0|OceanBase Call Interface| docs|Distributed Database

#docslug#/obci/obci/V1.2.0/vryn9e

OCIAttrGet

Purpose : You can call this function to retrieve an attribute value of a handle.

Function syntax :

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

Parameters :

Parameter	Description
trgthndlp(IN)	The pointer to the handle whose attribute is to be retrieved.
trghndltyp(IN)	The handle type. For supported handle types, see the handle attribute table in the Description section.
attributep(OUT)	The buffer that stores the output attributes.
size(OUT)	The buffer that stores the size of an attribute value.
attrtype(IN)	The type of the attribute to be retrieved.
errhp(IN)	An error handle.

Return value : OCI_SUCCESS is returned if the function call succeeded, or OCI_ERROR is returned if the function call failed.

Description : The following table describes the handles and their attributes that can be retrieved by using an OCIAttrGet() call.

Handle	Handle description	Attribute	Attribute description
OCI_HTYPE_SVCCTX	A context handle.	OCI_ATTR_SERVER	Returns the pointer to the server context attribute when this attribute is read. Sets the server context attribute when this attribute is modified.
OCI_HTYPE_SVCCTX	A context handle.	OCI_ATTR_SESSION	Returns the pointer to the authentication context attribute when this attribute is read. Sets the authentication context attribute when this attribute is modified.
OCI_HTYPE_SVCCTX	A context handle.	OCI_ATTR_TRANS	Returns the pointer to the transaction context attribute when this attribute is read. Sets the transaction context attribute when this attribute is modified.
OCI_HTYPE_SESSION	A session handle.	OCI_ATTR_USERNAME	Specifies the client certificate for proxy authentication.
OCI_HTYPE_STMT	A statement handle.	OCI_ATTR_ROW_COUNT	Returns the number of rows converted after the OCIDirPathColArrayToStream() function is called.
OCI_HTYPE_STMT	A statement handle.	OCI_ATTR_CURRENT_POSITION	Indicates the current position in the result set. This attribute can only be retrieved and cannot be configured.
OCI_HTYPE_STMT	A statement handle.	OCI_ATTR_ROWS_FETCHED	Indicates the number of rows that were fetched into the user buffers in the last fetch or the number of rows executed in non-zero iterations. This attribute can be used for both scrollable and nonscrollable statement handles.
OCI_HTYPE_STMT	A statement handle.	OCI_ATTR_PARAM_COUNT	Returns the number of parameters in the describe handle.
OCI_HTYPE_STMT	A statement handle.	OCI_ATTR_NUM_DML_ERRORS	Returns the number of errors occurred in the DML operation.
OCI_HTYPE_STMT	A statement handle.	OCI_ATTR_ROWID	Returns the ROWID descriptor allocated to the OCIDescriptorAlloc() function.
OCI_DTYPE_PARAM	A parameter descriptor handle.	OCI_ATTR_DATA_TYPE	Returns or sets the external data type of the column.
OCI_DTYPE_PARAM	A parameter descriptor handle.	OCI_ATTR_CHAR_SIZE	Returns the character length of the column, which is the number of characters allowed in the column.
OCI_DTYPE_PARAM	A parameter descriptor handle.	OCI_ATTR_CHARSET_ID	The character set ID.
OCI_DTYPE_PARAM	A parameter descriptor handle.	OCI_ATTR_DATA_SIZE	The maximum length of the column. The length is in bytes instead of character strings or original characters.
OCI_DTYPE_PARAM	A parameter descriptor handle.	OCI_ATTR_PRECISION	Returns or sets the precision.
OCI_DTYPE_PARAM	A parameter descriptor handle.	OCI_ATTR_SCALE	Returns or sets the number of digits to the right of the decimal point.
OCI_DTYPE_PARAM	A parameter descriptor handle.	OCI_ATTR_NAME	Indicates the name of the table to be loaded.
OCI_DTYPE_PARAM	A parameter descriptor handle.	OCI_ATTR_IS_NULL	Returns 0 if the column value cannot be NULL.
OCI_HTYPE_ERROR	An error handle.	OCI_ATTR_DML_ROW_OFFSET	Returns the offset at which the error occurred.

OCIAttrSet

Purpose : You can call this function to set an attribute for a handle.

Function syntax :

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

Parameters :

Parameter	Description
trgthndlp(IN)	The pointer to the handle whose attribute needs to be set.
trghndltyp(IN)	The type of the handle whose attribute needs to be set. For supported handle types, see the handle attribute table in the Description section.
attributep(IN)	The pointer to the attribute that needs to be set.
size(IN)	The size of the attributep parameter.
attrtype(IN)	The type of the attribute that needs to be set.
errhp(IN)	An error handle.

Return value : OCI_SUCCESS is returned if the function call succeeded, or OCI_ERROR is returned if the function call failed.

Description : The following table describes the handles and their attributes that can be set by using an OCIAttrSet() call.

Handle	Handle description	Attribute	Attribute description
OCI_HTYPE_SVCCTX	A context handle.	OCI_ATTR_SERVER	Returns the pointer to the server context attribute when this attribute is read. Sets the server context attribute when this attribute is modified.
OCI_HTYPE_SVCCTX	A context handle.	OCI_ATTR_SESSION	Returns the pointer to the authentication context attribute when this attribute is read. Sets the authentication context attribute when this attribute is modified.
OCI_HTYPE_SVCCTX	A context handle.	OCI_ATTR_TRANS	Returns the pointer to the transaction context attribute when this attribute is read. Sets the transaction context attribute when this attribute is modified.
OCI_HTYPE_SESSION	A session handle.	OCI_ATTR_USERNAME	Specifies the client certificate for proxy authentication.
OCI_HTYPE_SESSION	A session handle.	OCI_ATTR_PASSWORD	Specifies the password for authentication.
OCI_HTYPE_STMT	A statement handle.	OCI_ATTR_PREFETCH_MEMORY	Sets the memory level for top-level rows to be prefetched.
OCI_HTYPE_STMT	A statement handle.	OCI_ATTR_PREFETCH_ROWS	Sets the number of top-level rows to be prefetched. The default value is 1.
OCI_HTYPE_STMT	A statement handle.	OCI_ATTR_FETCH_ROWID	Specifies the ROWID.
OCI_HTYPE_BIND	A parameter bind handle.	OCI_ATTR_MAXDATA_SIZE	Sets the maximum number of bytes allowed in the server buffer to accommodate the client bind data after a character set conversion.
OCI_HTYPE_BIND	A parameter bind handle.	OCI_ATTR_CHARSET_FORM	The character set form of the define handle.
OCI_HTYPE_BIND	A parameter bind handle.	OCI_ATTR_CHARSET_ID	The character set ID of the define handle.
OCI_DTYPE_LOB	A large object (LOB) locator.	OCI_ATTR_LOBEMPTY	Sets the internal LOB locator to empty. Then, the locator can be used as a bind variable of an `INSERT` or `UPDATE`, to initialize the LOB to empty.
OCI_HTYPE_TRANS	A transaction handle.	OCI_ATTR_XID	Sets or reads the transaction ID (XID) that identifies a transaction.

OCIDescriptorAlloc

Purpose : You can call this function to allocate storage to hold descriptors or LOB locators

Function syntax :

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

Parameters :

Parameter	Description
parenth(IN)	An environment handle.
descpp(OUT)	A pointer to a descriptor or an LOB locator.
type(IN)	The type of the descriptor. For supported types, see the descriptor table in the Description section.
xtramem_sz(IN)	The amount of extra memory to be allocated.
usrmempp(IN)	Returns the address of the extra memory allocated.

Return value : OCI_SUCCESS is returned if the function call succeeded, or OCI_ERROR is returned if the function call failed.

Description : The following table describes the descriptors that the OCIDescriptorAlloc() function supports.

Descriptor	Description
OCI_DTYPE_LOB	An LOB locator.
OCI_DTYPE_TIME	A TIME descriptor.
OCI_DTYPE_TIMESTAMP	A `TIMESTAMP` descriptor.
OCI_DTYPE_TIMESTAMP_LTZ	A `TIMESTAMP WITH LOCAL TIME ZONE` descriptor.
OCI_DTYPE_TIMESTAMP_TZ	A `TIMESTAMP WITH TIME ZONE` descriptor.
OCI_DTYPE_DATE	A DATE descriptor.
OCI_DTYPE_ROWID	A `ROWID` descriptor.

OCIDescriptorFree

Purpose : You can call this function to release a descriptor allocated by using the OCIDescriptorAlloc() function.

Function syntax :

sword OCIArrayDescriptorFree ( void **descp,
const ub4 type );

Parameters :

Parameter	Description
descp(IN)	The pointer to an allocated descriptor.
type(IN)	The type of the descriptor. For supported types, see the descriptor table in the Description section.

Return value : OCI_SUCCESS is returned if the function call succeeded, or OCI_ERROR is returned if the function call failed.

Description : The following table describes the descriptors that the OCIArrayDescriptorFree() function supports.

Descriptor	Description
OCI_DTYPE_LOB	An LOB locator.
OCI_DTYPE_TIME	A TIME descriptor.
OCI_DTYPE_TIMESTAMP	A `TIMESTAMP` descriptor.
OCI_DTYPE_TIMESTAMP_LTZ	A `TIMESTAMP WITH LOCAL TIME ZONE` descriptor.
OCI_DTYPE_TIMESTAMP_TZ	A `TIMESTAMP WITH TIME ZONE` descriptor.
OCI_DTYPE_DATE	A DATE descriptor.
OCI_DTYPE_ROWID	A `ROWID` descriptor.
OCI_DTYPE_PARAM	A parameter descriptor.

OCIHandleAlloc

Purpose : You can call this function to allocate and initialize handles.

Function syntax :

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

Parameters :

Parameter	Description
parentth(IN)	An environment handle.
hndlpp(OUT)	A pointer to the handle.
type(IN)	The type of the handle. For supported handle types, see the handle table in the Description section.
xtramem_sz(IN)	The amount of extra memory to be allocated.
usrmempp(IN)	Returns the address of the extra memory allocated.

Return value : OCI_SUCCESS is returned if the function call succeeded, or OCI_ERROR is returned if the function call failed.

Description : The following table describes the handles that can be allocated by using the OCIHandleAlloc() function.

Handle	Description
OCI_HTYPE_ERROR	An error handle.
OCI_HTYPE_SVCCTX	A context handle.
OCI_HTYPE_STMT	A statement handle.
OCI_HTYPE_SERVER	A server handle.
OCI_HTYPE_SESSION	A session handle.
OCI_HTYPE_TRANS	A transaction handle.
OCI_HTYPE_BIND	A parameter bind handle.
OCI_HTYPE_DEFINE	A column bind handle.

OCIHandleFree

Purpose : You can call this function to release handles allocated by using the OCIHandleAlloc() function.

Function syntax :

sword OCIHandleFree ( dvoid *hndlp,
ub4 type );

Parameters :

Parameter	Description
hndlp(IN)	A pointer to the handle.
type(IN)	The type of the handle. For supported handle types, see the handle table in the Description section.

Return value : OCI_SUCCESS is returned if the function call succeeded, or OCI_ERROR is returned if the function call failed.

Description : The following table describes the handles that can be allocated by using the OCIHandleFree() function.

Handle	Description
OCI_HTYPE_ERROR	An error handle.
OCI_HTYPE_SVCCTX	A context handle.
OCI_HTYPE_STMT	A statement handle.
OCI_HTYPE_SERVER	A server handle.
OCI_HTYPE_SESSION	A session handle.
OCI_HTYPE_TRANS	A transaction handle.
OCI_HTYPE_BIND	A parameter bind handle.
OCI_HTYPE_DEFINE	A column bind handle.
OCI_HTYPE_ENV	An environment handle.

OCIParamGet

Purpose : You can call this function to get a descriptor handle at a specified position.

Function syntax :

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

Parameters :

Parameter	Description
hndlp(IN)	A handle that contains description information.
htype(IN)	The type of the handle specified by the `hndlp` parameter. For supported handle types, see the handle table in the Description section.
errhp(IN)	An error handle.
parmdpp(OUT)	A handle of the output descriptor.
pos(IN)	The position in the descriptor from which the description information is to be retrieved.

Return value : OCI_SUCCESS is returned if the function call succeeded, or OCI_ERROR is returned if the function call failed.

Description : The following table describes the parameter handles that can be retrieved by using an OCIParamGet() call.

Handle	Description
OCI_HTYPE_STMT	A statement handle.
OCI_DTYPE_PARAM	A parameter handle.