Format of arguments and return values for date and time intrinsic functions
The descriptions of intrinsic functions that process dates and times refer to the following different types of date and time related values:
Integer date form
Standard date form
- YYYY represents the year in the Gregorian calendar. It must be an integer greater than 1600 but not greater than 9999.
- MM represents a month and must be a positive integer less than 13.
- DD represents a day and must be a positive integer less than 32 if it is valid for the specified month and year combination.
Julian date form
- YYYY represents the year in the Gregorian calendar. It must be an integer greater than 1600 but not greater than 9999.
- DDD represents the day of the year. It must be a positive integer less than 367 if it is valid for the year specified.
UTC offset value
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. If the specified format literal is alphanumeric,
the result of the function will be an alphanumeric value; if the specified
format literal is national, the result of the function will be a national
value; and if the format literal is UTF-8, the result of the function
will be a UTF-8 value.
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.
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 | 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 | Format literals |
---|---|
Basic local time | hhmmss.ssss |
Extended local time | hh:mm:ss.ssss |
Basic UTC time | hhmmss.ssssZ |
Extended UTC time | hh:mm:ss.ssssZ |
Basic offset time | hhmmss.ssss+hhmm |
Extended offset time | hh:mm:ss.ssss+hh:mm |
A basic combined date and time format consists of a basic date format followed by an uppercase "T" character and a basic time format. For example, "YYYYMMDDThhmmss.sss+hmm".
An extended combined date and time format consists of an extended date format, followed by an uppercase "T" character and an extended time format. For example, "YYYY-MM-DDThh:mm:ss.sssss+hh:mm".
Combinations of basic date formats with extended time formats, or of extended date formats with basic time formats, are not allowed.
The uppercase "T" character that occurs in both basic and extended combined and time formats, which separates the date format portion from the time format portion, appears in the data associated with the format.
- Characters "YYYY" represent the year subfield. Data associated with this subfield must have a value greater than 1600 and less than or equal to 9999.
- Characters "MM" represent the month-of-year subfield. Data associated with this subfield must have a value between 01 and 12.
- Characters "DD" in calendar date formats represent the day-of-month subfield. Data associated with this subfield must have a value between 01 and 28, 29, 30, or 31, depending on the month subfield and year subfield of the data.
- Characters “DDD” in ordinal date formats represent the day-of-year subfield. For a leap year, the data associated with this subfield must have a value between 001 and 366, and between 001 and 365 otherwise.
- Characters “ww” in week date formats represent the week-of-year subfield. Data associated with this subfield must have a value between 01 and 52.
- Character “D” in week date formats represents the day-of-week subfield. Data associated with this subfield must have a value between 1 and 7.
- Character “W” in week date formats appears in associated data values as is at the same location indicated in the corresponding format literal.
- Character “-” in all extended date formats appears in associated data values as is at the same location indicated in the corresponding format literal.
- Characters “hh” represent the hours subfield. Data associated with this subfield must have a value between 00 and 23.
- Characters “mm” represent the minutes subfield. Data associated with this subfield must have a value between 00 and 59.
- Characters “ss” represent the seconds subfield. Data associated with this subfield must have a value between 00 and 59.
- In fractional seconds time formats, the fractional seconds subfield is introduced with a "." character and the rest of the subfield consists of a minimum of 1 and a maximum of 9 “s" characters. In data associated with this subfield, the "." character appears as is, and corresponding to each "s" character is a number between 0 and 9.
- In offset time formats, the "+" character introduces the "offset from UTC" subformat, which consists of characters "hh", representing the offset-hours subfield, followed by character ":" (extended time formats only), followed by characters "mm", representing the offset-minutes subfield.
- In data associated with the "offset from UTC" subformat:
- A "+" character appears at the same location as the "+" character in the format literal when the time portion of the data is adjusted downward by the offset values to represent UTC.
- A "-" character appears at the same location as the "+" character in the format literal when the time portion of the data is adjusted upward by the offset values to represent UTC.
- A "0" character appears at the same location as the "+" character in the format literal when offset from UTC is not available on the system.
- Data for the offset-hours subfield must have a value between 00 and 23 when offset from UTC is available on the system, and must have a value of 00 otherwise.
- Data for the offset-minutes subfield must have a value between 00 and 59 when offset from UTC is available on the system, and must have a value of 00 otherwise.
- In UTC time formats, the last character is "Z", which indicates a UTC time. In data associated with the UTC time formats, the "Z" character appears as is at the end of the data value.
- Character ":" in all extended time formats appears in associated data values as is at the same location indicated in the corresponding format literal.
Example 1
FORMATTED-CURRENT-DATE
intrinsic
function and the format literal specified for its argument.DISPLAY FUNCTION FORMATTED-CURRENT-DATE(‘YYYY-MM-DDThh:mm:ss.ss+hh:mm’)
2020-10-28T01:11:36.13-04:00
Example 2
SECONDS-FROM-FORMATTED-TIME
intrinsic
function demonstrates a combined date and time format literal and
corresponding value that is in the format indicated by the literal.01 SEC COMP-2.
:
COMPUTE SEC = FUNCTION SECONDS-FROM-FORMATTED-TIME(
‘YYYY-MM-DDThh:mm:ss.ss’,
‘1987-12-26T00:45:23.06’)
DISPLAY SEC
.27230599999999999E 04