The INFO Function

D Eloquence Library

The INFO Function

The INFO funtion provides structural information about the database currently being accessed. The syntax is as follows:

   idb_info(base,qual,mode,status,buffer)

   int base;
   void *qual;
   int mode;
   int status[10];
   void *buffer;

The parameters are:

base: Identifies the database. This must be the return value from the idb_open call.
dset: Identifies a data set or data item, depending on the mode used. Refer to description below for information on qualifier and mode. Refer to the idb_find parameters dset and item for information on specifying the data set or data item.
mode: The available modes and information returned by each are explained below.
status: A pointer to an array of a least 10 elements used to indicate the success or failure of the function call.
buffer: A pointer to a character array containing the values of all data items in the data set.

Description

The idb_info function allows you to programmatically retrieve database structure and access information about data items and data sets. Access to structural information is restricted by the security class number specified when the database is opened. Any data sets which are inaccessible to the specified security class are considered nonexistent. For example, if your password is paired with security class number 20, idb_info will not show any data sets to which security class 20 has no access.

Idb_info can be used to make application programs independent of the database structure. If this procedure is used to retrieve all structural information, including item and set numbers, new data items and data sets can be added to the database without affecting existing programs.

IDBINFO Modes

Mode 101: Item number

Mode 101 identifies the data item number.

Qualifier: Identifies the data item for which the information is requested.
Buffer: Contains the following:

                  struct m101 {
                     int item_number;
                  }

Mode 102: Item name, type and length

Mode 102 describes a specific data item, including its name, data type and length.

Qualifier: Identifies the data item for which the information is requested.
Buffer: Contains the following:

                  struct m102 {
                     char item_name[16];
                     char item_type;
                     char blanks[3];
                     int  subitem_length;
                     int  subitem_count;
                  }

Mode 103: Items in database

Mode 103 identifies all data items defined in the database.

Qualifier: Ignored
Buffer: Contains the following:

                  struct m103 {
                     int item_count;
                     int item_numbers[];
                  }

The data items are listed in the order in which they are defined in the item part of the schema.

Mode 104: Fields in data set entry

Mode 104 identifies all data items in an entry of a specific data set.

Qualifier: Identifies the data set for which the information is requested.
Buffer: Contains the following:

                  struct m104 {
                     int field_count;
                     int item_numbers[];
                  }

A field is the occurrence of an item within an entry. The fields are listed in the order in which they are defined for the set entry in the schema.

Mode 201: Set number and access

Mode 201 identifies the data set number and the type of access allowed.

Qualifier: Identifies the data set for which the information is requested.
Buffer: Contains the following:

                  typedef struct m201 {
                     int set_number;
                  }

The data set number is positive if the security class has only read access to the data set. The number is negative if the security class has both read and write access.

Mode 202: Set name, type and length

Mode 202 describes a specific data set, including its name, data set type and capacity.

Qualifier: Identifies the data item for which the information is requested.
Buffer: Contains the following:

                  typedef struct m202 {
                     char set_name[16];
                     char set_type;
                     char blanks[3];
                     int  entry_length;
                     char blanks2[4];
                     int  entry_count;
                     int  capacity;
                  }

Entry count is the number of records used in the data set. Capacity is the maximum capacity as defined in the schema text file and the maximum entry count.

Mode -202: Set name, type and length (local)

Mode -202 describes a specific data set, including its name, data set type and capacity. This is the same as mode 202. The difference is that this is performed locally (without contacting the database server). The entry_cnt element of the return structure is always zero.

Mode 203: Sets in database

Mode 203 identifies all data sets defined in the database and the type of access allowed.

Qualifier: Ignored
Buffer: Contains the following

                  struct m203 {
                     int set_count;
                     int set_numbers[];
                  }

The data set number is positive if the security class has only read access to the data item. The number is negative if the security class has both read and write access.

Mode 204: Sets with item

Mode 204 identifies all accessible data sets which contain a specified data item, and indicates the type of access allowed.

Qualifier: Identifies the data item for which the information is requested.
Buffer: Contains the following:

                  typedef struct m204 {
                     int set_count;
                     int set_numbers[];
                  }

The data set number is positive if the security class has only read access to the data item. The number is negative if the security class has both read and write access.

Mode 301: Paths and Indexes

Mode 301 identifies the search item and sort items defined for or related to the specified data set.

Qualifier: Identifies the data set for which the information is requested.
Buffer: Contains the following:

                  struct m301 {
                     int search_item_count;
                     struct {
                        int set_number;
                        int search_item_number;
                        int reserved;
                     } path_list[];
                  }

If the qualifier specifies a master data set, the returned set numbers identify the linked detail sets. The corresponding search item number identifies the search item in the linked detail set. If the master has no detail sets, the search item count is zero.

If the qualifier specifies a detail data set, the returned set numbers identify the linked master sets. The corresponding search item number identifies the item in the detail data set. If the detail set has no master sets, the search item count is zero.

Mode 302: Primary search item

Mode 302 identifies the primary search item for a specified data set.

Qualifier: Identifies the detail or master data set for which the information is requested.
Buffer: Contains the following:

                  struct m302 {
                     int item_number;
                     int parent_set_number;
                  }

If the qualifier is a detail data set, the item number is the primary search item number, and the set number is the related master data set number.

If the qualifier is a master data set, the item number is the key item number, and the set number is zero. If you do not have access to the key item, the item number is zero.

Mode 501: Index item number

Mode 501 identifies the index item number.

Qualifier: Identifies the index item for which the information is requested.
Buffer: Contains the following:

                  struct m501 {
                     int index_item_number;
                  }

Mode 502: Index item name and segments

Mode 502 describes a specific index item, including its name and segments.

Qualifier: Identifies the index item for which the information is requested.
Buffer: Contains the following:

                  struct m502 {
                     char iitem_name[16];
                     int  iitem_seg_cnt;
                     struct {
                        int item_number;
                        int item_length;
                     } seg[8];
                  }

Mode 503: Index items in database

Mode 503 identifies all index items defined in the database.

Qualifier: Ignored
Buffer: Contains the following:

                  struct m503 {
                     int iitem_count;
                     int iitem_numbers[];
                  }

The index items are listed in the order in which they are defined in the index item part of the schema.

Mode 504: Index items in data set entry

Mode 504 identifies all index items in an entry of a specific data set.

Qualifier: Identifies the data set for which the information is requested.
Buffer: Contains the following:

                  struct m504 {
                     int iitem_count;
                     int iitem_numbers[];
                  }

The index items are listed in the order in which they are defined for the set index in the schema.

Return value

Returns 0 if successful, or error number if an error was encountered.

Status codes

If idb-info was successfully executed, the status array will contain the following values:

Status codes
Element Meaning
0 S_OK
1 number of bytes transferred into buffer
2 0
3 unchanged
4 0
5 DB_INFO | (open_mode <<12)
6 0
7 0
8 mode
9 0

Status codes
Element	Meaning
0	S_OK
1	number of bytes transferred into buffer
2	0
3	unchanged
4	0
5	DB_INFO \| (open_mode <<12)
6	0
7	0
8	mode
9	0

Example

   union info info;

   if(idb_info(dbid,"ORDER",202,status,&info))
      error_handler();

   printf("Set name: %16.16s\\n", info.info_202.name);
   printf("Set type: %c\\n",      info.info_202.type);
   ...

This will describe the ORDER data set.

Eloquence Database Manual - 19 DEC 2002