isc_array_set_desc2()

Initializes an array descriptor.

Syntax

 ISC_STATUS isc_array_set_desc2(
 ISC_STATUS *status_vector, 
 char *table_name,
 char *column_name,
 short *sql_dtype,
 short *sql_length,
 short *dimensions,
 ISC_ARRAY_DESC_V2 *desc);

Parameter	Type	Description
`status_vector`	`ISC_STATUS` `*`	Pointer to the error status vector
`table_name`	`char *`	Blank- or null-terminated name of the table containing the array column, <column_name>
`column_name`	`char *`	Name of the array column; this may be either null-terminated or blank-terminated.
`sql_dtype`	`short *`	Pointer to SQL data type of the array elements
`sql_length`	`short *`	Pointer to length of each array element
`dimensions`	`short *`	Pointer to number of array dimensions
`desc`	`ISC_ARRAY_DESC_V2` `*`	Array descriptor to be filled in by this function

Description

isc_array_set_desc2() initializes the array descriptor, desc, from the function parameters, table_name, column_name, sql_dtype, sql_length, and dimensions.

isc_array_set_desc2() also sets to 0 a flag in the descriptor. This specifies that the array is accessed in future function calls in row-major order, the default. If an application requires column-major access, reset this flag to 1.

table_name and column_name can be either null-terminated or blank-terminated. The names stored in the descriptor will be null-terminated.

sql_dtype must be given as a SQL macro constant.

The array descriptor is used in subsequent calls to isc_array_get_slice2() or isc_array_put_slice2().

For a detailed description of the array descriptor, see Working with Array Data.

Note: There are ways to fill in an array descriptor other than by calling isc_array_set_desc2(). You can also:

Call isc_array_lookup_bounds2(). This function is similar to isc_array_lookup_desc2(), except that isc_array_lookup_bounds2() also fills in information about the upper and lower bounds of each dimension.
Call isc_array_lookup_desc2(). This function is similar to isc_array_lookup_bounds2(), except that isc_array_lookup_desc2() does not fill in information about the upper and lower bounds of each dimension.
Set the descriptor fields directly.

You must set array_desc_version to ARR_DESC_CURRENT_VERSION.
The array_desc_field_name and array_desc_relation_name parameters must be null-terminated:
array_desc_dtype must be expressed as one of the data types in the following table:

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

Example

The following illustrates a sample call to isc_array_set_desc2(). More complete examples of accessing arrays are found in the example programs for isc_array_get_slice2() and isc_array_put_slice2().

#include <ibase.h>
ISC_STATUS status_vector[20];
ISC_ARRAY_DESC_V2 desc;
short dtype = SQL_TEXT;
short len = 8;
short dims = 1;
isc_array_set_desc2( status_vector, "TABLE1", "CHAR_ARRAY", &dtype,
 &len, &dims, &desc);
if (status_vector[0] == 1 && status_vector[1]){
/* Process error. */
isc_print_status(status_vector);
return(1);
}

Return value

isc_array_set_desc2() returns the second element of the status vector. Zero indicates success. A nonzero value indicates an error. For InterBase errors, the first element of the status vector is set to 1, and the second element is set to an InterBase error code.

To check for an InterBase error, examine the first two elements of the status vector directly. For more information about examining the status vector, see Handling Error Conditions.

Advance To:

isc_attach_database()