Oracle® Call Interface Programmer's Guide, 11g Release 2 (11.2) Part Number E10646-02 |
|
|
View PDF |
This section describes the Any Data Interface functions.
Table 21-4 Any Data Functions
Function/Page | Purpose |
---|---|
Retrieves the data value of an |
|
Gets the value of the attribute at the current position in the |
|
Sets the attribute at the current position with a given value. |
|
Allocates an |
|
Adds the next collection element to the collection attribute of the |
|
Accesses sequentially the elements in the collection attribute at the current position in the |
|
Constructs an |
|
Frees an AnyData . |
|
Marks the end of |
|
Returns the current attribute number of the |
|
Gets the type corresponding to an AnyData value. |
|
Checks if |
|
Converts the |
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
The OCI service context.
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()
.
Initialized pointer to an OCIAnyData
.
Typecode of the data value. This is used for type checking (with the initialization type of the OCIAnyData
).
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
.
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.
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.
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.
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
The OCI service context.
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()
.
Pointer to initialized of type OCIAnyData
.
Typecode of the attribute. Type checking happens based on tc
, attr_type
and the type information in the OCIAnyData
.
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.
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.
Value for the attribute
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 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:
Table 21-5 Datatypes and Attribute Values
Datatypes | attr_value |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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
The OCI service context.
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()
.
Initialized OCIAnyData
.
Typecode of the attribute. Type checking happens based on tc
, attr_type
and the type information in the OCIAnyData
.
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.
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.
Value for the attribute
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 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:
Table 21-6 Datatypes and Attribute Values
Datatypes | attr_value |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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
The OCI service context.
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()
.
Initialized OCIAnyData
.
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
.
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).
Duration for which OCIAnyData
is allocated. One of the following:
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).
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
The OCI service context.
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()
.
Initialized OCIAnyData
.
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
.
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.
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.
Value for the collection element
Length of the collection element
Is the attribute in the form of OCIAnyData
?
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.
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
The OCI service context.
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()
.
Initialized OCIAnyData
.
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
.
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.
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.
Value for the collection element
Length of the collection element. Currently ignored. Set to 0 on input.
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.
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
The OCI service context.
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()
.
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.
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).
Duration for which the OCIAnyData
is allocated. One of the following:
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.
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.
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.
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).
Purpose
Frees an AnyData.
Syntax
sword OCIAnyDataDestroy ( OCISvcCtx *svchp, OCIError *errhp, OCIAnyData *sdata );
Parameters
The OCI service context.
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()
.
Pointer to an of type OCIAnyData
to be freed.
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
The OCI service context.
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()
.
Initialized OCIAnyData
.
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
The OCI service context.
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()
.
Initialized OCIAnyData
.
The attribute number.
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
The OCI service context.
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()
.
Initialized OCIAnyData
.
The typecode corresponding to the OCIAnyData
.
The type corresponding to the OCIAnyData
. This will be NULL
if the OCIAnyData
corresponds to a built-in type.
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
The OCI service context.
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()
.
OCIAnyData
to be checked.
TRUE
if NULL
, else FALSE
.
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
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()
.
OCITypeCode
corresponding to the AnyData value.
SQLT code corresponding to the user format of the typecode.
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.
See Also:
For more information see "NCHAR Typecodes for OCIAnyData Functions"