Learn how to use the Convert Seconds to Character Timestamp (CEEDATM) and Convert Timestamp to Number of Seconds (CEESECS) APIs.

In the last column of this series, we looked at the Get Current Local Time (CEELOCT) and Copy Numeric Value (LBCPYNV) APIs in order to simplify working with time durations involving seconds, minutes, or hours. Today, we will review the Convert Seconds to Character Timestamp (CEEDATM) and Convert Timestamp to Number of Seconds (CEESECS) APIs to see how these APIs can be used to provide a higher level of operational friendliness to the job at hand. As a reminder, the task we are working on is to send an alert from one program (CHKLSTSND) when another program (SNDUPD) has not successfully run in over six hours.

The first change we will make is to store a human readable form of the date and time SNDUPD last successfully run. We will create a new data area, QGPL/LSTSNDTIM2, with the following command:

CRTDTAARA DTAARA(QGPL/LSTSNDTIM2) TYPE(*CHAR) LEN(19)

The data area is created with a size of 19 bytes to accommodate a formatted timestamp value of MM/DD/YYYY HH:MM:SS. We will format this timestamp using the CEEDATM API. The API documentation can be found here and the parameter list is repeated below.

Required Parameters:

  Omissible Parameter:

The CEEDATM API formats an 8-byte floating point value representing the number of seconds since October 14, 1582, to a user-formatted timestamp character string. The first parameter, input_seconds, is the 8-byte floating point value to be formatted. The second parameter, picture_string, defines the desired format for the returned timestamp. The third parameter, output_timestamp, returns the formatted timestamp value. The types of formatting controls that are available can be found in the CEEDAYS API documentation. A new program, Send Update 2 (SNDUPD2), will use the CEEDATM API to format the date and time of the last successful send operation and then store this formatted value in the data area QGPL/LSTSNDTIM2. This is the source for SNDUPD2:

Pgm                                                      

Dcl        Var(&Snd_Float) Type(*Char) Len(8)            

Dcl        Var(&Snd_Greg)  Type(*Char) Len(19)           

Dcl        Var(&Greg_Pic)  Type(*Char) Len(19) +         

             Value('MM/DD/YYYY HH:MI:SS')                

Dcl        Var(&CurLilDt)  Type(*Int)                    

Dcl        Var(&CurGregDt) Type(*Char) Len(23)           

/* Send the updates and then:                         */ 

CallPrc    Prc('CEELOCT') Parm((&CurLilDt) (&Snd_Float) +

             (&CurGregDt) (*Omit))                       

CallPrc    Prc('CEEDATM') Parm((&Snd_Float) (&Greg_Pic) +

             (&Snd_Greg))                                 

ChgDtaAra  DtaAra(QGPL/LSTSNDTIM2) Value(&Snd_Greg)      

EndPgm    

SNDUPD2 essentially sends the updates (shown as a comment in the program), retrieves the current local time in seconds using the &Snd_Float parameter when calling the CEELOCT API, formats the value of &Snd_Float using the CEEDATM API and associated &Greg_Pic formatting controls, and then stores this formatted value in the data area QGPL/LSTSNDTIM2. An operator can now use the command DSPDTAARA DTAARA(QGPL/LSTSNDTIM2) and, if the last successful run was at 10:00:01 June 1, 2008, see the value '06/01/2008 10:00:01' displayed. A definite usability improvement over using DSPDTAARA DTAARA(QGPL/LSTSNDTIME) and seeing a raw floating point value displayed!

As the format of the data area has changed, we must also make some minor changes to the original CHKLSTSND program. The updated program Check Last Send 2 (CHKLSTSND2) is shown below.

            Pgm                                                    

            Dcl        Var(&Snd_Greg)   Type(*Char) Len(19)        

            Dcl        Var(&Snd_Float)  Type(*Char) Len(8)         

            Dcl        Var(&Snd_Dec)    Type(*Dec)  Len(15 0)      

            Dcl        Var(&Cur_Float)  Type(*Char) Len(8)          

            Dcl        Var(&Cur_Dec)    Type(*Dec)  Len(15 0)      

            Dcl        Var(&Alert_Time) Type(*Dec)  Value(21600)   

            Dcl        Var(&Delay_Time) Type(*Dec)                 

            Dcl        Var(&Status)     Type(*Char) Len(1)         

            Dcl        Var(&Greg_Pic)   Type(*Char) Len(19) +      

                         Value('MM/DD/YYYY HH:MI:SS')              

            Dcl        Var(&Float_Dfn)  Type(*Char) Len(7) +       

                         Value(X'01000800000000')                  

            Dcl        Var(&Dec_Dfn)    Type(*Char) Len(7) +       

                         Value(X'03000F00000000')                  

            Dcl        Var(&CurLilDt)   Type(*Int)                    

            Dcl        Var(&CurGregDt)  Type(*Char) Len(23)           

Loop:       RtvDtaAra  DtaAra(QGPL/LSTSNDTIM2) RtnVar(&Snd_Greg)      

            CallPrc    Prc('CEESECS') Parm((&Snd_Greg) (&Greg_Pic) +  

                         (&Snd_Float))                                

            CallPrc    Prc('_LBCPYNV') Parm((&Snd_Dec) (&Dec_Dfn) +   

                         (&Snd_Float) (&Float_Dfn))                   

            CallPrc    Prc('CEELOCT') Parm((&CurLilDt) (&Cur_Float) + 

                         (&CurGregDt) (*Omit))                        

            CallPrc    Prc('_LBCPYNV') Parm((&Cur_Dec) (&Dec_Dfn) +   

                         (&Cur_Float) (&Float_Dfn))                   

            If         Cond((&Cur_Dec - &Snd_Dec) > &Alert_Time) +    

                         Then(Do)                                     

                            SndPgmMsg Msg('Time to send alert') +     

                               ToPgmQ(*Ext)                           

                            ChgVar Var(&Delay_Time) Value(300)        

                            EndDo                                     

            Else       Cmd(ChgVar Var(&Delay_Time) +                  

                         Value(&Alert_Time - (&Cur_Dec - &Snd_Dec) +  

                         + 1))                                        

            RtvJobA    EndSts(&Status)                                

            If         Cond(&Status *NE '1') Then(Do)                 

                       DlyJob Dly(&Delay_Time)                        

                       GoTo CmdLbl(Loop)                              

                       EndDo                                          

            EndPgm                                                    

The major change in CHKLSTSND2 is in the retrieval of the data area LSTSNDTIM2 and in calling the API CEESECS to convert the formatted &Snd_Greg value back to the original number of seconds since October 14, 1582.

The CEESECS API allows us to convert any timestamp in the range of October 15, 1582, through December 31, 9999, inclusive and have the timestamp value returned as a number of seconds since October 14, 1582. The API documentation can be found here, and I've repeated the API's parameter list below:

Required Parameter Group:

  Omissible Parameter:

The first parameter, input_timestamp, is a formatted time value such as 06/01/2008 10:00:01, 20080601100001, or 01-06-2008 10.00.01 for 10:00:01 June 1, 2008, and the second parameter, picture_string, is a variable-length character string describing how to interpret the input_timestamp parameter. The formatting options, and there are many, can be found in the CEEDAYS API documentation. The third parameter, output_seconds, is the Lilian-formatted number of seconds that represents the value of the input_timestamp parameter.

In CHKLSTSND2, we call CEESECS with the input_timestamp parameter set to the value found in the data area LSTSNDTIM2 (&Snd_Greg) and the same control string (&Greg_Pic) as we used in SNDUPD2 to format &Snd_Greg. The CEESECS API returns in the output_seconds parameter (&Snd_Float) the Lilian seconds equivalent to the input_timestamp using an 8-byte floating point format. CHKLSTSND2 then processes this floating point value in the same manner as was done with CHKLSTSND. Using CEEDATM, SNDUPD2 could have stored the timestamp of the last send operation in pretty much any format the operator would find useful. CHKLSTSND2 could then convert this formatted input_timestamp value by simply using the same picture_string SNDUPD2 used when calling CEESECS.

One additional change in CHKLSTSND2, which is not related to the time duration program we are solving, is in the area of ending the program CHKLSTSND2. Associated with every job is the job attribute End status. The CHKLSTSND2 program, prior to running the DLYJOB command, retrieves this job end status in order to determine if the job, the subsystem the job is running in, or the system itself is being ended in a controlled fashion. If the End status variable, &Status, returned by RTVJOBA has a value of '1' then a controlled end has been requested and the program exits. Otherwise, the program continues running, determining if the SNDUPD2 program is successfully sending updates within a six-hour period. Using this job attribute to allow a program to end in a controlled fashion allows for an orderly shutdown of the program and avoids the generation of unnecessary job logs. This approach, or something similar, should be used by any program that essentially is written to "run forever."

I will point out that, in a production environment, I most likely would not use the above programs as they are really doing more work than is necessary. Rather than having the SNDUPD2 program store only the formatted timestamp value in the data area QGPL/LSTSNDTIM2, I would tend toward declaring the data area with a length of 28 bytes and storing both the formatted timestamp &Snd_Greg (for the operator) and the 8-byte floating point value &Snd_Float (for CHKLSTSND2) that is associated with the timestamp. Doing this would avoid having to call the CEESECS API within the CHKLSTSND2 program. Such an approach, however, would have not given us the opportunity to learn about CEESECS, and knowing about this API is important. If you do decide to implement a program storing both a timestamp and a floating point value in the data area, make sure that you update the data area with one CHGDTAARA command rather than two separate operations using the substring support of the CHGDTAARA command. This is to avoid your version of CHKLSTSND2 "sneaking" in between the two CHGDTAARA operations and seeing a "current" &Snd_Greg value (assuming it's updated with the first CHGDTAARA command) with an "old" &Snd_Float value. In the above sample programs, this discrepancy in retrieved values wouldn't cause any real problem, but it could in more complex environments.

In the last several columns, we've looked at quite a few of the CEE date- and time-related APIs. For CL developers, they certainly provide for quite a bit of flexibility in working with date and time values, especially when manipulating and/or formatting time-related values. There are several other CEE APIs that we have not reviewed, and I encourage you to familiarize yourself with them. The complete set of CEE date and time APIs can be found here.

In the next article, we will look at how to use system APIs other than the CEE date and time APIs to provide the function found in sample programs SNDUPD and CHKLSTSND. In particular, we will be reviewing how to use the C language runtime libraries provided with i in order to easily work with time durations measured in seconds.

More CL Questions?             

Wondering how to accomplish a function in CL? Send your CL-related questions to me at This email address is being protected from spambots. You need JavaScript enabled to view it.. I'll see what I can do about answering your burning questions in future columns.