isc_array_lookup_bounds2()

Go Up to API Function Reference

Determines the data type, length, scale, dimensions, and array boundaries for the specified array column in the specified table.

Syntax

 ISC_STATUS isc_array_lookup_bounds2(
 ISC_STATUS *status_vector, 
 isc_db_handle *db_handle, 
 isc_tr_handle *trans_handle,
 char *table_name,
 char *column_name,
 ISC_ARRAY_DESC_V2 *desc);

Parameter	Type	Description
`status_vector`	`ISC_STATUS` `*`	Pointer to the error status vector
`db_handle`	`isc_db_handle *`	Pointer to a database handle set by a previous call to `isc_attach_database`(); the handle identifies the database containing the array column. `db_handle` returns an error in `status_vector` if it is `NULL`.
`trans_handle`	`isc_tr_handle *`	Pointer to a transaction handle whose value has been set by a previous `isc_start_transaction()` call; `trans_handle` returns an error if `NULL`.
`table_name`	`char *`	Name of the table containing the array column, `column_name`; can be either null-terminated or blank-terminated.
`column_name`	`char *`	Name of the array column; can be either null-terminated or blank-terminated.
`desc`	`ISC_ARRAY_DESC_V2` `*`	Pointer to a descriptor for the arrays that will be filled in by this function.

Description

isc_array_lookup_bounds2() determines the data type, length, scale, dimensions, and array boundaries for the elements in an array column, <column_name> in the table, <table_name>. It stores this information in the array descriptor, desc.

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

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_lookup_bounds2(). You can also:

Call isc_array_lookup_desc2(). This is exactly the same as calling isc_array_lookup_bounds2(), except that the former does not fill in information about the upper and lower bounds of each dimension.
Call isc_array_set_desc2() to initialize the descriptor from parameters you call it with, rather than accessing the database metadata.
Set the descriptor fields directly. Note that array_desc_dtype must be expressed as one of the data types in the following table, and the parameters, array_desc_field_name, and array_desc_relation_name, must be null-terminated:

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_lookup_bounds2(). 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;
char *str1 = "PROJ_DEPT_BUDGET";
char *str2 = "QUARTERLY_HEAD_CNT";

isc_array_lookup_bounds2( status_vector,
&database_handle, /* Set in previous isc_attach_database() call. */
&tr_handle, /* Set in previous isc_start_transaction() call. */
str1, str2, &desc);
if (status_vector[0] == 1 && status_vector[1]){
/* Process error. */
isc_print_status(status_vector);
return(1);
}

Return value

isc_array_lookup_bounds2() 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 isc_bad_stmt_handle, isc_bad_trans_handle, isc_fld_not_def, or another 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_array_lookup_desc()