Convert Timestamp to Number of Seconds (CEESECS) API
Required Parameter Group:
1 | input_timestamp | Input | VSTRING |
2 | picture_string | Input | VSTRING |
3 | output_seconds | Output | FLOAT8 |
Omissible Parameter:
4 | fc | Output | FEEDBACK |
Service Program Name: QLEAWI
Default Public Authority: *USE
Threadsafe: Yes
The Convert Timestamp to Number of Seconds (CEESECS) API converts a string representing a timestamp into a number representing the number of seconds since 00:00:00 14 October 1582. This API makes it easier to do time calculations, such as the elapsed time between two timestamps.
Authorities and Locks
None.
Required Parameter Group
- input_timestamp (input by descriptor)
- A character string representing a date or timestamp in the format shown by
picture_string. The field width is 5 through 255 characters.
Input-timestamp may contain leading or trailing blanks. After
a valid date or timestamp is parsed, remaining characters are ignored. Valid
dates are in the range 15 October 1582 to 31 December 9999. A full date must be
specified. Valid times are in the range 00:00:00.000 to 23:59:59.999.
If any part or all of the time value is omitted, zeros are substituted for the remaining values. For example,
1988-05-17-19:02 is equivalent to 1988-05-17-19:02:00 1988-05-17 is equivalent to 1988-05-17-00:00:00
- picture_string (input by descriptor)
- A character string indicating the format of the date or timestamp value in
input_timestamp, for example
YY/MM/DD HH.MI.SS.
Each character in picture_string represents a character in input_timestamp. If delimiters such as the slash (/) appear in the picture string, leading zeros may be omitted. For example, these calls assign the same value to the variable secs.CALL CEESECS('88/06/03 15.35.03', 'YY/MM/DD HH.MI.SS', secs, fc); CALL CEESECS('88/6/3 15.35.03' , 'YY/MM/DD HH.MI.SS', secs, fc); CALL CEESECS('88/6/3 3.35.03 PM', 'YY/MM/DD HH.MI.SS AP', secs, fc); CALL CEESECS('88.155 3.35.03 pm', 'YY.DDD HH.MI.SS AP', secs, fc);
See Picture Characters Used in Picture Strings for a list of valid picture characters, and Examples of Picture Strings Recognized by ILE Date and Time APIs for examples of valid picture strings.
If picture_string is null or blank, CEESECS obtains picture_string based on the current job value for the country or region ID (CNTRYID). For example, if the current job value for CNTRYID is US (United States), the date format is MM/DD/YYYY. If the current job value for CNTRYID is FR (France), the date format is DD.MM.YYYY.
This default mechanism makes it easy not only for translators to specify the preferred date format, but also for application programs and library routines to automatically use this format.
- output_seconds (output)
- A 64-bit double floating-point number representing the number of seconds
since 00:00:00 on 14 October 1582. For example, 00:00:01 on 15 October 1582 is
second 86 401 (24*60*60 + 01). 19:00:01.12 on 16 May 1988 is second
12 799 191 601.12. The largest value that can be represented is
23:59:59.999 on 31 December 9999, which is second
265 621 679 999.999.
Note: A 64-bit double floating-point value can accurately represent approximately 16 significant decimal digits without loss of precision. Therefore, accuracy is available to the nearest millisecond (15 decimal digits).
If input_timestamp does not contain a valid date or timestamp, output_seconds is set to 0 and CEESECS 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 routine. 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: 00 | |
CEE2508 | The value for day is not valid |
Severity: 30 | |
CEE2509 | The value for era is not valid |
Severity: 30 | |
CEE2510 | The value for hour is not valid |
Severity: 30 | |
CEE2513 | The value for Lilian date is not valid |
Severity: 30 | |
CEE2515 | The value for millisecond is not valid |
Severity: 30 | |
CEE2516 | The minute value 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 | |
CEE2519 | The value for second is not valid |
Severity: 30 | |
CEE2521 | The value for year is not valid |
Severity: 30 | |
CEE2525 | Timestamp picture mismatch |
Severity: 30 | |
CEE9902 | Unexpected user error occurred in &1 |
Severity: 30 |
Usage Notes
-
The inverse of CEESECS is CEEDATM. The CEEDATM API converts output_seconds to character format.
-
Elapsed time calculations can be performed easily on the output_seconds, because it represents elapsed time. 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_timestamp is assumed to contain the year within Japanese era. See Examples of Picture Strings Recognized by ILE Date and Time APIs for an example. See Japanese Eras Used by ILE Date and Time APIs When <JJJJ> Specified for a list of the Japanese eras recognized by CEESECS.
-
If picture_string includes an ROC era symbol <CCCC> or <CCCCCCCC> , the YY position in input_timestamp is assumed to contain the year within ROC era. See Examples of Picture Strings Recognized by ILE Date and Time APIs for an example. See Republic of China Eras Used by ILE Date and Time APIs When <CCCC> or <CCCCCCCC> Specified for a list of the ROC eras recognized by CEESECS.
Example
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
-
Calculate the difference between two timestamps, in hours:
CALL CEESECS ('19880516190001','YYYYMMDDHHMISS', secs1, fc); CALL CEESECS ('1988-05-17-03.00.01', 'YYYY-MM-DD-HH.MI.SS', secs2, fc); diff = (secs2 - secs1) / 3600; /* Assume floating-point division */
- Convert a timestamp to number of seconds, to calculate the date and time 36
hours ago:
now = '1988/07/26 19:55:00'; CALL CEESECS (now, 'YYYY/MM/DD HH:MI:SS', secs, fc); secs = secs - 36*60*60; CALL CEEDATM (secs, 'YYYY/MM/DD HH:MI:SS', before, fc);
API introduced: V2R3
[ Back to top | ILE CEE APIs | APIs by category ]