COPYRIGHT © 1979 by Technical Systems Consultants, Inc. P.O. Box 2570 West Lafayette, Indiana 47906 All Rights Reserved COPYRIGHT lNFORMATlON This entire manual is provided for the personal use and enjoyment of the purchaser. Its contents are copyrighted by Technical Systems Consultants, Inc., and reproduction, in whole or in part, by any means is prohibited. Use of this program, or any part thereof, for any purpose other than single end use by the purchaser is prohibited. DISCLAlMER The supplied software is intended for use only as described in this manual. Use of undocumented features or parameters may cause unpredictable results for which Technical Systems Consultants, Inc. cannot assume responsibility. Although every effort has been made to make the supplied software and its documentation as accurate and functional as possible, Technical Systems Consultants, Inc. will not assume responsibility for any damages incurred or generated by such material. Technical Systems Consultants, inc. reserves the right to make changes in such material at any time without notice. CONTENTS PAGE 1. INTRODUCTION 3 2. DEFINITIONS 4 3. CONVENTIONS 5 4. FUNDAMENTALS OF BASIC 5 4.1 Lines 5 4.2 Constants 6 4.3 Variables 7 4.4 Dimensioning 7 4.5 Assignment 8 4.6 Operators 9 4.6.1 Mathematical Operators 10 4.6.2 Logical Operators 10 4.6.3 Relational Operators 12 4.6.4 String Operators 12 4.6.5 Operator Precedence 13 4.7 Mode 13 4.8 Remarks 14 5. COMMANDS 15 6. STATEMENTS 18 6.1 Assignment 18 6.2 Transfer of Control 20 6.3 Conditional 22 6.4 Input/Output 24 6.6 Loops 25 6.6 Termination 28 6.7 Miscellaneous 29 7. SUPPLIED FUNCTIONS 32 7.1 Mathematical 33 7.2 Trigonometric 34 7.3 Character 35 7.4 Input/Output 37 7.5 Miscellaneous 38 8. SEQUENTIAL FILE I/O 40 8.1 The OPEN Statement 40 8.2 Sequential Output 41 8.3 Sequential Input 42 8.4 The CLOSE Statement 43 8.5 INPUT on Channel 0 43 8.6 Output to Other Devices 44 8.7 The KILL Statement 45 8.8 The RENAME Statement 45 8.9 The CHAIN Statement 46 TSC BASIC User's Manual 9. ERROR HANDLING 47 9.1 The ON ERROR Statement 47 9.2 The RESUME Statement 48 9.3 ERR and ERL Variables 48 9.4 Disabling ON ERROR 49 9.5 Error Handling Examples 49 10. ADVANCED DISK CAPABILITIES 51 10.1 The EXEC Statement 51 10.2 Virtual Arrays 51 10.3 Opening a Random File 53 10.4 Using Virtual Arrays 54 10.5 Notes on Virtual Arrays 55 10.6 Extending Virtual Array Files 56 10.7 Record I/O 57 10.8 Opening Record I/O Files 57 10.9 The GET and PUT Statements 57 10.10 The FIELD Statement 58 10.11 The LSET and RSET Statements 61 10.12 The CVT Conversion Functions 62 10.13 Extending Record I/O Files 63 10.14 Record I/O Example 63 11. THE USR FUNCTION 65 11.1 USR Function for 6800 65 11.2 Multiple USR Functions 66 11.3 USR function for 6809 67 11.4 Multiple USR Functions 68 12. ERROR SUMMARY 69 13. GETTING BASIC RUNNING 72 14. RENUMBER 72 15. ADAPTING TO YOUR SYSTEM 73 15.1 Adapting to your 6800 73 15.2 User noted storage 73 15.3 I/O vectors 74 15.4 User supplied BREAK routine 74 15.5 Adapting to your 6809 75 15.6 User noted storage 75 15.7 I/O vectors 76 15.8 User supplied BREAK routine 76 16. ASCII CHARACTER CHART 77 17. INDEX TO STATEMENTS AND COMMANDS 78 -2 TSC BASIC User's Manual 1. INTRODUCTION TSC BASIC is a very fast and complete BASIC. It is used like most BASIC interpreters in that lines are entered from the keyboard to build the program and the resulting program may be run at anytime by using the RUN command. It contains all of the normal interactive features of BASIC including a direct execution mode which allows BASIC to be used as a calculator. All lines entered into a BASIC program must begin with a line number. All lines are automatically put in numerical sequence which allows for simple editing. Lines which already exist in a program may be deleted by simply typing the line number of the line followed by a carriage return. It is recommended that the user read this entire manual before attempting to use TSC BASIC. It is assumed that the reader is familiar with BASIC programming, so detailed programming examples are not given. This manual contains a chapter dealing with advanced disk features (chapter 10) which does not apply to the Mini FLEX version of BASIC. The index at the end of the manual also contains these advanced disk features. If the details of a particular statement are described in chapter 10 and you are using Mini FLEX, that statement is not supported in the BASIC you have. -3 TSC BASIC User's Manual 2. DEFINITIONS Several terms which will be used frequently in this manual are defined below to avoid any confusion in their meaning. a. COMMAND A Command is an instruction for BASIC to immediatley perform some specific operation. A Command is usually issued after the user has received the 'READY' prompt from BASIC. When this prompt appears on the screen, the computer is "READY and WAITING" for the user to tell it what to do. b. LINE In BASIC, each line begins with a line number and ends with a carriage return. A line may contain only a single statement or may consist of several statements separated by colons (:) or backslashes (\). c. PRINT BASIC prints on the CRT. d. STATEMENT A Statement is an instruction for the BASIC interpreter. A Statement is usually executed by BASIC as it is encountered in a program that is being executed. In contrast to this, a Command is executed outside of a BASIC program. e. TYPE The user types on the keyboard. f. .C This is notation for CONTROL C. It is typed by holding down on the "CONTROL" key and keeping it depressed while you strike the "C" key. This entry is used to interrupt BASIC as it is performing some operation. It can, for instance, be used to interrupt a program that is currently being executed. If this is done, then the statement that is in the process of being executed will be completed; then BASIC returns to the command level to await further instruction. g. ©H CONTROL H is typed to erase the last character typed in. If this is typed when the curser is at the beginning of a line, then the result will be a Carriage Return Line Feed. h. .X CONTROL X deletes the line currently being input and performs a Carriage Return Line Feed. i. CRLF This represents Carriage Return and Line Feed characters which cause a new line to be started. -4 TSC BASIC User's Manual 3. CONVENTIONS To make the definitions of BASIC statements and commands more easily understood, several conventions will be used throughout this manual. The statement or command being described, and any other which is used in the definition, will be printed in capital letters. Angle brackets (<>) will be used to enclose essential components of the statement. Square brackets ([]) will surround optional components. Once again the types of special enclosures are: [optional element] 4. FUNDAMENTALS OF BASIC 4.1 Lines Each line of a BASIC program begins with a LINE NUMBER. The line may contain one or more statements separated by colons or backslashes and is terminated by a CARRIAGE RETURN. The length of a line can not exceed 127 characters. Lines may be numbered from 1 through 32767 and each one must have a unique number. When a program is executed by BASIC, it starts with the smallest line number and progresses toward the largest. When writing programs it is usually wise to number lines in increments of 10, 20, or more so that additional ones may be added during program debugging or modification. Spaces may be used as desired to make a program easier to read. Examples of these features are given below. Note especially that statements 30 and 40 are equivalent except that line 40 may be a little easier to read. spaces: 30 X=32*X/3+7.3*X/2+6.54*X-.1 40 X = 32*X/3 + 7.3*X/2 + 6.54*X -.1 multiple statements on a line: 120 INPUT "SPEED,TIME";S,T:D=S*T:PRINT "DIST=";D 300 A=310*X : B=K-A:C=A*2.9/11:PRINT "CF=";A;B;C -5 TSC BASIC User's Manual 4.2 Constants Numbers may be represented using either floating point or scientific notation for positive and negative values. This BASIC has six decimal digit accuracy and an approximate range of: 10E-38 to 10E38 for positive numbers 0 zero -1OE-38 to -10E38 for negative numbers A floating point number can be entered into the computer in the form that you would normally write or type it. It may be a simple string of decimal digits (an integer) or it may have a decimal point appearing somewhere (a decimal digit). Since internal representation of numbers in this form is only possible over a limited range, BASIC is forced to convert very large or small numbers to scientific notation. The form for Scientific Notation is to write the mantissa, follow it by "E", and then the exponent. Any number over six digits long, whether typed in by the user or generated by the program, will automatically be converted to Scientific notation. Expressions can also be used to represent numbers. The reasons for using an expression can best be illustrated by an example. Take for instance the number 1/3. To type this into the computer as a decimal digit requires seven key strokes for the most accurate representation possible. You would type: ".333333". An expression would have been better here since only three keystrokes are required to type: "1/3". They each represent the same quantity and typing in more than six 3's in the first representation will not provide improved accuracy because anything beyond six digits is ignored. Expressions are often desirable just for the sake of clarity alone since not many people would recognize: ".111111" as the fraction: "1/9". Some examples of different number representations are: floating point: 365 98.345 scientific notation: 6.02E-23 -1.145E7 numerical expressions: 22/7 (approximation for PI) 7+1/6 Another type of constant is the character string. It is different than the other constants both in the way it is defined and in the way it is usually used. Character string constants will probably be seen most -6 TSC BASIC User's Manual often in PRINT and INPUT statements. String constants are defined by placing any ASCII character or group of characters (a string) between single or double quotes. Some examples of strings are: strings: "WHAT IS YOUR NAME" "'FRIDAY'" (string includes single quotes) '"REALLY"' (string includes double quotes) "H" (single element string) 4.3 Variables A variable is an item of data that may take on different values. For example, it can be assigned a value by the programmer and later be changed by the program during execution. The two types of variables are "real" and "character string", where "real" is used to describe both floating point and scientific notation. A "real" variable name can consist of a single alphabetic letter or a letter followed by another letter or single digit. Examples of names to define real variables are A, K, G9, E1, or XX. The second type of variable is the string variable. It is defined by following any "real" variable name with a dollar sign ($). Using the same five variables we just did, we could have defined them to be string variables by writing them as A$, K$, G9$, E1$, or XX$. Either of the variable types may be subscripted (dimensioned) and this will be described in the next section. The same variable name can be used in a program for a real variable and a string variable. For example, the variables "A" and "A$" listed above could both be used in the same program because they are considered different variables since one is a real and the other is a string variable. 4.4 Dimensioning Either type of variable defined in section 3.3 can be subscripted (dimensioned) using the DIM statement. A variable is dimensioned in a DIM statement by following the variable name with an integer that is enclosed in parentheses or two integers that are also enclosed in parentheses but separated by a comma. To use a subscripted variable you write it just as it appeared in the dimension statement except that you may use any legal expression to describe the subscripts. Suppose a one dimensional array has been created in a program with the statement: 100 DIM X(4) This will create 5 new variables that are called: X(O), X(1), X(2), X(3), and X(4) -7 TSC BASIC User's Manual They may be used in program operations just as they are written above or the "subscript" could be a variable such as X(A) where "A" has an integer value of 0, 1, 2, 3, or 4. The subscript could also be an expression such as X(A+2). When this is encountered in a program, the subscript expression is evaluated using the current value of "A". BASIC will also support two-dimensional arrays. A two-dimensional array defined by the statement: 30 DIM X(3,2) specifies a four by three element matrix. This matrix has the following elements: X(0,0) X(0,1) X(0,2) X(1,0) X(1,1) X(1,2) X(2,0) X(2,1) X(2,2) X(3,0) X(3,1) X(3,2) Just as with the one-dimensional array, this can also be used in a program with subscripts that are expressions. The same variable name can be used to specify a non-dimensioned and a dimensioned array. BASIC will consider these to be separate but one-dimensional and two-dimensional arrays cannot share the same name. All dimensioned variables must be declared in a DIM statement. 4.5 Assignment Variables are assigned values by the LET, INPUT, or by the combination of the READ and DATA statements. These statements will be explained more thoroughly in sections 6.1 and 6.4 but they need to be introduced now to really get a feel for the BASIC language. Most variables are assigned numeric or string values using the LET statement. For example the statement: 10 LET X=2 assigns a value of "2." to X. An INPUT statement such as this one: 240 INPUT P1 causes the computer to print a question mark and then wait for the user to type in something. The data the user types will be assigned to the variable P1. READ and DATA statements must be used together. Briefly, a READ statement such as: -8 TSC BASIC User's Manual 100 READ K will assign a new value to K each time it is encountered in the program. The first execution of this statement will assign to K the first piece of data from the first DATA statement of the program. The second execution of this READ statement will assign the second piece of data in the first DATA statement to K, and so on. After all the data has been read from the first DATA statement, reading continues at the next one and then goes through all those appearing in the program. If a READ is attempted after the program has read to the end (already read the last piece of data from the last DATA statement), then error number 31 will be issued to warn of this. A DATA statement such as this one might be used: 500 DATA 1,3.14,6.02 4.6 Operators There are three different classes of operators available. The class of operators most familiar to everyone is that of the Mathematical Operators. This is comprised of addition, subtraction, multiplication, division, and exponentiation. The second class is the Logical Operators. They are used to perform bit by bit operations on integer quantities and are used extensively in conditional tests and for things such as masking. Since they operate on integer quantities the internal "real" representation (floating point or scientific notation) must first be converted to integer. The operation can now be performed and then the number is converted back to its "real" representation. All of these conversions are done automatically by the BASIC interpreter. The remaining operators are called Relational Operators. They are also used in conditional tests. They may be used in an IF statement for example to determine if one quantity is greater than another. Each of the three classes of operators will be described separately. -9 TSC BASIC User's Manual 4.6.1 Mathematical Operators MATHEMATICAL OPERATORS: SYMBOL EXAMPLE MEANING + X+Y Add X and Y -X-Y Subtract Y from X * X*Y Multiply X and Y / X/Y Divide X by Y . X.Y X to the Yth power When an arithmetic expression containing several of these symbols is to be evaluated, it is processed using the following priority scheme. 1. Exponentiation 2. Unary Minus 3. Multiplication and Division 4. Addition and Subtraction This means that when BASIC is evaluating an expression containing a mixture of mathematical operators, it will first do the exponentiation, then take into account any unary minus signs (such as -3.4 or -A). Next it will do multiplications and divisions then, last of all, it does additions and subtractions. When signs of equal priority are encountered, it does the left one first since BASIC evaluates expressions from left to right. This order can be altered by the use of parentheses. BASIC evaluates quantities in parentheses first and, in the case of nested parentheses, it starts with the innermost set and works its way out. They can and should be used anytime there is a doubt about how the expression will be evaluated. 4.6.2 Logical Operators When Logical Operators are used on one or two numbers they form the desired operation on corresponding bits of the number or numbers. If, for example, we assume A and B are equal to the following binary quantities: A=(110O1O111111O110) B=(O111O1O1111OO1OO) Then: NOT A =(OO11O1OOOOOO1OO1) -10 TSC BASIC User's Manual A AND B=(0100000111100100) A OR B =(1111111111110110) It can be seen that these are bit-by-bit operations. These operators, when used like this, operate on one or two numbers to give a single numerical result. The logical operators have a totally different effect when they are used in an expression that is the test condition of an IF-THEN statement. In this case the expression is being logically evaluated (not arithmetically evaluated) to see if it is true or false. An expression that is evaluated and determined to be true has "-1" and one that is determined to be falsstatement such as: a e hnumerical as a value value of "0". of A 22 IF A>O AND A<1O THEN GO TO 40 will branch to statement 40 if and only if A is between 0 AND 10. The logical operator "AND" specifies that the condition "A>O" be true AND the condition "A<1O" also be true. The following is a list of the available operators. LOGICAL OPERATORS: SYMBOL EXAMPLE NOT NOT X AND X AND Y OR A OR B MEANING When operating on integers, this operator simply switches each bit in the binary representation with its complement (1's are replaced with 0's and 0's are replaced with 1's). The result of this is to assign to each bit of the result a "1" if each of the corresponding bits of the two arguments is a "1". When "AND" is used in a conditional test, then both X AND Y in the example must be true for the logical AND of them to be true. This leaves each bit of the resulting integer a "1" if either of the corresponding bits of A OR B is a one. When used in a conditional test, the test will yield true if either A OR B is true. With each of these three operators, the integer result is automatically converted back into a "real" number. -11 TSC BASIC User's Manual 4.6.3 Relational Operators As the name implies, this group of operators tests the relation of variables to other variables or constants. The six relational symbols recognized by BASIC are: RELATIONAL OPERATORS: SYMBOL EXAMPLE MEANING = X=Y X is equal to Y <> X<>Y X is not equal to Y < X X>Y X is greater that Y <= X<=Y X is less than or equal to Y >= X>=Y X is greater than or equal to Y These are often combined with the Logical Operators to perform complex tests. The statement: 660 IF A=O OR (C<127 AND D <> 0) GO TO 100 will cause a branch to statement 100 if A is equal to zero OR if both C is less than 127 AND D is not equal to zero. 4.6.4 String Operators The string operators consist of the concatenation operator ('+') and the relational operators. The '+' operator will concatenate two strings (join them together) to form a new string. The relational operators, when applied to string operands, indicate alphabetic sequence. If one string is "less than" another, it implies it would appear before the other if sorted into alphabetical order. In any string comparison, trailing blanks are ignored. If two strings of unequal length are compared, the shorter string is padded with trailing spaces to make it equal in length to the other. A string of zero length (null string) is considered to be completely blank and is less than any string of length greater than zero unless the string is all spaces, then the two are considered equal. All of the standard arithmetic relational operators may be used in connection with strings. -12 TSC BASIC User's Manual 4.6.5 Operator Precedence The overall operator precedence is shown in the table below. The operator at the top of the list has highest precedence, while the one at the bottom has lowest. Operators of equal precedence are evaluated left to right. 1. () Expressions enclosed in parenthesis 2. . Exponentiation 3. -Unary minus 4. * / Multiplication and division 5. + -Addition and subtraction 6. Relational operators 7. NOT The NOT operator 8. AND The AND operator 9. OR The OR operator 4.7 Mode There are two different modes in which BASIC can function. The one referenced most often to this point is that in which you use the RUN command to execute a program that has been typed in. The other mode is the Immediate Mode. In the Immediate Mode you can type in a command or statement without a line number and the computer will immediately execute it. In contrast to this, the normal running of a program starts at the statement with the smallest line number and progresses, executing statements, toward the largest numbered statement. BASIC distinguishes between these two types simply by the presence or absence of a line number. So, for instance, if you had typed in the statement: 100 PRINT "Sunday" nothing would happen after you hit the carriage return. This is because BASIC assumes that this is part of a program you are writing and it will save and execute it only in response to a RUN command. If, on the other hand, you type: PRINT "Monday" this would be executed immediately because there is no statement number. The two types of BASIC instructions (commands and statements) cross paths because of the immediate mode. Statements can be typed in without line numbers and used as if they were a command. This is done after BASIC has printed "READY" and is waiting for you to give it instructions. -13 TSC BASIC User's Manual 4.8 Remarks It is good programming practice to use remarks freely throughout your programs. This makes them easier for others to understand and will help you too when picking up one of your own programs that you haven't worked with for awhile. Remarks can be placed in a program by using the REMARK (can be typed REM for short) statement. When BASIC comes to a REM statement it ignores whatever follows. This statement must have a line number and the number can be referenced by the program (for example, by a GOTO statement). -14 TSC BASIC User's Manual 5. COMMANDS The following is a list of the commands that are available to the user. These commands are not used in the actual code of BASIC programs but are instructions to the computer. They are to be used when BASIC is at the command level, which is after it has printed "READY". When a command is typed into the computer, it causes action to be taken immediately. NAME EXAMPLE / EXPLANATION CLEAR CLEAR The CLEAR command has the effect of setting all the variables in a program to zero. This operation is automatically performed when a RUN is executed. COMPILE COMPILE "LEDGER" The COMPILE command is used to save a program on disk in a compiled form. The file name should be specified in quotes and should be in standard FLEX form (drive.name.ext). The drive will default to the working drive and the extension defaults to 'BAC' (BAsic Compiled). The resultant saved program will in most cases be smaller than the same program saved using the SAVE command. A compiled program can not be LOADed, LISTed, or edited. It can only be run by using the RUN "name" command (see RUN). The COMPILE feature should be used to save completed programs since they usually require less disk space and always load faster. Keep in mind that a compiled program can only be RUN, and any attempt to edit or LIST it once brought into memory will result in an error 64. CONT CONT The CONTINUE command is used to restart a program after it has been stopped by either a STOP statement or a CONTROL/C. The STOP statement may have occurred anywhere in the program but the .C would have had to been typed while the program was waiting for input at an INPUT statement. The command can not restart your program if you got an error during program execution or if you type in more program lines after you have stopped. If the program was stopped by a STOP statement, then CONT will cause the program to continue at -15 TSC BASIC User's Manual the first statement following the STOP. If the program has been stopped in an INPUT statement by a .C, then the CONT command will cause execution to resume at the INPUT statement. EXIT EXIT This command is used to EXIT BASIC and enter the system monitor. FLEX FLEX The FLEX command is used to exit BASIC and return to the FLEX disk operating system. This is the normal BASIC exit method. LIST LIST (list entire program) LIST 10 (list line 10) LIST 50-80 (list lines 50 through 80) LIST can be used to display lines of a program. As the examples demonstrate, it can display all of the program or only specific lines. When a program is being listed the output may be terminated by typing .C (control C). This is another way to display only part of a program. LOAD LOAD "ORDER" The LOAD command is used to load a text type file into BASIC from disk. The file name should be in quotes and in the standard FLEX form (drive.name.ext). The name defaults to the working drive and to a BAS (BAsic Source) extension. Standard FLEX text files (such as from the TSC Editor) may be loaded. NEW NEW When the NEW command is executed, it deletes the current program. After executing this command, you are ready to start typing in a "NEW" program. -16 TSC BASIC User's Manual RUN RUN The RUN command instructs the computer to begin execution of the current program. When you RUN a program, all variables are initialized to zero and DATA statements are restored. RUN RUN "LEDGER" This form of the RUN command is used to load and execute a compiled BASIC program from disk. The file name must be in quotes and in standard FLEX form (drive.name.ext). The name defaults to the working drive and to a BAC extension. This is the only way a compiled program may be loaded from disk. SAVE SAVE "ORDER" SAVE is used to store the source form (text form) of a BASIC program on disk. The file name should be specified in quotes and in the standard FLEX form (drive.name.ext). The drive defaults to the working drive and the extension defaults to BAS. Any BASIC programs saved using the SAVE command may be manipulated by any FLEX program which works with text files (such as the EDITOR). IMPORTANT NOTE: The SAVE command will delete any existing file of the same name specified without any warning! TRON TRON The TRON command turns Trace on. Trace is used to debug programs and will print the line number in brackets of each line executed. TROFF or NEW turns trace off. + +RENUMBER The "+" command tells BASIC to send the rest of the command line to FLEX. This is a dangerous command in that some FLEX utilities load in the same area of memory as BASIC. If a FLEX utility is executed from BASIC in this way, be certain that the utility loads into the utility command space in FLEX. The main use for this command is to invoke the RENUMBER utility which is supplied with BASIC. This utility loads into the utility command space in FLEX and will renumber BASIC programs in memory. See the section titled RENUMBER for more details. -17 TSC BASIC User's Manual 6. STATEMENTS All the BASIC statements listed below are arranged in groups that have similar functions or purposes. Appearing to the right of each statement is an expression showing its complete usage. This will be followed by one or more examples to demonstrate a typical use. Then, last of all, the definition and explanation of the statement appears. 6.1 Assignment NAME FORM / EXAMPLE / EXPLANATION DATA DATA [,,,... ] [,,,... ] 50 DATA -3.556E-5,O,2,4.59E11 60 DATA APRIL, MAY, THATS ALL 70 DATA " 100"," 1OOO","1O,OOO" The DATA statement specifies information that will be read in by the program. The data is read in from left to right and, of course, begins with the first piece of data listed. Each time a READ statement is encountered in the program, the next item in the data list is read. The READ statements will begin taking data from the first DATA statement that appears in the program and, when it has read all that is in this statement, it will drop down to the next data statement and so on. If, for example, we assume we're running a program containing statement 50, the first time a READ statement is executed, the value read will be -3.556E-5. The next value read will be 0 and this continues through this statement and to the following DATA statements in the program. The DATA statement cannot appear in multiple statement lines. If a string is needed that contains an embedded comma or it is proceeded by a space or spaces then it must be enclosed in quotes as in statement 70 above. LET LET = 10 LET X=3.5 25 LET H1=27.2*H1/(5.4E7-X) 70 LET DA$="MONDAY" 75 LET X(5,J)=O (dimensioned variable) 80 Y=12.314 (implied LET) -18 TSC BASIC User's Manual The LET statement assigns a value to a variable. Any variable can be assigned a value using this statement. The value can be a constant as in statement 10 or may be a complex expression as in statement 25. Notice that statement 80 is missing the word "LET". This is no accident but is an implied LET. This is a convenience feature of this BASIC interpreter, and any LET statement can be written this way. READ READ [,,,... ] 200 READ V,A1,CC The READ statement is used to read data from a DATA statement. This has been explained in the above definition of the DATA statement for the case of a single variable argument. The READ statement can also be used with more than one argument. When a statement that is followed by several variables is executed, each of the variables is assigned the next available piece of data. Statement 200 for instance will read the next available piece of data and assign it to the variable "V". The next data entry will be assigned to "A1" and the next one will be assigned to "CC". It is important that the program be prevented from trying to read beyond the last data item in the last DATA statement because an error (number 31) will be issued if this is attempted. RESTORE RESTORE 440 RESTORE When a BASIC program is run, the first execution of a READ statement causes the first element in the first DATA statement to be read (assuming of course that there is only one variable in the READ statement). The second execution of a READ causes the second available element to be read. Each time a READ is executed it reads the next available entry from the group of DATA statements that appears in the program. When everything has been read from the first DATA statement the next READ will occur at the second data statement and so on. When a RESTORE is executed it causes the next available entry to be the first one appearing in the first DATA statement or, in other words, it resets the "next available entry" pointer to the beginning of the group of data that appears in the DATA statements of the program. -19 TSC BASIC User's Manual 6.2 Transfer of Control NAME FORM / EXAMPLE / EXPLANATION GOSUB GOSUB 5 GOSUB 250 This statement causes control to be transfered to the subroutine at the line number specified. The example will call the subroutine at line 250. All subroutines should end with a RETURN statement which will pass control back to the statement following the GOSUB which called the subroutine. GOTO GOTO 100 GOTO 50 The GOTO statement simply causes a branch to the specified line. When statement 100 (in the example) is executed, it forces a branch to line 50. The GOTO statement should only be used in the last position in lines containing multiple statements. This is because this statement always causes a branch and any statements following it would never be executed. ON GOSUB ON GOSUB 20 ON I GOSUB 30,40,50,60 The ON GOSUB statement allows calling one of several subroutines. The expression is evaluated and the integer portion of the result (any fractional portion will be truncated) determines where the jump will go. The "list of line numbers" has positions corresponding to 1,2,3,4,... So if the expression is evaluated to have a value of 1, then this statement will cause a subroutine call to the first line number in the list. A value of two for the expression will cause a subroutine call to the the second line number in the list and so on for as many numbers as you have listed. If the expression evaluates to a number which is either less than or greater than the number of line numbers listed, an error message will result. The ON GOSUB statement should be the last statement on a line. -20 TSC BASIC User's Manual ON GOTO ON GOTO 200 ON I GOTO 500,600,700 This works exactly like the ON GOSUB statement except this causes a branch to one of several lines in the program. The ON GOTO statement is not used to branch to subroutines. Use the ON GOSUB statement instead. No statements should follow the ON GOTO in lines containing multiple statements. ON ERROR GOTO ON ERROR GOTO [] ON ERROR GOTO 1000 The ON ERROR GOTO statement allows user control of certain types of errors. All error numbers between 1 and 49 inclusive may be trapped and acted upon by the user. The ON ERROR statement tells BASIC where the user error routine is located and if an error occurs which is less than 50, control will be passed to the specified line number. See the section on "Using ON ERROR GOTO" for more details. RESUME RESUME [] RESUME 100 The resume statement is used to pass control back to main program after an error routine has been executed. the section "Using ON ERROR GOTO" for more details. theSee RETURN RETURN 34 RETURN RETURN instructs the computer to return to the calling routine from the subroutine that is now being executed. This is how subroutines should be exited. When control returns to the routine that called the subroutine, execution resumes at the first statement following the statement that caused the branch to the subroutine. The statement that branched to the subroutine will normally be a GOSUB or an ON GOSUB statement. The RETURN statement, as with all the rest of the Branch statements, must be the last statement in lines containing more than one statement since statements following this (on the same line) would never be reached and executed. -21 TSC BASIC User's Manual 6.3 Conditional NAME FORM / EXAMPLE / EXPLANATION IF GOTO IF GOTO 5 IF C=1 GOTO 110 1000 IF A>B AND F<>6.O GOTO 300 The expression is evaluated and if it is true (has a nonzero value), the computer jumps to the line number following the GOTO. If the expression is not true, the next sequentially numbered statement after this "IF GOTO" will be executed. In other words, this statement would not cause BASIC to take any action if the expression is false. IF THEN IF THEN < statement > 30 IF A+B=1O THEN 50 80 IF A=O THEN PRINT "A=O" 99 IF X=Y THEN IF X>Z GOTO 40 This works similar to the IF GOTO statement except that you don't have to branch to another line. If, as in the example, you follow the expression by "THEN 50" this has the same effect as GOTO 50. Each will cause a branch to line 50 if the expression is evaluated as being true. In line 80 of the example, we specified to execute the statement "PRINT "A=0"" if the expression is true. Executing another statement is our alternative to jumping to another line. The statement could even be another IF GOTO or IF THEN statement as in line 99 of the example. IF THEN ELSE IF THEN ELSE 20 IF H/(Y+5)<8 THEN GOTO 50 ELSE PRINT "OUT OF RANGE" This is identical to an IF THEN statement except that when an IF THEN statement evaluates an expression to be false it does nothing (doesn't execute the THEN part of the statement). Execution then passes to the next sequentially numbered statement. If the expression had been evaluated to be false and there had been an ELSE following what we just discussed, then whatever followed the ELSE would be -22 TSC BASIC User's Manual executed. To simplify the explanation slightly, the basic form for the IF THEN ELSE is: IF THEN ELSE considering this form, we will assume the expression has been evaluated. If it was true, then statement 1 will be executed; and if it wasn't, then statement 2 will be executed. Looking at the example, if the expression is true then the statement "GOTO 50" will be executed. If the expression is false, then the message "OUT OF RANGE" will be printed. Just as with the other conditional statements, IF THEN ELSE statements may be nested. -23 TSC BASIC User's Manual 6.4 Input/Output NAME FORM / EXAMPLE / EXPLANATION INPUT INPUT ['string'] ; ["string"] 556 INPUT "WHAT IS YOUR AGE";A 600 INPUT '"ENTER A NUMBER"';N 650 INPUT W,X,Y,Z The INPUT statement, when executed, prints out the character string enclosed in single or double quotes (if there is one). Then it prints a question mark and waits for the user to enter the value or values requested. Either single or double quotes may be used. If one is to be part of the actual string, the other should be used to enclose the string as in line 600 above. In statements that request more than one variable, each entry from the keyboard must be separated by a comma and the last one is followed by a carriage return. If you don't enter as much data as the INPUT statement requests, BASIC will respond to your carriage return with "?" which is a prompt for more input. If too many entries are made then the extra entries will be ignored. Note that the user may respond to this statement by typing a .C. If this is done the program will be terminated and BASIC will be in a mode to accept new commands. The program will resume execution at the INPUT statement if the CONT command is typed. INPUT LINE INPUT LINE 10 INPUT LINE A$ 20 INPUT LINE B1$(5) The INPUT LINE statement is used to put an entire input line into a string variable. The entire line is accepted, including embedded spaces, punctuation characters, and quotes. No text string can be output as in the INPUT statement and only one variable name may be listed. -24 TSC BASIC User's Manual PRINT PRINT [variable, string ;... ] , [ string ;variable,... ] ; 10 PRINT (only caused CRLF) 30 PRINT "WHAT" (prints "WHAT" on the terminal) 45 PRINT "SPEED=";S 50 PRINT A,B;X;Y 75 PRINT "SOLUTION=";H*G/3.2 (expression) The information following the PRINT statement can be left out or it can be an arbitrarily arranged string of constants, variables, expressions, and character strings. If the argument string is ended with a comma or semicolon, then a CRLF (carriage return line feed) will not be performed after the statement has been executed. Otherwise, a CRLF will be printed after the data. The individual items in the argument string are separated by either a comma or a semicolon but a short explanation of BASIC's printing format is necessary before the significance of each one can be understood. BASIC divides each output line into 5 fields with each field containing 16 character positions. When arguments are separated by commas, the comma after one item will cause the printer to jump to the beginning of the next field before printing the next value or string. Thus, a comma will cause the printer to jump to column 16, 32, 48 or 64, depending on the current location of the printer. If the printer is already at column 64 or beyond, then the printer or CRT will do a carriage return/line feed and print the data in column 1 of the next line. You can type two or more commas next to each other. This will cause the printer to skip one field just as three commas would cause two fields to be skipped and so on. When items are separated by a semicolon, they will be printed next to each other. There will still be a space or two between them if one or more of the adjacent arguments are numbers. This is because numbers are printed with one trailing space and a leading space if the number isn't negative. The last necessary bit of information is that character strings don't have leading or trailing spaces added. By knowing how to use commas and semicolons and by being aware of the format used to print numbers and character strings, you can tailor printed outputs any way needed. -25 TSC BASIC User's Manual 6.5 Loops NAME FORM / EXAMPLE / EXPLANATION FOR FOR = TO [STEP] 73 FOR H=3 TO 600 88 FOR B1=3.2*(X-7) TO 200+X STEP 5 When BASIC executes a FOR statement, this will cause all the following instructions to be executed until a NEXT is reached. Execution then loops back to the FOR and if the condition specified in the FOR is true, then the statements will all be executed again. Once more control loops back to the FOR, and this cycle continues until the test finally fails, at which time execution resumes following the NEXT statement. The "variable" in the FOR statement is used to keep track of how many trips or loops have been made through the FOR-NEXT statements. The variable is initially assigned the value of "expr 1" and each time the NEXT statement loops back to the FOR statement, "expr 3" is added to the current value of the variable. Since "expr 3" can be positive or negative, this can have the effect of incrementing or decrementing the value of the variable. If no STEP is specified, then a value of positive one is assumed. When no step is specified (+1 assumed), or when a positive step is given, then the test that is specified in the FOR statement is determined to be true as long as the value of the variable is not greater than that of "expr 2". When a negative step is specified, the test yields true as long as the variable is not less than "expr 2". Once again, the statements between a FOR and NEXT will always be executed a first time but subsequent executions only occur while the index variable in the FOR statement is within the bounds of "expr 2". FOR Statements may be nested ( FOR statements located within other FOR statements), but they can't use the same index variable. The number of levels of nesting is limited only by the available memory space. FOR statements can be exited abnormally by using a GOTO instruction in the statements between the FOR and NEXT. They should not be entered like this unless they have previously been left abnormally. If you enter a FOR loop like this, the results are unpredictable and probably not what is desired because no initial value for the index variable has been specified. -26 TSC BASIC User's Manual NEXT NEXT 10 FOR I=1 TO 10 20 PRINT "X" (print 10 X's) 30 NEXT I The NEXT statement is only used in a program with a companion FOR statement. The variable specified in the NEXT statement is the same one that is in the FOR statement with which this NEXT is used. The FOR-NEXT pair specifies the boundaries of the loop. The NEXT statement is just a signal to the FOR statement that it has reached the end of the code it is to execute. NEXT causes a branch back to its corresponding FOR statement where the control variable is incremented as directed in that statement and then the test is repeated. -27 TSC BASIC User's Manual 6.6 Termination NAME FORM / EXAMPLE / EXPLANATION END END 300 END The END statement terminates program execution but its appearance in a program is optional. END can be placed anywhere in a program and it doesn't cause a break message to be printed. After a program has been terminated with an END statement, it can not be restarted with a CONTINUE command. STOP STOP 50 STOP When a STOP statement is executed, program execution is terminated and a message is printed, informing the user where the break in execution occurred. If statement 50 above were executed it would halt the program and print the message: STOP AT LINE 50 The program can be restarted with a CONT command and execution resumes following the STOP statement. In short, the STOP statement works just like the END statement except that STOP causes a break message to be printed. -28 TSC BASIC User's Manual 6.7 Miscellaneous NAME FORM / EXAMPLE / EXPLANATION DEF DEF FN[(dummy variable)]= The user can define single line functions with the DEF statement. The function is defined (understood by the computer) as soon as the DEF statement has been executed. The same function may be redefined at any time in the program because only the most recent definition is used. The defined function may contain only one argument. The dummy variable used to represent this argument is local to the function definition and has no other meaning to the program. A legal function name is formed by preceding any legal variable name (except string names) by the letters "FN". If, for example, we wanted to use the variables X, H1, and EE as function names, we would write them as FNX, FNH1, and FNEE respectively. A function is called just by the appearance of its name. When program execution does come across a function, execution branches to the "single line function definition" where the defining expression is evaluated and assigned to the function name. Execution then continues in the line where the function was called and the function name takes on the value of the function. At this point it is used in the expression in which it occurs just like it was an ordinary variable because it does have a specific value like a variable. If we defined a function called "FNTT" which would multiply a variable passed to it by 10, we could use the following definition: 180 DEF FNTT(V)=10*V Now suppose the definition has already been executed and the following two lines of code are executed: 300 X=3 310 Y=100+FNTT(X) After they have been executed the value of Y will be 130. In statement 300, "X" is assigned a value of three. The next statement first calls the function FNTT. It is passed the variable "X" which is multiplied by ten as instructed by the definition. Control now returns to statement 310 where -29 TSC BASIC User's Manual the function name (which now has a value of 30) is added to 100 and this sum of 130 is assigned to the variable Y. Restrictions on the use of the DEF statement are that the definition must consist of only one line, only one argument is permitted, the returned value must be floating point, and string functions are not allowed. DIM DIM (n) [, (m),.. ] (k,l) (m,n) 20 DIM X(20),Y(30),Z(30,40) The DIM statement was described in detail in section 4.4. In summary, the DIM statement is an instruction to the computer to reserve memory space for the variables that are listed. The memory space is allocated such that the variables can be referenced with subscripts. It is essential that all arrays be dimensioned with this statement before they are used in the program. POKE POKE
, 300 POKE 1000,33 670 POKE L,X Data may be passed to output ports or to machine language subroutines with the POKE statement. These are two frequent uses. POKE stores the "data" that is given as the second argument at the "address" that is specified by the first argument. The address supplied must be in decimal format. The address and data that are used can be numbers or variables but they must have a numeric value that is subject to the following restrictions: O <= address <= 32767 (when decimal digit) O <= address <= 65535=(HEX("FFFF")) (when "HEX" used) O <= data <= 255 If either of these fall outside of the specified limits then the respective error numbers 75 or 74 is issued. Since this statement allows you to directly change the contents of memory, it should be used with care since you could write over your BASIC program or even over BASIC itself. It is safe, however, to write to non-existent memory locations. -30 TSC BASIC User's Manual REM REM [message.... ] 40 REM This could be the name of the program 50 REM The REM statement is used to place remarks and comments throughout your program. Anything following the REM statement is ignored, including multiple statement per line characters, so remarks should be the last statement on multiple statement lines. Any character is legal following the REM and you can even leave the rest of the line blank as in statement 50. It's very likely you'll find REMARK statements at the beginning of programs to give the name of the program and what it does. Also they are often placed at different points in programs to explain what certain unclear or complicated sections of code do. -31 TSC BASIC User's Manual 7. SUPPLIED FUNCTIONS Since, in programming, there is often a need for many of the same functions to be used over and over again, several of the more common ones have been included as part of BASIC. The supplied functions are divided into five groups which are: MATHEMATICAL, TRIGONOMETRIC, CHARACTER, INPUT/OUTPUT, and MISCELLANEOUS. Most of the functions require little explanation for what they do but a few words are necessary on the way that the functions in general are called. To call a function it is necessary only for its name and the required arguments to appear. For example, when the statement: 100 Y=SQR(9) is executed, Y will have a value of three since SQR is the Square Root function. There are also character functions such as CHR$(I) which return a character string. -32 TSC BASIC User's Manual 7.1 Mathematical FUNCTION DEFINITION EXP(X) The mathematical operation e.X (e raised to the X'th power) is peformed. Here "e" is the base of natural logarithms and is approximately equal to 2.718281. The maximum allowable value of X is 87.3365. An argument any greater than this will result in overflow and error message 102 will be issued. LOG(X) This is the natural logarithm (to the base "e") of the number X. This is the only logarithm supplied with BASIC, but it is the only one needed because logarithms to any other base can be calculated from it. The following formula is used to translate to logarithms of other bases where the LOG to the base B is desired. LOG of X to the base B = LOG(X)/LOG(B) Probably the most frequent use of this will be to convert to common logarithms (base 10). As an example suppose we wanted to find the common log of the number 327. The following expression will accomplish this. COMMON LOG OF 327 = LOG(327)/LOG(1O) SQR(X) The Square Root function returns the square root of the argument X. If the argument is negative, error message 107 will be issued. -33 TSC BASIC User's Manual 7.2 Trigonometric For each of the trigonometric functions, the accuracy of the value returned is dependant on the magnitude of the argument passed to it. More accurate values will be returned by these functions when arguments with smaller magnitudes are used. FUNCTION DEFINITION ATN(X) Returns the arctangent of X, in radians. The value returned will be between -pi/2 and pi/2, where pi/2 is approximately equal to 1.5708. COS(X) Determines the cosine of the angle X. The argument X is assumed to be in radians. SIN(X) This calculates the sine of the angle X where the argument is assumed to be in radians. TAN(X) The tangent of the argument X is calculated by this function. X is assumed to be in radians. -34 TSC BASIC User's Manual 7.3 Character FUNCTION DEFINITION ASC(X$) The argument X$ is a string expression. The value returned by the function will be the ASCII numeric value of the first character in the string. Zero will be returned if the argument is the null string. CHR$(I) This returns a single ASCII character (a one character string) whose numeric value is the argument I. The argument "I" must be a number within the limits: 0 <= I <= 255. HEX(X$) The HEX function converts a hexadecimal character string into its decimal equivalent. If the statement: 180 PRINT HEX("100") is executed, then the value printed would be "256" which is the decimal equivalent of the hexadecimal value of 100. LEFT$(X$,I) Character function "LEFT$" returns a string that is the I left-most characters of the string X$. The value of I must be be a positive number less than 32,767 to avoid an error. LEN(X$) LEN(X$) returns with the number of characters in the string X$. All characters in the string are counted, even spaces and non-printing characters. MID$(X$,I) This returns a character string that is a portion of the string X$. The returned string starts at position I in the string X$ and includes everything until the end of the string. Position I must be a number between 0 and 32,767 or an error will result. -35 TSC BASIC User's Manual MID$(X$,I,J) With a three variable argument, MID$ functions the same as it does with a two variable argument except that the returned string only includes J characters of the string X$. RIGHT$(X$,I) Returns a character string that is the rightmost I elements of the string X$. If the value of I is greater than or equal to the length of the string X$, then the entire string will be returned. Error number 74 will be returned if the value of I is negative or greater than 32,767. STR$(X) This will return a character string that represents the numerical expression X. In other words, it takes a number and transforms it to a character string. The string is constructed just as it would be output, including the leading space or minus sign and a trailing space. VAL(X$) VAL(X$) does just the opposite of STR$(X). VAL(X$) takes a numerical character string (a string composed entirely of numbers, plus or minus sign, and decimal point) and converts it to its numerical VALue. Zero will be returned if the first non-space character is anything other than a digit or a decimal point, plus sign, or minus sign. -36 TSC BASIC User's Manual 7.4 Input/Output FUNCTION DEFINITION PEEK(I) This function does the opposite of the BASIC statement POKE. PEEK(I) returns the contents of memory location I ( where I is the decimal address ). The value returned will be >=O and <=255. If the current value of the argument is negative or greater than 32767, error number 75 will be printed. If the HEX function is used, up to 65534 words may be addressed. P0S(I) The value returned will be the current column position of the cursor in the current line. Numbering starts at zero, so if the value returned is zero, then the cursor is in the first position (column) of a line. SPC(I) This function may only be used in a print statement. It causes "I" spaces to be printed. BASIC will respond with error number 74 if the value of I is negative or greater than 255. TAB(I) This function also must only be used in print statements. It moves the cursor to column I on the CRT or would move the print head to this column if a printer is being used. If the cursor is already past this position, then no action is taken. As usual, the argument must be positive and less than 256. -37 TSC BASIC User's Manual 7.5 Miscellaneous FUNCTION DEFINITION ABS(X) The absolute value of X is returned by this function. If X is positive, then the value returned is X, and if it is negative, the value returned is -X. INT(X) The value returned is the largest integer that is not greater than X. This function is often called the "Floor" of X. Several examples of the values returned are shown below. INT(70) =70 INT(-.01)=-1 INT(5.7)=5 INT(-3) =-3 INT(O) =0 INT(-4.2)=-5 PI This returns the value of "PI". PTR(var name) The PTR function returns the address of the variable named as the argument. If the variable is a floating point type, the address returned will be the actual storage location of the number. Floating point numbers are stored as four bytes, the first three being the mantissa (sign plus magnitude, with the sign in the most significant bit position) and the last byte is the exponent (base 2, biased by hex 80). The mantissa is kept in hidden bit, normalized form. If the argument is a string variable name, the value returned is the address of a four byte "string descriptor". The first two bytes of the string descriptor contain the actual address of the string, while the second two bytes indicate the strings length. It should be noted that no special string termination characters are stored with strings and any 8 bit combination is valid in a string. -38 TSC BASIC User's Manual RND(X) The function returns a random number that has a value between zero and one. The programmer can use this to generate random numbers between any desired limits using the formula: Random Number=(ML-MS)*RND(O)+MS Where ML is the larger number and MS is the smaller number. The resulting number that is generated will range from MS to ML. The argument X has an effect on the number that is generated according to the following rules. XO This returns the last random number that was generated. SGN(X) This is the sign function. It returns "1" if the argument is greater than zero. A zero is returned if the argument is zero and a minus one is returned if negative. -39 TSC BASIC User's Manual 8. SEQUENTIAL FILE I/O The simplest form of file I/O in BASIC is sequential I/O. Regular text files may be read and created sequentially. All disk data files are created with a default extension of "DAT" for DATa, and the default drive is the working drive. These defaults may be over-ridden at any time by simply specifying the desired extension or drive in the file name, as in any standard FLEX file specification. 8.1 The OPEN Statement Before any file may be used in BASIC, it must first be opened. The OPEN statement is used for this purpose. For sequential file manipulations, there are two forms of the OPEN statement. The syntax is as follows: OPEN OLD AS OPEN NEW AS Examples: OPEN OLD "TEST" AS 1 OPEN NEW A$ AS F The OPEN OLD statement will open the file specified in the string expression for read. The defaults are the working drive and DAT for the extension. The AS clause tells BASIC which I/O channel to use for the file I/O. The file channel may be 1 to 12, which means there is a limit of 12 open files at any one time (memory permitting). If the file is not found, an error will result (error #4). This error may be handled by using ON ERROR GOTO. Once opened, the file is ready for reading. The first example will open the file "TEST.DAT" on the working drive on channel I for read. The OPEN NEW statement is used for creating a new file and preparing it for writing. The file specified in the string expression will be created if it does not already exist. If it does exist, the original file WILL BE DELETED and a new file with the same name will be created! The defaults for the file name are as in OPEN OLD. The second example above will open the file whose name is contained in the string variable A$ for write. The I/O channel used will be the value of the variable F. It should be noted that the OPEN statement will not actually open the file on the disk, but will only make the preparations to do an open file operation. Only when actual file I/O is required will the file truly be opened on the disk. This implies that an OPEN OLD statement which tries to open a non-existent file will not generate an error, but when actual input is attempted, the error #4 will be generated. -40 TSC BASIC User's Manual 8.2 Sequential Output A modified version of the PRINT statement is used to output sequential data to a disk file. Its syntax is as follows: PRINT #, where the expression is the internal channel number specified in the OPEN statement. The list is the list of information to be output and follows all rules of the normal PRINT statement. An example will demonstrate its use. 10 OPEN NEW "TESTFILE" AS 3 20 PRINT #3, "THIS IS A TEST FILE" 30 PRINT #3, "THIS IS THE SECOND LINE" The above lines create a new file called "TESTFILE.DAT" on the working drive. Internal channel number 3 is used. The resultant file will have two lines, the first will be THIS IS A TEST FILE and the second will be THIS IS THE SECOND LINE. Another example will demonstrate a method of creating a table of the integers 1 through 5 and their values squared. The program might look as follows: 100 OPEN NEW "SQUARES" AS 1 110 FOR I=1 TO 5 120 PRINT #1, I, I.2 130 NEXT I The file that is created is a pure text file and may be edited, listed, etc. with any of the standard FLEX utilities. Listing the file SQUARES.DAT created above would display the following: 1 2 3 4 5 1491625 Notice that since commas were used in the PRINT statements, the resultant lines have the numbers spaced accordingly. -41 TSC BASIC User's Manual 8.3 Sequential Input Like the PRINT statement, the INPUT statement may also communicate with a file. The INPUT syntax is: INPUT #, INPUT LINE #, where the expression is the internal channel number referenced in the OPEN statement. The list is the same as the normal INPUT statement. No question mark prompt is output when inputting from a channel. The INPUT LINE will input an entire line from the disk file and put it in the string variable specified. An example will demonstrate input from a file. 10 OPEN OLD "NUMBERS" AS 2 20 INPUT #2, A, B This will cause the variables A and B to be read from the disk file NUMBERS.DAT on the working drive. The file must provide ASCII data exactly as it would be typed if the input were coming from the terminal. Since two variables need data, the numbers in the file must be separated by a comma and terminated by a carriage return, or both may be terminated by a carriage return. If a file is being created to be read later by an input statement such as shown above, commas need to be manually inserted in the data file between the data items. For example: 100 OPEN NEW "NUMBERS" AS 6 110 PRINT #6, A; ","; B 120 CLOSE 6 130 OPEN OLD "NUMBERS" AS 6 140 INPUT #6, A, B 150 PRINT A, B This sequence of lines will create a file NUMBERS.DAT on disk, output the values of A and B separated by a comma, close the file (see below), open the file for read, read in the values of A and B, and print the results on the terminal. It should be noted that reopening file for read after closing it will position the pointer back to the beginning of the file so all of the data becomes available for sequential read. -42 TSC BASIC User's Manual 8.4 The CLOSE Statement The CLOSE statement is used to terminate I/O between BASIC and a file. Closing a file also frees up the internal channel it was using allowing another file to be opened on the same channel. The syntax of the CLOSE statement is: CLOSE [,...] The expression indicated should have the same value as that used in the OPEN statement for the file and indicates the internal channel number of the file to close. Any number of files may be closed with one CLOSE statement. Some examples will demonstrate its use. 200 CLOSE 3 520 CLOSE 1,6 Line 200 will close the file on I/O channel 3 and line 520 will close the files open on channel 1 and channel 6. An error will result if the file had not been previously opened. 8.5 INPUT on Channel 0 Some times it is desirable to request input from the terminal but not output a question mark prompt as the INPUT statement does. This can be accomplished by inputting from channel 0. Even though it is illegal to open a file on channel 0, it is possible to reference channel 0 with the INPUT statement, just for the purpose of eliminating the input prompt (the question mark). An example follows: 10 INPUT #0, B$ will request input from the terminal just as a normal INPUT statement, but no question mark prompt is output. After entering the data and typing the return key, a carriage return line feed will not be echoed as is done with the standard INPUT. This mechanism will allow precise cursor control in programs requiring fancy input prompts. Remember that files may not be opened for input on channel 0, but referencing channel 0 in an INPUT statement is allowed for the above stated purpose. -43 TSC BASIC User's Manual 8.6 Output to Other Devices It is often necessary to have a BASIC program output to a device other than the terminal. Channel 0 has special meaning for the PRINT statement just as it does for the INPUT statement. Using channel 0 without an OPEN statement when PRINTing will print on the terminal just as if the channel 0 had not been specified. As an example: 200 PRINT #0, "THIS IS A TEST" will print THIS IS A TEST on the terminal, exactly as if the "#0," were not present. Opening channel 0 allows you to send output to some device (such as a line printer) rather than the terminal. This is done in much the same way as the "P" command works in FLEX. Using OPEN and specifying channel O will tell BASIC to read the file name specified as a PRINT.SYS type file and use this new output routine whenever PRINT #0 is specified. An example will demonstrate its use. 10 OPEN "O.PRINT" AS 0 20 FOR I=1 TO 10 30 PRINT #0, I, SQR(I) 40 NEXT I 50 CLOSE 0 Line 10 tells BASIC to read in the file PRINT.SYS (SYS is the default extension when channel 0 is referenced). Notice that it was not necessary to say OPEN OLD. The PRINT.SYS file format is described in the FLEX User's and Advanced Programmer's Manual. Once the PRINT.SYS file has been read, all output through PRINT #0 statements will use the driver routines which are contained in the print file loaded. If the PRINT.SYS contained drivers to output to a parallel printer port on port 7, then the output from the above sample program would have gone to that printer. All output with PRINT statements not containing the #0 would still go to the terminal. The CLOSE 0 statement would tell BASIC to send all PRINT #0 output data back to the terminal again until another OPEN AS 0 statement is executed. One last example will demonstrate the print to channel 0 use. This program allows output to be sent to either the terminal or the printer by user request. 10 INPUT "TERMINAL OR PRINTER (T OR P)",R$ 20 IF R$="P" THEN OPEN "O.PRINT" AS 0 30 FOR I=1 TO 10 40 PRINT #0, I, SQR(I) 50 NEXT I 60 CLOSE 0 70 END -44 TSC BASIC User's Manual Line 10 asks if the output should go to the printer or the terminal. Only if the response is P for printer will the program open channel 0 (line 20). If channel 0 is opened, the output from line 40 will go through the printer drivers supplied from PRINT.SYS and on to the printer. If it is not opened, the output will go to the terminal. It is very important that the file specified in the OPEN AS 0 statement is actually a printer system file. If it is not, unpredictable results will occur, possibly crashing BASIC! 8.7 The KILL Statement The KILL statement is used to delete an existing disk file. Its syntax is of the form: KILL where the string expression is used as the file name to be deleted. The default extension is BAS and the default drive is the working drive. This statement may also be used in the immediate mode. There is no prompting with this command as in the FLEX delete command, so caution is advised An example will demonstrate its use. 100 KILL "LEDGER" This line will delete the file named LEDGER.BAS from the working drive. Again, there is no prompt with this delete so be careful! 8.8 The RENAME Command The RENAME statement is used to rename a disk file. It may be used in a program or in the immediate mode. Its syntax is: RENAME , where the first expression specifies the name of the file to be renamed and the second expression is the new name it will have. The name defaults to a BAS extension and to the working drive. As an example: 225 RENAME "TEST", "OLDTEST" This line will rename the file TEST.BAS on the working drive to OLDTEST.BAS. If TEST does not exist, an error #4 will be issued. -45 TSC BASIC User's Manual 8.9 The CHAIN Statement When a program is too large to be loaded into memory and run by BASIC it must be divided into several smaller segments. The CHAIN statement is used to load and run these program segments from a running program. The program segments may be either BAS type source files or BAC type compiled files. Each segment has its own file name and any program on disk may be passed control (similar to a GOTO) by CHAIN. syntax is: The CHAIN [] The file name referenced by the string expression will be loaded and executed. The name will default to the working drive and BAC (compiled form) extension. The second optional expression designates the line number at which the program should be started. Without the line number specification, the program will begin execution at the lowest numbered line, just as with the RUN command. An example will demonstrate: 1300 CHAIN "BALANCE2" 100 This line will cause the file named BALANCE2.BAC to be loaded and run starting at line 100. Chaining to compiled programs (BAC type) will be much more efficient than chaining to source type files (BAS). The only way a source file can be chained is if it has a BAS extension and if the extension is explicitly stated in the file name. All other extensions will be assumed to be compiled type files. Communication between chained programs must be performed through disk files. When the CHAIN statement is executed, all open files are closed, the new program is loaded, and execution continues. Any files to be used in common by several programs should be opened in each of the programs run. -46 TSC BASIC User's Manual 9. ERROR HANDLING There are two classes of errors which can happen while executing a BASIC program. The first class consists of I/O errors, both disk and terminal related, while the second class deals with computational and syntax type errors. The complete list of error numbers and their respective meanings are in a following section. The error numbers between 1 and 49 are all I/O type errors while 50 and above fall into the second class. It should be noted that error numbers 1 through 28 are disk errors and are the same as those generated by FLEX. Normally BASIC will print the error number as the error occurs and the program will come to a halt. Many times it is desirable to continue execution of a program after an error occurs, especially if the error is I/O related. The ON ERROR statement is used for this situation and may be used to control the result of any I/O related error. 9.1 The ON ERROR GOTO Statement The ON ERROR GOTO statement is used to tell BASIC that there is a user supplied error handling routine. Anytime an error occurs which is in the range of 1 to 49, BASIC will check to see if an ON ERROR statement has been executed. If it has, control is transfered to the line specified, otherwise, the program will halt and print the error message in the usual manner. The syntax for the ON ERROR statement is: ON ERROR GOTO [] This statement should be placed in the program before any lines which may cause an I/O error for which the error routine deals. If an error does occur, control will be transfered to the line number specified in the ON ERROR statement. The system variables ERR and ERL will also be set to the value of the error number and to the line number which caused the error. More about these variables to follow. -47 TSC BASIC User's Manual 9.2 The RESUME Statement The RESUME statement is used to pass control back to the main BASIC program after the error handling routine has completed. During program execution, if an I/O error occurs, and an ON ERROR statement has been executed, BASIC will go to the first line of the error handling routine. When the error routine is finished it must pass control back to the main program, the function of RESUME. The syntax for the RESUME statement is: RESUME [] If a line number is specified after RESUME, BASIC will restart the main program execution at that line. If no line is specified (or 0 is specified), BASIC will resume by re-executing the line which caused the error. If this second method is used, note that the entire line will be re-executed, and not just the statement which caused the error. Thus, if the offending statement was not the first statement on the line, the preceeding statements on that line will also be repeated. Two examples follow: 1000 RESUME 2000 RESUME 200 The first example will restart the main program on the line which caused the error (this is equivalent to RESUME 0). Line 2000 would cause the program to resume at line 200. A RESUME statement should always be included in error handling routines. No other form of return is valid. 9.3 ERR and ERL System Variables When any error occurs, the two variables named ERR and ERL are updated. The ERR variable will contain the error number and ERL will contain the line number of the line which was executing at the time the error happened. These variables may not be set by the user but may be read at anytime. As an example: 130 IF ERR=4 THEN PRINT "NO SUCH FILE" This line will cause BASIC to print NO SUCH FILE if the last error was an error number 4. The variable ERL is used in a similar manner. It should be noted that programs using the ERL variable may need alteration after a RENUMBER operation since the line referenced may change! -48 TSC BASIC User's Manual 9.4 Disabling ON ERROR Many times there are only sections of a program which require a user supplied error routine. It is possible to disable the ON ERROR feature once it has been disabled by using one of the following: ON ERROR GOTO 0 ON ERROR GOTO Both of these are equivalent. After execution of this statement, BASIC will handle all errors, printing the error number and halting. Another user error handler may be setup at anytime by executing another ON ERROR GOTO and specifying the line number of the routine. The ON ERROR GOTO 0 statement may also be placed inside a user error handling routine. If BASIC comes across an ON ERROR GOTO 0 statement while executing a users error routine, the user routine immediately exits, and BASIC will print the error number on the terminal, just as if the user routine had never been activated. 9.5 Error Handling Examples Following are two examples which demonstrate typical applications of the ON ERROR and related statements. The first example deals with "data type mismatch" errors (error number 30). 10 ON ERROR GOTO 1000 20 INPUT "PLEASE TYPE THREE NUMBERS",A,B,C 30 PRINT "THE SUM IS";A+B+C 40 GOTO 20 1000 IF ERR<>30 THEN ON ERROR GOTO 0 1010 PRINT "PLEASE TYPE NUMBERS ONLY!" 1020 RESUME Line 10 tells BASIC where the error routine is located (line 1000). When the INPUT statement is executed on line 20, it expects numeric data only to be input. If the user enters a letter instead of a number, BASIC would normally stop and print ERROR #30 AT LINE 20 at the terminal. Since the ON ERROR statement has been executed, BASIC would transfer control to line 1000 if an error occured. Line 1000 checks to see if the error is number 30. If ERR is not 30, the ON ERROR GOTO 0 is executed which disables the error handling routine and causes BASIC to print the error number on the terminal and stop. If it is error 30, the message on line 1010 is printed. Line 1020 will cause the program to resume execution at the line which caused the error (line 20), and the input prompt will be reissued. -49 TSC BASIC User's Manual The second example demonstrates disk I/O error handling. A common situation when working with disk files is the detection of the end of file. The following short program will list a disk text file on the terminal. 10 INPUT "PLEASE TYPE FILE NAME (WITH EXTENSION)",F$ 20 ON ERROR GOTO 1000 30 OPEN OLD F$ AS 1 40 INPUT LINE #1, L$ 50 PRINT L$ 60 GOTO 40 100 CLOSE 1 110 END 1000 IF ERR<>8 THEN ON ERROR GOTO 1010 RESUME 100 After the file name is input on line 10 the error routine is identified to BASIC in line 20. Line 30 opens the file for sequential input on internal channel 1. Lines 40 and 50 read the file a line at a time and prints each line at the terminal. Eventually the end of the file will be reached and an error will occur at line 40 from attempting to read past the end of the file. At this time control will be passed to line 1000 which tests to see if the error was an error number 8 (end of file). If it is, then the program is resumed at line 100 which closes the file and ends the program. If the error was not 8, then the error number will be printed and the program stopped. -50 TSC BASIC User's Manual 10. ADVANCED DISK CAPABILITIES All of the additional statements and functions described in this section are not included in the Mini FLEX version of TSC BASIC. Most of these features deal with random file I/O which is not supported in Mini FLEX. It should be noted that any file created as a random file in BASIC may be read as a random or sequential file, but a file created as a sequential file can only be accessed sequentially. This is true of all FLEX random and sequential files. 10.1 The EXEC Statement The EXEC statement is used to execute any FLEX utility which loads into the FLEX utility command space ($A10O). Its syntax is: EXEC, where the string expression is used as a FLEX command, just as it would be typed into FLEX. As an example, suppose it was necessary to set a TTYSET parameter during a BASIC program execution, such as the line width. The line might look as follows: 300 EXEC, "TTYSET WD=64" The string in quotes would be sent to FLEX and executed, just as if it had been typed directly into FLEX. Remember that only commands which reside in the utility command space should be called. Programs which load into low memory will kill BASIC! BASIC does not check for a low memory utility, so it is up to the user. 10.2 Virtual Arrays The simplest form of random file I/O is called virtual arrays. The virtual array mechanism allows the user to specify that a data array be stored on a disk file rather than in memory. The two advantages of this feature are that the array may be much larger than what would fit in the available memory and that the data in the array remains after program execution and may be used at a later date from another program. Virtual array data is referenced exactly like standard array data which makes the mechanism quite powerful and easy to use! -51 TSC BASIC User's Manual The sequential I/O methods previously described only allow the next sequential data item to be accessed or stored at any one time. The virtual array storage method allows a random data item to be accessed or stored, no matter where in the file the item resides. Before a data matrix can exist in a virtual array, the array must be declared using a special form of the DIM statement. Its syntax is: DIM #, ( ) The expression designates an internal channel number and must be between 1 and 12. This is the channel number on which the file will be opened. Only one variable may be associated with each virtual array channel number. The variable may either be single or double dimension. As an example: 20 DIM #3, A(1O0,50) would define the matrix A to be 100 by 50 in size and be associated with channel 3. Virtual arrays may either be string or floating point. All data items are stored in the file in "internal format", 4 byte binary for floating point numbers, and ASCII characters for strings. For the most part, virtual array and standard memory array manipulations are identical. One difference is in the way string storage is performed. In a standard type string array, the data items may be any length and change in size as the program executes. A virtual string array requires each string in the array to have the same length. The maximum length allowed is 252 characters but may be defined to be anywhere from 1 to 252. Each string element stored into a virtual array will either have enough spaces attached to the right side of the string to make it equal in length to the defined string size (if it is shorter than the defined length), or it will be truncated from the right if it is longer than the defined length. To define the string length for a particular virtual string array, the following form should be used. DIM #, = Example: 100 DIM #7, A$(10O)=63 The equals sign and expression define the string length to be used. Again, the maximum length is 252 characters. The example defines the virtual string array A$, which has 101 elements (including the 0 element), each of which are 63 characters in length. If a string length is not specified in the DIM statement, a default length of 18 is used. -52 TSC BASIC User's Manual The length of a virtual string array data item can greatly affect the efficiency of data storage in a disk file. The system requires that a string be completely contained in one disk sector and that the string may not cross a sector boundary (thus the limit of 252 since there are 252 bytes of storage available in one sector). To avoid wasting disk space, the defined string length should be an even divisor of 252. A few examples will demonstrate this. 10 DIM #1, A$(1O0) 20 DIM #2, B$(1OO)=63 30 DIM #3, C$(20)=130 Line 10 would default to a string length of 18, creating 14 strings per sector. No disk space is wasted since 14 times 18 is 252. Line 20 would create strings of length 63, again not wasting disk space since there would be 4 strings per sector and 4 times 63 is 252. Line 30 is extremely wasteful since only one string of length 130 will fit in a sector, 50 252-130 bytes (122 bytes) are wasted in each sector of the file. 10.3 Opening a Random File Before any random file may be referenced, it first must be opened. Opening a random file is a little different than opening a sequential file. There are three forms of the OPEN statement for random file use. OPEN OLD AS OPEN NEW AS OPEN AS The OPEN statement used determines whether an existing disk file is to be used or if a new file should be created. The open statement does not determine if the file is going to be used for input or output as in the sequential file use since random file operations allow both input and output to a particular file. Each OPEN type will be described separately. The OPEN OLD statement tells BASIC to search for a file which already exists (an "old" file). If the file is not found, an error number 4 will be issued. As an example: 10 OPEN OLD "TEST" AS 8 will cause BASIC to search the working drive (by default) for the file named TEST.DAT. DAT is the default extension. Either of the defaults may be over-ridden, just as any FLEX file specification. If the file is not found, error 4 will be generated. -53 TSC BASIC User's Manual The OPEN NEW statement tells BASIC to create a "new" file. If the file name specified already exists, IT WILL BE DELETED, and a new file of the same name will be created. If the file does not exist, be created. As an example: it will 10 OPEN NEW "INVENT" AS 4 will cause a new file named INVENT.DAT to be created on the working drive. The same file name defaults apply as stated above. Finally, the OPEN statement, without the NEW or OLD modifier will first attempt to open an existing file (just like OPEN OLD). If the file name is not found, one will be created and no error will be issued. 10 OPEN "NAMES" AS 1 This line would cause BASIC to first search for a file named NAMES.DAT on the working drive (the above stated file name defaults apply). If the file is found it is opened. If the file is not found, one is created with the specified name. As in the sequential OPEN statement, the file is not actually opened at the time the OPEN statement is executed, but is only prepared for the opening process. When the first I/O attempt is executed, the disk file will actually get opened, so any file related errors will be delayed until this first I/O operation is performed. 10.4 Using Virtual Arrays Before a virtual array may be used, the corresponding disk file must be opened using the OPEN statement described above, and the array must be defined using the special DIM statement. Once this has been done, the virtual array may be used in assignments and expressions exactly like any standard array with one exception. There may only be one virtual array reference in an expression. A short example will demonstrate virtual array use. 10 OPEN "TESTFILE" AS 1 20 DIM #1, A(10O) 30 INPUT "TYPE ARRAY ELEMENT, NEW VALUE",E,V 40 PRINT "THE CURRENT VALUE IS";A(E) 50 A(E)=V 60 PRINT "THE NEW VALUE IS";A(E) 70 CLOSE 1 80 END Line 10 opens the file named TESTFILE.DAT on the working drive. If the file does not already exist, one will be created (because of the type of OPEN statement used). Line 20 defines the virtual array A which is a -54 TSC BASIC User's Manual floating point array containing 101 elements (counting element 0). From this point on, the program treats the array A just as if it were a standard array. Line 30 requests which element in the array is to receive a new value and what that value should be. Line 40 prints the current value of that data item, line 50 gives it the new value, and line 60 prints the new value of the selected array item. Notice that the array reference is purely random, and that it was not necessary to access the file sequentially. Line 70 closes the file (as is necessary after completing use of any disk file). The file TESTFILE now exists on the disk with the selected data item altered to reflect its new value. 10.5 Notes on Virtual Arrays A file created or referenced as a virtual array has no information contained in it which specifies its dimension or data type. If the file was created as a floating point virtual array, it consists of 4 byte binary numbers, one right after the other, with 63 numbers per sector (63 times 4 is 252). If it was created as a string array, it consists of one string after the other, of length specified in the DIM statement. A double dimensioned virtual array is stored in row form. This means that row 0 is closest to the beginning of the file, followed by row 1, etc. This information is important in two respects. First of all, sequential access of virtual array data items in a 2 dimension array will be faster if accessed by row than if accessed by column. The following example demonstrates this point. Program #1 Program #2 10 OPEN OLD "DATA" AS 1 10 OPEN OLD "DATA" AS 1 20 DIM #1, A(20,20) 20 DIM #1, A(20,20) 30 FOR I=0 TO 20 30 FOR I=0 TO 20 40 FOR J=O TO 20 40 FOR J=O TO 20 50 PRINT A(I,J) 50 PRINT A(J,I) 60 NEXT J 60 NEXT J 70 NEXT I 70 NEXT I 80 CLOSE 1 80 CLOSE 1 The two programs are identical except for line 50. In program 1 line 50 accesses the array by row (the row index advances the slowest) while in program 2 line 50 accesses the array by column (the column index advances the slowest). Program 1 will run much faster since it is progressing through the file sequentially, while program 2 is having to randomly thrash about the file which makes it run slower. The second point concerning 2 dimension arrays (which also applies to 1 dimension arrays) is the dimensioning method. Since a virtual array data file is just a collection of data items in the file, one right after the other, the file may be dimensioned in any way desired. It usually only makes sense to dimension the array in the same way it -55 TSC BASIC User's Manual was dimensioned when it was created, but this is not necessary. As an example, suppose a virtual array was created and dimensioned as (50,50). The array would potentially contain (50+1) times (50+1) data items or a total of 2601 elements. Normally, when referencing this array file at a later date, the same dimensioning would be used. We could however, just as easily dimension this existing array file as a single dimension array of 2060 (2061 elements). It could also be dimensioned as a one dimension array containing only 100 items, which would yield the remaining elements inaccessible. 10.6 Extending Virtual Array Disk Files When a random file is created it contains only one usable sector. If a virtual array element is referenced (read) which lies beyond the end of the file, an error number 24 will be issued (non-existent record number referenced). This is similar to an end of file type error with sequential file reading. A random file may be extended in size at anytime by assigning to an array element which lies beyond the end of file. Anytime an extension is necessary, BASIC will extend the file by a few more sectors than actually needed, in anticipation of another extension assignment. File extending can take considerable time and the actual amount of time required is directly proportional to the number of sectors by which the file is being extended. As an example: 10 OPEN NEW "DATA" AS 1 20 DIM #1, A(250) 30 PRINT A(250) will cause an error 24 at line 30 since a new file was just created and no data existed at the element referenced. To make this program run without an error, it is necessary to extend the file before the reference is made. 10 OPEN NEW "DATA" AS 1 20 DIM #1, A(250) 25 A(250)=0 30 PRINT A(250) The addition of line 25 causes the file to immediately be extended to contain all 250 data items. Now line 30 will run without error. It is not necessary to extend a file to its final size before use, but it must be extended to the size necessary to accomodate all data items which will be referenced. All new data items created at the time a file is extended will be zero if the array is floating point, and will be null strings if it is a string array. Remember that the file extending procedure can take a long time to complete. -56 TSC BASIC User's Manual 10.7 Record I/O Up to this point, two methods of disk I/O have been described, sequential I/0 using PRINT # and INPUT #, and virtual arrays for random file access. The sequential I/O is simple and easy to use but restricts data access to sequential methods. Virtual arrays provide high speed random access but do not allow the mixing of ASCII and numeric data in one disk file. There exists a third type of I/O called record I/O. Record I/O is the most flexible form of disk I/O but is also the most complex. Data may be accessed randomly and both ASCII and numeric data may be freely mixed in one disk file. The basic idea behind record I/O is that data is stored on the disk in fixed length records. These records are each 252 bytes or characters in length and reside in one physical disk sector. Any record in a file may be read or written upon request and the data in each record is easily defined to be ASCII or numeric data. Strings may be stored on disk as characters and numbers may be stored in four byte binary form, eliminating the need for I/O conversions. Record I/O is a very efficient method of saving data on a disk file. 10.8 Opening and Closing Record I/O Files Since record I/O files are random files, they are opened and closed exactly like virtual arrays. See section 11.3 for details. It is important to remember that random files are special and may be read in either a random or sequential manner. Sequential files however, may only be read sequentially. An attempt to open a sequential file for random operations will result in error number 48. The user will find the plain OPEN statement (without the NEW or OLD modifier) to be the most useful since it will work with existing files, or create a new file if the file referenced does not exist, without causing an error. Closing a record I/O file is exactly like closing any file and all of the same rules apply, as stated earlier. 10.9 The GET and PUT Statement All record I/O is performed by record (252 byte blocks). Records may be accessed randomly or sequentially. Once a file has been opened on a particular channel, the GET and PUT statements may be used to transfer data to and from the file. Their syntax is: GET # [,RECORD ] PUT # [,RECORD ] -57 TSC BASIC User's Manual The first expression in each line represents the internal channel number referenced in the OPEN statement and must be between 1 and 12. The RECORD portion of each line is optional, and if used, the expression following it designates which record number of the file should be used. If the RECORD option is not specified, the next sequential record will be read or written. The GET statement will read the appropriate record from the disk file into the I/O buffer associated with the channel number used. The PUT statement will write the contents of the I/O buffer to the specified record of the file. Records in a random file are numbered from 1 to n, where n is the size of the file in records. Trying to GET a record which is larger than n will result in an error number 24. Using PUT to write a record which is larger than n will automatically extend the file. There will be more information on disk file extension following. After performing a random access GET or PUT on a disk file, the next GET or PUT channel will access the next sequential record. As an example: on that 10 OPEN "TESTS" AS 2 20 GET #2, RECORD 25 30 PUT #2 The PUT statement in line 30 will write record number file since it is the next sequential after record 25. 26 to the disk 10.10 The FIELD Statement So far, methods of opening and closing record I/O files have been described, as well as methods of reading and writing the I/O buffer associated with the file. This section and the following deal with the manipulation of the data in the I/O buffer. For each record I/O file opened, there exists an I/O buffer designated by the internal channel number used with the OPEN statement. Each I/O buffer is 252 characters in length and is used for temporary storage of each disk file record as it is being operated on. The FIELD statement is used to associate string names with various parts of the I/O buffer. Its syntax is: FIELD #, AS [, AS ...] where the expression designates the internal channel number used in the OPEN statement. Expression 1 is used to designate the length, in characters, of the associated string variable and string var1 is a unique string variable name for this part of the buffer. As many expressions and names as desired may be listed and are associated left to right in the I/O buffer assigned to the channel number referenced. -58 TSC BASIC User's Manual As an example: 100 FIELD #1, 20 AS A$, 10 AS B$, 6 AS W$ A$ B$ W$ 252 byte buffer As shown in the diagram, line 100 would associate the string A$ with the first 20 character positions in the I/O buffer, B$ with the next 10 character positions, and W$ with the next 6 positions. The remaining 216 characters of the buffer are left undefined. The total number of characters positions associated with an I/O buffer must be less than or equal to 252. Each time a FIELD statement is executed, it will start the string association with the first character position in the buffer, regardless of how the buffer has been previously defined with prior FIELD statements. Once a variable name has been fielded by using the FIELD statement, its value will be whatever is currently in the I/O buffer it is associated. If the contents of the buffer change (by executing a GET statement) the contents of the string will also change. The string length will be the length allocated for that string in the FIELD statement. The FIELD statement does not move any data between variables and the I/O buffer but simply sets up a field definition for later use using LSET and RSET. Using a FIELD statement to associate a string variable with an I/O buffer is temporary and the definition is nullified by any attempt to assign a value to the string variable by using implied LET. As an example: LET or the 10 OPEN "TEST" AS 1 20 FIELD #1, 50 AS B$ 30 B$="TEST STRING" Line 30 does not put the string "TEST STRING" into the I/O buffer but instead removes B$'s association with the I/O buffer giving it new storage area for the string. The result is that line 30 nullifies the FIELD definition setup in line 20. It is possible to break the I/O buffer up into several smaller records if a record size of 252 is too large. As an example, suppose that each record of a disk file contains 14 sub-records, each 18 characters long (14 times 18 is 252). Each sub-record is further divided into one 10 character field and one 8 character field. To access the fifth sub-record of the I/O buffer, the following statement could be used: -59 TSC BASIC User's Manual 120 FIELD #1, 72 AS Z$, 10 AS A$, 8 AS B$ Z$ A$ B$ 18 bytes This line would cause A$ and B$ to point to the desired sub-record. The string Z$ is used as a "dummy string". Its purpose is to skip the first four records (4 times 18 is 72). A more general statement may be used which will allow accessing any one of the 14 records in the I/O buffer. 150 FIELD #1, (I-1)*18 AS Z$, 10 AS A$, 8 AS B$ A$(0) B$(0) A$(1) B$(1) A$(2) B$(2) A$(3) B$(3) A$(4) B$(4) Z$ I:1 I:2 I:3 I:4 I:5 When executing the above statement, the variable I should contain the desired sub-record number (a number between 1 and 14). As an example, if I is equal to 3, the dummy string Z$ will be assigned the first 36 character positions, allowing A$ and B$ to point to the third sub-record. If I is 1, A$ and B$ will point to the first sub-record since Z$ was given zero character positions in the buffer. It is also possible to use subscripted string variables in a FIELD statement (except for virtual strings). As an example: 100 DIM A$(13), B$(13) 110 FOR I=0 TO 13 120 FIELD #1, I*18 AS Z$, 10 AS A$(I), 8 AS B$(I) 130 NEXT I A$[0] B$[0] A$[1] B$[1] A$[2] B$[2] A$[3] B$[3] A$[4] B$[4] Z$ This set of statements will associate each element of the string arrays A$ and B$ with a sub-record in the I/O buffer. A$(O) and B$(O) will be associated with the first sub-record, A$(1) and B$(1) with the second, and so on. -60 TSC BASIC User's Manual 10.11 The LSET and RSET Statements The FIELD statement has been used to associate a string with an I/O buffer. Once fielded, the strings contents may be altered by using RSET or LSET. These statements are similar to the LET statement except the string storage location is not changed as it is with LET. The syntax for these two statements is as follows: LSET = RSET = Where string variable represents any legal string variable name, including subscripted variables. These statements store the result of the string expression into the previously defined space, the original string being overwritten. The old length of the string is not changed. If the new string is longer than the old one, the new one will be truncated to the same length as the old. If the new string is shorter, LSET will left justify the string, padding to the right with spaces until the lengths are equal, while RSET will right justify the string, padding with spaces on the left. The normal use of LSET and RSET is with FIELDed string variables but they may also be used with regular strings. They can be used to assign a value to any legal string variable in BASIC, following the above rules for padding and truncation. A short example will demonstrate the record I/O tools described so far. 10 OPEN "DATA5" AS 1 20 FIELD #1, 10 AS A$, 40 AS B$, 70 AS C$ 30 GET #1, RECORD 15 40 PRINT A$ 50 PRINT B$ 60 PRINT C$ 70 LSET A$="NEW A$" 80 LSET B$="NEW VALUE FOR B$" 90 RSET C$="NEW RIGHT JUSTIFIED C$" 100 PUT #1, RECORD 15 110 CLOSE 1 Line 10 opens the file DATA5.DAT on the working drive. Line 20 sets A$, B$, and C$ to the channel 1 I/O buffer. Line 30 reads record number 15 into the I/O buffer. The fielded string variables now contain the values from that record, so the print statements on lines 40 through 60 will print their values. The strings printed reflect what is contained in those character positions of record 15. Lines 70 through 90 assign new values to these strings using LSET and RSET. Remember that the new strings are actually being stored in the I/O buffer. Line 100 writes the I/O buffer back into record number 15 of the data file. If line 100 were omitted from this program, the file would remain unchanged. The file is finally closed in line 110. -61 TSC BASIC User's Manual 10.12 The CVT Conversion Functions The statements described above allow string data to be stored and retrieved from the I/O buffer. It is often desirable to store floating point values in a record I/O file. Two conversion functions exist which allow floating point numbers to be converted to a string and strings to floating point. Examples of each follow: A$ = CVTF$(X) X = CVT$F(A$) The first function maps its floating point argument (variable or expression) into a four character string. Each character in the new string is one of the four bytes of the floating point number (floating point numbers are stored in four bytes internally). The second function does just the opposite. It maps the first four characters of a string into a floating point number. If the string has fewer than four characters, null characters are appended and the resultant floating point number will be 0. These functions should not be confused with the STR$ and VAL functions. The CVT functions provide a compact and fast way of storing numeric data in a record I/O file. As an example, suppose it was necessary to store the items of a floating point array in a record I/O file. The following program demonstrates a way of accomplishing this. 10 DIM A(50), A$(50) 20 OPEN "FPDATA" AS 1 30 FOR I=0 TO 50 40 FIELD #1, 4*I AS D$, 4 AS A$(I) 50 NEXT I . . . 200 FOR I=0 TO 50 210 LSET A$(I) = CVTF$( A(I) ) 220 NEXT I 230 PUT #1 240 CLOSE 1 250 END After the variables are dimensioned and the file is opened, lines 30 through 50 setup the FIELD definition. Each element of the string array A$ is associated with a four byte section of the I/O buffer. It is assumed that the array A is assigned values between lines 50 and 200. Lines 200 through 220 assign the new buffer values by assigning to each element of the previously fielded array A$. Notice that the CVTF$ function is used to store the floating point elements of the array A into the buffer. Line 230 writes the record to the disk file and line 240 closes the file. -62 TSC BASIC User's Manual 10.13 Extending Record I/O Files As stated earlier, a random file is created with only one sector (record). If a GET statement is used to read a record of a file, and the file does not contain that many records, an error number 24 will be issued. This is similar to en end of file error with sequential files. A record I/O file may be extended at anytime by simply using a PUT statement to write a new record which lies beyond the end of the file. Anytime a file is extended, BASIC will extend the file by a few more records than is actually needed. This will speed up future attempts to extend the same file by one or two records. File extending can take a considerable amount of time and is directly proportional to the number of records the file is being increased. As an example: 10 OPEN NEW "TESTD" AS 1 20 FIELD #1, 100 AS G$ 30 GET #1, RECORD 20 Line 30 in the above program will cause an error number 24 since the file opened was just created (OPEN NEW) and only contains one record. To make this program run without an error, it is necessary to extend the file before the reference is made. 10 OPEN NEW "TESTD" AS 1 20 FIELD #1, 100 AS G$ 30 PUT #1, RECORD 20 40 GET #1, RECORD 20 This program will run without error since line 30 extends the file to contain at least 20 records. It is not necessary to extend a file to its final value before use, since it can be extended at anytime, but it must be extended to the size required to accomodate all record references in the program being run. All new records created in a file while the extending process is operating will contain null characters (0's). Keep in mind that the file extension process can take a long time to complete. 10.14 Record I/O Example The following short program demonstrates some of the record I/O statements. It works with an existing employee file which contains information about each employee. Each record of the file contains information about one employee and there are 100 records total. Each employee has a number which corresponds to the record number in the file. This program is used to print a selected employee's phone number and change it if desired. The employee's name is stored in the first 20 characters of each record and the phone number is in character positions 90 through 104. -63 TSC BASIC User's Manual 10 OPEN "EMPLOYEE" AS 1 20 FIELD #1, 20 AS N$, 69 AS D$, 15 AS P$ 30 INPUT "ENTER EMPLOYEE NUMBER",E 40 IF E>10O THEN 30 ELSE IF E<=0 THEN END 50 GET #1, RECORD E 60 PRINT N$,P$ 70 INPUT "CHANGE NUMBER",R$ 80 IF LEFT$(R$)<>"Y" THEN 30 90 INPUT "NEW NUMBER",A$ 100 LSET P$=A$ 110 PUT #1, RECORD E 120 PRINT "NUMBER CHANGED" 130 GOTO 30 Line 10 opens the employee file on channel 1. Line 20 fields the variables such that N$ points to the employee name and P$ points to the phone number. The variable D$ is used as a dummy variable so P$ is positioned correctly in the buffer (we have skipped data in the buffer). Line 30 prompts the user to enter the employee number which should be between 1 and 100. If the number entered is 0 or negative, the program will end. If the number is greater than 100, the user will be prompted for the number again. Line 50 reads in the selected employee record and prints his name and phone number in line 60. If the number does not need changed, the program prompts for another employee number. If it does need changed, line 90 inputs the new number, line 100 puts it in the I/O buffer using LSET, and line 110 writes the updated record back to the disk file. This is a simple program but does demonstrate the versatility of record I/O type operations. -64 TSC BASIC User's Manual 11. THE USR FUNCTION The USR function allows the programmer to call a machine language subroutine. A 16 bit value is passed to the routine and a 16 bit value may be returned to the BASIC program. To save space in memory for a user supplied subroutine, set the memory end pointer to save space between the end of BASIC and the actual end of memory (see Section 15). 11.1 USR FUNCTION FOR 6800 When BASIC encounters a USR function in an expression it evaluates the argument, converts the result to a 16 bit 2's complement integer, and places the result in memory locations hex 26 and 27. Next, BASIC gets a 16 bit address from memory locations hex 24 and 25. This address tells BASIC where the user supplied subroutine is located. If these bytes are zero, an error will be issued. If they are non-zero, a JSR to the address specified will be executed. This address may either be set manually or by using the POKE statement. In the user's routine, it is only necessary to access the locations hex 26 and 27 to retrieve the argument passed from BASIC. To return a value from the subroutine, simply write a 16 bit value into locations hex 26 and 27. When the subroutine is finished, do an RTS to return. It is very important that the executing subroutine returns with the stack pointer at the same location as when it was entered. The subroutine should also not use more than 256 bytes of stack space during execution. After the subroutine returns control to BASIC the USR function call will assume the value returned in locations hex 26 and 27. The following example demonstrates the mechanics of using USR without performing any specific task. 300 POKE HEX("24"),HEX("50") 310 POKE HEX("25"),HEX("0O") 320 A1 = 10 * USR(6) The machine code may look like this: ORG $5000 LDX $0026 GET PASSED ARGUMENT *** ACTUAL CODE HERE LDX #VALUE GET VALUE TO BE RETURNED STX $0026 SAVE FOR BASIC TO USE RTS SHOULD END WITH RTS Lines 300 and 310 in the BASIC code set up the address of the machine language routine ($5000) and puts it in location $24 (the USR vector). Line 320 will pass the value 6 to the machine language routine. After returning from the routine, the value returned will be multiplied by 10 and put in the variable A1. The assembly language code shown demonstrates a method of passing the parameter to and from the user -65 TSC BASIC User's Manual subroutine. 11.2 Calling multiple 6800 USR routines. While there is only one USR command setup in BASIC, there is no reason not to have more than one actual routine. The following hints will show you how to call as many assembly language routines as you want from BASIC. There are two ways to accomplish such a task. The first is to pass a parameter to the USR routine which could be decoded by the actual assembly routine to determine which of any other routines to jump to. The second method, which is much simpler, is to change the USR routine start address as desired. This is done via the POKE command. As an example, let's assume we have two assembly language user routines, one at hex 6E00 and one at hex 6FFO. To call these routines in a row (passing zero parameters to them) we would use the following lines. 190 POKE HEX("24"), HEX("6E") : POKE HEX("25"), HEX("O0") 200 A = USR(O) 210 POKE HEX("24"), HEX("6F") : POKE HEX("25"), HEX("FO") 220 B = USR(O) You might want to consider line 190 as part of the USR call for the routine at $6E00 and line 210 as part of the USR call for $6FFO. In fact it might make sense to put the two steps into a single line using the multiple statements per line character. This is done in the following example. The main purpose of the following example, however, is to show how you might save yourself some typing and chances for mistakes by assigning addresses to variable names. We will setup the address of the USR routine address vector as variables UL and UR (for User vector Left and Right halves) and the various user routines as XL, XR, and YL, YR. The result is as follows. 340 UL = HEX("24") : UR = HEX("25") 350 XL = HEX("6E") : XR = HEX("0O") 360 YL = HEX("6F") : YR = HEX("FO") 370 REM NOW USING MULTIPLE STATEMENTS PER LINE, 380 REM THE CALLS LOOK LIKE THE FOLLOWING. 390 POKE UL,XL : POKE UR,XR : A = USR(O) 400 POKE UL,YL : POKE UR,YR : B = USR(O) You can see that if there were to be many calls to the USR routines this method would make things much simpler and cleaner. -66 TSC BASIC User's Manual 11.3 THE USR FUNCTION FOR 6809 When BASIC encounters a USR function in an expression it evaluates the argument, converts the result to a 16 bit 2's complement integer, and places the result in memory at MEMEND-4. Next, BASIC gets a 16 bit address from memory at MEMEND-2. This address tells BASIC where the user supplied subroutine is located. If these bytes are zero, an error will be issued. If they are non-zero, a JSR to the address specified will be executed. This address may either be set manually or by using the POKE statement. MEMEND represents the FLEX memory end pointer. If memory end is $7FFF, then the USR argument will be at $7FFF-4 or $7FFB, and the USR vector will be at $7FFF-2 or $7FFD. You must know where the FLEX memory end is to use USR! The FLEX memory end is stored at $CC2B and $CC2C. The following explanation assumes a memory end of $7FFF. In the user's routine, it is only necessary to access the locations hex 7FFB and 7FFC to retrieve the argument passed from BASIC. To return a value from the subroutine, simply write a 16 bit value into locations hex 7FFB and 7FFC. When the subroutine is finished, do an RTS to return. It is very important that the executing subroutine returns with the stack pointers at the same location as when it was entered. The subroutine should also not use more than 256 bytes of stack space during execution. After the subroutine returns control to BASIC the USR function call will assume the value returned in locations hex following example demonstrates the mechanics performing any specific task. 7FFB of and using 7FFC. USR without The 300 POKE HEX("7FFD"),HEX("C1") 310 POKE HEX("7FFE"),HEX("OO") 320 A1 = 10 * USR(6) The machine code may look like this: ORG LDX *** LDX STX RTS $C100$7FFB #VALUE $7FFB GET PASSED ARGUMENTACTUAL CODE HEREGET VALUE TO BE RETURNEDSAVE FOR BASIC TO USESHOULD END WITH RTS Lines 300 and 310 in the BASIC code set up the address of the machine language routine ($C1OO) and puts it in location $7FFD (the USR vector). Line 320 will pass the value 6 to the machine language routine. After returning from the routine, the value returned will be multiplied by 10 and put in the variable A1. The assembly language code shown demonstrates a method of passing the parameter to and from the user subroutine. -67 TSC BASIC User's Manual 11.4 Calling multiple 6809 USR routines. While there is only one USR command setup in BASIC, there is no reason not to have more than one actual routine. The following hints will show you how to call as many assembly language routines as you want from BASIC. There are two ways to accomplish such a task. The first is to pass a parameter to the USR routine which could be decoded by the actual assembly routine to determine which of any other routines to jump to. The second method, which is much simpler, is to change the USR routine start address as desired. This is done via the POKE command. As an example, let's assume we have two assembly language user routines, one at hex AEOO and one at hex AFFO. Also assume memory end is at $7FFF as before. To call these routines in a row (passing zero parameters to them) we would use the following lines. 190 POKE HEX("7FFD"), HEX("AE") : POKE HEX("7FFE"), HEX("00") 200 A = USR(O) 210 POKE HEX("7FFD"), HEX("AF") : POKE HEX("7FFE"), HEX("FO") 220 B = USR(0) You might want to consider line 190 as part of the USR call for the routine at $AEOO and line 210 as part of the USR call for $AFFO. In fact it might make sense to put the two steps into a single line using the multiple statements per line character. This is done in the following example. The main purpose of the following example, however, is to show how you might save yourself some typing and chances for mistakes by assigning addresses to variable names. We will setup the address of the USR routine address vector as variables UL and UR (for User vector Left and Right halves) and the various user routines as XL, XR, and YL, YR. The result is as follows. 340 UL = HEX("7FFD") : UR = HEX("7FFE") 350 XL = HEX("AE") : XR = HEX("OO") 360 YL = HEX("AF") : YR = HEX("FO") 370 REM NOW USING MULTIPLE STATEMENTS PER LINE, 380 REM THE CALLS LOOK LIKE THE FOLLOWING. 390 POKE UL,XL : POKE UR,XR : A = USR(O) 400 POKE UL,YL : POKE UR,YR : B = USR(O) You can see that if there were to be many calls to the USR routines this method would make things much simpler and cleaner. -68 TSC BASIC User's Manual 12. ERROR SUMMARY Any time a program that is being executed encounters an error, of any kind, execution will be halted immediately and an ERROR MESSAGE will be printed (except when an ON ERROR is in effect). The message contains an ERROR NUMBER which can be looked up in the following table and also the line number in which the error occurred. The table provides a brief explanation of what type of error the number represents. an error message that you could receive is: An example of ERROR 50 AT LINE 100 Looking in the ERROR TABLE, we see that error number 50 represents an "unrecognizible statement". The message tells us that it occurred at line 100 so we could do a "LIST 100" to display this line and we will more than likely find a typing error in it. The error should be corrected then the program can be run again. All errors are assigned numbers below 100 except the arithmetic errors which range from 101 through 108 and error number 255. Error 255 informs you that an illegal token has been encountered. This error should never be encountered during normal program debugging. Its occurrence indicates the presence of a bad memory location or other serious problems. The errors are divided into two tables. Table one contains all of the I/O related errors and are numbered 1 through 49. It is this set of errors which may be acted upon by using the ON ERROR statement. It should be noted that all errors below error number 30 are FLEX errors and their numbers are identical to the FLEX error numbers. The second error table contains error numbers which are related to syntax or computational type errors. These errors may not be trapped using the ON ERROR statement. -69 TSC BASIC User's Manual I/O RELATED ERRORS (1-49) NUMBER MEANING _______________________________________________________ 1 IILEGAL FMS FUNCTION CODE 2 THE REQUESTED FILE IS IN USE 3 THE FILE ALREADY EXISTS 4 THE FILE COULD NOT BE FOUND 7 ALL DISK SPACE HAS BEEN USED 8 END OF FILE ERROR 9 DISK FILE READ ERROR 10 DISK FILE WRITE ERROR 11 THE FILE OR DISK IS WRITE PROTECTED 12 THE FILE IS PROTECTED 15 ILLEGAL DRIVE NUMBER SPECIFIED 16 DRIVES NOT READY 21 ILLEGAL FILE SPECIFICATION 22 FILE CLOSE ERROR 23 SECTOR MAP OVERFLOW 24 NON-EXISTENT RECORD NUMBER SPECIFIED 25 RECORD NUMBER MATCH ERROR - FILE DAMAGED 26 FLEX COMMAND ERROR 30 DATA TYPE MISMATCH 31 OUT OF DATA IN "READ" 32 BAD ARGUMENT IN "ON" STATEMENT 40 BAD FILE NUMBER USED 41 FILE ALREADY OPEN 42 MUST OPEN FILE AS "NEW" OR "OLD" 43 FILE HAS NOT BEEN OPENED 44 FILE STATUS ERROR 45 FIELD SIZE TOO LARGE (>252) 46 CAN'T EXTEND A SEQUENTIAL FILE 47 RECORD 0 NOT ALLOWED 48 MUST USE RANDOM TYPE FILE -70 TSC BASIC User's Manual SYNTAX AND COMPUTATIONAL ERRORS (50-255) NUMBER MEANING _______________________________________________________ 50 UNRECOGNIZABLE STATEMENT 51 ILLEGAL CHARACTER IN LINE 52 SYNTAX ERROR 53 ILLEGAL LINE TERMINATION 54 LINE NUMBER 0 NOT ALLOWED 55 UNBALANCED PARENTHESES 56 ILLEGAL FUNCTION REFERENCE 57 MISSING QUOTE IN STRING CONSTANT 58 MISSING "THEN" IN AN "IF" STATEMENT 60 BAD LINE REFERENCE IN "GOTO" OR "GOSUB" 61 RETURN WITHOUT "GOSUB" 62 "FOR-NEXT" NEST ERROR 63 CAN'T CONTINUE 64 SOURCE NOT PRESENT 65 BAD FILE - WON'T LOAD 66 "RESUME" NOT IN ERROR ROUTINE 72 MIXED MODE ERROR 73 ILLEGAL EXPRESSION 74 ARGUMENT <0 OR >255 75 ARGUMENT >32,767 76 ILLEGAL VARIABLE TYPE 77 ARRAY REFERENCE OUT OF RANGE 78 UNDIMENSIONED ARRAY REFERENCE 80 MEMORY OVERFLOW 81 ARRAY OVERFLOW 83 STRING TOO LONG 90 UNDEFINED USER FUNCTION 91 UNDEFINED USER CALL 94 BAD STRING LENGTH SPECIFIED 95 MULTIPLE VIRTUAL ARRAY REFERENCE 100 EXPRESSION TOO COMPLEX 101 OVERFLOW OR UNDERFLOW IN FLOATING POINT OP. 102 ARGUMENT TOO LARGE 103 DIVISION BY ZERO 104 NUMBER TOO LARGE TO CONVERT TO INTEGER 105 NEGATIVE OR ZERO ARGUMENT FOR "LOG" 106 CONVERSION ERROR IN INTEGER "INPUT" 107 IMAGINARY SQUARE ROOT 108 CONVERSION ERROR (NUMBER TOO LARGE) 255 ILLEGAL TOKEN ENCOUNTERED -71 TSC BASIC User's Manual 13. GETTING BASIC RUNNING Before BASIC can be run, FLEX should be running and the three plus sign prompt (+++) should be present. Insert the disk containing BASIC into the system drive and type BASIC. After a few seconds, BASIC should respond with "READY". BASIC is ready to go at this time. If BASIC is ever left by using RESET or the EXIT command, the WARM start entry point should be used. Entry at COLD start will clear out any program you may have entered while entry at WARM start will preserve it. There is an alternative way of calling BASIC from FLEX. It has the following form: +++BASIC, where is the name of a BASIC program. If this name is supplied on the calling line, once FLEX has loaded BASIC, BASIC will load and execute the program named. The file name defaults to the working drive but may be over-ridden in the file spec. The extension defaults to BAC for a BASIC compiled type program. A BAS extension may be specified with the file name which will allow BASIC to load a BASIC source type file and execute it. This mechanism may be used in the STARTUP file in FLEX so BASIC will load and execute a program when your disk is booted! 14. RENUMBER BASIC does not contain an internal renumbering routine but does contain a disk resident one. To use it you must be in BASIC and have the program you want renumbered in memory. To initiate the renumbering process, type the following: +RENUMBER,<1st Line>, where the + sign tells BASIC to send the following command to FLEX which gets the renumber command. The first number represents the number which should be assigned to the first line of the program. The increment indicates what value should be added to each successive line. Both of these values default to 10 if no numbers are specified. For example: +RENUMBER +RENUMBER,100,20 The first example will renumber the program with line number increments of 10 and the first line number will be 10. The second line will renumber it with the first line being 100 and a line increment of 20. Long source files may require a long time to renumber. -72 TSC BASIC User's Manual 15. ADAPTING TO YOUR SYSTEM There are several key locations in BASIC which will help you adapt it to your particular hardware configuration. 15.1 ADAPTING TO YOUR 6800 SYSTEM If you are running a 6800 system, which has 20K of memory starting at location 0, has an ACIA for terminal I/O at location hex 8004, and is using FLEX, no adaptions need be performed. It is recommended that this section is read whether or not it is necessary to make adaptions since other useful information is contained. After making any necessary changes, save BASIC back onto disk from location hex 20 through hex 35FF. The transfer address should be hex 100. 15.2 User Noted Storage for 6800 MEMEND $20-21. These two bytes specify to BASIC what the end of memory should be. As BASIC is distributed, this location is set to $4FFF, or for a 20K system. If more memory is installed in your computer, set these bytes accordingly. It may be desirable to set these lower than the actual end of memory to save space for a USER supplied subroutine to be called with the USR function. ACIA $22-23. These bytes contain the base location of the ACIA being used for terminal I/O. If yours is different from $8004, set accordingly. This location is used by the routine which tests for a control C. If your system does not use an ACIA for terminal input, see section 15.4 below. COLD $100. This is the cold start address used to initialize BASIC when first bringing up BASIC. WARM $103. This is the warm start address normally used to enter BASIC after doing an EXIT or FLEX command. It preserves any program currently in BASIC, and consequently does not reset the stack pointer on re-entry. If the stack pointer has been changed since exiting BASIC, unexpected results can occur. -73 TSC BASIC User's Manual 15.3 Input Output Vectors for 6800 The following addresses specify the locations of various jump vectors used in conjuction with I/O. The addresses specify the first byte of a three byte group. The first byte is always a $7E (JMP instruction) and should not be changed. The following 2 bytes are the actual address of the routine referenced. You may change these accordingly. If you substitute your own routines for any of the following, they should be written as subroutines and end with an RTS instruction. EXIT $106. This is used by BASIC when the EXIT command is typed and should be set to jump to the entry point in the monitor ROM being used. It is currently $EODO for MIKBUG compatibility. INCH $109. This vectors to FLEX's input routine. Change this vector to use your own input routine. Note that all registers should be preserved with the input character being returned in the A register with the parity removed. OUTCH $1OF. This vectors to FLEX's output routine. If you vector to your own routine, it should preserve all registers and output the character in A. 15.4 User Supplied Break Routine for 6800 If your system does not use an ACIA for terminal input, you will need to supply a routine which checks to see if a character has been received from the keyboard. If you do not need the control C break capability, set the ACIA address described above to point to a zero byte in ROM. This will disable this feature. The user supplied routine should check if a key has been typed, and return the zero status bit cleared (NE status) if so. The character should not be input! Make the following patches: at $0202 put BD O1 09 O1 at $0253 put BD xx xx O1 at $02B4 put BD xx xx O1 where 'xx xx' represents the address of your check key typed routine. -74 TSC BASIC User's Manual 15.5 ADAPTING TO YOUR 6809 SYSTEM There are several key locations in BASIC which will help you adapt it to your particular hardware configuration. If you are running a 6809 system which has an ACIA for terminal I/O at location hex E004, no adaptions need be performed. It is recommended that this section is read whether or not it is necessary to make adaptions since other useful information is contained. After making any necessary changes, save BASIC back onto disk from location hex 0 through hex 35FF. The transfer address should be hex 0000. 15.6 User Noted Storage for 6809 MEMEND $CC2B-CC2C. These two bytes specify to BASIC what the end of memory should be. These bytes are part of the FLEX operating system and are set by FLEX. These may be changed by the user if so desired (to a lower value only). It may be desirable to set these lower than the actual end of memory to save space for a USER supplied subroutine to be called with the USR function. If the memory end is changed, you must enter BASIC through the cold start entry point at location 0. Entry through warm start after changing memory end will cause program errors. ACIA $4B-4C. These bytes contain the base location of the ACIA being used for terminal I/O. If yours is different from $E004, set accordingly. This location is used by the routine which tests for a control C. If your system does not use an ACIA for terminal input, see section 15.8 below. After changing these bytes, the cold start entry point should be used (location 0). COLD $0000. This is the cold start address used to initialize BASIC when first bringing up BASIC. WARM $0003. This is the warm start address normally used to enter BASIC after doing an EXIT or FLEX command. It preserves any program currently in BASIC. -75 TSC BASIC User's Manual 15.7 Input Output Vectors for 6809 The following addresses specify the locations of various jump vectors used in conjuction with I/O. The addresses specify the first byte of a three byte group. The first byte is always a $7E (JMP instruction) and should not be changed. The following 2 bytes are the actual address of the routine referenced. You may change these accordingly. If you substitute your own routines for any of the following, they should be written as subroutines and end with an RTS instruction. EXIT $0006. This is used by BASIC when the EXIT command is typed and should be set to jump to the entry point in the monitor ROM being used. It is currently $F814, the SBUG entry point. INCH $OOOC. This vectors to FLEX's input routine. Change this vector to use your own input routine. Note that all registers should be preserved with the input character being returned in the A register with the parity removed. OUTCH $0012. This vectors to FLEX's output rou to your own routine, it should preserve output the character in A. tine. all If you veregisters ctorand 15.8 User Supplied Break Routine for 6809 If your system does not use an ACIA for terminal input, you will need to supply a routine which checks to see if a character has been received from the keyboard. If you do not need the control C break capability, set the ACIA address described above to point to a zero byte in ROM. This will disable this feature. The user supplied routine should check if a key has been typed, and return the zero status bit cleared (NE status) if so. The character should not be input! Make the following patches: at $0162 put BD OO OC 12 at $O1BA put BD xx xx 12 12 at $0212 put BD xx xx 12 12 where 'xx xx' represents the address of your check key typed routine. -76 TSC BASIC User's Manual 16. ASCII CHARACTER CHART CHARACTER HEXADECIMALDECIMAL CHARACTERHEXADECIMALDECIMAL CHARACTERHEXADECIMALDECIMAL NUL 00 000 + 2B 043 V 56 086 SOH O1 001 , 2C 044 W 57 087 STX 02 002 -2D 045 X 58 088 ETX 03 003 . 2E 046 Y 59 089 EOT 04 004 / 2F 047 Z 5A 090 END O5 005 0 30 048 ( 5B 091 ACK 06 006 1 31 049 \ 5C 092 BEL 07 007 2 32 050 ) 5D 093 BS 08 008 3 33 051 ^ 5E 094 HT 09 009 4 34 052 _ 5F 095 LF OA 010 5 35 053 ` 60 096 VT OB 011 6 36 054 a 61 097 FF OC 012 7 37 055 b 62 098 CR OD 013 8 38 056 c 63 099 SO OE 014 9 39 057 d 64 100 SI OF 015 : 3A 058 e 65 101 DLE 10 016 ; 38 059 f 66 102 DC1 11 017 , 3C 060 g 67 103 DC2 12 018 = 3D 061 h 68 104 DC3 13 019 > 3E 062 i 69 105 DC4 14 020 ? 3F 063 j 6A 106 NAK 15 021 @ 40 064 k 6B 107 SYN 16 022 A 41 065 l 6C 108 ETB 17 023 B 42 066 m 6D 109 CAN 18 024 C 43 067 n 6E 110 EM 19 025 D 44 068 o 6F 111 SUB 1A 026 E 45 069 p 70 112 ESC 1B 027 F 46 070 q 71 113 FS 1C 028 G 47 071 r 72 114 GS 1D 029 H 48 072 s 73 115 RS 1E 030 I 49 073 t 74 116 US 1F 031 J 4A 074 u 75 117 SP 20 032 K 48 075 v 76 118 ! 21 033 L 4C 076 w 77 119 " 22 034 M 4D 077 x 78 120 # 23 035 N 4E 078 y 79 121 $ 24 036 0 4F 079 z 7A 122 % 25 037 P 50 080 { 78 123 & 26 038 Q 51 081 / 7C 124 ' 27 039 R 52 082 } 7D 125 ( 28 040 S 53 083 ~ 7E 126 ) 29 041 T 54 084 DEL 7F 127 * 2A 042 U 55 085 -77 TSC BASIC User's Manual 17. INDEX TO STATEMENTS AND COMMANDS STATEMENTS NAME SECTION CHAIN 8.9 CLOSE 8.4 DATA 6.1 DEF 6.7 DIM 6.7 END 6.6 EXEC 10.1 FIELD 10.10 FOR 6.5 GET 10.9 GOSUB 6.2 GOTO 6.2 IF 6.3 INPUT 6.4 INPUT LINE 6.4 KILL 8.7 LET 6.1 LSET 10.11 NEXT 6.5 ON ERROR 6.2 ON GOSUB 6.2 ON GOTO 6.2 OPEN 8.1 10.3 POKE 6.7 PRINT 6.4 PUT 10.9 READ 6.1 REM 6.7 RENAME 8.8 RESTORE 6.1 RESUME 6.2 RETURN 6.2 RSET 10.11 STOP 6.6 COMMANDS NAME SECTION "+" 5.0CLEAR 5.0 COMPILE 5.0CONT 5.0EXIT 5.0FLEX 5.0LIST 5.0LOAD 5.0NEW 5.0RUN 5.0SAVE 5.0FUNCTIONSNAME SECTIONABS 7.5ASC 7.3ATN 7.2CHR$ 7.3COS 7.2CVT$F 10.12CVTF$ 10.12ERL 9.3ERR 9.3EXP 7.1HEX 7.3INT 7.5LEFT$ 7.3LEN 7.3LOG 7.1MID$ 7.3PEEK 7.4PI 7.5POS 7.4PTR 7.5 RIGHT$ 7.3 RND 7.5 SGN 7.5 SIN 7.2 SPC 7.4 SQR 7.1 STR$ 7.3 TAB 7.4 TAN 7.2 VAL 7.3 -78