Table of Contents

Locomotive BASIC

“It is practically impossible to teach good programming to students that have had a prior exposure to BASIC: as potential programmers they are mentally mutilated beyond hope of regeneration.”
Edsger W. Dijkstra.

Locomotive BASIC is a proprietary implementation of the BASIC programming language and was developped by Locomotive Software. It features dedicated commands for handling graphics, sounds, timers and files (on tape or disc). Additionnal commands can be easily added through the RSX system.

The Locomotive BASIC is located in the upper ROM 0 and usually starts as soon as the CPC/Plus is switched ON or reset, thus is the standard command line interface of the computer. The BASIC is also closely dependant on the Firmware routines. Newer BASIC (eg 1.1) can not run with older Firmware (eg. v1).

External links

Further informations about the Locomotive BASIC can be found on these websites:

Version history

BASIC 1.0

Locomotive BASIC 1.0 was developed in 1984 for the Zilog Z80 by Locomotive Software. When Amstrad was looking for a BASIC for their forthcoming CPC464 which was intended to be MOS Technology 6502 based, Locomotive Software convinced Amstrad to make the CPC Zilog Z80 based instead, to avoid a major rewrite of the BASIC Interpreter.

The CPC 464 was shipped with the Locomotive BASIC 1.0 (and a Z80 CPU :).

BASIC 1.1

Locomotive BASIC 1.1 was the enhanced version for the CPC664, CPC6128, 464Plus and 6128Plus computers.

New variable

DERR.

New commands

Modified commands

DATA

DATA statements can now appear anywhere within a line. With BASIC 1.0, they had to be at the end of a line.

AUTO

In AUTO mode, when a line number generated already exists, the content of the line will be displayed on the screen and may be edited. With BASIC 1.0, a star (*) is inserted after the line number to indicate that this particular line already exists.

DRAW/PLOT

All the absolute and relative DRAW/PLOT commands take an optional <ink mode> parameter to determine how the ink breing written interacts with that already on the graphics screen (Normal, XOR, AND and OR). With BASIC 1.0, this could be selected through control codes.

Improvements

  • Better handling of string arguments to RSXs.
    With BASIC 1.0, string parameter have to be passed by variable reference (eg. a$=“*.BAS”:|DIR,@a$).
    With BASIC 1.1, the string parameter can be given directly (eg. |DIR,”*.BAS”).
  • Better garbage collection.
  • Various bugfixes.

Revisions

Despite the fact that the Locomotive BASIC keeps displaying 1.1 on startup, several revisions exist if we refer to the ROM header:

AFAIK the differences, if any, between the v1.10 and later versions are undocumented. You can check the version installed on your own CPC with a small BASIC listing. (And if you discover a version not listed here, eg. v1.22, spread the infos and the ROM dump! Thanx!)

Notation.

Special Characters

Prefix

  • & or &H Prefix for hexadecimal constant.
  • &X Prefix for binary constant.
  • : Separates statements typed on the same line.
  • # Prefix for stream director.
  • @ Prefix a variable name to get it's memory pointer (use à on a french keyboard).

Postfix

  • % Postfix for integer.
  • ! Postfix for real.
  • $ Postfix for string.

Although the postfixes for numeric variable (integer% or real!) are optionnal (you can assign any numeric value to a non-postfixed variable name, eg. a=3.6 instead of a!=3.6), it is recommanded to use the postfixes as much as possible. This will save the system from the hassle to determine the type of the variable (integer or real) before manipulating it. You will gain some extra speed and also save some memory. Also see DEFINT, DEFREAL, DEFSTR.

Data types

Strings

Strings may be from 0 to 255 characters long, and are expressed as <string expression>. Strings may be appended to one another using the + operator, as long as the resulting <string expression> is less than 255 characters long.

Numeric

Numeric data can be either Integer or real. Integer data is held in the range – 32768 to 32767 and real data is held to a little over nine digits of precision in the range 1.7E+38 with the smallest value above zero approximately 2.9E-39.

A <numeric expression> is any expression that results in a numeric value: it may simply be numbers, or it may be a numeric variable, or it may be numbers operated on by variables. Just about anything that is not a <string expression>. A <stream expression>, refers to a <numeric expression> which identifies the screen, printer or cassette where the text is required to stream.

An improper argument means that a <numeric expression>, has returned a value that is outside the range defined as permissable in that situation or that a command parameter is invalid in some way and that BASIC has not accepted this as valid input.

Keywords

Keyword types

  • COMMANDS: operations that are executed directly.
  • FUNCTIONS: operations that are invoked as arguments in an expression.
  • VARIABLES: hold a value defined by the system.
  • OPERATORS: acting upon mathematical arguments.

Brackets

() are required as part of the command or function. Other types of brackets used in the KEYWORD description are for the purposes of the description, and should not be typed as part of the line:

  • [] enclose optional items.
  • <> enclose various expressions which are described in the subsequent description.

Quotes

Only ” ” form part of the actual BASIC program structure and italic is used to emphasise or highlight certain aspects of the description.

Entering

BASIC converts all keywords entered in lower case letters into UPPER CASE when a program is LISTed. The examples shown here use UPPER CASE, since this is how the program will appear when LISTed - if you enter using lower case , you will be able to spot typing errors more readily since the mistyped keyword will still be displayed in lower case when LISTed.

Keywords are delimited by separators, since AMSTRAD BASIC allows you to bury keywords into variable names: eg end2 and LISTCODE are acceptable as variables in AMSTRAD BASIC.

ABS

Function
ABS(<numeric expression>)
Return value
Numeric.

Returns the absolute value of the given expression -which primarily means that negative numbers are returned as positive.

Example

PRINT ABS(-67.98) 
67.98 

Associated keywords

SGN.

AFTER

Command
AFTER <integer expression>[,<integer expression>] GOSUB <line number>

Invoke a subroutine after a given time period has elapsed. The first <integer expression>, indicates the period of the delay, in units of 1/50 second, and the second <integer expression>, (in range 0 to 3), indicates which of the four available delay timers should be used.

Example

AFTER 200,2 GOSUB 320  

Associated keywords

AND

Operator
<argument> AND <argument>

Performs bit-wise boolean operation on integers. Result is 0 unless both arguments are 1.

Example

PRINT 1 AND 1
 1
PRINT 1 AND 0
 0
PRINT 0 AND 0
 0

Associated keywords

NOT, OR, XOR.

ASC

Function
ASC(<string expression>)
Return value
Numeric.

Gets the numeric value of the first character of a string as long as ASCII characters are used.

Example

PRINT ASC("X") 
88 

Associated keywords

CHR$.

ATN

Function
ATN(<numeric expression>)
Return value
Numeric.

Calculates the arc-tangent (forcing the numeric expression) to a real number ranging from -PI/2 to +PI/2 of the value specified.

Example

PRINT ATN(1) 
0.785398163 

Associated keywords

SIN, COS, TAN, DEG, RAD.

Related Firmware routines

Arcsin and Arcos

To calculate the inverse sinus and cosinus of a real number, here are some Locomotive BASIC friendly equivalents.

Arcos

With a ranging from 0 to PI:

 arcos(a) = atn(-a / sqr(-a*a+1)) + pi/2

If a ranges from -PI to 0, the sign of the result must be inversed.

Arcsin

With a ranging from -PI/2 to PI/2:

arcsin(a) = atn(a / sqr(-a*a+1))

AUTO

Command
AUTO [<line number>l[,<increment>]
Compatibility
With BASIC 1.0, where an existing program line is in danger of being overwritten, BASIC inserts a star * after the line number generated as a warning.
With BASIC 1.1, if a line number is generated which is already in use, then the contents of the line will be displayed on the screen and may be edited if required.

Generate line numbers automatically. The <line number>, sets the first line to be generated, in case you want to add to the end of an existing program. The value of the <increment> between line numbers, and the first line number to be generated, both default to 10 if not specified.

Example

AUTO 100,50 

BIN$

Function
BIN$(<unsigned integer expression>[,<integer expression>])
Return value
String.

Produces a string of binary digits that represents the value of the <unsigned integer expression>, filling with leading zeros to the number of digits instructed by the second <integer expression>.

Example

PRINT BIN$(64,8) 
01000000 

Associated keywords

BORDER

Command
BORDER <colour>[,<colour>]

To change the colour of the border on the screen. If two colours are specified, the border alternates between the two at the rate determined in the SPEED INK command, if given. The range of border colours is 0 to 26.

Example

BORDER 3,2 

Associated keywords

Related Firmware routines

CALL

Command
CALL <address expression> ,[<list of: <parameter>]

Allows an externally developed sub-routine to be invoked from BASIC. Use with caution, not a function for the inexperienced to experiment with.

Example

The following example is a relatively harmless CALL, since it waits for the next frame flyback, which is particularly useful for tidying up the movement of characters around the screen when producing animation effects.

CALL &BD19 

Associated keywords

UNT.

CAT

Command
CAT

Causes BASIC to start reading the directory of the current drive (cassette or disc) and to display the names of all files found.

This does not affect the program currently in memory, and so may be used to verify a program that has just been saved before altering the program memory.

Tape

CAT command on tape (CPC 464) The Command asks you to play the cassette, and on finding a program responds:

FILENAME BlockNumber Flag Ok

Flags indicate the type of recording made:

  • $: a BASIC program file
  • %: a Protected BASIC file
  • *: an ASCII text file
  • &: a Binary file

Other characters may occur in this column if the file was not produced by BASIC.

Disc

CAT command on disc (CPC 664/6128)

Associated keywords

Related Firmware routines

CHAIN

Command
CHAIN <file name>[, <line number expression>]

CHAIN loads a program from disc or cassette into the memory; replacing the existing program. The new program then commences running, either from the beginning, or from the line specified in the optional <line number expression>.

Protected files (saved with the ',P' type) can be loaded and run by chaining.

Example

CHAIN "TEST", 350

Associated keywords

CHAIN MERGE

Command
CHAIN MERGE <file name>[,<line number expression>][, DELETE <line number range>]

CHAIN MERGE merges a program from disc or cassette into the current program memory. The <line number expression>, indicates the line number from which execution is to begin once the new program is chain merged. In the absence of <line number expression>, BASIC will default to the lowest line number available.

  • If no file name is stated, then BASIC will attempt to merge the first valid file en countered on tape.
  • If the first character of the filename is a ! , then it is removed from the filename, and suppresses the usual messages generated by the cassette reading process.
  • CHAIN MERGE retains all current variables although User Functions and open files are discarded.
  • ON ERROR GOTO is turned off.
  • A RESTORE is implemented.
  • The DEFINT, DEFREAL & DEFSTR settings are reset.
  • All active FOR, WHILE and GOSUB commands are forgotten.
  • Protected files will not merge.

Associated keywords

CHR$

Function
CHR$(<integer expression>)
Return value
String.

Converts <integer expression> in the range 0 to 255, to its character string equivalent. Programming is 10% science, 20% ingenuity, and 70% getting the ingenuity to work with the science.

Note that 0 to 31 are control characters.

Example

PRINT CHR$(100) 
 d 

Associated keywords

CINT

Function
CINT(<numeric expression>)
Return value
Numeric.

Converts the given value to a rounded integer in the range -32768…32767.

Example

10 n=578.76543
20 PRINT CINT(n)
RUN
579

Associated keywords

Related Firmware routines

CLEAR

Command
CLEAR

Clears all variables to zero or null. All open files are abandoned, all arrays and user functions are erased, and BASIC is set to radians mode of calculation.

CLEAR INPUT

Command
CLEAR INPUT
Compatibility
Only available with BASIC 1.1

Discards all previously typed input from the keyboard, still in the keyboard buffer.

Example

To see the effect of this command, RUN the following program and type letters when asked to do so. Then delete line 50 of the program and RUN again, noting the difference.

10 CLS
20 PRINT "Type in letters now!"
30 FOR t=1 TO 3000
40 NEXT
50 CLEAR INPUT
run

Associated keywords

Related Firmware routines

Downgrade for BASIC 1.0

You can achieve a similar function on the CPC 464 by calling the Firmware routine KM RESET:

CALL &BB03

CLG

Command
CLG[<masked ink>]

Clears the graphics screen to the graphics paper colour. If the <ink> is specified, the graphics paper is set to that value.

Associated keywords

Related Firmware routines

CLOSEIN

Command
CLOSEIN

Close any input file from disc or cassette. Commands such as NEW and CHAIN MERGE will also abandon any open files.

Associated keywords

Related Firmware routines

CLOSEOUT

Command
CLOSEOUT

Close any output file to disc or cassette.

Associated keywords

Related Firmware routines

CLS

Command
CLS [#<stream expression>]

Clear the given screen stream (window) to its paper ink. If no <stream expression> is given, screen stream #0 is cleared.

Related Firmware routines

CONT

Command
CONT

Continue program execution after a *Break*, STOP or END, as long as the program has not been altered. Direct commands may be entered.

COPYCHR$

Function
COPYCHR$(#<stream expression>)
Return value
String.
Compatiblity
Only available with BASIC 1.1

COPies ChaRacter from the current position in the stream (which MUST be specified). If the character read is not recognized, a null string is returned.

Example

The following eample copies a character from location 1,1 (top left) and reproduces it at location 1,20.

10 CLS
20 PRINT "top corner"
30 LOCATE 1,1
40 a$=COPYCHR$(#0)
50 LOCATE 1,20
60 PRINT a$
run

Associated keywords

Related Firmware routines

Downgrade for BASIC 1.0

A short MC routine is required to simulate the COPYCHR$ command with BASIC 1.0. The following BASIC program will install such a routine in memory (at address &A000, but it can be relocated wherever you want, to some extent):

10 addr=&A000:FOR i=0 to 16:READ a$:POKE addr+i,VAL("&"+a$):NEXT
20 DATA dd,7e,00,cd,b4,bb,f5,cd,60,bb,32,FF,BF,f1,c3,b4,bb

Once the MC routine is installed, you can use it like this:

10 ' PRINT COPYCHR$(#0) for BASIC 1.0
20 CALL &A000,0:PRINT CHR$(PEEK(0))

It takes <stream expression> as a parameter and poke the ASCII code of the caracter read in memory at the address &0000. You just have to PEEK the addresss to get the result.

If you're curious, the source code of the MC routine given above is that:

_txt_str_select	equ &BBB4
_txt_rd_char	equ &BB60
 
		; Select the stream passed in parameter
		ld a,(ix+0)
		call _txt_str_select
		; Save the previously selected stream
		push af
		; Read the char at the current cursor position
		call _txt_rd_char
		; Save the ASCII code read into RAM
		ld (0),a
		; restore the stream
		pop af
		jp _txt_str_select

See TXT RD CHAR and TXT STR SELECT in the Firmware guide.

COS

Function
COS(<numeric expression>)
Return value
Numeric.

Calculates the COSINE of a given value. The function defaults to radian measure unless specifically instructed otherwise by the DEG command.

Example

? COS(34) 
-0.848570274 
Ready 
deg:? cos(34) 
0.829037573 

Note in the above example the use of ? shortform for PRINT, and the use of lowercase entry for keywords - a feature fully compatible with AMSTBAD BASIC.

Associated keywords

SIN, TAN, ATN, DEG, RAD.

Related Firmware routines

CREAL

Function
CREAL(<numeric expression>)
Return value
Numeric.

Converts a value to a real number (As opposed to integer).

Example

5 DEFINT n 
10 n=75.765 
20 d=n/34.6 
30 PRINT d  
40 PRINT CREAL(n) 
50 PRINT n/55.4 
run 
2.19653179 
76 
1.37184116 
Ready 

Associated keywords

CINT.

Related Firmware routines

CURSOR

Command
CURSOR [<system switch>][,<user switch>]
Compatibility
Only available with BASIC 1.1

Sets the system switch or the user switch to the cursor, ON or OFF. The <system switch> and <user switch> parameters must be either 0 (OFF) or 1 (ON).

The cursor is displayed whenever both the <system switch> and <user switch> are ON (1). The <system switch> is automatically turned OFF when printing text to screen.

Either swtich parameter may be omitted, but not both. If a switch parameter is omitted, that particular switch state is not changed.

Example

In the following INKEY$ command, where the cursor is not normally visible, the cursor has been turned ON by the <system switch> setting of 1 (in line 10).

10 CURSOR 1
20 PRINT "question?";
30 a$=INKEY$:IF a$="" THEN 30
40 PRINT a$
50 CURSOR 0
run

DATA

Command
DATA <list of constant>
Compatibility
With BASIC 1.0, DATA statements have to be at the end of the line.
With BASIC 1.1, DATA statements can appear anywhere within a line.

Declares constant data for use within a program. One of the most widely used features of BASIC that lumps constant data in DATA statements for retrieval as required. The data type must be consistent with the variable invoking it. A DATA statement may appear anywhere in a program.

Example

10 REM Proofreader 
20 DIM Proofer$(5) 
30 DIM ProoferSurname$(5)  
40 FOR n=l to 5 
50 READ Proofer$(n)  
60 READ ProoferSurname$(n)  
65 PRINT Proofer$(n);" "ProoferSurname$(n)   
70 DATA Bob,Smith,Dicky,Jones,Malcolm,Green,Alan,Brown,Ivor,Curry  
90 NEXT

Associated keywords

DEC$

Function
DEC$(<numeric expression>,<format template>)
Return value
String.
Compatiblity
Only available with BASIC 1.1

Return a DECimal string representation of the <numeric expression>, using the specified <format template> to control the print format of the resulting string.

The format template may contain ONLY the characters:

+ - £ $ * # , . ^

Example

PRINT DEC$(1234567,8901, "#########,.##")
1,234,567.89

Associated keywords

Downgrade for BASIC 1.0

The command is undocumented and requires two opening brackets:

PRINT DEC$((1234567,8901, "#########,.##")
1,234,567.89

You can also use PRINT USING too:

PRINT USING("######,. ##");STR$(1234567,8901)

DEF FN

Command
DEF FN <name> [(<formal parameters>)]=<general expression>

BASIC allows the program to define and use simple value returning functions. DEF FuNction is the definition part of this mechanism and creates program-specific function which works within the program in the same way as a function such as COS operates as a built-in function of BASIC.

It may be invoked throughout the program. Variable types must be consistent and the DEF FuNction command should be written in part of the program outside the execution loop.

Example

10 DEF FNinterest(principle)=l.l4*principle  
20 INPUT "What is the principle sum";principle  
30 PRINT "The amount owing plus interest after one year is ";FNinterest(principle)  

DEFINT

DEFSTR

DEFREAL

Command
DEF<type> <range(s) of letters>

Define default variable types where <type> is integer, real or string. The variable will be set according to the first letter of the variable's name – which may be either upper or lower case.

Example

DEFINT I-N 
DEFSTR A,W-2 
DEFREAL  

Associated keywords

DEG

Command
DEG

Set degrees mode. The default condition is for functions such as SIN and COS is to assume radian measure for numeric data. The command sets to degree mode until instructed otherwise by a CLEAR or RAD - or if any new program is loaded.

Associated keywords

RAD.

Related Firmware routines

DELETE

Command
DELETE <line number range>

A command that removes part of the current program as defined in the line number range, expression. Not recoverable if issued in error, so use with care, and check for mistyping before entering.

Example

DELETE 100-200 

Associated keywords

NEW.

DERR

Variable
DERR
Type
Numeric.
Compatiblity
Only available with BASIC 1.1.

Report the last error code returned by the disc operating system. The value of DERR may be used to ascertain the particular Disc ERRor that occured. See the listing of error messages.

Associated keywords

DI

Command
DI

Disable interrupts (other than the *Break* interrupt) until re-enabled explicitly by EI or implicitly by the RETURN at the end of an interrupt GOSUB routine.

Used when the program wishes to get on literally without interruption – for example when two routines within a program are competing for use of resources. In the example above, the main program and the interrupt subroutine are competing for the use of the graphics display.

Example

10 CLS 
20 TAG 
30 EVERY 10 GOSUB 100  
40 Xl=RND*320:X2=RND*320  
50 Y=200+RND*200 
60 FOR x=320-X1 TO 320+X2 STEP 2 
70 DI:PLOT 320,0,1:MOVE X-2,Y:PRINT " ";:MOVE X,Y: "#";:EI
80 NEXT 
90 GOTO 40 
100 MOVE 320,0 
110 DRAW X+8,Y-16,0 
120 RETURN 

Associated keywords

EI.

DIM

Command
DIM <list of: subscripted variable>

Allocate space for arrays and specify maximum subscript values.

Basic must be advised of the space to be reserved for an array, or it will default to 10. Once set either implicitly or explicitly, the size of the array may not be changed, or an error will result.

A subscripted variable, is one where the same variable name can take a series of values as set out in the list of integer numbers that comprise the dimension list.

The first number in the dimension list may be thought of as levels in a multistorey car park, and the subsequent numbers, the number of parking bays etc. A full understanding of arrays is a major element in advanced BASIC programming. The size of an array is limited only by available memory, and the programmers ability to keep track of the entries in the dimension list.

Example

10 CLS:PRINT "Enter 5 names....":PRINT
20 DIM B$(5)
30 FOR N=l TO 5
40 PRINT "Name"N"please";
50 INPUT B$(N)
60 NEXT
70 FOR N=l TO 5
80 PRINT "How wise of you ";B$(N);" to buy a CPC464"  
90 NEXT

Associated keywords

DRAW

Command
DRAW <x co-ordinate>,<y co-ordinate>[,<ink>][,<ink mode>]
Compatibility
<ink mode> is only available with BASIC 1.1

Draws a line on the screen from the current graphics cursor position to an absolute position. The co-ordinate positions remain unchanged between the three different screen modes. The <ink> in which to draw the line may be specified (in the range 0 to 15).

The optional <ink mode> determines how the ink being written interacts with that already on the graphics screen. The four <ink mode>s are:

  • 0: Normal
  • 1: XOR (eXclusive OR)
  • 2: AND
  • 3: OR

Example

DRAW 200,200,13 

Associated keywords

Related Firmware routines

Downgrade for BASIC 1.0

The <ink mode> can be selected by using the ETB control code:

10 ' DRAW 320,400,1,3
20 PRINT CHR$(23)CHR$(3):DRAW 320,400,1

DRAWR

Command
DRAWR <x offset>,<y offset>[,<ink>][,<ink mode>]
Compatibility
<ink mode> is only available with BASIC 1.1

To draw a line on the screen from the current graphics cursor position to a position relative to it. The <ink> in which to draw the line may be specified (in the range 0 to 15).

The optional <ink mode> determines how the ink being written interacts with that already on the graphics screen. The four <ink mode>s are:

  • 0: Normal
  • 1: XOR (eXclusive OR)
  • 2: AND
  • 3: OR

Example

DRAWR 200,200,13 

Associated keywords

Related Firmware routines

Downgrade for BASIC 1.0

The <ink mode> can be selected by using the ETB control code:

10 ' DRAWR 20,40,1,3
20 PRINT CHR$(23)CHR$(3):DRAWR 20,40,1

EDIT

Command
EDIT <line number>

Edit a program line by calling for a specific line number.

Example

EDIT 110 

Associated keywords

LIST.

EI

Command
EI

To Enable Interrupts disabled by a DI command.

Associated keywords

DI.

ELSE

(See IF)

END

Command
END

End of program. An END is implicit in AMSTRAD BASIC as the program passes the last line of instruction. END closes all cassette files and returns to the direct mode. Sound queues will continue until empty.

Associated keywords

STOP.

ENT

Command
ENT <envelope number>[,<envelope section>[,<envelope section>,…]]

Sets the Tone ENvelope specified in the <envelope section> (in the range 1 to 15), which is used in conjunction with the SOUND command. If the <envelope number> is negative (in the range -1 to -15), the envelope repeats until the end of the duration of the SOUND command.

Each of the <envelope section>s may contain either 2 ou 3 parameters.

Enveloppe section with 3 parameters

If 3 parameters are used, these are:

Parameter 1: <number of step>

This parameter specifies how many different steps of tone (pitch) you want the sound to pass through during the envelope section. For example, in a section of a note which lasts 10 seconds, you may wish to have 10 tone steps of 1 second each. In such case, the <number of steps> parameter used should be 10.

The available range of <number of steps> is 0 to 239.

Parameter 2: <step size>

This parameter myst be in the range -128 to +127. Negative steps make the pitch of the note higher; positive steps make it lower. The shortest tone period is 0.

Parameter 3: <pause time>

This parameter specifies the time between steps in 0.01 second (hundreths of a second) units. The range of <pause time> numbers is 0 to 255 (where 0 is treated as 256), which means that the longest time between steps is 2.56 seconds.

Enveloppe section with 2 parameters

Parameter 1: <tone period>

This parameter gives a new absolute setting for the tone period (See parameter 2 of the SOUND command).

Parameter 2: <pause time>

This parameter specifies the time between steps in 0.01 second (hundreths of a second) units. The range of <pause time> numbers is 0 to 255 (where 0 is treated as 256), which means that the longest time between steps is 2.56 seconds.

General

Note that the total lenght of all the <pause time>s shouldd not be greater than the <duration> parameter in the SOUND command, otherwise the sound will finish before all the tone steps have been passed through (In such a case, the remaining contents of the tone envelope are discarded).

Likewise, if the <duration> parameter in the SOUND command is longer than the total lenght of all the <pause time>s, the sound will continue after all of the tone steps have been passed through, and will remain constant at the final tone pitch.

Up to 5 different <envelope section>s (each made up of the above 2 or 3 parameters) may be used in an ENT command.

The first step of a tone envelope is executed immediately.

Each time a give tone envelope is set, it's previous value is lost.

Specifying an <enveloppe number> with no <envelope section>s cancels any previous setting.

Example

10 ENT 1,10,-50,10,10,50,10
20 SOUND 1,500,200,10,,1
run

Associated keywords

Related Firmware routines

ENV

Command
ENV <envelope number>[,<envelope section>][,<envelope section>][,…]

Sets the volume envelope specified in the <envelope number> (in the range 1 to 15), which is used in conjunction with the SOUND command.

Each of the <enveloppe section>s mai contain either 2 or 3 parameters:

Enveloppe section with 3 parameters

Parameter 1: <number of step>

This parameter specifies how many differents steps of volume you want the sound to pass through during the envelope section. For example, in a section of a note which lasts 10 seconds, you may wish to have 10 volumes steps of 1 second each. In such a case, the <number of steps> parameter used should be 10.

The available range of <number of steps> is 0 to 127.

Parameter 2: <step size>

Each step can vary in size from a volume level of 0 to 15 with respect to the previous step. The 16 different volume levels are the same as thos you will hear in the SOUND command. However, the <step size> parameter used can be between -128 and +127; the volume level re-cycling to 0 after each 15.

Parameter 3: <pause time>

This parameter specifies the time between steps in 0.01 second unit. The range of the <pause time> is 0 to 255 (where 0 is treated as 256), which means that the longest time between steps is 2.56 seconds.

Enveloppe section with 2 parameters

Parameter 1: <hardware envelope>

This parameter specifies the value to send to the envelope shape register of the soundchip.

Parameter 2: <envelope period>

This parameter specifies the value to send to the envelope period registers of the soundchip.

Knowledge of hardware is assumed when using hardware envelopes. Unless you have such knowledge, it is suggested that you use a software envelope incorporating a suitable <pause time> parameter.

General

Note that the total lenght of all the <pause time>s should not be greater than the <duration> parameter in the SOUND command, otherwise the sound will finish before all the volume steps have been passed through (In such a case, the remaining contents of the volume envelope are discarded).

Likewise, if the <duration> parameter in the SOUND command is longer than the total lenght of all the <pause time>s, the sound will continue after all the volume steps have been passed through, and will remain constant at the final level.

Up to 5 differents <envelope section>s (each made up of the above 2 or 3 parameters) may be used in an ENV command.

The first step of a volume envelope is executed immediately.

Each time a given volume envelope is set, it's previous content is lost.

Specifying an <envelope number> with no <envelope section>s cancels any previous setting.

Example

10 ENV 1,100,2,20 
20 SOUND 1,100,1000,4,1 

Associated keywords

Related Firmware routines

EOF

Variable
EOF
Return value
Numeric (-1:true or 0:false).

Tests to see if the cassette input is at the end of the file. Returns – 1 (true) at the end, otherwise 0 (false).

Example

PRINT EOF  
-1 

Associated keywords

Related Firmware routines

ERASE

Command
ERASE list of: <variable name>

When an array is no longer required, it may be ERASEd and the memory used be reclaimed ready for other use.

Example

ERASE A,B%

Associated keywords

DIM.

ERL

Variable
ERL
Return value
Numeric.

Reports the Line number of the last ERror encountered.

Example

In the following example you will see that the error is in line 20, and has been reported so by the ERL variable.

10 ON ERROR GOTO 30
20 GOTO 10000
30 PRINT "error is in line';ERL
40 END
run

Associated keywords

ERR

Variable
ERR
Return value
Numeric.

Reports the number of the last ERRor encountered. See the list of error message.

Example

In the following example you will see that ERRor number 8 is Line does not exist error.

GOTO 500
Line does not exist
Ready
PRINT ERR
 8

Associated keywords

ERROR

Command
ERROR <integer expression>

Invokes the error specified in the <integer expression>. The error may be one already used and recognised by BASIC, in which case the action taken is the same as would be taken if such an error had been detected by BASIC.

Error numbers beyond those recognised by BASIC may be used by the program to signal its own errors.

Example

10 ON ERROR GOTO 100
20 INPUT "enter one character";a$
30 IF LEN(a$)<>1 THEN ERROR 100
40 GOTO 20
100 IF ERR=100 THEN 110 ELSE 130
110 PRINT CHR$(7)
120 PRINT "I said ONE character!"
130 RESUME 20
run

Associated keywords

EVERY

Command
EVERY <integer expression>[,<integer expression>] GOSUB <line number>

The EVERY command allows a BASIC program to arrange for subroutines to be called at regular intervals. Four delay timers are available, specified by the 2nd <integer expression> in the range 0 to 3 each of which may have a subroutine associated with it.

Example

EVERY 500,2 GOSUB 50

Associated keywords

EXP

Function
EXP(<numeric expression>)
Return value
Numeric (Real).

Calculates E to the power given in numeric expression - where E is approximately 2.7182818 - the number whose natural logarithm is 1.

Example

PRINT EXP(6.876)
968.743625

Associated keywords

LOG.

Related Firmware routines

FILL

Command
FILL <ink>
Compatibility
Only available with BASIC 1.1

Fills an arbitrary area of the graphics screen. The edges of the area are bounded to lines drawn either in the current graphics pen ink or in the ink being used to fill (in the range 0 to 15).

The fill starts from the current graphics cursor position. If this position lies on an edge, nothing will be filled.

Example

10 MODE 1:sea=2:MOVE 0,200,3
20 DRAWR 100,-100:DRAWR 220,0
30 MOVER 10,0;DRAWR 220,0
40 DRAWR 100,100:MOVE 0,0
50 FILL sea
run

Associated keywords

Related Firmware routines

FIX

Function
FIX(<numeric expression>)
Return value
Numeric (Integer).

Unlike CINT, FIX merely removes the part of the numeric expression, to the right of the decimal point, and leaves an integer result, rounding towards zero.

Example

PRINT FIX(9.99999)
9

Associated keywords

Related Firmware routines

FOR

Command
FOR <simple variable> = <start> TO <end> [STEP <size>]

Execute a body of program a given number of times, stepping a control variable between a start and an end value. If not specified, STEP defaults to 1.

Example

FOR DAY=1 to 5 STEP 2:PRINT "Hello World!":NEXT

Associated keywords

FRAME

Command
FRAME
Compatiblity
Only available with BASIC 1.1

Synchronises the writing of the graphics on the screen with the frame flyback of the display. The overall effect of this is that character or graphics movement on the screen will appear to be smoother, without flickering or tearing.

Example

10 MODE 0
20 PRINT "FRAME off"
30 TAG
40 MOVE 0,200
50 FOR x=0 TO 500 STEP 4
60 IF f=1 THEN FRAME
70 MOVE x,200
80 PRINT " ";CHR$(143);
90 NEXT
100 IF f=1 THEN RUN
110 CLS
120 TAGOFF
130 PRINT "FRAME on"
140 f=1
150 GOTO 30
run

Related Firmware routines

Downgrade for BASIC 1.0

With BASIC 1.0, two alternatives for the FRAME command exist:

  • CALL &BD19 (call the firmware function MC WAIT FLYBACK).
  • WAIT &F500,1 (wait until the frame flyback bit at PPI Port B is set).

FRE

Function
FRE(<numeric expression>)
FRE(<string expression>)
Return value
Numeric.

Establishes how much memory remains unused by BASIC. The form FRE(””) forces a garbage collection before returning a value for available space.

Examples

PRINT FRE(0)
PRINT FRE("")

GOSUB

Command
GOSUB <line number>

Call a BASIC subroutine by branching to the specified line number.

Example

GOSUB 210

Associated keywords

GOTO

Command
GOTO <line number>

Branch to specified line number.

Example

GOTO 90

GRAPHICS PAPER

Command
GRAPHICS PAPER <ink>
Compatibility
Only available with BASIC 1.1

Sets the <ink> of the graphics paper, ie. the area behind graphics drawn on the screen. When drawing continuous lines, the graphics papers will not be seen.

The graphics paper's ink (in the range 0 to 15) is used for the paper area of characters written when TAG is in operation, and as the default when clearing the graphics window, using CLG.

Example

In the following example, the MASK command enables a broken line to be drawn, and the graphics paper to be seen.

10 MODE 0
20 MASK 15
30 GRAPHICS PAPER 3
40 DRAW 6400
run

Associated keywords

Related Firmware routines

GRAPHICS PEN

Command
GRAPHICS PEN [<ink>][,<background mode>]
Compatibility
Only available with BASIC 1.1

Set the <ink> (in the range 0 to 15) to be used for drawing lines and plotting points. The graphics <background mode> can also be set to either:

  • 0: Opaque background.
  • 1: Transparent background.

Transparent background affects the graphics paper of characters written with TAG on, and the gaps in dotted lines.

Either parameter may be omitted, but not both. If a parameter is omitted, that particular setting is not changed.

Example

10 MODE 0
20 GRAPHICS PEN 15
30 MOVE 200,0
40 DRAW 200,400
50 MOVE 639,0
60 FILL 15
run

Associated keywords

Related Firmware routines

HEX$

Function
HEX$(< unsigned integer expression>[,<integer expression>])
Return value
String.

Converts the number given into Hexadecimal form. The second <integer expression> can be used to specify the minimum length of the result.

Example

PRINT HEX$(65534)
FFFE

Associated keywords

HIMEM

Variable
HIMEM
Return value
Numeric.

Gives the address of the highest byte of memory used by BASIC, and can be used in numeric expressions in the usual way. Before resetting the highest byte of available memory using the MEMORY command, it is advisable to issue the command:

mm=HIMEM

You will thereafter be able to return to the previous memory capacity by issuing the command:

MEMORY mm

Example

?HIMEM 
43903 

Associated keywords

IF

Command
IF <logical expression> THEN <option part> [ELSE <option part>]
IF <logical expression> GOTO <line number> [ELSE <option part>]

A very widely used command that is used to conditionally determine branch points in a program. The logical part is evaluated, and if true the THEN or GOTO part is executed, if false, the program skips to the ELSE part, or merely passes onto the next line. The statements may be nested to any depth, limited by line length. The IF is terminated by the line end. It is not permissable to have further statements that are independent of the IF on the same line.

Example

IF A>B THEN A=C ELSE A=D  
IF A>B GOTO 1000 ELSE 300 

Associated keywords

INK

Command
INK <ink>,<colour>[,<colour>]

Assigns colour(s) to a given ink. The <ink> parameter describes the ink reference, which must be an integer expression in the range 0 to 15, for use in the appertaining PEN or PAPER command. The first <colour> parameter should be an integer expression yielding a colour value in the range 0 to 26. If an optional second <colour> is specified, the ink alternates between the two colours, at a rate determined by SPEED INK command.

Depending on the current screen mode, a number of INKs are available.

Example

INK 0,6,3

Associated keywords

Related Firmware routines

INKEY

Function
INKEY(<integer expression>)
Return value
Numeric.

This function interrogates the keyboard to report which keys are being pressed. The keyboard is scanned at 1/50 sec. The function is particularly useful for spotting Y/N responses, since the state of shift is not required according to one of the interpretation options.

[SHIFT] and [CTRL] are identified as follow:

Value returned[SHIFT][CTRL]Specified key
-1 ignored ignored UP
0 UP UP DOWN
32 DOWN UP DOWN
128 UP DOWN DOWN
160 DOWN DOWN DOWN

Example

The following example detects when [SHIFT] and V are pressed together.

10 CLS:IF INKEY(55)=32 THEN  30 ELSE 20 
20 CLS:GOTO 10 
30 PRINT "You're pressing [ SHIFT] and V" 
40 FOR t=l TO 1000:NEXT:GOTO 10  

Associated keywords

Related Firmware routines

INKEY$

Variable
INKEY$
Return value
String.

Reads a key from the keyboard to provide operator interaction without hitting [ENTER] after every answer. If there is a key pressed, then the function responds - if no key is pressed, it continues to return an empty string which is used to loop until a valid input is detected for processing.

Example

10 CLS 
20 PRINT "Are you clever (y or n) ?"  
30 a$=INKEY$: IF a$="" GOTO 30  
40 IF a$="N" OR a$="n" THEN PRINT "You must have been to buy me!":END  
50 IF a$="Y" OR a$="y" THEN PRINT "You're too modest!!!":END  
60 GOTO 20

Associated keywords

Related Firmware routines

INP

Function
INP(<port number>)
Return value
Numeric.

A function that returns the input value from the I/O port specified in the address.

Example

PRINT INP(&F500)

Associated keywords

OUT, WAIT.

INPUT

Command
INPUT [#<stream expression>][;][<quoted string>,]<list of: [variable]>

Reads data from the stated stream. A semicolon after INPUT suppresses the carriage return typed at the end of the line being entered. A semicolon after the <quoted string> causes a question mark to be displayed. A comma suppresses the question mark. If an entry is made that is of the wrong type (eg a letter O was typed instead of a 0 in a numeric expression, then BASIC will prompt with:

?Redo from start

… and the original prompt text that you entered.

All responses must be terminated with an [ENTER]. The semicolon immediately after the <stream expression> has the effect of suppressing the carriage return typed at the end of the line being entered, leaving the cursor at the end of the text just entered. Where a cassette stream is indicated, no prompt is generated, If one is specified, it will be ignored by the cassette software, so the same program may read from either stream.

One item will be read from the stream for each variable in the list given. It must be compatible with the type specified in the INPUT command, which is: a numeric variable, terminated either by comma, carriage return, white space or end of file.

Commas or [ENTER]s sent after trailing space will be ignored. Quoted strings will he read verbatim until terminated by double quotes, subsequent entries are ignored as for numeric values. Unquoted string items are terminated as in the case of numeric values.

Example

10 CLS 
20 INPUT "Give me two numbers, separated by a comma ";A,B 
30 IF A=B THEN PRINT "The two numbers are the same" 
40 IF A>B THEN PRINT A "is greater than" B  
50 IF A<B THEN PRINT A "is less than" B  
60 CLEAR:GOTO 20 

Associated keywords

INSTR

Function
INSTR([<integer expression>,<string expression>,<string expression>)
Return value
String.

Searches the first string expression, for the first occurance of the second string expression), where the optional number at the start indicates where to start the search - otherwise the search begins at the first character of the first string expression).

Example

 
PRINT INSTR(2,"BANANA","AN")  

Associated keywords

INT

Function
INT(<numeric expression>)
Return value
Numeric (Integer).

Rounds the number to the nearest lower integer, removing any fractional part. The same as FIX for positive numbers, but returns one less than FIX for negative numbers not already integers.

Example

PRINT INT(-1.995)  
-2

Associated keywords

Related Firmware routines

JOY

Function
JOY(<integer expression>)
Return value
Numeric.

The JOY function reads a bit-significant result from the joystick specified in the <integer expression> (either 0 or 1).

BitDecimal Joystick
0 1 Up
1 2 Down
2 4 Left
3 8 Right
4 16 Fire 2
5 32 Fire 1

Example

10 IF JOY(0) AND 8 THEN GOTO 100

Associated keywords

Related Firmware routines

KEY

Command
KEY <integer expression>,<string expression>

Fixes a new function key definition. There are thirty two keyboard expansion characters in the range 128-159. When one of these characters is read it is expanded into the string associated with it – although the total number of expansion characters cannot exceed 100. The KEY command associates a string with a given expansion character.

Example

KEY 140,"RUN"+CHR$(13)

Associated keywords

Related Firmware routines

KEY DEF

Command
KEY DEF <key number>,<repeat>[,<normal>[,<shifted>[,<control>]]]

DEFines the KEY values to be returned by the specified <key number> in the range 0 to 79. The <normal>, <shifted> and <control> parameters should contain the values required to be returned when the key is pressed, alone, together with [SHIFT], and together with [CTRL], respectively. Each of these parameters is optional.

the <repeat> parameter enables you to set the key auto-repeat function ON or OFF (1 or 0), the rate of auto-repeat being adjustable by use of the SPEED KEY command.

Example

The following example converts the N key to print the question mark character ? (Character number 63).

KEY DEF 46,1,63

To return the key to its normal function:

KEY DEF 46,1,110

where the character number 110 is the lower case n.

Associated keywords

KEY.

Related Firmware routines

LEFT$

Function
LEFT$(<string expression>,<integer expression>)
Return value
String.

Extracts characters to the left of, and including the position specified in the <integer expression> from the the given <string expression>. If the (string expression is shorter than the required length, the whole <string expression> is re-turned.

Example

10 CLS 
20 A$ = "AMSTRAD" 
30 B$ = LEFT$(A$,3) 
40 PRINT B$ 
RUN 
[SCREEN CLEARS] 
AMS 
Ready 

Associated keywords

LEN

Function
LEN(<string expression>)
Return value
Numeric.

Returns a number corresponding to the number of all types of characters, including spaces, in the <string expression>.

Example

A$="AMSTRAD":PRINT LEN(A$)  
7 

LET

Command
LET <variable>=<expression>

A remnant from early BASICS where variable assignments had to be seen coming . No use apart from providing compatibility with the programs supplied in early BASIC training manuals.

Example

LET x=100

With the AMSTRAD BASIC, the above example need only be typed:

x=100

LINE INPUT

Command
LINE INPUT [<#stream expression>,][;][quoted string; ]<string variable>

Reads an entire line from the stream indicated. The first optional semicolon suppresses the echo of carriage return / line feed. The default <stream expression> is, as always, #0 :screen.

Example

LINE INPUT A$ 
LINE INPUT "NAME"; N$

Associated keywords

LIST

Command
LIST [<line number range>][,#<strea m expression>]

List program lines to the given stream. 0 is the default screen, 8 is the printer.

LISTing may be suspended by pressing [ESC] once, and restarted by pressing the space bar. A double [ESC] will return BASIC to the direct mode.

Programs may be listed to previously defined windows to assist in debugging programs without overwriting the entire screen area. Listing may be performed from the start of a program to a given point, or from a specified line number to the program end, by omitting the first or last numbers in the line number range (see second example).

Example

LIST 100-1000,#1
LIST -200 or LIST 30-

LOAD

Command
LOAD <file name>[, <address expression>]

To read a BASIC program from disc or cassette into memory, replacing any existing program. Specifying the optional <address expression> will cause a binary file to be loaded at that address, rather than the address from which it was saved.

A protected BASIC program can NOT be loaded using the LOAD command as it will be immediately deleted from memory. Instead, use the RUN or CHAIN commands.

Example

LOAD "TITLE.SCR",&C000

LOCATE

Command
LOCATE [#<stream expression>,] <x coord>,<y coord>

Moves the text cursor at the stream indicated, to the position specified by the x and y co-ordinates, which are relative to the origin of the stream (WINDOW). Stream 0 is the default stream.

Example

10 MODE 1 
20 LOCATE 20,12 
30 PRINT CHRS(249) 

Associated keywords

Related Firmware routines

LOG

Function
LOG(<numeric expression>)
Return value
Numeric (Real).

Calculates the natural logarithm of numeric expression.

Example

?LOG(9999) 
9.21024037 

Associated keywords

Related Firmware routines

LOG10

Function
LOG10 ( <numeric expression> )
Return value
Numeric (Real).

Calculates the base 10 logarithm of <numeric expression>.

Example

?LOG10(9999)  
3.99995657  

Associated keywords

EXP,LOG.

Related Firmware routines

LOWER$

Function
LOWER$(<string expression>))
Return value
String.

Returns a new string expression the same as the input string expression but in which all upper case characters are converted to lower case. Useful for processing input where the answers may come in mixed upper/lower case.

Example

A$="AMSTRAD":PRINT LOWER$(A$)  
amstrad

Associated keywords

MASK

Command
MASK [<integer expression>l[,<first point setting>]
Compatibility
Only available with BASIC 1.1

Sets the mask or template to be used when drawing lines. The binary value of the <integer expression> in the range 0 to 255, sets the bits in each adjacent group of 8 pixels to ON (1) or OFF (0).

The <first point setting> determines whether the first point of the line is to be plotted (1) or not plotted (0).

Either of the parameters may be omitted, but not both. If a parameter is omitted, that particular setting is not changed.

Example

10 CLS:TAG
20 MASK 1:MOVE 0,250:DRAWR 240,0
30 PRINT "(binary 00000001 in mask)";
40 MASK 3:MOVE 0,200:DRAWR 240,0
50 PRINT "(binary 00000011 in mask)";
60 MASK 7:MOVE 0,150:DRAWR 240,0
70 PRINT "(binary 00000111 in mask)";
80 MASK 15:MOVE 0,100:DRAWR 240,0
90 PRINT "(binary 00001111 in mask)";
run

Associated keywords

MAX

Function
MAX(<list of: numeric expression>))
Return value
Numeric.

Extracts the largest value from the list of numeric expressions.

Example

10 n=66 
20 PRINT MAX(1,n,3,6,4,3)  

Associated keywords

MIN.

Related Firmware routines

MEMORY

Command
MEMORY <address expression>

Reset BASIC memory parameters to change the amount of BASIC memory available by setting the address of the highest byte. See the description of the keyword HIMEM. To examine the amount of memory, use the FRE command.

Example

MEMORY &20AA

Associated keywords

MERGE

Command
MERGE [<filename>]

Merge a program from disc or cassette into the current program memory. If tape deck is selected and no file name is stated, then BASIC will attempt to merge the first valid file encountered on tape. If the first character of the filename is a ! , then it is removed from the filename, and has the effect of suppressesing the usual messages generated by the cassette reading process.

Note that line numbers in the current program which exist in the new program to be merged will be over-written by the new program lines. If you wish to merge a program into memory without overwriting the current program, then the current program lines should be RENUM bered to a range different from those in the incoming program.

All variables, User Functions and open files are discarded. ON ERROR GOTO is turned off, a RESTORE is implemented and the DEFINT , DEFREAL & DEFSTR settings are reset.

Protected files will not merge.

Example

MERGE "PLAN"

Associated keywords

MID$

Function
MID$(<string>, <integer expression> [, <integer expression>]))
Return value
String.

MID$ specifies part of a string (a sub-string) which can be used either as the destination of an assignment (MID$ as a command) or as an argument in a string expression (MID$ as a Function). The first <integer expression> specifies the position of the first character of the sub-string.

The second <integer expression> specifies the length of the sub-string to be returned. If omitted, this extends to the end of the original string.

Example

A$="AMSTRAD":PRINT MID$(A$,2,4)
MSTR
A$="AMSTRAD":b$=MID$(A$,2,4):PRINT b$
MSTR

Associated keywords

MIN

Function
MIN(<list of: <numeric expression>))
Return value
Numeric.

Extracts the smallest value from the list of numeric expressions.

Example

PRINT MIN(3,6,2.999,8,9)
2.999

Associated keywords

MAX.

Related Firmware routines

MODE

Command
MODE <integer expression>

Change the screen mode (0,1 or 2), and clear the screen to INK 0, which may not be the current PAPER ink. All text and graphics WINDOWS are reset to the whole screen, and the text and graphics cursors homed to their respective origins.

Example

MODE 1

Associated keywords

Related Firmware routines

MOVE

Command
MOVE <x coord>,<y coord>[,<ink>][,<ink mode>]
Compatibility
<ink> and <ink mode> are only available with BASIC 1.1

To move the graphics cursor to a position specified by the absolute co-ordinates. YPOS and XPOS are the corresponding functions to establish the current graphics cursor position.

The optionnal <ink> parameter can be used to specify the graphic pen (in the range 0 to 15).

The optional <ink mode> determines how the ink being written interacts with that already on the graphics screen. The four <ink mode>s are:

  • 0: Normal
  • 1: XOR (eXclusive OR)
  • 2: AND
  • 3: OR

Example

MOVE 34,34

Associated keywords

Related Firmware routines

MOVER

Command
MOVER <x offset>,<y offset>[,<ink>][,<ink mode>]
Compatibility
<ink> and <ink mode> are only available with BASIC 1.1

To move the graphics cursor to a position relative to the current co-ordinates. YPOS and XPOS are the corresponding functions to establish the current graphics cursor position.

The optionnal <ink> parameter can be used to specify the graphic pen (in the range 0 to 15).

The optional <ink mode> determines how the ink being written interacts with that already on the graphics screen. The four <ink mode>s are:

  • 0: Normal
  • 1: XOR (eXclusive OR)
  • 2: AND
  • 3: OR

Example

MOVER 34,34

Associated keywords

Related Firmware routines

NEW

Command
NEW

Delete current program and variables. KEY definitions are not lost, and the display is not cleared.

Example

NEW

Command
NEXT [<list of:<variable>]

Delimits the end of a FOR loop. The NEXT command may be anonymous, or may refer to its matching FOR.

Example

FOR n=1 TO 1000:NEXT n

Associated keywords

FOR.

NOT

Operator
NOT <argument>

Performs bit-wise boolean operation on integers. Inverts each bit in the <argument>.

Example

PRINT NOT -1
 0
PRINT NOT 0
-1

Associated keywords

AND, OR, XOR.

ON GOSUB

Command
ON <integer expression> GOSUB <list of:<line number>

(see below)

ON GOTO

Command
ON <integer expression> GOTO <list of:<line number>

GOSUB to the subroutine, or GOTO the statement as directed by the result of the <integer expression>. If the result is 1, then the first line number in the list is chosen, if 2 then the second etc.

Examples

In the following example line 10, when DAY=1, the subroutine at line 100 would be visited. DAY=2 would cause a branch to line 200, and so on.

10 ON DAY GOSUB 100,200,300,400,500

Likewise with GOTO:

10 ON RATE GOTO 1000,2000,3000,4000

Associated keywords

ON BREAL CONT

Command
ON BREAK CONT
Compatibility
Only available with BASIC 1.1

Cancels the action of the [ESC] key from stopping the program, and instead CONTinues execution. Care should be taken when using this command, as the program will continue until the computer is completely reset; hence you should SAVE such a program before RUNning it.

ON BREAK CONT may be disabled within a program by ON BREAK STOP.

Example

10 ON BREAK CONT
20 PRINT "The program will CONtinue when you try to *Break* using [ESC]":PRINT
30 FOR t=1 TO 1000:NEXT:GOTO 20
run

Associated keywords

Downgrade for BASIC 1.0

There's several way to achieve a similar result:

KEY 66,0,0,0,0

ON BREAK GOSUB

Command
ON BREAK GOSUB <line number>

Calls a subroutine on breaking from program execution by pressing [ESC] twice.

Example

10 ON BREAK GOSUB 40
20 PRINT "program running"
30 GOTO 20
40 CLS
50 PRINT "pressing [ESC] twice calls GOSUB routine"
60 FOR t=l TO 2000:NEXT
70 RETURN

Associated keywords

ON BREAK STOP

Command
ON ERROR STOP

When issued in an ON BREAK interrupt subroutine, ON BREAK STOP disables the trap, but has no other immediate effect. In the above program, which includes ON BREAK STOP, the ON BREAK GOSUB trap will only operate once.

Example

10 ON BREAK GOSUB 40
20 PRINT "program running"
30 GOTO 20
40 CLS
50 PRINT "pressing [ESC] twice calls GOSUB routine"
60 FOR t=l TO 2000:NEXT
65 ON BREAK STOP
70 RETURN

Associated keywords

ON ERROR GOTO

Command
ON ERROR GOTO <linenumber>

Go to a specified line number in the program on detecting an error.

Example

In this example, an error will be found in line 70.

10 ON ERROR GOTO ERROR GOTO 80  
20 CLS 
30 PRINT"if there is an error, I would"  
40 PRINT"like the program listed, so that"  
50 PRINT"I can see where I went wrong"  
60 FOR t=l TO 4000:NEXT   
70 GOTO 200 
80 CLS:PRINT"THERE IS AN ERROR IN LINE";ERL:PRINT   
90 LIST

Associated keywords

ON SQ GOSUB

Command
ON SQ (<channel>) GOSUB <line number>

Enable an interrupt for when there is a free slot in the given sound queue. The <channel> is an integer expression yielding one of the values:

  • 1: for channel A
  • 2: for channel B
  • 4: for channel C

Example

ON SQ(2) GOSUB 2000

Associated keywords

SOUND, SQ.

OPENIN

Command
OPENIN <filename>

Opens an input file from disc or cassette which contains information for use in the current program in the computer's memory.

If tape deck is selected and the first character in the <file name> is ! then the displayed cassette processing messages are suppressed. The program reads in the first block from the cassette, ready for processing.

The input file to open myst be an ASCII file.

Example

100 OPENIN "!INFORMATION"

Associated keywords

Related Firmware routines

OPENOUT

Command
OPENOUT <filename>

Opens an output file onto disc or cassette. If the tape dekc is selected and the first character in the <file name> is ! then the displayed cassette processing messages are suppressed. The program creates the first block of data, in the file with the given name. Each block consists of up to 2048 bytes of data.

NB: A NEW command will abandon any open file buffered, and data will be lost.

Example

OPENOUT "!FACTS"

Associated keywords

Related Firmware routines

OR

Operator
<argument> OR <argument>

Performs bit-wise boolean operation on integers. Result is 1 unless both arguments are 0.

Example

PRINT 1 OR 1
 1
PRINT 1 OR 0
 1
PRINT 0 OR 0
 0

Associated keywords

AND, NOT, XOR.

ORIGIN

Command
ORIGIN <x>,<y>[<left>,<right>,<top>,<bottom>]

Determines the start point for the graphics cursor. The [optional part] of the command contains the instructions to set a new graphics window, which will be operational in all screen modes due the pixel addressing technique employed.

The ORIGIN is the point with co-ordinates 0,0 (co-ordinates grow up and right). If any of the window edges are specified to a position that is off the screen, they are assumed to represent the furthest visible position in the given direction.

Example

10 CLS:BORDER 13 
20 ORIGIN 0,0,50,590,350,50  
30 DRAW 540,350 
40 GOTO 20

Associated keywords

Related Firmware routines

OUT

Command
OUT <port number> , <integer expression>

Sends the value in the <integer expression> (which must lie in the range 0 to 255) to the port address specified in the <port number>.

Example

OUT &7F00,10:OUT &7F00,&4B

Associated keywords

INP, WAIT.

PAPER

Command
PAPER [#<stream expression>,]<masked ink>

Sets the background ink for characters. When characters are written to the text screen, the character cell is filled with the PAPER ink before the character is written - unless the transparent mode has been selected.

Example

10 MODE 0 
20 FOR p=0 TO 15 
30 PAPER p:CLS 
40 PEN 15-p 
50 LOCATE 6,12:PRINT "PAPER"p  
60 FOR t=l TO 500: NEXT t  
70 NEXT p  

Associated keywords

Related Firmware routines

PEEK

Function
PEEK(<address expression>)
Return value
Numeric (Integer).

Examine the contents of a memory location specified in the <address expression> which should be in the range &0000 to &FFFF (0 to 65535). In all cases PEEK will return the value at the RAM address specified (not the ROM), and wil be in the range &00 to &FF (0 to 255).

Example

The following utility program allows you to browse through the RAM. It reads the RAM under the lower (&0000-&3FFF) and upper (&C000-&FFFF) ROM - not the ROM.

10 MODE 2 
20 INK 1,0: INK 0,12: BORDER 12 
30 INPUT "Start address for examination";first  
40 INPUT "End address for examination";last  
50 FOR n= first TO last  
60 VALUE$=HEX$(PEEK(n),2)  
70 PRINT VALUE$; 
80 PRINT" at ";HEX$(n,4),  
90 NEXT

Associated keywords

POKE.

PEN

Command
PEN [#<stream expression>, ]<masked ink>

PEN sets the ink to be used when drawing at the given screen stream, defaulting to screen #0.

Example

PEN 1,2

Associated keywords

Related Firmware routines

PI

Variable
PI
Return value
Numeric (Real).

The value of the ratio between the circumference and the diameter of a circle. It is used extensively in graphics routines such as the one listed above.

Example

PRINT PI 
3.14159265 
10 REM Perspective drawing  
20 MODE 2 
30 RAD 
40 INK 1,0 
50 INK 0,12 
60 BORDER 9 
70 FOR N= 1 TO 200 
80 ORIGIN 420,0 
90 DRAW 0,200 
100 REM draw angles from vanishing point  
110 DRAW 30*N*SIN(N*PI/4),(SIN(PI/2))*N *SIN(N) 
120 NEXT 
130 MOVE 0,200 
140 DRAWR 0,50 
150 DRAWR 40,0 
160 WINDOW 1,40,1,10  
170 PRINT"Now you can finish the you can finish the Hangman program!"   

Associated keywords

DEG, RAD.

Related Firmware routines

PLOT

Command
PLOT <x co-ordinate>,<y co-ordinate>[,<ink>][,<ink mode>]
Compatibility
<ink mode> is only available with BASIC 1.1

Plots a point on the grphics screen at the absolute position specified in the x,y co-ordinates. The <ink> in which to plot the point may be specified (in the range 0 to 15).

The optional <ink mode> determines how the ink being written interacts with that already on the graphics screen. The four <ink mode>s are:

  • 0: Normal
  • 1: XOR (eXclusive OR)
  • 2: AND
  • 3: OR

Example

10 MODE 2:PRINT "Enter 4 numbers, separated by commas":PRINT  
20 PRINT "Enter X origin (0-639), Y origin (O-399), radius and angle to to step":INPUT x,y,r,s
30 ORIGIN x,y
40 FOR angle = 1 to 360 STEP s
50 XPOINT = r*COS(angle)
60 YPOINT = r*SIN(angle)
70 PLOT XPOINT,YPOINT
74 REM MOVE 0,0
75 REM DRAW XPOINT,YPOINT
80 NEXT

Try 320,200,20,1 as your first response. PLOT is the same as MOVE, except that the pixel at the destination is written. If you un-REM line 75 above and REM line 70 to make it inoperative, you will see the difference. (Un-REM line 74 to fill the circle).

Note that the process fills in the outline of the circle by repeated running around the perimeter.

Remember that this program has not reset the RADian mode of angular calculation, so the angle in each step is considerably more than one degree. Enter the command 25 DEG and run again.

Associated keywords

Related Firmware routines

Downgrade for BASIC 1.0

The <ink mode> can be selected by using the ETB control code:

10 ' PLOT 320,200,1,3
20 PRINT CHR$(23)CHR$(3):DRAW 320,200,1

PLOTR

Command
PLOTR <x offset>, <y offset>[,<ink>][,<ink mode>]
Compatibility
<ink mode> is only available with BASIC 1.1

Plots a point on the graphics screen at the specified position <x offset> and <y offset>, relative to the current graphics cursor position. The <ink> in which to plot the point may be specified (in the range 0 to 15).

The optional <ink mode> determines how the ink being written interacts with that already on the graphics screen. The four <ink mode>s are:

  • 0: Normal
  • 1: XOR (eXclusive OR)
  • 2: AND
  • 3: OR

Example

5 DEG 
10 MODE 2:PRINT "Enter 4 numbers, separated by commas":PRINT  
20 PRINT "Enter X origin (O -639), Y origin (O-399), radius and angle to to step":INPUT x,y,r,s
30 ORIGIN x,y
40 FOR angle = 1 to 360 STEP s  
50 XPOINT = r*COS(angle)  
60 YPOINT = r*SIN(angle)  
70 PLOTR XPOINT,YPOINT  
80 NEXT: GOTO 40 

Try 320,0,2,1 in reponse. PLOTR is the same as DRAWR except that only the pixel at the destination is written.

Associated keywords

Related Firmware routines

Downgrade for BASIC 1.0

The <ink mode> can be selected by using the ETB control code:

10 ' PLOTR 20,40,1,3
20 PRINT CHR$(23)CHR$(3):PLOTR 20,40,1

POKE

Command
POKE <address expression>, <integer expression>

Provides direct access to the machine memory. Writes the <integer expression> in the range 0 to 255 directly into the machine memory (RAM) at the specified <address expression>.

Not to be used by the unwary.

Example

POKE &00FF,10

Associated keywords

PEEK.

POS

Function
POS(#<stream expression>)
Return value
Numeric.

Reports the current horizontal POSition of the text cursor relative to the left edge of the text window. The <stream expression> MUST be specified, and does NOT default to #0.

Printer (POS(#8)): Returns the carriage position, where 1 is the left margin. All characters with ASCII reference numbers greater than &lF (31) are included.

Cassette/Disc (POS(#9)): Reports the position in the file stream, i.e. the number of printing characters sent to the stream since the last carriage return.

Example

PRINT POS(#0) 
1  

Associated keywords

VPOS.

Related Firmware routines

PRINT

Command
PRINT [#<stream expression>,][list of: <print item>]

Prints the list of: <print items>s to the given stream (to stream #0 if <stream expression> is not specified).

Note that when a semicolon ; is used to tell the computer to print the following <print item> next to the preceding item, BASIC first checks to see if the following <print item> can fit onto the same line. If not, it will be printed on a new line regardless of the semicolon.

Note that when a coma , is used to tell the computer to print the following <print item> in the next print zone, BASIC first checks to see that the preceding item has not exceeded the lenght of the current zone. If it has, the following <print item> is printed in a further zone.

Example

10 a$="small"
20 b$="this is a larger string"
30 PRINT a$;a$
40 PRINT a$;b$;"which end here"
run

Associated keywords

Related Firmware routines

PRINT SPC

Command
PRINT [#<stream expression>,][list of: <print item>][;][SPC(<integer expression>)][list of: <print item>]

SPC prints the number of spaces specified in the <integer expression>, and will print any following <print item> immediately next to the spaces (assuming the follown <print item> will fit onto the line). Hence it is not necessary to terminate SPC with a semicolon.

Example

10 FOR x=6 TO 15
20 PRINT SPC(5)"a";SPC(x)"b"
30 NEXT
run

PRINT TAB

Command
PRINT [#<stream expression>,][list of: <print item>][;][TAB(<integer expression>)][list of: <print item>]

TAB prints the number of spaces relative to the left efge of the text window, and will print any following <print item> immediately next to the spaces (assuming the following <print item> will fit ontoi the line). Hence it is not necessary to terminate TAB with a semicolon. If the current position is greater than the required position, then a carriage return is executed, followed by spaces to reach the required position on the next line.

Example

10 FOR x=6 TO 15
20 PRINT TAB(5)"a";TAB(x)"b"
30 NEXT
run

PRINT USING

Command
PRINT [#<stream expression>,][list of: <print item>][;][USING <format template>][<separator><expression>]

PRINT USING enables you to specify the print format of the expression returned by the PRINT command. This is achieved by specifying a <format template> to which the printed result must correspond. The <separator> is a comma or semicolon. The <format template> is a string expression which is constructed using the following format field specifiers:

Numeric Formats

Within the number:

#
  • Each # specifies a digit position.

Example template: ######

.
  • Specifies the position of the decimal point.

Example template: ######.##

,
  • Specifies one digit position. May appear BEFORE the decimal point only.
  • Specifies that digits before the decimal point are to be divided into groups of three (for thousands), separated by commas.

Example template: ######,.##

Around the number:

££
  • Specifies two digit positions
  • Specifies that a £ sign be printed immediately before the first digit or decimal point (after any leading sign). Note that the £ will occupy one of the digit positions.

Example template: ££######,.##

**
  • Specifies two digit positions.
  • Specifies that any leading spaces be replaced by asterisks.

Example template: **######,.##

**£
  • Specifies three digit positions.
  • Acts ** and ££ options combined, ie. leading * asteriks and £ sign.

Example template: **£######,.##

$$
  • Specifies two digit positions.
  • Specifies that a $ sign be printed immediately before the first digit or decimal point (after any leading sign). Note that the $ will occupy one of the digit position.

Example template: $$######,.##

**$
  • Specifies three digit positions.
  • Acts as ** and $$ options combined, ie. leading * asterisks and $ sign.

Example template: **$######,.##

+

Specificies that + or - is to be printed, as appropriate. If the + appears at the beginning of the template, the + sign is printed immediately before the number (and any leading currency sign). If the + appears at the end of the template, the sign is printed after the number (and any exponent part).

Example template: +######,.##

-
  • The - sign may only appear at the END of a template.
  • Specifies that - is to be printed after negative number (and exponent part). If the number is positive, a space will be printed. A - sign is printed before a negative number by default, unless countermanded by the use of this template.

Example template: -######,.##

↑↑↑↑
  • Specifies that the number is to be printed using the exponent option.
  • The ↑↑↑↑ in the template should appear AFTER the digit positions, but BEFORE any trailing + or - sign.

Example template: ######,.##↑↑↑↑+

The <format template> for a number may not exceed 20 characters. Numbers are rounded to the number of digits printed.

If the format template is too small for the input expression, for example:

PRINT USING "####";12345678

the printed result is NOT shortened to fit the template, but is instead printed in its entirety, preceded by a % sign, to indicate format failure.

String Formats

!
  • Specifies that only the first character of the string is to be printed.

Example template: !

\<space>\
  • Specifies that only the first x characters of the string are to be printed, where x is equal to the lenght of the template (including the back-slashes).

Example template:    

&
  • Specifies that the entire string is to be printed as is.

Example template: &

The <format template> for a string may not exceed 255 characters.

Both numeric and string <format template>s may be represented by string variables, for example:

10 a$="££######,.##"
20 b$="!"
30 PRINT USING a$;12345.6789:
40 PRINT USING b$;"pence"
run

Associated keywords

SPC, TAB.

RAD

Command
RAD

Set Radians Mode

Associated keywords

DEG,SIN, COS, TAN, ATN.

Related Firmware routines

RANDOMIZE

Command
RANDOMIZE [<numeric expression>]

BASIC's random number generator produces a pseudo random sequence in which each number depends on the previous number - starting from a given number, the sequence is always the same. RANDOMIZE sets a new initial value for the random number generator, either to a given value, or to a value entered by the operator. RANDOMIZE TIME will produce a sequence that will be difficult to repeat.

Example

10 RANDOMIZE 23 
20 PRINT RND(6) 

Associated keywords

RND.

READ

Command
READ list of:<variable>

READ fetches data from the list of constants supplied in the corresponding DATA statements and assigns it to variables, automatically stepping to the next item in the data statement. RESTORE will return the pointer to the beginning of the DATA statement.

See the DATA keyword.

Example

10 FOR X=1 TO 4 
20 READ N$ 
30 PRINT N$ 
40 DATA ADAM,DANNY,JAMIE,RICHARD  
50 NEXT 

Associated keywords

RELEASE

Command
RELEASE <sound channels>

When a sound is placed on a sound queue it may include a hold state. If any of the channels specified in this channel are in hold state, then they are released, the expression to identify the sound channel is bit significant:

  • A= bit 0
  • B= bit 1
  • C= bit 2

Thus 4 (binary &X0100) releases Queue C.

Example

RELEASE 4

Associated keywords

Related Firmware routines

REM

Command
REM <rest of line>

Used to place REM arks or REM inders in programs without affecting the program operation in any way. The : line separator is also ignored, everything from the REM to the line end is ignored. A single quote character ' in a line (not part of a <string expression>) is equivalent to :REM, other than in a DATA command, where it is treated as part of an unquoted string.

Example

10 REM Intergalatic Hyperspace Monster Invaders Deathchase by AMSOFT  
20 REM Copyright AMSOFT 1984
30 POKE &8000,&FF' Cheat the game with 255 lives

REMAIN

Function
REMAIN(<integer expression>)
Return value
Numeric.

Returns the REMAINing count from the delay timer specified in <integer expression> (in the range 0 to 3) and disable it.

Example

REMAIN (3)
PRINT #6,REMAIN(0);

Associated keywords

RENUM

Command
RENUM [<new line number>][ ,[<old line number>][,< increment>]

Renumber program lines from the line specified, using the increment specified.

The <new line number> gives the first number for. the new sequence, defaulting to 10. The <old line number> identifies where RENUM is to commence, and assumes the first program line if omitted.

The <increment> sets the increment to use between the line numbers, again defaulting to 10. RENUM takes care of all GOSUB, GOTO and other line calls.

If all the specifiers are omitted from the command, the program is renumbered as if RENUM 10,,10 were issued.

Line numbers are valid in the range 1 to 65535.

Example

RENUM
RENUM 100,,100

RESTORE

Command
RESTORE [<line number>]

Restores the position of the reading pointer back to the beginning of the DATA statement specified in the optional <line number>. Omitting <line number> restores the position of the pointer back to the beginning of the first DATA statement.

Example

 
10 FOR N=1 TO 6 
20 READ A$ 
30 PRINT A$;" "; 
40 DATA restored,data,can,be,read,again   
50 NEXT 
60 PRINT 
70 RESTORE 
80 GOTO 10 

Associated keywords

RESUME

Command
RESUME [<line number>]
RESUME NEXT

When an error has been trapped by an ON ERROR GOTO command, and has been processed, RESUME allows normal program execution to continue, the resuming line number being optionally specifiable. If not specified, the line in which the error has occurred is returned to.

RESUME NEXT returns to the line immediately following the statement in which the error was detected.

Associated keywords

RETURN

Command
RETURN

Signals the end of a subroutine. BASIC returns to continue processing at the point after the GOSUB which invoked it.

Associated keywords

RIGHT$

Function
RIGHT$(<string expression>,<integer expression>)
Return value
String.

Extracts the number of characters specified by the <integer expression> from the right of the string expression. If the string expression is shorter than the required length, the whole <string expression> is returned.

Example

10 A% = "AMSTRAD"   
20 B$ = RIGHT$(A$,3)  
30 PRINT B$ 
RUN 
RAD 
Ready 

Associated keywords

RND

Function
RND[(<numeric expression>)]
Return value
Numeric.

Fetches a random number, which may be the next in sequence, a repeat of the last one, or the first in a new sequence.

RND(0) returns a copy of the last random number generated. Where <numeric expression> is negative, the number sequence generated is predictable.

Example

10 RANDOMIZE 23 
20 PRINT RND  

Associated keywords

Related Firmware routines

ROUND

Function
ROUND (<numeric expression>[,<integer expression>])
Return value
Numeric.

Rounds <numeric expression> to a number of decimal places or power of ten specified in <integer expression>. If the <integer expression> is less than zero, then value is rounded to give an absolute integer followed by a number of zeros determined by the <integer expression> before the decimal point.

Example

10 x=0.123456789 
20 FOR r=9 TO 0 STEP -1:PRINT r,ROUND(x,r):NEXT   
25 x=123456789 
30 FOR r=0 TO -9 STEP –1 
40 PRINT r,ROUND (x,r)  
50 NEXT 

Associated keywords

INT, FIX, CINT, ABS.

RUN

Command
RUN <string expression>
RUN [<line number>]

RUN <string expression>

Loads a program (BASIC or binary) from disc or tape and start executing it.

Tape

If the string expression is empty ”” BASIC attempts to load and execute the first file it encounters on the tape, if the first character of the string expression is ! then the displayed cassette processing messages are suppressed.

RUN [<line number>]

Commences execution of the current BASIC program, from the specified <line number>, or from the beginning of the program if the parameter is omitted.

  • All current program, user functions and variables are deleted from memory.
  • DEFINT, DEFREAL and DEFSTR settings are reset.
  • All open files are abandoned, and any buffered output is lost.

Associated keywords

SAVE

Command
SAVE <filename>[,<file type>][,<binary parameters>]

Saves the current BASIC program or an area of memory to tape or disc.

Save the current BASIC program to file

SAVE "myprog"

Save the current BASIC program to file in protected mode

SAVE "myprog",P

A BASIC program saved with the ,P parameter can only be RUNed and won't be LOADable or LISTable anymore (using regular commands, but it can be easily cracked tho).
You should always keep an unprotected copy of your program if you intend to modify it later.

Save the current BASIC program to file in ASCII mode

SAVE "myprog.asc",A

Save an area of memory to a binary file

SAVE "screen.bin",B,&C000,&4000

Associated keywords

SGN

Function
SGN (<numeric expression>)
Return value
Numeric (-1, 0 or 1).

Determines the sign of the <numeric expression>.

Returns -1 if <numeric expression> is less than 0. Returns 0 if <numeric expression> equal 0. Returns 1 if <numeric expression> is greater than zero.

Example

10 INPUT "What's your current Bank Balance";CASH  
20 IF SGN(CASH)<1 GOTO 30 ELSE 40  
30 PRINT "Oh dear, oh dear":END  
40 PRINT"You've got more money than me"  

Associated keywords

ABS.

Related Firmware routines

SIN

Function
SIN(<numeric expression>)
Return value
Numeric (Real).

Calculates the Real value for the Sine of <numeric expression>, defaulting to the Radian measure mode unless otherwise declared by a DEG command.

Example

PRINT SIN(PI/2)  
1 

Associated keywords

COS, TAN, ATN, DEG, RAD.

Related Firmware routines

SOUND

Command
SOUND <channel status>, <tone period>[,<duration>[,<volume>[,<volume envelope>[,<tone envelope>[,<noise period>]]]]

Example

SOUND 1,200,1000,7,0,0,1

Associated keywords

ENV, ENT.

Related Firmware routines

SPACE$

Function
SPACE$(<integer expression>)
Return value
String.

Creates a string of spaces of the given length.

Example

SPACE$(190)

Associated keywords

PRINT, SPC, TAB.

SPEED INK

Command
SPEED INK <integer expression>,<integer expression>

The INK and BORDER commands allow two colours to be associated with each Ink, in which case the INK alternates between the two colours. The first integer expression) specifies the time for the first INK specified to be used, and the second integer expression sets the time for the second INK . Times between colour changes are measured in units of 1/50 second. (50 Hz)

You must exercise careful judgement to avoid mesmeric effects when selecting colours and repeat rates!

Example

10 INK 0,9,12:INK 1,0,26  
20 BORDER 12,9 
30 SPEED INK 50,20 

Associated keywords

Related Firmware routines

SPEED KEY

Command
SPEED KEY <start delay>, <repeat period>

If held down continuously, the keys auto repeat at the <repeat period> after the given <start delay> period. The setting is made in 1/50 sec units, in the range 1 to 255. The default rate is set to 30,2.

Very small start delays will interact with keyboard de-bounce routines. The actual speed at which the keyboard is read by the software is not affected by this command.

Not all keys repeat, the KEY DEF commnd will allow the user to redefine the particular attributes of a given key.

Example

SPEED KEY 20,3

Associated keywords

Related Firmware routines

SPEED WRITE

Command
SPEED WRITE <integer expression>

The cassette can be witten at either 2000 baud (where <integer expression> is 1), or the default of 1000 baud (where the <integer expression> is 0). When loading a file from tape, the CPC464 automatically establishes the correct reading speed from information in the file software, thus it is not necessary for the user to specify.

When using cassette tape of uncertain data recording ability, the 1000 baud rate is recommended for maximum reliability.

Example

SPEED WRITE 1

Associated keywords

SAVE.

Related Firmware routines

SQ

Function
SQ(<channel>)
Return value
Numeric (8bit significant).

The SQ function is used to check the number of free entries in the queue for a given channel, where channel A is 1, B is 2, and C is 3. The function determines whether the channel is active - and if not - why the entry at the head of the queue (if any) is waiting.

The result is bit significant:

  • bits 0,1,2 indicate the number of free entries in the queue
  • bits 3,4,5 indicate the Rendezvous state at the head of the queue (if any)
  • bit 6 is set if the head of the queue is held
  • bit 7 is set if the channel is currently active

Example

10 MODE 1 
20 FOR n=20 TO 0 STEP -l 
30 PRINT n; 
40 SOUND 1,10+n,l00,7  
50 WHILE SQ(1)>127:WEND  
60 NEXT 

Associated keywords

Related Firmware routines

SQR

Function
SQR(<numeric expression>)
Return value
Numeric.

Returns the square root of <numeric expression>.

Example

PRINT SQR(9) 
3 

Associated keywords

Related Firmware routines

STOP

Command
STOP

To stop execution of a program, but leave BASIC in a state where the program can be restarted after the STOP command by using the CONT command. This may be used to interrupt the program at a particular point when debugging.

Example

300 IF n<0 THEN STOP  

Associated keywords

CONT, END.

STR$

Function
STR$(<numeric expression>)
Return value
String.

Converts the numeric expression) to a decimal string representation in the same form as used in the PRINT command.

Example

PRINT STR$(&766) 
1894 
PRINT STR$(&X1010100)  
84 

Associated keywords

STRING$

Function
STRING$(<integer expression>,<character ex pression>)
Return value
String.

Delivers a <string expression> consisting of the specified character repeated a number of times.

Example

PRINT STRING$(&16,"*")  
**********************  

Associated keywords

SYMBOL

Command
SYMBOL <character number>,<list of: row>

The SYMBOL command redefines the representation of a given character that has first been specified in the SYMBOL AFTER command. The character number, is chosen from the available ASCII or other characters from the CPC464’ s standard character set, and the following entries define the new character on an 8×8 pixel matrix. A 0 in the row indicates the paper colour to be used and a 1 indicates that the pixel is to be set to the current ink colour.

Example

The following example produces a backslash that goes diagonally across the character cell, accessible by pressing the ] key.

5 MODE 2 
10 SYMBOL AFTER 90 
20 SYMBOL 93,&80,&40,&20,&10,&8,&4,&2,&1   
30 FOR n=1 TO 2000 
40 PRINT CHR$(93); 
50 NEXT 
60 GOTO 60 

Associated keywords

Related Firmware routines

SYMBOL AFTER

Command
SYMBOL AFTER <integer expression>

The number of user definable characters is set by the SYMBOL AFTER command. The default setting is 240, giving 16 user defined characters. If the <integer expression>, is 32, then all characters from 32 to 255 are redefinable.

Whenever a SYMBOL AFTER command is used, all user defined characters are reset to the default condition.

Example

SYMBOL AFTER 90

Associated keywords

TAG

Command
TAG [#<stream expression>]

Text sent to a given stream may be redirected to be written at the graphics cursor position. This allows text and symbols to be mixed with graphics. The stream expression) defaults to 0 if omitted. The top left of the character cell is tagged to the graphics cursor, and non-printing control characters will display. In particular, new line characters will display if the PRINT statement is not followed by a semi-colon ;

Example

10 MODE 2
11 BORDER 9
14 INK 0,12
15 INK 1,0
20 FOR n=l TO 100
30 MOVE 200+n,320+n
40 TAG
50 IF n<70 GOTO 60 ELSE 70
60 PRINT"Hello";:GOTO 80
70 PRINT" Farewell";
80 NEXT
90 GOTO 20

Associated keywords

Related Firmware routines

TAGOFF

Command
TAGOFF [#<stream expression>]

Cancels the TAG for a given stream, and sends the text to the previous text cursor position at the point at which TAG was invoked.

Example

TAGOFF #0

Associated keywords

TAG.

Related Firmware routines

TAN

Function
TAN(<numeric expression>)
Return value
Numeric.

Calculates the tangent for the angle given in <numeric expression>, which must be in the range -200,000….+200,000, defaulting to radian measure unless declared otherwise by a DEG command (like in the following example).

Example

DEG
PRINT TAN(45) 
 1

Associated keywords

COS, SIN, ATN, DEG, RAD.

Related Firmware routines

TEST

Function
TEST(<x co-ordinate>,<y co-ordinate>)
Return value
Numeric (0 to 15).

Reports the value of the ink currently at the specified graphics screen location.

Example

PRINT TEST(300,300)  

Associated keywords

Related Firmware routines

TESTR

Function
TESTR(<x offset>, <y offset>)
Return value
Numeric (0 to 15).

Moves the graphics cursor relatively from it's current location and reports the value of the ink at the new location.

Example

TESTR(5,5)

Associated keywords

Related Firmware routines

TIME

Variable
TIME
Return value
Numeric.

Holds the elapsed time since switch-on, excluding periods when reading or writing the cassette. The units of time are 1/300th of a second.

Example

10 DATUM = INT(TIME/300)  
20 TICKER=((TIME/300> -DATUM) 
30 PRINT TICKER; 
40 GOTO 20

Related Firmware routines

TRON

Command
TRON

TROFF

Command
TROFF

BASIC includes the facility to trace the execution of a program, by reporting the number of each line in square brackets [ ] , just before it is executed. TRON enables the feature, TROFF turns it off.

Associated keywords

RUN.

UNT

Funtion
UNT(<address expression>)
Return value
Numeric.

Converts an unsigned 16-bit integer in the range 0 to 65535. Returns an integer value in the range -32768 to +32767.

Example

PRINT UNT(65535)
-1

Associated keywords

UPPER$

Function
UPPER$(<string expression>)
Return value
String.

Returns a new string expression the same as the input string expression) but in which all lower case characters are converted to upper case.

Example

PRINT UPPER$("amstrad")
AMSTRAD

Associated keywords

VAL

Function
VAL(<string expression>)
Return value
Numeric.

Extracts a <numeric expression> from the beginning of the string expression,. The opposite of STR$.

Example

10 A$="7 is my lucky numbe r" 
20 PRINT VAL(A$) 

Associated keywords

STR$.

VPOS

Function
VPOS (#<stream expression>)
Return value
Numeric.

Returns the vertical position of the text cursor for the stream expression.

Example

PRINT VPOS(#0) 

Associated keywords

POS.

WAIT

Command
WAIT <port number>,<mask>[,<inversion)]

Suspends operation until a given I/O port returns a particular value in the range 0 to 255. BASIC loops whilst reading the I/O port. The value-read is Exclusive ORed with the <inversion> and then ANDed with the <mask> until a non-zero result occurs. BASIC will get stuck in a WAIT loop if the required condition does not occur.

Examples

If you type in the following example, you will have to fully reset the computer to escape.

WAIT &FF34,20,25 

The next example will wait for the frame flyback, bit0 of PPI Port B:

WAIT &F500,&X00000001

This is an equivalent to the famous CALL &BD19 (or FRAME keyword on BASIC 1.1).

Associated keywords

INP , OUT.

WEND

Command
WEND

The WHILE/WEND loop repeatedly executes a body of program until a given condition is true. The illustration here uses the WHILE/WEND loop to demonstrate the elegance of programs constructed using this approach. The body of the features of a variety of different clocks can now be added. The WEND command terminates the WHILE loop.

Example

10 MODE 1:REM BASIC CLOCK TIME ROUTINE  
20 INPUT "Enter the current hour, minute, and second (h,m,s)"; hour,minute,second  
30 CLS:datum = INT(TIME/300)
40 WHILE hour<13
50 WHILE minute<60
60 WHILE tick<60
70 tick=(INT(TIME/300)-datum)+second
80 LOCATE 70,4
90 PRINT #0,USING "## ";hour,minute,tick
100 WEND
110 tick=0
115 second=0
120 minute=minute+l
130 GOTO 30
140 WEND
150 minute=0
160 hour=hour+l
170 WEND
180 hour=1
190 GOTO 40

Associated keywords

WHILE

Command
WHILE <logical expression>

A WHILE loop repeatedly executes a body of program until a given condition is true. The WHILE command defines the head of the loop, and gives the condition. The WEND command terminates the WHILE loop.

See example above.

Associated keywords

WEND.

WIDTH

Command
WIDTH <integer expression>

Tells BASIC how wide the printer is in characters, this information allows BASIC to insert carriage returns as required when printing.

Example

WIDTH 86

Associated keywords

WINDOW

Command
WINDOW [#<stream expression>,] <left>, <right>, <top>, <bottom>

Sets a text window for a given screen stream.

Example

10 MODE 1  
20 BORDER 6 
30 WINDOW 10,30,7,18  
40 PAPER 2:PEN 3 
50 CLS 
60 PRINT CHR$(143);CHR$(242);"THIS IS LOCATION"  
70 PRINT "1,1 IN TEXT WINDOW"   
80 GOTO 80 

Associated keywords

Related Firmware routines

WINDOW SWAP

Command
WINDOW SWAP <stream expression>, <stream expression>

Exchanges the text windows. For example, BASIC messages sent to stream #O may be swapped with another window to highlight aspects of program development and operation.

Example

WINDOW SWAP 0,2 

Associated keywords

Related Firmware routines

WRITE

Command
WRITE [#<stream expression >, ][<write list>]

Prints the values of a number of expressions to the given stream, separating them by commas and enclosing strings in double quotes. Used mainly for outputting data to files (on tape or disc).

Example

WRITE #2,"HELL0",4,5
"HELL0",4,5 

XOR

Operator
<argument> XOR <argument>

Performs bit-wise boolean operation on integers. Result is 1 unless both arguments are the same - eXclusive OR.

Example

PRINT 1 XOR 1
 0
PRINT 1 XOR 0
 1
PRINT 0 XOR 0
 0

Associated keywords

AND, OR, NOT.

XPOS

Function
XPOS
Return value
Numeric.

Establishes the horizontal position of the graphics cursor.

Associated keywords

Related Firmware routines

YPOS

Function
YPOS
Return value
Numeric.

Establishes the vertical position of the graphics cursor.

Associated keywords

Related Firmware routines

ZONE

Command
ZONE <integer expression>

Changes the width of the Print Zone used in PRINT, from the default value of 13 to a new value in the range 1 to 255. Reset by NEW, LOAD, CHAIN and RUN"<file name>" commands.

Example

10 PRINT 1,2,3 
20 ZONE 19 
30 PRINT 4,5,6 

Associated keywords

Error codes (ERR)

1 - Unexpected NEXT

A NEXT command has been encountered while not in a FOR loop, or the control variable in the NEXT command does not match that in the FOR.

2 - Syntax Error

BASIC cannot understand the given line because a construct within it is not legal.

3 - Unexpected RETURN

A RETURN command has been encountered when not in a subroutine.

4 - DATA exhausted

A READ command has attempted to read beyond the end of the last DATA.

5 - Improper argument

This is a general purpose error. The value of a function's argument, or a command parameter is invalid in some way.

6 - Overflow Overflow

The result of an arithmetic operation has overflowed. This may be a floating point overflow, in which case some operation has yielded a value greater than 1.73-38 (approx.). Alternatively, this may be the result of a failed attempt to change a floating point number to a 16 bit signed integer.

7 - Memory full

The current program or its variables may be simply too big, or the control structure is too deeply nested (nested GOSUBs, WHILEs or FOR).

A MEMORY command will give this error if an attempt is made to set the top of BASIC's memory too low, or to an impossibly high value. Note that an open cassette file has a buffer allocated to it, and that may restrict the values that MEMORY may use.

8 - Line does not exist

The line referenced cannot be found.

9 - Subscript out of range

One of the subscripts in an array reference is too big or too small.

10 - Array already dimensioned

One of the arrays in a DIM statement has already been declared.

11 - Division by zero

May occur in Real division, integer division, integer modulus or in exponentiation.

12 - Invalid direct command

The last command attempted is not valid in Direct Mode.

13 - Type mismatch

A numeric value has been presented where a string value is required. and vice versa, or an invalidly formed number has been found in READ or INPUT.

14 - String space full

So many strings have been created that there is no further room available, even after garbage collection.

15 - String too long

String exceeds 255 characters in length. May be generated by adding a number of strings together.

16 - String expression too complex

String expressions may generate a number of intermediate string values. When the number. of these values exceeds a reasonable limit, BASIC gives up, and this error results.

17 - Cannot CONTinue

For one reason or another the current program cannot be restarted using CONT. Note that CONT is intended for restarting after a STOP command, [ESC][ESC] or error, and that any alteration of the program in the meantime makes a restart impossible.

18 - Unknown user function

No DEF FN has been executed for the FN just invoked.

19 - RESUME missing

The end of the program has been encountered while in Error Processing Mode (ie in an ON ERROR GOTO routine).

20 - Unexpected RESUME

RESUME is only valid while in Error Processing Mode (ie in an ON ERROR GOTO routine).

21 - Direct command found

When loading a program from disc or cassette, a line without a line number has been found.

22 - Operand missing

BASIC has encountered an incomplete expression.

23 - Line too long

A line when converted to BASIC internal form becomes too big.

24 - EOF met

An attempt has been made to read past end of file on the cassette input stream.

25 - File type error

The cassette file being read is not of a suitable type. OPENIN is only prepared to open ASCII text files. LOAD, RUN etc, are only prepared to deal with the file types produced by SAVE.

26 - NEXT missing

Cannot find a NEXT to match a FOR command.

27 - File already open

An OPENIN or OPENOUT command has been executed before the previously opened file has been closed.

28 - Unknown command

BASIC cannot find a taker for an external command.

29 - WEND missing

Cannot find a WEND to match a WHILE command.

30 - Unexpected WEND

Encountered a WEND when not in a WHILE loop, or a WEND that does not match the current WHILE loop.

31 - File not open

Compatibility
Only reported in BASIC 1.1 (With AMSDOS).

(See Disc error below)

32 - Broken in

Compatibility
Only reported in BASIC 1.1 (With AMSDOS).

(See Disc error below)

Disc Error (DERR)

Programming is like sex: One mistake and you have to support it for the rest of your life.

Compatibility
Only available on BASIC 1.1 (With AMSDOS).

These are the error codes reported by the disc operating system through the DERR variable.

0 or 22 - [ESC]

[ESC] has been pressed.

142 - Stream is fucked up

The stream is not in suitable state.

143 - Hard EOF

Hard end of file has been reached.

144 - Bad command

145 - File already exists

146 - File not found

147 - Directory full

148 - Disc full

149 - Disc changed

The disc changed while files were open.

150 - File is read only

154 - Soft EOF

Soft end of file has been detected.

Bitwise error code

Other values returned by DERR originate from the disc controller and are bit significant, always with bit6 set. Bit7 indicates whether the error has been reported by AMSDOS. This significance of each bit is as follows:

  • Bit0: Address mark missing.
  • Bit1: Not writable - disc is write protected.
  • Bit2: No data - can't find the sector.
  • Bit3: Drive not ready - no disc in the drive.
  • Bit4: Overrun error.
  • Bit5: Data error - CRC error.
  • Bit6: Always set to 1 to indicate an error from the disc controller.
  • Bit7: Set to 1 if error has already been reported by AMSDOS.

ERR may also return 31 if access was attempted when no file was open. The usual way in which one may use ERR and DERR would be to include an ON ERROR GOTO which call a short routine that checks if ERR has value 31 or 32, and if it is 32, DERR could be interrogated to five more detailled information regarding the nature of of the error. For example:

10 ON ERROR GOTO 1000
20 OPENOUT "myfile.asc"
30 WRITE #9,"test-data"
40 CLOSEOUT
50 END
1000 amsdoserr=(DERR AND &7F):REM mask off bit7
1010 IF ERR<31 THEN END
1020 IF ERR=31 THEN PRINT "are you sure you've typed line 20 correctly?":END
1030 IF amsdoserr=20 THEN PRINT "disc is full, suggest you use a new data disc":END
1040 IF amsdoserr=&X01001000 THEN PRINT "put a disc in a the drive, then press a key":WHILE INKEY$<>"":WEND:RESUME
1050 END

Data structures

Program

Tokens

Variables

Real number

Integer

String

documentations/software/locomotive.basic/start.txt · Last modified: 2012/06/15 21:05 by grim