Array Descriptors

An array descriptor describes an array or array subset to be retrieved or written to the ISC_ARRAY_DESC_V2 structure. ISC_ARRAY_DESC_V2 is defined in the InterBase header file as follows:

typedef struct {
short array_desc_version;
unsigned char array_desc_dtype;
char array_desc_scale;
unsigned short array_desc_length;
char array_desc_field_name [METADATALENGTH];
char array_desc_relation_name [METADATALENGTH];
short array_desc_dimensions;
short array_desc_flags;
ISC_ARRAY_BOUND array_desc_bounds [16];
} ISC_ARRAY_DESC_V2;

ISC_ARRAY_BOUND is defined as:

typedef struct {
short array_bound_lower; /* lower bound */
short array_bound_upper; /* upper bound */
} ISC_ARRAY_BOUND;

Array Descriptor Fields

Field	Description
array_desc_version	Set to ARRAY_DESC_CURRENT_VERSION
array_desc_dtype	Data type (see below)
array_desc_scale	Scale for numeric data types
array_desc_length	Length in bytes of each array element
array_desc_field_name	NULL-terminated column name
array_desc_relation_name	NULL-terminated relation name
array_desc_dimensions	Number of array dimensions
array_desc_flags	Specifies whether array is to be accessed in row- major or column-major order 0: row-major 1: column-major
array_desc_bounds	Lower and upper bounds for each dimension

Note:
The ISC_ARRAY_DESC_V2 structure supports long metadata names of length METADATALENGTH. The older ISC_ARRAY_DESC structure supports only metadata names of 32 bytes or less.

The array_desc_version field is set to ARRAY_DESC_CURRENT_VERSION by isc_array_lookup_bounds2(), isc_array_lookup_desc2(), and isc_array_set_desc2().

The array_desc_dtype field of an array descriptor must be expressed as one of the data types in the following table:

array_desc_dtype value	Corresponding InterBase data type
blr_boolean_dtype	BOOLEAN
blr_blob_id	ISC_QUAD structure
blr_cstring	NULL-terminated string
blr_cstring2	NULL-terminated string
blr_double	DOUBLE PRECISION
blr_float	FLOAT
blr_long	INTEGER
blr_quad	ISC_QUAD structure
blr_short	SMALLINT
blr_sql_date	DATE
blr_sql_time	TIME
blr_text	CHAR
blr_text2	CHAR
blr_timestamp	TIMESTAMP
blr_varying	VARCHAR
blr_varying2	VARCHAR

An array descriptor contains 16 ISC_ARRAY_BOUND structures, one for each possible dimension. An array with <n> dimensions has upper and lower bounds set for the first <n> ISC_ARRAY_BOUND structures. The number of actual array dimensions is specified in the array_desc_dimensions field of the array descriptor.

When you retrieve data from an array, you supply an array descriptor defining the array slice (entire array or subset of contiguous array elements) to be retrieved. Similarly, when you write data to an array, you supply an array descriptor defining the array slice to be written to.