16.20 - FNC_TblAllocCtrlCtx - 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 control scratchpad to propagate data from the table function control copy to all other copies running on all other AMP vprocs.

Syntax

void *
FNC_TblAllocCtrlCtx(int  length)
int length
the size, in bytes, to allocate to the control scratchpad.
The maximum length is 64 KB.

Return Value

FNC_TblAllocCtrlCtx returns the address of the control scratchpad that the control copy of the table function can use to propagate data to all other copies of the table function.

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

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

Use the control scratchpad to keep track of what a table function is supposed to be doing and what it has left to do.

Calling this function is valid when:
  • The table function calls FNC_GetPhase and gets a value of TBL_PRE_INIT for the processing phase
  • This copy of the table function establishes itself as the control copy of the table function by calling FNC_TblControl

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.

After the control copy of the table function completes the TBL_PRE_INIT processing phase, all copies of the table function (including the control copy) can gain access to the data that the control copy of the table function stores in the control scratchpad by calling FNC_TblGetCtrlCtx in any processing phase except for the TBL_PRE_INIT phase. Subsequent changes to the control scratchpad are considered local and are retained in the scratchpad for the next iterations of the local table function copy.

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 the following return values:
  • TBL_MODE_CONST for the mode
  • TBL_PRE_INIT for the processing phase

Example Using FNC_TblAllocCtrlCtx

typedef struct {
   unsigned short cntrl_fnc_AMP
   int            qfd;
   ...
} ctrl_ctx;

ctrl_ctx     *options;
AMP_Info_t   *LocalConfig;
FNC_Phase    Phase;

if (FNC_GetPhase(&Phase) == TBL_MODE_CONST)
{
   switch(Phase)
   {
      case TBL_PRE_INIT:
      {
         LocalConfig = FNC_AMPInfo();
         if ( FNC_TblControl() )
         {
            options = FNC_TblAllocCtrlCtx(sizeof(ctrl_ctx));                
            options->ctrl_fnc_AMP = LocalConfig->AMPId;
            ...
         }
      }
      ...
   }
}
...