TIMESTAMP WITH TIME ZONE - Analytics Database - Teradata Vantage

SQL External Routine Programming

Deployment
VantageCloud
VantageCore
Edition
Enterprise
IntelliFlex
VMware
Product
Analytics Database
Teradata Vantage
Release Number
17.20
Published
June 2022
Language
English (United States)
Last Update
2023-07-11
dita:mapPath
iiv1628111441820.ditamap
dita:ditavalPath
qkf1628213546010.ditaval
dita:id
B035-1147
lifecycle
latest
Product Category
Teradata Vantage™

C Data Type Definition

typedef struct ANSI_TimeStamp_WZone
{
    DECIMAL4 seconds;
    SMALLINT year;
    BYTEINT  month;
    BYTEINT  day;
    BYTEINT  hour;
    BYTEINT  minute;
    BYTEINT  zone_hour;
    BYTEINT  zone_minutes;
} ANSI_TimeStamp_WZone;

Usage

The seconds member is laid out as a DECIMAL(8,6) numeric field, which can represent up to two digits of whole seconds and six digits of fractional seconds.

The range of values defined for the SQL TIMESTAMP WITH TIME ZONE type applies to the input arguments and return argument of a function. A value outside the valid range of values produces an error. For details on the TIMESTAMP WITH TIME ZONE type, see Teradata Vantage™ - Data Types and Literals, B035-1143.

All TIMESTAMP WITH TIME ZONE values passed to a UDF are in Universal Coordinated Time (UTC), and all TIMESTAMP WITH TIME ZONE values that are returned from a UDF must be in UTC.

The TIMESTAMP WITH TIME ZONE type has time zone fields, zone_hour and zone_minute, that have an internal form and an external form. When input arguments of this type are passed to a UDF, the values must be in internal form. Similarly, return arguments with this type must be in internal form.

To modify the time zone fields of the TIMESTAMP WITH TIME ZONE type, use the following macros in the sqltypes_td.h file to convert between the internal and external representation of the time zone fields of ANSI_Time_Wzone and ANSI_TimeStamp_Wzone.

TIMEZONE_INTERNAL_TO_EXTERNAL(i, s, h, m)
TIMEZONE_EXTERNAL_TO_INTERNAL(s, h, m, i)
i
Pointer to either an ANSI_Time_Wzone or ANSI_TimeStamp_Wzone.
s
BYTEINT value to store the sign of i: 0 if h and m are negative and 1 if the they are positive.
h
BYTEINT value to store the hour offset of i.
The external form for the hour offset is a BYTEINT value in the range [0, 14], prior and post conversion, which represents the hour offset between UTC and the given time zone.
m
BYTEINT value to store the minute offset of i.
The external form for the minute offset is a BYTEINT value in the range [0, 59], prior and post conversion, which represents the minute offset between UTC and the given time zone.

The largest value for negative offsets is -12:59. The largest value for positive offsets is +14:00.

This representation results in two representations of UTC, that is +00:00 and -00:00. This mirrors the internal representation which uses both representations for display purposes.

Here is an example using TIMESTAMP WITH TIME ZONE in a UDF definition and C function declaration.

SQL Function Definition Equivalent C Function Declaration
CREATE FUNCTION F1 (
 A TIMESTAMP WITH TIME ZONE)
RETURNS INTEGER
 ...;
void f1( ANSI_TimeStamp_WZone *a,
         INTEGER *result,
   ... )
{  ... }