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

Returns the Well-Known Text (WKT) representation of the Geometry as a null terminated character string in the Latin character set.

Syntax

void
FNC_GeomGetWKT(GEO_HANDLE  geoHandle,
               unsigned char *wktBuffer,
               FNC_GeomSize_t  wktBufferSize,
               FNC_GeomSize_t *wktSize,
               int *srid)
GEO_HANDLE geoHandle
A handle to an ST_Geometry type that is defined to be an input parameter to an external routine.
unsigned char * wktBuffer
A pointer to the buffer that will hold the WKT string.
FNC_GeomSize_t wktBufferSize
Size in bytes of the wktBuffer passed to the FNC routine.
FNC_GeomSize_t * wktSize
Size in bytes of the WKT string returned by the routine.
int* srid
Spatial Reference System Identifier of the Geometry returned by the routine.

Usage Notes

FNC_GeomGetWKT gets the Well Known Text representation of the Geometry. The GEO_HANDLE for the Geometry is passed in as input along with a pointer to a buffer (wktBuffer) and the buffer size (wktBufferSize). The wktBuffer size must be large enough to hold the WKT value. To determine the appropriate buffer size, use the FNC_GetGeometryInfo function or FNC_GetWKTSize function call to get the Geometry length.

The routine fills up the wktBuffer with the WKT representation. The wktSize and srid fields are also filled in by the FNC routine.

This FNC function should be called only on inline ST_Geometry values. If invoked for a LOB-based ST_Geometry value, a 7579 error is generated: FNC_GeomGetWKT is only valid for inline ST_Geometry values.

Example: Using FNC_GeomGetWKT to retrieve a ST_Geometry WKT

The following example function takes a ST_Geometry parameter and retrieves the Well Known Text format for the geometry. It returns the string back in the ST_Geometry return parameter.

CREATE FUNCTION geomUDF1(P1 st_geometry(1000))
RETURNS ST_GEOMETRY(1000)
NO SQL
PARAMETER STYLE SQL
DETERMINISTIC
LANGUAGE C
EXTERNAL NAME 'CS!geomUDF1!geomUDF1.c';

void geomUDF1(GEO_HANDLE* geom_handle,
              GEO_HANDLE* return_handle,
              int* indicator_thisGeom,
              int* indicator_returnGeom,
              char  sqlstate[6],
              SQL_TEXT   extname[129],
              SQL_TEXT   specific_name[129],
              SQL_TEXT   error_message[257] )
{
    FNC_GeomSize_t geomsize;
    FNC_GeomSize_t wktSize;
    char* wktBuffer;
    FNC_GeomSize_t wktBufferSize;
    int srid , max_length, numLobs;

    /* Get the Geometry Info */
     FNC_GetGeometryInfo(*geom_handle,&max_length, &numLobs); 
    if(numLobs == 0)
    {
    /* Get the Geometry WKT Size */
     geomsize = FNC_GeomGetWKTSize(*geom_handle); 

     /* Allocate the buffer to hold the WKT. Note that we add 
        1 for the null termination character. */ 
    wktBuffer = (char*)FNC_Malloc(geomsize + 1);
    wktBufferSize = geomsize + 1;

    /* Get the WKT string */
     FNC_GeomGetWKT(*geom_handle,wktBuffer, wktBufferSize, 
                     &wktSize, &srid); 
                                                                                                   
    /* Set the WKT string as return value */
     FNC_GeomSetWKT(*return_handle, wktBuffer, wktSize,0); 
    *indicator_returnGeom = 0;
    FNC_free(wkbBuffer);
    }
}