BASIC Utilities Package

by: Barry Kolbe

Publication date: November 1989

With the BASIC Utilities Package, you can program in BASIC and still access the disk functions like: directory, locking files, deleting files. Normally, to do these func-tions you would have to save your program, type DOS and wait until DUP.SYS loaded. Then it was back to BASIC, reload your program, etc. With BUP.SYS you merely type "DIR" for a disk directory. That's all there is to it. Your program remains intact. And that's not all. You also get automatic line numbering and renumbering, not to mention decimal and hex conversions at your fingertips. And there's more! List the variables in your program and their line numbers, and trace your program while it is running.

Typing it in
BUP.SYS is a machine-language program and must be typed in using the M/L Editor. Listing 1 is the data that will create your copy of the BASIC Utilities Package. You should type it using the M/L Editor, found elsewhere in this issue, and name the resulting file AUTORUN.SYS.

Loading BUP.SYS
The BASIC Utilities Package will load automatically when you boot your computer with a disk containing DOS and the AUTORUN.SYS file you created from Listing 1. The message "BASIC Utilities Package" will appear, followed by the BASIC prompt "READY". BUP.SYS remains in memory until you type DOS or turn the computer off.

BUP.SYS supports 13 commands, shown in format below:

BUP.SYS Commands
DIR
PRO "D:filespec.ext
UNP "D:filespec.ext
NAM "D:filespec1.ext, filespec2.ext
ERA "D:filespec.ext
REM [nnnn,nnnn]
NUM [nnnn,nnnn]
TRA OFF
DEC nnnn
HEX [$]nnnn
LVA
DOS

All commands are three letters in length, with no spaces allowed in the first three let-ters. After the first three letters, spaces are removed. For example, HEX $ A0 00 is crunched down to HEX$A000.

DIR gives a listing of the disk directory.

PRO, UNP, NAM and ERA are file management commands. They lock (protect), unlock (unprotect), rename and erase files on disk. Think carefully before using ERA you are not asked if you are sure! Once you hit Return, your file is erased.

REN is the renumber command. The first number following REN is the new starting line number and the second is the increment between lines. For example, REN 100,10 makes the first program Line 100, the next 110, the next 120 and so on. More on REN later. Typing REN [Return] gives default values of 10 and 10.

NUM is the auto line-numbering com-mand. As in REN, the first number is the first line number and the second is the increment between lines. The default values are 10 and 10 if you type NUM [Return]. If a program is in memory, NUM [Return] will start numbering at the last line (plus the increment, of course). To stop auto line-numbering, hit the break key. Do not press Reset! Disastrous things may happen if you do.

NUM will not allow you to type over an already existing line. For example, if Line 100 exists and you type NUM 100,10, no auto line-numbering will be done. No mes-sage appears, just the READY prompt. Even while NUM is in operation, it will quit if you are about to type over an exist-ing line.

TRA allows you to trace a BASIC pro-gram. When you type TRA [Return] an extra display line is set up above the normal screen. The message "EXECUTING LINE: 032768" is displayed on this line. When you run a BASIC program, this message is updated 60 times a second during the vertical blank. Consequently, it may be a blur at times. Infinite loops are easy to spot. Trace works in any graphics mode. It will stay in effect until you remove it by typing OFF [Return]. Trace uses the immediate vertical blank interrupt, so don't use Trace if your program also uses that interrupt vector.

OFF turns off the Trace function and removes the extra display line. I would recommend turning it off before performing disk commands. Whenever BUP.SYS uses the disk drive, it automatically turns TRACE Off.

DEC converts any decimal number from 0 to 65535 to its hex equivalent. If you type in anything other than a whole number in this range, the result should not be trusted.

HEX converts any four-digit hex number to its decimal equivalent. A "$" is optional. For example: HEXA000 and HEX$A000 are both acceptable.

LVA lists the variables in your BASIC program and the line numbers in which they appear.

Now that we've covered the basic commands, we must turn our attention back to renumber.

REN, in addition to renumbering the program lines, renumbers internal line references. There are nine program statements that can use line numbers. They and their BASIC tokens are:

Token Statement
4
10
11
12
13
35
7(27)
30(30)
30(24)
LIST
GOTO
GO TO
GOSUB
TRAP
RESTORE
IF(THEN)
ON(GOTO)
ON(GOSUB)

De Re Atari has a nice explanation of tokenized BASIC. ANALOG issues 25 and 26 also have articles on this subject. Each statement can be followed by a line number(s), variable(s) or algebraic expression(s). For example:

    1. GOTO 1050
    2. LIST 1040,1100
    3. GOSUB N4
    4. RESTORE 240+Q
    5. TRAP 15*P
    6. ON Z GOSUB 20,N,25,6*T,30
    7. ON T GOTO 1000,1100,1200,1300

The numbers or expressions following the statements are internal line references; REN cannot decipher all of these. REN will only renumber an internal line reference if it is an actual number. Only in examples 1, 2 and 7 would all internal lines be renumbered. The others would cause a message to be sent to the screen.

The three conditions and their messages are shown in Table 1.

# Message
1 A renumbered line would be >=32768. No renumbering done.
Line > = 32768.
2 An internal line number cannot be found. It is not renumbered.
NF-100
3 An internal line reference is a variable or contains a variable.
VR-540

Table 1

To remedy the first condition, choose a smaller first line number and/or a smaller increment. The second condition means that you are missing a program line. For example, Line 100 might be "100 GOTO 2000" when Line 2000 doesn't exist.

The last type is the most frustrating to deal with. Examples 3, 4, 5 and 6 from above would result in a VR-line number message. Whenever REN encounters one of those special nine tokens, it checks whether it is followed by a line number. If it is a line number, that line number is renumbered. If not, a VR message is given.

If a list of line numbers, separated by commas, is possible (types 2, 6 and 7), these are renumbered until a variable is encountered. If a variable is found, all renumbering on that statement is halted and the next statement on the line or the next line is checked for one of the nine tokens. Again, the VR message would be sent to the screen. In example 6, the 20 would be renumbered, but no others, not even the 25 or 30.

A TRAP statement with a line greater than 32767 would also give an NF message, but this type of TRAP is used to shut off a previous TRAP and so doesn't need to be renumbered.

If LIST is not followed by a line number, it is listed as a VR. This doesn't represent a problem.

Except for the exceptions just noted, all lines printed on the screen with either NF or VR need to be examined and any necessary changes made. Save a copy of the unrenumbered program in case you need to check line numbers.

The message "Program renumbered" is displayed on the screen when the process is complete. It should not take more than a few seconds.

Anomalies
Some unusual things have happened to me while using BUP.SYS. An IF-THEN statement, such as "20 IF I$='R' THEN POP:GOTO 240" resulted in a VR-20 message when I renumbered it. Even though Line 240 existed, the message VR (NF) was sent to the screen. I'll try to explain why. In tokenized BASIC, following the token for THEN is a number (zero-255), which gives the offset to the next statement on the line. REN checks the token after the THEN token to see whether it is a line number. The token for a number is 14. Guess what the offset to the next statement is in Line 20. Yes, it is 14! The same as the token for a number. Since POP is not a number, the VR message was printed.

Originally, I used UNL as the command to UNLOCK files. I changed it to UNP so it is more like DOS XL. One Saturday my son, Philip, was trying out BUP.SYS. Needless to say, he was impressed! Then Phil decided to work with Clayton Walnum's programs from "Adventurous Programming." He got to the point where he was to "UNLOCK DOOR?" The screen looked like this:

     WHAT NOW? UNLOCK DOOR
     ERROR # 146
     READY
     WHAT NOW?

Remember that BUP.SYS parses (scans) all inputs before passing them on to BASIC. BUP.SYS thought he was trying to UNLOCK a file! We changed the verb to KEY to make the program work with BUP.SYS. It was also interesting to watch the program work with the TRACE function.

Technical Notes
BUP.SYS is a BASIC Utilities Package, so the BASIC cartridge must be present to use it. BUP.SYS loads at $2000 and moves LOMEM to $2AFB, using 2,811 bytes of memory. After loading, BUP.SYS clears the stack and jumps to the BASIC cartridge. If BASIC is not there, there will certainly be a lockup. In the initialization process, it wedges itself into the editor's Get-Byte routine. By doing this, an immediate-mode command is scanned by BUP.SYS before sending it to BASIC. In this way, BUP.SYS can take control if the command is one it recognizes. The Put-Byte routine is used to print messages on the screen.

BUP.SYS works fine with DOS 2.0 and 2.5, but has serious problems with DOS XL and perhaps others. Two vertical blanks are used. One is for the TRACE command. The other is used by auto line-numbering. BUP.SYS is "protected" from Reset to prevent its erasure. But if I were you, I would not press Reset while using auto number-ing, renumber or TRACE. I shudder to think of a program that is partially renum-bered. Any other time, pressing Reset should present no difficulty. If you do get stuck, typing X=USR(8192) will probably fix things by reinitializing BUP.SYS.

Conclusion
I think you'll agree that a program like BUP.SYS has been needed for some time. I hope it will make your programming easier.


Barry Kolbe is part of the BBK Programming team, which is responsible for such ANALOG programs as The BBK Artist, The BBK Monitor, and The ANALOG Database. He is a teacher in Wisconsin.

© 2008 Bryan P. Schappel • Valid XHTML Transitional • Valid CSS