Oracle collections (VARRAYS and Nested Tables)
C API

## Detailed Description

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, they are bounded arrays of homogeneous elements
- Nested Tables: available in SQL and PL/SQL, they are unbounded arrays of homogeneous elements and 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's possible to bind and fetch VARRAYS and Nested tables using OCI_Coll handle.

It's also possible to declare local collections based on some database type without using queries

OCI (and thus OCILIB) offers the possibility 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 elements 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;
  }

## Functions

OCI_EXPORT OCI_Coll *OCI_API | OCI_CollCreate (OCI_TypeInfo *typinf)
| Create a local collection instance. More...
OCI_EXPORT boolean OCI_API | OCI_CollFree (OCI_Coll *coll)
| Free a local collection. More...
OCI_EXPORT OCI_Coll **OCI_API | OCI_CollArrayCreate (OCI_Connection *con, OCI_TypeInfo *typinf, unsigned int nbelem)
| Create an array of Collection object. More...
OCI_EXPORT boolean OCI_API | OCI_CollArrayFree (OCI_Coll **colls)
| Free an array of Collection objects. More...
OCI_EXPORT boolean OCI_API | OCI_CollAssign (OCI_Coll *coll, OCI_Coll *coll_src)
| Assign a collection to another one. More...
OCI_EXPORT OCI_TypeInfo *OCI_API | OCI_CollGetTypeInfo (OCI_Coll *coll)
| Return the type info object associated to the collection. More...
OCI_EXPORT unsigned int OCI_API | OCI_CollGetType (OCI_Coll *coll)
| Return the collection type. More...
OCI_EXPORT unsigned int OCI_API | OCI_CollGetMax (OCI_Coll *coll)
| Returns the maximum number of elements of the given collection. More...
OCI_EXPORT unsigned int OCI_API | OCI_CollGetSize (OCI_Coll *coll)
| Returns the total number of elements of the given collection. More...
OCI_EXPORT unsigned int OCI_API | OCI_CollGetCount (OCI_Coll *coll)
| Returns the current number of elements of the given collection. More...
OCI_EXPORT boolean OCI_API | OCI_CollTrim (OCI_Coll *coll, unsigned int nb_elem)
| Trims the given number of elements from the end of the collection. More...
OCI_EXPORT boolean OCI_API | OCI_CollClear (OCI_Coll *coll)
| clear all items of the given collection More...
OCI_EXPORT OCI_Elem *OCI_API | OCI_CollGetElem (OCI_Coll *coll, unsigned int index)
| Return the element at the given position in the collection. More...
OCI_EXPORT boolean OCI_API | OCI_CollGetElem2 (OCI_Coll *coll, unsigned int index, OCI_Elem *elem)
| Return the element at the given position in the collection. More...
OCI_EXPORT 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. More...
OCI_EXPORT boolean OCI_API | OCI_CollAppend (OCI_Coll *coll, OCI_Elem *elem)
| Append the given element at the end of the collection. More...
OCI_EXPORT boolean OCI_API | OCI_CollToText (OCI_Coll *coll, unsigned int *size, otext *str)
| Convert a collection handle value to a string. More...
OCI_EXPORT boolean OCI_API | OCI_CollDeleteElem (OCI_Coll *coll, unsigned int index)
| Delete the element at the given position in the Nested Table Collection. More...
OCI_EXPORT OCI_Iter *OCI_API | OCI_IterCreate (OCI_Coll *coll)
| Create an iterator handle to iterate through a collection. More...
OCI_EXPORT boolean OCI_API | OCI_IterFree (OCI_Iter *iter)
| Free an iterator handle. More...
OCI_EXPORT OCI_Elem *OCI_API | OCI_IterGetNext (OCI_Iter *iter)
| Get the next element in the collection. More...
OCI_EXPORT OCI_Elem *OCI_API | OCI_IterGetPrev (OCI_Iter *iter)
| Get the previous element in the collection. More...
OCI_EXPORT OCI_Elem *OCI_API | OCI_IterGetCurrent (OCI_Iter *iter)
| Get the current element in the collection. More...
OCI_EXPORT OCI_Elem *OCI_API | OCI_ElemCreate (OCI_TypeInfo *typinf)
| Create a local collection element instance based on a collection type descriptor. More...
OCI_EXPORT boolean OCI_API | OCI_ElemFree (OCI_Elem *elem)
| Free a local collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemGetBoolean (OCI_Elem *elem)
| Return the boolean value of the given collection element. More...
OCI_EXPORT OCI_Number *OCI_API | OCI_ElemGetNumber (OCI_Elem *elem)
| Return the number value of the given collection element. More...
OCI_EXPORT short OCI_API | OCI_ElemGetShort (OCI_Elem *elem)
| Return the short value of the given collection element. More...
OCI_EXPORT unsigned short OCI_API | OCI_ElemGetUnsignedShort (OCI_Elem *elem)
| Return the unsigned short value of the given collection element. More...
OCI_EXPORT int OCI_API | OCI_ElemGetInt (OCI_Elem *elem)
| Return the int value of the given collection element. More...
OCI_EXPORT unsigned int OCI_API | OCI_ElemGetUnsignedInt (OCI_Elem *elem)
| Return the unsigned int value of the given collection element. More...
OCI_EXPORT big_int OCI_API | OCI_ElemGetBigInt (OCI_Elem *elem)
| Return the big int value of the given collection element. More...
OCI_EXPORT big_uint OCI_API | OCI_ElemGetUnsignedBigInt (OCI_Elem *elem)
| Return the unsigned big int value of the given collection element. More...
OCI_EXPORT double OCI_API | OCI_ElemGetDouble (OCI_Elem *elem)
| Return the Double value of the given collection element. More...
OCI_EXPORT float OCI_API | OCI_ElemGetFloat (OCI_Elem *elem)
| Return the float value of the given collection element. More...
OCI_EXPORT const otext *OCI_API | OCI_ElemGetString (OCI_Elem *elem)
| Return the String value of the given collection element. More...
OCI_EXPORT 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. More...
OCI_EXPORT unsigned int OCI_API | OCI_ElemGetRawSize (OCI_Elem *elem)
| Return the raw attribute value size of the given element handle. More...
OCI_EXPORT OCI_Date *OCI_API | OCI_ElemGetDate (OCI_Elem *elem)
| Return the Date value of the given collection element. More...
OCI_EXPORT OCI_Timestamp *OCI_API | OCI_ElemGetTimestamp (OCI_Elem *elem)
| Return the Timestamp value of the given collection element. More...
OCI_EXPORT OCI_Interval *OCI_API | OCI_ElemGetInterval (OCI_Elem *elem)
| Return the Interval value of the given collection element. More...
OCI_EXPORT OCI_Lob *OCI_API | OCI_ElemGetLob (OCI_Elem *elem)
| Return the Lob value of the given collection element. More...
OCI_EXPORT OCI_File *OCI_API | OCI_ElemGetFile (OCI_Elem *elem)
| Return the File value of the given collection element. More...
OCI_EXPORT OCI_Object *OCI_API | OCI_ElemGetObject (OCI_Elem *elem)
| Return the object value of the given collection element. More...
OCI_EXPORT OCI_Coll *OCI_API | OCI_ElemGetColl (OCI_Elem *elem)
| Return the collection value of the given collection element. More...
OCI_EXPORT OCI_Ref *OCI_API | OCI_ElemGetRef (OCI_Elem *elem)
| Return the Ref value of the given collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetBoolean (OCI_Elem *elem, boolean value)
| Set a boolean value to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetNumber (OCI_Elem *elem, OCI_Number *value)
| Set a number value to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetShort (OCI_Elem *elem, short value)
| Set a short value to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetUnsignedShort (OCI_Elem *elem, unsigned short value)
| Set a unsigned short value to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetInt (OCI_Elem *elem, int value)
| Set a int value to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetUnsignedInt (OCI_Elem *elem, unsigned int value)
| Set a unsigned int value to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetBigInt (OCI_Elem *elem, big_int value)
| Set a big int value to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetUnsignedBigInt (OCI_Elem *elem, big_uint value)
| Set a unsigned big_int value to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetDouble (OCI_Elem *elem, double value)
| Set a double value to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetFloat (OCI_Elem *elem, float value)
| Set a float value to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetString (OCI_Elem *elem, const otext *value)
| Set a string value to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetRaw (OCI_Elem *elem, void *value, unsigned int len)
| Set a RAW value to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetDate (OCI_Elem *elem, OCI_Date *value)
| Assign a Date handle to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetTimestamp (OCI_Elem *elem, OCI_Timestamp *value)
| Assign a Timestamp handle to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetInterval (OCI_Elem *elem, OCI_Interval *value)
| Assign an Interval handle to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetColl (OCI_Elem *elem, OCI_Coll *value)
| Assign a Collection handle to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetObject (OCI_Elem *elem, OCI_Object *value)
| Assign an Object handle to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetLob (OCI_Elem *elem, OCI_Lob *value)
| Assign a Lob handle to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetFile (OCI_Elem *elem, OCI_File *value)
| Assign a File handle to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetRef (OCI_Elem *elem, OCI_Ref *value)
| Assign a Ref handle to a collection element. More...
OCI_EXPORT boolean OCI_API | OCI_ElemIsNull (OCI_Elem *elem)
| Check if the collection element value is null. More...
OCI_EXPORT boolean OCI_API | OCI_ElemSetNull (OCI_Elem *elem)
| Set a collection element value to null. More...

## Function Documentation

## OCI_CollCreate()

OCI_EXPORT OCI_Coll* OCI_API OCI_CollCreate | ( | OCI_TypeInfo * | typinf | ) |

`#include <ocilib.h>`

Create a local collection instance.

Parameters

  typinf | - Type info handle of the collection type descriptor

Returns
  Return the collection object handle on success otherwise NULL on failure

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

## OCI_CollFree()

OCI_EXPORT boolean OCI_API OCI_CollFree | ( | OCI_Coll * | coll | ) |

`#include <ocilib.h>`

Free a local collection.

Parameters

  coll | - Collection handle

Warning
  Only collection created with OCI_CollCreate() should be freed by OCI_CollFree()

Returns
  TRUE on success otherwise FALSE

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

## OCI_CollArrayCreate()

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

`#include <ocilib.h>`

Create an array of Collection object.

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
  Return the Collection handle array on success otherwise NULL on failure

## OCI_CollArrayFree()

OCI_EXPORT boolean OCI_API OCI_CollArrayFree | ( | OCI_Coll ** | colls | ) |

`#include <ocilib.h>`

Free an array of Collection objects.

Parameters

  colls | - Array of Collection objects

Warning
  Only arrays of Collection created with OCI_CollArrayCreate() should be freed by OCI_CollArrayFree()

Returns
  TRUE on success otherwise FALSE

## OCI_CollAssign()

OCI_EXPORT boolean OCI_API OCI_CollAssign | ( | OCI_Coll * | coll,
|  | OCI_Coll * | coll_src
| ) |  |

`#include <ocilib.h>`

Assign a collection to another one.

Parameters

  coll | - Destination Collection handle
  coll_src | - Source Collection handle

Note
  Oracle proceeds to a deep copy of the collection content

Returns
  TRUE on success otherwise FALSE

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

## OCI_CollGetTypeInfo()

OCI_EXPORT OCI_TypeInfo* OCI_API OCI_CollGetTypeInfo | ( | OCI_Coll * | coll | ) |

`#include <ocilib.h>`

Return the type info object associated to the collection.

Parameters

  coll | - Collection handle

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

## OCI_CollGetType()

OCI_EXPORT unsigned int OCI_API OCI_CollGetType | ( | OCI_Coll * | coll | ) |

`#include <ocilib.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
  Collection type or OCI_UNKNOWN if the collection handle is null

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

## OCI_CollGetMax()

OCI_EXPORT unsigned int OCI_API OCI_CollGetMax | ( | OCI_Coll * | coll | ) |

`#include <ocilib.h>`

Returns the maximum number of elements of the given collection.

Parameters

  coll | - Collection handle

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

## OCI_CollGetSize()

OCI_EXPORT unsigned int OCI_API OCI_CollGetSize | ( | OCI_Coll * | coll | ) |

`#include <ocilib.h>`

Returns the total number of elements of the given collection.

Parameters

  coll | - Collection handle

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

## OCI_CollGetCount()

OCI_EXPORT unsigned int OCI_API OCI_CollGetCount | ( | OCI_Coll * | coll | ) |

`#include <ocilib.h>`

Returns the current number of elements of the given collection.

Note
  - For VARRAYs, it returns the same value than OCI_CollGetSize() as VARRAYs cannot contains holes
  - For Nested Tables that are spare collections that can have holes, it returns the total number of elements minus the total of deleted elements

Parameters

  coll | - Collection handle

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

## OCI_CollTrim()

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

`#include <ocilib.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_EXPORT boolean OCI_API OCI_CollClear | ( | OCI_Coll * | coll | ) |

`#include <ocilib.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_EXPORT OCI_Elem* OCI_API OCI_CollGetElem | ( | OCI_Coll * | coll,
|  | unsigned int | index
| ) |  |

`#include <ocilib.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
  Element handle on success otherwise FALSE

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

## OCI_CollGetElem2()

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

`#include <ocilib.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
  Element handle on success otherwise FALSE

## OCI_CollSetElem()

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

`#include <ocilib.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_EXPORT boolean OCI_API OCI_CollAppend | ( | OCI_Coll * | coll,
|  | OCI_Elem * | elem
| ) |  |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_CollToText | ( | OCI_Coll * | coll,
|  | unsigned int * | size,
|  | otext * | str
| ) |  |

`#include <ocilib.h>`

Convert a collection handle value to a string.

Parameters

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

Note
  In order to compute the needed string length, call the method with a NULL string Then call the method again with a valid buffer
  The resulting string is similar to the SQL*PLUS output for collections For RAWs and BLOBs attributes, their binary values are converted to hexadecimal strings

Warning
  This convenient method shall not be used when performance matters. It is usually called twice (buffer length computation) and must also care about quotes within strings.

Returns
  TRUE on success otherwise FALSE

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

## OCI_CollDeleteElem()

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

`#include <ocilib.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 otherwise FALSE on error
  - if the input collection is a VARRAY, it always returns FALSE without spawning an exception

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

## OCI_IterCreate()

OCI_EXPORT OCI_Iter* OCI_API OCI_IterCreate | ( | OCI_Coll * | coll | ) |

`#include <ocilib.h>`

Create an iterator handle to iterate through a collection.

Parameters

  coll | - Collection handle

Returns
  Return the iterator handle on success otherwise NULL on failure

## OCI_IterFree()

OCI_EXPORT boolean OCI_API OCI_IterFree | ( | OCI_Iter * | iter | ) |

`#include <ocilib.h>`

Free an iterator handle.

Parameters

  iter | - Iterator handle

Returns
  TRUE on success otherwise FALSE

## OCI_IterGetNext()

OCI_EXPORT OCI_Elem* OCI_API OCI_IterGetNext | ( | OCI_Iter * | iter | ) |

`#include <ocilib.h>`

Get the next element in the collection.

Parameters

  iter | - Iterator handle

Returns
  Element handle on success otherwise NULL if:
  - Empty collection
  - Iterator already positioned on the last collection element
  - An error occurred

## OCI_IterGetPrev()

OCI_EXPORT OCI_Elem* OCI_API OCI_IterGetPrev | ( | OCI_Iter * | iter | ) |

`#include <ocilib.h>`

Get the previous element in the collection.

Parameters

  iter | - Iterator handle

Returns
  Element handle on success otherwise NULL if:
  - Empty collection
  - Iterator already positioned on the last collection element
  - An error occurred

## OCI_IterGetCurrent()

OCI_EXPORT OCI_Elem* OCI_API OCI_IterGetCurrent | ( | OCI_Iter * | iter | ) |

`#include <ocilib.h>`

Get the current element in the collection.

Parameters

  iter | - Iterator handle

Returns
  Element handle on success otherwise NULL if:
  - Empty collection
  - Iterator already positioned on the last collection element
  - An error occurred

## OCI_ElemCreate()

OCI_EXPORT OCI_Elem* OCI_API OCI_ElemCreate | ( | OCI_TypeInfo * | typinf | ) |

`#include <ocilib.h>`

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

Parameters

  typinf | - Type info handle

Returns
  Return the collection element handle on success otherwise NULL on failure

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

## OCI_ElemFree()

OCI_EXPORT boolean OCI_API OCI_ElemFree | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Free a local collection element.

Parameters

  elem | - Element handle

Warning
  Only element 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_EXPORT boolean OCI_API OCI_ElemGetBoolean | ( | OCI_Elem * | elem | ) |

`#include <ocilib.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
  boolean value or FALSE on failure

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

## OCI_ElemGetNumber()

OCI_EXPORT OCI_Number* OCI_API OCI_ElemGetNumber | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Return the number value of the given collection element.

Parameters

  elem | - Element handle

Returns
  number handle or NULL on failure

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

## OCI_ElemGetShort()

OCI_EXPORT short OCI_API OCI_ElemGetShort | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Return the short value of the given collection element.

Parameters

  elem | - Element handle

Returns
  Short value or 0 on failure

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

## OCI_ElemGetUnsignedShort()

OCI_EXPORT unsigned short OCI_API OCI_ElemGetUnsignedShort | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Return the unsigned short value of the given collection element.

Parameters

  elem | - Element handle

Returns
  Unsigned short value or 0 on failure

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

## OCI_ElemGetInt()

OCI_EXPORT int OCI_API OCI_ElemGetInt | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Return the int value of the given collection element.

Parameters

  elem | - Element handle

Returns
  Int value or 0 on failure

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

## OCI_ElemGetUnsignedInt()

OCI_EXPORT unsigned int OCI_API OCI_ElemGetUnsignedInt | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Return the unsigned int value of the given collection element.

Parameters

  elem | - Element handle

Returns
  Unsigned int value or 0 on failure

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

## OCI_ElemGetBigInt()

OCI_EXPORT big_int OCI_API OCI_ElemGetBigInt | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Return the big int value of the given collection element.

Parameters

  elem | - Element handle

Returns
  Big int value or 0 on failure

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

## OCI_ElemGetUnsignedBigInt()

OCI_EXPORT big_uint OCI_API OCI_ElemGetUnsignedBigInt | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

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

Parameters

  elem | - Element handle

Returns
  Unsigned big int value or 0 on failure

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

## OCI_ElemGetDouble()

OCI_EXPORT double OCI_API OCI_ElemGetDouble | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Return the Double value of the given collection element.

Parameters

  elem | - Element handle

Returns
  Double value or 0 on failure

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

## OCI_ElemGetFloat()

OCI_EXPORT float OCI_API OCI_ElemGetFloat | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Return the float value of the given collection element.

Parameters

  elem | - Element handle

Returns
  Double value or 0 on failure

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

## OCI_ElemGetString()

OCI_EXPORT const otext* OCI_API OCI_ElemGetString | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Return the String value of the given collection element.

Parameters

  elem | - Element handle

Returns
  String value or NULL on failure

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

## OCI_ElemGetRaw()

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

`#include <ocilib.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
  Number of bytes read from the RAW value or 0 on failure

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

## OCI_ElemGetRawSize()

OCI_EXPORT unsigned int OCI_API OCI_ElemGetRawSize | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

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

Parameters

  elem | - Element handle

Returns
  size in bytes of the RAW value or 0 on failure or wrong attribute type

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

## OCI_ElemGetDate()

OCI_EXPORT OCI_Date* OCI_API OCI_ElemGetDate | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Return the Date value of the given collection element.

Parameters

  elem | - Element handle

Returns
  Date handle or NULL on failure

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

## OCI_ElemGetTimestamp()

OCI_EXPORT OCI_Timestamp* OCI_API OCI_ElemGetTimestamp | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Return the Timestamp value of the given collection element.

Parameters

  elem | - Element handle

Returns
  Timestamp handle or NULL on failure

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

## OCI_ElemGetInterval()

OCI_EXPORT OCI_Interval* OCI_API OCI_ElemGetInterval | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Return the Interval value of the given collection element.

Parameters

  elem | - Element handle

Returns
  Interval handle or NULL on failure

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

## OCI_ElemGetLob()

OCI_EXPORT OCI_Lob* OCI_API OCI_ElemGetLob | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Return the Lob value of the given collection element.

Parameters

  elem | - Element handle

Returns
  Lob handle or NULL on failure

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

## OCI_ElemGetFile()

OCI_EXPORT OCI_File* OCI_API OCI_ElemGetFile | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Return the File value of the given collection element.

Parameters

  elem | - Element handle

Returns
  File handle or NULL on failure

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

## OCI_ElemGetObject()

OCI_EXPORT OCI_Object* OCI_API OCI_ElemGetObject | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Return the object value of the given collection element.

Parameters

  elem | - Element handle

Returns
  Object handle or NULL on failure

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

## OCI_ElemGetColl()

OCI_EXPORT OCI_Coll* OCI_API OCI_ElemGetColl | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Return the collection value of the given collection element.

Parameters

  elem | - Element handle

Returns
  Collection handle or NULL on failure

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

## OCI_ElemGetRef()

OCI_EXPORT OCI_Ref* OCI_API OCI_ElemGetRef | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Return the Ref value of the given collection element.

Parameters

  elem | - Element handle

Returns
  Ref handle or NULL on failure

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

## OCI_ElemSetBoolean()

OCI_EXPORT boolean OCI_API OCI_ElemSetBoolean | ( | OCI_Elem * | elem,
|  | boolean | value
| ) |  |

`#include <ocilib.h>`

Set a boolean value to a collection element.

Parameters

  elem | - Element handle
  value | - Short value

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

Returns
  TRUE on success otherwise FALSE

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

## OCI_ElemSetNumber()

OCI_EXPORT boolean OCI_API OCI_ElemSetNumber | ( | OCI_Elem * | elem,
|  | OCI_Number * | value
| ) |  |

`#include <ocilib.h>`

Set a number value to a collection element.

Parameters

  elem | - Element handle
  value | - number value

Returns
  TRUE on success otherwise FALSE

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

## OCI_ElemSetShort()

OCI_EXPORT boolean OCI_API OCI_ElemSetShort | ( | OCI_Elem * | elem,
|  | short | value
| ) |  |

`#include <ocilib.h>`

Set a short value to a collection element.

Parameters

  elem | - Element handle
  value | - Short value

Returns
  TRUE on success otherwise FALSE

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

## OCI_ElemSetUnsignedShort()

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

`#include <ocilib.h>`

Set a unsigned short value to a collection element.

Parameters

  elem | - Element handle
  value | - Unsigned short value

Returns
  TRUE on success otherwise FALSE

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

## OCI_ElemSetInt()

OCI_EXPORT boolean OCI_API OCI_ElemSetInt | ( | OCI_Elem * | elem,
|  | int | value
| ) |  |

`#include <ocilib.h>`

Set a int value to a collection element.

Parameters

  elem | - Element handle
  value | - Int value

Returns
  TRUE on success otherwise FALSE

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

## OCI_ElemSetUnsignedInt()

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

`#include <ocilib.h>`

Set a unsigned int value to a collection element.

Parameters

  elem | - Element handle
  value | - Unsigned int value

Returns
  TRUE on success otherwise FALSE

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

## OCI_ElemSetBigInt()

OCI_EXPORT boolean OCI_API OCI_ElemSetBigInt | ( | OCI_Elem * | elem,
|  | big_int | value
| ) |  |

`#include <ocilib.h>`

Set a big int value to a collection element.

Parameters

  elem | - Element handle
  value | - big int value

Returns
  TRUE on success otherwise FALSE

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

## OCI_ElemSetUnsignedBigInt()

OCI_EXPORT boolean OCI_API OCI_ElemSetUnsignedBigInt | ( | OCI_Elem * | elem,
|  | big_uint | value
| ) |  |

`#include <ocilib.h>`

Set a unsigned big_int value to a collection element.

Parameters

  elem | - Element handle
  value | - Unsigned big int value

Returns
  TRUE on success otherwise FALSE

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

## OCI_ElemSetDouble()

OCI_EXPORT boolean OCI_API OCI_ElemSetDouble | ( | OCI_Elem * | elem,
|  | double | value
| ) |  |

`#include <ocilib.h>`

Set a double value to a collection element.

Parameters

  elem | - Element handle
  value | - Double value

Returns
  TRUE on success otherwise FALSE

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

## OCI_ElemSetFloat()

OCI_EXPORT boolean OCI_API OCI_ElemSetFloat | ( | OCI_Elem * | elem,
|  | float | value
| ) |  |

`#include <ocilib.h>`

Set a float value to a collection element.

Parameters

  elem | - Element handle
  value | - float value

Returns
  TRUE on success otherwise FALSE

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

## OCI_ElemSetString()

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

`#include <ocilib.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

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

## OCI_ElemSetRaw()

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

`#include <ocilib.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

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

## OCI_ElemSetDate()

OCI_EXPORT boolean OCI_API OCI_ElemSetDate | ( | OCI_Elem * | elem,
|  | OCI_Date * | value
| ) |  |

`#include <ocilib.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

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

## OCI_ElemSetTimestamp()

OCI_EXPORT boolean OCI_API OCI_ElemSetTimestamp | ( | OCI_Elem * | elem,
|  | OCI_Timestamp * | value
| ) |  |

`#include <ocilib.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

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

## OCI_ElemSetInterval()

OCI_EXPORT boolean OCI_API OCI_ElemSetInterval | ( | OCI_Elem * | elem,
|  | OCI_Interval * | value
| ) |  |

`#include <ocilib.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

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

## OCI_ElemSetColl()

OCI_EXPORT boolean OCI_API OCI_ElemSetColl | ( | OCI_Elem * | elem,
|  | OCI_Coll * | value
| ) |  |

`#include <ocilib.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

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

## OCI_ElemSetObject()

OCI_EXPORT boolean OCI_API OCI_ElemSetObject | ( | OCI_Elem * | elem,
|  | OCI_Object * | value
| ) |  |

`#include <ocilib.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 to object 's attribute set with this call

Note
  passing a null pointer for value calls OCI_ElemSetNull()

Returns
  TRUE on success otherwise FALSE

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

## OCI_ElemSetLob()

OCI_EXPORT boolean OCI_API OCI_ElemSetLob | ( | OCI_Elem * | elem,
|  | OCI_Lob * | value
| ) |  |

`#include <ocilib.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

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

## OCI_ElemSetFile()

OCI_EXPORT boolean OCI_API OCI_ElemSetFile | ( | OCI_Elem * | elem,
|  | OCI_File * | value
| ) |  |

`#include <ocilib.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

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

## OCI_ElemSetRef()

OCI_EXPORT boolean OCI_API OCI_ElemSetRef | ( | OCI_Elem * | elem,
|  | OCI_Ref * | value
| ) |  |

`#include <ocilib.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

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

## OCI_ElemIsNull()

OCI_EXPORT boolean OCI_API OCI_ElemIsNull | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Check if the collection element value is null.

Parameters

  elem | - Element handle

Returns
  TRUE if it's null otherwise FALSE

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

## OCI_ElemSetNull()

OCI_EXPORT boolean OCI_API OCI_ElemSetNull | ( | OCI_Elem * | elem | ) |

`#include <ocilib.h>`

Set a collection element value to null.

Parameters

  elem | - Element handle

Returns
  TRUE on success otherwise FALSE

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