21
Sun, Apr
5 New Articles

The CL Corner: More on ILE CEE Time APIs

CL
Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

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:

1

input_seconds

Input

FLOAT8

2

picture_string

Input

VSTRING

3

output_timestamp

Output

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

1

input_timestamp

Input

VSTRING

2

picture_string

Input

VSTRING

3

output_seconds

Output

FLOAT8


  Omissible Parameter:

4

fc

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

Bruce Vining

Bruce Vining is president and co-founder of Bruce Vining Services, LLC, a firm providing contract programming and consulting services to the System i community. He began his career in 1979 as an IBM Systems Engineer in St. Louis, Missouri, and then transferred to Rochester, Minnesota, in 1985, where he continues to reside. From 1992 until leaving IBM in 2007, Bruce was a member of the System Design Control Group responsible for OS/400 and i5/OS areas such as System APIs, Globalization, and Software Serviceability. He is also the designer of Control Language for Files (CLF).A frequent speaker and writer, Bruce can be reached at This email address is being protected from spambots. You need JavaScript enabled to view it.. 


MC Press books written by Bruce Vining available now on the MC Press Bookstore.

IBM System i APIs at Work IBM System i APIs at Work
Leverage the power of APIs with this definitive resource.
List Price $89.95

Now On Sale

BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$0.00 Raised:
$

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: