16.20 - Usage Notes - 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)

You must call FNC_Get_GLOP_Map first before calling any other GLOP functions such as FNC_GLOP_Lock, FNC_GLOP_Unlock, FNC_GLOP_Map_Page, or FNC_GLOP_Global_Copy. Also, you should call FNC_Get_GLOP_Map first in each phase of a table function that uses any of the other GLOP routines to initialize the memory pointer for that phase.

When this call completes, the structure is filled in with the address of all GLOP mapped data that the external routine has access to for the particular instance in which it is invoked. If a GLOP_ptr is NULL then it has no mapping for that particular GLOP data. An external routine cannot assume that the entry is set up. First, it has no way of knowing whether it is supposed to be mapped. Second, it might not be mapped anymore. If the mapping is supposed to exist in order for the external routine to work and it does not exist, the external routine should return with an exception. The way to check is to always reference the mapping like this:

#define SYSTEM_MAP  0

Sysinfo_t  SysInfoPtr;
GLOP_Map_t *MyGLOP;
int        glop_stat;
. . .
glop_stat = FNC_Get_GLOP_Map(&MyGLOP);

if (glop_stat)
   ... process error: Not a member of any GLOP set

if ( MyGLOP->GLOP[SYSTEM_MAP].GLOP_Ptr == NULL)
{
   ... process error: System level map does not exist
};

SysInfoPtr = MyGLOP->GLOP[SYSTEM_MAP].GLOP_ptr;

. . .
Here are some rules to consider:
  • You can map the same GLOP data in multiple map indexes except for role, user, or external routine GLOP data. That way you can map different pages of the same read-only GLOP data at the same time. This has to be set up that way in the GLOP_Map table.
  • The pages are mapped according to the map data.
  • If the initial page information in the map data is null and the page is a read-only page, then it maps the lowest-numbered, currently-mapped page that is in memory for the given vproc. If the page has never been mapped, then page one gets mapped.
  • A read/write GLOP or globally modifiable GLOP can only be a single page. It always maps page one.
  • Multiple page read-only GLOP data could have different pages mapped to different external routines at the same time.
  • When there is no data row for a particular page of a GLOP, but it is in range, a zero filled page is mapped when an external routine pages it in.
  • The external routine always has to check to make sure the correct page is mapped for multiple page read-only GLOP data.