EXTFNAPIV4_DESCRIBE_COL_MAXIMUM_VALUE (Get)

Data Type

an_extfn_value

Description

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

Usage

If a UDF gets the EXTFNAPIV4_DESCRIBE_COL_MAXIMUM_VALUE property, then the maximum value of the column data is returned in the describe_buffer. If the input table is a base table, the maximum value is based on all of the column data in the table and is accessible only if there is an index on the table column. If the input table is the result of another UDF, the maximum value is the COL_MAXIMUM_VALUE set by that UDF.

The data type for this property is different for different columns. The UDF can use EXTFNAPIV4_DESCRIBE_COL_TYPE to determine the data type of the column. The UDF can also use EXTFNAPIV4_DESCRIBE_COL_WIDTH to determine the storage requirements of the column, to provide an equivalently sized buffer to hold the value.

describe_buffer_length allows the server to determine if the buffer is valid.

If EXTFNAPIV4_DESCRIBE_COL_MAXIMUM_VALUE is unavailable, describe_buffer is NULL.

Returns

On success, returns the describe_buffer_length or:

• EXTFNAPIV4_DESCRIBE_NOT_AVAILABLE – If the attribute was unavailable to get. This can happen if the column was uninvolved in the query, or if the maximum value was unavailable for the requested column.

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

• EXTFNAPIV4_DESCRIBE_BUFFER_SIZE_MISMATCH – Get error returned if the describe buffer is not large enough to hold the maximum value.
• EXTFNAPIV4_DESCRIBE_INVALID_STATE – Get error returned if the state is not greater than Initial.

Query Processing States

Valid in any state except Initial state:

• Annotation state
• Query Optimization state
• Plan building state
• Execution state

Example

The PROCEDURE definition and code fragment in the _describe_extfn 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 illustrates how a TPF would get the maximum value for column two of the input table, for internal optimization purposes.

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

	     // Get the maximum value of the second column of the
	     // table input parameter  'col_table'
    	 ret = cntxt->describe_column_get( cntxt, 2, 2 
		          EXTFNAPIV4_DESCRIBE_COL_MAXIMUM_VALUE,
		          &max_value,
		          sizeof(a_sql_int32) );

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