BASIC-E DOCUMENTATION ===================== The EBASIC compiler system is an early two-step BASIC compiler and interpreter now available as a public-domain system under CP/M. More elaborate proprietary versions of EBASIC are marketed under the name CBASIC, with CBASIC2 being the latest version. This EBASIC can be obtained from Heath User's Group as well as the SIG/M library. Our interest in EBASIC is (1) it is in public domain and (2) it is a compiled language. This last means that programs can be presented in a way that aids comprehension and understanding, since there is no space penalty -- the comments, blank lines, and other pleasantries are removed by the compiler. WRITING SOURCE CODE Source code for EBASIC programs must be writtem with a text editor. Spaces and tabs may be used freely in a program to make it more readable, and will have no effect on the size of the compiler output file. Upper or lower case letters may be used, and the compiler will normally translate lower case key words to upper case for syntax checking. File names should be in upper case. STATEMENT NUMBERS Line numbers in EBASIC are optional, and serve only as labels referenced by GOTO, GOSUB, etc. They take from 2 to 32 digits, and need not be in ascending order, so long as unique. Line nos. are ignored by the compiler if they are not referenced. Line number 00 is not allowed. CONTINUATION AND MULTIPLE LINES EBASIC allows multiple statements on a line (separated by co- lons) with the following exceptions. IF (with THEN and ELSE), IF END, DEF, DIM, and END must be the first and only instruction on a line. INPUT and REM must be the last instruction on a line. The backslash (\) may be used to break up a logical line into several physical lines, as in this example. IF GAME.END=0 \ THEN PRINT "THIS IS THE END" \ ELSE PRINT "KEEP GOING" EBASIC LANGUAGE SUMMARY ======================== VARIABLE NAMES Variable names may be one to 32 characters long, consisting of letters, digits, or periods. The initial character must be a letter. The final character must be "$" if, and only, if the variable is a string name. Undefinded numeric variables are zero, and undefined strings are null. DATA TYPES Data types are Numeric, String and Logical. Numbers are floating point with six significant figures and E notation for very large or small numbers. The range allowed is 2.7 E-39 to 3.6 E+38. Strings may be one to 255 characters long. Logicals are 0 (false) and -1 (true). ARRAYS Arrays can have many dimensions, with subscripts rounded to the nearest integer. The implied lower limit of a subscript is zero. DIM is used to reserve space (from 0 to the given size). ASSIGNMENT OR REPLACEMENT To assign a value to a variable, use = or LET = where is any variable reference is an expression that is evaluated to the value assigned to OPERATORS EBASIC provides Arithmetic, Relational, and Logical operators, as listed below. OPERATOR OPERATION USAGE -------- --------- ----- ARITHMETIC OPERATORS (Numeric expression only) ^ Exponentiation Powers or roots - Unary minus Negates following number * Multiplication / Division Arithmetic quotient + Addition Also string concatenation - Subtraction RELATIONAL OPERATORS (Strings or numbers) < or LT Less than <= or LE Less than or equal to = or EQ Equal to >= or GE Greater than or equal to > or GT Greater than LOGICAL OPERATORS (Relational expressions) NOT True if false, else false AND True if all true, else false OR True if any true, else false XOR True if only one true, else false PRECEDENCE OF OPERATORS 1. Parentheses 2. Functions 3. Exponentiation 4. Unary minus 5. Multiplication and division 6. Addition and subtraction 7. Relational operators 8. NOT 9. AND 10. OR and XOR BUILT-IN FUNCTIONS MATHEMATICAL (x is arithmetic quantity) ABS(x) Absolute value ATN(x) Angle (in radians) whose tangent is X COS(x) Cosine of X (X in radians) COSH(x) Hyperbolic cosine of X EXP(x) Natural exponent of X (e^X) INT(x) Greatest integer less than or equal to X LOG(x) Natural logarithm of X RND Random number from 0 to 1 SGN(x) Sign of X (1 = pos., 0 = 0, -1 = neg.) SIN(x) Sine of X SINH(x) Hyperbolic sine of X SQR(x) Square root of X TAN(x) Tangent of X STRING (s any string; n,m integer values) ASC(s) ASCII code of first character of S CHR$(n) ASCII character whose ASCII code is N LEFT$(s,n) Substring, first N characters of S LEN(s) Number of characters in S MID$(s,n,m) Substring, M characters starting from N RIGHT$(s,n) Substring, last N characters of S STR$(x) ASCII representation of X, any number VAL(s) Numeric value of S taken as a number form MISCELLANEOUS (n is numberic) POS Position (column) in current output line TAB(n) Spaces output line up to column N FRE Returns unused memory space INP(n) Returns value at port N USER-DEFINED FUNCTIONS To define a function, use DEF FN name = expression where name is the name of the function, following variable name rules. The function must be defined before its use. PROGRAM STATEMENTS INPUT/OUTPUT STATEMENTS INPUT "optional prompt string"; variable list The (variable list) is one or more variables, separated by commas. Strings must be enclosed in quotes if they contain commas. INPUT must be the last instruction on a line. READ variable list Read DATA statement constants. READ #f; variable list Read sequential file number f into listed variables. Most BASICs use INPUT instead of READ here. Strings must be enclosed in quotes if they contain commas. READ #f,r; variable list Read record r of random file f into listed variables. PRINT list Print list of expressions at terminal. PRINT #f; list Print list of expressions into sequential file f. Com- mas are used to separate items in list, and are in- cluded in the output (they are not interpreted as tabs, as with the terminal PRINT command). EBASIC will automatically put quotes around any string expression. PRINT and READ statements are directly complementary. That is, if you say PRINT #1; A, B$, C it can be read with READ #1; A, B$, C PRINT #f,r; list Print list of expressions into random file f at record r. FILE variable list Open files for read or write. Up to 8 files may be opened at a time. The file names must be in string variables, and if more than one file is opened, the variables must be separated with commas. The files are assigned file numbers in the order they appear in the FILE statement. If the file to be opened is random, its record size is shown in a subscript to the varia- ble name. FILE1$ = "DATA1.DAT" FILE2$ = "DATA2.DAT" FILE FILE1$, FILE2$(100) In this example, DATA1.DAT (file #1) is opened as a sequential file, and DATA2.DAT (file #2) is opened as a random file with a block size of 100 bytes. The block size does not have to be related to the disk sector size, but should include room for quotes around strings, commas between items in PRINT statements, and a CR-LF at the end of the block. CLOSE (list) Close the files whose numbers are in the list. Close cancels any IF END statement. It removes the file number, renumbering the remaining files without any gap. CLOSE (1,2) will close the files in the above example. IF END #f THEN label Transfer to labeled instruction (line number) if an end of file is read. IF END should appear outside the loop where reading is done: IF END #1 THEN 100 INSTRUCTIONS$ = "INSTRUCT.DAT" FILE INSTRUCTIONS$ IF END #1 THEN 100 10 READ #1; A$: REM READ INSTRUCTIONS PRINT A$: REM PRINT THEM GOTO 10: REM LOOP UNTIL END 100 CLOSE (1): PRINT "END OF INSTRUCTIONS" REM CONTINUE WITH PROGRAM In this example, EBASIC will read and print lines from the file INSTRUCT.DAT until the end is read. DATA list Compile a list of constants. The list may consist of numeric and/or string constants. The strings must be enclosed in quotes if they contain commas. List items are separated by commas. RESTORE Reset DATA list pointer to the first item. OUT n,m Output a byte m to port n. CONTROL STATEMENTS END In EBASIC, END is a compiler directive, not a program statement. It instructs the compiler to reject any succeeding lines -- there is no more program text. GOTO label Transfer control to the label (line number). GOSUB label Call subroutine at the label. IF logical expression THEN label or command [ELSE label or command] Conditional: If true THEN, if false ELSE. The default ELSE is the next instruction. IF expression GOTO is not allowed. Always use THEN after IF (THEN label or THEN GOTO label). ON expression GOTO label list ON expression GOSUB label list Computed transfer. The value of the expression gives the number of the label in the list to transfer to. RETURN At the end of a subroutine, RETURN transfers control to the instruction following the GOSUB call of the subrou- tine. Subroutines may be nested 20 deep. STOP End processing and return control to CP/M. FOR v = a TO b [STEP c] Loop control: V is an unsubscripted variable, and A, B, and C are expressions. The default step is 1. A step of 0 makes an infinite loop. Loops may be nested, but must not be crossed. For example FOR X = 1 TO 10 FOR Y = 1 TO 10 NEXT Y: NEXT X is allowed, but FOR X = 1 TO 10 FOR Y = 1 TO 10 NEXT X: NEXT Y is NOT allowed. NEXT v NEXT complements FOR and ends the loop. MISCELLANEOUS STATEMENTS REM text Introduce a comment (which is ignored by the compiler). RANDOMIZE Initialize the random number generator. RANDOMIZE must follow an INPUT statement. COMPILING A PROGRAM To compile a program, enter the CP/M command d>x:EBASIC x:fname <$options> where x: is a valid drive designation (A:-P:), which may be left off if the default system drive is used, and fname is the name of the .BAS-type program to be compiled. The following options may be specified after the file name. B List only source code lines with errors. Normally, the entire source is listed during the second pass of the compilation. C Syntax check only (no output file produced). D Do not convert lower case to upper case. E Remember line numbers in error message produced when the program is running (takes more space but helps debugging) The output of the compiler is an intermediate-code .INT-type file. E.g., A>EBASIC GAME $E In this example, both the compiler (EBASIC.COM) and the program (GAME.BAS) are found by default file rules. The output file produced is GAME.INT on the same drive as GAME.BAS. Line numbers will be remembered for use in error messages. RUNNING A PROGRAM To run a compiled program, enter d>x:INT x:fname where x: is a valid drive designation (A:-P:), which may be left off if the default system drive is used fname is the name of the .INT-type program file to be run. COMPILER ERROR MESSAGES CE Can't close file DE Disk error DF Disk or directory full DL Duplicate label or synchronization error DP DIM variable name previously defined FC File name previously defined FD Function name previously defined FI FOR loop index is not an unsubscripted numeric variable FN Wrong number of arguments for function FP Invalid argument mode for function FU Undefined function IC Invalid character in source code IE IF logical expression is not floating point IS Subscript on undimensioned variable IU Array variable not subscripted MF String mode used for numeric expression MM Mixed mode in expression NI NEXT index fails to match FOR index NP Illegal instruction NS No source file NU Undefined NEXT (no FOR) SN Wrong number of subscripts or DIM error SO Compiler stack overflow TO Symbol table overflow UL Undefined label (no destination) VO Variable overflow RUN-TIME ERROR MESSAGES AC Null string in ASC argument CE File close error DR Disk read error (random access) DW Disk write error DZ Divide by zero EF End of file on disk file (and no IF END) ER Exceed block size on record II Invalid input from terminal IR Invalid record number in random access FU Attempt access of unopened file ME File creation error MF File identifier not 1 to 8 NE Negative exponent NI No .INT (P-code) file NM No memory left OD Attempt to read past data area OE File open error OI Out of bounds on index OM Out of memory (arrays too big) OS String overflow on blocked record RE Attempt read past end of blocked record RU Attempted random access of sequential file SB Array subscript out of bounds SL String length exceeds 255 SS MID$ start argument negative TZ TAN argument is pi/2