a2stuff/intbasic

INTBASIC.SYSTEM for running Integer BASIC programs under ProDOS

INTBASIC.SYSTEM

This is a version of Steve Wozniak's Integer BASIC for the Apple II, with a wrapper that allows it to be loaded under ProDOS. It operates in two modes:

1. When invoked directly, the Integer BASIC > prompt is shown and you can type in and execute programs. The following additional commands are available at the prompt:

   • SAVE path saves the current program as an INT program file.
   • LOAD path loads an INT program file.
   • RUN path loads and runs an INT program file.
   • CHAIN path loads and runs an INT program file, without clearing variables.
   • PREFIX shows the current ProDOS prefix.
   • PREFIX path sets the current ProDOS prefix.
   • CAT or CATALOG shows the contents of the current directory.
   • CAT path or CATALOG path shows the contents of the specified directory.
   • DELETE path deletes the specified file.
   • RENAME path,newpath renames the specified file.
   • BSAVE path,A<address>,L<length> saves a BIN file.
   • BLOAD path[,A<address>] loads a BIN file.
   • BRUN path[,A<address>] runs a BIN file.
   • LOCK path and UNLOCK path lock/unlock the specified file.
   • STORE path and RESTORE path save/load variables to the specified IVR file.
   • -path runs INT, BIN or SYS files
   • BYE exits back to ProDOS.

2. When invoked as an "interpreter" for an INT file from a program selector (such as Bitsy Bye or Apple II DeskTop), the file is loaded and executed.

   • When the program ends normally or encounters an error, control is returned to ProDOS and the program selector.
   • Pressing Control+C will usually exit a program as well.
   • Optionally, hold down Open Apple or Solid Apple when starting to allow exiting the program to remain at the > prompt.

3. When invoked directly, if a INT file named HELLO is present, will be run automatically.

⚠️ Note that while Integer BASIC programs do have the ability to execute commands from BASIC with PRINT "<control-D>...", only the above commands are supported. Commands for operating on text files (OPEN, READ, etc) are not supported.

Integer BASIC

See Integer BASIC on Wikipedia or Apple II BASIC Programming Manual to learn more about the language.

This uses the Integer BASIC disassembly by Paul R. Santa-Maria from: https://6502disassembly.com/a2-rom/ (utilizing the SourceGen format conversion by Andy McFadden)

Modifications:

• Target address commented out (defined by includer)
• SYNTABLE-118 is corrected to SYNTABLE>>1
• Dead code is ifdef'd out

Notes:

• At runtime, the GR command is modified to ensure the hires screen is not shown.
• At runtime, CALL -10473 is intercepted to support the Programmer's Aid Music Subroutine.

Programmer's Aid

As a convenience, and since they were used by some Integer BASIC programs, the Programmer's Aid #1 Music Subroutine by Gary J. Shannon is included. This uses the annotated disassembly by James Davis from https://6502disassembly.com/a2-rom/PA1.html#A2PA1.6

Modifications:

• Target address commented out (defined by includer)
• Padding bytes commented out

intbasic's Issues

Support default STARTUP file?

BASIC.SYSTEM hard-codes STARTUP into the $2006 buffer, so if the invoker doesn't override then BS will look for a STARTUP file and run that automatically.

INTBASIC.SYSTEM currently has the $2006 buffer empty. It would be easy to put something there to allow auto-starting a file. Options include:

• Do nothing - keep it blank
• STARTUP - same as BASIC.SYSTEM; INTBASIC is smart enough to only try to run INT programs
• INTSTARTUP - be more explicit, and allow you to have both SYS files w/ default programs in the same dir
• HELLO - a more classic name, from the DOS 3.3 days?

Add control-D interception and deferred command handling

Only important if we can find programs we actually want to run. Categories that are useful:

• Using BLOAD to load resources - important for some games?
• Interacting with sequential and random-access text files (OPEN, READ, WRITE, CLOSE) - maybe??
• CHAIN - maybe???

I'll want some real examples of programs that would work if we added specific support.

The good news is that rather than CSWL interception and trying to re-establish control we can actually modify intbasic in RAM to hook the MON_COUT calls to watch for ctrl-D.

Finish support for binary files

• BRUN path[,An]
• BLOAD in DOS doesn't have Ln arg - remove?
• Check if BSAVE in DOS works w/o A,L args (in BASIC.SYSTEM those re-use the existing file)
• Ensure BSAVE over existing file works as expected

Implement STORE and RESTORE commands

BASIC.SYSTEM provides STORE path and RESTORE path to save and load the Applesoft variables into $FD VAR files.

INTBASIC.SYSTEM should provide similar commands, especially as ProDOS reserves file type $FB IVR for this.

Nothing uses this, but it should be easy!

Add LOAD / SAVE support for the command line

This can be done with hooks into the relevant functions.

The current loading code can be moved up out of the $280-$3E0 area into the $BC00-$BEFF block (after IO_BUFFER) and re-used for loading.

Add support for random-access text files

• OPEN path,Ln (L is record length)
• CLOSE [path]
• READ path[,Rn][,Bn] (R is record number, B is byte offset in record)
• WRITE path[,Rn][,Bn] (R is record number, B is byte offset in record)

Look at and learn from "I am Rob"'s version

https://groups.google.com/g/comp.sys.apple2/c/jxsST6tDVRA/m/fPcCOKHdCQAJ

Usenet poster "I am Rob" did something similar, but I think using the aux language card?

He also put together an amazing collection of IB programs.

Add support for sequential text files

• OPEN path
• READ path[,Bn] (B is byte offset)
• WRITE path[,Bn] (B is byte offset)
• APPEND path
• POSITION path[,Rn] (R is record a.k.a. CR-delimited line number to start at)
• CLOSE [path]

Make RUN <num> work

Right now it'll try to run a file, rather than RUNWARM

Add support for environment commands

• EXEC path[,Rn] (R is record a.k.a. CR-delimited line number to start at)
• MAXFILES n
• CHAIN path

Possible support for Programmer's AID music routines?

I'm not sure if this is possible given the use of memory by Prodos, but there were routines in the Programmer's AID ROM which occupied the $D000-$D7FF address space of Integer Basic, such as the music routine. A disk image with a program that uses it can be found here: https://github.com/erangell/kfest2023/blob/main/INTBSYS_TTD2023.po
LOAD TTD.DRAGON.2023
LIST 1000,1100

Add BLOAD / BSAVE

Will require parsing for A and L arguments

Add dummy MON / NOMON commands

Several integer basic programs include NOMON I,C,O to turn off monitoring, even though they don't turn it on and don't do any other DOS operations.

We can just ignore those commands.