comp.sys.sinclair FAQ

There is an extensive discussion of Sinclair BASIC, including the history and development of the language, and various interpreters for different platforms at the Sinclair BASIC site.

Sinclair BASIC:
The Sinclair BASIC documentation.

TS1000 / TS1500 / ZX81:
The following commands are found exclusively on these models;

• FAST: Instructs the computer to operate in FAST mode. In this mode, the machine will run up to four times faster than in SLOW mode. This is accomplished by not refreshing the screen display until the program has completed, or input from the user is required. The system will stay in the specified mode until it is changed, allowing certain sections of a program to be executed more quickly than others if desired. It is common to switch from SLOW mode (the default) to FAST mode when entering large programs, for example. Programs loaded from cassette that were SAVEd when the machine is in FAST mode will be automatically opened that way, and vice-versa.
  
  Example: [line #] FAST
  
  
• SCROLL: The SCROLL command instructs the machine to automatically 'shift' the display up by the required number of lines when the screen becomes full. If SCROLL is not specified and a program 'overflows' the 22 available display lines, the program with stop with an error. Pressing CONT will allow continuation with a 'new' screen. However, if a series of PRINT statements preceded by SCROLL is followed by a PRINT statement that is not followed by a SCROLL, the computer will stop with an error.
  
  Example: [line #] SCROLL
  
  
• SLOW: The opposite of FAST. In SLOW mode, the screen is refreshed as required.
  
  Example: [line #] SLOW
  
  
• UNPLOT: UNPLOT essentially reverses the effect of the PLOT statement, and accepts 2 integer values as screen co-ordinates (if a decimal value is passed, it is rounded to the nearest integer) for the pixel to 'paint' white.
  
  Example: UNPLOT [n,n]
  
  

Timex BASIC:
Timex BASIC is a superset of Sinclair BASIC, with additional commands allowing access to the hardware features found on the Timex systems. Generally speaking, BASIC programs written for the ZX Spectrum will run on Timex machines without modification. The additional commands found in Timex BASIC are listed below:

• DELETE: The DELETE command is used to remove lines of a program between two supplied values, from the beginning of a program to the line specified, or from the line specified to the end of the program.
  
  Example: DELETE [n,n] (between values) or DELETE [ ,n] (to value) or DELETE [n, ] (from value)
  
  
• FREE: FREE can be used at any time within a program, or from immediate mode, to return the amount of available internal memory.
  
  Example: PRINT FREE
  
  
• ON ERR: ON ERR allows errors to be trapped and handled before the program automatically stops with an error. GOTO jumps to a specified line number, CONT continues operation from the point at which the error occurred and RESET disables ON ERR, raising the normal system error messages instead. After ON ERR GOTO, PEEK 23736 will give the error code, while PEEK 23739 and PEEK 23738 respectively give the line number and statement number within the line where the error occured.
  
  Example: ON ERR [GOTO, CONT, RESET]
  
  
• RESET: RESET is typically used to return attached peripherals to their original state. In addition, it can be used to reset the entire system.
  
  Example: RESET 0 (resets machine)
  
  
• SOUND: The SOUND command accepts pairs of numbers separated by semi-colons. Up to 15 pairs are permitted for each SOUND command. The first number in each pair designates the register, while the second number contains the value. The available registers are:
  
  
  • 0 - Fine Tune, Channel A. Permitted values: 0-255
  • 1 - Coarse Tune, Channel A. Permitted values: 0-15
  • 2 - Fine Tune, Channel B. Permitted values: 0-255
  • 3 - Coarse Tune, Channel B. Permitted values: 0-15
  • 4 - Fine Tune, Channel C. Permitted values: 0-255
  • 5 - Coarse Tune, Channel C. Permitted values: 0-15
  • 6 - Noise. Permitted values: 0-31
  • 7 - Enable. Permitted values: 0-63
  • 8 - Amplitude, Channel A. Permitted values: 0-15
  • 9 - Amplitude, Channel B. Permitted values: 0-15
  • 10 - Amplitude, Channel C. Permitted values: 0-15 (16 enables envelope)
  • 11 - Fine Tune envelope period. Permitted values: 0-255
  • 12 - Coarse Tune envelope period. Permitted values: 0-255
  • 13 - Envelope shape. Permitted values: 0-15
    
    
  Example: SOUND [n,n];[n,n] ..... [n,n];[n,n]
  
  
• STICK: The STICK command is used to read the signal generated by devices connected to one of the two Joystick ports available. The first number represents the device type being read - (1) is the Joystick and (2) is the button. The second number is the Joystick number - (1) is left and (2) is right. Valid return values are 1 (pressed) or 0 (not pressed) if reading the button, and:
  
  
  • 0 - Centred
  • 1 - Up
  • 2 - Down
  • 4 - Left
  • 5 - Up and Left
  • 6 - Down and Left
  • 8 - Right
  • 9 - Up and Right
  • 10 - Down and Right
    
    
  Example: IF STICK([n,n]) THEN ...
  
  

Error Codes:
Both Sinclair and Timex BASICs have very effective error-trapping routines built-in, making it impossible to enter syntactically incorrect lines. Before the system will accept a program line, it must be well formed and formatted - it doesn't have to be logical, as long as it's structured correctly!

The following codes, found in Appendix B of the ZX Spectrum user manual, are displayed when a program encounters an error and cannot continue uninterrupted:

• 0 - OK: Successful completion, or jump to a line number bigger than any existing. This report does not change the line and statement jumped to by CONTINUE.
  
  
• 1 - NEXT without FOR: The control variable does not exist (it has not been set up by a FOR statement), but there is an ordinary variable with the same name.
  
  
• 2 - Variable not found: For a simple variable this will happen if the variable is used before it has been assigned to in a LET, READ or INPUT statement or loaded from tape or set up in a FOR statement. For a subscripted variable it will happen if the variable is used before it has been dimensioned in a DIM statement or loaded from tape.
  
  
• 3 - Subscript wrong: A subscript is beyond the dimension of the array, or there are the wrong number of subscripts. If the subscript is negative or bigger than 65535, then error B will result.
  
  
• 4 - Out of Memory: Sometimes during expression evaluation. There is not enough room in the computer for what you are trying to do. If the computer really seems to be stuck in this state, you may have to clear out the command line using DELETE and then delete a program line or two (with the intention of putting them back afterwards) to give yourself room to manoeuvre with - say - CLEAR.
  
  
• 5 - Out of screen: An INPUT statement has tried to generate more than 23 lines in the lower half of the screen. Also occurs with PRINT AT 22, . . .
  
  
• 6 - Number too big: Calculations have led to a number greater than about 10^38.
  
  
• 7 - RETURN without GO SUB: There has been one more RETURN than there were GO SUBs.
  
  
• 8 - End of file: Undocumented.
  
  
• 9 - STOP statement: After this, CONTINUE will not repeat the STOP, but carries on with the statement after.
  
  
• A - Invalid Argument: The argument for a function is no good for some reason.
  
  
• B - Integer out of range: When an integer is required, the floating point argument is rounded to the nearest integer. If this is outside a suitable range then error B results. For array access, see also Error 3.
  
  
• C - Nonsense in BASIC: The text of the (string) argument does not form a valid expression.
  
  
• D - BREAK - CONT repeats: Also when the computer asks scroll? and you type N, SPACE or STOP. BREAK was pressed during some peripheral operation. The behaviour of CONTINUE after this report is normal in that it repeats the statement. Compare with report L.
  
  
• E - Out of DATA: You have tried to READ past the end of the DATA list.
  
  
• F - Invalid file name: SAVE with name empty or longer than 10 characters.
  
  
• G - No room for line: There is not enough room left in memory to accommodate the new program line.
  
  
• H - STOP in INPUT: Some INPUT data started with STOP, or cursor down (CAPS SHIFT + 6) was pressed during an INPUT LINE statement. Unlike the case with report 9, after report H CONTINUE will behave normally, by repeating the INPUT statement.
  
  
• I - FOR without NEXT: There was a FOR loop to be executed no times (e.g. FOR n= 1 TO 0) and the corresponding NEXT statement could not be found.
  
  
• J - Invalid I/O device: Undocumented.
  
  
• K - Invalid colour: The number specified is not an appropriate value.
  
  
• L - BREAK into program: BREAK pressed, this is detected between two statements. The line and statement number in the report refer to the statement before BREAK was pressed, but CONTINUE goes to the statement after (allowing for any jumps to be done), so it does not repeat any statements.
  
  
• M - RAMTOP no good: The number specified for RAMTOP is either too big or too small.
  
  
• N - Statement lost: Jump to a statement that no longer exists.
  
  
• O - Invalid stream: Undocumented.
  
  
• P - FN without DEF: A user-defined function was called but no corresponding definition could be found.
  
  
• Q - Parameter error: A user-defined function was given the wrong number of arguments, or one of them is the wrong type (string instead of number or vice versa).
  
  
• R - Tape loading error: A file on tape was found but for some reason could not be read in, or would not verify.