FNC_TblAllocCtx Function | C Library Functions | Teradata Vantage - 17.10 - FNC_TblAllocCtx - Advanced SQL Engine - Teradata Database

Teradata Vantageā„¢ - SQL External Routine Programming

Product
Advanced SQL Engine
Teradata Database
Release Number
17.10
Release Date
July 2021
Content Type
Programming Reference
Publication ID
B035-1147-171K
Language
English (United States)

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

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.

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

Syntax

void *
FNC_TblAllocCtx(int  length)

Syntax Elements

length
the size, in bytes, to allocate to the general scratchpad.

The maximum length is 64 KB.

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.

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;
            ...
         }
      }
      ...
   }
}
...