Manage Learn to apply best practices and optimize your operations.

LotusScript Date Time

A LotusScript date time can either be a date, a time or both.

Here are a few string representations of LS Date/Time:
30/02/2000 10:32:42

Opposed to NotesDateTime objects, a LS Date/Time does not contain hundreds of seconds, neither a time zone. Any time you need to handle dates or times (or both) in script without the need for a time zone, LS Date/Time should be preferred to NotesDateTime objects.

Note that a LS Date/Time is internally stored as a number. Consequently a LS DateTime can be converted to the double data type. The integer part represents a serial day counted from the date January 1, 100 AD (BEWARE, January 1, 100 is not day # 0 : day #0 = December 30th 1899 => January 1, 100 AD = day # - 657434). The fractional part represents the time as a fraction of a day, measured from midnight on the preceding day.

How do you create/set a LS Datetime

You may use any of the following functions:

Today (e.g. var = Today ?returns today?s date without any time component)
Now (e.g. var = now ?returns current date and time )
Datenumber(year, month, day) (e.g. var = datenumber(2000, 03, 20) returns the date March, 20th 2000)
Timenumber(hours, minutes, seconds) (e.g. var = Timenumber(14, 42, 26) returns the time 14:42:26)

The script below returns Today's date:
dim var as variant
var = today
Print var ?prints today?s date

The script below returns the current date and time:
dim var as variant
var = now
print var ?prints the current date and time

The script below returns the time 9h45m32s
dim var as variant
var = timevalue(9,45,32)

The script below returns the date February 23rd 1995
dim var as variant

How to get the date only or time only part of a LS DateTime

DateValue function (e.g. datevalue(datenumber(1999,2,4) + timenumber(23,45,00)) returns 4/2/1999

TimeValue function (e.g. Timevalue(datenumber(1999,2,4) + timenumber(23,45,00)) returns 23:45:00

You may also convert the LS DateTime to the double data type and use the integer part for the number of days since 30/12/1899 or the decimal part for the fraction of a day that the time represents. Note that since LS Date-times are stored as numbers, you may convert a number to a date.

e.g. Cdat(36550,25) represents 25/1/2000 8:00:00

Operations : Addition, subtractions

You may add or substract LS DateTimes. However, you have to make sure that the variables you use are of the data type 7 (Date/Time) and not of the data type 8 (string).

To better understand the examples below, I advise you to copy and paste the examples below in an agent and to enable the script debugger to see the string representations of the variables.

The script below returns today at 9 o?clock
dim var as variant
var = today + Timenumber(9,0,0)
print var ?prints today?s date followed by 09:00:00

The script below returns the date/time January 2nd 2002 at 10:43:00
dim var as variant
var = Datenumber(2002,1,2) + Timenumber(10,43,0)
print var ?prints 1/2/2000 10:43:00

The script below returns the time 17:30:00
dim var as variant
var = Timenumber(10,0,0) + Timenumber(6,0,0) + Timenumber(0,90,0)
print var ?prints 17:30:00

The script below shows you how to add days to a LS Date/Time and what NOT TO DO (in this example, I'm trying to add 6 days to the initial date)
Dim var1 as variant
dim var2 as variant
var1 = Datenumber(1999,12,27)
var2 = Datenumber(0,0,6)
print var1 + var2 ? prints 2/12/2099 because var2 represents the date 5/01/1900 the 6th day since 30/12/1899)
print var1 + 6 ? prints 2/1/2000 which is what you wanted

The script below shows you what happens when the result of 2 added times exceed 24 hours. Note that the time only variant has become a date and time variant!!!
Dim var1 as variant
dim var2 as variant
var1 = Timenumber(17,45,00)
var2 = Timenumber(10,30,00)
print var1 + var2 ?prints 31/12/1899 4:15:00

The script below returns the difference of 2 dates. The result is the number of days in between.
Dim var1 as variant
Dim var2 as variant
var1 = datenumber(2000,4,25)
var2 = datenumber(2000,3,26)
print var1 ? var2 ?prints 29/01/1990 which is the 30th day since 30/12/1899
print cstr(cint(var1 ? var2) ) & "days" ?prints 30 days

The script below shows you the integer part of a LS date/time converted to a number
Print Cstr(Cint(Datenumber(1900,1,4) ) ) ?prints 5
Print Cstr(Cint(Datenumber(1899,12,30) ) ) ? prints 0
Print Cstr(Cint(Datenumber(1899,12,25 ) ) ) ? prints ?5

The script below returns the difference of 2 time values. The result is a decimal number representing the fraction of a day that the difference represents.
Dim var1 as variant, var2 as variant
var1 = Timenumber(17,0,0)
var2 = Timenumber(11,0,0)
tmp = var1 ? var2
print tmp ?prints 6:00:00
print cstr(cdbl(tmp)) ?prints 0,25 since 6 hours represents one fourth of a day

Comparison operators

You can compare variable of the variant data types using the <, >, = signs.

However, do not compare a date only variable with a time only variable or you may get unexpected results. Note that Notes will not raise an error !!!

The script below prints whether today is smaller, greater or equals to the 1st January 2000
Dim var1 as variant
var1=datenumber(2000, 01, 01)
if var1 < today then
print var1 & " < Today"
elseif var1 > today then
print var1 & " > Today"
print var1 & " = Today"
end if

The script below prints "17:30:00 = 17:30:00"
Dim var1 as variant, var2 as variant
var1 = Timenumber(17,30,0)
var2 = Timenumber(16,90,0)
if var1 < var2 then
print var1 & " < " & var2
elseif var1 > var2 then
print var1 & " > " & var2
print var1 & " = " & var2
end if

Retrieving and setting field values

Fields in document store date and time values the same way as the script does which means that you may get time/dates values from fields in a document and set time/dates in fields in a document.

Getting field values

You can do it in several ways:

Use the values property of notesitems to retrieve the date/time (e.g. var = item.values(0) or var = item.values to get an array of LS Date/Times for time multi-value fields)
Var = doc.startdate(0) ? assuming startdate is a field of the Time data-type in the document

Here are a few examples:

In the examples below, I assume the document contains the following date/time fields:
StartDate (date only); StartTime (TimeOnly); FullStart (date and time)

Dim var as variant
Dim item as notesitem
?You can get the value using the following methods/properties
set item = doc.getfirstitem("StartDate")
var = item.values(0) ?assuming the item is not multivalue
? OR
var = doc.StartDate(0) ?Note that var is NOT a variant of the string datatype
? OR
tmp = doc.getitemvalue("StartDate")
var = tmp(0)
dim var as variant
var = doc.StartDate(0) + doc.StartTime(0)
?assuming stardate = 25th Feb 2000 and starttime = 17:30
Print cstr(var) ?prints 25/02/2000 17:30:00
var = var + 2
Print cstr(var) ?prints 27/02/2000 17:30:00
dim var as variant
?Assuming starttime = 17:30
var = doc.StartTime(0) + timenumber(1,15,0)
print cstr(var) ?Prints 18:45:00

Setting field values

You may do it in several manners as well:

Use the values property of notesitems (e.g. item.values = datenumber(1999, 1, 1) )
Doc.startdate = Timenumber(17, 25,0)
Doc.startdate = Cdat(36550,25) ?represents the 36550th day since 30/12/1899
(=25/01/2000) + 0,25 of a day ( = 8 hours)=> startdate = 25/01/2000 8:00:00
A few examples:
Dim var As Variant
var = Datenumber(2000,1,1)
Dim s As New notessession
Dim db As notesdatabase
Set db = s.currentdatabase
Dim doc As New notesdocument(db)
Dim item As notesitem
Set item = New notesitem(doc,"testdate",var) ?this script has created a new
date field named "TestDate" in a new document with the value 1/1/2000
Doc.fullStart = doc.StartDate(0) + doc.StartTime(0) ?This script has set the
value of the fullstart field to the stardate + starttime
Set doc = new notesdocument(db)
dim days as long
days = datevalue(doc.fullend(0)) ? datevalue(doc.fullstart(0)) ?returns the number of days between enddate and startdate
? OR
days = CLng(doc.Enddate(0)) ? CLng(doc.StartDate(0))

Dig Deeper on Domino Resources

  • Favorite iSeries cheat sheets

    Here you'll find a collection of valuable cheat sheets gathered from across the iSeries/ community. These cheat ...