DATE(), DATETIME(), TIME()

Hacker’s Guide to Visual FoxPro
An irreverent look at how Visual FoxPro really works. Tells you the inside scoop on every command, function, property, event and method of Visual FoxPro.

`DATE()`, `DATETIME()`, `TIME()`

DATE(), DATETIME() and TIME() return values for the present. Starting in VFP 6.0, DATE() and DATETIME() can be used to return any specified date or datetime in a Year-2000-compliant format.

Usage

ldDate = DATE( [ nYear, nMonth, nDay ] )
ltDateAndTime = DATETIME( [ nYear, nMonth, nDay
                  [, nHours [, nMinutes [, nSeconds ] ] ] ])
lcTheTime = TIME( [ uShowFractions ] )

Parameter	Value	Meaning
nYear	100 – 9999	The year of the date variable to create. Note that dates in the years 1753 and before could cause problems, because the Gregorian calendar wasn't standardized until then.
nMonth	1 – 12	The month of the variable to create.
nDay	1 – 31	The day of the variable to create.
nHours	0 – 23	Unlike the "strict date" format, this function accepts 24-hour based time. That makes sense—it would be a pain to have to pass two parameters.
nMinutes	0 – 59	The number of minutes to assign to the datetime return value.
nSeconds	0 – 59	The number of seconds in the return value.
uShowFractions	Any type will do	Display the time with tenths and hundredths of a second.

The display of the return values of DATE() and DATETIME() is affected by a number of SET commands. The sequence of month-day-year is determined by SET DATE, the separators between the numbers by SET MARK, and the number of digits shown for the year by SET CENTURY. In addition, SET HOURS changes the time display to 24-hour or 12-hour (with trailing “AM” or “PM”) format. SET SECONDS ON | OFF determines whether the seconds portion of the value is displayed. To complicate matters further, the SET SYSFORMATS command also comes into play with the possibility of applying the user’s system settings to the display. None of these affects what is actually stored in a field—only what is displayed.

As part of the effort to ensure that VFP developers can write Year-2000-compliant code, Microsoft extended the DATE() and DATETIME() functions so they accept all the date and time components as numbers, always returning the correct date or datetime value regardless of the settings of DATE and CENTURY. DATE and CENTURY, especially the ROLLOVER clause, make the resolution of dates by the CTOD() and CTOT() functions unpredictable, and thus these functions were extended.

TIME() always returns a character string in the form “HH:MM:SS” in 24-hour format, with no regard to the SET HOURS setting. It always displays seconds, regardless of the SET SECONDS command (which was added for datetime variables). We think it should respect both. If a parameter is passed (any number, character, null, anything will do), the time is displayed with tenths and hundredths of seconds—impressive, but probably not entirely accurate. In early versions, we calculated actual accuracy around .054 seconds (one-eighteenth of a second). So does anyone really know what time it is? Does anyone really care?

Example

? "TODAY IS ", DATE()  && returns "04/15/1998"
* Calculate the date of the next New Year's Day
ldNewYears = DATE(1+YEAR(DATE()),1,1)
? DATETIME()           && returns "04/15/1998 23:15:22"
? TIME()               && returns "23:15:22"
? TIME(1)              && returns "23:15:22.15"