Time Zones and Time Formats

Time Zone Data

The Gateway binary is accompanied by a time zone resources file, date_time_zonespec.csv, derived from the time zone database maintained by IANA. This file lists the names and abbreviations for the timezones known to the Gateway.

The time zone names can be used when configuring ActiveTime periods, scheduled events, and in Time arguments in Internal Commands. The time zone abbreviations can be used when defining rules to parse and format strings containing timestamps.

Be aware of the following:

  • Time zone abbreviations, such as "EST" are inherently ambiguous. By default, when the Gateway has to map an abbreviation to a time zone, it takes the first match. That is, it uses the time zone whose full name comes first in alphabetical order. This can be overridden by setting up time zone abbreviations in the Operating Environment setup of the Gateway.

  • The time zone resources file includes columns "DST Start Date rule" and "DST End Date rule". These encode the rules used to find the dates when Daylight Savings Time starts and ends. Each rule is represented by three numbers separated with semicolons, for example "-1;5;9".

    The first number indicates the "nth" weekday of the month. The possible values are: 1 (first), 2 (second), 3 (third), 4 (fourth), 5 (fifth), and -1 (last). The second number indicates the day-of-week from 0-6 (Sun=0). The third field indicates the month from 1-12 (Jan=1).

    For example, "-1;5;9" means "Last Friday of September" and "2;1;3" means "Second Monday of March".

  • Because some countries use DST rules that cannot be encoded this way and because the file format cannot represent historic changes in the rules or changes announced more than a year in advance, the file is regenerated from time to time. The latest version is included with each release of the Gateway.

Time Formatting Parsing Codes

The following formatting codes can be used in rule functions and with certain plug-ins.

Specifier Replaced by
%a, %A Day of the week; either abbreviated or full name. (e.g. Thu or Thursday)
%b, %B Month Name; either abbreviated or full name (eg Aug or August)
%c Date and time representation (local dependant)
%d Day of the month [01,31]; leading zeros are permitted but not required.
%D The date as %m/%d/%y
%e Day of the month [01,31]; leading zeros are permitted but not required.
%f1 Milliseconds. (Reads between 0 and 3 digits). The period is part of this code, to read seconds and milliseconds use %S%f. If you do not want the period included in the code please use %Of which reads just the digits.
%F The date as %Y-%m-%d
%g1 Microseconds. (Reads between 0 and 6 digits). The period is part of this code, to read seconds and microseconds use %S%g. If you do not want the period included in the code please use %Og which reads just the digits.
%H Hour in 24h format [00,23]; leading zeros are permitted but not required.
%I Hour in 12h format [01,12]; leading zeros are permitted but not required.
%m Month as a decimal number [01,12]; leading zeros are permitted but not required.
%M Minute [00,59]; leading zeros are permitted but not required.
%p AM or PM designation
%r The time as %I:%M:%S %p
%R The time as %H:%M
%s The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC)
%S Second [00,60]; leading zeros are permitted but not required.
%T The time as %H:%M:%S
%x The date as %m/%d/%y
%X The time as %H:%M:%S
%y Year, last two digits [00,99]
%Y Year, last all digits (e.g. 2008)
%z Timezone offset from GMT [+|-]:hh:mm
%Z Timezone standard/day light saving abbreviation (ie EET or EEST)
%+ The date and time as "%a %b %e %H:%M:%S %Z %Y"
%% A % sign

Note: The formats specified above with super-script 1 are useful only for messageTracker timestamp format.

On UNIX systems some conversion specifications can be modified by preceding the conversion specifier character by the E or O modifier to indicate that an alternative format should be used. If the alternative format or specification does not exist for the current locale, the behaviour will be as if the unmodified conversion specification were used. (SU) The Single Unix Specification mentions %Ec, %EC, %Ex, %EX, %Ey, %EY, %Od, %Oe, %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV, %Ow, %OW, %Oy, where the effect of the O modifier is to use alternative numeric symbols (say, roman numerals), and that of the E modifier is to use a locale-dependent alternative representation.

Full list of timezone regions, their abbreviations, GMT offset and DayLightSaving adjustments is given here.

Time Formatting Printing Codes

The following formatting codes can be used in rule functions, with certain plug-ins and for gateway log file rotation.

Specifier Replaced by
%a Abbreviated weekday name (ie Thu)
%A Full weekday name (ie Thursday)
%b Abbreviated month name (ie Aug)
%B Full month name (ie August)
%c Date and time representation (local dependant)
%C* The century number (year/100) as a 2-digit integer [00,99]
%d Day of the month [01,31]; leading zeros are permitted but not required.
%D The date as %m/%d/%y
%e Day of the month [01,31]; leading zeros are permitted but not required.
%F1 The date as %Y-%m-%d
%g1 Week-based year within century [00,99]
%G1 Week-based year, including the century [0000,9999]
%h Equivalent to %b
%H Hour in 24h format [00,23]; leading zeros are permitted but not required
%I Hour in 12h format [01,12]; leading zeros are permitted but not required
%j Day of the year [001,366]; leading zeros are permitted but not required
%k Hour in 24h format (0-23); single digits are preceded by a blank
%l1 Hour in 12h format (1-12); single digits are preceded by a blank
%m Month as a decimal number [01,12]; leading zeros are permitted but not required
%M Minute [00,59] ; leading zeros are permitted but not required
%n Insert a NEWLINE
%p AM or PM designation; Noon is treated as 'pm' and midnight as 'am'
%P12 Like %p but in lowercase: 'am' or 'pm'
%r The time as %I:%M:%S %p
%R The time as %H:%M
%s2 The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC)
%S* Second [00,60]; leading zeros are permitted but not required. The range is up to 60 to allow for occasional leap seconds.
%t Insert a TAB
%T The time as %H:%M:%S
%u The day of the week as a decimal, range 1 to 7, Monday being 1
%U Week number with the first Sunday as the first day of week one [00,53]
%V* Week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the current year, and with Monday as the first day of the week.
%w Weekday as a decimal number with Sunday as 0 [0,6]
%W Week number with the first Monday as the first day of week one [00,53]
%x Date representation (local dependant)
%X Time representation (local dependant)
%y Year, last two digits [00,99]
%Y Year, last all digits (e.g. 2008)
%z12 The time-zone as hour offset from GMT
%Z Timezone name or abbreviation (ie CDT)
%+12 The date and time as "%a %b %e %H:%M:%S %Z %Y"
%% A % sign

Points of Note:

Regular Expression Types Used In Plugins

The following table provides a summary of the types of regular expression used in the various plugins.

Plugin Types of regular expression supported
FKM By default uses POSIX extended regular expression syntax. If the configuration setting isPCREMode is set to true, it will use PCRE (Perl Compatible Regular Expressions) instead.
Message Tracker Perl Regular Expressions (perlre)
State Tracker Perl Compatible Regular Expressions (PCRE)
FIX-analyzer PCRE
IMXA POSIX extended
Webmon Perl Compatible Regular Expression
Processes

By using the configuration setting regexMode, the user can choose between the following regular expression types:

  • Berkeley - Berkeley library interface. On some platforms this may make a difference to the pattern matching algorithm. It is highly recommend that you use one of the other modes unless you have a specific reason for choosing this one.
  • Normal - POSIX regular expression syntax.
  • Extended - POSIX extended regular expression syntax.
  • PCRE - Perl compatible regular expression syntax.
  • None - text is searched for in string as is (case insensitive by default).

If regexMode is not set, the default is that POSIX extended regular expression syntax is used.