isc_array_lookup_desc2()

From InterBase
Jump to: navigation, search

Go Up to API Function Reference


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

Syntax

ISC_STATUS isc_array_lookup_desc2(
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 an array descriptor that will be filled in by this function.

Description

isc_array_lookup_desc2() determines the data type, length, scale, and dimensions for the array column, column_name, in the table, table_name. It stores this information in the array descriptor, desc.

It 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.

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_desc2(). You can also:
  • Call isc_array_lookup_bounds2(). This is like 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_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_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;
char str1 = "PROJ_DEPT_BUDGET";
char str2 = "QUARTERLY_HEAD_CNT";
isc_array_lookup_desc2( 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_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 ­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.

See Also

Advance To: