EXTFNAPIV4_DESCRIBE_COL_MAXIMUM_VALUE (Set)

Data Type

an_extfn_value

Description

The maximum value for a column. This property is valid only for argument 0 and table arguments.

Usage

The UDF can set EXTFNAPIV4_DESCRIBE_COL_MAXIMUM_VALUE, if it knows what the maximum data value of the column is. The server can use this information during optimization.

The UDF can use EXTFNAPIV4_DESCRIBE_COL_TYPE to determine the data type of the column, and EXTFNAPIV4_DESCRIBE_COL_WIDTH to determine the storage requirements of the column, to provide an equivalently sized buffer to hold the value to set.

describe_buffer_length is the sizeof() this buffer.

Returns

On success, returns the describe_buffer_length, if the value was set, or:

• EXTFNAPIV4_DESCRIBE_NOT_AVAILABLE – if the attribute could not be set. Returned if the column was not involved in the query or the maximum value was not available for the requested column.

On failure, returns one of the generic describe_column errors, or:

• EXTFNAPIV4_DESCRIBE_BUFFER_SIZE_MISMATCH – set error returned, if the describe buffer is not large enough to hold the maximum value.
• EXTFNAPIV4_DESCRIBE_INVALID_STATE – Set error returned, if the query processing state is not equal to Optimization.
• EXTFNAPIV4_DESCRIBE_INVALID_PARAMETER – set error returned, if the arg_num is not 0.

Query Processing States

Valid in:

• Optimization state

Example

The PROCEDURE definition and and UDF code fragment that implements the _describe_extfn callback API function:

CREATE PROCEDURE my_tpf( col_char char(10), col_table TABLE( c1 INT, c2 INT ) )
	     RESULTS ( r1 INT, r2 INT, r3 INT )
	     EXTERNAL ‘my_tpf_proc@mylibrary’;

CREATE TABLE T( x INT, y INT, z INT );

select * from my_tpf( 'test', TABLE( select x,y from T ) )

This example shows a TPF where it is useful to the server (or to another TPF that takes the result of this TPF as input) to know the maximum value of result set column one. In this instance, the maximum output value of column one is 500000.

my_tpf_describe(a_v4_extfn_proc_context *cntxt)
{
    if( cntxt->current_state == EXTFNAPIV4_STATE_OPTIMIZATION ) {
	     a_sql_int32 max_value = 500000;
	     a_sql_int32 ret = 0;

	     // Tell the server what the maximum value of the first column
	     // of our result set will be.

      ret = cntxt->describe_column_set( cntxt, 0, 1 
		          EXTFNAPIV4_DESCRIBE_COL_MAXIMUM_VALUE,
		          &max_value,
		          sizeof(a_sql_int32) );

	     if( ret < 0 ) {
	         // Handle the error.
     	}

   }
}