GetVariant

C++

long GetVariant(
  VARIANT *VariantBuffer,             // variant that receives data
  long NumberOfElements = -1,         // number of elements to read
  long FilePosition = -1,             // position of data in file
  long DataType =                     // forced data type
   IXF_VARIANT_VARIANT
);

BASIC

GetVariant(
  VariantBuffer As Variant,           // variant that receives data
  NumberOfElements As Long = -1,      // number of elements to read
  FilePosition As Long = -1,          // position of data in file
  DataType As VariantType =           // forced data type
   IXF_VARIANT_VARIANT        
) As Long

Parameters

VariantBuffer

Variant that receives data.
Variant can be of any allowed type, it can be either single variable or one dimensional array.
Variant can be uninitialized; in such case it is converted to type determined by DataType parameter.

NumberOfElements

Number of elements in data sequence to read.
If this parameter is -1 length of sequence is determined by the number of elements in VariantBuffer.

FilePosition

Position in file to read data at.
If this parameter is -1 data is read at current file position.

VariantType

Type of data to read, must be one of the following values:

IXF_VARIANT_BYTE	byte (unsigned 8 bit),
IXF_VARIANT_SHORT	short integer (16 bit),
IXF_VARIANT_LONG	long integer (32 bit),
IXF_VARIANT_BOOL	boolean (16 bit),
IXF_VARIANT_FLOAT	single precision floating point number (32 bit),
IXF_VARIANT_DOUBLE	double precision floating point number (64 bit),
IXF_VARIANT_CURRENCY	currency (64 bit),
IXF_VARIANT_DATE	date (64 bit),
IXF_VARIANT_DECIMAL	decimal number (128 bit),
IXF_VARIANT_STRING	Unicode text (variable size),
IXF_VARIANT_VARIANT	variant (variable size).
Following data types are also allowed but not available in Visual Basic:
IXF_VARIANT_CHAR	character (8 bit),
IXF_VARIANT_USHORT	unsigned short integer (16 bit),
IXF_VARIANT_ULONG	unsigned long integer (32 bit),
IXF_VARIANT_INT	machine integer (32 bit),
IXF_VARIANT_UINT	machine unsigned integer (32 bit).

Return Values

Remarks

VariantBuffer can be either single variable or one-dimensional array depending on how many elements are to be read. If only one element is to be read, VariantBuffer can be a single variable of given type or an uninitialized variant; in the second case it is converted to DataType type. If more than one element is to be read VariantBuffer must be a one-dimensional array either fixed- or variable-size. If it is a fixed-size array its size must be large enough to accept at most NumberOfElements elements. If it is a variable-size array it may be redimensioned to appropriate size for accepting all elements; please note that array is redimensioned only if its size is too small - array size is never decreased. If VariantBuffer is an array of variants (either variable- or fixed-size) it is never resized - NumberOfElements must specify exact or smaller number of elements that VariantBuffer can accept.

VariantBuffer variant can be of one of allowed types: Byte, Integer, Long, Single, Double, String, Boolean, Date, Currency, Decimal and Variant. The array of variants is especially interesting because it allows reading complex structured data with fields of various types. The only limitation is that all arrays must be one-dimensional. As mentioned above VariantBuffer can contain String data; it should be noted, however, that text in variant is always represented by IXFile as length-prefixed Unicode.

If VariantBuffer is uninitialized NumberOfElements must explicitly specify length of data sequence to read and DataType must explicitly specify type of data to read. If DataType is IXF_VARIANT_VARIANT VariantBuffer determines type of data and must be initialized to one of allowed types.

NumberOfElements parameter always specifies total number of elements in data sequence regardless of its structure. It means that if VariantBuffer consists of nested subarrays NumberOfElements specifies number of elements counted recursively through all subarrays - not elements in most outer array.

See Also