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

Allocates a general scratchpad to retain data between iterations of a local table function copy.

Syntax

void *
FNC_TblAllocCtx(int  length)
int length
the size, in bytes, to allocate to the general scratchpad.

The maximum length is 64 KB.

Return Value

FNC_TblAllocCtx returns the address of the general scratchpad that a local table function copy can use to retain data between iterations.

The return value is a NULL pointer if the table function already allocated a general scratchpad or the scratchpad could not be allocated.

Valid Invocation Mode

This library function is valid in either of the following two modes (returned by the FNC_GetPhase library function):
  • TBL_MODE_CONST, when the SELECT statement invoked the table function with constant expression input arguments
  • TBL_MODE_VARY, when the SELECT statement invoked the table function using the columns from a derived table as input arguments

Usage Notes

Subsequent invocations of the table function can gain access to the scratchpad by calling FNC_TblGetCtx.

Do not store pointers in the scratchpad that reference other structures in the scratchpad, because the returned address of the scratchpad is not the same for subsequent invocations of the table function. Instead, use relative addressing, such as offsets from the current address of the scratchpad.

The general scratchpad is local to each copy of the table function for the current transaction or request running on each AMP vproc. It is not retained for subsequent transactions or requests.

The control copy of a table function can place a flag in the general scratchpad to remember that it is the control copy.

To get around the 64 KB maximum length of the scratch pad, call FNC_malloc and save the address in the scratchpad so that you can refer to it in subsequent calls. Remember to call FNC_free during the FNC_END or FNC_ABORT phase or you will get a memory not freed error.

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.

This function can only be called once.

Example Using FNC_TblAllocCtx

typedef struct {
   unsigned short control_flag;
   int            qfd;
       ...
} scratchpad;

scratchpad     *options;
FNC_Phase      Phase;

if (FNC_GetPhase(&Phase) == TBL_MODE_CONST)
{
   switch(Phase)
   {
      case TBL_PRE_INIT:
      {
         if ( FNC_TblControl() )
         {
            options = FNC_TblAllocCtx(sizeof(scratchpad));                
             options->control_flag = 1;
            ...
         }
      }
      ...
   }
}
...