OCI Any Data Interface Functions

This section describes the Any Data Interface functions.

---

OCIAnyDataAccess()

Purpose

Retrieves the data value of an OCIAnyData. The data value should be of the type with which the OCIAnyData was initialized. This call can be used to access an entire OCIAnyData which can be of type OCI_TYPECODE_OBJECT, any of the collection types, or any of the built-in types.

Syntax

sword OCIAnyDataAccess ( OCISvcCtx    *svchp, 
                         OCIError     *errhp,
                         OCIAnyData   *sdata, 
                         OCITypeCode  tc, 
                         OCIType      *inst_type, 
                         void         *null_ind, 
                         void         *data_value, 
                         ub4          *length );

Parameters

svchp (IN)

The OCI service context.

errhp (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().

sdata (IN)

Initialized pointer to an OCIAnyData.

tc (IN)

Typecode of the data value. This is used for type checking (with the initialization type of the OCIAnyData).

inst_type (IN)

The OCIType of the data value (if it is not a primitive one). If the tc parameter is

• OCI_TYPECODE_OBJECT,

• OCI_TYPECODE_REF,

• OCI_TYPECODE_VARRAY,

• OCI_TYPECODE_TABLE,

then this parameter should be not NULL. Otherwise, it could be NULL.

null_ind (OUT)

Indicates if the data_value is NULL. Pass an (OCIInd *) for all typecodes except OCI_TYPECODE_OBJECT. The value returned will be OCI_IND_NOTNULL if the value is not NULL and it will be OCI_IND_NULL for a NULL value. If the typecode is OCI_TYPECODE_OBJECT, pass a pointer to the indicator struct of the data_value as the argument here. See OCIAnyDataAttrGet() for details.

data_value (OUT)

The data value (will be of the type with which the OCIAnyData was initialized). See OCIAnyDataAttrGet() for the appropriate C type corresponding to each allowed typecode and for a description of how memory allocation behavior depends on the value passed for this parameter.

length (OUT)

Currently, this parameter is ignored. In the future, this may be used for certain typecodes where the data representation itself will not give the length, in bytes, implicitly.

---

OCIAnyDataAttrGet()

Purpose

Gets the value of the attribute at the current position in the OCIAnyData. Attribute values can be accessed sequentially.

Syntax

sword OCIAnyDataAttrGet ( OCISvcCtx    *svchp, 
                          OCIError     *errhp, 
                          OCIAnyData   *sdata, 
                          OCITypeCode  tc, 
                          OCIType      *attr_type, 
                          void         *null_ind, 
                          void         *attr_value, 
                          ub4          *length, 
                          boolean      is_any );

Parameters

svchp (IN)

The OCI service context.

errhp (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().

sdata (IN/OUT)

Pointer to initialized of type OCIAnyData.

tc (IN)

Typecode of the attribute. Type checking happens based on tc, attr_type and the type information in the OCIAnyData.

attr_type (IN) [OPTIONAL]

attr_type should give the type description of the referenced type (for OCI_TYPECODE_REF) or the type description of the collection type (for OCI_TYPECODE_VARRAY, OCI_TYPECODE_TABLE) or the type description of the object (for OCI_TYPECODE_OBJECT). This parameter is not required for built-in typecodes.

null_ind (OUT)

Indicates if the attr_value is NULL. Pass (OCIInd *) in null_ind for all typecodes except OCI_TYPECODE_OBJECT.

If the typecode is OCI_TYPECODE_OBJECT, pass a pointer (void **) in null_ind.

The indicator returned will be OCI_IND_NOTNULL if the value is not NULL and it will be OCI_IND_NULL for a NULL value.

attr_value (IN/OUT)

Value for the attribute

length (IN/OUT)

Currently, this parameter is ignored. Pass 0 here. In the future, this may be used for certain typecodes where the data representation itself will not give the length, in bytes, implicitly.

is_any (IN)

Is attribute to be returned in the form of OCIAnyData?

Comments

This call can be used with OCIAnyData of typecode OCI_TYPECODE_OBJECT only

• This call gets the value of the attribute at the current position in the OCIAnyData.

• tc must match the type of the attribute at the current position, otherwise an error is returned.

• is_any is applicable only when the typecode of the attribute is one of the following:

  • OCI_TYPECODE_OBJECT,

  • OCI_TYPECODE_VARRAY,

  • OCI_TYPECODE_TABLE.

  If is_any is TRUE, then attr_value is returned in the form of OCIAnyData*.

• You must allocate the memory for the attribute before calling the function. You can allocate memory through OCIObjectNew(). In case of built-in types such as NUMBER, VARCHAR, etc, the attribute can be just a pointer to a stack variable. Here is the list of available Oracle datatypes which can be used as object attribute types and the corresponding types of the attribute value that should be passed:

---

OCIAnyDataAttrSet()

Purpose

Sets the attribute at the current position with a given value.

Syntax

sword OCIAnyDataAttrSet ( OCISvcCtx    *svchp, 
                          OCIError     *errhp, 
                          OCIAnyData   *sdata, 
                          OCITypeCode  tc, 
                          OCIType      *attr_type, 
                          void         *null_ind, 
                          void         *attr_value, 
                          ub4          length, 
                          boolean      is_any );

Parameters

svchp (IN)

The OCI service context.

errhp (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().

sdata (IN/OUT)

Initialized OCIAnyData.

tc (IN)

Typecode of the attribute. Type checking happens based on tc, attr_type and the type information in the OCIAnyData.

attr_type (IN)

OPTIONAL

attr_type will give the type description of the referenced type (for OCI_TYPECODE_REF) and it will give the type description of the collection type (for OCI_TYPECODE_VARRAY, OCI_TYPECODE_TABLE) and it will give the type description of the object (for OCI_TYPECODE_OBJECT). This parameter is not required for built-in typecodes or if OCI_TYPECODE_NONE is specified.

null_ind (IN)

Indicates if the attr_value is NULL. Pass (OCIInd *) for all typecodes except OCI_TYPECODE_OBJECT. The indicator should be OCI_IND_NOTNULL if the value is not NULL and it should be OCI_IND_NULL for a NULL value.

If the typecode is OCI_TYPECODE_OBJECT, pass a pointer to the indicator struct of the attr_value as the argument here.

attr_value (IN)

Value for the attribute

length (IN)

Currently, this parameter is ignored. Pass 0 here. In the future, this may be used for certain typecodes where the data representation itself will not give the length implicitly.

is_any (IN)

Is attribute in the form of OCIAnyData?

Comments

OCIAnyDataBeginCreate() creates an OCIAnyData with an empty skeleton instance. To fill the attribute values, use OCIAnyDataAttrSet() (for OCI_TYPECODE_OBJECT) or OCIAnyDataCollAttrAddElem() (for the collection typecodes).

Attribute values must be set in order, from the first attribute to the last. The current attribute number is remembered as state maintained inside the OCIAnyData. Piece-wise construction of embedded attributes and collection elements are not yet supported.

This call sets the attribute at the current position with attr_value. Once piece-wise construction has started for an OCIAnyData instance, the OCIAnyDataConstruct() calls can no longer be used.

tc must match the type of the attribute at the current position. Otherwise, an error is returned.

If is_any is TRUE, then the attribute must be in the form of OCIAnyData* and it is copied into the enclosing OCIAnyData (data) without any conversion.

Here is the list of available datatypes which can be used as object attribute types and the corresponding types of the attribute value that should be passed:

---

OCIAnyDataBeginCreate()

Purpose

Allocates an OCIAnyData for the given duration and initializes it with the type information.

Syntax

sword OCIAnyDataBeginCreate ( OCISvcCtx      *svchp, 
                              OCIError       *errhp, 
                              OCITypeCode    tc, 
                              OCIType        *type,
                              OCIDuration    dur,
                              OCIAnyData     **sdata );

Parameters

svchp (IN)

The OCI service context.

errhp (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().

sdata (IN/OUT)

Initialized OCIAnyData.

tc (IN)

Typecode corresponding to the OCIAnyData. Can be a built-in typecode or a user-defined type's typecode such as:

• OCI_TYPECODE_OBJECT,

• OCI_TYPECODE_REF,

• OCI_TYPECODE_VARRAY.

type (IN)

The type corresponding to OCIAnyData. If the typecode corresponds to a built-in type (OCI_TYPECODE_NUMBER, and so on), this parameter can be NULL. It should be non-NULL for user defined types (OCI_TYPECODE_OBJECT, OCI_TYPECODE_REF, collection types, and so on).

dur (IN)

Duration for which OCIAnyData is allocated. One of the following:

• A user duration that was previously created. It can be created by using OCIDurationBegin().

• A predefined duration, such as OCI_DURATION_SESSION.

sdata (OUT)

Initialized OCIAnyData. If (*sdata) is not NULL at the beginning of the call, the memory could be reused instead of reallocating space for the OCIAnyData.

Therefore, do not pass an uninitialized pointer here.

Comments

OCIAnyDataBeginCreate() creates an OCIAnyData with an empty skeleton instance. To fill in the attribute values, use OCIAnyDataAttrSet() for OCI_TYPECODE_OBJECT, or OCIAnyDataCollAttrAddElem() for the collection typecodes.

Attribute values must be set in order. They must be set from the first attribute to the last one. The current attribute number is remembered as state maintained inside the OCIAnyData. Piece-wise construction of embedded attributes and collection elements are not yet supported.

For performance reasons, the OCIAnyData will end up pointing to the OCIType parameter passed in. It is your responsibility to ensure that the OCIType is longer lived (has allocation duration >= the duration of the OCIAnyData, if the OCIType is a transient one, or has allocation/pin duration >= duration of the OCIAnyData, if the OCIType is a persistent one).

---

OCIAnyDataCollAddElem()

Purpose

Adds the next collection element to the collection attribute of the OCIAnyData at the current attribute position. If the OCIAnyData is of a collection type, then there is no notion of attribute position and this call adds the next collection element.

Syntax

sword OCIAnyDataCollAddElem ( OCISvcCtx    *svchp, 
                              OCIError     *errhp, 
                              OCIAnyData   *sdata, 
                              OCITypeCode  collelem_tc, 
                              OCIType      *collelem_type, 
                              void         *null_ind, 
                              void         *elem_value, 
                              ub4          length, 
                              boolean      is_any, 
                              boolean      last_elem );

Parameters

svchp (IN)

The OCI service context.

errhp (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().

sdata (IN/OUT)

Initialized OCIAnyData.

collelem_tc (IN)

The typecode of the collection element to be added. Type checking happens based on collelem_tc, collelem_type and the type information in the OCIAnyData.

collelem_type (IN)

OPTIONAL

collelem_type will give the type description of the referenced type (for OCI_TYPECODE_REF) and it will give the type description of the collection type (for OCI_TYPECODE_NAMEDCOLLECTION) and it will give the type description of the object (for OCI_TYPECODE_OBJECT).

This parameter is not required for built-in typecodes.

null_ind (IN)

Indicates if the elem_value is NULL. Pass an (OCIInd *) for all typecodes except OCI_TYPECODE_OBJECT. The indicator should be OCI_IND_NOTNULL if the value is not NULL and it should be OCI_IND_NULL for a NULL value.

If the typecode is OCI_TYPECODE_OBJECT, pass a pointer to the indicator struct of the elem_value as the argument here.

elem_value (IN)

Value for the collection element

length (IN)

Length of the collection element

is_any (IN)

Is the attribute in the form of OCIAnyData?

last_elem (IN)

Is the element being added the last in the collection?

Comments

This call can be invoked for an OCIAnyData of type OCI_TYPECODE_OBJECT or of any of the collection types. Once piece-wise construction has started for an OCIAnyData instance, the OCIAnyDataConstruct() calls can no longer be used.

As in OCIAnyDataAttrSet(), is_any is applicable only if the collelem_tc is that of typecode OCI_TYPECODE_OBJECT or a collection typecode. If is_any is TRUE, the attribute should be in the form of OCIAnyData *.

If the element being added is the last element in the collection, last_elem should be set to TRUE.

To add a NULL element, the NULL indicator, null_ind should be set to OCI_IND_NULL, in which case all other arguments will be ignored. Otherwise, null_ind must be set to OCI_IND_NOTNULL.

See "OCIAnyDataAttrSet()" for the type of attribute to be passed in for all the possible types of the collection elements.

---

OCIAnyDataCollGetElem()

Purpose

Accesses sequentially the elements in the collection attribute at the current position in the OCIAnyData.

Syntax

sword OCIAnyDataCollGetElem ( OCISvcCtx    *svchp, 
                              OCIError     *errhp, 
                              OCIAnyData   *sdata, 
                              OCITypeCode  collelem_tc, 
                              OCIType      *collelem_type, 
                              void         *null_ind, 
                              void         *collelem_value, 
                              ub4          *length, 
                              boolean      is_any );

Parameters

svchp (IN)

The OCI service context.

errhp (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().

sdata (IN/OUT)

Initialized OCIAnyData.

collelem_tc (IN)

The typecode of the collection element to be retrieved. Type checking happens based on collelem_tc, collelem_type and the type information in the OCIAnyData.

collelem_type (IN)

OPTIONAL

collelem_type will give the type description of the referenced type (for OCI_TYPECODE_REF) and it will give the type description of the collection type (for OCI_TYPECODE_NAMEDCOLLECTION) and it will give the type description of the object (for OCI_TYPECODE_OBJECT).

This parameter is not required for built-in typecodes.

null_ind (OUT)

Indicates if the collelem_value is NULL. Pass an (OCIInd *) for all typecodes except OCI_TYPECODE_OBJECT. The indicator should be OCI_IND_NOTNULL if the value is not NULL and it should be OCI_IND_NULL for a NULL value.

If the typecode is OCI_TYPECODE_OBJECT, pass a pointer (void **) to the indicator struct of the collelem_value as the argument here.

collelem_value (IN/OUT)

Value for the collection element

length (IN/OUT)

Length of the collection element. Currently ignored. Set to 0 on input.

is_any (IN)

Is attr_value to be returned in the form of OCIAnyData?

Comments

The OCIAnyData data can also correspond to a top level collection. If the OCIAnyData is of type OCI_TYPECODE_OBJECT, the attribute at the current position must be a collection of appropriate type. Otherwise, an error is returned.

As for OCIAnyDataAttrGet(), the is_any parameter is applicable only if collelem_tc typecode is that OCI_TYPECODE_OBJECT. If is_any is TRUE, the attr_value will be in the form of OCIAnyData *.

This call returns OCI_NO_DATA when the end of the collection has been reached. It returns OCI_SUCCESS upon success and OCI_ERROR upon error.

See "OCIAnyDataAttrGet()") for the type of attribute to be passed in for all the possible types of the collection elements.

---

OCIAnyDataConvert()

Purpose

Constructs an OCIAnyData with the given data value which will be of the given type. This call can be used to construct an entire OCIAnyData which could be of type OCI_TYPECODE_OBJECT, any of the collection types, or any of the built-in types.

Syntax

sword OCIAnyDataConvert ( OCISvcCtx    *svchp, 
                          OCIError     *errhp, 
                          OCITypeCode  tc, 
                          OCIType      *inst_type, 
                          OCIDuration  dur, 
                          void         *null_ind, 
                          void         *data_value, 
                          ub4          length, 
                          OCIAnyData   **sdata );

Parameters

svchp (IN)

The OCI service context.

errhp (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().

tc (IN)

Typecode of the data value. Can be a built-in typecode or a user-defined type's typecode (such as OCI_TYPECODE_OBJECT, OCI_TYPECODE_REF, OCI_TYPECODE_VARRAY).

If (*sdata) is not NULL and it represents a skeleton instance returned during the OCIAnyDataSetAddInstance(), the tc as well as the inst_type parameters are optional here. This is because the type-information for such a skeleton instance is already known. If the tc and inst_type parameters are provided here for this situation, they will be used only for type-checking purposes.

inst_type (IN)

Type corresponding to the OCIAnyData. If the typecode corresponds to a built-in type (OCI_TYPECODE_NUMBER, and so on), this parameter can be NULL. It should not be NULL for user defined types (OCI_TYPECODE_OBJECT, OCI_TYPECODE_REF, or collection types).

dur (IN)

Duration for which the OCIAnyData is allocated. One of the following:

• A user duration that was previously created. It can be created by using OCIDurationBegin().

• A predefined duration, such as OCI_DURATION_SESSION.

null_ind

Indicates if data_value is NULL. Pass an (OCIInd *) for all typecodes except OCI_TYPECODE_OBJECT. The indicator will be OCI_IND_NOTNULL if the value is not NULL and it will be OCI_IND_NULL for a NULL value.

If the typecode is OCI_TYPECODE_OBJECT, pass a pointer to the indicator struct of the data_value as the argument here.

data_value (IN)

The data value (should be of the type with which the OCIAnyData was initialized). See OCIAnyDataAttrSet() for the appropriate C type corresponding to each allowed typecode.

length (IN)

Currently, this parameter is ignored. Pass 0 here. In the future, this may be used for certain typecodes where the data representation itself will not give the length implicitly.

sdata (IN/OUT)

Initialized OCIAnyData. If (*sdata) is not NULL at the beginning of the call, the memory could bet reused instead of reallocating space for the OCIAnyData.

Therefore, do not pass an un-initialized pointer here.

If (*sdata) represents a skeleton instance returned during an OCIAnyDataSetAddInstance() call, the tc and inst_type parameters will be used for type-checking purposes if necessary.

Comments

For performance reasons, the OCIAnyData pointer will end up pointing to the passed in OCIType parameter. It is your responsibility to ensure that the OCIType is longer lived (has allocation duration >= the duration of the OCIAnyData, if the OCIType is a transient one, or has allocation/pin duration >= duration of the OCIAnyData, if the OCIType is a persistent one).

---

OCIAnyDataDestroy()

Purpose

Frees an AnyData.

Syntax

sword OCIAnyDataDestroy ( OCISvcCtx      *svchp, 
                          OCIError       *errhp, 
                          OCIAnyData     *sdata );

Parameters

svchp (IN)

The OCI service context.

errhp (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().

sdata (IN/OUT)

Pointer to an of type OCIAnyData to be freed.

---

OCIAnyDataEndCreate()

Purpose

Marks the end of OCIAnyData creation. It should be called after initializing all attributes of its instances with suitable values. This call is valid only if OCIAnyDataBeginCreate() had been called earlier for the OCIAnyData.

Syntax

sword OCIAnyDataEndCreate ( OCISvcCtx      *svchp, 
                            OCIError       *errhp, 
                            OCIAnyData     *data );

Parameters

svchp (IN)

The OCI service context.

errhp (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().

data (IN/OUT)

Initialized OCIAnyData.

---

OCIAnyDataGetCurrAttrNum()

Purpose

Returns the current attribute number of the OCIAnyData. If the OCIAnyData is being constructed, it refers to the current attribute that is being set. Else, if the OCIAnyData is being accessed, it refers to the attribute that is being accessed.

Syntax

sword OCIAnyDataGetCurrAttrNum( OCISvcCtx      *svchp, 
                                OCIError       *errhp, 
                                OCIAnyData     *sdata,
                                ub4            *attrnum );

Parameters

svchp (IN)

The OCI service context.

errhp (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().

sdata (IN)

Initialized OCIAnyData.

attrnum (OUT)

The attribute number.

---

OCIAnyDataGetType()

Purpose

Gets the type corresponding to an AnyData value. It returns the actual pointer to the type maintained inside an OCIAnyData. No copying is done for performance reasons. You are responsible for not using this type once the OCIAnyData is freed (or its duration ends).

Syntax

sword OCIAnyDataGetType( OCISvcCtx      *svchp, 
                         OCIError       *errhp, 
                         OCIAnyData     *data,
                         OCITypeCode    *tc, 
                         OCIType        **type ); 

Parameters

svchp (IN)

The OCI service context.

errhp (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().

data (IN)

Initialized OCIAnyData.

tc (OUT)

The typecode corresponding to the OCIAnyData.

type (OUT)

The type corresponding to the OCIAnyData. This will be NULL if the OCIAnyData corresponds to a built-in type.

---

OCIAnyDataIsNull()

Purpose

Checks if the contents of the type within the OCIAnyData is NULL.

Syntax

sword OCIAnyDataIsNull ( OCISvcCtx         *svchp, 
                         OCIError          *errhp,
                         const OCIAnyData  *sdata,
                         boolean           *isNull) ; 

Parameters

svchp (IN)

The OCI service context.

errhp (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().

sdata (IN)

OCIAnyData to be checked.

isNull (IN/OUT)

TRUE if NULL, else FALSE.

---

OCIAnyDataTypeCodeToSqlt()

Purpose

Converts the OCITypeCode for an AnyData value to the SQLT code that corresponds to the representation of the value as returned by the OCIAnyData API.

Syntax

sword  OCIAnyDataTypeCodeToSqlt ( OCIError       *errhp, 
                                  OCITypeCode    tc,
                                  ub1            *sqltcode,
                                  ub1            *csfrm) ;

Parameters

errhp (IN/OUT)

The OCI error handle. If there is an error, it is recorded in errhp and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().

tc (IN)

OCITypeCode corresponding to the AnyData value.

sqltcode (OUT)

SQLT code corresponding to the user format of the typecode.

csfrm (OUT)

Charset form corresponding to the user format of the typecode. Meaningful only for character types. Returns SQLCS_IMPLICIT or SQLCS_NCHAR (for NCHAR types).

Comments

This function converts OCI_TYPECODE_CHAR as well as OCI_TYPECODE_VARCHAR2 to SQLT_VST (which corresponds to the OCIString mapping) with a charset form of SQLCS_IMPLICIT. OCI_TYPECODE_NVARCHAR2 will also return SQLT_VST (OCIString mapping is used by the OCIAnyData API) with a charset form of SQLCS_NCHAR.