BASIC/XA
Development tools for ATARI BASIC programmers
by Thomas Newton
by Thomas Newton
Program and Manual Contents Copyright 1982 Thomas D.
Newton
October 2001 Freeware Distribution
(version 1.1)
This program is copyrighted, but this distribution is free of charge for non-commercial use.
You may distribute copies of the freeware distribution if you include this unaltered copyright notice, do not charge for BASIC/XA (as opposed to the service of distributing it), and do not impose restrictions that go beyond the ones in this copyright notice. Modified copies must be clearly marked as such. Since this program is free, there are no warranties, either express or implied.
This distribution does not include the Atari DOS files DOS.SYS and DUP.SYS that came with the Atari Program Exchange diskette product (APX-20177). Atari held the DOS copyrights. Recipients of this distribution must use their own, legal copies of Atari DOS to reconstitute a bootable BASIC/XA diskette or diskette image.
The following are trademarks of Atari, Inc.: ATARI, ATARI 400 Home Computer, ATARI 800 Home Computer, ATARI 410 Program Recorder, ATARI 810 Disk Drive, ATARI 820 40-Column Printer, ATARI 822 Thermal Printer, ATARI 825 80-Column Printer, ATARI 830 Acoustic Modem, and ATARI 850 Interface Module.
TABLE OF CONTENTS
- INTRODUCTION
- GETTING STARTED
- USING BASIC/XA
- CUSTOMIZING THE PROGRAM
- TRANSFERRING THE CASSETTE VERSION TO DISKETTE
- ADVANCED
TECHNICAL INFORMATION
- Combining BASIC/XA with other AUTORUN.SYS programs
- The PREPARE.BAS program
- The ATARI 850 Interface Module Handler
- Subroutines in
BASIC/XA
- TITLE
- INIT
- NEWDOS
- MENU
- OUTCHR
- LISTV
- DUMP
- VALUE
- VALSUB
- PINT
- PFLT
- CHANGE
- GETVAR
- FINDVAR
- DELETE2
- INSERT
- DELETE
- LINES
- XREF
- XREFSUB
- TOKEN
- DELLIN
- GETTWO
- RENUM
- RENSUB
- GETNEW
- CHECK
- CHSUB
- BASIC
- DOS
- RESTORE
- INPUT
- Source Code (Advanced Programmers Only)
1 INTRODUCTION
1.1 OVERVIEW
EXTENDED ATARI BASIC (BASIC/XA) helps you write programs in Atari BASIC. It can tell you what variables you have used in your program, their values and dimensions, and which lines use them. BASIC/XA also lets you change variable names, delete a range of lines from your program, renumber your program, and check your program for bad GOTO statements and syntax errors.
This automatically loading program is written in machine language and uses about 4000 bytes of memory. A BASIC program included with both versions lets you relocate the diskette version for your system and provides cassette owners with a way to transfer BASIC/XA to diskette.
To use BASIC/XA, just type DOS when the READY prompt displays. The screen will clear and display your choices, in the style of the DOS menu. Displaying the real DOS menu is one of BASIC/XA's menu choices.
1.2 REQUIRED ACCESSORIES
- Atari BASIC Language Cartridge
- Cassette version
- 16K RAM
- ATARI 410 Program Recorder
- 16K RAM
- Diskette version
- 24K RAM
- ATARI 810 Disk Drive
- 24K RAM
1.3 OPTIONAL ACCESSORIES
- ATARI printer or equivalent printer
1.4 RELATED PUBLICATIONS
- ATARI BASIC Reference Manual
The following publications aren't needed for using BASIC/XA, but advanced assembly language programmers who want to study the [source code] listings [and documentation] in the ADVANCED TECHNICAL INFORMATION section should have these materials.
- ATARI Operating System User's
Manual and Hardware Manual
(CO16555)
- Winner, Lane, "The Atari Tutorial, Part 6: ATARI BASIC,"
BYTE, February 1982, pp. 91-118. This material also appears
in De Re ATARI (APX-90008).
- ATARI Disk Operating System II Reference Manual (CO16347)
1.5 CONTACTING THE AUTHOR
Users wishing to contact the author about BASIC/XA may write to him at:
ThomasNewton@absolutely.no.spam.aol.com (remove anti-spam part of address before writing)
The Wrightsville Beach address listed in the 1982 manual is no longer valid. Please don't send mail there.
2 GETTING STARTED
The instructions in this section are for the original APX distributions. To make a bootable diskette out of the freeware distribution, you must prepare a bootable DOS diskette that has just DOS.SYS and DUP.SYS on it, then copy the freeware BASIC/XA files onto it.
2.1 LOADING BASIC/XA INTO COMPUTER MEMORY
- Insert the ATARI BASIC Language Cartridge in the (left)
cartridge slot of your computer.
- If you have the cassette
version of BASIC/XA:
a. Have your computer turned OFF.
b. Insert the BASIC/XA cassette into the program recorder's cassette holder and press REWIND until the tape rewinds completely. Then press PLAY to prepare the program recorder for loading the program.
c. Turn on the computer while holding down the START key, and then turn on your TV set.
d. When you hear a beep, release the START key and press the RETURN key. The program will load into computer memory and start automatically.
- If you have the diskette
version of BASIC/XA:
a. Have your computer turned OFF.
b. Turn on your disk drive.
c. When the BUSY light goes out, open the disk drive door and insert the BASIC/XA diskette with the label in the lower right-hand corner nearest to you. (Use disk drive one if you have more than one drive.)
d. Turn on your computer and your TV set. The program will load into computer memory and start automatically.
2.2 THE FIRST DISPLAY SCREEN
After BASIC/XA loads into computer memory, you'll see:
*** EXTENDED ATARI BASIC *** Version 1.1 *** Copyright 1982 Thomas Newton READY
3 USING BASIC/XA
3.1 BASIC/XA'S DISPLAY SCREEN
To use BASIC/XA, load your program into computer memory. Then type DOS and press the RETURN key to display this menu:
EXTENDED ATARI BASIC VERSION 1.1 COPYRIGHT 1982 THOMAS NEWTON A. LIST VARIABLES F. RENUMBER B. VARIABLE VALUES G. CHECK PROGRAM C. CHANGE NAME H. NEW OUTPUT FILE D. CROSS REFERENCE I. RETURN TO BASIC E. DELETE LINES J. GO TO DOS MENU SELECT ITEM OR RETURN FOR MENU
To select a command, type its letter and press RETURN. Press RETURN again to redisplay the menu.
3.2 COMMANDS
The description of each command is divided into the following sections:
- Function -- describes what the command does.
- Using it -- shows the questions you must answer when you use
the command. Your responses are underlined. If you're in BASIC's
READY mode, you should type DOS to display the BASIC/XA menu.
- Error messages -- explains the error messages that display if
you make a mistake or if the computer can't print to your NEW
OUTPUT FILE.
- Warning messages -- explains the warning messages you may see
when you use the RENUMBER and CHECK PROGRAM commands. These
messages tell you about expressions used as line numbers and
errors in your program.
- Example -- demonstrates the use of the command with a small
program.
- Notes -- lists additional information about the command that
you should know.
- If your program uses IOCB #5 (OPEN #5, PRINT #5, and so on),
you should CLOSE it before typing DOS to display the BASIC/XA
menu.
- If you have the diskette version of BASIC/XA, you must have a
MEM.SAV file on the diskette in disk drive one when you go to the
DOS menu with BASIC/XA's J command. While in DOS, you must not
give permission for DOS to use the program area. The same diskette
must be in drive one when you return to BASIC as when yuou went to
the DOS menu.
- If you want to use the DUPLICATE DISK command, turn the
computer off and turn it back on using a diskette that doesn't
contain BASIC/XA. You can now allow DOS to use the program area
(if the diskette does not have a MEM.SAV file, DOS will use it
automatically). You may also want to follow this procedure when
using the COPY FILE and DUPLICATE FILE commands, since allowing
DOS to use all of memory results in far less diskette
swapping.
3.2.1 COMMAND A: LIST VARIABLES
Function
This command lists the variable names you've used in your program. It also tells you how many variable names are in the table. If you've used command H, NEW OUTPUT FILE, the table prints to the file you selected (e.g., to the printer).
Using it
SELECT ITEM OR RETURN FOR MENU A
Error messages
- INPUT/OUTPUT ERROR -- the computer could not print to your file OR you pressed the BREAK key. If you were sending output to a file, the program closes the file, and the rest of the table prints on the TV screen.
Example
Suppose you enter the following program (your typing is underlined):
READY NEW READY 10 DIM C$(10),A(20) 20 FOR X=1 TO 10 30 A(X)=X*X*X 40 NEXT XNow you want to see all the variable names used in the program:
DOS (screen clears and the BASIC/XA menu appears) SELECT ITEM OR RETURN FOR MENU A VARIABLE NAME TABLE C$ A( X 3 VARIABLES USED SELECT ITEM OR RETURN FOR MENU I READYNotice that the name of array A ended with a "(" character. The name of an array or matrix always ends with a "(", and the name of a string, like C$, always ends with a dollar sign.
Variable names appear in the table in the order you used them in the program.
3.2.2 COMMAND B: VARIABLE VALUES
Function
This command lists the variables used in your program. It also prints the value of simple variables (such as X) and the dimensions of arrays, matrices, and strings. If you've used command H, NEW OUTPUT FILE, the table prints to the file you selected.
Using it
SELECT ITEM OR RETURN FOR MENU B
Error messages
- INPUT/OUTPUT ERROR -- the computer could not print to your file OR you pressed the BREAK key. If you were sending output to a file, the program closes the file, and the rest of the table prints on the TV screen.
Example
Suppose you enter the following program (your typing is underlined):
READY NEW READY 10 DIM C$(10),X(5) 20 FOR B=1 TO 5 30 X(B)=B*B 40 NEXT BNow you want to list the value of B and the dimensions of C$ and X(.
DOS (screen clears and the BASIC/XA menu appears) SELECT ITEM OR RETURN FOR MENU B VARIABLE VALUES C$(...) X(...) B = 0 3 VARIABLES USEDThe computer typed the (...) by C$ and X to let you know that these variables haven't been dimensioned. It also told you that B is zero. Now let's RUN the program and try it again.
SELECT ITEM OR RETURN FOR MENU I READY RUN READY DOS (screen clears and the BASIC/XA menu appears) SELECT ITEM OR RETURN FOR MENU B VARIABLE VALUES C$(10) X(5) B=6 3 VARIABLES USEDThis time, the computer told you the dimensions of C$ and X(. It also told you that B is equal to 6.
[ I'm not sure which version of the manual supplied the following text. ] This might seem hard to believe, since the FOR loop clearly says "FOR B=1 to 5". The reason why B is six is that the computer adds one to B at the end of the loop before it checks to see whether it has finished the loop.
SELECT ITEM OR RETURN FOR MENU I READY PRINT B:REM in case you don't believe it... 6 READY
Notes
VARIABLE VALUES is most useful when you're debugging a program. You can press the BREAK key to stop a running program, type DOS to get the BASIC/XA menu, select VARIABLE VALUES, and then return to BASIC.
Although the computer prints the DIMension of strings, it doesn't print their length. If X$ has been dimensioned, the BASIC command PRINT LEN(X$) will print the length of X$
3.2.3 COMMAND C: CHANGE NAME
Function
This command lets you change the name of any variable in your program. You can make long variable names short, or change short names such as F into more descriptive names such as FOOD.
Using it
SELECT ITEM OR RETURN FOR MENU C CHANGE NAME--OLD VARIABLE NAME? the name the variable has now NEW NAME (MUST BE SAME TYPE)? the name you want to change it toTo return to the SELECT ITEM prompt without changing any names, press RETURN or BREAK in response to either question.
Remember to end the name of an array with the "(" character; for example, array X is named X(. The name of a string variable ends with a dollar sign (example: C$).
Error messages
- LINE TOO LONG -- you entered a name that is more than one
screen line (38 characters) long. CHANGE NAME can only handle
names that are 38 characters long or less.
- NOT USED IN PROGRAM -- a variable name you entered is not used
in the program, so it is impossible to change it.
- BAD VARIABLE NAME -- a variable name must start with a letter
and consist of letters and numbers. The name of an array ends with
a "(" character, and the name of a string ends with a dollar sign.
You also get this message if you type spaces before the variable
name.
- TYPES DO NOT MATCH -- you can only change a simple variable to
a simple variable, an array to an array, or a string to a
string.
- NAME ALREADY EXISTS -- you cannot change a variable name to a
name already used in the program. This prevents you from having
two variables with the same name. You will also get this message
if you try to change a variable name to itself. It is possible to
have a variable named A, an array A, and a string A$, since their
respective names are A, A(, and A$ -- all different.
- NOT ENOUGH MEMORY -- there isn't enough memory to change the
variable name. This happens when the new name is too long or when
you have less than 20 bytes of free memory.
Any error message returns you to the SELECT ITEM OR RETURN FOR READY prompt without changing the variable name.
Example
Suppose you enter the following program (your typing is underlined):
READY NEW READY 10 DIM A(10),D$(5) 20 FOR C=1 TO 10 30 B=C*C:PRINT C,B 40 NEXT CNow you want to change the name of array A, string D$, and variable C:
DOS (screen clears and the BASIC/XA menu appears) SELECT ITEM OR RETURN FOR MENU C CHANGE NAME--OLD VARIABLE NAME? A( NEW NAME (MUST BE SAME TYPE)? ARRAY( SELECT ITEM OR RETURN FOR MENU C CHANGE NAME--OLD VARIABLE NAME? D$ NEW NAME (MUST BE SAME TYPE)? STAT$ SELECT ITEM OR RETURN FOR MENU C CHANGE NAME--OLD VARIABLE NAME? C NEW NAME (MUST BE SAME TYPE)? B NAME ALREADY EXISTSSince variable name B is already used, the computer doesn't permit the change. Instead, it prints an error message.
SELECT ITEM OR RETURN FOR MENU C CHANGE NAME--OLD VARIABLE NAME? C NEW NAME (MUST BE SAME TYPE)? COUNT SELECT ITEM OR RETURN FOR MENU I READY LIST 10 DIM ARRAY(10),STAT$(5) 20 FOR COUNT=1 TO 10 30 B=COUNT*COUNT:PRINT COUNT,B 40 NEXT COUNT READY
Notes
Although you can use variable names like INPUT, PRINT, and so on, avoid doing so, because BASIC may not let you edit your program. If you make this mistake, use CHANGE NAME to change the variable name to one that BASIC likes, such as X or INP.
If you use long lines in your program and you make your variable names too long, you won't be able to edit some of the lines in your program because they'll be more than three screen lines long. To edit these lines, you'll have to shorten the names.
3.2.4 COMMAND D: CROSS REFERENCE
Function
This command lists the variable names used in your program and the lines that use them. It also tells you how many variable names have been used. If you've used command H, NEW OUTPUT FILE, the table prints to the file you selected.
Using it
SELECT ITEM OR RETURN FOR MENU D
Error messages
- INPUT/OUTPUT ERROR -- the computer could not print to your file OR you pressed the BREAK key. If you were sending output to a file, the program closes the file, and the rest of the table prints on the TV screen.
Example
Suppose you enter the following program (your typing is underlined):
READY NEW READY 10 FOR C=1 TO 10 20 B=C*C:PRINT C,B 30 NEXT C PRINT A 0 READYNow you want to list the variables in the program and the lines that use them:
DOS (screen clears and the BASIC/XA menu appears) SELECT ITEM OR RETURN FOR MENU D VARIABLE CROSS REFERENCE TABLE C 10 20 30 B 20 A 3 VARIABLES USED SELECT ITEM OR RETURN FOR MENU I READY
Notes
On the screen, the cross reference table has four columns per line. When you use command H, NEW OUTPUT FILE, to send the table to the printer or a file, the table has ten columns per line (for an 80-column printer). To adjust BASIC/XA for a 40-column printer, see CUSTOMIZING THE PROGRAM.
To remove unused variable names from your program, follow this procedure:
- Load the program into memory.
- If you have a cassette recorder:
a. Type LIST "C:" and press RETURN. When you hear two beeps, place a blank tape in the recorder. Then press the PLAY and RECORD buttons on the recorder, and press the RETURN key on the computer console. The computer will list the program to the cassette.
b. Type NEW and press RETURN to remove the tokenized version of the program and the variable names from memory.
c. Rewind the cassette and press PLAY on the recorder to prepare it for loading the program. Then type ENTER "C:" and press RETURN. When you hear a beep, press RETURN again. The computer will get your program from the cassette. When the READY prompt appears, press STOP on the recorder.
If you have a disk drive:
a. Place a diskette with plenty of free space in drive one. Then type LIST "D:TEMP" and press RETURN. The computer will list the program to diskette.
b. Type NEW and press RETURN to remove the tokenized version of the program and the variable names from memory.
c. Type ENTER "D:TEMP" and press RETURN. The computer will get your program from the diskette.
d. To remove the "D:TEMP" file from the diskette, type XIO 33,#1,0,0,"D:TEMP" and press RETURN.
- Save your program to cassette or diskette. The unused variable names will now be gone.
Normally, BASIC stores your program in a "tokenized" form, meaning that commands like PRINT are stored as a single number. Variable names are stored in a table and referred to by a number. For example, the command PRINT X is translated into two numbers, the number for PRINT and the position of X in the variable name table. If you stop using a variable name, BASIC still keeps it in the table. When you LIST the program to tape or diskette and then ENTER it, BASIC translates the program into numbers all over again. Since unused variable names do not show up in the listing, they are removed from the variable name table.
3.2.5 COMMAND E: DELETE LINES
Function
This command lets you delete a range of lines from your program.
Using it
SELECT ITEM OR RETURN FOR MENU E DELETE--START, END LINES? starting line, ending lineTo return to the SELECT ITEM prompt, press RETURN or BREAK instead of entering the starting and ending lines.
Error messages
- BAD NUMBER -- you didn't type two numbers separated by a
comma.
- LINE TOO LONG -- your response was longer than one line on the
screen.
- NUMBER OUT OF RANGE -- one of the numbers you typed was
negative or greater than 32767. BASIC uses line numbers from 0 to
32767.
- SECOND LINE # MUST BE LARGER -- the first line number must be
smaller than or equal to the second one.
When the program prints any error message, you return to the SELECT ITEM OR RETURN FOR MENU prompt without deleting any lines.
Example
Suppose you enter the following program (your typing is underlined):
READY NEW READY 10 REM THIS LINE WILL REMAIN 20 REM THESE LINES WILL BE DELETED 22 REM 27 REM 30 REM THIS LINE WILL REMAINNow you want to delete lines 20 through 27:
DOS (screen clears and the BASIC/XA menu appears) SELECT ITEM OR RETURN FOR MENU E DELETE--START,END LINES? 20,27 SELECT ITEM OR RETURN FOR MENU I READY LIST 10 REM THIS LINE WILL REMAIN 30 REM THIS LINE WILL REMAIN READY
Notes
If you have many lines to delete, DELETE LINES may take several minutes. DO NOT press SYSTEM RESET or you will lose your program and lock up the computer. Just wait for the program to finish and return to the SELECT ITEM OR RETURN FOR MENU prompt.
For example, typing "400,32767" in response to the DELETE prompt will delete from line 400 to the end of the program.
If you delete a large section of the program, you might remove several variable names from the program. However, the names will still be stored by BASIC. Use the CROSS REFERENCE command to see how many unused variable names are in the table. You can remove unused names by following the steps listed in the notes for the CROSS REFERENCE command.
3.2.6 COMMAND F: RENUMBER
Function
This command lets you renumber your program. You choose the new starting line number and the spacing between lines.
Using it
SELECT ITEM OR RETURN FOR MENU F RENUMBER--NEW STARTING LINE, SPACING? new starting line number, spacing between line numbersIf you press RETURN without entering numbers, RENUMBER uses 10 for the new starting line number and 10 for the spacing between lines.
To return to the SELECT ITEM prompt without renumbering, press the BREAK key when you see the RENUMBER prompt.
Error messages
These messages appear if you answer the RENUMBER prompt incorrectly. You return to the SELECT ITEM prompt without renumbering the program.
- LINE TOO LONG -- your answer was longer than one screen
line.
- BAD NUMBER -- you didn't type two numbers separated by a
comma.
- NUMBER OUT OF RANGE -- one of the numbers you typed was
negative or greater than 32767. BASIC uses line numbers from 0 to
32767.
- SPACING CAN'T BE ZERO -- you cannot have zero spacing between
lines, since all lines would have the same line number.
- CAN'T RENUMBER -- renumbering would result in a line number within SPACING of 32767. For example, if the SPACING was 10, you would get CAN'T RENUMBER if renumbering would result in a line number greater than 32757. Try renumbering the program again with a smaller SPACING.
Warning messages
These messages appear during renumbering. They tell you to check lines in your program.
- EXPRESSION FOUND IN LINE xxx -- an expression or a negative
number follows a GOTO, GO TO, GOSUB, TRAP, RESTORE, LIST, IF/THEN,
ON/GOTO, or ON/GOSUB statement in line xxx. You must update the
expression; if it was in a LIST, ON/GOTO, or ON/GOSUB statement,
you must update line numbers following it in the statement.
- LINE #yyy, FOUND IN LINE xxx, DOES NOT EXIST -- a line number
in a GOTO, GOSUB, etc., statement does not correspond to any line
of the program (for example, GOTO 100 when there is no line 100).
The line number is left unchanged.
- BAD LINE NUMBER IN LINE xxx -- the line number in a GOTO, GOSUB, etc. statement is greater than 32767 (greater than 65535 for TRAP). When you RUN the program, this line will cause an ERROR - 7. The line number is left unchanged.
Example
Suppose you enter the following program (your typing is underlined):
READY NEW READY 10 INPUT A 20 ON A GOSUB 100,200,300 21 PRINT "TEST PROGRAM" 22 TRAP 40000 23 GOTO 23 100 REM SUB1 110 RETURN 300 REM SUB3 305 RETURNNow you want to renumber the program to make room for some statements between lines 21 and 22:
DOS (screen clears and the BASIC/XA menu appears) SELECT ITEM OR RETURN FOR MENU F RENUMBER--NEW STARTING LINE, SPACING? (you press the RETURN key) LINE #200, FOUND IN LINE 20, DOES NOT EXIST SELECT ITEM OR RETURN FOR MENU I READY LIST 10 INPUT A 20 ON A GOSUB 60,200,80 30 PRINT "TEST PROGRAM" 40 TRAP 40000 50 GOTO 50 60 REM SUB1 70 RETURN 80 REM SUB3 90 RETURN READYSince TRAP with a number between 32768 and 65535 cancels previous TRAPs, RENUMBER left the TRAP 40000 alone. In line 20, although the 200 caused an error, the other line numbers were adjusted for the renumbered program.
Notes
DO NOT press SYSTEM RESET or BREAK while RENUMBER is renumbering the program. Most renumbering jobs take only a few seconds.
If you use the LIST command in your program (e.g., 10 LIST), you will get a false EXPRESSION FOUND message if the LIST is to a device, and the line numbers following the device name will NOT be changed. For example, 10 LIST "P:",100,200 will cause an EXPRESSION FOUND message, and the LIST command will not be updated to reflect the new line numbers.
3.2.7 COMMAND G: CHECK PROGRAM
Function
This command lets you check your program for line numbers that don't exist, bad line numbers, INPUT statements without variables, and lines with syntax errors. It also tells you about expressions used as line numbers.
Using it
SELECT ITEM OR RETURN FOR MENU G
Warning messages
- INPUT/OUTPUT ERROR -- you pressed the BREAK key. If you were
sending output to a file, the file is closed and the output of
LIST VARIABLES, VARIABLE VALUES, and CROSS REFERENCE will be sent
to the TV screen.
- EXPRESSION FOUND IN LINE xxx -- an expression or a negative
number follows a GOTO, GO TO, GOSUB, TRAP, RESTORE, LIST, IF/THEN,
ON/GOTO, or ON/GOSUB statement in line xxx. Line numbers following
the expression in the same statement are not checked. This is not
really an error, but you will get this message again when you
renumber the program.
- LINE #yyy, FOUND IN LINE xxx, DOES NOT EXIST -- a line number
in a GOTO, GOSUB, etc., statement does not correspond to any line
in the program (for example GOTO 100 when there is no line 100).
This line will cause an ERROR - 12 when the program is RUN and
reaches the line.
- BAD LINE NUMBER IN LINE xxx -- the line number in a GOTO,
GOSUB, etc., statement is greater than 32767 (greater than 65535
for TRAP). When you RUN the program, this line will cause an ERROR
- 7.
- INPUT BY ITSELF IN LINE xxx -- the INPUT statement in line xxx
is not followed by a variable name. When you RUN the program, this
line will lock the computer up, losing your program. Although
BASIC checks for syntax errors, this is the one syntax error it
doesn't catch until it's too late.
- SYNTAX ERROR IN LINE xxx -- when you entered the line, BASIC told you it contained a syntax error and you didn't fix the line. When you RUN the program, this line will cause an ERROR - 17.
Example
Suppose you enter the following program (your typing is underlined):
READY NEW READY 10 PRINT "YOUR NUMBER" 20 INPUT 30 IF A=3 THEN 20 40 IF A=4 THEN 100 50 TRAP 100000Now you want to check the program for the errors listed above:
DOS (screen clears and the BASIC/XA menu appears) SELECT ITEM OR RETURN FOR MENU G LINE #100, FOUND IN LINE 40, DOES NOT EXIST BAD LINE NUMBER IN LINE 50 INPUT BY ITSELF IN LINE 20 SELECT ITEM OR RETURN FOR MENU I READYCHECK PROGRAM caught three errors: the branch to line 100 in line 40, the TRAP 100000 in line 50, and the INPUT in line 20. If you had RUN this program immediately, the computer would have locked up. Now let's fix the errors and try it again:
20 INPUT A 40 IF A=4 THEN PRINT "OK" 50 TRAP 40000 DOS (screen clears and the BASIC/XA menu appears) SELECT ITEM OR RETURN FOR MENU G SELECT ITEM OR RETURN FOR MENU I READYThis time, CHECK PROGRAM did not find any errors.
Notes
CHECK PROGRAM is most useful for catching bad GOTO and GOSUB statements. Often, you don't find these mistakes until you've RUN a program several times. CHECK PROGRAM catches all these mistakes at once.
CHECK PROGRAM cannot find logical errors in your program, such as setting A to 5 when it should be 6.
3.2.8 COMMAND H: NEW OUTPUT FILE
Function
This command lets you send the LIST VARIABLES, VARIABLE VALUES, and CROSS REFERENCE tables to the printer, a cassette file, or a diskette file. Having a printed copy of these tables is very useful.
Using it
SELECT ITEM OR RETURN FOR MENU H NEW OUTPUT FILE (RETURN FOR SCREEN)? filenameThe filename may be any of the following:
P: Sends tables to the printer
C: Sends tables to the cassette recorder. When you hear two beeps, place a blank tape in the recorder, press PLAY and RECORD, and press RETURN.
D:filename.ext Sends tables to a disk file. Anything that was in the file before will be lost.
Rn: Sends tables to serial port #n of the ATARI 850 Interface. You may have to condition the port with XIO statements before selecting it for printing.
E: or RETURN Sends tables to the screen.
If you were already sending output to a file, the program closes the previous file before opening the new file.
Error messages
- INPUT/OUTPUT ERROR -- you pressed the BREAK key while the
computer was trying to open the file.
- LINE TOO LONG -- the filename you gave was more than one
screen line long.
- CAN'T OPEN FILE -- when the computer tried to open the file,
an error happened. The most common errors are:
- Device timeout -- you selected the printer and a printer
was not connected or it was not turned on. You may also have
left your drive off when you tried to send output to a disk
file.
- Locked file -- you selected a diskette file and it was
locked.
- Diskette write-protected -- the write-protect notch on the
diskette is covered or the diskette does not have a
write-protect notch.
- Bad filename -- you forgot the D: for a diskette filename or the filename was bad.
- Device timeout -- you selected the printer and a printer
was not connected or it was not turned on. You may also have
left your drive off when you tried to send output to a disk
file.
Example
SELECT ITEM OR RETURN FOR MENU H NEW OUTPUT FILE (RETURN FOR SCREEN)? P: SELECT ITEM OR RETURN FOR MENU B SELECT ITEM OR RETURN FOR MENU DBoth the VARIABLE VALUES table and the CROSS REFERENCE table will be sent to the printer.
Notes
If there is an error when the computer tries to print to the file, you will see the INPUT/OUTPUT ERROR message on the screen. The program automatically closes the file and sends the rest of the listing to the screen.
When you select command I, RETURN TO BASIC, or command J, GO TO DOS MENU, the program closes the file. If you select command H again, the program closes the file before opening the new one.
If you have any file open, don't press SYSTEM RESET, because you may lose the file. Once you return to BASIC, go to the DOS menu, or select NEW OUTPUT FILE and send output to the screen, the program closes the file, making it safe to press SYSTEM RESET.
3.2.9 COMMAND I: RETURN TO BASIC
Function
This command lets you return to ATARI BASIC from BASIC/XA.
Using it
SELECT ITEM OR RETURN FOR MENU I READY
Notes
If you were sending output to a file, the file will be closed.
3.2.10 COMMAND J: GO TO DOS MENU
Function
This command lets you go to the DOS menu from BASIC/XA.
Using it
SELECT ITEM OR RETURN FOR MENU J (DOS menu appears on the screen)
Notes
The diskette must have a MEM.SAV file. While you are in DOS, you must not give DOS permission to use the program area. When you return to BASIC (DOS option B or SYSTEM RESET), you must have the same diskette in drive one as when you went to the DOS menu. See IMPORTANT NOTES for more information.
If you were sending output to a file, the file will be closed.
4 CUSTOMIZING THE PROGRAM
4.1 USING CROSS REFERENCE WITH A 40-COLUMN PRINTER
The CROSS REFERENCE command normally prints ten numbers on each printer line. This is fine for 80-column printers, but messy for 40-column ones. To adjust CROSS-REFERENCE for a 40-column printer:
- If you have the cassette version of BASIC/XA (WARNING: Do NOT
use this POKE unless you have loaded BASIC/XA. If you haven't, you
could lock up the computer.):
a. Type POKE 5681,4 for a forty-column printout.
b. To reset for eighty columns, type POKE 5681,10.
- If you have the diskette version of BASIC/XA (WARNING: Do NOT
use this POKE unless you have loaded BASIC/XA. If you haven't, you
could lock up the computer.):
a. Type POKE 11321,4 for a forty-column printout.
b. To reset for eighty columns, type POKE 11321,10.
Each time you load the standard version of BASIC/XA, you must do the POKE if you want to use the program with a forty-column printer.
If you have the diskette version of BASIC/XA, you can avoid the need to do the POKE by preparing a modified version of the program:
- Prepare a diskette that contains the DOS.SYS, DUP.SYS, and
MEM.SAV files. The diskette should not have an AUTORUN.SYS file
(it will be replaced). It should have at least 36 free sectors
(DOS prints the number of free sectors at the end of the directory
listing).
- If you have 24K of RAM, turn your computer off and turn it
back on using a diskette that does not have a copy of BASIC/XA. If
you have an ATARI 850 Interface module, leave it off. These steps
are necessary because CUSTOM.BAS uses all 24K of memory.
- Insert the BASIC/XA diskette into drive one. Type RUN
"D:CUSTOM.BAS" and press RETURN. The program loads into memory and
displays:
EXTENDED ATARI BASIC VERSION 1.1 Copyright 1982 Thomas Newton This program lets you relocate EXTENDED ATARI BASIC for your system. Please hold on while I get ready... Do you want to relocate the program (type Y or N)?
Type N and press RETURN.
- The computer asks:
Do you have an 80-column printer (type Y or N)?
If you have a 40-column printer, type N and press RETURN. If you have an 80-column printer, type Y and press RETURN.
- The computer asks:
Do you want the program to check for an ATARI 850 Interface included with EXTENDED ATARI BASIC (Type Y or N) ?
Type Y and press RETURN.
- The screen clears and displays:
EXTENDED ATARI BASIC VERSION 1.1 Copyright 1982 Thomas Newton Program loads at: 7420 Program ends at : 11491 Columns per line: 4 (10 for an 80-col. printer) Place a system diskette (one that has a copy of DOS) in drive one and press RETURN to write the AUTORUN.SYS file. Press any other key to quit without writing the AUTORUN.SYS file.
- Insert the diskette that you prepared in step 1 into drive one
and press RETURN. The computer saves a copy of BASIC/XA on the
diskette.
- The computer types:
Your disk now contains a copy of EXTENDED ATARI BASIC. To use the program, place the disk in drive one when you turn your system on. READY
4.2 RELOCATING THE PROGRAM FOR AN ALTERED DOS
If you change the number of drive buffers or file buffers that DOS uses (described in the DOS II Reference Manual), you must relocate BASIC/XA to work with your version of DOS. To make a copy of BASIC/XA for your system:
- Prepare a diskette that has the DOS.SYS, DUP.SYS, and MEM.SAV
files. This diskette contains your version of DOS. It should not
have an AUTORUN.SYS file. It should have at least 36 free sectors
(DOS prints the number of free sectors at the end of the directory
listing).
- Turn your computer off. Turn it back on using the diskette you
prepared in step 1. If you have an ATARI 850 Interface Module,
leave it off. Type PRINT PEEK(743)+256*PEEK(744), press RETURN,
and write down the number on the screen.
- Turn your computer off. Turn it back on using the DOS II
Master Diskette. If you have an ATARI 850 Interface Module, leave
it off.
- Insert the BASIC/XA diskette into drive one. Type RUN
"D:CUSTOM.BAS" and press RETURN. The program loads into memory and
displays:
EXTENDED ATARI BASIC VERSION 1.1 Copyright 1982 Thomas Newton This program lets you relocate EXTENDED ATARI BASIC for your system. Please hold on while I get ready... Do you want to relocate the program (type Y or N)?
- Type Y and press RETURN. The computer asks:
Where should the program start (give address in decimal)?
Type the number you wrote down in step 2 and press RETURN. The computer types:
Hold on while I relocate the program
- After the computer finishes, it asks:
Do you have an 80-column printer (type Y or N)?
Answer Y or N and press RETURN.
- The computer asks:
Do you want the program to check for an ATARI 850 Interface included with EXTENDED ATARI BASIC (Type Y or N) ?
Type Y and press RETURN.
- The screen clears and displays:
EXTENDED ATARI BASIC VERSION 1.1 Copyright 1982 Thomas Newton Program loads at: xxxxx Program ends at : yyyyy Columns per line: zz Place a system diskette (one that has a copy of DOS) in drive one and press RETURN to write the AUTORUN.SYS file. Press any other key to quit without writing the AUTORUN.SYS file.
- Insert the diskette that you prepared in step 1 into drive one
and press RETURN. The computer saves a copy of BASIC/XA on the
diskette.
- After the computer saves the program, it types:
Your disk now contains a copy of EXTENDED ATARI BASIC. To use the program, place the disk in drive one when you turn your system on.
5 TRANSFERRING THE CASSETTE VERSION TO DISKETTE
5.1 INTRODUCTION
Although you can't use the first program on the BASIC/XA cassette with a diskette, BASIC/XA includes a second program for use with diskettes.
5.2 TRANSFERRING BASIC/XA
To transfer BASIC/XA to diskette, you need DOS II and at least 24K of RAM.
- Prepare a diskette
a. Insert the ATARI BASIC Language cartridge in the cartridge slot
b. Insert the DOS II Master Diskette in disk drive one.
c. Turn on your computer. Note: If you have an ATARI 850 Interface Module, leave it turned off.
d. When you see the READY prompt, type DOS and press RETURN.
e. When the screen displays the DOS menu, place a new (blank) diskette in drive one and type these underlined responses:
SELECT ITEM OR RETURN FOR MENU I WHICH DRIVE TO FORMAT? 1 TYPE "Y" TO FORMAT DISK 1 Y
The disk drive whirs and clicks for a little while.
SELECT ITEM OR RETURN FOR MENU H WHICH DRIVE TO WRITE DOS FILES TO? 1 TYPE "Y" TO WRITE DOS FILES TO DRIVE 1? Y WRITING NEW DOS FILES SELECT ITEM OR RETURN FOR MENU N TYPE "Y" TO CREATE MEM.SAV Y
You have now prepared the diskette.
SELECT ITEM OR RETURN FOR MENU B
-
READY
- Remove the diskette from drive one. Turn the computer and disk
drive(s) off. Leave the disk drive(s) turned off and load the
program normally. Then turn the computer off. The tape is now
positioned to load the second program.
- Turn the disk drive(s) back on and insert your prepared
diskette (from step 1) into drive one. Turn on the computer, again
leaving the interface module off (if you have one).
- Press PLAY on the recorder. Type CLOAD and press RETURN. When
you hear a bell, press RETURN again. The computer loads the
program into memory and types READY when through.
- Type SAVE "D:CUSTOM.BAS" and press RETURN to save the program
on diskette. To create the AUTORUN.SYS file that loads BASIC/XA:
a. Type RUN. The program displays:
EXTENDED ATARI BASIC VERSION 1.1 Copyright 1982 Thomas Newton This program lets you relocate EXTENDED ATARI BASIC for your system. Please hold on while I get ready... Do you want to relocate the program (type Y or N)?
Type N and press RETURN.
b. The computer asks:
Do you have an 80-column printer (type Y or N)?
If you have a 40-column printer, type N and press RETURN. If you have an 80-column printer, type Y and press RETURN. If you don't have a printer, it doesn't matter which way you respond.
c. The computer asks:
Do you want the program to check for an ATARI 850 Interface included with EXTENDED ATARI BASIC (Type Y or N) ?
Type Y and press RETURN.
d. The screen clears and displays:
EXTENDED ATARI BASIC VERSION 1.1 Copyright 1982 Thomas Newton Program loads at: 7420 Program ends at : 11491 Columns per line: 4 (10 for 80-column printers) Place a system diskette (one that has a copy of DOS) in drive one and press RETURN to write the AUTORUN.SYS file. Press any other key to quit without writing the AUTORUN.SYS file.
e. Press RETURN. The computer saves a copy of BASIC/XA on the diskette. Then it types:
Your disk now contains a copy of EXTENDED ATARI BASIC. To use the program, place the disk in drive one when you turn your system on.
Your diskette is the same as the diskette version of BASIC/XA. Follow the instructions for the diskette version of the program.
6 ADVANCED TECHNICAL INFORMATION
6.1 COMBINING BASIC/XA WITH OTHER AUTORUN.SYS PROGRAMS
Since BASIC/XA is relocatable, you can combine it with many other AUTORUN.SYS programs. However, there are some restrictions:
- The other program must not be copy-protected. You will need to
make a copy of the other diskette when you combine the
programs.
- The other program must fit entirely on page six or entirely
above DOS.
- If the other program contains the code to check for the ATARI 850 Interface Module, you should remove it. The PREPARE.BAS program described below can do this job for you.
To combine the programs:
- Make a copy of the other program diskette and remove the ATARI
850 Interface Module code using the PREPARE.BAS program. Turn your
computer off. If you have an Atari 400 or 800, insert the ATARI
BASIC Language Cartridge into the cartridge slot of your computer.
Place the diskette (for the other program) into drive one and turn
the computer on. Type PRINT PEEK(743)+256*PEEK(744) and write down
the number that appears on the screen.
- Turn the computer off. Place a diskette without an AUTORUN.SYS
file in drive one and turn the computer back on. This frees memory
for CUSTOM.BAS.
- Place the diskette you used in step 1 into drive one. Type XIO
32, #1, 0, 0, "D:AUTORUN.SYS,PROG2" to rename the other
program.
- Place the BASIC/XA diskette in drive one and type RUN
"D:CUSTOM.BAS". The program loads and displays:
EXTENDED ATARI BASIC VERSION 1.1 Copyright 1982 Thomas Newton This program lets you relocate EXTENDED ATARI BASIC for your system. Please hold on while I get ready... Do you want to relocate the program (type Y or N)?
- Type Y and press RETURN. The computer asks:
Where should the program start (give address in decimal)?
Type the number you wrote down in step 1 and press RETURN. The computer types:
Hold on while I relocate the program
- After the computer finishes, it asks:
Do you have an 80-column printer (type Y or N)?
Answer Y or N and press RETURN.
- The computer asks:
Do you want the program to check for an ATARI 850 Interface included with EXTENDED ATARI BASIC (Type Y or N) ?
Type Y and press RETURN.
- The screen clears and displays:
EXTENDED ATARI BASIC VERSION 1.1 Copyright 1982 Thomas Newton Program loads at: xxxxx Program ends at : yyyyy Columns per line: 10 (4 for a 40-column printer) Place a system diskette (one that has a copy of DOS) in drive one and press RETURN to write the AUTORUN.SYS file. Press any other key to quit without writing the AUTORUN.SYS file.
- Place the diskette you used in step 3 in drive one and press
RETURN. The computer saves a copy of BASIC/XA on the diskette.
- The computer types:
Your disk now contains a copy of EXTENDED ATARI BASIC. To use the program, place the disks in drive one when you turn your system on.
- Type DOS to go to the DOS menu. When the SELECT ITEM OR RETURN
FOR MENU prompt appears:
a. If the other program fits entirely on page six:
SELECT ITEM OR RETURN FOR MENU C COPY--FROM, TO? PROG2,AUTORUN.SYS/A SELECT ITEM OR RETURN FROM MENU D DELETE FILESPEC PROG2 TYPE "Y" TO DELETE... D:PROG2 Y
b. If the other program loads above DOS:
SELECT ITEM OR RETURN FOR MENU C COPY--FROM, TO? AUTORUN.SYS,PROG2/A SELECT ITEM OR RETURN FOR MENU D DELETE FILESPEC AUTORUN.SYS TYPE "Y" TO DELETE... D:AUTORUN.SYS Y SELECT ITEM OR RETURN FOR MENU E RENAME, GIVE OLD NAME, NEW PROG2,AUTORUN.SYS
6.2 THE PREPARE.BAS PROGRAM
This program will remove the code that checks for the ATARI 850 Interface Module from any AUTORUN.SYS file. If you have the diskette version of BASIC/XA, this program is saved on the program diskette as PREPARE.BAS.
100 REM **************************** 110 REM ** EXTENDED ATARI BASIC ** 120 REM ** Version 1.1 ** 130 REM ** ** 140 REM ** Program: PREPARE.BAS ** 150 REM ** Thomas Newton, 7/1982 ** 160 REM **************************** 170 REM 180 REM 190 DIM A$(1) 200 GRAPHICS 0:PRINT "EXTENDED ATARI BASIC VERSION 1.1" 210 PRINT "Copyright 1982 Thomas Newton" 220 PRINT:PRINT "This program removes the code that" 230 PRINT "checks for the ATARI 850 from any" 240 PRINT "AUTORUN.SYS file." 250 PRINT:PRINT "Insert your diskette in drive one" 260 PRINT "and press any key to remove the ATARI" 270 PRINT "850 code." 280 POKE 764,255 290 IF PEEK(764)=255 THEN 290 300 POKE 764,255 310 PRINT:PRINT "Working...":PRINT 320 REM 330 REM Rename AUTORUN.SYS file 340 XIO 36,#1,0,0,"D:AUTORUN.SYS":REM unlock file if locked 350 XIO 32,#1,0,0,"D:AUTORUN.SYS,AUTORUN.TMP" 360 REM 370 REM Copy program to AUTORUN.SYS, 380 REM except for ATARI 850 program 390 OPEN #1,4,0,"D:AUTORUN.TMP" 400 OPEN #2,8,0,"D:AUTORUN.SYS" 410 TRAP 640:REM End-of-file trap 420 GET #1,X:PUT #2,X:GET #1,X:PUT #2,X:REM Copy header bytes to file 430 REM 440 REM Block copy loop 450 GET #1,X:GET #1,Y:START=256*Y+X 460 IF START=65535 THEN 450 470 GET #1,A:GET #1,B:ADEND=256*B+A 480 REM 490 REM Check for ATARI 850 INIT addr 500 IF START<>738 OR ADEND<>739 THEN 540 510 GET #1,C:GET #1,D:IF (256*D+C)=14336 THEN 440:REM Skip 850 INIT address 520 PUT #2,X:PUT #2,Y:PUT #2,A:PUT #2,B:PUT #2,C:PUT #2,D:GOTO 440:REM Regul ar INIT--copy all bytes to output 530 REM 540 REM Check START and ADEND 550 FLAG=1:IF START=14336 AND ADEND=14411 THEN FLAG=0 560 IF FLAG THEN PUT #2,X:PUT #2,Y:PUT #2,A:PUT #2,B:REM write block addr 570 REM 580 REM Loop for all bytes 590 FOR ADDR=START TO ADEND 600 GET #1,BYTE:IF FLAG THEN PUT #2,BYTE 610 NEXT ADDR 620 GOTO 440 630 REM 640 REM Error trap--EOF 650 X=PEEK(195):REM get error number 660 CLOSE #1:CLOSE #2:XIO 33,#1,0,0,"D:AUTORUN.TMP":REM Close files and dele te old program 670 IF X<>136 THEN PRINT "Disk ERROR ";X;" in line "; PEEK(186)+256*PE EK(187) 680 IF X=136 THEN PRINT "Through."
6.3 THE ATARI 850 INTERFACE HANDLER
After the computer loads DOS and/or an autoloading program, it checks for the presence of an ATARI 850 Interface Module. If it finds one, it loads the device driver over the serial bus. The device driver uses parts of page six while loading and relocates itself at LOMEM. It uses about 2K of memory.
On a cassette-based ATARI Computer, the Operating System checks for the 850 when you turn the computer on. An autoboot cassette file will load before the interface handler.
The sequence changes for a disk-based ATARI Computer. The computer loads DOS, but due to a bug in the Operating System does not check for the interface. To fix this bug, the AUTORUN.SYS file on the Master Diskette contains a program to check for the interface module. Here is a disassembly (labels come from the Operating System User's Manual:)
3800 LDA #$50 ; Device and unit numbers 3802 STA DDEVIC ; for R1: 3805 LDA #$01 3806 STA DUNIT 380a LDA #$3F ; Unknown command (probably an 380c STA DCOMND ; INIT or UPLOAD command) 380F LDA #$40 ; Will read a data frame from 3811 STA DSTATS ; the device 3814 LDA #$05 3816 STA DTIMLO ; Timeout = 5/60th of a second 3819 STA DBUFHI ; Load address = $0500 381c LDA #$00 381e STA DBUFLO 3821 STA DBYTHI 3824 STA DAUX1 ; Auxillary bytes set to zero 3827 STA DAUX2 382a LDA #$0c ; Transfer 12 bytes 382c STA DBYTLO 382f JSR SIOV ; Call Serial Bus Handler 3832 BPL GO ; Return if error (which 3834 RTS ; means no response) 3835 GO LDX #$0B ; Else copy these bytes 3837 LOOP LDA $0500,X ; as the new serial 383a STA $0300,X ; bus commands 383d DEX 383e BPL LOOP 3840 JSR SIOV ; Load driver 3843 BMI RET ; Return on error 3845 JSR $0506 ; Init RS-232 code 3848 JMP (DOSINI) ; Restart DOS 384b RET RTS
The program loads near the top of memory in a 16K ATARI Computer (DOS requires at least 16K of memory). It is relocatable - if you move the program up in memory, you don't need to change any instructions.
When the ATARI 850 Interface Module is present, the device handler takes about 2K of memory.
6.4 SUBROUTINES IN BASIC/XA
Below is a description of each subroutine in BASIC/XA, its interface with the rest of the program, and its purpose.
Name: TITLE
Entry conditions: Program just loaded
Exit conditions: Part of page six used, then set to zero.
Cassette: locations $0689 to $06FF
Diskette: locations $0600 to $0669
After BASIC/XA loads into memory, it does not use any part of page six. By using page six during loading, I added the title message with no loss of user memory.
Because of the nature of the autoload process, it is impossible to tell that page six was altered, since the program sets it back to zero.
Purpose: TITLE prints the title message and copyright:
*** EXTENDED ATARI BASIC *** Version 1.1 *** Copyright 1982 Thomas Newton
Name: INIT
Entry conditions: Program just loaded or SYSTEM RESET pressed
Exit conditions: MEMLO = address of first byte after program
DOSINI = address of INIT's SYSTEM RESET routine
DOSVEC = address of NEWDOS (when user types DOS, BASIC jumps through DOSVEC to BASIC/XA)
For program just loaded:
OLDINI = old contents of DOSINI
OLDVEC = old contents of DOSVEC
SYSTEM RESET while in BASIC/XA:
all registers restored
Screen Editor address/buffer length restored
contents of PTR and PTR2 restored
Purpose: INIT links the program with the Operating System and DOS.
Name: NEWDOS
Entry conditions: User typed DOS while in BASIC
Exit conditions: Jumps to MENU code after
* saving registers, Screen Editor address/buffer length, and the contents of PTR and PTR2
* setting the INUSE flag to $FF (program in use)
* setting NUMIOCB to $FF (print numbers to file)
* setting the output file as the screen and the cross reference command for 40 columns
* setting the screen margins to (2,39) and clearing the screen with a GRAPHICS 0
While you are in the BASIC/XA menu, the program uses zero-page locations $CB through $CE as pointers. When you return to BASIC or go to the DOS menu, their contents are restored.
Name: MENU
Entry conditions: NEWDOS has just finished
Exit conditions: BASIC and DOS actually exit from the menu by popping the return address from the stack and calling the RESTORE subroutine to restore registers and pointers.
Calls: PRINT, INPUT, LISTV, VALUE, CHANGE, XREF, DELLIN, RENUM, CHECK, OUTPUT, BASIC, and DOS
Except for PRINT and INPUT, MENU calls these routines by copying their addresses from a table and modifying a JSR at the end of the MENU loop.
Purpose: MENU displays the BASIC/XA menu, gets the user's choice, and calls the appropriate subroutine.
Name: PRINT
Entry conditions: Accumulator holds message #
All registers must be preserved
IOCB is $00 (screen) or $50 (file); all printing directed to the "file" goes to channel $IOCB.
Tables PRADDR and PRLEN hold the addresses and lengths of all messages.
Table PRIOCB holds one byte for each message:
$00 means always to send the message to the screen.
$FF means to send the message to file $IOCB.
Exit conditions: All registers are preserved.
Input/output errors are handled internally. When an error (including BREAK) occurs, PRINT closes file #5, resets IOCB and XMAX for the screen, prints "I/O ERROR", and reprints the message.
Purpose: PRINT prints every message used by BASIC/XA (except for the title message when you load the program)
Name: OUTCHR
Entry conditions: Accumulator holds character
Exit conditions: All registers are preserved.
Purpose: OUTCHR prints a single character to file $IOCB. It uses PRINT to do the actual work.
Name: LISTV
Called by: MENU
Entry conditions: none
Exit conditions: none
Purpose: LISTV is selection A on the BASIC/XA menu. It sets DUMPPTR to point to a RTS (do-nothing subroutine), then calls DUMP to list the variable names.
Name: DUMP
Called by: LIST, VALUE, and XREF
Entry conditions: DUMPPTR must be set to the address of a subroutine
Action: For each variable name, DUMP
prints the variable name
calls subroutine (DUMPPTR) with
PTR pointing to start of variable name
VNUM = variable number (0 to 127)
register Y holding length of name
all registers can be altered
prints a carriage return
After printing the names, DUMP prints the number of variable names in the table.
Exit conditions: All registers destroyed
PTR altered
Name: VALUE
Called by: MENU
Entry conditions: none
Action: Prints heading
Changes DUMPPTR to point to VALSUB
Calls DUMP to print the variable value table
Exit conditions: none
Purpose: VALUE is selection B on the BASIC/XA menu. It prints the variable value table.
Name: VALSUB
Called by: DUMP (through DUMPPTR)
Entry conditions: PTR is off-limits
VNUM holds number (0-127)
Action: VALSUB checks the variable value table entry for variable VNUM, then prints its value or dimension(s).
Exit conditions: All registers destroyed
PTR2 altered
Purpose: VALSUB prints the variable values after the variable names.
Name: PINT
Entry conditions: FRO and FRO+1 hold a 16-bit integer in low,high form
Exit conditions: All registers destroyed
MNUM holds length of ASCII representation
Purpose: PINT prints the integer in FRO to the output file (NUMIOCB = $FF, which is most of the time), or the screen (NUMIOCB $00).
Name: PFLT
Entry conditions: FRO holds a floating-point number
Exit conditions: All registers destroyed
MNUM holds length of ASCII representation
Purpose: PINT prints the number in FRO to the output file (NUMIOCB = $FF, which is most of the time), or the screen (NUMIOCB = $00).
Name: CHANGE
Called by: MENU
Entry conditions: none
Exit conditions: none
Calls: 1) GETVAR
Entry: none
Return: BUF holds variable name with bit 7 of last character set.
Y register holds length of variable name.
A register holds last character (with bit 7 set).
Carry set if error, clear if no error. GETVAR prints its own error messages.
Purpose: GETVAR gets a variable name for CHANGE and puts it in the format used by the variable name table.
2) FINDVAR
Entry: BUF holds variable name to be found
Y register holds length of variable name
Return: Carry set if name not found.
If name found (carry clear), PTR points to the start of the name in BASIC's variable name table.
3) DELETE2
Entry: PTR points to start of name to delete
LEND holds length of variable name
Return: Variable name deleted and BASIC's pointers adjusted. PTR2 is altered.
4) INSERT
Entry: PTR = where to insert new variable name
BUF holds variable name with bit 7 of last character set.
LENI is the length of the new variable name.
Return: Variable name inserted into BASIC's variable name table. PTR2 is altered.
Purpose: CHANGE is selection C on the BASIC/XA menu. It lets the user change variable names.
Name: GETVAR
Called by: CHANGE
Entry/exit: Described above
Purpose: GETVAR gets a variable name from the user and puts it in the correct format for BASIC's variable name table.
Name: FINDVAR
Called by: CHANGE
Entry/exit: Described under CHANGE
Purpose: FINDVAR finds the name in BUF in BASIC's variable name table. CHANGE uses FINDVAR twice - to find the old name in the table, and to make sure the new name is unused.
Name: DELETE2
Called by: CHANGE
Entry/exit: Described under CHANGE
Purpose: DELETE2 deletes a variable name from BASIC's variable name table. CHANGE uses DELETE2 to remove the old variable name before inserting the new one.
Name: INSERT
Called by: CHANGE
Entry/exit: Described under CHANGE
Purpose: INSERT puts the new variable name in BASIC's variable name table.
Name: DELETE
Called by: DELETE2, DELLIN
Entry conditions: PTR points to start of delete area
LEND holds number of bytes to delete
Exit conditions: PTR unchanged; PTR2 altered
All registers destroyed
BASIC pointers common to both variable names and program lines adjusted for deletion
Purpose: DELETE removes program line and variable names from the program.
Name: LINES
Called by: DUMP, RENUM, CHECK
Entry conditions: LINEPTR = address of subroutine to call for each stmt.
Exit conditions: PTR2 is altered by LINES
PTR may be altered by subroutine (LINPTR)
All registers destroyed
Calls: XREFSUB, RENSUB, and CHSUB (through LINPTR)
Conditions: LINENO = current line number (low byte, high byte)
LINELEN = length of current line (one byte)
INDEX = offset to statement length byte from start of current line
CMDBYT and register Y = offset to statement command byte from start of current line
LIMIT = offset to next statement length byte (LIMIT = LINRLRN if current statement is the last statement in the line)
PTR2 points to the start of the current line.
None of these variables may be altered.
The subroutine does not need to preserve any registers.
Purpose: LINES loops through all the statements in the program. By breaking a line into statements, LINES simplifies the jobs of XREFSUB, RENSUB, and CHSUB.
Name: XREF
Called by: MENU
Entry conditions: none
Exit conditions: none
Action: XREF prints the heading "VARIABLE CROSS REFERENCE TABLE". It changes DUMPPTR to LINES and LINPTR to XREFSUB.
XREF then calls DUMP:
For each variable name, DUMP prints the name and calls LINES:
XREFSUB checks to see if variable VNUM is used in the current statement and prints the line number if so.
After printing the names, DUMP prints the number of variable names in the table.
Purpose: XREF is selection D on the BASIC/XA menu. It prints a cross-reference listing of variable names and line numbers.
Name: XREFSUB
Called by: LINES (through LINPTR)
Entry conditions: see calling conditions for DUMP and LINES, also
OLDVAR = last variable for which XREFSUB printed a cross reference. OLDVAR is normally 0 to 127, but XREF sets it to 255 so that the first cross-reference starts a new line.
OLDLIN = last line number printed
XCNT = number of references printed on current line
XMAX = maximum number of cross-references per line. When XCNT XMAX, XREFSUB starts a new line before printing a cross-reference.
Calls: TOKEN, PRINT, PINT
Exit conditions: All registers destroyed
OLDVAR, OLDLIN, and XCNT updated when XREFSUB prints a line number
Action: XREFSUB checks the current statement for variable #VNUM.
If the variable is in the statement:
If VNUM is not equal to OLDVAR or LINENO is not equal to OLDLIN:
Start new printing line if VNUM and OLDVAR are different.
Start new printing line if XCNT = XMAX.
Print LINENO plus enough spaces to pad the field to seven characters.
Let XCNT = XCNT + 1
Let OLDVAR = VNUM and OLDLIN = LINENO
Purpose: XREFSUB prints the line numbers in the cross-reference table. The width of the table is set by XMAX; XREFSUB will print up to XMAX references per line, for a width of 7*XMAX+6 characters (XMAX=4 for the screen, and XMAX=4 or 10 for printouts).
Name: TOKEN
Called by: XREFSUB, RENSUB
Entry conditions: see calling conditions for LINES, also
Y register holds offset to current token from the start of the line
Exit conditions: OLDY = contents of Y register on entry
Y register points to next token (if any) or the same one (if none)
A register holds symbol (if any left) - for a numeric constant or string constant, the A register holds the first byte.
Carry set if there were no tokens left in the statement on entry
All registers destroyed
Purpose: TOKEN gets the next token in the current statement. Since XREFSUB and RENSUB need to get the next token in the current statement, I put the code in a subroutine. This also made it easier to handle statements such as IF A=B THEN PRINT A, where BASIC treats the line as two statements - IF A=B THEN and PRINT A - but does not put an end-of-statement byte between them.
Name: DELLIN
Called by: MENU
Entry conditions: none
Exit conditions: none
Calls: GETTWO, DELETE, PRINT
Purpose: DELLIN is selection E on the BASIC/XA menu. It deletes a range of lines from the program.
Name: GETTWO
Called by: DELLIN, RENUM
Entry conditions: none
Exit conditions: Carry set if error (error message handled internally)
If no error, carry clear and NUM1/NUM2 hold numbers in the range of 0 to 32767
All registers destroyed
Purpose: GETTWO gets two numbers from the user and checks to make sure that they are in the range of 0 to 32767.
Name: RENUM
Called by: MENU
Entry conditions: none
Exit conditions: none
Calls: PRINT, LINES, GETTWO
Purpose: RENUM is selection F on the BASIC/XA menu. It renumbers a BASIC program the following way:
Calls PRINT and GETTWO for starting line number and increment. If the user just presses RETURN, RENUM uses 10 for both numbers.
Checks to see if renumbering is possible by setting a temporary variable to NUM1 and adding NUM2 for each line of the program. If the sum exceeds 32767, RENUM prints the CAN'T RENUMBER message.
*** IF RENUMBERING IS POSSIBLE ***
Changes LINPTR to RENSUB and calls LINES. LINES calls RENSUB for each statement, and RENSUB changes the line reference in that statement. To save memory, RENSUB uses the line numbers at the beginning of each line (which have not been changed yet) to calculate the line numbers.
Changes the line numbers at the start of each line.
Name: RENSUB
Called by: LINES (through LINPTR)
Entry conditions: see calling conditions for LINES
Exit conditions: All registers destroyed; PTR altered
Calls: GETNEW, PRINT, PINT
Action: If RFLAG is zero, RENSUB updates GOTO, GOSUB, etc. references in the current statement and checks them for errors. If RFLAG is 255, RENSUB just checks the statement, but does not update it.
The combination of LINES and RENSUB checks every statement in the program.
Purpose: RENSUB updates GOTO, GOSUB, etc. references for RENUMBER. It also checks GOTO, GOSUB, etc. references for CHECK PROGRAM.
Name: GETNEW
Called by: RENSUB
Entry conditions: PTR2 off-limits
FLIN holds line number to find
Exit conditions: PTR altered
If line FLIN exists, FRO = new line number after renumbering
Carry set if line FLIN does not exist
Name: CHECK
Called by: MENU
Entry conditions: none
Exit conditions: none
Calls: LINES
Action: CHECK sets LINPTR to RENSUB, sets RFLAG to 255, and calls LINES to check all GOTO, GOSUB, etc. references.
Then CHECK sets LINPTR to CHSUB and calls LINES to check for syntax errors and INPUT statements without variable names.
Purpose: CHECK is selection G on the BASIC/XA menu. It checks the program for common errors.
Name: CHSUB
Called by: LINES (through LINPTR)
Entry conditions: see calling conditions for LINES
Exit conditions: All registers destroyed
Purpose: CHSUB checks the current statement for syntax errors.
Name: OUTPUT
Called by: MENU
Entry conditions: none
Exit conditions: none
Calls: INPUT, Operating System
Action: OUTPUT closes file #5 and sends output to the screen.
Then it prompts the user for a filename. OUTPUT attempts to open the file. If successful, it sets IOCB to $50 (file number * 16, as required by the Operating System).
There are two bugs in the cassette handler: (1) sometimes incorrect tones are written on the tape leader, and (2) the motor does not stop after an OPEN for writing. OUTPUT contains code to defeat these bugs (however, you will still encounter them in your programming).
Purpose: OUTPUT is selection H on the BASIC/XA menu. It sends output from LIST VARIABLES, VARIABLE VALUES, and CROSS REFERENCE to the screen, printer, or tape/diskette file.
Name: BASIC
Called by: MENU
Action: The subroutine pulls the return address off the stack, calls RESTORE, and does a RTS to return to BASIC.
Purpose: Returns to BASIC from the menu.
Name: DOS
Called by: MENU
Action: The subroutine pulls the return address off the stack, calls RESTORE, and does a JMP (OLDDOS) to go to the DOS menu.
Purpose: Goes to the DOS menu from the BASIC/XA menu.
Name: RESTORE
Called by: BASIC, DOS, INIT
Entry conditions: none
Exit conditions: File #5 closed
Screen Editor buffer and length restored
Contents of PTR and PTR2 restored
All registers restored to original values
Purpose: RESTORE restores the state of the ATARI Computer before returning to DOS, the Operating System, or BASIC.
Name: INPUT
Called by: many subroutines
Entry conditions: A register = maximum number of characters (incl. RETURN)
Exit conditions: BMI on error; Y register holds status/error code
Purpose: INPUT gets a line of input from the user and masks lower case and inverse video.
6.5 SOURCE CODE (ADVANCED PROGRAMMERS ONLY)
If you have the diskette version of BASIC/XA, the source code is in UTILITY.SRC and UTILITY2.SRC. If you want to modify the program, you'll need the Assembler/Editor cartridge and at least 40K of RAM. A second disk drive and a printer are useful, but not necessary. Because the source code is so large, you should not have any AUTORUN.SYS programs in memory, including the Atari 850 driver.
When you go to assemble the program, you should send the object code to disk to avoid crashing the Atari. If you want to make a listing on a printer attached to an 850 interface, you may need to assemble from disk. In either case, the Assembler/Editor will take a LONG time to assemble the programs - when you are assembling from memory, it takes two minutes before it starts listing the program, and attract mode shifts in automatically partway through the listing.
WARNING: Since I didn't have a printer when I wrote BASIC/XA, some lines may be too long for the printer. In particular, when APX tried to send the assembly listing to the printer, they got an ERROR 15 (line too long) when assembling UTILITY2.SRC. You may need to shorten some of my comments and/or replace control characters with their ASCII numbers.
Subroutines in BASIC/XA describes the program in detail. Notice that the TITLE routine does not appear in either file - I added it on later. It just prints three lines to the screen. If you have enough knowledge to modify BASIC/XA, you should be able to add a title routine easily. I used page six to hold the routine temporarily, then used a block of zeroes in the AUTORUN.SYS file to erase it after use.
If you reassemble the program, you must preserve the links between the two halves of the program. The end of UTILITY.SRC and the beginning of UTILITY2.SRC contain equates linking the two files. First, you should write down the links used by each half on a piece of paper. Assemble UTILITY.SRC first, noting the addresses required by UTILITY2.SRC. This first assembly is just to gather information. Change UTILITY2.SRC to reflect the new values and then assemble it, noting the addresses required by UTILITY.SRC. Finally, change UTILITY.SRC to reflect the new values and assemble it. It's a tedious and lengthy process, but it's the only choice with the Assembler/Editor.
Producing the AUTORUN.SYS file from the object files is somewhat easier. Remove all cartridges and turn the computer on using a disk with a MEM.SAV file and no AUTORUN.SYS file. Use the L option of the DOS Menu to load both object files into memory (made possible by MEM.SAV). Then use the K option with filename AUTORUN.SYS and the appropriate start, end, and INIT addresses.
