TdPeriodTimeWithTimeZone Structure

TdPeriodTimeWithTimeZone is a .Net Data Provider for Teradata specific type that represents a duration of time that is bound by beginning and ending times that have a time zone.

Object Model

Syntax

Visual Basic
C#
C++/CLI

'Declaration
 
Public Structure TdPeriodTimeWithTimeZone 
   Inherits System.ValueType
   Implements System.Data.SqlTypes.INullable, System.IComparable, System.IComparable(Of TdPeriodTimeWithTimeZone), System.IConvertible, System.IEquatable(Of TdPeriodTimeWithTimeZone), System.IFormattable, System.Xml.Serialization.IXmlSerializable

'Usage
 
Dim instance As TdPeriodTimeWithTimeZone

public struct TdPeriodTimeWithTimeZone : System.ValueType, System.Data.SqlTypes.INullable, System.IComparable, System.IComparable<TdPeriodTimeWithTimeZone>, System.IConvertible, System.IEquatable<TdPeriodTimeWithTimeZone>, System.IFormattable, System.Xml.Serialization.IXmlSerializable

public value class TdPeriodTimeWithTimeZone : public System.ValueType, System.Data.SqlTypes.INullable, System.IComparable, System.IComparable<TdPeriodTimeWithTimeZone>, System.IConvertible, System.IEquatable<TdPeriodTimeWithTimeZone>, System.IFormattable, System.Xml.Serialization.IXmlSerializable

Remarks

The Advanced SQL Engine introduced the Period type in release 13.0. Unfortunately, the .Net Framework does not contain a system type that corresponds to the Teradata Period(TimeWithTimeZone) type. Therefore, the Teradata provider exposes the TdPeriodTimeWithTimeZone type which enables an application to work with data of type Period(TimeWithTimeZone).

Similar to TdTimeWithTimeZone, TdPeriodTimeWithTimeZone supports a scale for the sub-seconds and a UTC Offset. The scale ranges from 0 to 6 and must be the same for both the beginning and ending bounds.

A period is an anchored duration. It represents a set of contiguous time granules within that duration. In the case of TdPeriodTimeWithTimeZone, the granularity of the time can range from 10^-6 (.000006 second) to 10^0 (1 second). The representation of a period is both inclusive and exclusive. It is inclusive in that the duration of the period begins from the beginning bound up to, but not including (excluding), the ending bound. For example suppose a TdPeriodTime contains the period of:

    "(13:12:21.05+08:00, 20:43:27.98+08:00)"

The duration will include "13:12:21.05+08:00" and not "20:43:27.98+08:00". It has a duration of 07:31:06.93 (7 hours, 31 minutes, 6 seconds, 980000 microseconds). The time element "15:21:43+08:00" is also included in the period.

The components of a period consists of the following:

Time Granule This is the minimum representation of time within a period. In the above example, the time granule is 10^-2 (.01 second).
Time Element A Time value that is contained within the period. The time element in TdPeriodTimeWithTimeZone is specified using a TdTimeWithTimeZone.
Beginning Bound The lower bound or the start of the period. Within a period, this value represents the "lowest" time element. The beginning bound must be less than the ending bound.
Ending Bound The upper bound or the ending of the period. The Ending Bound is not included in the period. Therefore, No Time Element in the period can be greater or equal to the Ending Bound.
Duration The number of granules in a period. It is represented as an interval/timespan.

The UTC Offset of the beginning and ending bounds do not have to be the same. However, the UTC representation of the beginning bound must be less than the UTC representation of the ending bound.

A TdPeriodTimeWithTimeZone can also be specified as an In, Out, or InOut parameter to a Stored Procedure. The data will be returned to an application using either the TdParameter.ProviderSpecificValue or TdParameter.Value property. Retrieving the parameter using TdParameter.ProviderSpecificValue, will return the data using the Period structure. When TdParameter.Value is used, the data is returned as a String (this is the corresponding .Net type).

Example

The following is an example on retrieving a TdPeriodTimeWithTimeZone, modify the period, and then updating the period.

Public void PeriodDateExample(TdCommand cmd, String studentId)
{
   cmd.Parameter.Clear();
            
   cmd.CommandText = "SELECT timePeriod  " +
                   "FROM ClassDetention " +
                   "WHERE StudentId = ?";
            
   cmd.CommandType = CommandType.Text;
            
   // creating the parameter
   cmd.Parameters.Add(null, TdType.Varchar, 9,
      System.Data.ParameterDirection.Input, true, 0, 0, null,    
      System.Data.DataRowVersion.Default, studentId);
            
   TdDataReader dr = null;
 
   Int32 i = 0;
            
   TdPeriodTimeWithTimeZone detention;
            
   Try
   {
      dr = cmd.ExecuteReader();
            
      If (false == dr.Read())
      {
	       return;
      }
   
      // Retrieving the Period
      detention = dr.GetTdPeriodTimeWithTimeZone(0);
   }
   finally
   {
      if (dr != null)
      {
         dr.Close();
      }
   }
            
   // An additional 1 hour will be added to ending bound.
            
   // Specifying a TimeSpan of 1 hour
   System.TimeSpan extraHours = new TimeSpan(1, 0, 0);
            
   // Getting the ending bound of the period and
   // adding 1 hour to it
   detention = new TdPeriodTimeWithTimeZone(detention.Begin, detention.End + extraHours);    
            
   cmd.Parameters.Clear();
            
   cmd.CommandText = "UPDATE classDetention " +
                        "SET timePeriod = ? " +
                        "WHERE StudentId = ?";
            
   cmd.Parameters.Add(null, TdType.PeriodTimeWithTimeZone, 0,
         System.Data.ParameterDirection.Input, true, 0, 0, null,    
         System.Data.DataRowVersion.Default, detention);
            
   cmd.Parameters.Add(null, TdType.Varchar, 9,
         System.Data.ParameterDirection.Input, true, 0, 0, null,    
         System.Data.DataRowVersion.Default, studentId);
            
   cmd.ExecuteNonQuery();
}

Inheritance Hierarchy

System.Object
System.ValueType
Teradata.Client.Provider.TdPeriodTimeWithTimeZone

Requirements

Target Platforms: Windows 8.1, Windows 10, Windows Server 2012 R2, Windows Server 2016, Windows Server 2019

Reference

TdPeriodTimeWithTimeZone Members
Teradata.Client.Provider Namespace
TdTime Structure
Provider Specific Types: Period Type Overview