“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).

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

• CPC-Wiki.
• Wikipedia.
• The Basic Idea - Excellent Amstrad Basic tutorial by Sean McManus.

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 :).

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

DERR.

CLEAR INPUT, COPYCHR$, CURSOR, DEC$, FILL, FRAME, GRAPHICS PAPER, GRAPHICS PEN, MASK, ON BREAK CONT.

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

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.

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.

• 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.

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

• CPC664 (v1.10)
• CPC6128 (v1.20)
• CPC6128 (v1.21)
• CPC6128 (v1.23)
• Amstrad Plus (v1.40)

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!)

• & 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 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.

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 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.

• 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.

() 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.

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

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.

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.

PRINT ABS(-67.98) 
67.98 

SGN.

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.

AFTER 200,2 GOSUB 320  

EVERY, REMAIN.

Operator

<argument> AND <argument>

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

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

NOT, OR, XOR.

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.

PRINT ASC("X") 
88 

CHR$.

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.

PRINT ATN(1) 
0.785398163 

SIN, COS, TAN, DEG, RAD.

REAL ARCTANGENT.

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

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.

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

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

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.

AUTO 100,50 

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>.

PRINT BIN$(64,8) 
01000000 

DEC$, HEX$, STR$.

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.

BORDER 3,2 

SPEED INK.

SCR SET BORDER, SCR GET BORDER.

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.

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 

UNT.

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.

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.

LOAD, RUN, SAVE.

CAS CATALOG.

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.

CHAIN "TEST", 350

CHAIN MERGE, LOAD, RUN.

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.

LOAD, MERGE.

Function

CHR$(<integer expression>)

Return value

String.

Converts <integer expression> in the range 0 to 255, to its character string equivalent.

Note that 0 to 31 are control characters.

PRINT CHR$(100) 
 d 

ASC, LEFT$, RIGHT$, MID$, STR$.

Function

CINT(<numeric expression>)

Return value

Numeric.

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

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

CREAL, INT, FIX, ROUND, UNT.

REAL TO INTEGER, REAL TO BINARY.

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.

Command

CLEAR INPUT

Compatibility

Only available with BASIC 1.1

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

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

INKEY, INKEY$, JOY

KM FLUSH.

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

CALL &BB03

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.

CLS, GRAPHICS PAPER, ORIGIN.

SCR FILL BOX.

Command

CLOSEIN

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

OPENIN, CLOSEOUT.

CAS IN CLOSE.

Command

CLOSEOUT

Close any output file to disc or cassette.

OPENOUT, CLOSEIN.

CAS OUT CLOSE.

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.

SCR FILL BOX.

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.

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.

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

LOCATE.

TXT RD CHAR.

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.

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.

? 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.

SIN, TAN, ATN, DEG, RAD.

REAL COSINE.

Function

CREAL(<numeric expression>)

Return value

Numeric.

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

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 

CINT.

INTEGER TO REAL, BINARY TO REAL.

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.

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

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.

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

READ, RESTORE.

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:

+ - £ $ * # , . ^

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

BIN$, hex$, PRINT USING, STR$.

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)

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.

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)  

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.

DEFINT I-N 
DEFSTR A,W-2 
DEFREAL  

LOAD, RUN, CHAIN,NEW, CLEAR.

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.

RAD.

SET ANGLE MODE.

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.

DELETE 100-200 

NEW.

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.

ERL, ERR, ERROR, ON ERROR GOTO, RESUME

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.

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 

EI.

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.

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

ERASE.

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

DRAW 200,200,13 

DRAWR, PLOT, PLOTR, MOVE, MOVER, TEST, TESTR, XPOS, YPOS, ORIGIN.

GRA LINE ABSOLUTE.

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

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

DRAWR 200,200,13 

DRAW, PLOT, PLOTR, MOVE, MOVER, TEST, TESTR, XPOS, YPOS, ORIGIN.

GRA LINE RELATIVE.

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

Command

EDIT <line number>

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

EDIT 110 

LIST.

Command

EI

To Enable Interrupts disabled by a DI command.

DI.

(See IF)

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.

STOP.

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.

If 3 parameters are used, these are:

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.

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.

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.

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

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.

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.

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

ENV, SOUND.

SOUND TONE ENVELOPE.

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:

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.

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.

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.

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

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.

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.

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

ENT, SOUND.

SOUND AMPL ENVELOPE.

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).

PRINT EOF  
-1 

OPENIN.

CAS TEST EOF.

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.

ERASE A,B%

DIM.

Variable

ERL

Return value

Numeric.

Reports the Line number of the last ERror encountered.

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

DERR, ERR, ERROR, ON ERROR GOTO, RESUME.

Variable

ERR

Return value

Numeric.

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

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

DERR, ERL, ERROR, ON ERROR GOTO, RESUME.

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.

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

ERL, ERR, ERROR, ON ERROR GOTO, RESUME.

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.

EVERY 500,2 GOSUB 50

AFTER, REMAIN.

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.

PRINT EXP(6.876)
968.743625

LOG.

REAL EXP.

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.

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

GRAPHICS PEN.

GRA FILL.

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.

PRINT FIX(9.99999)
9

CINT, INT, ROUND.

REAL FIX.

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.

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

NEXT, WHILE.

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.

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

MC WAIT FLYBACK.

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).

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.

PRINT FRE(0)

PRINT FRE("")

Command

GOSUB <line number>

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

GOSUB 210

RETURN.

Command

GOTO <line number>

Branch to specified line number.

GOTO 90

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.

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

CLG, GRAPHICS PEN, INK, MASK, TAG, TAGOFF.

GRA SET PAPER, GRA GET PAPER.

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.

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

GRAPHICS PAPER, INK, MASK, TAG, TAGOFF.

GRA SET PEN, GRA GET PEN.

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.

PRINT HEX$(65534)
FFFE

BIN$, STR$.

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

?HIMEM 
43903 

FRE, MEMORY.

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.

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

THEN, ELSE, GOTO, OR, AND, WHILE.

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.

INK 0,6,3

BORDER, PEN, PAPER, SPEED INK.

SCR SET INK, SCR GET INK.

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:

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  

INPUT, INKEY$.

KM TEST KEY.

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.

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

INPUT, INKEY.

KM READ KEY.

Function

INP(<port number>)

Return value

Numeric.

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

PRINT INP(&F500)

OUT, WAIT.

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.

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 

LINE INPUT, READ, INKEY$.

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).

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

MID$, LEFT$, RIGHT$.

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.

PRINT INT(-1.995)  
-2

CINT, FIX, ROUND.

REAL INT.

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).

10 IF JOY(0) AND 8 THEN GOTO 100

INKEY.

KM GET JOYSTICK.

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.

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

KEY DEF.

KM SET EXPAND.

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.

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.

KEY.

KM SET TRANSLATE.

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.

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

MID$, RIGHT$.

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>.

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

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.

LET x=100

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

x=100

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.

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

READ, INPUT, INKEY$.

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).

LIST 100-1000,#1

LIST -200 or LIST 30-

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.

LOAD "TITLE.SCR",&C000

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.

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

WINDOW.

TXT SET CURSOR.

Function

LOG(<numeric expression>)

Return value

Numeric (Real).

Calculates the natural logarithm of numeric expression.

?LOG(9999) 
9.21024037 

EXP, LOG10.

REAL LOG.

Function

LOG10 ( <numeric expression> )

Return value

Numeric (Real).

Calculates the base 10 logarithm of <numeric expression>.

?LOG10(9999)  
3.99995657  

EXP,LOG.

REAL LOG10.

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.

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

UPPER$.

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.

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

DRAW, DRAWR, GRAPHICS PAPER, GRAPHICS PEN.

Function

MAX(<list of: numeric expression>))

Return value

Numeric.

Extracts the largest value from the list of numeric expressions.

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

MIN.

REAL COMPARISON.

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.

MEMORY &20AA

HIMEM,FRE.

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.

MERGE "PLAN"

LOAD, CHAIN, CHAIN MERGE.

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.

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

LEFT$, RIGHT$.

Function

MIN(<list of: <numeric expression>))

Return value

Numeric.

Extracts the smallest value from the list of numeric expressions.

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

MAX.

REAL COMPARISON.

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.

MODE 1

WINDOW, ORIGIN.

SCR SET MODE, SCR GET MODE.

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

MOVE 34,34

MOVER, PLOT, PLOTR, DRAW, DRAWR, ORIGIN, TEST, TESTR, XPOS, YPOS.

GRA MOVE ABSOLUTE.

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

MOVER 34,34

MOVE , PLOT, PLOTR, DRAW, DRAWR, TEST, TESTR, XPOS, YPOS.

GRA MOVE RELATIVE.

Command

NEW

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

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.

FOR n=1 TO 1000:NEXT n

FOR.

Operator

NOT <argument>

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

PRINT NOT -1
 0
PRINT NOT 0
-1

AND, OR, XOR.

Command

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

(see below)

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.

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

GOTO, GOSUB.

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.

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

ON BREAK GOSUB, ON BREAK STOP.

There's several way to achieve a similar result:

KEY 66,0,0,0,0

Command

ON BREAK GOSUB <line number>

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

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

ON BREAK STOP, RETURN.

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.

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

ON BREAK GOSUB.

Command

ON ERROR GOTO <linenumber>

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

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

ERR, ERL, RESUME.

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

ON SQ(2) GOSUB 2000

SOUND, SQ.

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.

100 OPENIN "!INFORMATION"

CLOSEIN, OPENOUT.

CAS IN OPEN.

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.

OPENOUT "!FACTS"

CLOSEOUT, OPENIN.

CAS OUT OPEN.

Operator

<argument> OR <argument>

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

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

AND, NOT, XOR.

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.

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

WINDOW.

GRA SET ORIGIN, GRA GET ORIGIN.

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>.

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

INP, WAIT.

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.

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  

INK, WINDOW, PEN.

TXT SET PAPER, TXT GET PAPER.

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).

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

POKE.

Command

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

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

PEN 1,2

INK, PAPER.

TXT SET PEN, TXT GET PEN.

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.

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!"   

DEG, RAD.

REAL PI.

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

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.

DRAW, DRAWR, PLOT, PLOTR, MOVE, MOVER, ORIGIN, TEST, TESTR, XPOS, YPOS.

GRA PLOT ABSOLUTE.

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

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

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.

DRAW, DRAWR, PLOT, PLOTR, MOVE, MOVER, ORIGIN, TEST, TESTR, XPOS, YPOS.

GRA PLOT RELATIVE.

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

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.

POKE &00FF,10

PEEK.

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.

PRINT POS(#0) 
1  

VPOS.

SCR CHAR POSITION.

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.

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

USING, TAB, SPC.

TXT OUTPUT.

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.

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

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.

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

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:

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.

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

Example template: !

• 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

SPC, TAB.

Command

RAD

Set Radians Mode

DEG,SIN, COS, TAN, ATN.

SET ANGLE MODE.

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.

10 RANDOMIZE 23 
20 PRINT RND(6) 

RND.

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.

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

DATA, RESTORE.

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.

RELEASE 4

SOUND.

SOUND RELEASE.

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.

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

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.

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

AFTER, DI, EI, EVERY.

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.

RENUM

RENUM 100,,100

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.

 
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 

READ, DATA.

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.

ON ERROR GOTO.

Command

RETURN

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

GOSUB, ON x GOSUB, ON SQ GOSUB, AFTER n GOSUB, EVERY n GOSUB, ON BREAK GOSUB.

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.

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

MID$, LEFT$.

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.

10 RANDOMIZE 23 
20 PRINT RND  

RANDOMIZE.

REAL RND, REAL RND(0).

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.

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 

INT, FIX, CINT, ABS.

Command

RUN <string expression>

RUN [<line number>]

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

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.

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.

CONT, END, LOAD, STOP.

Command

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

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

SAVE "myprog"

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 "myprog.asc",A

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

LOAD, RUN <filename>, MERGE, CHAIN, CHAIN MERGE.

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.

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"  

ABS.

REAL SIGNUM/SGN.

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.

PRINT SIN(PI/2)  
1 

COS, TAN, ATN, DEG, RAD.

REAL SIN.

Command

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

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

ENV, ENT.

SOUND.

Function

SPACE$(<integer expression>)

Return value

String.

Creates a string of spaces of the given length.

SPACE$(190)

PRINT, SPC, TAB.

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!

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

INK, BORDER.

SCR SET FLASHING, SCR GET FLASHING.

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.

SPEED KEY 20,3

KEY DEF.

KM SET REPEAT, KM GET REPEAT, KM SET DELAY, KM GET DELAY.

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.

SPEED WRITE 1

SAVE.

CAS SET SPEED.

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

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 

SOUND, ON SQ GOSUB.

SOUND CHECK.

Function

SQR(<numeric expression>)

Return value

Numeric.

Returns the square root of <numeric expression>.

PRINT SQR(9) 
3 

PRINT.

REAL SQR.

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.

300 IF n<0 THEN STOP  

CONT, END.

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.

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

PRINT, VAL, hex$, BIN$.

Function

STRING$(<integer expression>,<character ex pression>)

Return value

String.

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

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

SPACE$.

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.

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 

SYMBOL AFTER.

TXT GET MATRIX, TXT SET MATRIX.

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.

SYMBOL AFTER 90

SYMBOL.

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 ;

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

TAGOFF.

TXT SET GRAPHIC.

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.

TAGOFF #0

TAG.

TXT SET GRAPHIC.

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).

DEG
PRINT TAN(45) 
 1

COS, SIN, ATN, DEG, RAD.

TEAL TANGEANT.

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.

PRINT TEST(300,300)  

TESTR, MOVE, MOVER, PLOT, PLOTR, DRAW, DRAWR.

GRA TEST ABSOLUTE.

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.

TESTR(5,5)

TEST, MOVE, MOVER, PLOT, PLOTR, DRAW, DRAWR.

GRA TEST RELATIVE.

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.

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

KL TIME PLEASE, KL TIME SET.

Command

TRON

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.

RUN.

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.

PRINT UNT(65535)
-1

INT, FIX, CINT, ROUND.

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.

PRINT UPPER$("amstrad")
AMSTRAD

LOWER$.

Function

VAL(<string expression>)

Return value

Numeric.

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

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

STR$.

Function

VPOS (#<stream expression>)

Return value

Numeric.

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

PRINT VPOS(#0) 

POS.

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.

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).

INP , OUT.

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.

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

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.

WEND.

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.

WIDTH 86

PRINT, POS.

Command

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

Sets a text window for a given screen stream.

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 

ORIGIN.

TXT WIN ENABLE, TXT GET WINDOW, TXT CLEAR WINDOW.

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.

WINDOW SWAP 0,2 

WINDOW, PEN, PAPER, TAG.

TXT WIN ENABLE, TXT GET WINDOW, TXT CLEAR WINDOW.

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).

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

Operator

<argument> XOR <argument>

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

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

AND, OR, NOT.

Function

XPOS

Return value

Numeric.

Establishes the horizontal position of the graphics cursor.

YPOS, MOVE, MOVER, ORIGIN.

GRA ASK CURSOR.

Function

YPOS

Return value

Numeric.

Establishes the vertical position of the graphics cursor.

XPOS, MOVE, MOVER, ORIGIN.

GRA ASK CURSOR.

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.

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

PRINT, WIDTH.

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.

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

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

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

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

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.

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.

The line referenced cannot be found.

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

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

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

The last command attempted is not valid in Direct Mode.

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.

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

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

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.

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.

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

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

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

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

BASIC has encountered an incomplete expression.

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

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

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.

Cannot find a NEXT to match a FOR command.

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

BASIC cannot find a taker for an external command.

Cannot find a WEND to match a WHILE command.

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

Compatibility

Only reported in BASIC 1.1 (With AMSDOS).

(See Disc error below)

Compatibility

Only reported in BASIC 1.1 (With AMSDOS).

(See Disc error below)

Compatibility

Only available on BASIC 1.1 (With AMSDOS).

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

[ESC] has been pressed.

The stream is not in suitable state.

Hard end of file has been reached.

The disc changed while files were open.

Soft end of file has been detected.

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