EXTFNAPIV4_DESCRIBE_COL_IS_USED_BY

The EXTFNAPIV4_DESCRIBE_COL_IS_USED_BY_CONSUMER attribute indicates if a column in the result table is used by the consumer. Used in a describe_column_get 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 queries this property to determine if a result table column is required by the consumer. This can help the UDF avoid unnecessary work for unused columns.

Returns

On success, returns the sizeof(a_sql_byte) or:

EXTFNAPIV4_DESCRIBE_NOT_AVAILABLE – if the attribute was unavailable to get. 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 – get error returned if the describe buffer is not the size of a_v4_extfn_estimate.
EXTFNAPIV4_DESCRIBE_INVALID_STATE – get error returned if the query processing phase is not greater than Initial.
EXTFNAPIV4_DESCRIBE_INVALID_PARAMETER – get error returned if the argument specified is not argument 0.

Query Processing Phases

Valid during:

Annotation phase
Query Optimization phase
Plan Building phase
Execution phase

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 to know if the user has selected column r1 of the result set. If the user does not need r1, calculations for r1 may be unnecessary and we do not need to produce it for the server.