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:

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	Heisei (`X'0E458D45BA0F'`) Showa (`X'0E45B3457A0F'`) Taisho (`X'0E455B45770F'`) Meiji (`X'0E45A645840F'`)	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 `M`s.
`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, `W`s 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 `W`s.
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

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-999 (01 = 1989)

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 ]