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/1999
03/12/0240
17:30:00
10:34:53
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)

Examples:
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
var=datevalue(1995,2,23)

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.

Examples:
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 !!!

Examples:
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"
else
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
else
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))

This was first published in November 2000

Dig deeper on Domino Resources

0 comments

Oldest 

Forgot Password?

No problem! Submit your e-mail address below. We'll send you an email containing your password.

Your password has been sent to:

-ADS BY GOOGLE

SearchWindowsServer

Search400

  • iSeries tutorials

    Search400.com's tutorials provide in-depth information on the iSeries. Our iSeries tutorials address areas you need to know about...

  • V6R1 upgrade planning checklist

    When upgrading to V6R1, make sure your software will be supported, your programs will function and the correct PTFs have been ...

  • Connecting multiple iSeries systems through DDM

    Working with databases over multiple iSeries systems can be simple when remotely connecting logical partitions with distributed ...

SearchEnterpriseLinux

SearchDataCenter

SearchExchange

SearchContentManagement

Close