Requesting Information About an Attachment
After an application attaches to a database, it may need information about the attachment. The isc_database_info() call enables an application to query for attachment information, such as the version of the on-disk structure (ODS) used by the attachment, the number of database cache buffers allocated, the number of databases pages read from or written to, and write-ahead log information.
In addition to a pointer to the error status vector and a database handle, isc_database_info() requires two application-provided buffers, a request buffer, where the application specifies the information it needs, and a result buffer, where InterBase returns the requested information. An application populates the request buffer with information prior to calling isc_database_info(), and passes it both a pointer to the request buffer, and the size, in bytes, of that buffer.
The application must also create a result buffer large enough to hold the information returned by InterBase. It passes both a pointer to the result buffer, and the size, in bytes, of that buffer, to isc_database_info(). If InterBase attempts to pass back more information than can fit in the result buffer, it puts the value, isc_info_truncated, defined in ibase.h, in the final byte of the result buffer.
Contents
- 1 The Request Buffer
- 2 The Result Buffer
- 3 Status Information
- 4 Request Buffer Items and Result Buffer Values
- 5 Database Characteristics
- 6 isc_database_info() Call Example
- 7 Advance to Next Section
The Request Buffer
The request buffer is a char array into which is placed a sequence of byte values, one per requested item of information. Each byte is an item type, specifying the kind of information desired. Compile-time constants for all item types are defined in ibase.h.
The Result Buffer
The result buffer returns a series of clusters of information, one per item requested. Each cluster consists of three parts:
- A one-byte item return type. There are compile-time constants defined for all the item return types in ibase.h.
- A two-byte number specifying the number of bytes that follow in the remainder of the cluster.
- A value, stored in a variable number of bytes, whose interpretation (for example, as a number or as a string of characters) depends on the item return type.
A calling program is responsible for interpreting the contents of the result buffer and for deciphering each cluster as appropriate. In many cases, the value simply contains a number or a string (sequence of characters). But in other cases, the value is a number of bytes whose interpretation depends on the item return type.
The clusters returned to the result buffer are not aligned. Furthermore, all numbers are represented in a generic format, with the least significant byte first, and the most significant byte last. Signed numbers have the sign in the last byte. Convert the numbers to a datatype native to your system, if necessary, before interpreting them. The API call, isc_portable_integer(), can be used to perform the conversion.
Status Information
In addition to the information InterBase returns in response to a request, InterBase can also return one or more of the following status messages to the result buffer. Each status message is one unsigned byte in length:
Table 4.6 Status message return items
| Item | Description | |
|---|---|---|
| isc_info_end | End of the messages | |
| isc_info_truncated | Result buffer is too small to hold any more requested information | |
| isc_info_error | Requested information is unavailable; check the status vector for an error code and message |
Request Buffer Items and Result Buffer Values
The following sections show the request buffer items and result buffer contents for the following categories of database information:
- Database characteristics
- Environmental characteristics
- Performance statistics
- Database operation counts
Database Characteristics
Several items are available for determining database characteristics, such as its size and major and minor ODS version numbers. The following table lists the request buffer items that can be passed, and the information returned in the result buffer for each item type.
Table 4.7 Database information items for database characteristics
| Request Buffer Item | Result Buffer Contents | |
|---|---|---|
| allocation | Number of database pages allocated | |
| base_level | Database version (level) number:
| |
| db_id | Database file name and site name:
| |
| implementation | Database implementation number:
| |
| no_reserve | 0 or 1
| |
| ods_minor_version | On-disk structure (ODS) minor version number; an increase in a minor version number indicates a non-structural change,which does not affect database access. | |
| ods_version | *ODS major version number | |
| page_size | Number of bytes per page of the attached database; use with isc_info_allocation</> to determine the size of the database | |
| sql_dialect | The SQL dialect supported by the database software. | |
| version | Version identification string of the database implementation:
The version string is for display only. Use the base level or version to identify versions functionally. |
Environmental Characteristics
Several items are provided for determining environmental characteristics, such as the amount of memory currently in use, or the number of database cache buffers currently allocated. These items are described in the following table:
Table 4.8 Database information items for environmental characteristics
| Request Buffer Item | Result Buffer Contents | |
|---|---|---|
| current_memory | Amount of server memory (in bytes) currently in use | |
| forced_writes | Number specifying the mode in which database writes are performed (0 for asynchronous, 1 for synchronous) | |
| max_memory | Maximum amount of memory (in bytes) used at one time since the first process attached to the database | |
| num_buffers | Number of memory buffers currently allocated | |
| sweep_interval | Number of transactions that are committed between “sweeps” to remove database record versions that are no longer needed | |
| ser_names | Names of all the users currently attached to the database; for each such user, the result buffer contains an isc_info_user_names byte followed by a 1-byte length specifying the number of bytes in the user name, followed by the user name |
- Note: Not all environmental information items are vailable on all platforms.
Performance Statistics
There are four items that request performance statistics for a database. These statistics accumulate for a database from the moment it is first attached by any process until the last remaining process detaches from the database.
For example, the value returned for isc_info_reads is the number of reads since the current database was first attached, that is, an aggregate of all reads done by all attached processes, rather than the number of reads done for the calling program since it attached to the database. The next table summarizes the request performance statistics.
Table 4.9 Database information items for performance statistics
| Request Buffer Item | Result Buffer Contents | |
|---|---|---|
| fetches | Number of reads from the memory buffer cache | |
| marks | Number of writes to the memory buffer cache | |
| reads | Number of page reads | |
| writes | Number of page writes |
Database Operation Counts
Several information items are provided for determining the number of various database operations performed by the currently attached calling program. These values are calculated on a per-table basis. When any of these information items is requested, InterBase returns to the result buffer:
- 1 byte specifying the item type (for example, isc_info_insert_count).
- 2 bytes telling how many bytes compose the subsequent value pairs.
- A pair of values for each table in the database on which the requested type of operation has occurred since the database was last attached.
Each pair consists of:
- 2 bytes specifying the table ID.
- 4 bytes listing the number of operations (for example, inserts) done on that table.
- Tip: To determine an actual table name from a table ID, query the system table, RDB$RELATION.
The following table describes the items which return count values for operations on the database:
Table 4.10 Database information items for operation counts
| Request Buffer Item | Result Buffer Contents | |
|---|---|---|
| backout_count | Number of removals of a version of a record | |
| delete_count | Number of database deletes since the database was last attached | |
| expunge_count | Number of removals of a version of a record | |
| insert_count | Number of inserts into the database since the database was last attached | |
| purge_count | Number of removals of old versions of fully mature records (records that are committed, so that older ancestor versions are no longer needed) | |
| read_idx_count | Number of reads done via an index since the database was last attached | |
| read_seq_count | Number of sequential table scans (row reads) done on each table since the database was last attached | |
| update_count | Number of database updates since the database was last attached |
isc_database_info() Call Example
The following code requests the page size and the number of buffers for the currently attached database, then examines the result buffer:
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;
};