16.20 - FNC_TblAbort - 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

Allows a table function or a table operator to gracefully abort a request when it encounters an error condition and cannot continue.

Syntax

int
FNC_TblAbort(void)

Return Value

IF the abort is initiated by … THEN FNC_TblAbort returns …
this copy of the table function 1.
another copy of the table function 0.

Valid Invocation Mode

This library function is valid during any phase or mode in which the table function was invoked.

Usage Notes

Because any copy of the table function can call FNC_TblAbort, the table function must check the return value to determine which copy made the call.

IF the return value is … THEN …
0 another copy of the table function initiated the abort.

Upon return of the call to FNC_TblAbort, this copy of the table function should simply return.

This copy of the function will be called again and when it calls FNC_GetPhase, the FNC_Phase argument will be set to TBL_ABORT. The function can close all resources and release any allocated memory at that time.

1 this copy of the table function initiated the abort.

The other copies of the table function will be notified about the abort the next time they call FNC_GetPhase, at which point the the value of the FNC_Phase return argument will be TBL_ABORT.

Control returns to this copy of the table function after all other copies return from the TBL_ABORT phase, at which point the table function should take the following steps:

  1. Set the sqlstate argument to an appropriate SQLSTATE exception condition.

    For more information, see Returning SQLSTATE Values.

  2. Set the error_message string to the error message text. The characters must be inside the LATIN character range.
  3. Close all resources and release any allocated memory.
  4. Write to an external log or send external error notification messages, if applicable.
  5. Return.

Restrictions

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

Example Using FNC_TblAbort

FNC_Phase    Phase;

if (FNC_GetPhase(&Phase) == TBL_MODE_CONST)    {
   switch(Phase)
   {
      ...
      case TBL_BUILD:
      {
         ...
         /* Get some bad data here. Need to abort. */
         if( FNC_TblAbort() )             {
            /* At this point, all other copies of the function */
            /* should have finished cleaning up */
            strcpy(sqlstate, "U0004");
            strcpy(error_message, "Bad Input data - not processed");
         break;
      }
      ...
   }
}
...