Softworks Basic Shows Toolbox Flavor

By Dave Kelly, MacTutor Editorial Board

Welcome to this months BASIC column. I'm excited this month because I have something new to show you (brag about??). About 3 or 4 weeks ago someone asked me via the Mousehole if I was going to feature anything about the new compilers that have come (are coming?) out on the market. At that time there were no compilers available except a few that advertised their "Vaporware" in the major magazines. That has prompted me to explore some of the new BASIC products that are coming out. As you know MacTutor has a general policy of not doing reviews of any products, especially "Vaporware". At the time of this writing I have only received one (the only new one that you can actually buy). Softworks Limited has been advertising in MacTutor for the past few months and has released their Personal Basic for $99. Two other new BASICs are due out very soon, ZBASIC and True BASIC.

One of the most annoying things about BASIC (I hear this complaint all the time from C and Assembly programmers) is that BASIC is so slow. Well, they're right! Microsoft has had a great advantage by having the only BASIC product for a couple of years now. Most everything that I want to do with my Mac I can program in Microsoft BASIC. Well, almost everything. You see, when I write a program I like to write a program that looks and behaves like one that I would pay for. If the program doesn't look professional to me then I don't feel that it is finished. I have to make some exceptions in this column with editorial deadlines, but that's to be expected.

Well, lets face it, there are some things that just can't be done in MS Basic. Most of these things could be resolved with a few well placed calls to the Macintosh ROM routines. When you learn how to do Menus, dialogs, windows etc. in MS BASIC, you are in fact just learning how to use the Microsoft implementation of the toolbox. You open or close Windows their way. You create menus their way. You monitor events their way. BASIC programmers have been left out in some ways from the real Macintosh. The very brief encounters we have with Inside Macintosh when programming in MS BASIC are really too few to even mention. Of course, with Library subroutines attached to BASIC you can have access to some of the toolbox but the library must be accessible. Frustrating? Well, maybe. Some BASIC programmers out there may not need more than what has been provided. Others of us would like to see MS BASIC with full toolbox support without having to make sure that the right library is on the disk. Try writing a desk accessory in MS BASIC. Right now it can't be done.

Benchmark Comparison

Softworks Limited Personal Basic is a step in the right direction. Take a look at the Sieve Benchmark Test which they have included in their ads. One of the first things I have tried to do is verify the results of their tests. I was suprised to see that it depends on which version of the Sieve Benchmark that you have. I have aquired at least two of them and both give different times. I recommend that you be sure that you only do comparisons with the same versions of the Sieve. One version I have is written in MS BASIC and uses WHILE-WEND. Softworks BASIC doesn't support WHILE-WEND so a good comparison can't be made with that version. The version that I recieved with Softworks BASIC (example program) runs under either MSBASIC or Softworks BASIC with very minor modification. The major change was replacement of the comment symbol (MS BASIC uses " ' " , Softworks uses " ! " ). The Sieve is a fairly good test of speed of a computer. The results of the Sieve provided with Softworks BASIC is as stated in their ad: Softworks Basic 53 seconds (10 iterations averaged) and MS BASIC 120+ seconds (depending on the version and precision). Another test that we like at MacTutor, tests the accuracy as well as speed:

! Softworks BASIC Benchmark
40 time1=TIME
50 s=0
100 x=0
200 FOR n=1 TO 1000
300 s=s+x*x
400 x=x+.00123
500 NEXT n
600 PRINT s,x
700 time2=TIME
800 Totaltime=time2-time1
900 PRINT "Elapsed Time = ",Totaltime," Seconds."
950 input a  ! halt to see screen

The only change needed to run this in MS BASIC is that the statement TIME must be changed to TIMER in lines 40 and 700. The results of the test are:

Product S X Time

Softworks BASIC: 503.544 1.23 3 secs

MS BASIC 2.1(b): 503.545 1.230001 4 secs

MS BASIC 2.1(d): 503.54380215 1.23 4 secs

By the way, very few computers ever get the right answers. [The right answer is 503.54380215 exactly. Anything else denotes error in the math routines due to binary representation and/or rounding. As an example, an HP 9836 desktop computer runs this same Basic benchmark in 1.03 seconds with the exact result while an IBM PC running MBASIC returns 503.545 in 7.5 seconds, and an Apple II with Applesoft takes 26 seconds to calculate 503.543832. -Ed.]

Before I highlight a few of Softworks BASIC's features, please keep in mind that basic BASIC has been enhanced on all of the more recent computers. When I was first introduced to computers about 10 years or so ago, BASIC consisted of LET, PRINT, FOR-NEXT, GOTO, DATA, INPUT and a few others, but that was all. In MS BASIC we have many new enhancements such as no line numbers, line labels, WHILE-WEND, IF-THEN-ELSE, PRINT USING etc. Remember that different versions of BASIC implement these enhancements in different ways. If you program in PASCAL, C or other languages that have made use of the toolbox, you will find many aspects of Softworks BASIC familiar to you just by virtue of having access to the toolbox. This will make programming seem a little strange to you if you are used to MS BASIC.

Softworks Features

Ok, lets talk about what Softworks BASIC has. Basically speaking, of course, Softworks has provided the standard set of BASIC commands with enhancements. Some of these enhancements include IF-THEN-ELSE, PRINT USING, MIN, MAX, FACTorial, FIX, HEX, OCT, BIN, TIME and others. It is not possible to go into all of them at this time. There are quite a few Softworks commands that are only implemented in Softworks BASIC, to my knowledge. Some of the other new BASIC products may have implemented some similar (or maybe even some of the same) type commands. Some examples of these are toolbox, XCALL, ISAM, MAP, BYTEORDER, BYTEMOVE, BSTR, PSTR, and WORD among others. One command that stands out is the MAP command. A distinct feature of Softworks BASIC is the ability to reserve space for complex data structures like those in languages such as C and PASCAL. This allows the user to handle almost any conceivable set of data as a coherent unit or by its parts. As an example look at the demo program for the Mapped variable named theEvent.

 map1 theEvent
 map2 what,b,2
 map2 message,b,4
 map2 when,b,4
 map2 where
 map3 where'v,b,2
   map3 where'h,b,2
  map2 modifiers,b,2

The MAP statement reserves space for the variable theEvent. The variable theEvent is divided into different parts, what, message, when, where, etc. You may refer to any one of them separately or refer to the whole variable, theEvent all at one time. The ,b,2 following the variable what tells Basic that what will be a 2 byte binary or integer variable. As you can see, this allows you to take the PASCAL procedures and variables in Inside Macintosh and structure them in your program. The set of toolbox commands available appears to be complete, with over 500 commands available. It is possible to write simple programs without doing any toolbox calls (a window is predefined for you to use for output), but to make your application look like a Macintosh application you will have to dig into Inside Macintosh and learn how to use the toolbox. A beginner could use Softworks BASIC, but would not be able to have Mac-like applications without obtaining skill at using Inside Macintosh.

One of MS BASIC's strengths is the ability to easily create Mac-like programs. It may take some time and experience to quickly write complete programs entirely using the toolbox. But since MS BASIC is slower (until a good compiler for it is finally released) and supports only a very few toolbox commands, Softworks BASIC is a likely candidate for experienced BASIC programmers. When some of the other "soon to be released" BASIC's are made available I will be comparing their strengths and weaknesses.

Another feature of Softworks BASIC is the ability to mix strings and numerics in the same statement without conversion. All expressions are calculated from left to right. If, in the evaluation of a numeric expression, a string is encountered, an attempt is made to convert the string to the equivalent number (as in the VAL function). If it cannot do this, the string is treated as a zero. Similarly, if a number is encountered while processing a string expression, the number is converted to a string, and then operated on accordingly.

These are the major strengths of Softworks BASIC as I see it: MAPed variables, complete toolbox access, faster speed than MS BASIC (note: the program is compiled into a type of p-code, not native 68000). You can either save your compiled programs and run them using the runtime application program (BRUN) or you may compile the runtime program with your own program to create stand-alone applications. Provision is made for launching into any other application you choose. You can call other routines written in other languages using the XCALL command. Many enhanced BASIC features are included.

Softworks BASIC weaknesses are: It is not possible to call a Softworks BASIC program/routine from another programming language. The .REL type standard is not supported. Stand alone applications must include all the runtime code, regardless of how much of it is actually used. Also, there is a one time $25 license fee for each stand alone application that you intend to distribute sell to other people. Softworks has told me that this fee is ONLY for programs you expect to get gain from, i. e. commercial. They say this license fee does not apply to public domain programs that you may write. In fact, it should be noted that the runtime package has already been made available on Compuserve. The compiler is still considered the key to Softworks BASIC and is not free. Another disadvantage: It is not possible to write desk accessories because the stand alone applications are not native 68000 and the runtime program must be included (that takes at least 50K or more). There are still some compatability problems with HFS and Softworks BASIC. For now, be sure to use the HFS Fix routine by Andy Hertzfeld or the Editor (MDS editor) used by Softworks will not find files properly. [Getting the latest Editor, 2.0d2 or 1.53 should solve this problem. -Ed.]

Only you can decide if Softworks BASIC is "right" for you. Beginners may have some difficulty becoming experienced using the Macintosh interface via the toolbox. Keep in mind that this is the first released BASIC to include all the toolbox commands. The manual included with Softworks Basic lists the toolbox commands which are supported, but not in detail. You will have to refer to Inside Macintosh PASCAL procedures to find out how to use toolbox commands.

The Demo Program

The demo program could have been written in either C or PASCAL with about the same amount of difficulty (or ease) if you know either C or PASCAL. The intent of the demo is to demonstrate how to access the Macintosh toolbox from Softworks BASIC. This demo could be considered a skeleton for use in beginning the structure of any program that you may write. In future articles regarding Softworks BASIC we will try to fill in the gaps that are skipped in the demo.

The first step to accomplish before beginning work on your application is to become familiar with the parts of Inside Macintosh that pertain to what you intend to do. The demo requires information from the Window Manager, Event Manager, Menu Manager and the Softworks Personal BASIC manual. One thing I wish to point out is that each of the variables mapped in the beginning of the program have been taken from Inside Macintosh with very little modification. In general, Pascal INTEGER variables are 2 bytes and MAPed as 2 byte integers (example: map2 what,b,2) where what is an INTEGER variable listed as part of the EventRecord PASCAL record in the summary section of the Event Manager (Inside Macintosh). You can see that PASCAL record structures are replaced by MAPed variables in Softworks BASIC.

In MS BASIC, most everything that uses the toolbox directly is done automatically for you by the BASIC interpreter. Not so in real toolbox programming. You must take care of every event that occurs (every movement or click of the mouse, every menu etc.) with the exception of system events which the system takes care of (like desk accessories). This may come as somewhat of a surprise to those of you that are used to MS BASIC programming. No need to fear... the ROM routines provide what is needed to take care of everything. You just have to decide what you want to happen. After setting up variables, the demo program opens a window and then sets up the menu. The window manager takes care of opening the window. The program supplies the parameters required (as listed in Inside Macintosh) to use the window procedures. I will have more on windows at another time.

Using menus in MS BASIC requires that you set up your menu with the MENU statement and then turn on menu event trapping with MENU ON. When a menu event occurs you can determine which path the program will take. Programming menus from the toolbox is very similar. You first set up your menus, then call the Event manager and observe what kind of event occurs. If a mouse click occurs (mouse down) you then check to see if the mouse is in the menu bar. If in the menu bar, you then call the menu manager to determine which menu and menu item was selected and act accordingly.

 toolbox NewMenu,1, pstr(appleMark), menuhandle(1)
 toolbox AddResMenu, menuhandle(1), DRVR

The NewMenu routine initializes the new menu. Notice that parameters passed in the routine are separated by commas in Softworks BASIC. The statement pstr in Softworks BASIC converts the string constant appleMark in Softworks BASIC format (terminated by a null byte) to a string in the Macintosh ROM format (preceded by a length byte). This menu will be titled and will be referenced by the handle named menuhandle(1). The items in the menu will be read from the titles of all resources of type DRVR. This is how all desk accessories are made available. The next menu statements

toolbox NewMenu,2,pstr("File"),menuhandle(2)
toolbox AppendMenu,menuhandle(2),pstr("Quit")
toolbox NewMenu,3,pstr("Edit"),menuhandle(3)
toolbox AppendMenu, menuhandle(3),&
 pstr("Cut/X;Copy/C;Paste/V")

define the File and Edit menus. This is done similar to the previous statements. The command keys are defined by using a slash and the command letter. (Refer to Inside Macintosh). It is recommended that the Edit menu be defined in this standard way so that desk accessories, which use it, can take advantage of it. Some desk accessories will not be useful (example: the scrapbook) without being able to cut and paste.

The final menu of our demo shows that font information can be read directly from resources also.

toolbox NewMenu,4,pstr("Fonts"),menuhandle(4)
toolbox AddResMenu,menuhandle(4),FONT

The demo also shows us how to get the font size information into the size menu. The GetItem statement gets the font name from the menu. Then GetFNum gets the font number for the given menu name. Then using RealFont, the font size is checked. If the size exists then the menu item is drawn in outline mode. Note: the GetFNum routine is in error in the Softworks BASIC manual. This demo should show how to use the GetFNum statement.

toolbox GetItem,menuhandle(4),i,ItemString$
toolbox GetFNum,ItemString$,varptr(fontNum)
toolbox RealFont,fontNum,size(1),sizestatus

After the menus are set up, the program monitors all events in an event loop. This is similar to the method which may be used in MS BASIC for checking for dialogs, menus or other events. The toolbox routine, SystemTask, should be called at regular periods to enable the Macintosh to take care of system events, like desk accessory activity. You should call SystemTask often as possible, usually once every time through your main event loop. Call it more than once if your application does an unusually large amount of processing each time through the loop. (Note: Inside Macintosh states that System Task should be called at least every sixtieth of a second). GetNextEvent returns result eResult which indicates if an event has occured. The variable, what, which is part of the variable, theEvent , indicates what kind of event occured. It is now the responsiblity of the BASIC program to determine what action if any should be taken. This demo program has not fully developed all of the possible events, however, it is easy to add you own routines which control what will happen with each event. The possible events that could happen are: mousedown, mouseup, keydown, keyup, autokey, updateEvt, diskEvt, activateEvt, networkEvt, driverEvt and 4 user defined events.

event'loop:
 toolbox SystemTask
 toolbox GetNextEvent,everyEvent,theEvent,eResult
 if eResult = 0 goto event'loop
 on what gosub mousedown, mouseup, keydown, &      keyup, autokey, updateEvt, 
diskEvt, activateEvt, &   networkEvt, driverEvt, app1Evt, app2Evt, app3Evt, 
&  app4Evt
 goto event'loop

When the mousedown event occurs, the program flow is routed to the mousedown routine. The mousedown routine calls the FindWindow routine to determine where on the screen the mousedown event occured. If a menu has been selected the cursor will be in the menu bar. Therefore, wResult will be equal to one, thus the program will call the inMenuBar subroutine.

 mousedown:
 toolbox FindWindow,where,varptr(whichWindow),wResult
 on wResult gosub inMenuBar, inSysWindow, inContent,&    inDrag, inGrow,inGoAway
 return

The inMenuBar subroutine calls the MenuSelect toolbox routine. The DoMenu routine uses the result of the MenuSelect routine to determine which menu number and item was selected.

inMenuBar:
 toolbox MenuSelect,where,mResult
 gosub DoMenu
 return

This structured programming example provides a way for programs to be written which handle a multitude of events. It is advised that you use Inside Macintosh for the majority of your programming development. As you can see, BASIC has taken a backseat to the toolbox in most of this program.

In future columns, I will add to the routines in this program so that other toolbox features can be explored.

! Softworks BASIC Demo
! ©MacTutor 1986

! Window Definitions
map1  wStorage,x,256
map1  DragBoundsRect
 map2 r'top  ,b,2,  4
 map2 r'left ,b,2, 24
 map2 r'bottm,b,2,338
 map2 r'right,b,2,508
map1   wBoundsRect
 map2 w'top  ,b,2, 40
 map2 w'left ,b,2, 30
  map2  w'bottm,b,2,300
  map2  w'right,b,2,480 
map1  WindowPtr,b,4
map1  nam$,s,32,pstr("MacTutor Window")
map1  whichWindow,b,4
map1  wResult,b,4

! Event Definitions
map1  theEvent
  map2  what,b,2
  map2  message,b,4
  map2  when,b,4
  map2  where
  map3  where'v,b,2
  map3  where'h,b,2
 map2 modifiers,b,2
map1  eResult,f,,0
map1  everyEvent,b,2,-1

! Menu Definitions
map1  appleMark,x,1,chr(&h14)
map1  menuhandle(5),b,4
map1   menu,b,2
map1   menuitem,b,2
map1  mResult,b,4
map1   MenuNumber,b,2
map1  MenuItem,b,2
map1   mrefNum,b,4

! Misc. Definitions
map1  true,b,2,-1
map1  false,b,2,0
map1  currentfont,b,2,1
map1  currentsize,b,2,1
map1  z,f
map1  i,f
map1   numberoffonts,b,2
map1   numberofsizes,b,2,6
map1   fontNum,b,2
map1   sizestatus,b,2
map1  size(6),b,2
size(1)=9:size(2)=10:size(3)=12:size(4)=14:size(5)=18 size(6)=24

! Begin
toolbox InitWindows
toolbox Newwindow,wStorage,wBoundsRect,nam$,       1,16,1,0,0,WindowPtr
toolbox SetPort,WindowPtr
toolbox InsetRect,WindowPtr + 16,4,0
toolbox ValidRect,varptr(wBoundsRect)
gosub Set'Up'Menus
event'loop:
 toolbox SystemTask
 toolbox GetNextEvent,everyEvent,theEvent,eResult
 if eResult = 0 goto event'loop
 on what gosub mousedown,mouseup,keydown,keyup,autokey,updateEvt,&
 diskEvt, activateEvt, networkEvt, driverEvt, app1Evt, &       app2Evt, 
app3Evt, app4Evt
 goto event'loop end
mousedown:
 toolbox FindWindow,where,varptr(whichWindow),wResult
 on wResult gosub inMenuBar, inSysWindow, inContent, &   inDrag, inGrow, 
inGoAway
 return
inMenuBar:
 toolbox MenuSelect,where,mResult
 gosub DoMenu
 return
inSysWindow:
 toolbox SystemClick,theEvent,whichWindow
 return
inContent:
 toolbox FrontWindow,z
 return
inDrag:
 toolbox DragWindow,whichWindow,where,DragBoundsRect
 return
inGrow:
 return
inGoAway:
 toolbox TrackGoAway,WindowPtr,where,z
 if z then toolbox CloseWindow,WindowPtr 
 return
mouseup:
 return
keydown:
 return
keyup:
 return
autokey:
 return
updateEvt:
 toolbox SetPort,WindowPtr
 toolbox BeginUpdate,WindowPtr
 toolbox EndUpdate,WindowPtr
 return
diskEvt:
 return
activateEvt:
 return
networkEvt:
 return
driverEvt:
 return
app1Evt:
 return
app2Evt:
 return
app3Evt:
 return
app4Evt:
 return
DoMenu:
 toolbox HiWord,mResult,MenuNumber
 toolbox LoWord,mResult,MenuItem
 on MenuNumber gosub apple,file,edit,fonts,sizes
 toolbox HiliteMenu,0
 return
apple:
 toolbox GetItem,menuhandle(1),MenuItem,nam$
 toolbox OpenDeskAcc,nam$,mrefNum
 return
file:
 end
 return
edit:
 toolbox SystemEdit,MenuItem+1,z
 if z return
 ! do cut or copy routines here.
 return
fonts:
 toolbox CheckItem,menuhandle(4),currentfont,false
 toolbox CheckItem,menuhandle(4),MenuItem,true
 currentfont = MenuItem
 toolbox DisposeMenu,menuhandle(5)
 gosub makesizemenu
 toolbox DrawMenuBar
 for i=1 to 6
 if mstring$(currentfont,i)=true then currentsize=i:i=7
 next i
 toolbox CheckItem,menuhandle(5),currentsize,true
 toolbox textsize,size(currentsize)
 return
 sizes:
 toolbox CheckItem,menuhandle(5),currentsize,false
 toolbox CheckItem,menuhandle(5),MenuItem,true
 currentsize = MenuItem
 toolbox textsize,size(currentsize)
 return
Set'Up'Menus:
toolbox InitMenus
map1 DRVR,x,4,"DRVR"
map1 FONT,x,4,"FONT"
 strsiz 32
 toolbox NewMenu,1,pstr(appleMark),menuhandle(1)   !create apple menu
 toolbox AddResMenu,menuhandle(1),DRVR !add desk accessories
 toolbox NewMenu,2,pstr("File"),menuhandle(2)      !create file menu
 toolbox AppendMenu,menuhandle(2),pstr("Quit/Q")   !add 'quit' item
 toolbox NewMenu,3,pstr("Edit"),menuhandle(3)      !create edit menu
 toolbox AppendMenu,menuhandle(3),pstr( "Cut/X;Copy/C;Paste/V")
 !add items
 toolbox NewMenu,4,pstr("Fonts"),menuhandle(4)     !create fonts menu
 toolbox AddResMenu,menuhandle(4),FONT !add fonts
 toolbox CountMItems,menuhandle(4),numberoffonts
map1 ItemString$,s,255
dim mstring$(numberoffonts,6)
 for i=1 to numberoffonts
 toolbox GetItem,menuhandle(4),i,ItemString$
 toolbox GetFNum,ItemString$,varptr(fontNum)
 toolbox RealFont,fontNum,size(1),sizestatus
 if sizestatus then mstring$(i,1) ="9 Point<O" else mstring$(i,1)="9 
Point"
 toolbox RealFont,fontNum,size(2),sizestatus
 if sizestatus then mstring$(i,2)="10 Point<O" else mstring$(i,2)="10 
Point"
 toolbox RealFont,fontNum,size(3),sizestatus
 if sizestatus then mstring$(i,3)="12 Point<O" else mstring$(i,3)="12 
Point"
 toolbox RealFont,fontNum,size(4),sizestatus
 if sizestatus then mstring$(i,4)="14 Point<O" else mstring$(i,4)="14 
Point"
 toolbox RealFont,fontNum,size(5),sizestatus
 if sizestatus then mstring$(i,5)="18 Point<O" else mstring$(i,5)="18 
Point"
 toolbox RealFont,fontNum,size(6),sizestatus
 if sizestatus then mstring$(i,6)="24 Point<O" else mstring$(i,6)="24 
Point"
 next i
 MenuItem = 1   ! default MenuItem is 1
 for i = 1 to 4  !put items in menubar
 toolbox InsertMenu,menuhandle(i),0
 next i
 gosub makesizemenu
 toolbox DrawMenuBar !draw menu bar
 toolbox CheckItem,menuhandle(4),1,true
 toolbox CheckItem,menuhandle(5),1,true
 return
 
makesizemenu:
 toolbox NewMenu,5,pstr("Size"),menuhandle(5)      !create size menu
 toolbox AppendMenu, menuhandle(5), &  pstr(mstring$(MenuItem,1))
 toolbox AppendMenu, menuhandle(5), &  pstr(mstring$(MenuItem,2))
 toolbox AppendMenu, menuhandle(5), &  pstr(mstring$(MenuItem,3))
 toolbox AppendMenu, menuhandle(5), &  pstr(mstring$(MenuItem,4))
 toolbox AppendMenu, menuhandle(5), &  pstr(mstring$(MenuItem,5))
 toolbox AppendMenu, menuhandle(5), &pstr(mstring$(MenuItem,6))
 toolbox InsertMenu,menuhandle(5),0
 return

A few words about Clear Lake Research Libraries with MS BASIC: CLR Libraries have been checked out on a Macintosh plus and worked with no problems. If you are having problems, check to see that your program is opening up the correct library name and that BASIC is in the same folder as the CLR Library. For that matter, your BASIC programs need to be in the same folder. The problems appear to be because of incompatibility between MS BASIC and HFS.