By Sean Nolan
This year, Christmas comes in June. The TERC BASIC Enhancements, an Applesoft enhancement package, are being dumped (pardon me, I mean released) into the public domain. The TERC BASIC Enhancements add over 50 additional BASIC commands to Applesoft which allow:
• Mixing text and graphics anywhere on the screen.
• Labeled subroutines with parameter passing and local variables. Improved INPUT commands which simplify catching of user errors.
• IF I THEN I ELSE.
• Hi-Res SCRN and XPLOT commands.
• Non-destructive pop-up menus and windows.
• Debugging and diagnostic commands.
• An optional ‘compiler’ (term used with blatant inaccuracy) which allows you to write BASIC programs on a word processor.
• No conflict with most Ampersand or USR libraries.
• Expandability and documented entry points for machine language programmers.
The TERC BASIC Enhancements were written for in-house use at Technical Education Research Centers (TERC), in Cambridge Massachusetts, by myself, Steve Beardslee, Steve Hunt, and Steve Bannasch. TERC is releasing the Enhancements into the public domain for non-commercial use only. The Enhancements may be ordered through A.P.P.L.E. Co-op (with documentation on disk) or through myself (with printed documentation). The Enhancements are ProDOS based, and thus require 64K of RAM. At present, they are not compatible with the Lasar 128 nor any other Apple clone. The core of the Enhancements use 6K of memory ($800-$IFFF). Some commands, such as the automatic MENU routine and pop-up windows, require more memory.
The BASIC Enhancements do not use Ampersand, but use the single quote (‘) instead. All Enhancements commands begin with this character. By avoiding the use of Ampersand, the Enhancements are able to add both new procedures and new functions to Applesoft (Ampersand lets you create procedures, but not functions). Procedures are commands which are meant to be executed at the beginning of a BASIC statement, such as the Applesoft commands HPLOT, HOME, PRINT, and their ilk. Functions are called from within a numeric or string expression and return some value back to BASIC. Applesoft examples of functions are SCRN, PDL, RND, SIN, COS, and PEEK (see quick reference sheet listing for all Enhancements commands). It also serves as as index for the 50-page manual.
The Enhancement commands can be separated loosely into four groups. First there are the standard goodies, commands which any self-respecting Applesoft extender should have. Next, the unusual commands, which make the TERC Enhancements unique. Third, the obscure technical commands. And then there are the commands which add no additional capabilities to BASIC, but make it more readable.
The standard goodies include an ELSE to go along with IF and THEN, a rudimentary PRINT USING command for formatted numeric printing (yawn), and an improved INPUT anything routine. ‘XPLOT draws Hi-Res lines in the complement of the background. A highresolution graphics SCRN function has been added, allowing you to read whether any Hi-Res pixel is on or off. A positionin- string function allows you to tell if any character or string is to be found within a second string. Three additional mathematical functions allow you to do genuine bitwise AND, OR, and XOR operations on numbers.
The two most important standard goodies, however, are its use of labeled subroutines and a Hi-Res character generator. Labeled Subroutines The Enhancements allow you to refer to subroutines by name rather than by line number. Instead of:
100 GOSUB 8045
which might call say, a help prompt subroutine, you can write
100 ‘GOSUB HELP
If you wanted to pass a particular prompt string to the HELP subroutine, you could do it with
100 ‘GOSUB HELP [ A$ ] 100 ‘GOSUB HELP [ “Put the disk back and press a key.” ]
This is officially known as parameter passing. Along with the use oflocal variables (which the Enhancements support), this allows you to write structured code and use recursion. The latter is illustrated with a sample program on the enhancements disk. Called ‘HILBERT, it draws a recursive curve. I translated it directly from the Pascal original (in the Call – A.P.P.L.E July 1984 article “Hilbert and the Alligators”) without having to change the recursive structure of the program. Because of the ability to refer to subroutines by name instead of by line number, you can now write BASIC without the use of line numbers at all. At TERC, we write our programs with a word processor. The Enhancements come with a utility for translating word processor text files into runnable BASIC programs. You can, if you wish, not use it and write BASIC programs the normal way.
Mixing Text and Graphics
The Enhancements contain a full fledged Hi-Res character generator. This lets you put text characters anywhere on the Hi-Res display screen. Unlike many other Hi-Res character generators (yes, there are many of them), ours does not let you scroll text on the Hi-Res page. But there are compensating features: with the Enhancements you can draw characters at any pixel position you like, it is done like this:
‘VTAB 11.5 : ‘HTAB 31.2: PRINT A$
Most character generators restrict characters to a rigid 40 by 24 matrix. Our character generator also supports underlining, variable character and line spacing, and three ways of combining the characters with their background. The Enhancements don’t provide Mac-like pull down menus, but do have their alternative. Pop-up windows containing text or menus can be placed anywhere on the screen; later they can be removed, leaving the background undamaged. One enhancement function, ‘MENU, causes a menu in a pop-up window to be displayed, interprets user keypresses, and returns with a number indicating which menu choice was chosen. You can even define a BASIC subroutine as a background process for ‘MENU. As ‘MENU waits for a keypress, the background subroutine will be called over and over. This gives the appearance of your BASIC program doing two things at once.
Our Sleazy Replacement for Virtual Memory
By now we’ve drifted into the second group of commands, those which make the TERC BASIC Enhancements unique. Pop-up windows, a Hi-Res display, graphics buffers, and the Enhancements altogether take up a good deal of memory . Fortunately, ProDOS has added a CHAIN command to allow BASIC programs to be broken up into pieces. The Enhancements go one step further with the ‘DISK GOSUB command. This treats a BASIC program on disk as if it were a subroutine. For example, Program A might contain the statement:
‘DISK GOSUB “SUBPROGRAM”
This runs the program SUBPROGRAM. When SUBPROGRAM ends, program A is automatically re-Ioaded, and resumes execution at the line following the ‘DISK GOSUB statement. BASIC variables survive the tumultuous journey unscathed. If you’ve got a 128K machine, you can run all the pieces off the RAMdisk with no noticeable delay.
The Enhancements contain built-in hex to decimal and decimal to hex converters. You can use them at the BASIC prompt or in your program; this lets you use hex (base 16) instead of base 10 anywhere you like. For example: HIMEM: ‘$9200 or Q = PEEK (‘$COOO) Are you tired? Depressed? Are your integer arrays being overwritten? Use ‘STOP WHEN to find out where. ‘STOP WHEN single steps through your BASIC program (at sub-glacial speed), continuously testing to see if a particular variable is being trashed, erased, or whatever. For example:
10 ‘STOP WHEN (W=7) 20 FORW=OT010 30 PRINTW 40 NEXTW
The above program will crash with the message “BREAK IN 40” after the seventh trip through the FOR-NEXT loop. ‘STOP WHEN is made possible by the way the Enhancements get control from Applesoft:’ we patched CHRGET. CHRGET is a little machine language subroutine that lives down in page zero. The BASIC interpreter calls it every time it needs to look at the next character in your BASIC program (for a full description of CHRGET, see Call -A.P.P.L.E March 1982). The patched CHRGET acts exactly as the original one does except that it gives the Enhancements control whenever it parses a single quote (which transfers control to the Enhancements command parser) or a zero (which signals that the end of a BASIC line has been reached).
Error trapping and bomb-proofing a program often requires as much attention as writing the real guts of the program. The Enhancements make error trapping easier in two ways – with improved INPUT and GET commands and with additional error trapping commands. The Enhancements INPUT routine allows you to specify ahead of time the maximum length of the string, allows all printable characters and only printable characters to be included (this allows commas, but not control characters), and tells you whether the user finished by pressing RETURN or by pressing ESCAPE. The new GET command takes a string parameter. It waits for the user to press one of the keys in the string, and returns the character position in the string of the matching character. For example:
A = ‘GET FN (“QWERTY”)
will wait for a “Q”, “W”, “E”, “R”, “T”, or “Y” to be pressed. If “Q” was pressed, A will be set to I. If”W” was pressed, A will be set to 2, and so on. Any keypresses other than “Q”, “W”, “E”, “R”, “T”, or “Y” will be ignored.
Applesoft Error trapping is improved three ways. First of all, the Enhancement have optional control-C trapping – it is not necessary to write an ONERR GOTO routine to trap these. ONERR routines, if used, can be referred to by label rather than by line number, and can be nested. This allows an error trapping routine to monitor errors in another error trapping routine – something I’ve actually needed to use when trapping the labyrinthine possibilities of disk access errors. The Enhancements also provide a third path to ONERR enlightenment. Normally, either of two things happen when an error occurs: either your program stops or it jumps to an error trapping routine. If you wish, you can cause errors to be simply ignored. This feature is useful in programs which save files onto disk. If the file already exists, the traditional thing to do is install an error trapping routine and try to VERIFY the file. With the third path, you simply do the VERIFY and then check afterwards if it was successful.
Opening the Floodgates of Abuse
We now come to the technical Enhancements commands. Most of these give you better control over your BASIC variables. There is a function which returns the address of a variable, you can POKE at it or BSAVE it. You can create strings which point anywhere in memory, even into the softswitches. You can undimension an array. The Enhancements let you do lots of silly or dangerous things.
Used foolishly, or with malice, they could scramble your Apple’s memory. The technical commands include some obscure trivia. There is a command, believe it or not, for retrieving half of the last random number seed as of the last ProDOS CHAIN executed. Why? Because we needed it at TERC to solve a particular problem. The Enhancements were developed for in-house use, and so contain only those commands which we needed. If the Enhancements had been written as a commercial product for sale, they would be less idiosyncratic. Instead of absurdities such as retrieving half of an old random number seed, there would be a command for drawing Hi-Res circles. It just so happened that we didn’t need any circles. So you don’t get circles … life is cruel.
The last group of Enhancement commands make BASIC more readable while adding no capabilities. ‘DBL POKE, for example, POKEs a 16-bit word into memory. You can do it without the enhancements with two regular POKE statements. ‘PI replaces 3.14159. ‘BELL replaces PRINT CHR$(7), and so on. Need I go on?
How to Get the Enhancements
I’ve covered the major Enhancements commands. Any commands which I haven’t discussed are either self-explanatory or rarely used. As one of the Enhancements programmers, I can not remain impartial; yet I feel that the Enhancements, at either $4 or $15 (take your pick) is an unbeatable bargain. The Enhancements are available from A.P.P.L.E. for four dollars, the usual price for two disks of public domain software. It comes with documentation on disk as ProDOS text files. The Enhancements are also available from yours truly (68 Roseland St., Sommerville Mass. 02143) for $15, including a 50-page printed manual and one free upgrade disk (which will be sent to you later, or maybe never – how’s that for a guarantee?). Future upgrades may include Double-HiRes graphics support or Lasar 128 compatibility.