Lotus Domino Designer 8.5 Help

LOTUSSCRIPT LANGUAGE

Dates/Time
LotusScript does not have a date/time data type as such: you can’t declare a variable with date/time values. However, LotusScript does recognize dates internally and provides a set of functions for entering, retrieving, and manipulating date/time values, which are stored as eight-byte (double) floating-point values. The integer part represents a serial day counted from 1/1/100 AD, and the fractional part represents the time as a fraction of a day, measured from midnight. The range of allowable values for a date is -657434 (January 1, 100 AD) to 2958465 (December 31, 9999). 0 is December 30, 1899.

You use Variant variables to hold and manipulate date/time values, which you can produce by calling one or another of the following functions:

Function/Statement	Purpose
CDat Function	Converts a numeric or string expression to a date/time Variant value
Date Function	Returns the system date
Date Statement	Sets the system date
DateNumber Function	Converts year, month, and day, to a date value
DateValue Function	Converts a string to a date value
Day Function	Returns the day of the month (1-31) from a date/time expression
FileDateTime Function	Returns the date and time a file was most recently saved
Format Function	Formats a number, a date/time value, or a string
Hour Function	Returns the hour of the day (0-24) of a date/time expression
IsDate Function	Returns True (-1) if a Variant date/time value, otherwise False (0)
Minute Function	Returns the minute of the hour (0-59) from a date/time expression
Month Function	Returns the month of the year (1-12) from a date/time expression
Now Function	Returns the current system date and time
Second Function	Returns the current second of the minute (0-59) from a date/time expression
Time Function	Returns the system time. The date part of the value is set to 0 or December 30, 1899.
Time Statement	Sets the system date
TimeNumber Function	Converts hours, minutes, and seconds to a fractional date/time value
Timer Function	Returns the time elapsed since midnight in seconds
TimeValue Function	Converts a string to a fractional date/time value
Today Function	Returns the system date (equivalent to the Date function)
WeekDay Function	Returns the day of the week (1-7) from a date/time expression
Year Function	Returns the year as a four-digit integer from a date/time expression

Note Variant variables containing date/time values may be added to produce another Variant variable containing a date/time value. However subtracting one Variant variable containing a date/time value from another will produce a Variant of type Double. You must use the Cdat function to convert the variable back to a date/time value.

You can use the DataType or TypeName functions to determine if a Variant variable holds a date or date/time value. If it does, DataType returns a value of 7, and TypeName returns DATE.

The following examples illustrate the various ways you can derive date and date/time values, how you can assign them to Variant variables, and some of the operations you can then perform on them, such as calculating a time span or determining the day of the week on which a given date will fall.

Suppose that today is October 26, 1994, the time is 7:49:23 AM, and you declare the following variables:

Dim theInstantV As Variant Dim theDateV As Variant Dim theDateValV As Variant Dim myDate As String

This example gets the current date and time by calling the function Now and then assigns the result to a Variant variable, the InstantV:

theInstantV = Now Print theInstantV ' Output: 10/26/94 7:49:23 AM

This example prints the integers corresponding to the day of the month and the hour of the day:

Print Day(theInstantV) & " " & Hour(theInstantV) ' Output: 26 7

This example assigns the current date to the Variant variable, theDateV:

theDateV = Date Print theDateV ' Output: 10/26/94 Print theDateV - 1 ' Output: 10/25/94

This example converts the value of the current date to a value of type Double:

Print CDbl(theDateV) ' Output: 34633 ' Convert a value of type Double ' to a date value, assign it to a ' Variant variable, and print it. theDateV = CDat(34633) Print theDateV ' Output: 10/26/94

This example gets the integer representation of the current year, month, and day; increments the month and day values and assigns the results to some Integer variables; passes them to DateNumber, which calculates the date on the basis of those values and returns it, assigning it to the Variant variable theDateV:

y% = Year(theDateV) m% = Month(theDateV) + 1 d% = Day(theDateV) + 1 theDateV = DateNumber(y%, m%, d%) Print theDateV ' Output: 11/27/94

This example assigns a string that can be interpreted as a date to a String variable, myDate$; then converts it to a date/time value and performs a calculation on it (subtract a day), and returns the resulting date:

myDate$ = "October 28, 1994" Print DateValue(myDate$) - 1 ' Output: 10/27/94 theDateV = DateValue(myDate$) ' Check the data type of the value ' held by the Variant variable theDateV. Print TypeName(theDateV) ' Output: DATE

This example displays the date in a particular print format:

Print Format(DateValue("10-18-14"), "mmm-d-yyyy") ' Output: Oct-18-1914

Note Various products have different interpretations of two-digit years. Notes, for instance, would write the same value as Oct-18-2014.

This example converts the date/time value of the current date to a value of type Double:

Print CDbl(Date) ' Output: 34633

This example converts the date/time value of a particular date to a value of type Double by passing it as a String to DateValue and then passing the result to CDbl, which converts it to a value of type Double:

Print CDbl(DateValue("10-18-14")) ' Output: 5405 Print CDbl(Date) - CDbl(DateValue("10-18-14")) ' Output: 29228

This example calculates the number of days between two dates:

theDateV = DateValue(Date) ' theDateV = 10/26/94 y% = Year(theDateV) m% = Month(theDateV) + 1 d% = Day(theDateV) + 1 theDateValV = DateNumber(y%, m%, d%) ' theDateValV = 11/27/94 Print CDbl(theDateValV) - CDbl(theDateV) ' Output: 32

Note If the dates are subtracted from each other without first converting to Double, the result will be a Variant of type Double.

This example determines which day of the week a particular day falls on — Sunday is 1.

Print Weekday(theDateValV) ' Output: 1

If the integer part of a value is 0, the value is interpreted as a Time value.

Print CDat(0) 'Prints "12:00:00 AM"

Print CDat(.0) 'Prints "12:00:00 AM"

Print CDat(0.0) 'Prints "12:00:00 AM"

Print CDat(0.1) 'Prints "2:24:00 AM"

If the fractional part of a value is 0, the value is interpreted as a Date value.

Print CDat(1.0) 'Prints "12/31/1899"

Print CDat(2.0) 'Prints "1/1/1900"

Print CDat(123456.0) 'Prints "1/3/2238"