EV_extractElement

- extract a data element from an EV_AttrValue structure

SYNOPSIS

#include <$OV_HEADER/ecs/EV/value.h>
int32 EV_extractElement
(
	const EV_AttrValue *AV,
	int32 elementNum,
	EV_AttrType *attrType,
	int32 *size,
	const void **elementData
);

DESCRIPTION

This function can be used to extract a data element from an EV_AttrValue structure of type EV_LIST or EV_TUPLE.

A pointer to an EV_AttrValue and an element number must be specified. The function returns the attribute type and size in bytes of the specified element, plus a pointer to it. The data pointer should be cast to the data type corresponding to the returned attribute type (corresponding to ECDL types) as follows:

EV_STRING    (char *)
EV_INTEGER   (int32 *)
EV_REAL      (real64 *)
EV_BOOLEAN   (ecsbool *)  ecstrue = 1, ecsfalse = 0
EV_TIME      (EV_Time *)
EV_DURATION  (EV_Duration *)
EV_OID       (u_int32 *)
EV_NULL      -
EV_TUPLE     (EV_AttrValue *)
EV_LIST      (EV_AttrValue *)

The data types EV_Time, EV_Duration are defined in the $OV_HEADERS/ecs/EV/value_struct.h header file.

If the specified element has an attribute type of EV_NULL, the returned size is zero, and the returned pointer value is NULL and size is 0.

If the specified element has an attribute type of EV_TUPLE or EV_LIST, the returned size is zero, and elementData is a pointer to another EV_AttrValue.

This can be decoded with further calls to EV_extractElement.

Parameters

const EV_AttrValue *AV

TheEV_AttrValue structure of typeEV_LIST orEV_TUPLE to extract data from.

int32 elementNum

Number of the data element to extract, starting at 1 for the first element of a list or tuple.

EV_AttrType *attrType

Returns the attribute type of the data element.

int32 *size

Returns size of the data element (in bytes). 0 is returned for EV_LIST and EV_TUPLE types.

const void **elementData

The address of a pointer to the actual data for the specified data element. This pointer should be cast to the data type corresponding to the attribute type of the data element The pointer points to storage inside the EV_AttrValue structure, and is valid until the AV is freed (using EV_deleteValue).

RETURNS

ECS_SUCCESS

Succeeded.

ECS_BAD_PARAMETER

ElementNum is less than 1.

EV_INCORRECT_AV_TYPE

AV is not an EV_AttrValue of EV_LIST or EV_TUPLE type.

EV_NO_SUCH_ELEMENT

ElementNum does not exist in AV.