Retrieving and setting time/date values

Concatenating date-only and time-only fields

Concatenating date-only and time-range

Related links:
Iris Sample Calendar Database download

Creating a Calendar view in Notes

Integrating C&S into a group application

Get the PDF:
(178Kb)

Overview
Calendaring and Scheduling (C&S) is one of the hottest features of Notes 4.5. C&S components such as the Calendar View rely heavily on time/date fields to store and retrieve values using Notes rich Time/Date format. While Time/Date specifies the basics, such as the day, month, year, and hours, minutes, seconds, it also captures other important time-related attributes, such as time zones. For example, with Notes Time/Date time zone information, an East Coast user can enter a time value and a West Coast Notes user will see these same time/date values automatically converted to Pacific time. Similarly, Time/Date translates dates whether entered using the standard day/month/year or some international syntax. If implemented properly, Time/Date formats can be retained from function to function.

Besides formatting the time/dates properly, you should make sure that these values are as simple as possible for the user to input. New time/date graphical controls make it easy to pick dates or enter a time or range of times with a few mouse clicks. Intuitive data entry and consistent time/date format increase the reliability of your C&S and other time/date-based applications, especially in more complicated applications that cross time zones and are shared among international sites.

Collecting time/dates with New Graphical Controls
Make time/date data entry easy. In Notes R4.5, you can include new graphical date and time control fields to simplify time/date entry in forms. The date control is a calendar-style popup that lets users select the date, month, and year. Similarly, the time control allows the user to select either a single time value, such as 3:00 PM, or a range of time, such as 1:00 PM - 2:00 PM, using a Lotus Organizer-like sliding bar. These controls are used in the Notes R4.5 Mail Calendaring & Scheduling (C&S) feature, but you can use these controls in your own applications that include a date or time.

Date Control


Time Control

Time-Range Control


Creating time/date Control Fields
All time/date control fields are objects in Notes Layout Regions, whether youre creating a date, time, or time-range control. If your form does not yet have a region, youll need to create one.

Date Control Fields
1. Create a new form or open an existing form in design mode.
2. Create a Layout Region anywhere on the form.
3. Create a new field in the Layout region. Name the field anything you want.
4. Set the "Show" property to "Date."
5. Be sure "Allow multi-values" is unchecked.
   
   

Time Fields
1. Create a new form or open an existing form in design mode.
2. Create a Layout Region anywhere on the form.
3. Create a new field in the Layout Region.
4. Give the field any name you want.
5. Set the "Show" property to "Date".
   
   
   
6. Set Allow multi-values unchecked for time control and checked for a time-range control.

Time-Range Fields
Time-range fields are nearly identical to time-only fields except for a couple of property differences:

1. Be sure Allow multi-values is checked.
2. On the Options property page, select Blank Line for the Input and Display separators.
   
   

Again, for time and time-range field control types, it's important that the Show and Allow multi-values are properly set, or your date control will not display.

Retrieving and Setting time/date Values
Hang on to what you've got. Time/date fields contain a wealth of information, including basic Time/Date values and time zone info. This is important information, especially when developing applications that span multiple time zones and you want a C&S or other time event to be displayed or acted on accurately based on the zone. If you're not careful, you can incorrectly set and retrieve Time/Date fields. Some of these problems are created by LotusScript when it stores and retrieves Time/Date values, while other problems get introduced when you use the separate date and time controls.

Doing It Right: Retrieving Time/Date Fields within LotusScript
Use the NotesDateTime or NotesDateRange classes to retrieve Time/Date values from documents. You might be tempted to simply retrieve a Time/Date value as a NotesDocument property. For example, the CalendarDate field could be retrieved as:

Messagebox note.CalendarDate(0)

But let's look at what happens. The Notes Time/Date format gets converted to a LotusScript Time/Date variant. The Time/Date variant doesn't store such attributes as time zone or Notes Time/Date format options, meaning that this information gets lost. The result: valuable Time/Date information is stripped, and your application may not do what you expected.

The preferred method of retrieving Time/Date values is to use the NotesItem class in conjunction with the NotesDateTime and NotesDateRange classes. Below is an example of script that uses Time/Date values from a NotesDocument object to preserve the Time/Date attributes.

Iris Sample Calendar Database
You can find Time/Date and other C&S-related samples in the Iris Sample Calendar database, which contains sample forms and script that are referenced by this article and that you can later use as you develop your own Time/Date-specific applications. As you might expect, the Sample Calendar database also contains examples of Calendar Views. (See Cathy Duffy's recipe on "Creating a Calendar view in Notes for more information.")

Concatenating Date-Only and Time-Only Fields
Collecting date and time information separately makes perfect sense, and segregating your date and time fields for date entry is logical for your users. But take special care later when trying to use both fields later in formulas, especially Calendar Views. For example, in the Calendar Entry form included in the Sample Calendar database, one of the types of Calendar Entry documents the user can create is a Reminder. A reminder tell the user that some action needs to be performed at that time. Typical reminders might be to call a coworker at 1:00 PM, leave work at 4:30 PM, etc. When users create a Reminder, they are given a date control and a time control. To position the reminder in the correct date and time slot of the Calendar view, the date portion of the date control must be combined with the time portion of the time control to create a complete Time/Date field.

'get the reminder time
Set remitem = note.GetFirstItem("ReminderTime")
'create a new DateTime object for the startdatetime
Set remdt = New NotesDateTime(dateitem.DateTimeValue.DateOnly & " " & remitem.DateTimeValue.TimeOnly)
'set the StartDateTime -> this is used in the Calendar for displaying the time of the Reminder
Set note.StartDateTime = remdt
'update the ReimnderTime item; this represents the Time control
'this preserves date/time properties across timezones and different date formats
Set note.ReminderTime = remdt
'update the StartDate item; this represents the Date control
'this preserves date/time properties across timezones and different date formats
Set note.StartDate = remdt
'we remove these fields since they aren't required by Reminders
Call note.RemoveItem("EndDateTime")
Call note.RemoveItem("TimeRange")

Concatenating Date-Only and Time-Range
Finally, the benefits of entering dates separate from a time range comes back to haunt you when trying combine the two values. In the Calendar Entry form included in the sample Calendar database, another type of Calendar Entry document the user can create is an Appointment. An appointment is a document that will appear on the user's Calendar that will tell her that an event occurs for a given time-period. Typical appointments might be getting your car serviced from 10:00 AM until 1:00 PM, a meeting from 9:30 AM - 10:00 AM, etc. When users create an appointment, they are given a date control and a time-range control. In order for this document to appear in the correct date and time slot, as well as mark off the duration of the appointment, you need to create two fields:

StartDateTime: Contains the date portion of the date control and combined with the time portion of the first element of the time control to create a time/date field.

EndDateTime: Contains the date portion of the date control and combined with the time portion of the second element of the time control to create a time/date field.

Both field names are arbitrary. Notice the formulas for each.

'get the TimeRange item
Set tritem = note.GetFirstItem("TimeRange")
'set the text value of the trdr DateRangeObject to the tritem text value
trdr.Text = tritem.Text
'instantiate two DateTime objects; one is the start date/time and the other is the end date/time
Set startdt = New NotesDatetime(dateitem.DateTimeValue.DateOnly & " " & trdr.StartDateTime.TimeOnly)
Set enddt = New NotesDateTime(dateitem.DateTimeValue.DateOnly & " " & trdr.EndDateTime.TimeOnly)
'update the backend note StartDateTime and EndDateTime items
'these items are used by the Calendar view
'we set the fields = the DateTime objects to maintain data and faster performance
Set note.StartDateTime = startdt
Set note.EndDateTime = enddt
'we need to update the StartDate field, which represents the DateControl
'this preserves date/time properties across timezones and different date formats
Set note.StartDate = startdt
'we need to update our DateRangeObject so we can update the TimeRange field
'the TimeRange field represents the Time control and needs to be updated to preserve date/time properties across timezones and different date formats
Set trdr.StartDateTime = startdt
Set trdr.EndDateTime = enddt
'finally, update the TimeRange field; the field will only display the time range even though we are storing a date with it
Set note.TimeRange = trdr
'although the time control currently does not allow day-overlapping, we still check
If startdt.TimeDifference(enddt) > 0 Then
enddt.AdjustDay(1)
Set note.EndDateTime = enddt
End If

ABOUT THE AUTHOR
Ryan has been with Iris since June of 1996. He was previously employed by Lotus and has also worked for a Lotus Premium Business Partner. At Iris, Ryan is one of the developers who worked on Calendaring & Scheduling in the Notes R4.5 Mail template and will continue working on this feature for future releases. During off hours, he is often found playing Quake™ or Red Alert™ with fellow Iris developers.

Copyright 1997 Iris Associates, Inc. All rights reserved.