C/C++ Function Body | SQL External Routine Programming | Teradata Vantage - C/C++ Function Body - Advanced SQL Engine - Teradata Database

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 "SQL_Text Definition" in 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 Database provides library functions that a UDM can use with UDT_HANDLE input arguments and return values.

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

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.

Teradata Database 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.

Teradata Database 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.

Although Teradata Database 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

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.