MicroBASIC A tiny BASIC for the 6809 Revised: 02-Dec-05 Dunfield Development Systems ---------------------------- High quality tools for Embedded Development at low prices. https://dunfield.themindfactory.com Copyright 1982-2005 Dave Dunfield All rights Reserved MicroBASIC USERS GUIDE TABLE OF CONTENTS Page 1. INTRODUCTION 1 1.1 Command syntax 1 1.2 Interactive mode 1 1.3 Program editing 1 2. LANGUAGE SUMMARY 2 2.1 Numbers 2 2.2 Character strings 2 2.3 Variables 2 2.4 Functions 3 2.5 Operators 4 2.6 Statements 5 3. Error Messages 13 3.1 Illegal program error 13 3.2 Illegal direct error 13 3.3 Syntax error 13 3.4 Line number error 13 3.5 Wrong type error 13 3.6 Divide by zero error 13 3.7 Nesting error 13 3.8 File not open error 13 3.9 File already open error 13 3.10 Input error 13 3.11 Dimension error 14 3.12 Data error 14 3.13 Out of memory error 14 4. Control-C 14 MicroBASIC USERS GUIDE Page: 1 1. INTRODUCTION MicroBASIC is tiny interpreter for the BASIC computer languag, which runs on the 6809 under CUBIX. 1.1 Command syntax To launch BASIC, simply type BASIC at the CUBIX command prompt. You may also specify a program name on the command line, which will cause MicroBASIC to automatically load the .BAS program file with that name and run it. *BASIC MYPROG 1.2 Interactive mode When MicroBASIC issues the 'Ready' prompt, it is waiting for a command. Most BASIC statements can be executed as an interactive command. 1.3 Program editing Entering a command beginning with a number will perform program editing. Any existing line in the program with the same line number will be replaced by the command line. If the line number does not exist in the program, the new line will be added to the program. If you enter a command containing a number only, that line from the program will be deleted. MicroBASIC USERS GUIDE Page: 2 2. LANGUAGE SUMMARY 2.1 Numbers MicroBASIC uses "16 bit integer" numbers. This means that any numeric values used in a program must fall in the range of -32768 to 32767. Within expressions, numbers can be expressed in hexidecimal by preceeding them with '$'. 2.2 Character strings MicroBASIC can also manipulate character strings. Character strings are identified by the double-quote (") character, and are limited to 100 characters or less in length. 2.3 Variables MicroBASIC provides a total of 780 "variables" which may be used to store numbers and character strings. These are divided into three "types" of 260 variables each. The variables of each type are identified with a single character from the alphabet followed by digit from 0 to 9; ie: A0-Z9. 2.3.1 Simple numeric variables: A0 - Z9 These variables are the most commonly used, and can each store one number (-32768 to 32767). They are used for loop counters, input values, and general purpose calculations. 2.3.2 String variables: A0$ - Z9$ These variables can hold character strings. These "string" variables are identified by a '$' appended to the name. They are normally used for input strings, names, and any other non-numeric data. String variables allow indexing to extract individual characters: A0$(n) = Return character n (0 to length-1) 2.3.3 Numeric arrays: A0(index) - Z9(index) These variables can each hold multiple numbers. Unlike the others, variables of this type must be explicitly created (with the 'DIM' statement). They are typically used for tables, lists and any applications which use a group of numbers. As a matter of convience, the '0' variables can be referenced by letter only. Ie: A is equivalent to A0, B$ is equivalent to B0$, and Z(index) is equivalent to Z0(index) MicroBASIC USERS GUIDE Page: 3 2.4 Functions MicroBASIC includes a number of "built in" functions which can be used as values in an expression: 2.4.1 CHR$(value) Converts a number into an ASCII character. For example: the ASCII value of the character 'A' is 65. Coding CHR$(65) would be equivalent to "A". This is the reverse of the ASC() function. 2.4.2 STR$(value) Converts a number into a character string. Coding STR$(1234) would be equivalent to "1234". This is reverse of the NUM() function. 2.4.3 ABS(value) Returns the "absolute value" of a number, which a number of the same magnitude, with a positive sign. For example: ABS(5) and ABS(-5) would both evaluate to a number of 5. 2.4.4 ASC(char) Converts a character into its numeric ASCII value. For example: coding ASC("A") would be equivalent to 65. This is the reverse of the CHR$() function. 2.4.5 PEEK(address) Reads a byte of memory at the absolute address given. 2.4.6 KEY() Tests to see if a key has been pressed on the PC keyboard and if so, returns its ASCII value. If no key has been pressed, KEY() returns 0. 2.4.7 LEN(variable) Returns the length of the specified string or array variable. If the variable has a '$' suffix, the length return is the number of characters in the character variable. If no '$', the length returned is the number of elements in the array variable. 2.4.8 NUM(string) Converts a character string containing a number into a numeric value. Coding NUM("1234") would be equivalent to 1234. This is the reverse of the STR$() function. MicroBASIC USERS GUIDE Page: 4 2.4.9 RND(value) Generates a "random" number which will fall in the range of 0 to (value-1). For example: RND(10) would generate a number ranging from 0 to 9. 2.4.10 USR(address[,parm1...]) Calls a machine language subroutine at the specified address. When the subroutine is called, the 6809 'X' register will point to the top of a stack frame containing any parameters which were passed. If a character string is passed, the stack value contains the address of the MicroBASIC internal buffer where the string is stored (NOTE: Only ONE character string may occur in the parameter list). The value returned by the USR function is the value of the 6809 16 bit accumulator (A:B) when the subroutine returns. ; Example machine language subroutine two add two numbers ADD2 LDD ,--X ; Get first parameter ADDD ,--X ; Add second parameter RTS ; Return with value All 6809 registers (except SP) may be modified by the subroutine. 2.5 Operators Numbers, Strings, Variables and Function may be formed into expressions and manipulated with the following operators: + Addition and String concatination ($) - Subtraction * Multiplication / Division % Modulus (remainder) & Bitwise AND | Bitwise OR ^ Bitwise EXCLUSIVE OR = Assignment / Test EQUAL ($) <> Test NOT EQUAL ($) < Test LESS THAN <= Test LESS THAN or EQUAL > Test GREATER THAN >= Test GREATER THAN or EQUAL ! Bitwise NOT (complement) Operators denoted with ($) can be applied to strings. When applied to strings, '+' performs string concatination, which is the operation of joining two strings into one. For example: "ABC"+"DEF" is equivalent to "ABCDEF". The "test" operators (=, <>, <, <=, >, >=) can be used in any expression, and evaluate to 1 of the test is TRUE, and 0 if it is FALSE. MicroBASIC USERS GUIDE Page: 5 2.6 Statements All actions performed by the MicroBASIC program are coded as "statements", which are commands directing the interpreter. Statements often contain expressions as described above to perform calculations. Most statements can be used either from within a program, or interactively from the command line "Ready" prompt. Those statements which are only available in one or the other mode are noted. 2.6.1 CLEAR Erases all variables. All numeric variables are set to zero. All string variables are set to null (0 length), and all arrays are removed. 10 REM clear all variables 20 CLEAR 2.6.2 CLOSE#unit Closes a previously opened file (0-9). See 'OPEN#unit'. 10 REM Close file # 5 20 CLOSE#5 2.6.3 DATA Codes numeric and string data in the program text such that it can be read with the READ statement. See 'READ' and 'ORDER'. DATA statements encountered during the normal flow of the program are ignored. They are only used as sources of data for the READ statement. DATA can only be used within a program (non-interactive). 10 REM Data for READ 20 DATA 1,2,3,"text" 30 DATA 4,5,6,"more text" MicroBASIC USERS GUIDE Page: 6 2.6.4 DIM variable(size)[, ...] This command "dimensions" (creates) a numeric array variable. The size parameter defines the maximum index value which can be used with the array. If an array of the same name was previously defined, it is erased first. All elements of the new array are set to zero. Note that MicroBASIC starts numbering its elements from 0, while most other BASIC's start numbering elements from 1. 10 REM Define arrays 11 elements (0-10) and 100 elements 20 DIM A(10), A1(99) 2.6.5 END Terminate execution of the program. No message is issued. 10 REM End program quietly 20 END 2.6.6 EXIT Terminates MicroBASIC and exits back to DOS. 10 REM Terminate MicroBASIC 20 EXIT 2.6.7 FOR variable=value TO limit [STEP increment] Begins a counted loop. The variable begins with the specified value. The program segment between FOR and a corresponding NEXT statement is repeated until the variable exceeds the specified limit. After each loop, the variable is incremented by the increment value. If no increment value is specified, a default value of 1 is used. FOR can only be used within a program (non-interactive). 10 REM Count to 10 and print it 20 FOR i=1 to 10 30 PRINT I 40 NEXT I MicroBASIC USERS GUIDE Page: 7 2.6.8 GOSUB line Calls a subroutine. The program segment beginning at the specified line number is executed until a RETURN statement is encountered, after which the program continues at the next statement after GOSUB. GOSUB can only be used within a program (non-interactive). 10 REM Call a subroutine 20 PRINT "start" 30 GOSUB 80 40 PRINT "middle" 50 GOSUB 80 60 PRINT "end" 70 END 80 PRINT "subroutine" 90 RETURN 2.6.9 GOTO line Causes a "jump" to the specified line number. The program will continue at the first statement in the indicated line. GOTO can only be used within a program (non-interactive). 10 REM goto example 20 PRINT "Hello" 30 GOTO 20 2.6.10 IF test THEN statement/line Performs a statement conditionaly upon a test. The indicated test expression is evaluated, and if the result is non-zero, the specified statement is performed. As a shorthand convienece, a statement consisting of only a number is assumed to be "GOTO number". 10 REM IF example 20 FOR i=1 TO 10 30 IF i=5 THEN PRINT "I is five" 40 IF i<>8 THEN 60 50 PRINT "I is eight" 60 NEXT i MicroBASIC USERS GUIDE Page: 8 2.6.11 INPUT ["prompt",]variable Prompts for a variable. The specified prompt is displayed, and a single line of input is accepted from the console, which is assigned to the indicated variable. String variables receive the input unchanged. Numeric variables cause the input line to be evaluated to a number. If no "prompt" string is given, a default of "?" is assumed. Note that you cannot directly use a character variable as the prompt (Input assumes that you are inputting into the variable), but you can use one concatinated to a string. 10 REM INPUT example 20 INPUT A 30 PRINT "A=",A 40 INPUT A$ 50 INPUT ""+A$,B 60 PRINT "B=",B 2.6.12 INPUT#unit,variable Reads the contents of a variable from a file previously opened with OPEN#unit. 10 REM open example 20 OPEN#1,"TEST.FIL","r" 30 INPUT#1,A$ 40 CLOSE#1 50 PRINT "A$=",A$ 2.6.13 LET variable = expression Assigns the value of the expression to the specified variable. The "LET" keyword is optional, since the interpreter will assume LET for any statement which it does not recognize. 10 REM LET example 20 LET a=10 30 A$="test string" 2.6.14 LIF test THEN statements Performs a "long IF". This statement behaves exactly like the IF statement, except that ALL statements on the line are conditional on the test. 10 REM IF/LIF example 20 INPUT "Enter a number?",A 30 IF A = 1 THEN PRINT "A=1" : PRINT "TEST1" 40 LIF A = 2 THEN PRINT "A=2" : PRINT "TEST2" 50 IF A<>0 THEN 20 MicroBASIC USERS GUIDE Page: 9 2.6.15 LIST [start,[end]] Displays the program on the console. If one line number is given, only that line is listed. If both start and end lines are given, only that range is listed. LIST LIST 10 LIST 10,50 2.6.16 LIST#unit[,start,[end]] Behaves exactly like LIST except that the program is written to a previously opened file (0-9). 10 REM List to file demo 20 OPEN#1,"PGM.BAS","wv" 30 LIST#1,100,200 40 CLOSE#1 2.6.17 LOAD "file" Loads the specified MicroBASIC program file into memory. Any previous program is erased. The extension ".BAS" is assumed. When used interactively, all variables are erased prior to loading the new program. When used within a program, LOAD performs a "chaining" function. The new program is loaded, and immediately begins to run. In this case, the variables are NOT erased, and may be used as a means of communication between the two programs. NOTE: If you do not need to pass variables to a chained program, it is a good idea to execute CLEAR just prior to LOAD. This makes it easier for MicroBASIC to manage memory, and also insures that the new program will start with a clean set of variables. LOAD "program" 10 REM LOAD demo 20 CLEAR 30 A$="String to pass" 40 LOAD "next" 2.6.18 NEW Erases the program and all variables. NEW MicroBASIC USERS GUIDE Page: 10 2.6.19 NEXT [variable] Terminates a FOR loop (see FOR). If a variable is specified it must match the one in the corresponding FOR statement. NEXT can only be used within a program (non-interactive). 10 REM FOR/NEXT demo 20 FOR i=1 TO 100 STEP 2 30 PRINT I 40 NEXT 2.6.20 OPEN#unit,"filename",R|W] Opens a file for subsequent 'R'ead or 'W'rite 10 REM OPEN/PRINT to file 20 OPEN#1,"test.fil",W 30 PRINT#1,"This is a test" 40 CLOSE#1 50 REM OPEN/INPUT from file 60 OPEN#2,"test.fil",R 70 INPUT#2,A$ 80 PRINT "A$=",A$ 90 CLOSE#2 2.6.21 OPEN#unit,"*device" Opens a CUBIX serial device for I/O. 10 REM OPEN/READ/WRITE device 2 20 OPEN#1,"*2" 30 INPUT#1,A$ 40 PRINT#1,"STRING=",A$ 50 CLOSE#1 2.6.22 ORDER line Positions the DATA/READ pointer to a specific line. The line MUST begin with a DATA statement. This command must be given before a READ statement can be used at the beginning of a program, and again after all data has been read from a data block. Once the data pointer has been set, READ will automatically accept data from multiple DATA statements, but it will not automatically skip over non-DATA statements. 10 REM ORDER/DATA demo 20 ORDER 30 30 DATA 1,9,2,8,3 40 DATA 7,4,6,5,0 50 PRINT "Nothing much happening yet" MicroBASIC USERS GUIDE Page: 11 2.6.23 POKE address,value Writes a byte value to the specified memory address. 10 REM Zero LPT data port 20 POKE 10,0 2.6.24 PRINT expression[,expression][,] Prints the values of expressions on the console. Either numeric values or character strings may be printed. Unless a trailing ',' is supplied, PRINT will output a Line-feed/Carriage-return to reposition output to a new line after the expressions are printed. NOTE: Print automatically preceeds numbers with a space, however it does no such special processing for character strings. The STR$ function can be used to convert a number into a string and avoid this space. 10 REM PRINT demo 20 FOR i=0 TO 10 30 PRINT "I=",i,"!" 40 PRINT "I=",STR$(i),"!" 50 NEXT I 2.6.25 PRINT#unit,expression[,expression], Behaves exactly like the PRINT command above except that the output is directed to a previously opened file. 10 REM PRINT#unit demo 20 OPEN#1,"TEST.FIL",W 30 FOR i=0 TO 10 40 PRINT#1,"I=",I 50 NEXT I 60 CLOSE#1 2.6.26 READ variable[,variable ...] Reads data into a variable from DATA statements in the program. An ORDER statement must be used to set the data pointer before READ can be used. 10 REM ORDER/READ/DATA demo 20 ORDER 60 30 READ A 40 PRINT "A=",A 50 IF A <> 0 THEN 30 60 DATA 1,9,2,8,3 70 DATA 7,4,6,5,0 MicroBASIC USERS GUIDE Page: 12 2.6.27 RETURN Returns program execution from a subroutine to the statement immediately following the GOSUB that invoked the subroutine. RETURN can only be used within a program (non-interactive). 10 REM Call a subroutine 20 PRINT "start" 30 GOSUB 80 40 PRINT "middle" 50 GOSUB 80 60 PRINT "end" 70 END 80 PRINT "subroutine" 90 RETURN 2.6.28 REM Inserts a comment in the program. The remainder of the line is ignored by the interpreter. Execution continues on the next line. 10 REM this is a comment 2.6.29 RUN [line] Starts the program executing. All user variables are cleared first. If a line number is specified then the program will be started at that line, otherwise execution begins on the first line of the program. RUN can only be used from the interactive command line (non-program) RUN 2.6.30 SAVE "name" Saves the program in the specified file. SAVE can only be used from the interactive command line (non-program). SAVE "test" 2.6.31 STOP Terminate execution of the program with an informational message. 10 REM End program with an announcement 20 STOP MicroBASIC USERS GUIDE Page: 13 3. Error Messages The following error messages are produced by MicroBASIC. If the error occurs during the execution of a program, it will be followed by "in line n" where n is the offending line unmber. 3.1 Illegal program error Results from an attempt to use a statement within a program which is only allowed as an interactive command. 3.2 Illegal direct error Results from an attempt to use a statement as an interactve command which is only available within a program. 3.3 Syntax error Results from any statement which does not follow the MicroBASIC syntax rules. 3.4 Line number error Results from an attempt to reference a line number which does not exist 3.5 Wrong type error Results from an attempt to use a value in a context where a different type (number or string) is expected. 3.6 Divide by zero error Results from an attempt to perform division by zero. 3.7 Nesting error Results from incorrect nesting of FOR/NEXT of GOSUB/RETURN constructs, or from overflow of the internal control stack which manages these constructs. 3.8 File not open error Results from an attempt to perform I/O to a unit number that does not have a corresponding open file. 3.9 File already open error Results from an attempt to open a file using a unit number that already has a corresponding file opened. 3.10 Input error Results an incorrect numeric entry in response to an input request for a numeric variable. MicroBASIC USERS GUIDE Page: 14 3.11 Dimension error Results from an attempt to access a numeric array that has not been defined, or use of an index value that is outside of the range declared for the array. 3.12 Data error Results from attempt to READ when the data pointer does not point to a data statement containing the correct data type for the variable you are attempting to use. 3.13 Out of memory error Results when MicroBASIC's available memory pool has been used up. Available memory is depleted by program lines, character strings, and numeric arrays. 4. Control-C MicroBASIC uses the keyboard Ctrl-C character (Press 'C' while holding CTRL) to signal an ABORT condition. MicroBASIC will stop it's current activity and return to the interactive prompt as quickly as possible when this key combination is detected.