16.20 - CHARACTER / CHAR - 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)

C Data Type Definition

typedef unsigned char CHARACTER;
typedef Latin_Text CHARACTER_LATIN;
typedef Kanjisjis_Text CHARACTER_KANJISJIS;
typedef Kanji1_Text CHARACTER_KANJI1;
typedef Unicode_Text CHARACTER_UNICODE;

Usage

Character data types are passed using the standard null-terminated C string. Because of this, the length of the C string is one more than the length of the SQL string.

If you want to allow a binary zero character in the middle of a UDF input parameter string, use the CHAR data type because your C code can more easily handle embedded binary zero characters in fixed length strings. Similarly, if you want to allow a binary zero character in the middle of a UDF result string, use the CHAR data type because a binary zero character in the middle of a VARCHAR result string will end the string.

If the function defines a fixed length character input parameter, the number of characters in the input string always matches the maximum defined by the CREATE FUNCTION statement. If the function is called with a string that has fewer characters than the maximum, the input string is padded on the right before it is passed to the function.

Fixed length character data that requires padding uses the space character for the specified character set.

If the function result type is fixed length character data, then the result argument points to a data area with the size set to the maximum defined by the CREATE FUNCTION statement, plus one for the null string terminator. The number of characters in the result string must match the maximum defined by the CREATE FUNCTION statement. If the returned data is less than the maximum, you must add padding to the result string.

If the character set is UNICODE, use the CHARACTER_UNICODE data type. For character sets other than UNICODE, you can use the CHARACTER data type.

This example uses CHAR in a UDF definition and CHARACTER_LATIN in a C function declaration.

SQL Function Definition Equivalent C Function Declaration
CREATE FUNCTION F1 (
 A CHAR(6) CHARACTER SET LATIN)
RETURNS CHAR CHARACTER SET LATIN
 ...;
void f1(CHARACTER_LATIN a[7],
     CHARACTER_LATIN *result,
   ... )
{  ... }

Restrictions

Unicode strings use two bytes per character, including the null string terminator. The C library wide characters (wchar_t) are four bytes; therefore, you cannot use the C library wide character routines to manipulate Unicode strings.