Improvements to RPG's timestamps

Ever since timestamps were introduction to RPG I have always felt aggrieved that they never contained the entire timestamp. Timestamps have six decimal places following the seconds and only the first three positions, milliseconds, were filled. The last three positions were always zero. Occasionally I have found in timestamp fields in two records with same value. I would unable to determine which record is older, without using other fields or the file's relative record number.

The latest round of new Technology Refreshes, IBM i 7.4 TR2 and 7.3 TR8, brought improvements to the way RPG does timestamps.

Some of what I am going to describe here may have been available in earlier releases or TRs.

One of the things I learned from the documentation is that I can define timestamps of different lengths:

01 dcl-s WorkX timestamp ; 02 dcl-s Work0 timestamp(0) ; 03 dcl-s Work1 timestamp(1) ; 04 dcl-s Work3 timestamp(3) ; 05 dcl-s Work12 timestamp(12) ;

Line 1: I have always defined timestamps in my RPG programs this way, this is the timestamp with the six decimal places.

Lines 2 - 4: I did not know I could define timestamps with different number of decimal places.

Line 5: This is new with the latest TRs, a timestamp with 12 decimal places. I will describe how it is special below.

Let me move values from the timestamp built in function, %TIMESTAMP, to these variables:

06 WorkX = %timestamp() ; 07 Work0 = %timestamp() ; 08 Work1 = %timestamp() ; 09 Work3 = %timestamp() ; 10 Work12 = %timestamp(*unique) ;

Lines 6 - 9: These are basically the same, moving the value returned from the timestamp BIF to the different size timestamp variables.

Line 10: This is the line that is all new. The special value *UNIQUE has to be used to fill the 12 decimal places of Work12 I will explain the significance of those what is in the 12 places when we see the values returned when I debugged the program:

WORKX = '2020-05-20-20.58.42.998389' WORK0 = '2020-05-20-20.58.42' WORK1 = '2020-05-20-20.58.42.9' WORK3 = '2020-05-20-20.58.42.998' WORK12 = '2020-05-20-20.58.42.998429000244'

The default timestamp variable, WORKX, now contains a timestamp to the full number of decimal places, microseconds. This was introduced in the latest TRs, and makes me a happy man.

The other variables, WORK0, WORK1, and WORK3, all have the expected number of decimal places.

I need to explain what is in the decimal places for WORK12. The first six numbers in the decimal, 988429, are the microseconds from the timestamp. The last six numbers, 000244, are a unique number generated to guarantee that this timestamp value is unique.

If I wanted to populate the "regular" timestamp variable, WorkX, with timestamps of differing lengths I would use the value *SYS as a parameter passed to the timestamp BIF followed by the number of decimal places I want. For example:

11 WorkX = %timestamp(*sys) ; Debug: WORKX = '2020-05-20-21.02.46.706974'

As I did not give the number of decimal places the default, six, is given.

In the example below I want zero decimal places in my timestamp. The timestamp still has its six decimal places, but they are all zero.

12 WorkX = %timestamp(*sys:0) ; Debug: WORKX = '2020-05-20-21.03.06.000000'

Below as I "asked" for only one decimal place I have only one in my variable.

13 WorkX = %timestamp(*sys:1) ; Debug: WORKX = '2020-05-20-21.03.32.200000'

In the example below I want just the milliseconds, first three decimal places, in my timestamp variable.

14 WorkX = %timestamp(*sys:3) ; Debug: WORKX = '2020-05-20-21.03.54.407000'

I am not going to give more examples as I am sure you get the idea.

If I wanted to calculate the difference between two timestamps that included the unique number I would want to exclude the unique part from the calculation. I can just use the first six decimal places:

i = %diff(%timestamp(TS2:6) : %timestamp(TS1:6) : *mseconds) ;

 

You can learn more about the changes to RPG's timestamp built in function from the IBM website here.

 

This article was written for IBM i 7.4 TR2 and 7.3 TR8.