Convert Date to Lilian Format (CEEDAYS) API
Required Parameter Group:
1 | input_char_date | Input | VSTRING |
2 | picture_string | Input | VSTRING |
3 | output_Lilian_date | Output | INT4 |
Omissible Parameter:
4 | fc | Output | FEEDBACK |
Service Program Name: QLEAWI
Default Public Authority: *USE
Threadsafe: Yes
The Convert Date to Lilian Format (CEEDAYS) API converts a string representing a date into a number representing the number of days since 14 October 1582. This API makes it easier to do calculations such as the number of days between two dates.
Authorities and Locks
None.
Required Parameter Group
- input_char_date (input by descriptor)
- A character string representing a date or timestamp in the format shown by
picture_string. Field width is 5 to 255 characters.
Input-char-date can contain leading or trailing blanks. Parsing for a
date begins with the first non-blank character unless the picture string
contains leading blanks, in which case CEEDAYS skips exactly that many
positions before parsing begins. After a valid date is parsed, remaining
characters are ignored. Valid dates are in the range 15 October 1582 to 31
December 9999.
- picture_string (input by descriptor)
- A character string indicating the format of the date value in
input_char_date, for example MM/DD/YY. Each character in
picture_string represents a character in input_char_date. If
delimiters such as the slash (/) appear in the picture string,
then leading zeros can be omitted. For example:
CALL CEEDAYS('6/2/88' , 'MM/DD/YY', lildate, fc); CALL CEEDAYS('06/02/88', 'MM/DD/YY', lildate, fc); CALL CEEDAYS('060288' , 'MMDDYY' , lildate, fc); CALL CEEDAYS('88154' , 'YYDDD' , lildate, fc);
would all assign the same value to variable lildate. If any time characters are included, for example HH:MI:SS YY/MM/DD, they count as place holders but are otherwise ignored.Picture Characters Used in Picture Strings contains a list of valid picture characters, and Examples of Picture Strings Recognized by ILE Date and Time APIs has examples of valid picture strings.
If picture_string is null or blank, CEEDAYS obtains picture_string based on the current job value for the country or region ID (CNTRYID). For example, if the current value for CNTRYID is US (United States), the date format is MM/DD/YY. If the current job value for CNTRYID is FR (France), the date format is DD.MM.YYYY.
This default mechanism makes it easy for translators to specify the preferred date format, and also easy for application programs and library procedures to automatically use this format.
- output_Lilian_date (output)
- A 32-bit binary integer representing the Lilian date, which is the number of days since 14 October 1582. For example, 16 May 1988 is day number 148 138. If input_char_date does not contain a valid date, output_Lilian_date is set to 0 and CEEDAYS ends with a nonzero feedback code.
Omissible Parameter
- fc (output)
- A 12-byte feedback code passed by reference. If specified as an argument, feedback information (a condition token) is returned to the calling procedure. If not specified and the requested operation was not successfully completed, the condition is signaled to the condition manager.
Feedback Codes and Conditions
CEE0000 | The API completed successfully |
Severity: 00 | |
CEE0501 | The operational descriptor data type is not valid |
Severity: 30 | |
CEE0502 | Missing operational descriptor |
Severity: 30 | |
CEE2507 | Insufficient data provided |
Severity: 30 | |
CEE2508 | The value for day is not valid |
Severity: 30 | |
CEE2509 | The value for era is not valid |
Severity: 30 | |
CEE2513 | The value for Lilian date is not valid |
Severity: 30 | |
CEE2517 | The value for month is not valid |
Severity: 30 | |
CEE2518 | The picture string specification is not valid |
Severity: 30 | |
CEE2521 | The value for year is not valid |
Severity: 30 | |
CEE9902 | Unexpected user error occurred in &1 |
Severity: 30 |
Usage Notes
-
The inverse of CEEDAYS is CEEDATE. The CEEDATE API converts a date in the Lilian format to character format.
-
Date calculations can be performed easily on the output_Lilian_date, because it is an integer. Leap year and end-of-year anomalies are avoided.
-
See Set Century (CEESCEN) API and Query Century (CEEQCEN) API for information about 2-digit years.
-
If picture_string includes a Japanese era symbol <JJJJ>, the YY position in input_char_date is assumed to contain the year within Japanese era. Examples of Picture Strings Recognized by ILE Date and Time APIs has an example. Japanese Eras Used by ILE Date and Time APIs When <JJJJ> Specified contains a list of the Japanese eras recognized by CEEDAYS.
- If picture_string includes a Republic of China (ROC) era symbol <CCCC> or <CCCCCCCC>, the YY position in input_char_date is assumed to contain the year within ROC era. Examples of Picture Strings Recognized by ILE Date and Time APIs has an example. Republic of China Eras Used by ILE Date and Time APIs When <CCCC> or <CCCCCCCC> Specified contains a list of the ROC eras recognized by CEEDAYS. The coding of YYY or ZYY without including one of the era symbols is a picture string specification error.
Picture Characters Used in Picture Strings
Picture Characters | Explanation | Valid Values | Notes |
---|---|---|---|
Y YY YYY ZYY YYYY |
1-digit year 2-digit year 3-digit year 3-digit year within era 4-digit year |
0-9 00-99 000-999 1-999 1582-9999 |
Y valid for output only. YY implies the years xx00-xx99. (The years are dependent on the century start value and the system date.) YYY or ZYY used with <JJJJ>, <CCCC>, and <CCCCCCCC>. |
<JJJJ> | Japanese era name in DBCS characters |
|
Affects YY field: if <JJJJ> specified, YY means the year within Japanese era. For example, 1988 = Showa 63. See example in Examples of Picture Strings Recognized by ILE Date and Time APIs. |
<CCCC> <CCCCCCCC> |
Republic of China (ROC) era name in DBCS characters |
MinKow (X'0E4D8256CE0F') ChuHwaMinKow (X'0E4C845ADD4D8256CE0F') |
Affects YY field: if <CCCC> specified, YY means the year within ROC era. For example, 1988 = Minkow 77. See example in Examples of Picture Strings Recognized by ILE Date and Time APIs. |
MM ZM |
2-digit month 1- or 2-digit month |
01-12 1-12 |
For output, leading zero suppressed. For input, ZM treated as MM. |
RRRR RRRZ |
Roman numeral month | I-XII (Left-justified) | For input, source string is folded to uppercase. For output, uppercase only. I=Jan, II=Feb, ..., XII=Dec. |
MMM Mmm MMMMMMMMMM Mmmmmmmmmm MMMMMMMMMZ Mmmmmmmmmz |
3-char month, uppercase 3-char month, mixed case 20-char month, uppercase 20-char month, mixed case trailing blanks suppressed trailing blanks suppressed |
JAN-DEC Jan-Dec JANUARY -DECEMBER January -December JANUARY-DECEMBER January-December |
For input, source string always folded to uppercase. For output, M generates uppercase and m generates lowercase. Output is padded with blanks ( ) (unless Z specified) or truncated to match the number of Ms. |
DD ZD DDD |
2-digit day of month 1- or 2-digit day of month day of year (Julian day) |
01-31 1-31 001-366 |
For output, leading zero suppressed. For input, ZD and DD are equivalent. That is, each accepts the format of the other. |
HH ZH |
2-digit hour 1- or 2-digit hour |
00-23 0-23 |
For output, leading zero suppressed. For input, ZH and HH are equivalent. That is, each accepts the format of the other. If AP is specified, valid values are 01-12. |
MI | minute | 00-59 | |
SS | second | 00-59 | |
9 99 999 |
tenths of a second hundredths of a second thousandths of a second |
0-9 00-99 000-999 |
No rounding. |
AP ap A.P. a.p. |
AM/PM indicator |
AM or PM am or pm A.M. or P.M. |
AP affects HH/ZH field. For input, source string always folded to uppercase. For output, AP generates uppercase and ap generates lowercase. |
W WWW Www WWWWWWWWWW Wwwwwwwwww WWWWWWWWWZ Wwwwwwwwwz |
1-char day-of-week 3-char day, uppercase 3-char day, mixed case 10-char day, uppercase 10-char day, mixed case trailing blanks suppressed trailing blanks suppressed |
S, M, T, W, T, F, S SUN-SAT Sun-Sat SUNDAY -SATURDAY Sunday -Saturday SUNDAY-SATURDAY Sunday-Saturday |
For input, Ws are ignored. For output, W generates uppercase and w generates lowercase. Output padded with blanks (unless Z specified) or truncated to match the number of Ws. |
All others, not including numbers 0 through 9 and any characters used in the month or day-of-week names. | delimiters | X'01'-X'FF'(X'00' reserved for ILE use.) | For input, treated as delimiters between the month, day, year, hour, minute, second, and fraction of a second. For output, copied exactly as is to the target string. |
Examples of Picture Strings Recognized by ILE Date and Time APIs
Picture String | Example | Notes |
---|---|---|
YYMMDD YYYYMMDD YYYY-MM-DD <JJJJ> YY.MM.DD <CCCC> YY.MM.DD |
880516 19880516 1988-05-16 Showa 63.05.16 MinKow 77.05.16 |
1988-5-16 would also be valid input. Showa is a Japanese era name. Showa 63 = 1988. MinKow is an ROC era name. MinKow 77 = 1988. |
MMDDYY MM/DD/YY ZM/ZD/YY MM/DD/YY MM/DD/Y |
050688 05/06/88 5/6/88 05/06/1988 05/06/8 |
1-digit year format (Y) valid for output only |
DD.MM.YY DD-RRRR-YY DD MMM YY DD Mmmmmmmmmm YY ZD Mmmmmmmmmz YY Mmmmmmmmmz ZD, YYYY ZDMMMMMMMMZYY |
09.06.88 09- VI-88 09 JUN 88 09 June 88 9 June 88 June 9, 1988 9JUNE88 |
Z suppresses zeros and blanks |
YY.DDD YYDDD YYYY/DDD |
88.137 88137 1988/137 |
Julian date |
YYMMDDHHMISS YYYYMMDDHHMISS YYYY-MM-DD HH:MI:SS.999 WWW, ZM/ZD/YY HH:MI AP Wwwwwwwwwz, DD Mmm YYYY, ZH:MI AP |
880516204229 19880516204229 1988-05-16 20:42:29.046 MON, 5/16/88 08:42 PM Monday, 16 May 1988, 8:42 PM |
Timestamp -- valid only for CEESECS and CEEDATM. If used with CEEDATE, time positions are left blank. If used with CEEDAYS, HH, MI, SS, and 999 fields are ignored. |
Japanese Eras Used by ILE Date and Time APIs When <JJJJ> Specified
![Start of change](delta.gif)
First date of Japanese Era | Era Name | Era Name in IBM® Japanese DBCS Code | Valid Year (YY, ZYY) Values |
---|---|---|---|
1868-09-08 | Meiji | X'0E45A645840F' | 01-45 |
1912-07-30 | Taisho | X'0E455B45770F' | 01-15 |
1926-12-25 | Showa | X'0E45B3457A0F' | 01-64 |
1989-01-08 | Heisei | X'0E458D45BA0F' | 01-31 |
2019-05-01 | Reiwa | X'0E49C3457A0F' | 01-999 (01 = 2019) |
![End of change](deltaend.gif)
Republic of China Eras Used by ILE Date and Time APIs When <CCCC> or <CCCCCCCC> Specified
First date of ROC Era | Era Name | Era Name in Traditional Chinese DBCS Code | Valid Year (YY, ZYY) Values |
---|---|---|---|
1912-01-01 | MinKow | X'0E4D8256CE0F' | 01-999 (77 = 1988) |
ChuHwaMinKow | X'0E4C845ADD4D8256CE0F' |
Example
-
Convert a date to the Lilian format to calculate the date 60 days hence:
CALL CEEDAYS ('880516','YYMMDD', ndays, fc); ndays = ndays + 60; CALL CEEDATE (ndays, 'YYMMDD', newdate, fc);
API introduced: V2R3
[ Back to top | ILE CEE APIs | APIs by category ]