Convert Date to Lilian Format (CEEDAYS) API

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

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 on 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

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

Heisei
(X'0E458D45BA0F')
Showa
(X'0E45B3457A0F')
Taisho
(X'0E455B45770F')
Meiji
(X'0E45A645840F')

<CCCC>
<CCCCCCCC>

MinKow
(X'0E4D8256CE0F')
ChuHwaMinKow
(X'0E4C845ADD4D8256CE0F')

MM
ZM

2-digit month
1- or 2-digit month

01-12
1-12

RRRR
RRRZ

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

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

HH
ZH

2-digit hour
1- or 2-digit hour

00-23
0-23

9
99
999

tenths of a second
hundredths of a second
thousandths of a second

0-9
00-99
000-999

AP
ap
A.P.
a.p.

AM or PM
am or pm
A.M. or P.M.

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

Examples of Picture Strings Recognized by ILE Date and Time APIs

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

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

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

YY.DDD
YYDDD
YYYY/DDD

88.137
88137
1988/137

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

Japanese Eras Used by ILE Date and Time APIs When <JJJJ> Specified

Republic of China Eras Used by ILE Date and Time APIs When <CCCC> or <CCCCCCCC> Specified

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);