w w w . P r o v a t o S y s . c o m M i c h a e l   C a t a l a n i 9 0 1 . 5 8 1 . 8 7 9 1

The TIME_TopOfTheHour() Function

Here's a nifty little function that has a self-describing name.  I have often needed to set a bath job to run at the start of each hour of the day. Or, I might need to report a time back as the top of the hour for some business purpose.

So I created the TIME_TopOfTheHour() function.  The functions optionally accepts a time field. If we dont pass it a parameter, the function will return the top of the hour for the current system time. ( One would probably rarely ever need to get the top of the hour for a time other than the system time, but it was too easy to include it just in case it was ever needed.)

Let's say you programmed the following:

/free
  NewTime = TIME_TopOfTheHour();

If the current system time was 10.12.30, then NewTime would contain 11.00.00

Prototype for TIME_TopOfTheHour()

 
  
     d TIME_TopOfTheHour...
     d                 pr              t
     d  PassedTime                     t   const options(*nopass)   

From the prototype, we can see that we pass an optional time parameter, and the function returns a time field back to us.

Prcoedure Interface and Code for TIME_TopOfTheHour()

 
     p TIME_TopOfTheHour...
     p                 b                   export
     d TIME_TopOfTheHour...
     d                 pi              t
     d  PassedTime                     t   const options(*nopass)
     d  NewTime        s               t
      /free

        if %parms = 0;
          NewTime = %time;
        else;
          NewTime = PassedTime;
        endif;

        NewTime = newtime - %minutes(%subdt(NewTime:*minutes))-
                            %seconds(%subdt(NewTime:*seconds))+
                            %hours(1);
        return newtime;
      /end-free
     p                 e   

The TIME_TopOfTheHour function receives in an optional time parameter. If we do not pass a parameter (%parms = 0), then we use the system time. Then the function sets the minutes and seconds of the time to 0, and then adds one to the hour.  Then it returns this new time.

Although this code is easily replicated in one line of code in an application, it's much easier to see the code replaced by TIME_TopOfTheHour, which is a self documenting function.  Also, we ensure that the function performs the same every time, and isn't prone to keying errors if the entire expression for calculting the top of the hour was included in every application that needed it. Take a quick look at the two sections of code below and judge for yourself which is more quickly and clearly readable:

• NewTime = NewTime - %minutes(%subdt(NewTime:*minutes))-
                              %seconds(%subdt(NewTime:*seconds))+
                              %hours(1);|
  OR
   
• NewTime = TIME_TopOfTheHour()

I show an example of using the TIME_TopOfTheHour function in the section on the TIME_DelayJobUntil example.

\