Date and Time Properties
When working with dates and times it is often necessary to know the current date and/or time. These values can be extracted from the server's system clock through the properties shown in the table below. These properties are used in several of the date and time functions described below.
| Property |
Value |
| DateString |
Returns a String value representing the current date.
DateString = 06-15-2007 |
| Now |
Returns a Date value containing the current date and time.
Now = 6/15/2007 3:34:34 PM |
| TimeOfDay |
Returns a Date value containing the current time of day (the date is set to 1/1/0001).
TimeOfDay = 1/1/0001 3:34:34 PM |
| Timer |
Returns a Double value representing the number of seconds elapsed since midnight.
Timer = 56074.6734594 |
| TimeString |
Returns a String value representing the current time of day.
TimeString = 15:34:34 |
| Today |
Returns or sets a Date value containing the current date.
Today = 6/15/2007 12:00:00 AM |
Date Functions
Date functions are summarized in the following table with functions described more fully below.
| Function |
Use |
| DateAdd() |
Returns a Date value containing a date and time value to which a specified time interval has been added. |
| DateDiff() |
Returns a Long value specifying the number of time intervals between two Date values. |
| DatePart() |
Returns an Integer value containing the specified component of a given Date value. |
| DateSerial() |
Returns a Date value representing a specified year, month, and day, with the time information set to midnight (00:00:00). |
| DateValue() |
Returns a Date value containing the date information represented by a string, with the time information set to midnight (00:00:00). |
| Day() |
Returns an Integer value from 1 through 31 representing the day of the month. |
| IsDate() |
Returns a Boolean value indicating whether an expression can be converted to a date. |
| Month() |
Returns an Integer value from 1 through 12 representing the month of the year. |
| MonthName() |
Returns a String value containing the name of the specified month. |
| WeekDay() |
Returns an Integer value containing a number representing the day of the week. |
DateAdd() adds a given date interval to a date to produce a calculated date. Its general format is
DateAdd(interval, number, date)
| String |
Unit of time interval |
| d |
Day of month (1 through 31) |
| y |
Day of year (1 through 366) |
| m |
Month |
| q |
Quarter |
| w |
Day of week (1 through 7) |
| ww |
Week of year (1 through 53) |
| yyyy |
Year |
where interval is one of the string values shown in the accompanying table, number gives the number of intervals to add, and date is the date and time to which the interval is to be added. For example, the following function returns the (formatted) date six months from today.
FormatDateTime(DateAdd("m", 6, Today),
DateFormat.LongDate)
Six months from today is Saturday, December 15, 2007.
DateDiff() returns a value giving the number of identified intervals between two dates. Its general format is
DateDiff(interval, date1, date2)
where interval is a string value representing an interval type using the date values shown in the table under the DateAdd() function, and date1 and date2 are the two dates between which the interval is calculated (date1 is subtracted from date2). The following example calculates the number of shopping days until Christmas.
DateDiff( "d", Today, "12/24/" & DatePart("yyyy", Today) )
There are 192 shopping days until Christmas.
Notice that the date2 argument passes "12/24" & DatePart("yyyy", Today). The DatePart() function (see below) extracts the current year from the current date and appends it to the string so that the calculation is always based on the current year.
DatePart() extracts a specified component of a given Date. Its general format is
DatePart(part, date)
where part is a string value representing a date component using the values shown in the table under the DateAdd() function, and date is any Date value. For example, the following function determines the day of the week on January 1, 2010.
WeekdayName(DatePart("w", "01/01/2010"))
January 1, 2010 is on a Friday
DatePart() returns an integer value (Sunday = 1) representing the day of the week. This value is converted into a weekday name with the WeekDayName() function (see below).
DateSerial() returns a Date value based upon integer values representing a year, month, and day. Its general format is
DateSerial(year, month, day)
For example, the function DateSerial(5, 7, 15) returns 7/15/2005 12:00:00 AM. You might wonder why the need to return a date if you already know the date! The point is that the passed values are integers, perhaps collected from a form in which a year, month, and day are selected from drop-down lists. These integer values are combined and converted into a Date type with the DateSerial() function.
DateValue() returns a Date type from a String value representing a date. This function works as a converter to a Date data type. For example, the function call DateValue("January 1, 2005") returns 1/1/2005 12:00:00 AM.
Day() returns an Integer representing the day of the month from a passed date. For instance, function Day(Today) returns 15. This is the same value as returned from the function DatePart("d", Today).
IsDate() returns a Boolean value indicating whether the passed value can be converted into a Date type. This function is handy when testing user input to verify that an actual date has been entered. A function call in the format IsDate("02/31/2005") returns False.
Month() returns an Integer value from 1 through 12 representing the month of the year. It works similar to the Day() function. The function call Month(Today) returns 6.
MonthName() accepts an Integer representing a month of the year and returns a String value containing the name of the month. Used in conjunction with the Month() function, the function call MonthName(Month(Today)) produces June.
WeekDay() returns an Integer value between 1 and 7 (Sunday = 1) representing the day of the week. The function WeekDay(Today) returns 6, which is identical to the value returned by DatePart("w", Today).
WeekDayName() accepts an Integer representing a day of the week and returns a String value containing the name of the day of the week. Used in conjunction with the Weekday() function, the function call WeekDayName(WeekDay(Today)) produces Friday.
Time Functions
Time functions are summarized in the following table with functions described more fully below. Several of the date functions can be applied to time measurements.
| Function |
Use |
| DateAdd() |
Returns a Date value containing a date and time value to which a specified time interval has been added. |
| DateDiff() |
Returns a Long value specifying the number of time intervals between two Date values. |
| DatePart() |
Returns an Integer value containing the specified component of a given Date value. |
| Hour() |
Returns an Integer value from 0 through 23 representing the hour of the day. |
| Minute() |
Returns an Integer value from 0 through 59 representing the minute of the hour. |
| Second() |
Returns an Integer value from 0 through 59 representing the second of the minute. |
| TimeSerial() |
Returns a Date value representing a specified hour, minute, and second, with the date information set relative to January 1 of the year 1. |
| TimeValue() |
Returns a Date value containing the time information represented by a string, with the date information set to January 1 of the year 1. |
DateAdd() adds a given time interval to a time to produce a calculated time. Its general format is
DateAdd(interval, number, time)
| String |
Unit of time interval |
| h |
Hour |
| n |
Minute |
| s |
Second |
where interval is one of the string values shown in the accompanying table, number gives the number of intervals to add, and time is the date and time to which the interval is to be added. For example, the following function returns the (formatted) time twelve hours from now.
FormatDateTime(DateAdd("h", 12, Now), DateFormat.LongDate)
Twelve hours from now is 3:34:34 AM.
DateDiff() can be used to return a value giving the number of identified intervals between two times. Its general format is
DateDiff(interval, time1, time2)
where interval is a string value representing an interval type using the time values shown in the table under the DateAdd() function, and time1 and time2 are the two times between which the interval is calculated (time1 is subtracted from time2). The following example calculates the number of minutes until midnight.
DateDiff("n", TimeString, "11:59:59 PM") + 1
There are 506 minutes until midnight.
It can be a bit tricky working with times because of the roll-over that takes place at midnight. If the value "00:00:00 AM" were to be used in the above example, it would produce -933 minutes, which are the number of minutes from the beginning of the current day. To get around this problem, one minute is added to the time difference until "11:59:59 PM" of the current day.
DatePart() can be used to extract a specified component of a given time. Its general format is
DatePart(part, time)
where part is a string value representing a time component using the time values shown in the table under the DateAdd() function, and time is any Date value. For example, the following function determines the current hour (24-hour clock) of the current day.
DatePart("h", Now)
The current hour of the day is 15
Hour() returns an Integer representing the hour of the day (24-hour clock). For instance, function Hour(Now) returns 15. This is the same value as returned from the function DatePart("h", Now).
Minute() returns an Integer representing the minute of the hour. For instance, function Minute(Now) returns 34. This is the same value as returned from the function DatePart("n", Now).
Second() returns an Integer representing the second of the minute. For instance, function Second(Now) returns 34. This is the same value as returned from the function DatePart("s", Now).
TimeSerial() returns a Date value representing a specified hour, minute, and second, with the date information set relative to January 1 of the year 1. Its general format is
TimeSerial(hour, minute, second)
For example, the function TimeSerial(5, 30, 45) returns 1/1/0001 5:30:45 AM. As in the case for the DateSerial() function, integer values are combined and converted into a Date type.
TimeValue() returns a Date type from a String value representing a time. This function works as a converter to a Date data type. For example, the function call TimeValue("4:35:17 PM") returns 1/1/0001 4:35:17 PM.
Some of the date and time functions appear trivial in isolation. However, you will find them crucial when you begin combining them in applications that relay on accurate reporting of and calculations involving dates and times.