CPCWiki - THE Amstrad CPC encyclopedia! - User contributions [en]

User:Laurentvaucher

2006-12-20T12:05:10Z

Laurentvaucher:

Well, I was just a simple french CPC464 user (I'm still french and simple, but I only use CPC emulators now). I used to program in BASIC (a lot) and in assembler (for limited graphical stuff). My most memorable experience was reproducing the sound of a roulette with the cassette deck, using some subtle POKEs.

User:Laurentvaucher

2006-12-20T12:04:52Z

Laurentvaucher:

Well, I was just a simple french CPC464 user (I'm still french and simple, but I only use PC emulators now). I used to program in BASIC (a lot) and in assembler (for limited graphical stuff). My most memorable experience was reproducing the sound of a roulette with the cassette deck, using some subtle POKEs.

User:Laurentvaucher

2006-12-20T12:04:38Z

Laurentvaucher:

Well, I was just a simple french CPC464 user (I'm still french and simple, bu I only use PC emulators now). I used to program in BASIC (a lot) and in assembler (for limited graphical stuff). My most memorable experience was reproducing the sound of a roulette with the cassette deck, using some subtle POKEs.

Locomotive BASIC

2006-12-20T08:09:09Z

Laurentvaucher: /* DRAWR xr, y2, [[i1][,i2]] */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
: Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
: Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: Switch to degrees mode for trigonometric functions (<tt>SIN</tt>, <tt>COS</tt>...).

''See also:'' <tt>RAD</tt>

==== DELETE [line] ====
: Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, yr, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
: Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
: Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: Switch to radians mode for trigonometric functions (<tt>SIN</tt>, <tt>COS</tt>...).

''See also:'' <tt>DEG</tt>

==== RANDOMIZE [seed] ====
: Resets the pseudo-random generator to the given seed. What is strange is that if no seed is given, one is interactively prompted for.

A common idiom to have a ''random'' random seed is to do:
<pre>
RANDOMIZE TIME
</pre>

==== READ variable ====
: Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM [any text]====
: Introduces a comment.

==== RENUM [newLine],[oldLine],[step] ====
: Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

: Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
: Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
: Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
: Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
: Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:55:52Z

Laurentvaucher: /* RANDOMIZE */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
: Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
: Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: Switch to degrees mode for trigonometric functions (<tt>SIN</tt>, <tt>COS</tt>...).

''See also:'' <tt>RAD</tt>

==== DELETE [line] ====
: Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
: Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
: Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: Switch to radians mode for trigonometric functions (<tt>SIN</tt>, <tt>COS</tt>...).

''See also:'' <tt>DEG</tt>

==== RANDOMIZE [seed] ====
: Resets the pseudo-random generator to the given seed. What is strange is that if no seed is given, one is interactively prompted for.

A common idiom to have a ''random'' random seed is to do:
<pre>
RANDOMIZE TIME
</pre>

==== READ variable ====
: Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM [any text]====
: Introduces a comment.

==== RENUM [newLine],[oldLine],[step] ====
: Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

: Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
: Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
: Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
: Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
: Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:52:15Z

Laurentvaucher: /* REM */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
: Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
: Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: Switch to degrees mode for trigonometric functions (<tt>SIN</tt>, <tt>COS</tt>...).

''See also:'' <tt>RAD</tt>

==== DELETE [line] ====
: Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
: Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
: Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: Switch to radians mode for trigonometric functions (<tt>SIN</tt>, <tt>COS</tt>...).

''See also:'' <tt>DEG</tt>

==== RANDOMIZE ====
: [...]

==== READ variable ====
: Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM [any text]====
: Introduces a comment.

==== RENUM [newLine],[oldLine],[step] ====
: Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

: Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
: Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
: Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
: Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
: Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:51:07Z

Laurentvaucher: /* Command list */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
: Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
: Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: Switch to degrees mode for trigonometric functions (<tt>SIN</tt>, <tt>COS</tt>...).

''See also:'' <tt>RAD</tt>

==== DELETE [line] ====
: Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
: Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
: Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: Switch to radians mode for trigonometric functions (<tt>SIN</tt>, <tt>COS</tt>...).

''See also:'' <tt>DEG</tt>

==== RANDOMIZE ====
: [...]

==== READ variable ====
: Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
: Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

: Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
: Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
: Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
: Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
: Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:50:22Z

Laurentvaucher: /* RAD */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
: Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
: Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: Switch to degrees mode for trigonometric functions (<tt>SIN</tt>, <tt>COS</tt>...).

''See also:'' <tt>RAD</tt>

==== DELETE [line] ====
: Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
: Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
: Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: Switch to radians mode for trigonometric functions (<tt>SIN</tt>, <tt>COS</tt>...).

''See also:'' <tt>DEG</tt>

==== RANDOMIZE ====
: [...]

==== READ variable ====
: Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
: Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

: Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
: Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
: Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
: Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
: Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:49:28Z

Laurentvaucher: /* DEG */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
: Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
: Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: Switch to degrees mode for trigonometric functions (<tt>SIN</tt>, <tt>COS</tt>...).

''See also:'' <tt>RAD</tt>

==== DELETE [line] ====
: Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
: Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
: Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
: Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
: Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

: Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
: Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
: Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
: Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
: Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:42:16Z

Laurentvaucher: /* CHR$ (n) */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
: Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
: Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE [line] ====
: Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
: Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
: Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
: Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
: Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

: Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
: Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
: Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
: Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
: Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:41:55Z

Laurentvaucher: /* SYMBOL AFTER n */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
: Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
: Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE [line] ====
: Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
: Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
: Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
: Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
: Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

: Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
: Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
: Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
: Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:41:09Z

Laurentvaucher: /* SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
: Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
: Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE [line] ====
: Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
: Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
: Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
: Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
: Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

: Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
: Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
: Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:40:55Z

Laurentvaucher: /* RUN [line] */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
: Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
: Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE [line] ====
: Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
: Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
: Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
: Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
: Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

: Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
: Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:40:34Z

Laurentvaucher: /* RESTORE [line] */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
: Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
: Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE [line] ====
: Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
: Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
: Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
: Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
: Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

: Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:39:43Z

Laurentvaucher: /* RENUM [newLine],[oldLine],[step] */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
: Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
: Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE [line] ====
: Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
: Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
: Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
: Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
: Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:39:24Z

Laurentvaucher: /* READ variable */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
: Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
: Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE [line] ====
: Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
: Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
: Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
: Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:39:11Z

Laurentvaucher: /* LOCATE x,y */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
: Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
: Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE [line] ====
: Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
: Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
: Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:38:57Z

Laurentvaucher: /* EDIT line */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
: Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
: Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE [line] ====
: Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
: Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:38:23Z

Laurentvaucher: /* DELETE [line] */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
: Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
: Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE [line] ====
: Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:38:14Z

Laurentvaucher: /* DATA x1[,x2,x3...] */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
: Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
: Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE [line] ====
Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:37:52Z

Laurentvaucher: /* BORDER color */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
: Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE [line] ====
Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:37:23Z

Laurentvaucher: /* EDIT */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE [line] ====
Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT line ====
Copies one program line to screen in edition mode.

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:35:19Z

Laurentvaucher: /* BORDER */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER color ====
Changes the color of the border.

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE [line] ====
Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT ====
: [...]

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:34:33Z

Laurentvaucher: /* DELETE */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER ====
: [...]

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE [line] ====
Deletes the current program completely (without argument) or only the given line.

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT ====
: [...]

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:24:15Z

Laurentvaucher: /* RUN */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER ====
: [...]

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE ====
: [...]

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT ====
: [...]

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN [line] ====
Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:20:21Z

Laurentvaucher: /* RESTORE */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER ====
: [...]

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE ====
: [...]

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT ====
: [...]

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE [line] ====

Resets the data pointer used by <tt>READ</tt>. When used without parameters, resets the pointer to the first data in the program. Otherwise, resets the pointer to the given line number.

''Example:''
<pre>
10 DATA 10,11,12,13,14
20 DATA 20
READ i:PRINT i
10
Ready
READ i:PRINT i
11
Ready
RESTORE
Ready
READ i:PRINT i
10
Ready
RESTORE 20
Ready
READ i:PRINT i
20
Ready
</pre>

''See also:'' <tt>DATA</tt>, <tt>READ</tt>

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN ====
: [...]

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:10:29Z

Laurentvaucher: /* DATA x1[,x2,x3...] */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER ====
: [...]

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

''See also:'' <tt>READ</tt>, <tt>RESTORE</tt>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE ====
: [...]

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT ====
: [...]

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE ====
: [...]

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN ====
: [...]

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:10:01Z

Laurentvaucher: /* READ variable */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER ====
: [...]

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE ====
: [...]

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT ====
: [...]

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

''See also:'' <tt>DATA</tt>, <tt>RESTORE</tt>

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE ====
: [...]

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN ====
: [...]

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:08:53Z

Laurentvaucher: /* READ variable */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER ====
: [...]

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE ====
: [...]

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT ====
: [...]

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
Gets the next data item (from <tt>DATA</tt> commands), stores it in the given variable and moves to the next item.
The variable must be of the correct type.

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE ====
: [...]

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN ====
: [...]

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T21:08:19Z

Laurentvaucher: /* READ */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER ====
: [...]

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE ====
: [...]

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT ====
: [...]

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ variable ====
Gets the next data item (from <tt>DATA</tt> commands) and moves to the next.
The variable must be of the correct type.

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE ====
: [...]

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN ====
: [...]

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T20:57:26Z

Laurentvaucher: /* RENUM [newLine],[oldLine],[step] */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER ====
: [...]

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE ====
: [...]

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT ====
: [...]

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ ====
: [...]

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.
It is important to note that ''jumps'' (<tt>GOTO</tt>, <tt>GOSUB</tt> and the like) are automatically converted to the new line numbers.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE ====
: [...]

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN ====
: [...]

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T20:51:28Z

Laurentvaucher: /* RENUM [newLine],[oldLine],[step] */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER ====
: [...]

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE ====
: [...]

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT ====
: [...]

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ ====
: [...]

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 GOTO 20
20 GOTO 30
30 GOTO 10
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== RESTORE ====
: [...]

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN ====
: [...]

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T20:49:42Z

Laurentvaucher: /* RENUM */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER ====
: [...]

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE ====
: [...]

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT ====
: [...]

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ ====
: [...]

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM [newLine],[oldLine],[step] ====
Renumbers the lines of the current program.

By default, the whole program is renumbered starting at line 10 with multiples of ten.

The whole set of parameters can be used to renumber only the last part of a program.

''Example:''
<pre>
10 REM Line 10
20 REM Line 20
30 REM Line 30
</pre>

becomes, after calling <tt>RENUM 100,20,5</tt>
<pre>
10 REM Line 10
100 REM Line 20
105 REM Line 30
</pre>

==== RESTORE ====
: [...]

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN ====
: [...]

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T20:27:37Z

Laurentvaucher: /* LOCATE */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER ====
: [...]

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE ====
: [...]

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT ====
: [...]

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE x,y ====
Moves the text cursor to the x,y location.

x starts at 1 on the left and goes up to 20 (in mode 0), 40 (in mode 1) or 80 (in mode 2).

y starts at 1 at the top and ends at 25 at the bottom.

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ ====
: [...]

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM ====
: [...]

==== RESTORE ====
: [...]

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN ====
: [...]

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]

Locomotive BASIC

2006-12-19T17:24:12Z

Laurentvaucher: /* DATA */

{{stub}}

[[Image:Screenshots-CPC_Start_screen.jpg|thumb|CPC Start Screen showing Locomotive copyright and BASIC version]]

Locomotive BASIC was a [http://en.wikipedia.org/wiki/BASIC_programming_language BASIC] interpreter for the Amstrad CPC range of computers.

== Description ==

Locomotive BASIC, was one of the best and fastest BASIC implementations of the era. The language benefited both from a clean, well-thought out implementation of the core language by Locomotive, and by the excellent [[firmware]] of the CPC, which lent most of its advanced features to the BASIC.

Unlike the competing Commodore 64, it featured a comprehensive graphic capabilities with its PLOT, DRAW, PAPER, INK, PEN, BORDER and (in BASIC 1.1) FILL commands. It had extensive sound commands, granting control of the [[AY-3-8912]] via the firmware's volume and tone envelope system. With the SOUND command, you could select channels, set envelopes, pitch, noise and volume. That was something unmatched by other computers of that era.

Also there was simple interface for memory management, with MEMORY and LOAD commands. The latter allowed for loading of raw screen data, thus providing easy picture showing. Both through this (combined with CALL, PEEK and POKE) and the firmware's [[RSX]] system, it was easy to mix BASIC and assembly code, thereby speeding up programs by coding the slowest parts directly in machine code. Many successful programs, including games such as [[Radzone]] and applications such as [[PowerPage]], made use of this technique.

With DEF FN, ON variable GOTO and ON variable GOSUB, Locomotive BASIC provided the rudiments of "structured programming", though nowhere near the extent of the PROCedures of [[BBC BASIC]].

All in all, if you compare BASIC interpreters of that era, the Locomotive's seems to be the best 'all-rounder' regarding the combination of speed and complexity, and still some of its features were unmatched by others.

== History ==

The CPC implementation of Locomotive BASIC was developed directly from [[Locomotive Software]]'s existing Z80 BASIC. The existence of this is cited as one of the reasons Locomotive requested that [[Amstrad]] change the CPC's processor from a 6502 to a [[Z80]].

The 464 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 664, 6128 and Plus machines to become BASIC 1.1. Changes were minor but significant for the programmer, and included:

* DEC$ bug removed (in BASIC 1.0, it required two opening brackets and was undocumented)
* Better handling of string arguments to RSXs (|DIR,"*.BAS" rather than a$="*.BAS":|DIR,@a$)
* DATA statements can appear anywhere within a line; in BASIC 1.0, they had to be at the end of a line
* FILL command (fill area with solid colour)
* COPYCHR$ function (fetch character from screen)
* Better garbage collection
* Some number-handling bugs removed (e.g. in FOR loops with negative start/end values)
* FRAME (CALL &BD19)
* Extra, optional 'plotting mode' parameter for DRAW/PLOT commands (supported only through control codes on BASIC 1.0)
* GRAPHICS PAPER, GRAPHICS PEN commands
* ON BREAK CONT (disable ESCape)
* CLEAR INPUT (flush keyboard buffer)
* The AUTO command show the whole line if it exist, it only printed a * on the 464

Some parts of 'BASIC' were actually housed in the firmware ROM, but were not officially accessible to other programs. This included the line editor.

The 'pure BASIC' parts of Locomotive BASIC - i.e. those not concerned with CPC-specific firmware and hardware features - were upgraded to become Mallard BASIC, the CP/M language shipped with the [[PCW]]. This also featured exceptionally advanced random-access file handling, a feature missing from the CPC.

== Command list ==

=== Commands and operators ===

==== AFTER I[,t] GOSUB Ln ====
: Waits for i/50 seconds and then jumps to the subruotine at line Ln.

==== AUTO [Ln, i] ====
: Automaticaly generates line numbers starting at line Ln with increment i between line numbers.
: Use [ESC to leave AUTO mode. Default value for Ln and i is 10.
::''Example:''
::AUTO 100,5 - generates line numbers 100, 105, 110...

==== BORDER ====
: [...]

==== CALL add[,list of parameters] ====
: Allows an externally developed subroutine to be called by BASIC
::''Example:''
::CALL 0 - resets the computer completely

==== CAT ====
: Displays the names of all existing programes on the tape or disk.
::'''Examples:'''
::CAT [ENTER] - lists all disk files in alpha-numeric order
::TAPE [ENTER]
::CAT [ENTER] - lists names of all tape files in their storage order

==== CHAIN ====
: [...]

==== CHAIN MERGE ====
: [...]

==== CLEAR ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.

==== CLG [ink] ====
: Clears the graphics screen to colour specified by ink. If parameter ink is not specified them the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== CLOSEIN ====
: [...]

==== CLOSEOUT ====
: [...]

==== CLS ====
: Clears the screen. The text cursor is moved to the upper left corner.

==== CONT ====
: [...]

==== CURSOR ====
: [...]

==== DATA x1[,x2,x3...]====
Defines a data ''section'' to be used by <tt>READ</tt> calls.
Data values can be of any type (integer, real or string) as long as the corresponding <tt>READ</tt> calls use a variable of the right type.

''Example:''
<pre>
10 DATA "Hello, world!", 42
20 READ message$:PRINT message$
30 READ answer:PRINT "The answer is:";answer
</pre>

==== DEF ====
: [...]

==== DEFINT ====
: [...]

==== DEFREAL ====
: [...]

==== DEFSTR ====
: [...]

==== DEG ====
: [...]

==== DELETE ====
: [...]

==== DI ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.

==== DIM ====
: [...]

==== DRAW x,y [,[i1][,i2]] ====
: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the logical colour.
<pre>
i2 = 0 normal colour i2 = 2 AND colour
i2 = 1 XOR colour i2 = 3 OR colour
</pre>
::''Example:''
::CLG 2
::DRAW 500,400,0 - draws a line from 0,0 to 500,400

==== DRAWR xr, y2, [[i1][,i2]] ====
: Draws a line from current graphics cursor position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as DRAW.
::''Example:''
:: Move 200,200
:: DRAWR 100,100,0 - draws a line from 200,200 to 300,300

==== EDIT ====
: [...]

==== EI ====
: Enable interrupts which have been disabled by DI

==== END ====
: Indicates end of program

==== ENT ====
: [...]

==== ENV ====
: [...]

==== ERASE v[$(i1[,i2]) ====
: Clears the contents of an array that is no longer required.

==== ERL ====
: [...]

==== ERROR i ====
: Returns the error message whose error code number is i.

==== EVERY ====
: [...]

==== FILL i ====
: Fills an area of a graphics screen i colour i (0-15). Default value of i is the current graphics pen colour. Only available in Basic 1.1.

==== FN ====
: [...]

==== FOR TO STEP NEXT ====
: [...]

==== FRAME ====
: Smooths character and graphics movement and reduces flicker (waits for a VSYNC signal). Only available in Basic 1.1. On a CPC 464 you can use CALL &BD19 instead.

==== GOSUB i ====
: Jumps to subroutine which is given as argument.
: ''Example:''
<pre>
10 PRINT "Calling subroutine"
20 GOSUB 100
30 PRINT "Back from subroutine"
40 END
100 REM Begin of the subroutine
110 PRINT "Subroutine started"
120 RETURN
</pre>

==== GOTO i ====
: Jumps to the line number which is given as argument.
: ''Example:''
<pre>
10 GOTO 100
20 REM not executed
30 REM not executed
100 PRINT "Hello World!"
</pre>

==== GRAPHICS ====
: [...]

==== IF THEN ELSE ====
: [...]

==== INK ====
: [...]

==== INPUT ====
: [...]

==== KEY ====
: [...]

==== LET ====
: [...]

==== LINE ====
: [...]

==== LIST ====
: [...]

==== LOAD ====
: [...]

==== LOCATE ====
: [...]

==== MASK ====
: [...]

==== MEMORY ====
: [...]

==== MERGE ====
: [...]

==== MID$ ====
: [...]

==== MODE ====
: Changes the screen mode: MODE 0 is 160x200 in 16 colors, MODE 1 is 320x200 4 colors and MODE 2 is 640x200 2 colors.

==== MOVE ====
: [...]

==== MOVER ====
: [...]

==== NEW ====
: [...]

==== ON BREAK ====
: [...]

==== ON ERROR ====
: [...]

==== OPENIN ====
: [...]

==== OPENOUT ====
: [...]

==== ORIGIN ====
: [...]

==== OUT ====
: [...]

==== PAPER ====
: [...]

==== PEN ====
: [...]

==== PLOT ====
: [...]

==== PLOTR ====
: [...]

==== POKE ====
: [...]

==== PRINT ====
: [...]

==== RAD ====
: [...]

==== RANDOMIZE ====
: [...]

==== READ ====
: [...]

==== RELEASE ====
: [...]

==== REM ====
: [...]

==== REM ====
: [...]

==== RENUM ====
: [...]

==== RESTORE ====
: [...]

==== RESUME ====
: [...]

==== RETURN ====
: [...]

==== RUN ====
: [...]

==== SAVE ====
: [...]

==== SOUND ====
: [...]

==== SPC ====
: [...]

==== SPEED ====
: [...]

==== SQ ====
: [...]

==== STOP ====
: [...]

==== SUB ====
: [...]

==== SWAP ====
: [...]

==== SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8] ====
Redefines the appearance of the character at index n.
Each of the following eight integers defines the contents of one pixel row, starting at the top of the character.
Each character fits in an 8x8 pixel grid.
Missing lines are considered as empty.

''Example:''
<pre>
SYMBOL 255,255,129,129,129,129,129,129,255
PRINT CHR$(255)
</pre>
defines character 255 to look like an empty square and prints it.

Initially, only characters with indices ranging from 240 to 255 can be redefined.
See also <tt>SYMBOL AFTER</tt> to allow redefinition of arbitrary characters.

==== SYMBOL AFTER n ====
Allows the redefinition of character symbols from index n included.

Symbol redefinitions are made using the SYMBOL command above.
Initially, only symbols from index 240 to 255 can be redefined. This initial situation can be restored with <tt>SYMBOL AFTER 240</tt>. Symbol previously redefined are restored to their original appearance.

==== TAB ====
: [...]

==== TAG ====
: [...]

==== TAGOFF ====
: [...]

==== TROFF ====
: [...]

==== TRON ====
: [...]

==== USING ====
: [...]

==== WAIT ====
: [...]

==== WHILE WEND ====
: [...]

==== WIDTH ====
: [...]

==== WINDOW ====
: [...]

==== WRITE ====
: [...]

==== ZONE ====
: [...]

=== Operators ===

==== AND ====
: [...]

==== MOD ====
: [...]

==== NOT ====
: [...]

==== OR ====
: [...]

==== XOR ====
: [...]

=== Functions ===

==== ABS (n) ====
: Returns the absolute value of n by ignoring the sign value.
::''Example''
:: PRINT ABS(-3.5) - prints 3.5

==== ASC ====
: [...]

==== ATN (n) ====
: Returns the arctangent of n.

==== BIN$ (i1,[i2]) ====
: Returns binary representation of i1 between -32768 and 65535. The number of binary digits (0s and 1s) is specified by i2 (0-16)
::''Example:''
:: PRINT BIN$(66,8) - prints 01000010

==== CHR$ (n)====
Returns the character for a given index n. For instance CHR$(65) returns the character 'A'. Valid indices range from 0 (zero) to 255.

As an example, try the following basic program :

<pre>10 print chr$(208+rnd(2));:goto 10</pre>

It will draw a random maze with characters 208 and 209, which are an horizontal and a vertical bar.

==== CINT ====
: [...]

==== COPYCHR$ ====
: [...]

==== COS ====
: [...]

==== CREAL ====
: [...]

==== DEC$ ====
: [...]

==== DERR ====
: [...]

==== EOF ====
: [...]

==== ERR ====
: [...]

==== EXP ====
: [...]

==== FIX ====
: [...]

==== FRE ====
: [...]

==== HEX$ ====
: [...]

==== HIMEM ====
: [...]

==== INKEY ====
: [...]

==== INKEY$ ====
: [...]

==== INP ====
: [...]

==== INSTR ====
: [...]

==== INT ====
: [...]

==== JOY ====
: [...]

==== LEFT$ ====
: [...]

==== LEN ====
: [...]

==== LOG ====
: [...]

==== LOG10 ====
: [...]

==== LOWER$ ====
: [...]

==== MAX ====
: [...]

==== MIN ====
: [...]

==== PEEK ====
: [...]

==== PI ====
: [...]

==== POS ====
: [...]

==== REMAIN ====
: [...]

==== RIGHT$ ====
: [...]

==== RND [(n)] ====
: Generates the next random number in the current squence if n is positive or omitted. If n = 0, the random number generated will be the same as the last random number generated.

==== ROUND (n[,i1]) ====
: Rounds n to a number of decimal places or to the power of ten specified by i. If i is negative, the n is rounded to give an absolute integer with i zeros before the decimal point.
::''Example''
:: PRINT ROUND(1562.357,2):PRINT ROUND(1562.375,-2) - prints 1562.36 1600

==== SGN (n) ====
: Returns 1 if n is positive, 0 if n = 0, -1 if n is negative.

==== SIN (n) ====
: Returns sine of n in degree or radian mode (see DEG and RAD)

==== SPACE$ ====
: [...]

==== SQ (channel) ====
: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1, 2, 3 = A, B, C.
<pre>
Bits 0,1 and 2 number of free entries in the queue
Bits 3,4 and 5 redezvous state at head of the queue
Bit 6 head of the queue is held
Bit 7 channel is currently active
</pre>

==== SQR (n) ====
: Returns the square root of n.

==== STR$ ====
: [...]

==== STRING$ ====
: [...]

==== TAN ====
: [...]

==== TEST ====
: [...]

==== TESTR ====
: [...]

==== TIME ====
: Returns time elapsed since the computer was switched on or reset.
: One second = TIME/300.

==== UNT ====
: [...]

==== UPPER$ ====
: [...]

==== VAL ====
: [...]

==== VPOS (#st) ====
: Reports the current row (line) position of the text cursor relative to the top of the text windows of the specified stream.

==== XPOS ====
: [...]

==== YPOS ====
: [...]

''(Please, fill in. Looks like a lot of work ;-) ...)''

== Other Basic Dialects avaliable for the CPC ==

[[BBC Basic]]

== Web links ==

* [http://www.kjthacker.f2s.com/docs/bastech.html Technical information at the Unofficial Amstrad WWW Resource]
* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]

[[Category:Programming]]