Formatting and parsing dateTimes as strings

This section gives information on how you can specify the dateTime format using a string of pattern letters.

When you are converting a date or time into a string, a format pattern can be applied that directs the conversion. This would apply if you were formatting from a date or time into a string or parsing a string into a date or time.

During the formatting (for example, a dateTime to a string) a pattern or a set of tokens is replaced with their equivalent source. Figure 1 gives a representation of how this is applied.

Figure 1. Using a pattern to format a dateTime source to produce a string output.

When a string is parsed (for example, converting it to a dateTime), the pattern or set of tokens are used to determine which part of the target dateTime is represented by which part of the string. Figure 2 gives a representation of how this is applied.

Figure 2. Using a pattern to parse a string source to produce a dateTime output.

Syntax

The expression pattern is defined by:

   .--------------.
   | .- -.        |
   V V   |        |
  >------+-symbol-+->
         '-string-'

Where:
symbol
is a character in the set adDeEFGhHIkKmMsSTUwWyYzZ.
string
is a sequence of characters enclosed in single quotation marks. If a single quote is required within the string, two single quotes, “''”, can be used.

Characters for formatting a dateTime as a string

The following table lists the allowable characters that can be used in a pattern for formatting or parsing strings in relation to a dateTime.

Symbol Meaning Presentation Examples
a am or pm marker Text Input am, AM, pm, PM. Output AM or PM
d day in month (1-31) Number 1, 20
dd day in month (01-31) Number 01, 31
D day in year (1-366) Number 3, 80, 100
DD day in year (01-366) Number 03, 80, 366
DDD day in year (001-366) Number 003
e day in week (1-7) Number 26
EEE day in week Text Tue
EEEE day in week Text Tuesday
F day of week in month (1-5) Number 2 (for second Wednesday in July)3
G Era Text BC or AD
h hour in am or pm (1-12) Number 6
hh hour in am or pm (01-12) Number 06
H hour of day in 24 hour form (0-23) Number 77
HH hour of day in 24 hour form (00-23) Number 077
I ISO8601 Date/Time (up to yyyy-MM-dd'T'HH:mm:ss. SSSZZZ) text 2004-10-07T12:06:56.568+01:00 5
IU ISO8601 Date/Time (as above, but ZZZ with output "Z" if the timezone is +00:00) text 2004-10-07T12:06:56.568+01:00, 2003-12 -15T15:42:12.000Z 5
k hour of day in 24 hour form (1-24) Number 87
k hour of day in 24 hour form (01-24) Number 087
K hour in am or pm (0-11) Number 9
KK hour in am or pm (00-11) Number 09
m minute Number 4
mm minute Number 04
M numeric month Number 5, 12
MM numeric month Number 05, 12
MMM named month Text Jan, Feb
MMMM named month Text January, February
s seconds Number 5
ss seconds Number 05
S decisecond Number 78
SS centisecond Number 708
SSS millisecond Number 7008
SSSS 1/10,000 th seconds Number 70008
SSSSS 1/100,000 th seconds Number 700008
SSSSSS 1/1,000,000 th seconds Number 7000008
T ISO8601 Time (up to HH:mm:ss.SSSZZZ) text 12:06:56.568+01:005
TU ISO8601 Time (as above, but a timezone of +00:00 is replaced with 'Z') text 12:06:56.568+01:00, 15:42:12.000Z5
w week in year Number 7, 532
ww week in year Number 07, 532
W week in month Number 24
yy year Number 961
yyyy year Number 19961
YY year: use with week in year only Number 962
YYYY year: use with week in year only Number 19962
zzz time zone (abbreviated name) Text gmt
zzzz time zone (full name) Text Greenwich Mean Time
Z time zone (+/-n) Text +3
ZZ time zone (+/-nn) Text +03
ZZZ time zone (+/-nn:nn) Text +03:00
ZZZU time zone (as ZZZ, "+00:00" is replaced by "Z") Text +03:00, Z
ZZZZ time zone (GMT+/-nn:nn) Text GMT+03:00
ZZZZZ time zone (as ZZZ, but no colon) (+/-nnnn) Text +0300
' escape for text   'User text'
'' (two single quotes) single quote within escaped text   'o''clock'

The presentation of the dateTime object depends on what symbols you specify as follows:

Notes: The following points explain the notes in the table above:
  1. Year is handled as a special case:
    • On output, if the count of y is 2, the year is truncated to 2 digits. For example, if yyyy produces 1997, yy produces 97.
    • On input, for 2 digits years the century window is fixed to 53. For example an input date of 52 will result in a year value of 2052, whilst 53 would give an output year of 1953 and 97 would give 1997.
  2. In ESQL, the first day of the year is assumed to be in the first week, thus January 1 is always in week 1. This can lead to dates specified relative to one year actually being in a different year. For example, "Monday week 1 2005" parsed using "EEEE' week 'w' 'YYYY" would give a date of 2004-12-27, since the Monday of the first week in 2005 is actually a date in 2004.

    If you use the y symbol, the adjustment is not done and unpredictable results could occur for dates around the end of the year. For example, if the string "2005 01 Monday" is formatted:

    • Monday of week 1 in 2005 using format string "YYYY ww EEEE" is correctly interpreted as 27st December 2004
    • Monday of week 1 in 2005 using format string "yyyy ww EEEE" is incorrectly interpreted as 27th December 2005
  3. The 11th July 2001 is the second Wednesday in July and can be expressed as 2001 July Wednesday 2 using format string yyyy MMMM EEEE F. This is not the same as Wednesday in week 2 of July 2001, which is 4th July 2001.
  4. The first and last week in a month might include days from neighboring months. For example, Tuesday 31st July 2001 could be expressed as Tuesday in week one of August 2001, which is 2001 08 1 Tuesday using format string yyyy MM W EEEE.
  5. See the section ISO8601, I and T DateTime tokens.
  6. The values specified in the day in week field are fixed to:
    • 1 - Sunday
    • 2 - Monday
    • 3 - Tuesday
    • 4 - Wednesday
    • 5 - Thursday
    • 6 - Friday
    • 7 - Saturday
  7. 24 hour fields may result in an ambiguous time if specified with a conflicting am/pm field.
  8. Fractional Seconds The length must implicitly match the number of format symbols on input. The output is rounded to the specified length.
  9. Long time zones work best when used in the Continent/City format. Similarly, on Unix systems, the TZ environment variable should be specified using the Continent/City format.

ISO8601, I and T DateTime tokens

If your dateTime values are compliant with the ISO8601:2000 'Representation of dates and times' standard, you should consider whether it is possible to use the formatting symbols I and T. These match a subset of the ISO8601 standard, specifically:

These symbols should only be used on their own.

On output, following form will be applied depending on the logical datatype:

Logical MRM Datatype Logical ESQL Datatype Output Form
xsd:dateTime TIMESTAMP or GMTTIMESTAMP yyyy-MM-dd'T'HH:mm:ss.SSSZZZ
xsd:date DATE yyyy-MM-dd
xsd:gYear INTERVAL yyyy
xsd:gYearMonth INTERVAL yyyy-MM
xsd:gMonth INTERVAL --MM
xsd:gmonthDay INTERVAL --MM-dd
xsd:gDay INTERVAL ---dd
xsd:time TIME / GMTTIME 'T'HH:mm:ss.SSSZZZ
Note:
  • On input both I and T accept '+00:00' and 'Z' to indicated a zero time difference from Coordinated Universal Time (UTC), but on output will always generate '+00:00'. If you require that 'Z' is always generated on output, you should use the alternative IU or TU formatting symbols instead.
  • ZZZ will always output '+00:00' to indicate a zero time difference from Coordinated Universal Time (UTC). If you require that 'Z' is always generated on output, you should use the alternative ZZZU form instead.

Using the input UTC format on output

An element or attribute of logical type xsd:dateTime or xsd:time that contains a dateTime as a string can specify Consolidated Universal Time (UTC) by using either the Z character or time zone +00:00. On input the MRM parser remembers the UTC format of such elements and attributes. On output you can specify whether Z or +00:00 should appear by using the dateTime format property of the element or attribute. Alternatively you can preserve the input UTC format by checking message set property Use input UTC format on output. If this property is checked, then the UTC format will be preserved into the output message and will override that implied by the dateTime format property.

Examples

The following table shows a few examples of dateTime formats:

Format pattern Result
"yyyy.MM.dd'at'HH:mm:ss ZZZ" 1996.07.10 at 15:08:56 -05:00
EEE, MMM d, "yy" Wed, July 10, '96
"h:mm a" 8:08 PM
"hh 'o''clock' a, ZZZZ" 09 o'clock AM, GMT+09:00
"K:mm a, ZZZ" 9:34 AM, -05:00
"yyyy.MMMMM.dd hh:mm aaa" 1996.July.10 12:08 PM
Related concepts
Message modeling
The message model
Related tasks
Developing message models
Working with a message definition file
Working with message model objects
Related reference
Message model reference information
Message model object properties
CAST function
Formatting and parsing numbers as strings
Supported casts
Implicit casts