DateTime as STRING data

If the dateTime object is CWF Packed Decimal, you can only use the symbols that are presented as numbers. For all other Physical Type options, you can use all symbols.

You can specify the dateTime format using a string of pattern letters. The count of pattern letters determines the format. The table of dateTime formatting symbols below defines the letters that are reserved as pattern letters:

Symbol Meaning Presentation Example
a am or pm marker Text pm
d day in month Number 10
D day in year Number 189
e day in week (1-7) Number 2
E day in week Text Tuesday
F day of week in month Number 2 (2nd Wed in July)3
G Era Text AD
h hour in am or pm (1-12) Number 12
H hour in day (0-24) Number 0
I Parse as Date/Time (ISO8601)   (note 6)
k hour in day (1-24) Number 24
K hour in am or pm (0-11) Number 0
m minute in hour Number 30
M month in year Text and Number July and 07
w week in year Number 272
W week in month Number 2
s second in minute Number 55
S millisecond Number 978
T Parse as Time (ISO8601)   (note 6)
y year Number 19961
Y year: use with week in year only Number 19962
z TimeZone Text zzzz = Pacific Standard Time
Z time zone Text +05:30
' escape for text   'User text'
'' 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 CWF message set property of Century Window is used to determine the century. For example, if Century Window is set to 53, year 97 is 1997, year 52 is 2052, and year 53 is 1953.
  2. The first day of a year does not usually fall on a week boundary, therefore dates expressed using week in year might refer to dates in neighboring years. For example, day 1 of week 1 in 2002 (2002 01 Monday) using format string YYYY ww EEEE is in fact 31st December 2001. 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:

    • day 1 of week 1 in 2002 using format string YYYY ww EEEE is correctly interpreted as 31st December 2001
    • day 1 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 2002-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. You can only express a time zone as an offset in hours and minutes from GMT ( +/-hh:mm ). The number of Z formatting symbols affects the output:
    • -Z (short form) produces -5
    • -ZZ (medium form) produces -05
    • -ZZZ (long form) produces -05:00
    • -ZZZZ (long form) produces GMT-05:00
  6. Start of change

    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:

    • The restricted profile as proposed by the W3C at http://www.w3.org/TR/NOTE-datetime
    • Truncated representations of calendar dates as specified in section 5.2.1.3 of ISO8601:2000
      • Basic format (sub-sections c, e and f)
      • Extended format (sub-sections a, b and d)

    These symbols should only be used on their own.

    • The I formatting symbol matches any dateTime string conforming to the supported subset.
    • The T formatting symbol matches any dateTime string conforming to the supported subset that consists of a time portion only.

    On output from a message flow, the dateTime is always expressed in the fullest form yyyy-MM-dd'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.
    End of change

Examples

The following table shows 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

The following are ISO8601 dateTime examples:

Year
   yyyy
Year and month
   yyyy-MM
Complete date
   yyyy-MM-dd
Complete date plus hours and minutes
   yyyy-MM-ddTHH:mm
Complete date plus hours, minutes, and seconds
   yyyy-MM-ddTHH:mm:ss
Complete date plus hours, minutes, seconds, and a decimal fraction of a second
   yyyy-MM-ddTHH:mm:ss.S

You can create formatting strings that produce unpredictable results, so you must use these symbols with care. For example, if you specify dMyyyy, it is impossible to distinguish between day, month, and year. dMyyyy tells the broker that a minimum of one character represents the day, a minimum of one character represents the month, and four characters represent the year. Therefore 3111999 could be interpreted as 3/11/1999 and 31/1/1999.