All the ATOM BASIC statements, functions, and commands are listed in the following pages in alphabetical order. Following each name is, where applicable, an explanation of the name and the shortest abbreviation of that name. The following symbols will be used; these are defined more fully in Chapter 26:
<VARIABLE> -- one of the variables A to Z, or @.
<FACTOR> -- a variable, a constant, a function, an array, an indirection, or an expression in brackets, any of which may optionally be preceded by a + or -- sign; e.g.:
A, -1234, ABS(12), AA(3), !A, (2*A+B).
<EXPRESSION> -- any arithmetic expression; e.g.:
A+B/2*(27-R)&H.
<RELATIONAL expression> -- an expression, or a pair of
expressons
linked by a relational operator; e.g.:
A, A>=B, $A="CAT"
<TESTABLE expression> -- any number of <RELATIONAL
expressions>
connected by AND or OR; e.g.:
A>B AND C>D.
<STRING right> -- a quoted string, or an expression
optionally preceded
by a dollar; e.g.:
"STRING", $A.
| ABS | Absolute value | A. |
This function returns the absolute value of its argument, which is a <FACTOR>. ABS will fail to take the absolute value of the maximum negative integer, -2147483648, since this has no corresponding positive value. The most common use of ABS is in conjunction with RND to produce random numbers in a specified range, see RND. Example:
PRINT ABS-1,ABS(-1),ABS1,ABS(1)'
1 1 1 1
| AND | Relational AND | A. |
This symbol provides the logical AND operation between two <RELATIONAL expression>s. Its form is <RELATIONAL expression a> AND <RELATIONAL expression b> and the result will be true only if both <RELATIONAL expression>s are true. AND has the same priority as OR. Example:
IF A=B AND C=D PRINT"EQUAL PAIRS"'
| BGET | Byte get | B. |
This function returns a single byte from a random file. The form of the instruction is:
BGET <FACTOR>
where <FACTOR> is the file's handle returned by the FIN
function. The next byte from the random file is returned as the
least significant byte of the value, the other three bytes being
zero. In the DOS the sequential pointer will be moved on by one
and the operating system will cause an error if the pointer
passes the end of the file.
Example:
A=FIN"FRED"
PRINT "THE FIRST BYTE FROM FRED IS "BGET A'
| BPUT | Byte put | B. |
This statement sends a single byte to a random file. The form of the statement is:
BPUT <FACTOR>, <EXPRESSION>
where <FACTOR> is the file's handle returned by the FOUT function; the <EXPRESSION> is evaluated and its least significant byte is sent to the random file. If you are using the DOS, the random file's sequential pointer will be moved on by one and the operating system will cause an error if the length of the file exceeds the space allowed. Example:
A=FOUT"FRED"
BPUT A, 23
| CH | Change character to number | CH |
This function returns the number representing the first ASCII character of the string supplied as its argument. It differs from straight use of the '?' operator in that it can take an immediate string argument or an <EXPRESSION>. Examples:
PRINT CH""'
13 (value of string terminatinq character)
PRINT CH"BETA"'
66
S=TOP;$S="BETA"
PRINT ?S/CH$S,CHS'
66 66 66
PRINT S?LENS,CH$S+LENS'
65 65
| CLEAR | Clear graphics screen | CLEAR |
This statement clears the screen and initialises the display for the graphics mode specified its argument:
CLEAR 0 : Screen is 64*48 (semi-graphics mode) CLEAR 1 : Screen is 128*64 CLEAR 2 : Screen is 128*96 CLEAR 3 : Screen is 128*192 CLEAR 4 : Screen is 256*192
In graphics modes 1 to 4 an error will be caused if the text space and graphics area conflict.
| COUNT | Count of characters printed | C. |
This function returns the number of characters printed since the last return, and is thus the column position on a line at which the next character will be printed. COUNT is useful for positioning table elements etc. Example:
DO PRINT"=";UNTIL COUNT=20 ====================>
| DIM | Dimension statement | DIM |
This statement automatically allocates space after the end of the text for arrays or strings. DIM causes an error if used in direct mode. Associated with DIM is a 16 bit location referred to as the 'free space pointer'. The RUN statement sets this pointer to the value of TOP. A declaration:
DIM A(Q)
sets A to the current value of the free space pointer, and the pointer is moved up by (Q+1) bytes. A declaration:
DIM AA(Q)
allocates space for an array AA with elements AA(0) to AA(Q), and moves the value of the free space pointer up by 4*(Q+1) bytes.
A special use of DIM is to set the value of P for assembling:
DIM P(-1)
sets P to the current value of the free space pointer, without changing the pointer's value. Several items may be dimensioned in one DIM statement:
DIM A(2),AA 45,BB(67),CC(F)
| DRAW | Draw line to absolute position | DRAW |
The statement DRAW A,B is equivalent to PLOT 5,A,B.
| DO | Start of DO...UNTIL loop | DO |
This statement is part of the DO...UNTIL control expression. As the BASIC interpreter passes DO it saves that position and will return to it if the UNTIL statement's condition is false. No more than 11 active DO statements are allowed. See UNTIL for examples.
| END | End of program | E. |
This statement has two functions:
1. Termination of an executing program
2. Resetting the value of TOP to point to the first free byte
after the program text.
END can be used in direct mode to set TOP. Programs can have as many END statements as required and they do not need to have an END statement as a last line, although an error will be caused on execution past the end of the program. See also TOP. Example:
IF SZ="FINISH" END; REM conditional end
| EXT | Extent of random file | E. |
In the DOS this function returns the EXTent (length) of a random file in bytes. The file can be either an input or an output file, and the form of the instruction is
EXT<FACTOR>
where factor is the file's handle found using either FIN or FOUT.
In the COS, execution of this function results in an error.
Example:
A=FIN"FRED"
PRINT "FRED IS "EXT(A)" BYTES LONG"'
| FIN | Find Input | F. |
In the DOS this function initialises a random file for input (with GET, BGET, and SGET) and updating (with PUT, BPUT, and SPUT), and returns a number which uniquely represents the file. This 'file handle' is used in all future references to the file. Zero is returned if the file does not exist. The file handle is only a byte long (1 -- 255) and can be stored in variables or using ! or ?. Usage of a file handle not given by the operating system will result in an error.
In the COS the message PLAY TAPE will be printed, and the system will wait for any key to be pressed.
| FOR | Start of FOR...NEXT loop | F. |
This statement is the first part of the FOR...NEXT loop, which allows a section of BASIC text to be executed several times. The form of the FOR statement is:
FOR (a) = (b) TO (c) STEP (d)
where
(a) is the CONTROL VARIABLE which is used to test for loop completion
(b) is the initial value of the control variable
(c) is the limit to the value of the control variable
(d) is the step size in value of the control variable for each pass of the loop; if omitted, it is assumed to be 1.
Items (b) (c) (d) are <EXPRESSION>s they are evaluated only once, when the FOR statement is encountered, and the values are stored for later reference by the NEXT statement. No more than 11 nested FOR statements are allowed by the interpreter. Examples:
FOR Z=0 TO 11
FOR @=X TO Y
FOR U=-7 TO 0
FOR G=(X+1)*2 TO Y-100
FOR J=0 TO 9 STEP 3
FOR K=X+1 TO Y+2 STEP I
FOR Q=-10*ABSX TO -20*ABSY STEP -ABSQ
| FOUT | Find output | FO. |
In the DOS this function initialises a random file for output (with PUT, BPUT, and SPUT), and returns a number which uniquely specifies the output file. This 'file handle' is used in all future references to the file. Zero will be returned there is a problem associated with using the file as an output file; e.g.:
(a) write protected file
(b) write protected disc
(c) insufficient space in directory
(d) file already in use as an input file
(e) insufficient memory space
The number returned is only a byte long (1-255) and can be stored in variables or using ! or ?. Usage of a number not given by the operating system will result in an error.
In the COS the message RECORD TAPE will be printed, and any key waited for. Example:
A=FOUT"FRED"
IF A=O PRINT "WE HAVE A PROBLEM WITH FRED"'
| GET | Get word from file | G. |
This function reads a 32 bit word from a random file and returns its value. The form of the instruction is:
GET<FACTOR>
where <FACTOR> is the file's handle found with the FIN function. The first byte fetched from the file becomes the least significant byte of the value.
In the the DOS the random file's sequential pointer will be moved on by 4 and the operating system will cause an error if the pointer passes the end of the file. Example:
A=FIN"FRED"
PRINT "THE FIRST WORD FROM FRED IS "GET A'
| GOSUB | Go to subroutine | GOS. |
This statement gives the ability for programs to call sub programs. The GOSUB statement stores its position so that it can come back later on execution of a RETURN statement. Like GOTO it ran be followed by an <FACTOR> whose value is a line number, or by a label. No more than 14 GOSUB statements without RETURNs are allowed. Example:
10 GOSUB a 20 GOSUB a 30 END 100a PRINT"THIS IS A SUB PROGRAM"' 200 RETURN
When RUN this will print.:
THIS IS A SUB PROGRAM THIS IS A SUB PROGRAM
| GOTO | Go to line | G. |
This statement overrides the sequential order of proqram statement execution. It can be used after an IF statement to give a conditional change in the proqram execution. The form of the statement is either:
GOTO <FACTOR> or GOTO <label>
The GOTO statement can transfer to either an unlabelled line, by specifying the line's number, or to a labelled line, by specifying the line's label.. Examples:
10 IF A=0 PRINT"ATTACK BY KLINGON "Z;GOTO x
20 PRINT"YOU ARE IN QUADRANT "X Y
30x PRINT'"STARDATE "T'
100m INPUT"CHOICE "A 110 IF A<1 OR A>9 PRINT"!!!!!"; GOTO m 120 GOTO(A*200); REM GO EVERYWHERE !
| IF | If statement | IF |
This statement is the main control mechanism of BASIC. It is followed by a <TESTABLE expression>, which is a single byte. If TRUE (non-zero) the remainder of the line will be interpreted; if FALSE (zero) execution will continue on the next line. After the <TESTABLE expression>, IF can be followed by one of two different options:
1. The symbol THEN, followed by any statement.
2. Any statement, provided that the statement does not begin with
T or a unary operator '!' or '?'.
Examples:
IF A<3 AND B>4 THEN C=26
IF A<3 IF B>4 C=26; REM equivalent condition to above
IF A>3 OR B<4 THEN C=22; REM complementary condition to above
IF A>3 AND $S="FRED" OR C=22; REM AND and OR have equal priority
| INPUT | Input statement | IN |
This statement receives data from the keyboard. The INPUT statement consists of a list of items which can be:
(a) a string delimited by "quotes
(b) any ' new-line symbols
(c) a <VARIABLE> or a $<EXPRESSION> separated from succeeding items by a comma.
Items (a) and (b) are printed out, and for each item (c) a '?' is printed and the the program will wait for a response. If the item is a <VARIABLE>, the response can be any valid <EXPRESSION> if the item was a $<EXPRESSION>, the response is reated as a stririg and will be located in memory starting at the address given by evaluating the <EXPRESSION>. If an invalid response is typed, no chanqe to the original is made. Example:
INPUT"WHAT IS YOUR NAME "$TOP,"AND HOW OLD ARE YOU "A
When RUN this will produce:
WHAT IS YOUR NAME ?FRED AND HOW OLD ARE YOU ?100
| LEN | Length of string | L. |
This function returns the number of characters in a string. The argument for LEN is a <FACTOR> which points to the first character in the string. Valid strings have between 0 and 255 characters before a terminating return; invalid strings for which the terminating return is not found after 255 characters will return length zero. Example:
$TOP="FRED";PRINT"LENGTH OF "$TOP" IS "LEN TOP'
| LET | Assignment statement | omit |
This statement is the assignment statement and the word LET is optional. There are two types of assignment statement:
l. Arithmetic
LET<VARIABLE>=<EXPRESSION>
<VARIABLE>!<FACTOR>=<EXPRESSION>
<VARIABLE>?<FACTOR>=<EXPRESSION>
!<FACTOR>=<EXPRESSION>
?<FACTOR>=<EXPRESSION>
2. String movement
LET$<EXPRESSION>=<STRING right>
In each case the value of the right hand side is evaluated, and then stored as designated by the left hand side. The word LET is not legal in an array assignment.
| LINK | Link to machine code subroutine | LI. |
This statement causes execution of a machine code subroutine at a specified address. Its form is:
LINK <FACTOR>
where <FACTOR> specifies the address of the subroutine. The processor's A, X and Y registers will be initialised to the least significant bytes of the BASIC variables A, X and Y, and the decimal mode flag will be cleared. The return to the interpreter from the machine code program is via an RTS instruction. Examples:
Q-TOP; !Q=06058; LINK Q; REM clear interrupt flag
Q-ZOP; !Q=06078; LINK Q; REM set interrupt flag
LINK #FFE3;REM wait for key to be pressed
| LIST | List BASIC text | L. |
This command will list program lines in the current text area. It can be interrupted by pressing ESC and can take any of these forms:
LIST list all lines
LIST 10 list line 10
LIST , 40 list all lines up to 40
LIST 100 , list all lines from 100
LIST 10,40 list all lines between 10 and 40
| LOAD | Load BASIC program | LO. |
This command will load a BASIC program into the current text area. Its form is:
LOAD <STRING right>
and it will pass the string to the operating system and request the operating system to complete the transfer before returning (in case the transfer is by interrupt or direct memory access). Then the text area is scanned through to set the value of TOP; if the file was machine code or data and not a valid BASIC program the prompt may not reappear. Example:
LOAD"FRED"
| MOVE | Move to absolute position | MOVE |
The statement MOVE A,B is equivalent to PLOT 4,A,B.
| NEW | Initialise text area | N. |
This command inserts an 'end of text' marker at the start of the text area, and changes the value of TOP accordingly. The OLD command provides an immediate recovery.
| NEXT | Terminator of FOR...NEXT loop | N. |
This statement is half of the FOR...NEXT control loop. When the word NEXT is encountered, the interpreter increases the value of the control variable by the step size, and if the control variable has not exceeded the loop termination value control is transfered back to the statement after the FOR statement; otherwise execution proceeds to the statement after the NEXT statement. The NEXT statement optionally takes a <VARIABLE> which will cause a return to the same level of nesting as the FOR statement with the same control variable, or an error if no such FOR statement is active. Examples:
@=2
FOR Z=0 TO 9; PRINT Z; NEXT; PRINT'
0 1 2 3 4 5 6 7 8 9
FOR Z=0 TO 9 STEP 2; PRINT Z; NEXT Z;PRINT'
0 2 4 6 8
FOR Z=0 TO 9; PRINT Z; NEXT Y
0
ERROR 230
>
| OLD | Recover text area | OLD |
This statement executes ?(?18*256+1)=0;END to recover a text space after typing NEW. If the first line number in the text area is greater than 255 it will be changed by the OLD statement.
| OR | Relational OR | OR |
This symbol provides the logical OR operation between two
<RELATIONAL expressions>. Its form is <RELATIONAL
expression a> OR <RELATIONAL expression b> and the
result will be true (non-zero) if either <RELATIONAL
expression> is true. OR has the same priority as AND.
Example:
IF A=B OR C=D PRINT"At least one pair equal"'
| PLOT | Plot statement | PLOT |
This statement takes three arguments: a parameter that determines how to plot, and a pair of relative or absolute cartesian coordinates. The first parameter is as follows:
0 plot line relative to last point with no change in pixels 1 as 0 but set pixels 2 as 0 but invert pixels 3 as 0 but clear pixels 4 plot line to absolute position with no change in pixels 5 as 4 but set pixels 6 as 4 but invert pixels 7 as 4 but clear pixels 8 plot point relative to last point with no change in pixel 9 as 8 but set pixel 10 as 8 but invert pixel 11 as 8 but clear pixel 12 plot point at absolute position with no change in pixel 13 as 12 but set pixel 14 as 12 but invert pixel 15 as 12 but clear pixel
| Print statement | P. |
This statement outputs results and strings to the screen.. A PRINT statement consists of a list of the following items:
(a) a string delimited by "quotes, which will be printed.
(b) any ' symbols which will cause a 'newline'.
(c) the character '&' which forces hexadecimal numerical print out until the next comma.
(d) an <EXPRESSION> whose value is printed out in either decimal or hexadecimal, right hand justified in a field width defined by '@'
(e) a $<EXPRESSION> if the value of the <EXPRESSION> is between 0 and 255, the ASCII character corresponding to that value will be printed out; otherwise the string pointed to by that value will be printed out.
Examples:
PRINT '
PRINT"Hello"'
Hello
PRINT 1'
1
PRINT 1'2'3'
1
2
3
PRINT"40*25="40*25'
40*25= 1000
PRINT$CH"e"'
e
PRINT$12
DO INPUT"Who are you "$TOP;PRINT"Hi "$TOP'; UNTIL $TOP=""
Who are you ?fred
Hi fred
Who are you ?
PRINT&0 10 20 30'
O A 14 1E
| PTR | Pointer of random file | PTR |
In the DOS this function and statement allows the manipulation of the pointers in sequential files. Its form is:
PTR<FACTOR>
where <FACTOR> is the file's handle found using FIN or FOUT, and it may appear on the left hand side of an equal sign or in an expression.
In the COS PTR will cause an error. Examples:
A=FIN"FRED"
PRINT PTR AI
0
PTRA=PTRA+23
| PUT | Put word to random file | PUT |
This statement sends a four byte word to a sequential output file. The form of the instruction is:
PUT <FACTOR> , <EXPRESSION>
where <FACTOR> is the file's handle returned by the FOUT function. The <EXPRESSION> is evaluated and sent, least significant byte first, to the sequential output file. The seguential output file's pointer will be moved on by four and the operating system will cause an error if the length of the file exceeds the space allowed. Example:
A=FOUT"FRED"
PUT A , 123456
| REM | Remark | REM |
This statement causes the interpreter to ignore the rest of the line, enabling comments to be written into the program. Alternatively comments can be written on lines branched around by a GOTO statement.
| RETURN | Return from subroutine | R. |
This statement causes a return to the last encountered GOSUB statement. See GOSUB for examples.
| RND | Random number | R. |
This function returns a random number between -2147483648 and 2147483647, generated from a 33 bit pseudo-random binary sequence generator which will only repeat after over eight thousand million calls. The sequence is not initialised on entering the interpreter, but locations 8 to 12 contain the seed, and can be set using '!' to a chosen startinq point. To produce random numbers in some range A to B use:
ABSRND%(B-A)+A
| RUN | Execute BASIC text from beginning | RUN |
This statement will cause the interpreter to cornmence execution at the lowest numbered line of the current text area. Since it is a statement, it may be used in both direct mode and programs.
| SAVE | Save BASIC text space | SA. |
This statement will cause the current contents of the memory between the start of the text area, given by ?18*256, and the value of TOP, to be saved by the operating system with a specified name. The operating system is not requested to wait until the transfer is finished before returning to the interpreter. Example:
SAVE"FRED"
| SGET | String get | S. |
This statement reads a string from a random file. The form of the statement is:
SGET <FACTOR>, <EXPRESSION>
where <FACTOR> is the file's handle returned by the FIN function. The <EXPRESSION> is evaluated to form an address, and bytes are taken from the sequential input file and put in memory at consecutive locations starting at that address, until a 'return' is read. The sequential input file's pointer will be moved on by the length of the string plus one and the operating system will cause an error if the pointer passes the end of the input file.
| SHUT | Finish with random file | SH. |
In the DOS this statement closes random input or output files. The form of the statement is:
SHUT <FACTOR>
where <FACTOR> is the file's handle found with either FIN or FOUT. If it is an output file any information remaining in buffer areas in memory is written to the file. If the <FACTOR> has value zero, all current sequential files will be closed. In the COS this statement is ignored.
| SPUT | String put | SP. |
This statement writes a string to a random file. The form of the instruction is:
SPUT <FACTOR>, <STRING right>
where <FACTOR> is the file's handle returned by the FOUT function. Every byte of the string, including the terminating 'return' character, is sent to the file. In the DOS the random file's sequential pointer will be moved on by the length of the string plus one, and the operating system will cause an error if the length of the file exceeds the space allowed; Example:
A=FOUT"FRED"
SPUT A , "THIS IS FILE FRED"
| STEP | Step specifier in FOR statement | S. |
This symbol is an optional parameter in the FOR statement, used to specify step sizes other than the default of +1. It is followed by an <EXPRESSION> which is evaluated and its value stored along with the other FOR parameters. See FOR for examples.
| THEN | Connective in IF statement | omit |
This symbol is an option in the IF statement; it can be followed by any statement.
| TO | Limit specifier in FOR statement | TO |
This symbol is required in a FOR statement to specify the limit which is to be reached before the FOR..NEXT loop can be terminated. See FOR for examples.
| TOP | First free byte | T. |
This function returns the address of the first free byte after the end of a stored BASIC program. Its value is adjusted during line editing and by the END statement and LOAD command. It is vital for TOP to have the correct value (set by END) before using the line editor. See also END.
| UNTIL | Terminator of DO...UNTIL loop | U. |
This statement is part of the DO..UNTIL repetitive loop. UNTIL takes a <TESTABLE expression> and will return control to the character after DO if this is zero (false), otherwise execution will continue with the next statement. Examples:
DO PRINT"O";UNTIL O; REM do forever
DO PRINT"$"; UNTIL COUNT=20; PRINT'
####################
DO INPUT"Calculation "A; PRINT"Answer is "A'; UNTIL A=12345678
Calulation ?2*3
Answer is 6
Calculation ?A
Answer is 6
Calculation ?12345678
Answer is 12345678
| WAIT | Wait statement | WAIT |
This statement waits until the next 60 Hz vertical sync pulse from the CRT controller. The statement has two uses: to give a delay of one sixtieth of a second, and to wait until flyback so that a subsequent graphics command will not cause noise on the screen. Examples:
FOR Z=l TO 60; WAIT; NEXT; REM wait a second.
MOVE 0,0; WAIT; DRAW 8,8; REM noise-free plotting