1 .\" $Id: basic.doc,v 2.6 1994/06/24 10:01:43 ceriel Exp $
22 Department of Mathematics and Computer Science.
28 This manual describes the
29 programming language BASIC and its compiler
30 included in the Amsterdam Compiler Kit.
35 The BASIC-EM compiler is an extensive implementation of the
36 programming language BASIC.
37 The language structure and semantics are modelled after the
38 BASIC interpreter/compiler of Microsoft (tr), a short comparison
39 is provided in appendix A.
41 The compiler generates code for a virtual machine, the EM machine
43 Using EM as an intermediate machine results in a highly portable
44 compiler and BASIC code.
46 The drawback of EM is that it does not directly reflect one particular
47 hardware design, which means that many of the low level operations available
48 within BASIC are ill-defined or even inapplicable.
49 To mention a few, the peek and poke instructions are likely
50 to be behave errorneous, while line printer and tapedeck
51 primitives are unknown.
53 This manual is divided into three chapters.
55 Chapter 1 discusses the general language syntax and semantics.
57 Chapter 2 describes the statements available in BASIC-EM.
59 Chapter 3 describes the predefined functions, ordered alphabetically.
61 Appendix A discusses the differences with Microsoft BASIC.
63 Appendix B describes all reserved symbols.
69 The conventions for syntax presentation are as follows:
71 Items are reserved words, must be input as shown.
73 Items in lowercase letters enclosed in angular brackets
74 are to be supplied by the user.
78 Items may be repeated any number of times
80 A choice between two or more alternatives. At least one of the entries
83 Vertical bars separate the choices within braces.
85 All punctuation must be included where shown.
90 The BASIC-EM compiler is designed for a UNIX based environment.
91 It accepts a text file with a BASIC program (suffix .b) and generates
92 an executable file, called a.out.
96 A BASIC program consists of a series of lines, starting with a
97 positive line number in the range 0 to 32767.
98 A line may consists of more than one physical line on a terminal, but
99 is limited to 1024 characters.
100 Multiple BASIC statements may be placed on a single line, provided
101 they are separated by a colon (:).
105 The BASIC compiler character set is comprised of alphabetic
106 characters, numeric characters, and special characters shown below.
108 = + - * / ^ ( ) % # $ \\ _
109 ! [ ] , . ; : & ' ? > < \\ (blanc)
112 BASIC uses two different types of constants during processing:
113 numeric and string constants.
115 A string constant is a sequence of characters taken from the ASCII
116 character set enclosed by double quotation marks.
118 Numeric constants are positive or negative numbers, grouped into
119 five different classes.
120 .IP "a) integer constants" 25
122 Whole numbers in the range of -32768 and 32767. Integer constants do
123 not contain decimal points.
124 .IP "b) fixed point constants" 25
126 Positive or negative real numbers, i.e. numbers with a decimal point.
127 .IP "c) floating point constants" 25
129 Real numbers in scientific notation. A floating point constant
130 consists of an optional signed integer or fixed point number
131 followed by the letter E (or D) and an optional signed integer
133 The allowable range of floating point constants is 10^-38 to 10^+38.
134 .IP "d) Hex constants" 25
136 Hexadecimal numbers, denoted by the prefix &H.
137 .IP "e) Octal constants" 25
139 Octal numbers, denoted by the prefix &O.
143 Variables are names used to represent values in a BASIC program.
144 A variable is assigned a value by assigment specified in the program.
145 Before a variable is assigned its value is assumed to be zero.
147 Variable names are composed of letters, digits or the decimal point,
148 starting with a letter. Up to 40 characters are significant.
149 A variable name can be followed by any of the following type
150 declaration characters:
152 Defines an integer variable
154 Defines a single precision variable (see below)
156 Defines a double precision variable
158 Defines a string variable.
160 Beside single valued variables, values may be grouped into tables or arrays.
161 Each element in an array is referenced by the array name and an index,
162 such a variable is called a subscripted variable.
163 An array has as many subscripts as there are dimensions in the array,
164 the maximum of which is 11.
166 If a variable starts with FN it is assumed to be a call to a user defined
169 A variable name may not be a reserved word nor the name
170 of a predefined function.
171 A list of all reserved identifiers is included as Appendix B.
175 Two variables with the same name but different type is
178 The type of a variable without typedeclaration-character is set,
179 at it's first occurence in the program,
180 to the defaulttype which is (in this implementation) double precision.
182 Multi-dimensional array's must be declared before use (see
185 BASIC-EM differs from Microsoft BASIC in supporting floats in one precision
186 only (due to EM), eg doubles and floats have the same precision.
190 When necessary the compiler will convert a numeric value from
192 A value is always converted to the precision of the variable it is assigned
194 When a floating point value is converted to an integer the fractional
196 In an expression all values are converted to the same degree of precision,
197 i.e. that of the most precise operand.
199 Division by zero results in the message "Division by zero".
200 If overflow (or underflow) occurs, the "Overflow (underflow)" message is
201 displayed and execution is terminated (contrary to Microsoft).
205 The arithmetic operators in order of precedence,a re:
209 *,/,\\\\\\\\,MOD Multiplication, Division, Remainder
210 +,- Addition, Substraction
212 The operator \\\\ denotes integer division, its operands are rounded to
213 integers before the operator is applied.
214 Modulus arithmetic is denoted by the operator MOD, which yields the
215 integer value that is the remainder of an integer division.
217 The order in which operators are performed can be changed with parentheses.
221 The relational operators in order of precedence, are:
227 <= Less than or equal to
228 >= Greater than or equal to
230 The relational operators are used to compare two values and returns
231 either "true" (-1) or "false" (0) (See IF statement).
232 The precedence of the relational operators is lower
233 then the arithmetic operators.
237 The logical operators performs tests on multiple relations, bit manipulations,
238 or boolean operations.
239 The logical operators returns a bitwise result ("true" or "false").
240 In an expression, logical operators are performed after the relational and
241 arithmetic operators.
242 The logical operators work by converting their operands to signed
243 two-complement integers in the range -32768 to 32767.
248 XOR Bitwise exclusive or
249 EQV Bitwise equivalence
255 A function is used in an expression to call a system or user defined
257 A list of predefined functions is presented in chapter 3.
261 Strings can be concatenated by using +. Strings can be compared with
262 the relational operators. String comparison is performed in lexicographic
267 The occurence of an error results in termination of the program
268 unless an ON....ERROR statement has been encountered.
273 This chapter describes the statements available within the BASIC-EM
274 compiler. Each description is formatted as follows:
276 Shows the correct syntax for the statement. See introduction of
277 syntax notation above.
279 Describes the purpose and details of the instructions.
281 Describes special cases, deviation from Microsoft BASIC etc.
286 CALL <variable name>[(<argument list>)]
288 The CALL statement provides the means to execute procedures
289 and functions written in another language included in the
290 Amsterdam Compiler Kit.
291 The argument list consist of (subscripted) variables.
292 The BASIC compiler pushes the address of the arguments on the stack in order
299 CLOSE [[#]<file number>[,[#]<file number...>]]
301 To terminate I/O on a disk file.
302 <file number> is the number associated with the file
303 when it was OPENed (See OPEN-statement). Ommission of parameters results in closing
306 The END statement and STOP statement always issue a CLOSE of
311 DATA <list of constants>
313 DATA statements are used to construct a data bank of values that are
314 accessed by the program's READ statement.
315 DATA statements are non-executable,
316 the data items are assembled in a data file by the BASIC compiler.
317 This file can be replaced, provided the layout remains
318 the same (otherwise the RESTORE won't function properly).
320 The list of data items consists of numeric and string constants
321 as discussed in section 1.
322 Moreover, string constants starting with a letter and not
323 containing blancs, newlines, commas, colon need not be enclosed with
326 DATA statements can be reread using the RESTORE statement.
330 DEF FN<name> [(<parameterlist>)]=<expression>
332 To define and name a function that is written by the user.
333 <name> must be an identifier and should be preceded by FN,
334 which is considered integral part of the function name.
335 <expression> defines the expression to be evaluated upon function call.
337 The parameter list is comprised of a comma separated
338 list of variable names, used within the function definition,
339 that are to replaced by values upon function call.
340 The variable names defined in the parameterlist, called formal
341 parameters, do not affect the definition and use of variables
342 defined with the same name in the rest of the BASIC program.
344 A type declaration character may be suffixed to the function name to
345 designate the data type of the function result.
349 DEF<type> <range of letters>
351 Any undefined variable starting with the letter included in the range of
352 letters is declared of type <type> unless a type declaration character
354 The range of letters is a comma separated list of characters and
355 character ranges (<letter>-<letter>).
359 DIM <list of subscripted variable>
361 The DIM statement allocates storage for subscripted variables.
362 If an undefined subscripted variable is used
363 the maximum value of the array subscript is assumed to be 10.
364 A subscript out of range is signalled by the program (when ACK works)
365 The minimum subscript value is 0, unless the OPTION BASE statement has been
368 All variables in a subscripted variable are initially zero.
370 BUGS. Multi-dimensional arrays MUST be defined. Subscript out of range is
377 END terminates a BASIC program and returns to the UNIX shell.
378 An END statement at the end of the BASIC program is optional.
382 <identifier name>= ERR
384 <identifier name>= ERL
386 Whenever an error occurs the variable ERR contains the
387 error number and ERL the BASIC line where the error occurred.
388 The variables are usually used in error handling routines
389 provided by the user.
393 ERROR <integer expression>
395 To simulate the occurrence of a BASIC error.
396 To define a private error code a value must be used that is not already in
397 use by the BASIC runtime system.
398 The list of error messages currently in use can be found in appendix B.
406 FOR <variable>= <low>TO<high>[STEP<size>]
410 NEXT [<variable>][,<variable>...]
412 The FOR statements allows a series of statements to be performed
413 repeatedly. <variable> is used as a counter. During the first
414 execution pass it is assigned the value <low>,
415 an arithmetic expression. After each pass the counter
416 is incremented (decremented) with the step size <size>, an expression.
417 Ommission of the step size is intepreted as an increment of 1.
419 Execution of the program lines specified between the FOR and the NEXT
420 statement is terminated as soon as <low> is greater (less) than <high>
422 The NEXT statement is labeled with the name(s) of the counter to be
425 The variables mentioned in the NEXT statement may be ommitted, in which case
426 the variable of increment the counter of the most recent FOR statement.
427 If a NEXT statement is encountered before its corresponding FOR statement,
428 the error message "NEXT without FOR" is generated.
432 GET [#]<file number>[, <record number>]
443 The GOSUB statement branches to the first statement of a subroutine.
444 The RETURN statement cause a branch back to the statement following the
445 most recent GOSUB statement.
446 A subroutine may contain more than one RETURN statement.
448 Subroutines may be called recursively.
449 Nesting of subroutine calls is limited, upon exceeding the maximum depth
450 the error message "XXXXX" is displayed.
456 To branch unconditionally to a specified line in the program.
457 If <line number> does not exists, the compilation error message
458 "Line not defined" is displayed.
460 Microsoft BASIC continues at the first line
461 equal or greater then the line specified.
466 IF <expression> THEN {<statements>|<line number>}
467 [ELSE {<statements>|<line number>}]
470 IF <expression> GOTO <line number>
471 [ELSE {<statements>|<line number>}]
473 The IF statement is used
474 to make a decision regarding the program flow based on the
475 result of the expressions.
476 If the expression is not zero, the THEN or GOTO clause is
477 executed. If the result of <expression> is zero, the THEN or
478 GOTO clause is ignored and the ELSE clause, if present is
481 IF..THEN..ELSE statements may be nested.
482 Nesting is limited by the length of the line.
483 The ELSE clause matches with the closests unmatched THEN.
485 When using IF to test equality for a value that is the
486 result of a floating point expression, remember that the
487 internal representation of the value may not be exact.
488 Therefore, the test should be against a range to
489 handle the relative error.
491 Microsoft BASIC allows a comma before THEN.
495 INPUT [;][<"prompt string">;]<list of variables>
497 An INPUT statement can be used to obtain values from the user at the
499 When an INPUT statement is encountered a question mark is printed
500 to indicate the program is awaiting data.
501 IF <"prompt string"> is included, the string is printed before the
502 the question mark. The question mark is suppressed when the prompt
503 string is followed by a comma, rather then a semicolon.
505 For each variable in the variable a list a value should be supplied.
506 Data items presented should be separated by a comma.
508 The type of the variable in the variable list must aggree with the
509 type of the data item entered. Responding with too few or too many
510 data items causes the message "?Redo". No assignment of input values
511 is made until an acceptable response is given.
513 The option to disgard the carriage return with the semicolon after the
514 input symbol is not yet implemented.
518 INPUT #<file number>,<list of variables>
520 The purpose of the INPUT# statement is to read data items from a sequential
521 file and assign them to program variables.
522 <file number> is the number used to open the file for input.
523 The variables mentioned are (subscripted) variables.
524 The type of the data items read should aggree with the type of the variables.
525 A type mismatch results in the error message "XXXXX".
527 The data items on the sequential file are separated by commas and newlines.
528 In scanning the file, leading spaces, new lines, tabs, and
529 carriage returns are ignored. The first character encountered
530 is assumed to be the state of a new item.
531 String items need not be enclosed with double quotes, provided
532 it does not contain spaces, tabs, newlines and commas,
534 Microsoft BASIC won't assign values until the end of input statement.
535 This means that the user has to supply all the information.
539 [LET]<variable>=<expression>
541 To assign the value of an expression to a (subscribted) variable.
542 The type convertions as dictated in chapter 1 apply.
546 LINE INPUT [;][<"prompt string">;]<string variable>
548 An entire line of input is assigned to the string variable.
549 See INPUT for the meaning of the <"prompt string"> option.
553 LINE INPUT #<file number>,<string variable>
555 Read an entire line of text from a sequential file <file number>
556 and assign it to a string variable.
564 MID$(<string expr1>,n[,m])=<string expr2>
566 To replace a portion of a string with another string value.
567 The characters of <string expr2> replaces characters in <string expr1>
568 starting at position n. If m is present, at most m characters are copied,
569 otherwise all characters are copied.
570 However, the string obtained never exceeds the length of string expr1.
574 ON ERROR GOTO <line number>
576 To enable error handling within the BASIC program.
577 An error may result from arithmetic errors, disk problems, interrupts, or
578 as a result of the ERROR statement.
579 After printing an error message the program is continued at the
580 statements associated with <line number>.
582 Error handling is disabled using ON ERROR GOTO 0.
583 Subsequent errors result in an error message and program termination.
585 ON...GOSUB and ON ...GOTO
587 ON <expression> GOSUB <list of line numbers>
589 ON <expression> GOTO <list of line numbers>
591 To branch to one of several specified line numbers or subroutines, based
592 on the result of the <expression>. The list of line numbers are considered
593 the first, second, etc alternative. Branching to the first occurs when
594 the expression evaluates to one, to the second alternative on two, etc.
595 If the value of the expression is zero or greater than the number of alternatives, processing continues at the first statement following the ON..GOTO
596 (ON GOSUB) statement.
598 When the expression results in a negative number the
599 an "Illegal function call" error occurs.
601 BUG If the value of the expression is zero or greater than the number of
602 alternatives, processing does NOT continue at the first statement
603 following the ON..GOTO (ON GOSUB) statement.
607 OPEN {"i" | "o" | "r" } , [#]<file number> , <file-name>
609 To open <file-name> (filename should be quoted) for input/reading or output.
610 If file is not opened for output it has to be existent, otherwise an
611 "file not found" error will occur.
617 To declare the lower bound of subsequent array subscripts as either
618 0 or 1. The default lower bound is zero.
624 To poke around in memory. The use of this statement is not recommended,
625 because it requires full understanding of both
626 the implementation of the Amsterdam
627 Compiler Kit and the hardware characteristics.
631 PRINT <list of variables and/or constants>
633 To print constants or the contents of variables on the terminal-device.
634 If the variables or constants are seperated by comma's the values will
635 be printed seperated by tabs.
636 If the variables or constants are seperated by semi-colon's the values
637 will be printed without spaces in between.
638 The new-line generated at the end of the print-statement can be suppressed by
639 a semi-colon at the end of list of variables or constants.
651 RANDOMIZE [<expression>]
653 To reset the random seed. When the expression is ommitted, the system
654 will ask for a value between -32768 and 32767.
655 The random number generator returns the same sequence of values provided
656 the same seed is used.
660 READ <list of variables>
662 To read values from the DATA statements and assign them to variables.
663 The type of the variables should match to the type of the items being read,
664 otherwise a "Syntax error" occurs. If all data is read the message "Out of
665 data" will be displayed.
671 To include explantory information in a program.
672 The REM statements are not executed.
673 A single quote has the same effect as : REM, which
674 allows for the inclusion of comment at the end of the line.
676 Microsoft BASIC does not allow REM statements as part of
681 RESTORE [<line number>]
683 To allow DATA statements to be re-read from a specific line.
684 After a RESTORE statement is executed, the next READ accesses
685 the first item of the DATA statements.
686 If <line number> is specified, the next READ accesses the first
687 item in the specified line.
689 Note that data statements result in a sequential datafile generated
690 by the compiler, being read by the read statements.
691 This data file may be replaced using the operating system functions
692 with a modified version, provided the same layout of items
693 (same number of lines and items per line) is used.
699 To terminate the execution of a program and return to the operating system
700 command interpreter. A STOP statement results in the message "Break in line
705 SWAP <variable>,<variable>
707 To exchange the values of two variables.
709 BUG. Strings cannot be swapped !
717 As an aid in debugging the TRON statement results in a program
718 listing each line being interpreted. TROFF disables generation of
727 To execute a series of BASIC statements as long as a conditional expression
728 is true. WHILE...WEND loops may be nested.
732 WRITE [<list of expressions>]
734 To write data at the terminal in DATA statement layout conventions.
735 The expressions should be separated by commas.
739 WRITE #<file number> ,<list of expressions>
741 To write a sequential data file, being opened with the "O" mode.
742 The values are being writting using the DATA statements layout conventions.
748 Returns the absolute value of expression X
750 Returns the numeric value of the first character of the string.
751 If X$ is not initialized an "Illegal function call" error
754 Returns the arctangent of X in radians. Result is in the range
757 Converts X to a double precision number.
759 Converts the integer value X to its ASCII character.
760 X must be in the range of 0 to 257.
761 It is used for cursor addressing and generating bel signals.
763 Converts X to an integer by rounding the fractional portion.
764 If X is not in the range -32768 to 32767 an "Overflow"
767 Returns the cosine of X in radians.
769 Converts X to a single precision number.
770 .IP CVI(<2-bytes>) 25
771 Convert two byte string value to integer number.
772 .IP CVS(<4-bytes>) 25
773 Convert four byte string value to single precision number.
774 .IP CVD(<8-bytes>) 25
775 Convert eight byte string value to double precision number.
776 .IP EOF[(<file-number>)] 25
777 Returns -1 (true) if the end of a sequential file has been reached.
779 Returns e(base of natural logarithm) to the power of X.
780 X should be less then 10000.0.
782 Returns the truncated integer part of X. FIX(X) is
783 equivalent to SGN(X)*INT(ABS(X)).
784 The major difference between FIX and INT is that FIX does not
785 return the next lower number for negative X.
787 Returns the string which represents the hexadecimal value of
788 the decimal argument. X is rounded to an integer using CINT
789 before HEX$ is evaluated.
791 Returns the largest integer <= X.
792 .IP INP$(X[,[#]Y]) 25
793 Returns the string of X characters read from the terminal or
796 Returns the number of characters in the string X$.
797 Non printable and blancs are counted too.
798 .IP LOC(<file\ number>) 25
799 For sequential files LOC returns
800 position of the read/write head, counted in number of bytes.
801 For random files the function returns the record number just
802 read or written from a GET or PUT statement.
803 If nothing was read or written 0 is returned.
805 Returns the natural logarithm of X. X must be greater than zero.
807 Returns first J characters from string X starting at position I in X.
808 If J is omitted all characters starting of from position I in X are returned.
810 Converts an integer expression to a two-byte string.
812 Converts a single precision expression to a four-byte string.
814 Converts a double precision expression to a eight-byte string.
816 Returns the string which represents the octal value of the decimal
817 argument. X is rounded to an integer using CINT before OCTS is evaluated.
819 Returns the byte read from the indicated memory. (Of limited use
820 in the context of ACK)
822 Returns the current cursor position. To be implemented.
824 Returns the right most I characters of string X$.
825 If I=0 then the empty string is returned.
827 Returns a random number between 0 and 1. X is a dummy argument.
829 If X>0 , SGN(X) returns 1.
831 if X=0, SGN(X) returns 0.
833 if X<0, SGN(X) returns -1.
835 Returns the sine of X in radians.
837 Returns a string of spaces length X. The expression
838 X is rounded to an integer using CINT.
840 Returns the string representation value of X.
842 Returns thes string of length Iwhose characters all
843 have ASCII code J. (or first character when J is a string)
845 Spaces to position I on the terminal. If the current
846 print position is already beyond space I,TAB
847 goes to that position on the next line.
848 Space 1 is leftmost position, and the rightmost position
849 is width minus 1. To be used within PRINT statements only.
851 Returns the tangent of X in radians. If TAN overflows
852 the "Overflow" message is displayed.
854 Returns the numerical value of string X$.
855 The VAL function strips leading blanks and tabs from the
859 APPENDIX A DIFFERENCES WITH MICROSOFT BASIC
861 The following list of Microsoft commands and statements are
862 not recognized by the compiler.
894 Some statements are in the current implementation not available,
895 but will be soon. These include:
911 APPENDIX B RESERVED WORDS IN BASIC-EM
913 The following list of words/symbols/names/identifiers are reserved, which
914 means that they can not be used for variable-names.
919 CLEAR CLOAD CLOSE COMMON
922 DEFINT DEFSNG DEFDBL DEFSTR
929 INKEY INPUT INP INSTR
933 LPRINT LSET MERGE MID
939 RANDOMIZE READ REM RENUM
940 REN RESTORE RESUME RETURN
947 WAIT WHILE WEND WIDTH
public / Ack-5.5.git / blob