Date/time masks and format specifiers

EGL uses a pattern of upper and lower case letters to represent the components of a DATE, TIME, TIMESTAMP, or INTERVAL variable. These characters are case-sensitive, and all letters in the pattern parse to a component of the date or time. The rules for using these letters differ slightly depending on how you use them:

For more information about the internal values of these variables, see "Primitive data types."

Creating an INTERVAL mask

For a mask that is in month-span format, you can use the following characters, in the order shown:
y
Zero to nine digits that represent the number of years in the interval.
M
Zero to nine digits that represent the number of months in the interval. If M is not the first character in the mask, only two digits are allowed, at most.

The default mask is yyyyMM.

For a mask that is in second-span format, you can use the following characters, in the order shown:
d
Zero to nine digits that represent the number of days in the interval.
H
Zero to nine digits that represent the number of hours in the interval. If H is not the first character in the mask, only two digits are allowed, at most.
m
Zero to nine digits that represent the number of minutes in the interval. If m is not the first character in the mask, only two digits are allowed, at most.
s
Zero to nine digits that represent the number of seconds in the interval. If s is not the first character in the mask, only two digits are allowed, at most.
f
Zero to six digits that each represent a fraction of seconds; the first represents tenths, the second represents hundreds, and so on. Even when f is the first character in the mask, only six digits are allowed, at most.
Although you can have zero characters of a given kind at the beginning or end of a mask, you cannot skip intermediate characters. The following masks are valid:
  yyyyyyMM
  yyyyyy
  MM

  ddHHmmssffffff
  HHmmssff
  mmss
  HHmm
The following masks, however, are not valid because intermediate characters are missing:
  // NOT valid
  ddmmssffffff 
  HHssff

Creating a TIMESTAMP mask

The following characters are available, in order, when you specify the mask:
yyyy
Four digits that represent the year. The range is 0000 to 9999.
MM
Two digits that represent the month. The range is 01 to 12.
dd
Two digits that represent the day. The range is 01 to 31.
HH
Two digits that represent the hour. The range is 00 to 23.
mm
Two digits that represent the minute. The range is 00 to 59.
ss
Two digits that represent the second. The range is 00 to 59.
f
Zero to six digits that each represent a fraction of seconds; the first represents tenths, the second represents hundreds, and so on.

The default mask is yyyyMMddHHmmss.

The following rules also apply (for exceptions, see "Compatibility" in this topic):
  • You can have zero characters of a given kind at the beginning or end of a mask, but cannot skip intermediate characters.
  • The following masks are valid:
      yyyyMMddHHmmss
      yyyy
      MMss
  • The following masks are not valid because intermediate characters are missing:
      // NOT valid
      ddMMssffffff
      HHssff

Creating a display or parsing format

When scanning an input string to set the value of a date/time variable, EGL uses the current value of one of the following system variables (depending on the type of the variable):
  • strLib.defaultDateFormat
  • strLib.defaultTimeFormat
  • strLib.defaultTimestampFormat

The rules for a parsing format are similar to those for a display format, with exceptions noted in the following rules.

You can convert a date/time variable to a string for output using any of the following system functions:
  • strLib.formatDate()
  • strLib.formatTime()
  • strLib.formatTimestamp()
You can use any of the following values to specify the format for the conversion:
  • A format pattern of your own creation.
  • One of several standard patterns that EGL defines as constants (see the "formatDate()" strLib function).
  • The appropriate default format (such as strLib.defaultDateFormat), depending on the type of the variable that you are converting.

Create your own format pattern by using letters to indicate the components of the date or time. To include letters in the date/time string without that text being parsed as a component of the date or time, enclose that letter or letters in single quotation marks. To display a single quotation mark in the date, time, or timestamp, use two single quotation marks.

The following table lists the letters and their values in the pattern.

Letter Date or time component Type Examples
G Era designator Text AD
y Year Year 1996; 96
M Month in year Month July; Jul; 07
w Week in year Number 27
W Week in month Number 2
D Day in year Number 189
d Day in month Number 10
F Day in week Number 2
E Day of week Text Tuesday; Tue
a AM/PM marker Text PM
H Hour in day (0-23) Number 0
k Hour in day (1-24) Number 24
K Hour in AM/PM (0-11) Number 0
h Hour in AM/PM (1-12) Number 12
m Minute in hour Number 30
s Second in minute Number 55
S Millisecond (output) Number 978
f Millisecond (parsing) Number 978
z Time zone General time zone Pacific Standard Time; PST; GMT-08:00
Z Time zone RFC 822 time zone -800
C Century Century 20; 21

Multiples of the same letter used consecutively in the pattern determine how EGL parses the corresponding numbers, letters, or both in the string. The interpretation depends on the type of letter, and on whether the pattern is being used for formatting or parsing. The following list describes the types of letters and how different quantities of those letters affect the way they are interpreted.

Text
For output, if the number of letters is greater than 4, the full form is used. Otherwise, an abbreviation is used, if available. In parsing, both forms are accepted, independent of the number of pattern letters.
Number
For output, the number of pattern letters represents the minimum number of digits. zeros are added to shorter numbers to make them the designated length. For parsing, the number of pattern letters is ignored unless it is needed to separate two adjacent fields.
Year
For formatting, if the number of pattern letters is 2, the year is truncated to 2 digits. Otherwise, it is interpreted as the Number type.

For parsing, if the number of pattern letters is not 2, the year is interpreted literally, regardless of the number of digits. For example, the pattern MM/dd/yyyy assigned the value 01/11/12 parses to January 11, 12 A.D. The same pattern assigned the value 01/02/3 or 01/02/0003 parses to January 2, 3 A.D. In the same way, the same pattern assigned the value 01/02/-3 parses to January 2, 4 B.C.

For parsing, if the pattern is yy, the parser determines the full year relative to the current year. The parser assumes that the two-digit year is within 80 years before or 20 years after the time of processing. For example, if the current year is 2007, the pattern MM/dd/yy assigned the value 01/11/12 parses to January 11, 2012, while the same pattern assigned the value 05/04/64 parses to May 4, 1964.

Month
If the number of pattern letters is 3 or more, the month is interpreted as the Text type. Otherwise, it is interpreted as the Number type.
Milliseconds
Use SSSS to format an INTERVAL or TIMESTAMP variable. (Use ffff instead when you declare the variable.) Consider the following examples:
t TIMESTAMP( "ssffff" );
s STRING = StrLib.formatTimestamp( t, "ssSSSS" );
General time zone
General time zones are interpreted as the Text type if they have names. For time zones representing a GMT offset value, the following syntax is used:

GMTOffsetTimeZone = GMT Sign Hours Minutes

Sign
Either + or -
Hours
A one-digit or two-digit number from 0 to 23. The format is locale independent and must be taken from the Basic Latin block of the Unicode standard.
Minutes
A two-digit number from 00 to 59. The format is locale independent and must be taken from the Basic Latin block of the Unicode standard.

For parsing, RFC 822 time zones are also accepted.

RFC 822 time zone
For formatting, the RFC 822 4-digit time zone format is used

RFC822TimeZone = Sign TwoDigitHours Minutes

TwoDigitHours must be a two-digit number from 00 to 23. The other definitions are the same as the General time zone type.

For parsing, General time zones are also accepted.

Century
Displayed as a Number type that shows the result of the following calculation: full year divided by 100, with the remainder ignored.

The following table lists some examples of date and time patterns interpreted in the U.S. locale. All use the same date: 4 July, 2001, 12:08:56 in the afternoon, Pacific Daylight Time.

Date and Time Pattern Result
yyyy.MM.dd G 'at' HH:mm:ss z 2001.07.04 AD at 12:08:56 PDT
EEE, MMM d, ''yy Wed, Jul 4, '01
h:mm a 12:08 PM
hh 'o''clock' a, zzzz 12 o'clock PM, Pacific Daylight Time
K:mm a, z 0:08 PM, PDT
yyyyy.MMMMM.dd GGG hh:mm aaa 02001.July.04 AD 12:08 PM
EEE, d MMM yyyy HH:mm:ss Z Wed, 4 Jul 2001 12:08:56 -0700
yyMMddHHmmssZ 010704120856-0700

Calendar specifiers

The date/time format specifiers can also include calendar specifiers. These specifiers indicate a calendar system that EGL uses to parse a date string for input, or format a date string for output. EGL performs a conversion between the string date for a specified calendar and the internal value of the DATE, TIME, or TIMESTAMP variable.

The two-letter calendar specifier must come at the beginning of a date pattern, and it must have an uppercase letter first and a lowercase letter second. The following table lists the available calendars:
Table 1. Calendars
Calendar specifier Calendar
Bu Buddhist
Ch Chinese
Gr Gregorian
He Hebrew
Is Islamic
Ja Japanese

This subject becomes complex quickly because localized date strings in the various calendar systems might not be printable in other locales. Different calendars use different starting points for numbering years, as well as different era designators, many of which display properly only in specific localized environments. For example, the Japanese Imperial date system ties dates to the reigns of Japanese emperors as well as to the old-style Julian Calendar (which is several days behind the Gregorian).

The following code fragment shows one way to convert dates from the Gregorian to the Japanese calendar:
myDate DATE;
myJapaneseDate STRING;

strLib.defaultDateFormat = "Gryyyy/MM/dd";
myDate = "1912/08/13";
myJapaneseDate = formatDate(myDate,"JaGyy/MM/dd");
If your system is localized for Japan, you can set strLib.defaultDateFormat to use the Japanese calendar and set myDate to a Japanese calendar date. EGL parses the date string according to the default date format and stores it as an eight-digit Gregorian date.

The following table lists sample Gregorian dates as converted to the Japanese era format specified above. The names in brackets represent the four double-byte Japanese characters for a specific Japanese era.

Table 2.
Gregorian Date Japanese Era-based Date
1868/09/20 [Meiji]01/09/08
1912/08/12 [Meiji]45/07/30
1912/08/13 [TaishÅ?]01/07/31
1927/01/07 [TaishÅ?]15/12/25
1927/01/08 [ShÅ?wa]01/12/26
1989/01/20 [ShÅ?wa]64/01/07
1989/01/21 [Heisei]01/01/08
2005/01/14 [Heisei]17/01/01

EGL uses the Java™ version of the International Components for Unicode libraries (ICU4J) to perform the necessary date conversions for input and display. However, EGL always stores the dates in Gregorian form using eight digits. This means that if a Thai application requests a date from the Buddhist calendar, EGL stores that date in eight-digit Gregorian form using ICU4J for the conversion. As long as the application is consistent in the patterns it uses, this process remains invisible to both the programmer and the user.

Compatibility

Table 3. Compatibility considerations for date/time formats
Platform Issue
COBOL generation
  • For the TIMESTAMP format, any components that you specify must be contiguous. For example, you can specify month and day, but not month and hour.
  • You can specify milliseconds (ffffff), but only the first 2 bytes are set when retrieving the system time; the remaining bytes in the milliseconds are set to 0.
DB2® See "COBOL generation" entry in this table.
Rich UI See Rich UI date and time support.

Feedback