9.22. ODPI-C Variable Functions

Variable handles are used to represent memory areas used for transferring data to and from the database. They are created by calling the function dpiConn_newVar(). They are destroyed when the last reference to the variable is released by calling the function dpiVar_release(). They are bound to statements by calling the function dpiStmt_bindByName() or the function dpiStmt_bindByPos(). They can also be used for fetching data from the database by calling the function dpiStmt_define().

int dpiVar_addRef(dpiVar *var)

Adds a reference to the variable. This is intended for situations where a reference to the variable needs to be maintained independently of the reference returned when the variable was created.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
var	IN	The variable to which a reference is to be added. If the reference is NULL or invalid, an error is returned.

int dpiVar_copyData(dpiVar *var, uint32_t pos, dpiVar *sourceVar, uint32_t sourcePos)

Copies the data from one variable to another variable.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
var	IN	The variable into which data is to be copied. If the reference is NULL or invalid, an error is returned.
pos	IN	The array position into which the data is to be copied. The first position is 0. If the array position specified exceeds the number of elements allocated in the variable, an error is returned.
sourceVar	IN	The variable from which is to be copied. If the reference is NULL or invalid, an error is returned.
sourcePos	IN	The array position from which the data is to be copied. The first position is 0. If the array position specified exceeds the number of elements allocated in the source variable, an error is returned.

int dpiVar_getNumElementsInArray(dpiVar *var, uint32_t *numElements)

Returns the number of elements in a PL/SQL index-by table if the variable was created as an array by the function dpiConn_newVar(). If the variable is one of the output bind variables of a DML returning statement, however, the value returned will correspond to the number of rows returned by the DML returning statement. In all other cases, the value returned will be the number of elements the variable was created with.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
var	IN	A reference to the variable from which the number of elements is to be retrieved. If the reference is NULL or invalid, an error is returned.
numElements	OUT	A pointer to the number of elements, which will be populated when the function completes successfully.

int dpiVar_getReturnedData(dpiVar *var, uint32_t pos, uint32_t *numElements, dpiData **data)

Returns a pointer to an array of dpiData structures used for transferring data to and from the database. These structures are allocated by the variable itself when a DML returning statement is executed and the variable is bound.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
var	IN	A reference to the variable which contains the data structures used for transferring data to and from the database. If the reference is NULL or invalid, an error is returned.
pos	IN	The array position in the variable from which returned data is to be determined. The first position is 0. If the position exceeds the number of elements allocated by the variable an error is returned.
numElements	OUT	A pointer to the number of elements that have been allocated by the variable, which will be populated when the function completes successfully. The value 0 is returned if the statement is not a DML returning statement or the statement returned no data.
data	OUT	A pointer to an array of dpiData structures which will be populated when the function completes successfully. A NULL value is returned if the statement is not a DML returning statement or the statement returned no data.

int dpiVar_getSizeInBytes(dpiVar *var, uint32_t *sizeInBytes)

Returns the size of the buffer used for one element of the array used for fetching/binding Oracle data.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
var	IN	A reference to the variable whose buffer size is to be retrieved. If the reference is NULL or invalid, an error is returned.
sizeInBytes	OUT	A pointer to the size of the buffer, in bytes, which will be populated when the function completes successfully.

int dpiVar_release(dpiVar *var)

Releases a reference to the variable. A count of the references to the variable is maintained and when this count reaches zero, the memory associated with the variable is freed.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
var	IN	The variable from which a reference is to be released. If the reference is NULL or invalid, an error is returned.

int dpiVar_setFromBytes(dpiVar *var, uint32_t pos, const char *value, uint32_t valueLength)

Sets the variable value to the specified byte string. In the case of the variable’s Oracle type being DPI_ORACLE_TYPE_NUMBER, the byte string is converted to an Oracle number during the call to this function.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
var	IN	A reference to the variable which should be set. If the reference is null or invalid, an error is returned. If the variable does not use native type DPI_NATIVE_TYPE_BYTES or DPI_NATIVE_TYPE_LOB, an error is returned.
pos	IN	The array position in the variable which is to be set. The first position is 0. If the position exceeds the number of elements allocated by the variable an error is returned.
value	IN	A pointer to the byte string which contains the data to be set. The data is copied to the variable buffer and does not need to be retained after this function call has completed. This value can be NULL if the valueLength parameter is 0.
valueLength	IN	The length of the data to be set, in bytes. The maximum value permitted is 2 bytes less than 1 GB (1,073,741,822 bytes).

int dpiVar_setFromJson(dpiVar *var, uint32_t pos, dpiJson *json)

Sets the variable value to the specified JSON value.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
var	IN	A reference to the variable which should be set. If the reference is null or invalid, an error is returned. If the variable does not use native type DPI_NATIVE_TYPE_JSON, an error is returned.
pos	IN	The array position in the variable which is to be set. The first position is 0. If the position exceeds the number of elements allocated by the variable an error is returned.
json	IN	A reference to the JSON value which should be set. If the reference is null or invalid, an error is returned. A reference is retained by the variable until a new value is set or the variable itself is freed.

int dpiVar_setFromLob(dpiVar *var, uint32_t pos, dpiLob *lob)

Sets the variable value to the specified LOB.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
var	IN	A reference to the variable which should be set. If the reference is null or invalid, an error is returned.
pos	IN	The array position in the variable which is to be set. The first position is 0. If the position exceeds the number of elements allocated by the variable an error is returned.
lob	IN	A reference to the LOB which should be set. If the reference is null or invalid, an error is returned. A reference is retained by the variable until a new value is set or the variable itself is freed.

int dpiVar_setFromObject(dpiVar *var, uint32_t pos, dpiObject *obj)

Sets the variable value to the specified object.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
var	IN	A reference to the variable which should be set. If the reference is null or invalid, an error is returned.
pos	IN	The array position in the variable which is to be set. The first position is 0. If the position exceeds the number of elements allocated by the variable an error is returned.
obj	IN	A reference to the object which should be set. If the reference is null or invalid, an error is returned. A reference is retained by the variable until a new value is set or the variable itself is freed.

int dpiVar_setFromRowid(dpiVar *var, uint32_t pos, dpiRowid *rowid)

Sets the variable value to the specified rowid.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
var	IN	A reference to the variable which should be set. If the reference is null or invalid, an error is returned.
pos	IN	The array position in the variable which is to be set. The first position is 0. If the position exceeds the number of elements allocated by the variable an error is returned.
rowid	IN	A reference to the rowid which should be set. If the reference is null or invalid, an error is returned. A reference is retained by the variable until a new value is set or the variable itself is freed.

int dpiVar_setFromStmt(dpiVar *var, uint32_t pos, dpiStmt *stmt)

Sets the variable value to the specified statement.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
var	IN	A reference to the variable which should be set. If the reference is null or invalid, an error is returned.
pos	IN	The array position in the variable which is to be set. The first position is 0. If the position exceeds the number of elements allocated by the variable an error is returned.
stmt	IN	A reference to the statement which should be set. If the reference is null or invalid, an error is returned. A reference is retained by the variable until a new value is set or the variable itself is freed.

int dpiVar_setNumElementsInArray(dpiVar *var, uint32_t numElements)

Sets the number of elements in a PL/SQL index-by table.

The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

Parameter	Mode	Description
var	IN	A reference to the variable in which the number of elements is to be set. If the reference is NULL or invalid, an error is returned.
numElements	IN	The number of elements that PL/SQL should consider part of the array. This number should not exceed the number of elements that have been allocated in the variable.