Classic Computer Magazine Archive START VOL. 1 NO. 3 / WINTER 1986

GETTING AROUND ST BASIC
CODE THE DRAGON'S MAZE

by David Plotkin

ST BASIC may be slow. It may be clumsy. It may have more windows than a Victorian greenhouse. But it's FREE! So, rather than look a gift horse in the mouse, let's see what we can do with this mightily maligned language. David Plotkin offers some tips, tricks and techniques for getting around in ST BASIC. Included on your START disk is the Dragon's Maze, an example game. You'll find the fire breather in the DRAGON.STQ folder.

I bought my Atari ST to program it. At the time, there was little else you could do. The current flood of software had yet to appear; there were no spreadsheets, no games, and only one rather limited word processor. But ST BASIC was included with the machine at no extra cost. A freebie. It seemed logical to take advantage of it.

BASIC is the most popular computer language ever developed, so it is reasonable to expect many want to use it for their programming efforts. ST BASIC is similar to the many versions of Microsoft BASIC available on other computers, and this means those familiar with Atari 8-bit BASIC will have to adapt to a whole new dialect. Chief differences include disk I/O and string handling. Plus, you're sure to miss the great screen editor built into the old Ataris. But those familiar with Microsoft BASIC (which includes most of the remainder of the microcomputer world) could he testing out their first program in short order.

This article is meant to give you an idea of what using ST BASIC is like. Along the way, I will point out some of its problems and suggest tricks and techniques to solve-or at least circumvent- a few of them. Even if you didn't buy your ST to program, eventually you may want to try this most creative of computer pursuits. This article is for you too.

To hear tell, ST BASIC is not a good language. People complain about the bugs, arithmetic errors, cluttering windows, clumsy GEM support (what there is of it) and missing features. These complaints have some merit, but recently it has gotten as fashionable to trash ST BAS1C as it was to complain about the food at the school cafeteria. Actually, most of the time the cafeteria served satisfactory meals, just as ST BASIC can satisfy many of the tasks usually expected of BASIC. These include such things as mortgage calculations, simple utilities, and simple graphics. ST BASIC introduces menus and windows to assist your programming efforts, and includes powerful debugging commands, like TRACE and FOLLOW, to isolate suspected sections of code. As an engineer, many of the uses I have for a home computer can he well filled by ST BASIC.

WE DO WINDOWS

The most frequent complaint I hear about ST BASIC is the way it uses windows. Many programmers think that windows don't belong in the programming environment. They prefer the single, full screen for entering and editing code, which is then replaced by the output screen when they run the program. Many computers, including the 8-bit Ataris, operate in just this fashion.

Multiple windows can be useful. For example. seeing your code on the screen as you watch your output helps in debugging. The problem is ST BASIC has too many windows: the Command window, for entering commands; the List window, to list the program; the Edit window, to alter and enter the program; and the Output window, where the running program appears. You can't really see all these windows on the screen at once, so the screen constantly rearranges as active windows move in front of dormant windows. GEM is fairly fast, but all this window juggling quickly hogs things down.


ST BASIC saves
screens very nicely.


You can do two things to minimize the clumsiness of ST BASIC's windows. First, expand the List and Edit windows to the full width of the screen. This lets you see more of each line. I also expand the Edit window to full screen depth so I can see more lines. Second, use the Edit window as much as possible. You can enter code in the Command window, but you can't edit it once you have pressed [Return]. You must move to the Edit window (by using the EDIT command) to correct any mistakes. The Edit window is perfectly happy to accept new lines, and you can edit there immediately. You can even type over the line number, creating a new line identical to the old one (except for the line number) without affecting the old line.

By specifying a beginning line number with the EDIT command (e.g., EDIT 3050), you may easily move between the Command window and the specified portions of your code in the Edit window. In most cases, only part of your program will be placed within the editor buffer, but more of it is there than meets the eye (or window frame). Use the vertical scroll bars to view portions of your text beyond the frame of the Edit window. Although the Command window may be hidden by the Edit window, you can flip back to the Command window by pressing [Return] and then any key except a number key. The Edit window can even replace the List window, since issuing the EDIT command with a line number lists all lines following, up to the capacity of the edit window buffer.

After writing a program, minimize screen clutter by expanding the Output window to the full size of the screen. The FULLW 2 command will accomplish this. Hiding the window borders and title is trickier. The BASIC FILL command will not cover up the borders. To do that you need GEM VDI calls (see REFERENCE for articles on using GEM's VDI and AES with ST BASIC). The VDI line drawing routines can cover up the borders but several events will cause the borders and title to show through again. INPUT always causes them to show, so get any information you need from the user before you hide the borders. Execute a PRINT statement before you hide the borders because the first PRINT statement will also cause them to show. And warn the user not to click the mouse in the border areas of the window. This too will expose the borders, and I don't know any way to prevent it.

If you don't want to hide the borders of your Output window, how about changing its title? After all, "Output" is not a very imaginative name for your programs window. To change the window title, you must use a call to AES as follows:

3510 Poke Systab+ 24,1 'hide the window
3520 a# = gb 'get globals address
3530 gintin = Peek(a# +8) AES Int_in array
3540 Poke gintin,Peek(Systab + 8) 'Output window handle
3550 Poke gintin + 2,2 'change the window title
3560 s# = gintin + 4 'double address for long Poke
3570 Poke s#,varptr(Title$) 'title of the window
3580 GemSys(105) 'wind_set AES call
3590 Poke systab + 24,0 'show the window

Your window title (Title$ in the above example) can contain up to 40 characters (so you don't overflow the title line in low-resolution mode). I suggest you call the routine again to change the window title back to "Output" when you are done.

Another nice feature would be to save a screen for future use. That way, if you drew over the screen or were providing an Undo feature in a graphics program, you could restore the screen. ST BASIC handles this very nicely. To save your Output screen, use the RESET command, which stores the screen in a buffer To retrieve the buffer to the screen, use OPENW 2. Note that this only works if the BUF GRAPHICS is enabled in the menus.

EDITING YOUR MASTERPIECE

The Edit mode in ST BASIC has some problems. Whenever you change a line in the Edit window, the ST redraws that line in a form I call "ghost" text. This tells you that the change is not yet incorporated in the program, and won't be until (and unless) you press [Return] on the ghost line, whereupon the line returns to normal text. As you get more experienced, this ghost text becomes less useful and more annoying. Ghost text is hard to read: Plus signs become arrows, and many letters are indistinguishable from one another. To disable 'ghost" mode, enter POKE Systab + 2,0 in the Command window.

Typing long lines in the Edit window reveals other difficulties. For one thing, the physical size of the edit window, even when fully open, will not display all the characters when a line exceeds the right boundary of the window. To see these characters, you have to scroll horizontally. The WIDTH statement, which could have been used to regulate this, does not operate in Edit or Command mode. If I have a lot of long lines to edit, I leave BASIC and edit the program in a word processor like 1ST Word.

THE WAYS AROUND

ST BASIC is missing some features and other included features don't work properly. For many of these, however, satisfactory alternative methods get the job done.

INKEY$, a command common to many BASICs, enables the computer to check the keyboard for a key press. Unlike INPUT, the computer does not stop and wait for a key and/or a [Return]. It reads the keyboard "on the fly," as shown here:

10 A$ = Inkey$:If A$ " "Then Goto 10 'no key pressed
20 Print A$

Many games and utilities written in Microsoft BASIC use INKEY$ to read arrow keys as a substitute for a joystick. But INKEY$, as implemented in ST BASIC, doesn't work. If you type in the short program segment above and run it, it will never exit; INKEY$ fails to detect the key press. To get out of this program, pull down the Run menu with your mouse and click on Break, then click on Stop. The reasons for this bug are involved and of no great importance. The best alternative is to use the INP function. INP gets input from a variety of devices. To get a keystroke, use the following:

10 A = INP(2):IF A = 0 THEN Goto 10 '2 for the keyboard
20 Print Chr$(A)

This works just as well as INKEY$ should. For your reference, the key codes returned by the arrow keys are: Up arrow- 200; Left arrow- 203; Right arrow- 205; Down arrow- 208.

FIGURE 1

ST BASIC does not support the mouse or the joystick. For the mouse, you can use a VDI call, but I don't know of any VDI call for the joystick. A memory location that is affected by the joystick, address $FFFC02, can be used in a joystick read routine as follows:

3470 Poke &HFFFC02,&H0012 'turn off the mouse
3480 Poke &HFFFC02,&H0014 'turn on the joystick
3485 Joystick = Peek(&HFFFC02)

This method is not foolproof. For one thing, a negative value in this location means the fire button is pressed. But the address starts out with a negative number until the first time you move the stick. After that, the joystick location reads 255 when you aren't pressing on the stick or pushing the button. Also, pressing keyboard keys affects this location, sometimes returning a negative number. So keep your hands off the keyboard if you are reading the joystick button. The values in the joystick location correspond to the joystick directions as shown in Figure 1.

I find it strange that ST BASIC doesn't have any commands to change the color palette. You are stuck with the default colors from BASIC, unless you fall back on VDI. The following code shows how to set any of the color registers to one of the 512 colors available:

1160 Poke Contrl,14:Poke Contrl+ 2,0
1165 Poke Contrl+6,4:Poke Intin,2 'set up. Intin contains the color register (2)
1170 Poke Intin + 2,0:Poke Intin + 4,800: Poke Intin + 6,0 'put in the color values of R,G,and B
1180 VdiSys(1) 'set register 2 to green

When you try the SOUND command, you will notice that only channel 1 is audible. Sounds played through channels 2 and 3 don't make any noise. To enable all three voices, you must issue the WAVE 7 command.

The DEFINT function has a well hidden bug. As designed, DEFINT should define as integers any variables which begin with the letters following the DEFINT command:

10 Defint A-C,X 'defines all variables starting with A,B,C,X as integers.

The advantage to using integer arithmetic is speed; your program runs faster. However, a problem arises while debugging programs using DEFINT defined variables. Suppose you break into the program and use the Command window to PRINT out the values of variables. Any variable that begins with a letter specified in the DEFINT will print out as 0, unless it is an array, in which case the array elements are equal to -4096! This does not affect the program during its run, but such behavior makes debugging much more difficult. To get around this, you can either accept a slower running speed until the program is debugged (whereupon you can add the DEFINT), or declare each variable as an integer explicitly using the % symbol next to the variable name.

At first encounter, ST BASIC's FILL routine doesn't seem to work right. This is an easy one. The manual has reversed the parameters in the COLOR statement which pertain to the fill style and type. For example, to choose the fill pattern 2,24, use the statement COLOR n,n,n,24,2 (the three n's represent any valid parameters). When you are finished filling, remember to set the fill style and type back to 1,1 so that future solid fills work correctly.

In ST BASIC, when a running program attempts to open and read a text file, the first character of the file is lost. To solve the problem, begin the file with an innocuous character such as a carriage return, that won't be missed when it gets lost.

NO WAYS AROUND

Some limitations of ST BASIC are beyond my abilities to solve. For one thing, the floating-point calculations are inaccurate. So be wary of calculations, such as Square Root, Log, and Trig, which depend on the floating-point routines. An inaccurate floating-point result may cause a perfectly good equation to generate an error. We'll have to wait for Atari to fix this one.

Your ST can keep track of the time and date for stamping files. You can enter the time/date using the Control Panel, or have it done automatically by one of the clock cartridges now available. So far, though, I haven't been able to figure out how to access the system clock using BASIC. The clock function is at the GEMDOS level (meaning that it is buried deeper than even AES/VDI) so it may not be available to BASIC.

Finally it would be nice to have easier access to the VDI and AES functions. These are the GEM routines which create windows, read the mouse, and perform all the special graphics effects which, after all, are the main reason most people bought the ST. The current GEM support is via the function call number, requiring not only that you know (or can find out) the number of the call you want to use, but also know what parameters you'll need and how to use the call. This information is available (see REFERENCE) but can be hard to dig out, since it is not in your BASIC manual. Also, since you can't build and use resource files in ST BASIC, menus and dialog boxes are not accessible. Messages from GEM are also not available, so anything that depends on receiving messages is not possible. Message-based items include such things as reading the menu selections and manipulating the windows.

THE DRAGON'S MAZE

The program DRAGON.BAS is on your START disk primarily to demonstrate many of the techniques discussed in this article. The original concept of the game came from Terry Pack of San Leandro Computer Club. Get your ST BASIC going, then load and run DRAGON.BAS.

The Dragon's Maze is a one person game where you control a red dot which starts out at the entrance to a maze. The dragon, represented by a green dot, starts out at the exit of the maze. The dragon will move each time you do, and the object of the game is to get by the dragon and exit the maze. You may guide your character either with the arrow keys or by a joystick plugged into port 0. The program will prompt you for the method of control you prefer.

You also choose whether the maze will be visible while you are playing the game. It will always be visible while it is being drawn, so you can study it. I must warn you that the game doesn't pose much of a challenge if the maze is visible. The visible maze was included primarily for children and to let you see how the game works. The maze will be different each time you play the game, though, so the hidden maze is quite a challenge. The parts of the maze become visible as you bump into walls-so you can see where you have been, but not where you are going. The game plays best in low resolution mode, although it will work in medium resolution. Note that when you reach the exit, you must move right to actually exit the maze before the game will realize you have reached the exit. Good luck, and watch out for the dragon!

REFERENCE:

BOOKS

  • Understanding Atari ST BASIC Programming, SYBEX Inc. ($17.95). Perhaps the best of the books on ST BASIC at this point. A professional-looking, thorough examination of the language with plenty of example programs.
  • ST BASIC Training Guide, Abacus Books ($16.95). A well written guide to using the ST BASIC commands, including GEM. Does not address the more advanced commands, such as WAVE.
  • ST Trick and Tips, Abacus Books ($16.95). The first section expands on some of the more advanced BASIC commands. This book is laced with typos, so be careful.
  • ST GEM Programmer's Reference Guide, Abacus Books ($19.95). This and the following book are currently the only thorough source of GEM information outside of the Atari Development Package. You will have to translate the GEM information presented here to ST BASIC for your use. Almost all VDI and AES routines are described in this book.
  • Elementary ST BASIC, Compute! Books ($14.95). A tutorial and reference guide to ST BASIC. Includes complete descriptions of all ST BASIC commands. $14.95
  • First Book of the Atari ST, Compute! Books ($16.95). Numerous programs written in ST BASIC, plus tutorials on using GEM from BASIC.
  • ST Programmer's Guide, Compute Books ($16.95). A large section of this book is devoted to explanations of ST BASIC commands and how to use them.
PERIODICALS
  • Antic Magazine: ST BASIC Disk I/O, May 1986; Control GEM with ST BASIC, April 1986; ST BASIC VDI Calls, May 1986.
  • Compute! Magazine: Adding System Power to ST BASIC, April and May, 1986; ST Hints and Tips, June 1986; ST Outlook, a series beginning September 1986.
  • Analog Magazine: GEMSYS(), April 1986

LIST OF MANUFACTURERS:

  • Abacus Software
    P.O. Box 7211
    Grand Rapids, Ml 49510
    (616) 241-5510
  • Analog Magazine
    P.O. Box 23
    Worcester, MA 01603
    (617) 892-3488
  • Antic Publishing
    524 Second Street
    San Francisco, CA 94107
    (415) 957-0886
  • Compute! Publications
    P.O. Box 5406
    Greensboro, NC 27403
    (919) 275-9809
  • SYBEX Computer Books
    2344 Sixth Street
    Berkeley, CA 94710
    (415) 848-8233
ALTERNATIVES

As of September 1986 Atari was preparing to release a new, improved ST BASIC. Sources at Atari told START that the new version would be faster, more accurate, and would include new commands to access the BIOS, XBIOS, and GEMDOS. They also said that although there would be some changes in the editor, the multiple-window interface would remain essentially the same. Like the original ST BASIC, the new implementation will he bundled free with new STs. LOGO, NeoChrome, and 1ST Word, however, will no longer he included in the package.

But if ST BASIC-old or new-can't handle all your needs, you might consider some of the other BASICs which are beginning to appear. Essentially, there are two types; compilers and interpreters.

Compiler BASICs require you first to write the source code with some form of editor, and then run it through the compiler program which turns out executable, standalone object code. The disadvantage of compilers is that the production of a runnable program is time consuming and complicated. The big advantage is that the end program is independent of the BASIC. Also, compiled BASIC programs run faster than interpreted ones.

An interpreted BASIC interprets each line as the program is run. Just write your program and run it. The advantage is instant gratification; you can try things out and see the results immediately. The disadvantage is that your program is usually tied to whatever dialect of BASIC you are using. If you want to send your program to friends. they will all need the same BASIC to he able to run it. Also, interpreted BASICs are usually very slow. ST BASIC is an interpreted BASIC. The following BASICs are divided by type. The first BASICs to arrive were compiler types. In general, they are not designed for the beginning programmer or hobbyist. Some of them are as complicated to use as Alcyon C. Interpreted BASICs have been much slower to arrive. As of September 1986, only one interpreted BASIC was available, apart from ST BASIC.

THE COMPILERS

Softworks BASIC-A compiled BASIC, you use a word processor (not included) to write your source code. Softworks BASIC has GEM support in the form of "Toolbox" commands but, apart from a list, the slim, 90-page documentation contains no information at all on how to use the GEM commands. No graphics support is offered except via GEM. (See review in Antic, October 1986.)

Softworks Limited
2944 N. Broadway
Chicago, IL 60657
(312) 975-4030
$79
CIRCLE 348 ON READER SERVICE CARD

LDW BASIC-Also a compiler but for ST BASIC code. The program itself is slow and disk hungry. but it does generate very fast 68000 machine code. LDW BASIC offers some minor enhancements (no line numbers. longer arrays), with more promised in future revisions. (See review in Antic November 1986.)

Logic Design Works
780 Montague Expressway. Ste. 205
San Jose, CA 95131
(408) 435-1445
CIRCLE 349 ON READER SERVICE CARD

Philon BASIC-This compiler comes on four disks and does not include a text editor so, again, you have to use a word processor. It includes virtually no graphics support and no GEM support.

Philon
641 Avenue of the Americas
New York, NY 10011
(212) 807-0303
$129
CIRCLE 350 ON READER SERVICE CARD

THE INTERPRETERS

Henry's Fundamental BASIC- Eagerly awaited as the first real alternative to ST BASIC, this interpreted BASIC was "accidentally" released for review last April and was filled with bugs. Contacted recently, a company spokesman stated that the persons responsible for the premature release are no longer with the company. The completed product is expected before the end of the year.

Philon
641 Avenue of the Americas
New York, NY 10011
(212) 807-0303
$49
CIRCLE 351 ON READER SERVICE CARD

Fast ST BASIC- Without a doubt, thc hottest BASIC we've seen for the ST. This interpreted BASIC comes on a cartridge and is extremely fast. START received a prerelease version just before press time and our first impression was very positive. Fast ST BASIC is from England and was designed specifically for the ST. It includes special commands to access GEM. For example DRAWMENU will install a user-defined menu bar. The package includes the cartridge, a 400-page spiral-bound manual, and a disk packed with sample programs (including such tempting goodies as a software-driven artificial speech module). In September, Fast ST BASIC was released in England at a price of £79 (approximately $120). No American distributor had yet been chosen.

Computer Concepts
Gaddesden Place
Hemel Hempstead
Hertfordshire HP2 6EX
England
CIRCLE 352 ON READER SERVICE CARD

MemSoft ST BASIC-We found this interpreted BASIC from France mentioned in several user's newsletters. The company plans to release the software free and charge for the documentation. At press time we had received no further information from the company.

MemSoft
3, rue Meyerbeer
06000 Nice, France