Date Functions

CDate

CDate(Value)

Converts Value to a Date. Accepts strings, OA date numbers (Double), or an existing Date value. Returns Nothing if the value cannot be converted.

Returns: Date

Examples:

CDate("2024-01-15")
CDate(OrderDate)

Date

Date(Year, Month, Day, Hour, Min, Sec, mSec)

Constructs a Date from its individual components.

Parameter Description
Year Four-digit year
Month Month (1–12)
Day Day of month (1–31)
Hour Hour (0–23)
Min Minute (0–59)
Sec Second (0–59)
mSec Millisecond (0–999)

Returns: Date

Examples:

Date(2024, 6, 15, 8, 30, 0, 0)   ' 2024-06-15 08:30:00

DateAdd

DateAdd(Interval, Number, Date)

Adds a quantity of time to a date.

Parameter Description
Interval Time unit string (see table below)
Number Number of units to add (negative to subtract)
Date Starting date

Interval strings:

String Unit
yyyy, yy, year Year
q, quarter Quarter
m, month Month
y, day of year Day of year
d, day Day
w, weekday Weekday
ww, week of year Week
h, hour Hour
n, min, minute Minute
s, sec, second Second

Returns: Date

Examples:

DateAdd("d", 30, OrderDate)        ' add 30 days
DateAdd("m", -3, Now)              ' subtract 3 months
DateAdd("h", 8, ShiftStart)        ' add 8 hours

DateDiff

DateDiff(Interval, Date1, Date2)

Returns the difference between Date1 and Date2 expressed in the specified interval. The result is Date2 - Date1, so a positive result means Date2 is later.

Parameter Description
Interval Time unit string (same as DateAdd, plus ms/milliseconds)
Date1 Start date
Date2 End date

Returns: Long (or Double for milliseconds)

Examples:

DateDiff("d", StartDate, EndDate)      ' days between dates
DateDiff("h", ShiftStart, ShiftEnd)    ' hours worked
DateDiff("ms", t1, t2)                 ' elapsed milliseconds

DatePart

DatePart(Interval, Date)

Extracts a single component from a date.

Parameter Description
Interval Part to extract (same interval strings as DateAdd, except ms)
Date Source date

Returns: Integer

Examples:

DatePart("yyyy", OrderDate)    ' extract year
DatePart("m", OrderDate)       ' extract month number
DatePart("d", OrderDate)       ' extract day of month
DatePart("h", LogTime)         ' extract hour

IsDate

IsDate(Value)

Returns True if Value can be interpreted as a valid date.

Returns: Boolean

Examples:

IsDate("2024-01-15")    ' True
IsDate("hello")         ' False
IsDate(OrderDate)

MCSecToDate

MCSecToDate(MicroSeconds, [AdjustFromUTC] = False)

Converts a microsecond timestamp (100-nanosecond ticks since the Unix epoch) to a Date.

Parameter Description
MicroSeconds Timestamp in microseconds since 1970-01-01 00:00:00
AdjustFromUTC (optional) If True, converts the UTC time to local time. Default False.

Returns: Date

Examples:

MCSecToDate(PLCTimestamp)
MCSecToDate(PLCTimestamp, True)   ' convert from UTC to local time

MSecToDate

MSecToDate(MSecs, [AdjustFromUTC] = False)

Converts a millisecond timestamp (milliseconds since the Unix epoch 1970-01-01 00:00:00) to a Date.

Parameter Description
MSecs Milliseconds since 1970-01-01 00:00:00
AdjustFromUTC (optional) If True, converts the UTC time to local time. Default False.

Returns: Date

Examples:

MSecToDate(EpochMs)
MSecToDate(EpochMs, True)

PLCDate

PLCDate(YYMM, DDHH, MMSS)

Decodes a PLC-format packed date where each argument packs two fields into a single number. The year is interpreted as 2000 + YY.

Parameter Format Description
YYMM YYMM Year (2-digit) × 100 + Month
DDHH DDHH Day × 100 + Hour
MMSS MMSS Minute × 100 + Second

Returns: Date (or DBNull if the date is invalid)

Examples:

' Decodes to 2024-06-15 08:30:45
PLCDate(2406, 1508, 3045)

SecToDate

SecToDate(Secs)

Converts a second-based Unix timestamp (seconds since 1970-01-01 00:00:00) to a Date. The result is in local time (no UTC adjustment).

Returns: Date

Examples:

SecToDate(UnixTimestamp)

Year

Year(Value)

Extracts the year from a date value.

Returns: Integer

Examples:

Year(OrderDate)
Year(Now)

Tip: Use DatePart for extracting month, day, hour, and other date parts. Year is a convenience shortcut for DatePart("yyyy", ...).