Basic Extensions Manual OVERVIEW -------- This ROM intercepts any error's sent to Sideways ROMs (service 6). If the error occured in BASIC and is a 'Mistake' or 'No such variable' then it processes the command/function before returning back into BASIC. It is compatable with BASIC 1,2 and 4 (Master version only), and has been tested on OS 1.20 and OS 3.20. The new commands are not tokenised since this would involve using an unused token which is not available in BASIC 4. New routines include turtle type graphics, program developement utilities, disc utilities and graphic transformations. On all machines PAGE in increased by 256 bytes. The graphics routines work by multiplying the co-ordinates to be ploted by a 'transformation matrix'. e.g { a b } { x } { ax+by } { c d } { y } { cd+dy } ^ ^ ^ | | | transformation co-ord actual screen matrix in defined co-ordinates grid system All transformations of this type are orientated on the origin e.g rotation about the origin, enlargement centred on the origin etc New transformations combine with the current one to form a composite function e.g ROTATE PI/2:LARGE 2,2 will rotate any points by PI/2 radians THEN enlarge it by a factor of 2. New Functions ------------- %BASIC This returns and integer containing the BASIC version currently being run (i.e 1,2 or 4) %BIN$ This returns a 32 character binary string of the supplied value e.g >PRINT %BIN$ 45 00000000000000000000000000101101 > %DEC This reconverts a binary string into an integer e.g >PRINT %DEC "101101" 45 > %ER$ This returns a string of the last error in the same form as the BASIC error routine e.g 10 ON ERROR PRINT %ER$:END %FREELOC This returns the next free memory location not used by variables %FREEMEM This return the amount of free memory currently left i.e from %FREELOC to HIMEM %MATRIX This return the values used for graphics transformations e.g For the example matrix in the overview, %MATRIX 1 would have the value a, %MATRIX 2 would be b, %MATRIX 3 would be c and %MATRIX 4 would be d. %TH This returns the turtle heading(in radians). NB straight up means %TH=0. Also a value of 2*PI would also mean the same, due to it meaning 'turn around in a full circle' %TX This is the turtle's X position %TY This is the turtle's Y position NB The turtle is unaffected by matrix transformations. New Commands ------------ ARC This is about the most complicated command this ROM has, and as such it has a section devoted just to it later. BYE This turns the ROM off and means that the 256 bytes are not claimed by the ROM when BREAK is pressed. To turn the ROM on again, enter *FX200,2 , then press BREAK, or alternatively enter ?(&DF0+rom socket)=0 , then press BREAK if the socket this ROM is plugged into is known. CASE This is similar to then ON x GOTO statement in BBC BASIC, and is used as follows: CASE THEN PROCa,PROCb.... ELSE... e.g CASE GET-48 THEN PROCkey1,PROCkey2 ELSE PRINT"Please press 1 or 2 only!" Here if key '1' is pressed, PROCkey1 is called; if '2' is pressed, PROCkey2 is called, otherwise the message is printed. If no ELSE condition is added and the value is out of range, then the error 'CASE range' will be generated. CAT This will perform a *CAT. If the DFS is active, and a second catalogue exists (see DFORM), this will also be printed. NB If in DFS the current drive will be set to the one specified in the command (if any). CENTRE This translates the centre of the screen for the new matrix commands. The parameters refer to the current graphics co-ordinates. CFILL This calls a fill routine which will fill over the colour at the position defined. It fills by mixing the colours defined by the MIX command. NB It is possible for very complex shapes to foil this routine, but this is very unlikely. The co-ordinates are in the defined system. This routine can be slow for large areas, so FFILL is recomended for large areas. CLTRANS This clears the defined system to the standard 1279*1023 co-ordinate grid. CLVARS This clears all variables including integer variables (not @%) as well as all stacks. CLWEND This clears the WHILE/WEND stack (see later). CURSOR This turns the cursor on or off via VDU 23,0... DFORM This enables a disc to be formatted (DFS only). Only 40 or 80 tracks are allowed. If the parameter 'E' is added then a second catalogue will also be created, allowing up to 60 filenames per side (this is Disc Doctor compatible). The second catalogue is accessed by the DSWAP command, and both catalogues are printed by the CAT command. This command was intended for DFS's without a built in formatter (e.g Acorn), but should work on any DFS which interprets OSWORD 7F properly. NB some 1770 based systems may corrupt memory when using this command, and may need forcing into single density mode. DISS This is a machine code disassembler for the 6502 chip. If the parameter 'C' is added, then the extended opcodes allowed by the Master 65C12 chip are also disassembled. Any illegal opcodes are output as an EQUB statement as per the BASIC assembler. DSWAP This, if in DFS, swaps the current and second catalogue over, and sets the current drive to the one specified in the command (if any). NB If using CAT or DSWAP with DFS, make sure that you do not save any programs under !.!!!!!!! since this file is used to check if a second catalogue exists. DUMPINT This will print out the contents of all the resident integer variables. The optional ~ makes the ouput in hexadecimal. DUMPVAR This will print out the contents of all other variables. If output is in hexadecimal, then any real variables will only have the integer part printed. e.g >A=1.2 >DUMPVAR A=1.2 >DUMPVAR ~ A=&1 DVERIFY This is a disc verify for DFS only. If no other parameters other than drive is specified, then the whole disc is verified. NB If a second catalogue is used and is the current catalogue, then only half the disc may be verified! The additional parameters allow a part of the disc to be verified. Do not verify past the last track on the disc since this will not do your drive any good! ERASE This does the same as BASIC's DELETE command, but much quicker since to delete between lines 10 and 100 (say), BASIC will try and delete 10,11,12...98,99,100 whereas ERASE will find lines 10 and 100, and just block delete this gap. If these lines do not exist, then any lines betwen these two will be deleted. FFILL This is similar to CFILL, but will not attempt to mix colours, it just fills in the current foreground colour using inbuilt OS PLOT options (PLOT 77) and so is faster. FIND This attempts to find a string in the program. If a match is found the line is printed with [ and ] around the string. If the first character is a '`' then the string will be tokenised so BASIC commands can be searched for as well. FIX This will attempt to recover a Bad Program as much as possible. Any control codes will be converted into # signs. If a '+' is added then a current program will be extended (i.e a new end will be found after the current one). FKEY This prints out the contents of the defined function keys in a form that can be copied to redefine them. On the Master, this calls the *SHOW command, whereas on the BBC the function key workspace is read direct. FREE This prints out a small table of BASIC workspace, such as HIMEM, PAGE etc. GPLOT This is the same as BASIC's PLOT command except that it uses the defined grid instead of the standard co-ordinate system. GREPL This is a global search and replace, with all replaces being printed out. A '`' in the search or replace string will cause that string to be tokenised. e.g GREPL "`A$=GET$","`A$=CHR$(GET AND 223)" GRID This clears any previous transformations then sets a co-ordinate grid with the screen edges as defined. e.g GRID -1,1,-1,1 will define a screen as follows: ------------------------------------------------------------- |(-1,1) (1,1) | | | | | | | | X (0,0) | | | | | | | | | |(-1,-1) (1,-1) | ------------------------------------------------------------- LARGE This enlarges the current screen so that lengths are multiplied by factors MATRIX This enables the values for a transformation to be entered direct, if a transformation is not a standard one. The example on page 1 would be: MATRIX a,b,c,d MERGE This takes a program from a file and merges it with a current program. Any lines overwritten are displayed on the screen. This cirumvents the need to spool an Ascii file and exec it in as per the User Guide since this works direct on saved programs. MIX This defines the 2 colours to be mixed together in CFILL. MPAGE This relocates a program to the specified address. NB No checking is done on range, so it is possible to put it onto the screen etc, hence losing your program! OSCLI This is only of benefit to BASIC 1 users which lack this function. It takes a string a converts it into a * command, but since it is in BASIC, variables etc can be used. e.g OSCLI("SAVE "+FILE$+" 1900+2000"):PRINT"SAVED!" PACK This is a program compactor which removes spaces, REMS, unnecessary colons etc then creates multi-statement lines, then re-removes any colons etc created by the process. NB save a copy of the current program before compacting in case you need to alter it. DO NOT PUT A PROGRAM WHICH USES THESE BASIC EXTENSIONS THROUGH A VARIABLE COMPACTOR SINCE IT WILL DESTROY THE COMMANDS. PARTSAVE This saves only the section of program between the two limits given e.g PARTSAVE "HI",10,30 will save between 10 and 30 inclusive. NB If the file will not save due to lack of space, but there is just enough space to save the file, then *SAVEing a block of data under the same should enable the file to save (Applies to disc only). PENDOWN This allows the turtle to draw lines on the screen. PENUP This stops the turtle drawing; instead it just moves to the position required by TAHEAD. PRENV This prints out the definition of the envelopes defined in a form suitable for copying for redefining. NB a value of -1 will be shown as 255 since these two values are equivalent for envelopes. REN This is a partial renumber utility REN start,end,new,inc will renumber lines between start and end to a new start value of 'new', with an increment of inc. Lack of memory space or giving silly parameters will cause errors. e.g >10 REM HI >20 PRINT "HI" >30 END >40 REM A USELESS PROGRAM >REN 10,30,50,1 Overlap > REFLECT This causes the current graphics grid to be reflected in a line through the origin. All lines through the origin can be written as : y = m * x or y = TAN(A) * X (A is in radians) where TAN(A)=m = the gradient of the line To reflect in this line, the command would be REFLECT A or REFLECT ATN(m) ROTATE This causes a rotation by the required angle (in radians) anticlockwise about the origin. SHEAR This causes a 2 way shear with the X and Y axis invarient. A shear factor of 0 causes no shearing hence a command such as: SHEAR 1,0 would only cause a shear, scale factor 1, X axis invarient, without affecting the Y scale. SREPL This is a selective search and replace routine. The two strings are as for GREPL, but after every successful find, the routine will wait for the user to enter 'Y' or 'N'. A 'Y' will perform the replace, a 'N' will cause it to continue. SYNTAX This enables the user to find out the syntax of a command without looking through the complete list of commands. e.g >SYNTAX "X." XHELP (C/F) > TAHEAD This causes the turtle to move ahead in the current direction. If the pen is down then a line is drawn, else the turtle just moves. A negative value causes the turtle to move backwards. TARC This is similar to the ARC command, except that the arc is drawn at the turtle position, and it ignores any defined graphics. See later for details. TLEFT This causes the turtle to rotate left by the required angle in radians. TMOVE This moves the turtle to an absolute position on the screen. Note that (0,0) is in the centre of the screen. TRIGHT This causes the turtle to rotate right by the required angle in radians. TURTLE This resets the turtle to (0,0), with heading 0 and pen down. VERIFY This compares a BASIC program file to one in memory, and if a difference occurs then the line number where this happens is shown. VIEW This allows the user to list a program file without loading it into memory, for copying a few lines from one program to another etc. WEND This marks the end of a WHILE/WEND loop. WHILE This is similar to a REPEAT/UNTIL structure, but whereas the instructions within a REPEAT/UNTIL loop must execute at least once, this is not true for WHILE/WEND. This type of loop can be stacked up to 28 times before an error occurs. An example of use is: 10 WHILE GET<>32 20 PRINT "Illegal key. Press SPACE." 30 WEND The equivalent REPEAT loop would be: 10 REPEAT 20 A=GET 30 IF A<>32 THEN PRINT "Illegal key. Press SPACE." 40 UNTIL A=32 The IF test is required here otherwise it would always be printed at least once, and a variable is also needed. XHELP This prints out the whole list of new commands and functions (see later). If the optional 'C' is added, then only the commands will be listed, whereas an 'F' would only list the functions. The ARC/TARC commands --------------------- This is a powerful command, in that it allows polygons to be drawn, or partly drawn and rotated about the center of the shape. The command format is: ARC ,,,,,(,,,) TARC ,,,(,,,) (In TARC the centre is the turtle's current position) The last 4 parameters are optional (if they are not used, then an ellipse is drawn). type If this is a 0 then an outline shape is drawn. A '1' makes a filled shape be drawn. Using EOR graphics when drawing a filled shape causes lines to appear where the triangles used to fill the shape overlap. X,Y (ARC only). These point to the centre of the shape in the defined graphics grid. Xs,Ys These are the radii of the ellipse (If they are the same then a circle would be drawn) num This optional parameter decides how many sides the polygon has. i.e 3 for a triangle,4 for a quadralateral etc... A value of 32 is adequate for an ellipse (this is what is taken as default if it is not used) NB If this parameter is used, then the other 3 must also be entered. start This decides what side the routine will start drawing at, and is entered as an angle (in radians) from the X axis (where the first point is plotted) e.g to miss out the first line of a triangle, this value would be 2*PI/3 sweep This decides how much of the shape is to be drawn from the start position, and is measured in radians. A value of 2*PI will draw the whole shape. A value of greater than 2*PI would cause the shape to be drawn more than once. angle This value (in radians) allows the whole shape to be rotated about the centre, so that the first point is no longer on the X axis. This causes the above two parameters to parameters to be adjusted so that they still work correctly. i.e start is now an offset from the first point, not the X axis any more. Looking at some of the demonstration programs over page should give some idea of how to use this command. Please note that no checking is done on the range of values entered, and it is possible to confuse this routine if polygons of over 100 sides are used (or a sweep of high value), but since these values are absolutely stupid, this should not cause any problems. Also note that TARC ignores defined co-ordinates since the turtle just works on the standard 1279*1023 screen. New errors ---------- Overlap 50 This occurs in REN if you try to renumber a section with new numbers which would put it elsewhere in the program. Bad type 51 This occurs in ARC/TARC if the first parameter is not a 0 or a 1 Bad disc size 52 Only 40 or 80 tracks can be formatted Bad catalogue 53 The optional parameter in DFORM must be an 'E' type No second 54 You tried to DSWAP a disc without a second catalogue catalogue. Wrong filing 55 You tried a DFS type command while not in DFS. system Not BASIC 56 You tried to VIEW/VERIFY a file which was not a BASIC program Bad Binary 57 A binary string can only consist of 0's and 1's. Too many WHILEs 58 You tried to stack more than 28 WHILE loops. No WHILE 59 A WEND statement was found without a corresponding WHILE statement. No WEND 60 A WHILE statement was found without a corresponding WEND. This only would occur if the condition in the WHILE statement was false. Direct only 61 A number of commands (see below) can only be entered in Direct mode i.e They will not run in a program. Bad PAGE 62 PAGE can only hold multiples of 256 e.g &E00 boundary Can't open file 63 An attempt to open a file failed e.g in VIEW, VERIFY, PARTSAVE etc. CASE range 64 The parameter for CASE did not have a PROC statement to run and there was no ELSE provision. No such command 65 The string passed to SYNTAX was not a valid command or function. MATRIX range 66 Only values of 1 to 4 can be passed to %MATRIX Function level 67 It is possible to stack functions using %DEC and %BIN$ e.g A=%DEC%BIN$%DEC%BIN$%DEC%BIN$%DEC%BIN$2 If this is too deep, then this error occurs. Commands that must be used in direct mode are: BYE ERASE FIND FIX GREPL MERGE MPAGE PACK PARTSAVE REN SREPL SYNTAX VERIFY VIEW Thanks to Peter Chapman for error testing this ROM, and to Adrian Hungate for getting me access to a Master. This ROM and accompanying manual are (C) 1987 Stephen Harris