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-Table Interface (VTI) 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 TABLE specifications in the table descriptor, including the following items:
  • Identification by table name, owner, table identifier, storage space, and current fragment
  • Structural details, such as the number of fragments in the whole table, 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:
  • Columns to project
  • 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. Each qualification descriptor contains information about the comparison of a column value and a constant. If a WHERE clause is more complex than a simple comparison of a column and a constant, use parameter descriptors along with qualification descriptors; otherwise complex qualifications are processed through SQL instead of the virtual table interface. 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 qualification can combine the results of two previous qualifications with an AND or OR operation, as the following example shows: 
WHERE price < 80 AND cost > 60
This example requires two qualification descriptors.

For examples, see Interpret the qualification descriptor.
parameter descriptor

MI_AM_PARAM_DESC

 A parameter descriptor contains information about parameters in a qualification descriptor. Parameter descriptors are useful when qualification descriptors contain multiple columns, constants, or expressions.

You enable parameter descriptors by including the AM_EXPR_PUSHDOWN flag when you register the access method.
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_STMT_EXEC duration and store a pointer to the user data in the table descriptor. PER_STMT_EXEC memory lasts for the duration of an SQL statement, while the accessed data source is open. For example, an access method might run DataBlade API functions that open smart large objects or files and store the values, or handles, that the functions return in PER_STMT_EXEC 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 current record.
qualification descriptor

MI_AM_QUAL_DESC

 As it processes each qualification against a single row, 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 optimize between scans for a join or subquery
parameter descriptor

MI_AM_PARAM_DESC

 As it processes each parameter, the access method can set the value of an expression in a parameter descriptor.
To allocate memory for a specific duration, the access method specifies a duration keyword. For example, the following command allocates PER_STMT_EXEC memory: 
my_data = (my_data_t *) mi_dalloc(sizeof(my_data_t),
   PER_STMT_EXEC)