16.20 - FNC_TblOptOut - Advanced SQL Engine - Teradata Database

Teradata Vantage™ - SQL External Routine Programming

Product
Advanced SQL Engine
Teradata Database
Release Number
16.20
Release Date
April 2020
Content Type
Programming Reference
Publication ID
B035-1147-162K
Language
English (United States)

Purpose

Called by a copy of a table function that does not want to participate in the process of returning rows.

Syntax

int
FNC_TblOptOut(void)

Return Value

IF the call is … THEN FNC_TblOptOut returns …
successful 0.
not successful -1.

This can happen when a table function calls FNC_TblOptOut in the wrong mode or phase.

Valid Invocation Mode

Use this library function when the return value of FNC_GetPhase is TBL_MODE_CONST, indicating that the SELECT statement invoked the table function with constant expression input arguments.

For example:

SELECT *
FROM TABLE (table_function_1('STRING_CONSTANT'))
AS table_1;

Usage Notes

If every copy of the table function calls FNC_TblOptOut, then the step ends as if no rows are created and the result is an empty derived table.

Restrictions

This function can only be called from within a table function. Calling this function from a scalar function, aggregate function, UDM, or external stored procedure results in an exception on the transaction.

Calling this function is valid only when the table function calls FNC_GetPhase and gets a:
  • return value of TBL_MODE_CONST for the mode
  • value of TBL_PRE_INIT or TBL_INIT for the processing phase

A table function can call FNC_TblOptOut only once.

Example Using FNC_TblOptOut

FNC_Phase    Phase;

if (FNC_GetPhase(&Phase) == TBL_MODE_CONST)
{
   switch(Phase)
   {
      case TBL_PRE_INIT:

         switch (FNC_Tbl_FirstParticipant() )
         {
            case 1:   /* participant */
               return;
            case 0:  /* not participant */
               if (FNC_TblOptOut()) 
                  strcpy(sqlstate, "U0006"); /* an error return */
               return;
            default:  /* -1 or other error */
               strcpy(sqlstate, "U0007");
               return;
         }
      ...
   }
   ...
}