C/C++ Function Body | SQL External Routine Programming | Teradata Vantage - 17.10 - C/C++ Function Body - 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)

Basic C/C++ Function Definition

Here are the basic steps you take to define a C/C++ function as a UDM:

  1. Define the SQL_TEXT constant.

    For more information, see Header Files.

  2. Include the sqltypes_td.h header file.

    For more information, see Header Files.

  3. Include other header files that define macros and variables that the function uses.
  4. Define the function parameter list in the order that matches the parameter passing convention specified in the METHOD specification of the CREATE TYPE statement.

    For more information, see UDM Parameter List.

  5. Implement the function and set the result to the appropriate value.

    If the function is a constructor UDM for a structured UDT or an instance UDM that provides cast, ordering, or transform functionality, the implementation must satisfy certain requirements.

    FOR details on implementing a C/C++ function that … SEE …
    is a constructor UDM Constructor UDMs.
    provides cast functionality for a UDT UDMs That Provide Cast Functionality for a UDT.
    provides ordering functionality for a UDT UDMs That Provide Ordering Functionality for a UDT.
    provides transform functionality for a UDT UDMs That Provide Transform Functionality for a UDT.
  6. If the function detects an error, set the:
    • sqlstate argument to an SQLSTATE exception or warning condition before the function exits.

      For more information, see Returning SQLSTATE Values.

    • error_message string to the error message text. The characters must be inside the LATIN character range. The string is initialized to a null-terminated string on input.
  7. If the method uses parameter style SQL, set the indicator_result argument.
    IF the result is … THEN set the indicator_result argument to …
    NULL -1.
    not NULL 0.

Example: Basic UDM

Here is an example of a simple C function that implements an instance UDM for a distinct UDT. The function uses the value of the UDT, which is in meters, and returns the equivalent value in inches. The UDM uses parameter style TD_GENERAL.

/*****  C source file name: to_inches.c  *****/

#define  SQL_TEXT Latin_Text
#include <sqltypes_td.h>
#include <string.h>

void meter_toInches( UDT_HANDLE  *meterUdt,
                     FLOAT       *result,
                     char         sqlstate[6])
{
   FLOAT value;
   int length;

   /* Get meter's value. */
   FNC_GetDistinctValue(*meterUdt, &value, SIZEOF_FLOAT, &length);

   /* Convert meters to inches and set the result value. */
   *result = value * 3.28 * 12;
}

Using UDT Handles in a UDM

Teradata provides library functions that a UDM can use with UDT_HANDLE input arguments and return values.

IF you want to … THEN use this library function …
get the value of a distinct type FNC_GetDistinctValue
set the value of a distinct type FNC_SetDistinctValue
get the locator for a distinct type that represents a LOB FNC_GetDistinctInputLob
FNC_GetDistinctResultLob
get the attribute value of a structured type FNC_GetStructuredAttribute
set the attribute value of a structured type FNC_SetStructuredAttribute
get the locator for a structured type LOB attribute FNC_GetStructuredInputLobAttribute
FNC_GetStructuredResultLobAttribute

Details on how to use the library functions appear in other sections of this document.

FOR details on how to … SEE …
access the value of a distinct UDT Accessing the Value of a Distinct UDT.
access the attribute values of a structured UDT Accessing the Attribute Values of a Structured UDT.
set the value of a distinct UDT result Setting the Value of a Distinct UDT Result.
set the attribute values of a structured UDT result Setting the Attribute Values of a Structured UDT Result.

UDMs That Provide Cast Functionality for a UDT

If the function is an instance UDM that provides cast functionality for a UDT, then the C/C++ function must satisfy the following requirements.

IF the method implements cast functionality that casts … THEN the C/C++ function must set the …
FROM … TO …
another UDT or predefined type a structured UDT attribute values of the UDT result using the value of the input argument.
a distinct UDT value of the UDT result using the value of the input argument.
a structured UDT another UDT or predefined type value of the result using the attribute values of the UDT input argument.
a distinct UDT value of the result using the value of the UDT input argument.

Vantage automatically generates cast functionality between a distinct type and its predefined source type. You can create additional methods for casting between a distinct type and other predefined data types or UDTs.

For examples of how to implement UDMs that provide cast functionality, see UDM Code Examples.

UDMs That Provide Ordering Functionality for a UDT

If the function is an instance UDM that provides ordering functionality for comparing two UDTs, the implementation must satisfy the following requirements.

IF the UDT is … THEN the C/C++ function must use the …
structured attribute values of the UDT to set the result to a value that Vantage uses for comparisons.
distinct value of the UDT to set the result to a value that Vantage uses for comparisons.

Vantage automatically generates ordering functionality when you create a distinct type where the source data type is not a LOB. However, you can drop the functionality and provide your own.

For an example of how to implement a UDM that provides ordering functionality, see UDM Code Examples.

UDMs That Provide Transform Functionality for a UDT

If the function is an instance UDM that provides transform functionality for exporting a UDT from the server, the implementation must satisfy the following requirements.

IF the UDT is … THEN the C/C++ function must transform the …
structured attribute values of the UDT into an appropriate value for the predefined type result.
distinct value of the UDT into an appropriate value for the predefined type result.

Although Vantage automatically generates transform functionality when you create a distinct type, you can drop the functionality and provide your own.

For an example of how to implement a UDM that provides transform functionality, see UDM Code Examples.

Constructor UDMs

If the function is a constructor UDM for a structured UDT, the C/C++ function must:
  • set the attribute values of the result UDT to the attribute values of UDT on which the UDM is invoked
  • set the attribute values of the result UDT to the values of corresponding input arguments

For an example of how to implement a constructor method, see UDM Code Examples.

UDMs That Use CLOB or BLOB Arguments

UDMs can define CLOB or BLOB input and output arguments, passing them by locator.

The guidelines for implementing UDMs that use CLOB or BLOB arguments are similar to the guidelines for implementing UDFs that use CLOB or BLOB arguments. For details, see Defining Functions that Use LOB Types.

UDMs That Use Period Arguments

UDMs can define Period input and output arguments, passing them by PDT handle.

The guidelines for defining UDMs that use Period arguments are similar to the guidelines for defining scalar UDFs that use Period arguments. For details, see Defining Functions that Use Period Types.

UDMs That Use ARRAY Arguments

UDMs can define ARRAY input and output arguments, passing them by ARRAY handle.

The guidelines for defining UDMs that use ARRAY arguments are similar to the guidelines for defining scalar UDFs that use ARRAY arguments. For details, see Defining Functions that Use ARRAY Types.

UDMs That Use TD_ANYTYPE Arguments

You can define UDMs with input and output parameters that are of TD_ANYTYPE data type.

The guidelines for defining UDMs that use TD_ANYTYPE arguments are similar to the guidelines for defining scalar UDFs that use TD_ANYTYPE arguments. For details, see Defining Functions that Use the TD_ANYTYPE Type.