6.1.2.4 DateTime Module

Note

This section describes the implementation of MS-VBAL §6.1.2.4 DateTime Module.

The DateTime module is represented in the SDK by the interface IStdDateTimeModule, and implemented by StdDateTime.

A function the specification declares with no As clause returns a Variant, which holds the type its description says: DateDiff a Long, DatePart and the functions of a part of a date an Integer, and DateAdd, DateSerial, DateValue, TimeSerial and TimeValue a Date.

The Session Is the System

The properties read the clock of the session (ISessionClock), and Calendar is its state too. The session is the program's system: assigning Time ("Sets the system time") sets the time of the session's clock, which goes on from there as the machine's does; the machine's own clock is never changed. An End resets both, to the machine's clock and the Gregorian calendar.

Now, Date and Time are to the second; Timer has the fraction of a second the clock has ("The sub-second resolution is implementation dependent"). Date$ is mm-dd-yyyy, in the current calendar, and Time$ is hh:mm:ss.

Dates

A Date is the serial number of OLE Automation: days since December 30, 1899, with the time as the fraction of a day, whose sign is the date's even before 1899 (−1.25 is December 29, 1899 at 6:00). The arithmetic is done on a line of time and turned back into a serial, which is how an hour added to a date before 1899 goes forward. The range of dates is January 1, 100 to December 31, 9999.

The parts of a date are those of the date rounded to the nearest second, as MS-VBA has them: Second(#0:00:00.6#) is 1.

The year, the month, the week and the day are in the current calendar: Gregorian, or Hijri (the tabular, "Kuwaiti" calendar of System.Globalization.HijriCalendar) when Calendar is vbCalHijri. Hours, minutes and seconds are the same in both. A date before the first day of the Hijri calendar (July 18, 622) has no Hijri year, month or day.

Errors

MS-VBAL §6.1.2.4 names error 5 for an interval that is none and for a DateAdd before the year 100, and says only that "an error occurs" elsewhere, so the rest is decided here:

When	Error
An interval that is none of yyyy, q, m, y, d, w, ww, h, n, s (in any case)	5
A result outside the range of dates (DateAdd, DateSerial, TimeSerial)	5
A date before the first day of the current calendar	5
A first day of the week, a first week of the year or a calendar that is no value of its enumeration	5
A DateDiff that does not fit a Long (seconds across the centuries)	6
A Null date given to DateAdd, DateDiff or DatePart	94: it is let-coerced like any other value; only the functions of a part of a date say Null returns Null
A string that is no date (DateValue, TimeValue, Time = )	13, the error of its let-coercion

What the Specification Leaves Open

• Weekday counts from FirstDayOfWeek as 1, as MS-VBA does: Weekday(d, vbMonday) of a Monday is 1. The specification's table lists the constants with Sunday as 1, which is the count for the default vbSunday.
• DateDiff: a weekday ("w") is counted on the day of the week of Date1, and a calendar week ("ww") on FirstDayOfWeek; both count Date2 and not Date1, as the specification says. FirstWeekOfYear is validated and has no effect: no interval of DateDiff counts weeks of the year.
• DatePart("ww") follows FirstWeekOfYear: under vbFirstFourDays and vbFirstFullWeek, a day in the first days of January can be in the last week of the year before (January 1, 2021 is week 53 with vbMonday, vbFirstFourDays).
• DateAdd rounds Number to the nearest whole number half to even, as the language rounds; "w" adds days, like "d" and "y".
• TimeValue is declared to take a String, and also said to return Null of Null: a Null cannot be passed to a String parameter, and is error 94.
• Date has no Property Let in the specification. MS-VBA's Date statement (which sets the system date) is not part of it: Date = x is error 451.
• A string given to DateValue or TimeValue is read by the let-coercion to Date (MS-VBAL §5.5.1.2.4), in the Gregorian calendar whatever Calendar is.

6.1.2.4.1 Public Functions

Note

This section describes the implementation of MS-VBAL §6.1.2.4.1 Public Functions.

§	Member	Notes
6.1.2.4.1.1	DateAdd	One month after January 31 is the last day of February.
6.1.2.4.1.2	DateDiff	Counts the boundaries of the interval: December 31 to January 1 is a year.
6.1.2.4.1.3	DatePart
6.1.2.4.1.4	DateSerial	A two-digit year: 0-29 are 2000-2029, 30-99 are 1930-1999; Hijri 0-99 are 1400-1499.
6.1.2.4.1.5	DateValue
6.1.2.4.1.6	Day	Null of Null.
6.1.2.4.1.7	Hour	Null of Null.
6.1.2.4.1.8	Minute	Null of Null.
6.1.2.4.1.9	Month	Null of Null.
6.1.2.4.1.10	Second	Null of Null.
6.1.2.4.1.11	TimeSerial	Before midnight is the day before: TimeSerial(-1, 0, 0) is 23:00 on December 29, 1899.
6.1.2.4.1.12	TimeValue
6.1.2.4.1.13	Weekday	Counted from FirstDayOfWeek as 1; Null of Null.
6.1.2.4.1.14	Year	Null of Null.

6.1.2.4.2 Public Properties

Note

This section describes the implementation of MS-VBAL §6.1.2.4.2 Public Properties.

§	Member	Notes
6.1.2.4.2.1	Calendar	State of the session; Gregorian until set.
6.1.2.4.2.2	Date/Date$	Date is a name in an expression (MS-VBAL §3.3.5.2 reserved-name), and a type only in a declaration.
6.1.2.4.2.3	Now
6.1.2.4.2.4	Time/Time$	Time = sets the time of the session's clock, never the machine's.
6.1.2.4.2.5	Timer

---

⏮️ RD-VBAL §6.1.2.3 Conversion Module | ⏭️ RD-VBAL §6.1.2.5 FileSystem