OCILIB (C Driver for Oracle) 3.9.2
Functions
Oracle Named Types (Oracle OBJECTs)

Detailed Description

OCILIB implements Oracle Named types (user types and built-in types) through the OCI_Object type.

OTT and C structures are not required to use objects in OCILIB.

In order to manipulate objects attributes, OCILIB proposes a set of functions to get/set properties for various supported types.

Objects can be:

References (Oracle type REF) are identifiers (smart pointers) to objects and are implemented in OCILIB with the type OCI_Ref.

OCILIB implements Oracle REFs as strong typed Reference (underlying OCI REFs are weaker in terms of typing). It means it's mandatory to provide type information to:

Note:
See Oracle Database SQL Language Reference for more details about REF datatype
Warning:
Prior to v3.5.0, OCILIB relied on some OCI routines to set/get objects attributes. these OCI calls had known bugs in Unicode mode that has been fixed in Oracle 11gR2. From v3.5.0, OCILIB directly sets objects attributes and thus OCILIB objects can now be used in Unicode mode.
Example : Inserting a local object into a table
#include "ocilib.h"

/* 
    DML for the test 

    create type t_vendor as object
    ( 
        code  number, 
        name  varchar2(30)
    ); 

    create type t_sale as object 
    ( 
        code  number, 
        price  float, 
        name  varchar2(30),
        ref  varchar2(30), 
        date_sale date, 
        vendor  t_vendor
    ); 

    create table sales(item t_sale);

*/

int main(void)
{
    OCI_Connection *cn;
    OCI_Statement *st;
    OCI_Object *obj, *obj2;
    OCI_Date *date;

    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

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

    obj  = OCI_ObjectCreate(cn, OCI_TypeInfoGet(cn, "t_sale", OCI_TIF_TYPE));

    OCI_ObjectSetInt(obj, "CODE", 1);
    OCI_ObjectSetDouble(obj, "PRICE", 12.99);
    OCI_ObjectSetString(obj, "NAME", "USB KEY 2go");
    OCI_ObjectSetString(obj, "REF", "A56547WSAA");

    date = OCI_ObjectGetDate(obj, "DATE_SALE");
    OCI_DateSysDate(date);

    obj2 = OCI_ObjectGetObject(obj, "VENDOR");
    OCI_ObjectSetInt(obj2, "CODE", 134);
    OCI_ObjectSetString(obj2, "NAME", "JOHN SMITH");

    OCI_Prepare(st, "insert into sales values(:obj)");
    OCI_BindObject(st, ":obj", obj);
    OCI_Execute(st);

    printf("\n%d row(s) inserted\n", OCI_GetAffectedRows(st));

    OCI_Commit(cn);

    OCI_ObjectFree(obj);

    OCI_Cleanup();

    return EXIT_SUCCESS;
}
Example : Using Object References
#include "ocilib.h"

#define SIZE_STR 100

void dump_ref(OCI_Ref *ref)
{
    OCI_Object *obj;
    dtext data[SIZE_STR + 1];

    /* print ref hexadecimal value */

    OCI_RefToText(ref, SIZE_STR, data);
    printf("...Ref Hex value : %s\n", data);

    /* get object from ref */

    obj = OCI_RefGetObject(ref);

    /* print object values */

    printf("...%i - %s\n", OCI_ObjectGetInt(obj, "ID"), 
                           OCI_ObjectGetString(obj, "NAME"));
}

int main(void)
{
    OCI_Connection *cn;
    OCI_Statement  *st;
    OCI_Resultset  *rs;
    OCI_Ref       *ref;

    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

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

    OCI_ExecuteStmt(st, "select ref(e) from table_obj e");
    rs = OCI_GetResultset(st);

    printf("\n\n=> fetch refs from object table\n\n");

    while (OCI_FetchNext(rs))
    {
        dump_ref(OCI_GetRef(rs, 1));
    }

    printf("\n\n=> bind a local ref object to a PL/SQL statement\n\n");

    ref = OCI_RefCreate(cn, OCI_TypeInfoGet(cn, "ARTICLE_T", OCI_TIF_TYPE));

    OCI_Prepare(st, "begin "
                    "  select ref(e) into :r from table_obj e where e.id = 1; "
                    "end; ");
    
    OCI_BindRef(st, ":r", ref);
    OCI_Execute(st);

    dump_ref(ref);

    OCI_RefFree(ref);

    OCI_Cleanup();

    return EXIT_SUCCESS;
}

Functions

OCI_EXPORT OCI_Object *OCI_API OCI_ObjectCreate (OCI_Connection *con, OCI_TypeInfo *typinf)
 Create a local object instance.
OCI_EXPORT boolean OCI_API OCI_ObjectFree (OCI_Object *obj)
 Free a local object.
OCI_EXPORT OCI_Object **OCI_API OCI_ObjectArrayCreate (OCI_Connection *con, OCI_TypeInfo *typinf, unsigned int nbelem)
 Create an array of Object object.
OCI_EXPORT boolean OCI_API OCI_ObjectArrayFree (OCI_Object **objs)
 Free an arrray of Object objects.
OCI_EXPORT boolean OCI_API OCI_ObjectAssign (OCI_Object *obj, OCI_Object *obj_src)
 Assign an object to another one.
OCI_EXPORT unsigned int OCI_API OCI_ObjectGetType (OCI_Object *obj)
 Return the type of an object instance.
OCI_EXPORT boolean OCI_API OCI_ObjectGetSelfRef (OCI_Object *obj, OCI_Ref *ref)
 Retrieve an Oracle Ref handle from an object and assign it to the given OCILIB OCI_Ref handle.
OCI_EXPORT OCI_TypeInfo *OCI_API OCI_ObjectGetTypeInfo (OCI_Object *obj)
 Return the type info object associated to the object.
OCI_EXPORT short OCI_API OCI_ObjectGetShort (OCI_Object *obj, const mtext *attr)
 Return the short value of the given object attribute.
OCI_EXPORT unsigned short OCI_API OCI_ObjectGetUnsignedShort (OCI_Object *obj, const mtext *attr)
 Return the unsigned short value of the given object attribute.
OCI_EXPORT int OCI_API OCI_ObjectGetInt (OCI_Object *obj, const mtext *attr)
 Return the integer value of the given object attribute.
OCI_EXPORT unsigned int OCI_API OCI_ObjectGetUnsignedInt (OCI_Object *obj, const mtext *attr)
 Return the unsigned integer value of the given object attribute.
OCI_EXPORT big_int OCI_API OCI_ObjectGetBigInt (OCI_Object *obj, const mtext *attr)
 Return the big integer value of the given object attribute.
OCI_EXPORT big_uint OCI_API OCI_ObjectGetUnsignedBigInt (OCI_Object *obj, const mtext *attr)
 Return the unsigned big integer value of the given object attribute.
OCI_EXPORT double OCI_API OCI_ObjectGetDouble (OCI_Object *obj, const mtext *attr)
 Return the double value of the given object attribute.
OCI_EXPORT const dtext *OCI_API OCI_ObjectGetString (OCI_Object *obj, const mtext *attr)
 Return the string value of the given object attribute.
OCI_EXPORT int OCI_API OCI_ObjectGetRaw (OCI_Object *obj, const mtext *attr, void *value, unsigned int len)
 Return the raw attribute value of the given object attribute into the given buffer.
OCI_EXPORT OCI_Date *OCI_API OCI_ObjectGetDate (OCI_Object *obj, const mtext *attr)
 Return the date value of the given object attribute.
OCI_EXPORT OCI_Timestamp *OCI_API OCI_ObjectGetTimestamp (OCI_Object *obj, const mtext *attr)
 Return the timestamp value of the given object attribute.
OCI_EXPORT OCI_Interval *OCI_API OCI_ObjectGetInterval (OCI_Object *obj, const mtext *attr)
 Return the interval value of the given object attribute.
OCI_EXPORT OCI_Coll *OCI_API OCI_ObjectGetColl (OCI_Object *obj, const mtext *attr)
 Return the collection value of the given object attribute.
OCI_EXPORT OCI_Ref *OCI_API OCI_ObjectGetRef (OCI_Object *obj, const mtext *attr)
 Return the Ref value of the given object attribute.
OCI_EXPORT OCI_Object *OCI_API OCI_ObjectGetObject (OCI_Object *obj, const mtext *attr)
 Return the object value of the given object attribute.
OCI_EXPORT OCI_Lob *OCI_API OCI_ObjectGetLob (OCI_Object *obj, const mtext *attr)
 Return the lob value of the given object attribute.
OCI_EXPORT OCI_File *OCI_API OCI_ObjectGetFile (OCI_Object *obj, const mtext *attr)
 Return the file value of the given object attribute.
OCI_EXPORT boolean OCI_API OCI_ObjectSetShort (OCI_Object *obj, const mtext *attr, short value)
 Set an object attribute of type short.
OCI_EXPORT boolean OCI_API OCI_ObjectSetUnsignedShort (OCI_Object *obj, const mtext *attr, unsigned short value)
 Set an object attribute of type unsigned short.
OCI_EXPORT boolean OCI_API OCI_ObjectSetInt (OCI_Object *obj, const mtext *attr, int value)
 Set an object attribute of type int.
OCI_EXPORT boolean OCI_API OCI_ObjectSetUnsignedInt (OCI_Object *obj, const mtext *attr, unsigned int value)
 Set an object attribute of type unsigned int.
OCI_EXPORT boolean OCI_API OCI_ObjectSetBigInt (OCI_Object *obj, const mtext *attr, big_int value)
 Set an object attribute of type big int.
OCI_EXPORT boolean OCI_API OCI_ObjectSetUnsignedBigInt (OCI_Object *obj, const mtext *attr, big_uint value)
 Set an object attribute of type unsigned big int.
OCI_EXPORT boolean OCI_API OCI_ObjectSetDouble (OCI_Object *obj, const mtext *attr, double value)
 Set an object attribute of type double.
OCI_EXPORT boolean OCI_API OCI_ObjectSetString (OCI_Object *obj, const mtext *attr, const dtext *value)
 Set an object attribute of type string.
OCI_EXPORT boolean OCI_API OCI_ObjectSetRaw (OCI_Object *obj, const mtext *attr, void *value, unsigned int len)
 Set an object attribute of type RAW.
OCI_EXPORT boolean OCI_API OCI_ObjectSetDate (OCI_Object *obj, const mtext *attr, OCI_Date *value)
 Set an object attribute of type Date.
OCI_EXPORT boolean OCI_API OCI_ObjectSetTimestamp (OCI_Object *obj, const mtext *attr, OCI_Timestamp *value)
 Set an object attribute of type Timestamp.
OCI_EXPORT boolean OCI_API OCI_ObjectSetInterval (OCI_Object *obj, const mtext *attr, OCI_Interval *value)
 Set an object attribute of type Interval.
OCI_EXPORT boolean OCI_API OCI_ObjectSetColl (OCI_Object *obj, const mtext *attr, OCI_Coll *value)
 Set an object attribute of type Collection.
OCI_EXPORT boolean OCI_API OCI_ObjectSetObject (OCI_Object *obj, const mtext *attr, OCI_Object *value)
 Set an object attribute of type Object.
OCI_EXPORT boolean OCI_API OCI_ObjectSetLob (OCI_Object *obj, const mtext *attr, OCI_Lob *value)
 Set an object attribute of type Lob.
OCI_EXPORT boolean OCI_API OCI_ObjectSetFile (OCI_Object *obj, const mtext *attr, OCI_File *value)
 Set an object attribute of type File.
OCI_EXPORT boolean OCI_API OCI_ObjectSetRef (OCI_Object *obj, const mtext *attr, OCI_Ref *value)
 Set an object attribute of type Ref.
OCI_EXPORT boolean OCI_API OCI_ObjectIsNull (OCI_Object *obj, const mtext *attr)
 Check if an object attribute is null.
OCI_EXPORT boolean OCI_API OCI_ObjectSetNull (OCI_Object *obj, const mtext *attr)
 Set an object attribute to null.
OCI_EXPORT boolean OCI_API OCI_ObjectGetStruct (OCI_Object *obj, void **pp_struct, void **pp_ind)
 Retrieve the underlying C (OTT/OCI style) structure of an OCI_Object handle.
OCI_EXPORT OCI_Ref *OCI_API OCI_RefCreate (OCI_Connection *con, OCI_TypeInfo *typinf)
 Create a local Ref instance.
OCI_EXPORT boolean OCI_API OCI_RefFree (OCI_Ref *ref)
 Free a local Ref.
OCI_EXPORT OCI_Ref **OCI_API OCI_RefArrayCreate (OCI_Connection *con, OCI_TypeInfo *typinf, unsigned int nbelem)
 Create an array of Ref object.
OCI_EXPORT boolean OCI_API OCI_RefArrayFree (OCI_Ref **refs)
 Free an arrray of Ref objects.
OCI_EXPORT boolean OCI_API OCI_RefAssign (OCI_Ref *ref, OCI_Ref *ref_src)
 Assign a Ref to another one.
OCI_EXPORT OCI_TypeInfo *OCI_API OCI_RefGetTypeInfo (OCI_Ref *ref)
 Return the type info object associated to the Ref.
OCI_EXPORT OCI_Object *OCI_API OCI_RefGetObject (OCI_Ref *ref)
 Returns the object pointed by the Ref handle.
OCI_EXPORT boolean OCI_API OCI_RefIsNull (OCI_Ref *ref)
 Check if the Ref points to an object or not.
OCI_EXPORT boolean OCI_API OCI_RefSetNull (OCI_Ref *ref)
 Nullify the given Ref handle.
OCI_EXPORT unsigned int OCI_API OCI_RefGetHexSize (OCI_Ref *ref)
 Returns the size of the hex representation of the given Ref handle.
OCI_EXPORT boolean OCI_API OCI_RefToText (OCI_Ref *ref, unsigned int size, mtext *str)
 Converts a Ref handle value to a hexadecimal string.

Function Documentation

OCI_EXPORT OCI_Object* OCI_API OCI_ObjectCreate ( OCI_Connection con,
OCI_TypeInfo typinf 
)

Create a local object instance.

Parameters:
con- Connection handle
typinf- Object type (type info handle)
Returns:
Return the object handle on success otherwise NULL on failure

Definition at line 611 of file object.c.

Referenced by OCI_MsgCreate().

OCI_EXPORT boolean OCI_API OCI_ObjectFree ( OCI_Object obj)

Free a local object.

Parameters:
obj- Object handle
Warning:
Only object created with OCI_ObjectCreate() should be freed by OCI_ObjectFree()
Returns:
TRUE on success otherwise FALSE

Definition at line 635 of file object.c.

Referenced by OCI_ElemFree(), OCI_MsgFree(), OCI_ObjectGetSelfRef(), OCI_RefAssign(), and OCI_RefSetNull().

OCI_EXPORT OCI_Object** OCI_API OCI_ObjectArrayCreate ( OCI_Connection con,
OCI_TypeInfo typinf,
unsigned int  nbelem 
)

Create an array of Object 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 Object handle array on success otherwise NULL on failure

Definition at line 675 of file object.c.

OCI_EXPORT boolean OCI_API OCI_ObjectArrayFree ( OCI_Object **  objs)

Free an arrray of Object objects.

Parameters:
objs- Array of Object objects
Warning:
Only arrays of Object created with OCI_ObjectArrayCreate() should be freed by OCI_ObjectArrayFree()
Returns:
TRUE on success otherwise FALSE

Definition at line 699 of file object.c.

OCI_EXPORT boolean OCI_API OCI_ObjectAssign ( OCI_Object obj,
OCI_Object obj_src 
)

Assign an object to another one.

Parameters:
obj- Destination Object handle
obj_src- Source Object handle
Note:
Oracle proceeds to a deep copy of the object content
The two object handles must have the same type otherwise an exception is thrown
Returns:
TRUE on success otherwise FALSE

Definition at line 711 of file object.c.

Referenced by OCI_ElemSetObject(), and OCI_MsgSetObject().

OCI_EXPORT unsigned int OCI_API OCI_ObjectGetType ( OCI_Object obj)

Return the type of an object instance.

Parameters:
obj- Object handle
Note:
Possibles values are :
  • OCI_OBJ_PERSISTENT: persistent object from the DB
  • OCI_OBJ_TRANSIENT : local temporary object
  • OCI_OBJ_VALUE : embedded object
Returns:
Instance type or OCI_UNKNOWN the input handle is NULL

Definition at line 1924 of file object.c.

OCI_EXPORT boolean OCI_API OCI_ObjectGetSelfRef ( OCI_Object obj,
OCI_Ref ref 
)

Retrieve an Oracle Ref handle from an object and assign it to the given OCILIB OCI_Ref handle.

Parameters:
obj- Object handle
ref- Ref handle
Note:
The type information of the object and the ref must be the same, otherwise an exception is thrown
Returns:
TRUE on success otherwise FALSE

Definition at line 1940 of file object.c.

References OCI_ObjectFree().

OCI_EXPORT OCI_TypeInfo* OCI_API OCI_ObjectGetTypeInfo ( OCI_Object obj)

Return the type info object associated to the object.

Parameters:
obj- Object handle

Definition at line 1908 of file object.c.

OCI_EXPORT short OCI_API OCI_ObjectGetShort ( OCI_Object obj,
const mtext *  attr 
)

Return the short value of the given object attribute.

Parameters:
obj- Object handle
attr- Attribute name
Note:
If the attribute is found in the object descriptor attributes list, then a datatype check is performed for integrity. OCI_ObjectGetShort() returns a valid value only for integer and number based attributes
Returns:
Attribute value or 0 on failure or wrong attribute type

Definition at line 750 of file object.c.

OCI_EXPORT unsigned short OCI_API OCI_ObjectGetUnsignedShort ( OCI_Object obj,
const mtext *  attr 
)

Return the unsigned short value of the given object attribute.

Parameters:
obj- Object handle
attr- Attribute name
Note:
If the attribute is found in the object descriptor attributes list, then a datatype check is performed for integrity. OCI_ObjectGetUnsignedShort() returns a valid value only for integer and number based attributes
Returns:
Attribute value or 0 on failure or wrong attribute type

Definition at line 767 of file object.c.

OCI_EXPORT int OCI_API OCI_ObjectGetInt ( OCI_Object obj,
const mtext *  attr 
)

Return the integer value of the given object attribute.

Parameters:
obj- Object handle
attr- Attribute name
Note:
If the attribute is found in the object descriptor attributes list, then a datatype check is performed for integrity. OCI_ObjectGetInt() returns a valid value only for integer and number based attributes
Returns:
Attribute value or 0 on failure or wrong attribute type

Definition at line 784 of file object.c.

OCI_EXPORT unsigned int OCI_API OCI_ObjectGetUnsignedInt ( OCI_Object obj,
const mtext *  attr 
)

Return the unsigned integer value of the given object attribute.

Parameters:
obj- Object handle
attr- Attribute name
Note:
If the attribute is found in the object descriptor attributes list, then a datatype check is performed for integrity. OCI_ObjectGetUnsignedInt() returns a valid value only for integer and number based attributes
Returns:
Attribute value or 0 on failure or wrong attribute type

Definition at line 801 of file object.c.

OCI_EXPORT big_int OCI_API OCI_ObjectGetBigInt ( OCI_Object obj,
const mtext *  attr 
)

Return the big integer value of the given object attribute.

Parameters:
obj- Object handle
attr- Attribute name
Note:
If the attribute is found in the object descriptor attributes list, then a datatype check is performed for integrity. OCI_ObjectGetBigInt() returns a valid value only for integer and number based attributes
Returns:
Attribute value or 0 on failure or wrong attribute type

Definition at line 818 of file object.c.

OCI_EXPORT big_uint OCI_API OCI_ObjectGetUnsignedBigInt ( OCI_Object obj,
const mtext *  attr 
)

Return the unsigned big integer value of the given object attribute.

Parameters:
obj- Object handle
attr- Attribute name
Note:
If the attribute is found in the object descriptor attributes list, then a datatype check is performed for integrity. OCI_ObjectGetUnsignedBigInt() returns a valid value only for integer and number based attributes
Returns:
Attribute value or 0 on failure or wrong attribute type

Definition at line 835 of file object.c.

OCI_EXPORT double OCI_API OCI_ObjectGetDouble ( OCI_Object obj,
const mtext *  attr 
)

Return the double value of the given object attribute.

Parameters:
obj- Object handle
attr- Attribute name
Note:
If the attribute is found in the object descriptor attributes list, then a datatype check is performed for integrity. OCI_ObjectGetDouble() returns a valid value only for integer and number based attributes
Returns:
Attribute value or 0.0 on failure or wrong attribute type

Definition at line 852 of file object.c.

OCI_EXPORT const dtext* OCI_API OCI_ObjectGetString ( OCI_Object obj,
const mtext *  attr 
)

Return the string value of the given object attribute.

Parameters:
obj- Object handle
attr- Attribute name
Note:
If the attribute is found in the object descriptor attributes list, then a datatype check is performed for integrity. OCI_ObjectGetString() returns a valid value only for string based attributes
Returns:
Attribute value or NULL on failure or wrong attribute type

Definition at line 869 of file object.c.

OCI_EXPORT int OCI_API OCI_ObjectGetRaw ( OCI_Object obj,
const mtext *  attr,
void *  value,
unsigned int  len 
)

Return the raw attribute value of the given object attribute into the given buffer.

Parameters:
obj- Object handle
attr- Attribute name
value- Destination buffer
len- Max size to write into buffer
Note:
If the attribute is found in the object descriptor attributes list, then a datatype check is performed for integrity. OCI_ObjectGetRaw() copies data into the buffer only for raw based attributes
Returns:
Number of bytes written to the buffer or 0 on failure or wrong attribute type

Definition at line 901 of file object.c.

OCI_EXPORT OCI_Date* OCI_API OCI_ObjectGetDate ( OCI_Object obj,
const mtext *  attr 
)

Return the date value of the given object attribute.

Parameters:
obj- Object handle
attr- Attribute name
Note:
If the attribute is found in the object descriptor attributes list, then a datatype check is performed for integrity. OCI_ObjectGetDate() returns a valid value only for date based attributes
Returns:
Attribute value or NULL on failure or wrong attribute type

Definition at line 942 of file object.c.

OCI_EXPORT OCI_Timestamp* OCI_API OCI_ObjectGetTimestamp ( OCI_Object obj,
const mtext *  attr 
)

Return the timestamp value of the given object attribute.

Parameters:
obj- Object handle
attr- Attribute name
Note:
If the attribute is found in the object descriptor attributes list, then a datatype check is performed for integrity. OCI_ObjectGetTimestamp() returns a valid value only for timestamps based attributes
Returns:
Attribute value or NULL on failure or wrong attribute type

Definition at line 976 of file object.c.

OCI_EXPORT OCI_Interval* OCI_API OCI_ObjectGetInterval ( OCI_Object obj,
const mtext *  attr 
)

Return the interval value of the given object attribute.

Parameters:
obj- Object handle
attr- Attribute name
Note:
If the attribute is found in the object descriptor attributes list, then a datatype check is performed for integrity. OCI_ObjectGetInterval() returns a valid value only for intervals based attributes
Returns:
Attribute value or NULL on failure or wrong attribute type

Definition at line 1014 of file object.c.

OCI_EXPORT OCI_Coll* OCI_API OCI_ObjectGetColl ( OCI_Object obj,
const mtext *  attr 
)

Return the collection value of the given object attribute.

Parameters:
obj- Object handle
attr- Attribute name
Note:
If the attribute is found in the object descriptor attributes list, then a datatype check is performed for integrity. OCI_ObjectGetColl() returns a valid value only for intervals based attributes
Returns:
Attribute value or NULL on failure or wrong attribute type

Definition at line 1051 of file object.c.

OCI_EXPORT OCI_Ref* OCI_API OCI_ObjectGetRef ( OCI_Object obj,
const mtext *  attr 
)

Return the Ref value of the given object attribute.

Parameters:
obj- Object handle
attr- Attribute name
Note:
If the attribute is found in the object descriptor attributes list, then a datatype check is performed for integrity. OCI_ObjectGetRef() returns a valid value only for Refs based attributes
Returns:
Attribute value or NULL on failure or wrong attribute type

Definition at line 1194 of file object.c.

OCI_EXPORT OCI_Object* OCI_API OCI_ObjectGetObject ( OCI_Object obj,
const mtext *  attr 
)

Return the object value of the given object attribute.

Parameters:
obj- Object handle
attr- Attribute name
Note:
If the attribute is found in the object descriptor attributes list, then a datatype check is performed for integrity. OCI_ObjectGetObject() returns a valid value only for object based attributes
Returns:
Attribute value or NULL on failure or wrong attribute type

Definition at line 1088 of file object.c.

OCI_EXPORT OCI_Lob* OCI_API OCI_ObjectGetLob ( OCI_Object obj,
const mtext *  attr 
)

Return the lob value of the given object attribute.

Parameters:
obj- Object handle
attr- Attribute name
Note:
If the attribute is found in the object descriptor attributes list, then a datatype check is performed for integrity. OCI_ObjectGetLob() returns a valid value only for lobs based attributes
Returns:
Attribute value or NULL on failure or wrong attribute type

Definition at line 1124 of file object.c.

OCI_EXPORT OCI_File* OCI_API OCI_ObjectGetFile ( OCI_Object obj,
const mtext *  attr 
)

Return the file value of the given object attribute.

Parameters:
obj- Object handle
attr- Attribute name
Note:
If the attribute is found in the object descriptor attributes list, then a datatype check is performed for integrity. OCI_ObjectGetFile() returns a valid value only for files based attributes
Returns:
Attribute value or NULL on failure or wrong attribute type

Definition at line 1159 of file object.c.

OCI_EXPORT boolean OCI_API OCI_ObjectSetShort ( OCI_Object obj,
const mtext *  attr,
short  value 
)

Set an object attribute of type short.

Parameters:
obj- Object handle
attr- Attribute name
value- Short value
Returns:
TRUE on success otherwise FALSE

Definition at line 1229 of file object.c.

OCI_EXPORT boolean OCI_API OCI_ObjectSetUnsignedShort ( OCI_Object obj,
const mtext *  attr,
unsigned short  value 
)

Set an object attribute of type unsigned short.

Parameters:
obj- Object handle
attr- Attribute name
value- Unsigned short value
Returns:
TRUE on success otherwise FALSE

Definition at line 1243 of file object.c.

OCI_EXPORT boolean OCI_API OCI_ObjectSetInt ( OCI_Object obj,
const mtext *  attr,
int  value 
)

Set an object attribute of type int.

Parameters:
obj- Object handle
attr- Attribute name
value- Int value
Returns:
TRUE on success otherwise FALSE

Definition at line 1257 of file object.c.

OCI_EXPORT boolean OCI_API OCI_ObjectSetUnsignedInt ( OCI_Object obj,
const mtext *  attr,
unsigned int  value 
)

Set an object attribute of type unsigned int.

Parameters:
obj- Object handle
attr- Attribute name
value- Unsigned int value
Returns:
TRUE on success otherwise FALSE

Definition at line 1271 of file object.c.

OCI_EXPORT boolean OCI_API OCI_ObjectSetBigInt ( OCI_Object obj,
const mtext *  attr,
big_int  value 
)

Set an object attribute of type big int.

Parameters:
obj- Object handle
attr- Attribute name
value- Big int value
Returns:
TRUE on success otherwise FALSE

Definition at line 1285 of file object.c.

OCI_EXPORT boolean OCI_API OCI_ObjectSetUnsignedBigInt ( OCI_Object obj,
const mtext *  attr,
big_uint  value 
)

Set an object attribute of type unsigned big int.

Parameters:
obj- Object handle
attr- Attribute name
value- Unsigned big int value
Returns:
TRUE on success otherwise FALSE

Definition at line 1299 of file object.c.

OCI_EXPORT boolean OCI_API OCI_ObjectSetDouble ( OCI_Object obj,
const mtext *  attr,
double  value 
)

Set an object attribute of type double.

Parameters:
obj- Object handle
attr- Attribute name
value- Double value
Returns:
TRUE on success otherwise FALSE

Definition at line 1313 of file object.c.

OCI_EXPORT boolean OCI_API OCI_ObjectSetString ( OCI_Object obj,
const mtext *  attr,
const dtext *  value 
)

Set an object attribute of type string.

Parameters:
obj- Object handle
attr- Attribute name
value- String value
Note:
passing a null pointer for value calls OCI_ObjectSetNull()
Returns:
TRUE on success otherwise FALSE

Definition at line 1327 of file object.c.

References OCI_ObjectSetNull().

OCI_EXPORT boolean OCI_API OCI_ObjectSetRaw ( OCI_Object obj,
const mtext *  attr,
void *  value,
unsigned int  len 
)

Set an object attribute of type RAW.

Parameters:
obj- Object handle
attr- Attribute name
value- Raw value
len- Size of the raw value
Note:
passing a null pointer for value calls OCI_ObjectSetNull()
Returns:
TRUE on success otherwise FALSE

Definition at line 1372 of file object.c.

References OCI_ObjectSetNull().

OCI_EXPORT boolean OCI_API OCI_ObjectSetDate ( OCI_Object obj,
const mtext *  attr,
OCI_Date value 
)

Set an object attribute of type Date.

Parameters:
obj- Object handle
attr- Attribute name
value- Date Handle
Note:
passing a null pointer for value calls OCI_ObjectSetNull()
Returns:
TRUE on success otherwise FALSE

Definition at line 1426 of file object.c.

References OCI_ObjectSetNull().

OCI_EXPORT boolean OCI_API OCI_ObjectSetTimestamp ( OCI_Object obj,
const mtext *  attr,
OCI_Timestamp value 
)

Set an object attribute of type Timestamp.

Parameters:
obj- Object handle
attr- Attribute name
value- Timestamp Handle
Note:
passing a null pointer for value calls OCI_ObjectSetNull()
Returns:
TRUE on success otherwise FALSE

Definition at line 1475 of file object.c.

References OCI_ObjectSetNull().

OCI_EXPORT boolean OCI_API OCI_ObjectSetInterval ( OCI_Object obj,
const mtext *  attr,
OCI_Interval value 
)

Set an object attribute of type Interval.

Parameters:
obj- Object handle
attr- Attribute name
value- Interval Handle
Note:
passing a null pointer for value calls OCI_ObjectSetNull()
Returns:
TRUE on success otherwise FALSE

Definition at line 1531 of file object.c.

References OCI_ObjectSetNull().

OCI_EXPORT boolean OCI_API OCI_ObjectSetColl ( OCI_Object obj,
const mtext *  attr,
OCI_Coll value 
)

Set an object attribute of type Collection.

Parameters:
obj- Object handle
attr- Attribute name
value- Collection Handle
Note:
passing a null pointer for value calls OCI_ObjectSetNull()
Returns:
TRUE on success otherwise FALSE

Definition at line 1587 of file object.c.

References OCI_ObjectSetNull().

OCI_EXPORT boolean OCI_API OCI_ObjectSetObject ( OCI_Object obj,
const mtext *  attr,
OCI_Object value 
)

Set an object attribute of type Object.

Parameters:
obj- Object handle
attr- Attribute name
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_ObjectSetNull()
Returns:
TRUE on success otherwise FALSE

Definition at line 1636 of file object.c.

References OCI_ObjectSetNull().

OCI_EXPORT boolean OCI_API OCI_ObjectSetLob ( OCI_Object obj,
const mtext *  attr,
OCI_Lob value 
)

Set an object attribute of type Lob.

Parameters:
obj- Object handle
attr- Attribute name
value- Lob Handle
Note:
passing a null pointer for value calls OCI_ObjectSetNull()
Returns:
TRUE on success otherwise FALSE

Definition at line 1688 of file object.c.

References OCI_ObjectSetNull().

OCI_EXPORT boolean OCI_API OCI_ObjectSetFile ( OCI_Object obj,
const mtext *  attr,
OCI_File value 
)

Set an object attribute of type File.

Parameters:
obj- Object handle
attr- Attribute name
value- File Handle
Note:
passing a null pointer for value calls OCI_ObjectSetNull()
Returns:
TRUE on success otherwise FALSE

Definition at line 1737 of file object.c.

References OCI_ObjectSetNull().

OCI_EXPORT boolean OCI_API OCI_ObjectSetRef ( OCI_Object obj,
const mtext *  attr,
OCI_Ref value 
)

Set an object attribute of type Ref.

Parameters:
obj- Object handle
attr- Attribute name
value- Ref Handle
Note:
passing a null pointer for value calls OCI_ObjectSetNull()
Returns:
TRUE on success otherwise FALSE

Definition at line 1786 of file object.c.

References OCI_ObjectSetNull().

OCI_EXPORT boolean OCI_API OCI_ObjectIsNull ( OCI_Object obj,
const mtext *  attr 
)

Check if an object attribute is null.

Parameters:
obj- Object handle
attr- Attribute name
Returns:
FALSE if the attribute is not null otherwise TRUE

Definition at line 1871 of file object.c.

OCI_EXPORT boolean OCI_API OCI_ObjectSetNull ( OCI_Object obj,
const mtext *  attr 
)

Set an object attribute to null.

Parameters:
obj- Object handle
attr- Attribute name
Returns:
TRUE on success otherwise FALSE

Definition at line 1835 of file object.c.

Referenced by OCI_ObjectSetColl(), OCI_ObjectSetDate(), OCI_ObjectSetFile(), OCI_ObjectSetInterval(), OCI_ObjectSetLob(), OCI_ObjectSetObject(), OCI_ObjectSetRaw(), OCI_ObjectSetRef(), OCI_ObjectSetString(), and OCI_ObjectSetTimestamp().

OCI_EXPORT boolean OCI_API OCI_ObjectGetStruct ( OCI_Object obj,
void **  pp_struct,
void **  pp_ind 
)

Retrieve the underlying C (OTT/OCI style) structure of an OCI_Object handle.

Parameters:
obj- Object handle
pp_struct- Address of a pointer that retrieve the C structure of data
pp_ind- Address of a pointer that retrieve the C structure of indicators
Note:
See Oracle OCI programming guide for more details about OTT structures. The members of these structures are OCI datatypes like OCINumber, OCIString that requires mixing OCILIB code and raw OCI code. OCI Object API headers have to be included to handle this datatypes using OCI object functions
Returns:
TRUE on success otherwise FALSE

Definition at line 1975 of file object.c.

OCI_EXPORT OCI_Ref* OCI_API OCI_RefCreate ( OCI_Connection con,
OCI_TypeInfo typinf 
)

Create a local Ref instance.

Parameters:
con- Connection handle
typinf- Ref type
Returns:
Return the Ref handle on success otherwise NULL on failure

Definition at line 208 of file ref.c.

OCI_EXPORT boolean OCI_API OCI_RefFree ( OCI_Ref ref)

Free a local Ref.

Parameters:
ref- Ref handle
Warning:
Only Refs created with OCI_RefCreate() should be freed by OCI_RefFree()
Returns:
TRUE on success otherwise FALSE

Definition at line 232 of file ref.c.

Referenced by OCI_ElemFree().

OCI_EXPORT OCI_Ref** OCI_API OCI_RefArrayCreate ( OCI_Connection con,
OCI_TypeInfo typinf,
unsigned int  nbelem 
)

Create an array of Ref object.

Parameters:
con- Connection handle
typinf- Object type (type info handle)
nbelem- number of elements in the array
Note:
see OCI_RefCreate() for more details
Returns:
Return the Ref handle array on success otherwise NULL on failure

Definition at line 262 of file ref.c.

OCI_EXPORT boolean OCI_API OCI_RefArrayFree ( OCI_Ref **  refs)

Free an arrray of Ref objects.

Parameters:
refs- Array of Ref objects
Warning:
Only arrays of Ref created with OCI_RefArrayCreate() should be freed by OCI_RefArrayFree()
Returns:
TRUE on success otherwise FALSE

Definition at line 286 of file ref.c.

OCI_EXPORT boolean OCI_API OCI_RefAssign ( OCI_Ref ref,
OCI_Ref ref_src 
)

Assign a Ref to another one.

Parameters:
ref- Destination Ref handle
ref_src- Source Ref handle
Note:
The two Ref handles must have the same type otherwise an exception is thrown
Returns:
TRUE on success otherwise FALSE

Definition at line 323 of file ref.c.

References OCI_ObjectFree().

Referenced by OCI_ElemSetRef().

OCI_EXPORT OCI_TypeInfo* OCI_API OCI_RefGetTypeInfo ( OCI_Ref ref)

Return the type info object associated to the Ref.

Parameters:
ref- Ref handle

Definition at line 477 of file ref.c.

OCI_EXPORT OCI_Object* OCI_API OCI_RefGetObject ( OCI_Ref ref)

Returns the object pointed by the Ref handle.

Parameters:
ref- Ref handle
Returns:
The object handle is the ref is not null otherwise NULL

Definition at line 298 of file ref.c.

References OCI_RefIsNull().

OCI_EXPORT boolean OCI_API OCI_RefIsNull ( OCI_Ref ref)

Check if the Ref points to an object or not.

Parameters:
ref- Ref handle
Returns:
TRUE if it does not point to a valid object otherwise FALSE

Definition at line 364 of file ref.c.

Referenced by OCI_RefGetObject().

OCI_EXPORT boolean OCI_API OCI_RefSetNull ( OCI_Ref ref)

Nullify the given Ref handle.

Parameters:
ref- Ref handle
Note:
this call clears the reference to object pointed by the Ref handle.
Returns:
TRUE on success otherwise FALSE

Definition at line 380 of file ref.c.

References OCI_ObjectFree().

OCI_EXPORT unsigned int OCI_API OCI_RefGetHexSize ( OCI_Ref ref)

Returns the size of the hex representation of the given Ref handle.

Parameters:
ref- Ref handle
Note:
the returned size is the number of character needed to store the hex representation of the Ref that can be retrieved with OCI_RefToText()

Definition at line 455 of file ref.c.

OCI_EXPORT boolean OCI_API OCI_RefToText ( OCI_Ref ref,
unsigned int  size,
mtext *  str 
)

Converts a Ref handle value to a hexadecimal string.

Parameters:
ref- Ref handle
size- Destination string size in characters
str- Destination string
Returns:
TRUE on success otherwise FALSE

Definition at line 411 of file ref.c.

Referenced by OCI_GetString().