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:
A description of each of these values, including a range
of permissible values, is given as follows.
Note: The definitions are
intended to be consistent with ISO 8601 Data elements and interchange
formats – Information interchange – Representation of
dates and times.
Integer date form
A value
in integer date form is a positive integer that represents a number
of days succeeding 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
option affects the starting date of the integer date functions. For
details, see INTDATE in
the Enterprise COBOL Programming Guide.
Standard date form
A value
in standard date form is an integer of the form YYYYMMDD, whose value
is obtained from the calculation (YYYY * 10,000) + (MM * 100) + DD,
where:
- 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
A value
in Julian date form is an integer of the form YYYYDDD whose value
is obtained from the calculation (YYYY * 1000) + DDD, where:
- 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
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. 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.
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 Meaning
of date and time format subfields and permissible values of associated
data section.
| 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 |
Note: In Table 3, 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
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.
Meaning of date and time format subfields and permissible
values of associated data
For date formats:
- 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.
For time formats:
- 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.
Examples
Example 1
The
following example demonstrates the correspondence between the value
returned by the
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’)
The output is:
2020-10-28T01:11:36.13-04:00Example 2
The following example involving a call to the
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
The output is:
.27230599999999999E 04