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, 
                          dvoid        *null_ind, 
                          dvoid        *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, etc.), 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).