WebSphere Message Brokers
File: ad09291_
Writer: John Morris-Smith

Reference topic

This build: July 31, 2007 21:23:11

DateTime as string data

This topic explains how to specify the dateTime format using a string of pattern letters.

When you convert a date or time into a string, a format pattern must be applied that directs the conversion. Apply the format pattern to convert a date or time into a string, or to parse a string into a date or time.

During the conversion (for example, of a dateTime into a string), a pattern or a set of tokens is replaced with the equivalent source. The following diagram shows how a pattern is used to format a dateTime source to produce a character string output.

When a string is parsed (for example, converting it to a dateTime), the pattern or set of tokens is used to determine which part of the target dateTime is represented by which part of the string. The following diagram shows how this is done.

Syntax

The expression pattern is defined by:

Where:
symbol
is a character in the set adDeEFGhHIkKmMsSTUwWyYzZ.
string
is a sequence of characters enclosed in single quotation marks. If a single quotation mark is required within the string, use two single quotes, “ '' �.

Characters for formatting a dateTime as a string

The following table lists the characters that you can use in a pattern for formatting or parsing strings in relation to a dateTime. Some notes follow the table; these explain more about some of the examples in the table.

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)1 Number 2
EEE day in week1 Text Tue
EEEE day in week1 Text Tuesday
F day of week in month (1-5)2 Number 2
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)3 Number 7
HH hour of day in 24 hour form (00-23)3 Number 07
I ISO8601 Date/Time (up to yyyy-MM-dd'T'HH:mm:ss. SSSZZZ)4 text 2006-10-07T12:06:56.568+01:00
IU ISO8601 Date/Time (as above, but ZZZ with output "Z" if the time zone is +00:00)4 text 2006-10-07T12:06:56.568+01:00, 2003-12 -15T15:42:12.000Z
k hour of day in 24 hour form (1-24)3 Number 8
k hour of day in 24 hour form (01-24)3 Number 08
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 decisecond5 Number 7
SS centisecond5 Number 70
SSS millisecond5 Number 700
SSSS 1/10,000 th seconds5 Number 7000
SSSSS 1/100,000 th seconds5 Number 70000
SSSSSS 1/1,000,000 th seconds5 Number 700000
T ISO8601 Time (up to HH:mm:ss.SSSZZZ)4 text 12:06:56.568+01:00
TU ISO8601 Time (as above, but a time zone of +00:00 is replaced with 'Z')4 text 12:06:56.568+01:00, 15:42:12.000Z
w week in year6 Number 7, 53
ww week in year6 Number 07, 53
W week in month7 Number 2
yy year8 Number 06
yyyy year8 Number 2006
YY year: use with week in year only6 Number 06
YYYY year: use with week in year only6 Number 2006
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 the symbols that you specify.

Notes: The following notes apply to the table above.
  1. The day in week field is the numeric offset into a week and varies according to the value of the physical message set property First Day of Week. For example, the third day in the week is Wednesday if the physical message set property First Day of Week is set to Monday.
  2. The 12th July 2006 is the second Wednesday in July and can be expressed as 2006 July Wednesday 2 using format string yyyy MMMM EEEE F. This is not the same as Wednesday in week 2 of July 2006, which is 5th July 2006.
  3. 24-hour fields might result in an ambiguous time, if specified with a conflicting am/pm field.
  4. See ISO8601, I and T DateTime tokens.
  5. Fractional seconds are represented by upper case S. The length must implicitly match the number of format symbols on input. The format string ss SSS or ss.SSS, for example, represents seconds and milliseconds. However, the format string ss.sss represents just seconds, a repeated field, and the value after the period is taken as the seconds field. The output is truncated to the specified length.
  6. The start of a year typically 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 lower case y symbol, the adjustment is not done and unpredictable results might 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

    Use Y only together 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 2006-03-01 because the year input is ignored and the current year is assumed.

  7. The first and last week in a month might include days from neighboring months. For example, Monday 31st July 2006 can be expressed as Monday in week one of August 2006, which is 2006 08 1 Monday using format string yyyy MM W EEEE.
  8. 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 2006, yy produces 06.
    • 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.
  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 comply with the ISO8601:2000 'Representation of dates and times' standard, consider using the formatting symbols I and T, which match the following subset of the ISO8601 standard.

Use these symbols only on their own.

The following table shows how the output form relates to the logical data type.

Logical MRM data type Logical ESQL data type 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 indicate a zero time difference from Coordinated Universal Time (UTC), but on output they always generate '+00:00'. If you want 'Z' to always be generated on output, use the IU or TU formatting symbols instead.
  • ZZZ always outputs '+00:00' to indicate a zero time difference from Coordinated Universal Time (UTC). If you want 'Z' to always be generated on output, use ZZZU 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, the UTC format is preserved in the output message and overrides the format that is 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" 2006.07.10 at 15:08:56 -05:00
"EEE, MMM d, "yy" Wed, July 10, '06
"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
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:23:12

ad09291_ This topic's URL is: