TOOLKIT PLUS
BASIC PROGRAMMING AID
FOR THE BBC MICRO
by Alan Malik
1
© BEEBUGSOFT 1985
Dolphin Place, Holywell Hill, St. Albans, Herts., AL1 1EX.
All rights reserved. No part of this product may be reproduced in whole or part by any means without written permission of the publisher. Unauthorised hiring, renting, loaning, public performance or broadcasting of this product or its constituent parts is prohibited. While every care is taken, the publisher cannot be held responsible for any errors in this product.
Manual written by Geoff Bains.
1
CONTENTS
INTRODUCTION3
Conventions used3
Fitting Toolkit Plus3
Using Toolkit Plus commands3
Parameters5
Optional Parameters5
Escape5
Screen modes6
Toolkit Plus with other languages6
Toolkit Plus workspace6
SPECIAL COMMANDS7
HELP7
TOOLS8
MENU8
THE TOOLKIT PLUS COMMANDS10
AUTOSAVE10
CHECK11
CLEAR11
CRUNCH12
DUPLICATE13
EDIT13
ENVELOPE14
ERASE14
ERROR15
FKEY15
FORMAT16
HELP16
LMOVE17
LOOK18
MEMORY19
MENU20
MERGE20
PARTSAVE21
RECOVER21
RELOCATE22
RENUMBER23
REPORT24
ROMS24
1
SCREEN25
SEARCH26
SET27
SLOMO28
STATUS29
SYNTAX30
TOOLS31
TRACE32
VERIFY32
XREF33
THE FULL SCREEN EDITOR35
COMMAND SUMMARY44
1
INTRODUCTION
Toolkit Plus is a sophisticated piece of software designed to assist Basic programming on the BBC micro. It is supplied on Rom, and provides the user with more than 50 new command features which not only speed up the process of programming, but assist in the task of debugging, and generally streamline the activity of programming in Basic. Toolkit Plus also includes a full screen program editor to help you enter and modify your programs more easily.
For simplicity of use, all commands may be entered with a unique command name directly from the keyboard, or from within your own Basic program. A special option also allows nearly all the commands to be selected from a main menu and several of the routines may be entered directly from the program editor, making Toolkit Plus extremely easy to use.
Extensive error checking routines are also incorporated, and the user is given a range of error messages if commands are incorrectly entered.
Conventions used in this manual
In this manual specific keystrokes required by Toolkit Plus (such as the 'RETURN', 'SHIFT', and cursor keys) are indicated : RETURN, SHIFT and ↑↓←→.
All parameters are shown in this manual enclosed in angled brackets. Single sets of brackets >are used to indicate essential parameters, while double brackets indicate optional parameters.
Fitting Toolkit Plus
Toolkit Plus is supplied on a sideways Rom and can be fitted either in the main circuit board of your BBC micro or in any kind of sideways Rom board. Please refer to the separate fitting sheet for instructions on how to fit Toolkit Plus.
Once Toolkit Plus is fitted in your machine you may use your computer as normal, but the added commands of Toolkit Plus are now available whenever needed. You will probably be using Toolkit Plus to work on a program in Basic. This may now be loaded and run in the normal way from cassette or disc.
Using Toolkit Plus Commands
All the facilities of Toolkit Plus are accessed using 'star' commands. Each facility has a command word associated with it.
1
For example if you type the following:
*TOOLS RETURN
you will see a list of the commands available in Toolkit Plus.
The command word may be entered in either upper or lower case letters or
even a mixture of both. All of the following commands are legal with Toolkit
Plus.
*TOOLS RETURN
*toolsRETURN
*Tools RETURN
The Toolkit Plus commands may also be entered in an abbreviated form. The shortest abbreviation that you can use will depend on the types and priorities of other Roms fitted in your computer. Each command has a minimum abbreviation that will allow Toolkit Plus to recognise it. In this manual the minimum abbreviation given is the command that will call the Toolkit Plus routine when Toolkit Plus is the highest priority Rom, apart from Basic and the DFS. For the command, *TOOLS this minimum abbreviation is *TO. so this routine could also be entered by typing:
*TO. RETURN
or even:
*to. RETURN
Although each Toolkit Plus command has a its own unique command word, you may find that some of these clash with the command words of other Roms which you may have fitted to your machine. Toolkit Plus has a special feature to avoid command name clashes. If any command name clashes, when the Toolkit Plus command is required, simply preface the command name with a B - for Beebugsoft - eg type:
*BTOOLS RETURN
instead of just:
*TOOLS RETURN
This will ensure that the command is intercepted by Toolkit Plus rather than any other Rom. There are no clashes of command words with any other Beebugsoft Roms.
If you require the command from the other, clashing, Rom to be executed and that Rom does not have a similar letter prefix facility you can signify to Toolkit Plus that the command is not to be obeyed but passed on to the other Rom by prefixing the command with a B or a b and typing the second letter (the first of the command word) in a different case from the prefix.
To clarify these conventions by way of example, the following commands are all legal with Toolkit Plus and have differing effects.
*TOOLSwill execute the Toolkit Plus routine if that Rom is in
a higher priority to any clashing Rom.
*toolswill execute the Toolkit Plus routine if that Rom is in
a higher priority to any clashing Rom.
1
*BTOOLSwill execute the Toolkit Plus command regardless of
priority.
*btoolswill execute the Toolkit Plus command regardless of
priority.
*bTOOLSwill execute the routine of a clashing Rom if it is in a
lower priority to Toolkit Plus.
*Btoolswill execute the routine of a clashing Rom if it is in a
lower priority to Toolkit Plus.
A further method of calling a Toolkit Plus command is to type:
*MENU RETURN
This displays a menu on the screen from which almost all of the Toolkit Plus routines may be selected with a single keystroke.
Parameters
Many of the Toolkit Plus commands require parameters to control their action. These parameters can be either numeric, string, or literal. (Literal parameters are flags that determine the effect of the command and, when required, should be entered as given). If parameters are being entered together with the command, these should follow the command with one or more spaces between the command and the first parameter, and commas before subsequent parameters. Literal parameters should be separated from one another by spaces.
For example, the Toolkit Plus command to renumber a Basic program is
*RENUMBER. This may be followed by up to four numeric parameters to
specify the program lines which are to be renumbered and the manner in
which the renumbering is to take place. A typical renumber command issued
to Toolkit Plus might be:
*RENUMBER 1000,10,370,800 RETURN
Optional Parameters
Some parameters, such as the literals used with the *CRUNCH command, are optional. Optional parameters are indicated in this manual with a double angle bracket thus:
*CRUNCHBCLRS
<T<V<:>
So, to call this command, specifying only the B and R constraints, you would
simply type:
*CRUNCH B R RETURN
Escape
TheESCAPEkey may be used at any time to exit any Toolkit Plus routine with the exception of *CRUNCH, the menu display and the full screen editor.
1
On pressing ESCAPEduring the execution of the other routines you will see the prompt appear, signifying that you have been returned to Basic.
ESCAPEhas no effect during the compaction of a program using *CRUNCH. When in the full screen editor, ESCAPEwill take you to the menu display to select further Toolkit Plus routines and a further press of ESCAPEwill return you to the editor. CTRLESCAPEwill return you to Basic from either the menu or the full screen editor.
Screen Modes
All the facilities of Toolkit Plus, with the exception of the full screen editor, will operate correctly in all the display modes available on the BBC micro. The full screen editor is not operative in modes 2 and 5.
When a Toolkit Plus routine is called no changes will be made to the currently selected screen mode or to the currently selected text colours.
Toolkit Plus Workspace
Toolkit Plus does not raise the value of PAGE. However, it does make extensive use of the following memory areas.
PAGE 0(&0000 - &00FF)
PAGE 5(&0500 - &05FF)
PAGE 6(&0600 - &06FF)
PAGE 7(&0700 - &07FF)
PAGE 9(&0900 - &09FF)
1
SPECIAL COMMANDS
There are over fifty new command features provided by Toolkit Plus. The function, syntax, and methods of use of most of these are described in the next section of this manual. However, three of the commands, *HELP, *TOOLS, and *MENU have a different use from the other commands and so they are considered here, separately.
*HELP
Like most Roms available for the BBC micro, Toolkit Plus makes use of the Operating System's *HELP command. Issued on its own this command will display a list of the Roms present in your machine.
>*HELP
DFS 0.9V
DFS
UTILS
TOOLKIT PLUS 2.00
TOOLKIT
EXMON II 1 .03
SPELLCHECK II v1.20
WORDWISE PLUS 1.4A
OS 1.20
Some Roms are able to provide greater help on aspects of their operation by making use of the extended HELP command. Toolkit Plus is one of these. By following the command *HELP with the name TOOLKIT, a complete list of all the commands available in Toolkit Plus along with their syntax, as detailed in this manual, is displayed on the screen.
>*HELP TOOLKIT
AUTOSAVE <filename>
CHECK <filename>
CLEAR
1
CRUNCH <B> <C> <L> <R> <S> <T> <V> <:>
DUPLICATE <start>,<end>,<dest>
EDIT
ENVELOPE <envno>
ERASE <start>,<end>
ERROR <toggle>
FORMAT <trks>,<drv> <drv> <drv> <drv>
FKEY <keyno>
LMOVE <start>,<end>,<dest>
LOOK <filename>
MENU
MEMORY <addr>
MERGE <filename>
PARTSAVE <filename>,<start>,<end>
RECOVER <+> <+> <+> <+>...
RELOCATE <addr>
RENUMBER <newstart>,<inc>,<oldstart>,<oldend>
REPORT
ROMS
SCREEN <filename>
SEARCH <string1>,<string2>
SET
SLOMO <delay>
STATUS
SYNTAX <P>
TOOLS
TRACE <start>,<end>,<S>
VERIFY <drv> <drv> <drv> <drv>
XREF <R> <I> <S> <A> <H> <F> <P> <C> <L>
The list of commands is long and it will scroll off the screen. This may be prevented by typing CTRLN before issuing the *HELP TOOLKIT command and pressing SHIFTto scroll the display, or by pressing CTRL SHIFTas the list is displayed.
*TOOLS
The Toolkit Plus command, *TOOLS has the same effect as the *HELP TOOLKIT command and it will display the Toolkit Plus commands and their syntax.
*MENU
All the Toolkit Plus commands may be entered as 'star' commands directly from the keyboard or from inside a Basic program. Another method of calling the majority of the Toolkit Plus commands is to use the in built menu system.
1
The Toolkit Plus menu is called with the command, *MENU. This will display a menu on the screen from which almost all the Toolkit Plus commands may be called with a single keystroke. One command, *SCREEN, is not available from the menu as this would defeat its purpose (see the full description of *SCREEN in the next section of this manual).
The commands are arranged in the menu in groups to aid quick selection.
TOOLKIT PLUS
DiagnosticEditingProgram
1 SEARCH7 EDITD CLEAR
2 SLOMO8 DUPLICATEE CRUNCH
3 TRACE9 ERASEF RELOCATE
A REPORTA LMOVEG RECOVER
5 XREFB RENUMBERH MERGE
6 ERRORC PSAVEI SYNTAX
InfoFiling
Escape
J ENVELOPEP AUTOSAVEto edit
K STATUSQ CHECK
L FKEYR LOOKCTRL ESCAPE
M MEMORYS SETto exit
N ROMST FORMAT
0 TOOLSU VERIFYBEEBUGSOFT
Enter option:-
Any parameters required by Toolkit Plus commands selected from the menu are prompted for. So, for example, selecting option U from the menu will prompt for the disc drive number to be verified before entering the verify routine.
In addition to the Toolkit Plus commands, the menu also allows access to other 'star' commands. These can be entered in the normal way after * has been pressed.
Pressing ESCAPEfrom the menu will select the full screen Basic editor from which programs can be easily entered or altered and pressing ESCAPEfrom within the editor will take you back to the menu. Pressing CTRLESCAPE from the menu will return you to Basic in immediate mode.
1
THE TOOLKIT PLUS COMMANDS
In this section of the manual, each of the commands provided by Toolkit Plus will be described in alphabetical order. However, there are several commands which deserve special attention. *HELP, *TOOLS, and *MENU have been described in the previous section. *EDIT also requires special treatment and you will find a complete description of the full screen editor in the next section of this manual.
AUTOSAVE
Syntax:*AUTOSAVE <filename>
Minimum
abbreviation:*AU.
Menu option:P
Function:Enable the automatic backup facility.
Issuing this command without a following filename will disable the automatic backup facility. Specifying a filename will cause the program currently in memory to be saved to disc whenever CTRL@ is pressed. The program is saved under a filename which comprises the specified filename with the addition of a single character that is incremented through the numbers 0 to 9, and then the alphabet, on each successive press of CTRL@.
The filename specified should be less than seven characters. If a filename is specified that is longer than permitted, it will be truncated to six characters.
For example:
>*AUTOSAVE prog
1
CHECK
Syntax:*CHECK <filename>
Minimum
abbreviation:*CH. Menu option: Q
Function:Report differences between a program in memory and one
on cassette or disc.
This command performs a comparison of the Basic program in memory with a program on cassette or disc with the specified filename. If the two programs are found to be identical then the message Program OK is issued. At the first difference found between the programs, the routine terminates and the error is reported.
For example:
>LIST
10 REM example
20 FOR I%=0 TO 10
30 PRINT "Toolkit Plus"
40 NEXT I%
>*LOOK prog
10 REM example
20 FOR I%=0 TO 10
30 PRINT "Toolkit Plus for the BBC micro"
40 NEXT I%
>*CHECK prog
Error at line 30
CLEAR
Syntax:*CLEAR
Minimum
abbreviation: *CL.
Menu option: D
Function:Reset the resident integer variables (A% - Z%).
This command supplements the Basic command, CLEAR, which performs a similar function on all other variables.
For example:
10 CLS
20 CLEAR
30 *CLEAR
1
CRUNCH
Syntax:*CRUNCH <B> <C> <L> <R> <S> <T> <V> <:>
Minimum
abbreviation:*CR.
Menu option:E
Function:Compact a Basic program.
This command invokes a powerful set of routines which remove from a Basic program all unnecessary spaces and REM statements, concatenate program lines, and substitute short variable names.
All the various program-shortening functions will be performed if *CRUNCH is issued alone. Each of the functions may be prevented by following the command with one or more of the following parameters:
BBrackets
CProgram line concatenation
LLET statement removal
RREM statement removal
SSpace removal
TTHEN statement removal
VVariable name contractions
:Colons and null line removal
If substitution of shortened variable names is performed a list of the new, contracted variable names against the original variable names is displayed.
For example:
>LIST
10 REM example
20 FOR count=0 TO 10
30 PRINT "Toolkit Plus"
40 NEXT count
>*CRUNCH
Variable crunching
A — count
Old Program Size = 72
Bytes Saved = 40
New Program Size = 32
>LIST
20FORA=0T010:PRINT"Toolkit Plus"NEXTA
1
DUPLICATE
Syntax:*DUPLICATE <startline>,<endline>,<destinationline>
Minimum
abbreviation:*DUP.
Menu option:8
Function:Copy program lines within a Basic program.
This command may also be called by pressingCTRLDfrom within the full screen editor.
This command will copy one or more program lines between, and including, the specified start line and the specified end line, from their original position in the program to a new position after the specified destination line.
When program lines have been copied in this way the program line numbers will be out of sequence. Toolkit Plus automatically renumbers all the program lines after the destination line number in steps of ten to avoid problems when subsequently running or editing the program.
For example:
>LIST
10 REM example
20 FOR I%=0 TO 10
30 PRINT "Toolkit Plus"
40 NEXT I%
50 REM destination
>*DUPLICATE 20,40,50
>LIST
10 REM example
20 FOR I%=0 TO 10
30 PRINT "Toolkit Plus"
40 NEXT I%
50 REM destination
60 FOR I%=0 TO 10
70 PRINT "Toolkit Plus"
80 NEXT I%
EDIT
Syntax:*EDIT <line>
Minimum
abbreviation:*ED.
Menu option:Escape or 7
Function:Enter the full screen Basic program editor.
Full details of the editor are provided later in this manual.
1
ENVELOPE
Syntax:*ENVELOPE <envelopenumber>
Minimum
abbreviation:*ENV.
Menu option:J
Function:List envelope definitions.
This command will list the fourteen envelope parameters in the format of the Basic ENVELOPE command. This allows the easy editing of the parameters using the COPYkey.
The command, *ENVELOPE on its own will list the envelope definitions for all the envelopes, 1 - 16. Specifying an envelope number will list that envelope definition only.
For example:
>*ENVELOPE 3
ENVELOPE 3,1,5,5,10,255,255,1,2,2,0,1,126,126
ERASE
Syntax:*ERASE <startline>,<endline>
Minimum
abbreviation:*ERA.
Menu option:9
Function:Delete Basic program lines.
This command may also be called by pressing CTRL E from within the full screen editor.
This command is much faster than the Basic DELETE command. The command alone will delete the whole program. A section of the program may be erased by specifying the start and end line number of that section.
Specifying a single line number will delete just that line. Specifying a single line number followed by a comma will delete all lines starting at that line and a single line number preceded by a comma all line up to and including that line.
If you delete your entire program using the *ERASE command, you may recover your program with the Basic command, OLD. Sections of the program deleted with this command cannot be recovered by any means.