Date and Time Formats

For functions FORMATTED-CURRENT-DATE , FORMATTED-DATE , FORMATTED-TIME , and FORMATTED-DATETIME , the format literal argument indicates the format of the date or time value that is the result of the function. The result of the function will have the same type as its format literal, which can be alphanumeric, national or UTF-8.

For functions INTEGER-OF-FORMATTED-DATE , SECONDS-FROM-FORMATTED-TIME , and TEST-FORMATTED-DATETIME , the format literal indicates the format of the date or time value specified as the second argument of the function.

The permissible format strings are listed as follows. For a full description of each subfield in the format literals, including a range of permissible values in data associated with the formats, see the Value meanings and limits section.

Integer date form

A value in integer date form is a positive integer that represents the number of days since 31 December, 1600 in the Gregorian calendar. It must be greater than zero and less than or equal to the value of FUNCTION INTEGER-OF-DATE (99991231), which is 3,067,671.

Note: The INTDATE Compiler directive can affect the starting date of the integer date functions.

Standard date form

A value in standard date form is an integer of the form YYYYMMDD, calculated using (YYYY * 10,000) + (MM * 100) + DD, where:

YYYY represents the year in the Gregorian calendar. It must be an integer in the range [1601, 9999].
MM represents a month and must be an integer in the range [01, 12].
DD represents a day and must be an integer in the range [01, 31], valid for the specified month and year combination.

Julian date form

A value in Julian date form is an integer of the form YYYYDDD, calculated using (YYYY * 1000) + DDD, where:

YYYY represents the year in the Gregorian calendar. It must be an integer in the range [1601, 9999].
DDD represents the day of the year. It must be a positive integer in the range [1, 366], valid for the year specified.

UTC offset value

A UTC offset value is an integer representation of offset from UTC (Coordinated Universal Time) expressed in minutes. The value must be greater than or equal to -1439 and less than or equal to 1439.

Note: The offset value 1439 represents 23 hours 59 minutes, which is one minute less than a day.

Standard numeric time form

A value in standard numeric time form is a numeric value representing seconds past midnight. The value must be greater than or equal to zero and less than 86,400

Date and time formats

For functions FORMATTED-CURRENT-DATE, FORMATTED-DATE, FORMATTED-TIME, and FORMATTED-DATETIME, the format literal argument indicates the format of the date or time value that is the result of the function. The result of the function will have the same type as its format literal, which can be alphanumeric, national or UTF-8.

For functions INTEGER-OF-FORMATTED-DATE, SECONDS-FROM-FORMATTED-TIME, and TEST-FORMATTED-DATETIME, the format literal indicates the format of the date or time value specified as the second argument of the function.

The permissible format strings are listed as follows. For a full description of each subfield in the format literals, including a range of permissible values in data associated with the formats, see Value meanings and limits.

Date formats	Format literals
Basic calendar date	YYYYMMDD
Extended calendar date	YYYY-MM-DD
Basic ordinal date	YYYYDDD
Extended ordinal date	YYYY-DDD
Basic week date	YYYYWwwD
Extended week date	YYYY-Www-D

Integer-seconds time formats

Integer-seconds time formats	Format literals
Basic local time	hhmmss
Extended local time	hh:mm:ss
Basic Coordinated Universal Time (UTC)	hhmmssZ
Extended UTC time	hh:mm:ssZ
Basic offset time	hhmmss+hhmm
Extended offset time	hh:mm:ss+hh:mm

Fractional-seconds time formats

Fractional-seconds time formats	Format literals
Basic local time	hhmmss.ssss
Extended local time	hh:mm:ss.ssss
Basic Coordinated Universal Time (UTC)	hhmmss.ssssZ
Extended UTC time	hh:mm:ss.ssssZ
Basic offset time	hhmmss.ssss+hhmm
Extended offset time	hh:mm:ss.ssss+hh:mm

Note: The period is used as the decimal separator, and four "s" characters after the period are used for illustrative purposes. The number of "s" characters that might be specified after the decimal separator in these formats might range from 1 to 9.

Combined date and time formats

You can combine the date and time formats by concatenating them with an uppercase T. This character also appears at the same place in data associated with the format.

When specifying basic date formats, you can only combine them with the basic time formats, and conversely, you can only combine extended date formats with extended time formats. You cannot mix the two types.

Value meanings and limits

The permissible date and time formats have the following meanings and limits:

Format	Meaning and limits
YYYY	Year, 1601-9999
MM	Month, 01-12
DD	Day of month, 01-{28\|29\|30\|31} dependent on month sub-field
DDD	Day of year for ordinal date formats, 001-365\|366
ww	Week of year, 01-53
D	Day of week, 1-7
W
-
hh	Hours, 00-23
mm	Minutes, 00-59
ss	Seconds, 00-59
.s	Fractional seconds, always prefixed with '.' then 1-9 's'
+\|-hh:mm	UTC offset hours (extended times only), the offset can be adjusted upward (by a '+' prefix) or downward (by a - prefix). A prefix of 0 (zero) indicates that an offset of UTC is not available on the system.
Z	UTC time indicator