A Bevy of BIFs: Getting a Date is Easy with %Date

Published: February 18, 2009

by Susan Gantner

Almost every kind of business application uses dates. Hopefully you're taking full advantage of all the RPG support for date data types to simplify your logic. If you're using more than one line of code to calculate the number of days, months or years between two dates, or to add a number of days, months, or years to a date, you're working way too hard!

Many of the "dates" we deal with come from a screen or a database file and aren't true date data type fields. They are numeric or character fields that contain values that we treat as dates. So to be able to use that data with functions like %Diff (to calculate the difference between two dates) or %Days (to add some number of days to a date), you need to convert the data to true date formats.

That's where %Date comes in. There are also similar functions for converting data into time and timestamp fields, but I'll concentrate on dates in these examples. The syntax looks like this: %DATE{(expression{:date-format})}. The expression can be character or numeric (or sometimes a timestamp, although that's rarely used). Because it is an expression, we can concatenate or add fields together if the year, month, and day are stored as separate fields.

The second parameter, date format, is optional, but since the default is the default date format for the program, it is typically needed. Keep in mind that this is the format of the "date-like" expression in the first parameter--not the format you want the output to be. You could control the default date format using the DATFMT keyword on the H spec, but it's probably easier and safer to specify it using the parameter.

Some examples of using %Date follow. All result in output of the *ISO date value of "1988-06-21".

H  Option(*SrcStmt:*NoDebugIO)

D Number          S              6S 0 inz(880621)
D Character       S              6A   inz('880621')
D DateFld         S               D
D Day             S              2  0 Inz(21)
D Month           S              2  0 Inz(6)
D Year            S              2  0 Inz(88)
D DayChar         S              2    Inz('21')
D MonthChar       S              2    Inz('06')
D YearChar        S              2    Inz('88')
D JulianDay       S              3  0 Inz(173)
D iAge            S              3  0  

/FREE

   DateFld = %Date(Number:*YMD);
   DateFld = %Date(Character:*YMD0);
   DateFld = %Date((Year*10000)+ (Month*100)+ Day:*YMD);
   DateFld = %Date((YearChar + MonthChar + DayChar):*YMD0);
   DateFld = %Date((Year*1000)+ JulianDay :*JUL);
   DateFld = %Date('0' + Character:*CYMD0);

One last hidden talent of %Date, which if you call it passing no parameters, it returns the current system date, is it is a nice way to get today's date into an expression. Keep in mind that you may never need to define a date field in your program. Often you can simply convert your date-like data on the fly. See how simple it can be to use %Date compared to using the older SUBDUR support in this example:

          // Calculate Age of my favorite platform
   iAge = %Diff( %Date() : %Date(Number:*YMD) : *Years );

What would happen, however, if an invalid date value were used as input to %Date? If the field Number contained zeroes or 880631 or 062188, then the first line of logic above would produce the error:

RNQ0112 Date, Time or Timestamp value is not valid.

So an important step in converting "date-like" data to real dates so that they can use other date functions involves either testing the date-like data first by using the Test operation code or using Monitor to capture and react to status code 112. I'll cover the details of using Test and Monitor with date operations in a later tip. Stay tuned!

Susan Gantner is one of the most respected System i gurus in the world and is one of the co-founders of System i Developer, an organization dedicated to RPG, DB2, and other relevant software technologies for the System i platform that hosts the new RPG & DB2 Summit conference. Gantner, who has worked in IBM's Rochester and Toronto labs, left IBM to focus on training OS/400 and i5/OS shops on the latest programming technologies. She is also a regular speaker at COMMON and other user groups. Send your questions or comments for Susan to Ted Holt via the IT Jungle Contact page.

RELATED STORY

A Bevy of BIFs: Look Up to %LookUp

                     Post this story to del.icio.us
               Post this story to Digg
    Post this story to Slashdot