DTGEN Function

Returns a date/time array variable beginning with a specified date and incremented by a specified amount.

Usage

result = DTGEN(dt_start, dimension)

Input Parameters

dt_start — A date/time variable containing a value representing the first date and time in the new data set.

dimension — Specifies the number of date/time values to generate.

Returned Value

result — A date/time array variable containing the specified number of date/time values.

Keywords

Compress — If present and nonzero, excludes predefined weekends and holidays from the result. The default is no compression (0).

Day — Specifies an offset value in days.

Hour — Specifies an offset value in hours.

Minute — Specifies an offset value in minutes.

Month — Specifies an offset value in months.

Second — Specifies an offset value in seconds.

Year — Specifies an offset value in years.

Note: Only one keyword can be specified at a time. You cannot, for example, specify both years and months in a single DTGEN call. But if you need to add, for example, one day and one hour, you can simply add 25 hours.

Discussion

Each value in the result is offset from the previous value by the amount specified with a keyword.

DTGEN lets you generate date and time data that match a particular dataset. For example, if you have gathered data at regular intervals, but do not have time stamps in your dataset, you can use DTGEN to generate date and time data that corresponds to your data-gathering intervals.

Only whole numbers (including zero) can be used with the keywords to specify the offset between dates and times. Therefore, the smallest unit by which generated dates can be offset is one second. If no keyword is specified, the default offset is one day.

Example 1

This generates an array of date/time structures for consecutive years.

; Create a date/time variable.
date1 = VAR_TO_DT(2005, 3, 26, 6, 28, 50)
; Use DTGEN to create a new date/time variable containing four
; date/time values. The four date/time values represent four
; consecutive years with identical months, days, and times.
date2 = DTGEN(date1, 4, /Year)
PRINT, date2
; PV-WAVE prints the following:
; {  2005  3  26  6  28  50.0000  92235.270  0}
; {  2006  3  26  6  28  50.0000  92600.270  0}
; {  2007  3  26  6  28  50.0000  92965.270  0}
; {  2008  3  26  6  28  50.0000  93331.270  0}

Example 2

The second example shows how to create an array containing date/time structures for every other month of a year.

; Create a date/time variable for January 1, 2002.
date = VAR_TO_DT(2002, 1, 1)
; Create an array variable containing date/time data
; for every other month of the year 2002.
date1 = DTGEN(date, 6, Month=2)
PRINT, date1

; PV-WAVE prints the following:
; { 2002   1   1   0   0   0.000000   91055.000   0}
; { 2002   3   1   0   0   0.000000   91114.000   0}
; { 2002   5   1   0   0   0.000000   91175.000   0}
; { 2002   7   1   0   0   0.000000   91236.000   0}
; { 2002   9   1   0   0   0.000000   91298.000   0}
; { 2002  11   1   0   0   0.000000   91359.000   0}