DateSerial Function (Visual Basic)

Returns a Date value representing a specified year, month, and day, with the time information set to midnight (00:00:00).

Public Function DateSerial( _
   ByVal [Year] As Integer, _
   ByVal [Month] As Integer, _
   ByVal [Day] As Integer _
) As DateTime

Parameters

• Year
  Required. Integer expression from 1 through 9999. However, values below this range are also accepted. If Year is 0 through 99, it is interpreted as being between 1930 and 2029, as explained in the "Remarks" section below. If Year is less than 1, it is subtracted from the current year.

• Month
  Required. Integer expression from 1 through 12. However, values outside this range are also accepted. The value of Month is offset by 1 and applied to January of the calculated year. In other words, (Month - 1) is added to January. The year is recalculated if necessary. The following results illustrate this effect:

  • If Month is 1, the result is January of the calculated year.

  • If Month is 0, the result is December of the previous year.

  • If Month is -1, the result is November of the previous year.

  • If Month is 13, the result is January of the following year.

• Day
  Required. Integer expression from 1 through 31. However, values outside this range are also accepted. The value of Day is offset by 1 and applied to the first day of the calculated month. In other words, (Day - 1) is added to the first of the month. The month and year are recalculated if necessary. The following results illustrate this effect:

  • If Day is 1, the result is the first day of the calculated month.

  • If Day is 0, the result is the last day of the previous month.

  • If Day is -1, the result is the penultimate day of the previous month.

  • If Day is past the end of the current month, the result is the appropriate day of the following month. For example, if Month is 4 and Day is 31, the result is May 1.

Remarks

Under Windows 98 or Windows 2000, two-digit years for the Year argument are interpreted based on user-defined computer settings. The default settings are that values from 0 through 29 are interpreted as the years 2000–2029, and values from 30 through 99 are interpreted as the years 1930–1999. For all other Year arguments, use a four-digit year; for example, 1924.

Earlier versions of Windows interpret two-digit years based on the defaults described previously. To be sure the function returns the proper value, use a four-digit Year.

The following example demonstrates negative, zero, and positive argument values. Here, the DateSerial function returns a Date representing the day before the first day of March in the year 10 years before the current year; in other words, the last day of February ten years ago.

Dim EndFeb As Date = DateSerial(-10, 3, 0)

If either Month or Day exceeds its normal range, it is applied to the next larger unit as appropriate. For example, if you specify 32 days, it is evaluated as one month and from one to four days, depending on the value of Month. If Year is greater than 9999, or if any argument is outside the range -2,147,483,648 through 2,147,483,647, an ArgumentException error occurs. If the date specified by the three arguments is earlier than 00:00:00 on January 1 of the year 1, or later than 23:59:59 on December 31, 9999, an ArgumentOutOfRangeException error occurs.

The Date data type includes time components. DateSerial sets all of these to 0, so the returned value represents the beginning of the calculated day.

Since every Date value is supported by a DateTime structure, its methods give you additional options in assembling a Date value. For example, you can use one of the overloaded DateTime constructors to populate a Date variable using the desired combination of components. The following example sets NewDateTime to May 6, 1978 at one tenth of a second before 8:30 in the morning:

Dim NewDateTime As Date = New Date(1978, 5, 6, 8, 29, 59, 900)

Example

The following examples use the DateSerial function to return several dates.

' DateSerial returns the date for a specified year, month, and day. 
Dim aDate As Date 
' Variable aDate contains the date for February 12, 1969.
aDate = DateSerial(1969, 2, 12)
Console.WriteLine(aDate)

' The following example uses DateSerial to determine and display 
' the last day of the previous month. 
' First, establish a starting date. 
Dim startDate = #1/23/1994#
' The 0 for the day represents the last day of the previous month. 
Dim endOfLastMonth = DateSerial(startDate.Year, startDate.Month, 0)
Console.WriteLine("Last day in the previous month: " & endOfLastMonth)

' The following example finds and displays the day of the week that the  
' 15th day of the following month will fall on. 
Dim fifteenthsDay = DateSerial(Today.Year, Today.Month + 1, 15)
Console.WriteLine("The 15th of next month is a {0}", fifteenthsDay.DayOfWeek)

Requirements

Namespace: Microsoft.VisualBasic

Module: DateAndTime

Assembly: Visual Basic Runtime Library (in Microsoft.VisualBasic.dll)

See Also

Reference

DateValue Function (Visual Basic)

Day Function (Visual Basic)

Month Function (Visual Basic)

Now Property

TimeSerial Function (Visual Basic)

TimeValue Function (Visual Basic)

Weekday Function (Visual Basic)

Year Function (Visual Basic)

Date Data Type (Visual Basic)

System

Change History

Date	History	Reason
August 2008	Expanded the examples section.	Customer feedback.