Related Info: Control Manager Vert. Retrace Mgr Memory Manager

Forth Tools, News and Tricks

Creative Solutions is distributing some excellent solutions for real problems

By Jörg Langowski, MacTech Magazine Regular Contributing Author

OK, here I’m back after one month’s break. And I’ll finally give you some news from the Forth scene. Actually, it is nice to see that there is still an ‘ecological niche’ for Forth programmers in the Macintosh world - with all the Bedrock and class libraries and what-not out there that try to abstract (distract?) you more and more from the actual machine you’re working on. Although this is nice for those of you planning the program that’s going to sell a million copies on Macs, Windows, and X-Windows environments, there still seem to be quite a few individuals that want to make the Mac do something quickly and elegantly, without producing 3 megabytes of code (and we do get feedback from you, and are very happy about that). Forth seems to be one of the languages of choice for those ‘individualized’ tasks, and fortunately there is MacForth around, with a big user base and a CompuServe forum. Then, of course, there are the object-oriented Mops and Yerk Forth environments which you’ve read about. For those of you interested in chasing lost dreams, the basically defunct Mach2 Forth may be on its way to resurrection. First, though, I’d like to show you a couple of interesting tools and demos that can be found on the MacForth Tools disk, which is available for $25 from Creative Solutions (see their ad in this issue).

The MacForth 4.0 Tools

This disk contains a wealth of useful Forth code, a lot of it in the public domain and from other sources. Those of you with no access to CompuServe, like myself, will appreciate this collection. The most important single piece of code is an upgrade to the editor integrated into MacForth. Even in its original version, the Sibley Editor is already one of the main reasons why MacForth is such an appealing development system - it features multiple windows in which Forth code can be executed interactively (similar to MPW worksheet windows), automatic highlighting of the place where an error occurred, scroll bars with line/page number display, setting markers, and more. Best of all, the full source code is included with MacForth, so you can customize the editor if you like. That is what Jeff Dripps did with his extensions to the editor, and now the Sibley editor has really grown into a fancy programming tool. Now the editor features color windows, and parameters like foreground and background colors, scroll modes, word wrap, the current selection etc. are held in resources in the edited text file. The maximum number of open windows is 24, and in the next version there will be no limit. There is also a very extensive search/replace facility which allows you to work on all files in a folder at once. All in all, this makes the MacForth editor almost as powerful as the MPW worksheets; alas, MPW doesn’t give you a Forth environment

A Control Device in MacForth

Another piece of code that I liked was an example by Scott Squires on programming a CDEV and a desk accessory. There is support for stand-alone code in MacForth, which adds a ‘mini-kernel’ to your Forth code so it can be called as a code resource from the Mac system. I enclose the control panel device on the source code disk; it shows a simple window with two controls and a clickable user item (Fig. 1). The resulting code is only 11390 bytes long, and the actual executable code (Forth mini-kernel + Forth code) is only 2170 bytes out of that! The compactness of Forth code really shows here - of course, it would be even more striking for more complicated applications. The example listing shows an excerpt of the Forth source code for the CDEV. Writing such a control device is rather straightforward, it is a code resource which is called through a standardized interface; your code has to do certain actions depending which message it receives when it is called.

The system calls the code contained in the ‘cdev’ resource as if it were a Pascal function defined in the following way:

FUNCTION cdev (message, Item, numItems, CPanelID: INTEGER;  
 VAR theEvent: EventRecord; cdevValue: LONGINT;
 CPDialog: DialogPtr ) : LONGINT; 

Here message contains the type of action that the CDEV has to perform, item is the number of the item that was hit in the control panel, numItems the number of dialog items in the control panel, CPanelID gives the resource ID of the Control Panel driver (numItems and CPanelID are really only relevant for System 6.x, where the Control Panel is a desk accessory), theEvent is the event record corresponding to the event that caused the message, cdevValue is the return value from the last access of the CDEV (which is given back here and can therefore be used as an intermediate storage, e.g., for a handle to a data block), and CPDialog is the dialog pointer of the Control Panel dialog box.

Fig. 1: A CDEV written in MacForth

The main body of the control device code then consists of a CASE statement which calls the appropriate handlers (see listing). In the example, I have only printed a few of those handlers, to give you an idea how a control device can be written in MacForth. I leave the code for the other handlers to your imagination.

Vertical blanking tasks

Another contributor to the MacForth tools disk is Arden Henderson (who put all of his code in the public domain). Among others, he gives an example of a vertical blanking task written in Forth. Remember, unlike Desk Accessories and MacForth multitasking, VBL Tasks execute without calling SYSTEM.TASK (or DO.EVENTS). Therefore, they run despite menus, dialogs, mouse downs, synchronous i/o, other applications using the CPU, etc. However, a VBL Task may not use any traps that allocate, move, or resize heap objects through the memory manager. Years ago, in volume 2#6 of (then) MacTutor, we had an example of a screen saver written as a VBL task in Mach2. Well, here is a similar example in MacForth. As for the CDEV, a mini-kernel is needed to interpret the token-threaded MacForth code in order to produce stand-alone code that can be integrated into the vertical blanking task queue. Ward McFarland, that all-time MacForth hero and generous contributor to the Tools disk, has written the support code that installs MacForth VBL tasks. With this code present, you can define a VBL task in a very simple way (see listing):

• put a tick value after which the VBL task should execute for the first time into the VBLTask.Duration field of the VBL queue element;

• put the tick value after which the VBL task should be re-executed (zero if no re-execution) into the VBLTask.AutoRepeat field of the VBL queue element;

• put the token corresponding to the Forth word to be executed in the VBL task into the VBLTask.token field of the VBL queue element;

• and call add.vblTask with the address of the VBL queue element on the stack.

The extra information necessary for executing MacForth code from a VBL task is appended to the standard VBL queue element, and the MacForth VBL queue element is defined as:

\1

STRUCTURE VBLTASK\ MacForth VBL Task
 \ long: ( relative chain linkage to VBLTask.LINKAGE )
 \ long: ( CFA of MacForth VBL Task )

 \ the first 14 bytes of the PFA define a standard Macintosh VBLQueueEntry:
 long: ^vblQ.Link
 \ pointer to next element in chain - set by Mac
 short: ^vblQ.Type
 \ queue type = 01 for VBLQueueEntry
 long: ^vblQ.Addr
 \ address of code routine to be executed at timeout
 short: ^vblQ.Duration
 \ number of ticks remaining before timeout
  short: ^vblQ.Phase \ see IM

 \ The next 16+ bytes is specific to MacForth VBL Tasks:
 short: ^vbl.AutoRepeat
 \ #Ticks to setup for subsequent timeouts
 long: ^vbl.Addr
 \ Non-relocatable address of user Code routine
 short: ^vbl.Token
 \ Token to execute
  long: ^vbl.Addr.Rel
 \ Relocatable Address of user code routine
 long: ^vbl.Spare\ User specifiable long word
 \ room for extra stuff here if you need it...
 \  (an event number to post, flags, 
 \   data storage area, etc.) 
 byte:  ^Dflt.VBL.Code
 \ start of short assembly routine for ^vblQ.Addr
 \ this is where the Forth ‘mini-kernel’ goes
STRUCTURE.END

When the VBL task is executed, a jump is taken to the mini-kernel, which starts Forth execution at the token contained in vbl.token (at least that’s it in a nutshell). For more details, you should get the MacForth Tools disk, or look in the CompuServe MacForth forum.

Dissect - a recursive Forth decompiler

The last MacForth tool I’d like to present is a very powerful decompiler that re-creates the Forth code from a compiled definition. Since Forth code is threaded, that means highly structured, the words from which a definition is compiled will in turn reference definitions that consist of several words. With the decompiler Dissect 4.0 (by Ward McFarland), you can choose the depth to which a Forth definition will be dissected. For instance, if you define the word

: hello.world .” hello world” cr ;

and then

: hi 10 0 do hello.world loop ;

you can view your definition by typing

0 rdef hi

which will give:

'NFA' Name Token  CFA    (CFA)    (PFA)          
19A0  HI   CAAC   54008A 4EAE004A 00E6  000A  05AA  020A 
       found in  FORTH  ( in "Dissect 4.0" )
 
$54008E WLIT 10
$540092 0 
$540094 (DO) $54009C 
$540098 HELLO.WORLD 
$54009A (LOOP) 
$54009C (;) 

and with

1 rdef hi

you step down one more level and will see the definitions of each word of which hi is composed:

'NFA' Name Token CFA    (CFA)    (PFA)          
19A0  HI   CAAC  54008A 4EAE004A 00E6  000A  05AA  020A 
       found in   FORTH  ( in "Dissect 4.0" )
 
$54008E WLIT 10 Machine Language 
 ( token = $  E6 , CFA = $51F5F8 )
0051,F5F8: 305A             MOVEA.W  (A2)+,A0
0051,F5FA: 2F08             MOVE.L  A0,-(A7)
0051,F5FC: 361A             MOVE.W  (A2)+,D3
0051,F5FE: 4EF6 3000        JMP  (0,A6,D3.W)
$540092 0  WConstant = 0
$540094 (DO) $54009C  Machine Language 
 ( token = $ 20A , CFA = $51F71C )
0051,F71C: 2706             MOVE.L  D6,-(A3)
0051,F71E: 2705             MOVE.L  D5,-(A3)
0051,F720: 548A             ADDQ.L  #2,A2
0051,F722: 270A             MOVE.L  A2,-(A3)
0051,F724: 2A3C 8000 0000   MOVE.L  #-80000000,D5
0051,F72A: 261F             MOVE.L  (A7)+,D3
0051,F72C: 2C1F             MOVE.L  (A7)+,D6
0051,F72E: 9686             SUB.L  D6,D3
0051,F730: 67C0             BEQ.B  51F6F2
0051,F732: DC85             ADD.L  D5,D6
0051,F734: DA83             ADD.L  D3,D5
0051,F736: 361A             MOVE.W  (A2)+,D3
0051,F738: 4EF6 3000        JMP  (0,A6,D3.W)
$540098 HELLO.WORLD  
$540078 >1   (.") "hello world"
$540086 >1   CR 
$540088 >1   (;) 
$54009A (LOOP)  Machine Language 
 ( token = $ 1F2 , CFA = $51F704 )
0051,F704: 5285             ADDQ.L  #1,D5
0051,F706: 69F0             BVS.B  51F6F8
0051,F708: 2453             MOVEA.L  (A3),A2
0051,F70A: 361A             MOVE.W  (A2)+,D3
0051,F70C: 4EF6 3000        JMP  (0,A6,D3.W)
$54009C (;)  Machine Language 
 ( token = $  C0 , CFA = $51F5D2 )
0051,F5D2: 245B             MOVEA.L  (A3)+,A2
0051,F5D4: 361A             MOVE.W  (A2)+,D3
0051,F5D6: 4EF6 3000        JMP  (0,A6,D3.W)

So you can imagine what kind of output you get when you go to even lower levels. But this is very useful for debugging, and for analyzing how the words built into MacForth are defined.

All in all, MacForth together with the Tools disk is a very elegant and well supported Forth development system for the Macintosh, and the only one with a commercial backing.

And Mach2 is not dead, either

For those of you who are still nostalgic about the other Forth system for the Macintosh, here’s a message that I received just before I finished this column:

“From: John_Fleming@sat.mot.com

To: jl@macjl.embl-grenoble.fr

Hi Joerg:

Good news. Steve Wiley finally got the source code for Mach2. I imagine we will start working on it soon, merging all our fixes to come up with an update version. From then, there are plans to do several big updates.

We now have Mach2 working with Virtual Memory (but not the Debugger). There have been all sorts of fixes, so the new update should be relatively robust.”

So after all, Mach2 may go the way of Neon (alias Yerk alias Mops) to become one more high-quality public domain Forth on the Macintosh. I hope I can fill you in on further developments very soon.

[But remember, this is still not a commercially supported product so it is in the 'buyer beware' category. - Ed.]

LS Fortran updated to version 3.3

The latest version of Language Systems’ MPW Fortran has just arrived here. Before giving you a detailed review (in the next column), I’d like to show you at least the most important new features as they are described in the release notes:

“Version 3.3 of LS FORTRAN contains a number of performance improvements over the previous version, v3.0.1. The highlights of this new version are:

• Faster execution speed for many programs

• High performance 68040 Math Library

• Faster compile speed for many programs

• More robust syntax checking

The compiler now requires a 68020 processor (Mac LC or greater). Finished programs will still run on any Macintosh, even a Mac Plus, with or without a floating point coprocessor. Version 3.0.1 is available for programmers who still need to compile on 68000-based machines.

Faster Execution Speed:

Programs ported from other systems often require the

- saveall or -vax options for proper execution on the Macintosh. These programs will run significantly faster in version 3.3 because local variables are allocated statically with -saveall or

- vax, thus avoiding the runtime SAVE overhead.

The FastComplexFPU.o math library is now included at compile time by default. This library provides accuracy in excess of double precision. If you require even greater accuracy, or want to revert to the same behavior as previous versions, use the -sane compiler option. It is no longer necessary to add FastComplexFPU.o to your link commands. Complex multiplication with the -fpu option is now performed inline.

Other improvements include faster READ operations in programs compiled as MPW Tools, and faster WRITE operations with unformatted files.

High Performance 68040 Math Library:

A new transcendental library optimized for the 68040 processor is automatically added when using the -mc68040 and

-fpu options. For maximum benefit, include IntrinsicLibFPU040.o in your link command. Many other 68040 specific improvements take effect when the -mc68040 option is used.

Faster Compile Speed:

Any program with large numbers of constants (character, floating point, or complex) should compile noticeably faster. Significant compiling improvements have been made for programs that include DATA statements with implied DO loops.

More Robust Syntax Checking:

The compiler is now enforcing certain aspects of the F77 standard more strictly. In particular, procedural arguments (a subroutine name passed as an argument) must be declared EXTERNAL. This may cause some programs that previously compiled correctly to now produce compiler errors.

Other Enhancements:

The output window now enables the user to scroll and paste data during READ statements. The File and Edit menus will also become active at this time.

The Debugging Toolkit and FORTRAN Tools for AppMaker products have also been updated. Registered owners should have received free upgrade(s) with their FORTRAN upgrade.”

So far that's the news from Language Systems; next time you’ll see some benchmark figures, and other impressions I had with using their new compiler. Until then.

Example 1: A Control Device written in MacForth
( Excerpts of code originally written by Scott Squires )

( first some of the words that define the cdev handlers )

: DO.INIT ( -- | first message usually received )
 ( init storage and user items )
  cdevStorageRecord  _NewHandle  ?dup
  IF -> cdevValue    \ store handle in cdevValue
 0 cdevValue h@ +user.value !
 init.dialog
 ELSE   
 cdevMemErr -> cdevValue  \ return error
 THEN ;


: DO.CLOSE( -- | get rid of any handles and clean up )
 cdevValue _DisposHandle
 0 -> cdevValue ;


: DO.ABOUT   
 ( -- | ABout button action, display About information )
 " Simple CDEV Written by Scott Squires"
 $>dlg.text#  ;

: DO.CHECK   
 ( -- | Check box action, display status message )
  dlg.Check# numitems + dCntlSet?
 IF     " Check Box On" 
 ELSE   " Check Box Off" 
 THEN
 $>dlg.text#  ;

( not all handler words printed here for space reasons )
( CDEV main code follows )

{
FUNCTION cdev (message, Item, numItems, CPanelID: INTEGER;  VAR theEvent: 
EventRecord; cdevValue: LONGINT;  CPDialog: DialogPtr ) : LONGINT; 
}

: DO.CDEV ( sp -- |the main routine)
   ( this is the entry point for all routines)
 -> old.sp 
 old.sp @ ->   cpdialog
 old.sp 4+  @ -> cdevValue
 old.sp   8+     @ ->   theEvent
 old.sp   12 +   w@ ->  CPanelID
 old.sp   14 +   w@ ->  numItems
 old.sp   16 +   w@  ->   Item
 old.sp 18 +   w@ -> message
 cpdialog dPtr !   \ save the dialog pointer 
 \ for utility words
 message  \ Event message that we respond to.
 \ The handler words in  the following
 \ CASE statement have been defined 
 \ before (some of them are shown above)
 CASE   
 initDev  OF     do.init  ENDOF
 hitDev OF       do.hit   ENDOF
 closeDev OF     do.close ENDOF
 nulDev OF       ENDOF
 updateDev  OF     do.user.icon   ENDOF
 activDev OF     ENDOF
 deActivDev OF     ENDOF
 keyEvtDev  OF     do.key.event  ENDOF
 macDev OF    true -> cdevValue    ENDOF
 undoDev  OF     do.undo  ENDOF
 cutDev OF       do.cut   ENDOF
 copyDevOF     do.copy    ENDOF
 pasteDev OF     do.paste   ENDOF
 clearDev OF     do.clear ENDOF
 cursorDev  OF   DO.CURSORENDOF
 ENDCASE
 old.sp 20 +( remove stack items )
 cdevValue   over ! ;\  return cdevValue

SA do.cdev   \ creates a stand-alone code resource 
 \ from the do.cdev word

Example 2: VBL task in MacForth

{simple beachball cursor written by Arden Henderson, 
 Lone Star Industrial Tool Co. (73057,2045)

 Last Revision: 06/28/90  12:01:37 AM  AH 

 Free for any use---placed in public domain. As such, this source code 
is not warranted or supported in any way and the user assumes full responsibility 
for its use and utility. This source code has been tested on a Mac SE 
& IIx with MacForth 4.0. All text was produced with the Sibley Editor 
and is formatted with tabs.
 Comments welcome.
}

Forth Definitions 
Decimal

anew ---vblCur--

global theCursorImage
0 -> theCursorImage


\ Instead of using CURS resources, here we hard-code the 
\ cursor images into MacForth's object area. The "right" 
\ way is to use resources, BUT  it's a cruel, cold world out 
\ there and by placing these images in the object area, we 
\ make it REAL difficult for resource editing types to tamper 
\ with the code. 
\ How to do other images: build the image using ResEdit, 
\ then copy and paste the hex numbers into a SE window 
\ and edit...

\ Our cursor for the day is the famous so-called "beach 
\ ball" cursor--  though it only kinda resembles a beach ball. 
\ This animated cursor is found in a zillion Mac programs 
\ and perhaps can be thought of as a sort of standard 
\ alternative to the winding watch cursor...if there is such...
 
\ the cool stuff Forth lets you do: compiling what you want 
\ when you want...

hex
create bb1
000007C0 , 1F303F08 , 7F047F04 , FF02FF02 , FFFE81FE , 
81FE41FC , 41FC21F8 , 19F007C0 , 000007C0 , 1FF03FF8 , 
7FFC7FFC , FFFEFFFE , FFFEFFFE , FFFE7FFC , 7FFC3FF8 , 
1FF007C0 , 00010000 , 

create bb2
000007C0 , 1FF03FF8 , 5FF44FE4 , 87C28382 , 81028382 , 
87C24FE4 , 5FF43FF8 , 1FF007C0 , 000007C0 , 1FF03FF8 , 
7FFC7FFC , FFFEFFFE , FFFEFFFE , FFFE7FFC , 7FFC3FF8 , 
1FF007C0 , 00010000 , 

create bb3
000007C0 , 19F021F8 , 41FC41FC , 81FE81FE , FFFEFF02 , 
FF027F04 , 7F043F08 , 1F3007C0 , 000007C0 , 1FF03FF8 , 
7FFC7FFC , FFFEFFFE , FFFEFFFE , FFFE7FFC , 7FFC3FF8 , 
1FF007C0 , 00010000 , 

create bb4
000007C0 , 18302008 , 701C783C , FC7EFEFE , FFFEFEFE , 
FC7E783C , 701C2008 , 183007C0 , 000007C0 , 1FF03FF8 , 
7FFC7FFC , FFFEFFFE , FFFEFFFE , FFFE7FFC , 7FFC3FF8 , 
1FF007C0 , 00010000 , 

decimal

\ cut-and-dried standard MacForth stuff....

4 4 1array beachball.array

bb1 0 beachball.array )!  \ must be relocatable addresses!
bb2 1 beachball.array )!
bb3 2 beachball.array )!
bb4 3 beachball.array )!


\ note that there is no limit to the (hard-coded) number of 
\ sequenced images.. modify as needed...

: set.cursor.now ( -- | assign the next cursor in sequence as THE cursor 
)

 theCursorImage beachball.array )@ set.cursor

 1 +to theCursorImage
 theCursorImage 4 = 
 if 
 0 -> theCursorImage
 then
  ;


new.vbltask CURSOR.TASK   
 1 cursor.task !VBLTask.Duration
 12cursor.task !VBLTask.AutoRepeat
 token.for set.cursor.now
 cursor.task !VBLTask.token

\ working words .......................................................

: do.BBeach.Cursor ( -- | initialize and startup VBL cursor )

 0 -> theCursorImage
 1    cursor.task !VBLTask.Duration
 10cursor.task !VBLTask.AutoRepeat
 token.for set.cursor.now
 cursor.task !VBLTask.token
 cursor.task   add.vblTask  
;


exodus linked
: stop.BBeach.Cursor ( -- | remove VBL CURSOR task )
 0 cursor.task ^vbl.AutoRepeat w!
 \ force VBL task to stop by itself
 cursor.task remove.vbltask drop \ kill it to be sure
 init.cursor
;

on.forget stop.BBeach.Cursor

\ for quick entry...

: aaa  do.BBeach.Cursor ;
: xxx  stop.BBeach.Cursor ;