Date/Time Structure

User Guide > Working with Date/Time Data > Date/Time Structure

Date/Time Structure

Date/Time data is stored in a structure (!DT) containing the fields shown in Fields of the !DT Structure.

Table 8-1: Fields of the !DT Structure
Element	Data Type	Valid Range
!DT.Year	integer	0 to 9999
!DT.Month	byte	1 to 12
!DT.Day	byte	1 to 31
!DT.Hour	byte	0 to 23
!DT.Minute	byte	0 to 59
!DT.Second	floating point	0.0000 to 59.9999
!DT.Julian	double precision	The number of days calculated from September 14, 1752. The decimal part contains the time as a fraction of a day.
!DT.Recalc	byte	Recalculation flag: setting this flag to 1 forces the julian day to be recalculated.

For example:

date = {!dt, 1992,4,27,7,45,40.0,87519.323,0}

PRINT, date

; PV-WAVE prints: { 1992 4 27 7 45 40.0000 87519.323 0}

For more information on structures, see Chapter 6: Working with Structures in the PV‑WAVE Programmer’s Guide.

Julian Field

PV‑WAVE uses the Julian field to perform many date/time calculations. A date/time value is interpreted as a day in a series of days that begins on September 14, 1752. For example, 2 is equated with September 15, 1752. The decimal part of the Julian day indicates the time as a portion of the day. For example, for May 1, 1992 at 8:00 a.m, the Julian day is 84702.333.

Recalc Field

If you modify a date/time variable directly by assigning a new value to one of its elements, you must also set the Recalc flag (the last element of the date/time structure) to 1. This recalculates the Julian day for the new date. For example, for a date/time variable date that looks like:

date = {!dt, 1992, 4, 27, 7, 45, 40.0, 87519.323, 0}

If you add three days to this variable by assigning a new value to date.day directly.

date.day = 30

The new value of date is:

PRINT, date

; PV-WAVE prints: { 1992 4 30 7 45 40.0000 87519.323 0}

Notice that the Julian field 87519.323 has not changed. You must set the recalc flag to 1 for date to obtain the correct Julian day:

date.recalc = 1

The Julian date is then recalculated automatically when the date/time variable is used with any of the date/time functions.

note	Rather than modifying a date/time variable by assigning a new value to one of its elements, you should use the DT_ADD and DT_SUBTRACT functions to create new variables. If you use these functions, the Julian day is automatically recalculated.

Date/time calculation notes

It is possible when working with date/time functions for the Julian day to become out of sync with the remaining fields of the !DT structure. If you have noticed these changes while using the DT_COMPRESS Function or JUL_TO_DT Function, we recommend using the new keyword SetToZero when calling the DT_COMPRESS routine, and modifying the !DT_BASE system variable directly to an “empty” date/time variable by assigning !DT to !DT_BASE.

For example:

!DT_BASE = {!DT}

CREATE_WEEKENDS, ['Saturday', 'Sunday']

day1 = VAR_TO_DT(2015, 1, 1)

dt_array = DTGEN(day1, 366)

Julian_day = DT_COMPRESS(dt_array, /SETTOZERO)

result = JUL_TO_DT(Julian_day)

Creating Empty Date/Time Variables

Normally, you create date/time variables using the conversion functions or the DC_READ functions. However, you can also create an “empty” date/time variable by assigning !DT to a variable name. Here are a couple of examples:

; Creates a date/time structure filled with zeros.

date = {!DT}

PRINT, date

; PV-WAVE prints: { 0 0 0 0 0 0.00000 0.0000000 0}

; Creates 3 structures filled with zeros.

date1 = REPLICATE({!DT}, 3)

PRINT, date1

; PV-WAVE prints the following:

; { 0 0 0 0 0 0.00000 0.0000000 0}

; { 0 0 0 0 0 0.00000 0.0000000 0}

; { 0 0 0 0 0 0.00000 0.0000000 0}

note

When you use the DC_READ functions with the DT_Template keyword to import and convert data, you must use this REPLICATE method to create an “empty” array variable containing date/time structures. Once you have created this array variable, you can read date/time data from a file into the variable. See "Creating Plots with Date/Time Data" for examples.

Version 2017.0