isc_database_info()

Go Up to API Function Reference

Reports requested information about a previously attached database. For more information about requesting database attachment information, see Requesting Information About an Attachment (API Guide).

Syntax

 ISC_STATUS isc_database_info(
 ISC_STATUS *status_vector,
 isc_db_handle *db_handle,
 short item_list_buffer_length,
 char *item_list_buffer,
 short result_buffer_length,
 char *result_buffer);

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`(). `db_handle` returns an error in `status_vector` if it is `NULL`.
`item_list_buffer_length`	`short`	Number of bytes in the item-list buffer
`item_list_buffer`	`char *`	Address of the item-list buffer
`result_buffer_length`	`short`	Number of bytes in the result buffer
`result_buffer`	`char *`	Address of the result buffer

Description

isc_database_info() returns information about an attached database. Typically, isc_database_info() is called to:

Determine how much space is used for page caches. The space is the product of the number of buffers and the page size, which are determined by calling isc_database_info() with the isc_info_num_buffers and isc_info_page_size item-list options.
Monitor performance. For example, to compare the efficiency of two update strategies, such as updating a sorted or unsorted stream.
When enabling embedded user authentication, if you check if to see if EUA is active with isc_database_info API, if isc_databaseinfo() is invoked with info item isc_info_db_eua_active it returns:

1 if EUA is active for the database
0 if EUA is not active

Note: Only the owner or SYSDBA can query for this information, once connected to the database. For all other users, the info request is ignored.

The calling program passes its request for information through the item-list buffer supplied by the program, and InterBase returns the information to a program-supplied result buffer.

Example

The following program fragment requests the page size and the number of buffers, then examines the result buffer to retrieve the values supplied by the InterBase engine:

char db_items[] = {
isc_info_page_size, isc_info_num_buffers,
isc_info_ end};
char res_buffer[40], *p, item;
int length;
SLONG page_size = 0L, num_buffers = 0L;
ISC_STATUS status_vector[20];

isc_database_info( status_vector,
  &handle, /* Set in previous isc_attach_database() call. */
  sizeof(db_items), db_items, sizeof(res_buffer), res_buffer);
if (status_vector[0] == 1 && status_vector[1]) {
/* An error occurred. */
isc_print_status(status_vector);
return(1);
};
/* Extract the values returned in the result buffer. */
for (p = res_buffer; *p != isc_info_end ;) {
item = *p++;
length = isc_portable_integer (p, 2);
p += 2;
switch (item)
{
case isc_info_page_size:
page_size = isc_portable_integer (p, length);
break;
case isc_info_num_buffers:
num_buffers = isc_portable_integer (p, length);
break;
default:
break;
}
p += length;
};

Return value

isc_database_info() 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_decode_sql_date()