Changes

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.

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

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$

|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 ------------------------

|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$

|REN,"NEWBIE.BAS","OLDIE.BAS"

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 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.

-=-

Select a |EDIT,character to edit using one of the above commands value (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 characterall machines), and the a$="character will appear. You can move your cursor using the cursor keys": |EDIT, invert pixels with COPY, and finish with ENTER or RETURN@a$ (BASIC 1. When you've finished0)|EDIT, the appropriate numbers will be displayed on-screen "character" (in hexBASIC 1.1), ready to be copied into a SYMBOL statement.

Remember that, to define Working out character designs manually for BASIC's SYMBOL command can be a characterchore at the best of times, you must have set SYMBOL AFTER appropriately beforehand (idownright annoying at the worst.e. if you want But what is that in the distance? Could it be a heroic RSX decked in shades and riding a Harley-Davidson here to define character 100save the day? Yes, you'll need to have typed SYMBOL AFTER 100 or less)it is. An error will appear if you havenBut please don't. The standard loader for laugh at the Toolkit sets SYMBOL AFTER 32, so you should be okpoor 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)

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)

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

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 ; (all machines)COMMANDS

|DUMPDraws a graphical representation of memory very,start[very quickly. Coloured bits indicate there's something in the memory at that point,finish] ; (all machines)whereas blank bits suggest that it's empty.

When displaying long sections of memory|DUMP, the computer pauses every so often and waits for you to press a key.start[,finish] (all machines)

|FIND When displaying long sections of memory,start,finish,byte ;(all machines)the computer pauses every so often and waits for you to press a key.

|BANKLooks through memory for the occurrence of a particular byte,bank-switch ; (128k systems and over only)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.READIf you have a 256k expansion,from|BANK,to&C8, |BANK,&D0,length (128k systems and over only)|BANK,&D8 may prove useful.

|BANK.WRITE,This copies a section of memory from,the currently selected bank of extra memory tothe specified address in the main 64k,length where you can wreak your wicked ways on it weasily. (128k systems and over onlyOr stoatily, if you prefer.)

|COPYUnsurprisingly,this is the opposite of the previous command, and copies memory from,the main 64k to,length ; (all machines)the extra memory.

|COPY,&C000from,&2000to,&4000length (all machines)

|FILLCOPY,address&C000,length&2000,byte (all machines)&4000

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)

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 printsit on your printer, too. You can pause output at any time by pressing any key,

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)

; -=-

|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 èscheduleschedule". Seriously. I need some sleep...

; -=-   DISC COMMANDS

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.

; -=-

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.

; -=-

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

Sets up a function key (usually) to generate a $="string of characters": |KEY,0exp.token, "|CLI"+CHR@a$(13BASIC 1.0), for example, will set f0 to enter CLI mode. This is no different from the standard Amstrad |KEY command, butexpansion token, again, is provided for use in |EXEC files. In an |EXEC file, you would write the above as.."string" (BASIC 1.1)

Sets up a function key (usually) to generate a string of characters: |KEY ,0 , "|CLI^M"+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...

|PUTKEY,character value ;(all machines)a$ -="character": |PUTKEY,@a$ (BASIC 1.0)|PUTKEY,"character" ;(BASIC 1.1)-

Pretends that a key has been pressed|PUTKEY, so that next time you come to read the keyboard character value (using INKEYall machines)a$="character": |PUTKEY, INPUT or similar@a$ (BASIC 1.0)|PUTKEY, that key will appear. You can only "put backcharacter" 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 letterBASIC 1.1)

---------------------------------------Using Pretends that a key has been pressed, so that next time you come to read the commands in your own programs---------------------------------------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:

— - The headerless file was not of the right length.

— - The current SYMBOL AFTER setting is inappropriate for the command you are trying to carry out.

— - You've tried to set too many function keys at once, and the computer has run out of memory for them.

— - Five hundred elephants came charging through the undergrowth. (Well, really.)

— - A tape operation was interrupted by you pressing ESC.

— - Some sort of error occurred while trying to access a file.

— - You haven't supplied the right number of parameters (or arguments) for a command.

— - Bad news. Sounds like your headerless file has been messed up.

— - |CLI or |EXEC is trying to find a command you have given it and failing miserably, poor thing.

You are welcome to use the AA Toolkit (TOOLKIT.RSX) in your own programs --------- Copyright --------- 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.

-------------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 final word--------------Toolkit may not be copied as a toolkit, rather than as part of a program, without the permission of the author.

<pre>*ROBOT</pre>

<pre>*STS</pre>