DATETIME / DATETIME-TZ Format Specification¶

This specification defines the valid format strings for DATETIME and DATETIME-TZ in OE.

Parsing and formatting rules using these formats will be covered in separate specifications.

DATETIME / DATETIME-TZ Format Structure¶

Both DATETIME and DATETIME-TZ use the same format syntax:

1. Date part (not covered in this document)
2. Time part: HH:MM:SS.SSS
3. Timezone offset part: +HH:MM

All parts (time and timezone offset) are optional, but components must be specified in order — you cannot omit an earlier part while including a later one (e.g., you cannot have minutes without hours, or seconds without minutes).

Placeholder characters are case-insensitive (H ≡ h, M ≡ m, etc.).

Note:
Any number of trailing spaces is allowed after the format. These spaces are ignored during formatting and stripped when the format is set in FILL-IN widgets.

Time Part¶

The time part immediately follows the date part and is separated by any number (one or more) of spaces.

It consists of up to five components, in this exact order:

1. Hours: one or more H or h characters
2. Minutes: one or more M or m characters
3. Seconds: one or more S or s characters
4. Milliseconds: one or more S or s characters after a dot
5. AM: either AM or just A for ante meridiem / post meridiem

Rules:

- Hours, minutes, and seconds must be separated by exactly one colon (:).
- Seconds and milliseconds must be separated by exactly one dot (.).
- Trailing separators (colons or dots) are allowed (e.g., HH: or HH:MM:SS.).
- AM must be separated by one or more spaces.

Valid time part examples:

• HH:MM:SS.SSS — full default time format
• HH:MM — hours and minutes only
• H — minimal one-digit hours (no minutes/seconds/ms)
• HH — two-digit hours only
• HH: — two-digit hours with trailing colon
• H:MM — one-digit hours + two-digit minutes
• HHH — three-digit hours
• HHH: — three-digit hours + trailing colon
• HHH:M — three-digit hours + one-digit minutes
• HHH:MM — three-digit hours + two-digit minutes
• HHHHHH:MMMMM:SSSS.S — extreme width

Timezone Offset Part¶

The timezone offset immediately follows the time part (no spaces allowed) and consists of:

- A sign: + or -
- Hours: one or more H or h characters
- A colon (:)
- Minutes: one or more M or m characters

Examples:

• +HH:MM — standard offset
• -HH:MM — standard offset (same as plus?)
• +H:M — minimal one-digit hours/minutes
• +HH: — hours only (trailing colon allowed)
• +HHHHH:MMMMMMM — extreme width (allowed but unusual)

Limited Number of S Characters Rule¶

The format cannot contain more than 5 S characters in total (counted across all parts of the format).
If exceeded, error 14312 is raised: Too many 'S' characters in format "F".

This check occurs before the format structure is fully verified.

Examples of invalid formats (raise error 14312):

• 99/99/9999 HH:MM:SSSSSS
• 99/99/9999 HH:MM:SSSS.SS
• 99/99/9999 HH:MM:SSS+HH:MMSSS
• 99/99/9999 SSSSHH:MM:SS+HH:MM
• 99/99/9999 SSHH:MSSM:SS+HH:MM

Default Formats¶

Default format for DATETIME:

99/99/9999 HH:MM:SS.SSS

Default format for DATETIME-TZ:

99/99/9999 HH:MM:SS.SSS+HH:MM

Below is an updated specification:

DATETIME and DATETIME-TZ Format Specification¶

This document defines the rules for the time part, AM/PM indicator, and timezone offset of datetime and datetime-tz format strings.

The format string begins with a mandatory date part (whose exact rules are defined in a separate document), followed by optional elements described below.

Global Restriction on 's' and 'S'¶

Before any other validation is performed, the system counts all occurrences of the letters s and S anywhere in the entire format string (including the date part).

If the total number of s and S characters exceeds five, the format is rejected immediately with an error (OE error 14312).

This check is performed even if some s/S characters appear in invalid positions. The count is global.

Time Part (including optional AM/PM indicator)¶

The time part is optional. When present, it must immediately follow the date part and be introduced by exactly one of the following delimiters (they are mutually exclusive):

• a single t or T
• one or more spaces (but no t/T in this case)

The time part may have any of the following forms (all letters are case-insensitive):

• one or more h or H (hours only)
• one or more h/H followed by : (hours with trailing colon)
• one or more h/H : one or more m/M (hours and minutes)
• one or more h/H : one or more m/M : (hours, minutes, trailing colon)
• one or more h/H : one or more m/M : one or more s/S
  (hours, minutes, seconds)
• one or more h/H : one or more m/M : one or more s/S .
  (hours, minutes, seconds, trailing dot)
• one or more h/H : one or more m/M : one or more s/S . one or more s/S
  (hours, minutes, seconds, followed by 1 or more fractional-second digits)

Each component — hours (h/H), minutes (m/M), seconds (s/S), and fractional seconds (s/S after the dot) — may consist of one or more consecutive identical letters.

Optional AM/PM indicator (part of the time part)¶

After the above time specification, an optional AM/PM indicator may appear.

It must be preceded by one or more spaces and consists of:

• A or a followed by exactly one M or m (in any case combination: "AM", "Am", "aM", or "am") → complete form
• A or a alone → incomplete form

The AM/PM indicator is considered part of the time part and may appear at the very end of the format string if no timezone offset follows.

No spaces are allowed after the AM/PM indicator.

Trailing delimiters and separators¶

A trailing time delimiter (t, T, or spaces), a trailing colon (:), or a trailing dot (.) is permitted only if it is at the very end of the entire format string.

Timezone Offset¶

A timezone offset, when present, must appear immediately after the time part (which may include an AM/PM indicator) with no intervening spaces and must be at the very end of the format string.

It is introduced by a sign (+ or -) and follows a structure analogous to a minimal time part:

• one or more h or H (hours only)
• one or more h/H followed by : (hours with trailing colon)
• one or more h/H : one or more m/M (hours and minutes)

Each component consists of one or more consecutive identical letters.

No seconds, fractional seconds, or further separators are allowed.

Restrictions on timezone usage¶

A timezone offset is forbidden when either of the following is true:

• There is an incomplete AM/PM indicator (only A or a present)
• There is no AM/PM indicator and the time part does not contain minutes

Consequently, a timezone offset is permitted in these cases:

• Time part has minutes and no AM/PM indicator
• Time part has complete AM/PM indicator (any case combination)

No characters are allowed after a complete timezone offset.

Valid Examples (time-related portion only)¶

• thhhh:mmmm
• HHHHH:MMMMMM:SSSSSS.SSSSS
• t
• hhhhh:
• HHH:MMM:SSS.
• hh:mmmm AM
• hh:mmmm Am
• hhhh:mmmm:ssss+hhhhh:mmmmm
• thhh:mmm+hhh:mm (no AM/PM, minutes present → allowed)
• thhh:mmm Am+hhh:mm (complete AM/PM → allowed)
• thhh:mmm A (incomplete AM/PM → forbidden timezone)

Invalid Examples¶

More than 5 s/S total (complete format):

• 9999s9999 HH:MM:SSSSS
• 99/99/9999 HH:MM:SSSSSS
• 99/99/9999 HH:MM:[SSSS.SS]
• 99/99/9999 HH:MM:SSS+HH:MMSSS
• 99/99/9999 SSSSHH:MM:SS+HH:MM
• 99/99/9999 SSHH:MSSM:SS+HH:MM

Time-related portion only:

• t hhhh:mmmm (both t and space delimiter)
• +hhh:mm (timezone without the time part)
• thhh A+hhh:mm (timezone after incomplete AM/PM)
• thhhh+hhh:mm (timezone, no minutes in time part, no AM/PM)
• thhh:mmm +hhh:mm (space before timezone sign)
• thhh:mmm Am +hhh:mm (space after AM/PM)
• HHH:MMM:SSS+hhh:mm extra (content after timezone)
• HHH:MMM:SSS. extra (content after trailing dot)