The MI_FUNCARG data type

The MI_FUNCARG data type is an opaque type defined for HCL Informix® that contains information about the companion UDR of a selectivity or cost function.

Selectivity and cost functions both have the same number of arguments as their companion UDRs. To calculate selectivity or cost effectively, however, your user-defined function might need to know additional information about the context in which the UDR was called. The DataBlade API provides this contextual information in the MI_FUNCARG structure.

Each argument of a cost or selectivity function is of type MI_FUNCARG. The DataBlade API provides accessor functions for the MI_FUNCARG structure. You can use any of these functions to extract information about the companion-UDR arguments from the selectivity or cost function. The following table lists the DataBlade API accessor functions that obtain information from the MI_FUNCARG structure.

Table 1. Argument information in the MI_FUNCARG structure
MI_FUNCARG information		DataBlade API function
Information about the companion UDR:
	The identifier of the companion UDR	mi_funcarg_get_routine_id()
	The name of the companion UDR	mi_funcarg_get_routine_name()
General companion-UDR argument information:
	Whether the companion-UDR argument is a column, constant, or parameter	mi_funcarg_get_argtype()
	The data type of companion-UDR argument	mi_funcarg_get_datatype()
	The length of the companion-UDR argument	mi_funcarg_get_datalen()
Constant argument (MI_FUNCARG_CONSTANT):
	The constant value of the companion-UDR argument	mi_funcarg_get_constant()
	Whether the value of the companion-UDR argument is the SQL NULL value	mi_funcarg_isnull()
Column-value argument (MI_FUNCARG_COLUMN):
	The column number of the column associated with the companion-UDR argument	mi_funcarg_get_colno()
	The table identifier of the table that contains the column associated with the companion-UDR argument	mi_funcarg_get_tabid()
	The distribution information for the column associated with the companion-UDR argument	mi_funcarg_get_distrib()

The following table lists the DataBlade API accessor functions that obtain general information about a companion UDR from the MI_FUNCARG structure.

Table 2. General companion-UDR information in the MI_FUNCARG structure
MI_FUNCARG information		DataBlade API function
Information about the companion UDR:
	The identifier of the companion UDR	mi_funcarg_get_routine_id()
	The name of the companion UDR	mi_funcarg_get_routine_name()
General companion-UDR argument information:
	Whether the companion-UDR argument is a column, constant, or parameter	mi_funcarg_get_argtype()
	The data type of companion-UDR argument	mi_funcarg_get_datatype()
	The length of the companion-UDR argument	mi_funcarg_get_datalen()

Restriction: To a DataBlade API module, the MI_FUNCARG data type is an opaque data type. Do not access its internal fields directly. The internal structure of this opaque data type might change in future releases. Therefore, to create portable code, always use the accessor functions in Table 1 to obtain values in this data type.

The MI_FUNCARG structure categorizes each argument of the companion UDR arguments. The MI_FUNCARG data type identifies the following kinds of arguments in the companion UDR.

Companion-UDR argument type	Argument-type constant
Argument is a constant value	MI_FUNCARG_CONSTANT
Argument is a column value	MI_FUNCARG_COLUMN
Argument is a parameter	MI_FUNCARG_PARAM

In addition to the general companion-UDR information that the functions in Table 2 obtain, you can also obtain information about the arguments themselves. The information that you can obtain depends on the particular category of the companion-UDR argument. The following table lists the DataBlade API accessor functions that obtain argument information from the MI_FUNCARG structure.

Table 3. Argument information in the MI_FUNCARG structure
MI_FUNCARG information		DataBlade API function
Constant argument (MI_FUNCARG_CONSTANT):
	The constant value of the companion-UDR argument	mi_funcarg_get_constant()
	Determines if the value of the companion-UDR argument is the SQL NULL value	mi_funcarg_isnull()
Column-value argument (MI_FUNCARG_COLUMN):
	The column number of the column associated with the companion-UDR argument	mi_funcarg_get_colno()
	The table identifier of the table that contains the column associated with the companion-UDR argument	mi_funcarg_get_tabid()
	The distribution information for the column associated with the companion-UDR argument	mi_funcarg_get_distrib()

For example, you can write the following query:

SELECT * FROM tab1 WHERE meets_cost(tab1.int_col, 20) ...;

Suppose you register the meets_cost() function with a selectivity function named meets_cost_selfunc(), as follows:

CREATE FUNCTION meets_cost(col INTEGER, value INTEGER)
   RETURNS BOOLEAN
   WITH (....SELFUNC=meets_cost_selfunc....)
   EXTERNAL NAME '......'
   LANGUAGE C;

Because the meets_cost() function returns a BOOLEAN value, you can write a selectivity function for the function. You write meets_cost_selfunc() so that it expects two arguments of the data type MI_FUNCARG. The following table shows what different MI_FUNCARG accessor functions return when you invoke them for each of the arguments of the meets_cost() function.

DataBlade API function	Argument 1	Argument 2
mi_funcarg_get_argtype()	MI_FUNCARG_COLUMN	MI_FUNCARG_CONSTANT
mi_funcarg_get_datatype()	Type identifier for data type of tab1.int_col	Type identifier for INTEGER data type
mi_funcarg_get_datalen()	Length of tab1.int_col	Length of INTEGER
mi_funcarg_get_tabid()	Table identifier of tab1	Undefined
mi_funcarg_get_colno()	Column number of int_col	Undefined
mi_funcarg_isnull()	FALSE	FALSE
mi_funcarg_get_constant()	Undefined	An MI_DATUM structure that holds the value of `20`