The sample table UDF udf_rg_2 builds on the sample in udf_rg_1.cxx and has the same behavior. The procedure is called udf_rg_2 and its implementation is in the samples directory in udf_rg_2.cxx.
The table UDF udf_rg_2 provides an alternate implementation of the _describe_extfn method in the a_v4_extfn_proc descriptor.
static void UDF_CALLBACK udf_rg_describe(
a_v4_extfn_proc_context *ctx )
/*****************************************************************/
{
a_sql_int32 desc_rc;
// The following describes will ensure that the schema defined
// by the user matches the schema supported by this table udf.
// This is achieved by telling the server what our schema is
// using describe_xxxx_set methods.
if( ctx->current_state == EXTFNAPIV4_STATE_ANNOTATION ) {
a_sql_data_type type = DT_NOTYPE;
a_sql_uint32 num_cols = 0;
a_sql_uint32 num_parms = 0;
// Inform the server that we support a single input
// parameter.
num_parms = 1;
desc_rc = ctx->describe_udf_set
( ctx,
EXTFNAPIV4_DESCRIBE_UDF_NUM_PARMS,
&num_parms,
sizeof( num_parms ) );
// Checks the return code and sets an error if the
// describe was unsuccessful for any reason.
UDF_CHECK_DESCRIBE( ctx, desc_rc );
// Inform the server that the type of parameter 1 is int.
type = DT_INT;
desc_rc = ctx->describe_parameter_set
( ctx,
1,
EXTFNAPIV4_DESCRIBE_PARM_TYPE,
&type,
sizeof( type ) );
UDF_CHECK_DESCRIBE( ctx, desc_rc );
// Inform the server that the number of columns in our
// result set is 1.
num_cols = 1;
desc_rc = ctx->describe_parameter_set
( ctx,
0,
EXTFNAPIV4_DESCRIBE_PARM_TABLE_NUM_COLUMNS,
&num_cols,
sizeof( num_cols ) );
UDF_CHECK_DESCRIBE( ctx, desc_rc );
// Inform the server that the type of column 1 in our
// result set is int.
type = DT_INT;
desc_rc = ctx->describe_column_set
( ctx,
0,
1,
EXTFNAPIV4_DESCRIBE_COL_TYPE,
&type,
sizeof( type ) );
UDF_CHECK_DESCRIBE( ctx, desc_rc );
}
// The following describes will inform the server of various
// optimizer related characteristics.
if( ctx->current_state == EXTFNAPIV4_STATE_OPTIMIZATION ) {
an_extfn_value p1_value;
a_v4_extfn_estimate num_rows;
// If the value of parameter 1 was constant, then we can
// inform the server how many distinct values will be.
desc_rc = ctx->describe_parameter_get
( ctx,
1,
EXTFNAPIV4_DESCRIBE_PARM_CONSTANT_VALUE,
&p1_value,
sizeof( p1_value ) );
UDF_CHECK_DESCRIBE( ctx, desc_rc );
if( desc_rc != EXTFNAPIV4_DESCRIBE_NOT_AVAILABLE ) {
// Inform the server that this UDF will produce n rows.
num_rows.value = *(a_sql_int32 *)p1_value.data;
num_rows.confidence = 1;
desc_rc = ctx->describe_parameter_set
( ctx,
0,
EXTFNAPIV4_DESCRIBE_PARM_TABLE_NUM_ROWS,
&num_rows,
sizeof( num_rows ) );
UDF_CHECK_DESCRIBE( ctx, desc_rc );
// Inform the server that this UDF will produce n distinct
// values for column 1 of its result set.
desc_rc = ctx->describe_column_set
( ctx,
0,
1,
EXTFNAPIV4_DESCRIBE_COL_DISTINCT_VALUES,
&num_rows,
sizeof( num_rows ) );
UDF_CHECK_DESCRIBE( ctx, desc_rc );
}
}
}
The describe function is called during several states. However, not all describe attributes are usable in every state. The describe method determines the state in which it is executing by checking the current_state variable on the a_v4_extfn_proc structure.
During the Annotation state, the udf_rg_2 table udf informs the server that it has one parameter of type INTEGER and its result set contains a single column of type INTEGER. This is accomplished by setting these attributes:
If the information set in these describe methods does not match the procedure definition from the CREATE PROCEDURE statement, the describe_parameter_set and describe_column_set methods return EXTFNAPIV4_DESCRIBE_INVALID_ATTRIBUTE_VALUE. The describe method then sets an error to indicate to the client there is a mismatch.
This example uses the macro UDF_CHECK_DESCRIBE defined in udf_utils.h to check the return value from a describe and set an error, if it is not successful.
During optimization, the udf_rg_2 table udf informs the server that it returns the same number of rows indicated in parameter one. Since the generated rows increment, the values are also unique. During optimization, only parameters that have a constant value are available. Use the describe attribute EXTFNAPIV4_DESCRIBE_PARM_CONSTANT_VALUE to obtain the value of a constant parameter. Once the table udf determines that the attribute value is available, udf_rg_2 sets EXTFNAPIV4_DESCRIBE_PARM_TABLE_NUM_ROWS and EXTFNAPIV4_DESCRIBE_COL_DISTINCT_VALUES to the value obtained.