AA Toolkit
AA Toolkit is a programmers toolkit written by Richard Fairhurst for Amstrad Action
Manual
--------------------------
The Amstrad Action Toolkit
--------------------------
Welcome to AA's set of utilities for BASIC and machine code programmers.
You've probably seen "BASIC extensions" like this a thousand times before:
they add a few commands, most of which you can live perfectly well without,
and disappear again.
We hope that, with the AA Toolkit, you'll find something genuinely useful. The
commands here are often really quite sophisticated, even more so when compared
to standard toolkit fare.
Most of the commands will work equally well no matter what CPC you have. A few
are for disc owners only, and a couple are only to be used with cassettes.
(The program won't let you use the disc commands if you only have a tape
drive on your system.) Similarly, a few commands are designed for systems with
over 64k, and there are some commands especially suited for the 464. Something
for everyone, basically.
HOW THE COMMANDS ARE ADDED
The commands that this adds to BASIC are called RSXs, which is techie jargon
for "Resident System Extensions", which is techie jargon for something that
begins with a "|" (bar) symbol. For example, one of the commands is called
|MEMORY. You can just use it like any normal command: in a program line, for
example...
10 |MEMORY
...or just on its own. Some commands, like BASIC commands, take arguments -
that is, you can't just put the command down and expect it to do something,
but you have to supply a few numbers (or whatever) for it to work from. The
thing to note here about RSXs is that they must have a comma directly after
the command name (yes, it does look odd), such as...
|PUTKEY,65
A NOTE FOR 464 OWNERS (BASIC 1.0)
As you'll know if you have a disc drive, the 464 is spectacularly inept at
handling bar commands. For example, to erase a file from disc on the 464, you
have to type:
a$="filename": |ERA,@a$
instead of the simpler 664, 6128 or Plus (BASIC 1.1) equivalent:
|ERA,"filename"
Remember that this applies to the AA Toolkit commands too. (However, one of
the commands should help to free you from all this hassle. Read on...!)
------------------------
The commands, one-by-one
------------------------
COMMAND SYSTEM
|CLI (all machines)
a$="command": |CLI,@a$ (BASIC 1.0)
|CLI,"command" (BASIC 1.1)
What does CLI mean? Well, apart from what a friend of mine does when he gets
his Japanese translation all wrong, it stands for Command Line Interpreter.
This, basically, means that you can type in a command and it will obey it.
"Big deal!" shout several thousand readers over Britain. "BASIC does that
already!" Hang about, hang about. This has several advantages. For a start, if
you just type |CLI, you'll be put in a mode where you can type RSX commands
(i.e. those usually prefixed with |) to your heart's content. It's easier than
from BASIC, because you can use spaces instead of commas to separate items,
and you needn't bother with the speech marks (unless, of course, you have a
space in the item). For example, let's say that we want to rename the file
OLDIE.BAS to NEWBIE.BAS. 464 owners would usually have to suffer this:
a$="OLDIE.BAS": b$="NEWBIE.BAS": |REN,@b$,@a$
Other CPC and Plus owners could get away with this:
|REN,"NEWBIE.BAS","OLDIE.BAS"
Under |CLI, though, it's a much easier
REN NEWBIE.BAS OLDIE.BAS
To quit from command mode, press ESC.
|CLI has other advantages. If you supply it with an argument, it won't go
into the command mode, but will instead try to execute the string you supplied
as a command. For example, if a$ contained "ERA *.BAK", then typing |CLI,@a$
would delete all the backup files on a disc.
-=-
|EXEC (all machines)
a$="filename": |EXEC,@a$ (BASIC 1.0)
|EXEC,"filename" (BASIC 1.1)
|CLI acts on what you type in at the keyboard. |EXEC is similar, but takes its
orders from a text file (perhaps created with a word-processor or text editor)
on your tape or disc. This means that you can write a list of RSX commands to
execute, save them (say) in the file "COMMANDS.BAT", and then execute them
using |EXEC,"COMMANDS.BAT" .
For ultimate convenience, if you just type |EXEC on its own, it will try to
load and execute a file called #EXEC.BAT .
Possible uses? Well, you could set up a file to set up your favourite
colours and function key definitions, for example, erase all your backup
files, and then leap into Protext. Your imagination is the only limit (er, so
long as your imagination isn't greater than 800k, because otherwise the file
will overflow even a 3.5" disc).
If you want to use control codes in the file being executed - for example,
CTRL-M (which is the same as ENTER or RETURN), at the end of a key definition
- use the "^" symbol followed by the appropriate letter.
-=-
SCREEN COMMANDS
|EDIT,character value (all machines)
a$="character": |EDIT,@a$ (BASIC 1.0)
|EDIT,"character" (BASIC 1.1)
Working out character designs manually for BASIC's SYMBOL command can be a
chore at the best of times, downright annoying at the worst. But what is that
in the distance? Could it be a heroic RSX decked in shades and riding a
Harley-Davidson here to save the day? Yes, it is. But please don't laugh at
the poor thing.
Select a character to edit using one of the above commands (the first one
takes an ASCII code - 65 for capital A, for example, or 240 for an up arrow -
as an argument, whereas the other methods take the actual character), and the
character will appear. You can move your cursor using the cursor keys, invert
pixels with COPY, and finish with ENTER or RETURN. When you've finished, the
appropriate numbers will be displayed on-screen (in hex), ready to be copied
into a SYMBOL statement.
Remember that, to define a character, you must have set SYMBOL AFTER
appropriately beforehand (i.e. if you want to define character 100, you'll
need to have typed SYMBOL AFTER 100 or less). An error will appear if you
haven't. The standard loader for the Toolkit sets SYMBOL AFTER 32, so you
should be ok.
-=-
a$="text": |DOUBLE,@a$ (BASIC 1.0)
|DOUBLE,"text" (BASIC 1.1)
Prints double-height text.
One note: you must have set SYMBOL AFTER 254 or less beforehand. The default
is SYMBOL AFTER 240 when you first turn on, and the AA Toolkit sets it to
SYMBOL AFTER 32, so it shouldn't be a problem.
-=-
a$="text": |WRITE,[style,] @a$ (BASIC 1.0)
|WRITE,[style,] @a$ (BASIC 1.1)
Writes text to the screen in a specified style. The style is expressed by a
number, which can be any of these:
1 bold
2 thin
4 italics
8 underlined
16 flippy (upside-down)
...or you can add two (or more) together for a combination of styles.
You can even change style half-way through some text. Use CTRL-B to toggle
bold on or off, CTRL-T for thin, CTRL-I for italics, CTRL-U for underline, and
CTRL-F for flippy. (Who said programmers had no imagination...?) If you're
going to do this later on in the text, you can leave out the number in the
command if you want, so the text will start out plain (like writing 0).
This command relies on at least SYMBOL AFTER 255 being set (see above).
-=-
|MODE,mode number (all machines)
|INK,ink,colour (all machines)
|BORDER,colour (all machines)
Yes, these do work in the same way as the standard BASIC commands. We've just
supplied you with them as RSXs so that you can use them from an |EXEC file.
-=-
464 COMMANDS
|FRAME
|CURSOR[,system switch],user switch
|CLEAR.INPUT
|COPY.CHR,@variable%
|GRAPHICS.PEN,ink
|GRAPHICS.PAPER,ink
These pretty much emulate the commands to be found in BASIC 1.1, for the
benefit of those struggling over Type-Ins that don't work on the 464. Simply
replace CLEAR INPUT with |CLEAR.INPUT, for example, and hey presto.
|COPY.CHR works in a slightly different way to the 6128's COPYCHR$ function.
Instead of a$=COPYCHR$(#0), you would write
a%=0: |COPY.CHR,@a%: a$=CHR$(a%)
Note that the "a%=0" is important (although the variable can be called
anything, of course).
-=-
MEMORY COMMANDS
|MEMORY (all machines)
Draws a graphical representation of memory very, very quickly. Coloured bits
indicate there's something in the memory at that point, whereas blank bits
suggest that it's empty.
-=-
|DUMP,start[,finish] (all machines)
Displays a section of memory on the screen, from the start address to the
finish address. If no finish address is specified, then a short display will
be produced from the start address.
When displaying long sections of memory, the computer pauses every so often
and waits for you to press a key.
-=-
|FIND,start,finish,byte (all machines)
Looks through memory for the occurrence of a particular byte, and prints up
all the places at which it occurs.
-=-
|BANK,bank-switch (128k systems and over only)
For use with the following commands, this command selects which bank of extra
RAM is to be used. The standard 6128 extra 64k can be selected with |BANK,&C0.
If you have a 256k expansion, |BANK,&C8, |BANK,&D0, and |BANK,&D8 may prove
useful.
-=-
|BANK.READ,from,to,length (128k systems and over only)
This copies a section of memory from the currently selected bank of extra
memory to the specified address in the main 64k, where you can wreak your
wicked ways on it weasily. (Or stoatily, if you prefer.)
-=-
|BANK.WRITE,from,to,length (128k systems and over only)
Unsurprisingly, this is the opposite of the previous command, and copies
memory from the main 64k to the extra memory.
-=-
|COPY,from,to,length (all machines)
This copies the specified portion of memory (in the main 64k). For example, to
copy the contents of screen memory (which starts at &C000, and is &4000 bytes
long) to &2000, you could type
|COPY,&C000,&2000,&4000
-=-
|FILL,address,length,byte (all machines)
This fills a section of memory with the given byte, obliterating everything
else underneath. |FILL &C000,&4000,240, for example, will fill screen memory
with ink 1.
-=-
|CALL,address (all machines)
|AF,value: |BC,value: |DE,value
|HL,value: |IX,value: |IY,value
The firmware has a lot of good routines in it, but many are not easily
accessible from BASIC. These routines will help you to use them to the full.
All you have to do is set up the required registers (so, to set HL to &4350,
type |HL,&4350), and then CALL the routine using |CALL,address .
To set the accumulator to 5, you would type |AF,&0500 . This also sets the
flags register to 0, but the flags are never significant on entering a
firmware routine.
-=-
FILE COMMANDS
a$="filename":|TYPE,@a$ (BASIC 1.0)
a$="filename":|PTYPE,@a$ (BASIC 1.0)
|TYPE,"filename" (BASIC 1.1)
|PTYPE,"filename" (BASIC 1.1)
These two commands type a file from tape or disc to the screen. |PTYPE prints
it on your printer, too. You can pause output at any time by pressing any key,
with another key to resume (ESC to quit).
One useful feature of this is that it makes a half-decent job of Protext
files, meaning that you no longer need to load the word-processor itself to
read the files. (In fact, this instruction file is a Protext file.)
-=-
a$="filename":|INFO,@a$ (BASIC 1.0)
|INFO,"filename" (BASIC 1.1)
This reads header information from the specified file and displays it in hex
- filetype, start address and so on. Ideal for hackers.
-=-
a$="filename": |LOAD,@a$,addr (BASIC 1.0)
|LOAD,"filename",addr (BASIC 1.1)
Loads a file into anywhere in (the main 64k of) memory. Unlike BASIC's normal
LOAD command, this doesn't worry about HIMEM or other such nonsense.
-=-
a$="filename": |DEPROTECT,@a$ (BASIC 1.0)
|DEPROTECT,"filename" (BASIC 1.1)
Loads a protected BASIC program and removes its protection. Naughty naughty!
-=-
|HL.WRITE,address,length,sync (cassette)
|HL.READ,address,length,sync (cassette)
Records an area of memory to tape as a headerless file, which is impossible to
read if you don't know the sync byte (which should be a number between 0 and
255). Make sure you don't forget it.
I must be going mad. I wrote the first sentence of the last paragraph
originally as "Records and writes an area of Australia to Channel 4's current
schedule". Seriously. I need some sleep...
-=-
DISC COMMANDS
|SECTOR.WRITE,address,drive,track,sector
|SECTOR.READ,address,drive,track,sector
Record an area of memory (usually &200 bytes, half a kilobyte) directly to a
sector on disc. Be very careful using |SECTOR.WRITE - if used indiscriminately
on non-write-protected discs it could mess them up for good. Try experimenting
on a disc of CP/M languages or something boring like that.
The drive parameter should be 0 for drive A and 1 for drive B.
-=-
|USER,user number
Just like the usual command, except that the 0-15 limit has been removed and
you can now select any user area from 0 to 255. 229 is where erased files go
to rest before they die forever.
-=-
|CAT,drive
Catalogues the disc in the specified drive: 0 for drive A and 1 for drive B.
This enables you to quickly catalogue a drive which you're not using at the
moment, without having to go through the rigmarole of |B:CAT:|A.
-=-
MISCELLANEOUS COMMANDS
a$="string":|KEY,exp.token,@a$ (BASIC 1.0)
|KEY,expansion token,"string" (BASIC 1.1)
Sets up a function key (usually) to generate a string of characters: |KEY,0,
"|CLI"+CHR$(13), for example, will set f0 to enter CLI mode. This is no
different from the standard Amstrad KEY command, but, again, is provided for
use in |EXEC files. In an |EXEC file, you would write the above as...
KEY 0 |CLI^M
-=-
|PUTKEY,character value (all machines)
a$="character": |PUTKEY,@a$ (BASIC 1.0)
|PUTKEY,"character" (BASIC 1.1)
Pretends that a key has been pressed, so that next time you come to read the
keyboard (using INKEY$, INPUT or similar), that key will appear. You can only
"put back" one key at a time before reading a key. Useful for when certain
keys (detected with INKEY$) trigger off a line of INPUT beginning with that
letter.
---------------------------------------
Using the commands in your own programs
---------------------------------------
The file that does all the hard work is called TOOLKIT.RSX. To load it and set
up the extra commands, you would need to use a few lines like this at the
beginning of your program:
10 SYMBOL AFTER 32
20 MEMORY &7FFF
30 LOAD "TOOLKIT.RSX"
40 CALL &8000
Make sure that TOOLKIT.RSX is on the current disc or tape.
--------------
Error messages
--------------
There are a number of error messages that the commands might generate. Here's
what they mean:
Cassette overrun
- The headerless file was not of the right length.
Character not editable
- The current SYMBOL AFTER setting is inappropriate for the command you are
trying to carry out.
Could not set key
- You've tried to set too many function keys at once, and the computer has run
out of memory for them.
Disc error
- Five hundred elephants came charging through the undergrowth. (Well,
really.)
Escape pressed
- A tape operation was interrupted by you pressing ESC.
File error
- Some sort of error occurred while trying to access a file.
Illegal parameter count
- You haven't supplied the right number of parameters (or arguments) for a
command.
Read error b (CRC error)
- Bad news. Sounds like your headerless file has been messed up.
Unknown command
- |CLI or |EXEC is trying to find a command you have given it and failing
miserably, poor thing.
---------
Copyright
---------
You are welcome to use the AA Toolkit (TOOLKIT.RSX) in your own programs -
after all, that's what it's here for! An acknowledgement along the lines of
"Uses AA Toolkit from Amstrad Action and Robot PD" would be appreciated. The
Toolkit may not be copied as a toolkit, rather than as part of a program,
without the permission of the author.
--------------
The final word
--------------
And that's your lot. If you have any problems working with the Toolkit, drop
us a line at Technical Forum, Amstrad Action, 30 Monmouth Street, Bath, Avon
BA1 2BW: any suggestions for new commands for a possible future version of the
Toolkit, and improvements to existing ones, are also welcome.
Meanwhile, I'm off to sleep before going off to sunny Pembrokeshire for a
week tomorrow. Programming is never good for your sleep patterns...!
Enjoy yourself,
Richard Fairhurst
Amstrad Action
Robot PD
March 1994
Easter Eggs
In included source hints at three easter eggs.
To see these, use the |CLI command and once you are at the "|" prompt type:
*ROBOT
- This returns the messsage "It's twiffic!"
*STS
- This plays a tune
*ANNA
- This produces a line of hearts