DateTime as string data

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 digit years the physical message set property of Start of century for 2 digit years is used to determine the century. For example, if Start of century for 2 digit years is set to 53, year 97 is 1997, year 52 is 2052, and year 53 is 1953.
  2. The start of a year usually falls in the middle of a week. If the number of days in that week is less than the value specified by the physical message set property Days in First Week of Year, the week is considered to be the last week of the previous year; hence week 1 starts some days into the new year. Otherwise it is considered to be the first week of the new year; hence week 1 starts some days before the new year. For example, Monday of week 1 in 2004 (2004 01 Monday, where Days in First Week of Year = 4 and First Day of Week = Monday ) using format string YYYY ww EEEE is in fact 29th December 2003. If you use Y, the day of week (E) and week in year (w) are adjusted if necessary to indicate that the date falls in the previous year.

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

    • Monday of week 1 in 2002 using format string YYYY ww EEEE is correctly interpreted as 31st December 2001
    • Monday of week 1 in 2002 using format string yyyy ww EEEE is incorrectly interpreted as 30th December 2002

    Y should only be used in conjunction with w. If you specify Y without w, the year is ignored. For example, if you specify YYYY-MM-dd to format 1996-03-01 the result is 2005-03-01 because the year input is ignored and the current year is assumed.

  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 day in week field is the numeric offset into a week and will vary depending on the value of the physical message set property First Day of Week. For example, the third day in the week would be Wednesday where a physical message set property First Day of Week set to Monday
  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