Convert Timestamp to Number of Seconds (CEESECS) API

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

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

See Code disclaimer information for information pertaining to code examples.

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