BBK Command Processer

BBK CP Screen

by: Bryan Schappel

Publication date: May and June 1989

Download the executable (1,757 bytes). Source code will be posted in the future.

Do you use DOS 2.0 or 2.5? If so, this article is for you. If you tire of waiting for DUP.SYS to load, and hate MEM.SAV, you will enjoy this memory-resident DUP.SYS file, The BBK Command Processor.

The idea of a command processor is not new; they have been around for quite some time. Have you ever used UNIX, OSS/A+ or SpartaDOS? All these operating systems use a system of input called Command Processing. Put simply, you type in commands, followed by a string of arguments which are then interpreted by the computer. This is what the BBK Command Processor does and what is better is that it gives you most of the functions of DUP.SYS (and some DUP never thought of) in less than 2,000 bytes!

About the BBKCP
BBKCP has ten internal commands and can have an extensive library of external commands. The built-in commands are given, with syntax, below:

COMMAND DESCRIPTION
ERASE fname
PROTECT fname
UNPROTECT fname
RENAME old new
DIR [Dx:]
COPY fn1 fn2
RUN [hex addr]
CAR
TYPE fname
KILL
delete file
lock file
unlock file
rename file
disk directory
copy file
run at address
run cartridge
type file
unload BBKCP

In the table above, fname stands for any legal DOS filename in the format of [Dx:]filename.ext, where x is any legal drive number. Anything in brackets is considered optional.

For optional arguments, certain default conditions will be used. For example, just giving a filename following a command will tell BBKCP that this command is issued to the default device. (The default device is used as the prompt.) So if you typed PROTECT MYFILE.BAS, BBKCP would expand this to PROTECT D1:MYFILE.BAS - assuming D1: is the default device.

To change the default device, just enter it on the command line. For example, if the prompt is D1:, and you type D2:, you are now prompted with D2:.

Any legal Atari device may be used for the default device, such as P:, E:, S: and C:. You should remember, though, that most of the commands are used for disk operation and will give errors with another device.

BBKCP uses the Space (ATASCII 32) as a delimiter to separate commands and arguments on the command line. You may put as many spaces between arguments as you like, however there may be no spaces before a command.

To enter the BBKCP from BASIC or MAC/65 (or any other language cartridge), simply use the DOS command. Any program currently in memory will remain safe unless you use the COPY command or use an external command. (We'll discuss external commands in a little while.)

About the Commands
You are only required to enter the first three letters of any internal command, but in all examples the entire command name will be used.

ERASE. This command accepts a filename as the argument (wildcards are allowed) and will delete the matching file(s) from your disk. You are not asked for verification, so be careful with this command.

PROTECT. Again only specify the file to be used, and voila, it's locked. Use UNPROTECT to reverse the locking process. Wildcards are allowed.

RENAME. This requires two arguments, namely the current name of the file and its new name. Separate the names by at least one space to ensure the rename will function correctly. Wildcards are allowed, but be careful not to rename two files with the same name.

Do not supply a device prefix for the new filename with a rename command, as it will cause unpredictable results. It will not destroy your disk, but it will cause some headaches. It is, however, perfectly legal to put a device prefix on the old filename.

DIR. This command takes an optional argument, the directory specifier. The default specifier is [*].[*], but you may use D2:[*].BAS or anything else you may think of. To get the directory from anything but the default device, just type the device name after the DIR command.

COPY. This command will copy one file to another disk drive or file. Wildcards will produce strange results — Don't use them. COPY will make as many passes as needed to duplicate the file. COPY is mainly for a two-drive system; if used with a one-drive system, it can only duplicate the file to the same disk under a separate name. (Note: If you are using one drive with COPY, make certain that you use unique filenames for the source and destination files. Otherwise you could loose the source file forever!)

Another great use for COPY is to copy a text file to the screen or printer. To do this your commands would look like this:

      COPY MYFILE.TXT E: (screen)
      COPY MYFILE.TXT P: (printer)

Using the COPY command will destroy any program in memory, so save your work before performing a COPY.

RUN. This command takes an optional hexadecimal address as its parameter and is used to execute a machine-language program in memory. If an address is supplied, RUN will execute at the supplied address. If no address is given, the last run address will be used. At the end of your machine-language routine, execute an RTS instruction to return to BBKCP.

RUN (with no argument) may also be used to re-run the last external command, assuming it still resides in memory.

The RUN command checks to see if the address given as an argument contains only legal hexadecimal digits and that the number contains no more than four digits. If these conditions are not met, an ERROR 180 is given, and control passes back to BBKCP.

CAR. This command will attempt to pass control to the left cartridge, if it is present. (In the case of an XL or XE, the "left" cartridge is either the built-in BASIC or whatever cartridge is plugged into the computer.) If no cartridge exists, the message "No Cart" will appear, and you are returned to BBKCP; otherwise, the cartridge will be entered.

TYPE. This command will print the contents of a text file (the name of which you supply) to the screen, assuming each line of the text has a maximum of 64 characters per line. Mainly this is used to show the contents of a BATCH file. (More on BATCH files later.)

KILL. Use of this command will (1) remove BBKCP from memory, (2) wipe out any program in memory and (3) pass control to either a cartridge (if present) or go to DOS.

External Commands
If you enter something that BBKCP does not understand, it assumes that it is an external command, and BBKCP attempts to binary load the file. If what you typed has no filename extension, BBKCP adds on a COM extension. Executing an external command is destructive to memory, in most cases.

External commands must be binary, load-and-go machine-language files. If the file doesn't begin with a $FF $FF header, an ERROR 181 is given and control passes back to BBKCP.

Batch Files
Batch files are a wonderful way of automating certain processes. A batch file is simply a text file full of commands that either BBKCP understands or commands that the left cartridge understands. You may use a batch file to perform simple operations like copying a few files or running other external commands.
Use any text editor to make a bath file or simply use the COPY command like this:

      COPY E1: D1:MYBATCH.BAT

When using this command, type your text one line at a time (maximum length is 64 characters), and press Return after each line. When you are finished press Control-3 to terminate the COPY.

To execute a batch file, type a "*" before the filename at the prompt. You are also allowed to chain batch files if the last line in the batch file looks like "*batfile".

If no file extension is supplied on the filename a BAT extension is used. Here is a sample batch file:

      ;BATCH FILE TO GIVE DIRECTORY AND
      ;RUN THE CART.
      ;ANY LINE STARTING WITH A ';'
      ;IS IGNORED BY BBKCP!
      DIR
      CAR

Upon powerup, after it has loaded, BBKCP will attempt to run the batch file called AUTORUN.BAT from Drive 1. If the file does not exist you are left in BBKCP, or control is passed to a cartridge (if present).
The AUTORUN.BAT file is extremely powerful. You could use it to copy files to a RAMdisk or go to the cartridge and run a program or simply print a "hello" message whenever you boot up your system. You can think of this file as giving you an infinite number of AUTORUN.SYS files.

External Commands
Now we'll discuss external commands, how external commands interface with BBKCP, and how to write your own external commands. There are also four external commands supplied. Let's get to it.

More on External Commands
We said an external command is something that the internal or memory resident portion of BBKCP does not understand. Such a command is loaded from disk each time it is called. Almost all external commands are destructive to memory, meaning that when an external command is executed any program in memory will be lost!

External commands interface directly by calling routines built into BBKCP. By doing this, filenames, addresses and numbers may be sent to an external command. Table 1 gives the name, address and description of special routines in BBKCP. These routines are called by a 6502 JSR instruction. Any parameters or initial conditions for the routines will be given.

By using the routines in the table, we may write any number of external commands, performing almost any operation. Here are some samples.

Name Addr Description
ADDRESS 23B7 Contains the last run address of an external command. Contains address for the RUN command.
CLOSE1 1EE4 Closes IOCB #1. Returns with X=$10.
CLOSE2 1EE8 Closes IOCB #2. Returns with X=$20.
CLOSEIT 1EEA Closes any IOCB, enter with X=IOCB offset. ($00, $10, $20, ...)
DEFDEV 2354 This is the default device and device number in the format D1.
DEVICE 23B9 Contains a correct DOS filename in the format of D1:filename.ext
EPRINT 1E64 Will print a NULL terminated string to the screen. Enter with A, Y containing the LO, HI of your text. (NULL = 0)
FINDARG 21F4 Will find the start of the next argument on the command line. Enter with Y=search offset. (i.e. Y=3 starts searching on character 4.) Exits with Y and LNPOS = start of the argument.
FINDFILE 1FDB Enter with Y=start of name and DEVICE will return the filename in the D1:filename.ext format.
FNAME 23BC Start of formatted filename. Same as DEVICE+3.
FR0 00D4 Contains the result of a GRAB_HEX. $D4 is the LO byte and $D5 is the HI byte.
GOCART 1F11 Tries to run a cartridge. Calling this is the same as issuing a CAR command.
GRAB_HEX 1E9D Pulls a hex address from the command line. Enter with Y=offset. Exit: Carry Clear means a good number. Carry Set means a bad number.
HEXDIG 236B Contains the ATASCII hexadecimal digits. 0-9 and A-F.
INPUT 1EF7 Prints the current prompt and accepts one 64-byte line from the screen editor.
IOERROR 1FAC Closes IOCB #1 and prints the I/O error number in decimal. Enter with Y=error number.
LNPOS 00DF Contains the current offset to the argument on the command line.
MYBUF 0500 64-byte command line buffer.
WARMST 0008 Warm start flag. If the value here is $FF, memory contents are OK. If the value is $00, memory will be wiped out.

Table 1 — External command API.

COMMAND #1: DISBAT**
This command will toggle the batch-file processing feature of BBKCP on or off. After the file executes, a message will be displayed telling you about the status of batch processing.

This command is not destructive to memory. It was included because certain programs and games published in ANALOG will fail to run if batch processing is left on.

COMMAND #2: DUMP [addr]
This is a memory dump utility that loads and runs at $2480. It will begin dumping the contents of memory on the screen from the address you specify. Press Start or Break to return to BBKCP.

COMMAND #3: SAVE fname start end [init run]
This allows you to perform a binary save of memory. You must provide a legal filename, a start address, an end address and optional initialize and run addresses.

COMMAND #4: FORMAT**
This is a diskette initialization program. The menu contains five options: Format, Write DOS, Format and Write DOS, Change Drive and Exit. Just press the number next to the description to select your option. If you choose an option between 1 and 3, you are asked to insert a disk and press Return. Pressing Return begins the process; pressing any other key aborts the option, returning you to the menu.

When you choose to write DOS, FORMAT not only writes the DOS.SYS file, but it also writes the AUTORUN.SYS version of BBKCP to the disk.

Option 4 allows you to alter the drive number that the commands are being executed on. Just type the new drive number, and you are returned to the menu.

Option 5 returns you to BBKCP.

Writing External Commands
All external commands must be written in machine language, therefore you must be familiar with 6502 assembly language. Here are a couple of rules to follow.

Rule #1: Assemble all your commands with an origin not less than $2410, otherwise part of BBKCP would be overwritten, causing a system crash.

Rule #2: While a batch file is being processed never use IOCB #5. Doing so will most likely cause a system crash. This is the IOCB that the input is being redirected from - take care.

Some Tips
If you write a small external command that is less than 448 bytes long, you may load it at $0540 and set WARMST back to a $FF, thus preserving the contents of memory.

Study the source code for the external commands. They will guide you in the method of writing your own commands. Some extra commands you may consider writing would be a multi-file copy program, a disk copier or a simple assembler/disassembler. The possibilities are quite endless.


By the time you read this, Bryan and Carol will have been happily married for a while. Their new (read: same) apartment contains a new Mega ST2, which shares the computer room with the 800XL. The compu-kids get along very well — if you overlook the constant battle for the printer.

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