|
CEESECS converts a
string representing a timestamp into the number of Lilian seconds
(number of seconds since 00:00:00 14 October 1582). This service makes
it easier to perform time arithmetic, such as calculating the elapsed
time between two timestamps.
CEESECS is affected only by the
country code setting of the COUNTRY runtime option or CEE3CTY callable
service, not the CEESETL callable service or the setlocale() function.
The
inverse of CEESECS is CEEDATM, which converts output_seconds to
character format. By default, 2-digit years lie within the 100 year
range starting 80 years prior to the system date. Thus, in 1995, all
2-digit years represent dates between 1915 and 2014, inclusive. You
can change this range by using the callable service CEESCEN.
Syntax
>>-CEESECS--(--input_timestamp--,--picture_string--,------------>
>--output_seconds--,--fc--)------------------------------------><
- input_timestamp (input)
- A length-prefixed character string representing a date or timestamp
in a format matching that specified by picture_string.
The character string must contain between 5 and 80 picture characters,
inclusive. input_timestamp can contain leading
or trailing blanks. Parsing begins with the first nonblank character
(unless the picture string itself contains leading blanks; in this
case, CEESECS skips exactly that many positions before parsing begins).
After
a valid date is parsed, as determined by the format of the date you
specify in picture_string, all remaining
characters are ignored by CEESECS. Valid dates range between and including
the dates 15 October 1582 to 31 December 9999. A full date must be
specified. Valid times range from 00:00:00.000 to 23:59:59.999.
As
the following example shows, if any part or all of the time value
is omitted, zeros are substituted for the remaining values. 1992-05-17-19:02 is equivalent to 1992-05-17-19:02:00
1992-05-17 is equivalent to 1992-05-17-00:00:00
- picture_string (input)
- A halfword length-prefixed character string (VSTRING), indicating
the format of the date or timestamp value specified in input_timestamp.
Each character in the picture_string represents
a character in input_timestamp. For example,
if you specify MMDDYY HH.MI.SS as the picture_string,
CEESECS reads an input_char_date of 060288
15.35.02 as 3:35:02 PM on 02 June 1988. If delimiters such as the
slash (/) appear in the picture string, leading zeros can be omitted.
For example, the following calls to CEESECS all assign the same value
to variable secs:
CALL CEESECS('92/06/03 15.35.03', 'YY/MM/DD
HH.MI.SS', secs, fc);
CALL CEESECS('92/6/3 15.35.03' , 'YY/MM/DD
HH.MI.SS', secs, fc);
CALL CEESECS('92/6/3 3.35.03 PM', 'YY/MM/DD
HH.MI.SS AP', secs, fc);
CALL CEESECS('92.155 3.35.03 pm', 'YY.DDD
HH.MI.SS AP', secs, fc);
If picture string is left null or blank, CEESECS gets picture_string based
on the current value of the COUNTRY
runtime option. For example, if the current value of the COUNTRY runtime
option is FR (France), the date format would be DD.MM.YYYY.
If picture_string includes
a Japanese era symbol <JJJJ>, the YY position
in input_timestamp represents the year number
within the Japanese era. For example, the year 1988 equals the Japanese
year 63 in the Showa era. See Table 3 for
a list of Japanese eras supported by CEESECS.
If picture_string includes
era symbol <CCCC> or <CCCCCCCC>,
the YY position in input_timestamp represents
the year number within the era.
See Table 1 for a list
of valid picture characters, and Table 2 for
examples of valid picture strings.
- output_seconds (output)
- A 64-bit double floating-point number representing the number
of seconds since 00:00:00 on 14 October 1582, not counting leap seconds.
For example, 00:00:01 on 15 October 1582 is second 86,401 (24*60*60
+ 01) in the Lilian format. 19:00:01.12 on 16 May 1988 is second 12,799,191,601.12.
The largest value represented is 23:59:59.999 on 31 December 9999,
which is second 265,621,679,999.999 in the Lilian format.
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 terminates with a non-CEE000 symbolic feedback
code.
Elapsed time calculations are performed easily on the output_seconds,
because it represents elapsed time. Leap year and end-of-year anomalies
do not affect the calculations.
- fc (output)
- A 12-byte feedback code, optional in some languages,
that indicates the result of this service. If you choose to omit this
parameter, refer to Invoking callable services for the
appropriate syntax to indicate that the feedback code was omitted.
The
following symbolic conditions can result from this service:
Code |
Severity |
Message number |
Message text |
---|
CEE000 |
0 |
— |
The service completed successfully. |
CEE2EB |
3 |
2507 |
Insufficient data was passed to CEEDAYS or CEESECS. The Lilian
value was not calculated. |
CEE2EC |
3 |
2508 |
The date value passed to CEEDAYS or CEESECS was invalid. |
CEE2ED |
3 |
2509 |
The era passed to CEEDAYS or CEESECS was not recognized. |
CEE2EE |
3 |
2510 |
The hours value in a call to CEEISEC or CEESECS was not recognized. |
CEE2EH |
3 |
2513 |
The input date passed in a CEEISEC, CEEDAYS, or CEESECS call
was not within the supported range. |
CEE2EK |
3 |
2516 |
The minutes value in a CEEISEC call was not recognized. |
CEE2EL |
3 |
2517 |
The month value in a CEEISEC call was not recognized. |
CEE2EM |
3 |
2518 |
An invalid picture string was specified in a call to a date/time
service. |
CEE2EN |
3 |
2519 |
The seconds value in a CEEISEC call was not recognized. |
CEE2EP |
3 |
2521 |
The year-within-era
value passed to CEEDAYS or CEESECS was zero. |
CEE2ET |
3 |
2525 |
CEESECS detected non-numeric data in a numeric field, or the
timestamp string did not match the picture string. |
Usage notes - The probable cause for receiving message number 2518 is a picture
string that contains an invalid DBCS string. You should verify that
the data in the picture string is correct.
- z/OS UNIX consideration—In
multithread applications, CEESECS affects only the calling thread.
Examples - Following is an example of CEESECS called by C/C++.
/*Module/File Name: EDCSECS */
#include <stdio.h>
#include <string.h>
#include <leawi.h>
#include <stdlib.h>
#include <ceeedcct.h>
int main(void) {
_FEEDBACK fc;
_FLOAT8 seconds1, seconds2;
_VSTRING date,date_pic;
/* use CEESECS to convert to seconds timestamp */
strcpy(date.string,"09/13/91 23:23:23");
date.length = strlen(date.string);
strcpy(date_pic.string,"MM/DD/YY HH:MI:SS");
date_pic.length = strlen(date_pic.string);
CEESECS(&date,&date_pic,&seconds1,&fc);
if ( _FBCHECK ( fc , CEE000 ) != 0 ) {
printf("CEESECS failed with message number %d\n",
fc.tok_msgno);
exit(2999);
}
strcpy(date.string,
"December 15, 1992 at 8:23:45 AM");
date.length = strlen(date.string);
strcpy(date_pic.string,
"Mmmmmmmmmmmz DD, YYYY at ZH:MI:SS AP");
date_pic.length = strlen(date_pic.string);
CEESECS(&date,&date_pic,&seconds2,&fc);
if ( _FBCHECK ( fc , CEE000 ) != 0 ) {
printf("CEESECS failed with message number %d\n",
fc.tok_msgno);
exit(2999);
}
printf("The number of seconds between:\n");
printf(" September 13, 1991 at 11:23:23 PM");
printf(
" and December 15, 1992 at 8:23:45 AM is:\n %f\n",
seconds2 - seconds1);
}
- Following is an example of CEESECS called by COBOL.
CBL LIB,QUOTE
*Module/File Name: IGZTSECS
************************************************
** CBLSECS - Call CEESECS to convert **
** timestamp to number of seconds **
** **
** In this example, calls are made to CEESECS **
** to convert two timestamps to the number of **
** seconds since 00:00:00 14 October 1582. **
** The Lilian seconds for the earlier **
** timestamp are then subtracted from the **
** Lilian seconds for the later timestamp **
** to determine the number of between the **
** two. This result is displayed. **
************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. CBLSECS.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 SECOND1 COMP-2.
01 SECOND2 COMP-2.
01 TIMESTP.
02 Vstring-length PIC S9(4) BINARY.
02 Vstring-text.
03 Vstring-char PIC X,
OCCURS 0 TO 256 TIMES
DEPENDING ON Vstring-length
of TIMESTP.
01 TIMESTP2.
02 Vstring-length PIC S9(4) BINARY.
02 Vstring-text.
03 Vstring-char PIC X,
OCCURS 0 TO 256 TIMES
DEPENDING ON Vstring-length
of TIMESTP2.
01 PICSTR.
02 Vstring-length PIC S9(4) BINARY.
02 Vstring-text.
03 Vstring-char PIC X,
OCCURS 0 TO 256 TIMES
DEPENDING ON Vstring-length
of PICSTR.
01 FC.
02 Condition-Token-Value.
COPY CEEIGZCT.
03 Case-1-Condition-ID.
04 Severity PIC S9(4) BINARY.
04 Msg-No PIC S9(4) BINARY.
03 Case-2-Condition-ID
REDEFINES Case-1-Condition-ID.
04 Class-Code PIC S9(4) BINARY.
04 Cause-Code PIC S9(4) BINARY.
03 Case-Sev-Ctl PIC X.
03 Facility-ID PIC XXX.
02 I-S-Info PIC S9(9) BINARY.
PROCEDURE DIVISION.
PARA-SECS1.
************************************************
** Specify first timestamp and a picture string
** describing the format of the timestamp
** as input to CEESECS
************************************************
MOVE 25 TO Vstring-length of TIMESTP.
MOVE "1969-05-07 12:01:00.000"
TO Vstring-text of TIMESTP.
MOVE 25 TO Vstring-length of PICSTR.
MOVE "YYYY-MM-DD HH:MI:SS.999"
TO Vstring-text of PICSTR.
************************************************
** Call CEESECS to convert the first timestamp
** to Lilian seconds
************************************************
CALL "CEESECS" USING TIMESTP, PICSTR,
SECOND1, FC.
IF NOT CEE000 of FC THEN
DISPLAY "CEESECS failed with msg "
Msg-No of FC UPON CONSOLE
STOP RUN
END-IF.
PARA-SECS2.
************************************************
** Specify second timestamp and a picture string
** describing the format of the timestamp as
** input to CEESECS.
************************************************
MOVE 25 TO Vstring-length of TIMESTP2.
MOVE "2000-01-01 00:00:01.000"
TO Vstring-text of TIMESTP2.
MOVE 25 TO Vstring-length of PICSTR.
MOVE "YYYY-MM-DD HH:MI:SS.999"
TO Vstring-text of PICSTR.
************************************************
** Call CEESECS to convert the second timestamp
** to Lilian seconds
************************************************
CALL "CEESECS" USING TIMESTP2, PICSTR,
SECOND2, FC.
IF NOT CEE000 of FC THEN
DISPLAY "CEESECS failed with msg "
Msg-No of FC UPON CONSOLE
STOP RUN
END-IF.
PARA-SECS2.
************************************************
** Subtract SECOND2 from SECOND1 to determine the
** number of seconds between the two timestamps
************************************************
SUBTRACT SECOND1 FROM SECOND2.
DISPLAY "The number of seconds between "
Vstring-text OF TIMESTP " and "
Vstring-text OF TIMESTP2 " is: " SECOND2.
GOBACK.
- Following is an example of CEESECS called by PL/I.
*PROCESS MACRO;
/* Module/File Name: IBMSECS */
/****************************************************/
/** */
/** Function: CEESECS - Change timestamp to seconds */
/** */
/** In this example, CEESECS is called to return an */
/** input timestamp as the number of seconds since */
/** 14 October 1582. */
/** */
/****************************************************/
PLISECS: PROC OPTIONS(MAIN);
%INCLUDE CEEIBMAW;
%INCLUDE CEEIBMCT;
DCL TIMESTP CHAR(255) VARYING;
DCL PICSTR CHAR(255) VARYING;
DCL SECONDS REAL FLOAT DECIMAL(16);
DCL 01 FC, /* Feedback token */
03 MsgSev REAL FIXED BINARY(15,0),
03 MsgNo REAL FIXED BINARY(15,0),
03 Flags,
05 Case BIT(2),
05 Severity BIT(3),
05 Control BIT(3),
03 FacID CHAR(3), /* Facility ID */
03 ISI /* Instance-Specific Information */
REAL FIXED BINARY(31,0);
TIMESTP = '10 November 1992'; /* Specify input */
/* date as timestamp */
PICSTR = 'ZD Mmmmmmmmmmmmmmz YYYY';
/* Picture string that descibes timestamp */
/* Call CEESECS to return the input date as */
/* Lilian seconds */
CALL CEESECS ( TIMESTP, PICSTR, SECONDS, FC );
IF FBCHECK( FC, CEE000) THEN DO;
PUT SKIP LIST( 'There were ' || SECONDS
|| ' seconds between 14 Oct 1582 and '
|| TIMESTP );
END;
ELSE DO;
DISPLAY( 'CEESECS failed with msg '
|| FC.MsgNo );
STOP;
END;
END PLISECS;
|