19
Fri, Jul
2 New Articles

The API Corner: How Do You Want That Date and Time?

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

 

Have it the way you want it by using the Convert Date and Time Format API.

 

Last month, in What's the Status of My Data Queue?, we used the Convert Date and Time Format (QWCCVTDT) API to format a date and time value stored in an internal format to a YYYYMMDDHHMMSS format much friendlier to work with, but we really didn't discuss how the API is used. This month, we'll look at some of the uses of QWCCVTDT.

The Convert Date and Time Format API converts date and time values from one format to another. For example, using the API you can:

  • Access the current local time to character formats such as YYYYMMDDHHMMSS, MMDDYYYYHHMMSS, YYYYDDD HHMMSS, etc.
  • Convert a system date time stamp value to character formats such as YYYYMMDDHHMMSS, MMDDYYYYHHMMSS, YYYYDDD HHMMSS, etc. (with a conversion to YYYYMMDDHHMMSS being what was done last month)
  • Convert a date and time from one character format to another
  • Convert a date and time from one time zone to another time zone
  • Specify the level of time precision (milliseconds or microseconds) desired for input and output of the conversion process

Note that I would not necessarily use the QWCCVTDT API to actually perform all the format conversions listed above. The following program, for instance, shows how to access the local time, have it converted to YYYYMMDDHHMMSS character format, and then dsply the date and time value retuned by the API.

h dftactgrp(*no)                                  

                                                       

d CvtDat          pr                              

                                                      

d CvtDat          pi                             

                                                         

 ************************************************************   

                                                        

d CvtDatTim       pr                  extpgm('QWCCVTDT')       

d  InpFmt                       10a   const                

d  InpValue                     20a   const options(*varsize) 

d  OutFmt                       10a   const            

d  OutValue                     20a   options(*varsize)     

d  ErrCde                             likeds(QUSEC)       

d  InpTZ                        10a   const options(*nopass)  

d  OutTZ                        10a   const options(*nopass) 

d  TZInfo                        1a   const options(*nopass)  

d  LenTZInfo                    10i 0 const options(*nopass)  

d  PrecInd                       1a   const options(*nopass)

d  InpTimInd                     1a   const options(*nopass)

                                                  

 ************************************************************    

                                                         

d YYMDValue       s             20a                        

                                                         

 ************************************************************   

                                                          

 /copy qsysinc/qrpglesrc,qusec                          

                                                          

 ************************************************************   

                                                         

 /free                                       

                                             

  CvtDatTim('*CURRENT' :' ' :'*YYMD' :YYMDValue :QUSEC);   

  dsply %subst(YYMDValue :1 :14);                     

                                                    

  *inlr = *on;                                         

  return;                                                

                                                 

  // ******************************************************** 

                                                     

  begsr *inzsr;                                        

                                                      

    QUSBPrv = 0;                                           

                                                           

  endsr;                    

/end-free

This same result, however, could also be obtained quite easily using RPG-provided interfaces, with one possible solution shown in the following program.

h dftactgrp(*no)                                                    

                                                                     

d CvtDat          pr                                                

                                                                     

d CvtDat          pi                                                

                                                                     

 ****************************************************************   

d YYMDValue       s             20a                                 

                                                                     

 ****************************************************************   

                                                                     

 /free                                                              

                                                                 

  YYMDValue = %char(%timestamp() :*ISO0);                       

  dsply %subst(YYMDValue :1 :14);                               

                                                                 

  *inlr = *on;                                                    

  return;                                    

/end-free                      

In some cases, though, the API is the way to go.

As seen in the previous prototype, the QWCCVTDT API defines five required parameters and six optional parameters that are divided across two optional parameter groups. This month, we'll look at the required parameters. Next month, we'll review how the API can really assist you when needing to work with time values across users who are in different time zones.

The first required parameter is the input format. This is a Char(10) input value that defines the data you want converted. The actual data to be converted is passed in the second parameter. The special values supported are:

  • *CURRENT to use the current system time (in which case the second parameter is not used)
  • *DTS to use a system date time stamp
  • *JOB to use the format found in the DATFMT job attribute
  • *SYSVAL to use the format found in the QDATFMT system value
  • A variety of common formats, such as *YYMD, *YMD, *MDYY, *MDY, *LONGJUL, and *JUL, where a single Y indicates a 2-digit year and YY indicates a 4-digit year

The second parameter is a variable-length input value that provides the date and time you want converted. As mentioned before, this parameter is not used (but must be passed) when the input format parameter is set to *CURRENT. One item to keep in mind is that the size of this parameter is implicitly assumed, based on the input format value. These are the assumed lengths based on the input format:

  • *DTS will use the first 8 bytes of the input value.
  • *YYMD, *MDYY, *DMYY, and *LONGJUL, when working with a millisecond precision (which is the default), will use the first 17 bytes of the input value.
  • Other formats, when working with a millisecond precision, will use the first 16 bytes of the input value.
  • *YYMD, *MDYY, *DMYY, and *LONGJUL, when working with a microsecond precision (parameter Precision indicator is set to '1'), will use the first 20 bytes of the input value.
  • Other formats, when working with a microsecond precision, will use the first 19 bytes of the input value.

The third parameter is the desired output format. The special values supported are essentially those that can be used for the input format parameter, with the exception that you cannot specify *CURRENT.

The fourth parameter is a variable-length receiver variable for the API to use in returning the converted data and time value. The necessary size of this receiver variable is, like in the case of the input value, implicitly assumed, based on the output format value.

One item to be very careful about is the allocated size of this parameter within your application program. You'll note that there is no separate parameter for you to indicate the length of the receiver variable, so if you have the output format specified as *YYMD, the API is going to return 17 bytes of data. If your variable is less than 17 bytes in size, then storage is going to be overwritten (which can be a real pain to debug). That is partly why, in the previous sample program, I allocated the variable YYMDValue with a worst-case 20 bytes (the maximum amount of data returned by any format), though strictly speaking it only needs 17 bytes. There's no problem allocating more than is necessary, and I want to avoid having to remember in the future that, if I want to start using microsecond precision, I need to increase my variable allocations by 3 bytes (something easily forgotten).

The fifth parameter is the standard API error code structure.

Returning to our program of last month, GetDQInfo had obtained a system date time stamp and then called QWCCVTDT as in:

           CvtDatTim('*DTS' :DQMsg.QMHMDT00                            

                     :'*YYMD' :YYMDValue :ErrCde);                     

This call is indicating that variable DQMsg.QMHMDT00 is a system date time stamp (input format is *DTS) and that the date and time value is to be converted to a YYYYMMDDHHMMSS format for further processing by the application program.

So just what is this *DTS format? It's basically an internal format for recording time in a consistent manner. The use of system date time stamps can be found in many areas of the system. You'll find *DTS as being a valid message data field format (FMT) on the Add Message Description (ADDMSGD) CL command (meaning you may need to work with *DTS values when sending or receiving a message), APIs such as Retrieve User Information (QSYRUSRI) (date password expires, password change date, etc.), and, as we saw last month, Retrieve Data Queue Message (QMHRDQM) (message enqueue date and time). For those readers who work with Machine Interface (MI) instructions, you also find system date time stamps, though referred to as a Time-of-Day (*TOD) clock value within MI documentation, on instructions such as Materialize Machine Attributes (MATMATR) and Materialize Time of Day Clock Attributes (MATTODAT). If you're interested in how system date time stamps are implemented within the system, you'll find the details under the MI topic Standard Time Format. When you're working with system date time stamps, I suspect you'll find the QWCCVTDT API to be, in general, the easiest way to go.

Next month, we'll look at some additional capabilities of the QWCCVTDT API.

Have Some System API Questions?

As usual, if you have any API questions, send them to me at This email address is being protected from spambots. You need JavaScript enabled to view it..

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

$

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: