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, etc.), this parameter can be NULL. It should be non-NULL for user defined types (OCI_TYPECODE_OBJECT, OCI_TYPECODE_REF, collection types, etc.)

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).