Skip to content

DateTime

See Also: Declaring Variables, Variable Declaration Commands, Time and Date Functions, Struct, Date, Time, TimeSpan

Purpose

Declares one or more DateTime variables.

Syntax

To declare DateTime variables:

DateTime {identifier} [… {identifier}]

Where:

  • {identifier} is the name of a variable of type DateTime. The first {identifier} is required.
  • {identifier} may be between 1 and 4096 characters in length, must start with a letter, and may not contain spaces. Recommended characters are 0-9, a-z, A-Z, and _ (underscore).

To declare array variables of type DateTime:

DateTime {dimension-list} {identifier} [… {identifier}]

Where:

  • {dimension-list} is a list of one or more array dimensions for the array. A dimension list is declared using square brackets []. One pair of brackets is used to declare each dimension. If the array is static, then you must specify the static size of each dimension between each pair of brackets, i.e., [{size}]. For more information about declaring arrays, refer to Array Variable Assignments.
  • {identifier} may be between 1 and 4096 characters in length, must start with a letter, and may not contain spaces. Recommended characters are 0-9, a-z, A-Z, and _ (underscore).

What It Does

The DateTime command declares DateTime variables. This is useful for storing dates and performing calculations.

A DateTime variable can contain a value in the range of 1/1/-32768 12:00:00.000 AM to 12/31/32767 11:59:59.999 PM.

String conversions to DateTime variables are locale-specific, so use the DateSet function to set a date and the DateAddXXX (DateAddDay, DateAddHour, DateAddMillisecond, DateAddMinute, DateAddMonth, DateAddSecond, DateAddYear) functions to place constant values in a DateTime variable.

Multiple variables may be declared on one command line, with their names separated from each other by spaces.

Typecasting between DateTime and TimeSpan

When you move data between DateTime, TimeSpan, and Date types, automatic casting occurs as follows:

  • Move DateTime to TimeSpan - Always works; data is transferred except month and year, which are set to 0.
  • Move TimeSpan to DateTime - Always works, but DateTime will be invalid unless it happens to be null.
  • Move Date to DateTime - Always works; time portion is all 0.
  • Move DateTime to Date - Does limited Date type check. It simply checks that Month is 1-12 and Day is 1-31. It will advance the date if the Day (29, 30, 31) is too large for the month (legacy Date conversion behavior).
  • Move Date to TimeSpan - Always works; will move date portion to TimeSpan. Day will be added but not Month or Year. Time portion is all 0.
  • Move TimeSpan to Date - Will be an error unless the TimeSpan is null.

DateTime and TimeSpan Arithmetic

DateTime and TimeSpan arithmetic works according to the following table:

Operation Result
DateTime + DateTime error
DateTime + TimeSpan DateTime
TimeSpan + TimeSpan TimeSpan
TimeSpan - TimeSpan TimeSpan (result is always a positive difference)
DateTime - DateTime TimeSpan (result is always a positive difference)
DateTime - TimeSpan DateTime (result is always a positive difference)
TimeSpan + DateTime error
TimeSpan - DateTime error

Examples

Procedure Test
    DateTime dtVar
    Move (DateSetMillisecond(dtVar, 10)) To dtVar
    Move (DateSetSecond(dtVar, 30)) To dtVar
    Move (DateSetMinute(dtVar, 10)) To dtVar
    Move (DateSetHour(dtVar, 10)) To dtVar
    Move (DateSetDay(dtVar, 30)) To dtVar
    Move (DateSetMonth(dtVar, 1)) To dtVar
    Move (DateSetYear(dtVar, 2006)) To dtVar
End_Procedure

This example declares a DateTime variable and initializes it to 01/30/2006, 10:10:30.01 am.

DateTime dtNow
TimeSpan tsWeek
Move (CurrentDateTime()) to dtNow
Move (DateSetDay(tsWeek, 7)) to tsWeek
Move (dtNow + tsWeek) to dtNow

This example adds one week to the current date and time.

DateTime[] dAppointments

This example declares a dynamic array variable named dAppointments, containing an undefined number of elements of type DateTime.

DateTime[5] dAppointments

This example declares a static array variable named dAppointments, containing 5 elements of type DateTime.

DateTime[][3] dAppointments

This example creates a two-dimensional dynamic array variable named dAppointments, containing an undefined number of elements of type DateTime. Conceptually, this represents a rectangular array with an undefined number of rows, each of 3 columns.

You can declare dynamic multi-dimensional arrays where all dimensions are dynamic; these are called jagged arrays.

Notes

  • The DateTime data type uses the Windows Regional Settings for the date and time format when converting to/from string. The time format specified in the Windows Regional Settings does not support milliseconds. So, for the DateTime type, the format for milliseconds is expected to be in fractions of seconds, using the decimal specifier. For example, 1/15/2007 3:03:10.545, where it's 10 seconds and 545 milliseconds, expressed in fractions as 10.545 seconds. Trailing zeroes are normally stripped in a manner consistent with fractional parts, so 10.54 seconds is naturally the same as 10.540 seconds.

  • The DateTime data type can hold invalid DateTime values. Conversion to/from string can be performed on invalid DateTime values without changing the value. For example, Move "11/31/2006" to dtValue is OK. However, when a valid DateTime is required, such as with DateTime arithmetic, error 4523 "The specified DateTime contains an invalid value" will be raised, and the result will be a Null DateTime/TimeSpan.

  • If you need to define a global DateTime variable, you should use the global_variable command to do so.