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
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)