%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % mmmmm mmm mmm m m m m mmmmm % % m m m m m m m m m m % % m m m m m m mm m m % % m m m m m m m m m m % % m mmm mmm mmmm m m m m % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% PLEASE READ AND UNDERSTAND THESE INSTRUCTIONS BEFORE PROCEEDING. Your programmer’s toolkit is supplied in a 4K EPROM which must be inserted in socket 24 of your Acorn Atom. To fit the chip, turn the Atom upside down and remove the two large crosspoint screws which attach the base to the keyboard Lift off the base and identify socket 24; this is the 24-pin socket which lies between two 40-pin sockets, one holding the 6502 microprocessor, and the other the INS 8255 I/0 chip. If a colour board is fitted this will have to be removed before proceeding, as it partly obscures socket 24. Insert the Toolkit in socket 24 so that the end of the chip with the small semi-circular indent points towards the aluminium heatsink at the edge of the printed circuit board. Make sure that none of the pins of the EPROM have become bent, and that they are all in the socket. When you are sure that the Toolbox has been inserted correctly, check once more to be certain, if necessary refit the colour board, then replace the base and screws. --------------------------------------- After the Acorn has been switched on the Toolkit is brought into operation by entering LINK #AF00 or LINK 44800. The screen will clear and the message PROGRAMMERS TOOLKIT will be displayed (the lower case letters appear in inverse video on the screen). All the toolkit commands are now available. Whenever you press the 'Break’ key you must re-link the Toolkit to activate the extra commands. The Toolkit has no effect on the operation of the Atom until it has been initialised with the LINK command. --------------------------------------- THE CASSETTE INTERFACE The Toolkit provides you with a cassette system which operates at 1200 Baud, in addition to the standard 300 Baud system. The Baud rate is automatically set to 1200 by the command LINK #AFOO (LINK 44800). Each block of data can be recorded and read in one quarter of the time tahen at 300 Baud. Because the Atom inserts a long delay between blocks, you will get the maximum advantage from the increased Baud rate by using unnamed files. You may find that the level setting of your recorder needs to be adjusted for 12O0 Baud. It is also important to keep the tape head clean to ensure reliable operation. Page 1 Of course, data must be read at the Baud rate at which it was recorded. You can switch between Baud rates in the Toolkit by using the command VECTOR; VECTOR 0 sets the rate to 300, VECTOR 1 to 1200. Alternatively, you can retain the Baud rate at 300 when you initialise the Toolbox by using the command LINK 04F04 (LINK 44804). At either Baud rate the Toolkit provides visible indication of the operation of the cassette interface. Each byte of data being sent to or received fram the cassette is displayed at the top right corner of the screen. You can thus always see that a 'load’ is proceeding correctly. When using the Toolkit cassette routines it is essential that you respond to the prompts 'PLAY TAPE’ and 'RECORD TAPE’ by pressing the Space Bar, as specified in the Atom manual, and not the Return key. --------------------------------------- THE COMMANDS COMMAND PAGE COMMAND PAGE COMMAND PAGE COMMAND PAGE AUTO . . . 3 FIND . . . 2 OFF. . . . 4 STOP . . . 5 BEEP . . . 4 HEX. . . . 5 ON ERROR . 7 TRACE. . . 4 CURSOR . . 4 IHEX . . . 3 POP. . . . 5 VAR, . . . 3 DATA . . . 6 INKEY. . . 5 READ . . . 6 VECTOR . . 4 DELETE . . 3 KEY. . . . 5 RESTORE. . 6 WHILE. , . 6 DUMP . . . 4 LTRACE . . 4 RENUMBER . 2 XIF. . . . 5 ELSE . . . 5 LVAR . . . 3 STEP . . . 3 ZERO . . . 3 ENDWHILE . 6 In the command descriptions below, if any part of the command name is enclosed in brackets the command may be abbreviated by terminating it with a full stop anywhere after the start of the brackets. Thus REN(UMBER) can be replaced by REN., RENU., etc. Commands marked 'Direct’ can only be used in the direct mode, that is , they cannot be used within programs. FI(ND) "string" Direct This command lists the numbers of all lines in which the string of characters within the quotation marks occurs. The string may be up to 32 characters long. REN(UMBER) x, y Direct This command renumbers a program, starting with x in steps of y. If only one number is entered, this will be used for the start and step. If no number is entered the default value is 10. The program is first checked to see that renumbering will not produce a line number greater than 32767, which is not permitted in Atom Basic. All GOTOs and GOSUBs are changed to match the line to which they refer, with the exception of 'indirect’ jumps, such as GOS. (A+3*B). The RENUMBER routine lists the new number of all lines containing such indirection, so that you can edit the program after renumbering. If a program contains many indirect GOTOs and GOSUBs, you may find that some of the line numbers scroll off the screen. Enter CONTROL/N and do another RENUMBER. The indirect lines uill now be listed one screenful at a time. You should not start a program with a line number greater Page 2 than 255. When you recover a program after a 'Break’ by the use of OLD, the Atom assumes that the first byte of the first line number is zero; a number greater than 255 is therefore changed by OLD. Far example, 1000, which is stored as #03, #E8, is changed to 232, Stared as #00, #E8. AU(TO) x, y Direct This initialisas the automatic generation of line numbers for use in Basic programs, starting at x in steps of y. If only one number is entered after AUTO, this will be used for the start and step; if no number is entered. the start and step will be 10. Generation of the line numbers is turned on and off with CONTROL/A; if CONTROL/A is entered beware the start and step have been initialisad line numbers will be produced, but the start and step will be unpredictable. When the routine is turned on, a new line number is produced whenever RETURN is pressed. DE(LETE) x, y Direct All lines in a program from x to y inclusive are deleted. DE. x deletes line x; DE. x, deletes all lines from x to the end of the program; DE., x deletes all lines from the start of the program to x. An error message is produced if there is no line x or line y in the program. V(AR) [#] Direct Prints the vaues of variables A - Z in two columns on the screen; if followed by the symbol #, it prints the values in hexadecimal. LV(AR) [#] VIA Direct Outputs the values of the variables A - Z to a printer connected to the Atom’s Centronics interface. If fallowed by the symbol # the values are printed in hexadecimal. ZE(RO) This command can be used directly from the keyboard or in programs to set variables A - Z to zero. H(EX) yyyy Direct The bytes stared in memnry, starting at address yyyy, are tabulated in hexadecimal and in ASCII. The format of each line is:- address (hexadecimal), four bytes of data (hexadecimal), the four ASCII characters corresponding to those bytes. Eight lines are printed, the routine then waits for a Icy to be pressed. The SPACE bar causes a further block of eight lines to appear, while the RETURN key terminates the command. The starting address can be specified in decimal or hexadecimal. IH(EX) YYYY Direct Tabulates the hexadecimal codes in memory starting at address yyyy in instruction format; that is, one, two or three bytes of data appear on a line, d»pending on the number of bytes used by the instruction represented by the first byte. As in the case of HEX, eight lines are tabulated at a time, and yyyy may be specified in decimal or hexadecimal. S(TEP) VIA Direct For this command to operate, the Atom must be fitted with Page 3 the VIA chip (6522), and link 2 (the IRQ link) must be in place. The command allows line-by-line single stepping when a program is RUN. The current line number is displayed .at the top left of the screen (unless a graphics mode is selected). The program halts at each line and waits for a key to be pressed. You can quit the program at any point with the escape key, when you can, for example, list the values of the variables with the VAR command. TR(ACE) x VIA Direct Can only be used with the VIA chip and IRQ link in place. Operates in the same way as the step command, except that it pauses for a predetermined period on each line. The delay is set by x, which should be a number, variable or expression in the range 0 - 255. If x is not entered, a value of #55 is used, which gives approximately 3 steps in tw0 seconds. LT(RACE) VIA Direct Prints the numbers of the lines as they are executed on a printer connected the the Atom’s Centronics interface. O(FF) Turns off the TRACE, LTRACE, and STEP commands. These commands must be turned off before you edit a program - editing a program with any of these three commands still in operation could result in corruption of the program. DU(MP) The printer is enabled, the contents of the screen are printed out line-by line (unless a graphics mode is selected), and the printer is turned off. VEC(TOR) x If x is zero the command sets the cassette Baud rate to 300; if x is one, the Baud rate is 1200. If other values are entered, the command is ignored. BE(EP) v, y This generates a nate whose pitch depends on x and duration on y. Both x and y may be numbers, variables or expressions between 0 and 255 (if they are outside this range, only the least significant byte will be used). The lower the value of x the higher the note will be; if x is less than 8 no nate will be heard - this can be used to qive a programmable delay. The duration can lie between about 20 milliseconds (y=1) and six seconds (y=255). 'Space invader’ sound effects can be produced with the BEEP command, e.g., 100 FOR J=1 TO 5 110 FOR K=40 TO 80 STEP 4 120 BEEP K, 1 130 NEXT; NEXT; END Music can be produced by first reading the pitches of the notes of the scale into an array (using READ and DATA statements, see below), and then specifying the desired array element as the pitch in a series of BEEP statements. Alternatively, the durations and pitches of the notes of a tune can be placed in a Page 4 series of DATA statements, and you can then READ them as you play the tune. The note values are given in the table below. N0TE VALUE VALUE VALUE NOTE VALUE VALUE VALUE A 246 121 60 D# 173 86 42 Bb 231 114 57 E 163 81 39 B 217 108 54 F 154 76 37 C 205 102 50 F# 145 72 35 C# 194 96 47 G 137 68 33 D 183 91 45 G# 129 64 51 CU(RSOR) x, y Repositions the cursor to the xth column on line y, where x and y can be numbers, variables or expressions. The leftmost position corresponds to x=0, the rightmost to x=31; if x lies outside this range, only the least significant 5 bits are used. The top line of the screen corresponds to y=O, the bottom line to y=15; only the least significant 4 bits are used. If only the first value is entered, the cursor is repositioned to the xth column on the current line. KEY A The keyboard is scanned once and the value of the ASCII code of any key pressed is returned in the variable specified after the command. If no key was pressed, a zero is returned. INK(EY) $A This command operates in a similar way to KEY, but returns the character corresponding to the key pressed in the designated string. Normally one of the string variables A - Z will be used (this must have been previously dimensioned), but forms such as INKEY $TOP or INKEY $#B200 are valid. If no key has been pressed a null string is recurned. The LOCK, COPY, CURSOR CONTROL and RETURN keys will also give a null string. STOP If a program is misbehaving, you can insert STOP commands at several points throughout the program. When the STOP is reached the computer prints STOP AT, fallowed by the line number, and then waits for a key to be pressed before continuing. If ESCAPE is pressed control returns to the Basic monitor, when you can list the variables with VAR. Once the program has been debugged, the STOP statements can be removed. POP This removes references to a current subroutine free the stack, so that you can jump directly fram the subroutine to any point in the main program, rather than going back to the command after the GOSUB which called the subroutine. XIF ... THEN ... EL(SE) The XIF command has the same action and the same syntax as the normal IF command in Atom Basic, except that it sets a flag (in location #A7) to indicate the result of the IF condition. THEN is used with XIF in the same way and with the same syntax as with IF. The ELSE command tests the flag set by the preceeding Page 5 XIF. If the condition in the XIF line was true, the whole line following ELSE will be skipped; if false, however, everything after the ELSE will be executed. For example:- 100 XIF A=1 AND B=0 THEN PRINT "CORRECT" 110 ELSE PRINT "THAT’S WRONG" The ELSE must not be placed on the same line as XIF, because it would then be skipped if the condition were false. It can be placed anywhere after that line, and in fact the XIF could be followed by several lines containing ELSE, as they would all use the flag value set by the last XIF command. If an ELSE is encountered before an XIF it will not produce an error message. but the results will be unpredictable. W(HILE) ... END(WHILE) The statements between these two commands are executed repeatedly for as long as the condition specified in the WHILE command is true. This loop differes from the DO ... UNTIL loop in two repects:- (a) The condition is tested at the start of the loop, not at the end. Thus if the condition is false on entry, the entire loop will be skipped. (b) The loop is repeated while the condition is true; the DO ... UNTIL loop is executed whiie the condition is false. WHILE can be followed by any testable integer expression (with the conjunctions AND and OR if desired). ENDWHILE takes no argument - it just serves as a marker for the end of the loop. WHILE/ENDWHILE loops can be nested inside each other up to a maximum depth of 18. Please note that WHILE/ENDWHILE is a structured loop, and the structure should be adhered to. Don’t try jumping in and out of the loop with GOTO commands. READ .. DA(TA) ... RES(TORE) These statements provide a convenient way of incorpocating data (numerical or character strings) in a program. A data painter is initialised to the start of the current text space by the RESTORE command. Each READ statement searches through the program for the next DATA. DA(TA) This can be followed by any string at characters, or by several strings separated by commas. Each time data is to be read, the next string will be taken. Depending on the form of the statement, either the data string will be taken exactly as it stands (i.e., all the characters between the commas), or it will be evaluated as an integer expression. Where numerical data is to be evaluated in this manner, ordinarily it will be simple numbers, such as:- DATA 1, 10, 250, #FF but there is no reason why a complicated expression such as ABSRND%6+4 should not be evaluated. Where data is read as a string rather than as a numerical expression, any spaces in the string will also be read, except Page 6 that spaces immediately following DATA are ignored. If the first data string has leading spaces, place a comma after the word DATA. DATA statements must not be included in multiple statement lines; they must have a line to themselves and can not be preceeded by a label. READ This can take three different types of arguments - a variable, a string ($ followed by anything which evaluates to a valid address where the string will be stored), or an array element (the array must of course have been previausly dimensioned). Each READ statement may have more than one argument if desired. Each argument will be read in turn e.g., READ $A, X, AA(X). RE(STORE) This command must be used before the first READ, to initialize the data pointer. It can be used at any other point in the program to reset the pointer. ON( ERROR) When this is encountered in a program the normal Basic error-handler vector (locations 16 and 17) is changed to the start of the statement immediately following ON ERROR, and the rest of the line, including any multiple statements, is skipped. Every time an error occurs the normal error message is suppressed and execution will recommence after the ON ERROR comand. All the interpreter stacks are cleared to ensure correct operation if the error occurs in a FOR, DO or WHILE loop or in a subroutine. This means that you should not jump into the middle of a loop or subroutine with an ON ERROR command; if you do, the end of the loop or subroutine will itself cause an error, sending control back to the ON ERROR statement, and the program will go round in circles. A program can contain more than one ON ERROR statement. For example, if a program has a series of input statements, each one can be supplied with its own error handling routine of the type:- 100 ON ERROR PRINT "NUMBERS ONLY" 110 INPUT "TYPE A NUMBER",A --------------------------------------- ERROR MESSAGES Any programming errors will still produce the normal Atom error messages, even if the error occurred as the result of the incorrect use of a toolkit command. For example, if you try to renumber a program with too large a step, so that the line number would become greater than 32767, the message ERROR 109