Changes
Initial page entry for AA Toolkit
== Manual ==
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
== Links ==
* [https://www.cpc-power.com/index.php?page=detail&num=5108 ''AA Toolkit'' from CPC-Power]
* [https://archive.org/details/AA_Toolkit_1994_Amstrad_Action_Robot-PD ''AA Toolkit'' from The Internet Archive]
