Detailed Description

OcilibCApiPlSql

OCILIB supports all Oracle collections:

PL/SQL Tables: Only available in PL/SQL, unbounded, sparse arrays of homogeneous elements.
VARRAYS : Available in SQL and PL/SQL, bounded arrays of homogeneous elements.
Nested Tables: Available in SQL and PL/SQL, unbounded arrays of homogeneous elements that can become sparse through deletions.

PL/SQL tables are implemented by binding regular C arrays with the array interface (using OCI_BindArrayOfXXX() calls).

VARRAYS and Nested Tables are implemented in OCILIB with the type OCI_Coll. It is possible to bind and fetch VARRAYS and Nested Tables using OCI_Coll handles.

It is also possible to declare local collections based on a database type without using queries.

OCI (and thus OCILIB) offers the ability to access collection elements:

Directly by index (OCI_CollGetElem() and OCI_CollSetElem()).
Using an iterator (OCI_Iter) to iterate through the collection (OCI_IterGetNext(), OCI_IterGetPrev()).

Collection items are implemented through the type OCI_Elem and use the series of calls OCI_ElemGetXXX() and OCI_ElemSetXXX() to manipulate element content values.

Example: #include "ocilib.h"

/* requires script demo/collections.sql */

void err_handler(OCI_Error *err)

{

printf("%s\n", OCI_ErrorGetString(err));

}

void print_elem(OCI_Object *product)

{

printf("...product: code %d, %s\n", OCI_ObjectGetInt(product, "code"), OCI_ObjectGetString(product, "name"));

}

void print_coll(OCI_Coll *coll)

{

OCI_Iter *iter = OCI_IterCreate(coll);

OCI_Elem *elem = OCI_IterGetNext(iter);

while (elem)

{

print_elem(OCI_ElemGetObject(elem));

elem = OCI_IterGetNext(iter);

}

OCI_IterFree(iter);

}

void bind_coll(OCI_Connection *cn)

{

OCI_Coll *coll = OCI_CollCreate(OCI_TypeInfoGet(cn, "product_varray_t", OCI_TIF_TYPE));

OCI_Statement *st = OCI_StatementCreate(cn);

OCI_Prepare(st, "begin :array := product_varray_t(product_t(123, 'name 123'), product_t(456, 'name 456'), product_t(789, 'name 789')); end;");

OCI_BindColl(st, ":array", coll);

OCI_Execute(st);

print_coll(coll);

OCI_CollFree(coll);

OCI_StatementFree(st);

}

void fetch_coll(OCI_Connection *cn, otext * table_name)

{

OCI_Statement *st = OCI_StatementCreate(cn);

OCI_Resultset *rs = NULL;

OCI_ExecuteStmtFmt(st, "SELECT * from %m", table_name);

rs = OCI_GetResultset(st);

while (OCI_FetchNext(rs))

{

printf("#%s\n", OCI_GetString(rs, 1));

print_coll(OCI_GetColl(rs, 2));

}

OCI_StatementFree(st);

}

int main(void)

{

OCI_Connection *cn;

if (!OCI_Initialize(err_handler, NULL, OCI_ENV_DEFAULT))

{

return EXIT_FAILURE;

}

cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);

bind_coll(cn);

fetch_coll(cn, "products_varray");

fetch_coll(cn, "products_nested_table");

OCI_ConnectionFree(cn);

OCI_Cleanup();

return EXIT_SUCCESS;

}

OCI_BindColl
OCI_SYM_PUBLIC boolean OCI_API OCI_BindColl(OCI_Statement *stmt, const otext *name, OCI_Coll *data)
Bind a Collection variable.

OCI_IterCreate
OCI_SYM_PUBLIC OCI_Iter *OCI_API OCI_IterCreate(OCI_Coll *coll)
Create an iterator handle to iterate through a collection.

OCI_CollFree
OCI_SYM_PUBLIC boolean OCI_API OCI_CollFree(OCI_Coll *coll)
Free a local collection.

OCI_IterFree
OCI_SYM_PUBLIC boolean OCI_API OCI_IterFree(OCI_Iter *iter)
Free an iterator handle.

OCI_IterGetNext
OCI_SYM_PUBLIC OCI_Elem *OCI_API OCI_IterGetNext(OCI_Iter *iter)
Get the next element in the collection.

OCI_ElemGetObject
OCI_SYM_PUBLIC OCI_Object *OCI_API OCI_ElemGetObject(OCI_Elem *elem)
Return the object value of the given collection element.

OCI_CollCreate
OCI_SYM_PUBLIC OCI_Coll *OCI_API OCI_CollCreate(OCI_TypeInfo *typinf)
Create a local collection instance.

OCI_ConnectionFree
OCI_SYM_PUBLIC boolean OCI_API OCI_ConnectionFree(OCI_Connection *con)
Close a physical connection to an Oracle database server.

OCI_ConnectionCreate
OCI_SYM_PUBLIC OCI_Connection *OCI_API OCI_ConnectionCreate(const otext *db, const otext *user, const otext *pwd, unsigned int mode)
Create a physical connection to an Oracle database server.

OCI_Elem
struct OCI_Elem OCI_Elem
Oracle Collection item representation.
Definition: types.h:329

OCI_Connection
struct OCI_Connection OCI_Connection
Oracle physical connection.
Definition: types.h:124

OCI_Object
struct OCI_Object OCI_Object
Oracle Named types representation.
Definition: types.h:309

OCI_Statement
struct OCI_Statement OCI_Statement
Oracle SQL or PL/SQL statement.
Definition: types.h:136

OCI_Coll
struct OCI_Coll OCI_Coll
Oracle Collections (VARRAYs and Nested Tables) representation.
Definition: types.h:319

OCI_Error
struct OCI_Error OCI_Error
Encapsulates an Oracle or OCILIB exception.
Definition: types.h:410

OCI_Resultset
struct OCI_Resultset OCI_Resultset
Collection of output columns from a select statement.
Definition: types.h:163

OCI_Iter
struct OCI_Iter OCI_Iter
Oracle Collection iterator representation.
Definition: types.h:338

OCI_ErrorGetString
OCI_SYM_PUBLIC const otext *OCI_API OCI_ErrorGetString(OCI_Error *err)
Retrieve the error message string from an error handle.

OCI_FetchNext
OCI_SYM_PUBLIC boolean OCI_API OCI_FetchNext(OCI_Resultset *rs)
Fetch the next row of the result set.

OCI_GetString
OCI_SYM_PUBLIC const otext *OCI_API OCI_GetString(OCI_Resultset *rs, unsigned int index)
Return the current string value of the column at the given index in the result set.

OCI_GetResultset
OCI_SYM_PUBLIC OCI_Resultset *OCI_API OCI_GetResultset(OCI_Statement *stmt)
Retrieve the result set handle from an executed statement.

OCI_GetColl
OCI_SYM_PUBLIC OCI_Coll *OCI_API OCI_GetColl(OCI_Resultset *rs, unsigned int index)
Return the current Collection value of the column at the given index in the result set.

OCI_ExecuteStmtFmt
OCI_SYM_PUBLIC boolean OCI_ExecuteStmtFmt(OCI_Statement *stmt, const otext *sql,...)
Execute a formatted SQL statement or PL/SQL block.

OCI_Cleanup
OCI_SYM_PUBLIC boolean OCI_API OCI_Cleanup(void)
Clean up all resources allocated by the library.

OCI_Initialize
OCI_SYM_PUBLIC boolean OCI_API OCI_Initialize(POCI_ERROR err_handler, const otext *lib_path, unsigned int mode)
Initialize the library.

OCI_TypeInfoGet
OCI_SYM_PUBLIC OCI_TypeInfo *OCI_API OCI_TypeInfoGet(OCI_Connection *con, const otext *name, unsigned int type)
Retrieve the available type info information.

OCI_StatementCreate
OCI_SYM_PUBLIC OCI_Statement *OCI_API OCI_StatementCreate(OCI_Connection *con)
Create a statement object and return its handle.

OCI_StatementFree
OCI_SYM_PUBLIC boolean OCI_API OCI_StatementFree(OCI_Statement *stmt)
Free a statement and all resources associated with it (result sets, bind variables,...

OCI_Prepare
OCI_SYM_PUBLIC boolean OCI_API OCI_Prepare(OCI_Statement *stmt, const otext *sql)
Prepare a SQL statement or PL/SQL block.

OCI_Execute
OCI_SYM_PUBLIC boolean OCI_API OCI_Execute(OCI_Statement *stmt)
Execute a prepared SQL statement or PL/SQL block.

OCI_ObjectGetInt
OCI_SYM_PUBLIC int OCI_API OCI_ObjectGetInt(OCI_Object *obj, const otext *attr)
Return the integer value of the given object attribute.

OCI_ObjectGetString
OCI_SYM_PUBLIC const otext *OCI_API OCI_ObjectGetString(OCI_Object *obj, const otext *attr)
Return the string value of the given object attribute.

Functions
OCI_SYM_PUBLIC OCI_Coll *OCI_API	OCI_CollCreate (OCI_TypeInfo *typinf)
	Create a local collection instance.

OCI_SYM_PUBLIC boolean OCI_API	OCI_CollFree (OCI_Coll *coll)
	Free a local collection.

OCI_SYM_PUBLIC OCI_Coll **OCI_API	OCI_CollArrayCreate (OCI_Connection con, OCI_TypeInfo typinf, unsigned int nbelem)
	Create an array of Collection objects.

OCI_SYM_PUBLIC boolean OCI_API	OCI_CollArrayFree (OCI_Coll **colls)
	Free an array of Collection objects.

OCI_SYM_PUBLIC boolean OCI_API	OCI_CollAssign (OCI_Coll coll, OCI_Coll coll_src)
	Assign a collection to another one.

OCI_SYM_PUBLIC OCI_TypeInfo *OCI_API	OCI_CollGetTypeInfo (OCI_Coll *coll)
	Return the type info object associated with the collection.

OCI_SYM_PUBLIC unsigned int OCI_API	OCI_CollGetType (OCI_Coll *coll)
	Return the collection type.

OCI_SYM_PUBLIC unsigned int OCI_API	OCI_CollGetMax (OCI_Coll *coll)
	Return the maximum number of elements of the given collection.

OCI_SYM_PUBLIC unsigned int OCI_API	OCI_CollGetSize (OCI_Coll *coll)
	Return the total number of elements of the given collection.

OCI_SYM_PUBLIC unsigned int OCI_API	OCI_CollGetCount (OCI_Coll *coll)
	Return the current number of elements of the given collection.

OCI_SYM_PUBLIC boolean OCI_API	OCI_CollTrim (OCI_Coll *coll, unsigned int nb_elem)
	Trims the given number of elements from the end of the collection.

OCI_SYM_PUBLIC boolean OCI_API	OCI_CollClear (OCI_Coll *coll)
	Clear all items of the given collection.

OCI_SYM_PUBLIC OCI_Elem *OCI_API	OCI_CollGetElem (OCI_Coll *coll, unsigned int index)
	Return the element at the given position in the collection.

OCI_SYM_PUBLIC boolean OCI_API	OCI_CollGetElem2 (OCI_Coll coll, unsigned int index, OCI_Elem elem)
	Return the element at the given position in the collection.

OCI_SYM_PUBLIC boolean OCI_API	OCI_CollSetElem (OCI_Coll coll, unsigned int index, OCI_Elem elem)
	Assign the given element value to the element at the given position in the collection.

OCI_SYM_PUBLIC boolean OCI_API	OCI_CollAppend (OCI_Coll coll, OCI_Elem elem)
	Append the given element at the end of the collection.

OCI_SYM_PUBLIC boolean OCI_API	OCI_CollToText (OCI_Coll coll, unsigned int size, otext *str)
	Convert a collection handle value to a string.

OCI_SYM_PUBLIC boolean OCI_API	OCI_CollDeleteElem (OCI_Coll *coll, unsigned int index)
	Delete the element at the given position in the Nested Table Collection.

OCI_SYM_PUBLIC OCI_Iter *OCI_API	OCI_IterCreate (OCI_Coll *coll)
	Create an iterator handle to iterate through a collection.

OCI_SYM_PUBLIC boolean OCI_API	OCI_IterFree (OCI_Iter *iter)
	Free an iterator handle.

OCI_SYM_PUBLIC OCI_Elem *OCI_API	OCI_IterGetNext (OCI_Iter *iter)
	Get the next element in the collection.

OCI_SYM_PUBLIC OCI_Elem *OCI_API	OCI_IterGetPrev (OCI_Iter *iter)
	Get the previous element in the collection.

OCI_SYM_PUBLIC OCI_Elem *OCI_API	OCI_IterGetCurrent (OCI_Iter *iter)
	Get the current element in the collection.

OCI_SYM_PUBLIC OCI_Elem *OCI_API	OCI_ElemCreate (OCI_TypeInfo *typinf)
	Create a local collection element instance based on a collection type descriptor.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemFree (OCI_Elem *elem)
	Free a local collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemGetBoolean (OCI_Elem *elem)
	Return the boolean value of the given collection element.

OCI_SYM_PUBLIC OCI_Number *OCI_API	OCI_ElemGetNumber (OCI_Elem *elem)
	Return the Number value of the given collection element.

OCI_SYM_PUBLIC short OCI_API	OCI_ElemGetShort (OCI_Elem *elem)
	Return the short value of the given collection element.

OCI_SYM_PUBLIC unsigned short OCI_API	OCI_ElemGetUnsignedShort (OCI_Elem *elem)
	Return the unsigned short value of the given collection element.

OCI_SYM_PUBLIC int OCI_API	OCI_ElemGetInt (OCI_Elem *elem)
	Return the int value of the given collection element.

OCI_SYM_PUBLIC unsigned int OCI_API	OCI_ElemGetUnsignedInt (OCI_Elem *elem)
	Return the unsigned int value of the given collection element.

OCI_SYM_PUBLIC big_int OCI_API	OCI_ElemGetBigInt (OCI_Elem *elem)
	Return the big int value of the given collection element.

OCI_SYM_PUBLIC big_uint OCI_API	OCI_ElemGetUnsignedBigInt (OCI_Elem *elem)
	Return the unsigned big int value of the given collection element.

OCI_SYM_PUBLIC double OCI_API	OCI_ElemGetDouble (OCI_Elem *elem)
	Return the Double value of the given collection element.

OCI_SYM_PUBLIC float OCI_API	OCI_ElemGetFloat (OCI_Elem *elem)
	Return the float value of the given collection element.

OCI_SYM_PUBLIC const otext *OCI_API	OCI_ElemGetString (OCI_Elem *elem)
	Return the String value of the given collection element.

OCI_SYM_PUBLIC unsigned int OCI_API	OCI_ElemGetRaw (OCI_Elem elem, void value, unsigned int len)
	Read the RAW value of the collection element into the given buffer.

OCI_SYM_PUBLIC unsigned int OCI_API	OCI_ElemGetRawSize (OCI_Elem *elem)
	Return the raw attribute value size of the given element handle.

OCI_SYM_PUBLIC OCI_Date *OCI_API	OCI_ElemGetDate (OCI_Elem *elem)
	Return the Date value of the given collection element.

OCI_SYM_PUBLIC OCI_Timestamp *OCI_API	OCI_ElemGetTimestamp (OCI_Elem *elem)
	Return the Timestamp value of the given collection element.

OCI_SYM_PUBLIC OCI_Interval *OCI_API	OCI_ElemGetInterval (OCI_Elem *elem)
	Return the Interval value of the given collection element.

OCI_SYM_PUBLIC OCI_Lob *OCI_API	OCI_ElemGetLob (OCI_Elem *elem)
	Return the Lob value of the given collection element.

OCI_SYM_PUBLIC OCI_File *OCI_API	OCI_ElemGetFile (OCI_Elem *elem)
	Return the File value of the given collection element.

OCI_SYM_PUBLIC OCI_Object *OCI_API	OCI_ElemGetObject (OCI_Elem *elem)
	Return the object value of the given collection element.

OCI_SYM_PUBLIC OCI_Coll *OCI_API	OCI_ElemGetColl (OCI_Elem *elem)
	Return the collection value of the given collection element.

OCI_SYM_PUBLIC OCI_Ref *OCI_API	OCI_ElemGetRef (OCI_Elem *elem)
	Return the Ref value of the given collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetBoolean (OCI_Elem *elem, boolean value)
	Set a boolean value to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetNumber (OCI_Elem elem, OCI_Number value)
	Set a number value to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetShort (OCI_Elem *elem, short value)
	Set a short value to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetUnsignedShort (OCI_Elem *elem, unsigned short value)
	Set an unsigned short value to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetInt (OCI_Elem *elem, int value)
	Set an int value to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetUnsignedInt (OCI_Elem *elem, unsigned int value)
	Set an unsigned int value to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetBigInt (OCI_Elem *elem, big_int value)
	Set a big int value to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetUnsignedBigInt (OCI_Elem *elem, big_uint value)
	Set an unsigned big int value to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetDouble (OCI_Elem *elem, double value)
	Set a double value to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetFloat (OCI_Elem *elem, float value)
	Set a float value to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetString (OCI_Elem elem, const otext value)
	Set a string value to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetRaw (OCI_Elem elem, void value, unsigned int len)
	Set a RAW value to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetDate (OCI_Elem elem, OCI_Date value)
	Assign a Date handle to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetTimestamp (OCI_Elem elem, OCI_Timestamp value)
	Assign a Timestamp handle to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetInterval (OCI_Elem elem, OCI_Interval value)
	Assign an Interval handle to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetColl (OCI_Elem elem, OCI_Coll value)
	Assign a Collection handle to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetObject (OCI_Elem elem, OCI_Object value)
	Assign an Object handle to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetLob (OCI_Elem elem, OCI_Lob value)
	Assign a Lob handle to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetFile (OCI_Elem elem, OCI_File value)
	Assign a File handle to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetRef (OCI_Elem elem, OCI_Ref value)
	Assign a Ref handle to a collection element.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemIsNull (OCI_Elem *elem)
	Check if the collection element value is null.

OCI_SYM_PUBLIC boolean OCI_API	OCI_ElemSetNull (OCI_Elem *elem)
	Set a collection element value to null.

Function Documentation

◆ OCI_CollCreate()

OCI_SYM_PUBLIC OCI_Coll *OCI_API OCI_CollCreate ( OCI_TypeInfo * typinf )

#include <api.h>

Create a local collection instance.

Parameters

typinf - Type info handle of the collection type descriptor

Returns: The collection object handle on success, or NULL on failure.

Referenced by ocilib::Collection< T >::Collection().

◆ OCI_CollFree()

OCI_SYM_PUBLIC boolean OCI_API OCI_CollFree ( OCI_Coll * coll )

#include <api.h>

Free a local collection.

Parameters

coll	- Collection handle

Warning: Only collections created with OCI_CollCreate() should be freed by OCI_CollFree().

Returns: TRUE on success, otherwise FALSE.

◆ OCI_CollArrayCreate()

OCI_SYM_PUBLIC OCI_Coll **OCI_API OCI_CollArrayCreate	(	OCI_Connection *	con,
		OCI_TypeInfo *	typinf,
		unsigned int	nbelem
	)

#include <api.h>

Create an array of Collection objects.

Parameters

con	- Connection handle
typinf	- Object type (type info handle)
nbelem	- Number of elements in the array

Note: See OCI_ObjectCreate() for more details.

Returns: The Collection handle array on success, or NULL on failure.

◆ OCI_CollArrayFree()

OCI_SYM_PUBLIC boolean OCI_API OCI_CollArrayFree ( OCI_Coll ** colls )

#include <api.h>

Free an array of Collection objects.

Parameters

colls - Array of Collection objects

Warning: Only arrays of Collections created with OCI_CollArrayCreate() should be freed by OCI_CollArrayFree().

Returns: TRUE on success, otherwise FALSE.

◆ OCI_CollAssign()

OCI_SYM_PUBLIC boolean OCI_API OCI_CollAssign	(	OCI_Coll *	coll,
		OCI_Coll *	coll_src
	)

#include <api.h>

Assign a collection to another one.

Parameters

coll	- Destination Collection handle
coll_src	- Source Collection handle

Note: Oracle performs a deep copy of the collection content.

Returns: TRUE on success, otherwise FALSE.

Referenced by ocilib::Collection< T >::Clone().

◆ OCI_CollGetTypeInfo()

OCI_SYM_PUBLIC OCI_TypeInfo *OCI_API OCI_CollGetTypeInfo ( OCI_Coll * coll )

#include <api.h>

Return the type info object associated with the collection.

Parameters

coll	- Collection handle

Returns: The type info handle, or NULL on failure.

Referenced by ocilib::Collection< T >::Append(), and ocilib::Collection< T >::GetTypeInfo().

◆ OCI_CollGetType()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_CollGetType ( OCI_Coll * coll )

#include <api.h>

Return the collection type.

Parameters

coll	- Collection handle

Note: Current collection types are:

OCI_COLL_VARRAY: Oracle VARRAY
OCI_COLL_NESTED_TABLE: Oracle Nested Table

Returns: The collection type, or OCI_UNKNOWN if the collection handle is NULL.

Referenced by ocilib::Collection< T >::GetType().

◆ OCI_CollGetMax()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_CollGetMax ( OCI_Coll * coll )

#include <api.h>

Return the maximum number of elements of the given collection.

Parameters

coll	- Collection handle

Returns: The maximum number of elements.

Referenced by ocilib::Collection< T >::GetMax().

◆ OCI_CollGetSize()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_CollGetSize ( OCI_Coll * coll )

#include <api.h>

Return the total number of elements of the given collection.

Parameters

coll	- Collection handle

Returns: The total number of elements.

Referenced by ocilib::Collection< T >::GetSize().

◆ OCI_CollGetCount()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_CollGetCount ( OCI_Coll * coll )

#include <api.h>

Return the current number of elements of the given collection.

Parameters

coll	- Collection handle

Note

For VARRAYs, it returns the same value as OCI_CollGetSize() since VARRAYs cannot contain holes.
For Nested Tables (sparse collections that can have holes), it returns the total number of elements minus the number of deleted elements.

Returns: The current number of elements.

Referenced by ocilib::Collection< T >::GetCount().

◆ OCI_CollTrim()

OCI_SYM_PUBLIC boolean OCI_API OCI_CollTrim	(	OCI_Coll *	coll,
		unsigned int	nb_elem
	)

#include <api.h>

Trims the given number of elements from the end of the collection.

Parameters

coll	- Collection handle
nb_elem	- Number of elements to trim

Returns: TRUE on success, otherwise FALSE.

Referenced by ocilib::Collection< T >::Truncate().

◆ OCI_CollClear()

OCI_SYM_PUBLIC boolean OCI_API OCI_CollClear ( OCI_Coll * coll )

#include <api.h>

Clear all items of the given collection.

Parameters

coll	- Collection handle

Returns: TRUE on success, otherwise FALSE.

Referenced by ocilib::Collection< T >::Clear().

◆ OCI_CollGetElem()

OCI_SYM_PUBLIC OCI_Elem *OCI_API OCI_CollGetElem	(	OCI_Coll *	coll,
		unsigned int	index
	)

#include <api.h>

Return the element at the given position in the collection.

Parameters

coll	- Collection handle
index	- Index of the destination element

Note: Collection indexes start at position 1.

Returns: The element handle on success, or NULL on failure.

Referenced by ocilib::Collection< T >::Get(), ocilib::Collection< T >::IsElementNull(), ocilib::Collection< T >::Set(), and ocilib::Collection< T >::SetElementNull().

◆ OCI_CollGetElem2()

OCI_SYM_PUBLIC boolean OCI_API OCI_CollGetElem2	(	OCI_Coll *	coll,
		unsigned int	index,
		OCI_Elem *	elem
	)

#include <api.h>

Return the element at the given position in the collection.

Parameters

coll	- Collection handle
index	- Index of the destination element
elem	- Element handle to hold the collection item data

Note: Collection indexes start at position 1.

Returns: TRUE on success, otherwise FALSE.

◆ OCI_CollSetElem()

OCI_SYM_PUBLIC boolean OCI_API OCI_CollSetElem	(	OCI_Coll *	coll,
		unsigned int	index,
		OCI_Elem *	elem
	)

#include <api.h>

Assign the given element value to the element at the given position in the collection.

Parameters

coll	- Collection handle
index	- Index of the destination element
elem	- Source element handle to assign

Note: Collection indexes start at position 1.

Returns: TRUE on success, otherwise FALSE.

Referenced by ocilib::Collection< T >::Set().

◆ OCI_CollAppend()

OCI_SYM_PUBLIC boolean OCI_API OCI_CollAppend	(	OCI_Coll *	coll,
		OCI_Elem *	elem
	)

#include <api.h>

Append the given element at the end of the collection.

Parameters

coll	- Collection handle
elem	- Element handle to add

Returns: TRUE on success, otherwise FALSE.

Referenced by ocilib::Collection< T >::Append().

◆ OCI_CollToText()

OCI_SYM_PUBLIC boolean OCI_API OCI_CollToText	(	OCI_Coll *	coll,
		unsigned int *	size,
		otext *	str
	)

#include <api.h>

Convert a collection handle value to a string.

Parameters

coll	- Collection handle
size	- Destination string length pointer in characters
str	- Destination string

Note: To compute the required string length, call this function with a NULL string. Then call it again with a valid buffer.; The resulting string is similar to the SQL*Plus output for collections. For RAW and BLOB attributes, their binary values are converted to hexadecimal strings.

Warning: This convenience method should not be used when performance matters. It is usually called twice (for buffer length computation) and must also handle quotes within strings.

Returns: TRUE on success, otherwise FALSE.

Referenced by ocilib::Collection< T >::ToString().

◆ OCI_CollDeleteElem()

OCI_SYM_PUBLIC boolean OCI_API OCI_CollDeleteElem	(	OCI_Coll *	coll,
		unsigned int	index
	)

#include <api.h>

Delete the element at the given position in the Nested Table Collection.

Parameters

coll	- Collection handle
index	- Index of the element to delete

Note: Collection indexes start at position 1.

Warning: OCI_CollDeleteElem() is only valid for nested tables.

Returns

If the input collection is a Nested Table, it returns TRUE if the element is successfully deleted, or FALSE on error.
If the input collection is a VARRAY, it always returns FALSE without raising an exception.

Referenced by ocilib::Collection< T >::Delete().

◆ OCI_IterCreate()

OCI_SYM_PUBLIC OCI_Iter *OCI_API OCI_IterCreate ( OCI_Coll * coll )

#include <api.h>

Create an iterator handle to iterate through a collection.

Parameters

coll	- Collection handle

Returns: The iterator handle on success, or NULL on failure.

◆ OCI_IterFree()

OCI_SYM_PUBLIC boolean OCI_API OCI_IterFree ( OCI_Iter * iter )

#include <api.h>

Free an iterator handle.

Parameters

iter	- Iterator handle

Returns: TRUE on success, otherwise FALSE.

◆ OCI_IterGetNext()

OCI_SYM_PUBLIC OCI_Elem *OCI_API OCI_IterGetNext ( OCI_Iter * iter )

#include <api.h>

Get the next element in the collection.

Parameters

iter	- Iterator handle

Returns

The element handle on success, or NULL if:

The collection is empty.
The iterator is already positioned on the last element.
An error occurred.

◆ OCI_IterGetPrev()

OCI_SYM_PUBLIC OCI_Elem *OCI_API OCI_IterGetPrev ( OCI_Iter * iter )

#include <api.h>

Get the previous element in the collection.

Parameters

iter	- Iterator handle

Returns

The element handle on success, or NULL if:

The collection is empty.
The iterator is already positioned on the first element.
An error occurred.

◆ OCI_IterGetCurrent()

OCI_SYM_PUBLIC OCI_Elem *OCI_API OCI_IterGetCurrent ( OCI_Iter * iter )

#include <api.h>

Get the current element in the collection.

Parameters

iter	- Iterator handle

Returns

The element handle on success, or NULL if:

The collection is empty.
An error occurred.

◆ OCI_ElemCreate()

OCI_SYM_PUBLIC OCI_Elem *OCI_API OCI_ElemCreate ( OCI_TypeInfo * typinf )

#include <api.h>

Create a local collection element instance based on a collection type descriptor.

Parameters

typinf - Type info handle

Returns: The collection element handle on success, or NULL on failure.

Referenced by ocilib::Collection< T >::Append().

◆ OCI_ElemFree()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemFree ( OCI_Elem * elem )

#include <api.h>

Free a local collection element.

Parameters

elem	- Element handle

Warning: Only elements created with OCI_ElemCreate() should be freed by OCI_ElemFree().

Returns: TRUE on success, otherwise FALSE.

Referenced by ocilib::Collection< T >::Append().

◆ OCI_ElemGetBoolean()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemGetBoolean ( OCI_Elem * elem )

#include <api.h>

Return the boolean value of the given collection element.

Parameters

elem	- Element handle

Warning: OCI_ElemGetBoolean() returns a valid value only for collection elements of PL/SQL boolean type.

Returns: The boolean value, or FALSE on failure.

◆ OCI_ElemGetNumber()

OCI_SYM_PUBLIC OCI_Number *OCI_API OCI_ElemGetNumber ( OCI_Elem * elem )

#include <api.h>

Return the Number value of the given collection element.

Parameters

elem	- Element handle

Returns: The Number handle, or NULL on failure.

◆ OCI_ElemGetShort()

OCI_SYM_PUBLIC short OCI_API OCI_ElemGetShort ( OCI_Elem * elem )

#include <api.h>

Return the short value of the given collection element.

Parameters

elem	- Element handle

Returns: The short value, or 0 on failure.

◆ OCI_ElemGetUnsignedShort()

OCI_SYM_PUBLIC unsigned short OCI_API OCI_ElemGetUnsignedShort ( OCI_Elem * elem )

#include <api.h>

Return the unsigned short value of the given collection element.

Parameters

elem	- Element handle

Returns: The unsigned short value, or 0 on failure.

◆ OCI_ElemGetInt()

OCI_SYM_PUBLIC int OCI_API OCI_ElemGetInt ( OCI_Elem * elem )

#include <api.h>

Return the int value of the given collection element.

Parameters

elem	- Element handle

Returns: The int value, or 0 on failure.

◆ OCI_ElemGetUnsignedInt()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_ElemGetUnsignedInt ( OCI_Elem * elem )

#include <api.h>

Return the unsigned int value of the given collection element.

Parameters

elem	- Element handle

Returns: The unsigned int value, or 0 on failure.

◆ OCI_ElemGetBigInt()

OCI_SYM_PUBLIC big_int OCI_API OCI_ElemGetBigInt ( OCI_Elem * elem )

#include <api.h>

Return the big int value of the given collection element.

Parameters

elem	- Element handle

Returns: The big int value, or 0 on failure.

◆ OCI_ElemGetUnsignedBigInt()

OCI_SYM_PUBLIC big_uint OCI_API OCI_ElemGetUnsignedBigInt ( OCI_Elem * elem )

#include <api.h>

Return the unsigned big int value of the given collection element.

Parameters

elem	- Element handle

Returns: The unsigned big int value, or 0 on failure.

◆ OCI_ElemGetDouble()

OCI_SYM_PUBLIC double OCI_API OCI_ElemGetDouble ( OCI_Elem * elem )

#include <api.h>

Return the Double value of the given collection element.

Parameters

elem	- Element handle

Returns: The double value, or 0.0 on failure.

◆ OCI_ElemGetFloat()

OCI_SYM_PUBLIC float OCI_API OCI_ElemGetFloat ( OCI_Elem * elem )

#include <api.h>

Return the float value of the given collection element.

Parameters

elem	- Element handle

Returns: The float value, or 0.0 on failure.

◆ OCI_ElemGetString()

OCI_SYM_PUBLIC const otext *OCI_API OCI_ElemGetString ( OCI_Elem * elem )

#include <api.h>

Return the String value of the given collection element.

Parameters

elem	- Element handle

Returns: The string value, or NULL on failure.

◆ OCI_ElemGetRaw()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_ElemGetRaw	(	OCI_Elem *	elem,
		void *	value,
		unsigned int	len
	)

#include <api.h>

Read the RAW value of the collection element into the given buffer.

Parameters

elem	- Element handle
value	- Buffer to store the RAW value
len	- Size of the buffer

Returns: The number of bytes read from the RAW value, or 0 on failure.

◆ OCI_ElemGetRawSize()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_ElemGetRawSize ( OCI_Elem * elem )

#include <api.h>

Return the raw attribute value size of the given element handle.

Parameters

elem	- Element handle

Returns: The size in bytes of the RAW value, or 0 on failure or wrong attribute type.

◆ OCI_ElemGetDate()

OCI_SYM_PUBLIC OCI_Date *OCI_API OCI_ElemGetDate ( OCI_Elem * elem )

#include <api.h>

Return the Date value of the given collection element.

Parameters

elem	- Element handle

Returns: The Date handle, or NULL on failure.

◆ OCI_ElemGetTimestamp()

OCI_SYM_PUBLIC OCI_Timestamp *OCI_API OCI_ElemGetTimestamp ( OCI_Elem * elem )

#include <api.h>

Return the Timestamp value of the given collection element.

Parameters

elem	- Element handle

Returns: The Timestamp handle, or NULL on failure.

◆ OCI_ElemGetInterval()

OCI_SYM_PUBLIC OCI_Interval *OCI_API OCI_ElemGetInterval ( OCI_Elem * elem )

#include <api.h>

Return the Interval value of the given collection element.

Parameters

elem	- Element handle

Returns: The Interval handle, or NULL on failure.

◆ OCI_ElemGetLob()

OCI_SYM_PUBLIC OCI_Lob *OCI_API OCI_ElemGetLob ( OCI_Elem * elem )

#include <api.h>

Return the Lob value of the given collection element.

Parameters

elem	- Element handle

Returns: The Lob handle, or NULL on failure.

◆ OCI_ElemGetFile()

OCI_SYM_PUBLIC OCI_File *OCI_API OCI_ElemGetFile ( OCI_Elem * elem )

#include <api.h>

Return the File value of the given collection element.

Parameters

elem	- Element handle

Returns: The File handle, or NULL on failure.

◆ OCI_ElemGetObject()

OCI_SYM_PUBLIC OCI_Object *OCI_API OCI_ElemGetObject ( OCI_Elem * elem )

#include <api.h>

Return the object value of the given collection element.

Parameters

elem	- Element handle

Returns: The Object handle, or NULL on failure.

◆ OCI_ElemGetColl()

OCI_SYM_PUBLIC OCI_Coll *OCI_API OCI_ElemGetColl ( OCI_Elem * elem )

#include <api.h>

Return the collection value of the given collection element.

Parameters

elem	- Element handle

Returns: The Collection handle, or NULL on failure.

◆ OCI_ElemGetRef()

OCI_SYM_PUBLIC OCI_Ref *OCI_API OCI_ElemGetRef ( OCI_Elem * elem )

#include <api.h>

Return the Ref value of the given collection element.

Parameters

elem	- Element handle

Returns: The Ref handle, or NULL on failure.

◆ OCI_ElemSetBoolean()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetBoolean	(	OCI_Elem *	elem,
		boolean	value
	)

#include <api.h>

Set a boolean value to a collection element.

Parameters

elem	- Element handle
value	- Boolean value

Warning: OCI_ElemSetBoolean() is only valid for collection elements of PL/SQL boolean type.

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetNumber()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetNumber	(	OCI_Elem *	elem,
		OCI_Number *	value
	)

#include <api.h>

Set a number value to a collection element.

Parameters

elem	- Element handle
value	- Number value

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetShort()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetShort	(	OCI_Elem *	elem,
		short	value
	)

#include <api.h>

Set a short value to a collection element.

Parameters

elem	- Element handle
value	- Short value

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetUnsignedShort()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetUnsignedShort	(	OCI_Elem *	elem,
		unsigned short	value
	)

#include <api.h>

Set an unsigned short value to a collection element.

Parameters

elem	- Element handle
value	- Unsigned short value

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetInt()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetInt	(	OCI_Elem *	elem,
		int	value
	)

#include <api.h>

Set an int value to a collection element.

Parameters

elem	- Element handle
value	- Int value

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetUnsignedInt()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetUnsignedInt	(	OCI_Elem *	elem,
		unsigned int	value
	)

#include <api.h>

Set an unsigned int value to a collection element.

Parameters

elem	- Element handle
value	- Unsigned int value

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetBigInt()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetBigInt	(	OCI_Elem *	elem,
		big_int	value
	)

#include <api.h>

Set a big int value to a collection element.

Parameters

elem	- Element handle
value	- Big int value

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetUnsignedBigInt()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetUnsignedBigInt	(	OCI_Elem *	elem,
		big_uint	value
	)

#include <api.h>

Set an unsigned big int value to a collection element.

Parameters

elem	- Element handle
value	- Unsigned big int value

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetDouble()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetDouble	(	OCI_Elem *	elem,
		double	value
	)

#include <api.h>

Set a double value to a collection element.

Parameters

elem	- Element handle
value	- Double value

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetFloat()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetFloat	(	OCI_Elem *	elem,
		float	value
	)

#include <api.h>

Set a float value to a collection element.

Parameters

elem	- Element handle
value	- Float value

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetString()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetString	(	OCI_Elem *	elem,
		const otext *	value
	)

#include <api.h>

Set a string value to a collection element.

Parameters

elem	- Element handle
value	- String value

Note: Passing a NULL pointer for value calls OCI_ElemSetNull().

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetRaw()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetRaw	(	OCI_Elem *	elem,
		void *	value,
		unsigned int	len
	)

#include <api.h>

Set a RAW value to a collection element.

Parameters

elem	- Element handle
value	- Raw value
len	- Size of the raw value

Note: Passing a NULL pointer for value calls OCI_ElemSetNull().

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetDate()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetDate	(	OCI_Elem *	elem,
		OCI_Date *	value
	)

#include <api.h>

Assign a Date handle to a collection element.

Parameters

elem	- Element handle
value	- Date handle

Note: Passing a NULL pointer for value calls OCI_ElemSetNull().

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetTimestamp()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetTimestamp	(	OCI_Elem *	elem,
		OCI_Timestamp *	value
	)

#include <api.h>

Assign a Timestamp handle to a collection element.

Parameters

elem	- Element handle
value	- Timestamp handle

Note: Passing a NULL pointer for value calls OCI_ElemSetNull().

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetInterval()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetInterval	(	OCI_Elem *	elem,
		OCI_Interval *	value
	)

#include <api.h>

Assign an Interval handle to a collection element.

Parameters

elem	- Element handle
value	- Interval handle

Note: Passing a NULL pointer for value calls OCI_ElemSetNull().

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetColl()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetColl	(	OCI_Elem *	elem,
		OCI_Coll *	value
	)

#include <api.h>

Assign a Collection handle to a collection element.

Parameters

elem	- Element handle
value	- Collection handle

Note: Passing a NULL pointer for value calls OCI_ElemSetNull().

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetObject()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetObject	(	OCI_Elem *	elem,
		OCI_Object *	value
	)

#include <api.h>

Assign an Object handle to a collection element.

Parameters

elem	- Element handle
value	- Object handle

Warning: This function assigns a copy of the object to the given attribute. Any further modifications of the object passed as the parameter 'value' will not be reflected in the object's attribute set with this call.

Note: Passing a NULL pointer for value calls OCI_ElemSetNull().

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetLob()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetLob	(	OCI_Elem *	elem,
		OCI_Lob *	value
	)

#include <api.h>

Assign a Lob handle to a collection element.

Parameters

elem	- Element handle
value	- Lob handle

Note: Passing a NULL pointer for value calls OCI_ElemSetNull().

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetFile()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetFile	(	OCI_Elem *	elem,
		OCI_File *	value
	)

#include <api.h>

Assign a File handle to a collection element.

Parameters

elem	- Element handle
value	- File handle

Note: Passing a NULL pointer for value calls OCI_ElemSetNull().

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemSetRef()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetRef	(	OCI_Elem *	elem,
		OCI_Ref *	value
	)

#include <api.h>

Assign a Ref handle to a collection element.

Parameters

elem	- Element handle
value	- Ref handle

Note: Passing a NULL pointer for value calls OCI_ElemSetNull().

Returns: TRUE on success, otherwise FALSE.

◆ OCI_ElemIsNull()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemIsNull ( OCI_Elem * elem )

#include <api.h>

Check if the collection element value is null.

Parameters

elem	- Element handle

Returns: TRUE if the value is null, otherwise FALSE.

Referenced by ocilib::Collection< T >::IsElementNull().

◆ OCI_ElemSetNull()

OCI_SYM_PUBLIC boolean OCI_API OCI_ElemSetNull ( OCI_Elem * elem )

#include <api.h>

Set a collection element value to null.

Parameters

elem	- Element handle

Returns: TRUE on success, otherwise FALSE.

Referenced by ocilib::Collection< T >::SetElementNull().

Detailed Description

Functions

Function Documentation

◆ OCI_CollCreate()

◆ OCI_CollFree()

◆ OCI_CollArrayCreate()

◆ OCI_CollArrayFree()

◆ OCI_CollAssign()

◆ OCI_CollGetTypeInfo()

◆ OCI_CollGetType()

◆ OCI_CollGetMax()

◆ OCI_CollGetSize()

◆ OCI_CollGetCount()

◆ OCI_CollTrim()

◆ OCI_CollClear()

◆ OCI_CollGetElem()

◆ OCI_CollGetElem2()

◆ OCI_CollSetElem()

◆ OCI_CollAppend()

◆ OCI_CollToText()

◆ OCI_CollDeleteElem()

◆ OCI_IterCreate()

◆ OCI_IterFree()

◆ OCI_IterGetNext()

◆ OCI_IterGetPrev()

◆ OCI_IterGetCurrent()

◆ OCI_ElemCreate()

◆ OCI_ElemFree()

◆ OCI_ElemGetBoolean()

◆ OCI_ElemGetNumber()

◆ OCI_ElemGetShort()

◆ OCI_ElemGetUnsignedShort()

◆ OCI_ElemGetInt()

◆ OCI_ElemGetUnsignedInt()

◆ OCI_ElemGetBigInt()

◆ OCI_ElemGetUnsignedBigInt()

◆ OCI_ElemGetDouble()

◆ OCI_ElemGetFloat()

◆ OCI_ElemGetString()

◆ OCI_ElemGetRaw()

◆ OCI_ElemGetRawSize()

◆ OCI_ElemGetDate()

◆ OCI_ElemGetTimestamp()

◆ OCI_ElemGetInterval()

◆ OCI_ElemGetLob()

◆ OCI_ElemGetFile()

◆ OCI_ElemGetObject()

◆ OCI_ElemGetColl()

◆ OCI_ElemGetRef()

◆ OCI_ElemSetBoolean()

◆ OCI_ElemSetNumber()

◆ OCI_ElemSetShort()

◆ OCI_ElemSetUnsignedShort()

◆ OCI_ElemSetInt()

◆ OCI_ElemSetUnsignedInt()

◆ OCI_ElemSetBigInt()

◆ OCI_ElemSetUnsignedBigInt()

◆ OCI_ElemSetDouble()

◆ OCI_ElemSetFloat()

◆ OCI_ElemSetString()

◆ OCI_ElemSetRaw()

◆ OCI_ElemSetDate()

◆ OCI_ElemSetTimestamp()

◆ OCI_ElemSetInterval()

◆ OCI_ElemSetColl()

◆ OCI_ElemSetObject()

◆ OCI_ElemSetLob()

◆ OCI_ElemSetFile()

◆ OCI_ElemSetRef()

◆ OCI_ElemIsNull()

◆ OCI_ElemSetNull()