AppendTZAdjustedTime

STD.Date.TimeZone.AppendTZAdjustedTime( infile, timeField, timeZoneAbbrevField, newTimeField, [fromLocationField, ][toTimeZoneAbbrev, ] [toLocation ] )

infileREQUIRED. The dataset to process.
timeFieldREQUIRED. The field within inFile that contains a time represented in Time_t format. This is not a string.
timeZoneAbbrevFieldREQUIRED. The field within inFile that contains the time zone abbreviation to use for matching; the values in this field should be uppercase.
newTimeFieldREQUIRED. The field to append to inFile that will contain the adjusted value of timeField.
fromLocationFieldOPTIONAL. The field within inFile that contains the time zone location for the time zone cited by timeZoneAbbrevField. Defaults to a null value (indicating that there is no time zone location attribute.) If a location is not provided or is an empty string, the first record matching fromTimeZoneAbbrevField is used
toTimeZoneAbbrevOPTIONAL. The to time zone abbreviation to use for all calculations, as a string. Defaults to 'UTC'
toLocationOPTIONAL. The name of the location that goes along with toTimeZoneAbbrev; if a location is not provided or is an empty string, the first record matching toTimeZoneAbbrev is used; Defaults to an empty string
Returns:A new dataset with the same record definition as inFile but with four new fields added; the new fields are named based on the name given as the newOffsetField attribute:
std.Date.Time_t <newOffsetField>   // Value of timeField expressed in new 
                                   // time zone 
BOOLEAN <newOffsetField>_is_valid  // TRUE if <newOffsetField> contains a 
                                   // valid value 
                                   // If <newOffsetField>_is_valid is FALSE  
                                   // then <newOffsetField> will have the same 
                                   // value as timeField.
STRING5 <newOffsetField>_tz        // The value of toTimeZoneAbbrev 
STRING15 <newOffsetField>_location // The time zone location for
                                   // <newOffsetField>_tz 

The STD.Date.TimeZone.AppendTZAdjustedTime takes a given a dataset that contains a time (in Time_t format), a time zone abbreviation, and an optional time zone location, and appends four new fields to the dataset: A new Time_t attribute containing the original time expressed in a different time zone, and three attributes providing information regarding that destination time zone and the validity of the translation.

This could be useful as an ETL step where time data is made common in respect to one particular time zone (e.g., UTC). The actions within this function macro are conceptually similar to AdjustTimeTZ() but applied to an entire dataset, and somewhat more efficiently.

Note: In order for this function macro to execute correctly, the calling code must import the STD library.

Example:

IMPORT STD;
ds := DATASET ([
                {120000, 'CT'},
                {120000, 'ET'}
               ],{Std.Date.Time_t time, STRING tz});

utcRewriteDS := Std.Date.TimeZone.AppendTZAdjustedTime(ds, time, tz, utc_time);
OUTPUT(utcRewriteDS, NAMED('utc_result'));
 
ptRewriteDS := Std.Date.TimeZone.AppendTZAdjustedTime (ds, time, tz, pacific_time, 
                                                       toTimeZoneAbbrev := 'PT', 
                                                       toLocation := 'NORTH AMERICA');
OUTPUT(ptRewriteDS, NAMED('pacific_time_result'));

See Also: AppendTZOffset , AdjustTimeTZ