NotesDateTime (LotusScript®)

Represents a date and time. Provides a means of translating between the LotusScript® date-time format and the Domino® format.

Containment

Contained by: NotesDateRange, NotesDocument, NotesItem, NotesNoteCollection, NotesSession, NotesUIScheduler

Properties

DateOnly

GMTTime

IsDST

IsValidDate

LocalTime

LSGMTTime

LSLocalTime

Parent

TimeOnly

TimeZone

ZoneTime

Methods

AdjustDay

AdjustHour

AdjustMinute

AdjustMonth

AdjustSecond

AdjustYear

ConvertToZone

New

SetAnyDate

SetAnyTime

SetNow

TimeDifference

TimeDifferenceDouble

Creation

To create a new NotesDateTime object, you can use the following:

  • New
Note: The New method is not supported in COM.
  • CreateDateTime method in NotesSession

Given a string that represents the date and time you want, New creates an object that represents that date and time.

Syntax

Dim variableName As New NotesDateTime( dateTime$ )

or

Set notesDateTime = New NotesDateTime( dateTime$ )

Parameters

dateTime$

String. The date and time you want the object to represent. If you use an empty string (""), the date is set to a wildcard date. The Notes® date-time expressions "Today," "Tomorrow," and "Yesterday" are supported.

Usage

The dateTime$ parameter of New and the CreateDateTime method in NotesSession should specify a date, followed by a space, followed by a time. You can specify a date without a time component, or a time without a date component, but the time zone will not be set.

The following applies when setting a date and time from a String value:

  • The date and time components are interpreted according to the regional settings of the operating system if possible. For example, if the regional setting for dates is M/d/yy h:mm:ss:tt, then "3/4/05 6:07" means 4 March 2005 at 6:07 AM.
  • If the date or time cannot be interpreted using the regional setting, alternate settings are tried until one works. For example, if the regional setting for dates is M/d/yy, then "13/4/05" means 13 April 2005 (using d/M/yy as the alternate setting) and "13/33/05" means 13 May 2033 (using d/yy/M as the alternate setting).
  • If the date or time cannot be interpreted using any setting, a wildcard date is set and the property IsValidDate is set to False.

The LotusScript® functions DateNumber and TimeNumber can be used to avoid dependencies on regional settings. For example, the sum of DateNumber and TimeNumber can be used as the parameter for the CreateDateTime method in NotesSession.

Time zones

When you create a new NotesDateTime object, the time zone setting in Domino® determines the TimeZone property. For example, if the code runs on a computer where the Domino® time zone is set to Eastern Standard Time, the TimeZone property of any new NotesDateTime object is automatically set to 5. The time zone setting also affects the GMTTime and LSGMTTime properties.

If you create a DateTime object without a time component or without a date component, the time zone is invalid and the TimeZone property returns 0. In this case, both LocalTime and GMTTime return the same time value without a time zone appended. If you apply ConvertToZone, the time zone remains invalid and TimeZone remains 0; no error occurs.

Today, Tomorrow, and Yesterday

When you create a new DateTime object using an expression such as "Today," "Tomorrow" or "Yesterday," the value of the date is determined using the current date setting in Domino®. These expressions have no effect on the time component of a DateTime object. To set a DateTime object to the current date and time, specify the time after "Today," "Tomorrow" or "Yesterday" (for example, "Today 12:00:00 AM") or use setNow.

Storing dates in LotusScript®

Unlike LotusScript® date-time variants, Domino® date-time items and NotesDateTime objects store a time zone and hundredths of a second (the hundredths of a second are not visible to the user). Use the NotesDateTime class if you need to store a time zone or hundredths of a second. Use LotusScript® date-time variants if you only need a date and time component without a time zone or hundredths of a second.

Access

To access a date-time value stored in an item on a Notes® document, use the DateTimeValue property in NotesItem.

You can get the operating system date and time separators, and time zone settings through the NotesInternational class.

Example