|
Volume Number: | 4 | |
Issue Number: | 3 | |
Column Tag: | Forth Forum |
Time Manager Reminder DA
By Jörg Langowski, MacTutor Editorial Board, Grenoble, France
Jörg Langowski is a bio-chemical engineer for a french concern and is a founding and current board member of MacTutor. He can be reached at EMBL, c/o I.L.L. 156x, Grenoble, Cedex, France F-38042. We encourage European authors to contact Jörg directly about submissions to MacTutor.
“Using the Time Manager”
One thing I always wanted to have on my Mac is some utility that reminds me of an appointment, no matter what I’m doing on the machine at any given time. On our VAX, for example, there is this great program called Reminder which sits in the background and will beep at you when your next appointment arrives.
In the new system (128K ROMs and up) there exists a set of routines called the Time Manager. I thought it would be a good idea to show you their usage in developing a Reminder utility similar to the one on the VAX. In the process, I’ll show you how to work with modeless dialogs from a DA, how to call memory manager dependent traps from a time manager task, and some more.
The Time Manager
The Time manager is used to execute a task at a predetermined time. Its routines are documented in IM Vol. 4. All time manager tasks are described by entries in the time mamager queue, where each element has the following format:
header TMtask 14 allot 0 CONSTANT qLink 4 CONSTANT qType 6 CONSTANT tmTask 10 CONSTANT tmCount
That means, the queue entry looks just like a regular queue element, with two 4-byte fields, tmTask and tmCount, relevant to our task. tmTask contains a pointer to the routine to be executed, and tmCount is used by the system to count down the elapsed time. When it has reached zero, the task at tmTask will be executed.\
Three routines are provided by the time manager: InsTime, called with a pointer to the queue element in A0, will insert this queue element into the time manager queue. PrimeTime, with the queue element pointer in A0 and a 32-bit count in D0, will schedule the routine specified in that queue element to be executed after count milliseconds have elapsed. RmvTime, with a pointer to the queue element in A0, will remove the queue element. The Mach2 interface to these routines is given at the beginning of listing 1.
Fig. 1 Our Reminder DA lets Mac Widows post alerts for late night programmers!
Programming the Reminder utility
The strategy to follow seems very simple: we create a desk accessory that allows us to enter a message text and a delay time, that desk accessory will then setup a queue element with a pointer to a routine that displays an alert box containing that string.
Thinking about it, programming such a utility is not quite so simple. First of all, the routine passed to the time manager for execution cannot be part of the desk accessory. We’d like to enter appointments that are due in several hours or days (32 bits of milliseconds, unsigned, give a maximum possible delay of 49.7 days), and we’ll most probably have left the application where the desk accessory was started by then. Under MultiFinder this doesn’t matter, but under Finder, the desk accessory would have been closed, leaving the task pointer point to anything but the desired code.
My first thought was to use a ‘stick-around’ desk accessory that would automatically restart itself after an involuntary close, like I described earlier. But it is actually much easier to put a copy of the routine to be executed into a small block of system heap, leaving it independent of the DA. Then, one has to take caution that the routine, once executed, will remove its own queue entry and dispose of its own memory.
The second problem is that a time manager task may be executed at any time, interrupting whatever else is being done at that moment. For the same reason as in the case of VBL tasks, we may not call any routines from the time manager task that can move things around in the heap. If we did, there would be a chance that the interrupt occurs right in the middle of a memory manager operation, or while a handle hangs around dereferenced somewhere.
The time manager task must therefore be rather simple. I use the same trick as I described for the ‘stick-around’ DA, patching SystemTask from the scheduled routine. The next time SystemTask is called (which should happen rather soon in any benign application) the patch routine will be executed, which then can do the more involved stuff such as drawing an alert box.
Now look at the first part of the example: the routine that is executed by the time manager is contained between the markers mytask and mytask.end. The first bytes of this block contain the queue element. The name string ‘Reminder’ follows for debugging purposes. Some local variable space is reserved, where the original SystemTask trap address, the alert ID and the alert message can be kept. The SystemTask patch routine alertMe follows. It will display a note alert with the message in parameter ^0, unlock the alert, remove the time manager queue element and dispose of the memory allocated for itself.
Fig.2 After time has elapsed, an alert pops up!
alertMe is patched into SystemTask by the following routine, wakeMe, which is the one first executed by the time manager. A pointer to wakeMe will be contained in the tmTask field of the queue element at the beginning of the block. Since we do not know yet where this routine will be located, we’ll have to install the pointer after moving the code into the system heap.
As you see, the code between mytask and mytask.end is completely self-contained (as long as the ALRT resource can be found). We may therefore move any number of these little code blocks into the system heap and install their queue elements using the time manager; each will be executed at its scheduled time and display its little message. Appointment ‘objects’, so to say.
The desk accessory
The DA is used to install the tasks. It is a very simple DA which just draws up a modeless dialog box with two editable text items. The dialog window will have the driver reference number in its windowKind field, so that the system will handle mouse down events in the close box and drag region. Only when the event is passed through to the DA, windowKind will be temporarily set to 2 (dialog window), so that IsDialogEvent and DialogSelect work correctly.
When the OK button in the dialog box has been clicked, the dialog handler will be invoked. This routine converts the string in item 4 to a number, the delay in seconds, and gets the message to be displayed after this delay (item 3). These parameters are passed to install.wakeup, together with the alert ID. install.wakeup gets the wakeup routine described above from the resource file and installs a copy of it in the system heap. It saves a pointer to the wakeup routine in the tmTask field of the queue element, stores the alert ID and the message string at their appropriate positions and then schedules the routine for execution by calling InsTime and PrimeTime.
Things missing
The desk accessory described here is already quite useful ‘as is’. However, one could include some improvements that I leave as an exercise for you (or me, for that matter):
- Input of the appointment time in standard date format.
- Keeping a list of appointments that can be displayed and edited.
- Saving this list to a file every time it is changed; this file is then checked on system startup and the pending appointments rescheduled automatically.
I wish you good luck with those experiments; now, some mail that I recently received.
Feedback Dept.
“Dear Jörg,
I read your recent column in MacTutor with great interest and would like to obtain the addresses for Serge Rostan and also for Winsoft. [Serge Rostan, “TechnoPro”, rue Faraday, F-78180 Montigny le Bretonneux, France, phone (33) 1 30 45 26 62, and Winsoft, 34, boulevard de l’Esplanade, F-38000 Grenoble, France, phone (33) 76 87 56 01 - JL].
We are in the process of completing a book on fonts for the Macintosh for European and many other non-Roman languages. It will also show specimens of over 2000 bit-mapped and several hundred PostScript fonts.
If you can suggest any font vendors that do not advertise in US Macintosh magazines, it would be very helpful [not off the top of my head, but I’ll look around - JL].
As you may know, Apple refuses to sell European keyboards in the US, even to certified developers. Users here must cultivate acquaintances overseas and buy them indirectly. Do you know whether Apple tries to prevent the export of such keyboards from Europe? We would like to be able to list a commercial source for such keyboards in our book, but do not want to cause difficulties for anyone there. If they are readily available for export, we would appreciate the name of a recommended source.
[You address a problem that I’ve encountered myself. There seems no way for Macintosh developers in France to get other than French keyboards through the developer program. However, there is at least one Apple dealer in Grenoble who sells the US keyboard on request; we have several international research institutions here, so there’s a market. I’ll send you addresses of some Apple dealers in Germany and France that you might be able to order from.
I don’t think there are any export restrictions imposed by Apple on non-US keyboards into the US (unless you re-sell them to Colonel Kh...). The problem most probably is the bureaucracy that inevitably builds up in a large corporation, even one like Apple that for a while tried to maintain some ‘non-conformistic hacker’ kind of image. Which it is trying to forget at a rapid rate, I presume. Someone, it seems, must have set a guideline that in country X only systems localized for X will be sold, with few exceptions. The only way I get the most recent US system updates is through US sources, too. Funniest of all: The MacII system that I finally got a week ago (yes, I love it), has English documentation, US system disks (but 4.1, not 4.2, which is not officially released at the time I write this), but no way can I get a US keyboard. Probably the people at Apple France just wanted to be nice and ship me as many US parts as possible, but then they had only French keyboards. What a nuisance to have all the numbers on the top row...]
Lastly, Apple also tries to limit the availability of any Script Manager code or fonts it has developed to the country for which it was developed! This seems strange given that the Macintosh is touted as a Multinational machine. Apple has made Kanji and Arabic available through APDA, but feels that they are sufficient for the testing purposes intended. They have also developed a Chinese, a Hebrew and a Greek. The Chinese is distributed from Hong Kong and the Hebrew and Greek are distributed from Paris. I have written to the Paris office to no avail after a conversation with Mark Davis at Apple, the creator of the Script Manager. Do you know of a way for someone in the US to get these fonts from Paris? Actually, I am more interested in finding out the arrangement of characters in the coding table than I am in the font, but the exact status of ‘dead’ keys might be hard to discern accurately without actually having the font in hand.
Best regards,
Tim Ryan, SourceNet, Santa Barbara, CA “
[You address a very timely issue, that’s why I have your letter printed immediately without having the answers on hand yet. I’ll forward your mail with my comments to Apple France. I’m actually quite optimistic that you can get the Script Manager versions that you want. JL]
One comment to the letter from Peter Adamson, MT V4#1, p.11: The Pascal equivalent to the Mach2 PAUSE is actually WaitNextEvent; much like PAUSE under Mach2, WaitNextEvent will transfer control to the next MultiFinder task under certain circumstances. If you have a very long event loop, you may try to intersperse WaitNextEvents with event masks of zero, so that they’ll always return a null event. That should transfer control to the next task under MultiFinder. Only the crucial WaitNextEvent - the one with the BIG case statement behind it - would be called with a non-zero event mask. This is all untested, so don’t blame me if it doesn’t work.
See you next month.
Listing 1: Appointment reminder using the time manager \ ***** Time manager example - a ‘reminder’ utility \ J. Langowski December 87 \ \ Strategy: write a driver that sets up a dialog which allows \ to enter a time & message to display after that time. After \ the appointment has been entered, the driver sets up a \ time manager call for that appointment. \ The time manager routine installs a SystemTask trap \ patch which at the next occasion will draw an alert box \ containing the message to be displayed. \ \ Note that we have to use the patch rather than calling \ the alert routine directly from our time manager task, \ since we can’t be sure we’re not in the middle of a \ memory manager operation when it is called. \ only forth also assembler also mac CODE InsTime ( tmTaskPtr | -- ) MOVE.L (A6)+,A0 _InsTime RTS END-CODE MACH CODE PrimeTime ( tmTaskPtr count | -- ) MOVE.L (A6)+,D0 MOVE.L (A6)+,A0 _PrimeTime RTS END-CODE MACH CODE RmvTime ( tmTaskPtr | -- ) MOVE.L (A6)+,A0 _RmvTime RTS END-CODE MACH 4ascii MENU constant “menu 4ascii PROC constant “proc \ *** compiler support words for external definitions *** : :xdef create -4 allot $4EFA w, ( JMP ) 0 w, ( entry point to be filled later ) 0 , ( length of routine to be filled later ) here 6 - 76543 ; : ;xdef { branch marker entry | -- } marker 76543 <> abort” xdef mismatch” entry branch - branch w! here branch - 2+ branch 2+ ! ; : xlen 4 + @ ; ( get length word of external definition ) ( *** driver header block *** ) 0 CONSTANT drvrFlags 2 CONSTANT drvrdelay 4 CONSTANT drvrEMask 6 CONSTANT drvrMenu 8 CONSTANT drvrOpen 10 CONSTANT drvrPrime 12 CONSTANT drvrCtl 14 CONSTANT drvrStatus 16 CONSTANT drvrClose 18 CONSTANT drvrname 50 CONSTANT DAlength \ *** compiler support words for DA and driver definitions : :DA create -4 allot here 87654 ( start of DA block, and marker ) 50 allot ( length of block ) ; : ;DA { DAstart marker Ropen Rprime Rctl Rstatus Rclose Rflags Rdelay Remask Rmenu Rname | -- } marker 87654 <> abort” DA definition mismatch” Ropen DAStart - DAStart drvrOpen + w! Rprime DAStart - DAStart drvrPrime + w! Rctl DAStart - DAStart drvrCtl + w! Rstatus DAStart - DAStart drvrStatus + w! Rclose DAStart - DAStart drvrClose + w! Rflags DAStart drvrFlags + w! Rdelay DAStart drvrDelay + w! Remask DAStart drvrEmask + w! RMenu DAStart drvrMenu + w! Rname count dup DAStart drvrName + c! DAStart drvrName + 1+ swap dup 31 > if drop 31 then cmove here DAstart - DAStart DAlength + ! ; : DAlen DAlength + @ ; \ get length word of external definition \ **** DA glue macros CODE DA.prelude LINK A6,#-512 \ 512 bytes of local Forth stack MOVEM.L A0-A1,-(A7) \ save registers MOVE.L A6,A3 \ setup local loop return stack SUBA.L #256,A3 \ in the low 256 local stack bytes MOVE.L A0,-(A6) \ parameter block MOVE.L A1,-(A6)\ device control entry RTS \ just to indicate the MACHro stops here END-CODE MACH CODE DA.epilogue MOVE.L (A6)+,D0\ return code MOVEM.L (A7)+,A0-A1 \ restore registers UNLK A6 RTS END-CODE MACH CODE DA.Jiodone MOVE.L (A6)+,D0\ return code MOVEM.L (A7)+,A0-A1 \ restore registers UNLK A6 move.l JIODone,A0 movem.l d4-d7/a4-a6,-(a7) jsr (a0) movem.l(a7)+,d4-d7/a4-a6 RTS END-CODE MACH .TRAP _newptr,sys$A51E %0000000101001010 CONSTANT DAEmask $1B4 CONSTANT SystemTask \ ____________________________________________ \ time manager and systemTask patch routine \ this routine must reside in a block allocated \ in the system heap through a pointer. \ ____________________________________________ header myTask 14 allot 6 CONSTANT taskPtr HEADER myName DC.B 9,0,’Reminder’ header myTrap 4 allot header myAlert 4 allot header myString 256 allot : alertMe MOVEM.LA0-A4/A6/D0-D7,-(A7) LINK A6,#-128 \ 128 bytes of local Forth stack (call) frontwindow windowkind + @ 2 <> IF [‘] myTrap @ SystemTask (call) SetTrapAddress [‘] myString 0 0 0 (call) paramText [‘] myAlert @ 0 (call) noteAlert drop [‘] myAlert @ (call) freeAlert [‘] myTask RmvTime [‘] myTask (call) DisposPtr drop THEN UNLK A6 MOVEM.L(A7)+,A0-A4/A6/D0-D7 ; : wakeMe SystemTask (call) GetTrapAddr [‘] myTrap ! [‘] alertMe SystemTask (call) SetTrapAddr ; header mytask.end ‘ wakeme ‘ mytask - CONSTANT *wakeme \ task offset ‘ myAlert ‘ mytask - CONSTANT *myAlert \ alertID ‘ myString ‘ mytask - CONSTANT *myString \ alert string \ ___________________________________________ \ desk accessory code starts here. \ ___________________________________________ :DA reminder .ALIGN ( *** main desk accessory routines *** ) header myRes0 4 allot\ local res ID=0 offset header dlgText 256 allot \ redefinition of cmove to make it \ available locally CODE cmove move.l (a6)+,d0 move.l (a6)+,a1 move.l (a6)+,a0 tst.l d0 ble.s @2 @1 move.b (a0)+,(a1)+ subq.l #1,d0 bne.s @1 @2 rts END-CODE \ ___________________ \ wakeup routine installation \ ___________________ : install.wakeup { delay alrtID msg | procHdl hSize taskBlock -- } “proc [‘] myRes0 @ (call) GetResource -> procHdl procHdl (call) getHandleSize -> hSize hSize MOVE.L (A6)+,D0 _newPtr,sys MOVE.L A0,-(A6) -> taskBlock procHdl @ taskBlock hSize cmove procHdl (call) releaseResource \ we have made a local copy of the wakeup routine taskBlock dup *wakeMe + swap taskPtr + ! msg taskBlock *myString + 256 cmove alrtID taskBlock *myAlert + ! alrtID (call) CouldAlert taskBlock InsTime taskBlock delay PrimeTime \ now the wakeup routine will wake up after \ the scheduled delay. ; : getDrvrID { dCtlEntry | -- num } dCtlEntry dCtlRefNum + w@ l_ext 1+ negate ; : ownResID ( resID drvrID ) 5 shl + -16384 + ; : Open { parblk dce | DAWind Res0 -- returncode } 5 (call) sysbeep \ to get attention if automatically opened 0 dce getDrvrID ownResID -> Res0 dce dCtlWindow + @ -> DAWind DAWind 0= IF ( not open already ) Res0 [‘] myRes0 ! Res0 0 -1 (call) getNewDialog -> DAWind DAWind dce dCtlWindow + ! \ store dialog pointer DAWind dce dCtlRefNum + w@ swap windowKind + w! ELSE DAWind (call) selectWindow THEN 0 ; : Close { parblk dce | -- returncode } dce dCtlWindow + dup @ (call) DisposDialog 0 swap ! ( so that Open will work again ) 0 ; : dialog-handler { dlgPtr itemHit | itemType hItem rBox seconds -- } \ we get here if the OK button in the dialog \ has been hit, therefore itemHit is always =1 \ - in our case. But it is nice to have itemHit \ available, to be more general. \ item #3 contains the appointment message \ item #4 contains the delay in seconds \ (decimal number string) dlgPtr 4 ^ itemType ^ hItem ^ rBox (call) GetDItem hItem [‘] dlgText (call) GetIText [‘] dlgText (call) StringToNum -> seconds seconds 0> IF dlgPtr 3 ^ itemType ^ hItem ^ rBox (call) GetDItem hItem [‘] dlgText (call) GetIText seconds 1000 w* [‘] myres0 @ [‘] dlgText install.wakeup ELSE 10 (call) sysbeep THEN ; : Ctl { parblk dce | DAWind event-rec dlgPtr itemHit -- returncode } dce dCtlWindow + @ -> DAWind parblk csCode + w@ l_ext CASE accEvent OF 2 DAWind windowKind + w! \ set to dialog window parblk csParam + @ -> event-rec event-rec (call) IsDialogEvent IF event-rec ^ dlgPtr ^ itemHit (call) Dialogselect IF dlgPtr itemHit dialog-handler THEN THEN DAWind dce dCtlRefNum + w@ swap windowKind + w! \ reset windowkind ENDOF ENDCASE 0 ; : DrOpen DA.Prelude Open DA.Epilogue ; : DrClose DA.Prelude Close DA.Epilogue ; : DrCtl DA.Prelude Ctl DA.JioDone ; : DrStatus ; : DrPrime ; ‘ DrOpen ‘ DrPrime ‘ DrCtl ‘ DrStatus ‘ DrClose $7400 \ need lock, need time, need goodbye, ctl calls 60 DAEmask 0 \ delay mask menu “ Reminder” \ name ;DA ( write resource to file ) : $create-res ( str-addr - errcode ) call CreateResFile call ResError L_ext ; : $open-res { addr | refNum - refNum or errcode } addr call OpenResFile -> refNum call ResError L_ext ?dup IF ELSE refNum THEN ; : close-res ( refNum - errcode ) call CloseResFile call ResError L_ext ; : make-res { addr len rtype ID name | -- } addr len call PtrToHand abort” Could not create resource handle” rtype ID name call AddResource ; : write-out { filename | refnum -- } filename $create-res abort” That resource file already exists” filename $open-res dup 0< abort” Open resource file failed” -> refnum refnum call UseResFile [‘] reminder dup DALen “drvr 12 “ Reminder” make-res [‘] myTask [‘] mytask.end over - “proc -16000 “ wakeUp” make-res “proc -16000 call GetResource dup 80 call SetResAttrs ( 64: sysheap + 16: locked ) call ChangedResource refnum close-res abort” Could not close resource file” ; : make-DA “ Reminder.rsrc” $delete drop “ Reminder.rsrc” write-out ;
- SPREAD THE WORD:
- Slashdot
- Digg
- Del.icio.us
- Newsvine