RELEASE NOTE CASSETTE EXTENDED BASIC REFERENCE MANUAL VERSION: 5.1E Research Machines August 1981 EXTENDED BASIC VERSION 5 REFERENCE MANUAL RELEASE NOTE There are 5 versions of BASIC recorded on the two cassettes provided. These differ only in the provision of special additional functions. BASC is Extended BASIC version 5 for cassette systems, without support for the High Resolution Graphics board or Reader support. Filename BASC Version 5.1 E Start address 100 Restart address 103 Memory Limits 100-30E4 BASCG is Extended BASIC version 5 for cassette systems with level 1 High Resolution Graphics support. Filename BASCG Version 5.1 E Start address 100 Restart address 103 Memory Limits 100-3A06 BASCG2 is Extended BASIC version 5 for cassette systems with level 2 High Resolution Graphics support. This is supplied on the second cassette. Filename BASCG2 Version 5.1 E Start address 100 Restart address 103 Memory Limits 100-4737 BASCP is Extended BASIC version 5 for cassette systems with Reader support. Filename BASCP Version 5.1 E Start address 100 Restart address 103 Memory Limits 100-332B Research Machines i Copyright August 1981 Extended BASIC Version 5 Release Note BASCGP is Extended BASIC version 5 for cassette systems with level 1 High Resolution Graphics support and Reader support. Filename BASCGP Version 5.1 E Start address 100 Restart address 103 Memory Limits 100-3C46 Extended BASIC version 5.1 E is an enhancement of the previous version 5.1 D. The changes are given below. Also given below is a new version of chapter 11, which deals with the changes to the graphics commands made to cater for 80 character disc systems. They are provided in the cassette version in order to maintain compatibility between the cassette and disc versions of BASIC. 1. The maximum line length allowable on initial entry from the keyboard has been reduced by one character. This means that when the space after the line number has been inserted, the line is of maximum length, and can then be LOADed correctly. However, it is still possible to create lines of excessive length with the aid of RENUMBER, so caution should be exercised when manipulating very long lines. 2. Lower case 'e' is recognized as indicating an exponent (when found after a number). This affects VAL and INPUT only, as lower case letters elsewhere are translated into upper case. 3. Lower case 'a' to 'f' are recognized as valid hexadecimal characters after &. As in 5. above, this affects only VAL and INPUT. 4. Checks are made for silly exponents in numeric constants. Previously, the exponent was calculated modulo 256, with no overflow check. Very large positive exponents cause 'Arithmetic overflow' while large negative exponents generate zero. 5. A check is made that a line number after GOTO, GOSUB, THEN, etc. terminates the statement. Previously, no check was made. 6. Any ON ERROR flag is cleared when BASIC is reentered via its restart address (normally 103 hex). This means that the program does not automatically resume execution. 7. Line 0 (zero) is not permitted. Previously, it was allowed, but could cause some routines (e.g. RENUMBER) to fail. RENUMBER makes more checks on the line numbers it is creating and will not allow line numbers to be formed which will be rejected by other parts of the interpreter. Research Machines ii Copyright August 1981 Extended BASIC Version 5 Release Note 8. The warning messages '*Extra lost' and '*Invalid input' do not appear after INPUT from a file. Instead, these error conditions are ignored, with a new line being read after '*Invalid input'. 9. Lines not starting with a digit are ignored on LOAD, LOADGO, MERGE, and MERGEGO. This allows correct parts of corrupt files to be loaded successfully. As a result, the error message 'Missing statement number' disappears. The statement ERROR 26, which would have generated this error, now results in 'Unknown error'. 10. Error 20, 'Illegal EOF', becomes 'Illegal end of file'. 11. The console is inspected less often (every 8 statements instead of every statement) while a program is running, speeding the interpreter by about 5% on typical programs. 12. Typing CTRL O has no effect. In version 5.1 D, output was suppressed after CTRL O until another CTRL O. The advantages of this feature were outweighed by the fact that on most current keyboards, the SI key, generating CTRL O, is situated next to RETURN. The statement PUT 15 still works under COS 3.4 or later by sending a CTRL O to the COS scroller. 13. The statement 'LINE INPUT' has been added. Its effect is identical to that of 'INPUT LINE', and is introduced to make Extended BASIC more compatible with the DBAS12 interpreter, which insists on 'LINE INPUT'. 14. When CTRL F is typed, the message ^F--are you sure (Y/N): appears and BASIC waits for a key to be typed. If the response is Y or y the Front Panel is entered. Otherwise BASIC continues execution. IF CTRL F is typed while GET or GET$ is waiting for a character, the value 6 is returned and the Front Panel is NOT entered. 15. The size of the STEP on a FOR loop is now checked. If it is zero the error message 'Illegal function' is printed and program execution stops. Otherwise, the program continues as before. 16. A bug in VAL has been corrected whereby the program or CP/M could be corrupted if the string represented an illegal number. Research Machines iii Copyright August 1981 Extended BASIC Version 5 Release Note Since the manual was printed, some areas have been found where it is unclear, misleading, or simply wrong. 1. A program can be CONTinued after an END statement as well as after STOP or CTRL Z. 2. A user defined function (see Chapter 9) can be redefined as often as desired. The definition used is the one through which program flow most recently passed. 3. If control is transferred with ON BREAK or ON ERROR or ON EOF, any active GOSUBs or FOR loops are left on the stack. This may cause problems if attempts are made to resume execution inside loops or subroutines. 4. On page 2.3, for EXPONENTATION read EXPONENTIATION. The start of BASIC contains a number of jumps and vectors. These will be of interest to those who wish to add machine code subroutines to the interpreter. This listing contains the values of all the symbolic locations mentioned in Chapter 13. The addresses of the routines themselves will vary from version to version, and are here represented by zeros. 0100 C30000 0165 BASIC: JP INIT ;INITIALIZE ENTRY POINT 0103 C30000 0166 REST: JP ERR.RC ;RECOVERY ENTRY POINT 0106 C30000 0167 USR: JP ERR.FC ;USER DEFINED JUMP 0109 C30000 0168 USRVF: JP CVRLIN ;USR SUBROUTINE TO GET VAR 010C C30000 0169 USRVT: JP CS16R2 ;USR SUBROUTINE TO PASS VAR 010F C30000 0170 SAVVAR: JP SAVINT ;SAVE INTEGER IN VAR 0112 C30000 0171 OUTMX: JP .OUTM ;PRINT MESSAGE 0115 CD0000 0172 E.ERR: CALL ER.EXT ;EXTERNAL ERROR 0118 0000 0173 BBUFV: DEFW ENDIT ;END OF BASIC 011A 0000 0174 SUBPTR: DEFW 0 ;POINTER TO SUBS 011C 0000 0175 ENDMEM: DEFW 0 ;END OF MEMORY 011E 0000 0176 BRFCB: DEFW RFCB ;READ FCB 0120 0000 0177 BWFCB: DEFW WFCB ;WRITE FCB 0122 01 0178 DEFBLK: DEFB 1 ;COPY COUNT 0123 14 0179 DEFB 20 ;INTERRECORD GAP 0124 00 0180 DEFB 0 ;START BLOCK 0125 00 0181 HRMEMF: DEFB 0 ;HRG MEMORY FLAG 0182 COND RDRIN ;IF READER EXTENSIONS 0126 0000 0183 RDRCOD: DEFW 0 ;READER EXTENSION INFO ENDC Research Machines iv Copyright August 1981 Extended BASIC Version 5 Graphics CHAPTER 11A GRAPHICS The 380Z screen consists of 24 lines of either 40 or 80 characters each, depending on the hardware configuration and software selectable mode of operation. Normally, the whole of this is used for scrolling. However, Extended BASIC has a special graphics mode whereby the bottom four lines only are used for scrolling or graphics, and the top 20 lines can be used for graphics only. Each character cell can be divided into six dots arranged in a rectangle three high by two wide, with each dot capable of being set on or off individually. The 'on' dots of a particular character can be either grey or white. However, two dots within the same character cell cannot be of different shades. The top 20 lines of the screen can thus be treated as an array of dots 60 high by 80 (or 160) wide, with each dot being either off, grey, or white. The bottom four lines can be used for scrolling or graphics, and can be treated as an array 12 high by 80 or 160 wide. GRAPH GRAPH GRAPH 0 GRAPH 1 The effect of the GRAPH command depends on the value of the expression following it. This expression can take the values 0, 1, 2, or 3, or it can be omitted. If the argument is negative or greater than 3 the error message Illegal function is produced and program execution halts. GRAPH 1, or GRAPH on its own, sets the scroller to use only the bottom four lines of the screen and clears the top 20 lines, in preparation for graphics. GRAPH 0, or TEXT (see below), restores the full screen scroller. GRAPH 2 and GRAPH 3 are provided to maintain compatibility with previous versions. GRAPH 2 'opens' the screen so that PEEK and POKE work. However, it also blanks the screen, resulting at best in an annoying flicker at the top of the screen. GRAPH 3 restores the screen to its normal state. GRAPH 2 and GRAPH 3 will not work when in 80 character mode. TEXT TEXT TEXT restores the scroller to use all 24 lines on the VT screen. It is equivalent to the GRAPH 0 command described above, although it is somewhat faster and leads to clearer programs. Research Machines 11A.1 Copyright August 1981 Extended BASIC Version 5 Graphics PLOT PLOT 10,12,2 PLOT 18,21,"HELLO, WORLD",2 The PLOT command is used for plotting points, characters, and strings, anywhere on the screen. The first two arguments to PLOT are the x and y coordinates of the item to be plotted, where (0,0) is at the bottom left of the normal graphics area and (79,59) is at the top right in 40 character mode or (159,59) in 80 character mode. However, no error is caused when the plotted point lies off the screen, provided that both x and y are less than 65535 and greater than -65536. Values of x or y outside this range cause the error message Illegal function and program execution stops. Values of the y coordinate in the range -12 to -1 signify points in the bottom four lines of the screen normally used for scrolling. The third argument to PLOT, if present, is the item to be PLOTted. If it is a string, then the string is plotted character by character across the screen. Thus, PLOT 28,27,"HI THERE" would result in the message 'HI THERE' appearing in the middle of the screen. If the third argument to PLOT is a number or numeric expression, the item plotted is either a point or a character. 0, 1, and 2 signify point plotting; the specified point becomes off, grey, or white respectively. Other values in the range 3 to 255 result in the specified ASCII character being PLOTted. The following program shows the character set. Each character occupies one character cell, which is six points. 10 GRAPH 20 FOR I=0 TO 15 30 FOR J=0 TO 31 40 PLOT J*2,I*3,I*32+J 50 NEXT J 60 NEXT I 70 TEXT If the third argument to PLOT is omitted, BASIC uses the last specified value, or 0 initially. The fourth argument to PLOT sets up attributes. Attributes are available only on an 80 character board, and on a 40 character board the attribute argument has no effect. On an 80 character board, the attribute argument is treated as an 8-bit number, of which the least significant four bits control the available attributes. These are: Research Machines 11A.2 Copyright August 1981 Extended BASIC Version 5 Graphics Bit Effect 0 :- Alternate ROM 1 :- Underline 2 :- Dim character 3 :- Reverse video The attribute argument must lie in the range 0 to 255, otherwise the error message Illegal function is produced. If the attributes are omitted, they default to zero (no attributes), unless the third argument is also omitted, in which case they default to the last attributes specified. The default attributes are initially zero. As a simple example, the following program plots a sine wave on the screen, together with a heading which will be in dim reverse video on an 80 character board. 10 GRAPH 20 FOR X=0 TO 79 30 PLOT X,25*SIN(X/10)+26,2 40 NEXT X 50 PLOT 30,0,"SINE WAVE",12 60 TEXT LINE LINE 10,20,2 LINE X,Y LINE draws a straight line from the coordinates of the last PLOT command or the endpoint of the last LINE command to the specified position. The x and y coordinates can take the same range of values as for PLOT. The line will be black, grey, or white if the third argument, which defaults to the last value given, is respectively 0, 1, or 2. Larger values will cause the line to be drawn in characters, as is the case with PLOT. Again as with PLOT, an attributes argument can be specified, although it is probably not useful to do so. The effect is as in PLOT. For example, the following program draws a box in the middle of the screen, in black, grey, and white in sequence. 10 GRAPH 20 FOR I=0 TO 2 30 PLOT 10,10,I 40 LINE 10,49 50 LINE 69,49 60 LINE 69,10 70 LINE 10,10 80 NEXT I 90 GOTO 20 Research Machines 11A.3 Copyright August 1981 Extended BASIC Version 5 Graphics POINT LET A=POINT(30,30) POINT returns the intensity at the specified coordinates on the screen. As with both PLOT and LINE, both arguments must lie in the range -65536 to 65535. If the character at the specified location is a graphics character (i.e. it is a pattern of dots), POINT will return 0, 1, or 2 depending whether the point is off, grey, or white. If the point contains an ASCII character, that character will be returned. POINTS A=POINTS(30,30) POINTS will return the value of the character stored at the specified point on the screen. If the point is not a graphics character, POINTS will return the same value as POINT. A graphics character will be returned as a number in the range 128-255. ATTRIB A=ATTRIB(X,Y) The ATTRIB function returns the attributes at the specified location. On an 80 character board the number returned will lie in the range 0-15. In a 40 character board the result will always be zero. See the PLOT command for the meaning of the attribute bits. The following program will save the contents of the screen on file, and then redisplay it. This scheme allows a library of pictures to be maintained on file and be displayed as required. 10 CLEAR 1500 20 CREATE #10,"PICTURE" 30 QUOTE #10,0 40 FOR I=0 TO 19 50 LET A$="" 60 FOR J=0 TO 79 70 LET A$=A$+CHR$(POINTS(J*2,I*3)) 80 NEXT J 90 PRINT #10,A$ 100 NEXT I 110 CLOSE #10 120 GRAPH 130 OPEN #10,"PICTURE" 140 FOR I=0 TO 19 150 INPUT LINE #10,A$ 160 PLOT 0,I*3,A$ 170 NEXT I 180 TEXT Research Machines 11A.4 Copyright August 1981 IPN 01358101