The mi_qual_constant_nohostvar() accessor function

The mi_qual_constant_nohostvar() function returns an explicit constant value, if any, from the qualification-function arguments.

Syntax

MI_DATUM
mi_qual_constant_nohostvar(MI_AM_QUAL_DESC *qualDesc);
qualDesc
Points to the qualification descriptor.

Usage

To help calculate the cost of a qualification function, the am_scancost purpose function can extract the constant and column arguments and evaluate the distribution of the specified constant value in the specified column. Function arguments can include constants from two sources:
  • A value that the WHERE clause explicitly supplies
  • A dynamic value, or host variable, that the access method or a client application might supply

    In the WHERE clause, the function argument list contains a placeholder, such as a question mark (?), for the host variable.

The following function involves both an explicit value (200) and a host variable (?) as constant arguments, rather than an explicit value: 
WHERE range(cost, 200, ?)
In the following example, a WHERE clause specifies two constant values in a row that holds three values. A client program supplies the remaining value. 
WHERE equal(prices, row(10, ?, 20))

For the preceding qualification, the mi_qual_constant_nohostvar() function returns row(10, NULL, 20).

Because the am_scancost purpose function cannot predict the value of a host variable, it can only evaluate the cost of scanning for constants that the WHERE clause explicitly specifies. Call the mi_qual_constant_nohostvar() function to obtain any argument value that is available to am_scancost. The mi_qual_constant_nohostvar() function ignores host variables if the qualification supplies an explicit constant value.

By the time the database server invokes the am_beginscan or am_getnext purpose function, the qualification descriptor contains a value for any host- variable argument. To execute the function, obtain the constant value with the mi_qual_constant() function.

Return values

If the argument list of a function includes a specified constant value, mi_qual_constant_nohostvar() returns that value in an MI_DATUM structure.

If the specified constant contains multiple values, this function returns all provided values and substitutes a NULL for each host variable.

If the function arguments do not explicitly specify a constant value, this function returns a NULL value.

Related topics

See the descriptions of:
  • MI_DATUM in the Informix® DataBlade® API Programmer's Guide
  • Host variables in the Informix DataBlade API Programmer's Guide