EXTFNAPIV4_DESCRIBE_COL_IS_USED_BY

The EXTFNAPIV4_DESCRIBE_COL_IS_USED_BY_CONSUMER attribute indicates if the column in the result table is used by the consumer. Used in a describe_column_set scenario.

Data Type

a_sql_byte

Description

Used either to determine whether a column in the result table is used by the consumer, or to indicate that a column in an input is not needed. Valid for table arguments. Allows the user to set or retrieve information about a single column, whereas the similar attribute EXTFNAPIV4_DESCRIBE_PARM_TABLE_UNUSED_COLUMNS sets or retrieves information about all columns in a single call.

Usage

The UDF sets EXTFNAPIV4_DESCRIBE_COL_IS_USED_BY_CONSUMER on columns in an input table to inform the producer that it does not need values for the column.

Returns

On success, returns the sizeof(a_sql_byte) or:

EXTFNAPIV4_DESCRIBE_NOT_AVAILABLE – if the attribute was not available to set. This can happen if the column was not involved in the query.

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 the size of a_v4_extfn_estimate.
EXTFNAPIV4_DESCRIBE_INVALID_PARAMETER – set error returned if the argument specified is argument 0.
EXTFNAPIV4_DESCRIBE_INVALID_STATE – set error returned if the state is not equal to Optimization.
EXTFNAPIV4_DESCRIBE_INVALID_ATTRIBUTE_VALUE – set error returned if the value the UDF is setting is not 0 or 1.

Query Processing States

Valid during:

Optimization state

Example 1

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 r2,r3 from my_tpf( 'test', TABLE( select x,y from T ) )

When this TPF runs, it is beneficial for the server to know if column y is used by this TPF. If the TPF does not need y, the server can use this knowledge for optimization and does not send this column information to the TPF.