Descriptors

Descriptors are predefined opaque data types that the database server creates to exchange information with a DataBlade module or an access method. The Virtual-Index Interface (VII) provides several descriptors in addition to those descriptors that the DataBlade API provides.

An access-method descriptor contains the specifications from an SQL statement or oncheck request, and relevant information from the system catalog.

The database server passes descriptors by reference as arguments to purpose functions. The following table highlights only a few access-method descriptors to illustrate the type of information that the database server passes to an access method.

Descriptor name and structure Database server entries in the descriptor

Descriptor name and structure	Database server entries in the descriptor
table descriptor MI_AM_TABLE_DESC	The database server puts CREATE INDEX specifications in the table descriptor, including the following items: Identification by index name, owner, storage space, and current fragment Structural details, such as the number of fragments in the whole index, column names, and data types Optional user-supplied parameters Constraints such as read/write mode
scan descriptor MI_AM_SCAN_DESC	The database server puts SELECT statement specifications in the scan descriptor, including the following items: Index-key columns Lock type and isolation level Pointers to the table descriptor and the qualification descriptor
qualification descriptor MI_AM_QUAL_DESC	In the qualification descriptor, the database server describes the functions and Boolean operators that a WHERE clause specifies. A qualification function tests the value in a column against a constant or value that an application supplies. The following examples test the value in the price column against the constant value 80. `WHERE lessthan(price,80) WHERE price < 80` The qualification descriptor for a function identifies the following items: Function name Arguments that the WHERE clause passes to the function Negation (NOT) operator, if any A complex qualification combines the results of two previous qualifications with an AND or OR operation, as the following example shows: `WHERE price < 80 AND cost > 60` A complex qualification descriptor contains each Boolean AND or OR operator from the WHERE clause. For examples, see Interpret the qualification descriptor.

table descriptor

MI_AM_TABLE_DESC

The database server puts CREATE INDEX specifications in the table descriptor, including the following items:

Identification by index name, owner, storage space, and current fragment
Structural details, such as the number of fragments in the whole index, column names, and data types
Optional user-supplied parameters
Constraints such as read/write mode

scan descriptor

MI_AM_SCAN_DESC

The database server puts SELECT statement specifications in the scan descriptor, including the following items:

Index-key columns
Lock type and isolation level
Pointers to the table descriptor and the qualification descriptor

qualification descriptor

MI_AM_QUAL_DESC

In the qualification descriptor, the database server describes the functions and Boolean operators that a WHERE clause specifies. A qualification function tests the value in a column against a constant or value that an application supplies. The following examples test the value in the price column against the constant value 80.

WHERE lessthan(price,80)
WHERE price < 80

The qualification descriptor for a function identifies the following items:

Function name
Arguments that the WHERE clause passes to the function
Negation (NOT) operator, if any

A complex qualification combines the results of two previous qualifications with an AND or OR operation, as the following example shows:

WHERE price < 80 AND cost > 60

A complex qualification descriptor contains each Boolean AND or OR operator from the WHERE clause.

For examples, see Interpret the qualification descriptor.

Descriptors reserve areas where the access method stores information. An access method can also allocate user-data memory of a specified duration and store a pointer to the user-data in a descriptor, as the following list shows.

Descriptor name and structure	Access method entries in the descriptor
table descriptor MI_AM_TABLE_DESC	To share state information among multiple purpose functions, the access method can allocate user-data memory with a PER_STATEMENT duration and store a pointer to the user data in the table descriptor. PER_STATEMENT memory lasts for the duration of an SQL statement, for as long as the accessed data source is open. For example, an access method might execute DataBlade API functions that open smart large objects or files and store the values, or handles, that the functions return in PER_STATEMENT memory.
scan descriptor MI_AM_SCAN_DESC	To maintain state information during a scan, an access method can allocate user-data memory with a PER_COMMAND duration and store a pointer to the user data in the scan descriptor. For example, as it scans a table, the access method can maintain a pointer in PER_COMMAND memory to the address of the index entry
qualification descriptor MI_AM_QUAL_DESC	As it processes each qualification against a single index entry, the access method can set the following items in the qualification descriptor: A host-variable value for a function with an OUT argument The MI_VALUE_TRUE or MI_VALUE_FALSE to indicate the result that each function or Boolean operator returns An indicator that forces the database server to reoptimize between scans for a join or subquery

To allocate memory for a specific duration, the access method specifies a duration keyword. For example, the following command allocates PER_STATEMENT memory:

my_data = (my_data_t *) mi_dalloc(sizeof(my_data_t),
   PER_STATEMENT)