The CL Corner More on ILE CEE Time APIs

7/27/2019 The CL Corner More on ILE CEE Time APIs

1/10

The CL Corner: More on ILE CEE Time APIs

Contributed by Bruce ViningFriday, 11 July 2008Last Updated Thursday, 12 June 2008

Learn how to use the Convert Seconds to Character Timestamp (CEEDATM) and Convert Timestamp to Number ofSeconds (CEESECS) APIs. By Bruce Vining 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 willreview 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 athand. As a reminder, the task we are working on is to send an alert from one program (CHKLSTSND) when anotherprogram (SNDUPD) has not successfully run in over six hours.

Learn how to use the Convert Seconds to Character Timestamp (CEEDATM) and Convert Timestamp to Number ofSeconds (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 willreview 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 athand. 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. Wewill 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/YYYYHH:MM:SS. We will format this timestamp using the CEEDATM API. The API documentation can be found here and theparameter list is repeated below.

Required Parameters:

MC Press Online

http://www.mcpressonline.com Powered by Joomla! Generated: 29 August, 2008, 00:15


2/10


3/10

VSTRING

Omissible Parameter:

4 fc Output

FEEDBACK 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 tobe formatted. The second parameter, picture_string, defines the desired format for the returned timestamp. The thirdparameter, output_timestamp, returns the formatted timestamp value. The types of formatting controls that are availablecan be found in the CEEDAYS API documentation. A new program, Send Update 2 (SNDUPD2), will use the CEEDATMAPI to format the date and time of the last successful send operation and then store this formatted value in the data areaQGPL/LSTSNDTIM2. This is the source for SNDUPD2: Pgm Dcl Var(&Snd_Float) Type(*Char) Len(8) Dcl Var(&Snd_Greg) Type(*Char) Len(19)

MC Press Online



4/10

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 inseconds using the &Snd_Float parameter when calling the CEELOCT API, formats the value of &Snd_Float using theCEEDATM API and associated &Greg_Pic formatting controls, and then stores this formatted value in the data areaQGPL/LSTSNDTIM2. An operator can now use the command DSPDTAARA DTAARA(QGPL/LSTSNDTIM2) and, if thelast successful run was at 10:00:01 June 1, 2008, see the value '06/01/2008 10:00:01' displayed. A definite usabilityimprovement 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 CHKLSTSNDprogram. The updated program Check Last Send 2 (CHKLSTSND2) is shown below.

MC Press Online



5/10

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) +

MC Press Online



6/10

(&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)

MC Press Online



7/10

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 toconvert 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 APIdocumentation can be found here, and I've repeated the API's parameter list below: Required Parameter Group:

1

input_timestamp Input VSTRING

MC Press Online



8/10

2 picture_string

Input VSTRING

3 output_seconds Output

FLOAT8

Omissible Parameter:

4 fc

MC Press Online



9/10

Output FEEDBACK

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 characterstring describing how to interpret the input_timestamp parameter. The formatting options, and there are many, can befound 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 areaLSTSNDTIM2 (&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 theinput_timestamp using an 8-byte floating point format. CHKLSTSND2 then processes this floating point value in thesame manner as was done with CHKLSTSND. Using CEEDATM, SNDUPD2 could have stored the timestamp of the lastsend operation in pretty much any format the operator would find useful. CHKLSTSND2 could then convert this formattedinput_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 areaof ending the program CHKLSTSND2. Associated with every job is the job attribute End status. The CHKLSTSND2program, prior to running the DLYJOB command, retrieves this job end status in order to determine if the job, thesubsystem 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 withina six-hour period. Using this job attribute to allow a program to end in a controlled fashion allows for an orderly shutdownof 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 doingmore work than is necessary. Rather than having the SNDUPD2 program store only the formatted timestamp value in thedata area QGPL/LSTSNDTIM2, I would tend toward declaring the data area with a length of 28 bytes and storing boththe formatted timestamp &Snd_Greg (for the operator) and the 8-byte floating point value &Snd_Float (forCHKLSTSND2) that is associated with the timestamp. Doing this would avoid having to call the CEESECS API within theCHKLSTSND2 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 floatingpoint value in the data area, make sure that you update the data area with one CHGDTAARA command rather than twoseparate operations using the substring support of the CHGDTAARA command. This is to avoid your version ofCHKLSTSND2 "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 sampleprograms, this discrepancy in retrieved values wouldn't cause any real problem, but it could in more complex

MC Press Online



10/10

environments. In the last several columns, we've looked at quite a few of the CEE date- and time-related APIs. For CL developers, theycertainly 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 tofamiliarize 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 functionfound in sample programs SNDUPD and CHKLSTSND. In particular, we will be reviewing how to use the C languageruntime 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 [email protected]. I'llsee what I can do about answering your burning questions in future columns.

MC Press Online


Documents

The CL Corner More on ILE CEE Time APIs