Tips For Proper Handling of Julian Dates in IDL

These tips address how to properly handle Julian dates in IDL to avoid common errors.
1. Make sure to typecast a decimal number to "DOUBLE" before feeding it to CALDAT.

This is easy to forget but very important if a Julian date includes hours, minutes, and/or seconds. 


   IDL> j = JULDAY(3,1,2000,13,32,25)
   IDL> PRINT, j, FORMAT='(D23.15)'
   2451605.064178241400000

This call to CALDAT (without the d) will not give expected results:
   IDL> CALDAT, 2451605.064178241400000, mo, da, yr, hr, mi, se
   IDL> PRINT, mo, da, yr, hr, mi, se
    3 1 2000 12 0 0.0000000

Notice the loss of precision on the hour, minute, and second.
This call to CALDAT (with the d) will give expected results:
   IDL> CALDAT, 2451605.064178241400000d, mo, da, yr, hr, mi, se
    3 1 2000 13 32 25.000058

2. When reading a Julian date from a string or a file, be sure to initialize the storage variable as a "DOUBLE."

This is similar to the previous tip.

For example, the following will give unexpected results:
   IDL> s = 'Sat Jan 01 12:32:54 2000'
   IDL> jul = 0
   IDL> READS, s, jul, FORMAT='(C())'
   IDL> PRINT, jul, FORMAT='(C())'
   Tue Feb 19 12:00:00 4640

Notice that the printed date does not match the original date.
This call will give the expected results:
   IDL> s = 'Sat Jan 01 12:32:54 2000'
   IDL> jul = 0d0
   IDL> READS, s, jul, FORMAT='(C())'
   IDL> PRINT, jul, FORMAT='(C())'
   Sat Jan 01 12:32:54 2000

3. Negative years (i.e., B.C.) require extra field width beyond the default width for years.

For example:
   IDL> mydate = 0.0d ; Julian Date 0 = 4713 B.C.
   IDL> PRINT, mydate, FORMAT='(C(CYI))'
   4713

Notice that the negative sign before the year, 4713, is not included. This is because the default field width for years is 4.
Try this instead:
   IDL> PRINT, mydate, FORMAT='(C(CYI5))'
   -4713

The standard calendar code, '(C())', also uses a default field width of 4 for the year portion of the string. Therefore, if the year is earlier than -999, the negative sign will not appear.
   IDL> mydate = 0.0d ; Julian Date 0 = 4713 B.C.
   IDL> PRINT, mydate, FORMAT='(C())'
   Mon Jan 01 12:00:00 4713

To include the negative sign, the following explicit format will do the trick:
   IDL> PRINT, mydate, FORMAT= $
   IDL> '(C(CDwA,X,CMoA,X,CDI2.2,X,CHI2.2,":",CMI2.2,":",CSI2.2,X,CYI5))'
   Mon Jan 01 12:00:00 -4713