All Databases Frameworks Archive

September 30 - UDates

UDates

Jesse Feiler, The Philmont Software Mill

Who am I to argue with a cute, curly-haired orphan, but Annie was wrong.

"Tomorrow, tomorrow, I love ya, tomorrow, you're only a day away" she sang (and at

the slightest provo cation).

To those of us who have worked on systems that are time-sensitive, we know that

"tomorrow" is only sometimes a day away. For example:

• in most businesses, the "tomorrow" of Friday is Monday

• similarly, the "tomorrow" of December 24 is December 26 (unless a

weekend in tervenes, or Boxing Day is a holiday, as in England [and in Canada:

Ed.]).

• and, if you are editing a transaction that was entered days ago in order to

fix a typo, you may be processing data as of last week, and the system's idea of

"tomorrow" is actually a week ago.

The code to handle all of this is not particularly obscure, and many of us have written

it-over and over and over again.

From the earliest days on the Mac, we have had very good date and time manipulation

routines available in the toolbox. Recently, the Script Manager incorporated some

rather nifty text-parsing routines that it combines with new date routines to make

everything trans parent, whether you are in Japan or Egypt, and whether you are

interested in this era or in one distant by several millennia.

I decided that once and for all I would take the toolbox routines and combine them into

some MacApp objects that could be used (and overridden) for almost any purpose

involv ing date manipulation. And thus was the UDates unit born.

From a user's point of view, the two most important objects in UDates are the

TDateCluster and the TElapsedTimeCluster. Both are descendants of TCluster and are

designed to be placed in TDialogViews.

Here's a step-by-step description of their behavior. Note that both are initialized to a

"today" date which will be described later. In addition, assume that Saturday and

Sunday are week ends, although UDates allows you to specify any weekend days that you

want.

TDateCluster

Now, as you might expect, the two boxes at the left are editable. In fact, they belong to

a class called TDateEditText which is a descendant of TEditText. TDateEditText objects

are basi cally TEditTexts but with the added functionality that their Validate methods

expect the contents to be a date which is parsable by the Script Manager routines. If

the date doesn't pass the Script Manager parsing, Validate fails and MacApp restores

the previous value. The programmer can thus always assume that there's a valid date

in a TDateEditText.

Finally, the TDateCluster provides the information as to whether the date values it

returns are the result of user data entry or of clicking on the radio buttons. In some

cases, the program is only interested in the start and stop dates shown in the

TDateCluster. In other cases, it is important to know whether the user is after this

week's data (regardless of date) or the data for 3/12 – 3/16 specifically.

Here's the interface to TDateCluster:

TDateCluster = OBJECT (TCluster)

fDateObj: TDateObj;         {a TDateObj, probably set to today}
fFrom, fTo: TDateEditText;  {private - use GetStartStop}

FUNCTION TDateCluster.GetStartStop(

VAR d1, d2: LongDateTime;

VAR rChoice: IDType): BOOLEAN;

PROCEDURE TDateCluster.IDateCluster(aDate: TDateObj);

PROCEDURE TDateCluster.DoChoice(

origView: TView;

itsChoice: INTEGER); OVERRIDE;

PROCEDURE TDateCluster.Fields(PROCEDURE DoToField(

fieldName: STR255;

feldAddr: Ptr;

fieldType: INTEGER)); OVERRIDE;

PROCEDURE TDateCluster.Free; OVERRIDE;

END;

Only IDateCluster and GetStartStop are normally used.

TElapsedTimeCluster

The TElapsedTimeCluster consists of three editable fields: two date-time fields, and one

field which represents the number of hours between the two date-times. Thus, after

posing the TElapsedTimeCluster in the DateSample program, you can enter 1.5 in the

elapsed time field and after any other event in the dialog, the second date-time field

will be adjusted. The TElapsedTimeCluster will take whatever two fields are entered

and calculate the third.

{IElapsedTimeCluster can handle a 0 for d2 (stop time) and/or duration.  If duration is

0, it is calculated. If d2 (stop time) is 0, it is calculated using duration. You might

want to do your own error-checking to make sure that you are passing in good values.

TElapsedTimeCluster makes sure that all three fields are consistent: change fFrom or

fTo, and fDuration is updated. Change fDuration and fTo is changed. (Yes, it could have

been coded the other way, but it wasn't. If you want duration to count backwards from

fTo and modify fFrom, modify the object.) GetStartStop gives you the start and stop

times.}

Here is the interface to TElapsedTimeCluster:

TElapsedTimeCluster = OBJECT (TCluster)

fDateObj:   TDateObj;           {probably today}
fFrom, fTo: TValDateEditText;   {private - use StartStop}
fDuration:  TValEditText;       {private - use GetStartStop}

PROCEDURE TElapsedTimeCluster.Free; OVERRIDE;

FUNCTION TElapsedTimeCluster.GetStartStop(

VAR d1,d2:LongDateTime):BOOLEAN;

PROCEDURE TElapsedTimeCluster.IElapsedTimeCluster(

aDate: TDateObj;

d1,d2: LongDateTime;

duration: comp;

aStyle: TextStyle);

FUNCTION TElapsedTimeCluster.Validate:LONGINT; OVERRIDE;

PROCEDURE TElapsedTimeCluster.Fields(PROCEDUREDoToField(

fieldName:STR255;

fieldAddr: Ptr;

FieldType:INTEGER)); OVERRIDE;

END;

Again, GetStartStop and IElapsedTimeCluster are likely to be the only methods which

you'll call directly. Validate is called for you by TDialogView, but nothing prevents you

from calling it yourself at some other time.

TDateEditText

In the DateSample program, the Set "today" dialog allows you not only to set the

"today," but also to experiment with a TDateEditText field. Typing in "12" sets the date

to March 12, 1990, since the Script Manager defaults to current month and current

year. The Script Manager will recognize non-standard delimiters and-as shown in a

recent Tech Note-its flexibility will allow it in some circumstances to wander off in

very peculiar directions. Fortunately, you can check to see how far afield the parser

has gone and set your tolerance level as low or as high as you want.

{The IEditText and IRes methods initialize all fields. You may want to subsequently

reset fWantDate or fWantTime. Resetting fDidEdit is undefined (polite for "stupid").

fDate is obtainable in alternate formats by calling GetLongDateTime or GetLongDateRec.

}

Here's the interface to TDateEditText:

TDateEditText = OBJECT (TEditText)

fWantDate, fWantTime, fDidEdit, fZeroBlank: BOOLEAN;

fDate: LongDateRec;

PROCEDURE TDateEditText.Fields(PROCEDURE DoToField(

fieldName:STR255;

fieldAddr: Ptr;

FieldType: INTEGER)); OVERRIDE;

FUNCTION TDateEditText.GetLongDateTime(

VAR aDate: LongDateTime):BOOLEAN;

FUNCTION TDateEditText.GetLongDateRec(

VAR aDateRec: LongDateRec): BOOLEAN;

PROCEDURE TDateEditText.IEditText(

itsSuperView: TView;

itsLocation, itsSize:VPoint;

itsMaxChars: INTEGER);

OVERRIDE;

PROCEDURE TDateEditText.IRes(

itsDocument: TDocument;

itsSuperView: TView;

VAR itsParams: Ptr); OVERRIDE;

PROCEDURE TDateEditText.SetDate(

aDate: LongDateTime;

reDraw: BOOLEAN);

FUNCTION TDateEditText.Validate: LONGINT; OVERRIDE;

END;

Once again, the methods shown in bold are the ones which you are likely to call

directly. Note one point about IEditText: it does NOT set the initial value; you have to

call SetDate. It is generally agreed that the IYourObject methods should leave all fields

set to some value (e.g., handles to NIL if not actually allocated). In our recent projects

we have tended to separate the setting of values from the initialization of the object.

Thus, in a project that uses UDates, we have three methods that handle the fields:

1. InstallADate (location, etc.)

2. LoadADate (sets values)

3. UnLoadADate (gets values)

Similar triplets of methods are used for other types of data entry fields. This works

very nicely for cases where one view is used to show and update data from various

database records.

TDateObj

The third major object in UDates is the TDateObj. It is initialized to a given date and to

the weekends and holidays which it should recognize. Thereafter, it can quickly provide

yes terday, tomorrow, next week, etc. as needed. In general, one TDateObj is initialized

for the application and is not reset during program execution.

The interface for TDateObj is not provided here, since it is fairly lengthy and is

provided in the code which follows.

Using UDates

The objects in UDates are designed to be as basic as possible and still provide the

needed functionality. They can be customized in two ways. First of all, they can of

course be overridden to change their behavior. Secondly, there are parameters which

can be set by the program (e.g., do you want both date and time shown in a

TDateEditText field?) to modify their behavior. In general, I have assumed that the

parameter setting will be fairly con stant within an application, and therefore

error-checking for parameters is done only in the Debug version. Both Debug and

NonDebug versions should catch errors which a user might make in data entry.

In addition, the TDateCluster and TElapsedTimeCluster are views that are editable in

ViewEdit to allow a developer to use a specific application's standard fonts and graphic

styles. TElapsedTimeCluster is about as sparse as you can get in terms of text, because

in those cases where it's been used, we have always modified the resource to

incorporate addi tional text fields.

The code which follows is for UDates itself as well as for DateSample, a small

application which uses UDates and to show the results of various commands via

messages in the Debug window.

The code is (I hope) fairly clear and well-annotated, so there's no point in going

through it in detail. I will, however, mention a few points which may be of interest.

Creating a new, generalized unit

All programmers, and MacApp programmers in particular, have sections of code which

they reuse. In my particular repertoire are a FailDBErr routine that I use to trap

Inside Out errors, a unit of utility dialogs, and of course UDates itself. In creating

these units, I've found a few points to be useful:

• Do spend a few extra moments to provide Get and Set routines for

variables of your objects that would normally be visible to the outside world,

even if that outside world is you. In TDateEditText, the GetLongDateRec and

GetLongDateTime functions were the last changes made. At first it seemed silly

to write these functions when the data could easily be found with the field

names. The decision to add the functions was NOT made for reasons of

ideological purity; it was made because some of the manipulation code was

being written several times in my application.

Whenever code is duplicated, that's a clue that it's in the wrong place and

should be moved to a location where it's written once and done with. In UDates,

not every variable is accessible to the outside world; providing Get and Set

methods for all fields of an object is unnecessary (in my humble opinion).

What is necessary is to decide which fields and which common transformations

of them are likely to be necessary, and to provide those.

• Don't think you save time by not having a Fields method for every object.

Even if the Fields method has nothing but the object's title (bClass), it may

well save you from lost time trying to figure out where you are.

• In creating new units that you plan to reuse, take a moment to think of all

possible uses of the unit. For example, we are in the process of creating a

generalized numeric entry object-much like TDateEditText. That object must

be a descendant of TEditText and not of TNumberText. Why? The fMinimum and

fMaximum fields of TNumberText are LongInts. In addition, lots of

TNumberText code assumes LongInt values.

• Don't use standard segment names. Thus you'll find that in UDates, code is

placed into $ADateRes and $ADateFields segments. The –sn option in your

MAMake file will allow you to remap these segments to $ARes and $ADates if

you want to. By keeping your segmentation at least temporarily separate from

normal MacApp segmentation, you can easily make adjustments if you blow up

a segment with the infamous >32000 error.

• Add a local debugging option (such as qTraceDate). You'll notice that this

option tracks procedure entries, sometimes printing parameters out so that

you can see how things are going. Again, by using your own debugging options,

you avoid interfering with MacApp and your other debuggers, so that you don't

get a slew of UDates debugging messages while you're trying to debug a

database problem.

• Consider adding additional debugging code to your unit. Debugging code

turns out to be (in my experience) some of the most reusable code there is.

The bLongDateRec and bLongDateTime Fields options are used all through our

applications.

Creating the clusters

Normally, one has a choice of creating views either from templates or

programmatically. In UDates, the clusters are designed to be created ONLY from

templates-and in fact the appropriate ICluster methods are missing. This is deliberate

and should be considered as an advertisement for ViewEdit. The TDateCluster contains

eight subviews, each of which must be placed, sized, and identified properly in order

for the TDateCluster to work. In addition, the six radio buttons must be named with

appropriate base names-and no one would con sider hard-coding words like "Today" or

"Yesterday," so those would have to be stored in a string resource. The code for doing

all of this initialization is about 50 lines long. In a case like this, I do not think that

template and programmatic creation are equally appropriate: ViewEdit wins hands

down in such a case (even with some of its bugs-which I'm sure will be gone shortly).

Referenced by (3):