STD.Date.TimeZone.AppendTZOffset( infile, timeZoneAbbrevField, newOffsetField, [fromLocationField, ][toTimeZoneAbbrev, ] [toLocation ] )
| infile | REQUIRED. The dataset to process. |
| timeZoneAbbrevField | REQUIRED. The field within inFile that contains the time zone abbreviation to use for matching; the values in this field should be uppercase. This is not a string |
| newOffsetField | REQUIRED. The field to append to inFile that will contain the number of seconds offset from UTC. This is not a string |
| fromLocationField | OPTIONAL. The field within inFile that contains the time zone location for the time zone cited by timeZoneAbbrevField. This is not a string. Defaults to a null value (indicating that there is no time zone location field). |
| toTimeZoneAbbrev | OPTIONAL. The to time zone abbreviation to use for all calculations, as a string. Defaults to 'UTC' |
| toLocation | OPTIONAL. 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. The appended fields
are:INTEGER4 <newOffsetField> // Offset, in seconds, between original
//time zone and toTimeZoneAbbrev
BOOLEAN <newOffsetField>_is_valid // TRUE if <newOffsetField> contains a
// valid value
// If <newOffsetField>_is_valid is FALSE
// then <newOffsetField> will be zero.
STRING5 <newOffsetField>_tz // The value of toTimeZoneAbbrev
STRING15 <newOffsetField>_location // The time zone location for
// <newOffsetField>_tz. |
The STD.Date.TimeZone.AppendTZOffset takes a dataset that contains a time zone abbreviation and optional location, and appends four new attributes to the dataset that contain useful information for translating a time value into another time zone.
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 SecondsBetweenTZ() 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});
utcOffsetDS := Std.Date.TimeZone.AppendTZOffset(ds, tz, seconds_to_utc);
OUTPUT(utcOffsetDS, NAMED('offset_to_utc_result'));
ptOffsetDS := Std.Date.TimeZone.AppendTZOffset (ds, tz, seconds_to_pacific_time,
toTimeZoneAbbrev := 'PT',
toLocation := 'NORTH AMERICA');
OUTPUT(ptOffsetDS, NAMED('offset_to_pacific_time_result'));See Also: AppendTZAdjustedTime , SecondsBetweenTZ