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

Locomotive BASIC

2025-10-02T13:05:04Z

Arnoldemu: /* SAVE "filename" [,filetype][,paramter1,parameter2,parameter3] */

For other BASIC language versions see the [[:Category:BASIC]]

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

It was availlable directly from in-built ROMs on [[CPC old generation]] and on the [[Plus System Cartridge]] for the [[Plus]] range. [https://benchmarko.github.io/CPCBasic/ Online Interpreter]

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

If you are interested in more information about the different versions of the CPC's BASIC and the technical details, you can have a look at the article "[[Technical information about Locomotive BASIC]]".

Another helpful and further resource of information about BASIC and a similar comprehension to this is Grimware's Website about the CPC http://www.grimware.org/doku.php/documentations/software/locomotive.basic/start

== 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 and Spanish 472 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 472 (British), 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.

== Variables ==
Many contemporary BASIC interpreters only supported the first few characters of a variable name as a discriminator. For example <code>WATER$</code> and <code>WALDO$</code> would refer to the same variable on a Commodore 64 or Apple II. But Locomotive BASIC allowed variable names up to 40 characters in length, so <code>THEQUICKBROWNFOXJUMPEDOVERTHELAZYDOGFAST$</code> and <code>THEQUICKBROWNFOXJUMPEDOVERTHELAZYDOGFATS$</code> could be use as separate variables.

=== Real (Floating Point) Numbers ===

This is the default type for a Locomotive BASIC variables, but can be clarified using <code>!</code> after the variable name, e.g., <code>real!=500.0</code>.
You can force all variables starting with specific letters to be this type by using the <code>DEFREAL</code> keyword.
In many cases you don't want to use these, as they are slower than using the integer type, and use more memory (5 bytes, as opposed to 2).

=== Signed 16-bit Integers ===

Defined using <code>%</code> after the variable name, e.g., <code>integer%=500</code>.
You can force all variables starting with specific letters to be this type by using the <code>DEFINT</code> keyword.
These can store values between -32,768 and 32,767.
To assign a 16-bit value to a signed integer directly, you should give the number in a hexadecimal format, e.g., <code>uint=&c0000</code>.

=== Strings ===

These are defined by using <code>$</code> after the variable name, e.g., <code>str$="Hello"</code>.
You can force all variables starting with specific letters to be this type by using the <code>DEFSTR</code> keyword.
A String can be up to 255 characters long.

== Type Conversions ==

The BASIC functions <code>ROUND</code>, <code>INT</code>, <code>CINT</code> and <code>FIX</code> can be used to convert real numbers into integers taking some care about rounding. The difference is in rounding mode - <code>ROUND</code> rounds to nearest, <code>FIX</code> rounds to zero, <code>INT</code> always rounds down, and <code>CINT</code>rounds up. e.g., <code>value%=INT(3.14)</code>. Note that if you don't specify the % you will actually get a real number still.

To convert an integer to a real number, you can use the <code>UNT</code> function which will take the value supplied and return the two's complement number. e.g., <code>real=UNT(&ABCD)</code>.

<pre>
w=UNT(50000)
Ready
PRINT w
-15536
Ready
█
</pre>

If you want an integer result from division, use the <code>\</code> integer division operator. e.g., <code>int=value\divisor</code>. This is as opposed to the standard <code>/</code> division operator, that can create a real number.

== Command list ==

=== Commands and operators ===

==== <code>AFTER ‹time delay›[,‹timer number›] GOSUB ‹line number› </code>====
: Waits for ‹time delay›/50 seconds and then jumps NON-RECURRING to the subroutine at ‹line number› (see also <code>"EVERY i[,t] GOSUB line"</code>).

==== <code>AUTO [‹line number›][,‹increment›] </code>====
: Automatically generates line numbers starting at ‹line number› with ‹increment› after each entered line number. Use '''[ESC]''' to leave AUTO mode. Default values for ‹line number› and ‹increment› are 10.

: Example:
<pre>AUTO 100,5 :REM generates line numbers 100, 105, 110...</pre>

==== <code>BORDER ‹colour›[,‹colour›] </code>====
: Changes the colour of the border. If the second argument is supplied the border flashes between the two colours.

==== <code>CALL ‹address expression›[,‹list of: parameter›] </code>====
: Allows a machine code routine to be called by BASIC. Variables, string values and constants can be passed to the routine. Values of any supported type can be passed back by supplying a variable with <code>@</code> in front of it. This passes the address of the variable to the routine although it doesn't implicitly know the data type.
: Example:
<pre>CALL 0 :REM resets the computer completely</pre>

==== <code>CAT</code> ====
: Displays the names of the files on the tape or disc. Tape files are displayed in the order they are encountered. Disc files are sorted alphabetically by ASCII code. Only files matching the current user are displayed. Files marked as system are not displayed.
: Examples:
<pre>CAT :REM lists all disc files in alpha-numeric (ASCII) order</pre>

<pre>|TAPE :CAT :REM lists names of all tape files in their storage order</pre>

==== <code>CHAIN ‹file name›[,‹line number expression›] </code>====

:Enables the specified program to be loaded and RUN automatically. If the optional parameter ‹line number expression› is specified, the program execution will commence from that line.

==== <code>CHAIN MERGE ‹file name›[,‹line number expression› | [,[‹line number expression›],DELETE ‹line number range›]] </code>====

:Loads the specified program from tape or disc, merges it into the program in memory, and starts execution of the merged program. The parameter <code>DELETE</code> ‹line number range› is used to delete part of the original program before running it, if required.

==== <code>CLEAR</code> ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.
: The command clear inside a subroutine (<code>GOSUB</code>... <code>RETURN</code>) will also clear the "stack pointer" address of the gosub heap. That means that a RETURN won't work and a GOTO has to be used instead.

==== <code>CLG [‹masked ink›] </code>====
: Clears the graphics screen to colour specified by <code>‹masked ink›</code>. If parameter <code>‹masked ink›</code> is not specified then the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== <code>CLOSEIN</code> ====
: Closes any input file (tape or disc).

==== <code>CLOSEOUT</code> ====
: Closes any output file (tape or disc).

==== <code>CLS [#‹stream expression›]</code>====
: Clears the window specified by ‹stream expression›. If ‹stream expression› is omitted it defaults to #0 (usually the whole screen). The text cursor of the stream is moved to the upper left corner.

==== <code>CONT</code> ====
: CONTinues program execution interrupted either by [ESC] [ESC] or as a result of STOP within a program. A program cannot be continued after being modified.

==== <code>CURSOR ‹expression› </code>====
: <code>‹expression›</code> must be either 0 or 1.

==== <code>DATA x1[,x2,x3...]</code> ====
: 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>

==== <code>DEF</code> ====
: DEF means "define" and comes along with defining a function in case of DEF FN or defining variables in case of DEFREAL, DEFINT or DEFSTR.
: DEF FN must come before using the statement FN.
: DEF with a variable declaration should come before using a variable.
: (see also FN)

==== <code>DEFINT ‹letter range›</code> ====
:Forces all variables(s) starting with the specified letter(s) to be integer variables. Singular letters could be defined or a range by a minus symbol between two letters.

:Examples:
<pre>
20 DEFINT a-z:' sets all variables starting with an A until Z as integer.
</pre>
or
<pre>
10 DEFINT F,S ..... (or 10 DEFINT A-Z)
20 FIRST=111.11:SECOND=22.2
30 PRINT FIRST,SECOND:' prints out 111 22
</pre>

==== <code>DEFREAL ‹letter range›</code> ====
: Sets the default for variable(s) with the specified first letter(s) to a floating point figure.

==== <code>DEFSTR ‹letter range›</code> ====

: Sets the default for variable(s) with the specified first letter(s) to string(s) variables.

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

==== <code>DELETE [first line][-[last line]]</code> ====
: Deletes the current program completely (without arguments) or only the given line or line range. Even
: <code>DELETE -</code>
: is legal, it has the same effect as
: <code>DELETE</code>
: The lines specified do not have to exist, all lines matching the range will be deleted and having no matches does not cause an error.

==== <code>DI</code> ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.
: This means that DI (if it's activated in a subroutine) is useful helping a low-priority-interrupt not to be stopped by a higher-priority-interrupt. RETURN then re-enable the interrupt without EI.

==== <code>DIM a[%|!|$](d1[,d2[,...]])</code> ====

: Creates array <code>a</code> with single or multiple dimensions. You may optionally specify integer (<code>%</code>), real (<code>!</code>) or string (<code>$</code>) type otherwise it defaults to the current type set for the first letter of the array name. <code>d1</code> is size of first dimension-1, <code>d2</code> is size of second dimension-1 and so on. <code>DIM x(10)</code> will create an array with 11 elements, <code>x(0)</code> is the first element, <code>x(10)</code> is the eleventh and last. You can specify as many dimensions as will fit on one 255 character line, which is a maximum of 125. Trying to create an array that already exists will generate an <code>Array already dimensioned</code> error. If an array is not specified by <code>DIM</code> before being accessed, each dimension value defaults to 10. The maximum dimensions that can be created this way is three.

==== <code>DRAW x,y[,[i1][,i2]]</code> ====

: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the drawing style.

: 4 drawing styles:
<pre>
i2 = 0 normal colour
i2 = 1 XOR colour
i2 = 2 AND colour
i2 = 3 OR colour
</pre>
: Example:
<pre>
CLG 2
DRAW 500,400,0 :REM draws a line from 0,0 to 500,400
</pre>

<code>DRAWR xr,yr[,[i1][,i2]]</code> ====

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

<pre>
Move 200,200
DRAWR 100,100,0 - draws a line from 200,200 to 300,300
</pre>

==== <code>EDIT ‹line›</code> ====
: Display 1 program line for editing.

The following keys can be used in editing mode, or during typing in BASIC:

CTRL+TAB - toggle overwrite/insert mode
CTRL+CURSOR LEFT or CTRL+CURSOR UP - go to start of line
CTRL+CURSOR RIGHT or CTRL+CURSOR DOWN - go to end of line
CURSOR LEFT - move left one character
CURSOR RIGHT - move right one character
ESC - quit editing and do not accept changes
ENTER/RETURN - quit editing and accept changes
SHIFT + CURSOR UP/DOWN/LEFT/RIGHT - enter copy mode. You can move the cursor to where you want to copy from. Hold SHIFT and cursors to move copy cursor.
COPY - copy character covered by copy cursor.
DEL - delete character and go back a char
CLR - delete character under cursor
CTRL + CAPS LOCK - toggle shift lock.

==== <code>EI</code> ====
: Enable interrupts which have been disabled by DI

==== <code>END</code> ====
: Indicates end of program

==== <code>ENT ‹tone envelope number›[,‹tone env. section›][,‹tone env. section›][,‹tone env. section›][,‹tone env. section›][,‹tone env. section›]</code> ====
:The ENT command define the TONE shape of a sound which means manipulating the frequency in a certain range.
:The command could looks like:
<pre>
ENT NUMBER,STEPS?,VERTICAL?,HORIZONTAL?
</pre>
:It is possible to define 15 different envelope shapes. So '''NUMBER''' could be 1-15.

:Each '''?''' stands for up to five sections (1-5), where each STEP<>VERTICAL<>HORIZONTAL with the same '''?''' are belong together.

:'''STEP:''' means how many steps in each section (0-127) > one step is 1/100 of a second!
:'''VERTICAL''': means how big is the step size from bottom to top (-128 to 127)
:'''HORIZONTAL''': means how big is the step size from left to right (0-255)

==== <code>ENV ‹volume envelope number›[,‹volume env. section›][,‹volume env. section›][,‹volume env. section›][,‹volume env. section›][,‹volume env. section›]</code> ====
:The ENV command define the VOLUME shape of a sound which means manipulating the loudness in a certain range.
:The command could looks like:
<pre>
ENV NUMBER,STEPS?,VERTICAL?,HORIZONTAL?
</pre>
:It is possible to define 15 different envelope shapes. So '''NUMBER''' could be 1-15.

:Each '''?''' stands for up to five sections (1-5), where each STEP<>VERTICAL<>HORIZONTAL with the same '''?''' are belong together.

:'''STEP:''' means how many steps in each section (0-127) > one step is 1/100 of a second!
:'''VERTICAL''': means how big is the step size from bottom to top (-128 to 127)
:'''HORIZONTAL''': means how big is the step size from left to right (0-255)

==== <code>ERASE v1[% | ! | $][,v2[% | ! | $][,...]]</code> ====
: Erases the specified array(s) and frees the memory used. Must specify existing array(s) or an <code>Improper argument</code> error will be generated.

==== <code>ERL</code> ====

: Returns the line number of the last error encountered.

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

==== <code>EVERY i[,t] GOSUB ln</code> ====

: BASIC branches to the subroutine at line ln EVERY (reccuring) i/50 seconds. (see also "AFTER i[,t] GOSUB line")

: There are 4 delay timers from 0 to 3 which can be specified with ‹timer number›. If omitted ‹timer number› defaults to 0.
: In the case of parallel task has 3 the highest and 0 the lowest priority.
: With DI or EI you can disable or enable the timing interrupt. With REMAIN <timer number> you can also disable an AFTER or EVERY construct and stores the "remaining" time (> REMAIN)
: Interrupts run as long as the main loop / program runs, even the main programm is paused > press ESC only '''once''' not twice for a break.
: It is important to know or realise that low-priority-interrupts which occurs simultanously to higher-priority-interrupts are not lost. Their task remains or handled again after finishing the higher-prio interrupt.

<pre>
10 REM > interrupts
20 EVERY 50,0 GOSUB 100: REM > lowest priority
30 EVERY 100,1 GOSUB 200
40 EVERY 200,2 GOSUB 300:
50 AFTER 1000,3 GOSUB 400: REM > highest priority
60 WHILE flag=0
70 a=a+1:print a
80 WEND
90 END
100 REM #0
110 PEN 2:PRINT "timer 0":PEN 1
120 RETURN
200 REM #1
210 PEN 2:PRINT "timer 1":PEN 1
220 RETURN
300 REM #2
310 PEN 2:PRINT "timer 2":PEN 1
320 RETURN
400 REM #3
410 flag=1:PEN 2:PRINT "no more interrupts..."
420 RETURN
</pre>

: Hint: Timing with interrupts is important, especially if more than one interrupts run. If the interval of a subroutine driven by an interrupt is too long than the processor can never get back to deal the main program again. Work out timing by measuring the subroutine or by trial and error.
: There are system internal interrupts (highest level) which cannot be influenced by BASIC interrupts (e.g. keyboard scan > BREAK key.)
: The next level of sytem internal interrupts CAN be influenced by BASIC interrupts. For example the sound queue which will be created by "ON SQ <chanel> GOSUB <line>". Those sound interrupts have an independent time tricker but their priority is parallel to the second priority times of BASICs interrupts. Therefore interrupts with timer 3 could "interrupt" them.

==== <code>FILL i</code> ====
: 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.

==== <code>FN</code> ====
:BASIC allows the program to define and use simple value returning functions. DEF FuNction is the definition part of this mechanism and creates program-specific function which works within the
:program in the same way as a function such a COS operates as a built-in function of BASIC. It may be invoked throughout the program. Variable types must be consistent and the DEF FN
:command should be written in part of the program outside the execution loop.

:Syntax : <code>DEF FN<name>[(<formal parameters>)]=<general expression></code>

:Example: ''"with the definition of..."''
<pre>
10 gn=9.80665
20 DEF FNgrv=s0+v0*t+0.5*gn*t^2
30 s0=0:v0=0:t=5
40 PRINT "...after";t;"seconds your dropped stone falls";FNgrv;"metres"
</pre>
:''"the results are..."''
<pre>
:...after 5 seconds your dropped stone falls 122.58315 metres
</pre>

==== <code>FOR TO STEP NEXT</code> ====
: Creating a counting loop (control strucutre) with a starting condition. Inside the counting loop one or more commands will be executed.
: The loop consists of of following specifications:

: 1. FOR
: 2. ''a control variable''
: 3. =
: 4. ''starting value''
: 5. TO
: 6. ''target value''
: 7. STEP [optional]
: 8. ''increment / step size''
: ''... instructions between''
: 9. NEXT
: 10. ''control variable'' [optional]

: You have to use the command STEP if you wish to count backwards. It's good to name the ''control variable'' after NEXT for readability and better program style.
: After each loop the computer checks internaly if the ''target value'' has been reached (like an IF ... THEN ... ELSE instruction). If the target value is reached NEXT closes the loop and calculates another step, so the ''control variable'' will be changed last time.
: The default STEP value - if not specified - is one (1).

: Example:
<pre>
10 FOR I=1 TO 10
20 PRINT I;
30 NEXT I
40 PRINT I
RUN
1 2 3 4 5 6 7 8 9 10 11
READY
</pre>

==== <code>FRAME</code> ====
: 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.

==== <code>GOSUB i</code> ====

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

==== <code>GOTO i</code> ====
: 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>
: GOTO is the simplest form of a jump or creating a loop '''without''' condition controll.
: ''Example: (unconditional and endless loop)''
<pre>
10 PRINT "#";
20 GOTO 10
</pre>
: Combine the GOTO command with an IF...THEN...ELSE instruction for creating a condition-controlled loop with the '''test at the end'''. Helpful because the Locomotive Basic has no practical DO...WHILE... loop.
: ''Example: (condition at the end)''
<pre>
10 I=1
20 PRINT I
30 I=I+1
40 IF I<25 THEN GOTO 20
50 END
</pre>

==== <code>GRAPHICS</code> ====
: ...works only in combination with the command <code>PEN</code> or <code>PAPER</code> to set the plotting/drawing pen or background colour.
: If the <code>TAG</code> command is used to set text at the graphics cursor <code>GRAPHICS PEN</code> or <code>GRAPHICS PAPER</code> instead of the regular <code>PEN</code> or <code>PAPER</code>is necessary to colour the text.

==== <code>IF THEN ELSE</code> ====
: Asks for a choice with the '''IF...THEN...ELSE''' statement.
: '''IF''' compares the entry condition in a logical way
: '''THEN''' contains instruction if the comparison is true
: '''ELSE''' contains instruction if it's false.
: '''Example:'''
<pre>
10 INPUT "guess a figure:",f
20 IF f=10 THEN PRINT "right": END: ELSE GOTO 10
</pre>
: In case of nested choices there's a possibility to that with an IF...THEN instruction but not very recommended:
<pre>
10 INPUT "guess a figure:",f
20 IF f=10 THEN PRINT "right": END: ELSE IF f<10 THEN PRINT "too small" ELSE PRINT "too big"
30 GOTO 10
</pre>
:Other nested structures like IF...THEN...'''ELSE...ELSE''' won't work first because the Locomotive Basic only looks after the first ELSE instruction found and can't execute more single commands as a block for a certain condition in comparision to e.g. "PASCAL" > begin...end-block, "C" > {...}-block.

==== <code>INK ‹pen›,‹colour›,[‹second colour›]</code> ====
: Used to set the colour palette for each of the 16 available inks.
: pen specifies the pen slot to use.
: colour specifies the system colour to use (0..27.)
: if the second colour is provided, Locomotive Basic will blink between the colour and second colour.
: In MODE 0, all 16 pens are available. In MODE 1, only 4 pens are available (0..3). In MODE 2, only 2 pens are available (0..1.)
: By default, pen 0 is the background colour and pen 1 is the foreground/text colour.
: Examples:
<pre>
10 MODE 2
20 INK 0,3: REM Set background colour to red
30 INK 1,26: REM Set foreground/text colour to white
</pre>

==== <code>INPUT[#‹stream expression›][,]</code> ====
: [...]

==== <code>KEY</code> ====
: [...]

==== <code>LET</code> ====
: Used to define variables. You don't need to use the ''LET'' command because it is just a command which was added for compatibility reasons.
: ''Example:''
<pre>
10 LET a$ = "hello world"
20 PRINT a$
</pre>

==== <code>LINE INPUT [#‹stream expression›][,]‹variable›[,‹variable›] </code>====
: [...]

==== <code>LIST [‹line number›][-[‹line number›]], [#‹stream expression›]</code>====
: A command for listing the Basic program code.
: Possibility for manipulating display is using line numbers with a minus symbol.
: Example:
<pre>
LIST 100-
</pre>
: List every line after line number 100.
<pre>
LIST -100
</pre>
: List every line until line number 100 has reached.
<pre>
LIST 100-200
</pre>
: List every line between line number 100 and 200 included

: With the help of separate window definitions it is possible to print out long listings, better differentiate parts / slices of it into different window predefined
: Example:
<pre>
LIST 1000-1100,#1
LIST 3000-3100,#2
</pre>
: ...prints out two parts of one program out into two windows (if they are defined well)

==== <code>LOAD ‹file name›[,‹address›] </code>====

With this directive you may load any file in memory

Basic files (extension .BAS) are loaded in Basic memory, you cannot choose loading address

Binary files are loaded to the default address location stored in the AMSDOS header but you may force loading address (&C000 for a screen)

TAPE convention:

When loading tape files, the basic display a message every block which may cause trouble. Message output may be disabled by using prefix "!" before the filename.

It's also possible to load the next file disregarding his name using only "!" => <code>LOAD "!"</code>

==== <code>LOCATE[#‹stream expression›][,] x,y</code> ====

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

==== <code>MASK [i1][,i2]</code> ====

: Sets bits in each adjacent group of 8 pixel on (1) or off (0) according to binary value of i1 (0-255). i2 determines whether the first point of the line is to plotted (1) or not (0).

:Example:

<pre>
10 CLG 2:MASK 1:MOVE 0,0:DRAW 500,400
20 MASK 15:MOVE 0,0:DRAW 500,400
</pre>

==== <code>MEMORY ‹memory address›</code> ====

: Allocates the amount of memory to be used by BASIC by setting the [[Locomotive_BASIC#HIMEM|address of the highest byte]] it may use.

==== <code>MERGE</code> ====
: [...]

==== <code>MID$ (‹string›,‹start position›[,‹length of substring›])</code> ====
: With the MID$ command there are two applications possible:

: 1. MID$ creates a new substring out of the give ‹string› and starts at the defined position ‹start position› and print the number of given characters by ‹length of substring›.
: If no length is defined every character from ‹start position› will be printed out.
: If a higher value of ‹start position› or ‹length of substring› than the real length of the initial string is defined a blank string will be printed.
: The range of ‹start position› or ‹length of substring› is from 0 up to 255 characters.

: 2. With MID$ you're able to manipulates given strings by inserting a new string.
: Take care of the two different applications and using in BASIC.

: Example for the 1. application:
<pre>
10 a$="Hello"
20 PRINT MID$(a$,2,2)
run
el
Ready
</pre>
:
: Example for the 2. application
<pre>
10 a$="Hello"
20 MID$(a$,2,3)="ipp"
30 PRINT a$
run
Hippo
Ready
</pre>

==== <code>MODE</code> ====
: Changes the screen mode: MODE 0 is 160×200 in 16 colours, MODE 1 is 320×200 4 colours, MODE 2 is 640×200 2 colours and MODE 3 is 160×200 in 4 colours.

==== <code>MOVE x,y [[,i1][,i2]]</code> ====

: Moves the graphic cursor to position x,y. The parameter i1 may be used to change the pen (drawing) colour. The parameter i2 specifies the logical colour, as in DRAW.

: 4 drawing styles:
<pre>
i2 = 0 normal colour
i2 = 1 XOR colour
i2 = 2 AND colour
i2 = 3 OR colour
</pre>

==== <code>MOVER xr,yr[,[i1][,i2]]</code> ====
: moves the graphic cursor (relative) from current position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as in MOVE.

==== <code>NEW</code> ====
: Clears BASIC RAM which means program and variables. Keeps symbol defintion (if defined) and screen mode without clearing.

==== <code>ON BREAK CONT</code> ====

: Prevents the interruption of program execution by the ESC key.

==== <code>ON BREAK GOSUB ln</code> ====

: Passes control to subroutine at line ln when ESC ESC pressed.

==== <code>ON BREAK STOP</code> ====

: Restores normal function of ESC key during program execution.

==== <code>ON ERROR GOTO ln</code> ====

: Passes the control to line ln if an error is detected in the program.

: ON ERROR GOTO 0, Turns of the error trap, and restores normal error processing.

==== <code>ON variable GOTO ln x1, x2, x3, x4, ...</code> ====

: In case of passing more choices '''ON variable GOTO ln x1, x2, x3, x4, ...''' points to a table with the jumping target.
: '''Example:'''
<pre>
10 PRINT "1. LOAD - 2. SAVE - 3. EXIT"
20 INPUT choice
30 ON choice GOTO 1000, 2000, 3000
40 CLS: GOTO 10
1000 PRINT "1. LOAD":END
2000 PRINT "2. SAVE":END
3000 END
</pre>
:In case that the variable ''choice'' won't fullfil the condition (in a range between line 0 and 65535) the next instruction will be executed (here: Line 40). If "choice" is smaller than 0 an error will occur.

==== <code>ON variable GOSUB ln x1, x2, x3, x4, ...</code> ====

: In case of passing more choices targeting to SUBROUTINES '''ON variable GOSUB ln x1, x2, x3, x4, ...''' points to a jumping table.
: '''Example:'''
<pre>
10 PRINT "1. LOAD - 2. SAVE - 3. EXIT"
20 INPUT choice
30 ON choice GOSUB 1000, 2000, 3000
40 CLS: GOTO 10
1000 PRINT "1. LOAD":RETURN
2000 PRINT "2. SAVE":RETURN
3000 END
</pre>
:In case that the variable ''choice'' won't fullfil the condition (in a range between line 0 and 65535) the next instruction will be executed (here: Line 40). If "choice" is smaller than 0 an error will occur.

==== <code>ON SQ(x) GOSUB ln x1, x2, x3, x4, ...</code> ====
:ON SQ(x) can trigger an interrupt when e.g. a space or free channel in queue.
:Using that command is a one way interrupt trigger and shouldn't be mixed with <code>EVERY</code> or <code>AFTER</code> commands.

:See also the <code>SQ(x)</code> command for more details.

==== <code>OPENIN ‹filename›</code> ====
: Opens the specified data file for reading. It has to be an ASCII file. ( The command <code>CLOSEIN</code> closes reading data file. )
: Read from the file using <code>INPUT #9</code>

==== <code>OPENOUT ‹filename›</code> ====
: Opens the specified data file for writing. It writes an ASCII file. (The command <code>CLOSEOUT</code> finishes writing to the file and closes it cleanly.)
: Write to the file with PRINT#9.
: No file is likely to be written until enough data is written (e.g. 2KB) or the file has at least 1 byte written and CLOSEOUT is used.
: The following code pattern can be used to set MEMORY and lower HIMEM lower than would normally be allowed. This is often seen in disc loaders. This doesn't cause any file to be written:

OPENOUT"<filename>
MEMORY address
CLOSEOUT

==== <code>ORIGIN x,y[,l,r,t,b]</code> ====
: The command defines the origin ('world reference point') for the graphics coordinate system. Normally the reference origin is in the left, bottom corner of the default screen and has 0,0. So the most left coordinate value could be by default 639 and the most top value 399. Independent from the actual modus (2, 1 or 0) the range for the x coordinate are always 640 points and for the y coordinate 400 points. In theory you are able to address 256,000 pixel but only 128,000 are visible due to the maximal resolution of the hardware.
: <code>x,y</code> are the the new coordinates for the 'world reference '.
: <code>l,r,t,b</code> are optional and set the borders for the new graphical window (works in the same way like the <code>WINDOW</code> command for a text window). l,r,t,b means left, right, tob and bottom coordinates.
: If a new graphical window (borders) is defined every point or drawn line won't be plotted (clipped internally).

: Example (the line drawn will be cutted):
<pre>
ORIGIN 320,200,250,450,100,300
DRAW 0,200
</pre>

==== <code>OUT ‹address›,‹value›</code> ====

: Outputs a value (range of 0-255) to a specific I/O address.
: Watch out http://cpcwiki.eu/index.php/I/O_Port_Summary

==== <code>PAPER[#‹stream expression›][,]</code> ====
: [...]

==== <code>PEN[#‹stream expression›][,]</code> ====
: [...]

==== <code>PLOT</code> ====
: [...]

==== <code>PLOTR</code> ====
: [...]

==== <code>POKE add</code> ====

: Alters contents of memory location add to value i (0-255)

==== <code>PRINT[#‹stream expression›][,]</code> ====
: [...]

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

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

==== <code>RANDOMIZE [seed]</code> ====

: Resets the pseudo-random generator to the given seed (starting value of the 'random' series). 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>

: <code>RANDOMIZE TIME</code> isn't still a 'real' random number but to hit the same series again is pretty hard due to the time elapsed.
: The algorithm used for randomizing is the following: the generator starts with the seed, adds 1, multiplies by 75 (fiddle factor), divides by 65537 and then uses the remainder -1.

==== <code>READ variable</code> ====
: 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>

==== <code>RELEASE chanel</code> ====
: Releases a sound which was hold on (by a SOUND command) before. It uses the same bit matrix like the SOUND command for the first parameter
# (&x00000001) releases chanel A
# (&x00000010) releases chanel B
# (&x00000011) releases chanel A and B
# (&x00000100) releases chanel C
# (&x00000101) releases chanel A and C
# (&x00000110) releases chanel B and C
# (&x00000111) releases chanel A, B and C

:Example:
<pre>
10 SOUND 65,1000,100
20 PRINT"PRESS R TO LET IT SOUND"
30 IF INKEY(50)=-1 THEN 30
40 RELEASE 1
</pre>

==== <code>REM [any text]</code> ====
: Introduces a comment.

==== <code>RENUM [‹newLine›][,‹oldLine› | ,[‹oldLine›],‹step›] </code>====
: Renumbers the lines of the current program.

: By default, the whole program is renumbered starting at line 10 with multiples of ten. Any parameter that is left out defaults to 10. It is important to note that ''jumps'' (<code>GOTO</code>, <code>GOSUB</code> 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 <code>RENUM 100,20,5</code>

<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== <code>RESTORE [line]</code> ====

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

==== <code>RESUME [line] or NEXT</code> ====
: Command causes the program to resume after an error code and if it is interrupted by an '''ON ERROR GOTO''' jump
: So it can either resume
*(if there's no line number stated) at the same line after error code (and if there are more statements in one line)
or
* at the line number stated (optional)
or
* with the NEXT parameter (optional) ... at the line followed by the error line

==== <code>RETURN</code> ====

: Terminates a subroutine and returns control to the line following the GOSUB call (see GOSUB)

==== <code>RUN [line] or "filename"</code> ====
:Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

:If a string is used after RUN command a programm will be loaded and executed from storage medium (e.g. Tape, Disc). With that command protected BASIC programs can be executed.

:Exampel:
<pre>
RUN"disc"
</pre>

==== <code>SAVE "filename" [,filetype][,parameter1,parameter2,parameter3]</code> ====
: Command saves the current BASIC program / content from RAM onto a storage medium (e.g. Tape, Disc)

: Filetype could be:
* ''',A''' for a ASCII file
* ''',B''' for a binary file (store RAM content as it is)
* ''',P''' for a regular, ''protected'' BASIC file
: without that parameter the content will be stored as a regular BASIC file

:The three parameters after filetype could be used in combination with the binary filetype (,B).
* '''''parameter1''''' defines the starting address of memory range
* '''''parameter2''''' defines the length (range of memory)
* '''''parameter3''''' defines the entry point (optional)

==== <code>SOUND</code> ====
: the SOUND command has following shape:
: SOUND '''C'''hannel,'''P'''eriod,'''D'''uration,'''V'''olume,Volume-'''Env'''elope,'''T'''one-'''En'''velope,'''N'''oise

:'''C:''' Selecting channel is done bitwise (combinations are possible of course):

<pre>
(Bit 0) &x00000001 = 1 = channel A (middle)
(Bit 1) &x00000010 = 2 = channel B (left)
(Bit 2) &x00000100 = 4 = channel C (right)
</pre>
:more function about channel are
<pre>
(Bit 3) &x00001000 = 8 = Rendezvous with channel A
(Bit 4) &x00010000 = 16 = Rendesvous with channel B
(Bit 5) &x00100000 = 32 = Rendesvous with channel C
(Bit 6) &x01000000 = 64 = Hold
(Bit 7) &x10000000 = 128 = Flush
</pre>
:'''P:''' the period number can be a figure between 0 and 4095 (2^12-1... 12 means that we have 12 tones (inclusive half-tones) in nine octaves on the CPC in sum and their distance between is the twelves square root of two), where 8 octaves are available. E.g. Octave 0 starts on middle C with number 478.
: To calculate the period you can use following formula: '''period=1,000,000/(16*frequency)''' or in short '''period=(62,500/frequency)'''
: (e.g. the note "A" with the frequency 440 Hz has the period 142 on the CPC)

:'''D:''' the duration of the note is measured in 1/100th of a second and can be any positive number in the range 1-32,767. 0 and negative number are in combination with ENT and ENV commands usefull. A negative number means repititions.

:'''V:''' the volume number range from 0-7 on a CPC 464 (BASIC 1.0) or 0-15 on a CPC664/6128 (BASIC 1.1)

:'''ENV:''' and '''ENT:''' For shaping the sound ENV (Volume) and ENT (Frequency) commands are available. The relation between SOUND and those commands comes with a figure between 1 to 15 for ENV (5th parameter) and 1 to 15 for ENT (6th parameter).

:'''N:''' the seventh parameter can be used for blending in noise between the range of 0-15 (BASIC 1.0) or 0-30 (BASIC 1.1). The higher the number the 'deeper' or 'dirty' is the noise.

==== <code>SPC <n></code> ====
: in conjunction with PRINT the SPC command prints out a certain number (n) of spaces.
: Example:
<pre>
PRINT "Hello";SPC(10);"World";
Hello World
</pre>

==== <code>SPEED INK <n1,n2> </code> ====
: SPEED INK command defines the frequency of colour changes if a colour change was defined. The duration is calculated by n1=... or n2 =duration/50 seconds.

==== <code>SPEED KEY <start,repeat> </code> ====
: SPEED KEY command defines the delay after which a key repeat (for keys that do repeat). The first parameter is the delay before the first repeat and the second parameter is the delay between further repeats. Delay is in 1/50th of seconds.

:When using it with low values, it is common to associate a key to reset the default speed of 30,2.
:For example to associate the key 0 from the numpad:
<pre>
KEY 0,"SPEED KEY 30,2"+CHR$(13)
</pre>

==== <code>SPEED WRITE <n> </code> ====
: SPEED WRITE defines the speed at which data is to be saved or written to a cassette unit. n=1 means 2000 baud, n=0 (default) means 1000 baud. When reading from the tape, the correct speed is automatically selected.

==== <code>SQ (channel)</code> ====

: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1,2,3, = A, B, C

: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

==== <code>STOP</code> ====

: Breaks program execution at line containing the STOP statement. The message '''BREAK in''' is output with the line number.

==== <code>SWAP</code> ====
: SWAP works only in combination with the window command. Every error or status messages from the operating system will be displayed normaly on WINDOW#0 (=''main'' window). WINDOW SWAP changes the ''main'' window to the desired target window.
: Example (if a window with number 4 was defined before...):
<pre>
WINDOW SWAP 0,4
</pre>

==== <code>SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8]</code> ====

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

==== <code>SYMBOL AFTER n</code> ====
: 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.

==== <code>TAB</code> ====
: [...]

==== <code>TAG [#st]</code> ====

: Allows text to print at graphics cursor position.
: see TAGOFF

==== <code>TAGOFF [#st]</code> ====

: Directs text to stream st printing it at previous text cursor position.

==== <code>TROFF</code> ====

: Turns off the program flow trace (see TRON)

==== <code>TRON</code> ====

: Turns on the program flow trace for debugging. Causes the line number of each statement executed to be displayed.

==== <code>USING</code> ====
: The USING assignement defines the format of the PRINT output. Its appointment happens by characters where each has a certain meaning.

'''Numbers / Figures'''
: the character:
:'''#''' stands for a figure between 0 - 9
:'''.''' stands for a decimal point
:'''+''' generates a positive sign if the value is positive
:'''-''' generates a negative sign if the value is nagative
:'''**''' generates a asterix for each empty "location" before the printed character
:'''$$''' generates a Dollar characters before the printed character (the same with the pound note)
:''',''' generates a comma every each three decimals (thousands per figure) and has to be set before the decimal point or at the end if without a decimal point.
:^ generates a scientific notation (with exponents) and a the end of the format appointment

'''Strings'''
: the character:
:'''!''' prints out only the first character
:'''\xxx\''' prints out only with x-numbers defined length of the string (from left to right). x means a blank sign made with the space bar
:'''&''' the whole string is printed out as given (unknown function)

: a print output (numbers) with "%" in the beginning shows that not enough positions has to be declared (at all or before the decimal point).

: Example:
<pre>
10 figure=123456789
20 word$="Hello"
30 print using "+**,##########";figure
40 print using "\ \";word$

creates following output:

*****+12,345,679
Hel
</pre>

==== <code>WAIT add, i1[,i2]</code> ====

: Waits until the I/O port at add returns a value (0-255). The value returned is XORed with i2 and the ANDed with i1. This is repeated until a non-zero result occurs.

==== <code>WHILE WEND</code> ====
: [...]

==== <code>WIDTH</code> ====
: [...]

==== <code>WINDOW[#‹stream expression›],[L],[R],[T],[B]</code> ====
: It is possible to define in BASIC eight (8) independent windows for text output. Overlapping is possible.

: #STREAM: eight window are possible. No. zero (0) is the main window where error or status messages were put out by default.
: each position is included inside the window
: L = left column / R = right column (dependent of the mode 0 = 20 / 1 = 40 / 2 = 80)
: T = top row / B = bottom row (always from 1 to 25)

: Example:
<pre>
MODE 1
WINDOW#1,1,40,1,6
</pre>
: ...defines the first top quarter of the screen for window No. 1

==== <code>WRITE [#st,] v[$], v[$]</code> ====

: Writes the values of the specified variable to the specified stream.

: Example:

<pre>
10 OPENOUT "DUMMY"
20 INPUT A$,A
30 WRITE #9,A$,A
40 CLOSEOUT
</pre>

==== <code>ZONE i</code> ====

: Changes the width of the print zone. Default is 13.
: Example:
<pre>
10 MODE 2
20 PRINT"normal zone (13)"
30 PRINT 1,2,3,4
RUN
normal zone(13)
1 2 3 4
READY
20 PRINT"now with different zone(5)"
30 ZONE 5
40 PRINT 1,2,3,4
RUN
now with different zone(5)
1 2 3 4
READY
</pre>

=== Operators ===
: A logical status in Locomotive Basic will be represented by a "-1" for TRUE and by a "0" for FALSE.
: Example:
<pre>
PRINT (1=1)
-1
PRINT (1=2)
0
</pre>
==== <code>AND</code> ====
: Possible combinations with the AND Function:
<pre>
NPUT1 INPUT2 OUTPUT
======================
TRUE TRUE TRUE
FALSE FALSE FALSE
TRUE FALSE FALSE
FALSE TRUE FALSE
</pre>
: Example:
<pre>
PRINT 128 AND 64
0
</pre>
: looking at the BIT combination for a better understanding:
<pre>
10000000
AND 01000000
================
= 00000000
</pre>
: even in BASIC it is possible to manipulate single BITs although there are no special commands but AND, OR and XOR.
: first an example for a loop with an increasing counter WITHOUT an AND:
<pre>
10 counter=0
20 counter=counter+1
30 IF counter=32 THEN counter=0
40 GOTO 20
</pre>
: then a shorter example WITH and AND:
<pre>
10 counter=0
20 counter=(counter+1) AND 31
30 GOTO 20
</pre>
: in the second example all more significant BITs will be deleted (a common method in assembler programming)
: Beware: it only works here with BIT/number conditions one figure smaller than 1, 3, 7, 15, 31, 63 and 127
==== <code>MOD</code> ====
: '''MOD''' returns a (rounded) rest (Modulos) after dividen has been devided by the devisor.
:
:'''Example:'''
<pre>
32767 mod 256
255
</pre>
: Note: only works with numbers in the range -32768 and 32767 (&8000 < 0 < &7FFF)

==== <code>NOT</code> ====
: '''NOT''' executes a bit for bit '''negation''' of the current value. The output is a 16-Bit-Word.
:
:'''Example:'''
<pre>
10 value1=1
20 value2=NOT value1
30 PRINT value2
run
-2
</pre>
:for a better understanding...
<pre>
10 value1=1
20 PRINT HEX$(value1):PRINT BIN$(value1,8)
30 value2=NOT value1
40 PRINT HEX$(value2):PRINT BIN$(value2,8)
run
1
00000001
FFFE
1111111111111110
</pre>

==== <code>OR</code> ====
: Possible combinations with the OR Function:
<pre>
NPUT1 INPUT2 OUTPUT
======================
TRUE TRUE TRUE
FALSE TRUE TRUE
TRUE FALSE TRUE
FALSE FALSE FALSE
</pre>
==== <code>XOR</code> ====
: Possible combinations with the XOR Function:
<pre>
NPUT1 INPUT2 OUTPUT
======================
TRUE TRUE FALSE
FALSE TRUE TRUE
TRUE FALSE TRUE
FALSE FALSE FALSE
</pre>

=== Functions ===

==== <code><big>ABS (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the ABSolute value of the given numeric expression (n). This means that negative numbers are returned as positive.
: '''Associated keywords''': SGN

: '''Example''':

<pre>
PRINT ABS(-67.98)
67.98
</pre>

==== <code><big>ASC (<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the numeric value of the first character in the <string expression> (s).
: '''Associated keywords''': CHR$

: '''Example''':
<pre>
PRINT ASC("x")
120
</pre>
==== <code><big>ATN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the Arc-TaNgent of the <numeric expression> (n) to a real number ranging from -PI/2 to +PI/2 of the value specified.
: Note that DEG and RAD can be used to force the result of the below calculation to degrees or radians respectively.

: '''Associated keywords''': COS, DEG, RAD, SIN, TAN

: '''Example''':
<pre>
PRINT ATN(1)
0.785398163
</pre>
==== <code><big>BIN$ (<unsigned integer expression>,[<integer expression>])</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Produces a string of BINary digits respresenting the value of the <unsigned integer expression>, using the number of binary digits instruced by the second <integer expression> (in the range of 0 to 16). If the number of digits instructed is too great, the resulting expression will be filled with leading zeros; if the number of digits instructed is too small, the resulting expression will NOT be shortened to the instructed number of digits, but will produced in as many digits as are required.
: The <unsigned integer expression> to be converted into binary form must yield a value in the range -32768 to 65535.
: '''Associated keywords''': DEC$, HEX$, STR$
: '''Example''':
<pre>
PRINT BIN$(66,8)
01000000
</pre>
==== <code><big>CHR$ (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Converts an <integer expression> in the range 0 to 255, to its CHaRacter $tring equivalent, using the AMSTRAD character set shown in the ASCII table or e.g. in the manual part 3.
: Note that 0 to 31 are control characters; hence the below example prints CHR$(x) in the range 32 to 255
: '''Associated keywords''': ASC, LEFT$, RIGHT$, MID$, STR$

: '''Example''':
<pre>
10 FOR X=32 to 255
20 PRINT X;CHR$(X);
30 NEXT
</pre>
: A further 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.

: Control Codes Table:
<pre>
===============================================================================
| VALUE | NAME | PARAMETERS | EFFECT |
===============================================================================
| DEC | HEX | | | |
===============================================================================
| 0 | &00 | NUL | NONE | DOES NOTHING |
| 1 | &01 | SOH | 0-255 | PRINTS CHARACTER TO SCREEN |
| 2 | &02 | STX | NONE | TURNS TEXT CURSOR OFF |
| 3 | &03 | ETX | NONE | TURNS TEXT CURSOR ON IN IMMEDIATE MODE |
| 4 | &04 | EOT | 0-2 | SET SCREEN MODE |
| 5 | &05 | ENQ | 0-255 | PRINT CHARACTER AT GRAPHICS CURS. |
| 6 | &06 | ACK | NONE | TURNS ON TEXT SCREEN (SEE ALSO CHR$(21))|
| 7 | &07 | BEL | NONE | MAKE A SHORT BEEP |
| 8 | &08 | BS | NONE | MOVES TEXT CURSOR BACK ONE CHARACTER |
| 9 | &09 | TAB | NONE | MOVES TEXT CURSOR FORWARD ONE CHARACTER |
| 10 | &0A | LF | NONE | MOVES TEXT CURSOR DOWN ONE CHARACTER |
| 11 | &0B | VT | NONE | MOVES TEXT CURSOR UP ONE CHARACTER |
| 12 | &0C | FF | NONE | CLEARS SCREEN OR WINDOWS (= CLS) |
| 13 | &0D | CR | NONE | MOVES CURSOR TO LEFT EDGE OF WINDOW ON |
| | | | | CURRENT LINE |
| 14 | &0E | SO | 0-15 | SETS PAPER COLOUR |
| 15 | &0F | SI | 0-15 | SETS PEN COLOUR |
| 16 | &10 | DLE | NONE | DELETES CHARACTER UNDER TEXT CURSOR |
| 17 | &11 | DC1 | NONE | CLEARS LINE FROM LEFT OF WINDOW UP TO |
| | | | | AND INCLUDING CURRENT CHARACTER |
| 18 | &12 | DC2 | NONE | CLEARS FROM CURRENT CHARACTER TO RIGHT |
| | | | | EDGE OF THE WINDOW |
| 19 | &13 | DC3 | NONE | CLEARS FROM START OF WINDOW UP TO AND |
| | | | | INCLUDING CURRENT CHARACTER |
| 20 | &14 | DC4 | NONE | CLEARS FROM CURRENT CHARACTER TO END OF |
| | | | | WINDOW |
| 21 | &15 | NAK | NONE | TURNS OFF TEXT SCREEN (SEE ALSO CHR$(6))|
| 22 | &16 | SYN | 0 AND 1 | TURNS TRANSPARENT OPTION OFF AND ON |
| 23 | &17 | ETB | 0-3 | SET GRPAHICS PLOTTING MODE |
| 24 | &18 | CAN | NONE | CHANGE TO INVERSE CHARACTER DISPLAYING |
| 25 | &19 | EM | NINE PARAM. | DEFINES A CHARACTER (= SAME AS SYMBOL) |
| | | | EACH 0-255 | |
| 26 | &1A | SUB | FOUR PARAM. | DEFINES A TEXT WINDOW (=SAME AS WINDOW) |
| | | | 1-80, 1-80 | FROM LEFT, RIGHT, TOP TO BOTTOM |
| | | | 1-25, 1-25 | FROM LEFT, RIGHT, TOP TO BOTTOM |
| 27 | &1B | ESC | NONE | DOES NOTHING ON SCREEN (PRINTER SIGNAL) |
| 28 | &1C | FS | THREE PARAM. | SETS INK COLOUR TO FLASH BETWEEN TWO |
| | | | 0-15, 0-32 | INK NO, COLOUR 1, COLOUR 2 |
| | | | 0-32 | |
| 29 | &1D | GS | TWO PARAM. | SETS BORDER COLOUR TO FLASH BETWEEN TWO |
| | | | 0-31, 0-31 | COLOURS |
| 30 | &1E | RS | NONE | HOMES CURSOR TO TOP LEFT OF SCREEN |
| 31 | &1F | US | TWO PARAM. | MOVES CURSOR TO CELL SPECIFIED BY TWO |
| | | | 1-80, 1-25 | PARAMETERS (=SAME AS LOCATE) |
===============================================================================
</PRE>

==== <code><big>CINT (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the value of the <numeric expression> (n), Converting it to a rounded INTeger in the range -32768 to 32767.

: '''Associated keywords''': CREAL, FIX, INT, ROUND, UNT

: '''Example''':
<pre>
10 n=1.9999
20 PRINT CINT(n)
run
2
</pre>
==== <code><big>COPYCHR$ (#stream)</big></code> ====
: : ''BASIC 1.1''
: '''FUNCTION''': COPies a CHaRacter from the current position in the stream (which MUST be specified). The below program copies a character from location 1,1 (top left), and reproduces it at location 1,20.
: If the character read is not recognized, a null string is returned.

: '''Associated keywords''': LOCATE

: '''Example''':
<pre>
10 CLS
20 PRINT "top corner"
30 LOCATE 1,1
40 a$=COPYCHR$(#0)
50 LOCATE 1,20
60 PRINT a$
</pre>
==== <code><big>COS (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the COSinus of the <numeric expression> (n).
: Note that DEG and RAD can be used to force the result of the below calculation to degrees or radians respectively.

: '''Associated keywords''': ATN, DEG, RAD, SIN

: '''Example''':
<pre>
DEG
PRINT COS(45)
0.707106781
</pre>
==== <code><big>CREAL (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the value of the <numeric expression> (n), Converting it to REAL.

: '''Associated keywords''': CINT

: '''Example''':
<pre>
10 a=PI
20 PRINT CINT(a)
30 PRINT CREAL(a)
run
3
3.14159265
</pre>
==== <code><big>DEC$(<numeric expression>, <format template>)</big></code> ====
: ''BASIC 1.1''
: '''FUNCTIION''': Returns a DECimal string representation of the <numeric expression> (n), using the specified <format template> to control the print format of the resulting string.
: The format template may contain ONLY the characters:

: + - $ £ * # , . ^

: The use of these 'format field specifiers' is described under the keyword PRINT USING.

: '''Associated keyword''': BIN$, HEX$, PRINT USING, STR$

: '''Example''':
<pre>
PRINT DEC$(10^7,"££########,.##")
£10,000,000.00
</pre>
==== <code><big>DERR</big></code> ====
: ''BASIC 1.1''
: '''FUNCTION''': Reports the last error code returned by the disc filing system. The value of DERR may be used to ascertain the particular Disc ERRor that occurred. See the listing of error messages below.

: '''Associated keywords''': ERL, ERR, ERROR, ON ERROR GOTO, RESUME

: '''Example''':
<pre>
LOAD "xyz.abc"

XYZ .ABC not found
Ready
PRINT DERR
146
</pre>
: '''Table of Disc ERRor codes''':
: If AMSDOS has already reported an error, then bit 7 is set, hence the value of DERR is offset by 128.
<pre>
===============================================================================
| VALUE | DERR value | DESCRIPTION |
===============================================================================
| 0 | 0 or 22 | [ESC] has been pressed |
| 14 | 142 (128+14) | The stream is not in a suitable state. |
| 15 | 143 (128+15) | Hard end of file has been reached. |
| 16 | 144 (128+16) | Bad command, usually an incorrect filename. |
| 17 | 145 (128+17) | File already exists. |
| 18 | 146 (128+18) | File does not exists. |
| 19 | 147 (128+19) | Directory is full. |
| 20 | 148 (128+20) | Disc is full. |
| 21 | 149 (128+21) | Disc changed while file were open. |
| 22 | 150 (128+22) | File is Read/Only. |
| 26 | 154 (128+26) | Soft end of file has been detected. |
| | | |
===============================================================================
</pre>
: Other values returned by DERR originate from the disc controller and are bit significant, always with bit 6 set.
: The significance of each bit is as follows:
<pre>
===============================================================================
| BIT | Significance |
===============================================================================
| 0 | Address mark missing. |
| 1 | Not writable - disc is write protected. |
| 2 | No data - can't find the sector. |
| 3 | Drive not ready - no disc in the drive. |
| 4 | Overrun error. |
| 5 | Data error - CRC error. |
| 6 | Always set to 1 to indicate error from disc controller. |
| 7 | Set to 1 if error has already been reported by AMSDOS. |
===============================================================================
</pre>
==== <code><big>EOF</big></code> ====
: ''BASIC 1.1''
: '''FUNCTION''': Checks to see if end of specified file has been reached during input. Returns 0 (false) until the end of file, then -1 (true).

: '''Associated keywords''': OPENIN, CLOSEIN

: This '''example''' reads a file from disc and print it out on screen. Like the "TYPE" command in CP/M or "|TYPE,file" of the UTOPIA-ROM.
<pre>
10 OPENIN "text.txt"
20 WHILE NOT EOF
30 LINE INPUT#9,a$
40 PRINT a$
50 WEND
60 CLOSEIN
</pre>
==== <code><big>ERR</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the number of the last ERRor encountered. See the table below of error messages. In the example below you will see that ERRor number 8 is a 'Line does not exist' error.

: '''Example''':
<pre>
GOTO 500
Line does not exist
Ready
PRINT ERR
8
</pre>
: NOTE: BASIC 1.0 (officially) describes error codes until 30 (without an attached floppy disc controller). 31 & 32 are floppy disc error codes.
: '''Table of ERRor codes''':
<pre>
========================================================================================
| VALUE | NAME | DESCRIPTION |
========================================================================================
| 1 |Unexpected NEXT |A NEXT command has been encountered while not in a |
| | |FOR loop, or the control variable in the NEXT |
| | |command does not match that in the FOR. |
| 2 |Syntax Error |BASIC cannot understand the given line because |
| | |a construct within it is not legal. |
| 3 |Unexpected RETURN |A RETURN command has been encountered when not in a |
| | |subroutine. |
| 4 |DATA exhausted |A READ command has attempted to read beyond the end |
| | |of the last DATA. |
| 5 |Improper Argument |This is a general purpose error. The value of a |
| | |function's argument, or a command parameter is |
| | |invalid in some way. |
| 6 |Overflow |The result of an arithmetic operation has over- |
| | |flowed. This may be a floating point overflow, in |
| | |which case some operation has yielded a value |
| | |greater than 1.7E^38 (approx.). Alternatively, this |
| | |may be the result of a failed attempt to change a |
| | |floating point number to a 16 bit signed integer. |
| 7 |Memory full |The current program or its variables may be simply |
| | |too big, or the control structure is too deeply |
| | |nested (nested GOUSBs, WHILEs or FORs). |
| | |A MEMORY command will give this error if an attempt |
| | |is made to set the top of BASIC's memory too low, or|
| | |to an impossible high value. Note that an open file |
| | |has a buffer allocated to it, and that may restrict |
| | |the values that MEMORY may use. |
| 8 |Line does not exist |The line referenced cannot be found. |
| 9 |Subcript out of range |One of the subscripts in an array reference is too |
| | |big or too small. |
| 10 |Array already dimensioned|One of the arrays in a DIM statement has already |
| | |been declared. |
| 11 |Division by zero |May occur in real division, integer division, |
| | |integer modulus or exponentiation. |
| 12 |Invalid direct command |The last command attempted is not valid in direct |
| | |mode. |
| 13 |Type mismatch |A numeric value has been presented where a string |
| | |value is required or vice versa, or an invalidly |
| | |formed number has been found in READ or INPUT. |
| 14 |String space full |So many strings have been created that there is no |
| | |further room available, even after 'garbage |
| | |collection'. |
| 15 |String too long |Strings exceeds 255 characters in length. May be |
| | |generated by appending strings together. |
| 16 |String expression too |String expressions may generate a number of |
| |complex |intermediate string values. When the number of these|
| | |values exceeds a reasonable limit, this error |
| | |results. |
| 17 |Cannot CONTinue |For one reason or another the current program |
| | |be restarted using CONT. Note that CONT is intended |
| | |for restarting after a STOP command, [ESC][ESC], |
| | |or an error, and that any alteration of the |
| | |program in the meantime makes a restart impossible. |
| 18 |Unknown user function |No DEF FN has been executed for the FN just |
| | |invoked. |
| 19 |RESUME missing |The end of the program has been encountered while |
| | |in error processing mode (i.e. in an ON ERROR GOTO |
| | |routine). |
| 20 |Unexpected RESUME |RESUME is only valid while in error processing mode |
| | |(i.e. in an ON ERROR GOTO routine). |
| 21 |Direct command found |When loading a file, a line without a line number |
| | |has been found. |
| 22 |Operand missing |BASIC has encountered an incomplete expression. |
| 23 |Line too long |A line when converted to BASIC internal-form becomes|
| | |too big. |
| 24 |EOF met |An attempt has been made to read past end of the |
| | |file input stream. |
| 25 |File type error |The file being read is not of a suitable type. |
| | |OPENIN is only prepared to open ASCII text files. |
| | |Similarly, LOAD, RUN, etc, are only prepared to |
| | |deal with file types produces by SAVE. |
| 26 |NEXT missing |Cannot find a NEXT to match a FOR command. A line |
| | |number accompanying this message indicates the FOR |
| | |command to which this error applies. |
| 27 |File already open |An OPENIN or OPENOUT command has been executed |
| | |before the previously opened file has been closed. |
| 28 |Unknown command |BASIC cannot find a taker for an external command, |
| | |i.e. a command preceded by a bar |. |
| 29 |WEND missing |Cannot find a WEND to match a WHILE command. |
| 30 |Unexpected WEND |Encountered a WEND when not in a WHILE loop, or a |
| | |WEND that does not match the current WHILE loop. |
| 31 |File not open |(see 'Disc ERRors above). |
| | |If access attempted when no file was open. |
| 32 |Broken in |(see 'Disc ERRors above). |
| | |If access attempted when no file was open. |
| | | |
| | |If value 31 or 32 are stated, DERR could be |
| | |interrogate to give more detailed information. |
| | |(see example below.) |
========================================================================================
</pre>
: '''Example for ERR 31 / 32''':
<pre>
10 ON ERROR GOTO 1000
20 OPENOUT "myfile.asc"
30 WRITE #9,"test-data"
40 CLOSEOUT
50 END
1000 amsdoserr=(DERR AND &7F):REM mask off bit 7
1010 IF ERR<31 THEN END
1020 IF ERR=31 THEN PRINT "are you sure you've typed line 20 correctly?":END
1030 IF amsdoserr=20 THEN PRINT "disc is full, suggest you use a new data disc":END
1040 IF amsdoserr=&X01001000 THEN PRINT "put a disc in the drive, then press a key":WHILE INKEY$="":WEND:RESUME
1050 END
</pre>
==== <code><big>EXP (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates 'E' to the power given in the <numeric expression> (i), where 'E' is approximately 2,7182818-the number whose natural logarithm is 1.

: '''Associated keywords''': LOG

: '''Example''':
<pre>
PRINT EXP(6.876)
968.743625
</pre>
==== <code><big>FIX (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Unlike CINT, FIX merely removes the part of the numeric expression, to the right of the decimal point, and leaves an integer result, rounding towards zero.

: '''Associated keywords''': CINT, INT, ROUND

: '''Example''':
<pre>
PRINT FIX(9.99999)
9
</pre>
==== <code><big>FRE (<numeric expression>/<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Establishes how much FREe memory remains unused by BASIC. The form FRE("") forces a 'GARBAGE COLLECTION' before returning a value for available space.
: NOTE: BASIC uses only the first 64K of the memory.

: '''Associated keywords''': HIMEM, MEMORY

: '''Examples''':
<pre>
PRINT FRE(0) or PRINT FRE("hello")
PRINT FRE("")
</pre>
==== <code><big>HEX$ (<unsigned integer expression>, <field width>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Produces a $tring of HEXadecimal digits representing the value of the <unsigned integer expression>, using the number of hexadecimal digits instructed by the <field width> (in the range 0 to 16). If the number of digits instructed is too great, the resulting expression will be filled with leading zeros; if the number of digits instructed is too small, the resulting expression will NOT be shortened to the instructed number of digits, but will be produced in as many digits as are required.
: The <unsigned integer expression> to be converted into hexadecimal form must yield a value in the range -32768 to 65535.

: '''Accociated keywords''': BIN$, DEC$, STR$, UNT

: '''Example''':
<pre>
PRINT HEX$(255,4)
00FF
</pre>
==== <code><big>HIMEM</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the address of the Highest byte of Memory use by BASIC, (which may altered by e.g. the MEMROY command).
: Before resetting the highest byte of available memory using the MEMORY command, it is advisable to issue the 'command mm=HIMEM'. You will thereafter be able to return to the previous memory capacity by issuing the command: 'MEMORY mm'
: NOTE: BASIC uses only the first 64K of memory.

: Associated keywords: FRE, MEMORY, SYMBOL, SYMBOL AFTER.

: '''Example''':
...on a CPC464
<pre>
PRINT HIMEM
43903
</pre>
...on a CPC6128
<pre>
PRINT HIMEM
42619
</pre>
==== <code><big>INKEY (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': INterrogates the KEYboard to report which keys are being pressed. The keyboard is scanned every 0.02 (1/50) second.
: The function is useful for spotting whether a certain key is down or up, by detecting the returned value of -1 (which occurs regardless of [SHIFT] and [CONTROL] key status).
: The example below detects when [SHIFT] and V (key number 55) are pressed together, then ends the program. Refer the manual for the key numbers.

: '''Associated keywords''': CLEAR INPUT, INKEY$, JOY

: '''Example''':
<pre>
10 IF INKEY(55)<>32 THEN 10
20 PRINT "You've pressed [SHIFT] and V"
30 CLEAR INPUT
run
</pre>
: The state of [SHIFT] and [CONTROL] in conjunction with the key specified in the <integer expression> is identified as follows:
<pre>
==============================================================================
|Value returned |[SHIFT] |[CTRL] |Specified key |
==============================================================================
|-1 |ignored |ignored |up |
|0 |up |up |down |
|32 |down |up |down |
|128 |up |down |down |
|160 |down |down |down |
==============================================================================
</pre>
==== <code><big>INKEY$</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': INterrogates the KEYboard, returning the current $tring reflecting any key that is pressed. It provides operator interaction without hitting [ENTER] after every answer. If there is a key pressed, then the function responds. If no key is pressed, INKEY$ returns an empty string.
: In the example below, lines 40 and 70 tell the program to loop back to line 30 after interrogating the keyboard string.

: '''Associated keywords''': CLEAR INPUT, INKEY

: '''Example''':
<pre>
10 CLS
20 PRINT "Select Yes or No (Y/N)?"
30 a$=INKEY$
40 IF a$="" THEN 30
50 IF a$="y" OR a$="Y" THEN 80
60 IF a$="N" OR a$="n" THEN 90
70 GOTO 30
80 PRINT "You have selected YES": END
90 PRINT "You have selected NO":
run
</pre>
==== <code><big>INP (‹port number›)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the INPut value from the I/O address specified in the <port number>.

: '''Associated keywords''': OUT, WAIT

: Watch out http://cpcwiki.eu/index.php/I/O_Port_Summary

: '''Example''':
<pre>
PRINT INP(&FF00)
255
Ready
</pre>
==== <code><big>INSTR ([‹startposition›,]‹searched string›, ‹searched for string›)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Searches the first <searched string> expression to find the first occurance of the <searched for string expression<, and reports the position of its occurance within the <searched string>. If the <searched for string> does not occur within the <searched string>, then 0 is reported.
: The position at which to start searching the <searched string> is optionally specifiable using the <start position> parameter which must yield an integer number in the range 1 to 255.

: '''Associated keywords''': none

: '''1. Example''':
<pre>
a$="ABCD":PRINT INSTR(a$,"C")
3
Ready
</pre>
: '''2. Example''':
<pre>
a$="Hello":IF INSTR(a$,"i")<>0 THEN PRINT "no" else a$
no
Ready
</pre>
: '''3. Example''':
<pre>
10 CLS
20 alphabet$="ABCDEFGHIJKLMNOPQRSTUVWXYZ"
30 INPUT "Enter a letter";a$
40 b$=UPPER$(a$)
50 PRINT b$;" is number";
60 PRINT INSTR(alphabet$,b$);
70 PRINT "in the alphabet.":PRINT
80 GOTO 40
run
</pre>
==== <code><big>INT (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Rounds the number to the nearest smaller INTeger, removing any fractional part. Returns then same value as FIX for positive number, but returns one less than FIX for negative numbers which are not already integers.

: '''Associated keyword''': CINT, FIX, ROUND

: '''Example''':
<pre>
PRINT INT(3.99), INT(-3.99)
3 -4
</pre>
==== <code><big>JOY (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': The JOY function reads a bit significant result from the joystick in the <integer expression> (either 0 or 1).
<pre>
================================
|Bit | Value decimal |
================================
|0(up) | 1 |
|1(down) | 2 |
|2(left) | 4 |
|3(right) | 8 |
|4(fire 2) | 16 |
|5(fire 1) | 32 |
================================
</pre>
==== <code><big>LEFT$ (<string expression>, <required length>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the number of characters (in the range 0 to 255) specified in the <required length> parameter (<integer expression>), after extracting them from the LEFT of the <string expression>. If the <string expression> is shorter than the <required length>, the whole <string expression> is returned.

: '''Associated keywords''': MID$, RIGHT$

: '''1. Example''':
<pre>
A$="ABCDEFG":PRINT LEFT$(A$,3) - prints ABC
</pre>
: '''2. Example''':
<pre>
10 CLS
20 a$="AMSTRAD"
30 FOR n=1 to 7
40 PRINT LEFT$(a$,n)
50 NEXT
run
</pre>
==== <code><big>LEN (<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the total number of characters (i.e. the LENgth) of the <string expression>.

: '''Associated keywords''': none

: '''Example''':
<pre>
10 LINE INPUT "Enter a phrase";a$
20 PRINT "The phrase is";
30 PRINT LEN(a$);"characters long."
run
</pre>
==== <code><big>LOG (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the natural LOGarithm (base of ''e'') of <numeric expression> which mustbe greater than zero.

: '''Associated keywords''': EXP, LOG10

: '''Example''':
<pre>
PRINT LOG(9999)
9.21024037
</pre>
==== <code><big>LOG10 (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the logarithm to base 10 of <numeric expression> which must be greater than zero.

: '''Associated keywords''': EXP, LOG

: '''Example''':
<pre>
PRINT LOG10(9999)
3.99995657
</pre>
==== <code><big>LOWER$ (<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns a new string expression which is a copy of the specified <string expression> but in which all alphabetic characters in the range A to Z are converted to lower case. Useful for processing input where the answers may come in mixed upper/lower case.

: '''Associated keywords''': UPPER$

: '''1. Example''':
<pre>
A$="AMSTRAD":PRINT A$="AMSTRAD":PRINT LOWER$(A$)
Amstrad
</pre>
: '''2. Example''':
<pre>
10 a$="SEE HOW THE LETTERS CHANGE TO ... NUMBERS 1234 NOT..."
20 PRINT LOWER$(a$+"LOWER CASE")
see how the letters change to ... numbers 1234 not... LOWER CASE
</pre>
==== <code><big>MAX (<list of: numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the MAXimum value from the <list of: numeric expression>s.

: '''Associated keywords''': MIN

: '''Example''':
<pre>
10 n=66
20 PRINT MAX(1,n,3,6,4,3)
run
66
</pre>
==== <code><big>MIN (<list of: numeric expression>)</big></code> ====
''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the MINimum value from the <list of: numeric expression>s.
: '''Associated keywords''': MAX

: '''Example''':
<pre>
PRINT MIN (3,6,2.999.8,9,)
2.999
</pre>

==== <code><big>PEEK (<address expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the contents of the Z80 memory location specified in the <address expression> which should be in the range &0000 to &FFFF (0 to 65535). In all cases PEEK will return the value at the RAM address specified (not the ROM), and will be in the range &00 to &FF (0 to 255)

: '''Associated keywords''': POKE

: '''Example''':
<pre>
10 MODE 1: ZONE 7
20 WINDOW 1,40,1,2:WINDOW #1,1,40,3,25
30 PRINT "memory-address"
40 LOCATE 20,1:PRINT "memory-contents"
50 FOR n=1 to 65535
60 p=PEEK(n)
70 PRINT #1,n,"(&";HEX$(n);")";
80 PRINT #1,TAB(20);p,"(&";HEX$(p);")"
90 NEXT
run
</pre>
==== <code><big>PI</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': The value of the ratio between the circumference and the diameter of a circle.

: '''Associated keywords''': DEG, RAD

: '''Example''':
<pre>
PRINT PI
3.14159265
</pre>
==== <code><big>POS (#<stream expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current horizontal POSition of the text cursor relative to the left edge of the text window. The <stream expression> MUST be specified, and does NOT default to #0.
: POS(#8) reports the current horizontal carriage position for the printer, where 1 is the extreme left hand edge.
: POS(#9) reports the logical position in the disc file stream, i.e. the number of printing characters sent to the stream since the last carriage return.

: '''Associated keywords''': VPOS, WINDOW
: '''Example''':
<pre>
10 MODE 1: BORDER 0:LOCATE 8,2
20 PRINT "use cursor left/right keys"
30 WINDOW 1,40,12,12:CURSOR 1,1
40 FOR n=1 TO 19:PRINT CHR$(9);:NEXT
50 IF INKEY(1)<>-1 THEN PRINT CHR$(9);
60 IF INKEY(8)<>-1 THEN PRINT CHR$(8);
70 LOCATE #1,2,24
80 PRINT #1,"text cursor ";
90 PRINT #1,"horizontal position = ";
100 PRINT #1,POS(#0):GOTO 50
run
</pre>
==== <code><big>REMAIN (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns count REMAINing count from the delay timer specified in <integer expression> (= timer number in the range 0 to 3), and disable it. If the delay timer was not enabled zero will be returned.

: '''Associated keywords''': AFTER, DI, EI, EVERY

: For the reason that REMAIN is no normal command but a "function" it is necessary in case of a proper functionality to link the command.
: an '''example''' in combination with an interrupt delay timer 1:
<pre>
PRINT REMAIN(1)
</pre>
: or to stop several/all interrupts at the same time...
<pre>
A=REMAIN(0)=REMAIN(1)=REMAIN(2)=REMAIN(3)
</pre>
: Hint: Take care of interrupts due to parallel working (the same cycle time) or if they are stopped with the BREAK key. Interrupts which were disabled for a certain time will be stored in buffer (for a maximum of 128 entries) and made up their task afterwards in the priorisation as declared.
: further '''example''':
<pre>
10 AFTER 500,1 GOSUB 40
20 AFTER 100,2 GOSUB 50
30 PRINT "program running":GOTO 30
40 REM this GOUSB-Routine will not be called as it is disabled in line 80
50 PRINT:PRINT "Timer 1 will now be ";
60 PRINT "disabled by REMAIN."
70 PRINT "Time-units remaining were:";
80 PRINT REMAIN(1)
run
</pre>
==== <code><big>RIGHT$ (<string expression>, <integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the number of characters (in the range 0 to 255) specified in the <integer expression> (=required length) parameter, after extracting them from the RIGHT of the <string expression>. If the <string expression> is shorter than the <integer expression>, the whole <string expression> is returned.

: '''Associated keywords''': LEFT$, MID$

: '''Example''':
<pre>
10 MODE 1:a$="AMSTRAD computer"
20 FOR n=1 TO 16:LOCATE 41-n,n
30 PRINT RIGHT$(a$,n)
40 NEXT
</pre>
==== <code><big>RND [(<numeric expression>)]</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the next RaNDom number in sequence if the <numeric expression> has a positive value or is not specified.
: If the <numeric expression> yields a value of zero, RND returns a copy of the last random number generated.
: If the <numeric expression> yields a negative value, a new random number sequence is started, the first number of which is returned.

: '''Associated keywords''': RANDOMIZE

: '''1. Example''':
<pre>
PRINT RND(0)
0.536703827
Ready
PRINT RND(1)
0.271940658
Ready
PRINT RND(0)
0.271940658
Ready
</pre>
: '''2. Example''':
: Example for generating an integer random number between 1 and 1000
<pre>
10 A=INT((RND(1)*1000)+1)
20 PRINT A
30 GOTO 10
</pre>
: '''3. Example''':
: For generating a random number between a lower and higher border
<pre>
10 INPUT "Low border",low
20 INPUT "High border",high
30 A=INT(RND(1)*(high-low))+low
40 PRINT A
</pre>
: '''4. Example''':
<pre>
10 RANDOMIZE
20 FOR x=1 TO -1 STEP -1
30 PRINT "rnd parameter=";x
40 FOR n=1 TO 6
50 PRINT RND(x)
60 NEXT n,x
run
</pre>

==== <code><big>ROUND (<numeric expression>[,<integer expression>])</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Rounds <numeric expression> to a number of decimal places or to the power of ten specified by <integer expression>. If <integer expression> less than zero, the <numeric expression> is rounded to give an absolute integer with <integer expression> number of zeros before the decimal point.

: '''Associated keywords''': ABS, CINT, FIX, INT
: '''1. Example''':
<pre>
PRINT ROUND(1562.357,2),ROUND(1562.375,-2)
1562.36 1600
</pre>
: '''2. Example''':
<pre>
10 FOR n=4 TO -4 STEP -1
20 PRINT ROUND (1234.5678,n)
30 PRINT "with integer expression";n
40 NEXT
run
</pre>
==== <code><big>SGN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: FUNCTION: Determines the SiGN of the <numeric expression>. Returns -1 if <numeric expression> is less than 0, returns 0 if <numeric expression> = 0, and returns 1 if <numeric expression> is greater than zero.

: '''Associated keywords''': ABS

: '''Example''':
<pre>
10 FOR n=255 to -200 STEP -20
20 PRINT "SGN returns";
30 PRINT SGN(n);"for a value of";n
40 NEXT n
run
</pre>
==== <code><big>SIN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the Real value for the Sine of <numeric expression>, defaulting to the Radian (RAD) measure mode unless otherwise declared by a DEG command.

: '''Associated keywords''': ATN, COS, DEG, RAD, TAN

: '''Example''':
<pre>
10 CLS:DEG:ORIGIN 0,20
20 FOR n=0 to 720
30 y=SIN(n)
40 PLOT n*640/720,198*y:NEXT
50 GOTO 50
run
</pre>
==== <code><big>SPACE$(<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Creates a string of spaces of the given length, (in the range 0 to 255) specified in the <integer expression>.

: '''Associated keywords''': SPC, STRING$, TAB

: '''Example''':
<pre>
10 MODE 1
20 PRINT "Put 9 spaces between me";
30 PRINT SPACE$(9);
40 PRINT "and you!"
run
</pre>
==== <code><big>SQ (<channel>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the state of the Sound Queue for the specified <channel> which must be an integer expression, yielding one the values:
: 1: for channel A
: 2: for channel B
: 4: for channel C
: The SQ function returns a bit significant integer, comprising the following bit settings:
: Bit 0,1 and 2: the number of free entries in the queue
: Bit 3,4 and 5: the rendezvous state at the head of this queue
: Bit 6 : the head of the queue is held
: Bit 7 : the channel is currently active
: ... where Bit 0 is the least significant bit, and Bit 7 is the most significant bit.
: It can be seen, that if Bit 6 is set, Bit 7 cannot be set at the same time, and vice versa. Similarly if Bits 3, 4, or 5 are set, Bit 6 and 7 cannot be set.

: '''Associated keywords''': ON SQ GOSUB, SOUND

: '''Example''':
<pre>
10 SOUND 65,100,100
20 PRINT SQ(1)
run
67
</pre>
==== <code><big>SQR (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the SQuare Root of the specified <numeric expression>.

: '''Associated keywords''': none

: '''Example''':
<pre>
PRINT SQR(9)
3
</pre>
==== <code><big>STR$ (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Converts the <numeric expression> to a decimal STRing representation.
: Useful for converting a number to a string in case of string manipulation. E.g. after converting a figure to a string then the most left character holds the sign: a minus in case the figure is negative and a space in case the figure is positiv.

: '''Associated keywords''': BIN$, DEC$, HEX$, VAL

: '''1. Example''':
<pre>
10 FIGURE=-1599
20 FIGURE$=STR$(FIGURE)
30 PRINT FIGURE$
-1599
</pre>
: '''2. Example''':
<pre>
10 FIGURE=1769
20 FIGURE$=STR$(FIGURE)
30 PRINT FIGURE$
1769
</pre>
: '''NOTE''': (there's a blank on the left-hand of the number "1769")
: If you want to add e.g. zero before the figure in case of a high score with fix digit-number then you're able to add zero(s) in front of a string instead of a figure.

: '''3. Example''':
<pre>
10 a=&FF:REM 255 hex
20 b=&x1111:REM 15 binary
30 c$="***"
40 PRINT c$+STR$(a+b)+c$
run
*** 270***
</pre>

==== <code><big>STRING$ (<length>,<character specifier>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns a string expression consisting of the <character specifier> repeated the number of time (in the range 0 to 255) specified in the <length>.

: '''Associated keywords''': SPACE$

: '''1. Example''':
<pre>
PRINT STRING$(40,"*")
****************************************
</pre>
: '''2. Example''':
<pre>
PRINT STRING(40,42)
****************************************
</pre>
: '''NOTE''': the <character specifier> 42 refers to the ASCII value of the character '*' and is also equivalent to PRINT STRING$(40,CHR$(42))
==== <code><big>TAN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the TANgent of the <numeric expression>, which must be in the range -200,000 to +200,000.
: '''NOTE''': DEG and RAD can be used to force the result of the calculation to degrees or radians respectively.

: '''Associated keywords''': ATN, COS, DEG, RAD, SIN

: '''Example''':
<pre>
PRINT TAN(45)
1.61977519
</pre>

==== <code><big>TEST (<x co-ordinate>,<y co-ordinate>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Moves the graphics cursor to the absolute position specified by the <x> and <y co-ordinate>s, and reports the value of the ink at the new location.

: '''Associated keywords''': MOVE, MOVER, TESTR, XPOS, YPOS

: '''Example''':
<pre>
10 CLS
20 PRINT "Your are using pen number";
30 PRINT TEST(10,386)
40 PRINT "Try changing PENs and MODEs";
50 PRINT "....then RUN again."
run
</pre>
==== <code><big>TESTR (<x offset>,<y offset>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Moves the graphics cursor by the amount specified in the <x> and <y offset>s relative to its current position, and reports the value of the ink at the new location.

: '''Associated keywords''': MOVE, MOVER, TEST, XPOS, YPOS

: '''Example''':
<pre>
10 MODE 0:FOR x=1 TO 15:LOCATE 1,x
20 PEN x:PRINT STRING$(10,143);:NEXT
30 MOVE 200,400:PEN 1
40 FOR n=1 TO 23:LOCATE 12,n
50 PRINT "pen";TESTR(0,-16):NEXT
run
</pre>
==== <code><big>TIME</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the elapsed time since the computer was last switched-on or reset, (excluding periods when reading or writing to disc).
: Each second of real time is equal to the returned value = TIME/300.

: '''Associated keyword''': AFTER, EVERY, WEND, WHILE

: '''Example''':
<pre>
10 CLS:REM clock
20 INPUT "hour";hour
30 INPUT "minute";minute
40 INPUT "second";second
50 CLS:datum=INT(TIME/300)
60 WHILE hour<13
70 WHILE minute<60
80 WHILE tick<60
90 tick=(INT(TIME/300)-datum)+second
100 LOCATE 1,1
110 PRINT USING "## ";hour,minute,tick
120 WEND
130 tick=0:second=0:minute=minute+1
140 GOTO 50
150 WEND
160 minute=0:hour=hour+1
170 WEND
180 hour=1
190 GOTO 60
run
</pre>
==== <code><big>UNT (<address expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Return an integer in the range -32768 to +32767 which is the twos-complement equivalent of the unsigned value of the <address expression>.

: '''Associated keywords''': CINT, FIX, INT, ROUND

: '''Example''':
<pre>
PRINT UNT(&FF66)
-154
</pre>
==== <code><big>UPPER$(<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns a new string expression which is a copy of the specified <string expression> but in which all alphabetic characters in the range A to Z are converted to upper case. The function is useful for processing input which may come in mixed upper / lower case.

: '''Associated keywords''': LOWER$

: '''Example''':
<pre>
10 CLS: a$="my, how you've grown!"
20 PRINT UPPER$(a$)
run
</pre>
==== <code><big>VAL(<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the numeric VALue, (including any negative sign and decimal point) of the first character(s) in the specified <string expression>.
:If the first character is not a number, then 0 is returned. If the first character is a negative sign or decimal point followed by non-numeric characters, a 'Type mismatch' error (13) will be reported.

: '''Associated keywords''': STR$

: '''1. Example''':
<pre>
PRINT VAL("-12.34x"),VAL("A-12")
-12.34 0
</pre>
: '''Exception''': if <se> starts with "&" + character (and it's between "A" and "F") the whole character will be handled like a hexadezimal numeric character (...often used in DATA Loaders). The returning numeric value is a  signed integer (16-Bit Word).
: '''2. Example''':
<pre>
PRINT VAL("&A")
10

PRINT VAL("&7FFF")
32767

PRINT VAL("&8000")
-32768
</pre>
: '''3. Example''':
<pre>
10 CLS: PRINT "I know my times tables!"
20 PRINT:PRINT "Press a key (1 to 9)"
30 a$=INKEY$:IF a$="" THEN 30
40 n=VAL(a$):if n<1 or n>9 then 30
50 FOR x=1 to 12
60 PRINT n;"X";x;"=";n*x
70 NEXT:GOTO 20
run
</pre>
==== <code><big>VPOS (#<stream expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current vertical POSition of the text cursor relative to the top of the text window. The <stream expression> MUST be specified, and does NOT default to #0.

: '''Associated keywords''': POS, WINDOW

: '''Example''':
<pre>
10 MODE 1:BORDER 0:LOCATE 8,2
20 PRINT "use cursor up/down keys"
30 WINDOW 39,39,1,25:CURSOR 1,1
40 LOCATE 1,3
50 IF INKEY(0)<>-1 THEN PRINT CHR$(11);
60 IF INKEY(2)<>-1 THEN PRINT CHR$(10);
70 LOCATE #1,3,24
80 PRINT #1,"text cursor ";
90 PRINT #1,"vertical position =";
100 PRINT #1,VPOS(#0):GOTO 50
run
</pre>
==== <code><big>XPOS</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current horizontal (X)POSition of the graphics cursor.

: '''Associated keywords''': MOVE, MOVER, ORIGIN, YPOS

: '''Example''':
<pre>
10 MODE 1:DRAW 320,200
20 PRINT "graphics cursor X position = ";
30 PRINT XPOS
</pre>
==== <code><big>YPOS</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current vertical (Y)POSition of the graphic cursor.

: '''Associated keywords''': MOVE, MOVER, ORIGIN, XPOS

: '''Example''':
<pre>
10 MODE 1:DRAW 320,200
20 PRINT "graphics cursor Y position = ";
30 PRINT YPOS
</pre>

== Other Basic Dialects available for the CPC ==

*[[BBC Basic]]
*[[C BASIC Compiler|CBASIC]]
*[[BASIC-E]]

== Technical Information ==

* [[Technical_information_about_Locomotive_BASIC]]

== Web links ==

* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]
* [http://rosettacode.org/wiki/Category:Locomotive_Basic Code examples at Rosetta Code]

* [http://cpctech.cpc-live.com/docs/basic.asm Disassembly of Locomotive BASIC v1.1]

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Locomotive BASIC

2025-10-02T13:04:35Z

Arnoldemu: /* CAT */

For other BASIC language versions see the [[:Category:BASIC]]

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

It was availlable directly from in-built ROMs on [[CPC old generation]] and on the [[Plus System Cartridge]] for the [[Plus]] range. [https://benchmarko.github.io/CPCBasic/ Online Interpreter]

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

If you are interested in more information about the different versions of the CPC's BASIC and the technical details, you can have a look at the article "[[Technical information about Locomotive BASIC]]".

Another helpful and further resource of information about BASIC and a similar comprehension to this is Grimware's Website about the CPC http://www.grimware.org/doku.php/documentations/software/locomotive.basic/start

== 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 and Spanish 472 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 472 (British), 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.

== Variables ==
Many contemporary BASIC interpreters only supported the first few characters of a variable name as a discriminator. For example <code>WATER$</code> and <code>WALDO$</code> would refer to the same variable on a Commodore 64 or Apple II. But Locomotive BASIC allowed variable names up to 40 characters in length, so <code>THEQUICKBROWNFOXJUMPEDOVERTHELAZYDOGFAST$</code> and <code>THEQUICKBROWNFOXJUMPEDOVERTHELAZYDOGFATS$</code> could be use as separate variables.

=== Real (Floating Point) Numbers ===

This is the default type for a Locomotive BASIC variables, but can be clarified using <code>!</code> after the variable name, e.g., <code>real!=500.0</code>.
You can force all variables starting with specific letters to be this type by using the <code>DEFREAL</code> keyword.
In many cases you don't want to use these, as they are slower than using the integer type, and use more memory (5 bytes, as opposed to 2).

=== Signed 16-bit Integers ===

Defined using <code>%</code> after the variable name, e.g., <code>integer%=500</code>.
You can force all variables starting with specific letters to be this type by using the <code>DEFINT</code> keyword.
These can store values between -32,768 and 32,767.
To assign a 16-bit value to a signed integer directly, you should give the number in a hexadecimal format, e.g., <code>uint=&c0000</code>.

=== Strings ===

These are defined by using <code>$</code> after the variable name, e.g., <code>str$="Hello"</code>.
You can force all variables starting with specific letters to be this type by using the <code>DEFSTR</code> keyword.
A String can be up to 255 characters long.

== Type Conversions ==

The BASIC functions <code>ROUND</code>, <code>INT</code>, <code>CINT</code> and <code>FIX</code> can be used to convert real numbers into integers taking some care about rounding. The difference is in rounding mode - <code>ROUND</code> rounds to nearest, <code>FIX</code> rounds to zero, <code>INT</code> always rounds down, and <code>CINT</code>rounds up. e.g., <code>value%=INT(3.14)</code>. Note that if you don't specify the % you will actually get a real number still.

To convert an integer to a real number, you can use the <code>UNT</code> function which will take the value supplied and return the two's complement number. e.g., <code>real=UNT(&ABCD)</code>.

<pre>
w=UNT(50000)
Ready
PRINT w
-15536
Ready
█
</pre>

If you want an integer result from division, use the <code>\</code> integer division operator. e.g., <code>int=value\divisor</code>. This is as opposed to the standard <code>/</code> division operator, that can create a real number.

== Command list ==

=== Commands and operators ===

==== <code>AFTER ‹time delay›[,‹timer number›] GOSUB ‹line number› </code>====
: Waits for ‹time delay›/50 seconds and then jumps NON-RECURRING to the subroutine at ‹line number› (see also <code>"EVERY i[,t] GOSUB line"</code>).

==== <code>AUTO [‹line number›][,‹increment›] </code>====
: Automatically generates line numbers starting at ‹line number› with ‹increment› after each entered line number. Use '''[ESC]''' to leave AUTO mode. Default values for ‹line number› and ‹increment› are 10.

: Example:
<pre>AUTO 100,5 :REM generates line numbers 100, 105, 110...</pre>

==== <code>BORDER ‹colour›[,‹colour›] </code>====
: Changes the colour of the border. If the second argument is supplied the border flashes between the two colours.

==== <code>CALL ‹address expression›[,‹list of: parameter›] </code>====
: Allows a machine code routine to be called by BASIC. Variables, string values and constants can be passed to the routine. Values of any supported type can be passed back by supplying a variable with <code>@</code> in front of it. This passes the address of the variable to the routine although it doesn't implicitly know the data type.
: Example:
<pre>CALL 0 :REM resets the computer completely</pre>

==== <code>CAT</code> ====
: Displays the names of the files on the tape or disc. Tape files are displayed in the order they are encountered. Disc files are sorted alphabetically by ASCII code. Only files matching the current user are displayed. Files marked as system are not displayed.
: Examples:
<pre>CAT :REM lists all disc files in alpha-numeric (ASCII) order</pre>

<pre>|TAPE :CAT :REM lists names of all tape files in their storage order</pre>

==== <code>CHAIN ‹file name›[,‹line number expression›] </code>====

:Enables the specified program to be loaded and RUN automatically. If the optional parameter ‹line number expression› is specified, the program execution will commence from that line.

==== <code>CHAIN MERGE ‹file name›[,‹line number expression› | [,[‹line number expression›],DELETE ‹line number range›]] </code>====

:Loads the specified program from tape or disc, merges it into the program in memory, and starts execution of the merged program. The parameter <code>DELETE</code> ‹line number range› is used to delete part of the original program before running it, if required.

==== <code>CLEAR</code> ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.
: The command clear inside a subroutine (<code>GOSUB</code>... <code>RETURN</code>) will also clear the "stack pointer" address of the gosub heap. That means that a RETURN won't work and a GOTO has to be used instead.

==== <code>CLG [‹masked ink›] </code>====
: Clears the graphics screen to colour specified by <code>‹masked ink›</code>. If parameter <code>‹masked ink›</code> is not specified then the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== <code>CLOSEIN</code> ====
: Closes any input file (tape or disc).

==== <code>CLOSEOUT</code> ====
: Closes any output file (tape or disc).

==== <code>CLS [#‹stream expression›]</code>====
: Clears the window specified by ‹stream expression›. If ‹stream expression› is omitted it defaults to #0 (usually the whole screen). The text cursor of the stream is moved to the upper left corner.

==== <code>CONT</code> ====
: CONTinues program execution interrupted either by [ESC] [ESC] or as a result of STOP within a program. A program cannot be continued after being modified.

==== <code>CURSOR ‹expression› </code>====
: <code>‹expression›</code> must be either 0 or 1.

==== <code>DATA x1[,x2,x3...]</code> ====
: 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>

==== <code>DEF</code> ====
: DEF means "define" and comes along with defining a function in case of DEF FN or defining variables in case of DEFREAL, DEFINT or DEFSTR.
: DEF FN must come before using the statement FN.
: DEF with a variable declaration should come before using a variable.
: (see also FN)

==== <code>DEFINT ‹letter range›</code> ====
:Forces all variables(s) starting with the specified letter(s) to be integer variables. Singular letters could be defined or a range by a minus symbol between two letters.

:Examples:
<pre>
20 DEFINT a-z:' sets all variables starting with an A until Z as integer.
</pre>
or
<pre>
10 DEFINT F,S ..... (or 10 DEFINT A-Z)
20 FIRST=111.11:SECOND=22.2
30 PRINT FIRST,SECOND:' prints out 111 22
</pre>

==== <code>DEFREAL ‹letter range›</code> ====
: Sets the default for variable(s) with the specified first letter(s) to a floating point figure.

==== <code>DEFSTR ‹letter range›</code> ====

: Sets the default for variable(s) with the specified first letter(s) to string(s) variables.

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

==== <code>DELETE [first line][-[last line]]</code> ====
: Deletes the current program completely (without arguments) or only the given line or line range. Even
: <code>DELETE -</code>
: is legal, it has the same effect as
: <code>DELETE</code>
: The lines specified do not have to exist, all lines matching the range will be deleted and having no matches does not cause an error.

==== <code>DI</code> ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.
: This means that DI (if it's activated in a subroutine) is useful helping a low-priority-interrupt not to be stopped by a higher-priority-interrupt. RETURN then re-enable the interrupt without EI.

==== <code>DIM a[%|!|$](d1[,d2[,...]])</code> ====

: Creates array <code>a</code> with single or multiple dimensions. You may optionally specify integer (<code>%</code>), real (<code>!</code>) or string (<code>$</code>) type otherwise it defaults to the current type set for the first letter of the array name. <code>d1</code> is size of first dimension-1, <code>d2</code> is size of second dimension-1 and so on. <code>DIM x(10)</code> will create an array with 11 elements, <code>x(0)</code> is the first element, <code>x(10)</code> is the eleventh and last. You can specify as many dimensions as will fit on one 255 character line, which is a maximum of 125. Trying to create an array that already exists will generate an <code>Array already dimensioned</code> error. If an array is not specified by <code>DIM</code> before being accessed, each dimension value defaults to 10. The maximum dimensions that can be created this way is three.

==== <code>DRAW x,y[,[i1][,i2]]</code> ====

: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the drawing style.

: 4 drawing styles:
<pre>
i2 = 0 normal colour
i2 = 1 XOR colour
i2 = 2 AND colour
i2 = 3 OR colour
</pre>
: Example:
<pre>
CLG 2
DRAW 500,400,0 :REM draws a line from 0,0 to 500,400
</pre>

<code>DRAWR xr,yr[,[i1][,i2]]</code> ====

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

<pre>
Move 200,200
DRAWR 100,100,0 - draws a line from 200,200 to 300,300
</pre>

==== <code>EDIT ‹line›</code> ====
: Display 1 program line for editing.

The following keys can be used in editing mode, or during typing in BASIC:

CTRL+TAB - toggle overwrite/insert mode
CTRL+CURSOR LEFT or CTRL+CURSOR UP - go to start of line
CTRL+CURSOR RIGHT or CTRL+CURSOR DOWN - go to end of line
CURSOR LEFT - move left one character
CURSOR RIGHT - move right one character
ESC - quit editing and do not accept changes
ENTER/RETURN - quit editing and accept changes
SHIFT + CURSOR UP/DOWN/LEFT/RIGHT - enter copy mode. You can move the cursor to where you want to copy from. Hold SHIFT and cursors to move copy cursor.
COPY - copy character covered by copy cursor.
DEL - delete character and go back a char
CLR - delete character under cursor
CTRL + CAPS LOCK - toggle shift lock.

==== <code>EI</code> ====
: Enable interrupts which have been disabled by DI

==== <code>END</code> ====
: Indicates end of program

==== <code>ENT ‹tone envelope number›[,‹tone env. section›][,‹tone env. section›][,‹tone env. section›][,‹tone env. section›][,‹tone env. section›]</code> ====
:The ENT command define the TONE shape of a sound which means manipulating the frequency in a certain range.
:The command could looks like:
<pre>
ENT NUMBER,STEPS?,VERTICAL?,HORIZONTAL?
</pre>
:It is possible to define 15 different envelope shapes. So '''NUMBER''' could be 1-15.

:Each '''?''' stands for up to five sections (1-5), where each STEP<>VERTICAL<>HORIZONTAL with the same '''?''' are belong together.

:'''STEP:''' means how many steps in each section (0-127) > one step is 1/100 of a second!
:'''VERTICAL''': means how big is the step size from bottom to top (-128 to 127)
:'''HORIZONTAL''': means how big is the step size from left to right (0-255)

==== <code>ENV ‹volume envelope number›[,‹volume env. section›][,‹volume env. section›][,‹volume env. section›][,‹volume env. section›][,‹volume env. section›]</code> ====
:The ENV command define the VOLUME shape of a sound which means manipulating the loudness in a certain range.
:The command could looks like:
<pre>
ENV NUMBER,STEPS?,VERTICAL?,HORIZONTAL?
</pre>
:It is possible to define 15 different envelope shapes. So '''NUMBER''' could be 1-15.

:Each '''?''' stands for up to five sections (1-5), where each STEP<>VERTICAL<>HORIZONTAL with the same '''?''' are belong together.

:'''STEP:''' means how many steps in each section (0-127) > one step is 1/100 of a second!
:'''VERTICAL''': means how big is the step size from bottom to top (-128 to 127)
:'''HORIZONTAL''': means how big is the step size from left to right (0-255)

==== <code>ERASE v1[% | ! | $][,v2[% | ! | $][,...]]</code> ====
: Erases the specified array(s) and frees the memory used. Must specify existing array(s) or an <code>Improper argument</code> error will be generated.

==== <code>ERL</code> ====

: Returns the line number of the last error encountered.

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

==== <code>EVERY i[,t] GOSUB ln</code> ====

: BASIC branches to the subroutine at line ln EVERY (reccuring) i/50 seconds. (see also "AFTER i[,t] GOSUB line")

: There are 4 delay timers from 0 to 3 which can be specified with ‹timer number›. If omitted ‹timer number› defaults to 0.
: In the case of parallel task has 3 the highest and 0 the lowest priority.
: With DI or EI you can disable or enable the timing interrupt. With REMAIN <timer number> you can also disable an AFTER or EVERY construct and stores the "remaining" time (> REMAIN)
: Interrupts run as long as the main loop / program runs, even the main programm is paused > press ESC only '''once''' not twice for a break.
: It is important to know or realise that low-priority-interrupts which occurs simultanously to higher-priority-interrupts are not lost. Their task remains or handled again after finishing the higher-prio interrupt.

<pre>
10 REM > interrupts
20 EVERY 50,0 GOSUB 100: REM > lowest priority
30 EVERY 100,1 GOSUB 200
40 EVERY 200,2 GOSUB 300:
50 AFTER 1000,3 GOSUB 400: REM > highest priority
60 WHILE flag=0
70 a=a+1:print a
80 WEND
90 END
100 REM #0
110 PEN 2:PRINT "timer 0":PEN 1
120 RETURN
200 REM #1
210 PEN 2:PRINT "timer 1":PEN 1
220 RETURN
300 REM #2
310 PEN 2:PRINT "timer 2":PEN 1
320 RETURN
400 REM #3
410 flag=1:PEN 2:PRINT "no more interrupts..."
420 RETURN
</pre>

: Hint: Timing with interrupts is important, especially if more than one interrupts run. If the interval of a subroutine driven by an interrupt is too long than the processor can never get back to deal the main program again. Work out timing by measuring the subroutine or by trial and error.
: There are system internal interrupts (highest level) which cannot be influenced by BASIC interrupts (e.g. keyboard scan > BREAK key.)
: The next level of sytem internal interrupts CAN be influenced by BASIC interrupts. For example the sound queue which will be created by "ON SQ <chanel> GOSUB <line>". Those sound interrupts have an independent time tricker but their priority is parallel to the second priority times of BASICs interrupts. Therefore interrupts with timer 3 could "interrupt" them.

==== <code>FILL i</code> ====
: 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.

==== <code>FN</code> ====
:BASIC allows the program to define and use simple value returning functions. DEF FuNction is the definition part of this mechanism and creates program-specific function which works within the
:program in the same way as a function such a COS operates as a built-in function of BASIC. It may be invoked throughout the program. Variable types must be consistent and the DEF FN
:command should be written in part of the program outside the execution loop.

:Syntax : <code>DEF FN<name>[(<formal parameters>)]=<general expression></code>

:Example: ''"with the definition of..."''
<pre>
10 gn=9.80665
20 DEF FNgrv=s0+v0*t+0.5*gn*t^2
30 s0=0:v0=0:t=5
40 PRINT "...after";t;"seconds your dropped stone falls";FNgrv;"metres"
</pre>
:''"the results are..."''
<pre>
:...after 5 seconds your dropped stone falls 122.58315 metres
</pre>

==== <code>FOR TO STEP NEXT</code> ====
: Creating a counting loop (control strucutre) with a starting condition. Inside the counting loop one or more commands will be executed.
: The loop consists of of following specifications:

: 1. FOR
: 2. ''a control variable''
: 3. =
: 4. ''starting value''
: 5. TO
: 6. ''target value''
: 7. STEP [optional]
: 8. ''increment / step size''
: ''... instructions between''
: 9. NEXT
: 10. ''control variable'' [optional]

: You have to use the command STEP if you wish to count backwards. It's good to name the ''control variable'' after NEXT for readability and better program style.
: After each loop the computer checks internaly if the ''target value'' has been reached (like an IF ... THEN ... ELSE instruction). If the target value is reached NEXT closes the loop and calculates another step, so the ''control variable'' will be changed last time.
: The default STEP value - if not specified - is one (1).

: Example:
<pre>
10 FOR I=1 TO 10
20 PRINT I;
30 NEXT I
40 PRINT I
RUN
1 2 3 4 5 6 7 8 9 10 11
READY
</pre>

==== <code>FRAME</code> ====
: 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.

==== <code>GOSUB i</code> ====

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

==== <code>GOTO i</code> ====
: 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>
: GOTO is the simplest form of a jump or creating a loop '''without''' condition controll.
: ''Example: (unconditional and endless loop)''
<pre>
10 PRINT "#";
20 GOTO 10
</pre>
: Combine the GOTO command with an IF...THEN...ELSE instruction for creating a condition-controlled loop with the '''test at the end'''. Helpful because the Locomotive Basic has no practical DO...WHILE... loop.
: ''Example: (condition at the end)''
<pre>
10 I=1
20 PRINT I
30 I=I+1
40 IF I<25 THEN GOTO 20
50 END
</pre>

==== <code>GRAPHICS</code> ====
: ...works only in combination with the command <code>PEN</code> or <code>PAPER</code> to set the plotting/drawing pen or background colour.
: If the <code>TAG</code> command is used to set text at the graphics cursor <code>GRAPHICS PEN</code> or <code>GRAPHICS PAPER</code> instead of the regular <code>PEN</code> or <code>PAPER</code>is necessary to colour the text.

==== <code>IF THEN ELSE</code> ====
: Asks for a choice with the '''IF...THEN...ELSE''' statement.
: '''IF''' compares the entry condition in a logical way
: '''THEN''' contains instruction if the comparison is true
: '''ELSE''' contains instruction if it's false.
: '''Example:'''
<pre>
10 INPUT "guess a figure:",f
20 IF f=10 THEN PRINT "right": END: ELSE GOTO 10
</pre>
: In case of nested choices there's a possibility to that with an IF...THEN instruction but not very recommended:
<pre>
10 INPUT "guess a figure:",f
20 IF f=10 THEN PRINT "right": END: ELSE IF f<10 THEN PRINT "too small" ELSE PRINT "too big"
30 GOTO 10
</pre>
:Other nested structures like IF...THEN...'''ELSE...ELSE''' won't work first because the Locomotive Basic only looks after the first ELSE instruction found and can't execute more single commands as a block for a certain condition in comparision to e.g. "PASCAL" > begin...end-block, "C" > {...}-block.

==== <code>INK ‹pen›,‹colour›,[‹second colour›]</code> ====
: Used to set the colour palette for each of the 16 available inks.
: pen specifies the pen slot to use.
: colour specifies the system colour to use (0..27.)
: if the second colour is provided, Locomotive Basic will blink between the colour and second colour.
: In MODE 0, all 16 pens are available. In MODE 1, only 4 pens are available (0..3). In MODE 2, only 2 pens are available (0..1.)
: By default, pen 0 is the background colour and pen 1 is the foreground/text colour.
: Examples:
<pre>
10 MODE 2
20 INK 0,3: REM Set background colour to red
30 INK 1,26: REM Set foreground/text colour to white
</pre>

==== <code>INPUT[#‹stream expression›][,]</code> ====
: [...]

==== <code>KEY</code> ====
: [...]

==== <code>LET</code> ====
: Used to define variables. You don't need to use the ''LET'' command because it is just a command which was added for compatibility reasons.
: ''Example:''
<pre>
10 LET a$ = "hello world"
20 PRINT a$
</pre>

==== <code>LINE INPUT [#‹stream expression›][,]‹variable›[,‹variable›] </code>====
: [...]

==== <code>LIST [‹line number›][-[‹line number›]], [#‹stream expression›]</code>====
: A command for listing the Basic program code.
: Possibility for manipulating display is using line numbers with a minus symbol.
: Example:
<pre>
LIST 100-
</pre>
: List every line after line number 100.
<pre>
LIST -100
</pre>
: List every line until line number 100 has reached.
<pre>
LIST 100-200
</pre>
: List every line between line number 100 and 200 included

: With the help of separate window definitions it is possible to print out long listings, better differentiate parts / slices of it into different window predefined
: Example:
<pre>
LIST 1000-1100,#1
LIST 3000-3100,#2
</pre>
: ...prints out two parts of one program out into two windows (if they are defined well)

==== <code>LOAD ‹file name›[,‹address›] </code>====

With this directive you may load any file in memory

Basic files (extension .BAS) are loaded in Basic memory, you cannot choose loading address

Binary files are loaded to the default address location stored in the AMSDOS header but you may force loading address (&C000 for a screen)

TAPE convention:

When loading tape files, the basic display a message every block which may cause trouble. Message output may be disabled by using prefix "!" before the filename.

It's also possible to load the next file disregarding his name using only "!" => <code>LOAD "!"</code>

==== <code>LOCATE[#‹stream expression›][,] x,y</code> ====

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

==== <code>MASK [i1][,i2]</code> ====

: Sets bits in each adjacent group of 8 pixel on (1) or off (0) according to binary value of i1 (0-255). i2 determines whether the first point of the line is to plotted (1) or not (0).

:Example:

<pre>
10 CLG 2:MASK 1:MOVE 0,0:DRAW 500,400
20 MASK 15:MOVE 0,0:DRAW 500,400
</pre>

==== <code>MEMORY ‹memory address›</code> ====

: Allocates the amount of memory to be used by BASIC by setting the [[Locomotive_BASIC#HIMEM|address of the highest byte]] it may use.

==== <code>MERGE</code> ====
: [...]

==== <code>MID$ (‹string›,‹start position›[,‹length of substring›])</code> ====
: With the MID$ command there are two applications possible:

: 1. MID$ creates a new substring out of the give ‹string› and starts at the defined position ‹start position› and print the number of given characters by ‹length of substring›.
: If no length is defined every character from ‹start position› will be printed out.
: If a higher value of ‹start position› or ‹length of substring› than the real length of the initial string is defined a blank string will be printed.
: The range of ‹start position› or ‹length of substring› is from 0 up to 255 characters.

: 2. With MID$ you're able to manipulates given strings by inserting a new string.
: Take care of the two different applications and using in BASIC.

: Example for the 1. application:
<pre>
10 a$="Hello"
20 PRINT MID$(a$,2,2)
run
el
Ready
</pre>
:
: Example for the 2. application
<pre>
10 a$="Hello"
20 MID$(a$,2,3)="ipp"
30 PRINT a$
run
Hippo
Ready
</pre>

==== <code>MODE</code> ====
: Changes the screen mode: MODE 0 is 160×200 in 16 colours, MODE 1 is 320×200 4 colours, MODE 2 is 640×200 2 colours and MODE 3 is 160×200 in 4 colours.

==== <code>MOVE x,y [[,i1][,i2]]</code> ====

: Moves the graphic cursor to position x,y. The parameter i1 may be used to change the pen (drawing) colour. The parameter i2 specifies the logical colour, as in DRAW.

: 4 drawing styles:
<pre>
i2 = 0 normal colour
i2 = 1 XOR colour
i2 = 2 AND colour
i2 = 3 OR colour
</pre>

==== <code>MOVER xr,yr[,[i1][,i2]]</code> ====
: moves the graphic cursor (relative) from current position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as in MOVE.

==== <code>NEW</code> ====
: Clears BASIC RAM which means program and variables. Keeps symbol defintion (if defined) and screen mode without clearing.

==== <code>ON BREAK CONT</code> ====

: Prevents the interruption of program execution by the ESC key.

==== <code>ON BREAK GOSUB ln</code> ====

: Passes control to subroutine at line ln when ESC ESC pressed.

==== <code>ON BREAK STOP</code> ====

: Restores normal function of ESC key during program execution.

==== <code>ON ERROR GOTO ln</code> ====

: Passes the control to line ln if an error is detected in the program.

: ON ERROR GOTO 0, Turns of the error trap, and restores normal error processing.

==== <code>ON variable GOTO ln x1, x2, x3, x4, ...</code> ====

: In case of passing more choices '''ON variable GOTO ln x1, x2, x3, x4, ...''' points to a table with the jumping target.
: '''Example:'''
<pre>
10 PRINT "1. LOAD - 2. SAVE - 3. EXIT"
20 INPUT choice
30 ON choice GOTO 1000, 2000, 3000
40 CLS: GOTO 10
1000 PRINT "1. LOAD":END
2000 PRINT "2. SAVE":END
3000 END
</pre>
:In case that the variable ''choice'' won't fullfil the condition (in a range between line 0 and 65535) the next instruction will be executed (here: Line 40). If "choice" is smaller than 0 an error will occur.

==== <code>ON variable GOSUB ln x1, x2, x3, x4, ...</code> ====

: In case of passing more choices targeting to SUBROUTINES '''ON variable GOSUB ln x1, x2, x3, x4, ...''' points to a jumping table.
: '''Example:'''
<pre>
10 PRINT "1. LOAD - 2. SAVE - 3. EXIT"
20 INPUT choice
30 ON choice GOSUB 1000, 2000, 3000
40 CLS: GOTO 10
1000 PRINT "1. LOAD":RETURN
2000 PRINT "2. SAVE":RETURN
3000 END
</pre>
:In case that the variable ''choice'' won't fullfil the condition (in a range between line 0 and 65535) the next instruction will be executed (here: Line 40). If "choice" is smaller than 0 an error will occur.

==== <code>ON SQ(x) GOSUB ln x1, x2, x3, x4, ...</code> ====
:ON SQ(x) can trigger an interrupt when e.g. a space or free channel in queue.
:Using that command is a one way interrupt trigger and shouldn't be mixed with <code>EVERY</code> or <code>AFTER</code> commands.

:See also the <code>SQ(x)</code> command for more details.

==== <code>OPENIN ‹filename›</code> ====
: Opens the specified data file for reading. It has to be an ASCII file. ( The command <code>CLOSEIN</code> closes reading data file. )
: Read from the file using <code>INPUT #9</code>

==== <code>OPENOUT ‹filename›</code> ====
: Opens the specified data file for writing. It writes an ASCII file. (The command <code>CLOSEOUT</code> finishes writing to the file and closes it cleanly.)
: Write to the file with PRINT#9.
: No file is likely to be written until enough data is written (e.g. 2KB) or the file has at least 1 byte written and CLOSEOUT is used.
: The following code pattern can be used to set MEMORY and lower HIMEM lower than would normally be allowed. This is often seen in disc loaders. This doesn't cause any file to be written:

OPENOUT"<filename>
MEMORY address
CLOSEOUT

==== <code>ORIGIN x,y[,l,r,t,b]</code> ====
: The command defines the origin ('world reference point') for the graphics coordinate system. Normally the reference origin is in the left, bottom corner of the default screen and has 0,0. So the most left coordinate value could be by default 639 and the most top value 399. Independent from the actual modus (2, 1 or 0) the range for the x coordinate are always 640 points and for the y coordinate 400 points. In theory you are able to address 256,000 pixel but only 128,000 are visible due to the maximal resolution of the hardware.
: <code>x,y</code> are the the new coordinates for the 'world reference '.
: <code>l,r,t,b</code> are optional and set the borders for the new graphical window (works in the same way like the <code>WINDOW</code> command for a text window). l,r,t,b means left, right, tob and bottom coordinates.
: If a new graphical window (borders) is defined every point or drawn line won't be plotted (clipped internally).

: Example (the line drawn will be cutted):
<pre>
ORIGIN 320,200,250,450,100,300
DRAW 0,200
</pre>

==== <code>OUT ‹address›,‹value›</code> ====

: Outputs a value (range of 0-255) to a specific I/O address.
: Watch out http://cpcwiki.eu/index.php/I/O_Port_Summary

==== <code>PAPER[#‹stream expression›][,]</code> ====
: [...]

==== <code>PEN[#‹stream expression›][,]</code> ====
: [...]

==== <code>PLOT</code> ====
: [...]

==== <code>PLOTR</code> ====
: [...]

==== <code>POKE add</code> ====

: Alters contents of memory location add to value i (0-255)

==== <code>PRINT[#‹stream expression›][,]</code> ====
: [...]

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

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

==== <code>RANDOMIZE [seed]</code> ====

: Resets the pseudo-random generator to the given seed (starting value of the 'random' series). 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>

: <code>RANDOMIZE TIME</code> isn't still a 'real' random number but to hit the same series again is pretty hard due to the time elapsed.
: The algorithm used for randomizing is the following: the generator starts with the seed, adds 1, multiplies by 75 (fiddle factor), divides by 65537 and then uses the remainder -1.

==== <code>READ variable</code> ====
: 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>

==== <code>RELEASE chanel</code> ====
: Releases a sound which was hold on (by a SOUND command) before. It uses the same bit matrix like the SOUND command for the first parameter
# (&x00000001) releases chanel A
# (&x00000010) releases chanel B
# (&x00000011) releases chanel A and B
# (&x00000100) releases chanel C
# (&x00000101) releases chanel A and C
# (&x00000110) releases chanel B and C
# (&x00000111) releases chanel A, B and C

:Example:
<pre>
10 SOUND 65,1000,100
20 PRINT"PRESS R TO LET IT SOUND"
30 IF INKEY(50)=-1 THEN 30
40 RELEASE 1
</pre>

==== <code>REM [any text]</code> ====
: Introduces a comment.

==== <code>RENUM [‹newLine›][,‹oldLine› | ,[‹oldLine›],‹step›] </code>====
: Renumbers the lines of the current program.

: By default, the whole program is renumbered starting at line 10 with multiples of ten. Any parameter that is left out defaults to 10. It is important to note that ''jumps'' (<code>GOTO</code>, <code>GOSUB</code> 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 <code>RENUM 100,20,5</code>

<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== <code>RESTORE [line]</code> ====

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

==== <code>RESUME [line] or NEXT</code> ====
: Command causes the program to resume after an error code and if it is interrupted by an '''ON ERROR GOTO''' jump
: So it can either resume
*(if there's no line number stated) at the same line after error code (and if there are more statements in one line)
or
* at the line number stated (optional)
or
* with the NEXT parameter (optional) ... at the line followed by the error line

==== <code>RETURN</code> ====

: Terminates a subroutine and returns control to the line following the GOSUB call (see GOSUB)

==== <code>RUN [line] or "filename"</code> ====
:Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

:If a string is used after RUN command a programm will be loaded and executed from storage medium (e.g. Tape, Disc). With that command protected BASIC programs can be executed.

:Exampel:
<pre>
RUN"disc"
</pre>

==== <code>SAVE "filename" [,filetype][,paramter1,parameter2,parameter3]</code> ====
: Command saves the current BASIC program / content from RAM onto a storage medium (e.g. Tape, Disc)

: Filetype could be:
* ''',A''' for a ASCII file
* ''',B''' for a binary file (store RAM content as it is)
* ''',P''' for a regular, ''protected'' BASIC file
: without that parameter the content will be stored as a regular BASIC file

:The three parameters after filetype could be used in combination with the binary filetype (,B).
* '''''parameter1''''' defines the starting address of memory range
* '''''parameter2''''' defines the length (range of memory)
* '''''parameter3''''' defines the entry point (optional)

==== <code>SOUND</code> ====
: the SOUND command has following shape:
: SOUND '''C'''hannel,'''P'''eriod,'''D'''uration,'''V'''olume,Volume-'''Env'''elope,'''T'''one-'''En'''velope,'''N'''oise

:'''C:''' Selecting channel is done bitwise (combinations are possible of course):

<pre>
(Bit 0) &x00000001 = 1 = channel A (middle)
(Bit 1) &x00000010 = 2 = channel B (left)
(Bit 2) &x00000100 = 4 = channel C (right)
</pre>
:more function about channel are
<pre>
(Bit 3) &x00001000 = 8 = Rendezvous with channel A
(Bit 4) &x00010000 = 16 = Rendesvous with channel B
(Bit 5) &x00100000 = 32 = Rendesvous with channel C
(Bit 6) &x01000000 = 64 = Hold
(Bit 7) &x10000000 = 128 = Flush
</pre>
:'''P:''' the period number can be a figure between 0 and 4095 (2^12-1... 12 means that we have 12 tones (inclusive half-tones) in nine octaves on the CPC in sum and their distance between is the twelves square root of two), where 8 octaves are available. E.g. Octave 0 starts on middle C with number 478.
: To calculate the period you can use following formula: '''period=1,000,000/(16*frequency)''' or in short '''period=(62,500/frequency)'''
: (e.g. the note "A" with the frequency 440 Hz has the period 142 on the CPC)

:'''D:''' the duration of the note is measured in 1/100th of a second and can be any positive number in the range 1-32,767. 0 and negative number are in combination with ENT and ENV commands usefull. A negative number means repititions.

:'''V:''' the volume number range from 0-7 on a CPC 464 (BASIC 1.0) or 0-15 on a CPC664/6128 (BASIC 1.1)

:'''ENV:''' and '''ENT:''' For shaping the sound ENV (Volume) and ENT (Frequency) commands are available. The relation between SOUND and those commands comes with a figure between 1 to 15 for ENV (5th parameter) and 1 to 15 for ENT (6th parameter).

:'''N:''' the seventh parameter can be used for blending in noise between the range of 0-15 (BASIC 1.0) or 0-30 (BASIC 1.1). The higher the number the 'deeper' or 'dirty' is the noise.

==== <code>SPC <n></code> ====
: in conjunction with PRINT the SPC command prints out a certain number (n) of spaces.
: Example:
<pre>
PRINT "Hello";SPC(10);"World";
Hello World
</pre>

==== <code>SPEED INK <n1,n2> </code> ====
: SPEED INK command defines the frequency of colour changes if a colour change was defined. The duration is calculated by n1=... or n2 =duration/50 seconds.

==== <code>SPEED KEY <start,repeat> </code> ====
: SPEED KEY command defines the delay after which a key repeat (for keys that do repeat). The first parameter is the delay before the first repeat and the second parameter is the delay between further repeats. Delay is in 1/50th of seconds.

:When using it with low values, it is common to associate a key to reset the default speed of 30,2.
:For example to associate the key 0 from the numpad:
<pre>
KEY 0,"SPEED KEY 30,2"+CHR$(13)
</pre>

==== <code>SPEED WRITE <n> </code> ====
: SPEED WRITE defines the speed at which data is to be saved or written to a cassette unit. n=1 means 2000 baud, n=0 (default) means 1000 baud. When reading from the tape, the correct speed is automatically selected.

==== <code>SQ (channel)</code> ====

: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1,2,3, = A, B, C

: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

==== <code>STOP</code> ====

: Breaks program execution at line containing the STOP statement. The message '''BREAK in''' is output with the line number.

==== <code>SWAP</code> ====
: SWAP works only in combination with the window command. Every error or status messages from the operating system will be displayed normaly on WINDOW#0 (=''main'' window). WINDOW SWAP changes the ''main'' window to the desired target window.
: Example (if a window with number 4 was defined before...):
<pre>
WINDOW SWAP 0,4
</pre>

==== <code>SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8]</code> ====

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

==== <code>SYMBOL AFTER n</code> ====
: 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.

==== <code>TAB</code> ====
: [...]

==== <code>TAG [#st]</code> ====

: Allows text to print at graphics cursor position.
: see TAGOFF

==== <code>TAGOFF [#st]</code> ====

: Directs text to stream st printing it at previous text cursor position.

==== <code>TROFF</code> ====

: Turns off the program flow trace (see TRON)

==== <code>TRON</code> ====

: Turns on the program flow trace for debugging. Causes the line number of each statement executed to be displayed.

==== <code>USING</code> ====
: The USING assignement defines the format of the PRINT output. Its appointment happens by characters where each has a certain meaning.

'''Numbers / Figures'''
: the character:
:'''#''' stands for a figure between 0 - 9
:'''.''' stands for a decimal point
:'''+''' generates a positive sign if the value is positive
:'''-''' generates a negative sign if the value is nagative
:'''**''' generates a asterix for each empty "location" before the printed character
:'''$$''' generates a Dollar characters before the printed character (the same with the pound note)
:''',''' generates a comma every each three decimals (thousands per figure) and has to be set before the decimal point or at the end if without a decimal point.
:^ generates a scientific notation (with exponents) and a the end of the format appointment

'''Strings'''
: the character:
:'''!''' prints out only the first character
:'''\xxx\''' prints out only with x-numbers defined length of the string (from left to right). x means a blank sign made with the space bar
:'''&''' the whole string is printed out as given (unknown function)

: a print output (numbers) with "%" in the beginning shows that not enough positions has to be declared (at all or before the decimal point).

: Example:
<pre>
10 figure=123456789
20 word$="Hello"
30 print using "+**,##########";figure
40 print using "\ \";word$

creates following output:

*****+12,345,679
Hel
</pre>

==== <code>WAIT add, i1[,i2]</code> ====

: Waits until the I/O port at add returns a value (0-255). The value returned is XORed with i2 and the ANDed with i1. This is repeated until a non-zero result occurs.

==== <code>WHILE WEND</code> ====
: [...]

==== <code>WIDTH</code> ====
: [...]

==== <code>WINDOW[#‹stream expression›],[L],[R],[T],[B]</code> ====
: It is possible to define in BASIC eight (8) independent windows for text output. Overlapping is possible.

: #STREAM: eight window are possible. No. zero (0) is the main window where error or status messages were put out by default.
: each position is included inside the window
: L = left column / R = right column (dependent of the mode 0 = 20 / 1 = 40 / 2 = 80)
: T = top row / B = bottom row (always from 1 to 25)

: Example:
<pre>
MODE 1
WINDOW#1,1,40,1,6
</pre>
: ...defines the first top quarter of the screen for window No. 1

==== <code>WRITE [#st,] v[$], v[$]</code> ====

: Writes the values of the specified variable to the specified stream.

: Example:

<pre>
10 OPENOUT "DUMMY"
20 INPUT A$,A
30 WRITE #9,A$,A
40 CLOSEOUT
</pre>

==== <code>ZONE i</code> ====

: Changes the width of the print zone. Default is 13.
: Example:
<pre>
10 MODE 2
20 PRINT"normal zone (13)"
30 PRINT 1,2,3,4
RUN
normal zone(13)
1 2 3 4
READY
20 PRINT"now with different zone(5)"
30 ZONE 5
40 PRINT 1,2,3,4
RUN
now with different zone(5)
1 2 3 4
READY
</pre>

=== Operators ===
: A logical status in Locomotive Basic will be represented by a "-1" for TRUE and by a "0" for FALSE.
: Example:
<pre>
PRINT (1=1)
-1
PRINT (1=2)
0
</pre>
==== <code>AND</code> ====
: Possible combinations with the AND Function:
<pre>
NPUT1 INPUT2 OUTPUT
======================
TRUE TRUE TRUE
FALSE FALSE FALSE
TRUE FALSE FALSE
FALSE TRUE FALSE
</pre>
: Example:
<pre>
PRINT 128 AND 64
0
</pre>
: looking at the BIT combination for a better understanding:
<pre>
10000000
AND 01000000
================
= 00000000
</pre>
: even in BASIC it is possible to manipulate single BITs although there are no special commands but AND, OR and XOR.
: first an example for a loop with an increasing counter WITHOUT an AND:
<pre>
10 counter=0
20 counter=counter+1
30 IF counter=32 THEN counter=0
40 GOTO 20
</pre>
: then a shorter example WITH and AND:
<pre>
10 counter=0
20 counter=(counter+1) AND 31
30 GOTO 20
</pre>
: in the second example all more significant BITs will be deleted (a common method in assembler programming)
: Beware: it only works here with BIT/number conditions one figure smaller than 1, 3, 7, 15, 31, 63 and 127
==== <code>MOD</code> ====
: '''MOD''' returns a (rounded) rest (Modulos) after dividen has been devided by the devisor.
:
:'''Example:'''
<pre>
32767 mod 256
255
</pre>
: Note: only works with numbers in the range -32768 and 32767 (&8000 < 0 < &7FFF)

==== <code>NOT</code> ====
: '''NOT''' executes a bit for bit '''negation''' of the current value. The output is a 16-Bit-Word.
:
:'''Example:'''
<pre>
10 value1=1
20 value2=NOT value1
30 PRINT value2
run
-2
</pre>
:for a better understanding...
<pre>
10 value1=1
20 PRINT HEX$(value1):PRINT BIN$(value1,8)
30 value2=NOT value1
40 PRINT HEX$(value2):PRINT BIN$(value2,8)
run
1
00000001
FFFE
1111111111111110
</pre>

==== <code>OR</code> ====
: Possible combinations with the OR Function:
<pre>
NPUT1 INPUT2 OUTPUT
======================
TRUE TRUE TRUE
FALSE TRUE TRUE
TRUE FALSE TRUE
FALSE FALSE FALSE
</pre>
==== <code>XOR</code> ====
: Possible combinations with the XOR Function:
<pre>
NPUT1 INPUT2 OUTPUT
======================
TRUE TRUE FALSE
FALSE TRUE TRUE
TRUE FALSE TRUE
FALSE FALSE FALSE
</pre>

=== Functions ===

==== <code><big>ABS (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the ABSolute value of the given numeric expression (n). This means that negative numbers are returned as positive.
: '''Associated keywords''': SGN

: '''Example''':

<pre>
PRINT ABS(-67.98)
67.98
</pre>

==== <code><big>ASC (<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the numeric value of the first character in the <string expression> (s).
: '''Associated keywords''': CHR$

: '''Example''':
<pre>
PRINT ASC("x")
120
</pre>
==== <code><big>ATN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the Arc-TaNgent of the <numeric expression> (n) to a real number ranging from -PI/2 to +PI/2 of the value specified.
: Note that DEG and RAD can be used to force the result of the below calculation to degrees or radians respectively.

: '''Associated keywords''': COS, DEG, RAD, SIN, TAN

: '''Example''':
<pre>
PRINT ATN(1)
0.785398163
</pre>
==== <code><big>BIN$ (<unsigned integer expression>,[<integer expression>])</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Produces a string of BINary digits respresenting the value of the <unsigned integer expression>, using the number of binary digits instruced by the second <integer expression> (in the range of 0 to 16). If the number of digits instructed is too great, the resulting expression will be filled with leading zeros; if the number of digits instructed is too small, the resulting expression will NOT be shortened to the instructed number of digits, but will produced in as many digits as are required.
: The <unsigned integer expression> to be converted into binary form must yield a value in the range -32768 to 65535.
: '''Associated keywords''': DEC$, HEX$, STR$
: '''Example''':
<pre>
PRINT BIN$(66,8)
01000000
</pre>
==== <code><big>CHR$ (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Converts an <integer expression> in the range 0 to 255, to its CHaRacter $tring equivalent, using the AMSTRAD character set shown in the ASCII table or e.g. in the manual part 3.
: Note that 0 to 31 are control characters; hence the below example prints CHR$(x) in the range 32 to 255
: '''Associated keywords''': ASC, LEFT$, RIGHT$, MID$, STR$

: '''Example''':
<pre>
10 FOR X=32 to 255
20 PRINT X;CHR$(X);
30 NEXT
</pre>
: A further 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.

: Control Codes Table:
<pre>
===============================================================================
| VALUE | NAME | PARAMETERS | EFFECT |
===============================================================================
| DEC | HEX | | | |
===============================================================================
| 0 | &00 | NUL | NONE | DOES NOTHING |
| 1 | &01 | SOH | 0-255 | PRINTS CHARACTER TO SCREEN |
| 2 | &02 | STX | NONE | TURNS TEXT CURSOR OFF |
| 3 | &03 | ETX | NONE | TURNS TEXT CURSOR ON IN IMMEDIATE MODE |
| 4 | &04 | EOT | 0-2 | SET SCREEN MODE |
| 5 | &05 | ENQ | 0-255 | PRINT CHARACTER AT GRAPHICS CURS. |
| 6 | &06 | ACK | NONE | TURNS ON TEXT SCREEN (SEE ALSO CHR$(21))|
| 7 | &07 | BEL | NONE | MAKE A SHORT BEEP |
| 8 | &08 | BS | NONE | MOVES TEXT CURSOR BACK ONE CHARACTER |
| 9 | &09 | TAB | NONE | MOVES TEXT CURSOR FORWARD ONE CHARACTER |
| 10 | &0A | LF | NONE | MOVES TEXT CURSOR DOWN ONE CHARACTER |
| 11 | &0B | VT | NONE | MOVES TEXT CURSOR UP ONE CHARACTER |
| 12 | &0C | FF | NONE | CLEARS SCREEN OR WINDOWS (= CLS) |
| 13 | &0D | CR | NONE | MOVES CURSOR TO LEFT EDGE OF WINDOW ON |
| | | | | CURRENT LINE |
| 14 | &0E | SO | 0-15 | SETS PAPER COLOUR |
| 15 | &0F | SI | 0-15 | SETS PEN COLOUR |
| 16 | &10 | DLE | NONE | DELETES CHARACTER UNDER TEXT CURSOR |
| 17 | &11 | DC1 | NONE | CLEARS LINE FROM LEFT OF WINDOW UP TO |
| | | | | AND INCLUDING CURRENT CHARACTER |
| 18 | &12 | DC2 | NONE | CLEARS FROM CURRENT CHARACTER TO RIGHT |
| | | | | EDGE OF THE WINDOW |
| 19 | &13 | DC3 | NONE | CLEARS FROM START OF WINDOW UP TO AND |
| | | | | INCLUDING CURRENT CHARACTER |
| 20 | &14 | DC4 | NONE | CLEARS FROM CURRENT CHARACTER TO END OF |
| | | | | WINDOW |
| 21 | &15 | NAK | NONE | TURNS OFF TEXT SCREEN (SEE ALSO CHR$(6))|
| 22 | &16 | SYN | 0 AND 1 | TURNS TRANSPARENT OPTION OFF AND ON |
| 23 | &17 | ETB | 0-3 | SET GRPAHICS PLOTTING MODE |
| 24 | &18 | CAN | NONE | CHANGE TO INVERSE CHARACTER DISPLAYING |
| 25 | &19 | EM | NINE PARAM. | DEFINES A CHARACTER (= SAME AS SYMBOL) |
| | | | EACH 0-255 | |
| 26 | &1A | SUB | FOUR PARAM. | DEFINES A TEXT WINDOW (=SAME AS WINDOW) |
| | | | 1-80, 1-80 | FROM LEFT, RIGHT, TOP TO BOTTOM |
| | | | 1-25, 1-25 | FROM LEFT, RIGHT, TOP TO BOTTOM |
| 27 | &1B | ESC | NONE | DOES NOTHING ON SCREEN (PRINTER SIGNAL) |
| 28 | &1C | FS | THREE PARAM. | SETS INK COLOUR TO FLASH BETWEEN TWO |
| | | | 0-15, 0-32 | INK NO, COLOUR 1, COLOUR 2 |
| | | | 0-32 | |
| 29 | &1D | GS | TWO PARAM. | SETS BORDER COLOUR TO FLASH BETWEEN TWO |
| | | | 0-31, 0-31 | COLOURS |
| 30 | &1E | RS | NONE | HOMES CURSOR TO TOP LEFT OF SCREEN |
| 31 | &1F | US | TWO PARAM. | MOVES CURSOR TO CELL SPECIFIED BY TWO |
| | | | 1-80, 1-25 | PARAMETERS (=SAME AS LOCATE) |
===============================================================================
</PRE>

==== <code><big>CINT (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the value of the <numeric expression> (n), Converting it to a rounded INTeger in the range -32768 to 32767.

: '''Associated keywords''': CREAL, FIX, INT, ROUND, UNT

: '''Example''':
<pre>
10 n=1.9999
20 PRINT CINT(n)
run
2
</pre>
==== <code><big>COPYCHR$ (#stream)</big></code> ====
: : ''BASIC 1.1''
: '''FUNCTION''': COPies a CHaRacter from the current position in the stream (which MUST be specified). The below program copies a character from location 1,1 (top left), and reproduces it at location 1,20.
: If the character read is not recognized, a null string is returned.

: '''Associated keywords''': LOCATE

: '''Example''':
<pre>
10 CLS
20 PRINT "top corner"
30 LOCATE 1,1
40 a$=COPYCHR$(#0)
50 LOCATE 1,20
60 PRINT a$
</pre>
==== <code><big>COS (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the COSinus of the <numeric expression> (n).
: Note that DEG and RAD can be used to force the result of the below calculation to degrees or radians respectively.

: '''Associated keywords''': ATN, DEG, RAD, SIN

: '''Example''':
<pre>
DEG
PRINT COS(45)
0.707106781
</pre>
==== <code><big>CREAL (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the value of the <numeric expression> (n), Converting it to REAL.

: '''Associated keywords''': CINT

: '''Example''':
<pre>
10 a=PI
20 PRINT CINT(a)
30 PRINT CREAL(a)
run
3
3.14159265
</pre>
==== <code><big>DEC$(<numeric expression>, <format template>)</big></code> ====
: ''BASIC 1.1''
: '''FUNCTIION''': Returns a DECimal string representation of the <numeric expression> (n), using the specified <format template> to control the print format of the resulting string.
: The format template may contain ONLY the characters:

: + - $ £ * # , . ^

: The use of these 'format field specifiers' is described under the keyword PRINT USING.

: '''Associated keyword''': BIN$, HEX$, PRINT USING, STR$

: '''Example''':
<pre>
PRINT DEC$(10^7,"££########,.##")
£10,000,000.00
</pre>
==== <code><big>DERR</big></code> ====
: ''BASIC 1.1''
: '''FUNCTION''': Reports the last error code returned by the disc filing system. The value of DERR may be used to ascertain the particular Disc ERRor that occurred. See the listing of error messages below.

: '''Associated keywords''': ERL, ERR, ERROR, ON ERROR GOTO, RESUME

: '''Example''':
<pre>
LOAD "xyz.abc"

XYZ .ABC not found
Ready
PRINT DERR
146
</pre>
: '''Table of Disc ERRor codes''':
: If AMSDOS has already reported an error, then bit 7 is set, hence the value of DERR is offset by 128.
<pre>
===============================================================================
| VALUE | DERR value | DESCRIPTION |
===============================================================================
| 0 | 0 or 22 | [ESC] has been pressed |
| 14 | 142 (128+14) | The stream is not in a suitable state. |
| 15 | 143 (128+15) | Hard end of file has been reached. |
| 16 | 144 (128+16) | Bad command, usually an incorrect filename. |
| 17 | 145 (128+17) | File already exists. |
| 18 | 146 (128+18) | File does not exists. |
| 19 | 147 (128+19) | Directory is full. |
| 20 | 148 (128+20) | Disc is full. |
| 21 | 149 (128+21) | Disc changed while file were open. |
| 22 | 150 (128+22) | File is Read/Only. |
| 26 | 154 (128+26) | Soft end of file has been detected. |
| | | |
===============================================================================
</pre>
: Other values returned by DERR originate from the disc controller and are bit significant, always with bit 6 set.
: The significance of each bit is as follows:
<pre>
===============================================================================
| BIT | Significance |
===============================================================================
| 0 | Address mark missing. |
| 1 | Not writable - disc is write protected. |
| 2 | No data - can't find the sector. |
| 3 | Drive not ready - no disc in the drive. |
| 4 | Overrun error. |
| 5 | Data error - CRC error. |
| 6 | Always set to 1 to indicate error from disc controller. |
| 7 | Set to 1 if error has already been reported by AMSDOS. |
===============================================================================
</pre>
==== <code><big>EOF</big></code> ====
: ''BASIC 1.1''
: '''FUNCTION''': Checks to see if end of specified file has been reached during input. Returns 0 (false) until the end of file, then -1 (true).

: '''Associated keywords''': OPENIN, CLOSEIN

: This '''example''' reads a file from disc and print it out on screen. Like the "TYPE" command in CP/M or "|TYPE,file" of the UTOPIA-ROM.
<pre>
10 OPENIN "text.txt"
20 WHILE NOT EOF
30 LINE INPUT#9,a$
40 PRINT a$
50 WEND
60 CLOSEIN
</pre>
==== <code><big>ERR</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the number of the last ERRor encountered. See the table below of error messages. In the example below you will see that ERRor number 8 is a 'Line does not exist' error.

: '''Example''':
<pre>
GOTO 500
Line does not exist
Ready
PRINT ERR
8
</pre>
: NOTE: BASIC 1.0 (officially) describes error codes until 30 (without an attached floppy disc controller). 31 & 32 are floppy disc error codes.
: '''Table of ERRor codes''':
<pre>
========================================================================================
| VALUE | NAME | DESCRIPTION |
========================================================================================
| 1 |Unexpected NEXT |A NEXT command has been encountered while not in a |
| | |FOR loop, or the control variable in the NEXT |
| | |command does not match that in the FOR. |
| 2 |Syntax Error |BASIC cannot understand the given line because |
| | |a construct within it is not legal. |
| 3 |Unexpected RETURN |A RETURN command has been encountered when not in a |
| | |subroutine. |
| 4 |DATA exhausted |A READ command has attempted to read beyond the end |
| | |of the last DATA. |
| 5 |Improper Argument |This is a general purpose error. The value of a |
| | |function's argument, or a command parameter is |
| | |invalid in some way. |
| 6 |Overflow |The result of an arithmetic operation has over- |
| | |flowed. This may be a floating point overflow, in |
| | |which case some operation has yielded a value |
| | |greater than 1.7E^38 (approx.). Alternatively, this |
| | |may be the result of a failed attempt to change a |
| | |floating point number to a 16 bit signed integer. |
| 7 |Memory full |The current program or its variables may be simply |
| | |too big, or the control structure is too deeply |
| | |nested (nested GOUSBs, WHILEs or FORs). |
| | |A MEMORY command will give this error if an attempt |
| | |is made to set the top of BASIC's memory too low, or|
| | |to an impossible high value. Note that an open file |
| | |has a buffer allocated to it, and that may restrict |
| | |the values that MEMORY may use. |
| 8 |Line does not exist |The line referenced cannot be found. |
| 9 |Subcript out of range |One of the subscripts in an array reference is too |
| | |big or too small. |
| 10 |Array already dimensioned|One of the arrays in a DIM statement has already |
| | |been declared. |
| 11 |Division by zero |May occur in real division, integer division, |
| | |integer modulus or exponentiation. |
| 12 |Invalid direct command |The last command attempted is not valid in direct |
| | |mode. |
| 13 |Type mismatch |A numeric value has been presented where a string |
| | |value is required or vice versa, or an invalidly |
| | |formed number has been found in READ or INPUT. |
| 14 |String space full |So many strings have been created that there is no |
| | |further room available, even after 'garbage |
| | |collection'. |
| 15 |String too long |Strings exceeds 255 characters in length. May be |
| | |generated by appending strings together. |
| 16 |String expression too |String expressions may generate a number of |
| |complex |intermediate string values. When the number of these|
| | |values exceeds a reasonable limit, this error |
| | |results. |
| 17 |Cannot CONTinue |For one reason or another the current program |
| | |be restarted using CONT. Note that CONT is intended |
| | |for restarting after a STOP command, [ESC][ESC], |
| | |or an error, and that any alteration of the |
| | |program in the meantime makes a restart impossible. |
| 18 |Unknown user function |No DEF FN has been executed for the FN just |
| | |invoked. |
| 19 |RESUME missing |The end of the program has been encountered while |
| | |in error processing mode (i.e. in an ON ERROR GOTO |
| | |routine). |
| 20 |Unexpected RESUME |RESUME is only valid while in error processing mode |
| | |(i.e. in an ON ERROR GOTO routine). |
| 21 |Direct command found |When loading a file, a line without a line number |
| | |has been found. |
| 22 |Operand missing |BASIC has encountered an incomplete expression. |
| 23 |Line too long |A line when converted to BASIC internal-form becomes|
| | |too big. |
| 24 |EOF met |An attempt has been made to read past end of the |
| | |file input stream. |
| 25 |File type error |The file being read is not of a suitable type. |
| | |OPENIN is only prepared to open ASCII text files. |
| | |Similarly, LOAD, RUN, etc, are only prepared to |
| | |deal with file types produces by SAVE. |
| 26 |NEXT missing |Cannot find a NEXT to match a FOR command. A line |
| | |number accompanying this message indicates the FOR |
| | |command to which this error applies. |
| 27 |File already open |An OPENIN or OPENOUT command has been executed |
| | |before the previously opened file has been closed. |
| 28 |Unknown command |BASIC cannot find a taker for an external command, |
| | |i.e. a command preceded by a bar |. |
| 29 |WEND missing |Cannot find a WEND to match a WHILE command. |
| 30 |Unexpected WEND |Encountered a WEND when not in a WHILE loop, or a |
| | |WEND that does not match the current WHILE loop. |
| 31 |File not open |(see 'Disc ERRors above). |
| | |If access attempted when no file was open. |
| 32 |Broken in |(see 'Disc ERRors above). |
| | |If access attempted when no file was open. |
| | | |
| | |If value 31 or 32 are stated, DERR could be |
| | |interrogate to give more detailed information. |
| | |(see example below.) |
========================================================================================
</pre>
: '''Example for ERR 31 / 32''':
<pre>
10 ON ERROR GOTO 1000
20 OPENOUT "myfile.asc"
30 WRITE #9,"test-data"
40 CLOSEOUT
50 END
1000 amsdoserr=(DERR AND &7F):REM mask off bit 7
1010 IF ERR<31 THEN END
1020 IF ERR=31 THEN PRINT "are you sure you've typed line 20 correctly?":END
1030 IF amsdoserr=20 THEN PRINT "disc is full, suggest you use a new data disc":END
1040 IF amsdoserr=&X01001000 THEN PRINT "put a disc in the drive, then press a key":WHILE INKEY$="":WEND:RESUME
1050 END
</pre>
==== <code><big>EXP (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates 'E' to the power given in the <numeric expression> (i), where 'E' is approximately 2,7182818-the number whose natural logarithm is 1.

: '''Associated keywords''': LOG

: '''Example''':
<pre>
PRINT EXP(6.876)
968.743625
</pre>
==== <code><big>FIX (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Unlike CINT, FIX merely removes the part of the numeric expression, to the right of the decimal point, and leaves an integer result, rounding towards zero.

: '''Associated keywords''': CINT, INT, ROUND

: '''Example''':
<pre>
PRINT FIX(9.99999)
9
</pre>
==== <code><big>FRE (<numeric expression>/<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Establishes how much FREe memory remains unused by BASIC. The form FRE("") forces a 'GARBAGE COLLECTION' before returning a value for available space.
: NOTE: BASIC uses only the first 64K of the memory.

: '''Associated keywords''': HIMEM, MEMORY

: '''Examples''':
<pre>
PRINT FRE(0) or PRINT FRE("hello")
PRINT FRE("")
</pre>
==== <code><big>HEX$ (<unsigned integer expression>, <field width>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Produces a $tring of HEXadecimal digits representing the value of the <unsigned integer expression>, using the number of hexadecimal digits instructed by the <field width> (in the range 0 to 16). If the number of digits instructed is too great, the resulting expression will be filled with leading zeros; if the number of digits instructed is too small, the resulting expression will NOT be shortened to the instructed number of digits, but will be produced in as many digits as are required.
: The <unsigned integer expression> to be converted into hexadecimal form must yield a value in the range -32768 to 65535.

: '''Accociated keywords''': BIN$, DEC$, STR$, UNT

: '''Example''':
<pre>
PRINT HEX$(255,4)
00FF
</pre>
==== <code><big>HIMEM</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the address of the Highest byte of Memory use by BASIC, (which may altered by e.g. the MEMROY command).
: Before resetting the highest byte of available memory using the MEMORY command, it is advisable to issue the 'command mm=HIMEM'. You will thereafter be able to return to the previous memory capacity by issuing the command: 'MEMORY mm'
: NOTE: BASIC uses only the first 64K of memory.

: Associated keywords: FRE, MEMORY, SYMBOL, SYMBOL AFTER.

: '''Example''':
...on a CPC464
<pre>
PRINT HIMEM
43903
</pre>
...on a CPC6128
<pre>
PRINT HIMEM
42619
</pre>
==== <code><big>INKEY (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': INterrogates the KEYboard to report which keys are being pressed. The keyboard is scanned every 0.02 (1/50) second.
: The function is useful for spotting whether a certain key is down or up, by detecting the returned value of -1 (which occurs regardless of [SHIFT] and [CONTROL] key status).
: The example below detects when [SHIFT] and V (key number 55) are pressed together, then ends the program. Refer the manual for the key numbers.

: '''Associated keywords''': CLEAR INPUT, INKEY$, JOY

: '''Example''':
<pre>
10 IF INKEY(55)<>32 THEN 10
20 PRINT "You've pressed [SHIFT] and V"
30 CLEAR INPUT
run
</pre>
: The state of [SHIFT] and [CONTROL] in conjunction with the key specified in the <integer expression> is identified as follows:
<pre>
==============================================================================
|Value returned |[SHIFT] |[CTRL] |Specified key |
==============================================================================
|-1 |ignored |ignored |up |
|0 |up |up |down |
|32 |down |up |down |
|128 |up |down |down |
|160 |down |down |down |
==============================================================================
</pre>
==== <code><big>INKEY$</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': INterrogates the KEYboard, returning the current $tring reflecting any key that is pressed. It provides operator interaction without hitting [ENTER] after every answer. If there is a key pressed, then the function responds. If no key is pressed, INKEY$ returns an empty string.
: In the example below, lines 40 and 70 tell the program to loop back to line 30 after interrogating the keyboard string.

: '''Associated keywords''': CLEAR INPUT, INKEY

: '''Example''':
<pre>
10 CLS
20 PRINT "Select Yes or No (Y/N)?"
30 a$=INKEY$
40 IF a$="" THEN 30
50 IF a$="y" OR a$="Y" THEN 80
60 IF a$="N" OR a$="n" THEN 90
70 GOTO 30
80 PRINT "You have selected YES": END
90 PRINT "You have selected NO":
run
</pre>
==== <code><big>INP (‹port number›)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the INPut value from the I/O address specified in the <port number>.

: '''Associated keywords''': OUT, WAIT

: Watch out http://cpcwiki.eu/index.php/I/O_Port_Summary

: '''Example''':
<pre>
PRINT INP(&FF00)
255
Ready
</pre>
==== <code><big>INSTR ([‹startposition›,]‹searched string›, ‹searched for string›)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Searches the first <searched string> expression to find the first occurance of the <searched for string expression<, and reports the position of its occurance within the <searched string>. If the <searched for string> does not occur within the <searched string>, then 0 is reported.
: The position at which to start searching the <searched string> is optionally specifiable using the <start position> parameter which must yield an integer number in the range 1 to 255.

: '''Associated keywords''': none

: '''1. Example''':
<pre>
a$="ABCD":PRINT INSTR(a$,"C")
3
Ready
</pre>
: '''2. Example''':
<pre>
a$="Hello":IF INSTR(a$,"i")<>0 THEN PRINT "no" else a$
no
Ready
</pre>
: '''3. Example''':
<pre>
10 CLS
20 alphabet$="ABCDEFGHIJKLMNOPQRSTUVWXYZ"
30 INPUT "Enter a letter";a$
40 b$=UPPER$(a$)
50 PRINT b$;" is number";
60 PRINT INSTR(alphabet$,b$);
70 PRINT "in the alphabet.":PRINT
80 GOTO 40
run
</pre>
==== <code><big>INT (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Rounds the number to the nearest smaller INTeger, removing any fractional part. Returns then same value as FIX for positive number, but returns one less than FIX for negative numbers which are not already integers.

: '''Associated keyword''': CINT, FIX, ROUND

: '''Example''':
<pre>
PRINT INT(3.99), INT(-3.99)
3 -4
</pre>
==== <code><big>JOY (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': The JOY function reads a bit significant result from the joystick in the <integer expression> (either 0 or 1).
<pre>
================================
|Bit | Value decimal |
================================
|0(up) | 1 |
|1(down) | 2 |
|2(left) | 4 |
|3(right) | 8 |
|4(fire 2) | 16 |
|5(fire 1) | 32 |
================================
</pre>
==== <code><big>LEFT$ (<string expression>, <required length>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the number of characters (in the range 0 to 255) specified in the <required length> parameter (<integer expression>), after extracting them from the LEFT of the <string expression>. If the <string expression> is shorter than the <required length>, the whole <string expression> is returned.

: '''Associated keywords''': MID$, RIGHT$

: '''1. Example''':
<pre>
A$="ABCDEFG":PRINT LEFT$(A$,3) - prints ABC
</pre>
: '''2. Example''':
<pre>
10 CLS
20 a$="AMSTRAD"
30 FOR n=1 to 7
40 PRINT LEFT$(a$,n)
50 NEXT
run
</pre>
==== <code><big>LEN (<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the total number of characters (i.e. the LENgth) of the <string expression>.

: '''Associated keywords''': none

: '''Example''':
<pre>
10 LINE INPUT "Enter a phrase";a$
20 PRINT "The phrase is";
30 PRINT LEN(a$);"characters long."
run
</pre>
==== <code><big>LOG (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the natural LOGarithm (base of ''e'') of <numeric expression> which mustbe greater than zero.

: '''Associated keywords''': EXP, LOG10

: '''Example''':
<pre>
PRINT LOG(9999)
9.21024037
</pre>
==== <code><big>LOG10 (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the logarithm to base 10 of <numeric expression> which must be greater than zero.

: '''Associated keywords''': EXP, LOG

: '''Example''':
<pre>
PRINT LOG10(9999)
3.99995657
</pre>
==== <code><big>LOWER$ (<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns a new string expression which is a copy of the specified <string expression> but in which all alphabetic characters in the range A to Z are converted to lower case. Useful for processing input where the answers may come in mixed upper/lower case.

: '''Associated keywords''': UPPER$

: '''1. Example''':
<pre>
A$="AMSTRAD":PRINT A$="AMSTRAD":PRINT LOWER$(A$)
Amstrad
</pre>
: '''2. Example''':
<pre>
10 a$="SEE HOW THE LETTERS CHANGE TO ... NUMBERS 1234 NOT..."
20 PRINT LOWER$(a$+"LOWER CASE")
see how the letters change to ... numbers 1234 not... LOWER CASE
</pre>
==== <code><big>MAX (<list of: numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the MAXimum value from the <list of: numeric expression>s.

: '''Associated keywords''': MIN

: '''Example''':
<pre>
10 n=66
20 PRINT MAX(1,n,3,6,4,3)
run
66
</pre>
==== <code><big>MIN (<list of: numeric expression>)</big></code> ====
''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the MINimum value from the <list of: numeric expression>s.
: '''Associated keywords''': MAX

: '''Example''':
<pre>
PRINT MIN (3,6,2.999.8,9,)
2.999
</pre>

==== <code><big>PEEK (<address expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the contents of the Z80 memory location specified in the <address expression> which should be in the range &0000 to &FFFF (0 to 65535). In all cases PEEK will return the value at the RAM address specified (not the ROM), and will be in the range &00 to &FF (0 to 255)

: '''Associated keywords''': POKE

: '''Example''':
<pre>
10 MODE 1: ZONE 7
20 WINDOW 1,40,1,2:WINDOW #1,1,40,3,25
30 PRINT "memory-address"
40 LOCATE 20,1:PRINT "memory-contents"
50 FOR n=1 to 65535
60 p=PEEK(n)
70 PRINT #1,n,"(&";HEX$(n);")";
80 PRINT #1,TAB(20);p,"(&";HEX$(p);")"
90 NEXT
run
</pre>
==== <code><big>PI</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': The value of the ratio between the circumference and the diameter of a circle.

: '''Associated keywords''': DEG, RAD

: '''Example''':
<pre>
PRINT PI
3.14159265
</pre>
==== <code><big>POS (#<stream expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current horizontal POSition of the text cursor relative to the left edge of the text window. The <stream expression> MUST be specified, and does NOT default to #0.
: POS(#8) reports the current horizontal carriage position for the printer, where 1 is the extreme left hand edge.
: POS(#9) reports the logical position in the disc file stream, i.e. the number of printing characters sent to the stream since the last carriage return.

: '''Associated keywords''': VPOS, WINDOW
: '''Example''':
<pre>
10 MODE 1: BORDER 0:LOCATE 8,2
20 PRINT "use cursor left/right keys"
30 WINDOW 1,40,12,12:CURSOR 1,1
40 FOR n=1 TO 19:PRINT CHR$(9);:NEXT
50 IF INKEY(1)<>-1 THEN PRINT CHR$(9);
60 IF INKEY(8)<>-1 THEN PRINT CHR$(8);
70 LOCATE #1,2,24
80 PRINT #1,"text cursor ";
90 PRINT #1,"horizontal position = ";
100 PRINT #1,POS(#0):GOTO 50
run
</pre>
==== <code><big>REMAIN (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns count REMAINing count from the delay timer specified in <integer expression> (= timer number in the range 0 to 3), and disable it. If the delay timer was not enabled zero will be returned.

: '''Associated keywords''': AFTER, DI, EI, EVERY

: For the reason that REMAIN is no normal command but a "function" it is necessary in case of a proper functionality to link the command.
: an '''example''' in combination with an interrupt delay timer 1:
<pre>
PRINT REMAIN(1)
</pre>
: or to stop several/all interrupts at the same time...
<pre>
A=REMAIN(0)=REMAIN(1)=REMAIN(2)=REMAIN(3)
</pre>
: Hint: Take care of interrupts due to parallel working (the same cycle time) or if they are stopped with the BREAK key. Interrupts which were disabled for a certain time will be stored in buffer (for a maximum of 128 entries) and made up their task afterwards in the priorisation as declared.
: further '''example''':
<pre>
10 AFTER 500,1 GOSUB 40
20 AFTER 100,2 GOSUB 50
30 PRINT "program running":GOTO 30
40 REM this GOUSB-Routine will not be called as it is disabled in line 80
50 PRINT:PRINT "Timer 1 will now be ";
60 PRINT "disabled by REMAIN."
70 PRINT "Time-units remaining were:";
80 PRINT REMAIN(1)
run
</pre>
==== <code><big>RIGHT$ (<string expression>, <integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the number of characters (in the range 0 to 255) specified in the <integer expression> (=required length) parameter, after extracting them from the RIGHT of the <string expression>. If the <string expression> is shorter than the <integer expression>, the whole <string expression> is returned.

: '''Associated keywords''': LEFT$, MID$

: '''Example''':
<pre>
10 MODE 1:a$="AMSTRAD computer"
20 FOR n=1 TO 16:LOCATE 41-n,n
30 PRINT RIGHT$(a$,n)
40 NEXT
</pre>
==== <code><big>RND [(<numeric expression>)]</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the next RaNDom number in sequence if the <numeric expression> has a positive value or is not specified.
: If the <numeric expression> yields a value of zero, RND returns a copy of the last random number generated.
: If the <numeric expression> yields a negative value, a new random number sequence is started, the first number of which is returned.

: '''Associated keywords''': RANDOMIZE

: '''1. Example''':
<pre>
PRINT RND(0)
0.536703827
Ready
PRINT RND(1)
0.271940658
Ready
PRINT RND(0)
0.271940658
Ready
</pre>
: '''2. Example''':
: Example for generating an integer random number between 1 and 1000
<pre>
10 A=INT((RND(1)*1000)+1)
20 PRINT A
30 GOTO 10
</pre>
: '''3. Example''':
: For generating a random number between a lower and higher border
<pre>
10 INPUT "Low border",low
20 INPUT "High border",high
30 A=INT(RND(1)*(high-low))+low
40 PRINT A
</pre>
: '''4. Example''':
<pre>
10 RANDOMIZE
20 FOR x=1 TO -1 STEP -1
30 PRINT "rnd parameter=";x
40 FOR n=1 TO 6
50 PRINT RND(x)
60 NEXT n,x
run
</pre>

==== <code><big>ROUND (<numeric expression>[,<integer expression>])</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Rounds <numeric expression> to a number of decimal places or to the power of ten specified by <integer expression>. If <integer expression> less than zero, the <numeric expression> is rounded to give an absolute integer with <integer expression> number of zeros before the decimal point.

: '''Associated keywords''': ABS, CINT, FIX, INT
: '''1. Example''':
<pre>
PRINT ROUND(1562.357,2),ROUND(1562.375,-2)
1562.36 1600
</pre>
: '''2. Example''':
<pre>
10 FOR n=4 TO -4 STEP -1
20 PRINT ROUND (1234.5678,n)
30 PRINT "with integer expression";n
40 NEXT
run
</pre>
==== <code><big>SGN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: FUNCTION: Determines the SiGN of the <numeric expression>. Returns -1 if <numeric expression> is less than 0, returns 0 if <numeric expression> = 0, and returns 1 if <numeric expression> is greater than zero.

: '''Associated keywords''': ABS

: '''Example''':
<pre>
10 FOR n=255 to -200 STEP -20
20 PRINT "SGN returns";
30 PRINT SGN(n);"for a value of";n
40 NEXT n
run
</pre>
==== <code><big>SIN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the Real value for the Sine of <numeric expression>, defaulting to the Radian (RAD) measure mode unless otherwise declared by a DEG command.

: '''Associated keywords''': ATN, COS, DEG, RAD, TAN

: '''Example''':
<pre>
10 CLS:DEG:ORIGIN 0,20
20 FOR n=0 to 720
30 y=SIN(n)
40 PLOT n*640/720,198*y:NEXT
50 GOTO 50
run
</pre>
==== <code><big>SPACE$(<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Creates a string of spaces of the given length, (in the range 0 to 255) specified in the <integer expression>.

: '''Associated keywords''': SPC, STRING$, TAB

: '''Example''':
<pre>
10 MODE 1
20 PRINT "Put 9 spaces between me";
30 PRINT SPACE$(9);
40 PRINT "and you!"
run
</pre>
==== <code><big>SQ (<channel>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the state of the Sound Queue for the specified <channel> which must be an integer expression, yielding one the values:
: 1: for channel A
: 2: for channel B
: 4: for channel C
: The SQ function returns a bit significant integer, comprising the following bit settings:
: Bit 0,1 and 2: the number of free entries in the queue
: Bit 3,4 and 5: the rendezvous state at the head of this queue
: Bit 6 : the head of the queue is held
: Bit 7 : the channel is currently active
: ... where Bit 0 is the least significant bit, and Bit 7 is the most significant bit.
: It can be seen, that if Bit 6 is set, Bit 7 cannot be set at the same time, and vice versa. Similarly if Bits 3, 4, or 5 are set, Bit 6 and 7 cannot be set.

: '''Associated keywords''': ON SQ GOSUB, SOUND

: '''Example''':
<pre>
10 SOUND 65,100,100
20 PRINT SQ(1)
run
67
</pre>
==== <code><big>SQR (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the SQuare Root of the specified <numeric expression>.

: '''Associated keywords''': none

: '''Example''':
<pre>
PRINT SQR(9)
3
</pre>
==== <code><big>STR$ (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Converts the <numeric expression> to a decimal STRing representation.
: Useful for converting a number to a string in case of string manipulation. E.g. after converting a figure to a string then the most left character holds the sign: a minus in case the figure is negative and a space in case the figure is positiv.

: '''Associated keywords''': BIN$, DEC$, HEX$, VAL

: '''1. Example''':
<pre>
10 FIGURE=-1599
20 FIGURE$=STR$(FIGURE)
30 PRINT FIGURE$
-1599
</pre>
: '''2. Example''':
<pre>
10 FIGURE=1769
20 FIGURE$=STR$(FIGURE)
30 PRINT FIGURE$
1769
</pre>
: '''NOTE''': (there's a blank on the left-hand of the number "1769")
: If you want to add e.g. zero before the figure in case of a high score with fix digit-number then you're able to add zero(s) in front of a string instead of a figure.

: '''3. Example''':
<pre>
10 a=&FF:REM 255 hex
20 b=&x1111:REM 15 binary
30 c$="***"
40 PRINT c$+STR$(a+b)+c$
run
*** 270***
</pre>

==== <code><big>STRING$ (<length>,<character specifier>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns a string expression consisting of the <character specifier> repeated the number of time (in the range 0 to 255) specified in the <length>.

: '''Associated keywords''': SPACE$

: '''1. Example''':
<pre>
PRINT STRING$(40,"*")
****************************************
</pre>
: '''2. Example''':
<pre>
PRINT STRING(40,42)
****************************************
</pre>
: '''NOTE''': the <character specifier> 42 refers to the ASCII value of the character '*' and is also equivalent to PRINT STRING$(40,CHR$(42))
==== <code><big>TAN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the TANgent of the <numeric expression>, which must be in the range -200,000 to +200,000.
: '''NOTE''': DEG and RAD can be used to force the result of the calculation to degrees or radians respectively.

: '''Associated keywords''': ATN, COS, DEG, RAD, SIN

: '''Example''':
<pre>
PRINT TAN(45)
1.61977519
</pre>

==== <code><big>TEST (<x co-ordinate>,<y co-ordinate>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Moves the graphics cursor to the absolute position specified by the <x> and <y co-ordinate>s, and reports the value of the ink at the new location.

: '''Associated keywords''': MOVE, MOVER, TESTR, XPOS, YPOS

: '''Example''':
<pre>
10 CLS
20 PRINT "Your are using pen number";
30 PRINT TEST(10,386)
40 PRINT "Try changing PENs and MODEs";
50 PRINT "....then RUN again."
run
</pre>
==== <code><big>TESTR (<x offset>,<y offset>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Moves the graphics cursor by the amount specified in the <x> and <y offset>s relative to its current position, and reports the value of the ink at the new location.

: '''Associated keywords''': MOVE, MOVER, TEST, XPOS, YPOS

: '''Example''':
<pre>
10 MODE 0:FOR x=1 TO 15:LOCATE 1,x
20 PEN x:PRINT STRING$(10,143);:NEXT
30 MOVE 200,400:PEN 1
40 FOR n=1 TO 23:LOCATE 12,n
50 PRINT "pen";TESTR(0,-16):NEXT
run
</pre>
==== <code><big>TIME</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the elapsed time since the computer was last switched-on or reset, (excluding periods when reading or writing to disc).
: Each second of real time is equal to the returned value = TIME/300.

: '''Associated keyword''': AFTER, EVERY, WEND, WHILE

: '''Example''':
<pre>
10 CLS:REM clock
20 INPUT "hour";hour
30 INPUT "minute";minute
40 INPUT "second";second
50 CLS:datum=INT(TIME/300)
60 WHILE hour<13
70 WHILE minute<60
80 WHILE tick<60
90 tick=(INT(TIME/300)-datum)+second
100 LOCATE 1,1
110 PRINT USING "## ";hour,minute,tick
120 WEND
130 tick=0:second=0:minute=minute+1
140 GOTO 50
150 WEND
160 minute=0:hour=hour+1
170 WEND
180 hour=1
190 GOTO 60
run
</pre>
==== <code><big>UNT (<address expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Return an integer in the range -32768 to +32767 which is the twos-complement equivalent of the unsigned value of the <address expression>.

: '''Associated keywords''': CINT, FIX, INT, ROUND

: '''Example''':
<pre>
PRINT UNT(&FF66)
-154
</pre>
==== <code><big>UPPER$(<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns a new string expression which is a copy of the specified <string expression> but in which all alphabetic characters in the range A to Z are converted to upper case. The function is useful for processing input which may come in mixed upper / lower case.

: '''Associated keywords''': LOWER$

: '''Example''':
<pre>
10 CLS: a$="my, how you've grown!"
20 PRINT UPPER$(a$)
run
</pre>
==== <code><big>VAL(<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the numeric VALue, (including any negative sign and decimal point) of the first character(s) in the specified <string expression>.
:If the first character is not a number, then 0 is returned. If the first character is a negative sign or decimal point followed by non-numeric characters, a 'Type mismatch' error (13) will be reported.

: '''Associated keywords''': STR$

: '''1. Example''':
<pre>
PRINT VAL("-12.34x"),VAL("A-12")
-12.34 0
</pre>
: '''Exception''': if <se> starts with "&" + character (and it's between "A" and "F") the whole character will be handled like a hexadezimal numeric character (...often used in DATA Loaders). The returning numeric value is a  signed integer (16-Bit Word).
: '''2. Example''':
<pre>
PRINT VAL("&A")
10

PRINT VAL("&7FFF")
32767

PRINT VAL("&8000")
-32768
</pre>
: '''3. Example''':
<pre>
10 CLS: PRINT "I know my times tables!"
20 PRINT:PRINT "Press a key (1 to 9)"
30 a$=INKEY$:IF a$="" THEN 30
40 n=VAL(a$):if n<1 or n>9 then 30
50 FOR x=1 to 12
60 PRINT n;"X";x;"=";n*x
70 NEXT:GOTO 20
run
</pre>
==== <code><big>VPOS (#<stream expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current vertical POSition of the text cursor relative to the top of the text window. The <stream expression> MUST be specified, and does NOT default to #0.

: '''Associated keywords''': POS, WINDOW

: '''Example''':
<pre>
10 MODE 1:BORDER 0:LOCATE 8,2
20 PRINT "use cursor up/down keys"
30 WINDOW 39,39,1,25:CURSOR 1,1
40 LOCATE 1,3
50 IF INKEY(0)<>-1 THEN PRINT CHR$(11);
60 IF INKEY(2)<>-1 THEN PRINT CHR$(10);
70 LOCATE #1,3,24
80 PRINT #1,"text cursor ";
90 PRINT #1,"vertical position =";
100 PRINT #1,VPOS(#0):GOTO 50
run
</pre>
==== <code><big>XPOS</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current horizontal (X)POSition of the graphics cursor.

: '''Associated keywords''': MOVE, MOVER, ORIGIN, YPOS

: '''Example''':
<pre>
10 MODE 1:DRAW 320,200
20 PRINT "graphics cursor X position = ";
30 PRINT XPOS
</pre>
==== <code><big>YPOS</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current vertical (Y)POSition of the graphic cursor.

: '''Associated keywords''': MOVE, MOVER, ORIGIN, XPOS

: '''Example''':
<pre>
10 MODE 1:DRAW 320,200
20 PRINT "graphics cursor Y position = ";
30 PRINT YPOS
</pre>

== Other Basic Dialects available for the CPC ==

*[[BBC Basic]]
*[[C BASIC Compiler|CBASIC]]
*[[BASIC-E]]

== Technical Information ==

* [[Technical_information_about_Locomotive_BASIC]]

== Web links ==

* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]
* [http://rosettacode.org/wiki/Category:Locomotive_Basic Code examples at Rosetta Code]

* [http://cpctech.cpc-live.com/docs/basic.asm Disassembly of Locomotive BASIC v1.1]

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Locomotive BASIC

2025-10-02T13:03:28Z

Arnoldemu: /* OPENOUT ‹filename› */

For other BASIC language versions see the [[:Category:BASIC]]

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

It was availlable directly from in-built ROMs on [[CPC old generation]] and on the [[Plus System Cartridge]] for the [[Plus]] range. [https://benchmarko.github.io/CPCBasic/ Online Interpreter]

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

If you are interested in more information about the different versions of the CPC's BASIC and the technical details, you can have a look at the article "[[Technical information about Locomotive BASIC]]".

Another helpful and further resource of information about BASIC and a similar comprehension to this is Grimware's Website about the CPC http://www.grimware.org/doku.php/documentations/software/locomotive.basic/start

== 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 and Spanish 472 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 472 (British), 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.

== Variables ==
Many contemporary BASIC interpreters only supported the first few characters of a variable name as a discriminator. For example <code>WATER$</code> and <code>WALDO$</code> would refer to the same variable on a Commodore 64 or Apple II. But Locomotive BASIC allowed variable names up to 40 characters in length, so <code>THEQUICKBROWNFOXJUMPEDOVERTHELAZYDOGFAST$</code> and <code>THEQUICKBROWNFOXJUMPEDOVERTHELAZYDOGFATS$</code> could be use as separate variables.

=== Real (Floating Point) Numbers ===

This is the default type for a Locomotive BASIC variables, but can be clarified using <code>!</code> after the variable name, e.g., <code>real!=500.0</code>.
You can force all variables starting with specific letters to be this type by using the <code>DEFREAL</code> keyword.
In many cases you don't want to use these, as they are slower than using the integer type, and use more memory (5 bytes, as opposed to 2).

=== Signed 16-bit Integers ===

Defined using <code>%</code> after the variable name, e.g., <code>integer%=500</code>.
You can force all variables starting with specific letters to be this type by using the <code>DEFINT</code> keyword.
These can store values between -32,768 and 32,767.
To assign a 16-bit value to a signed integer directly, you should give the number in a hexadecimal format, e.g., <code>uint=&c0000</code>.

=== Strings ===

These are defined by using <code>$</code> after the variable name, e.g., <code>str$="Hello"</code>.
You can force all variables starting with specific letters to be this type by using the <code>DEFSTR</code> keyword.
A String can be up to 255 characters long.

== Type Conversions ==

The BASIC functions <code>ROUND</code>, <code>INT</code>, <code>CINT</code> and <code>FIX</code> can be used to convert real numbers into integers taking some care about rounding. The difference is in rounding mode - <code>ROUND</code> rounds to nearest, <code>FIX</code> rounds to zero, <code>INT</code> always rounds down, and <code>CINT</code>rounds up. e.g., <code>value%=INT(3.14)</code>. Note that if you don't specify the % you will actually get a real number still.

To convert an integer to a real number, you can use the <code>UNT</code> function which will take the value supplied and return the two's complement number. e.g., <code>real=UNT(&ABCD)</code>.

<pre>
w=UNT(50000)
Ready
PRINT w
-15536
Ready
█
</pre>

If you want an integer result from division, use the <code>\</code> integer division operator. e.g., <code>int=value\divisor</code>. This is as opposed to the standard <code>/</code> division operator, that can create a real number.

== Command list ==

=== Commands and operators ===

==== <code>AFTER ‹time delay›[,‹timer number›] GOSUB ‹line number› </code>====
: Waits for ‹time delay›/50 seconds and then jumps NON-RECURRING to the subroutine at ‹line number› (see also <code>"EVERY i[,t] GOSUB line"</code>).

==== <code>AUTO [‹line number›][,‹increment›] </code>====
: Automatically generates line numbers starting at ‹line number› with ‹increment› after each entered line number. Use '''[ESC]''' to leave AUTO mode. Default values for ‹line number› and ‹increment› are 10.

: Example:
<pre>AUTO 100,5 :REM generates line numbers 100, 105, 110...</pre>

==== <code>BORDER ‹colour›[,‹colour›] </code>====
: Changes the colour of the border. If the second argument is supplied the border flashes between the two colours.

==== <code>CALL ‹address expression›[,‹list of: parameter›] </code>====
: Allows a machine code routine to be called by BASIC. Variables, string values and constants can be passed to the routine. Values of any supported type can be passed back by supplying a variable with <code>@</code> in front of it. This passes the address of the variable to the routine although it doesn't implicitly know the data type.
: Example:
<pre>CALL 0 :REM resets the computer completely</pre>

==== <code>CAT</code> ====
: Displays the names of the files on the tape or disc. Tape files are displayed in the order they are encountered. Disc files are sorted alphabetically by ACSII code. Only files matching the current user are displayed. Files marked as system are not displayed.
: Examples:
<pre>CAT :REM lists all disc files in alpha-numeric (ASCII) order</pre>

<pre>|TAPE :CAT :REM lists names of all tape files in their storage order</pre>

==== <code>CHAIN ‹file name›[,‹line number expression›] </code>====

:Enables the specified program to be loaded and RUN automatically. If the optional parameter ‹line number expression› is specified, the program execution will commence from that line.

==== <code>CHAIN MERGE ‹file name›[,‹line number expression› | [,[‹line number expression›],DELETE ‹line number range›]] </code>====

:Loads the specified program from tape or disc, merges it into the program in memory, and starts execution of the merged program. The parameter <code>DELETE</code> ‹line number range› is used to delete part of the original program before running it, if required.

==== <code>CLEAR</code> ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.
: The command clear inside a subroutine (<code>GOSUB</code>... <code>RETURN</code>) will also clear the "stack pointer" address of the gosub heap. That means that a RETURN won't work and a GOTO has to be used instead.

==== <code>CLG [‹masked ink›] </code>====
: Clears the graphics screen to colour specified by <code>‹masked ink›</code>. If parameter <code>‹masked ink›</code> is not specified then the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== <code>CLOSEIN</code> ====
: Closes any input file (tape or disc).

==== <code>CLOSEOUT</code> ====
: Closes any output file (tape or disc).

==== <code>CLS [#‹stream expression›]</code>====
: Clears the window specified by ‹stream expression›. If ‹stream expression› is omitted it defaults to #0 (usually the whole screen). The text cursor of the stream is moved to the upper left corner.

==== <code>CONT</code> ====
: CONTinues program execution interrupted either by [ESC] [ESC] or as a result of STOP within a program. A program cannot be continued after being modified.

==== <code>CURSOR ‹expression› </code>====
: <code>‹expression›</code> must be either 0 or 1.

==== <code>DATA x1[,x2,x3...]</code> ====
: 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>

==== <code>DEF</code> ====
: DEF means "define" and comes along with defining a function in case of DEF FN or defining variables in case of DEFREAL, DEFINT or DEFSTR.
: DEF FN must come before using the statement FN.
: DEF with a variable declaration should come before using a variable.
: (see also FN)

==== <code>DEFINT ‹letter range›</code> ====
:Forces all variables(s) starting with the specified letter(s) to be integer variables. Singular letters could be defined or a range by a minus symbol between two letters.

:Examples:
<pre>
20 DEFINT a-z:' sets all variables starting with an A until Z as integer.
</pre>
or
<pre>
10 DEFINT F,S ..... (or 10 DEFINT A-Z)
20 FIRST=111.11:SECOND=22.2
30 PRINT FIRST,SECOND:' prints out 111 22
</pre>

==== <code>DEFREAL ‹letter range›</code> ====
: Sets the default for variable(s) with the specified first letter(s) to a floating point figure.

==== <code>DEFSTR ‹letter range›</code> ====

: Sets the default for variable(s) with the specified first letter(s) to string(s) variables.

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

==== <code>DELETE [first line][-[last line]]</code> ====
: Deletes the current program completely (without arguments) or only the given line or line range. Even
: <code>DELETE -</code>
: is legal, it has the same effect as
: <code>DELETE</code>
: The lines specified do not have to exist, all lines matching the range will be deleted and having no matches does not cause an error.

==== <code>DI</code> ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.
: This means that DI (if it's activated in a subroutine) is useful helping a low-priority-interrupt not to be stopped by a higher-priority-interrupt. RETURN then re-enable the interrupt without EI.

==== <code>DIM a[%|!|$](d1[,d2[,...]])</code> ====

: Creates array <code>a</code> with single or multiple dimensions. You may optionally specify integer (<code>%</code>), real (<code>!</code>) or string (<code>$</code>) type otherwise it defaults to the current type set for the first letter of the array name. <code>d1</code> is size of first dimension-1, <code>d2</code> is size of second dimension-1 and so on. <code>DIM x(10)</code> will create an array with 11 elements, <code>x(0)</code> is the first element, <code>x(10)</code> is the eleventh and last. You can specify as many dimensions as will fit on one 255 character line, which is a maximum of 125. Trying to create an array that already exists will generate an <code>Array already dimensioned</code> error. If an array is not specified by <code>DIM</code> before being accessed, each dimension value defaults to 10. The maximum dimensions that can be created this way is three.

==== <code>DRAW x,y[,[i1][,i2]]</code> ====

: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the drawing style.

: 4 drawing styles:
<pre>
i2 = 0 normal colour
i2 = 1 XOR colour
i2 = 2 AND colour
i2 = 3 OR colour
</pre>
: Example:
<pre>
CLG 2
DRAW 500,400,0 :REM draws a line from 0,0 to 500,400
</pre>

<code>DRAWR xr,yr[,[i1][,i2]]</code> ====

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

<pre>
Move 200,200
DRAWR 100,100,0 - draws a line from 200,200 to 300,300
</pre>

==== <code>EDIT ‹line›</code> ====
: Display 1 program line for editing.

The following keys can be used in editing mode, or during typing in BASIC:

CTRL+TAB - toggle overwrite/insert mode
CTRL+CURSOR LEFT or CTRL+CURSOR UP - go to start of line
CTRL+CURSOR RIGHT or CTRL+CURSOR DOWN - go to end of line
CURSOR LEFT - move left one character
CURSOR RIGHT - move right one character
ESC - quit editing and do not accept changes
ENTER/RETURN - quit editing and accept changes
SHIFT + CURSOR UP/DOWN/LEFT/RIGHT - enter copy mode. You can move the cursor to where you want to copy from. Hold SHIFT and cursors to move copy cursor.
COPY - copy character covered by copy cursor.
DEL - delete character and go back a char
CLR - delete character under cursor
CTRL + CAPS LOCK - toggle shift lock.

==== <code>EI</code> ====
: Enable interrupts which have been disabled by DI

==== <code>END</code> ====
: Indicates end of program

==== <code>ENT ‹tone envelope number›[,‹tone env. section›][,‹tone env. section›][,‹tone env. section›][,‹tone env. section›][,‹tone env. section›]</code> ====
:The ENT command define the TONE shape of a sound which means manipulating the frequency in a certain range.
:The command could looks like:
<pre>
ENT NUMBER,STEPS?,VERTICAL?,HORIZONTAL?
</pre>
:It is possible to define 15 different envelope shapes. So '''NUMBER''' could be 1-15.

:Each '''?''' stands for up to five sections (1-5), where each STEP<>VERTICAL<>HORIZONTAL with the same '''?''' are belong together.

:'''STEP:''' means how many steps in each section (0-127) > one step is 1/100 of a second!
:'''VERTICAL''': means how big is the step size from bottom to top (-128 to 127)
:'''HORIZONTAL''': means how big is the step size from left to right (0-255)

==== <code>ENV ‹volume envelope number›[,‹volume env. section›][,‹volume env. section›][,‹volume env. section›][,‹volume env. section›][,‹volume env. section›]</code> ====
:The ENV command define the VOLUME shape of a sound which means manipulating the loudness in a certain range.
:The command could looks like:
<pre>
ENV NUMBER,STEPS?,VERTICAL?,HORIZONTAL?
</pre>
:It is possible to define 15 different envelope shapes. So '''NUMBER''' could be 1-15.

:Each '''?''' stands for up to five sections (1-5), where each STEP<>VERTICAL<>HORIZONTAL with the same '''?''' are belong together.

:'''STEP:''' means how many steps in each section (0-127) > one step is 1/100 of a second!
:'''VERTICAL''': means how big is the step size from bottom to top (-128 to 127)
:'''HORIZONTAL''': means how big is the step size from left to right (0-255)

==== <code>ERASE v1[% | ! | $][,v2[% | ! | $][,...]]</code> ====
: Erases the specified array(s) and frees the memory used. Must specify existing array(s) or an <code>Improper argument</code> error will be generated.

==== <code>ERL</code> ====

: Returns the line number of the last error encountered.

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

==== <code>EVERY i[,t] GOSUB ln</code> ====

: BASIC branches to the subroutine at line ln EVERY (reccuring) i/50 seconds. (see also "AFTER i[,t] GOSUB line")

: There are 4 delay timers from 0 to 3 which can be specified with ‹timer number›. If omitted ‹timer number› defaults to 0.
: In the case of parallel task has 3 the highest and 0 the lowest priority.
: With DI or EI you can disable or enable the timing interrupt. With REMAIN <timer number> you can also disable an AFTER or EVERY construct and stores the "remaining" time (> REMAIN)
: Interrupts run as long as the main loop / program runs, even the main programm is paused > press ESC only '''once''' not twice for a break.
: It is important to know or realise that low-priority-interrupts which occurs simultanously to higher-priority-interrupts are not lost. Their task remains or handled again after finishing the higher-prio interrupt.

<pre>
10 REM > interrupts
20 EVERY 50,0 GOSUB 100: REM > lowest priority
30 EVERY 100,1 GOSUB 200
40 EVERY 200,2 GOSUB 300:
50 AFTER 1000,3 GOSUB 400: REM > highest priority
60 WHILE flag=0
70 a=a+1:print a
80 WEND
90 END
100 REM #0
110 PEN 2:PRINT "timer 0":PEN 1
120 RETURN
200 REM #1
210 PEN 2:PRINT "timer 1":PEN 1
220 RETURN
300 REM #2
310 PEN 2:PRINT "timer 2":PEN 1
320 RETURN
400 REM #3
410 flag=1:PEN 2:PRINT "no more interrupts..."
420 RETURN
</pre>

: Hint: Timing with interrupts is important, especially if more than one interrupts run. If the interval of a subroutine driven by an interrupt is too long than the processor can never get back to deal the main program again. Work out timing by measuring the subroutine or by trial and error.
: There are system internal interrupts (highest level) which cannot be influenced by BASIC interrupts (e.g. keyboard scan > BREAK key.)
: The next level of sytem internal interrupts CAN be influenced by BASIC interrupts. For example the sound queue which will be created by "ON SQ <chanel> GOSUB <line>". Those sound interrupts have an independent time tricker but their priority is parallel to the second priority times of BASICs interrupts. Therefore interrupts with timer 3 could "interrupt" them.

==== <code>FILL i</code> ====
: 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.

==== <code>FN</code> ====
:BASIC allows the program to define and use simple value returning functions. DEF FuNction is the definition part of this mechanism and creates program-specific function which works within the
:program in the same way as a function such a COS operates as a built-in function of BASIC. It may be invoked throughout the program. Variable types must be consistent and the DEF FN
:command should be written in part of the program outside the execution loop.

:Syntax : <code>DEF FN<name>[(<formal parameters>)]=<general expression></code>

:Example: ''"with the definition of..."''
<pre>
10 gn=9.80665
20 DEF FNgrv=s0+v0*t+0.5*gn*t^2
30 s0=0:v0=0:t=5
40 PRINT "...after";t;"seconds your dropped stone falls";FNgrv;"metres"
</pre>
:''"the results are..."''
<pre>
:...after 5 seconds your dropped stone falls 122.58315 metres
</pre>

==== <code>FOR TO STEP NEXT</code> ====
: Creating a counting loop (control strucutre) with a starting condition. Inside the counting loop one or more commands will be executed.
: The loop consists of of following specifications:

: 1. FOR
: 2. ''a control variable''
: 3. =
: 4. ''starting value''
: 5. TO
: 6. ''target value''
: 7. STEP [optional]
: 8. ''increment / step size''
: ''... instructions between''
: 9. NEXT
: 10. ''control variable'' [optional]

: You have to use the command STEP if you wish to count backwards. It's good to name the ''control variable'' after NEXT for readability and better program style.
: After each loop the computer checks internaly if the ''target value'' has been reached (like an IF ... THEN ... ELSE instruction). If the target value is reached NEXT closes the loop and calculates another step, so the ''control variable'' will be changed last time.
: The default STEP value - if not specified - is one (1).

: Example:
<pre>
10 FOR I=1 TO 10
20 PRINT I;
30 NEXT I
40 PRINT I
RUN
1 2 3 4 5 6 7 8 9 10 11
READY
</pre>

==== <code>FRAME</code> ====
: 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.

==== <code>GOSUB i</code> ====

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

==== <code>GOTO i</code> ====
: 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>
: GOTO is the simplest form of a jump or creating a loop '''without''' condition controll.
: ''Example: (unconditional and endless loop)''
<pre>
10 PRINT "#";
20 GOTO 10
</pre>
: Combine the GOTO command with an IF...THEN...ELSE instruction for creating a condition-controlled loop with the '''test at the end'''. Helpful because the Locomotive Basic has no practical DO...WHILE... loop.
: ''Example: (condition at the end)''
<pre>
10 I=1
20 PRINT I
30 I=I+1
40 IF I<25 THEN GOTO 20
50 END
</pre>

==== <code>GRAPHICS</code> ====
: ...works only in combination with the command <code>PEN</code> or <code>PAPER</code> to set the plotting/drawing pen or background colour.
: If the <code>TAG</code> command is used to set text at the graphics cursor <code>GRAPHICS PEN</code> or <code>GRAPHICS PAPER</code> instead of the regular <code>PEN</code> or <code>PAPER</code>is necessary to colour the text.

==== <code>IF THEN ELSE</code> ====
: Asks for a choice with the '''IF...THEN...ELSE''' statement.
: '''IF''' compares the entry condition in a logical way
: '''THEN''' contains instruction if the comparison is true
: '''ELSE''' contains instruction if it's false.
: '''Example:'''
<pre>
10 INPUT "guess a figure:",f
20 IF f=10 THEN PRINT "right": END: ELSE GOTO 10
</pre>
: In case of nested choices there's a possibility to that with an IF...THEN instruction but not very recommended:
<pre>
10 INPUT "guess a figure:",f
20 IF f=10 THEN PRINT "right": END: ELSE IF f<10 THEN PRINT "too small" ELSE PRINT "too big"
30 GOTO 10
</pre>
:Other nested structures like IF...THEN...'''ELSE...ELSE''' won't work first because the Locomotive Basic only looks after the first ELSE instruction found and can't execute more single commands as a block for a certain condition in comparision to e.g. "PASCAL" > begin...end-block, "C" > {...}-block.

==== <code>INK ‹pen›,‹colour›,[‹second colour›]</code> ====
: Used to set the colour palette for each of the 16 available inks.
: pen specifies the pen slot to use.
: colour specifies the system colour to use (0..27.)
: if the second colour is provided, Locomotive Basic will blink between the colour and second colour.
: In MODE 0, all 16 pens are available. In MODE 1, only 4 pens are available (0..3). In MODE 2, only 2 pens are available (0..1.)
: By default, pen 0 is the background colour and pen 1 is the foreground/text colour.
: Examples:
<pre>
10 MODE 2
20 INK 0,3: REM Set background colour to red
30 INK 1,26: REM Set foreground/text colour to white
</pre>

==== <code>INPUT[#‹stream expression›][,]</code> ====
: [...]

==== <code>KEY</code> ====
: [...]

==== <code>LET</code> ====
: Used to define variables. You don't need to use the ''LET'' command because it is just a command which was added for compatibility reasons.
: ''Example:''
<pre>
10 LET a$ = "hello world"
20 PRINT a$
</pre>

==== <code>LINE INPUT [#‹stream expression›][,]‹variable›[,‹variable›] </code>====
: [...]

==== <code>LIST [‹line number›][-[‹line number›]], [#‹stream expression›]</code>====
: A command for listing the Basic program code.
: Possibility for manipulating display is using line numbers with a minus symbol.
: Example:
<pre>
LIST 100-
</pre>
: List every line after line number 100.
<pre>
LIST -100
</pre>
: List every line until line number 100 has reached.
<pre>
LIST 100-200
</pre>
: List every line between line number 100 and 200 included

: With the help of separate window definitions it is possible to print out long listings, better differentiate parts / slices of it into different window predefined
: Example:
<pre>
LIST 1000-1100,#1
LIST 3000-3100,#2
</pre>
: ...prints out two parts of one program out into two windows (if they are defined well)

==== <code>LOAD ‹file name›[,‹address›] </code>====

With this directive you may load any file in memory

Basic files (extension .BAS) are loaded in Basic memory, you cannot choose loading address

Binary files are loaded to the default address location stored in the AMSDOS header but you may force loading address (&C000 for a screen)

TAPE convention:

When loading tape files, the basic display a message every block which may cause trouble. Message output may be disabled by using prefix "!" before the filename.

It's also possible to load the next file disregarding his name using only "!" => <code>LOAD "!"</code>

==== <code>LOCATE[#‹stream expression›][,] x,y</code> ====

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

==== <code>MASK [i1][,i2]</code> ====

: Sets bits in each adjacent group of 8 pixel on (1) or off (0) according to binary value of i1 (0-255). i2 determines whether the first point of the line is to plotted (1) or not (0).

:Example:

<pre>
10 CLG 2:MASK 1:MOVE 0,0:DRAW 500,400
20 MASK 15:MOVE 0,0:DRAW 500,400
</pre>

==== <code>MEMORY ‹memory address›</code> ====

: Allocates the amount of memory to be used by BASIC by setting the [[Locomotive_BASIC#HIMEM|address of the highest byte]] it may use.

==== <code>MERGE</code> ====
: [...]

==== <code>MID$ (‹string›,‹start position›[,‹length of substring›])</code> ====
: With the MID$ command there are two applications possible:

: 1. MID$ creates a new substring out of the give ‹string› and starts at the defined position ‹start position› and print the number of given characters by ‹length of substring›.
: If no length is defined every character from ‹start position› will be printed out.
: If a higher value of ‹start position› or ‹length of substring› than the real length of the initial string is defined a blank string will be printed.
: The range of ‹start position› or ‹length of substring› is from 0 up to 255 characters.

: 2. With MID$ you're able to manipulates given strings by inserting a new string.
: Take care of the two different applications and using in BASIC.

: Example for the 1. application:
<pre>
10 a$="Hello"
20 PRINT MID$(a$,2,2)
run
el
Ready
</pre>
:
: Example for the 2. application
<pre>
10 a$="Hello"
20 MID$(a$,2,3)="ipp"
30 PRINT a$
run
Hippo
Ready
</pre>

==== <code>MODE</code> ====
: Changes the screen mode: MODE 0 is 160×200 in 16 colours, MODE 1 is 320×200 4 colours, MODE 2 is 640×200 2 colours and MODE 3 is 160×200 in 4 colours.

==== <code>MOVE x,y [[,i1][,i2]]</code> ====

: Moves the graphic cursor to position x,y. The parameter i1 may be used to change the pen (drawing) colour. The parameter i2 specifies the logical colour, as in DRAW.

: 4 drawing styles:
<pre>
i2 = 0 normal colour
i2 = 1 XOR colour
i2 = 2 AND colour
i2 = 3 OR colour
</pre>

==== <code>MOVER xr,yr[,[i1][,i2]]</code> ====
: moves the graphic cursor (relative) from current position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as in MOVE.

==== <code>NEW</code> ====
: Clears BASIC RAM which means program and variables. Keeps symbol defintion (if defined) and screen mode without clearing.

==== <code>ON BREAK CONT</code> ====

: Prevents the interruption of program execution by the ESC key.

==== <code>ON BREAK GOSUB ln</code> ====

: Passes control to subroutine at line ln when ESC ESC pressed.

==== <code>ON BREAK STOP</code> ====

: Restores normal function of ESC key during program execution.

==== <code>ON ERROR GOTO ln</code> ====

: Passes the control to line ln if an error is detected in the program.

: ON ERROR GOTO 0, Turns of the error trap, and restores normal error processing.

==== <code>ON variable GOTO ln x1, x2, x3, x4, ...</code> ====

: In case of passing more choices '''ON variable GOTO ln x1, x2, x3, x4, ...''' points to a table with the jumping target.
: '''Example:'''
<pre>
10 PRINT "1. LOAD - 2. SAVE - 3. EXIT"
20 INPUT choice
30 ON choice GOTO 1000, 2000, 3000
40 CLS: GOTO 10
1000 PRINT "1. LOAD":END
2000 PRINT "2. SAVE":END
3000 END
</pre>
:In case that the variable ''choice'' won't fullfil the condition (in a range between line 0 and 65535) the next instruction will be executed (here: Line 40). If "choice" is smaller than 0 an error will occur.

==== <code>ON variable GOSUB ln x1, x2, x3, x4, ...</code> ====

: In case of passing more choices targeting to SUBROUTINES '''ON variable GOSUB ln x1, x2, x3, x4, ...''' points to a jumping table.
: '''Example:'''
<pre>
10 PRINT "1. LOAD - 2. SAVE - 3. EXIT"
20 INPUT choice
30 ON choice GOSUB 1000, 2000, 3000
40 CLS: GOTO 10
1000 PRINT "1. LOAD":RETURN
2000 PRINT "2. SAVE":RETURN
3000 END
</pre>
:In case that the variable ''choice'' won't fullfil the condition (in a range between line 0 and 65535) the next instruction will be executed (here: Line 40). If "choice" is smaller than 0 an error will occur.

==== <code>ON SQ(x) GOSUB ln x1, x2, x3, x4, ...</code> ====
:ON SQ(x) can trigger an interrupt when e.g. a space or free channel in queue.
:Using that command is a one way interrupt trigger and shouldn't be mixed with <code>EVERY</code> or <code>AFTER</code> commands.

:See also the <code>SQ(x)</code> command for more details.

==== <code>OPENIN ‹filename›</code> ====
: Opens the specified data file for reading. It has to be an ASCII file. ( The command <code>CLOSEIN</code> closes reading data file. )
: Read from the file using <code>INPUT #9</code>

==== <code>OPENOUT ‹filename›</code> ====
: Opens the specified data file for writing. It writes an ASCII file. (The command <code>CLOSEOUT</code> finishes writing to the file and closes it cleanly.)
: Write to the file with PRINT#9.
: No file is likely to be written until enough data is written (e.g. 2KB) or the file has at least 1 byte written and CLOSEOUT is used.
: The following code pattern can be used to set MEMORY and lower HIMEM lower than would normally be allowed. This is often seen in disc loaders. This doesn't cause any file to be written:

OPENOUT"<filename>
MEMORY address
CLOSEOUT

==== <code>ORIGIN x,y[,l,r,t,b]</code> ====
: The command defines the origin ('world reference point') for the graphics coordinate system. Normally the reference origin is in the left, bottom corner of the default screen and has 0,0. So the most left coordinate value could be by default 639 and the most top value 399. Independent from the actual modus (2, 1 or 0) the range for the x coordinate are always 640 points and for the y coordinate 400 points. In theory you are able to address 256,000 pixel but only 128,000 are visible due to the maximal resolution of the hardware.
: <code>x,y</code> are the the new coordinates for the 'world reference '.
: <code>l,r,t,b</code> are optional and set the borders for the new graphical window (works in the same way like the <code>WINDOW</code> command for a text window). l,r,t,b means left, right, tob and bottom coordinates.
: If a new graphical window (borders) is defined every point or drawn line won't be plotted (clipped internally).

: Example (the line drawn will be cutted):
<pre>
ORIGIN 320,200,250,450,100,300
DRAW 0,200
</pre>

==== <code>OUT ‹address›,‹value›</code> ====

: Outputs a value (range of 0-255) to a specific I/O address.
: Watch out http://cpcwiki.eu/index.php/I/O_Port_Summary

==== <code>PAPER[#‹stream expression›][,]</code> ====
: [...]

==== <code>PEN[#‹stream expression›][,]</code> ====
: [...]

==== <code>PLOT</code> ====
: [...]

==== <code>PLOTR</code> ====
: [...]

==== <code>POKE add</code> ====

: Alters contents of memory location add to value i (0-255)

==== <code>PRINT[#‹stream expression›][,]</code> ====
: [...]

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

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

==== <code>RANDOMIZE [seed]</code> ====

: Resets the pseudo-random generator to the given seed (starting value of the 'random' series). 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>

: <code>RANDOMIZE TIME</code> isn't still a 'real' random number but to hit the same series again is pretty hard due to the time elapsed.
: The algorithm used for randomizing is the following: the generator starts with the seed, adds 1, multiplies by 75 (fiddle factor), divides by 65537 and then uses the remainder -1.

==== <code>READ variable</code> ====
: 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>

==== <code>RELEASE chanel</code> ====
: Releases a sound which was hold on (by a SOUND command) before. It uses the same bit matrix like the SOUND command for the first parameter
# (&x00000001) releases chanel A
# (&x00000010) releases chanel B
# (&x00000011) releases chanel A and B
# (&x00000100) releases chanel C
# (&x00000101) releases chanel A and C
# (&x00000110) releases chanel B and C
# (&x00000111) releases chanel A, B and C

:Example:
<pre>
10 SOUND 65,1000,100
20 PRINT"PRESS R TO LET IT SOUND"
30 IF INKEY(50)=-1 THEN 30
40 RELEASE 1
</pre>

==== <code>REM [any text]</code> ====
: Introduces a comment.

==== <code>RENUM [‹newLine›][,‹oldLine› | ,[‹oldLine›],‹step›] </code>====
: Renumbers the lines of the current program.

: By default, the whole program is renumbered starting at line 10 with multiples of ten. Any parameter that is left out defaults to 10. It is important to note that ''jumps'' (<code>GOTO</code>, <code>GOSUB</code> 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 <code>RENUM 100,20,5</code>

<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== <code>RESTORE [line]</code> ====

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

==== <code>RESUME [line] or NEXT</code> ====
: Command causes the program to resume after an error code and if it is interrupted by an '''ON ERROR GOTO''' jump
: So it can either resume
*(if there's no line number stated) at the same line after error code (and if there are more statements in one line)
or
* at the line number stated (optional)
or
* with the NEXT parameter (optional) ... at the line followed by the error line

==== <code>RETURN</code> ====

: Terminates a subroutine and returns control to the line following the GOSUB call (see GOSUB)

==== <code>RUN [line] or "filename"</code> ====
:Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

:If a string is used after RUN command a programm will be loaded and executed from storage medium (e.g. Tape, Disc). With that command protected BASIC programs can be executed.

:Exampel:
<pre>
RUN"disc"
</pre>

==== <code>SAVE "filename" [,filetype][,paramter1,parameter2,parameter3]</code> ====
: Command saves the current BASIC program / content from RAM onto a storage medium (e.g. Tape, Disc)

: Filetype could be:
* ''',A''' for a ASCII file
* ''',B''' for a binary file (store RAM content as it is)
* ''',P''' for a regular, ''protected'' BASIC file
: without that parameter the content will be stored as a regular BASIC file

:The three parameters after filetype could be used in combination with the binary filetype (,B).
* '''''parameter1''''' defines the starting address of memory range
* '''''parameter2''''' defines the length (range of memory)
* '''''parameter3''''' defines the entry point (optional)

==== <code>SOUND</code> ====
: the SOUND command has following shape:
: SOUND '''C'''hannel,'''P'''eriod,'''D'''uration,'''V'''olume,Volume-'''Env'''elope,'''T'''one-'''En'''velope,'''N'''oise

:'''C:''' Selecting channel is done bitwise (combinations are possible of course):

<pre>
(Bit 0) &x00000001 = 1 = channel A (middle)
(Bit 1) &x00000010 = 2 = channel B (left)
(Bit 2) &x00000100 = 4 = channel C (right)
</pre>
:more function about channel are
<pre>
(Bit 3) &x00001000 = 8 = Rendezvous with channel A
(Bit 4) &x00010000 = 16 = Rendesvous with channel B
(Bit 5) &x00100000 = 32 = Rendesvous with channel C
(Bit 6) &x01000000 = 64 = Hold
(Bit 7) &x10000000 = 128 = Flush
</pre>
:'''P:''' the period number can be a figure between 0 and 4095 (2^12-1... 12 means that we have 12 tones (inclusive half-tones) in nine octaves on the CPC in sum and their distance between is the twelves square root of two), where 8 octaves are available. E.g. Octave 0 starts on middle C with number 478.
: To calculate the period you can use following formula: '''period=1,000,000/(16*frequency)''' or in short '''period=(62,500/frequency)'''
: (e.g. the note "A" with the frequency 440 Hz has the period 142 on the CPC)

:'''D:''' the duration of the note is measured in 1/100th of a second and can be any positive number in the range 1-32,767. 0 and negative number are in combination with ENT and ENV commands usefull. A negative number means repititions.

:'''V:''' the volume number range from 0-7 on a CPC 464 (BASIC 1.0) or 0-15 on a CPC664/6128 (BASIC 1.1)

:'''ENV:''' and '''ENT:''' For shaping the sound ENV (Volume) and ENT (Frequency) commands are available. The relation between SOUND and those commands comes with a figure between 1 to 15 for ENV (5th parameter) and 1 to 15 for ENT (6th parameter).

:'''N:''' the seventh parameter can be used for blending in noise between the range of 0-15 (BASIC 1.0) or 0-30 (BASIC 1.1). The higher the number the 'deeper' or 'dirty' is the noise.

==== <code>SPC <n></code> ====
: in conjunction with PRINT the SPC command prints out a certain number (n) of spaces.
: Example:
<pre>
PRINT "Hello";SPC(10);"World";
Hello World
</pre>

==== <code>SPEED INK <n1,n2> </code> ====
: SPEED INK command defines the frequency of colour changes if a colour change was defined. The duration is calculated by n1=... or n2 =duration/50 seconds.

==== <code>SPEED KEY <start,repeat> </code> ====
: SPEED KEY command defines the delay after which a key repeat (for keys that do repeat). The first parameter is the delay before the first repeat and the second parameter is the delay between further repeats. Delay is in 1/50th of seconds.

:When using it with low values, it is common to associate a key to reset the default speed of 30,2.
:For example to associate the key 0 from the numpad:
<pre>
KEY 0,"SPEED KEY 30,2"+CHR$(13)
</pre>

==== <code>SPEED WRITE <n> </code> ====
: SPEED WRITE defines the speed at which data is to be saved or written to a cassette unit. n=1 means 2000 baud, n=0 (default) means 1000 baud. When reading from the tape, the correct speed is automatically selected.

==== <code>SQ (channel)</code> ====

: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1,2,3, = A, B, C

: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

==== <code>STOP</code> ====

: Breaks program execution at line containing the STOP statement. The message '''BREAK in''' is output with the line number.

==== <code>SWAP</code> ====
: SWAP works only in combination with the window command. Every error or status messages from the operating system will be displayed normaly on WINDOW#0 (=''main'' window). WINDOW SWAP changes the ''main'' window to the desired target window.
: Example (if a window with number 4 was defined before...):
<pre>
WINDOW SWAP 0,4
</pre>

==== <code>SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8]</code> ====

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

==== <code>SYMBOL AFTER n</code> ====
: 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.

==== <code>TAB</code> ====
: [...]

==== <code>TAG [#st]</code> ====

: Allows text to print at graphics cursor position.
: see TAGOFF

==== <code>TAGOFF [#st]</code> ====

: Directs text to stream st printing it at previous text cursor position.

==== <code>TROFF</code> ====

: Turns off the program flow trace (see TRON)

==== <code>TRON</code> ====

: Turns on the program flow trace for debugging. Causes the line number of each statement executed to be displayed.

==== <code>USING</code> ====
: The USING assignement defines the format of the PRINT output. Its appointment happens by characters where each has a certain meaning.

'''Numbers / Figures'''
: the character:
:'''#''' stands for a figure between 0 - 9
:'''.''' stands for a decimal point
:'''+''' generates a positive sign if the value is positive
:'''-''' generates a negative sign if the value is nagative
:'''**''' generates a asterix for each empty "location" before the printed character
:'''$$''' generates a Dollar characters before the printed character (the same with the pound note)
:''',''' generates a comma every each three decimals (thousands per figure) and has to be set before the decimal point or at the end if without a decimal point.
:^ generates a scientific notation (with exponents) and a the end of the format appointment

'''Strings'''
: the character:
:'''!''' prints out only the first character
:'''\xxx\''' prints out only with x-numbers defined length of the string (from left to right). x means a blank sign made with the space bar
:'''&''' the whole string is printed out as given (unknown function)

: a print output (numbers) with "%" in the beginning shows that not enough positions has to be declared (at all or before the decimal point).

: Example:
<pre>
10 figure=123456789
20 word$="Hello"
30 print using "+**,##########";figure
40 print using "\ \";word$

creates following output:

*****+12,345,679
Hel
</pre>

==== <code>WAIT add, i1[,i2]</code> ====

: Waits until the I/O port at add returns a value (0-255). The value returned is XORed with i2 and the ANDed with i1. This is repeated until a non-zero result occurs.

==== <code>WHILE WEND</code> ====
: [...]

==== <code>WIDTH</code> ====
: [...]

==== <code>WINDOW[#‹stream expression›],[L],[R],[T],[B]</code> ====
: It is possible to define in BASIC eight (8) independent windows for text output. Overlapping is possible.

: #STREAM: eight window are possible. No. zero (0) is the main window where error or status messages were put out by default.
: each position is included inside the window
: L = left column / R = right column (dependent of the mode 0 = 20 / 1 = 40 / 2 = 80)
: T = top row / B = bottom row (always from 1 to 25)

: Example:
<pre>
MODE 1
WINDOW#1,1,40,1,6
</pre>
: ...defines the first top quarter of the screen for window No. 1

==== <code>WRITE [#st,] v[$], v[$]</code> ====

: Writes the values of the specified variable to the specified stream.

: Example:

<pre>
10 OPENOUT "DUMMY"
20 INPUT A$,A
30 WRITE #9,A$,A
40 CLOSEOUT
</pre>

==== <code>ZONE i</code> ====

: Changes the width of the print zone. Default is 13.
: Example:
<pre>
10 MODE 2
20 PRINT"normal zone (13)"
30 PRINT 1,2,3,4
RUN
normal zone(13)
1 2 3 4
READY
20 PRINT"now with different zone(5)"
30 ZONE 5
40 PRINT 1,2,3,4
RUN
now with different zone(5)
1 2 3 4
READY
</pre>

=== Operators ===
: A logical status in Locomotive Basic will be represented by a "-1" for TRUE and by a "0" for FALSE.
: Example:
<pre>
PRINT (1=1)
-1
PRINT (1=2)
0
</pre>
==== <code>AND</code> ====
: Possible combinations with the AND Function:
<pre>
NPUT1 INPUT2 OUTPUT
======================
TRUE TRUE TRUE
FALSE FALSE FALSE
TRUE FALSE FALSE
FALSE TRUE FALSE
</pre>
: Example:
<pre>
PRINT 128 AND 64
0
</pre>
: looking at the BIT combination for a better understanding:
<pre>
10000000
AND 01000000
================
= 00000000
</pre>
: even in BASIC it is possible to manipulate single BITs although there are no special commands but AND, OR and XOR.
: first an example for a loop with an increasing counter WITHOUT an AND:
<pre>
10 counter=0
20 counter=counter+1
30 IF counter=32 THEN counter=0
40 GOTO 20
</pre>
: then a shorter example WITH and AND:
<pre>
10 counter=0
20 counter=(counter+1) AND 31
30 GOTO 20
</pre>
: in the second example all more significant BITs will be deleted (a common method in assembler programming)
: Beware: it only works here with BIT/number conditions one figure smaller than 1, 3, 7, 15, 31, 63 and 127
==== <code>MOD</code> ====
: '''MOD''' returns a (rounded) rest (Modulos) after dividen has been devided by the devisor.
:
:'''Example:'''
<pre>
32767 mod 256
255
</pre>
: Note: only works with numbers in the range -32768 and 32767 (&8000 < 0 < &7FFF)

==== <code>NOT</code> ====
: '''NOT''' executes a bit for bit '''negation''' of the current value. The output is a 16-Bit-Word.
:
:'''Example:'''
<pre>
10 value1=1
20 value2=NOT value1
30 PRINT value2
run
-2
</pre>
:for a better understanding...
<pre>
10 value1=1
20 PRINT HEX$(value1):PRINT BIN$(value1,8)
30 value2=NOT value1
40 PRINT HEX$(value2):PRINT BIN$(value2,8)
run
1
00000001
FFFE
1111111111111110
</pre>

==== <code>OR</code> ====
: Possible combinations with the OR Function:
<pre>
NPUT1 INPUT2 OUTPUT
======================
TRUE TRUE TRUE
FALSE TRUE TRUE
TRUE FALSE TRUE
FALSE FALSE FALSE
</pre>
==== <code>XOR</code> ====
: Possible combinations with the XOR Function:
<pre>
NPUT1 INPUT2 OUTPUT
======================
TRUE TRUE FALSE
FALSE TRUE TRUE
TRUE FALSE TRUE
FALSE FALSE FALSE
</pre>

=== Functions ===

==== <code><big>ABS (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the ABSolute value of the given numeric expression (n). This means that negative numbers are returned as positive.
: '''Associated keywords''': SGN

: '''Example''':

<pre>
PRINT ABS(-67.98)
67.98
</pre>

==== <code><big>ASC (<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the numeric value of the first character in the <string expression> (s).
: '''Associated keywords''': CHR$

: '''Example''':
<pre>
PRINT ASC("x")
120
</pre>
==== <code><big>ATN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the Arc-TaNgent of the <numeric expression> (n) to a real number ranging from -PI/2 to +PI/2 of the value specified.
: Note that DEG and RAD can be used to force the result of the below calculation to degrees or radians respectively.

: '''Associated keywords''': COS, DEG, RAD, SIN, TAN

: '''Example''':
<pre>
PRINT ATN(1)
0.785398163
</pre>
==== <code><big>BIN$ (<unsigned integer expression>,[<integer expression>])</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Produces a string of BINary digits respresenting the value of the <unsigned integer expression>, using the number of binary digits instruced by the second <integer expression> (in the range of 0 to 16). If the number of digits instructed is too great, the resulting expression will be filled with leading zeros; if the number of digits instructed is too small, the resulting expression will NOT be shortened to the instructed number of digits, but will produced in as many digits as are required.
: The <unsigned integer expression> to be converted into binary form must yield a value in the range -32768 to 65535.
: '''Associated keywords''': DEC$, HEX$, STR$
: '''Example''':
<pre>
PRINT BIN$(66,8)
01000000
</pre>
==== <code><big>CHR$ (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Converts an <integer expression> in the range 0 to 255, to its CHaRacter $tring equivalent, using the AMSTRAD character set shown in the ASCII table or e.g. in the manual part 3.
: Note that 0 to 31 are control characters; hence the below example prints CHR$(x) in the range 32 to 255
: '''Associated keywords''': ASC, LEFT$, RIGHT$, MID$, STR$

: '''Example''':
<pre>
10 FOR X=32 to 255
20 PRINT X;CHR$(X);
30 NEXT
</pre>
: A further 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.

: Control Codes Table:
<pre>
===============================================================================
| VALUE | NAME | PARAMETERS | EFFECT |
===============================================================================
| DEC | HEX | | | |
===============================================================================
| 0 | &00 | NUL | NONE | DOES NOTHING |
| 1 | &01 | SOH | 0-255 | PRINTS CHARACTER TO SCREEN |
| 2 | &02 | STX | NONE | TURNS TEXT CURSOR OFF |
| 3 | &03 | ETX | NONE | TURNS TEXT CURSOR ON IN IMMEDIATE MODE |
| 4 | &04 | EOT | 0-2 | SET SCREEN MODE |
| 5 | &05 | ENQ | 0-255 | PRINT CHARACTER AT GRAPHICS CURS. |
| 6 | &06 | ACK | NONE | TURNS ON TEXT SCREEN (SEE ALSO CHR$(21))|
| 7 | &07 | BEL | NONE | MAKE A SHORT BEEP |
| 8 | &08 | BS | NONE | MOVES TEXT CURSOR BACK ONE CHARACTER |
| 9 | &09 | TAB | NONE | MOVES TEXT CURSOR FORWARD ONE CHARACTER |
| 10 | &0A | LF | NONE | MOVES TEXT CURSOR DOWN ONE CHARACTER |
| 11 | &0B | VT | NONE | MOVES TEXT CURSOR UP ONE CHARACTER |
| 12 | &0C | FF | NONE | CLEARS SCREEN OR WINDOWS (= CLS) |
| 13 | &0D | CR | NONE | MOVES CURSOR TO LEFT EDGE OF WINDOW ON |
| | | | | CURRENT LINE |
| 14 | &0E | SO | 0-15 | SETS PAPER COLOUR |
| 15 | &0F | SI | 0-15 | SETS PEN COLOUR |
| 16 | &10 | DLE | NONE | DELETES CHARACTER UNDER TEXT CURSOR |
| 17 | &11 | DC1 | NONE | CLEARS LINE FROM LEFT OF WINDOW UP TO |
| | | | | AND INCLUDING CURRENT CHARACTER |
| 18 | &12 | DC2 | NONE | CLEARS FROM CURRENT CHARACTER TO RIGHT |
| | | | | EDGE OF THE WINDOW |
| 19 | &13 | DC3 | NONE | CLEARS FROM START OF WINDOW UP TO AND |
| | | | | INCLUDING CURRENT CHARACTER |
| 20 | &14 | DC4 | NONE | CLEARS FROM CURRENT CHARACTER TO END OF |
| | | | | WINDOW |
| 21 | &15 | NAK | NONE | TURNS OFF TEXT SCREEN (SEE ALSO CHR$(6))|
| 22 | &16 | SYN | 0 AND 1 | TURNS TRANSPARENT OPTION OFF AND ON |
| 23 | &17 | ETB | 0-3 | SET GRPAHICS PLOTTING MODE |
| 24 | &18 | CAN | NONE | CHANGE TO INVERSE CHARACTER DISPLAYING |
| 25 | &19 | EM | NINE PARAM. | DEFINES A CHARACTER (= SAME AS SYMBOL) |
| | | | EACH 0-255 | |
| 26 | &1A | SUB | FOUR PARAM. | DEFINES A TEXT WINDOW (=SAME AS WINDOW) |
| | | | 1-80, 1-80 | FROM LEFT, RIGHT, TOP TO BOTTOM |
| | | | 1-25, 1-25 | FROM LEFT, RIGHT, TOP TO BOTTOM |
| 27 | &1B | ESC | NONE | DOES NOTHING ON SCREEN (PRINTER SIGNAL) |
| 28 | &1C | FS | THREE PARAM. | SETS INK COLOUR TO FLASH BETWEEN TWO |
| | | | 0-15, 0-32 | INK NO, COLOUR 1, COLOUR 2 |
| | | | 0-32 | |
| 29 | &1D | GS | TWO PARAM. | SETS BORDER COLOUR TO FLASH BETWEEN TWO |
| | | | 0-31, 0-31 | COLOURS |
| 30 | &1E | RS | NONE | HOMES CURSOR TO TOP LEFT OF SCREEN |
| 31 | &1F | US | TWO PARAM. | MOVES CURSOR TO CELL SPECIFIED BY TWO |
| | | | 1-80, 1-25 | PARAMETERS (=SAME AS LOCATE) |
===============================================================================
</PRE>

==== <code><big>CINT (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the value of the <numeric expression> (n), Converting it to a rounded INTeger in the range -32768 to 32767.

: '''Associated keywords''': CREAL, FIX, INT, ROUND, UNT

: '''Example''':
<pre>
10 n=1.9999
20 PRINT CINT(n)
run
2
</pre>
==== <code><big>COPYCHR$ (#stream)</big></code> ====
: : ''BASIC 1.1''
: '''FUNCTION''': COPies a CHaRacter from the current position in the stream (which MUST be specified). The below program copies a character from location 1,1 (top left), and reproduces it at location 1,20.
: If the character read is not recognized, a null string is returned.

: '''Associated keywords''': LOCATE

: '''Example''':
<pre>
10 CLS
20 PRINT "top corner"
30 LOCATE 1,1
40 a$=COPYCHR$(#0)
50 LOCATE 1,20
60 PRINT a$
</pre>
==== <code><big>COS (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the COSinus of the <numeric expression> (n).
: Note that DEG and RAD can be used to force the result of the below calculation to degrees or radians respectively.

: '''Associated keywords''': ATN, DEG, RAD, SIN

: '''Example''':
<pre>
DEG
PRINT COS(45)
0.707106781
</pre>
==== <code><big>CREAL (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the value of the <numeric expression> (n), Converting it to REAL.

: '''Associated keywords''': CINT

: '''Example''':
<pre>
10 a=PI
20 PRINT CINT(a)
30 PRINT CREAL(a)
run
3
3.14159265
</pre>
==== <code><big>DEC$(<numeric expression>, <format template>)</big></code> ====
: ''BASIC 1.1''
: '''FUNCTIION''': Returns a DECimal string representation of the <numeric expression> (n), using the specified <format template> to control the print format of the resulting string.
: The format template may contain ONLY the characters:

: + - $ £ * # , . ^

: The use of these 'format field specifiers' is described under the keyword PRINT USING.

: '''Associated keyword''': BIN$, HEX$, PRINT USING, STR$

: '''Example''':
<pre>
PRINT DEC$(10^7,"££########,.##")
£10,000,000.00
</pre>
==== <code><big>DERR</big></code> ====
: ''BASIC 1.1''
: '''FUNCTION''': Reports the last error code returned by the disc filing system. The value of DERR may be used to ascertain the particular Disc ERRor that occurred. See the listing of error messages below.

: '''Associated keywords''': ERL, ERR, ERROR, ON ERROR GOTO, RESUME

: '''Example''':
<pre>
LOAD "xyz.abc"

XYZ .ABC not found
Ready
PRINT DERR
146
</pre>
: '''Table of Disc ERRor codes''':
: If AMSDOS has already reported an error, then bit 7 is set, hence the value of DERR is offset by 128.
<pre>
===============================================================================
| VALUE | DERR value | DESCRIPTION |
===============================================================================
| 0 | 0 or 22 | [ESC] has been pressed |
| 14 | 142 (128+14) | The stream is not in a suitable state. |
| 15 | 143 (128+15) | Hard end of file has been reached. |
| 16 | 144 (128+16) | Bad command, usually an incorrect filename. |
| 17 | 145 (128+17) | File already exists. |
| 18 | 146 (128+18) | File does not exists. |
| 19 | 147 (128+19) | Directory is full. |
| 20 | 148 (128+20) | Disc is full. |
| 21 | 149 (128+21) | Disc changed while file were open. |
| 22 | 150 (128+22) | File is Read/Only. |
| 26 | 154 (128+26) | Soft end of file has been detected. |
| | | |
===============================================================================
</pre>
: Other values returned by DERR originate from the disc controller and are bit significant, always with bit 6 set.
: The significance of each bit is as follows:
<pre>
===============================================================================
| BIT | Significance |
===============================================================================
| 0 | Address mark missing. |
| 1 | Not writable - disc is write protected. |
| 2 | No data - can't find the sector. |
| 3 | Drive not ready - no disc in the drive. |
| 4 | Overrun error. |
| 5 | Data error - CRC error. |
| 6 | Always set to 1 to indicate error from disc controller. |
| 7 | Set to 1 if error has already been reported by AMSDOS. |
===============================================================================
</pre>
==== <code><big>EOF</big></code> ====
: ''BASIC 1.1''
: '''FUNCTION''': Checks to see if end of specified file has been reached during input. Returns 0 (false) until the end of file, then -1 (true).

: '''Associated keywords''': OPENIN, CLOSEIN

: This '''example''' reads a file from disc and print it out on screen. Like the "TYPE" command in CP/M or "|TYPE,file" of the UTOPIA-ROM.
<pre>
10 OPENIN "text.txt"
20 WHILE NOT EOF
30 LINE INPUT#9,a$
40 PRINT a$
50 WEND
60 CLOSEIN
</pre>
==== <code><big>ERR</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the number of the last ERRor encountered. See the table below of error messages. In the example below you will see that ERRor number 8 is a 'Line does not exist' error.

: '''Example''':
<pre>
GOTO 500
Line does not exist
Ready
PRINT ERR
8
</pre>
: NOTE: BASIC 1.0 (officially) describes error codes until 30 (without an attached floppy disc controller). 31 & 32 are floppy disc error codes.
: '''Table of ERRor codes''':
<pre>
========================================================================================
| VALUE | NAME | DESCRIPTION |
========================================================================================
| 1 |Unexpected NEXT |A NEXT command has been encountered while not in a |
| | |FOR loop, or the control variable in the NEXT |
| | |command does not match that in the FOR. |
| 2 |Syntax Error |BASIC cannot understand the given line because |
| | |a construct within it is not legal. |
| 3 |Unexpected RETURN |A RETURN command has been encountered when not in a |
| | |subroutine. |
| 4 |DATA exhausted |A READ command has attempted to read beyond the end |
| | |of the last DATA. |
| 5 |Improper Argument |This is a general purpose error. The value of a |
| | |function's argument, or a command parameter is |
| | |invalid in some way. |
| 6 |Overflow |The result of an arithmetic operation has over- |
| | |flowed. This may be a floating point overflow, in |
| | |which case some operation has yielded a value |
| | |greater than 1.7E^38 (approx.). Alternatively, this |
| | |may be the result of a failed attempt to change a |
| | |floating point number to a 16 bit signed integer. |
| 7 |Memory full |The current program or its variables may be simply |
| | |too big, or the control structure is too deeply |
| | |nested (nested GOUSBs, WHILEs or FORs). |
| | |A MEMORY command will give this error if an attempt |
| | |is made to set the top of BASIC's memory too low, or|
| | |to an impossible high value. Note that an open file |
| | |has a buffer allocated to it, and that may restrict |
| | |the values that MEMORY may use. |
| 8 |Line does not exist |The line referenced cannot be found. |
| 9 |Subcript out of range |One of the subscripts in an array reference is too |
| | |big or too small. |
| 10 |Array already dimensioned|One of the arrays in a DIM statement has already |
| | |been declared. |
| 11 |Division by zero |May occur in real division, integer division, |
| | |integer modulus or exponentiation. |
| 12 |Invalid direct command |The last command attempted is not valid in direct |
| | |mode. |
| 13 |Type mismatch |A numeric value has been presented where a string |
| | |value is required or vice versa, or an invalidly |
| | |formed number has been found in READ or INPUT. |
| 14 |String space full |So many strings have been created that there is no |
| | |further room available, even after 'garbage |
| | |collection'. |
| 15 |String too long |Strings exceeds 255 characters in length. May be |
| | |generated by appending strings together. |
| 16 |String expression too |String expressions may generate a number of |
| |complex |intermediate string values. When the number of these|
| | |values exceeds a reasonable limit, this error |
| | |results. |
| 17 |Cannot CONTinue |For one reason or another the current program |
| | |be restarted using CONT. Note that CONT is intended |
| | |for restarting after a STOP command, [ESC][ESC], |
| | |or an error, and that any alteration of the |
| | |program in the meantime makes a restart impossible. |
| 18 |Unknown user function |No DEF FN has been executed for the FN just |
| | |invoked. |
| 19 |RESUME missing |The end of the program has been encountered while |
| | |in error processing mode (i.e. in an ON ERROR GOTO |
| | |routine). |
| 20 |Unexpected RESUME |RESUME is only valid while in error processing mode |
| | |(i.e. in an ON ERROR GOTO routine). |
| 21 |Direct command found |When loading a file, a line without a line number |
| | |has been found. |
| 22 |Operand missing |BASIC has encountered an incomplete expression. |
| 23 |Line too long |A line when converted to BASIC internal-form becomes|
| | |too big. |
| 24 |EOF met |An attempt has been made to read past end of the |
| | |file input stream. |
| 25 |File type error |The file being read is not of a suitable type. |
| | |OPENIN is only prepared to open ASCII text files. |
| | |Similarly, LOAD, RUN, etc, are only prepared to |
| | |deal with file types produces by SAVE. |
| 26 |NEXT missing |Cannot find a NEXT to match a FOR command. A line |
| | |number accompanying this message indicates the FOR |
| | |command to which this error applies. |
| 27 |File already open |An OPENIN or OPENOUT command has been executed |
| | |before the previously opened file has been closed. |
| 28 |Unknown command |BASIC cannot find a taker for an external command, |
| | |i.e. a command preceded by a bar |. |
| 29 |WEND missing |Cannot find a WEND to match a WHILE command. |
| 30 |Unexpected WEND |Encountered a WEND when not in a WHILE loop, or a |
| | |WEND that does not match the current WHILE loop. |
| 31 |File not open |(see 'Disc ERRors above). |
| | |If access attempted when no file was open. |
| 32 |Broken in |(see 'Disc ERRors above). |
| | |If access attempted when no file was open. |
| | | |
| | |If value 31 or 32 are stated, DERR could be |
| | |interrogate to give more detailed information. |
| | |(see example below.) |
========================================================================================
</pre>
: '''Example for ERR 31 / 32''':
<pre>
10 ON ERROR GOTO 1000
20 OPENOUT "myfile.asc"
30 WRITE #9,"test-data"
40 CLOSEOUT
50 END
1000 amsdoserr=(DERR AND &7F):REM mask off bit 7
1010 IF ERR<31 THEN END
1020 IF ERR=31 THEN PRINT "are you sure you've typed line 20 correctly?":END
1030 IF amsdoserr=20 THEN PRINT "disc is full, suggest you use a new data disc":END
1040 IF amsdoserr=&X01001000 THEN PRINT "put a disc in the drive, then press a key":WHILE INKEY$="":WEND:RESUME
1050 END
</pre>
==== <code><big>EXP (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates 'E' to the power given in the <numeric expression> (i), where 'E' is approximately 2,7182818-the number whose natural logarithm is 1.

: '''Associated keywords''': LOG

: '''Example''':
<pre>
PRINT EXP(6.876)
968.743625
</pre>
==== <code><big>FIX (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Unlike CINT, FIX merely removes the part of the numeric expression, to the right of the decimal point, and leaves an integer result, rounding towards zero.

: '''Associated keywords''': CINT, INT, ROUND

: '''Example''':
<pre>
PRINT FIX(9.99999)
9
</pre>
==== <code><big>FRE (<numeric expression>/<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Establishes how much FREe memory remains unused by BASIC. The form FRE("") forces a 'GARBAGE COLLECTION' before returning a value for available space.
: NOTE: BASIC uses only the first 64K of the memory.

: '''Associated keywords''': HIMEM, MEMORY

: '''Examples''':
<pre>
PRINT FRE(0) or PRINT FRE("hello")
PRINT FRE("")
</pre>
==== <code><big>HEX$ (<unsigned integer expression>, <field width>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Produces a $tring of HEXadecimal digits representing the value of the <unsigned integer expression>, using the number of hexadecimal digits instructed by the <field width> (in the range 0 to 16). If the number of digits instructed is too great, the resulting expression will be filled with leading zeros; if the number of digits instructed is too small, the resulting expression will NOT be shortened to the instructed number of digits, but will be produced in as many digits as are required.
: The <unsigned integer expression> to be converted into hexadecimal form must yield a value in the range -32768 to 65535.

: '''Accociated keywords''': BIN$, DEC$, STR$, UNT

: '''Example''':
<pre>
PRINT HEX$(255,4)
00FF
</pre>
==== <code><big>HIMEM</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the address of the Highest byte of Memory use by BASIC, (which may altered by e.g. the MEMROY command).
: Before resetting the highest byte of available memory using the MEMORY command, it is advisable to issue the 'command mm=HIMEM'. You will thereafter be able to return to the previous memory capacity by issuing the command: 'MEMORY mm'
: NOTE: BASIC uses only the first 64K of memory.

: Associated keywords: FRE, MEMORY, SYMBOL, SYMBOL AFTER.

: '''Example''':
...on a CPC464
<pre>
PRINT HIMEM
43903
</pre>
...on a CPC6128
<pre>
PRINT HIMEM
42619
</pre>
==== <code><big>INKEY (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': INterrogates the KEYboard to report which keys are being pressed. The keyboard is scanned every 0.02 (1/50) second.
: The function is useful for spotting whether a certain key is down or up, by detecting the returned value of -1 (which occurs regardless of [SHIFT] and [CONTROL] key status).
: The example below detects when [SHIFT] and V (key number 55) are pressed together, then ends the program. Refer the manual for the key numbers.

: '''Associated keywords''': CLEAR INPUT, INKEY$, JOY

: '''Example''':
<pre>
10 IF INKEY(55)<>32 THEN 10
20 PRINT "You've pressed [SHIFT] and V"
30 CLEAR INPUT
run
</pre>
: The state of [SHIFT] and [CONTROL] in conjunction with the key specified in the <integer expression> is identified as follows:
<pre>
==============================================================================
|Value returned |[SHIFT] |[CTRL] |Specified key |
==============================================================================
|-1 |ignored |ignored |up |
|0 |up |up |down |
|32 |down |up |down |
|128 |up |down |down |
|160 |down |down |down |
==============================================================================
</pre>
==== <code><big>INKEY$</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': INterrogates the KEYboard, returning the current $tring reflecting any key that is pressed. It provides operator interaction without hitting [ENTER] after every answer. If there is a key pressed, then the function responds. If no key is pressed, INKEY$ returns an empty string.
: In the example below, lines 40 and 70 tell the program to loop back to line 30 after interrogating the keyboard string.

: '''Associated keywords''': CLEAR INPUT, INKEY

: '''Example''':
<pre>
10 CLS
20 PRINT "Select Yes or No (Y/N)?"
30 a$=INKEY$
40 IF a$="" THEN 30
50 IF a$="y" OR a$="Y" THEN 80
60 IF a$="N" OR a$="n" THEN 90
70 GOTO 30
80 PRINT "You have selected YES": END
90 PRINT "You have selected NO":
run
</pre>
==== <code><big>INP (‹port number›)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the INPut value from the I/O address specified in the <port number>.

: '''Associated keywords''': OUT, WAIT

: Watch out http://cpcwiki.eu/index.php/I/O_Port_Summary

: '''Example''':
<pre>
PRINT INP(&FF00)
255
Ready
</pre>
==== <code><big>INSTR ([‹startposition›,]‹searched string›, ‹searched for string›)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Searches the first <searched string> expression to find the first occurance of the <searched for string expression<, and reports the position of its occurance within the <searched string>. If the <searched for string> does not occur within the <searched string>, then 0 is reported.
: The position at which to start searching the <searched string> is optionally specifiable using the <start position> parameter which must yield an integer number in the range 1 to 255.

: '''Associated keywords''': none

: '''1. Example''':
<pre>
a$="ABCD":PRINT INSTR(a$,"C")
3
Ready
</pre>
: '''2. Example''':
<pre>
a$="Hello":IF INSTR(a$,"i")<>0 THEN PRINT "no" else a$
no
Ready
</pre>
: '''3. Example''':
<pre>
10 CLS
20 alphabet$="ABCDEFGHIJKLMNOPQRSTUVWXYZ"
30 INPUT "Enter a letter";a$
40 b$=UPPER$(a$)
50 PRINT b$;" is number";
60 PRINT INSTR(alphabet$,b$);
70 PRINT "in the alphabet.":PRINT
80 GOTO 40
run
</pre>
==== <code><big>INT (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Rounds the number to the nearest smaller INTeger, removing any fractional part. Returns then same value as FIX for positive number, but returns one less than FIX for negative numbers which are not already integers.

: '''Associated keyword''': CINT, FIX, ROUND

: '''Example''':
<pre>
PRINT INT(3.99), INT(-3.99)
3 -4
</pre>
==== <code><big>JOY (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': The JOY function reads a bit significant result from the joystick in the <integer expression> (either 0 or 1).
<pre>
================================
|Bit | Value decimal |
================================
|0(up) | 1 |
|1(down) | 2 |
|2(left) | 4 |
|3(right) | 8 |
|4(fire 2) | 16 |
|5(fire 1) | 32 |
================================
</pre>
==== <code><big>LEFT$ (<string expression>, <required length>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the number of characters (in the range 0 to 255) specified in the <required length> parameter (<integer expression>), after extracting them from the LEFT of the <string expression>. If the <string expression> is shorter than the <required length>, the whole <string expression> is returned.

: '''Associated keywords''': MID$, RIGHT$

: '''1. Example''':
<pre>
A$="ABCDEFG":PRINT LEFT$(A$,3) - prints ABC
</pre>
: '''2. Example''':
<pre>
10 CLS
20 a$="AMSTRAD"
30 FOR n=1 to 7
40 PRINT LEFT$(a$,n)
50 NEXT
run
</pre>
==== <code><big>LEN (<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the total number of characters (i.e. the LENgth) of the <string expression>.

: '''Associated keywords''': none

: '''Example''':
<pre>
10 LINE INPUT "Enter a phrase";a$
20 PRINT "The phrase is";
30 PRINT LEN(a$);"characters long."
run
</pre>
==== <code><big>LOG (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the natural LOGarithm (base of ''e'') of <numeric expression> which mustbe greater than zero.

: '''Associated keywords''': EXP, LOG10

: '''Example''':
<pre>
PRINT LOG(9999)
9.21024037
</pre>
==== <code><big>LOG10 (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the logarithm to base 10 of <numeric expression> which must be greater than zero.

: '''Associated keywords''': EXP, LOG

: '''Example''':
<pre>
PRINT LOG10(9999)
3.99995657
</pre>
==== <code><big>LOWER$ (<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns a new string expression which is a copy of the specified <string expression> but in which all alphabetic characters in the range A to Z are converted to lower case. Useful for processing input where the answers may come in mixed upper/lower case.

: '''Associated keywords''': UPPER$

: '''1. Example''':
<pre>
A$="AMSTRAD":PRINT A$="AMSTRAD":PRINT LOWER$(A$)
Amstrad
</pre>
: '''2. Example''':
<pre>
10 a$="SEE HOW THE LETTERS CHANGE TO ... NUMBERS 1234 NOT..."
20 PRINT LOWER$(a$+"LOWER CASE")
see how the letters change to ... numbers 1234 not... LOWER CASE
</pre>
==== <code><big>MAX (<list of: numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the MAXimum value from the <list of: numeric expression>s.

: '''Associated keywords''': MIN

: '''Example''':
<pre>
10 n=66
20 PRINT MAX(1,n,3,6,4,3)
run
66
</pre>
==== <code><big>MIN (<list of: numeric expression>)</big></code> ====
''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the MINimum value from the <list of: numeric expression>s.
: '''Associated keywords''': MAX

: '''Example''':
<pre>
PRINT MIN (3,6,2.999.8,9,)
2.999
</pre>

==== <code><big>PEEK (<address expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the contents of the Z80 memory location specified in the <address expression> which should be in the range &0000 to &FFFF (0 to 65535). In all cases PEEK will return the value at the RAM address specified (not the ROM), and will be in the range &00 to &FF (0 to 255)

: '''Associated keywords''': POKE

: '''Example''':
<pre>
10 MODE 1: ZONE 7
20 WINDOW 1,40,1,2:WINDOW #1,1,40,3,25
30 PRINT "memory-address"
40 LOCATE 20,1:PRINT "memory-contents"
50 FOR n=1 to 65535
60 p=PEEK(n)
70 PRINT #1,n,"(&";HEX$(n);")";
80 PRINT #1,TAB(20);p,"(&";HEX$(p);")"
90 NEXT
run
</pre>
==== <code><big>PI</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': The value of the ratio between the circumference and the diameter of a circle.

: '''Associated keywords''': DEG, RAD

: '''Example''':
<pre>
PRINT PI
3.14159265
</pre>
==== <code><big>POS (#<stream expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current horizontal POSition of the text cursor relative to the left edge of the text window. The <stream expression> MUST be specified, and does NOT default to #0.
: POS(#8) reports the current horizontal carriage position for the printer, where 1 is the extreme left hand edge.
: POS(#9) reports the logical position in the disc file stream, i.e. the number of printing characters sent to the stream since the last carriage return.

: '''Associated keywords''': VPOS, WINDOW
: '''Example''':
<pre>
10 MODE 1: BORDER 0:LOCATE 8,2
20 PRINT "use cursor left/right keys"
30 WINDOW 1,40,12,12:CURSOR 1,1
40 FOR n=1 TO 19:PRINT CHR$(9);:NEXT
50 IF INKEY(1)<>-1 THEN PRINT CHR$(9);
60 IF INKEY(8)<>-1 THEN PRINT CHR$(8);
70 LOCATE #1,2,24
80 PRINT #1,"text cursor ";
90 PRINT #1,"horizontal position = ";
100 PRINT #1,POS(#0):GOTO 50
run
</pre>
==== <code><big>REMAIN (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns count REMAINing count from the delay timer specified in <integer expression> (= timer number in the range 0 to 3), and disable it. If the delay timer was not enabled zero will be returned.

: '''Associated keywords''': AFTER, DI, EI, EVERY

: For the reason that REMAIN is no normal command but a "function" it is necessary in case of a proper functionality to link the command.
: an '''example''' in combination with an interrupt delay timer 1:
<pre>
PRINT REMAIN(1)
</pre>
: or to stop several/all interrupts at the same time...
<pre>
A=REMAIN(0)=REMAIN(1)=REMAIN(2)=REMAIN(3)
</pre>
: Hint: Take care of interrupts due to parallel working (the same cycle time) or if they are stopped with the BREAK key. Interrupts which were disabled for a certain time will be stored in buffer (for a maximum of 128 entries) and made up their task afterwards in the priorisation as declared.
: further '''example''':
<pre>
10 AFTER 500,1 GOSUB 40
20 AFTER 100,2 GOSUB 50
30 PRINT "program running":GOTO 30
40 REM this GOUSB-Routine will not be called as it is disabled in line 80
50 PRINT:PRINT "Timer 1 will now be ";
60 PRINT "disabled by REMAIN."
70 PRINT "Time-units remaining were:";
80 PRINT REMAIN(1)
run
</pre>
==== <code><big>RIGHT$ (<string expression>, <integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the number of characters (in the range 0 to 255) specified in the <integer expression> (=required length) parameter, after extracting them from the RIGHT of the <string expression>. If the <string expression> is shorter than the <integer expression>, the whole <string expression> is returned.

: '''Associated keywords''': LEFT$, MID$

: '''Example''':
<pre>
10 MODE 1:a$="AMSTRAD computer"
20 FOR n=1 TO 16:LOCATE 41-n,n
30 PRINT RIGHT$(a$,n)
40 NEXT
</pre>
==== <code><big>RND [(<numeric expression>)]</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the next RaNDom number in sequence if the <numeric expression> has a positive value or is not specified.
: If the <numeric expression> yields a value of zero, RND returns a copy of the last random number generated.
: If the <numeric expression> yields a negative value, a new random number sequence is started, the first number of which is returned.

: '''Associated keywords''': RANDOMIZE

: '''1. Example''':
<pre>
PRINT RND(0)
0.536703827
Ready
PRINT RND(1)
0.271940658
Ready
PRINT RND(0)
0.271940658
Ready
</pre>
: '''2. Example''':
: Example for generating an integer random number between 1 and 1000
<pre>
10 A=INT((RND(1)*1000)+1)
20 PRINT A
30 GOTO 10
</pre>
: '''3. Example''':
: For generating a random number between a lower and higher border
<pre>
10 INPUT "Low border",low
20 INPUT "High border",high
30 A=INT(RND(1)*(high-low))+low
40 PRINT A
</pre>
: '''4. Example''':
<pre>
10 RANDOMIZE
20 FOR x=1 TO -1 STEP -1
30 PRINT "rnd parameter=";x
40 FOR n=1 TO 6
50 PRINT RND(x)
60 NEXT n,x
run
</pre>

==== <code><big>ROUND (<numeric expression>[,<integer expression>])</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Rounds <numeric expression> to a number of decimal places or to the power of ten specified by <integer expression>. If <integer expression> less than zero, the <numeric expression> is rounded to give an absolute integer with <integer expression> number of zeros before the decimal point.

: '''Associated keywords''': ABS, CINT, FIX, INT
: '''1. Example''':
<pre>
PRINT ROUND(1562.357,2),ROUND(1562.375,-2)
1562.36 1600
</pre>
: '''2. Example''':
<pre>
10 FOR n=4 TO -4 STEP -1
20 PRINT ROUND (1234.5678,n)
30 PRINT "with integer expression";n
40 NEXT
run
</pre>
==== <code><big>SGN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: FUNCTION: Determines the SiGN of the <numeric expression>. Returns -1 if <numeric expression> is less than 0, returns 0 if <numeric expression> = 0, and returns 1 if <numeric expression> is greater than zero.

: '''Associated keywords''': ABS

: '''Example''':
<pre>
10 FOR n=255 to -200 STEP -20
20 PRINT "SGN returns";
30 PRINT SGN(n);"for a value of";n
40 NEXT n
run
</pre>
==== <code><big>SIN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the Real value for the Sine of <numeric expression>, defaulting to the Radian (RAD) measure mode unless otherwise declared by a DEG command.

: '''Associated keywords''': ATN, COS, DEG, RAD, TAN

: '''Example''':
<pre>
10 CLS:DEG:ORIGIN 0,20
20 FOR n=0 to 720
30 y=SIN(n)
40 PLOT n*640/720,198*y:NEXT
50 GOTO 50
run
</pre>
==== <code><big>SPACE$(<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Creates a string of spaces of the given length, (in the range 0 to 255) specified in the <integer expression>.

: '''Associated keywords''': SPC, STRING$, TAB

: '''Example''':
<pre>
10 MODE 1
20 PRINT "Put 9 spaces between me";
30 PRINT SPACE$(9);
40 PRINT "and you!"
run
</pre>
==== <code><big>SQ (<channel>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the state of the Sound Queue for the specified <channel> which must be an integer expression, yielding one the values:
: 1: for channel A
: 2: for channel B
: 4: for channel C
: The SQ function returns a bit significant integer, comprising the following bit settings:
: Bit 0,1 and 2: the number of free entries in the queue
: Bit 3,4 and 5: the rendezvous state at the head of this queue
: Bit 6 : the head of the queue is held
: Bit 7 : the channel is currently active
: ... where Bit 0 is the least significant bit, and Bit 7 is the most significant bit.
: It can be seen, that if Bit 6 is set, Bit 7 cannot be set at the same time, and vice versa. Similarly if Bits 3, 4, or 5 are set, Bit 6 and 7 cannot be set.

: '''Associated keywords''': ON SQ GOSUB, SOUND

: '''Example''':
<pre>
10 SOUND 65,100,100
20 PRINT SQ(1)
run
67
</pre>
==== <code><big>SQR (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the SQuare Root of the specified <numeric expression>.

: '''Associated keywords''': none

: '''Example''':
<pre>
PRINT SQR(9)
3
</pre>
==== <code><big>STR$ (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Converts the <numeric expression> to a decimal STRing representation.
: Useful for converting a number to a string in case of string manipulation. E.g. after converting a figure to a string then the most left character holds the sign: a minus in case the figure is negative and a space in case the figure is positiv.

: '''Associated keywords''': BIN$, DEC$, HEX$, VAL

: '''1. Example''':
<pre>
10 FIGURE=-1599
20 FIGURE$=STR$(FIGURE)
30 PRINT FIGURE$
-1599
</pre>
: '''2. Example''':
<pre>
10 FIGURE=1769
20 FIGURE$=STR$(FIGURE)
30 PRINT FIGURE$
1769
</pre>
: '''NOTE''': (there's a blank on the left-hand of the number "1769")
: If you want to add e.g. zero before the figure in case of a high score with fix digit-number then you're able to add zero(s) in front of a string instead of a figure.

: '''3. Example''':
<pre>
10 a=&FF:REM 255 hex
20 b=&x1111:REM 15 binary
30 c$="***"
40 PRINT c$+STR$(a+b)+c$
run
*** 270***
</pre>

==== <code><big>STRING$ (<length>,<character specifier>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns a string expression consisting of the <character specifier> repeated the number of time (in the range 0 to 255) specified in the <length>.

: '''Associated keywords''': SPACE$

: '''1. Example''':
<pre>
PRINT STRING$(40,"*")
****************************************
</pre>
: '''2. Example''':
<pre>
PRINT STRING(40,42)
****************************************
</pre>
: '''NOTE''': the <character specifier> 42 refers to the ASCII value of the character '*' and is also equivalent to PRINT STRING$(40,CHR$(42))
==== <code><big>TAN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the TANgent of the <numeric expression>, which must be in the range -200,000 to +200,000.
: '''NOTE''': DEG and RAD can be used to force the result of the calculation to degrees or radians respectively.

: '''Associated keywords''': ATN, COS, DEG, RAD, SIN

: '''Example''':
<pre>
PRINT TAN(45)
1.61977519
</pre>

==== <code><big>TEST (<x co-ordinate>,<y co-ordinate>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Moves the graphics cursor to the absolute position specified by the <x> and <y co-ordinate>s, and reports the value of the ink at the new location.

: '''Associated keywords''': MOVE, MOVER, TESTR, XPOS, YPOS

: '''Example''':
<pre>
10 CLS
20 PRINT "Your are using pen number";
30 PRINT TEST(10,386)
40 PRINT "Try changing PENs and MODEs";
50 PRINT "....then RUN again."
run
</pre>
==== <code><big>TESTR (<x offset>,<y offset>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Moves the graphics cursor by the amount specified in the <x> and <y offset>s relative to its current position, and reports the value of the ink at the new location.

: '''Associated keywords''': MOVE, MOVER, TEST, XPOS, YPOS

: '''Example''':
<pre>
10 MODE 0:FOR x=1 TO 15:LOCATE 1,x
20 PEN x:PRINT STRING$(10,143);:NEXT
30 MOVE 200,400:PEN 1
40 FOR n=1 TO 23:LOCATE 12,n
50 PRINT "pen";TESTR(0,-16):NEXT
run
</pre>
==== <code><big>TIME</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the elapsed time since the computer was last switched-on or reset, (excluding periods when reading or writing to disc).
: Each second of real time is equal to the returned value = TIME/300.

: '''Associated keyword''': AFTER, EVERY, WEND, WHILE

: '''Example''':
<pre>
10 CLS:REM clock
20 INPUT "hour";hour
30 INPUT "minute";minute
40 INPUT "second";second
50 CLS:datum=INT(TIME/300)
60 WHILE hour<13
70 WHILE minute<60
80 WHILE tick<60
90 tick=(INT(TIME/300)-datum)+second
100 LOCATE 1,1
110 PRINT USING "## ";hour,minute,tick
120 WEND
130 tick=0:second=0:minute=minute+1
140 GOTO 50
150 WEND
160 minute=0:hour=hour+1
170 WEND
180 hour=1
190 GOTO 60
run
</pre>
==== <code><big>UNT (<address expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Return an integer in the range -32768 to +32767 which is the twos-complement equivalent of the unsigned value of the <address expression>.

: '''Associated keywords''': CINT, FIX, INT, ROUND

: '''Example''':
<pre>
PRINT UNT(&FF66)
-154
</pre>
==== <code><big>UPPER$(<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns a new string expression which is a copy of the specified <string expression> but in which all alphabetic characters in the range A to Z are converted to upper case. The function is useful for processing input which may come in mixed upper / lower case.

: '''Associated keywords''': LOWER$

: '''Example''':
<pre>
10 CLS: a$="my, how you've grown!"
20 PRINT UPPER$(a$)
run
</pre>
==== <code><big>VAL(<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the numeric VALue, (including any negative sign and decimal point) of the first character(s) in the specified <string expression>.
:If the first character is not a number, then 0 is returned. If the first character is a negative sign or decimal point followed by non-numeric characters, a 'Type mismatch' error (13) will be reported.

: '''Associated keywords''': STR$

: '''1. Example''':
<pre>
PRINT VAL("-12.34x"),VAL("A-12")
-12.34 0
</pre>
: '''Exception''': if <se> starts with "&" + character (and it's between "A" and "F") the whole character will be handled like a hexadezimal numeric character (...often used in DATA Loaders). The returning numeric value is a  signed integer (16-Bit Word).
: '''2. Example''':
<pre>
PRINT VAL("&A")
10

PRINT VAL("&7FFF")
32767

PRINT VAL("&8000")
-32768
</pre>
: '''3. Example''':
<pre>
10 CLS: PRINT "I know my times tables!"
20 PRINT:PRINT "Press a key (1 to 9)"
30 a$=INKEY$:IF a$="" THEN 30
40 n=VAL(a$):if n<1 or n>9 then 30
50 FOR x=1 to 12
60 PRINT n;"X";x;"=";n*x
70 NEXT:GOTO 20
run
</pre>
==== <code><big>VPOS (#<stream expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current vertical POSition of the text cursor relative to the top of the text window. The <stream expression> MUST be specified, and does NOT default to #0.

: '''Associated keywords''': POS, WINDOW

: '''Example''':
<pre>
10 MODE 1:BORDER 0:LOCATE 8,2
20 PRINT "use cursor up/down keys"
30 WINDOW 39,39,1,25:CURSOR 1,1
40 LOCATE 1,3
50 IF INKEY(0)<>-1 THEN PRINT CHR$(11);
60 IF INKEY(2)<>-1 THEN PRINT CHR$(10);
70 LOCATE #1,3,24
80 PRINT #1,"text cursor ";
90 PRINT #1,"vertical position =";
100 PRINT #1,VPOS(#0):GOTO 50
run
</pre>
==== <code><big>XPOS</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current horizontal (X)POSition of the graphics cursor.

: '''Associated keywords''': MOVE, MOVER, ORIGIN, YPOS

: '''Example''':
<pre>
10 MODE 1:DRAW 320,200
20 PRINT "graphics cursor X position = ";
30 PRINT XPOS
</pre>
==== <code><big>YPOS</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current vertical (Y)POSition of the graphic cursor.

: '''Associated keywords''': MOVE, MOVER, ORIGIN, XPOS

: '''Example''':
<pre>
10 MODE 1:DRAW 320,200
20 PRINT "graphics cursor Y position = ";
30 PRINT YPOS
</pre>

== Other Basic Dialects available for the CPC ==

*[[BBC Basic]]
*[[C BASIC Compiler|CBASIC]]
*[[BASIC-E]]

== Technical Information ==

* [[Technical_information_about_Locomotive_BASIC]]

== Web links ==

* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]
* [http://rosettacode.org/wiki/Category:Locomotive_Basic Code examples at Rosetta Code]

* [http://cpctech.cpc-live.com/docs/basic.asm Disassembly of Locomotive BASIC v1.1]

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Locomotive BASIC

2025-10-02T13:02:26Z

Arnoldemu: /* OPENOUT ‹filename› */

For other BASIC language versions see the [[:Category:BASIC]]

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

It was availlable directly from in-built ROMs on [[CPC old generation]] and on the [[Plus System Cartridge]] for the [[Plus]] range. [https://benchmarko.github.io/CPCBasic/ Online Interpreter]

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

If you are interested in more information about the different versions of the CPC's BASIC and the technical details, you can have a look at the article "[[Technical information about Locomotive BASIC]]".

Another helpful and further resource of information about BASIC and a similar comprehension to this is Grimware's Website about the CPC http://www.grimware.org/doku.php/documentations/software/locomotive.basic/start

== 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 and Spanish 472 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 472 (British), 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.

== Variables ==
Many contemporary BASIC interpreters only supported the first few characters of a variable name as a discriminator. For example <code>WATER$</code> and <code>WALDO$</code> would refer to the same variable on a Commodore 64 or Apple II. But Locomotive BASIC allowed variable names up to 40 characters in length, so <code>THEQUICKBROWNFOXJUMPEDOVERTHELAZYDOGFAST$</code> and <code>THEQUICKBROWNFOXJUMPEDOVERTHELAZYDOGFATS$</code> could be use as separate variables.

=== Real (Floating Point) Numbers ===

This is the default type for a Locomotive BASIC variables, but can be clarified using <code>!</code> after the variable name, e.g., <code>real!=500.0</code>.
You can force all variables starting with specific letters to be this type by using the <code>DEFREAL</code> keyword.
In many cases you don't want to use these, as they are slower than using the integer type, and use more memory (5 bytes, as opposed to 2).

=== Signed 16-bit Integers ===

Defined using <code>%</code> after the variable name, e.g., <code>integer%=500</code>.
You can force all variables starting with specific letters to be this type by using the <code>DEFINT</code> keyword.
These can store values between -32,768 and 32,767.
To assign a 16-bit value to a signed integer directly, you should give the number in a hexadecimal format, e.g., <code>uint=&c0000</code>.

=== Strings ===

These are defined by using <code>$</code> after the variable name, e.g., <code>str$="Hello"</code>.
You can force all variables starting with specific letters to be this type by using the <code>DEFSTR</code> keyword.
A String can be up to 255 characters long.

== Type Conversions ==

The BASIC functions <code>ROUND</code>, <code>INT</code>, <code>CINT</code> and <code>FIX</code> can be used to convert real numbers into integers taking some care about rounding. The difference is in rounding mode - <code>ROUND</code> rounds to nearest, <code>FIX</code> rounds to zero, <code>INT</code> always rounds down, and <code>CINT</code>rounds up. e.g., <code>value%=INT(3.14)</code>. Note that if you don't specify the % you will actually get a real number still.

To convert an integer to a real number, you can use the <code>UNT</code> function which will take the value supplied and return the two's complement number. e.g., <code>real=UNT(&ABCD)</code>.

<pre>
w=UNT(50000)
Ready
PRINT w
-15536
Ready
█
</pre>

If you want an integer result from division, use the <code>\</code> integer division operator. e.g., <code>int=value\divisor</code>. This is as opposed to the standard <code>/</code> division operator, that can create a real number.

== Command list ==

=== Commands and operators ===

==== <code>AFTER ‹time delay›[,‹timer number›] GOSUB ‹line number› </code>====
: Waits for ‹time delay›/50 seconds and then jumps NON-RECURRING to the subroutine at ‹line number› (see also <code>"EVERY i[,t] GOSUB line"</code>).

==== <code>AUTO [‹line number›][,‹increment›] </code>====
: Automatically generates line numbers starting at ‹line number› with ‹increment› after each entered line number. Use '''[ESC]''' to leave AUTO mode. Default values for ‹line number› and ‹increment› are 10.

: Example:
<pre>AUTO 100,5 :REM generates line numbers 100, 105, 110...</pre>

==== <code>BORDER ‹colour›[,‹colour›] </code>====
: Changes the colour of the border. If the second argument is supplied the border flashes between the two colours.

==== <code>CALL ‹address expression›[,‹list of: parameter›] </code>====
: Allows a machine code routine to be called by BASIC. Variables, string values and constants can be passed to the routine. Values of any supported type can be passed back by supplying a variable with <code>@</code> in front of it. This passes the address of the variable to the routine although it doesn't implicitly know the data type.
: Example:
<pre>CALL 0 :REM resets the computer completely</pre>

==== <code>CAT</code> ====
: Displays the names of the files on the tape or disc. Tape files are displayed in the order they are encountered. Disc files are sorted alphabetically by ACSII code. Only files matching the current user are displayed. Files marked as system are not displayed.
: Examples:
<pre>CAT :REM lists all disc files in alpha-numeric (ASCII) order</pre>

<pre>|TAPE :CAT :REM lists names of all tape files in their storage order</pre>

==== <code>CHAIN ‹file name›[,‹line number expression›] </code>====

:Enables the specified program to be loaded and RUN automatically. If the optional parameter ‹line number expression› is specified, the program execution will commence from that line.

==== <code>CHAIN MERGE ‹file name›[,‹line number expression› | [,[‹line number expression›],DELETE ‹line number range›]] </code>====

:Loads the specified program from tape or disc, merges it into the program in memory, and starts execution of the merged program. The parameter <code>DELETE</code> ‹line number range› is used to delete part of the original program before running it, if required.

==== <code>CLEAR</code> ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.
: The command clear inside a subroutine (<code>GOSUB</code>... <code>RETURN</code>) will also clear the "stack pointer" address of the gosub heap. That means that a RETURN won't work and a GOTO has to be used instead.

==== <code>CLG [‹masked ink›] </code>====
: Clears the graphics screen to colour specified by <code>‹masked ink›</code>. If parameter <code>‹masked ink›</code> is not specified then the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== <code>CLOSEIN</code> ====
: Closes any input file (tape or disc).

==== <code>CLOSEOUT</code> ====
: Closes any output file (tape or disc).

==== <code>CLS [#‹stream expression›]</code>====
: Clears the window specified by ‹stream expression›. If ‹stream expression› is omitted it defaults to #0 (usually the whole screen). The text cursor of the stream is moved to the upper left corner.

==== <code>CONT</code> ====
: CONTinues program execution interrupted either by [ESC] [ESC] or as a result of STOP within a program. A program cannot be continued after being modified.

==== <code>CURSOR ‹expression› </code>====
: <code>‹expression›</code> must be either 0 or 1.

==== <code>DATA x1[,x2,x3...]</code> ====
: 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>

==== <code>DEF</code> ====
: DEF means "define" and comes along with defining a function in case of DEF FN or defining variables in case of DEFREAL, DEFINT or DEFSTR.
: DEF FN must come before using the statement FN.
: DEF with a variable declaration should come before using a variable.
: (see also FN)

==== <code>DEFINT ‹letter range›</code> ====
:Forces all variables(s) starting with the specified letter(s) to be integer variables. Singular letters could be defined or a range by a minus symbol between two letters.

:Examples:
<pre>
20 DEFINT a-z:' sets all variables starting with an A until Z as integer.
</pre>
or
<pre>
10 DEFINT F,S ..... (or 10 DEFINT A-Z)
20 FIRST=111.11:SECOND=22.2
30 PRINT FIRST,SECOND:' prints out 111 22
</pre>

==== <code>DEFREAL ‹letter range›</code> ====
: Sets the default for variable(s) with the specified first letter(s) to a floating point figure.

==== <code>DEFSTR ‹letter range›</code> ====

: Sets the default for variable(s) with the specified first letter(s) to string(s) variables.

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

==== <code>DELETE [first line][-[last line]]</code> ====
: Deletes the current program completely (without arguments) or only the given line or line range. Even
: <code>DELETE -</code>
: is legal, it has the same effect as
: <code>DELETE</code>
: The lines specified do not have to exist, all lines matching the range will be deleted and having no matches does not cause an error.

==== <code>DI</code> ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.
: This means that DI (if it's activated in a subroutine) is useful helping a low-priority-interrupt not to be stopped by a higher-priority-interrupt. RETURN then re-enable the interrupt without EI.

==== <code>DIM a[%|!|$](d1[,d2[,...]])</code> ====

: Creates array <code>a</code> with single or multiple dimensions. You may optionally specify integer (<code>%</code>), real (<code>!</code>) or string (<code>$</code>) type otherwise it defaults to the current type set for the first letter of the array name. <code>d1</code> is size of first dimension-1, <code>d2</code> is size of second dimension-1 and so on. <code>DIM x(10)</code> will create an array with 11 elements, <code>x(0)</code> is the first element, <code>x(10)</code> is the eleventh and last. You can specify as many dimensions as will fit on one 255 character line, which is a maximum of 125. Trying to create an array that already exists will generate an <code>Array already dimensioned</code> error. If an array is not specified by <code>DIM</code> before being accessed, each dimension value defaults to 10. The maximum dimensions that can be created this way is three.

==== <code>DRAW x,y[,[i1][,i2]]</code> ====

: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the drawing style.

: 4 drawing styles:
<pre>
i2 = 0 normal colour
i2 = 1 XOR colour
i2 = 2 AND colour
i2 = 3 OR colour
</pre>
: Example:
<pre>
CLG 2
DRAW 500,400,0 :REM draws a line from 0,0 to 500,400
</pre>

<code>DRAWR xr,yr[,[i1][,i2]]</code> ====

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

<pre>
Move 200,200
DRAWR 100,100,0 - draws a line from 200,200 to 300,300
</pre>

==== <code>EDIT ‹line›</code> ====
: Display 1 program line for editing.

The following keys can be used in editing mode, or during typing in BASIC:

CTRL+TAB - toggle overwrite/insert mode
CTRL+CURSOR LEFT or CTRL+CURSOR UP - go to start of line
CTRL+CURSOR RIGHT or CTRL+CURSOR DOWN - go to end of line
CURSOR LEFT - move left one character
CURSOR RIGHT - move right one character
ESC - quit editing and do not accept changes
ENTER/RETURN - quit editing and accept changes
SHIFT + CURSOR UP/DOWN/LEFT/RIGHT - enter copy mode. You can move the cursor to where you want to copy from. Hold SHIFT and cursors to move copy cursor.
COPY - copy character covered by copy cursor.
DEL - delete character and go back a char
CLR - delete character under cursor
CTRL + CAPS LOCK - toggle shift lock.

==== <code>EI</code> ====
: Enable interrupts which have been disabled by DI

==== <code>END</code> ====
: Indicates end of program

==== <code>ENT ‹tone envelope number›[,‹tone env. section›][,‹tone env. section›][,‹tone env. section›][,‹tone env. section›][,‹tone env. section›]</code> ====
:The ENT command define the TONE shape of a sound which means manipulating the frequency in a certain range.
:The command could looks like:
<pre>
ENT NUMBER,STEPS?,VERTICAL?,HORIZONTAL?
</pre>
:It is possible to define 15 different envelope shapes. So '''NUMBER''' could be 1-15.

:Each '''?''' stands for up to five sections (1-5), where each STEP<>VERTICAL<>HORIZONTAL with the same '''?''' are belong together.

:'''STEP:''' means how many steps in each section (0-127) > one step is 1/100 of a second!
:'''VERTICAL''': means how big is the step size from bottom to top (-128 to 127)
:'''HORIZONTAL''': means how big is the step size from left to right (0-255)

==== <code>ENV ‹volume envelope number›[,‹volume env. section›][,‹volume env. section›][,‹volume env. section›][,‹volume env. section›][,‹volume env. section›]</code> ====
:The ENV command define the VOLUME shape of a sound which means manipulating the loudness in a certain range.
:The command could looks like:
<pre>
ENV NUMBER,STEPS?,VERTICAL?,HORIZONTAL?
</pre>
:It is possible to define 15 different envelope shapes. So '''NUMBER''' could be 1-15.

:Each '''?''' stands for up to five sections (1-5), where each STEP<>VERTICAL<>HORIZONTAL with the same '''?''' are belong together.

:'''STEP:''' means how many steps in each section (0-127) > one step is 1/100 of a second!
:'''VERTICAL''': means how big is the step size from bottom to top (-128 to 127)
:'''HORIZONTAL''': means how big is the step size from left to right (0-255)

==== <code>ERASE v1[% | ! | $][,v2[% | ! | $][,...]]</code> ====
: Erases the specified array(s) and frees the memory used. Must specify existing array(s) or an <code>Improper argument</code> error will be generated.

==== <code>ERL</code> ====

: Returns the line number of the last error encountered.

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

==== <code>EVERY i[,t] GOSUB ln</code> ====

: BASIC branches to the subroutine at line ln EVERY (reccuring) i/50 seconds. (see also "AFTER i[,t] GOSUB line")

: There are 4 delay timers from 0 to 3 which can be specified with ‹timer number›. If omitted ‹timer number› defaults to 0.
: In the case of parallel task has 3 the highest and 0 the lowest priority.
: With DI or EI you can disable or enable the timing interrupt. With REMAIN <timer number> you can also disable an AFTER or EVERY construct and stores the "remaining" time (> REMAIN)
: Interrupts run as long as the main loop / program runs, even the main programm is paused > press ESC only '''once''' not twice for a break.
: It is important to know or realise that low-priority-interrupts which occurs simultanously to higher-priority-interrupts are not lost. Their task remains or handled again after finishing the higher-prio interrupt.

<pre>
10 REM > interrupts
20 EVERY 50,0 GOSUB 100: REM > lowest priority
30 EVERY 100,1 GOSUB 200
40 EVERY 200,2 GOSUB 300:
50 AFTER 1000,3 GOSUB 400: REM > highest priority
60 WHILE flag=0
70 a=a+1:print a
80 WEND
90 END
100 REM #0
110 PEN 2:PRINT "timer 0":PEN 1
120 RETURN
200 REM #1
210 PEN 2:PRINT "timer 1":PEN 1
220 RETURN
300 REM #2
310 PEN 2:PRINT "timer 2":PEN 1
320 RETURN
400 REM #3
410 flag=1:PEN 2:PRINT "no more interrupts..."
420 RETURN
</pre>

: Hint: Timing with interrupts is important, especially if more than one interrupts run. If the interval of a subroutine driven by an interrupt is too long than the processor can never get back to deal the main program again. Work out timing by measuring the subroutine or by trial and error.
: There are system internal interrupts (highest level) which cannot be influenced by BASIC interrupts (e.g. keyboard scan > BREAK key.)
: The next level of sytem internal interrupts CAN be influenced by BASIC interrupts. For example the sound queue which will be created by "ON SQ <chanel> GOSUB <line>". Those sound interrupts have an independent time tricker but their priority is parallel to the second priority times of BASICs interrupts. Therefore interrupts with timer 3 could "interrupt" them.

==== <code>FILL i</code> ====
: 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.

==== <code>FN</code> ====
:BASIC allows the program to define and use simple value returning functions. DEF FuNction is the definition part of this mechanism and creates program-specific function which works within the
:program in the same way as a function such a COS operates as a built-in function of BASIC. It may be invoked throughout the program. Variable types must be consistent and the DEF FN
:command should be written in part of the program outside the execution loop.

:Syntax : <code>DEF FN<name>[(<formal parameters>)]=<general expression></code>

:Example: ''"with the definition of..."''
<pre>
10 gn=9.80665
20 DEF FNgrv=s0+v0*t+0.5*gn*t^2
30 s0=0:v0=0:t=5
40 PRINT "...after";t;"seconds your dropped stone falls";FNgrv;"metres"
</pre>
:''"the results are..."''
<pre>
:...after 5 seconds your dropped stone falls 122.58315 metres
</pre>

==== <code>FOR TO STEP NEXT</code> ====
: Creating a counting loop (control strucutre) with a starting condition. Inside the counting loop one or more commands will be executed.
: The loop consists of of following specifications:

: 1. FOR
: 2. ''a control variable''
: 3. =
: 4. ''starting value''
: 5. TO
: 6. ''target value''
: 7. STEP [optional]
: 8. ''increment / step size''
: ''... instructions between''
: 9. NEXT
: 10. ''control variable'' [optional]

: You have to use the command STEP if you wish to count backwards. It's good to name the ''control variable'' after NEXT for readability and better program style.
: After each loop the computer checks internaly if the ''target value'' has been reached (like an IF ... THEN ... ELSE instruction). If the target value is reached NEXT closes the loop and calculates another step, so the ''control variable'' will be changed last time.
: The default STEP value - if not specified - is one (1).

: Example:
<pre>
10 FOR I=1 TO 10
20 PRINT I;
30 NEXT I
40 PRINT I
RUN
1 2 3 4 5 6 7 8 9 10 11
READY
</pre>

==== <code>FRAME</code> ====
: 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.

==== <code>GOSUB i</code> ====

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

==== <code>GOTO i</code> ====
: 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>
: GOTO is the simplest form of a jump or creating a loop '''without''' condition controll.
: ''Example: (unconditional and endless loop)''
<pre>
10 PRINT "#";
20 GOTO 10
</pre>
: Combine the GOTO command with an IF...THEN...ELSE instruction for creating a condition-controlled loop with the '''test at the end'''. Helpful because the Locomotive Basic has no practical DO...WHILE... loop.
: ''Example: (condition at the end)''
<pre>
10 I=1
20 PRINT I
30 I=I+1
40 IF I<25 THEN GOTO 20
50 END
</pre>

==== <code>GRAPHICS</code> ====
: ...works only in combination with the command <code>PEN</code> or <code>PAPER</code> to set the plotting/drawing pen or background colour.
: If the <code>TAG</code> command is used to set text at the graphics cursor <code>GRAPHICS PEN</code> or <code>GRAPHICS PAPER</code> instead of the regular <code>PEN</code> or <code>PAPER</code>is necessary to colour the text.

==== <code>IF THEN ELSE</code> ====
: Asks for a choice with the '''IF...THEN...ELSE''' statement.
: '''IF''' compares the entry condition in a logical way
: '''THEN''' contains instruction if the comparison is true
: '''ELSE''' contains instruction if it's false.
: '''Example:'''
<pre>
10 INPUT "guess a figure:",f
20 IF f=10 THEN PRINT "right": END: ELSE GOTO 10
</pre>
: In case of nested choices there's a possibility to that with an IF...THEN instruction but not very recommended:
<pre>
10 INPUT "guess a figure:",f
20 IF f=10 THEN PRINT "right": END: ELSE IF f<10 THEN PRINT "too small" ELSE PRINT "too big"
30 GOTO 10
</pre>
:Other nested structures like IF...THEN...'''ELSE...ELSE''' won't work first because the Locomotive Basic only looks after the first ELSE instruction found and can't execute more single commands as a block for a certain condition in comparision to e.g. "PASCAL" > begin...end-block, "C" > {...}-block.

==== <code>INK ‹pen›,‹colour›,[‹second colour›]</code> ====
: Used to set the colour palette for each of the 16 available inks.
: pen specifies the pen slot to use.
: colour specifies the system colour to use (0..27.)
: if the second colour is provided, Locomotive Basic will blink between the colour and second colour.
: In MODE 0, all 16 pens are available. In MODE 1, only 4 pens are available (0..3). In MODE 2, only 2 pens are available (0..1.)
: By default, pen 0 is the background colour and pen 1 is the foreground/text colour.
: Examples:
<pre>
10 MODE 2
20 INK 0,3: REM Set background colour to red
30 INK 1,26: REM Set foreground/text colour to white
</pre>

==== <code>INPUT[#‹stream expression›][,]</code> ====
: [...]

==== <code>KEY</code> ====
: [...]

==== <code>LET</code> ====
: Used to define variables. You don't need to use the ''LET'' command because it is just a command which was added for compatibility reasons.
: ''Example:''
<pre>
10 LET a$ = "hello world"
20 PRINT a$
</pre>

==== <code>LINE INPUT [#‹stream expression›][,]‹variable›[,‹variable›] </code>====
: [...]

==== <code>LIST [‹line number›][-[‹line number›]], [#‹stream expression›]</code>====
: A command for listing the Basic program code.
: Possibility for manipulating display is using line numbers with a minus symbol.
: Example:
<pre>
LIST 100-
</pre>
: List every line after line number 100.
<pre>
LIST -100
</pre>
: List every line until line number 100 has reached.
<pre>
LIST 100-200
</pre>
: List every line between line number 100 and 200 included

: With the help of separate window definitions it is possible to print out long listings, better differentiate parts / slices of it into different window predefined
: Example:
<pre>
LIST 1000-1100,#1
LIST 3000-3100,#2
</pre>
: ...prints out two parts of one program out into two windows (if they are defined well)

==== <code>LOAD ‹file name›[,‹address›] </code>====

With this directive you may load any file in memory

Basic files (extension .BAS) are loaded in Basic memory, you cannot choose loading address

Binary files are loaded to the default address location stored in the AMSDOS header but you may force loading address (&C000 for a screen)

TAPE convention:

When loading tape files, the basic display a message every block which may cause trouble. Message output may be disabled by using prefix "!" before the filename.

It's also possible to load the next file disregarding his name using only "!" => <code>LOAD "!"</code>

==== <code>LOCATE[#‹stream expression›][,] x,y</code> ====

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

==== <code>MASK [i1][,i2]</code> ====

: Sets bits in each adjacent group of 8 pixel on (1) or off (0) according to binary value of i1 (0-255). i2 determines whether the first point of the line is to plotted (1) or not (0).

:Example:

<pre>
10 CLG 2:MASK 1:MOVE 0,0:DRAW 500,400
20 MASK 15:MOVE 0,0:DRAW 500,400
</pre>

==== <code>MEMORY ‹memory address›</code> ====

: Allocates the amount of memory to be used by BASIC by setting the [[Locomotive_BASIC#HIMEM|address of the highest byte]] it may use.

==== <code>MERGE</code> ====
: [...]

==== <code>MID$ (‹string›,‹start position›[,‹length of substring›])</code> ====
: With the MID$ command there are two applications possible:

: 1. MID$ creates a new substring out of the give ‹string› and starts at the defined position ‹start position› and print the number of given characters by ‹length of substring›.
: If no length is defined every character from ‹start position› will be printed out.
: If a higher value of ‹start position› or ‹length of substring› than the real length of the initial string is defined a blank string will be printed.
: The range of ‹start position› or ‹length of substring› is from 0 up to 255 characters.

: 2. With MID$ you're able to manipulates given strings by inserting a new string.
: Take care of the two different applications and using in BASIC.

: Example for the 1. application:
<pre>
10 a$="Hello"
20 PRINT MID$(a$,2,2)
run
el
Ready
</pre>
:
: Example for the 2. application
<pre>
10 a$="Hello"
20 MID$(a$,2,3)="ipp"
30 PRINT a$
run
Hippo
Ready
</pre>

==== <code>MODE</code> ====
: Changes the screen mode: MODE 0 is 160×200 in 16 colours, MODE 1 is 320×200 4 colours, MODE 2 is 640×200 2 colours and MODE 3 is 160×200 in 4 colours.

==== <code>MOVE x,y [[,i1][,i2]]</code> ====

: Moves the graphic cursor to position x,y. The parameter i1 may be used to change the pen (drawing) colour. The parameter i2 specifies the logical colour, as in DRAW.

: 4 drawing styles:
<pre>
i2 = 0 normal colour
i2 = 1 XOR colour
i2 = 2 AND colour
i2 = 3 OR colour
</pre>

==== <code>MOVER xr,yr[,[i1][,i2]]</code> ====
: moves the graphic cursor (relative) from current position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as in MOVE.

==== <code>NEW</code> ====
: Clears BASIC RAM which means program and variables. Keeps symbol defintion (if defined) and screen mode without clearing.

==== <code>ON BREAK CONT</code> ====

: Prevents the interruption of program execution by the ESC key.

==== <code>ON BREAK GOSUB ln</code> ====

: Passes control to subroutine at line ln when ESC ESC pressed.

==== <code>ON BREAK STOP</code> ====

: Restores normal function of ESC key during program execution.

==== <code>ON ERROR GOTO ln</code> ====

: Passes the control to line ln if an error is detected in the program.

: ON ERROR GOTO 0, Turns of the error trap, and restores normal error processing.

==== <code>ON variable GOTO ln x1, x2, x3, x4, ...</code> ====

: In case of passing more choices '''ON variable GOTO ln x1, x2, x3, x4, ...''' points to a table with the jumping target.
: '''Example:'''
<pre>
10 PRINT "1. LOAD - 2. SAVE - 3. EXIT"
20 INPUT choice
30 ON choice GOTO 1000, 2000, 3000
40 CLS: GOTO 10
1000 PRINT "1. LOAD":END
2000 PRINT "2. SAVE":END
3000 END
</pre>
:In case that the variable ''choice'' won't fullfil the condition (in a range between line 0 and 65535) the next instruction will be executed (here: Line 40). If "choice" is smaller than 0 an error will occur.

==== <code>ON variable GOSUB ln x1, x2, x3, x4, ...</code> ====

: In case of passing more choices targeting to SUBROUTINES '''ON variable GOSUB ln x1, x2, x3, x4, ...''' points to a jumping table.
: '''Example:'''
<pre>
10 PRINT "1. LOAD - 2. SAVE - 3. EXIT"
20 INPUT choice
30 ON choice GOSUB 1000, 2000, 3000
40 CLS: GOTO 10
1000 PRINT "1. LOAD":RETURN
2000 PRINT "2. SAVE":RETURN
3000 END
</pre>
:In case that the variable ''choice'' won't fullfil the condition (in a range between line 0 and 65535) the next instruction will be executed (here: Line 40). If "choice" is smaller than 0 an error will occur.

==== <code>ON SQ(x) GOSUB ln x1, x2, x3, x4, ...</code> ====
:ON SQ(x) can trigger an interrupt when e.g. a space or free channel in queue.
:Using that command is a one way interrupt trigger and shouldn't be mixed with <code>EVERY</code> or <code>AFTER</code> commands.

:See also the <code>SQ(x)</code> command for more details.

==== <code>OPENIN ‹filename›</code> ====
: Opens the specified data file for reading. It has to be an ASCII file. ( The command <code>CLOSEIN</code> closes reading data file. )
: Read from the file using <code>INPUT #9</code>

==== <code>OPENOUT ‹filename›</code> ====
: Opens the specified data file for writing. It writes an ASCII file. (To close writing use the command <code>CLOSEOUT</code>.)
: Write to the file with PRINT#9.
: No file is likely to be written until enough data is written (e.g. 2KB) or the file has at least 1 byte written and CLOSEOUT is used.
: The following code pattern can be used to set MEMORY and lower HIMEM lower than would normally be allowed. This is often seen in disc loaders. This doesn't cause any file to be written:

OPENOUT"<filename>
MEMORY address
CLOSEOUT

==== <code>ORIGIN x,y[,l,r,t,b]</code> ====
: The command defines the origin ('world reference point') for the graphics coordinate system. Normally the reference origin is in the left, bottom corner of the default screen and has 0,0. So the most left coordinate value could be by default 639 and the most top value 399. Independent from the actual modus (2, 1 or 0) the range for the x coordinate are always 640 points and for the y coordinate 400 points. In theory you are able to address 256,000 pixel but only 128,000 are visible due to the maximal resolution of the hardware.
: <code>x,y</code> are the the new coordinates for the 'world reference '.
: <code>l,r,t,b</code> are optional and set the borders for the new graphical window (works in the same way like the <code>WINDOW</code> command for a text window). l,r,t,b means left, right, tob and bottom coordinates.
: If a new graphical window (borders) is defined every point or drawn line won't be plotted (clipped internally).

: Example (the line drawn will be cutted):
<pre>
ORIGIN 320,200,250,450,100,300
DRAW 0,200
</pre>

==== <code>OUT ‹address›,‹value›</code> ====

: Outputs a value (range of 0-255) to a specific I/O address.
: Watch out http://cpcwiki.eu/index.php/I/O_Port_Summary

==== <code>PAPER[#‹stream expression›][,]</code> ====
: [...]

==== <code>PEN[#‹stream expression›][,]</code> ====
: [...]

==== <code>PLOT</code> ====
: [...]

==== <code>PLOTR</code> ====
: [...]

==== <code>POKE add</code> ====

: Alters contents of memory location add to value i (0-255)

==== <code>PRINT[#‹stream expression›][,]</code> ====
: [...]

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

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

==== <code>RANDOMIZE [seed]</code> ====

: Resets the pseudo-random generator to the given seed (starting value of the 'random' series). 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>

: <code>RANDOMIZE TIME</code> isn't still a 'real' random number but to hit the same series again is pretty hard due to the time elapsed.
: The algorithm used for randomizing is the following: the generator starts with the seed, adds 1, multiplies by 75 (fiddle factor), divides by 65537 and then uses the remainder -1.

==== <code>READ variable</code> ====
: 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>

==== <code>RELEASE chanel</code> ====
: Releases a sound which was hold on (by a SOUND command) before. It uses the same bit matrix like the SOUND command for the first parameter
# (&x00000001) releases chanel A
# (&x00000010) releases chanel B
# (&x00000011) releases chanel A and B
# (&x00000100) releases chanel C
# (&x00000101) releases chanel A and C
# (&x00000110) releases chanel B and C
# (&x00000111) releases chanel A, B and C

:Example:
<pre>
10 SOUND 65,1000,100
20 PRINT"PRESS R TO LET IT SOUND"
30 IF INKEY(50)=-1 THEN 30
40 RELEASE 1
</pre>

==== <code>REM [any text]</code> ====
: Introduces a comment.

==== <code>RENUM [‹newLine›][,‹oldLine› | ,[‹oldLine›],‹step›] </code>====
: Renumbers the lines of the current program.

: By default, the whole program is renumbered starting at line 10 with multiples of ten. Any parameter that is left out defaults to 10. It is important to note that ''jumps'' (<code>GOTO</code>, <code>GOSUB</code> 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 <code>RENUM 100,20,5</code>

<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== <code>RESTORE [line]</code> ====

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

==== <code>RESUME [line] or NEXT</code> ====
: Command causes the program to resume after an error code and if it is interrupted by an '''ON ERROR GOTO''' jump
: So it can either resume
*(if there's no line number stated) at the same line after error code (and if there are more statements in one line)
or
* at the line number stated (optional)
or
* with the NEXT parameter (optional) ... at the line followed by the error line

==== <code>RETURN</code> ====

: Terminates a subroutine and returns control to the line following the GOSUB call (see GOSUB)

==== <code>RUN [line] or "filename"</code> ====
:Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

:If a string is used after RUN command a programm will be loaded and executed from storage medium (e.g. Tape, Disc). With that command protected BASIC programs can be executed.

:Exampel:
<pre>
RUN"disc"
</pre>

==== <code>SAVE "filename" [,filetype][,paramter1,parameter2,parameter3]</code> ====
: Command saves the current BASIC program / content from RAM onto a storage medium (e.g. Tape, Disc)

: Filetype could be:
* ''',A''' for a ASCII file
* ''',B''' for a binary file (store RAM content as it is)
* ''',P''' for a regular, ''protected'' BASIC file
: without that parameter the content will be stored as a regular BASIC file

:The three parameters after filetype could be used in combination with the binary filetype (,B).
* '''''parameter1''''' defines the starting address of memory range
* '''''parameter2''''' defines the length (range of memory)
* '''''parameter3''''' defines the entry point (optional)

==== <code>SOUND</code> ====
: the SOUND command has following shape:
: SOUND '''C'''hannel,'''P'''eriod,'''D'''uration,'''V'''olume,Volume-'''Env'''elope,'''T'''one-'''En'''velope,'''N'''oise

:'''C:''' Selecting channel is done bitwise (combinations are possible of course):

<pre>
(Bit 0) &x00000001 = 1 = channel A (middle)
(Bit 1) &x00000010 = 2 = channel B (left)
(Bit 2) &x00000100 = 4 = channel C (right)
</pre>
:more function about channel are
<pre>
(Bit 3) &x00001000 = 8 = Rendezvous with channel A
(Bit 4) &x00010000 = 16 = Rendesvous with channel B
(Bit 5) &x00100000 = 32 = Rendesvous with channel C
(Bit 6) &x01000000 = 64 = Hold
(Bit 7) &x10000000 = 128 = Flush
</pre>
:'''P:''' the period number can be a figure between 0 and 4095 (2^12-1... 12 means that we have 12 tones (inclusive half-tones) in nine octaves on the CPC in sum and their distance between is the twelves square root of two), where 8 octaves are available. E.g. Octave 0 starts on middle C with number 478.
: To calculate the period you can use following formula: '''period=1,000,000/(16*frequency)''' or in short '''period=(62,500/frequency)'''
: (e.g. the note "A" with the frequency 440 Hz has the period 142 on the CPC)

:'''D:''' the duration of the note is measured in 1/100th of a second and can be any positive number in the range 1-32,767. 0 and negative number are in combination with ENT and ENV commands usefull. A negative number means repititions.

:'''V:''' the volume number range from 0-7 on a CPC 464 (BASIC 1.0) or 0-15 on a CPC664/6128 (BASIC 1.1)

:'''ENV:''' and '''ENT:''' For shaping the sound ENV (Volume) and ENT (Frequency) commands are available. The relation between SOUND and those commands comes with a figure between 1 to 15 for ENV (5th parameter) and 1 to 15 for ENT (6th parameter).

:'''N:''' the seventh parameter can be used for blending in noise between the range of 0-15 (BASIC 1.0) or 0-30 (BASIC 1.1). The higher the number the 'deeper' or 'dirty' is the noise.

==== <code>SPC <n></code> ====
: in conjunction with PRINT the SPC command prints out a certain number (n) of spaces.
: Example:
<pre>
PRINT "Hello";SPC(10);"World";
Hello World
</pre>

==== <code>SPEED INK <n1,n2> </code> ====
: SPEED INK command defines the frequency of colour changes if a colour change was defined. The duration is calculated by n1=... or n2 =duration/50 seconds.

==== <code>SPEED KEY <start,repeat> </code> ====
: SPEED KEY command defines the delay after which a key repeat (for keys that do repeat). The first parameter is the delay before the first repeat and the second parameter is the delay between further repeats. Delay is in 1/50th of seconds.

:When using it with low values, it is common to associate a key to reset the default speed of 30,2.
:For example to associate the key 0 from the numpad:
<pre>
KEY 0,"SPEED KEY 30,2"+CHR$(13)
</pre>

==== <code>SPEED WRITE <n> </code> ====
: SPEED WRITE defines the speed at which data is to be saved or written to a cassette unit. n=1 means 2000 baud, n=0 (default) means 1000 baud. When reading from the tape, the correct speed is automatically selected.

==== <code>SQ (channel)</code> ====

: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1,2,3, = A, B, C

: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

==== <code>STOP</code> ====

: Breaks program execution at line containing the STOP statement. The message '''BREAK in''' is output with the line number.

==== <code>SWAP</code> ====
: SWAP works only in combination with the window command. Every error or status messages from the operating system will be displayed normaly on WINDOW#0 (=''main'' window). WINDOW SWAP changes the ''main'' window to the desired target window.
: Example (if a window with number 4 was defined before...):
<pre>
WINDOW SWAP 0,4
</pre>

==== <code>SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8]</code> ====

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

==== <code>SYMBOL AFTER n</code> ====
: 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.

==== <code>TAB</code> ====
: [...]

==== <code>TAG [#st]</code> ====

: Allows text to print at graphics cursor position.
: see TAGOFF

==== <code>TAGOFF [#st]</code> ====

: Directs text to stream st printing it at previous text cursor position.

==== <code>TROFF</code> ====

: Turns off the program flow trace (see TRON)

==== <code>TRON</code> ====

: Turns on the program flow trace for debugging. Causes the line number of each statement executed to be displayed.

==== <code>USING</code> ====
: The USING assignement defines the format of the PRINT output. Its appointment happens by characters where each has a certain meaning.

'''Numbers / Figures'''
: the character:
:'''#''' stands for a figure between 0 - 9
:'''.''' stands for a decimal point
:'''+''' generates a positive sign if the value is positive
:'''-''' generates a negative sign if the value is nagative
:'''**''' generates a asterix for each empty "location" before the printed character
:'''$$''' generates a Dollar characters before the printed character (the same with the pound note)
:''',''' generates a comma every each three decimals (thousands per figure) and has to be set before the decimal point or at the end if without a decimal point.
:^ generates a scientific notation (with exponents) and a the end of the format appointment

'''Strings'''
: the character:
:'''!''' prints out only the first character
:'''\xxx\''' prints out only with x-numbers defined length of the string (from left to right). x means a blank sign made with the space bar
:'''&''' the whole string is printed out as given (unknown function)

: a print output (numbers) with "%" in the beginning shows that not enough positions has to be declared (at all or before the decimal point).

: Example:
<pre>
10 figure=123456789
20 word$="Hello"
30 print using "+**,##########";figure
40 print using "\ \";word$

creates following output:

*****+12,345,679
Hel
</pre>

==== <code>WAIT add, i1[,i2]</code> ====

: Waits until the I/O port at add returns a value (0-255). The value returned is XORed with i2 and the ANDed with i1. This is repeated until a non-zero result occurs.

==== <code>WHILE WEND</code> ====
: [...]

==== <code>WIDTH</code> ====
: [...]

==== <code>WINDOW[#‹stream expression›],[L],[R],[T],[B]</code> ====
: It is possible to define in BASIC eight (8) independent windows for text output. Overlapping is possible.

: #STREAM: eight window are possible. No. zero (0) is the main window where error or status messages were put out by default.
: each position is included inside the window
: L = left column / R = right column (dependent of the mode 0 = 20 / 1 = 40 / 2 = 80)
: T = top row / B = bottom row (always from 1 to 25)

: Example:
<pre>
MODE 1
WINDOW#1,1,40,1,6
</pre>
: ...defines the first top quarter of the screen for window No. 1

==== <code>WRITE [#st,] v[$], v[$]</code> ====

: Writes the values of the specified variable to the specified stream.

: Example:

<pre>
10 OPENOUT "DUMMY"
20 INPUT A$,A
30 WRITE #9,A$,A
40 CLOSEOUT
</pre>

==== <code>ZONE i</code> ====

: Changes the width of the print zone. Default is 13.
: Example:
<pre>
10 MODE 2
20 PRINT"normal zone (13)"
30 PRINT 1,2,3,4
RUN
normal zone(13)
1 2 3 4
READY
20 PRINT"now with different zone(5)"
30 ZONE 5
40 PRINT 1,2,3,4
RUN
now with different zone(5)
1 2 3 4
READY
</pre>

=== Operators ===
: A logical status in Locomotive Basic will be represented by a "-1" for TRUE and by a "0" for FALSE.
: Example:
<pre>
PRINT (1=1)
-1
PRINT (1=2)
0
</pre>
==== <code>AND</code> ====
: Possible combinations with the AND Function:
<pre>
NPUT1 INPUT2 OUTPUT
======================
TRUE TRUE TRUE
FALSE FALSE FALSE
TRUE FALSE FALSE
FALSE TRUE FALSE
</pre>
: Example:
<pre>
PRINT 128 AND 64
0
</pre>
: looking at the BIT combination for a better understanding:
<pre>
10000000
AND 01000000
================
= 00000000
</pre>
: even in BASIC it is possible to manipulate single BITs although there are no special commands but AND, OR and XOR.
: first an example for a loop with an increasing counter WITHOUT an AND:
<pre>
10 counter=0
20 counter=counter+1
30 IF counter=32 THEN counter=0
40 GOTO 20
</pre>
: then a shorter example WITH and AND:
<pre>
10 counter=0
20 counter=(counter+1) AND 31
30 GOTO 20
</pre>
: in the second example all more significant BITs will be deleted (a common method in assembler programming)
: Beware: it only works here with BIT/number conditions one figure smaller than 1, 3, 7, 15, 31, 63 and 127
==== <code>MOD</code> ====
: '''MOD''' returns a (rounded) rest (Modulos) after dividen has been devided by the devisor.
:
:'''Example:'''
<pre>
32767 mod 256
255
</pre>
: Note: only works with numbers in the range -32768 and 32767 (&8000 < 0 < &7FFF)

==== <code>NOT</code> ====
: '''NOT''' executes a bit for bit '''negation''' of the current value. The output is a 16-Bit-Word.
:
:'''Example:'''
<pre>
10 value1=1
20 value2=NOT value1
30 PRINT value2
run
-2
</pre>
:for a better understanding...
<pre>
10 value1=1
20 PRINT HEX$(value1):PRINT BIN$(value1,8)
30 value2=NOT value1
40 PRINT HEX$(value2):PRINT BIN$(value2,8)
run
1
00000001
FFFE
1111111111111110
</pre>

==== <code>OR</code> ====
: Possible combinations with the OR Function:
<pre>
NPUT1 INPUT2 OUTPUT
======================
TRUE TRUE TRUE
FALSE TRUE TRUE
TRUE FALSE TRUE
FALSE FALSE FALSE
</pre>
==== <code>XOR</code> ====
: Possible combinations with the XOR Function:
<pre>
NPUT1 INPUT2 OUTPUT
======================
TRUE TRUE FALSE
FALSE TRUE TRUE
TRUE FALSE TRUE
FALSE FALSE FALSE
</pre>

=== Functions ===

==== <code><big>ABS (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the ABSolute value of the given numeric expression (n). This means that negative numbers are returned as positive.
: '''Associated keywords''': SGN

: '''Example''':

<pre>
PRINT ABS(-67.98)
67.98
</pre>

==== <code><big>ASC (<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the numeric value of the first character in the <string expression> (s).
: '''Associated keywords''': CHR$

: '''Example''':
<pre>
PRINT ASC("x")
120
</pre>
==== <code><big>ATN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the Arc-TaNgent of the <numeric expression> (n) to a real number ranging from -PI/2 to +PI/2 of the value specified.
: Note that DEG and RAD can be used to force the result of the below calculation to degrees or radians respectively.

: '''Associated keywords''': COS, DEG, RAD, SIN, TAN

: '''Example''':
<pre>
PRINT ATN(1)
0.785398163
</pre>
==== <code><big>BIN$ (<unsigned integer expression>,[<integer expression>])</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Produces a string of BINary digits respresenting the value of the <unsigned integer expression>, using the number of binary digits instruced by the second <integer expression> (in the range of 0 to 16). If the number of digits instructed is too great, the resulting expression will be filled with leading zeros; if the number of digits instructed is too small, the resulting expression will NOT be shortened to the instructed number of digits, but will produced in as many digits as are required.
: The <unsigned integer expression> to be converted into binary form must yield a value in the range -32768 to 65535.
: '''Associated keywords''': DEC$, HEX$, STR$
: '''Example''':
<pre>
PRINT BIN$(66,8)
01000000
</pre>
==== <code><big>CHR$ (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Converts an <integer expression> in the range 0 to 255, to its CHaRacter $tring equivalent, using the AMSTRAD character set shown in the ASCII table or e.g. in the manual part 3.
: Note that 0 to 31 are control characters; hence the below example prints CHR$(x) in the range 32 to 255
: '''Associated keywords''': ASC, LEFT$, RIGHT$, MID$, STR$

: '''Example''':
<pre>
10 FOR X=32 to 255
20 PRINT X;CHR$(X);
30 NEXT
</pre>
: A further 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.

: Control Codes Table:
<pre>
===============================================================================
| VALUE | NAME | PARAMETERS | EFFECT |
===============================================================================
| DEC | HEX | | | |
===============================================================================
| 0 | &00 | NUL | NONE | DOES NOTHING |
| 1 | &01 | SOH | 0-255 | PRINTS CHARACTER TO SCREEN |
| 2 | &02 | STX | NONE | TURNS TEXT CURSOR OFF |
| 3 | &03 | ETX | NONE | TURNS TEXT CURSOR ON IN IMMEDIATE MODE |
| 4 | &04 | EOT | 0-2 | SET SCREEN MODE |
| 5 | &05 | ENQ | 0-255 | PRINT CHARACTER AT GRAPHICS CURS. |
| 6 | &06 | ACK | NONE | TURNS ON TEXT SCREEN (SEE ALSO CHR$(21))|
| 7 | &07 | BEL | NONE | MAKE A SHORT BEEP |
| 8 | &08 | BS | NONE | MOVES TEXT CURSOR BACK ONE CHARACTER |
| 9 | &09 | TAB | NONE | MOVES TEXT CURSOR FORWARD ONE CHARACTER |
| 10 | &0A | LF | NONE | MOVES TEXT CURSOR DOWN ONE CHARACTER |
| 11 | &0B | VT | NONE | MOVES TEXT CURSOR UP ONE CHARACTER |
| 12 | &0C | FF | NONE | CLEARS SCREEN OR WINDOWS (= CLS) |
| 13 | &0D | CR | NONE | MOVES CURSOR TO LEFT EDGE OF WINDOW ON |
| | | | | CURRENT LINE |
| 14 | &0E | SO | 0-15 | SETS PAPER COLOUR |
| 15 | &0F | SI | 0-15 | SETS PEN COLOUR |
| 16 | &10 | DLE | NONE | DELETES CHARACTER UNDER TEXT CURSOR |
| 17 | &11 | DC1 | NONE | CLEARS LINE FROM LEFT OF WINDOW UP TO |
| | | | | AND INCLUDING CURRENT CHARACTER |
| 18 | &12 | DC2 | NONE | CLEARS FROM CURRENT CHARACTER TO RIGHT |
| | | | | EDGE OF THE WINDOW |
| 19 | &13 | DC3 | NONE | CLEARS FROM START OF WINDOW UP TO AND |
| | | | | INCLUDING CURRENT CHARACTER |
| 20 | &14 | DC4 | NONE | CLEARS FROM CURRENT CHARACTER TO END OF |
| | | | | WINDOW |
| 21 | &15 | NAK | NONE | TURNS OFF TEXT SCREEN (SEE ALSO CHR$(6))|
| 22 | &16 | SYN | 0 AND 1 | TURNS TRANSPARENT OPTION OFF AND ON |
| 23 | &17 | ETB | 0-3 | SET GRPAHICS PLOTTING MODE |
| 24 | &18 | CAN | NONE | CHANGE TO INVERSE CHARACTER DISPLAYING |
| 25 | &19 | EM | NINE PARAM. | DEFINES A CHARACTER (= SAME AS SYMBOL) |
| | | | EACH 0-255 | |
| 26 | &1A | SUB | FOUR PARAM. | DEFINES A TEXT WINDOW (=SAME AS WINDOW) |
| | | | 1-80, 1-80 | FROM LEFT, RIGHT, TOP TO BOTTOM |
| | | | 1-25, 1-25 | FROM LEFT, RIGHT, TOP TO BOTTOM |
| 27 | &1B | ESC | NONE | DOES NOTHING ON SCREEN (PRINTER SIGNAL) |
| 28 | &1C | FS | THREE PARAM. | SETS INK COLOUR TO FLASH BETWEEN TWO |
| | | | 0-15, 0-32 | INK NO, COLOUR 1, COLOUR 2 |
| | | | 0-32 | |
| 29 | &1D | GS | TWO PARAM. | SETS BORDER COLOUR TO FLASH BETWEEN TWO |
| | | | 0-31, 0-31 | COLOURS |
| 30 | &1E | RS | NONE | HOMES CURSOR TO TOP LEFT OF SCREEN |
| 31 | &1F | US | TWO PARAM. | MOVES CURSOR TO CELL SPECIFIED BY TWO |
| | | | 1-80, 1-25 | PARAMETERS (=SAME AS LOCATE) |
===============================================================================
</PRE>

==== <code><big>CINT (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the value of the <numeric expression> (n), Converting it to a rounded INTeger in the range -32768 to 32767.

: '''Associated keywords''': CREAL, FIX, INT, ROUND, UNT

: '''Example''':
<pre>
10 n=1.9999
20 PRINT CINT(n)
run
2
</pre>
==== <code><big>COPYCHR$ (#stream)</big></code> ====
: : ''BASIC 1.1''
: '''FUNCTION''': COPies a CHaRacter from the current position in the stream (which MUST be specified). The below program copies a character from location 1,1 (top left), and reproduces it at location 1,20.
: If the character read is not recognized, a null string is returned.

: '''Associated keywords''': LOCATE

: '''Example''':
<pre>
10 CLS
20 PRINT "top corner"
30 LOCATE 1,1
40 a$=COPYCHR$(#0)
50 LOCATE 1,20
60 PRINT a$
</pre>
==== <code><big>COS (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the COSinus of the <numeric expression> (n).
: Note that DEG and RAD can be used to force the result of the below calculation to degrees or radians respectively.

: '''Associated keywords''': ATN, DEG, RAD, SIN

: '''Example''':
<pre>
DEG
PRINT COS(45)
0.707106781
</pre>
==== <code><big>CREAL (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the value of the <numeric expression> (n), Converting it to REAL.

: '''Associated keywords''': CINT

: '''Example''':
<pre>
10 a=PI
20 PRINT CINT(a)
30 PRINT CREAL(a)
run
3
3.14159265
</pre>
==== <code><big>DEC$(<numeric expression>, <format template>)</big></code> ====
: ''BASIC 1.1''
: '''FUNCTIION''': Returns a DECimal string representation of the <numeric expression> (n), using the specified <format template> to control the print format of the resulting string.
: The format template may contain ONLY the characters:

: + - $ £ * # , . ^

: The use of these 'format field specifiers' is described under the keyword PRINT USING.

: '''Associated keyword''': BIN$, HEX$, PRINT USING, STR$

: '''Example''':
<pre>
PRINT DEC$(10^7,"££########,.##")
£10,000,000.00
</pre>
==== <code><big>DERR</big></code> ====
: ''BASIC 1.1''
: '''FUNCTION''': Reports the last error code returned by the disc filing system. The value of DERR may be used to ascertain the particular Disc ERRor that occurred. See the listing of error messages below.

: '''Associated keywords''': ERL, ERR, ERROR, ON ERROR GOTO, RESUME

: '''Example''':
<pre>
LOAD "xyz.abc"

XYZ .ABC not found
Ready
PRINT DERR
146
</pre>
: '''Table of Disc ERRor codes''':
: If AMSDOS has already reported an error, then bit 7 is set, hence the value of DERR is offset by 128.
<pre>
===============================================================================
| VALUE | DERR value | DESCRIPTION |
===============================================================================
| 0 | 0 or 22 | [ESC] has been pressed |
| 14 | 142 (128+14) | The stream is not in a suitable state. |
| 15 | 143 (128+15) | Hard end of file has been reached. |
| 16 | 144 (128+16) | Bad command, usually an incorrect filename. |
| 17 | 145 (128+17) | File already exists. |
| 18 | 146 (128+18) | File does not exists. |
| 19 | 147 (128+19) | Directory is full. |
| 20 | 148 (128+20) | Disc is full. |
| 21 | 149 (128+21) | Disc changed while file were open. |
| 22 | 150 (128+22) | File is Read/Only. |
| 26 | 154 (128+26) | Soft end of file has been detected. |
| | | |
===============================================================================
</pre>
: Other values returned by DERR originate from the disc controller and are bit significant, always with bit 6 set.
: The significance of each bit is as follows:
<pre>
===============================================================================
| BIT | Significance |
===============================================================================
| 0 | Address mark missing. |
| 1 | Not writable - disc is write protected. |
| 2 | No data - can't find the sector. |
| 3 | Drive not ready - no disc in the drive. |
| 4 | Overrun error. |
| 5 | Data error - CRC error. |
| 6 | Always set to 1 to indicate error from disc controller. |
| 7 | Set to 1 if error has already been reported by AMSDOS. |
===============================================================================
</pre>
==== <code><big>EOF</big></code> ====
: ''BASIC 1.1''
: '''FUNCTION''': Checks to see if end of specified file has been reached during input. Returns 0 (false) until the end of file, then -1 (true).

: '''Associated keywords''': OPENIN, CLOSEIN

: This '''example''' reads a file from disc and print it out on screen. Like the "TYPE" command in CP/M or "|TYPE,file" of the UTOPIA-ROM.
<pre>
10 OPENIN "text.txt"
20 WHILE NOT EOF
30 LINE INPUT#9,a$
40 PRINT a$
50 WEND
60 CLOSEIN
</pre>
==== <code><big>ERR</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the number of the last ERRor encountered. See the table below of error messages. In the example below you will see that ERRor number 8 is a 'Line does not exist' error.

: '''Example''':
<pre>
GOTO 500
Line does not exist
Ready
PRINT ERR
8
</pre>
: NOTE: BASIC 1.0 (officially) describes error codes until 30 (without an attached floppy disc controller). 31 & 32 are floppy disc error codes.
: '''Table of ERRor codes''':
<pre>
========================================================================================
| VALUE | NAME | DESCRIPTION |
========================================================================================
| 1 |Unexpected NEXT |A NEXT command has been encountered while not in a |
| | |FOR loop, or the control variable in the NEXT |
| | |command does not match that in the FOR. |
| 2 |Syntax Error |BASIC cannot understand the given line because |
| | |a construct within it is not legal. |
| 3 |Unexpected RETURN |A RETURN command has been encountered when not in a |
| | |subroutine. |
| 4 |DATA exhausted |A READ command has attempted to read beyond the end |
| | |of the last DATA. |
| 5 |Improper Argument |This is a general purpose error. The value of a |
| | |function's argument, or a command parameter is |
| | |invalid in some way. |
| 6 |Overflow |The result of an arithmetic operation has over- |
| | |flowed. This may be a floating point overflow, in |
| | |which case some operation has yielded a value |
| | |greater than 1.7E^38 (approx.). Alternatively, this |
| | |may be the result of a failed attempt to change a |
| | |floating point number to a 16 bit signed integer. |
| 7 |Memory full |The current program or its variables may be simply |
| | |too big, or the control structure is too deeply |
| | |nested (nested GOUSBs, WHILEs or FORs). |
| | |A MEMORY command will give this error if an attempt |
| | |is made to set the top of BASIC's memory too low, or|
| | |to an impossible high value. Note that an open file |
| | |has a buffer allocated to it, and that may restrict |
| | |the values that MEMORY may use. |
| 8 |Line does not exist |The line referenced cannot be found. |
| 9 |Subcript out of range |One of the subscripts in an array reference is too |
| | |big or too small. |
| 10 |Array already dimensioned|One of the arrays in a DIM statement has already |
| | |been declared. |
| 11 |Division by zero |May occur in real division, integer division, |
| | |integer modulus or exponentiation. |
| 12 |Invalid direct command |The last command attempted is not valid in direct |
| | |mode. |
| 13 |Type mismatch |A numeric value has been presented where a string |
| | |value is required or vice versa, or an invalidly |
| | |formed number has been found in READ or INPUT. |
| 14 |String space full |So many strings have been created that there is no |
| | |further room available, even after 'garbage |
| | |collection'. |
| 15 |String too long |Strings exceeds 255 characters in length. May be |
| | |generated by appending strings together. |
| 16 |String expression too |String expressions may generate a number of |
| |complex |intermediate string values. When the number of these|
| | |values exceeds a reasonable limit, this error |
| | |results. |
| 17 |Cannot CONTinue |For one reason or another the current program |
| | |be restarted using CONT. Note that CONT is intended |
| | |for restarting after a STOP command, [ESC][ESC], |
| | |or an error, and that any alteration of the |
| | |program in the meantime makes a restart impossible. |
| 18 |Unknown user function |No DEF FN has been executed for the FN just |
| | |invoked. |
| 19 |RESUME missing |The end of the program has been encountered while |
| | |in error processing mode (i.e. in an ON ERROR GOTO |
| | |routine). |
| 20 |Unexpected RESUME |RESUME is only valid while in error processing mode |
| | |(i.e. in an ON ERROR GOTO routine). |
| 21 |Direct command found |When loading a file, a line without a line number |
| | |has been found. |
| 22 |Operand missing |BASIC has encountered an incomplete expression. |
| 23 |Line too long |A line when converted to BASIC internal-form becomes|
| | |too big. |
| 24 |EOF met |An attempt has been made to read past end of the |
| | |file input stream. |
| 25 |File type error |The file being read is not of a suitable type. |
| | |OPENIN is only prepared to open ASCII text files. |
| | |Similarly, LOAD, RUN, etc, are only prepared to |
| | |deal with file types produces by SAVE. |
| 26 |NEXT missing |Cannot find a NEXT to match a FOR command. A line |
| | |number accompanying this message indicates the FOR |
| | |command to which this error applies. |
| 27 |File already open |An OPENIN or OPENOUT command has been executed |
| | |before the previously opened file has been closed. |
| 28 |Unknown command |BASIC cannot find a taker for an external command, |
| | |i.e. a command preceded by a bar |. |
| 29 |WEND missing |Cannot find a WEND to match a WHILE command. |
| 30 |Unexpected WEND |Encountered a WEND when not in a WHILE loop, or a |
| | |WEND that does not match the current WHILE loop. |
| 31 |File not open |(see 'Disc ERRors above). |
| | |If access attempted when no file was open. |
| 32 |Broken in |(see 'Disc ERRors above). |
| | |If access attempted when no file was open. |
| | | |
| | |If value 31 or 32 are stated, DERR could be |
| | |interrogate to give more detailed information. |
| | |(see example below.) |
========================================================================================
</pre>
: '''Example for ERR 31 / 32''':
<pre>
10 ON ERROR GOTO 1000
20 OPENOUT "myfile.asc"
30 WRITE #9,"test-data"
40 CLOSEOUT
50 END
1000 amsdoserr=(DERR AND &7F):REM mask off bit 7
1010 IF ERR<31 THEN END
1020 IF ERR=31 THEN PRINT "are you sure you've typed line 20 correctly?":END
1030 IF amsdoserr=20 THEN PRINT "disc is full, suggest you use a new data disc":END
1040 IF amsdoserr=&X01001000 THEN PRINT "put a disc in the drive, then press a key":WHILE INKEY$="":WEND:RESUME
1050 END
</pre>
==== <code><big>EXP (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates 'E' to the power given in the <numeric expression> (i), where 'E' is approximately 2,7182818-the number whose natural logarithm is 1.

: '''Associated keywords''': LOG

: '''Example''':
<pre>
PRINT EXP(6.876)
968.743625
</pre>
==== <code><big>FIX (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Unlike CINT, FIX merely removes the part of the numeric expression, to the right of the decimal point, and leaves an integer result, rounding towards zero.

: '''Associated keywords''': CINT, INT, ROUND

: '''Example''':
<pre>
PRINT FIX(9.99999)
9
</pre>
==== <code><big>FRE (<numeric expression>/<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Establishes how much FREe memory remains unused by BASIC. The form FRE("") forces a 'GARBAGE COLLECTION' before returning a value for available space.
: NOTE: BASIC uses only the first 64K of the memory.

: '''Associated keywords''': HIMEM, MEMORY

: '''Examples''':
<pre>
PRINT FRE(0) or PRINT FRE("hello")
PRINT FRE("")
</pre>
==== <code><big>HEX$ (<unsigned integer expression>, <field width>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Produces a $tring of HEXadecimal digits representing the value of the <unsigned integer expression>, using the number of hexadecimal digits instructed by the <field width> (in the range 0 to 16). If the number of digits instructed is too great, the resulting expression will be filled with leading zeros; if the number of digits instructed is too small, the resulting expression will NOT be shortened to the instructed number of digits, but will be produced in as many digits as are required.
: The <unsigned integer expression> to be converted into hexadecimal form must yield a value in the range -32768 to 65535.

: '''Accociated keywords''': BIN$, DEC$, STR$, UNT

: '''Example''':
<pre>
PRINT HEX$(255,4)
00FF
</pre>
==== <code><big>HIMEM</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the address of the Highest byte of Memory use by BASIC, (which may altered by e.g. the MEMROY command).
: Before resetting the highest byte of available memory using the MEMORY command, it is advisable to issue the 'command mm=HIMEM'. You will thereafter be able to return to the previous memory capacity by issuing the command: 'MEMORY mm'
: NOTE: BASIC uses only the first 64K of memory.

: Associated keywords: FRE, MEMORY, SYMBOL, SYMBOL AFTER.

: '''Example''':
...on a CPC464
<pre>
PRINT HIMEM
43903
</pre>
...on a CPC6128
<pre>
PRINT HIMEM
42619
</pre>
==== <code><big>INKEY (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': INterrogates the KEYboard to report which keys are being pressed. The keyboard is scanned every 0.02 (1/50) second.
: The function is useful for spotting whether a certain key is down or up, by detecting the returned value of -1 (which occurs regardless of [SHIFT] and [CONTROL] key status).
: The example below detects when [SHIFT] and V (key number 55) are pressed together, then ends the program. Refer the manual for the key numbers.

: '''Associated keywords''': CLEAR INPUT, INKEY$, JOY

: '''Example''':
<pre>
10 IF INKEY(55)<>32 THEN 10
20 PRINT "You've pressed [SHIFT] and V"
30 CLEAR INPUT
run
</pre>
: The state of [SHIFT] and [CONTROL] in conjunction with the key specified in the <integer expression> is identified as follows:
<pre>
==============================================================================
|Value returned |[SHIFT] |[CTRL] |Specified key |
==============================================================================
|-1 |ignored |ignored |up |
|0 |up |up |down |
|32 |down |up |down |
|128 |up |down |down |
|160 |down |down |down |
==============================================================================
</pre>
==== <code><big>INKEY$</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': INterrogates the KEYboard, returning the current $tring reflecting any key that is pressed. It provides operator interaction without hitting [ENTER] after every answer. If there is a key pressed, then the function responds. If no key is pressed, INKEY$ returns an empty string.
: In the example below, lines 40 and 70 tell the program to loop back to line 30 after interrogating the keyboard string.

: '''Associated keywords''': CLEAR INPUT, INKEY

: '''Example''':
<pre>
10 CLS
20 PRINT "Select Yes or No (Y/N)?"
30 a$=INKEY$
40 IF a$="" THEN 30
50 IF a$="y" OR a$="Y" THEN 80
60 IF a$="N" OR a$="n" THEN 90
70 GOTO 30
80 PRINT "You have selected YES": END
90 PRINT "You have selected NO":
run
</pre>
==== <code><big>INP (‹port number›)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the INPut value from the I/O address specified in the <port number>.

: '''Associated keywords''': OUT, WAIT

: Watch out http://cpcwiki.eu/index.php/I/O_Port_Summary

: '''Example''':
<pre>
PRINT INP(&FF00)
255
Ready
</pre>
==== <code><big>INSTR ([‹startposition›,]‹searched string›, ‹searched for string›)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Searches the first <searched string> expression to find the first occurance of the <searched for string expression<, and reports the position of its occurance within the <searched string>. If the <searched for string> does not occur within the <searched string>, then 0 is reported.
: The position at which to start searching the <searched string> is optionally specifiable using the <start position> parameter which must yield an integer number in the range 1 to 255.

: '''Associated keywords''': none

: '''1. Example''':
<pre>
a$="ABCD":PRINT INSTR(a$,"C")
3
Ready
</pre>
: '''2. Example''':
<pre>
a$="Hello":IF INSTR(a$,"i")<>0 THEN PRINT "no" else a$
no
Ready
</pre>
: '''3. Example''':
<pre>
10 CLS
20 alphabet$="ABCDEFGHIJKLMNOPQRSTUVWXYZ"
30 INPUT "Enter a letter";a$
40 b$=UPPER$(a$)
50 PRINT b$;" is number";
60 PRINT INSTR(alphabet$,b$);
70 PRINT "in the alphabet.":PRINT
80 GOTO 40
run
</pre>
==== <code><big>INT (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Rounds the number to the nearest smaller INTeger, removing any fractional part. Returns then same value as FIX for positive number, but returns one less than FIX for negative numbers which are not already integers.

: '''Associated keyword''': CINT, FIX, ROUND

: '''Example''':
<pre>
PRINT INT(3.99), INT(-3.99)
3 -4
</pre>
==== <code><big>JOY (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': The JOY function reads a bit significant result from the joystick in the <integer expression> (either 0 or 1).
<pre>
================================
|Bit | Value decimal |
================================
|0(up) | 1 |
|1(down) | 2 |
|2(left) | 4 |
|3(right) | 8 |
|4(fire 2) | 16 |
|5(fire 1) | 32 |
================================
</pre>
==== <code><big>LEFT$ (<string expression>, <required length>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the number of characters (in the range 0 to 255) specified in the <required length> parameter (<integer expression>), after extracting them from the LEFT of the <string expression>. If the <string expression> is shorter than the <required length>, the whole <string expression> is returned.

: '''Associated keywords''': MID$, RIGHT$

: '''1. Example''':
<pre>
A$="ABCDEFG":PRINT LEFT$(A$,3) - prints ABC
</pre>
: '''2. Example''':
<pre>
10 CLS
20 a$="AMSTRAD"
30 FOR n=1 to 7
40 PRINT LEFT$(a$,n)
50 NEXT
run
</pre>
==== <code><big>LEN (<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the total number of characters (i.e. the LENgth) of the <string expression>.

: '''Associated keywords''': none

: '''Example''':
<pre>
10 LINE INPUT "Enter a phrase";a$
20 PRINT "The phrase is";
30 PRINT LEN(a$);"characters long."
run
</pre>
==== <code><big>LOG (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the natural LOGarithm (base of ''e'') of <numeric expression> which mustbe greater than zero.

: '''Associated keywords''': EXP, LOG10

: '''Example''':
<pre>
PRINT LOG(9999)
9.21024037
</pre>
==== <code><big>LOG10 (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the logarithm to base 10 of <numeric expression> which must be greater than zero.

: '''Associated keywords''': EXP, LOG

: '''Example''':
<pre>
PRINT LOG10(9999)
3.99995657
</pre>
==== <code><big>LOWER$ (<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns a new string expression which is a copy of the specified <string expression> but in which all alphabetic characters in the range A to Z are converted to lower case. Useful for processing input where the answers may come in mixed upper/lower case.

: '''Associated keywords''': UPPER$

: '''1. Example''':
<pre>
A$="AMSTRAD":PRINT A$="AMSTRAD":PRINT LOWER$(A$)
Amstrad
</pre>
: '''2. Example''':
<pre>
10 a$="SEE HOW THE LETTERS CHANGE TO ... NUMBERS 1234 NOT..."
20 PRINT LOWER$(a$+"LOWER CASE")
see how the letters change to ... numbers 1234 not... LOWER CASE
</pre>
==== <code><big>MAX (<list of: numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the MAXimum value from the <list of: numeric expression>s.

: '''Associated keywords''': MIN

: '''Example''':
<pre>
10 n=66
20 PRINT MAX(1,n,3,6,4,3)
run
66
</pre>
==== <code><big>MIN (<list of: numeric expression>)</big></code> ====
''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the MINimum value from the <list of: numeric expression>s.
: '''Associated keywords''': MAX

: '''Example''':
<pre>
PRINT MIN (3,6,2.999.8,9,)
2.999
</pre>

==== <code><big>PEEK (<address expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the contents of the Z80 memory location specified in the <address expression> which should be in the range &0000 to &FFFF (0 to 65535). In all cases PEEK will return the value at the RAM address specified (not the ROM), and will be in the range &00 to &FF (0 to 255)

: '''Associated keywords''': POKE

: '''Example''':
<pre>
10 MODE 1: ZONE 7
20 WINDOW 1,40,1,2:WINDOW #1,1,40,3,25
30 PRINT "memory-address"
40 LOCATE 20,1:PRINT "memory-contents"
50 FOR n=1 to 65535
60 p=PEEK(n)
70 PRINT #1,n,"(&";HEX$(n);")";
80 PRINT #1,TAB(20);p,"(&";HEX$(p);")"
90 NEXT
run
</pre>
==== <code><big>PI</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': The value of the ratio between the circumference and the diameter of a circle.

: '''Associated keywords''': DEG, RAD

: '''Example''':
<pre>
PRINT PI
3.14159265
</pre>
==== <code><big>POS (#<stream expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current horizontal POSition of the text cursor relative to the left edge of the text window. The <stream expression> MUST be specified, and does NOT default to #0.
: POS(#8) reports the current horizontal carriage position for the printer, where 1 is the extreme left hand edge.
: POS(#9) reports the logical position in the disc file stream, i.e. the number of printing characters sent to the stream since the last carriage return.

: '''Associated keywords''': VPOS, WINDOW
: '''Example''':
<pre>
10 MODE 1: BORDER 0:LOCATE 8,2
20 PRINT "use cursor left/right keys"
30 WINDOW 1,40,12,12:CURSOR 1,1
40 FOR n=1 TO 19:PRINT CHR$(9);:NEXT
50 IF INKEY(1)<>-1 THEN PRINT CHR$(9);
60 IF INKEY(8)<>-1 THEN PRINT CHR$(8);
70 LOCATE #1,2,24
80 PRINT #1,"text cursor ";
90 PRINT #1,"horizontal position = ";
100 PRINT #1,POS(#0):GOTO 50
run
</pre>
==== <code><big>REMAIN (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns count REMAINing count from the delay timer specified in <integer expression> (= timer number in the range 0 to 3), and disable it. If the delay timer was not enabled zero will be returned.

: '''Associated keywords''': AFTER, DI, EI, EVERY

: For the reason that REMAIN is no normal command but a "function" it is necessary in case of a proper functionality to link the command.
: an '''example''' in combination with an interrupt delay timer 1:
<pre>
PRINT REMAIN(1)
</pre>
: or to stop several/all interrupts at the same time...
<pre>
A=REMAIN(0)=REMAIN(1)=REMAIN(2)=REMAIN(3)
</pre>
: Hint: Take care of interrupts due to parallel working (the same cycle time) or if they are stopped with the BREAK key. Interrupts which were disabled for a certain time will be stored in buffer (for a maximum of 128 entries) and made up their task afterwards in the priorisation as declared.
: further '''example''':
<pre>
10 AFTER 500,1 GOSUB 40
20 AFTER 100,2 GOSUB 50
30 PRINT "program running":GOTO 30
40 REM this GOUSB-Routine will not be called as it is disabled in line 80
50 PRINT:PRINT "Timer 1 will now be ";
60 PRINT "disabled by REMAIN."
70 PRINT "Time-units remaining were:";
80 PRINT REMAIN(1)
run
</pre>
==== <code><big>RIGHT$ (<string expression>, <integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the number of characters (in the range 0 to 255) specified in the <integer expression> (=required length) parameter, after extracting them from the RIGHT of the <string expression>. If the <string expression> is shorter than the <integer expression>, the whole <string expression> is returned.

: '''Associated keywords''': LEFT$, MID$

: '''Example''':
<pre>
10 MODE 1:a$="AMSTRAD computer"
20 FOR n=1 TO 16:LOCATE 41-n,n
30 PRINT RIGHT$(a$,n)
40 NEXT
</pre>
==== <code><big>RND [(<numeric expression>)]</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the next RaNDom number in sequence if the <numeric expression> has a positive value or is not specified.
: If the <numeric expression> yields a value of zero, RND returns a copy of the last random number generated.
: If the <numeric expression> yields a negative value, a new random number sequence is started, the first number of which is returned.

: '''Associated keywords''': RANDOMIZE

: '''1. Example''':
<pre>
PRINT RND(0)
0.536703827
Ready
PRINT RND(1)
0.271940658
Ready
PRINT RND(0)
0.271940658
Ready
</pre>
: '''2. Example''':
: Example for generating an integer random number between 1 and 1000
<pre>
10 A=INT((RND(1)*1000)+1)
20 PRINT A
30 GOTO 10
</pre>
: '''3. Example''':
: For generating a random number between a lower and higher border
<pre>
10 INPUT "Low border",low
20 INPUT "High border",high
30 A=INT(RND(1)*(high-low))+low
40 PRINT A
</pre>
: '''4. Example''':
<pre>
10 RANDOMIZE
20 FOR x=1 TO -1 STEP -1
30 PRINT "rnd parameter=";x
40 FOR n=1 TO 6
50 PRINT RND(x)
60 NEXT n,x
run
</pre>

==== <code><big>ROUND (<numeric expression>[,<integer expression>])</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Rounds <numeric expression> to a number of decimal places or to the power of ten specified by <integer expression>. If <integer expression> less than zero, the <numeric expression> is rounded to give an absolute integer with <integer expression> number of zeros before the decimal point.

: '''Associated keywords''': ABS, CINT, FIX, INT
: '''1. Example''':
<pre>
PRINT ROUND(1562.357,2),ROUND(1562.375,-2)
1562.36 1600
</pre>
: '''2. Example''':
<pre>
10 FOR n=4 TO -4 STEP -1
20 PRINT ROUND (1234.5678,n)
30 PRINT "with integer expression";n
40 NEXT
run
</pre>
==== <code><big>SGN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: FUNCTION: Determines the SiGN of the <numeric expression>. Returns -1 if <numeric expression> is less than 0, returns 0 if <numeric expression> = 0, and returns 1 if <numeric expression> is greater than zero.

: '''Associated keywords''': ABS

: '''Example''':
<pre>
10 FOR n=255 to -200 STEP -20
20 PRINT "SGN returns";
30 PRINT SGN(n);"for a value of";n
40 NEXT n
run
</pre>
==== <code><big>SIN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the Real value for the Sine of <numeric expression>, defaulting to the Radian (RAD) measure mode unless otherwise declared by a DEG command.

: '''Associated keywords''': ATN, COS, DEG, RAD, TAN

: '''Example''':
<pre>
10 CLS:DEG:ORIGIN 0,20
20 FOR n=0 to 720
30 y=SIN(n)
40 PLOT n*640/720,198*y:NEXT
50 GOTO 50
run
</pre>
==== <code><big>SPACE$(<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Creates a string of spaces of the given length, (in the range 0 to 255) specified in the <integer expression>.

: '''Associated keywords''': SPC, STRING$, TAB

: '''Example''':
<pre>
10 MODE 1
20 PRINT "Put 9 spaces between me";
30 PRINT SPACE$(9);
40 PRINT "and you!"
run
</pre>
==== <code><big>SQ (<channel>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the state of the Sound Queue for the specified <channel> which must be an integer expression, yielding one the values:
: 1: for channel A
: 2: for channel B
: 4: for channel C
: The SQ function returns a bit significant integer, comprising the following bit settings:
: Bit 0,1 and 2: the number of free entries in the queue
: Bit 3,4 and 5: the rendezvous state at the head of this queue
: Bit 6 : the head of the queue is held
: Bit 7 : the channel is currently active
: ... where Bit 0 is the least significant bit, and Bit 7 is the most significant bit.
: It can be seen, that if Bit 6 is set, Bit 7 cannot be set at the same time, and vice versa. Similarly if Bits 3, 4, or 5 are set, Bit 6 and 7 cannot be set.

: '''Associated keywords''': ON SQ GOSUB, SOUND

: '''Example''':
<pre>
10 SOUND 65,100,100
20 PRINT SQ(1)
run
67
</pre>
==== <code><big>SQR (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the SQuare Root of the specified <numeric expression>.

: '''Associated keywords''': none

: '''Example''':
<pre>
PRINT SQR(9)
3
</pre>
==== <code><big>STR$ (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Converts the <numeric expression> to a decimal STRing representation.
: Useful for converting a number to a string in case of string manipulation. E.g. after converting a figure to a string then the most left character holds the sign: a minus in case the figure is negative and a space in case the figure is positiv.

: '''Associated keywords''': BIN$, DEC$, HEX$, VAL

: '''1. Example''':
<pre>
10 FIGURE=-1599
20 FIGURE$=STR$(FIGURE)
30 PRINT FIGURE$
-1599
</pre>
: '''2. Example''':
<pre>
10 FIGURE=1769
20 FIGURE$=STR$(FIGURE)
30 PRINT FIGURE$
1769
</pre>
: '''NOTE''': (there's a blank on the left-hand of the number "1769")
: If you want to add e.g. zero before the figure in case of a high score with fix digit-number then you're able to add zero(s) in front of a string instead of a figure.

: '''3. Example''':
<pre>
10 a=&FF:REM 255 hex
20 b=&x1111:REM 15 binary
30 c$="***"
40 PRINT c$+STR$(a+b)+c$
run
*** 270***
</pre>

==== <code><big>STRING$ (<length>,<character specifier>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns a string expression consisting of the <character specifier> repeated the number of time (in the range 0 to 255) specified in the <length>.

: '''Associated keywords''': SPACE$

: '''1. Example''':
<pre>
PRINT STRING$(40,"*")
****************************************
</pre>
: '''2. Example''':
<pre>
PRINT STRING(40,42)
****************************************
</pre>
: '''NOTE''': the <character specifier> 42 refers to the ASCII value of the character '*' and is also equivalent to PRINT STRING$(40,CHR$(42))
==== <code><big>TAN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the TANgent of the <numeric expression>, which must be in the range -200,000 to +200,000.
: '''NOTE''': DEG and RAD can be used to force the result of the calculation to degrees or radians respectively.

: '''Associated keywords''': ATN, COS, DEG, RAD, SIN

: '''Example''':
<pre>
PRINT TAN(45)
1.61977519
</pre>

==== <code><big>TEST (<x co-ordinate>,<y co-ordinate>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Moves the graphics cursor to the absolute position specified by the <x> and <y co-ordinate>s, and reports the value of the ink at the new location.

: '''Associated keywords''': MOVE, MOVER, TESTR, XPOS, YPOS

: '''Example''':
<pre>
10 CLS
20 PRINT "Your are using pen number";
30 PRINT TEST(10,386)
40 PRINT "Try changing PENs and MODEs";
50 PRINT "....then RUN again."
run
</pre>
==== <code><big>TESTR (<x offset>,<y offset>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Moves the graphics cursor by the amount specified in the <x> and <y offset>s relative to its current position, and reports the value of the ink at the new location.

: '''Associated keywords''': MOVE, MOVER, TEST, XPOS, YPOS

: '''Example''':
<pre>
10 MODE 0:FOR x=1 TO 15:LOCATE 1,x
20 PEN x:PRINT STRING$(10,143);:NEXT
30 MOVE 200,400:PEN 1
40 FOR n=1 TO 23:LOCATE 12,n
50 PRINT "pen";TESTR(0,-16):NEXT
run
</pre>
==== <code><big>TIME</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the elapsed time since the computer was last switched-on or reset, (excluding periods when reading or writing to disc).
: Each second of real time is equal to the returned value = TIME/300.

: '''Associated keyword''': AFTER, EVERY, WEND, WHILE

: '''Example''':
<pre>
10 CLS:REM clock
20 INPUT "hour";hour
30 INPUT "minute";minute
40 INPUT "second";second
50 CLS:datum=INT(TIME/300)
60 WHILE hour<13
70 WHILE minute<60
80 WHILE tick<60
90 tick=(INT(TIME/300)-datum)+second
100 LOCATE 1,1
110 PRINT USING "## ";hour,minute,tick
120 WEND
130 tick=0:second=0:minute=minute+1
140 GOTO 50
150 WEND
160 minute=0:hour=hour+1
170 WEND
180 hour=1
190 GOTO 60
run
</pre>
==== <code><big>UNT (<address expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Return an integer in the range -32768 to +32767 which is the twos-complement equivalent of the unsigned value of the <address expression>.

: '''Associated keywords''': CINT, FIX, INT, ROUND

: '''Example''':
<pre>
PRINT UNT(&FF66)
-154
</pre>
==== <code><big>UPPER$(<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns a new string expression which is a copy of the specified <string expression> but in which all alphabetic characters in the range A to Z are converted to upper case. The function is useful for processing input which may come in mixed upper / lower case.

: '''Associated keywords''': LOWER$

: '''Example''':
<pre>
10 CLS: a$="my, how you've grown!"
20 PRINT UPPER$(a$)
run
</pre>
==== <code><big>VAL(<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the numeric VALue, (including any negative sign and decimal point) of the first character(s) in the specified <string expression>.
:If the first character is not a number, then 0 is returned. If the first character is a negative sign or decimal point followed by non-numeric characters, a 'Type mismatch' error (13) will be reported.

: '''Associated keywords''': STR$

: '''1. Example''':
<pre>
PRINT VAL("-12.34x"),VAL("A-12")
-12.34 0
</pre>
: '''Exception''': if <se> starts with "&" + character (and it's between "A" and "F") the whole character will be handled like a hexadezimal numeric character (...often used in DATA Loaders). The returning numeric value is a  signed integer (16-Bit Word).
: '''2. Example''':
<pre>
PRINT VAL("&A")
10

PRINT VAL("&7FFF")
32767

PRINT VAL("&8000")
-32768
</pre>
: '''3. Example''':
<pre>
10 CLS: PRINT "I know my times tables!"
20 PRINT:PRINT "Press a key (1 to 9)"
30 a$=INKEY$:IF a$="" THEN 30
40 n=VAL(a$):if n<1 or n>9 then 30
50 FOR x=1 to 12
60 PRINT n;"X";x;"=";n*x
70 NEXT:GOTO 20
run
</pre>
==== <code><big>VPOS (#<stream expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current vertical POSition of the text cursor relative to the top of the text window. The <stream expression> MUST be specified, and does NOT default to #0.

: '''Associated keywords''': POS, WINDOW

: '''Example''':
<pre>
10 MODE 1:BORDER 0:LOCATE 8,2
20 PRINT "use cursor up/down keys"
30 WINDOW 39,39,1,25:CURSOR 1,1
40 LOCATE 1,3
50 IF INKEY(0)<>-1 THEN PRINT CHR$(11);
60 IF INKEY(2)<>-1 THEN PRINT CHR$(10);
70 LOCATE #1,3,24
80 PRINT #1,"text cursor ";
90 PRINT #1,"vertical position =";
100 PRINT #1,VPOS(#0):GOTO 50
run
</pre>
==== <code><big>XPOS</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current horizontal (X)POSition of the graphics cursor.

: '''Associated keywords''': MOVE, MOVER, ORIGIN, YPOS

: '''Example''':
<pre>
10 MODE 1:DRAW 320,200
20 PRINT "graphics cursor X position = ";
30 PRINT XPOS
</pre>
==== <code><big>YPOS</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current vertical (Y)POSition of the graphic cursor.

: '''Associated keywords''': MOVE, MOVER, ORIGIN, XPOS

: '''Example''':
<pre>
10 MODE 1:DRAW 320,200
20 PRINT "graphics cursor Y position = ";
30 PRINT YPOS
</pre>

== Other Basic Dialects available for the CPC ==

*[[BBC Basic]]
*[[C BASIC Compiler|CBASIC]]
*[[BASIC-E]]

== Technical Information ==

* [[Technical_information_about_Locomotive_BASIC]]

== Web links ==

* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]
* [http://rosettacode.org/wiki/Category:Locomotive_Basic Code examples at Rosetta Code]

* [http://cpctech.cpc-live.com/docs/basic.asm Disassembly of Locomotive BASIC v1.1]

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Locomotive BASIC

2025-10-02T13:01:37Z

Arnoldemu: /* OPENOUT ‹filename› */

For other BASIC language versions see the [[:Category:BASIC]]

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

It was availlable directly from in-built ROMs on [[CPC old generation]] and on the [[Plus System Cartridge]] for the [[Plus]] range. [https://benchmarko.github.io/CPCBasic/ Online Interpreter]

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

If you are interested in more information about the different versions of the CPC's BASIC and the technical details, you can have a look at the article "[[Technical information about Locomotive BASIC]]".

Another helpful and further resource of information about BASIC and a similar comprehension to this is Grimware's Website about the CPC http://www.grimware.org/doku.php/documentations/software/locomotive.basic/start

== 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 and Spanish 472 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 472 (British), 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.

== Variables ==
Many contemporary BASIC interpreters only supported the first few characters of a variable name as a discriminator. For example <code>WATER$</code> and <code>WALDO$</code> would refer to the same variable on a Commodore 64 or Apple II. But Locomotive BASIC allowed variable names up to 40 characters in length, so <code>THEQUICKBROWNFOXJUMPEDOVERTHELAZYDOGFAST$</code> and <code>THEQUICKBROWNFOXJUMPEDOVERTHELAZYDOGFATS$</code> could be use as separate variables.

=== Real (Floating Point) Numbers ===

This is the default type for a Locomotive BASIC variables, but can be clarified using <code>!</code> after the variable name, e.g., <code>real!=500.0</code>.
You can force all variables starting with specific letters to be this type by using the <code>DEFREAL</code> keyword.
In many cases you don't want to use these, as they are slower than using the integer type, and use more memory (5 bytes, as opposed to 2).

=== Signed 16-bit Integers ===

Defined using <code>%</code> after the variable name, e.g., <code>integer%=500</code>.
You can force all variables starting with specific letters to be this type by using the <code>DEFINT</code> keyword.
These can store values between -32,768 and 32,767.
To assign a 16-bit value to a signed integer directly, you should give the number in a hexadecimal format, e.g., <code>uint=&c0000</code>.

=== Strings ===

These are defined by using <code>$</code> after the variable name, e.g., <code>str$="Hello"</code>.
You can force all variables starting with specific letters to be this type by using the <code>DEFSTR</code> keyword.
A String can be up to 255 characters long.

== Type Conversions ==

The BASIC functions <code>ROUND</code>, <code>INT</code>, <code>CINT</code> and <code>FIX</code> can be used to convert real numbers into integers taking some care about rounding. The difference is in rounding mode - <code>ROUND</code> rounds to nearest, <code>FIX</code> rounds to zero, <code>INT</code> always rounds down, and <code>CINT</code>rounds up. e.g., <code>value%=INT(3.14)</code>. Note that if you don't specify the % you will actually get a real number still.

To convert an integer to a real number, you can use the <code>UNT</code> function which will take the value supplied and return the two's complement number. e.g., <code>real=UNT(&ABCD)</code>.

<pre>
w=UNT(50000)
Ready
PRINT w
-15536
Ready
█
</pre>

If you want an integer result from division, use the <code>\</code> integer division operator. e.g., <code>int=value\divisor</code>. This is as opposed to the standard <code>/</code> division operator, that can create a real number.

== Command list ==

=== Commands and operators ===

==== <code>AFTER ‹time delay›[,‹timer number›] GOSUB ‹line number› </code>====
: Waits for ‹time delay›/50 seconds and then jumps NON-RECURRING to the subroutine at ‹line number› (see also <code>"EVERY i[,t] GOSUB line"</code>).

==== <code>AUTO [‹line number›][,‹increment›] </code>====
: Automatically generates line numbers starting at ‹line number› with ‹increment› after each entered line number. Use '''[ESC]''' to leave AUTO mode. Default values for ‹line number› and ‹increment› are 10.

: Example:
<pre>AUTO 100,5 :REM generates line numbers 100, 105, 110...</pre>

==== <code>BORDER ‹colour›[,‹colour›] </code>====
: Changes the colour of the border. If the second argument is supplied the border flashes between the two colours.

==== <code>CALL ‹address expression›[,‹list of: parameter›] </code>====
: Allows a machine code routine to be called by BASIC. Variables, string values and constants can be passed to the routine. Values of any supported type can be passed back by supplying a variable with <code>@</code> in front of it. This passes the address of the variable to the routine although it doesn't implicitly know the data type.
: Example:
<pre>CALL 0 :REM resets the computer completely</pre>

==== <code>CAT</code> ====
: Displays the names of the files on the tape or disc. Tape files are displayed in the order they are encountered. Disc files are sorted alphabetically by ACSII code. Only files matching the current user are displayed. Files marked as system are not displayed.
: Examples:
<pre>CAT :REM lists all disc files in alpha-numeric (ASCII) order</pre>

<pre>|TAPE :CAT :REM lists names of all tape files in their storage order</pre>

==== <code>CHAIN ‹file name›[,‹line number expression›] </code>====

:Enables the specified program to be loaded and RUN automatically. If the optional parameter ‹line number expression› is specified, the program execution will commence from that line.

==== <code>CHAIN MERGE ‹file name›[,‹line number expression› | [,[‹line number expression›],DELETE ‹line number range›]] </code>====

:Loads the specified program from tape or disc, merges it into the program in memory, and starts execution of the merged program. The parameter <code>DELETE</code> ‹line number range› is used to delete part of the original program before running it, if required.

==== <code>CLEAR</code> ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.
: The command clear inside a subroutine (<code>GOSUB</code>... <code>RETURN</code>) will also clear the "stack pointer" address of the gosub heap. That means that a RETURN won't work and a GOTO has to be used instead.

==== <code>CLG [‹masked ink›] </code>====
: Clears the graphics screen to colour specified by <code>‹masked ink›</code>. If parameter <code>‹masked ink›</code> is not specified then the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== <code>CLOSEIN</code> ====
: Closes any input file (tape or disc).

==== <code>CLOSEOUT</code> ====
: Closes any output file (tape or disc).

==== <code>CLS [#‹stream expression›]</code>====
: Clears the window specified by ‹stream expression›. If ‹stream expression› is omitted it defaults to #0 (usually the whole screen). The text cursor of the stream is moved to the upper left corner.

==== <code>CONT</code> ====
: CONTinues program execution interrupted either by [ESC] [ESC] or as a result of STOP within a program. A program cannot be continued after being modified.

==== <code>CURSOR ‹expression› </code>====
: <code>‹expression›</code> must be either 0 or 1.

==== <code>DATA x1[,x2,x3...]</code> ====
: 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>

==== <code>DEF</code> ====
: DEF means "define" and comes along with defining a function in case of DEF FN or defining variables in case of DEFREAL, DEFINT or DEFSTR.
: DEF FN must come before using the statement FN.
: DEF with a variable declaration should come before using a variable.
: (see also FN)

==== <code>DEFINT ‹letter range›</code> ====
:Forces all variables(s) starting with the specified letter(s) to be integer variables. Singular letters could be defined or a range by a minus symbol between two letters.

:Examples:
<pre>
20 DEFINT a-z:' sets all variables starting with an A until Z as integer.
</pre>
or
<pre>
10 DEFINT F,S ..... (or 10 DEFINT A-Z)
20 FIRST=111.11:SECOND=22.2
30 PRINT FIRST,SECOND:' prints out 111 22
</pre>

==== <code>DEFREAL ‹letter range›</code> ====
: Sets the default for variable(s) with the specified first letter(s) to a floating point figure.

==== <code>DEFSTR ‹letter range›</code> ====

: Sets the default for variable(s) with the specified first letter(s) to string(s) variables.

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

==== <code>DELETE [first line][-[last line]]</code> ====
: Deletes the current program completely (without arguments) or only the given line or line range. Even
: <code>DELETE -</code>
: is legal, it has the same effect as
: <code>DELETE</code>
: The lines specified do not have to exist, all lines matching the range will be deleted and having no matches does not cause an error.

==== <code>DI</code> ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.
: This means that DI (if it's activated in a subroutine) is useful helping a low-priority-interrupt not to be stopped by a higher-priority-interrupt. RETURN then re-enable the interrupt without EI.

==== <code>DIM a[%|!|$](d1[,d2[,...]])</code> ====

: Creates array <code>a</code> with single or multiple dimensions. You may optionally specify integer (<code>%</code>), real (<code>!</code>) or string (<code>$</code>) type otherwise it defaults to the current type set for the first letter of the array name. <code>d1</code> is size of first dimension-1, <code>d2</code> is size of second dimension-1 and so on. <code>DIM x(10)</code> will create an array with 11 elements, <code>x(0)</code> is the first element, <code>x(10)</code> is the eleventh and last. You can specify as many dimensions as will fit on one 255 character line, which is a maximum of 125. Trying to create an array that already exists will generate an <code>Array already dimensioned</code> error. If an array is not specified by <code>DIM</code> before being accessed, each dimension value defaults to 10. The maximum dimensions that can be created this way is three.

==== <code>DRAW x,y[,[i1][,i2]]</code> ====

: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the drawing style.

: 4 drawing styles:
<pre>
i2 = 0 normal colour
i2 = 1 XOR colour
i2 = 2 AND colour
i2 = 3 OR colour
</pre>
: Example:
<pre>
CLG 2
DRAW 500,400,0 :REM draws a line from 0,0 to 500,400
</pre>

<code>DRAWR xr,yr[,[i1][,i2]]</code> ====

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

<pre>
Move 200,200
DRAWR 100,100,0 - draws a line from 200,200 to 300,300
</pre>

==== <code>EDIT ‹line›</code> ====
: Display 1 program line for editing.

The following keys can be used in editing mode, or during typing in BASIC:

CTRL+TAB - toggle overwrite/insert mode
CTRL+CURSOR LEFT or CTRL+CURSOR UP - go to start of line
CTRL+CURSOR RIGHT or CTRL+CURSOR DOWN - go to end of line
CURSOR LEFT - move left one character
CURSOR RIGHT - move right one character
ESC - quit editing and do not accept changes
ENTER/RETURN - quit editing and accept changes
SHIFT + CURSOR UP/DOWN/LEFT/RIGHT - enter copy mode. You can move the cursor to where you want to copy from. Hold SHIFT and cursors to move copy cursor.
COPY - copy character covered by copy cursor.
DEL - delete character and go back a char
CLR - delete character under cursor
CTRL + CAPS LOCK - toggle shift lock.

==== <code>EI</code> ====
: Enable interrupts which have been disabled by DI

==== <code>END</code> ====
: Indicates end of program

==== <code>ENT ‹tone envelope number›[,‹tone env. section›][,‹tone env. section›][,‹tone env. section›][,‹tone env. section›][,‹tone env. section›]</code> ====
:The ENT command define the TONE shape of a sound which means manipulating the frequency in a certain range.
:The command could looks like:
<pre>
ENT NUMBER,STEPS?,VERTICAL?,HORIZONTAL?
</pre>
:It is possible to define 15 different envelope shapes. So '''NUMBER''' could be 1-15.

:Each '''?''' stands for up to five sections (1-5), where each STEP<>VERTICAL<>HORIZONTAL with the same '''?''' are belong together.

:'''STEP:''' means how many steps in each section (0-127) > one step is 1/100 of a second!
:'''VERTICAL''': means how big is the step size from bottom to top (-128 to 127)
:'''HORIZONTAL''': means how big is the step size from left to right (0-255)

==== <code>ENV ‹volume envelope number›[,‹volume env. section›][,‹volume env. section›][,‹volume env. section›][,‹volume env. section›][,‹volume env. section›]</code> ====
:The ENV command define the VOLUME shape of a sound which means manipulating the loudness in a certain range.
:The command could looks like:
<pre>
ENV NUMBER,STEPS?,VERTICAL?,HORIZONTAL?
</pre>
:It is possible to define 15 different envelope shapes. So '''NUMBER''' could be 1-15.

:Each '''?''' stands for up to five sections (1-5), where each STEP<>VERTICAL<>HORIZONTAL with the same '''?''' are belong together.

:'''STEP:''' means how many steps in each section (0-127) > one step is 1/100 of a second!
:'''VERTICAL''': means how big is the step size from bottom to top (-128 to 127)
:'''HORIZONTAL''': means how big is the step size from left to right (0-255)

==== <code>ERASE v1[% | ! | $][,v2[% | ! | $][,...]]</code> ====
: Erases the specified array(s) and frees the memory used. Must specify existing array(s) or an <code>Improper argument</code> error will be generated.

==== <code>ERL</code> ====

: Returns the line number of the last error encountered.

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

==== <code>EVERY i[,t] GOSUB ln</code> ====

: BASIC branches to the subroutine at line ln EVERY (reccuring) i/50 seconds. (see also "AFTER i[,t] GOSUB line")

: There are 4 delay timers from 0 to 3 which can be specified with ‹timer number›. If omitted ‹timer number› defaults to 0.
: In the case of parallel task has 3 the highest and 0 the lowest priority.
: With DI or EI you can disable or enable the timing interrupt. With REMAIN <timer number> you can also disable an AFTER or EVERY construct and stores the "remaining" time (> REMAIN)
: Interrupts run as long as the main loop / program runs, even the main programm is paused > press ESC only '''once''' not twice for a break.
: It is important to know or realise that low-priority-interrupts which occurs simultanously to higher-priority-interrupts are not lost. Their task remains or handled again after finishing the higher-prio interrupt.

<pre>
10 REM > interrupts
20 EVERY 50,0 GOSUB 100: REM > lowest priority
30 EVERY 100,1 GOSUB 200
40 EVERY 200,2 GOSUB 300:
50 AFTER 1000,3 GOSUB 400: REM > highest priority
60 WHILE flag=0
70 a=a+1:print a
80 WEND
90 END
100 REM #0
110 PEN 2:PRINT "timer 0":PEN 1
120 RETURN
200 REM #1
210 PEN 2:PRINT "timer 1":PEN 1
220 RETURN
300 REM #2
310 PEN 2:PRINT "timer 2":PEN 1
320 RETURN
400 REM #3
410 flag=1:PEN 2:PRINT "no more interrupts..."
420 RETURN
</pre>

: Hint: Timing with interrupts is important, especially if more than one interrupts run. If the interval of a subroutine driven by an interrupt is too long than the processor can never get back to deal the main program again. Work out timing by measuring the subroutine or by trial and error.
: There are system internal interrupts (highest level) which cannot be influenced by BASIC interrupts (e.g. keyboard scan > BREAK key.)
: The next level of sytem internal interrupts CAN be influenced by BASIC interrupts. For example the sound queue which will be created by "ON SQ <chanel> GOSUB <line>". Those sound interrupts have an independent time tricker but their priority is parallel to the second priority times of BASICs interrupts. Therefore interrupts with timer 3 could "interrupt" them.

==== <code>FILL i</code> ====
: 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.

==== <code>FN</code> ====
:BASIC allows the program to define and use simple value returning functions. DEF FuNction is the definition part of this mechanism and creates program-specific function which works within the
:program in the same way as a function such a COS operates as a built-in function of BASIC. It may be invoked throughout the program. Variable types must be consistent and the DEF FN
:command should be written in part of the program outside the execution loop.

:Syntax : <code>DEF FN<name>[(<formal parameters>)]=<general expression></code>

:Example: ''"with the definition of..."''
<pre>
10 gn=9.80665
20 DEF FNgrv=s0+v0*t+0.5*gn*t^2
30 s0=0:v0=0:t=5
40 PRINT "...after";t;"seconds your dropped stone falls";FNgrv;"metres"
</pre>
:''"the results are..."''
<pre>
:...after 5 seconds your dropped stone falls 122.58315 metres
</pre>

==== <code>FOR TO STEP NEXT</code> ====
: Creating a counting loop (control strucutre) with a starting condition. Inside the counting loop one or more commands will be executed.
: The loop consists of of following specifications:

: 1. FOR
: 2. ''a control variable''
: 3. =
: 4. ''starting value''
: 5. TO
: 6. ''target value''
: 7. STEP [optional]
: 8. ''increment / step size''
: ''... instructions between''
: 9. NEXT
: 10. ''control variable'' [optional]

: You have to use the command STEP if you wish to count backwards. It's good to name the ''control variable'' after NEXT for readability and better program style.
: After each loop the computer checks internaly if the ''target value'' has been reached (like an IF ... THEN ... ELSE instruction). If the target value is reached NEXT closes the loop and calculates another step, so the ''control variable'' will be changed last time.
: The default STEP value - if not specified - is one (1).

: Example:
<pre>
10 FOR I=1 TO 10
20 PRINT I;
30 NEXT I
40 PRINT I
RUN
1 2 3 4 5 6 7 8 9 10 11
READY
</pre>

==== <code>FRAME</code> ====
: 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.

==== <code>GOSUB i</code> ====

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

==== <code>GOTO i</code> ====
: 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>
: GOTO is the simplest form of a jump or creating a loop '''without''' condition controll.
: ''Example: (unconditional and endless loop)''
<pre>
10 PRINT "#";
20 GOTO 10
</pre>
: Combine the GOTO command with an IF...THEN...ELSE instruction for creating a condition-controlled loop with the '''test at the end'''. Helpful because the Locomotive Basic has no practical DO...WHILE... loop.
: ''Example: (condition at the end)''
<pre>
10 I=1
20 PRINT I
30 I=I+1
40 IF I<25 THEN GOTO 20
50 END
</pre>

==== <code>GRAPHICS</code> ====
: ...works only in combination with the command <code>PEN</code> or <code>PAPER</code> to set the plotting/drawing pen or background colour.
: If the <code>TAG</code> command is used to set text at the graphics cursor <code>GRAPHICS PEN</code> or <code>GRAPHICS PAPER</code> instead of the regular <code>PEN</code> or <code>PAPER</code>is necessary to colour the text.

==== <code>IF THEN ELSE</code> ====
: Asks for a choice with the '''IF...THEN...ELSE''' statement.
: '''IF''' compares the entry condition in a logical way
: '''THEN''' contains instruction if the comparison is true
: '''ELSE''' contains instruction if it's false.
: '''Example:'''
<pre>
10 INPUT "guess a figure:",f
20 IF f=10 THEN PRINT "right": END: ELSE GOTO 10
</pre>
: In case of nested choices there's a possibility to that with an IF...THEN instruction but not very recommended:
<pre>
10 INPUT "guess a figure:",f
20 IF f=10 THEN PRINT "right": END: ELSE IF f<10 THEN PRINT "too small" ELSE PRINT "too big"
30 GOTO 10
</pre>
:Other nested structures like IF...THEN...'''ELSE...ELSE''' won't work first because the Locomotive Basic only looks after the first ELSE instruction found and can't execute more single commands as a block for a certain condition in comparision to e.g. "PASCAL" > begin...end-block, "C" > {...}-block.

==== <code>INK ‹pen›,‹colour›,[‹second colour›]</code> ====
: Used to set the colour palette for each of the 16 available inks.
: pen specifies the pen slot to use.
: colour specifies the system colour to use (0..27.)
: if the second colour is provided, Locomotive Basic will blink between the colour and second colour.
: In MODE 0, all 16 pens are available. In MODE 1, only 4 pens are available (0..3). In MODE 2, only 2 pens are available (0..1.)
: By default, pen 0 is the background colour and pen 1 is the foreground/text colour.
: Examples:
<pre>
10 MODE 2
20 INK 0,3: REM Set background colour to red
30 INK 1,26: REM Set foreground/text colour to white
</pre>

==== <code>INPUT[#‹stream expression›][,]</code> ====
: [...]

==== <code>KEY</code> ====
: [...]

==== <code>LET</code> ====
: Used to define variables. You don't need to use the ''LET'' command because it is just a command which was added for compatibility reasons.
: ''Example:''
<pre>
10 LET a$ = "hello world"
20 PRINT a$
</pre>

==== <code>LINE INPUT [#‹stream expression›][,]‹variable›[,‹variable›] </code>====
: [...]

==== <code>LIST [‹line number›][-[‹line number›]], [#‹stream expression›]</code>====
: A command for listing the Basic program code.
: Possibility for manipulating display is using line numbers with a minus symbol.
: Example:
<pre>
LIST 100-
</pre>
: List every line after line number 100.
<pre>
LIST -100
</pre>
: List every line until line number 100 has reached.
<pre>
LIST 100-200
</pre>
: List every line between line number 100 and 200 included

: With the help of separate window definitions it is possible to print out long listings, better differentiate parts / slices of it into different window predefined
: Example:
<pre>
LIST 1000-1100,#1
LIST 3000-3100,#2
</pre>
: ...prints out two parts of one program out into two windows (if they are defined well)

==== <code>LOAD ‹file name›[,‹address›] </code>====

With this directive you may load any file in memory

Basic files (extension .BAS) are loaded in Basic memory, you cannot choose loading address

Binary files are loaded to the default address location stored in the AMSDOS header but you may force loading address (&C000 for a screen)

TAPE convention:

When loading tape files, the basic display a message every block which may cause trouble. Message output may be disabled by using prefix "!" before the filename.

It's also possible to load the next file disregarding his name using only "!" => <code>LOAD "!"</code>

==== <code>LOCATE[#‹stream expression›][,] x,y</code> ====

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

==== <code>MASK [i1][,i2]</code> ====

: Sets bits in each adjacent group of 8 pixel on (1) or off (0) according to binary value of i1 (0-255). i2 determines whether the first point of the line is to plotted (1) or not (0).

:Example:

<pre>
10 CLG 2:MASK 1:MOVE 0,0:DRAW 500,400
20 MASK 15:MOVE 0,0:DRAW 500,400
</pre>

==== <code>MEMORY ‹memory address›</code> ====

: Allocates the amount of memory to be used by BASIC by setting the [[Locomotive_BASIC#HIMEM|address of the highest byte]] it may use.

==== <code>MERGE</code> ====
: [...]

==== <code>MID$ (‹string›,‹start position›[,‹length of substring›])</code> ====
: With the MID$ command there are two applications possible:

: 1. MID$ creates a new substring out of the give ‹string› and starts at the defined position ‹start position› and print the number of given characters by ‹length of substring›.
: If no length is defined every character from ‹start position› will be printed out.
: If a higher value of ‹start position› or ‹length of substring› than the real length of the initial string is defined a blank string will be printed.
: The range of ‹start position› or ‹length of substring› is from 0 up to 255 characters.

: 2. With MID$ you're able to manipulates given strings by inserting a new string.
: Take care of the two different applications and using in BASIC.

: Example for the 1. application:
<pre>
10 a$="Hello"
20 PRINT MID$(a$,2,2)
run
el
Ready
</pre>
:
: Example for the 2. application
<pre>
10 a$="Hello"
20 MID$(a$,2,3)="ipp"
30 PRINT a$
run
Hippo
Ready
</pre>

==== <code>MODE</code> ====
: Changes the screen mode: MODE 0 is 160×200 in 16 colours, MODE 1 is 320×200 4 colours, MODE 2 is 640×200 2 colours and MODE 3 is 160×200 in 4 colours.

==== <code>MOVE x,y [[,i1][,i2]]</code> ====

: Moves the graphic cursor to position x,y. The parameter i1 may be used to change the pen (drawing) colour. The parameter i2 specifies the logical colour, as in DRAW.

: 4 drawing styles:
<pre>
i2 = 0 normal colour
i2 = 1 XOR colour
i2 = 2 AND colour
i2 = 3 OR colour
</pre>

==== <code>MOVER xr,yr[,[i1][,i2]]</code> ====
: moves the graphic cursor (relative) from current position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as in MOVE.

==== <code>NEW</code> ====
: Clears BASIC RAM which means program and variables. Keeps symbol defintion (if defined) and screen mode without clearing.

==== <code>ON BREAK CONT</code> ====

: Prevents the interruption of program execution by the ESC key.

==== <code>ON BREAK GOSUB ln</code> ====

: Passes control to subroutine at line ln when ESC ESC pressed.

==== <code>ON BREAK STOP</code> ====

: Restores normal function of ESC key during program execution.

==== <code>ON ERROR GOTO ln</code> ====

: Passes the control to line ln if an error is detected in the program.

: ON ERROR GOTO 0, Turns of the error trap, and restores normal error processing.

==== <code>ON variable GOTO ln x1, x2, x3, x4, ...</code> ====

: In case of passing more choices '''ON variable GOTO ln x1, x2, x3, x4, ...''' points to a table with the jumping target.
: '''Example:'''
<pre>
10 PRINT "1. LOAD - 2. SAVE - 3. EXIT"
20 INPUT choice
30 ON choice GOTO 1000, 2000, 3000
40 CLS: GOTO 10
1000 PRINT "1. LOAD":END
2000 PRINT "2. SAVE":END
3000 END
</pre>
:In case that the variable ''choice'' won't fullfil the condition (in a range between line 0 and 65535) the next instruction will be executed (here: Line 40). If "choice" is smaller than 0 an error will occur.

==== <code>ON variable GOSUB ln x1, x2, x3, x4, ...</code> ====

: In case of passing more choices targeting to SUBROUTINES '''ON variable GOSUB ln x1, x2, x3, x4, ...''' points to a jumping table.
: '''Example:'''
<pre>
10 PRINT "1. LOAD - 2. SAVE - 3. EXIT"
20 INPUT choice
30 ON choice GOSUB 1000, 2000, 3000
40 CLS: GOTO 10
1000 PRINT "1. LOAD":RETURN
2000 PRINT "2. SAVE":RETURN
3000 END
</pre>
:In case that the variable ''choice'' won't fullfil the condition (in a range between line 0 and 65535) the next instruction will be executed (here: Line 40). If "choice" is smaller than 0 an error will occur.

==== <code>ON SQ(x) GOSUB ln x1, x2, x3, x4, ...</code> ====
:ON SQ(x) can trigger an interrupt when e.g. a space or free channel in queue.
:Using that command is a one way interrupt trigger and shouldn't be mixed with <code>EVERY</code> or <code>AFTER</code> commands.

:See also the <code>SQ(x)</code> command for more details.

==== <code>OPENIN ‹filename›</code> ====
: Opens the specified data file for reading. It has to be an ASCII file. ( The command <code>CLOSEIN</code> closes reading data file. )
: Read from the file using <code>INPUT #9</code>

==== <code>OPENOUT ‹filename›</code> ====
: Opens the specified data file for writing. It writes an ASCII file. (To close writing use the command <code>CLOSEOUT</code>.)

Write to the file with PRINT#9.

NOTE: No file is likely to be written until enough data is written (e.g. 2KB) or the file has at least 1 byte written and CLOSEOUT is used.

NOTE: The following pattern can be used to set MEMORY and lower HIMEM lower than would normally be allowed. This doesn't cause any file to be written:

OPENOUT"<filename>
MEMORY address
CLOSEOUT

==== <code>ORIGIN x,y[,l,r,t,b]</code> ====
: The command defines the origin ('world reference point') for the graphics coordinate system. Normally the reference origin is in the left, bottom corner of the default screen and has 0,0. So the most left coordinate value could be by default 639 and the most top value 399. Independent from the actual modus (2, 1 or 0) the range for the x coordinate are always 640 points and for the y coordinate 400 points. In theory you are able to address 256,000 pixel but only 128,000 are visible due to the maximal resolution of the hardware.
: <code>x,y</code> are the the new coordinates for the 'world reference '.
: <code>l,r,t,b</code> are optional and set the borders for the new graphical window (works in the same way like the <code>WINDOW</code> command for a text window). l,r,t,b means left, right, tob and bottom coordinates.
: If a new graphical window (borders) is defined every point or drawn line won't be plotted (clipped internally).

: Example (the line drawn will be cutted):
<pre>
ORIGIN 320,200,250,450,100,300
DRAW 0,200
</pre>

==== <code>OUT ‹address›,‹value›</code> ====

: Outputs a value (range of 0-255) to a specific I/O address.
: Watch out http://cpcwiki.eu/index.php/I/O_Port_Summary

==== <code>PAPER[#‹stream expression›][,]</code> ====
: [...]

==== <code>PEN[#‹stream expression›][,]</code> ====
: [...]

==== <code>PLOT</code> ====
: [...]

==== <code>PLOTR</code> ====
: [...]

==== <code>POKE add</code> ====

: Alters contents of memory location add to value i (0-255)

==== <code>PRINT[#‹stream expression›][,]</code> ====
: [...]

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

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

==== <code>RANDOMIZE [seed]</code> ====

: Resets the pseudo-random generator to the given seed (starting value of the 'random' series). 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>

: <code>RANDOMIZE TIME</code> isn't still a 'real' random number but to hit the same series again is pretty hard due to the time elapsed.
: The algorithm used for randomizing is the following: the generator starts with the seed, adds 1, multiplies by 75 (fiddle factor), divides by 65537 and then uses the remainder -1.

==== <code>READ variable</code> ====
: 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>

==== <code>RELEASE chanel</code> ====
: Releases a sound which was hold on (by a SOUND command) before. It uses the same bit matrix like the SOUND command for the first parameter
# (&x00000001) releases chanel A
# (&x00000010) releases chanel B
# (&x00000011) releases chanel A and B
# (&x00000100) releases chanel C
# (&x00000101) releases chanel A and C
# (&x00000110) releases chanel B and C
# (&x00000111) releases chanel A, B and C

:Example:
<pre>
10 SOUND 65,1000,100
20 PRINT"PRESS R TO LET IT SOUND"
30 IF INKEY(50)=-1 THEN 30
40 RELEASE 1
</pre>

==== <code>REM [any text]</code> ====
: Introduces a comment.

==== <code>RENUM [‹newLine›][,‹oldLine› | ,[‹oldLine›],‹step›] </code>====
: Renumbers the lines of the current program.

: By default, the whole program is renumbered starting at line 10 with multiples of ten. Any parameter that is left out defaults to 10. It is important to note that ''jumps'' (<code>GOTO</code>, <code>GOSUB</code> 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 <code>RENUM 100,20,5</code>

<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== <code>RESTORE [line]</code> ====

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

==== <code>RESUME [line] or NEXT</code> ====
: Command causes the program to resume after an error code and if it is interrupted by an '''ON ERROR GOTO''' jump
: So it can either resume
*(if there's no line number stated) at the same line after error code (and if there are more statements in one line)
or
* at the line number stated (optional)
or
* with the NEXT parameter (optional) ... at the line followed by the error line

==== <code>RETURN</code> ====

: Terminates a subroutine and returns control to the line following the GOSUB call (see GOSUB)

==== <code>RUN [line] or "filename"</code> ====
:Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

:If a string is used after RUN command a programm will be loaded and executed from storage medium (e.g. Tape, Disc). With that command protected BASIC programs can be executed.

:Exampel:
<pre>
RUN"disc"
</pre>

==== <code>SAVE "filename" [,filetype][,paramter1,parameter2,parameter3]</code> ====
: Command saves the current BASIC program / content from RAM onto a storage medium (e.g. Tape, Disc)

: Filetype could be:
* ''',A''' for a ASCII file
* ''',B''' for a binary file (store RAM content as it is)
* ''',P''' for a regular, ''protected'' BASIC file
: without that parameter the content will be stored as a regular BASIC file

:The three parameters after filetype could be used in combination with the binary filetype (,B).
* '''''parameter1''''' defines the starting address of memory range
* '''''parameter2''''' defines the length (range of memory)
* '''''parameter3''''' defines the entry point (optional)

==== <code>SOUND</code> ====
: the SOUND command has following shape:
: SOUND '''C'''hannel,'''P'''eriod,'''D'''uration,'''V'''olume,Volume-'''Env'''elope,'''T'''one-'''En'''velope,'''N'''oise

:'''C:''' Selecting channel is done bitwise (combinations are possible of course):

<pre>
(Bit 0) &x00000001 = 1 = channel A (middle)
(Bit 1) &x00000010 = 2 = channel B (left)
(Bit 2) &x00000100 = 4 = channel C (right)
</pre>
:more function about channel are
<pre>
(Bit 3) &x00001000 = 8 = Rendezvous with channel A
(Bit 4) &x00010000 = 16 = Rendesvous with channel B
(Bit 5) &x00100000 = 32 = Rendesvous with channel C
(Bit 6) &x01000000 = 64 = Hold
(Bit 7) &x10000000 = 128 = Flush
</pre>
:'''P:''' the period number can be a figure between 0 and 4095 (2^12-1... 12 means that we have 12 tones (inclusive half-tones) in nine octaves on the CPC in sum and their distance between is the twelves square root of two), where 8 octaves are available. E.g. Octave 0 starts on middle C with number 478.
: To calculate the period you can use following formula: '''period=1,000,000/(16*frequency)''' or in short '''period=(62,500/frequency)'''
: (e.g. the note "A" with the frequency 440 Hz has the period 142 on the CPC)

:'''D:''' the duration of the note is measured in 1/100th of a second and can be any positive number in the range 1-32,767. 0 and negative number are in combination with ENT and ENV commands usefull. A negative number means repititions.

:'''V:''' the volume number range from 0-7 on a CPC 464 (BASIC 1.0) or 0-15 on a CPC664/6128 (BASIC 1.1)

:'''ENV:''' and '''ENT:''' For shaping the sound ENV (Volume) and ENT (Frequency) commands are available. The relation between SOUND and those commands comes with a figure between 1 to 15 for ENV (5th parameter) and 1 to 15 for ENT (6th parameter).

:'''N:''' the seventh parameter can be used for blending in noise between the range of 0-15 (BASIC 1.0) or 0-30 (BASIC 1.1). The higher the number the 'deeper' or 'dirty' is the noise.

==== <code>SPC <n></code> ====
: in conjunction with PRINT the SPC command prints out a certain number (n) of spaces.
: Example:
<pre>
PRINT "Hello";SPC(10);"World";
Hello World
</pre>

==== <code>SPEED INK <n1,n2> </code> ====
: SPEED INK command defines the frequency of colour changes if a colour change was defined. The duration is calculated by n1=... or n2 =duration/50 seconds.

==== <code>SPEED KEY <start,repeat> </code> ====
: SPEED KEY command defines the delay after which a key repeat (for keys that do repeat). The first parameter is the delay before the first repeat and the second parameter is the delay between further repeats. Delay is in 1/50th of seconds.

:When using it with low values, it is common to associate a key to reset the default speed of 30,2.
:For example to associate the key 0 from the numpad:
<pre>
KEY 0,"SPEED KEY 30,2"+CHR$(13)
</pre>

==== <code>SPEED WRITE <n> </code> ====
: SPEED WRITE defines the speed at which data is to be saved or written to a cassette unit. n=1 means 2000 baud, n=0 (default) means 1000 baud. When reading from the tape, the correct speed is automatically selected.

==== <code>SQ (channel)</code> ====

: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1,2,3, = A, B, C

: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

==== <code>STOP</code> ====

: Breaks program execution at line containing the STOP statement. The message '''BREAK in''' is output with the line number.

==== <code>SWAP</code> ====
: SWAP works only in combination with the window command. Every error or status messages from the operating system will be displayed normaly on WINDOW#0 (=''main'' window). WINDOW SWAP changes the ''main'' window to the desired target window.
: Example (if a window with number 4 was defined before...):
<pre>
WINDOW SWAP 0,4
</pre>

==== <code>SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8]</code> ====

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

==== <code>SYMBOL AFTER n</code> ====
: 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.

==== <code>TAB</code> ====
: [...]

==== <code>TAG [#st]</code> ====

: Allows text to print at graphics cursor position.
: see TAGOFF

==== <code>TAGOFF [#st]</code> ====

: Directs text to stream st printing it at previous text cursor position.

==== <code>TROFF</code> ====

: Turns off the program flow trace (see TRON)

==== <code>TRON</code> ====

: Turns on the program flow trace for debugging. Causes the line number of each statement executed to be displayed.

==== <code>USING</code> ====
: The USING assignement defines the format of the PRINT output. Its appointment happens by characters where each has a certain meaning.

'''Numbers / Figures'''
: the character:
:'''#''' stands for a figure between 0 - 9
:'''.''' stands for a decimal point
:'''+''' generates a positive sign if the value is positive
:'''-''' generates a negative sign if the value is nagative
:'''**''' generates a asterix for each empty "location" before the printed character
:'''$$''' generates a Dollar characters before the printed character (the same with the pound note)
:''',''' generates a comma every each three decimals (thousands per figure) and has to be set before the decimal point or at the end if without a decimal point.
:^ generates a scientific notation (with exponents) and a the end of the format appointment

'''Strings'''
: the character:
:'''!''' prints out only the first character
:'''\xxx\''' prints out only with x-numbers defined length of the string (from left to right). x means a blank sign made with the space bar
:'''&''' the whole string is printed out as given (unknown function)

: a print output (numbers) with "%" in the beginning shows that not enough positions has to be declared (at all or before the decimal point).

: Example:
<pre>
10 figure=123456789
20 word$="Hello"
30 print using "+**,##########";figure
40 print using "\ \";word$

creates following output:

*****+12,345,679
Hel
</pre>

==== <code>WAIT add, i1[,i2]</code> ====

: Waits until the I/O port at add returns a value (0-255). The value returned is XORed with i2 and the ANDed with i1. This is repeated until a non-zero result occurs.

==== <code>WHILE WEND</code> ====
: [...]

==== <code>WIDTH</code> ====
: [...]

==== <code>WINDOW[#‹stream expression›],[L],[R],[T],[B]</code> ====
: It is possible to define in BASIC eight (8) independent windows for text output. Overlapping is possible.

: #STREAM: eight window are possible. No. zero (0) is the main window where error or status messages were put out by default.
: each position is included inside the window
: L = left column / R = right column (dependent of the mode 0 = 20 / 1 = 40 / 2 = 80)
: T = top row / B = bottom row (always from 1 to 25)

: Example:
<pre>
MODE 1
WINDOW#1,1,40,1,6
</pre>
: ...defines the first top quarter of the screen for window No. 1

==== <code>WRITE [#st,] v[$], v[$]</code> ====

: Writes the values of the specified variable to the specified stream.

: Example:

<pre>
10 OPENOUT "DUMMY"
20 INPUT A$,A
30 WRITE #9,A$,A
40 CLOSEOUT
</pre>

==== <code>ZONE i</code> ====

: Changes the width of the print zone. Default is 13.
: Example:
<pre>
10 MODE 2
20 PRINT"normal zone (13)"
30 PRINT 1,2,3,4
RUN
normal zone(13)
1 2 3 4
READY
20 PRINT"now with different zone(5)"
30 ZONE 5
40 PRINT 1,2,3,4
RUN
now with different zone(5)
1 2 3 4
READY
</pre>

=== Operators ===
: A logical status in Locomotive Basic will be represented by a "-1" for TRUE and by a "0" for FALSE.
: Example:
<pre>
PRINT (1=1)
-1
PRINT (1=2)
0
</pre>
==== <code>AND</code> ====
: Possible combinations with the AND Function:
<pre>
NPUT1 INPUT2 OUTPUT
======================
TRUE TRUE TRUE
FALSE FALSE FALSE
TRUE FALSE FALSE
FALSE TRUE FALSE
</pre>
: Example:
<pre>
PRINT 128 AND 64
0
</pre>
: looking at the BIT combination for a better understanding:
<pre>
10000000
AND 01000000
================
= 00000000
</pre>
: even in BASIC it is possible to manipulate single BITs although there are no special commands but AND, OR and XOR.
: first an example for a loop with an increasing counter WITHOUT an AND:
<pre>
10 counter=0
20 counter=counter+1
30 IF counter=32 THEN counter=0
40 GOTO 20
</pre>
: then a shorter example WITH and AND:
<pre>
10 counter=0
20 counter=(counter+1) AND 31
30 GOTO 20
</pre>
: in the second example all more significant BITs will be deleted (a common method in assembler programming)
: Beware: it only works here with BIT/number conditions one figure smaller than 1, 3, 7, 15, 31, 63 and 127
==== <code>MOD</code> ====
: '''MOD''' returns a (rounded) rest (Modulos) after dividen has been devided by the devisor.
:
:'''Example:'''
<pre>
32767 mod 256
255
</pre>
: Note: only works with numbers in the range -32768 and 32767 (&8000 < 0 < &7FFF)

==== <code>NOT</code> ====
: '''NOT''' executes a bit for bit '''negation''' of the current value. The output is a 16-Bit-Word.
:
:'''Example:'''
<pre>
10 value1=1
20 value2=NOT value1
30 PRINT value2
run
-2
</pre>
:for a better understanding...
<pre>
10 value1=1
20 PRINT HEX$(value1):PRINT BIN$(value1,8)
30 value2=NOT value1
40 PRINT HEX$(value2):PRINT BIN$(value2,8)
run
1
00000001
FFFE
1111111111111110
</pre>

==== <code>OR</code> ====
: Possible combinations with the OR Function:
<pre>
NPUT1 INPUT2 OUTPUT
======================
TRUE TRUE TRUE
FALSE TRUE TRUE
TRUE FALSE TRUE
FALSE FALSE FALSE
</pre>
==== <code>XOR</code> ====
: Possible combinations with the XOR Function:
<pre>
NPUT1 INPUT2 OUTPUT
======================
TRUE TRUE FALSE
FALSE TRUE TRUE
TRUE FALSE TRUE
FALSE FALSE FALSE
</pre>

=== Functions ===

==== <code><big>ABS (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the ABSolute value of the given numeric expression (n). This means that negative numbers are returned as positive.
: '''Associated keywords''': SGN

: '''Example''':

<pre>
PRINT ABS(-67.98)
67.98
</pre>

==== <code><big>ASC (<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the numeric value of the first character in the <string expression> (s).
: '''Associated keywords''': CHR$

: '''Example''':
<pre>
PRINT ASC("x")
120
</pre>
==== <code><big>ATN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the Arc-TaNgent of the <numeric expression> (n) to a real number ranging from -PI/2 to +PI/2 of the value specified.
: Note that DEG and RAD can be used to force the result of the below calculation to degrees or radians respectively.

: '''Associated keywords''': COS, DEG, RAD, SIN, TAN

: '''Example''':
<pre>
PRINT ATN(1)
0.785398163
</pre>
==== <code><big>BIN$ (<unsigned integer expression>,[<integer expression>])</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Produces a string of BINary digits respresenting the value of the <unsigned integer expression>, using the number of binary digits instruced by the second <integer expression> (in the range of 0 to 16). If the number of digits instructed is too great, the resulting expression will be filled with leading zeros; if the number of digits instructed is too small, the resulting expression will NOT be shortened to the instructed number of digits, but will produced in as many digits as are required.
: The <unsigned integer expression> to be converted into binary form must yield a value in the range -32768 to 65535.
: '''Associated keywords''': DEC$, HEX$, STR$
: '''Example''':
<pre>
PRINT BIN$(66,8)
01000000
</pre>
==== <code><big>CHR$ (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Converts an <integer expression> in the range 0 to 255, to its CHaRacter $tring equivalent, using the AMSTRAD character set shown in the ASCII table or e.g. in the manual part 3.
: Note that 0 to 31 are control characters; hence the below example prints CHR$(x) in the range 32 to 255
: '''Associated keywords''': ASC, LEFT$, RIGHT$, MID$, STR$

: '''Example''':
<pre>
10 FOR X=32 to 255
20 PRINT X;CHR$(X);
30 NEXT
</pre>
: A further 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.

: Control Codes Table:
<pre>
===============================================================================
| VALUE | NAME | PARAMETERS | EFFECT |
===============================================================================
| DEC | HEX | | | |
===============================================================================
| 0 | &00 | NUL | NONE | DOES NOTHING |
| 1 | &01 | SOH | 0-255 | PRINTS CHARACTER TO SCREEN |
| 2 | &02 | STX | NONE | TURNS TEXT CURSOR OFF |
| 3 | &03 | ETX | NONE | TURNS TEXT CURSOR ON IN IMMEDIATE MODE |
| 4 | &04 | EOT | 0-2 | SET SCREEN MODE |
| 5 | &05 | ENQ | 0-255 | PRINT CHARACTER AT GRAPHICS CURS. |
| 6 | &06 | ACK | NONE | TURNS ON TEXT SCREEN (SEE ALSO CHR$(21))|
| 7 | &07 | BEL | NONE | MAKE A SHORT BEEP |
| 8 | &08 | BS | NONE | MOVES TEXT CURSOR BACK ONE CHARACTER |
| 9 | &09 | TAB | NONE | MOVES TEXT CURSOR FORWARD ONE CHARACTER |
| 10 | &0A | LF | NONE | MOVES TEXT CURSOR DOWN ONE CHARACTER |
| 11 | &0B | VT | NONE | MOVES TEXT CURSOR UP ONE CHARACTER |
| 12 | &0C | FF | NONE | CLEARS SCREEN OR WINDOWS (= CLS) |
| 13 | &0D | CR | NONE | MOVES CURSOR TO LEFT EDGE OF WINDOW ON |
| | | | | CURRENT LINE |
| 14 | &0E | SO | 0-15 | SETS PAPER COLOUR |
| 15 | &0F | SI | 0-15 | SETS PEN COLOUR |
| 16 | &10 | DLE | NONE | DELETES CHARACTER UNDER TEXT CURSOR |
| 17 | &11 | DC1 | NONE | CLEARS LINE FROM LEFT OF WINDOW UP TO |
| | | | | AND INCLUDING CURRENT CHARACTER |
| 18 | &12 | DC2 | NONE | CLEARS FROM CURRENT CHARACTER TO RIGHT |
| | | | | EDGE OF THE WINDOW |
| 19 | &13 | DC3 | NONE | CLEARS FROM START OF WINDOW UP TO AND |
| | | | | INCLUDING CURRENT CHARACTER |
| 20 | &14 | DC4 | NONE | CLEARS FROM CURRENT CHARACTER TO END OF |
| | | | | WINDOW |
| 21 | &15 | NAK | NONE | TURNS OFF TEXT SCREEN (SEE ALSO CHR$(6))|
| 22 | &16 | SYN | 0 AND 1 | TURNS TRANSPARENT OPTION OFF AND ON |
| 23 | &17 | ETB | 0-3 | SET GRPAHICS PLOTTING MODE |
| 24 | &18 | CAN | NONE | CHANGE TO INVERSE CHARACTER DISPLAYING |
| 25 | &19 | EM | NINE PARAM. | DEFINES A CHARACTER (= SAME AS SYMBOL) |
| | | | EACH 0-255 | |
| 26 | &1A | SUB | FOUR PARAM. | DEFINES A TEXT WINDOW (=SAME AS WINDOW) |
| | | | 1-80, 1-80 | FROM LEFT, RIGHT, TOP TO BOTTOM |
| | | | 1-25, 1-25 | FROM LEFT, RIGHT, TOP TO BOTTOM |
| 27 | &1B | ESC | NONE | DOES NOTHING ON SCREEN (PRINTER SIGNAL) |
| 28 | &1C | FS | THREE PARAM. | SETS INK COLOUR TO FLASH BETWEEN TWO |
| | | | 0-15, 0-32 | INK NO, COLOUR 1, COLOUR 2 |
| | | | 0-32 | |
| 29 | &1D | GS | TWO PARAM. | SETS BORDER COLOUR TO FLASH BETWEEN TWO |
| | | | 0-31, 0-31 | COLOURS |
| 30 | &1E | RS | NONE | HOMES CURSOR TO TOP LEFT OF SCREEN |
| 31 | &1F | US | TWO PARAM. | MOVES CURSOR TO CELL SPECIFIED BY TWO |
| | | | 1-80, 1-25 | PARAMETERS (=SAME AS LOCATE) |
===============================================================================
</PRE>

==== <code><big>CINT (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the value of the <numeric expression> (n), Converting it to a rounded INTeger in the range -32768 to 32767.

: '''Associated keywords''': CREAL, FIX, INT, ROUND, UNT

: '''Example''':
<pre>
10 n=1.9999
20 PRINT CINT(n)
run
2
</pre>
==== <code><big>COPYCHR$ (#stream)</big></code> ====
: : ''BASIC 1.1''
: '''FUNCTION''': COPies a CHaRacter from the current position in the stream (which MUST be specified). The below program copies a character from location 1,1 (top left), and reproduces it at location 1,20.
: If the character read is not recognized, a null string is returned.

: '''Associated keywords''': LOCATE

: '''Example''':
<pre>
10 CLS
20 PRINT "top corner"
30 LOCATE 1,1
40 a$=COPYCHR$(#0)
50 LOCATE 1,20
60 PRINT a$
</pre>
==== <code><big>COS (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the COSinus of the <numeric expression> (n).
: Note that DEG and RAD can be used to force the result of the below calculation to degrees or radians respectively.

: '''Associated keywords''': ATN, DEG, RAD, SIN

: '''Example''':
<pre>
DEG
PRINT COS(45)
0.707106781
</pre>
==== <code><big>CREAL (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the value of the <numeric expression> (n), Converting it to REAL.

: '''Associated keywords''': CINT

: '''Example''':
<pre>
10 a=PI
20 PRINT CINT(a)
30 PRINT CREAL(a)
run
3
3.14159265
</pre>
==== <code><big>DEC$(<numeric expression>, <format template>)</big></code> ====
: ''BASIC 1.1''
: '''FUNCTIION''': Returns a DECimal string representation of the <numeric expression> (n), using the specified <format template> to control the print format of the resulting string.
: The format template may contain ONLY the characters:

: + - $ £ * # , . ^

: The use of these 'format field specifiers' is described under the keyword PRINT USING.

: '''Associated keyword''': BIN$, HEX$, PRINT USING, STR$

: '''Example''':
<pre>
PRINT DEC$(10^7,"££########,.##")
£10,000,000.00
</pre>
==== <code><big>DERR</big></code> ====
: ''BASIC 1.1''
: '''FUNCTION''': Reports the last error code returned by the disc filing system. The value of DERR may be used to ascertain the particular Disc ERRor that occurred. See the listing of error messages below.

: '''Associated keywords''': ERL, ERR, ERROR, ON ERROR GOTO, RESUME

: '''Example''':
<pre>
LOAD "xyz.abc"

XYZ .ABC not found
Ready
PRINT DERR
146
</pre>
: '''Table of Disc ERRor codes''':
: If AMSDOS has already reported an error, then bit 7 is set, hence the value of DERR is offset by 128.
<pre>
===============================================================================
| VALUE | DERR value | DESCRIPTION |
===============================================================================
| 0 | 0 or 22 | [ESC] has been pressed |
| 14 | 142 (128+14) | The stream is not in a suitable state. |
| 15 | 143 (128+15) | Hard end of file has been reached. |
| 16 | 144 (128+16) | Bad command, usually an incorrect filename. |
| 17 | 145 (128+17) | File already exists. |
| 18 | 146 (128+18) | File does not exists. |
| 19 | 147 (128+19) | Directory is full. |
| 20 | 148 (128+20) | Disc is full. |
| 21 | 149 (128+21) | Disc changed while file were open. |
| 22 | 150 (128+22) | File is Read/Only. |
| 26 | 154 (128+26) | Soft end of file has been detected. |
| | | |
===============================================================================
</pre>
: Other values returned by DERR originate from the disc controller and are bit significant, always with bit 6 set.
: The significance of each bit is as follows:
<pre>
===============================================================================
| BIT | Significance |
===============================================================================
| 0 | Address mark missing. |
| 1 | Not writable - disc is write protected. |
| 2 | No data - can't find the sector. |
| 3 | Drive not ready - no disc in the drive. |
| 4 | Overrun error. |
| 5 | Data error - CRC error. |
| 6 | Always set to 1 to indicate error from disc controller. |
| 7 | Set to 1 if error has already been reported by AMSDOS. |
===============================================================================
</pre>
==== <code><big>EOF</big></code> ====
: ''BASIC 1.1''
: '''FUNCTION''': Checks to see if end of specified file has been reached during input. Returns 0 (false) until the end of file, then -1 (true).

: '''Associated keywords''': OPENIN, CLOSEIN

: This '''example''' reads a file from disc and print it out on screen. Like the "TYPE" command in CP/M or "|TYPE,file" of the UTOPIA-ROM.
<pre>
10 OPENIN "text.txt"
20 WHILE NOT EOF
30 LINE INPUT#9,a$
40 PRINT a$
50 WEND
60 CLOSEIN
</pre>
==== <code><big>ERR</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the number of the last ERRor encountered. See the table below of error messages. In the example below you will see that ERRor number 8 is a 'Line does not exist' error.

: '''Example''':
<pre>
GOTO 500
Line does not exist
Ready
PRINT ERR
8
</pre>
: NOTE: BASIC 1.0 (officially) describes error codes until 30 (without an attached floppy disc controller). 31 & 32 are floppy disc error codes.
: '''Table of ERRor codes''':
<pre>
========================================================================================
| VALUE | NAME | DESCRIPTION |
========================================================================================
| 1 |Unexpected NEXT |A NEXT command has been encountered while not in a |
| | |FOR loop, or the control variable in the NEXT |
| | |command does not match that in the FOR. |
| 2 |Syntax Error |BASIC cannot understand the given line because |
| | |a construct within it is not legal. |
| 3 |Unexpected RETURN |A RETURN command has been encountered when not in a |
| | |subroutine. |
| 4 |DATA exhausted |A READ command has attempted to read beyond the end |
| | |of the last DATA. |
| 5 |Improper Argument |This is a general purpose error. The value of a |
| | |function's argument, or a command parameter is |
| | |invalid in some way. |
| 6 |Overflow |The result of an arithmetic operation has over- |
| | |flowed. This may be a floating point overflow, in |
| | |which case some operation has yielded a value |
| | |greater than 1.7E^38 (approx.). Alternatively, this |
| | |may be the result of a failed attempt to change a |
| | |floating point number to a 16 bit signed integer. |
| 7 |Memory full |The current program or its variables may be simply |
| | |too big, or the control structure is too deeply |
| | |nested (nested GOUSBs, WHILEs or FORs). |
| | |A MEMORY command will give this error if an attempt |
| | |is made to set the top of BASIC's memory too low, or|
| | |to an impossible high value. Note that an open file |
| | |has a buffer allocated to it, and that may restrict |
| | |the values that MEMORY may use. |
| 8 |Line does not exist |The line referenced cannot be found. |
| 9 |Subcript out of range |One of the subscripts in an array reference is too |
| | |big or too small. |
| 10 |Array already dimensioned|One of the arrays in a DIM statement has already |
| | |been declared. |
| 11 |Division by zero |May occur in real division, integer division, |
| | |integer modulus or exponentiation. |
| 12 |Invalid direct command |The last command attempted is not valid in direct |
| | |mode. |
| 13 |Type mismatch |A numeric value has been presented where a string |
| | |value is required or vice versa, or an invalidly |
| | |formed number has been found in READ or INPUT. |
| 14 |String space full |So many strings have been created that there is no |
| | |further room available, even after 'garbage |
| | |collection'. |
| 15 |String too long |Strings exceeds 255 characters in length. May be |
| | |generated by appending strings together. |
| 16 |String expression too |String expressions may generate a number of |
| |complex |intermediate string values. When the number of these|
| | |values exceeds a reasonable limit, this error |
| | |results. |
| 17 |Cannot CONTinue |For one reason or another the current program |
| | |be restarted using CONT. Note that CONT is intended |
| | |for restarting after a STOP command, [ESC][ESC], |
| | |or an error, and that any alteration of the |
| | |program in the meantime makes a restart impossible. |
| 18 |Unknown user function |No DEF FN has been executed for the FN just |
| | |invoked. |
| 19 |RESUME missing |The end of the program has been encountered while |
| | |in error processing mode (i.e. in an ON ERROR GOTO |
| | |routine). |
| 20 |Unexpected RESUME |RESUME is only valid while in error processing mode |
| | |(i.e. in an ON ERROR GOTO routine). |
| 21 |Direct command found |When loading a file, a line without a line number |
| | |has been found. |
| 22 |Operand missing |BASIC has encountered an incomplete expression. |
| 23 |Line too long |A line when converted to BASIC internal-form becomes|
| | |too big. |
| 24 |EOF met |An attempt has been made to read past end of the |
| | |file input stream. |
| 25 |File type error |The file being read is not of a suitable type. |
| | |OPENIN is only prepared to open ASCII text files. |
| | |Similarly, LOAD, RUN, etc, are only prepared to |
| | |deal with file types produces by SAVE. |
| 26 |NEXT missing |Cannot find a NEXT to match a FOR command. A line |
| | |number accompanying this message indicates the FOR |
| | |command to which this error applies. |
| 27 |File already open |An OPENIN or OPENOUT command has been executed |
| | |before the previously opened file has been closed. |
| 28 |Unknown command |BASIC cannot find a taker for an external command, |
| | |i.e. a command preceded by a bar |. |
| 29 |WEND missing |Cannot find a WEND to match a WHILE command. |
| 30 |Unexpected WEND |Encountered a WEND when not in a WHILE loop, or a |
| | |WEND that does not match the current WHILE loop. |
| 31 |File not open |(see 'Disc ERRors above). |
| | |If access attempted when no file was open. |
| 32 |Broken in |(see 'Disc ERRors above). |
| | |If access attempted when no file was open. |
| | | |
| | |If value 31 or 32 are stated, DERR could be |
| | |interrogate to give more detailed information. |
| | |(see example below.) |
========================================================================================
</pre>
: '''Example for ERR 31 / 32''':
<pre>
10 ON ERROR GOTO 1000
20 OPENOUT "myfile.asc"
30 WRITE #9,"test-data"
40 CLOSEOUT
50 END
1000 amsdoserr=(DERR AND &7F):REM mask off bit 7
1010 IF ERR<31 THEN END
1020 IF ERR=31 THEN PRINT "are you sure you've typed line 20 correctly?":END
1030 IF amsdoserr=20 THEN PRINT "disc is full, suggest you use a new data disc":END
1040 IF amsdoserr=&X01001000 THEN PRINT "put a disc in the drive, then press a key":WHILE INKEY$="":WEND:RESUME
1050 END
</pre>
==== <code><big>EXP (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates 'E' to the power given in the <numeric expression> (i), where 'E' is approximately 2,7182818-the number whose natural logarithm is 1.

: '''Associated keywords''': LOG

: '''Example''':
<pre>
PRINT EXP(6.876)
968.743625
</pre>
==== <code><big>FIX (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Unlike CINT, FIX merely removes the part of the numeric expression, to the right of the decimal point, and leaves an integer result, rounding towards zero.

: '''Associated keywords''': CINT, INT, ROUND

: '''Example''':
<pre>
PRINT FIX(9.99999)
9
</pre>
==== <code><big>FRE (<numeric expression>/<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Establishes how much FREe memory remains unused by BASIC. The form FRE("") forces a 'GARBAGE COLLECTION' before returning a value for available space.
: NOTE: BASIC uses only the first 64K of the memory.

: '''Associated keywords''': HIMEM, MEMORY

: '''Examples''':
<pre>
PRINT FRE(0) or PRINT FRE("hello")
PRINT FRE("")
</pre>
==== <code><big>HEX$ (<unsigned integer expression>, <field width>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Produces a $tring of HEXadecimal digits representing the value of the <unsigned integer expression>, using the number of hexadecimal digits instructed by the <field width> (in the range 0 to 16). If the number of digits instructed is too great, the resulting expression will be filled with leading zeros; if the number of digits instructed is too small, the resulting expression will NOT be shortened to the instructed number of digits, but will be produced in as many digits as are required.
: The <unsigned integer expression> to be converted into hexadecimal form must yield a value in the range -32768 to 65535.

: '''Accociated keywords''': BIN$, DEC$, STR$, UNT

: '''Example''':
<pre>
PRINT HEX$(255,4)
00FF
</pre>
==== <code><big>HIMEM</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the address of the Highest byte of Memory use by BASIC, (which may altered by e.g. the MEMROY command).
: Before resetting the highest byte of available memory using the MEMORY command, it is advisable to issue the 'command mm=HIMEM'. You will thereafter be able to return to the previous memory capacity by issuing the command: 'MEMORY mm'
: NOTE: BASIC uses only the first 64K of memory.

: Associated keywords: FRE, MEMORY, SYMBOL, SYMBOL AFTER.

: '''Example''':
...on a CPC464
<pre>
PRINT HIMEM
43903
</pre>
...on a CPC6128
<pre>
PRINT HIMEM
42619
</pre>
==== <code><big>INKEY (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': INterrogates the KEYboard to report which keys are being pressed. The keyboard is scanned every 0.02 (1/50) second.
: The function is useful for spotting whether a certain key is down or up, by detecting the returned value of -1 (which occurs regardless of [SHIFT] and [CONTROL] key status).
: The example below detects when [SHIFT] and V (key number 55) are pressed together, then ends the program. Refer the manual for the key numbers.

: '''Associated keywords''': CLEAR INPUT, INKEY$, JOY

: '''Example''':
<pre>
10 IF INKEY(55)<>32 THEN 10
20 PRINT "You've pressed [SHIFT] and V"
30 CLEAR INPUT
run
</pre>
: The state of [SHIFT] and [CONTROL] in conjunction with the key specified in the <integer expression> is identified as follows:
<pre>
==============================================================================
|Value returned |[SHIFT] |[CTRL] |Specified key |
==============================================================================
|-1 |ignored |ignored |up |
|0 |up |up |down |
|32 |down |up |down |
|128 |up |down |down |
|160 |down |down |down |
==============================================================================
</pre>
==== <code><big>INKEY$</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': INterrogates the KEYboard, returning the current $tring reflecting any key that is pressed. It provides operator interaction without hitting [ENTER] after every answer. If there is a key pressed, then the function responds. If no key is pressed, INKEY$ returns an empty string.
: In the example below, lines 40 and 70 tell the program to loop back to line 30 after interrogating the keyboard string.

: '''Associated keywords''': CLEAR INPUT, INKEY

: '''Example''':
<pre>
10 CLS
20 PRINT "Select Yes or No (Y/N)?"
30 a$=INKEY$
40 IF a$="" THEN 30
50 IF a$="y" OR a$="Y" THEN 80
60 IF a$="N" OR a$="n" THEN 90
70 GOTO 30
80 PRINT "You have selected YES": END
90 PRINT "You have selected NO":
run
</pre>
==== <code><big>INP (‹port number›)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the INPut value from the I/O address specified in the <port number>.

: '''Associated keywords''': OUT, WAIT

: Watch out http://cpcwiki.eu/index.php/I/O_Port_Summary

: '''Example''':
<pre>
PRINT INP(&FF00)
255
Ready
</pre>
==== <code><big>INSTR ([‹startposition›,]‹searched string›, ‹searched for string›)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Searches the first <searched string> expression to find the first occurance of the <searched for string expression<, and reports the position of its occurance within the <searched string>. If the <searched for string> does not occur within the <searched string>, then 0 is reported.
: The position at which to start searching the <searched string> is optionally specifiable using the <start position> parameter which must yield an integer number in the range 1 to 255.

: '''Associated keywords''': none

: '''1. Example''':
<pre>
a$="ABCD":PRINT INSTR(a$,"C")
3
Ready
</pre>
: '''2. Example''':
<pre>
a$="Hello":IF INSTR(a$,"i")<>0 THEN PRINT "no" else a$
no
Ready
</pre>
: '''3. Example''':
<pre>
10 CLS
20 alphabet$="ABCDEFGHIJKLMNOPQRSTUVWXYZ"
30 INPUT "Enter a letter";a$
40 b$=UPPER$(a$)
50 PRINT b$;" is number";
60 PRINT INSTR(alphabet$,b$);
70 PRINT "in the alphabet.":PRINT
80 GOTO 40
run
</pre>
==== <code><big>INT (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Rounds the number to the nearest smaller INTeger, removing any fractional part. Returns then same value as FIX for positive number, but returns one less than FIX for negative numbers which are not already integers.

: '''Associated keyword''': CINT, FIX, ROUND

: '''Example''':
<pre>
PRINT INT(3.99), INT(-3.99)
3 -4
</pre>
==== <code><big>JOY (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': The JOY function reads a bit significant result from the joystick in the <integer expression> (either 0 or 1).
<pre>
================================
|Bit | Value decimal |
================================
|0(up) | 1 |
|1(down) | 2 |
|2(left) | 4 |
|3(right) | 8 |
|4(fire 2) | 16 |
|5(fire 1) | 32 |
================================
</pre>
==== <code><big>LEFT$ (<string expression>, <required length>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the number of characters (in the range 0 to 255) specified in the <required length> parameter (<integer expression>), after extracting them from the LEFT of the <string expression>. If the <string expression> is shorter than the <required length>, the whole <string expression> is returned.

: '''Associated keywords''': MID$, RIGHT$

: '''1. Example''':
<pre>
A$="ABCDEFG":PRINT LEFT$(A$,3) - prints ABC
</pre>
: '''2. Example''':
<pre>
10 CLS
20 a$="AMSTRAD"
30 FOR n=1 to 7
40 PRINT LEFT$(a$,n)
50 NEXT
run
</pre>
==== <code><big>LEN (<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the total number of characters (i.e. the LENgth) of the <string expression>.

: '''Associated keywords''': none

: '''Example''':
<pre>
10 LINE INPUT "Enter a phrase";a$
20 PRINT "The phrase is";
30 PRINT LEN(a$);"characters long."
run
</pre>
==== <code><big>LOG (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the natural LOGarithm (base of ''e'') of <numeric expression> which mustbe greater than zero.

: '''Associated keywords''': EXP, LOG10

: '''Example''':
<pre>
PRINT LOG(9999)
9.21024037
</pre>
==== <code><big>LOG10 (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the logarithm to base 10 of <numeric expression> which must be greater than zero.

: '''Associated keywords''': EXP, LOG

: '''Example''':
<pre>
PRINT LOG10(9999)
3.99995657
</pre>
==== <code><big>LOWER$ (<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns a new string expression which is a copy of the specified <string expression> but in which all alphabetic characters in the range A to Z are converted to lower case. Useful for processing input where the answers may come in mixed upper/lower case.

: '''Associated keywords''': UPPER$

: '''1. Example''':
<pre>
A$="AMSTRAD":PRINT A$="AMSTRAD":PRINT LOWER$(A$)
Amstrad
</pre>
: '''2. Example''':
<pre>
10 a$="SEE HOW THE LETTERS CHANGE TO ... NUMBERS 1234 NOT..."
20 PRINT LOWER$(a$+"LOWER CASE")
see how the letters change to ... numbers 1234 not... LOWER CASE
</pre>
==== <code><big>MAX (<list of: numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the MAXimum value from the <list of: numeric expression>s.

: '''Associated keywords''': MIN

: '''Example''':
<pre>
10 n=66
20 PRINT MAX(1,n,3,6,4,3)
run
66
</pre>
==== <code><big>MIN (<list of: numeric expression>)</big></code> ====
''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the MINimum value from the <list of: numeric expression>s.
: '''Associated keywords''': MAX

: '''Example''':
<pre>
PRINT MIN (3,6,2.999.8,9,)
2.999
</pre>

==== <code><big>PEEK (<address expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the contents of the Z80 memory location specified in the <address expression> which should be in the range &0000 to &FFFF (0 to 65535). In all cases PEEK will return the value at the RAM address specified (not the ROM), and will be in the range &00 to &FF (0 to 255)

: '''Associated keywords''': POKE

: '''Example''':
<pre>
10 MODE 1: ZONE 7
20 WINDOW 1,40,1,2:WINDOW #1,1,40,3,25
30 PRINT "memory-address"
40 LOCATE 20,1:PRINT "memory-contents"
50 FOR n=1 to 65535
60 p=PEEK(n)
70 PRINT #1,n,"(&";HEX$(n);")";
80 PRINT #1,TAB(20);p,"(&";HEX$(p);")"
90 NEXT
run
</pre>
==== <code><big>PI</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': The value of the ratio between the circumference and the diameter of a circle.

: '''Associated keywords''': DEG, RAD

: '''Example''':
<pre>
PRINT PI
3.14159265
</pre>
==== <code><big>POS (#<stream expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current horizontal POSition of the text cursor relative to the left edge of the text window. The <stream expression> MUST be specified, and does NOT default to #0.
: POS(#8) reports the current horizontal carriage position for the printer, where 1 is the extreme left hand edge.
: POS(#9) reports the logical position in the disc file stream, i.e. the number of printing characters sent to the stream since the last carriage return.

: '''Associated keywords''': VPOS, WINDOW
: '''Example''':
<pre>
10 MODE 1: BORDER 0:LOCATE 8,2
20 PRINT "use cursor left/right keys"
30 WINDOW 1,40,12,12:CURSOR 1,1
40 FOR n=1 TO 19:PRINT CHR$(9);:NEXT
50 IF INKEY(1)<>-1 THEN PRINT CHR$(9);
60 IF INKEY(8)<>-1 THEN PRINT CHR$(8);
70 LOCATE #1,2,24
80 PRINT #1,"text cursor ";
90 PRINT #1,"horizontal position = ";
100 PRINT #1,POS(#0):GOTO 50
run
</pre>
==== <code><big>REMAIN (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns count REMAINing count from the delay timer specified in <integer expression> (= timer number in the range 0 to 3), and disable it. If the delay timer was not enabled zero will be returned.

: '''Associated keywords''': AFTER, DI, EI, EVERY

: For the reason that REMAIN is no normal command but a "function" it is necessary in case of a proper functionality to link the command.
: an '''example''' in combination with an interrupt delay timer 1:
<pre>
PRINT REMAIN(1)
</pre>
: or to stop several/all interrupts at the same time...
<pre>
A=REMAIN(0)=REMAIN(1)=REMAIN(2)=REMAIN(3)
</pre>
: Hint: Take care of interrupts due to parallel working (the same cycle time) or if they are stopped with the BREAK key. Interrupts which were disabled for a certain time will be stored in buffer (for a maximum of 128 entries) and made up their task afterwards in the priorisation as declared.
: further '''example''':
<pre>
10 AFTER 500,1 GOSUB 40
20 AFTER 100,2 GOSUB 50
30 PRINT "program running":GOTO 30
40 REM this GOUSB-Routine will not be called as it is disabled in line 80
50 PRINT:PRINT "Timer 1 will now be ";
60 PRINT "disabled by REMAIN."
70 PRINT "Time-units remaining were:";
80 PRINT REMAIN(1)
run
</pre>
==== <code><big>RIGHT$ (<string expression>, <integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the number of characters (in the range 0 to 255) specified in the <integer expression> (=required length) parameter, after extracting them from the RIGHT of the <string expression>. If the <string expression> is shorter than the <integer expression>, the whole <string expression> is returned.

: '''Associated keywords''': LEFT$, MID$

: '''Example''':
<pre>
10 MODE 1:a$="AMSTRAD computer"
20 FOR n=1 TO 16:LOCATE 41-n,n
30 PRINT RIGHT$(a$,n)
40 NEXT
</pre>
==== <code><big>RND [(<numeric expression>)]</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the next RaNDom number in sequence if the <numeric expression> has a positive value or is not specified.
: If the <numeric expression> yields a value of zero, RND returns a copy of the last random number generated.
: If the <numeric expression> yields a negative value, a new random number sequence is started, the first number of which is returned.

: '''Associated keywords''': RANDOMIZE

: '''1. Example''':
<pre>
PRINT RND(0)
0.536703827
Ready
PRINT RND(1)
0.271940658
Ready
PRINT RND(0)
0.271940658
Ready
</pre>
: '''2. Example''':
: Example for generating an integer random number between 1 and 1000
<pre>
10 A=INT((RND(1)*1000)+1)
20 PRINT A
30 GOTO 10
</pre>
: '''3. Example''':
: For generating a random number between a lower and higher border
<pre>
10 INPUT "Low border",low
20 INPUT "High border",high
30 A=INT(RND(1)*(high-low))+low
40 PRINT A
</pre>
: '''4. Example''':
<pre>
10 RANDOMIZE
20 FOR x=1 TO -1 STEP -1
30 PRINT "rnd parameter=";x
40 FOR n=1 TO 6
50 PRINT RND(x)
60 NEXT n,x
run
</pre>

==== <code><big>ROUND (<numeric expression>[,<integer expression>])</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Rounds <numeric expression> to a number of decimal places or to the power of ten specified by <integer expression>. If <integer expression> less than zero, the <numeric expression> is rounded to give an absolute integer with <integer expression> number of zeros before the decimal point.

: '''Associated keywords''': ABS, CINT, FIX, INT
: '''1. Example''':
<pre>
PRINT ROUND(1562.357,2),ROUND(1562.375,-2)
1562.36 1600
</pre>
: '''2. Example''':
<pre>
10 FOR n=4 TO -4 STEP -1
20 PRINT ROUND (1234.5678,n)
30 PRINT "with integer expression";n
40 NEXT
run
</pre>
==== <code><big>SGN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: FUNCTION: Determines the SiGN of the <numeric expression>. Returns -1 if <numeric expression> is less than 0, returns 0 if <numeric expression> = 0, and returns 1 if <numeric expression> is greater than zero.

: '''Associated keywords''': ABS

: '''Example''':
<pre>
10 FOR n=255 to -200 STEP -20
20 PRINT "SGN returns";
30 PRINT SGN(n);"for a value of";n
40 NEXT n
run
</pre>
==== <code><big>SIN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the Real value for the Sine of <numeric expression>, defaulting to the Radian (RAD) measure mode unless otherwise declared by a DEG command.

: '''Associated keywords''': ATN, COS, DEG, RAD, TAN

: '''Example''':
<pre>
10 CLS:DEG:ORIGIN 0,20
20 FOR n=0 to 720
30 y=SIN(n)
40 PLOT n*640/720,198*y:NEXT
50 GOTO 50
run
</pre>
==== <code><big>SPACE$(<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Creates a string of spaces of the given length, (in the range 0 to 255) specified in the <integer expression>.

: '''Associated keywords''': SPC, STRING$, TAB

: '''Example''':
<pre>
10 MODE 1
20 PRINT "Put 9 spaces between me";
30 PRINT SPACE$(9);
40 PRINT "and you!"
run
</pre>
==== <code><big>SQ (<channel>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the state of the Sound Queue for the specified <channel> which must be an integer expression, yielding one the values:
: 1: for channel A
: 2: for channel B
: 4: for channel C
: The SQ function returns a bit significant integer, comprising the following bit settings:
: Bit 0,1 and 2: the number of free entries in the queue
: Bit 3,4 and 5: the rendezvous state at the head of this queue
: Bit 6 : the head of the queue is held
: Bit 7 : the channel is currently active
: ... where Bit 0 is the least significant bit, and Bit 7 is the most significant bit.
: It can be seen, that if Bit 6 is set, Bit 7 cannot be set at the same time, and vice versa. Similarly if Bits 3, 4, or 5 are set, Bit 6 and 7 cannot be set.

: '''Associated keywords''': ON SQ GOSUB, SOUND

: '''Example''':
<pre>
10 SOUND 65,100,100
20 PRINT SQ(1)
run
67
</pre>
==== <code><big>SQR (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the SQuare Root of the specified <numeric expression>.

: '''Associated keywords''': none

: '''Example''':
<pre>
PRINT SQR(9)
3
</pre>
==== <code><big>STR$ (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Converts the <numeric expression> to a decimal STRing representation.
: Useful for converting a number to a string in case of string manipulation. E.g. after converting a figure to a string then the most left character holds the sign: a minus in case the figure is negative and a space in case the figure is positiv.

: '''Associated keywords''': BIN$, DEC$, HEX$, VAL

: '''1. Example''':
<pre>
10 FIGURE=-1599
20 FIGURE$=STR$(FIGURE)
30 PRINT FIGURE$
-1599
</pre>
: '''2. Example''':
<pre>
10 FIGURE=1769
20 FIGURE$=STR$(FIGURE)
30 PRINT FIGURE$
1769
</pre>
: '''NOTE''': (there's a blank on the left-hand of the number "1769")
: If you want to add e.g. zero before the figure in case of a high score with fix digit-number then you're able to add zero(s) in front of a string instead of a figure.

: '''3. Example''':
<pre>
10 a=&FF:REM 255 hex
20 b=&x1111:REM 15 binary
30 c$="***"
40 PRINT c$+STR$(a+b)+c$
run
*** 270***
</pre>

==== <code><big>STRING$ (<length>,<character specifier>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns a string expression consisting of the <character specifier> repeated the number of time (in the range 0 to 255) specified in the <length>.

: '''Associated keywords''': SPACE$

: '''1. Example''':
<pre>
PRINT STRING$(40,"*")
****************************************
</pre>
: '''2. Example''':
<pre>
PRINT STRING(40,42)
****************************************
</pre>
: '''NOTE''': the <character specifier> 42 refers to the ASCII value of the character '*' and is also equivalent to PRINT STRING$(40,CHR$(42))
==== <code><big>TAN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the TANgent of the <numeric expression>, which must be in the range -200,000 to +200,000.
: '''NOTE''': DEG and RAD can be used to force the result of the calculation to degrees or radians respectively.

: '''Associated keywords''': ATN, COS, DEG, RAD, SIN

: '''Example''':
<pre>
PRINT TAN(45)
1.61977519
</pre>

==== <code><big>TEST (<x co-ordinate>,<y co-ordinate>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Moves the graphics cursor to the absolute position specified by the <x> and <y co-ordinate>s, and reports the value of the ink at the new location.

: '''Associated keywords''': MOVE, MOVER, TESTR, XPOS, YPOS

: '''Example''':
<pre>
10 CLS
20 PRINT "Your are using pen number";
30 PRINT TEST(10,386)
40 PRINT "Try changing PENs and MODEs";
50 PRINT "....then RUN again."
run
</pre>
==== <code><big>TESTR (<x offset>,<y offset>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Moves the graphics cursor by the amount specified in the <x> and <y offset>s relative to its current position, and reports the value of the ink at the new location.

: '''Associated keywords''': MOVE, MOVER, TEST, XPOS, YPOS

: '''Example''':
<pre>
10 MODE 0:FOR x=1 TO 15:LOCATE 1,x
20 PEN x:PRINT STRING$(10,143);:NEXT
30 MOVE 200,400:PEN 1
40 FOR n=1 TO 23:LOCATE 12,n
50 PRINT "pen";TESTR(0,-16):NEXT
run
</pre>
==== <code><big>TIME</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the elapsed time since the computer was last switched-on or reset, (excluding periods when reading or writing to disc).
: Each second of real time is equal to the returned value = TIME/300.

: '''Associated keyword''': AFTER, EVERY, WEND, WHILE

: '''Example''':
<pre>
10 CLS:REM clock
20 INPUT "hour";hour
30 INPUT "minute";minute
40 INPUT "second";second
50 CLS:datum=INT(TIME/300)
60 WHILE hour<13
70 WHILE minute<60
80 WHILE tick<60
90 tick=(INT(TIME/300)-datum)+second
100 LOCATE 1,1
110 PRINT USING "## ";hour,minute,tick
120 WEND
130 tick=0:second=0:minute=minute+1
140 GOTO 50
150 WEND
160 minute=0:hour=hour+1
170 WEND
180 hour=1
190 GOTO 60
run
</pre>
==== <code><big>UNT (<address expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Return an integer in the range -32768 to +32767 which is the twos-complement equivalent of the unsigned value of the <address expression>.

: '''Associated keywords''': CINT, FIX, INT, ROUND

: '''Example''':
<pre>
PRINT UNT(&FF66)
-154
</pre>
==== <code><big>UPPER$(<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns a new string expression which is a copy of the specified <string expression> but in which all alphabetic characters in the range A to Z are converted to upper case. The function is useful for processing input which may come in mixed upper / lower case.

: '''Associated keywords''': LOWER$

: '''Example''':
<pre>
10 CLS: a$="my, how you've grown!"
20 PRINT UPPER$(a$)
run
</pre>
==== <code><big>VAL(<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the numeric VALue, (including any negative sign and decimal point) of the first character(s) in the specified <string expression>.
:If the first character is not a number, then 0 is returned. If the first character is a negative sign or decimal point followed by non-numeric characters, a 'Type mismatch' error (13) will be reported.

: '''Associated keywords''': STR$

: '''1. Example''':
<pre>
PRINT VAL("-12.34x"),VAL("A-12")
-12.34 0
</pre>
: '''Exception''': if <se> starts with "&" + character (and it's between "A" and "F") the whole character will be handled like a hexadezimal numeric character (...often used in DATA Loaders). The returning numeric value is a  signed integer (16-Bit Word).
: '''2. Example''':
<pre>
PRINT VAL("&A")
10

PRINT VAL("&7FFF")
32767

PRINT VAL("&8000")
-32768
</pre>
: '''3. Example''':
<pre>
10 CLS: PRINT "I know my times tables!"
20 PRINT:PRINT "Press a key (1 to 9)"
30 a$=INKEY$:IF a$="" THEN 30
40 n=VAL(a$):if n<1 or n>9 then 30
50 FOR x=1 to 12
60 PRINT n;"X";x;"=";n*x
70 NEXT:GOTO 20
run
</pre>
==== <code><big>VPOS (#<stream expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current vertical POSition of the text cursor relative to the top of the text window. The <stream expression> MUST be specified, and does NOT default to #0.

: '''Associated keywords''': POS, WINDOW

: '''Example''':
<pre>
10 MODE 1:BORDER 0:LOCATE 8,2
20 PRINT "use cursor up/down keys"
30 WINDOW 39,39,1,25:CURSOR 1,1
40 LOCATE 1,3
50 IF INKEY(0)<>-1 THEN PRINT CHR$(11);
60 IF INKEY(2)<>-1 THEN PRINT CHR$(10);
70 LOCATE #1,3,24
80 PRINT #1,"text cursor ";
90 PRINT #1,"vertical position =";
100 PRINT #1,VPOS(#0):GOTO 50
run
</pre>
==== <code><big>XPOS</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current horizontal (X)POSition of the graphics cursor.

: '''Associated keywords''': MOVE, MOVER, ORIGIN, YPOS

: '''Example''':
<pre>
10 MODE 1:DRAW 320,200
20 PRINT "graphics cursor X position = ";
30 PRINT XPOS
</pre>
==== <code><big>YPOS</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current vertical (Y)POSition of the graphic cursor.

: '''Associated keywords''': MOVE, MOVER, ORIGIN, XPOS

: '''Example''':
<pre>
10 MODE 1:DRAW 320,200
20 PRINT "graphics cursor Y position = ";
30 PRINT YPOS
</pre>

== Other Basic Dialects available for the CPC ==

*[[BBC Basic]]
*[[C BASIC Compiler|CBASIC]]
*[[BASIC-E]]

== Technical Information ==

* [[Technical_information_about_Locomotive_BASIC]]

== Web links ==

* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]
* [http://rosettacode.org/wiki/Category:Locomotive_Basic Code examples at Rosetta Code]

* [http://cpctech.cpc-live.com/docs/basic.asm Disassembly of Locomotive BASIC v1.1]

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Locomotive BASIC

2025-10-02T13:00:47Z

Arnoldemu: /* OPENOUT ‹filename› */

For other BASIC language versions see the [[:Category:BASIC]]

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

It was availlable directly from in-built ROMs on [[CPC old generation]] and on the [[Plus System Cartridge]] for the [[Plus]] range. [https://benchmarko.github.io/CPCBasic/ Online Interpreter]

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

If you are interested in more information about the different versions of the CPC's BASIC and the technical details, you can have a look at the article "[[Technical information about Locomotive BASIC]]".

Another helpful and further resource of information about BASIC and a similar comprehension to this is Grimware's Website about the CPC http://www.grimware.org/doku.php/documentations/software/locomotive.basic/start

== 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 and Spanish 472 shipped with BASIC 1.0 on ROM.

The language was revised and debugged for the 472 (British), 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.

== Variables ==
Many contemporary BASIC interpreters only supported the first few characters of a variable name as a discriminator. For example <code>WATER$</code> and <code>WALDO$</code> would refer to the same variable on a Commodore 64 or Apple II. But Locomotive BASIC allowed variable names up to 40 characters in length, so <code>THEQUICKBROWNFOXJUMPEDOVERTHELAZYDOGFAST$</code> and <code>THEQUICKBROWNFOXJUMPEDOVERTHELAZYDOGFATS$</code> could be use as separate variables.

=== Real (Floating Point) Numbers ===

This is the default type for a Locomotive BASIC variables, but can be clarified using <code>!</code> after the variable name, e.g., <code>real!=500.0</code>.
You can force all variables starting with specific letters to be this type by using the <code>DEFREAL</code> keyword.
In many cases you don't want to use these, as they are slower than using the integer type, and use more memory (5 bytes, as opposed to 2).

=== Signed 16-bit Integers ===

Defined using <code>%</code> after the variable name, e.g., <code>integer%=500</code>.
You can force all variables starting with specific letters to be this type by using the <code>DEFINT</code> keyword.
These can store values between -32,768 and 32,767.
To assign a 16-bit value to a signed integer directly, you should give the number in a hexadecimal format, e.g., <code>uint=&c0000</code>.

=== Strings ===

These are defined by using <code>$</code> after the variable name, e.g., <code>str$="Hello"</code>.
You can force all variables starting with specific letters to be this type by using the <code>DEFSTR</code> keyword.
A String can be up to 255 characters long.

== Type Conversions ==

The BASIC functions <code>ROUND</code>, <code>INT</code>, <code>CINT</code> and <code>FIX</code> can be used to convert real numbers into integers taking some care about rounding. The difference is in rounding mode - <code>ROUND</code> rounds to nearest, <code>FIX</code> rounds to zero, <code>INT</code> always rounds down, and <code>CINT</code>rounds up. e.g., <code>value%=INT(3.14)</code>. Note that if you don't specify the % you will actually get a real number still.

To convert an integer to a real number, you can use the <code>UNT</code> function which will take the value supplied and return the two's complement number. e.g., <code>real=UNT(&ABCD)</code>.

<pre>
w=UNT(50000)
Ready
PRINT w
-15536
Ready
█
</pre>

If you want an integer result from division, use the <code>\</code> integer division operator. e.g., <code>int=value\divisor</code>. This is as opposed to the standard <code>/</code> division operator, that can create a real number.

== Command list ==

=== Commands and operators ===

==== <code>AFTER ‹time delay›[,‹timer number›] GOSUB ‹line number› </code>====
: Waits for ‹time delay›/50 seconds and then jumps NON-RECURRING to the subroutine at ‹line number› (see also <code>"EVERY i[,t] GOSUB line"</code>).

==== <code>AUTO [‹line number›][,‹increment›] </code>====
: Automatically generates line numbers starting at ‹line number› with ‹increment› after each entered line number. Use '''[ESC]''' to leave AUTO mode. Default values for ‹line number› and ‹increment› are 10.

: Example:
<pre>AUTO 100,5 :REM generates line numbers 100, 105, 110...</pre>

==== <code>BORDER ‹colour›[,‹colour›] </code>====
: Changes the colour of the border. If the second argument is supplied the border flashes between the two colours.

==== <code>CALL ‹address expression›[,‹list of: parameter›] </code>====
: Allows a machine code routine to be called by BASIC. Variables, string values and constants can be passed to the routine. Values of any supported type can be passed back by supplying a variable with <code>@</code> in front of it. This passes the address of the variable to the routine although it doesn't implicitly know the data type.
: Example:
<pre>CALL 0 :REM resets the computer completely</pre>

==== <code>CAT</code> ====
: Displays the names of the files on the tape or disc. Tape files are displayed in the order they are encountered. Disc files are sorted alphabetically by ACSII code. Only files matching the current user are displayed. Files marked as system are not displayed.
: Examples:
<pre>CAT :REM lists all disc files in alpha-numeric (ASCII) order</pre>

<pre>|TAPE :CAT :REM lists names of all tape files in their storage order</pre>

==== <code>CHAIN ‹file name›[,‹line number expression›] </code>====

:Enables the specified program to be loaded and RUN automatically. If the optional parameter ‹line number expression› is specified, the program execution will commence from that line.

==== <code>CHAIN MERGE ‹file name›[,‹line number expression› | [,[‹line number expression›],DELETE ‹line number range›]] </code>====

:Loads the specified program from tape or disc, merges it into the program in memory, and starts execution of the merged program. The parameter <code>DELETE</code> ‹line number range› is used to delete part of the original program before running it, if required.

==== <code>CLEAR</code> ====
: Clears all variables from memory, leaving the program in memory unchanged. All open files are abandoned.
: The command clear inside a subroutine (<code>GOSUB</code>... <code>RETURN</code>) will also clear the "stack pointer" address of the gosub heap. That means that a RETURN won't work and a GOTO has to be used instead.

==== <code>CLG [‹masked ink›] </code>====
: Clears the graphics screen to colour specified by <code>‹masked ink›</code>. If parameter <code>‹masked ink›</code> is not specified then the graphics screen is cleared to the colour specified by the GRAPHICS PAPER statement.

==== <code>CLOSEIN</code> ====
: Closes any input file (tape or disc).

==== <code>CLOSEOUT</code> ====
: Closes any output file (tape or disc).

==== <code>CLS [#‹stream expression›]</code>====
: Clears the window specified by ‹stream expression›. If ‹stream expression› is omitted it defaults to #0 (usually the whole screen). The text cursor of the stream is moved to the upper left corner.

==== <code>CONT</code> ====
: CONTinues program execution interrupted either by [ESC] [ESC] or as a result of STOP within a program. A program cannot be continued after being modified.

==== <code>CURSOR ‹expression› </code>====
: <code>‹expression›</code> must be either 0 or 1.

==== <code>DATA x1[,x2,x3...]</code> ====
: 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>

==== <code>DEF</code> ====
: DEF means "define" and comes along with defining a function in case of DEF FN or defining variables in case of DEFREAL, DEFINT or DEFSTR.
: DEF FN must come before using the statement FN.
: DEF with a variable declaration should come before using a variable.
: (see also FN)

==== <code>DEFINT ‹letter range›</code> ====
:Forces all variables(s) starting with the specified letter(s) to be integer variables. Singular letters could be defined or a range by a minus symbol between two letters.

:Examples:
<pre>
20 DEFINT a-z:' sets all variables starting with an A until Z as integer.
</pre>
or
<pre>
10 DEFINT F,S ..... (or 10 DEFINT A-Z)
20 FIRST=111.11:SECOND=22.2
30 PRINT FIRST,SECOND:' prints out 111 22
</pre>

==== <code>DEFREAL ‹letter range›</code> ====
: Sets the default for variable(s) with the specified first letter(s) to a floating point figure.

==== <code>DEFSTR ‹letter range›</code> ====

: Sets the default for variable(s) with the specified first letter(s) to string(s) variables.

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

==== <code>DELETE [first line][-[last line]]</code> ====
: Deletes the current program completely (without arguments) or only the given line or line range. Even
: <code>DELETE -</code>
: is legal, it has the same effect as
: <code>DELETE</code>
: The lines specified do not have to exist, all lines matching the range will be deleted and having no matches does not cause an error.

==== <code>DI</code> ====
: Disables interrupts (but not[ESC]) until re-enabled by EI command or by RETURN at end of an interrupts service routine.
: This means that DI (if it's activated in a subroutine) is useful helping a low-priority-interrupt not to be stopped by a higher-priority-interrupt. RETURN then re-enable the interrupt without EI.

==== <code>DIM a[%|!|$](d1[,d2[,...]])</code> ====

: Creates array <code>a</code> with single or multiple dimensions. You may optionally specify integer (<code>%</code>), real (<code>!</code>) or string (<code>$</code>) type otherwise it defaults to the current type set for the first letter of the array name. <code>d1</code> is size of first dimension-1, <code>d2</code> is size of second dimension-1 and so on. <code>DIM x(10)</code> will create an array with 11 elements, <code>x(0)</code> is the first element, <code>x(10)</code> is the eleventh and last. You can specify as many dimensions as will fit on one 255 character line, which is a maximum of 125. Trying to create an array that already exists will generate an <code>Array already dimensioned</code> error. If an array is not specified by <code>DIM</code> before being accessed, each dimension value defaults to 10. The maximum dimensions that can be created this way is three.

==== <code>DRAW x,y[,[i1][,i2]]</code> ====

: Draws a line from the current cursor position to position x,y. i1 specifies colour, i2 is the drawing style.

: 4 drawing styles:
<pre>
i2 = 0 normal colour
i2 = 1 XOR colour
i2 = 2 AND colour
i2 = 3 OR colour
</pre>
: Example:
<pre>
CLG 2
DRAW 500,400,0 :REM draws a line from 0,0 to 500,400
</pre>

<code>DRAWR xr,yr[,[i1][,i2]]</code> ====

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

<pre>
Move 200,200
DRAWR 100,100,0 - draws a line from 200,200 to 300,300
</pre>

==== <code>EDIT ‹line›</code> ====
: Display 1 program line for editing.

The following keys can be used in editing mode, or during typing in BASIC:

CTRL+TAB - toggle overwrite/insert mode
CTRL+CURSOR LEFT or CTRL+CURSOR UP - go to start of line
CTRL+CURSOR RIGHT or CTRL+CURSOR DOWN - go to end of line
CURSOR LEFT - move left one character
CURSOR RIGHT - move right one character
ESC - quit editing and do not accept changes
ENTER/RETURN - quit editing and accept changes
SHIFT + CURSOR UP/DOWN/LEFT/RIGHT - enter copy mode. You can move the cursor to where you want to copy from. Hold SHIFT and cursors to move copy cursor.
COPY - copy character covered by copy cursor.
DEL - delete character and go back a char
CLR - delete character under cursor
CTRL + CAPS LOCK - toggle shift lock.

==== <code>EI</code> ====
: Enable interrupts which have been disabled by DI

==== <code>END</code> ====
: Indicates end of program

==== <code>ENT ‹tone envelope number›[,‹tone env. section›][,‹tone env. section›][,‹tone env. section›][,‹tone env. section›][,‹tone env. section›]</code> ====
:The ENT command define the TONE shape of a sound which means manipulating the frequency in a certain range.
:The command could looks like:
<pre>
ENT NUMBER,STEPS?,VERTICAL?,HORIZONTAL?
</pre>
:It is possible to define 15 different envelope shapes. So '''NUMBER''' could be 1-15.

:Each '''?''' stands for up to five sections (1-5), where each STEP<>VERTICAL<>HORIZONTAL with the same '''?''' are belong together.

:'''STEP:''' means how many steps in each section (0-127) > one step is 1/100 of a second!
:'''VERTICAL''': means how big is the step size from bottom to top (-128 to 127)
:'''HORIZONTAL''': means how big is the step size from left to right (0-255)

==== <code>ENV ‹volume envelope number›[,‹volume env. section›][,‹volume env. section›][,‹volume env. section›][,‹volume env. section›][,‹volume env. section›]</code> ====
:The ENV command define the VOLUME shape of a sound which means manipulating the loudness in a certain range.
:The command could looks like:
<pre>
ENV NUMBER,STEPS?,VERTICAL?,HORIZONTAL?
</pre>
:It is possible to define 15 different envelope shapes. So '''NUMBER''' could be 1-15.

:Each '''?''' stands for up to five sections (1-5), where each STEP<>VERTICAL<>HORIZONTAL with the same '''?''' are belong together.

:'''STEP:''' means how many steps in each section (0-127) > one step is 1/100 of a second!
:'''VERTICAL''': means how big is the step size from bottom to top (-128 to 127)
:'''HORIZONTAL''': means how big is the step size from left to right (0-255)

==== <code>ERASE v1[% | ! | $][,v2[% | ! | $][,...]]</code> ====
: Erases the specified array(s) and frees the memory used. Must specify existing array(s) or an <code>Improper argument</code> error will be generated.

==== <code>ERL</code> ====

: Returns the line number of the last error encountered.

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

==== <code>EVERY i[,t] GOSUB ln</code> ====

: BASIC branches to the subroutine at line ln EVERY (reccuring) i/50 seconds. (see also "AFTER i[,t] GOSUB line")

: There are 4 delay timers from 0 to 3 which can be specified with ‹timer number›. If omitted ‹timer number› defaults to 0.
: In the case of parallel task has 3 the highest and 0 the lowest priority.
: With DI or EI you can disable or enable the timing interrupt. With REMAIN <timer number> you can also disable an AFTER or EVERY construct and stores the "remaining" time (> REMAIN)
: Interrupts run as long as the main loop / program runs, even the main programm is paused > press ESC only '''once''' not twice for a break.
: It is important to know or realise that low-priority-interrupts which occurs simultanously to higher-priority-interrupts are not lost. Their task remains or handled again after finishing the higher-prio interrupt.

<pre>
10 REM > interrupts
20 EVERY 50,0 GOSUB 100: REM > lowest priority
30 EVERY 100,1 GOSUB 200
40 EVERY 200,2 GOSUB 300:
50 AFTER 1000,3 GOSUB 400: REM > highest priority
60 WHILE flag=0
70 a=a+1:print a
80 WEND
90 END
100 REM #0
110 PEN 2:PRINT "timer 0":PEN 1
120 RETURN
200 REM #1
210 PEN 2:PRINT "timer 1":PEN 1
220 RETURN
300 REM #2
310 PEN 2:PRINT "timer 2":PEN 1
320 RETURN
400 REM #3
410 flag=1:PEN 2:PRINT "no more interrupts..."
420 RETURN
</pre>

: Hint: Timing with interrupts is important, especially if more than one interrupts run. If the interval of a subroutine driven by an interrupt is too long than the processor can never get back to deal the main program again. Work out timing by measuring the subroutine or by trial and error.
: There are system internal interrupts (highest level) which cannot be influenced by BASIC interrupts (e.g. keyboard scan > BREAK key.)
: The next level of sytem internal interrupts CAN be influenced by BASIC interrupts. For example the sound queue which will be created by "ON SQ <chanel> GOSUB <line>". Those sound interrupts have an independent time tricker but their priority is parallel to the second priority times of BASICs interrupts. Therefore interrupts with timer 3 could "interrupt" them.

==== <code>FILL i</code> ====
: 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.

==== <code>FN</code> ====
:BASIC allows the program to define and use simple value returning functions. DEF FuNction is the definition part of this mechanism and creates program-specific function which works within the
:program in the same way as a function such a COS operates as a built-in function of BASIC. It may be invoked throughout the program. Variable types must be consistent and the DEF FN
:command should be written in part of the program outside the execution loop.

:Syntax : <code>DEF FN<name>[(<formal parameters>)]=<general expression></code>

:Example: ''"with the definition of..."''
<pre>
10 gn=9.80665
20 DEF FNgrv=s0+v0*t+0.5*gn*t^2
30 s0=0:v0=0:t=5
40 PRINT "...after";t;"seconds your dropped stone falls";FNgrv;"metres"
</pre>
:''"the results are..."''
<pre>
:...after 5 seconds your dropped stone falls 122.58315 metres
</pre>

==== <code>FOR TO STEP NEXT</code> ====
: Creating a counting loop (control strucutre) with a starting condition. Inside the counting loop one or more commands will be executed.
: The loop consists of of following specifications:

: 1. FOR
: 2. ''a control variable''
: 3. =
: 4. ''starting value''
: 5. TO
: 6. ''target value''
: 7. STEP [optional]
: 8. ''increment / step size''
: ''... instructions between''
: 9. NEXT
: 10. ''control variable'' [optional]

: You have to use the command STEP if you wish to count backwards. It's good to name the ''control variable'' after NEXT for readability and better program style.
: After each loop the computer checks internaly if the ''target value'' has been reached (like an IF ... THEN ... ELSE instruction). If the target value is reached NEXT closes the loop and calculates another step, so the ''control variable'' will be changed last time.
: The default STEP value - if not specified - is one (1).

: Example:
<pre>
10 FOR I=1 TO 10
20 PRINT I;
30 NEXT I
40 PRINT I
RUN
1 2 3 4 5 6 7 8 9 10 11
READY
</pre>

==== <code>FRAME</code> ====
: 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.

==== <code>GOSUB i</code> ====

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

==== <code>GOTO i</code> ====
: 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>
: GOTO is the simplest form of a jump or creating a loop '''without''' condition controll.
: ''Example: (unconditional and endless loop)''
<pre>
10 PRINT "#";
20 GOTO 10
</pre>
: Combine the GOTO command with an IF...THEN...ELSE instruction for creating a condition-controlled loop with the '''test at the end'''. Helpful because the Locomotive Basic has no practical DO...WHILE... loop.
: ''Example: (condition at the end)''
<pre>
10 I=1
20 PRINT I
30 I=I+1
40 IF I<25 THEN GOTO 20
50 END
</pre>

==== <code>GRAPHICS</code> ====
: ...works only in combination with the command <code>PEN</code> or <code>PAPER</code> to set the plotting/drawing pen or background colour.
: If the <code>TAG</code> command is used to set text at the graphics cursor <code>GRAPHICS PEN</code> or <code>GRAPHICS PAPER</code> instead of the regular <code>PEN</code> or <code>PAPER</code>is necessary to colour the text.

==== <code>IF THEN ELSE</code> ====
: Asks for a choice with the '''IF...THEN...ELSE''' statement.
: '''IF''' compares the entry condition in a logical way
: '''THEN''' contains instruction if the comparison is true
: '''ELSE''' contains instruction if it's false.
: '''Example:'''
<pre>
10 INPUT "guess a figure:",f
20 IF f=10 THEN PRINT "right": END: ELSE GOTO 10
</pre>
: In case of nested choices there's a possibility to that with an IF...THEN instruction but not very recommended:
<pre>
10 INPUT "guess a figure:",f
20 IF f=10 THEN PRINT "right": END: ELSE IF f<10 THEN PRINT "too small" ELSE PRINT "too big"
30 GOTO 10
</pre>
:Other nested structures like IF...THEN...'''ELSE...ELSE''' won't work first because the Locomotive Basic only looks after the first ELSE instruction found and can't execute more single commands as a block for a certain condition in comparision to e.g. "PASCAL" > begin...end-block, "C" > {...}-block.

==== <code>INK ‹pen›,‹colour›,[‹second colour›]</code> ====
: Used to set the colour palette for each of the 16 available inks.
: pen specifies the pen slot to use.
: colour specifies the system colour to use (0..27.)
: if the second colour is provided, Locomotive Basic will blink between the colour and second colour.
: In MODE 0, all 16 pens are available. In MODE 1, only 4 pens are available (0..3). In MODE 2, only 2 pens are available (0..1.)
: By default, pen 0 is the background colour and pen 1 is the foreground/text colour.
: Examples:
<pre>
10 MODE 2
20 INK 0,3: REM Set background colour to red
30 INK 1,26: REM Set foreground/text colour to white
</pre>

==== <code>INPUT[#‹stream expression›][,]</code> ====
: [...]

==== <code>KEY</code> ====
: [...]

==== <code>LET</code> ====
: Used to define variables. You don't need to use the ''LET'' command because it is just a command which was added for compatibility reasons.
: ''Example:''
<pre>
10 LET a$ = "hello world"
20 PRINT a$
</pre>

==== <code>LINE INPUT [#‹stream expression›][,]‹variable›[,‹variable›] </code>====
: [...]

==== <code>LIST [‹line number›][-[‹line number›]], [#‹stream expression›]</code>====
: A command for listing the Basic program code.
: Possibility for manipulating display is using line numbers with a minus symbol.
: Example:
<pre>
LIST 100-
</pre>
: List every line after line number 100.
<pre>
LIST -100
</pre>
: List every line until line number 100 has reached.
<pre>
LIST 100-200
</pre>
: List every line between line number 100 and 200 included

: With the help of separate window definitions it is possible to print out long listings, better differentiate parts / slices of it into different window predefined
: Example:
<pre>
LIST 1000-1100,#1
LIST 3000-3100,#2
</pre>
: ...prints out two parts of one program out into two windows (if they are defined well)

==== <code>LOAD ‹file name›[,‹address›] </code>====

With this directive you may load any file in memory

Basic files (extension .BAS) are loaded in Basic memory, you cannot choose loading address

Binary files are loaded to the default address location stored in the AMSDOS header but you may force loading address (&C000 for a screen)

TAPE convention:

When loading tape files, the basic display a message every block which may cause trouble. Message output may be disabled by using prefix "!" before the filename.

It's also possible to load the next file disregarding his name using only "!" => <code>LOAD "!"</code>

==== <code>LOCATE[#‹stream expression›][,] x,y</code> ====

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

==== <code>MASK [i1][,i2]</code> ====

: Sets bits in each adjacent group of 8 pixel on (1) or off (0) according to binary value of i1 (0-255). i2 determines whether the first point of the line is to plotted (1) or not (0).

:Example:

<pre>
10 CLG 2:MASK 1:MOVE 0,0:DRAW 500,400
20 MASK 15:MOVE 0,0:DRAW 500,400
</pre>

==== <code>MEMORY ‹memory address›</code> ====

: Allocates the amount of memory to be used by BASIC by setting the [[Locomotive_BASIC#HIMEM|address of the highest byte]] it may use.

==== <code>MERGE</code> ====
: [...]

==== <code>MID$ (‹string›,‹start position›[,‹length of substring›])</code> ====
: With the MID$ command there are two applications possible:

: 1. MID$ creates a new substring out of the give ‹string› and starts at the defined position ‹start position› and print the number of given characters by ‹length of substring›.
: If no length is defined every character from ‹start position› will be printed out.
: If a higher value of ‹start position› or ‹length of substring› than the real length of the initial string is defined a blank string will be printed.
: The range of ‹start position› or ‹length of substring› is from 0 up to 255 characters.

: 2. With MID$ you're able to manipulates given strings by inserting a new string.
: Take care of the two different applications and using in BASIC.

: Example for the 1. application:
<pre>
10 a$="Hello"
20 PRINT MID$(a$,2,2)
run
el
Ready
</pre>
:
: Example for the 2. application
<pre>
10 a$="Hello"
20 MID$(a$,2,3)="ipp"
30 PRINT a$
run
Hippo
Ready
</pre>

==== <code>MODE</code> ====
: Changes the screen mode: MODE 0 is 160×200 in 16 colours, MODE 1 is 320×200 4 colours, MODE 2 is 640×200 2 colours and MODE 3 is 160×200 in 4 colours.

==== <code>MOVE x,y [[,i1][,i2]]</code> ====

: Moves the graphic cursor to position x,y. The parameter i1 may be used to change the pen (drawing) colour. The parameter i2 specifies the logical colour, as in DRAW.

: 4 drawing styles:
<pre>
i2 = 0 normal colour
i2 = 1 XOR colour
i2 = 2 AND colour
i2 = 3 OR colour
</pre>

==== <code>MOVER xr,yr[,[i1][,i2]]</code> ====
: moves the graphic cursor (relative) from current position to current cursor x position + xr, current cursor y position + yr. i1 and i2 as in MOVE.

==== <code>NEW</code> ====
: Clears BASIC RAM which means program and variables. Keeps symbol defintion (if defined) and screen mode without clearing.

==== <code>ON BREAK CONT</code> ====

: Prevents the interruption of program execution by the ESC key.

==== <code>ON BREAK GOSUB ln</code> ====

: Passes control to subroutine at line ln when ESC ESC pressed.

==== <code>ON BREAK STOP</code> ====

: Restores normal function of ESC key during program execution.

==== <code>ON ERROR GOTO ln</code> ====

: Passes the control to line ln if an error is detected in the program.

: ON ERROR GOTO 0, Turns of the error trap, and restores normal error processing.

==== <code>ON variable GOTO ln x1, x2, x3, x4, ...</code> ====

: In case of passing more choices '''ON variable GOTO ln x1, x2, x3, x4, ...''' points to a table with the jumping target.
: '''Example:'''
<pre>
10 PRINT "1. LOAD - 2. SAVE - 3. EXIT"
20 INPUT choice
30 ON choice GOTO 1000, 2000, 3000
40 CLS: GOTO 10
1000 PRINT "1. LOAD":END
2000 PRINT "2. SAVE":END
3000 END
</pre>
:In case that the variable ''choice'' won't fullfil the condition (in a range between line 0 and 65535) the next instruction will be executed (here: Line 40). If "choice" is smaller than 0 an error will occur.

==== <code>ON variable GOSUB ln x1, x2, x3, x4, ...</code> ====

: In case of passing more choices targeting to SUBROUTINES '''ON variable GOSUB ln x1, x2, x3, x4, ...''' points to a jumping table.
: '''Example:'''
<pre>
10 PRINT "1. LOAD - 2. SAVE - 3. EXIT"
20 INPUT choice
30 ON choice GOSUB 1000, 2000, 3000
40 CLS: GOTO 10
1000 PRINT "1. LOAD":RETURN
2000 PRINT "2. SAVE":RETURN
3000 END
</pre>
:In case that the variable ''choice'' won't fullfil the condition (in a range between line 0 and 65535) the next instruction will be executed (here: Line 40). If "choice" is smaller than 0 an error will occur.

==== <code>ON SQ(x) GOSUB ln x1, x2, x3, x4, ...</code> ====
:ON SQ(x) can trigger an interrupt when e.g. a space or free channel in queue.
:Using that command is a one way interrupt trigger and shouldn't be mixed with <code>EVERY</code> or <code>AFTER</code> commands.

:See also the <code>SQ(x)</code> command for more details.

==== <code>OPENIN ‹filename›</code> ====
: Opens the specified data file for reading. It has to be an ASCII file. ( The command <code>CLOSEIN</code> closes reading data file. )
: Read from the file using <code>INPUT #9</code>

==== <code>OPENOUT ‹filename›</code> ====
: Opens the specified data file for writing. It writes an ASCII file. (To close writing use the command CLOSEOUT.)

NOTE: No file is likely to be written until enough data is written (e.g. 2KB) or the file has at least 1 byte written and CLOSEOUT is used.

NOTE: The following pattern can be used to set MEMORY and lower HIMEM lower than would normally be allowed. This doesn't cause any file to be written:

OPENOUT"<filename>
MEMORY address
CLOSEOUT

==== <code>ORIGIN x,y[,l,r,t,b]</code> ====
: The command defines the origin ('world reference point') for the graphics coordinate system. Normally the reference origin is in the left, bottom corner of the default screen and has 0,0. So the most left coordinate value could be by default 639 and the most top value 399. Independent from the actual modus (2, 1 or 0) the range for the x coordinate are always 640 points and for the y coordinate 400 points. In theory you are able to address 256,000 pixel but only 128,000 are visible due to the maximal resolution of the hardware.
: <code>x,y</code> are the the new coordinates for the 'world reference '.
: <code>l,r,t,b</code> are optional and set the borders for the new graphical window (works in the same way like the <code>WINDOW</code> command for a text window). l,r,t,b means left, right, tob and bottom coordinates.
: If a new graphical window (borders) is defined every point or drawn line won't be plotted (clipped internally).

: Example (the line drawn will be cutted):
<pre>
ORIGIN 320,200,250,450,100,300
DRAW 0,200
</pre>

==== <code>OUT ‹address›,‹value›</code> ====

: Outputs a value (range of 0-255) to a specific I/O address.
: Watch out http://cpcwiki.eu/index.php/I/O_Port_Summary

==== <code>PAPER[#‹stream expression›][,]</code> ====
: [...]

==== <code>PEN[#‹stream expression›][,]</code> ====
: [...]

==== <code>PLOT</code> ====
: [...]

==== <code>PLOTR</code> ====
: [...]

==== <code>POKE add</code> ====

: Alters contents of memory location add to value i (0-255)

==== <code>PRINT[#‹stream expression›][,]</code> ====
: [...]

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

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

==== <code>RANDOMIZE [seed]</code> ====

: Resets the pseudo-random generator to the given seed (starting value of the 'random' series). 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>

: <code>RANDOMIZE TIME</code> isn't still a 'real' random number but to hit the same series again is pretty hard due to the time elapsed.
: The algorithm used for randomizing is the following: the generator starts with the seed, adds 1, multiplies by 75 (fiddle factor), divides by 65537 and then uses the remainder -1.

==== <code>READ variable</code> ====
: 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>

==== <code>RELEASE chanel</code> ====
: Releases a sound which was hold on (by a SOUND command) before. It uses the same bit matrix like the SOUND command for the first parameter
# (&x00000001) releases chanel A
# (&x00000010) releases chanel B
# (&x00000011) releases chanel A and B
# (&x00000100) releases chanel C
# (&x00000101) releases chanel A and C
# (&x00000110) releases chanel B and C
# (&x00000111) releases chanel A, B and C

:Example:
<pre>
10 SOUND 65,1000,100
20 PRINT"PRESS R TO LET IT SOUND"
30 IF INKEY(50)=-1 THEN 30
40 RELEASE 1
</pre>

==== <code>REM [any text]</code> ====
: Introduces a comment.

==== <code>RENUM [‹newLine›][,‹oldLine› | ,[‹oldLine›],‹step›] </code>====
: Renumbers the lines of the current program.

: By default, the whole program is renumbered starting at line 10 with multiples of ten. Any parameter that is left out defaults to 10. It is important to note that ''jumps'' (<code>GOTO</code>, <code>GOSUB</code> 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 <code>RENUM 100,20,5</code>

<pre>
10 GOTO 100
100 GOTO 105
105 GOTO 10
</pre>

==== <code>RESTORE [line]</code> ====

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

==== <code>RESUME [line] or NEXT</code> ====
: Command causes the program to resume after an error code and if it is interrupted by an '''ON ERROR GOTO''' jump
: So it can either resume
*(if there's no line number stated) at the same line after error code (and if there are more statements in one line)
or
* at the line number stated (optional)
or
* with the NEXT parameter (optional) ... at the line followed by the error line

==== <code>RETURN</code> ====

: Terminates a subroutine and returns control to the line following the GOSUB call (see GOSUB)

==== <code>RUN [line] or "filename"</code> ====
:Runs the current program, optionally starting at a given line. If no line number is given, starts at the first line.

:If a string is used after RUN command a programm will be loaded and executed from storage medium (e.g. Tape, Disc). With that command protected BASIC programs can be executed.

:Exampel:
<pre>
RUN"disc"
</pre>

==== <code>SAVE "filename" [,filetype][,paramter1,parameter2,parameter3]</code> ====
: Command saves the current BASIC program / content from RAM onto a storage medium (e.g. Tape, Disc)

: Filetype could be:
* ''',A''' for a ASCII file
* ''',B''' for a binary file (store RAM content as it is)
* ''',P''' for a regular, ''protected'' BASIC file
: without that parameter the content will be stored as a regular BASIC file

:The three parameters after filetype could be used in combination with the binary filetype (,B).
* '''''parameter1''''' defines the starting address of memory range
* '''''parameter2''''' defines the length (range of memory)
* '''''parameter3''''' defines the entry point (optional)

==== <code>SOUND</code> ====
: the SOUND command has following shape:
: SOUND '''C'''hannel,'''P'''eriod,'''D'''uration,'''V'''olume,Volume-'''Env'''elope,'''T'''one-'''En'''velope,'''N'''oise

:'''C:''' Selecting channel is done bitwise (combinations are possible of course):

<pre>
(Bit 0) &x00000001 = 1 = channel A (middle)
(Bit 1) &x00000010 = 2 = channel B (left)
(Bit 2) &x00000100 = 4 = channel C (right)
</pre>
:more function about channel are
<pre>
(Bit 3) &x00001000 = 8 = Rendezvous with channel A
(Bit 4) &x00010000 = 16 = Rendesvous with channel B
(Bit 5) &x00100000 = 32 = Rendesvous with channel C
(Bit 6) &x01000000 = 64 = Hold
(Bit 7) &x10000000 = 128 = Flush
</pre>
:'''P:''' the period number can be a figure between 0 and 4095 (2^12-1... 12 means that we have 12 tones (inclusive half-tones) in nine octaves on the CPC in sum and their distance between is the twelves square root of two), where 8 octaves are available. E.g. Octave 0 starts on middle C with number 478.
: To calculate the period you can use following formula: '''period=1,000,000/(16*frequency)''' or in short '''period=(62,500/frequency)'''
: (e.g. the note "A" with the frequency 440 Hz has the period 142 on the CPC)

:'''D:''' the duration of the note is measured in 1/100th of a second and can be any positive number in the range 1-32,767. 0 and negative number are in combination with ENT and ENV commands usefull. A negative number means repititions.

:'''V:''' the volume number range from 0-7 on a CPC 464 (BASIC 1.0) or 0-15 on a CPC664/6128 (BASIC 1.1)

:'''ENV:''' and '''ENT:''' For shaping the sound ENV (Volume) and ENT (Frequency) commands are available. The relation between SOUND and those commands comes with a figure between 1 to 15 for ENV (5th parameter) and 1 to 15 for ENT (6th parameter).

:'''N:''' the seventh parameter can be used for blending in noise between the range of 0-15 (BASIC 1.0) or 0-30 (BASIC 1.1). The higher the number the 'deeper' or 'dirty' is the noise.

==== <code>SPC <n></code> ====
: in conjunction with PRINT the SPC command prints out a certain number (n) of spaces.
: Example:
<pre>
PRINT "Hello";SPC(10);"World";
Hello World
</pre>

==== <code>SPEED INK <n1,n2> </code> ====
: SPEED INK command defines the frequency of colour changes if a colour change was defined. The duration is calculated by n1=... or n2 =duration/50 seconds.

==== <code>SPEED KEY <start,repeat> </code> ====
: SPEED KEY command defines the delay after which a key repeat (for keys that do repeat). The first parameter is the delay before the first repeat and the second parameter is the delay between further repeats. Delay is in 1/50th of seconds.

:When using it with low values, it is common to associate a key to reset the default speed of 30,2.
:For example to associate the key 0 from the numpad:
<pre>
KEY 0,"SPEED KEY 30,2"+CHR$(13)
</pre>

==== <code>SPEED WRITE <n> </code> ====
: SPEED WRITE defines the speed at which data is to be saved or written to a cassette unit. n=1 means 2000 baud, n=0 (default) means 1000 baud. When reading from the tape, the correct speed is automatically selected.

==== <code>SQ (channel)</code> ====

: Returns a bit significant integer showing state of the sound queue for specified channel where channel 1,2,3, = A, B, C

: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

==== <code>STOP</code> ====

: Breaks program execution at line containing the STOP statement. The message '''BREAK in''' is output with the line number.

==== <code>SWAP</code> ====
: SWAP works only in combination with the window command. Every error or status messages from the operating system will be displayed normaly on WINDOW#0 (=''main'' window). WINDOW SWAP changes the ''main'' window to the desired target window.
: Example (if a window with number 4 was defined before...):
<pre>
WINDOW SWAP 0,4
</pre>

==== <code>SYMBOL n,i1[,i2,i3,i4,i5,i6,i7,i8]</code> ====

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

==== <code>SYMBOL AFTER n</code> ====
: 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.

==== <code>TAB</code> ====
: [...]

==== <code>TAG [#st]</code> ====

: Allows text to print at graphics cursor position.
: see TAGOFF

==== <code>TAGOFF [#st]</code> ====

: Directs text to stream st printing it at previous text cursor position.

==== <code>TROFF</code> ====

: Turns off the program flow trace (see TRON)

==== <code>TRON</code> ====

: Turns on the program flow trace for debugging. Causes the line number of each statement executed to be displayed.

==== <code>USING</code> ====
: The USING assignement defines the format of the PRINT output. Its appointment happens by characters where each has a certain meaning.

'''Numbers / Figures'''
: the character:
:'''#''' stands for a figure between 0 - 9
:'''.''' stands for a decimal point
:'''+''' generates a positive sign if the value is positive
:'''-''' generates a negative sign if the value is nagative
:'''**''' generates a asterix for each empty "location" before the printed character
:'''$$''' generates a Dollar characters before the printed character (the same with the pound note)
:''',''' generates a comma every each three decimals (thousands per figure) and has to be set before the decimal point or at the end if without a decimal point.
:^ generates a scientific notation (with exponents) and a the end of the format appointment

'''Strings'''
: the character:
:'''!''' prints out only the first character
:'''\xxx\''' prints out only with x-numbers defined length of the string (from left to right). x means a blank sign made with the space bar
:'''&''' the whole string is printed out as given (unknown function)

: a print output (numbers) with "%" in the beginning shows that not enough positions has to be declared (at all or before the decimal point).

: Example:
<pre>
10 figure=123456789
20 word$="Hello"
30 print using "+**,##########";figure
40 print using "\ \";word$

creates following output:

*****+12,345,679
Hel
</pre>

==== <code>WAIT add, i1[,i2]</code> ====

: Waits until the I/O port at add returns a value (0-255). The value returned is XORed with i2 and the ANDed with i1. This is repeated until a non-zero result occurs.

==== <code>WHILE WEND</code> ====
: [...]

==== <code>WIDTH</code> ====
: [...]

==== <code>WINDOW[#‹stream expression›],[L],[R],[T],[B]</code> ====
: It is possible to define in BASIC eight (8) independent windows for text output. Overlapping is possible.

: #STREAM: eight window are possible. No. zero (0) is the main window where error or status messages were put out by default.
: each position is included inside the window
: L = left column / R = right column (dependent of the mode 0 = 20 / 1 = 40 / 2 = 80)
: T = top row / B = bottom row (always from 1 to 25)

: Example:
<pre>
MODE 1
WINDOW#1,1,40,1,6
</pre>
: ...defines the first top quarter of the screen for window No. 1

==== <code>WRITE [#st,] v[$], v[$]</code> ====

: Writes the values of the specified variable to the specified stream.

: Example:

<pre>
10 OPENOUT "DUMMY"
20 INPUT A$,A
30 WRITE #9,A$,A
40 CLOSEOUT
</pre>

==== <code>ZONE i</code> ====

: Changes the width of the print zone. Default is 13.
: Example:
<pre>
10 MODE 2
20 PRINT"normal zone (13)"
30 PRINT 1,2,3,4
RUN
normal zone(13)
1 2 3 4
READY
20 PRINT"now with different zone(5)"
30 ZONE 5
40 PRINT 1,2,3,4
RUN
now with different zone(5)
1 2 3 4
READY
</pre>

=== Operators ===
: A logical status in Locomotive Basic will be represented by a "-1" for TRUE and by a "0" for FALSE.
: Example:
<pre>
PRINT (1=1)
-1
PRINT (1=2)
0
</pre>
==== <code>AND</code> ====
: Possible combinations with the AND Function:
<pre>
NPUT1 INPUT2 OUTPUT
======================
TRUE TRUE TRUE
FALSE FALSE FALSE
TRUE FALSE FALSE
FALSE TRUE FALSE
</pre>
: Example:
<pre>
PRINT 128 AND 64
0
</pre>
: looking at the BIT combination for a better understanding:
<pre>
10000000
AND 01000000
================
= 00000000
</pre>
: even in BASIC it is possible to manipulate single BITs although there are no special commands but AND, OR and XOR.
: first an example for a loop with an increasing counter WITHOUT an AND:
<pre>
10 counter=0
20 counter=counter+1
30 IF counter=32 THEN counter=0
40 GOTO 20
</pre>
: then a shorter example WITH and AND:
<pre>
10 counter=0
20 counter=(counter+1) AND 31
30 GOTO 20
</pre>
: in the second example all more significant BITs will be deleted (a common method in assembler programming)
: Beware: it only works here with BIT/number conditions one figure smaller than 1, 3, 7, 15, 31, 63 and 127
==== <code>MOD</code> ====
: '''MOD''' returns a (rounded) rest (Modulos) after dividen has been devided by the devisor.
:
:'''Example:'''
<pre>
32767 mod 256
255
</pre>
: Note: only works with numbers in the range -32768 and 32767 (&8000 < 0 < &7FFF)

==== <code>NOT</code> ====
: '''NOT''' executes a bit for bit '''negation''' of the current value. The output is a 16-Bit-Word.
:
:'''Example:'''
<pre>
10 value1=1
20 value2=NOT value1
30 PRINT value2
run
-2
</pre>
:for a better understanding...
<pre>
10 value1=1
20 PRINT HEX$(value1):PRINT BIN$(value1,8)
30 value2=NOT value1
40 PRINT HEX$(value2):PRINT BIN$(value2,8)
run
1
00000001
FFFE
1111111111111110
</pre>

==== <code>OR</code> ====
: Possible combinations with the OR Function:
<pre>
NPUT1 INPUT2 OUTPUT
======================
TRUE TRUE TRUE
FALSE TRUE TRUE
TRUE FALSE TRUE
FALSE FALSE FALSE
</pre>
==== <code>XOR</code> ====
: Possible combinations with the XOR Function:
<pre>
NPUT1 INPUT2 OUTPUT
======================
TRUE TRUE FALSE
FALSE TRUE TRUE
TRUE FALSE TRUE
FALSE FALSE FALSE
</pre>

=== Functions ===

==== <code><big>ABS (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the ABSolute value of the given numeric expression (n). This means that negative numbers are returned as positive.
: '''Associated keywords''': SGN

: '''Example''':

<pre>
PRINT ABS(-67.98)
67.98
</pre>

==== <code><big>ASC (<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the numeric value of the first character in the <string expression> (s).
: '''Associated keywords''': CHR$

: '''Example''':
<pre>
PRINT ASC("x")
120
</pre>
==== <code><big>ATN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the Arc-TaNgent of the <numeric expression> (n) to a real number ranging from -PI/2 to +PI/2 of the value specified.
: Note that DEG and RAD can be used to force the result of the below calculation to degrees or radians respectively.

: '''Associated keywords''': COS, DEG, RAD, SIN, TAN

: '''Example''':
<pre>
PRINT ATN(1)
0.785398163
</pre>
==== <code><big>BIN$ (<unsigned integer expression>,[<integer expression>])</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Produces a string of BINary digits respresenting the value of the <unsigned integer expression>, using the number of binary digits instruced by the second <integer expression> (in the range of 0 to 16). If the number of digits instructed is too great, the resulting expression will be filled with leading zeros; if the number of digits instructed is too small, the resulting expression will NOT be shortened to the instructed number of digits, but will produced in as many digits as are required.
: The <unsigned integer expression> to be converted into binary form must yield a value in the range -32768 to 65535.
: '''Associated keywords''': DEC$, HEX$, STR$
: '''Example''':
<pre>
PRINT BIN$(66,8)
01000000
</pre>
==== <code><big>CHR$ (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Converts an <integer expression> in the range 0 to 255, to its CHaRacter $tring equivalent, using the AMSTRAD character set shown in the ASCII table or e.g. in the manual part 3.
: Note that 0 to 31 are control characters; hence the below example prints CHR$(x) in the range 32 to 255
: '''Associated keywords''': ASC, LEFT$, RIGHT$, MID$, STR$

: '''Example''':
<pre>
10 FOR X=32 to 255
20 PRINT X;CHR$(X);
30 NEXT
</pre>
: A further 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.

: Control Codes Table:
<pre>
===============================================================================
| VALUE | NAME | PARAMETERS | EFFECT |
===============================================================================
| DEC | HEX | | | |
===============================================================================
| 0 | &00 | NUL | NONE | DOES NOTHING |
| 1 | &01 | SOH | 0-255 | PRINTS CHARACTER TO SCREEN |
| 2 | &02 | STX | NONE | TURNS TEXT CURSOR OFF |
| 3 | &03 | ETX | NONE | TURNS TEXT CURSOR ON IN IMMEDIATE MODE |
| 4 | &04 | EOT | 0-2 | SET SCREEN MODE |
| 5 | &05 | ENQ | 0-255 | PRINT CHARACTER AT GRAPHICS CURS. |
| 6 | &06 | ACK | NONE | TURNS ON TEXT SCREEN (SEE ALSO CHR$(21))|
| 7 | &07 | BEL | NONE | MAKE A SHORT BEEP |
| 8 | &08 | BS | NONE | MOVES TEXT CURSOR BACK ONE CHARACTER |
| 9 | &09 | TAB | NONE | MOVES TEXT CURSOR FORWARD ONE CHARACTER |
| 10 | &0A | LF | NONE | MOVES TEXT CURSOR DOWN ONE CHARACTER |
| 11 | &0B | VT | NONE | MOVES TEXT CURSOR UP ONE CHARACTER |
| 12 | &0C | FF | NONE | CLEARS SCREEN OR WINDOWS (= CLS) |
| 13 | &0D | CR | NONE | MOVES CURSOR TO LEFT EDGE OF WINDOW ON |
| | | | | CURRENT LINE |
| 14 | &0E | SO | 0-15 | SETS PAPER COLOUR |
| 15 | &0F | SI | 0-15 | SETS PEN COLOUR |
| 16 | &10 | DLE | NONE | DELETES CHARACTER UNDER TEXT CURSOR |
| 17 | &11 | DC1 | NONE | CLEARS LINE FROM LEFT OF WINDOW UP TO |
| | | | | AND INCLUDING CURRENT CHARACTER |
| 18 | &12 | DC2 | NONE | CLEARS FROM CURRENT CHARACTER TO RIGHT |
| | | | | EDGE OF THE WINDOW |
| 19 | &13 | DC3 | NONE | CLEARS FROM START OF WINDOW UP TO AND |
| | | | | INCLUDING CURRENT CHARACTER |
| 20 | &14 | DC4 | NONE | CLEARS FROM CURRENT CHARACTER TO END OF |
| | | | | WINDOW |
| 21 | &15 | NAK | NONE | TURNS OFF TEXT SCREEN (SEE ALSO CHR$(6))|
| 22 | &16 | SYN | 0 AND 1 | TURNS TRANSPARENT OPTION OFF AND ON |
| 23 | &17 | ETB | 0-3 | SET GRPAHICS PLOTTING MODE |
| 24 | &18 | CAN | NONE | CHANGE TO INVERSE CHARACTER DISPLAYING |
| 25 | &19 | EM | NINE PARAM. | DEFINES A CHARACTER (= SAME AS SYMBOL) |
| | | | EACH 0-255 | |
| 26 | &1A | SUB | FOUR PARAM. | DEFINES A TEXT WINDOW (=SAME AS WINDOW) |
| | | | 1-80, 1-80 | FROM LEFT, RIGHT, TOP TO BOTTOM |
| | | | 1-25, 1-25 | FROM LEFT, RIGHT, TOP TO BOTTOM |
| 27 | &1B | ESC | NONE | DOES NOTHING ON SCREEN (PRINTER SIGNAL) |
| 28 | &1C | FS | THREE PARAM. | SETS INK COLOUR TO FLASH BETWEEN TWO |
| | | | 0-15, 0-32 | INK NO, COLOUR 1, COLOUR 2 |
| | | | 0-32 | |
| 29 | &1D | GS | TWO PARAM. | SETS BORDER COLOUR TO FLASH BETWEEN TWO |
| | | | 0-31, 0-31 | COLOURS |
| 30 | &1E | RS | NONE | HOMES CURSOR TO TOP LEFT OF SCREEN |
| 31 | &1F | US | TWO PARAM. | MOVES CURSOR TO CELL SPECIFIED BY TWO |
| | | | 1-80, 1-25 | PARAMETERS (=SAME AS LOCATE) |
===============================================================================
</PRE>

==== <code><big>CINT (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the value of the <numeric expression> (n), Converting it to a rounded INTeger in the range -32768 to 32767.

: '''Associated keywords''': CREAL, FIX, INT, ROUND, UNT

: '''Example''':
<pre>
10 n=1.9999
20 PRINT CINT(n)
run
2
</pre>
==== <code><big>COPYCHR$ (#stream)</big></code> ====
: : ''BASIC 1.1''
: '''FUNCTION''': COPies a CHaRacter from the current position in the stream (which MUST be specified). The below program copies a character from location 1,1 (top left), and reproduces it at location 1,20.
: If the character read is not recognized, a null string is returned.

: '''Associated keywords''': LOCATE

: '''Example''':
<pre>
10 CLS
20 PRINT "top corner"
30 LOCATE 1,1
40 a$=COPYCHR$(#0)
50 LOCATE 1,20
60 PRINT a$
</pre>
==== <code><big>COS (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the COSinus of the <numeric expression> (n).
: Note that DEG and RAD can be used to force the result of the below calculation to degrees or radians respectively.

: '''Associated keywords''': ATN, DEG, RAD, SIN

: '''Example''':
<pre>
DEG
PRINT COS(45)
0.707106781
</pre>
==== <code><big>CREAL (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the value of the <numeric expression> (n), Converting it to REAL.

: '''Associated keywords''': CINT

: '''Example''':
<pre>
10 a=PI
20 PRINT CINT(a)
30 PRINT CREAL(a)
run
3
3.14159265
</pre>
==== <code><big>DEC$(<numeric expression>, <format template>)</big></code> ====
: ''BASIC 1.1''
: '''FUNCTIION''': Returns a DECimal string representation of the <numeric expression> (n), using the specified <format template> to control the print format of the resulting string.
: The format template may contain ONLY the characters:

: + - $ £ * # , . ^

: The use of these 'format field specifiers' is described under the keyword PRINT USING.

: '''Associated keyword''': BIN$, HEX$, PRINT USING, STR$

: '''Example''':
<pre>
PRINT DEC$(10^7,"££########,.##")
£10,000,000.00
</pre>
==== <code><big>DERR</big></code> ====
: ''BASIC 1.1''
: '''FUNCTION''': Reports the last error code returned by the disc filing system. The value of DERR may be used to ascertain the particular Disc ERRor that occurred. See the listing of error messages below.

: '''Associated keywords''': ERL, ERR, ERROR, ON ERROR GOTO, RESUME

: '''Example''':
<pre>
LOAD "xyz.abc"

XYZ .ABC not found
Ready
PRINT DERR
146
</pre>
: '''Table of Disc ERRor codes''':
: If AMSDOS has already reported an error, then bit 7 is set, hence the value of DERR is offset by 128.
<pre>
===============================================================================
| VALUE | DERR value | DESCRIPTION |
===============================================================================
| 0 | 0 or 22 | [ESC] has been pressed |
| 14 | 142 (128+14) | The stream is not in a suitable state. |
| 15 | 143 (128+15) | Hard end of file has been reached. |
| 16 | 144 (128+16) | Bad command, usually an incorrect filename. |
| 17 | 145 (128+17) | File already exists. |
| 18 | 146 (128+18) | File does not exists. |
| 19 | 147 (128+19) | Directory is full. |
| 20 | 148 (128+20) | Disc is full. |
| 21 | 149 (128+21) | Disc changed while file were open. |
| 22 | 150 (128+22) | File is Read/Only. |
| 26 | 154 (128+26) | Soft end of file has been detected. |
| | | |
===============================================================================
</pre>
: Other values returned by DERR originate from the disc controller and are bit significant, always with bit 6 set.
: The significance of each bit is as follows:
<pre>
===============================================================================
| BIT | Significance |
===============================================================================
| 0 | Address mark missing. |
| 1 | Not writable - disc is write protected. |
| 2 | No data - can't find the sector. |
| 3 | Drive not ready - no disc in the drive. |
| 4 | Overrun error. |
| 5 | Data error - CRC error. |
| 6 | Always set to 1 to indicate error from disc controller. |
| 7 | Set to 1 if error has already been reported by AMSDOS. |
===============================================================================
</pre>
==== <code><big>EOF</big></code> ====
: ''BASIC 1.1''
: '''FUNCTION''': Checks to see if end of specified file has been reached during input. Returns 0 (false) until the end of file, then -1 (true).

: '''Associated keywords''': OPENIN, CLOSEIN

: This '''example''' reads a file from disc and print it out on screen. Like the "TYPE" command in CP/M or "|TYPE,file" of the UTOPIA-ROM.
<pre>
10 OPENIN "text.txt"
20 WHILE NOT EOF
30 LINE INPUT#9,a$
40 PRINT a$
50 WEND
60 CLOSEIN
</pre>
==== <code><big>ERR</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the number of the last ERRor encountered. See the table below of error messages. In the example below you will see that ERRor number 8 is a 'Line does not exist' error.

: '''Example''':
<pre>
GOTO 500
Line does not exist
Ready
PRINT ERR
8
</pre>
: NOTE: BASIC 1.0 (officially) describes error codes until 30 (without an attached floppy disc controller). 31 & 32 are floppy disc error codes.
: '''Table of ERRor codes''':
<pre>
========================================================================================
| VALUE | NAME | DESCRIPTION |
========================================================================================
| 1 |Unexpected NEXT |A NEXT command has been encountered while not in a |
| | |FOR loop, or the control variable in the NEXT |
| | |command does not match that in the FOR. |
| 2 |Syntax Error |BASIC cannot understand the given line because |
| | |a construct within it is not legal. |
| 3 |Unexpected RETURN |A RETURN command has been encountered when not in a |
| | |subroutine. |
| 4 |DATA exhausted |A READ command has attempted to read beyond the end |
| | |of the last DATA. |
| 5 |Improper Argument |This is a general purpose error. The value of a |
| | |function's argument, or a command parameter is |
| | |invalid in some way. |
| 6 |Overflow |The result of an arithmetic operation has over- |
| | |flowed. This may be a floating point overflow, in |
| | |which case some operation has yielded a value |
| | |greater than 1.7E^38 (approx.). Alternatively, this |
| | |may be the result of a failed attempt to change a |
| | |floating point number to a 16 bit signed integer. |
| 7 |Memory full |The current program or its variables may be simply |
| | |too big, or the control structure is too deeply |
| | |nested (nested GOUSBs, WHILEs or FORs). |
| | |A MEMORY command will give this error if an attempt |
| | |is made to set the top of BASIC's memory too low, or|
| | |to an impossible high value. Note that an open file |
| | |has a buffer allocated to it, and that may restrict |
| | |the values that MEMORY may use. |
| 8 |Line does not exist |The line referenced cannot be found. |
| 9 |Subcript out of range |One of the subscripts in an array reference is too |
| | |big or too small. |
| 10 |Array already dimensioned|One of the arrays in a DIM statement has already |
| | |been declared. |
| 11 |Division by zero |May occur in real division, integer division, |
| | |integer modulus or exponentiation. |
| 12 |Invalid direct command |The last command attempted is not valid in direct |
| | |mode. |
| 13 |Type mismatch |A numeric value has been presented where a string |
| | |value is required or vice versa, or an invalidly |
| | |formed number has been found in READ or INPUT. |
| 14 |String space full |So many strings have been created that there is no |
| | |further room available, even after 'garbage |
| | |collection'. |
| 15 |String too long |Strings exceeds 255 characters in length. May be |
| | |generated by appending strings together. |
| 16 |String expression too |String expressions may generate a number of |
| |complex |intermediate string values. When the number of these|
| | |values exceeds a reasonable limit, this error |
| | |results. |
| 17 |Cannot CONTinue |For one reason or another the current program |
| | |be restarted using CONT. Note that CONT is intended |
| | |for restarting after a STOP command, [ESC][ESC], |
| | |or an error, and that any alteration of the |
| | |program in the meantime makes a restart impossible. |
| 18 |Unknown user function |No DEF FN has been executed for the FN just |
| | |invoked. |
| 19 |RESUME missing |The end of the program has been encountered while |
| | |in error processing mode (i.e. in an ON ERROR GOTO |
| | |routine). |
| 20 |Unexpected RESUME |RESUME is only valid while in error processing mode |
| | |(i.e. in an ON ERROR GOTO routine). |
| 21 |Direct command found |When loading a file, a line without a line number |
| | |has been found. |
| 22 |Operand missing |BASIC has encountered an incomplete expression. |
| 23 |Line too long |A line when converted to BASIC internal-form becomes|
| | |too big. |
| 24 |EOF met |An attempt has been made to read past end of the |
| | |file input stream. |
| 25 |File type error |The file being read is not of a suitable type. |
| | |OPENIN is only prepared to open ASCII text files. |
| | |Similarly, LOAD, RUN, etc, are only prepared to |
| | |deal with file types produces by SAVE. |
| 26 |NEXT missing |Cannot find a NEXT to match a FOR command. A line |
| | |number accompanying this message indicates the FOR |
| | |command to which this error applies. |
| 27 |File already open |An OPENIN or OPENOUT command has been executed |
| | |before the previously opened file has been closed. |
| 28 |Unknown command |BASIC cannot find a taker for an external command, |
| | |i.e. a command preceded by a bar |. |
| 29 |WEND missing |Cannot find a WEND to match a WHILE command. |
| 30 |Unexpected WEND |Encountered a WEND when not in a WHILE loop, or a |
| | |WEND that does not match the current WHILE loop. |
| 31 |File not open |(see 'Disc ERRors above). |
| | |If access attempted when no file was open. |
| 32 |Broken in |(see 'Disc ERRors above). |
| | |If access attempted when no file was open. |
| | | |
| | |If value 31 or 32 are stated, DERR could be |
| | |interrogate to give more detailed information. |
| | |(see example below.) |
========================================================================================
</pre>
: '''Example for ERR 31 / 32''':
<pre>
10 ON ERROR GOTO 1000
20 OPENOUT "myfile.asc"
30 WRITE #9,"test-data"
40 CLOSEOUT
50 END
1000 amsdoserr=(DERR AND &7F):REM mask off bit 7
1010 IF ERR<31 THEN END
1020 IF ERR=31 THEN PRINT "are you sure you've typed line 20 correctly?":END
1030 IF amsdoserr=20 THEN PRINT "disc is full, suggest you use a new data disc":END
1040 IF amsdoserr=&X01001000 THEN PRINT "put a disc in the drive, then press a key":WHILE INKEY$="":WEND:RESUME
1050 END
</pre>
==== <code><big>EXP (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates 'E' to the power given in the <numeric expression> (i), where 'E' is approximately 2,7182818-the number whose natural logarithm is 1.

: '''Associated keywords''': LOG

: '''Example''':
<pre>
PRINT EXP(6.876)
968.743625
</pre>
==== <code><big>FIX (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Unlike CINT, FIX merely removes the part of the numeric expression, to the right of the decimal point, and leaves an integer result, rounding towards zero.

: '''Associated keywords''': CINT, INT, ROUND

: '''Example''':
<pre>
PRINT FIX(9.99999)
9
</pre>
==== <code><big>FRE (<numeric expression>/<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Establishes how much FREe memory remains unused by BASIC. The form FRE("") forces a 'GARBAGE COLLECTION' before returning a value for available space.
: NOTE: BASIC uses only the first 64K of the memory.

: '''Associated keywords''': HIMEM, MEMORY

: '''Examples''':
<pre>
PRINT FRE(0) or PRINT FRE("hello")
PRINT FRE("")
</pre>
==== <code><big>HEX$ (<unsigned integer expression>, <field width>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Produces a $tring of HEXadecimal digits representing the value of the <unsigned integer expression>, using the number of hexadecimal digits instructed by the <field width> (in the range 0 to 16). If the number of digits instructed is too great, the resulting expression will be filled with leading zeros; if the number of digits instructed is too small, the resulting expression will NOT be shortened to the instructed number of digits, but will be produced in as many digits as are required.
: The <unsigned integer expression> to be converted into hexadecimal form must yield a value in the range -32768 to 65535.

: '''Accociated keywords''': BIN$, DEC$, STR$, UNT

: '''Example''':
<pre>
PRINT HEX$(255,4)
00FF
</pre>
==== <code><big>HIMEM</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the address of the Highest byte of Memory use by BASIC, (which may altered by e.g. the MEMROY command).
: Before resetting the highest byte of available memory using the MEMORY command, it is advisable to issue the 'command mm=HIMEM'. You will thereafter be able to return to the previous memory capacity by issuing the command: 'MEMORY mm'
: NOTE: BASIC uses only the first 64K of memory.

: Associated keywords: FRE, MEMORY, SYMBOL, SYMBOL AFTER.

: '''Example''':
...on a CPC464
<pre>
PRINT HIMEM
43903
</pre>
...on a CPC6128
<pre>
PRINT HIMEM
42619
</pre>
==== <code><big>INKEY (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': INterrogates the KEYboard to report which keys are being pressed. The keyboard is scanned every 0.02 (1/50) second.
: The function is useful for spotting whether a certain key is down or up, by detecting the returned value of -1 (which occurs regardless of [SHIFT] and [CONTROL] key status).
: The example below detects when [SHIFT] and V (key number 55) are pressed together, then ends the program. Refer the manual for the key numbers.

: '''Associated keywords''': CLEAR INPUT, INKEY$, JOY

: '''Example''':
<pre>
10 IF INKEY(55)<>32 THEN 10
20 PRINT "You've pressed [SHIFT] and V"
30 CLEAR INPUT
run
</pre>
: The state of [SHIFT] and [CONTROL] in conjunction with the key specified in the <integer expression> is identified as follows:
<pre>
==============================================================================
|Value returned |[SHIFT] |[CTRL] |Specified key |
==============================================================================
|-1 |ignored |ignored |up |
|0 |up |up |down |
|32 |down |up |down |
|128 |up |down |down |
|160 |down |down |down |
==============================================================================
</pre>
==== <code><big>INKEY$</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': INterrogates the KEYboard, returning the current $tring reflecting any key that is pressed. It provides operator interaction without hitting [ENTER] after every answer. If there is a key pressed, then the function responds. If no key is pressed, INKEY$ returns an empty string.
: In the example below, lines 40 and 70 tell the program to loop back to line 30 after interrogating the keyboard string.

: '''Associated keywords''': CLEAR INPUT, INKEY

: '''Example''':
<pre>
10 CLS
20 PRINT "Select Yes or No (Y/N)?"
30 a$=INKEY$
40 IF a$="" THEN 30
50 IF a$="y" OR a$="Y" THEN 80
60 IF a$="N" OR a$="n" THEN 90
70 GOTO 30
80 PRINT "You have selected YES": END
90 PRINT "You have selected NO":
run
</pre>
==== <code><big>INP (‹port number›)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the INPut value from the I/O address specified in the <port number>.

: '''Associated keywords''': OUT, WAIT

: Watch out http://cpcwiki.eu/index.php/I/O_Port_Summary

: '''Example''':
<pre>
PRINT INP(&FF00)
255
Ready
</pre>
==== <code><big>INSTR ([‹startposition›,]‹searched string›, ‹searched for string›)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Searches the first <searched string> expression to find the first occurance of the <searched for string expression<, and reports the position of its occurance within the <searched string>. If the <searched for string> does not occur within the <searched string>, then 0 is reported.
: The position at which to start searching the <searched string> is optionally specifiable using the <start position> parameter which must yield an integer number in the range 1 to 255.

: '''Associated keywords''': none

: '''1. Example''':
<pre>
a$="ABCD":PRINT INSTR(a$,"C")
3
Ready
</pre>
: '''2. Example''':
<pre>
a$="Hello":IF INSTR(a$,"i")<>0 THEN PRINT "no" else a$
no
Ready
</pre>
: '''3. Example''':
<pre>
10 CLS
20 alphabet$="ABCDEFGHIJKLMNOPQRSTUVWXYZ"
30 INPUT "Enter a letter";a$
40 b$=UPPER$(a$)
50 PRINT b$;" is number";
60 PRINT INSTR(alphabet$,b$);
70 PRINT "in the alphabet.":PRINT
80 GOTO 40
run
</pre>
==== <code><big>INT (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Rounds the number to the nearest smaller INTeger, removing any fractional part. Returns then same value as FIX for positive number, but returns one less than FIX for negative numbers which are not already integers.

: '''Associated keyword''': CINT, FIX, ROUND

: '''Example''':
<pre>
PRINT INT(3.99), INT(-3.99)
3 -4
</pre>
==== <code><big>JOY (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': The JOY function reads a bit significant result from the joystick in the <integer expression> (either 0 or 1).
<pre>
================================
|Bit | Value decimal |
================================
|0(up) | 1 |
|1(down) | 2 |
|2(left) | 4 |
|3(right) | 8 |
|4(fire 2) | 16 |
|5(fire 1) | 32 |
================================
</pre>
==== <code><big>LEFT$ (<string expression>, <required length>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the number of characters (in the range 0 to 255) specified in the <required length> parameter (<integer expression>), after extracting them from the LEFT of the <string expression>. If the <string expression> is shorter than the <required length>, the whole <string expression> is returned.

: '''Associated keywords''': MID$, RIGHT$

: '''1. Example''':
<pre>
A$="ABCDEFG":PRINT LEFT$(A$,3) - prints ABC
</pre>
: '''2. Example''':
<pre>
10 CLS
20 a$="AMSTRAD"
30 FOR n=1 to 7
40 PRINT LEFT$(a$,n)
50 NEXT
run
</pre>
==== <code><big>LEN (<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the total number of characters (i.e. the LENgth) of the <string expression>.

: '''Associated keywords''': none

: '''Example''':
<pre>
10 LINE INPUT "Enter a phrase";a$
20 PRINT "The phrase is";
30 PRINT LEN(a$);"characters long."
run
</pre>
==== <code><big>LOG (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the natural LOGarithm (base of ''e'') of <numeric expression> which mustbe greater than zero.

: '''Associated keywords''': EXP, LOG10

: '''Example''':
<pre>
PRINT LOG(9999)
9.21024037
</pre>
==== <code><big>LOG10 (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the logarithm to base 10 of <numeric expression> which must be greater than zero.

: '''Associated keywords''': EXP, LOG

: '''Example''':
<pre>
PRINT LOG10(9999)
3.99995657
</pre>
==== <code><big>LOWER$ (<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns a new string expression which is a copy of the specified <string expression> but in which all alphabetic characters in the range A to Z are converted to lower case. Useful for processing input where the answers may come in mixed upper/lower case.

: '''Associated keywords''': UPPER$

: '''1. Example''':
<pre>
A$="AMSTRAD":PRINT A$="AMSTRAD":PRINT LOWER$(A$)
Amstrad
</pre>
: '''2. Example''':
<pre>
10 a$="SEE HOW THE LETTERS CHANGE TO ... NUMBERS 1234 NOT..."
20 PRINT LOWER$(a$+"LOWER CASE")
see how the letters change to ... numbers 1234 not... LOWER CASE
</pre>
==== <code><big>MAX (<list of: numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the MAXimum value from the <list of: numeric expression>s.

: '''Associated keywords''': MIN

: '''Example''':
<pre>
10 n=66
20 PRINT MAX(1,n,3,6,4,3)
run
66
</pre>
==== <code><big>MIN (<list of: numeric expression>)</big></code> ====
''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the MINimum value from the <list of: numeric expression>s.
: '''Associated keywords''': MAX

: '''Example''':
<pre>
PRINT MIN (3,6,2.999.8,9,)
2.999
</pre>

==== <code><big>PEEK (<address expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the contents of the Z80 memory location specified in the <address expression> which should be in the range &0000 to &FFFF (0 to 65535). In all cases PEEK will return the value at the RAM address specified (not the ROM), and will be in the range &00 to &FF (0 to 255)

: '''Associated keywords''': POKE

: '''Example''':
<pre>
10 MODE 1: ZONE 7
20 WINDOW 1,40,1,2:WINDOW #1,1,40,3,25
30 PRINT "memory-address"
40 LOCATE 20,1:PRINT "memory-contents"
50 FOR n=1 to 65535
60 p=PEEK(n)
70 PRINT #1,n,"(&";HEX$(n);")";
80 PRINT #1,TAB(20);p,"(&";HEX$(p);")"
90 NEXT
run
</pre>
==== <code><big>PI</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': The value of the ratio between the circumference and the diameter of a circle.

: '''Associated keywords''': DEG, RAD

: '''Example''':
<pre>
PRINT PI
3.14159265
</pre>
==== <code><big>POS (#<stream expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current horizontal POSition of the text cursor relative to the left edge of the text window. The <stream expression> MUST be specified, and does NOT default to #0.
: POS(#8) reports the current horizontal carriage position for the printer, where 1 is the extreme left hand edge.
: POS(#9) reports the logical position in the disc file stream, i.e. the number of printing characters sent to the stream since the last carriage return.

: '''Associated keywords''': VPOS, WINDOW
: '''Example''':
<pre>
10 MODE 1: BORDER 0:LOCATE 8,2
20 PRINT "use cursor left/right keys"
30 WINDOW 1,40,12,12:CURSOR 1,1
40 FOR n=1 TO 19:PRINT CHR$(9);:NEXT
50 IF INKEY(1)<>-1 THEN PRINT CHR$(9);
60 IF INKEY(8)<>-1 THEN PRINT CHR$(8);
70 LOCATE #1,2,24
80 PRINT #1,"text cursor ";
90 PRINT #1,"horizontal position = ";
100 PRINT #1,POS(#0):GOTO 50
run
</pre>
==== <code><big>REMAIN (<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns count REMAINing count from the delay timer specified in <integer expression> (= timer number in the range 0 to 3), and disable it. If the delay timer was not enabled zero will be returned.

: '''Associated keywords''': AFTER, DI, EI, EVERY

: For the reason that REMAIN is no normal command but a "function" it is necessary in case of a proper functionality to link the command.
: an '''example''' in combination with an interrupt delay timer 1:
<pre>
PRINT REMAIN(1)
</pre>
: or to stop several/all interrupts at the same time...
<pre>
A=REMAIN(0)=REMAIN(1)=REMAIN(2)=REMAIN(3)
</pre>
: Hint: Take care of interrupts due to parallel working (the same cycle time) or if they are stopped with the BREAK key. Interrupts which were disabled for a certain time will be stored in buffer (for a maximum of 128 entries) and made up their task afterwards in the priorisation as declared.
: further '''example''':
<pre>
10 AFTER 500,1 GOSUB 40
20 AFTER 100,2 GOSUB 50
30 PRINT "program running":GOTO 30
40 REM this GOUSB-Routine will not be called as it is disabled in line 80
50 PRINT:PRINT "Timer 1 will now be ";
60 PRINT "disabled by REMAIN."
70 PRINT "Time-units remaining were:";
80 PRINT REMAIN(1)
run
</pre>
==== <code><big>RIGHT$ (<string expression>, <integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the number of characters (in the range 0 to 255) specified in the <integer expression> (=required length) parameter, after extracting them from the RIGHT of the <string expression>. If the <string expression> is shorter than the <integer expression>, the whole <string expression> is returned.

: '''Associated keywords''': LEFT$, MID$

: '''Example''':
<pre>
10 MODE 1:a$="AMSTRAD computer"
20 FOR n=1 TO 16:LOCATE 41-n,n
30 PRINT RIGHT$(a$,n)
40 NEXT
</pre>
==== <code><big>RND [(<numeric expression>)]</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the next RaNDom number in sequence if the <numeric expression> has a positive value or is not specified.
: If the <numeric expression> yields a value of zero, RND returns a copy of the last random number generated.
: If the <numeric expression> yields a negative value, a new random number sequence is started, the first number of which is returned.

: '''Associated keywords''': RANDOMIZE

: '''1. Example''':
<pre>
PRINT RND(0)
0.536703827
Ready
PRINT RND(1)
0.271940658
Ready
PRINT RND(0)
0.271940658
Ready
</pre>
: '''2. Example''':
: Example for generating an integer random number between 1 and 1000
<pre>
10 A=INT((RND(1)*1000)+1)
20 PRINT A
30 GOTO 10
</pre>
: '''3. Example''':
: For generating a random number between a lower and higher border
<pre>
10 INPUT "Low border",low
20 INPUT "High border",high
30 A=INT(RND(1)*(high-low))+low
40 PRINT A
</pre>
: '''4. Example''':
<pre>
10 RANDOMIZE
20 FOR x=1 TO -1 STEP -1
30 PRINT "rnd parameter=";x
40 FOR n=1 TO 6
50 PRINT RND(x)
60 NEXT n,x
run
</pre>

==== <code><big>ROUND (<numeric expression>[,<integer expression>])</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Rounds <numeric expression> to a number of decimal places or to the power of ten specified by <integer expression>. If <integer expression> less than zero, the <numeric expression> is rounded to give an absolute integer with <integer expression> number of zeros before the decimal point.

: '''Associated keywords''': ABS, CINT, FIX, INT
: '''1. Example''':
<pre>
PRINT ROUND(1562.357,2),ROUND(1562.375,-2)
1562.36 1600
</pre>
: '''2. Example''':
<pre>
10 FOR n=4 TO -4 STEP -1
20 PRINT ROUND (1234.5678,n)
30 PRINT "with integer expression";n
40 NEXT
run
</pre>
==== <code><big>SGN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: FUNCTION: Determines the SiGN of the <numeric expression>. Returns -1 if <numeric expression> is less than 0, returns 0 if <numeric expression> = 0, and returns 1 if <numeric expression> is greater than zero.

: '''Associated keywords''': ABS

: '''Example''':
<pre>
10 FOR n=255 to -200 STEP -20
20 PRINT "SGN returns";
30 PRINT SGN(n);"for a value of";n
40 NEXT n
run
</pre>
==== <code><big>SIN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the Real value for the Sine of <numeric expression>, defaulting to the Radian (RAD) measure mode unless otherwise declared by a DEG command.

: '''Associated keywords''': ATN, COS, DEG, RAD, TAN

: '''Example''':
<pre>
10 CLS:DEG:ORIGIN 0,20
20 FOR n=0 to 720
30 y=SIN(n)
40 PLOT n*640/720,198*y:NEXT
50 GOTO 50
run
</pre>
==== <code><big>SPACE$(<integer expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Creates a string of spaces of the given length, (in the range 0 to 255) specified in the <integer expression>.

: '''Associated keywords''': SPC, STRING$, TAB

: '''Example''':
<pre>
10 MODE 1
20 PRINT "Put 9 spaces between me";
30 PRINT SPACE$(9);
40 PRINT "and you!"
run
</pre>
==== <code><big>SQ (<channel>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the state of the Sound Queue for the specified <channel> which must be an integer expression, yielding one the values:
: 1: for channel A
: 2: for channel B
: 4: for channel C
: The SQ function returns a bit significant integer, comprising the following bit settings:
: Bit 0,1 and 2: the number of free entries in the queue
: Bit 3,4 and 5: the rendezvous state at the head of this queue
: Bit 6 : the head of the queue is held
: Bit 7 : the channel is currently active
: ... where Bit 0 is the least significant bit, and Bit 7 is the most significant bit.
: It can be seen, that if Bit 6 is set, Bit 7 cannot be set at the same time, and vice versa. Similarly if Bits 3, 4, or 5 are set, Bit 6 and 7 cannot be set.

: '''Associated keywords''': ON SQ GOSUB, SOUND

: '''Example''':
<pre>
10 SOUND 65,100,100
20 PRINT SQ(1)
run
67
</pre>
==== <code><big>SQR (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the SQuare Root of the specified <numeric expression>.

: '''Associated keywords''': none

: '''Example''':
<pre>
PRINT SQR(9)
3
</pre>
==== <code><big>STR$ (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Converts the <numeric expression> to a decimal STRing representation.
: Useful for converting a number to a string in case of string manipulation. E.g. after converting a figure to a string then the most left character holds the sign: a minus in case the figure is negative and a space in case the figure is positiv.

: '''Associated keywords''': BIN$, DEC$, HEX$, VAL

: '''1. Example''':
<pre>
10 FIGURE=-1599
20 FIGURE$=STR$(FIGURE)
30 PRINT FIGURE$
-1599
</pre>
: '''2. Example''':
<pre>
10 FIGURE=1769
20 FIGURE$=STR$(FIGURE)
30 PRINT FIGURE$
1769
</pre>
: '''NOTE''': (there's a blank on the left-hand of the number "1769")
: If you want to add e.g. zero before the figure in case of a high score with fix digit-number then you're able to add zero(s) in front of a string instead of a figure.

: '''3. Example''':
<pre>
10 a=&FF:REM 255 hex
20 b=&x1111:REM 15 binary
30 c$="***"
40 PRINT c$+STR$(a+b)+c$
run
*** 270***
</pre>

==== <code><big>STRING$ (<length>,<character specifier>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns a string expression consisting of the <character specifier> repeated the number of time (in the range 0 to 255) specified in the <length>.

: '''Associated keywords''': SPACE$

: '''1. Example''':
<pre>
PRINT STRING$(40,"*")
****************************************
</pre>
: '''2. Example''':
<pre>
PRINT STRING(40,42)
****************************************
</pre>
: '''NOTE''': the <character specifier> 42 refers to the ASCII value of the character '*' and is also equivalent to PRINT STRING$(40,CHR$(42))
==== <code><big>TAN (<numeric expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Calculates the TANgent of the <numeric expression>, which must be in the range -200,000 to +200,000.
: '''NOTE''': DEG and RAD can be used to force the result of the calculation to degrees or radians respectively.

: '''Associated keywords''': ATN, COS, DEG, RAD, SIN

: '''Example''':
<pre>
PRINT TAN(45)
1.61977519
</pre>

==== <code><big>TEST (<x co-ordinate>,<y co-ordinate>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Moves the graphics cursor to the absolute position specified by the <x> and <y co-ordinate>s, and reports the value of the ink at the new location.

: '''Associated keywords''': MOVE, MOVER, TESTR, XPOS, YPOS

: '''Example''':
<pre>
10 CLS
20 PRINT "Your are using pen number";
30 PRINT TEST(10,386)
40 PRINT "Try changing PENs and MODEs";
50 PRINT "....then RUN again."
run
</pre>
==== <code><big>TESTR (<x offset>,<y offset>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Moves the graphics cursor by the amount specified in the <x> and <y offset>s relative to its current position, and reports the value of the ink at the new location.

: '''Associated keywords''': MOVE, MOVER, TEST, XPOS, YPOS

: '''Example''':
<pre>
10 MODE 0:FOR x=1 TO 15:LOCATE 1,x
20 PEN x:PRINT STRING$(10,143);:NEXT
30 MOVE 200,400:PEN 1
40 FOR n=1 TO 23:LOCATE 12,n
50 PRINT "pen";TESTR(0,-16):NEXT
run
</pre>
==== <code><big>TIME</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the elapsed time since the computer was last switched-on or reset, (excluding periods when reading or writing to disc).
: Each second of real time is equal to the returned value = TIME/300.

: '''Associated keyword''': AFTER, EVERY, WEND, WHILE

: '''Example''':
<pre>
10 CLS:REM clock
20 INPUT "hour";hour
30 INPUT "minute";minute
40 INPUT "second";second
50 CLS:datum=INT(TIME/300)
60 WHILE hour<13
70 WHILE minute<60
80 WHILE tick<60
90 tick=(INT(TIME/300)-datum)+second
100 LOCATE 1,1
110 PRINT USING "## ";hour,minute,tick
120 WEND
130 tick=0:second=0:minute=minute+1
140 GOTO 50
150 WEND
160 minute=0:hour=hour+1
170 WEND
180 hour=1
190 GOTO 60
run
</pre>
==== <code><big>UNT (<address expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Return an integer in the range -32768 to +32767 which is the twos-complement equivalent of the unsigned value of the <address expression>.

: '''Associated keywords''': CINT, FIX, INT, ROUND

: '''Example''':
<pre>
PRINT UNT(&FF66)
-154
</pre>
==== <code><big>UPPER$(<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns a new string expression which is a copy of the specified <string expression> but in which all alphabetic characters in the range A to Z are converted to upper case. The function is useful for processing input which may come in mixed upper / lower case.

: '''Associated keywords''': LOWER$

: '''Example''':
<pre>
10 CLS: a$="my, how you've grown!"
20 PRINT UPPER$(a$)
run
</pre>
==== <code><big>VAL(<string expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Returns the numeric VALue, (including any negative sign and decimal point) of the first character(s) in the specified <string expression>.
:If the first character is not a number, then 0 is returned. If the first character is a negative sign or decimal point followed by non-numeric characters, a 'Type mismatch' error (13) will be reported.

: '''Associated keywords''': STR$

: '''1. Example''':
<pre>
PRINT VAL("-12.34x"),VAL("A-12")
-12.34 0
</pre>
: '''Exception''': if <se> starts with "&" + character (and it's between "A" and "F") the whole character will be handled like a hexadezimal numeric character (...often used in DATA Loaders). The returning numeric value is a  signed integer (16-Bit Word).
: '''2. Example''':
<pre>
PRINT VAL("&A")
10

PRINT VAL("&7FFF")
32767

PRINT VAL("&8000")
-32768
</pre>
: '''3. Example''':
<pre>
10 CLS: PRINT "I know my times tables!"
20 PRINT:PRINT "Press a key (1 to 9)"
30 a$=INKEY$:IF a$="" THEN 30
40 n=VAL(a$):if n<1 or n>9 then 30
50 FOR x=1 to 12
60 PRINT n;"X";x;"=";n*x
70 NEXT:GOTO 20
run
</pre>
==== <code><big>VPOS (#<stream expression>)</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current vertical POSition of the text cursor relative to the top of the text window. The <stream expression> MUST be specified, and does NOT default to #0.

: '''Associated keywords''': POS, WINDOW

: '''Example''':
<pre>
10 MODE 1:BORDER 0:LOCATE 8,2
20 PRINT "use cursor up/down keys"
30 WINDOW 39,39,1,25:CURSOR 1,1
40 LOCATE 1,3
50 IF INKEY(0)<>-1 THEN PRINT CHR$(11);
60 IF INKEY(2)<>-1 THEN PRINT CHR$(10);
70 LOCATE #1,3,24
80 PRINT #1,"text cursor ";
90 PRINT #1,"vertical position =";
100 PRINT #1,VPOS(#0):GOTO 50
run
</pre>
==== <code><big>XPOS</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current horizontal (X)POSition of the graphics cursor.

: '''Associated keywords''': MOVE, MOVER, ORIGIN, YPOS

: '''Example''':
<pre>
10 MODE 1:DRAW 320,200
20 PRINT "graphics cursor X position = ";
30 PRINT XPOS
</pre>
==== <code><big>YPOS</big></code> ====
: ''BASIC 1.0 & 1.1''
: '''FUNCTION''': Reports the current vertical (Y)POSition of the graphic cursor.

: '''Associated keywords''': MOVE, MOVER, ORIGIN, XPOS

: '''Example''':
<pre>
10 MODE 1:DRAW 320,200
20 PRINT "graphics cursor Y position = ";
30 PRINT YPOS
</pre>

== Other Basic Dialects available for the CPC ==

*[[BBC Basic]]
*[[C BASIC Compiler|CBASIC]]
*[[BASIC-E]]

== Technical Information ==

* [[Technical_information_about_Locomotive_BASIC]]

== Web links ==

* [http://www.sean.co.uk/books/amstrad/bforbasic.shtm Locomotive Basic Tutorial by Sean McManus]
* [http://rosettacode.org/wiki/Category:Locomotive_Basic Code examples at Rosetta Code]

* [http://cpctech.cpc-live.com/docs/basic.asm Disassembly of Locomotive BASIC v1.1]

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Technical information about Locomotive BASIC

2025-08-24T10:24:34Z

Arnoldemu: /* Sign */

[[Category:Cpctech.org]]

'''''This article originally came from Kevin Thackers' archive at [http://www.cpctech.org.uk http://www.cpctech.org.uk].'''''

= Technical information about Locomotive BASIC =

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== BASIC v1.0 only ==

There is a region of memory between AC00-AC1B which is filled with RET instructions. The BASIC ROM calls the following locations:
AC01,AC04,AC07,AC0A,AC0D,AC10,AC13,AC16,AC19

It almost looks like these were used for debugging the ROM but were left in.

They can be used to implement new BASIC commands.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR". A binary function is accessed through BASIC using the "CALL" command.

Both RSX and CALL commands work (are!) similar from the BASIC command line and invoke machine code - the only difference is: with the help of a RSX command you don't need to know the exact access address. You can pass up to 32 parameters with a CALL or RSX command. Possible parameters could be integer, floating points and strings. Just store the parameter into a variable:
Passing for integer:
<pre>
CALL &4000,32,34,&5E,&x10101010
|RSX-command,32,34,&5E,&x10101010
</pre>
Passing for floating points
<pre>
@a!=43.375
CALL or |RSX-command,@a!
</pre>

 Passing a string parameter:
 BASIC v1.0
<pre>a$="A":|DRIVE,@a$
</pre>
BASIC v1.1:
<pre>|DRIVE,"A"
</pre>
or
<pre>
b$="test"
CALL or |RSX-command,@b$
</pre>

The parameters will be stored inside the range of Stack:
<pre>
A=n -------> MSB PARAM1
LSB PARAM1
MSB PARAM2
LSB PARAM2
...
...
...
MSB PARAMn
IX+0 ------> LSB PARAMn
</pre>
with the help of that assembly code is it possible to find the parameters:
<pre>
ROUT1: CP x ;test register A if "x" parameters were given, e.g. x = 2
RET NZ ; if not exactly x parameters then do not execute RSX.
LD L,(IX+0)
LD H,(IX+1) ; HL = value of last parameter
LD E,(IX+2)
LD D,(IX+3) ; DE = value of next to last parameter
...
</pre>
A register holds the number of parameters. IX points to each parameter. IX+0/IX+1 is the last parameter. This happens because each parameter in order is pushed onto the stack and IX then points to the last parameter pushed. Each parameter is a 16-bit value.

If a parameter is a string, then IX holds the address of the string descriptor which point to a 3 byte block. The first byte of the string descriptor is the length. The next 2 bytes are an address that point to the string in memory.

With the help of the variable container "@" it is also possible to get a result from an invoked mc-code back to basic.
In this case the parameter contains the address of the integer, floating point or string. You can modify these to give the result.
BASIC allocates the strings, so when you modify a string, do not write more characters than the original string.

Hint: the first two bytes at the end of stack shows the internal return address from BASIC interpreter where it was executed.

== Additional keywords and variables in BASIC v1.1 ==

#BASIC v1.1 has the following additional keywords:
#*COPYCHR$
#*CURSOR
#*DEC$
#*FILL
#*FRAME
#*GRAPHICS
#*MASK
#BASIC v1.1 has the following additional predefined variables:
#*DERR

 

== BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

There are some rules for assigning names for variables:
: - it is not allowed to define a variable starting with a figure (the system expect then programming mode and interpret it as a program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - different sign e.g.: a slash (doesn't depend which direction), a 'minus' sign, a 'and' sign can't be used in a variable names
: - after a dollar sign (for defining string variables) it is not allowed to use further signs
: - different defining functions together are not allowed (e.g. use '%' together with '$')

: - you can use 40 characters for a variable name
: - use ! for defining a REAL value variable (like the function DEFREAL but only for the assigned variable) > It's also possible to omit the exlamation mark because it's the default system declaration after powering on then CPC.
: - use % for defining a INTEGER value variable (like the function DEFINT but only for the assigned variable)
: - use $ for defining a STRING variable (like the function DEFSTR but only for the assigned variable)
: - Minimum line number is 1. Maximum line number is 65535.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

 

== Speeding up BASIC programs ==

To speed up BASIC programs following rules could help:
: - Avoid loops or a branching program structure if possible. Internally the operating system searches for the right line number always from the beginning of the program 'listing'. Often recurring subroutines (if necessary) should be at the beginning of RAM to speed up things.
: - Avoid the index variable after the <code>NEXT</code> command/statement (although it isn't a good program style)
: - Avoid spaces inside program code or remarks
: - Put lots of statements as possible in ONE line
: - Use variables instead of constants. A constant has always to be converted in a binary/digital format. A variable is already converted.
: - Dimensioning at the beginning of the program
: - Dimensioning your variables & pre-calculate
: - Avoid AND/OR/XOR in IF-THEN statements. It's faster to write IF ... THEN (statement 1).. IF ... THEN (statement 2).
: - Minimise string/char manipulation as this often requires memory allocations. (e.g. joining strings with +, use of MID$, LEFT$, RIGHT$, SPACE$)

== Minimizing memory usage ==

To minimize memory usage in BASIC here are some things to consider.

The size of the tokenized program:
: - Difficult to measure without looking at the data in memory.
: - Use short variable names. The names are stored in the tokenized BASIC program as-is.
: - Minimize the number of variables. The names are stored in the tokenized BASIC program everywhere they are used.
: - Use as few lines as possible. It's a small saving of about 5 bytes per line.
: - Consider using numbers vs strings and potentially 8-bit or 16-bit values.

Minimising memory usage when the program is running:
: - Minimize string operations. (e.g. A$=SPACE$(30)+CHR$(28) in memory this first allocates a string of length 30 containing spaces, then it allocates a new string of length 31 with spaces and char 28 at the end and assigns it to A$. In this line at least 30 bytes have been wasted. So consider if you need strings or perhaps if possible pre-define them).

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences. Each line of the BASIC program has the form:

 

{| border="1"
|-
! Offset
! Size
! Description
|-
| 0
| 2
| Length of line data in bytes (note 1)
|-
| 2
| 2
| 16-bit decimal integer line number (note 2)
|-
| 4
| n
| BASIC line encoded into tokens (note 3)
|-
| n+1
| 1
| "0" the end of line marker (note 4)
|}

 Notes:

#This 16-bit value has two functions: if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data, otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
#This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
#This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
#This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| end of tokenised line marker
|-
| &01
| ":" statement seperator
|-
| &02
| integer variable definition (defined with "%" suffix)
|-
| &03
| string variable definition (defined with "$" suffix)
|-
| &04
| floating point variable definition (defined with "!" suffix)
|-
| &05
| var?
|-
| &06
| var?
|-
| &07
| var?
|-
| &08
| var?
|-
| &09
| var?
|-
| &0a
| var?
|-
| &0b
| variable definition (no suffix)
|-
| &0c
| variable definition (no suffix)
|-
| &0d
| variable definition (no suffix)
|-
| &0e
| number constant "0"
|-
| &0f
| number constant "1"
|-
| &10
| number constant "2"
|-
| &11
| number constant "3"
|-
| &12
| number constant "4"
|-
| &13
| number constant "5"
|-
| &14
| number constant "6"
|-
| &15
| number constant "7"
|-
| &16
| number constant "8"
|-
| &17
| number constant "9"
|-
| &18
| number constant "10"
|-
| &19
| 8-bit integer decimal value
|-
| &1a
| 16-bit integer decimal value
|-
| &1b
| 16-bit integer binary value (with "&X" prefix)
|-
| &1c
| 16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
| &1d
| 16-bit BASIC program line memory address pointer (see notes)
|-
| &1e
| 16-bit integer BASIC line number
|-
| &1f
| floating point value
|-
| &20
| " " (space) symbol
|-
| &21
| ASCII "!" symbol
|-
| &22
| quoted string value
|-
| &23-7b
| ASCII printable symbols
|-
| &7c
| "|" symbol; prefix for RSX commands
|-
| &80
| AFTER
|-
| &81
| AUTO
|-
| &82
| BORDER
|-
| &83
| CALL
|-
| &84
| CAT
|-
| &85
| CHAIN
|-
| &86
| CLEAR
|-
| &87
| CLG
|-
| &88
| CLOSEIN
|-
| &89
| CLOSEOUT
|-
| &8a
| CLS
|-
| &8b
| CONT
|-
| &8c
| DATA
|-
| &8d
| DEF
|-
| &8e
| DEFINT
|-
| &8f
| DEFREAL
|-
| &90
| DEFSTR
|-
| &91
| DEG
|-
| &92
| DELETE
|-
| &93
| DIM
|-
| &94
| DRAW
|-
| &95
| DRAWR
|-
| &96
| EDIT
|-
| &97
| ELSE
|-
| &98
| END
|-
| &99
| ENT
|-
| &9a
| ENV
|-
| &9b
| ERASE
|-
| &9c
| ERROR
|-
| &9d
| EVERY
|-
| &9e
| FOR
|-
| &9f
| GOSUB, GO SUB
|-
| &a0
| GOTO, GO TO
|-
| &a1
| IF
|-
| &a2
| INK
|-
| &a3
| INPUT
|-
| &a4
| KEY
|-
| &a5
| LET
|-
| &a6
| LINE
|-
| &a7
| LIST
|-
| &a8
| LOAD
|-
| &a9
| LOCATE
|-
| &aa
| MEMORY
|-
| &ab
| MERGE
|-
| &ac
| MID$
|-
| &ad
| MODE
|-
| &ae
| MOVE
|-
| &af
| MOVER
|-
| &b0
| NEXT
|-
| &b1
| NEW
|-
| &b2
| ON
|-
| &b3
| ON BREAK
|-
| &b4
| ON ERROR GOTO, ON ERROR GO TO
|-
| &b5
| ON SQ
|-
| &b6
| OPENIN
|-
| &b7
| OPENOUT
|-
| &b8
| ORIGIN
|-
| &b9
| OUT
|-
| &ba
| PAPER
|-
| &bb
| PEN
|-
| &bc
| PLOT
|-
| &bd
| PLOTR
|-
| &be
| POKE
|-
| &bf
| PRINT
|-
| &c0
| "'" symbol (same function as REM keyword)
|-
| &c1
| RAD
|-
| &c2
| RANDOMIZE
|-
| &c3
| READ
|-
| &c4
| RELEASE
|-
| &c5
| REM
|-
| &c6
| RENUM
|-
| &c7
| RESTORE
|-
| &c8
| RESUME
|-
| &c9
| RETURN
|-
| &ca
| RUN
|-
| &cb
| SAVE
|-
| &cc
| SOUND
|-
| &cd
| SPEED
|-
| &ce
| STOP
|-
| &cf
| SYMBOL
|-
| &d0
| TAG
|-
| &d1
| TAGOFF
|-
| &d2
| TROFF
|-
| &d3
| TRON
|-
| &d4
| WAIT
|-
| &d5
| WEND
|-
| &d6
| WHILE
|-
| &d7
| WIDTH
|-
| &d8
| WINDOW
|-
| &d9
| WRITE
|-
| &da
| ZONE
|-
| &db
| DI
|-
| &dc
| EI
|-
| &dd
| FILL (v1.1)
|-
| &de
| GRAPHICS (v1.1)
|-
| &df
| MASK (v1.1)
|-
| &e0
| FRAME (v1.1)
|-
| &e1
| CURSOR (v1.1)
|-
| &e2
| (note 2)
|-
| &e3
| ERL
|-
| &e4
| FN
|-
| &e5
| SPC
|-
| &e6
| STEP
|-
| &e7
| SWAP
|-
| &e8
| (note 2)
|-
| &e9
| (note 2)
|-
| &ea
| TAB
|-
| &eb
| THEN
|-
| &ec
| TO
|-
| &ed
| USING
|-
| &ee
| > (greater than)
|-
| &ef
| = (equal)
|-
| &f0
| &gt=, > =, => (greater or equal)
|-
| &f1
| < (less than)
|-
| &f2
| <&gt, < > (not equal)
|-
| &f3
| =<, <=, < = (less than or equal)
|-
| &f4
| + (addition)
|-
| &f5
| - (subtraction or unary minus)
|-
| &f6
| * (multiplication)
|-
| &f7
| / (division)
|-
| &f8
| ^ (x to the power of y)
|-
| &f9
| \ (integer division)
|-
| &fa
| AND
|-
| &fb
| MOD
|-
| &fc
| OR
|-
| &fd
| XOR
|-
| &fe
| NOT
|-
| &ff
| (prefix for additional keywords)
|}

 Notes:

*The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
*&e2,&e8 and &e9 are not used
*&7c ("|") is a character prefix used to identify an RSX command. e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| "|" character prefix
|-
| 1
| 1
| 8-bit byte offset to tokens following RSX name.
|-
| 2
| x
| RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
|}

*This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &1a,&2d,&00 represents the integer number "&002d"="45".
*This token (&0B) is changed at run-time to &0D
*This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
*This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
*This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| &1f (note 1)
|-
| 1
| 5
| Floating point number (note 2)
|}

*#This byte is the BASIC token identifying a floating point number
*#These 5 bytes define the floating point number.
*The space symbol is used as a command seperator
*Variable definitions:
**The variable definition has the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| Token defining variable type
|-
| 2
| 2
| 16-bit Byte offset to variable value within tokenised BASIC program.
|-
| 4
| x
| Variable name
|}

 The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.

**The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
**The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
*String values:
**Each string value is prefixed with &22 token.
**All strings must be enclosed by double quote symbols (&quot). This symbols define the start and end of the string value.
**The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.

*After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

 This table list the BASIC tokens with a &ff prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| ABS
|-
| &01
| ASC
|-
| &02
| ATN
|-
| &03
| CHR$
|-
| &04
| CINT
|-
| &05
| COS
|-
| &06
| CREAL
|-
| &07
| EXP
|-
| &08
| FIX
|-
| &09
| FRE
|-
| &0a
| INKEY
|-
| &0b
| INP
|-
| &0c
| INT
|-
| &0d
| JOY
|-
| &0e
| LEN
|-
| &0f
| LOG
|-
| &10
| LOG10
|-
| &11
| LOWER$
|-
| &12
| PEEK
|-
| &13
| REMAIN
|-
| &14
| SGN
|-
| &15
| SIN
|-
| &16
| SPACE$
|-
| &17
| SQ
|-
| &18
| SQR
|-
| &19
| STR$
|-
| &1a
| TAN
|-
| &1b
| UNT
|-
| &1c
| UPPER$
|-
| &1d
| VAL
|-
|  
| (note 2)
|-
| &40
| EOF
|-
| &41
| ERR
|-
| &42
| HIMEM
|-
| &43
| INKEY$
|-
| &44
| PI
|-
| &45
| RND
|-
| &46
| TIME
|-
| &47
| XPOS
|-
| &48
| YPOS
|-
| &49
| DERR (v1.1)
|-
|  
| (note 3)
|-
| &71
| BIN$
|-
| &72
| DEC$ (v1.1)
|-
| &73
| HEX$
|-
| &74
| INSTR
|-
| &75
| LEFT$
|-
| &76
| MAX
|-
| &77
| MIN
|-
| &78
| POS
|-
| &79
| RIGHT$
|-
| &7a
| ROUND
|-
| &7b
| STRING$
|-
| &7c
| TEST
|-
| &7d
| TESTR
|-
| &7e
| COPYCHR$ (v1.1)
|-
| &7f
| VPOS
|-
|  
| (note 4)
|}

 NOTES:

*These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence: <pre>&FF,&00</pre>
*Codes &1e...&3f inclusive are not used
*Codes &4a...&6f inclusive are not used
*Codes &80...&ff inclusive are not used

*When a BASIC program is in memory, the BASIC ROM can replace "16-bit BASIC program line number" tokens with "16-bit BASIC program line memory address pointer".

When a program is loaded or saved, there will only be "16-bit BASIC program line number" tokens followed by a 16-bit number of the line.

When a program is running, BASIC will replace the "16-bit BASIC program line number" with the "16-bit BASIC program line memory address pointer" token, and replace the 16-bit line number with the memory address of the start of that line.

It does this to avoid having to lookup the address of the line each time.

* When a REM or ' is seen, the characters following it are output directly (i.e. the bytes are not tokenized) until the end of line or a ':' is seen.

* When a BASIC program is listed each line is converted to a string (this includes the line number and the tokens converted to their strings). There is a maximum length for this string of 256 characters. This means that if the BASIC line is LISTed or EDITed, then the line will be displayed incorrectly with missing characters on the end. This is also noticed if you have a "10-liner" program that packs as much BASIC as possible into each line and renumber it so the line number has more digits.

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

 In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form: 1 x 2<exponent> The representation uses 5 bytes and is stored using the following structure:

 

{| border="1"
|-
! Byte
! colspan="8" | 0
! colspan="8" | 1
! colspan="8" | 2
! colspan="8" | 3
! colspan="8" | 4
|-
! Bit
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
|-
| Function
| colspan="8" | (LSB) mantissa (bits 31-24)
| colspan="8" | mantissa (bits 23-16)
| colspan="8" | mantissa (bits 15-8)
| colspan="1" | sign
| colspan="7" | (MSB) mantissa (bits 7-0)
| colspan="8" | exponent
|}

=== Sign ===

The sign is represented by bit 7 of byte 3. The value of the sign bit indicates the sign of the floating point number.

*If the sign bit is "1", then the number is negative.
*If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4. It is stored with a bias of 128.

*128-255 are positive exponents,
*1-127 are negative exponents.
*0 means, the number is zero

To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 1 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^127.
A value of 0 just means, that the number is zero (0).

=== BASIC Display of Floating point numbers ===

* Numbers are displayed to 9 decimal places.
* If the number doesn't have a fractional part (e.g. .0) then the fractional part is not displayed.
* Trailing zeros (zero digits after the last digit in the fraction) are not displayed
* The value is rounded in the following way for display:

If the 10th fractional digit is 5 or above, then the number is rounded up.
If the 10th fractional digit is 4 or below, then the number is rounded down.
e.g.
0.1234567891 is displayed as 0.123456789
0.1234567895 is displayed as 0.12345679

=== floating point example in RAM by MaV ===

The initial figure = 43.375.
An example in BASIC:
<pre>
a!=43.375
READY
PRINT a!
43.375
PRINT @a!
374
FOR I=0 TO 4:PRINT HEX$(PEEK(374+I),2);:NEXT I
0000802D86
</pre>
the result for better readability: 
'''00 00 80 2D 86''' 
The first byte contains the least significant bits of the mantissa, and every following byte up to the fourth byte contain the bits following the first in significance and in exactly that order!

That means that you have to turn around the first four bytes if you want to read the mantissa correctly:
2D800000
or
0010.1101.1000.0000.0000.0000.0000.0000
in binary (the stops are inserted for better readability).

Now the highest significant bit here is 0, so the number is positive.
What's more, you need to clear that bit and substitute the implied highest bit (see description in the link), which is always 1 (regardless of the deleted sign bit!!!).
Thus you get:
AD800000
or
1010.1101.1000.0000.0000.0000.0000.0000
in binary.

The mantissa has an implied decimal point before the number. Since the number is 2^32 bits (i.e. 4 bytes) long you have to divide by 2^32 to get the proper decimal representation.

AD800000 (hex) = 2910846976 (dec)

2910846976 / 2^32 = 0.677734375

The mantissa in a decimal representation is: 0.677734375

Now, the last byte contains the exponent: 86 (hex) or 134 (dec). You need to subtract 128 to get the real exponent, the highest bit tells you that the exponent is positive (1) or negative (0). Your exponent is 6.

0.677734375 * 2^6 = 43.375

'''Another example:''' 
PI is represented in memory as: 
'''A2 DA 0F 49 82''' 
The mantissa is 
490FDAA2 (highest significant bit is zero => number is positive)
The exponent is 
82 (=positive mantissa, value=2 thus multiply mantissa with 2^2) 

Delete the sign bit (which is 0 anyway), and then add the implied 1 bit: 
C90FDAA2 (hex) = 3373259426 (dec) = 1100.1001.0000.1111.1101.1010.1010.0010 (bin) 

Calculate the decimal representation of the mantissa: 
3373259426 / 2^32 = 0,7853981633670628070831298828125 

Then add the exponent (82h - 80h = 2 thus 2^2) 
0,7853981633670628070831298828125 * 2^2 = 3,14159265346825122833251953125 

Voilà! The internal representation of the number PI on the CPC is: 3,14159265346825122833251953125 

If you compare to a (more) correct representation of PI, you'll see that the CPC is correct up to the 9th decimal place: 

CPC: 
3.14159265346825122833251953125 
more correctly: 
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986...

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts. The biggest figure which can be stored correctly in RAM by a variable is 2^32-1 = 4294967295.

*A real variable is defined with a "!" character postfix.

e.g.
<pre>a! = 3.141592654
</pre>
*A real number uses 5 bytes of memory as storage. The format is described above.
*The address of a real variable can be found in BASIC by:
<pre>PRINT @a!
</pre>

Where "a" should be replaced with the name of the variable.

 

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

 NOTES:

*A integer variable is defined with a "%" character postfix.

e.g.
<pre>a% = 3
</pre>
*A integer variable has a range of -32768 to 32767
*A integer variable always uses two bytes of memory as storage with the following format:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 2
| Integer number
|}

*The address of the integer variable can be found in BASIC by:
<pre>PRINT @a%
</pre>

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

 NOTES:

*A string variable is defined in BASIC with a "$" character postfix.

e.g.
<pre>a$ = "hello"
</pre>
*A string variable is described internally by a "string descriptor block" which has the following structure:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 1
| Length of string in bytes/characters
|-
| 1
| 2
| Location of start of string
|}

*The address of the "string descriptor block" for the string variable can be found in BASIC by typing:
<pre>PRINT @a$
</pre>

replacing "a$" with the name of the string variable.

*A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
*A string variable can contain any ASCII character code in the range 0-255.
*A string variable can store a minimum of 0 characters and a maximum of 255 characters.
*The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Technical information about Locomotive BASIC

2025-08-24T10:24:22Z

Arnoldemu: /* Exponent */

[[Category:Cpctech.org]]

'''''This article originally came from Kevin Thackers' archive at [http://www.cpctech.org.uk http://www.cpctech.org.uk].'''''

= Technical information about Locomotive BASIC =

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== BASIC v1.0 only ==

There is a region of memory between AC00-AC1B which is filled with RET instructions. The BASIC ROM calls the following locations:
AC01,AC04,AC07,AC0A,AC0D,AC10,AC13,AC16,AC19

It almost looks like these were used for debugging the ROM but were left in.

They can be used to implement new BASIC commands.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR". A binary function is accessed through BASIC using the "CALL" command.

Both RSX and CALL commands work (are!) similar from the BASIC command line and invoke machine code - the only difference is: with the help of a RSX command you don't need to know the exact access address. You can pass up to 32 parameters with a CALL or RSX command. Possible parameters could be integer, floating points and strings. Just store the parameter into a variable:
Passing for integer:
<pre>
CALL &4000,32,34,&5E,&x10101010
|RSX-command,32,34,&5E,&x10101010
</pre>
Passing for floating points
<pre>
@a!=43.375
CALL or |RSX-command,@a!
</pre>

 Passing a string parameter:
 BASIC v1.0
<pre>a$="A":|DRIVE,@a$
</pre>
BASIC v1.1:
<pre>|DRIVE,"A"
</pre>
or
<pre>
b$="test"
CALL or |RSX-command,@b$
</pre>

The parameters will be stored inside the range of Stack:
<pre>
A=n -------> MSB PARAM1
LSB PARAM1
MSB PARAM2
LSB PARAM2
...
...
...
MSB PARAMn
IX+0 ------> LSB PARAMn
</pre>
with the help of that assembly code is it possible to find the parameters:
<pre>
ROUT1: CP x ;test register A if "x" parameters were given, e.g. x = 2
RET NZ ; if not exactly x parameters then do not execute RSX.
LD L,(IX+0)
LD H,(IX+1) ; HL = value of last parameter
LD E,(IX+2)
LD D,(IX+3) ; DE = value of next to last parameter
...
</pre>
A register holds the number of parameters. IX points to each parameter. IX+0/IX+1 is the last parameter. This happens because each parameter in order is pushed onto the stack and IX then points to the last parameter pushed. Each parameter is a 16-bit value.

If a parameter is a string, then IX holds the address of the string descriptor which point to a 3 byte block. The first byte of the string descriptor is the length. The next 2 bytes are an address that point to the string in memory.

With the help of the variable container "@" it is also possible to get a result from an invoked mc-code back to basic.
In this case the parameter contains the address of the integer, floating point or string. You can modify these to give the result.
BASIC allocates the strings, so when you modify a string, do not write more characters than the original string.

Hint: the first two bytes at the end of stack shows the internal return address from BASIC interpreter where it was executed.

== Additional keywords and variables in BASIC v1.1 ==

#BASIC v1.1 has the following additional keywords:
#*COPYCHR$
#*CURSOR
#*DEC$
#*FILL
#*FRAME
#*GRAPHICS
#*MASK
#BASIC v1.1 has the following additional predefined variables:
#*DERR

 

== BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

There are some rules for assigning names for variables:
: - it is not allowed to define a variable starting with a figure (the system expect then programming mode and interpret it as a program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - different sign e.g.: a slash (doesn't depend which direction), a 'minus' sign, a 'and' sign can't be used in a variable names
: - after a dollar sign (for defining string variables) it is not allowed to use further signs
: - different defining functions together are not allowed (e.g. use '%' together with '$')

: - you can use 40 characters for a variable name
: - use ! for defining a REAL value variable (like the function DEFREAL but only for the assigned variable) > It's also possible to omit the exlamation mark because it's the default system declaration after powering on then CPC.
: - use % for defining a INTEGER value variable (like the function DEFINT but only for the assigned variable)
: - use $ for defining a STRING variable (like the function DEFSTR but only for the assigned variable)
: - Minimum line number is 1. Maximum line number is 65535.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

 

== Speeding up BASIC programs ==

To speed up BASIC programs following rules could help:
: - Avoid loops or a branching program structure if possible. Internally the operating system searches for the right line number always from the beginning of the program 'listing'. Often recurring subroutines (if necessary) should be at the beginning of RAM to speed up things.
: - Avoid the index variable after the <code>NEXT</code> command/statement (although it isn't a good program style)
: - Avoid spaces inside program code or remarks
: - Put lots of statements as possible in ONE line
: - Use variables instead of constants. A constant has always to be converted in a binary/digital format. A variable is already converted.
: - Dimensioning at the beginning of the program
: - Dimensioning your variables & pre-calculate
: - Avoid AND/OR/XOR in IF-THEN statements. It's faster to write IF ... THEN (statement 1).. IF ... THEN (statement 2).
: - Minimise string/char manipulation as this often requires memory allocations. (e.g. joining strings with +, use of MID$, LEFT$, RIGHT$, SPACE$)

== Minimizing memory usage ==

To minimize memory usage in BASIC here are some things to consider.

The size of the tokenized program:
: - Difficult to measure without looking at the data in memory.
: - Use short variable names. The names are stored in the tokenized BASIC program as-is.
: - Minimize the number of variables. The names are stored in the tokenized BASIC program everywhere they are used.
: - Use as few lines as possible. It's a small saving of about 5 bytes per line.
: - Consider using numbers vs strings and potentially 8-bit or 16-bit values.

Minimising memory usage when the program is running:
: - Minimize string operations. (e.g. A$=SPACE$(30)+CHR$(28) in memory this first allocates a string of length 30 containing spaces, then it allocates a new string of length 31 with spaces and char 28 at the end and assigns it to A$. In this line at least 30 bytes have been wasted. So consider if you need strings or perhaps if possible pre-define them).

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences. Each line of the BASIC program has the form:

 

{| border="1"
|-
! Offset
! Size
! Description
|-
| 0
| 2
| Length of line data in bytes (note 1)
|-
| 2
| 2
| 16-bit decimal integer line number (note 2)
|-
| 4
| n
| BASIC line encoded into tokens (note 3)
|-
| n+1
| 1
| "0" the end of line marker (note 4)
|}

 Notes:

#This 16-bit value has two functions: if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data, otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
#This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
#This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
#This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| end of tokenised line marker
|-
| &01
| ":" statement seperator
|-
| &02
| integer variable definition (defined with "%" suffix)
|-
| &03
| string variable definition (defined with "$" suffix)
|-
| &04
| floating point variable definition (defined with "!" suffix)
|-
| &05
| var?
|-
| &06
| var?
|-
| &07
| var?
|-
| &08
| var?
|-
| &09
| var?
|-
| &0a
| var?
|-
| &0b
| variable definition (no suffix)
|-
| &0c
| variable definition (no suffix)
|-
| &0d
| variable definition (no suffix)
|-
| &0e
| number constant "0"
|-
| &0f
| number constant "1"
|-
| &10
| number constant "2"
|-
| &11
| number constant "3"
|-
| &12
| number constant "4"
|-
| &13
| number constant "5"
|-
| &14
| number constant "6"
|-
| &15
| number constant "7"
|-
| &16
| number constant "8"
|-
| &17
| number constant "9"
|-
| &18
| number constant "10"
|-
| &19
| 8-bit integer decimal value
|-
| &1a
| 16-bit integer decimal value
|-
| &1b
| 16-bit integer binary value (with "&X" prefix)
|-
| &1c
| 16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
| &1d
| 16-bit BASIC program line memory address pointer (see notes)
|-
| &1e
| 16-bit integer BASIC line number
|-
| &1f
| floating point value
|-
| &20
| " " (space) symbol
|-
| &21
| ASCII "!" symbol
|-
| &22
| quoted string value
|-
| &23-7b
| ASCII printable symbols
|-
| &7c
| "|" symbol; prefix for RSX commands
|-
| &80
| AFTER
|-
| &81
| AUTO
|-
| &82
| BORDER
|-
| &83
| CALL
|-
| &84
| CAT
|-
| &85
| CHAIN
|-
| &86
| CLEAR
|-
| &87
| CLG
|-
| &88
| CLOSEIN
|-
| &89
| CLOSEOUT
|-
| &8a
| CLS
|-
| &8b
| CONT
|-
| &8c
| DATA
|-
| &8d
| DEF
|-
| &8e
| DEFINT
|-
| &8f
| DEFREAL
|-
| &90
| DEFSTR
|-
| &91
| DEG
|-
| &92
| DELETE
|-
| &93
| DIM
|-
| &94
| DRAW
|-
| &95
| DRAWR
|-
| &96
| EDIT
|-
| &97
| ELSE
|-
| &98
| END
|-
| &99
| ENT
|-
| &9a
| ENV
|-
| &9b
| ERASE
|-
| &9c
| ERROR
|-
| &9d
| EVERY
|-
| &9e
| FOR
|-
| &9f
| GOSUB, GO SUB
|-
| &a0
| GOTO, GO TO
|-
| &a1
| IF
|-
| &a2
| INK
|-
| &a3
| INPUT
|-
| &a4
| KEY
|-
| &a5
| LET
|-
| &a6
| LINE
|-
| &a7
| LIST
|-
| &a8
| LOAD
|-
| &a9
| LOCATE
|-
| &aa
| MEMORY
|-
| &ab
| MERGE
|-
| &ac
| MID$
|-
| &ad
| MODE
|-
| &ae
| MOVE
|-
| &af
| MOVER
|-
| &b0
| NEXT
|-
| &b1
| NEW
|-
| &b2
| ON
|-
| &b3
| ON BREAK
|-
| &b4
| ON ERROR GOTO, ON ERROR GO TO
|-
| &b5
| ON SQ
|-
| &b6
| OPENIN
|-
| &b7
| OPENOUT
|-
| &b8
| ORIGIN
|-
| &b9
| OUT
|-
| &ba
| PAPER
|-
| &bb
| PEN
|-
| &bc
| PLOT
|-
| &bd
| PLOTR
|-
| &be
| POKE
|-
| &bf
| PRINT
|-
| &c0
| "'" symbol (same function as REM keyword)
|-
| &c1
| RAD
|-
| &c2
| RANDOMIZE
|-
| &c3
| READ
|-
| &c4
| RELEASE
|-
| &c5
| REM
|-
| &c6
| RENUM
|-
| &c7
| RESTORE
|-
| &c8
| RESUME
|-
| &c9
| RETURN
|-
| &ca
| RUN
|-
| &cb
| SAVE
|-
| &cc
| SOUND
|-
| &cd
| SPEED
|-
| &ce
| STOP
|-
| &cf
| SYMBOL
|-
| &d0
| TAG
|-
| &d1
| TAGOFF
|-
| &d2
| TROFF
|-
| &d3
| TRON
|-
| &d4
| WAIT
|-
| &d5
| WEND
|-
| &d6
| WHILE
|-
| &d7
| WIDTH
|-
| &d8
| WINDOW
|-
| &d9
| WRITE
|-
| &da
| ZONE
|-
| &db
| DI
|-
| &dc
| EI
|-
| &dd
| FILL (v1.1)
|-
| &de
| GRAPHICS (v1.1)
|-
| &df
| MASK (v1.1)
|-
| &e0
| FRAME (v1.1)
|-
| &e1
| CURSOR (v1.1)
|-
| &e2
| (note 2)
|-
| &e3
| ERL
|-
| &e4
| FN
|-
| &e5
| SPC
|-
| &e6
| STEP
|-
| &e7
| SWAP
|-
| &e8
| (note 2)
|-
| &e9
| (note 2)
|-
| &ea
| TAB
|-
| &eb
| THEN
|-
| &ec
| TO
|-
| &ed
| USING
|-
| &ee
| > (greater than)
|-
| &ef
| = (equal)
|-
| &f0
| &gt=, > =, => (greater or equal)
|-
| &f1
| < (less than)
|-
| &f2
| <&gt, < > (not equal)
|-
| &f3
| =<, <=, < = (less than or equal)
|-
| &f4
| + (addition)
|-
| &f5
| - (subtraction or unary minus)
|-
| &f6
| * (multiplication)
|-
| &f7
| / (division)
|-
| &f8
| ^ (x to the power of y)
|-
| &f9
| \ (integer division)
|-
| &fa
| AND
|-
| &fb
| MOD
|-
| &fc
| OR
|-
| &fd
| XOR
|-
| &fe
| NOT
|-
| &ff
| (prefix for additional keywords)
|}

 Notes:

*The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
*&e2,&e8 and &e9 are not used
*&7c ("|") is a character prefix used to identify an RSX command. e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| "|" character prefix
|-
| 1
| 1
| 8-bit byte offset to tokens following RSX name.
|-
| 2
| x
| RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
|}

*This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &1a,&2d,&00 represents the integer number "&002d"="45".
*This token (&0B) is changed at run-time to &0D
*This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
*This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
*This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| &1f (note 1)
|-
| 1
| 5
| Floating point number (note 2)
|}

*#This byte is the BASIC token identifying a floating point number
*#These 5 bytes define the floating point number.
*The space symbol is used as a command seperator
*Variable definitions:
**The variable definition has the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| Token defining variable type
|-
| 2
| 2
| 16-bit Byte offset to variable value within tokenised BASIC program.
|-
| 4
| x
| Variable name
|}

 The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.

**The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
**The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
*String values:
**Each string value is prefixed with &22 token.
**All strings must be enclosed by double quote symbols (&quot). This symbols define the start and end of the string value.
**The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.

*After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

 This table list the BASIC tokens with a &ff prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| ABS
|-
| &01
| ASC
|-
| &02
| ATN
|-
| &03
| CHR$
|-
| &04
| CINT
|-
| &05
| COS
|-
| &06
| CREAL
|-
| &07
| EXP
|-
| &08
| FIX
|-
| &09
| FRE
|-
| &0a
| INKEY
|-
| &0b
| INP
|-
| &0c
| INT
|-
| &0d
| JOY
|-
| &0e
| LEN
|-
| &0f
| LOG
|-
| &10
| LOG10
|-
| &11
| LOWER$
|-
| &12
| PEEK
|-
| &13
| REMAIN
|-
| &14
| SGN
|-
| &15
| SIN
|-
| &16
| SPACE$
|-
| &17
| SQ
|-
| &18
| SQR
|-
| &19
| STR$
|-
| &1a
| TAN
|-
| &1b
| UNT
|-
| &1c
| UPPER$
|-
| &1d
| VAL
|-
|  
| (note 2)
|-
| &40
| EOF
|-
| &41
| ERR
|-
| &42
| HIMEM
|-
| &43
| INKEY$
|-
| &44
| PI
|-
| &45
| RND
|-
| &46
| TIME
|-
| &47
| XPOS
|-
| &48
| YPOS
|-
| &49
| DERR (v1.1)
|-
|  
| (note 3)
|-
| &71
| BIN$
|-
| &72
| DEC$ (v1.1)
|-
| &73
| HEX$
|-
| &74
| INSTR
|-
| &75
| LEFT$
|-
| &76
| MAX
|-
| &77
| MIN
|-
| &78
| POS
|-
| &79
| RIGHT$
|-
| &7a
| ROUND
|-
| &7b
| STRING$
|-
| &7c
| TEST
|-
| &7d
| TESTR
|-
| &7e
| COPYCHR$ (v1.1)
|-
| &7f
| VPOS
|-
|  
| (note 4)
|}

 NOTES:

*These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence: <pre>&FF,&00</pre>
*Codes &1e...&3f inclusive are not used
*Codes &4a...&6f inclusive are not used
*Codes &80...&ff inclusive are not used

*When a BASIC program is in memory, the BASIC ROM can replace "16-bit BASIC program line number" tokens with "16-bit BASIC program line memory address pointer".

When a program is loaded or saved, there will only be "16-bit BASIC program line number" tokens followed by a 16-bit number of the line.

When a program is running, BASIC will replace the "16-bit BASIC program line number" with the "16-bit BASIC program line memory address pointer" token, and replace the 16-bit line number with the memory address of the start of that line.

It does this to avoid having to lookup the address of the line each time.

* When a REM or ' is seen, the characters following it are output directly (i.e. the bytes are not tokenized) until the end of line or a ':' is seen.

* When a BASIC program is listed each line is converted to a string (this includes the line number and the tokens converted to their strings). There is a maximum length for this string of 256 characters. This means that if the BASIC line is LISTed or EDITed, then the line will be displayed incorrectly with missing characters on the end. This is also noticed if you have a "10-liner" program that packs as much BASIC as possible into each line and renumber it so the line number has more digits.

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

 In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form: 1 x 2<exponent> The representation uses 5 bytes and is stored using the following structure:

 

{| border="1"
|-
! Byte
! colspan="8" | 0
! colspan="8" | 1
! colspan="8" | 2
! colspan="8" | 3
! colspan="8" | 4
|-
! Bit
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
|-
| Function
| colspan="8" | (LSB) mantissa (bits 31-24)
| colspan="8" | mantissa (bits 23-16)
| colspan="8" | mantissa (bits 15-8)
| colspan="1" | sign
| colspan="7" | (MSB) mantissa (bits 7-0)
| colspan="8" | exponent
|}

=== Sign ===

The sign is represented by bit 7 of byte 3. The value of the sign bit indicates the sign of the floating point number.

#*If the sign bit is "1", then the number is negative.
#*If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4. It is stored with a bias of 128.

*128-255 are positive exponents,
*1-127 are negative exponents.
*0 means, the number is zero

To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 1 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^127.
A value of 0 just means, that the number is zero (0).

=== BASIC Display of Floating point numbers ===

* Numbers are displayed to 9 decimal places.
* If the number doesn't have a fractional part (e.g. .0) then the fractional part is not displayed.
* Trailing zeros (zero digits after the last digit in the fraction) are not displayed
* The value is rounded in the following way for display:

If the 10th fractional digit is 5 or above, then the number is rounded up.
If the 10th fractional digit is 4 or below, then the number is rounded down.
e.g.
0.1234567891 is displayed as 0.123456789
0.1234567895 is displayed as 0.12345679

=== floating point example in RAM by MaV ===

The initial figure = 43.375.
An example in BASIC:
<pre>
a!=43.375
READY
PRINT a!
43.375
PRINT @a!
374
FOR I=0 TO 4:PRINT HEX$(PEEK(374+I),2);:NEXT I
0000802D86
</pre>
the result for better readability: 
'''00 00 80 2D 86''' 
The first byte contains the least significant bits of the mantissa, and every following byte up to the fourth byte contain the bits following the first in significance and in exactly that order!

That means that you have to turn around the first four bytes if you want to read the mantissa correctly:
2D800000
or
0010.1101.1000.0000.0000.0000.0000.0000
in binary (the stops are inserted for better readability).

Now the highest significant bit here is 0, so the number is positive.
What's more, you need to clear that bit and substitute the implied highest bit (see description in the link), which is always 1 (regardless of the deleted sign bit!!!).
Thus you get:
AD800000
or
1010.1101.1000.0000.0000.0000.0000.0000
in binary.

The mantissa has an implied decimal point before the number. Since the number is 2^32 bits (i.e. 4 bytes) long you have to divide by 2^32 to get the proper decimal representation.

AD800000 (hex) = 2910846976 (dec)

2910846976 / 2^32 = 0.677734375

The mantissa in a decimal representation is: 0.677734375

Now, the last byte contains the exponent: 86 (hex) or 134 (dec). You need to subtract 128 to get the real exponent, the highest bit tells you that the exponent is positive (1) or negative (0). Your exponent is 6.

0.677734375 * 2^6 = 43.375

'''Another example:''' 
PI is represented in memory as: 
'''A2 DA 0F 49 82''' 
The mantissa is 
490FDAA2 (highest significant bit is zero => number is positive)
The exponent is 
82 (=positive mantissa, value=2 thus multiply mantissa with 2^2) 

Delete the sign bit (which is 0 anyway), and then add the implied 1 bit: 
C90FDAA2 (hex) = 3373259426 (dec) = 1100.1001.0000.1111.1101.1010.1010.0010 (bin) 

Calculate the decimal representation of the mantissa: 
3373259426 / 2^32 = 0,7853981633670628070831298828125 

Then add the exponent (82h - 80h = 2 thus 2^2) 
0,7853981633670628070831298828125 * 2^2 = 3,14159265346825122833251953125 

Voilà! The internal representation of the number PI on the CPC is: 3,14159265346825122833251953125 

If you compare to a (more) correct representation of PI, you'll see that the CPC is correct up to the 9th decimal place: 

CPC: 
3.14159265346825122833251953125 
more correctly: 
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986...

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts. The biggest figure which can be stored correctly in RAM by a variable is 2^32-1 = 4294967295.

*A real variable is defined with a "!" character postfix.

e.g.
<pre>a! = 3.141592654
</pre>
*A real number uses 5 bytes of memory as storage. The format is described above.
*The address of a real variable can be found in BASIC by:
<pre>PRINT @a!
</pre>

Where "a" should be replaced with the name of the variable.

 

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

 NOTES:

*A integer variable is defined with a "%" character postfix.

e.g.
<pre>a% = 3
</pre>
*A integer variable has a range of -32768 to 32767
*A integer variable always uses two bytes of memory as storage with the following format:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 2
| Integer number
|}

*The address of the integer variable can be found in BASIC by:
<pre>PRINT @a%
</pre>

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

 NOTES:

*A string variable is defined in BASIC with a "$" character postfix.

e.g.
<pre>a$ = "hello"
</pre>
*A string variable is described internally by a "string descriptor block" which has the following structure:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 1
| Length of string in bytes/characters
|-
| 1
| 2
| Location of start of string
|}

*The address of the "string descriptor block" for the string variable can be found in BASIC by typing:
<pre>PRINT @a$
</pre>

replacing "a$" with the name of the string variable.

*A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
*A string variable can contain any ASCII character code in the range 0-255.
*A string variable can store a minimum of 0 characters and a maximum of 255 characters.
*The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Technical information about Locomotive BASIC

2025-08-24T10:24:05Z

Arnoldemu: /* BASIC floating-point/real variables */

[[Category:Cpctech.org]]

'''''This article originally came from Kevin Thackers' archive at [http://www.cpctech.org.uk http://www.cpctech.org.uk].'''''

= Technical information about Locomotive BASIC =

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== BASIC v1.0 only ==

There is a region of memory between AC00-AC1B which is filled with RET instructions. The BASIC ROM calls the following locations:
AC01,AC04,AC07,AC0A,AC0D,AC10,AC13,AC16,AC19

It almost looks like these were used for debugging the ROM but were left in.

They can be used to implement new BASIC commands.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR". A binary function is accessed through BASIC using the "CALL" command.

Both RSX and CALL commands work (are!) similar from the BASIC command line and invoke machine code - the only difference is: with the help of a RSX command you don't need to know the exact access address. You can pass up to 32 parameters with a CALL or RSX command. Possible parameters could be integer, floating points and strings. Just store the parameter into a variable:
Passing for integer:
<pre>
CALL &4000,32,34,&5E,&x10101010
|RSX-command,32,34,&5E,&x10101010
</pre>
Passing for floating points
<pre>
@a!=43.375
CALL or |RSX-command,@a!
</pre>

 Passing a string parameter:
 BASIC v1.0
<pre>a$="A":|DRIVE,@a$
</pre>
BASIC v1.1:
<pre>|DRIVE,"A"
</pre>
or
<pre>
b$="test"
CALL or |RSX-command,@b$
</pre>

The parameters will be stored inside the range of Stack:
<pre>
A=n -------> MSB PARAM1
LSB PARAM1
MSB PARAM2
LSB PARAM2
...
...
...
MSB PARAMn
IX+0 ------> LSB PARAMn
</pre>
with the help of that assembly code is it possible to find the parameters:
<pre>
ROUT1: CP x ;test register A if "x" parameters were given, e.g. x = 2
RET NZ ; if not exactly x parameters then do not execute RSX.
LD L,(IX+0)
LD H,(IX+1) ; HL = value of last parameter
LD E,(IX+2)
LD D,(IX+3) ; DE = value of next to last parameter
...
</pre>
A register holds the number of parameters. IX points to each parameter. IX+0/IX+1 is the last parameter. This happens because each parameter in order is pushed onto the stack and IX then points to the last parameter pushed. Each parameter is a 16-bit value.

If a parameter is a string, then IX holds the address of the string descriptor which point to a 3 byte block. The first byte of the string descriptor is the length. The next 2 bytes are an address that point to the string in memory.

With the help of the variable container "@" it is also possible to get a result from an invoked mc-code back to basic.
In this case the parameter contains the address of the integer, floating point or string. You can modify these to give the result.
BASIC allocates the strings, so when you modify a string, do not write more characters than the original string.

Hint: the first two bytes at the end of stack shows the internal return address from BASIC interpreter where it was executed.

== Additional keywords and variables in BASIC v1.1 ==

#BASIC v1.1 has the following additional keywords:
#*COPYCHR$
#*CURSOR
#*DEC$
#*FILL
#*FRAME
#*GRAPHICS
#*MASK
#BASIC v1.1 has the following additional predefined variables:
#*DERR

 

== BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

There are some rules for assigning names for variables:
: - it is not allowed to define a variable starting with a figure (the system expect then programming mode and interpret it as a program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - different sign e.g.: a slash (doesn't depend which direction), a 'minus' sign, a 'and' sign can't be used in a variable names
: - after a dollar sign (for defining string variables) it is not allowed to use further signs
: - different defining functions together are not allowed (e.g. use '%' together with '$')

: - you can use 40 characters for a variable name
: - use ! for defining a REAL value variable (like the function DEFREAL but only for the assigned variable) > It's also possible to omit the exlamation mark because it's the default system declaration after powering on then CPC.
: - use % for defining a INTEGER value variable (like the function DEFINT but only for the assigned variable)
: - use $ for defining a STRING variable (like the function DEFSTR but only for the assigned variable)
: - Minimum line number is 1. Maximum line number is 65535.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

 

== Speeding up BASIC programs ==

To speed up BASIC programs following rules could help:
: - Avoid loops or a branching program structure if possible. Internally the operating system searches for the right line number always from the beginning of the program 'listing'. Often recurring subroutines (if necessary) should be at the beginning of RAM to speed up things.
: - Avoid the index variable after the <code>NEXT</code> command/statement (although it isn't a good program style)
: - Avoid spaces inside program code or remarks
: - Put lots of statements as possible in ONE line
: - Use variables instead of constants. A constant has always to be converted in a binary/digital format. A variable is already converted.
: - Dimensioning at the beginning of the program
: - Dimensioning your variables & pre-calculate
: - Avoid AND/OR/XOR in IF-THEN statements. It's faster to write IF ... THEN (statement 1).. IF ... THEN (statement 2).
: - Minimise string/char manipulation as this often requires memory allocations. (e.g. joining strings with +, use of MID$, LEFT$, RIGHT$, SPACE$)

== Minimizing memory usage ==

To minimize memory usage in BASIC here are some things to consider.

The size of the tokenized program:
: - Difficult to measure without looking at the data in memory.
: - Use short variable names. The names are stored in the tokenized BASIC program as-is.
: - Minimize the number of variables. The names are stored in the tokenized BASIC program everywhere they are used.
: - Use as few lines as possible. It's a small saving of about 5 bytes per line.
: - Consider using numbers vs strings and potentially 8-bit or 16-bit values.

Minimising memory usage when the program is running:
: - Minimize string operations. (e.g. A$=SPACE$(30)+CHR$(28) in memory this first allocates a string of length 30 containing spaces, then it allocates a new string of length 31 with spaces and char 28 at the end and assigns it to A$. In this line at least 30 bytes have been wasted. So consider if you need strings or perhaps if possible pre-define them).

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences. Each line of the BASIC program has the form:

 

{| border="1"
|-
! Offset
! Size
! Description
|-
| 0
| 2
| Length of line data in bytes (note 1)
|-
| 2
| 2
| 16-bit decimal integer line number (note 2)
|-
| 4
| n
| BASIC line encoded into tokens (note 3)
|-
| n+1
| 1
| "0" the end of line marker (note 4)
|}

 Notes:

#This 16-bit value has two functions: if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data, otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
#This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
#This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
#This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| end of tokenised line marker
|-
| &01
| ":" statement seperator
|-
| &02
| integer variable definition (defined with "%" suffix)
|-
| &03
| string variable definition (defined with "$" suffix)
|-
| &04
| floating point variable definition (defined with "!" suffix)
|-
| &05
| var?
|-
| &06
| var?
|-
| &07
| var?
|-
| &08
| var?
|-
| &09
| var?
|-
| &0a
| var?
|-
| &0b
| variable definition (no suffix)
|-
| &0c
| variable definition (no suffix)
|-
| &0d
| variable definition (no suffix)
|-
| &0e
| number constant "0"
|-
| &0f
| number constant "1"
|-
| &10
| number constant "2"
|-
| &11
| number constant "3"
|-
| &12
| number constant "4"
|-
| &13
| number constant "5"
|-
| &14
| number constant "6"
|-
| &15
| number constant "7"
|-
| &16
| number constant "8"
|-
| &17
| number constant "9"
|-
| &18
| number constant "10"
|-
| &19
| 8-bit integer decimal value
|-
| &1a
| 16-bit integer decimal value
|-
| &1b
| 16-bit integer binary value (with "&X" prefix)
|-
| &1c
| 16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
| &1d
| 16-bit BASIC program line memory address pointer (see notes)
|-
| &1e
| 16-bit integer BASIC line number
|-
| &1f
| floating point value
|-
| &20
| " " (space) symbol
|-
| &21
| ASCII "!" symbol
|-
| &22
| quoted string value
|-
| &23-7b
| ASCII printable symbols
|-
| &7c
| "|" symbol; prefix for RSX commands
|-
| &80
| AFTER
|-
| &81
| AUTO
|-
| &82
| BORDER
|-
| &83
| CALL
|-
| &84
| CAT
|-
| &85
| CHAIN
|-
| &86
| CLEAR
|-
| &87
| CLG
|-
| &88
| CLOSEIN
|-
| &89
| CLOSEOUT
|-
| &8a
| CLS
|-
| &8b
| CONT
|-
| &8c
| DATA
|-
| &8d
| DEF
|-
| &8e
| DEFINT
|-
| &8f
| DEFREAL
|-
| &90
| DEFSTR
|-
| &91
| DEG
|-
| &92
| DELETE
|-
| &93
| DIM
|-
| &94
| DRAW
|-
| &95
| DRAWR
|-
| &96
| EDIT
|-
| &97
| ELSE
|-
| &98
| END
|-
| &99
| ENT
|-
| &9a
| ENV
|-
| &9b
| ERASE
|-
| &9c
| ERROR
|-
| &9d
| EVERY
|-
| &9e
| FOR
|-
| &9f
| GOSUB, GO SUB
|-
| &a0
| GOTO, GO TO
|-
| &a1
| IF
|-
| &a2
| INK
|-
| &a3
| INPUT
|-
| &a4
| KEY
|-
| &a5
| LET
|-
| &a6
| LINE
|-
| &a7
| LIST
|-
| &a8
| LOAD
|-
| &a9
| LOCATE
|-
| &aa
| MEMORY
|-
| &ab
| MERGE
|-
| &ac
| MID$
|-
| &ad
| MODE
|-
| &ae
| MOVE
|-
| &af
| MOVER
|-
| &b0
| NEXT
|-
| &b1
| NEW
|-
| &b2
| ON
|-
| &b3
| ON BREAK
|-
| &b4
| ON ERROR GOTO, ON ERROR GO TO
|-
| &b5
| ON SQ
|-
| &b6
| OPENIN
|-
| &b7
| OPENOUT
|-
| &b8
| ORIGIN
|-
| &b9
| OUT
|-
| &ba
| PAPER
|-
| &bb
| PEN
|-
| &bc
| PLOT
|-
| &bd
| PLOTR
|-
| &be
| POKE
|-
| &bf
| PRINT
|-
| &c0
| "'" symbol (same function as REM keyword)
|-
| &c1
| RAD
|-
| &c2
| RANDOMIZE
|-
| &c3
| READ
|-
| &c4
| RELEASE
|-
| &c5
| REM
|-
| &c6
| RENUM
|-
| &c7
| RESTORE
|-
| &c8
| RESUME
|-
| &c9
| RETURN
|-
| &ca
| RUN
|-
| &cb
| SAVE
|-
| &cc
| SOUND
|-
| &cd
| SPEED
|-
| &ce
| STOP
|-
| &cf
| SYMBOL
|-
| &d0
| TAG
|-
| &d1
| TAGOFF
|-
| &d2
| TROFF
|-
| &d3
| TRON
|-
| &d4
| WAIT
|-
| &d5
| WEND
|-
| &d6
| WHILE
|-
| &d7
| WIDTH
|-
| &d8
| WINDOW
|-
| &d9
| WRITE
|-
| &da
| ZONE
|-
| &db
| DI
|-
| &dc
| EI
|-
| &dd
| FILL (v1.1)
|-
| &de
| GRAPHICS (v1.1)
|-
| &df
| MASK (v1.1)
|-
| &e0
| FRAME (v1.1)
|-
| &e1
| CURSOR (v1.1)
|-
| &e2
| (note 2)
|-
| &e3
| ERL
|-
| &e4
| FN
|-
| &e5
| SPC
|-
| &e6
| STEP
|-
| &e7
| SWAP
|-
| &e8
| (note 2)
|-
| &e9
| (note 2)
|-
| &ea
| TAB
|-
| &eb
| THEN
|-
| &ec
| TO
|-
| &ed
| USING
|-
| &ee
| > (greater than)
|-
| &ef
| = (equal)
|-
| &f0
| &gt=, > =, => (greater or equal)
|-
| &f1
| < (less than)
|-
| &f2
| <&gt, < > (not equal)
|-
| &f3
| =<, <=, < = (less than or equal)
|-
| &f4
| + (addition)
|-
| &f5
| - (subtraction or unary minus)
|-
| &f6
| * (multiplication)
|-
| &f7
| / (division)
|-
| &f8
| ^ (x to the power of y)
|-
| &f9
| \ (integer division)
|-
| &fa
| AND
|-
| &fb
| MOD
|-
| &fc
| OR
|-
| &fd
| XOR
|-
| &fe
| NOT
|-
| &ff
| (prefix for additional keywords)
|}

 Notes:

*The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
*&e2,&e8 and &e9 are not used
*&7c ("|") is a character prefix used to identify an RSX command. e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| "|" character prefix
|-
| 1
| 1
| 8-bit byte offset to tokens following RSX name.
|-
| 2
| x
| RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
|}

*This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &1a,&2d,&00 represents the integer number "&002d"="45".
*This token (&0B) is changed at run-time to &0D
*This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
*This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
*This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| &1f (note 1)
|-
| 1
| 5
| Floating point number (note 2)
|}

*#This byte is the BASIC token identifying a floating point number
*#These 5 bytes define the floating point number.
*The space symbol is used as a command seperator
*Variable definitions:
**The variable definition has the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| Token defining variable type
|-
| 2
| 2
| 16-bit Byte offset to variable value within tokenised BASIC program.
|-
| 4
| x
| Variable name
|}

 The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.

**The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
**The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
*String values:
**Each string value is prefixed with &22 token.
**All strings must be enclosed by double quote symbols (&quot). This symbols define the start and end of the string value.
**The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.

*After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

 This table list the BASIC tokens with a &ff prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| ABS
|-
| &01
| ASC
|-
| &02
| ATN
|-
| &03
| CHR$
|-
| &04
| CINT
|-
| &05
| COS
|-
| &06
| CREAL
|-
| &07
| EXP
|-
| &08
| FIX
|-
| &09
| FRE
|-
| &0a
| INKEY
|-
| &0b
| INP
|-
| &0c
| INT
|-
| &0d
| JOY
|-
| &0e
| LEN
|-
| &0f
| LOG
|-
| &10
| LOG10
|-
| &11
| LOWER$
|-
| &12
| PEEK
|-
| &13
| REMAIN
|-
| &14
| SGN
|-
| &15
| SIN
|-
| &16
| SPACE$
|-
| &17
| SQ
|-
| &18
| SQR
|-
| &19
| STR$
|-
| &1a
| TAN
|-
| &1b
| UNT
|-
| &1c
| UPPER$
|-
| &1d
| VAL
|-
|  
| (note 2)
|-
| &40
| EOF
|-
| &41
| ERR
|-
| &42
| HIMEM
|-
| &43
| INKEY$
|-
| &44
| PI
|-
| &45
| RND
|-
| &46
| TIME
|-
| &47
| XPOS
|-
| &48
| YPOS
|-
| &49
| DERR (v1.1)
|-
|  
| (note 3)
|-
| &71
| BIN$
|-
| &72
| DEC$ (v1.1)
|-
| &73
| HEX$
|-
| &74
| INSTR
|-
| &75
| LEFT$
|-
| &76
| MAX
|-
| &77
| MIN
|-
| &78
| POS
|-
| &79
| RIGHT$
|-
| &7a
| ROUND
|-
| &7b
| STRING$
|-
| &7c
| TEST
|-
| &7d
| TESTR
|-
| &7e
| COPYCHR$ (v1.1)
|-
| &7f
| VPOS
|-
|  
| (note 4)
|}

 NOTES:

*These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence: <pre>&FF,&00</pre>
*Codes &1e...&3f inclusive are not used
*Codes &4a...&6f inclusive are not used
*Codes &80...&ff inclusive are not used

*When a BASIC program is in memory, the BASIC ROM can replace "16-bit BASIC program line number" tokens with "16-bit BASIC program line memory address pointer".

When a program is loaded or saved, there will only be "16-bit BASIC program line number" tokens followed by a 16-bit number of the line.

When a program is running, BASIC will replace the "16-bit BASIC program line number" with the "16-bit BASIC program line memory address pointer" token, and replace the 16-bit line number with the memory address of the start of that line.

It does this to avoid having to lookup the address of the line each time.

* When a REM or ' is seen, the characters following it are output directly (i.e. the bytes are not tokenized) until the end of line or a ':' is seen.

* When a BASIC program is listed each line is converted to a string (this includes the line number and the tokens converted to their strings). There is a maximum length for this string of 256 characters. This means that if the BASIC line is LISTed or EDITed, then the line will be displayed incorrectly with missing characters on the end. This is also noticed if you have a "10-liner" program that packs as much BASIC as possible into each line and renumber it so the line number has more digits.

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

 In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form: 1 x 2<exponent> The representation uses 5 bytes and is stored using the following structure:

 

{| border="1"
|-
! Byte
! colspan="8" | 0
! colspan="8" | 1
! colspan="8" | 2
! colspan="8" | 3
! colspan="8" | 4
|-
! Bit
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
|-
| Function
| colspan="8" | (LSB) mantissa (bits 31-24)
| colspan="8" | mantissa (bits 23-16)
| colspan="8" | mantissa (bits 15-8)
| colspan="1" | sign
| colspan="7" | (MSB) mantissa (bits 7-0)
| colspan="8" | exponent
|}

=== Sign ===

The sign is represented by bit 7 of byte 3. The value of the sign bit indicates the sign of the floating point number.

#*If the sign bit is "1", then the number is negative.
#*If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4. It is stored with a bias of 128.

#*128-255 are positive exponents,
#*1-127 are negative exponents.
#*0 means, the number is zero

To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 1 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^127.
A value of 0 just means, that the number is zero (0).

=== BASIC Display of Floating point numbers ===

* Numbers are displayed to 9 decimal places.
* If the number doesn't have a fractional part (e.g. .0) then the fractional part is not displayed.
* Trailing zeros (zero digits after the last digit in the fraction) are not displayed
* The value is rounded in the following way for display:

If the 10th fractional digit is 5 or above, then the number is rounded up.
If the 10th fractional digit is 4 or below, then the number is rounded down.
e.g.
0.1234567891 is displayed as 0.123456789
0.1234567895 is displayed as 0.12345679

=== floating point example in RAM by MaV ===

The initial figure = 43.375.
An example in BASIC:
<pre>
a!=43.375
READY
PRINT a!
43.375
PRINT @a!
374
FOR I=0 TO 4:PRINT HEX$(PEEK(374+I),2);:NEXT I
0000802D86
</pre>
the result for better readability: 
'''00 00 80 2D 86''' 
The first byte contains the least significant bits of the mantissa, and every following byte up to the fourth byte contain the bits following the first in significance and in exactly that order!

That means that you have to turn around the first four bytes if you want to read the mantissa correctly:
2D800000
or
0010.1101.1000.0000.0000.0000.0000.0000
in binary (the stops are inserted for better readability).

Now the highest significant bit here is 0, so the number is positive.
What's more, you need to clear that bit and substitute the implied highest bit (see description in the link), which is always 1 (regardless of the deleted sign bit!!!).
Thus you get:
AD800000
or
1010.1101.1000.0000.0000.0000.0000.0000
in binary.

The mantissa has an implied decimal point before the number. Since the number is 2^32 bits (i.e. 4 bytes) long you have to divide by 2^32 to get the proper decimal representation.

AD800000 (hex) = 2910846976 (dec)

2910846976 / 2^32 = 0.677734375

The mantissa in a decimal representation is: 0.677734375

Now, the last byte contains the exponent: 86 (hex) or 134 (dec). You need to subtract 128 to get the real exponent, the highest bit tells you that the exponent is positive (1) or negative (0). Your exponent is 6.

0.677734375 * 2^6 = 43.375

'''Another example:''' 
PI is represented in memory as: 
'''A2 DA 0F 49 82''' 
The mantissa is 
490FDAA2 (highest significant bit is zero => number is positive)
The exponent is 
82 (=positive mantissa, value=2 thus multiply mantissa with 2^2) 

Delete the sign bit (which is 0 anyway), and then add the implied 1 bit: 
C90FDAA2 (hex) = 3373259426 (dec) = 1100.1001.0000.1111.1101.1010.1010.0010 (bin) 

Calculate the decimal representation of the mantissa: 
3373259426 / 2^32 = 0,7853981633670628070831298828125 

Then add the exponent (82h - 80h = 2 thus 2^2) 
0,7853981633670628070831298828125 * 2^2 = 3,14159265346825122833251953125 

Voilà! The internal representation of the number PI on the CPC is: 3,14159265346825122833251953125 

If you compare to a (more) correct representation of PI, you'll see that the CPC is correct up to the 9th decimal place: 

CPC: 
3.14159265346825122833251953125 
more correctly: 
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986...

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts. The biggest figure which can be stored correctly in RAM by a variable is 2^32-1 = 4294967295.

*A real variable is defined with a "!" character postfix.

e.g.
<pre>a! = 3.141592654
</pre>
*A real number uses 5 bytes of memory as storage. The format is described above.
*The address of a real variable can be found in BASIC by:
<pre>PRINT @a!
</pre>

Where "a" should be replaced with the name of the variable.

 

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

 NOTES:

*A integer variable is defined with a "%" character postfix.

e.g.
<pre>a% = 3
</pre>
*A integer variable has a range of -32768 to 32767
*A integer variable always uses two bytes of memory as storage with the following format:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 2
| Integer number
|}

*The address of the integer variable can be found in BASIC by:
<pre>PRINT @a%
</pre>

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

 NOTES:

*A string variable is defined in BASIC with a "$" character postfix.

e.g.
<pre>a$ = "hello"
</pre>
*A string variable is described internally by a "string descriptor block" which has the following structure:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 1
| Length of string in bytes/characters
|-
| 1
| 2
| Location of start of string
|}

*The address of the "string descriptor block" for the string variable can be found in BASIC by typing:
<pre>PRINT @a$
</pre>

replacing "a$" with the name of the string variable.

*A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
*A string variable can contain any ASCII character code in the range 0-255.
*A string variable can store a minimum of 0 characters and a maximum of 255 characters.
*The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Technical information about Locomotive BASIC

2025-08-24T10:23:52Z

Arnoldemu: /* BASIC integer variables */

[[Category:Cpctech.org]]

'''''This article originally came from Kevin Thackers' archive at [http://www.cpctech.org.uk http://www.cpctech.org.uk].'''''

= Technical information about Locomotive BASIC =

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== BASIC v1.0 only ==

There is a region of memory between AC00-AC1B which is filled with RET instructions. The BASIC ROM calls the following locations:
AC01,AC04,AC07,AC0A,AC0D,AC10,AC13,AC16,AC19

It almost looks like these were used for debugging the ROM but were left in.

They can be used to implement new BASIC commands.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR". A binary function is accessed through BASIC using the "CALL" command.

Both RSX and CALL commands work (are!) similar from the BASIC command line and invoke machine code - the only difference is: with the help of a RSX command you don't need to know the exact access address. You can pass up to 32 parameters with a CALL or RSX command. Possible parameters could be integer, floating points and strings. Just store the parameter into a variable:
Passing for integer:
<pre>
CALL &4000,32,34,&5E,&x10101010
|RSX-command,32,34,&5E,&x10101010
</pre>
Passing for floating points
<pre>
@a!=43.375
CALL or |RSX-command,@a!
</pre>

 Passing a string parameter:
 BASIC v1.0
<pre>a$="A":|DRIVE,@a$
</pre>
BASIC v1.1:
<pre>|DRIVE,"A"
</pre>
or
<pre>
b$="test"
CALL or |RSX-command,@b$
</pre>

The parameters will be stored inside the range of Stack:
<pre>
A=n -------> MSB PARAM1
LSB PARAM1
MSB PARAM2
LSB PARAM2
...
...
...
MSB PARAMn
IX+0 ------> LSB PARAMn
</pre>
with the help of that assembly code is it possible to find the parameters:
<pre>
ROUT1: CP x ;test register A if "x" parameters were given, e.g. x = 2
RET NZ ; if not exactly x parameters then do not execute RSX.
LD L,(IX+0)
LD H,(IX+1) ; HL = value of last parameter
LD E,(IX+2)
LD D,(IX+3) ; DE = value of next to last parameter
...
</pre>
A register holds the number of parameters. IX points to each parameter. IX+0/IX+1 is the last parameter. This happens because each parameter in order is pushed onto the stack and IX then points to the last parameter pushed. Each parameter is a 16-bit value.

If a parameter is a string, then IX holds the address of the string descriptor which point to a 3 byte block. The first byte of the string descriptor is the length. The next 2 bytes are an address that point to the string in memory.

With the help of the variable container "@" it is also possible to get a result from an invoked mc-code back to basic.
In this case the parameter contains the address of the integer, floating point or string. You can modify these to give the result.
BASIC allocates the strings, so when you modify a string, do not write more characters than the original string.

Hint: the first two bytes at the end of stack shows the internal return address from BASIC interpreter where it was executed.

== Additional keywords and variables in BASIC v1.1 ==

#BASIC v1.1 has the following additional keywords:
#*COPYCHR$
#*CURSOR
#*DEC$
#*FILL
#*FRAME
#*GRAPHICS
#*MASK
#BASIC v1.1 has the following additional predefined variables:
#*DERR

 

== BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

There are some rules for assigning names for variables:
: - it is not allowed to define a variable starting with a figure (the system expect then programming mode and interpret it as a program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - different sign e.g.: a slash (doesn't depend which direction), a 'minus' sign, a 'and' sign can't be used in a variable names
: - after a dollar sign (for defining string variables) it is not allowed to use further signs
: - different defining functions together are not allowed (e.g. use '%' together with '$')

: - you can use 40 characters for a variable name
: - use ! for defining a REAL value variable (like the function DEFREAL but only for the assigned variable) > It's also possible to omit the exlamation mark because it's the default system declaration after powering on then CPC.
: - use % for defining a INTEGER value variable (like the function DEFINT but only for the assigned variable)
: - use $ for defining a STRING variable (like the function DEFSTR but only for the assigned variable)
: - Minimum line number is 1. Maximum line number is 65535.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

 

== Speeding up BASIC programs ==

To speed up BASIC programs following rules could help:
: - Avoid loops or a branching program structure if possible. Internally the operating system searches for the right line number always from the beginning of the program 'listing'. Often recurring subroutines (if necessary) should be at the beginning of RAM to speed up things.
: - Avoid the index variable after the <code>NEXT</code> command/statement (although it isn't a good program style)
: - Avoid spaces inside program code or remarks
: - Put lots of statements as possible in ONE line
: - Use variables instead of constants. A constant has always to be converted in a binary/digital format. A variable is already converted.
: - Dimensioning at the beginning of the program
: - Dimensioning your variables & pre-calculate
: - Avoid AND/OR/XOR in IF-THEN statements. It's faster to write IF ... THEN (statement 1).. IF ... THEN (statement 2).
: - Minimise string/char manipulation as this often requires memory allocations. (e.g. joining strings with +, use of MID$, LEFT$, RIGHT$, SPACE$)

== Minimizing memory usage ==

To minimize memory usage in BASIC here are some things to consider.

The size of the tokenized program:
: - Difficult to measure without looking at the data in memory.
: - Use short variable names. The names are stored in the tokenized BASIC program as-is.
: - Minimize the number of variables. The names are stored in the tokenized BASIC program everywhere they are used.
: - Use as few lines as possible. It's a small saving of about 5 bytes per line.
: - Consider using numbers vs strings and potentially 8-bit or 16-bit values.

Minimising memory usage when the program is running:
: - Minimize string operations. (e.g. A$=SPACE$(30)+CHR$(28) in memory this first allocates a string of length 30 containing spaces, then it allocates a new string of length 31 with spaces and char 28 at the end and assigns it to A$. In this line at least 30 bytes have been wasted. So consider if you need strings or perhaps if possible pre-define them).

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences. Each line of the BASIC program has the form:

 

{| border="1"
|-
! Offset
! Size
! Description
|-
| 0
| 2
| Length of line data in bytes (note 1)
|-
| 2
| 2
| 16-bit decimal integer line number (note 2)
|-
| 4
| n
| BASIC line encoded into tokens (note 3)
|-
| n+1
| 1
| "0" the end of line marker (note 4)
|}

 Notes:

#This 16-bit value has two functions: if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data, otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
#This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
#This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
#This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| end of tokenised line marker
|-
| &01
| ":" statement seperator
|-
| &02
| integer variable definition (defined with "%" suffix)
|-
| &03
| string variable definition (defined with "$" suffix)
|-
| &04
| floating point variable definition (defined with "!" suffix)
|-
| &05
| var?
|-
| &06
| var?
|-
| &07
| var?
|-
| &08
| var?
|-
| &09
| var?
|-
| &0a
| var?
|-
| &0b
| variable definition (no suffix)
|-
| &0c
| variable definition (no suffix)
|-
| &0d
| variable definition (no suffix)
|-
| &0e
| number constant "0"
|-
| &0f
| number constant "1"
|-
| &10
| number constant "2"
|-
| &11
| number constant "3"
|-
| &12
| number constant "4"
|-
| &13
| number constant "5"
|-
| &14
| number constant "6"
|-
| &15
| number constant "7"
|-
| &16
| number constant "8"
|-
| &17
| number constant "9"
|-
| &18
| number constant "10"
|-
| &19
| 8-bit integer decimal value
|-
| &1a
| 16-bit integer decimal value
|-
| &1b
| 16-bit integer binary value (with "&X" prefix)
|-
| &1c
| 16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
| &1d
| 16-bit BASIC program line memory address pointer (see notes)
|-
| &1e
| 16-bit integer BASIC line number
|-
| &1f
| floating point value
|-
| &20
| " " (space) symbol
|-
| &21
| ASCII "!" symbol
|-
| &22
| quoted string value
|-
| &23-7b
| ASCII printable symbols
|-
| &7c
| "|" symbol; prefix for RSX commands
|-
| &80
| AFTER
|-
| &81
| AUTO
|-
| &82
| BORDER
|-
| &83
| CALL
|-
| &84
| CAT
|-
| &85
| CHAIN
|-
| &86
| CLEAR
|-
| &87
| CLG
|-
| &88
| CLOSEIN
|-
| &89
| CLOSEOUT
|-
| &8a
| CLS
|-
| &8b
| CONT
|-
| &8c
| DATA
|-
| &8d
| DEF
|-
| &8e
| DEFINT
|-
| &8f
| DEFREAL
|-
| &90
| DEFSTR
|-
| &91
| DEG
|-
| &92
| DELETE
|-
| &93
| DIM
|-
| &94
| DRAW
|-
| &95
| DRAWR
|-
| &96
| EDIT
|-
| &97
| ELSE
|-
| &98
| END
|-
| &99
| ENT
|-
| &9a
| ENV
|-
| &9b
| ERASE
|-
| &9c
| ERROR
|-
| &9d
| EVERY
|-
| &9e
| FOR
|-
| &9f
| GOSUB, GO SUB
|-
| &a0
| GOTO, GO TO
|-
| &a1
| IF
|-
| &a2
| INK
|-
| &a3
| INPUT
|-
| &a4
| KEY
|-
| &a5
| LET
|-
| &a6
| LINE
|-
| &a7
| LIST
|-
| &a8
| LOAD
|-
| &a9
| LOCATE
|-
| &aa
| MEMORY
|-
| &ab
| MERGE
|-
| &ac
| MID$
|-
| &ad
| MODE
|-
| &ae
| MOVE
|-
| &af
| MOVER
|-
| &b0
| NEXT
|-
| &b1
| NEW
|-
| &b2
| ON
|-
| &b3
| ON BREAK
|-
| &b4
| ON ERROR GOTO, ON ERROR GO TO
|-
| &b5
| ON SQ
|-
| &b6
| OPENIN
|-
| &b7
| OPENOUT
|-
| &b8
| ORIGIN
|-
| &b9
| OUT
|-
| &ba
| PAPER
|-
| &bb
| PEN
|-
| &bc
| PLOT
|-
| &bd
| PLOTR
|-
| &be
| POKE
|-
| &bf
| PRINT
|-
| &c0
| "'" symbol (same function as REM keyword)
|-
| &c1
| RAD
|-
| &c2
| RANDOMIZE
|-
| &c3
| READ
|-
| &c4
| RELEASE
|-
| &c5
| REM
|-
| &c6
| RENUM
|-
| &c7
| RESTORE
|-
| &c8
| RESUME
|-
| &c9
| RETURN
|-
| &ca
| RUN
|-
| &cb
| SAVE
|-
| &cc
| SOUND
|-
| &cd
| SPEED
|-
| &ce
| STOP
|-
| &cf
| SYMBOL
|-
| &d0
| TAG
|-
| &d1
| TAGOFF
|-
| &d2
| TROFF
|-
| &d3
| TRON
|-
| &d4
| WAIT
|-
| &d5
| WEND
|-
| &d6
| WHILE
|-
| &d7
| WIDTH
|-
| &d8
| WINDOW
|-
| &d9
| WRITE
|-
| &da
| ZONE
|-
| &db
| DI
|-
| &dc
| EI
|-
| &dd
| FILL (v1.1)
|-
| &de
| GRAPHICS (v1.1)
|-
| &df
| MASK (v1.1)
|-
| &e0
| FRAME (v1.1)
|-
| &e1
| CURSOR (v1.1)
|-
| &e2
| (note 2)
|-
| &e3
| ERL
|-
| &e4
| FN
|-
| &e5
| SPC
|-
| &e6
| STEP
|-
| &e7
| SWAP
|-
| &e8
| (note 2)
|-
| &e9
| (note 2)
|-
| &ea
| TAB
|-
| &eb
| THEN
|-
| &ec
| TO
|-
| &ed
| USING
|-
| &ee
| > (greater than)
|-
| &ef
| = (equal)
|-
| &f0
| &gt=, > =, => (greater or equal)
|-
| &f1
| < (less than)
|-
| &f2
| <&gt, < > (not equal)
|-
| &f3
| =<, <=, < = (less than or equal)
|-
| &f4
| + (addition)
|-
| &f5
| - (subtraction or unary minus)
|-
| &f6
| * (multiplication)
|-
| &f7
| / (division)
|-
| &f8
| ^ (x to the power of y)
|-
| &f9
| \ (integer division)
|-
| &fa
| AND
|-
| &fb
| MOD
|-
| &fc
| OR
|-
| &fd
| XOR
|-
| &fe
| NOT
|-
| &ff
| (prefix for additional keywords)
|}

 Notes:

*The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
*&e2,&e8 and &e9 are not used
*&7c ("|") is a character prefix used to identify an RSX command. e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| "|" character prefix
|-
| 1
| 1
| 8-bit byte offset to tokens following RSX name.
|-
| 2
| x
| RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
|}

*This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &1a,&2d,&00 represents the integer number "&002d"="45".
*This token (&0B) is changed at run-time to &0D
*This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
*This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
*This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| &1f (note 1)
|-
| 1
| 5
| Floating point number (note 2)
|}

*#This byte is the BASIC token identifying a floating point number
*#These 5 bytes define the floating point number.
*The space symbol is used as a command seperator
*Variable definitions:
**The variable definition has the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| Token defining variable type
|-
| 2
| 2
| 16-bit Byte offset to variable value within tokenised BASIC program.
|-
| 4
| x
| Variable name
|}

 The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.

**The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
**The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
*String values:
**Each string value is prefixed with &22 token.
**All strings must be enclosed by double quote symbols (&quot). This symbols define the start and end of the string value.
**The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.

*After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

 This table list the BASIC tokens with a &ff prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| ABS
|-
| &01
| ASC
|-
| &02
| ATN
|-
| &03
| CHR$
|-
| &04
| CINT
|-
| &05
| COS
|-
| &06
| CREAL
|-
| &07
| EXP
|-
| &08
| FIX
|-
| &09
| FRE
|-
| &0a
| INKEY
|-
| &0b
| INP
|-
| &0c
| INT
|-
| &0d
| JOY
|-
| &0e
| LEN
|-
| &0f
| LOG
|-
| &10
| LOG10
|-
| &11
| LOWER$
|-
| &12
| PEEK
|-
| &13
| REMAIN
|-
| &14
| SGN
|-
| &15
| SIN
|-
| &16
| SPACE$
|-
| &17
| SQ
|-
| &18
| SQR
|-
| &19
| STR$
|-
| &1a
| TAN
|-
| &1b
| UNT
|-
| &1c
| UPPER$
|-
| &1d
| VAL
|-
|  
| (note 2)
|-
| &40
| EOF
|-
| &41
| ERR
|-
| &42
| HIMEM
|-
| &43
| INKEY$
|-
| &44
| PI
|-
| &45
| RND
|-
| &46
| TIME
|-
| &47
| XPOS
|-
| &48
| YPOS
|-
| &49
| DERR (v1.1)
|-
|  
| (note 3)
|-
| &71
| BIN$
|-
| &72
| DEC$ (v1.1)
|-
| &73
| HEX$
|-
| &74
| INSTR
|-
| &75
| LEFT$
|-
| &76
| MAX
|-
| &77
| MIN
|-
| &78
| POS
|-
| &79
| RIGHT$
|-
| &7a
| ROUND
|-
| &7b
| STRING$
|-
| &7c
| TEST
|-
| &7d
| TESTR
|-
| &7e
| COPYCHR$ (v1.1)
|-
| &7f
| VPOS
|-
|  
| (note 4)
|}

 NOTES:

*These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence: <pre>&FF,&00</pre>
*Codes &1e...&3f inclusive are not used
*Codes &4a...&6f inclusive are not used
*Codes &80...&ff inclusive are not used

*When a BASIC program is in memory, the BASIC ROM can replace "16-bit BASIC program line number" tokens with "16-bit BASIC program line memory address pointer".

When a program is loaded or saved, there will only be "16-bit BASIC program line number" tokens followed by a 16-bit number of the line.

When a program is running, BASIC will replace the "16-bit BASIC program line number" with the "16-bit BASIC program line memory address pointer" token, and replace the 16-bit line number with the memory address of the start of that line.

It does this to avoid having to lookup the address of the line each time.

* When a REM or ' is seen, the characters following it are output directly (i.e. the bytes are not tokenized) until the end of line or a ':' is seen.

* When a BASIC program is listed each line is converted to a string (this includes the line number and the tokens converted to their strings). There is a maximum length for this string of 256 characters. This means that if the BASIC line is LISTed or EDITed, then the line will be displayed incorrectly with missing characters on the end. This is also noticed if you have a "10-liner" program that packs as much BASIC as possible into each line and renumber it so the line number has more digits.

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

 In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form: 1 x 2<exponent> The representation uses 5 bytes and is stored using the following structure:

 

{| border="1"
|-
! Byte
! colspan="8" | 0
! colspan="8" | 1
! colspan="8" | 2
! colspan="8" | 3
! colspan="8" | 4
|-
! Bit
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
|-
| Function
| colspan="8" | (LSB) mantissa (bits 31-24)
| colspan="8" | mantissa (bits 23-16)
| colspan="8" | mantissa (bits 15-8)
| colspan="1" | sign
| colspan="7" | (MSB) mantissa (bits 7-0)
| colspan="8" | exponent
|}

=== Sign ===

The sign is represented by bit 7 of byte 3. The value of the sign bit indicates the sign of the floating point number.

#*If the sign bit is "1", then the number is negative.
#*If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4. It is stored with a bias of 128.

#*128-255 are positive exponents,
#*1-127 are negative exponents.
#*0 means, the number is zero

To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 1 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^127.
A value of 0 just means, that the number is zero (0).

=== BASIC Display of Floating point numbers ===

* Numbers are displayed to 9 decimal places.
* If the number doesn't have a fractional part (e.g. .0) then the fractional part is not displayed.
* Trailing zeros (zero digits after the last digit in the fraction) are not displayed
* The value is rounded in the following way for display:

If the 10th fractional digit is 5 or above, then the number is rounded up.
If the 10th fractional digit is 4 or below, then the number is rounded down.
e.g.
0.1234567891 is displayed as 0.123456789
0.1234567895 is displayed as 0.12345679

=== floating point example in RAM by MaV ===

The initial figure = 43.375.
An example in BASIC:
<pre>
a!=43.375
READY
PRINT a!
43.375
PRINT @a!
374
FOR I=0 TO 4:PRINT HEX$(PEEK(374+I),2);:NEXT I
0000802D86
</pre>
the result for better readability: 
'''00 00 80 2D 86''' 
The first byte contains the least significant bits of the mantissa, and every following byte up to the fourth byte contain the bits following the first in significance and in exactly that order!

That means that you have to turn around the first four bytes if you want to read the mantissa correctly:
2D800000
or
0010.1101.1000.0000.0000.0000.0000.0000
in binary (the stops are inserted for better readability).

Now the highest significant bit here is 0, so the number is positive.
What's more, you need to clear that bit and substitute the implied highest bit (see description in the link), which is always 1 (regardless of the deleted sign bit!!!).
Thus you get:
AD800000
or
1010.1101.1000.0000.0000.0000.0000.0000
in binary.

The mantissa has an implied decimal point before the number. Since the number is 2^32 bits (i.e. 4 bytes) long you have to divide by 2^32 to get the proper decimal representation.

AD800000 (hex) = 2910846976 (dec)

2910846976 / 2^32 = 0.677734375

The mantissa in a decimal representation is: 0.677734375

Now, the last byte contains the exponent: 86 (hex) or 134 (dec). You need to subtract 128 to get the real exponent, the highest bit tells you that the exponent is positive (1) or negative (0). Your exponent is 6.

0.677734375 * 2^6 = 43.375

'''Another example:''' 
PI is represented in memory as: 
'''A2 DA 0F 49 82''' 
The mantissa is 
490FDAA2 (highest significant bit is zero => number is positive)
The exponent is 
82 (=positive mantissa, value=2 thus multiply mantissa with 2^2) 

Delete the sign bit (which is 0 anyway), and then add the implied 1 bit: 
C90FDAA2 (hex) = 3373259426 (dec) = 1100.1001.0000.1111.1101.1010.1010.0010 (bin) 

Calculate the decimal representation of the mantissa: 
3373259426 / 2^32 = 0,7853981633670628070831298828125 

Then add the exponent (82h - 80h = 2 thus 2^2) 
0,7853981633670628070831298828125 * 2^2 = 3,14159265346825122833251953125 

Voilà! The internal representation of the number PI on the CPC is: 3,14159265346825122833251953125 

If you compare to a (more) correct representation of PI, you'll see that the CPC is correct up to the 9th decimal place: 

CPC: 
3.14159265346825122833251953125 
more correctly: 
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986...

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts. The biggest figure which can be stored correctly in RAM by a variable is 2^32-1 = 4294967295.

#A real variable is defined with a "!" character postfix.

e.g.
<pre>a! = 3.141592654
</pre>
#A real number uses 5 bytes of memory as storage. The format is described above.
#The address of a real variable can be found in BASIC by:
<pre>PRINT @a!
</pre>

Where "a" should be replaced with the name of the variable.

 

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

 NOTES:

*A integer variable is defined with a "%" character postfix.

e.g.
<pre>a% = 3
</pre>
*A integer variable has a range of -32768 to 32767
*A integer variable always uses two bytes of memory as storage with the following format:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 2
| Integer number
|}

*The address of the integer variable can be found in BASIC by:
<pre>PRINT @a%
</pre>

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

 NOTES:

*A string variable is defined in BASIC with a "$" character postfix.

e.g.
<pre>a$ = "hello"
</pre>
*A string variable is described internally by a "string descriptor block" which has the following structure:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 1
| Length of string in bytes/characters
|-
| 1
| 2
| Location of start of string
|}

*The address of the "string descriptor block" for the string variable can be found in BASIC by typing:
<pre>PRINT @a$
</pre>

replacing "a$" with the name of the string variable.

*A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
*A string variable can contain any ASCII character code in the range 0-255.
*A string variable can store a minimum of 0 characters and a maximum of 255 characters.
*The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Technical information about Locomotive BASIC

2025-08-24T10:23:40Z

Arnoldemu: /* BASIC string variables */

[[Category:Cpctech.org]]

'''''This article originally came from Kevin Thackers' archive at [http://www.cpctech.org.uk http://www.cpctech.org.uk].'''''

= Technical information about Locomotive BASIC =

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== BASIC v1.0 only ==

There is a region of memory between AC00-AC1B which is filled with RET instructions. The BASIC ROM calls the following locations:
AC01,AC04,AC07,AC0A,AC0D,AC10,AC13,AC16,AC19

It almost looks like these were used for debugging the ROM but were left in.

They can be used to implement new BASIC commands.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR". A binary function is accessed through BASIC using the "CALL" command.

Both RSX and CALL commands work (are!) similar from the BASIC command line and invoke machine code - the only difference is: with the help of a RSX command you don't need to know the exact access address. You can pass up to 32 parameters with a CALL or RSX command. Possible parameters could be integer, floating points and strings. Just store the parameter into a variable:
Passing for integer:
<pre>
CALL &4000,32,34,&5E,&x10101010
|RSX-command,32,34,&5E,&x10101010
</pre>
Passing for floating points
<pre>
@a!=43.375
CALL or |RSX-command,@a!
</pre>

 Passing a string parameter:
 BASIC v1.0
<pre>a$="A":|DRIVE,@a$
</pre>
BASIC v1.1:
<pre>|DRIVE,"A"
</pre>
or
<pre>
b$="test"
CALL or |RSX-command,@b$
</pre>

The parameters will be stored inside the range of Stack:
<pre>
A=n -------> MSB PARAM1
LSB PARAM1
MSB PARAM2
LSB PARAM2
...
...
...
MSB PARAMn
IX+0 ------> LSB PARAMn
</pre>
with the help of that assembly code is it possible to find the parameters:
<pre>
ROUT1: CP x ;test register A if "x" parameters were given, e.g. x = 2
RET NZ ; if not exactly x parameters then do not execute RSX.
LD L,(IX+0)
LD H,(IX+1) ; HL = value of last parameter
LD E,(IX+2)
LD D,(IX+3) ; DE = value of next to last parameter
...
</pre>
A register holds the number of parameters. IX points to each parameter. IX+0/IX+1 is the last parameter. This happens because each parameter in order is pushed onto the stack and IX then points to the last parameter pushed. Each parameter is a 16-bit value.

If a parameter is a string, then IX holds the address of the string descriptor which point to a 3 byte block. The first byte of the string descriptor is the length. The next 2 bytes are an address that point to the string in memory.

With the help of the variable container "@" it is also possible to get a result from an invoked mc-code back to basic.
In this case the parameter contains the address of the integer, floating point or string. You can modify these to give the result.
BASIC allocates the strings, so when you modify a string, do not write more characters than the original string.

Hint: the first two bytes at the end of stack shows the internal return address from BASIC interpreter where it was executed.

== Additional keywords and variables in BASIC v1.1 ==

#BASIC v1.1 has the following additional keywords:
#*COPYCHR$
#*CURSOR
#*DEC$
#*FILL
#*FRAME
#*GRAPHICS
#*MASK
#BASIC v1.1 has the following additional predefined variables:
#*DERR

 

== BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

There are some rules for assigning names for variables:
: - it is not allowed to define a variable starting with a figure (the system expect then programming mode and interpret it as a program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - different sign e.g.: a slash (doesn't depend which direction), a 'minus' sign, a 'and' sign can't be used in a variable names
: - after a dollar sign (for defining string variables) it is not allowed to use further signs
: - different defining functions together are not allowed (e.g. use '%' together with '$')

: - you can use 40 characters for a variable name
: - use ! for defining a REAL value variable (like the function DEFREAL but only for the assigned variable) > It's also possible to omit the exlamation mark because it's the default system declaration after powering on then CPC.
: - use % for defining a INTEGER value variable (like the function DEFINT but only for the assigned variable)
: - use $ for defining a STRING variable (like the function DEFSTR but only for the assigned variable)
: - Minimum line number is 1. Maximum line number is 65535.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

 

== Speeding up BASIC programs ==

To speed up BASIC programs following rules could help:
: - Avoid loops or a branching program structure if possible. Internally the operating system searches for the right line number always from the beginning of the program 'listing'. Often recurring subroutines (if necessary) should be at the beginning of RAM to speed up things.
: - Avoid the index variable after the <code>NEXT</code> command/statement (although it isn't a good program style)
: - Avoid spaces inside program code or remarks
: - Put lots of statements as possible in ONE line
: - Use variables instead of constants. A constant has always to be converted in a binary/digital format. A variable is already converted.
: - Dimensioning at the beginning of the program
: - Dimensioning your variables & pre-calculate
: - Avoid AND/OR/XOR in IF-THEN statements. It's faster to write IF ... THEN (statement 1).. IF ... THEN (statement 2).
: - Minimise string/char manipulation as this often requires memory allocations. (e.g. joining strings with +, use of MID$, LEFT$, RIGHT$, SPACE$)

== Minimizing memory usage ==

To minimize memory usage in BASIC here are some things to consider.

The size of the tokenized program:
: - Difficult to measure without looking at the data in memory.
: - Use short variable names. The names are stored in the tokenized BASIC program as-is.
: - Minimize the number of variables. The names are stored in the tokenized BASIC program everywhere they are used.
: - Use as few lines as possible. It's a small saving of about 5 bytes per line.
: - Consider using numbers vs strings and potentially 8-bit or 16-bit values.

Minimising memory usage when the program is running:
: - Minimize string operations. (e.g. A$=SPACE$(30)+CHR$(28) in memory this first allocates a string of length 30 containing spaces, then it allocates a new string of length 31 with spaces and char 28 at the end and assigns it to A$. In this line at least 30 bytes have been wasted. So consider if you need strings or perhaps if possible pre-define them).

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences. Each line of the BASIC program has the form:

 

{| border="1"
|-
! Offset
! Size
! Description
|-
| 0
| 2
| Length of line data in bytes (note 1)
|-
| 2
| 2
| 16-bit decimal integer line number (note 2)
|-
| 4
| n
| BASIC line encoded into tokens (note 3)
|-
| n+1
| 1
| "0" the end of line marker (note 4)
|}

 Notes:

#This 16-bit value has two functions: if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data, otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
#This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
#This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
#This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| end of tokenised line marker
|-
| &01
| ":" statement seperator
|-
| &02
| integer variable definition (defined with "%" suffix)
|-
| &03
| string variable definition (defined with "$" suffix)
|-
| &04
| floating point variable definition (defined with "!" suffix)
|-
| &05
| var?
|-
| &06
| var?
|-
| &07
| var?
|-
| &08
| var?
|-
| &09
| var?
|-
| &0a
| var?
|-
| &0b
| variable definition (no suffix)
|-
| &0c
| variable definition (no suffix)
|-
| &0d
| variable definition (no suffix)
|-
| &0e
| number constant "0"
|-
| &0f
| number constant "1"
|-
| &10
| number constant "2"
|-
| &11
| number constant "3"
|-
| &12
| number constant "4"
|-
| &13
| number constant "5"
|-
| &14
| number constant "6"
|-
| &15
| number constant "7"
|-
| &16
| number constant "8"
|-
| &17
| number constant "9"
|-
| &18
| number constant "10"
|-
| &19
| 8-bit integer decimal value
|-
| &1a
| 16-bit integer decimal value
|-
| &1b
| 16-bit integer binary value (with "&X" prefix)
|-
| &1c
| 16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
| &1d
| 16-bit BASIC program line memory address pointer (see notes)
|-
| &1e
| 16-bit integer BASIC line number
|-
| &1f
| floating point value
|-
| &20
| " " (space) symbol
|-
| &21
| ASCII "!" symbol
|-
| &22
| quoted string value
|-
| &23-7b
| ASCII printable symbols
|-
| &7c
| "|" symbol; prefix for RSX commands
|-
| &80
| AFTER
|-
| &81
| AUTO
|-
| &82
| BORDER
|-
| &83
| CALL
|-
| &84
| CAT
|-
| &85
| CHAIN
|-
| &86
| CLEAR
|-
| &87
| CLG
|-
| &88
| CLOSEIN
|-
| &89
| CLOSEOUT
|-
| &8a
| CLS
|-
| &8b
| CONT
|-
| &8c
| DATA
|-
| &8d
| DEF
|-
| &8e
| DEFINT
|-
| &8f
| DEFREAL
|-
| &90
| DEFSTR
|-
| &91
| DEG
|-
| &92
| DELETE
|-
| &93
| DIM
|-
| &94
| DRAW
|-
| &95
| DRAWR
|-
| &96
| EDIT
|-
| &97
| ELSE
|-
| &98
| END
|-
| &99
| ENT
|-
| &9a
| ENV
|-
| &9b
| ERASE
|-
| &9c
| ERROR
|-
| &9d
| EVERY
|-
| &9e
| FOR
|-
| &9f
| GOSUB, GO SUB
|-
| &a0
| GOTO, GO TO
|-
| &a1
| IF
|-
| &a2
| INK
|-
| &a3
| INPUT
|-
| &a4
| KEY
|-
| &a5
| LET
|-
| &a6
| LINE
|-
| &a7
| LIST
|-
| &a8
| LOAD
|-
| &a9
| LOCATE
|-
| &aa
| MEMORY
|-
| &ab
| MERGE
|-
| &ac
| MID$
|-
| &ad
| MODE
|-
| &ae
| MOVE
|-
| &af
| MOVER
|-
| &b0
| NEXT
|-
| &b1
| NEW
|-
| &b2
| ON
|-
| &b3
| ON BREAK
|-
| &b4
| ON ERROR GOTO, ON ERROR GO TO
|-
| &b5
| ON SQ
|-
| &b6
| OPENIN
|-
| &b7
| OPENOUT
|-
| &b8
| ORIGIN
|-
| &b9
| OUT
|-
| &ba
| PAPER
|-
| &bb
| PEN
|-
| &bc
| PLOT
|-
| &bd
| PLOTR
|-
| &be
| POKE
|-
| &bf
| PRINT
|-
| &c0
| "'" symbol (same function as REM keyword)
|-
| &c1
| RAD
|-
| &c2
| RANDOMIZE
|-
| &c3
| READ
|-
| &c4
| RELEASE
|-
| &c5
| REM
|-
| &c6
| RENUM
|-
| &c7
| RESTORE
|-
| &c8
| RESUME
|-
| &c9
| RETURN
|-
| &ca
| RUN
|-
| &cb
| SAVE
|-
| &cc
| SOUND
|-
| &cd
| SPEED
|-
| &ce
| STOP
|-
| &cf
| SYMBOL
|-
| &d0
| TAG
|-
| &d1
| TAGOFF
|-
| &d2
| TROFF
|-
| &d3
| TRON
|-
| &d4
| WAIT
|-
| &d5
| WEND
|-
| &d6
| WHILE
|-
| &d7
| WIDTH
|-
| &d8
| WINDOW
|-
| &d9
| WRITE
|-
| &da
| ZONE
|-
| &db
| DI
|-
| &dc
| EI
|-
| &dd
| FILL (v1.1)
|-
| &de
| GRAPHICS (v1.1)
|-
| &df
| MASK (v1.1)
|-
| &e0
| FRAME (v1.1)
|-
| &e1
| CURSOR (v1.1)
|-
| &e2
| (note 2)
|-
| &e3
| ERL
|-
| &e4
| FN
|-
| &e5
| SPC
|-
| &e6
| STEP
|-
| &e7
| SWAP
|-
| &e8
| (note 2)
|-
| &e9
| (note 2)
|-
| &ea
| TAB
|-
| &eb
| THEN
|-
| &ec
| TO
|-
| &ed
| USING
|-
| &ee
| > (greater than)
|-
| &ef
| = (equal)
|-
| &f0
| &gt=, > =, => (greater or equal)
|-
| &f1
| < (less than)
|-
| &f2
| <&gt, < > (not equal)
|-
| &f3
| =<, <=, < = (less than or equal)
|-
| &f4
| + (addition)
|-
| &f5
| - (subtraction or unary minus)
|-
| &f6
| * (multiplication)
|-
| &f7
| / (division)
|-
| &f8
| ^ (x to the power of y)
|-
| &f9
| \ (integer division)
|-
| &fa
| AND
|-
| &fb
| MOD
|-
| &fc
| OR
|-
| &fd
| XOR
|-
| &fe
| NOT
|-
| &ff
| (prefix for additional keywords)
|}

 Notes:

*The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
*&e2,&e8 and &e9 are not used
*&7c ("|") is a character prefix used to identify an RSX command. e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| "|" character prefix
|-
| 1
| 1
| 8-bit byte offset to tokens following RSX name.
|-
| 2
| x
| RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
|}

*This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &1a,&2d,&00 represents the integer number "&002d"="45".
*This token (&0B) is changed at run-time to &0D
*This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
*This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
*This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| &1f (note 1)
|-
| 1
| 5
| Floating point number (note 2)
|}

*#This byte is the BASIC token identifying a floating point number
*#These 5 bytes define the floating point number.
*The space symbol is used as a command seperator
*Variable definitions:
**The variable definition has the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| Token defining variable type
|-
| 2
| 2
| 16-bit Byte offset to variable value within tokenised BASIC program.
|-
| 4
| x
| Variable name
|}

 The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.

**The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
**The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
*String values:
**Each string value is prefixed with &22 token.
**All strings must be enclosed by double quote symbols (&quot). This symbols define the start and end of the string value.
**The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.

*After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

 This table list the BASIC tokens with a &ff prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| ABS
|-
| &01
| ASC
|-
| &02
| ATN
|-
| &03
| CHR$
|-
| &04
| CINT
|-
| &05
| COS
|-
| &06
| CREAL
|-
| &07
| EXP
|-
| &08
| FIX
|-
| &09
| FRE
|-
| &0a
| INKEY
|-
| &0b
| INP
|-
| &0c
| INT
|-
| &0d
| JOY
|-
| &0e
| LEN
|-
| &0f
| LOG
|-
| &10
| LOG10
|-
| &11
| LOWER$
|-
| &12
| PEEK
|-
| &13
| REMAIN
|-
| &14
| SGN
|-
| &15
| SIN
|-
| &16
| SPACE$
|-
| &17
| SQ
|-
| &18
| SQR
|-
| &19
| STR$
|-
| &1a
| TAN
|-
| &1b
| UNT
|-
| &1c
| UPPER$
|-
| &1d
| VAL
|-
|  
| (note 2)
|-
| &40
| EOF
|-
| &41
| ERR
|-
| &42
| HIMEM
|-
| &43
| INKEY$
|-
| &44
| PI
|-
| &45
| RND
|-
| &46
| TIME
|-
| &47
| XPOS
|-
| &48
| YPOS
|-
| &49
| DERR (v1.1)
|-
|  
| (note 3)
|-
| &71
| BIN$
|-
| &72
| DEC$ (v1.1)
|-
| &73
| HEX$
|-
| &74
| INSTR
|-
| &75
| LEFT$
|-
| &76
| MAX
|-
| &77
| MIN
|-
| &78
| POS
|-
| &79
| RIGHT$
|-
| &7a
| ROUND
|-
| &7b
| STRING$
|-
| &7c
| TEST
|-
| &7d
| TESTR
|-
| &7e
| COPYCHR$ (v1.1)
|-
| &7f
| VPOS
|-
|  
| (note 4)
|}

 NOTES:

*These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence: <pre>&FF,&00</pre>
*Codes &1e...&3f inclusive are not used
*Codes &4a...&6f inclusive are not used
*Codes &80...&ff inclusive are not used

*When a BASIC program is in memory, the BASIC ROM can replace "16-bit BASIC program line number" tokens with "16-bit BASIC program line memory address pointer".

When a program is loaded or saved, there will only be "16-bit BASIC program line number" tokens followed by a 16-bit number of the line.

When a program is running, BASIC will replace the "16-bit BASIC program line number" with the "16-bit BASIC program line memory address pointer" token, and replace the 16-bit line number with the memory address of the start of that line.

It does this to avoid having to lookup the address of the line each time.

* When a REM or ' is seen, the characters following it are output directly (i.e. the bytes are not tokenized) until the end of line or a ':' is seen.

* When a BASIC program is listed each line is converted to a string (this includes the line number and the tokens converted to their strings). There is a maximum length for this string of 256 characters. This means that if the BASIC line is LISTed or EDITed, then the line will be displayed incorrectly with missing characters on the end. This is also noticed if you have a "10-liner" program that packs as much BASIC as possible into each line and renumber it so the line number has more digits.

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

 In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form: 1 x 2<exponent> The representation uses 5 bytes and is stored using the following structure:

 

{| border="1"
|-
! Byte
! colspan="8" | 0
! colspan="8" | 1
! colspan="8" | 2
! colspan="8" | 3
! colspan="8" | 4
|-
! Bit
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
|-
| Function
| colspan="8" | (LSB) mantissa (bits 31-24)
| colspan="8" | mantissa (bits 23-16)
| colspan="8" | mantissa (bits 15-8)
| colspan="1" | sign
| colspan="7" | (MSB) mantissa (bits 7-0)
| colspan="8" | exponent
|}

=== Sign ===

The sign is represented by bit 7 of byte 3. The value of the sign bit indicates the sign of the floating point number.

#*If the sign bit is "1", then the number is negative.
#*If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4. It is stored with a bias of 128.

#*128-255 are positive exponents,
#*1-127 are negative exponents.
#*0 means, the number is zero

To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 1 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^127.
A value of 0 just means, that the number is zero (0).

=== BASIC Display of Floating point numbers ===

* Numbers are displayed to 9 decimal places.
* If the number doesn't have a fractional part (e.g. .0) then the fractional part is not displayed.
* Trailing zeros (zero digits after the last digit in the fraction) are not displayed
* The value is rounded in the following way for display:

If the 10th fractional digit is 5 or above, then the number is rounded up.
If the 10th fractional digit is 4 or below, then the number is rounded down.
e.g.
0.1234567891 is displayed as 0.123456789
0.1234567895 is displayed as 0.12345679

=== floating point example in RAM by MaV ===

The initial figure = 43.375.
An example in BASIC:
<pre>
a!=43.375
READY
PRINT a!
43.375
PRINT @a!
374
FOR I=0 TO 4:PRINT HEX$(PEEK(374+I),2);:NEXT I
0000802D86
</pre>
the result for better readability: 
'''00 00 80 2D 86''' 
The first byte contains the least significant bits of the mantissa, and every following byte up to the fourth byte contain the bits following the first in significance and in exactly that order!

That means that you have to turn around the first four bytes if you want to read the mantissa correctly:
2D800000
or
0010.1101.1000.0000.0000.0000.0000.0000
in binary (the stops are inserted for better readability).

Now the highest significant bit here is 0, so the number is positive.
What's more, you need to clear that bit and substitute the implied highest bit (see description in the link), which is always 1 (regardless of the deleted sign bit!!!).
Thus you get:
AD800000
or
1010.1101.1000.0000.0000.0000.0000.0000
in binary.

The mantissa has an implied decimal point before the number. Since the number is 2^32 bits (i.e. 4 bytes) long you have to divide by 2^32 to get the proper decimal representation.

AD800000 (hex) = 2910846976 (dec)

2910846976 / 2^32 = 0.677734375

The mantissa in a decimal representation is: 0.677734375

Now, the last byte contains the exponent: 86 (hex) or 134 (dec). You need to subtract 128 to get the real exponent, the highest bit tells you that the exponent is positive (1) or negative (0). Your exponent is 6.

0.677734375 * 2^6 = 43.375

'''Another example:''' 
PI is represented in memory as: 
'''A2 DA 0F 49 82''' 
The mantissa is 
490FDAA2 (highest significant bit is zero => number is positive)
The exponent is 
82 (=positive mantissa, value=2 thus multiply mantissa with 2^2) 

Delete the sign bit (which is 0 anyway), and then add the implied 1 bit: 
C90FDAA2 (hex) = 3373259426 (dec) = 1100.1001.0000.1111.1101.1010.1010.0010 (bin) 

Calculate the decimal representation of the mantissa: 
3373259426 / 2^32 = 0,7853981633670628070831298828125 

Then add the exponent (82h - 80h = 2 thus 2^2) 
0,7853981633670628070831298828125 * 2^2 = 3,14159265346825122833251953125 

Voilà! The internal representation of the number PI on the CPC is: 3,14159265346825122833251953125 

If you compare to a (more) correct representation of PI, you'll see that the CPC is correct up to the 9th decimal place: 

CPC: 
3.14159265346825122833251953125 
more correctly: 
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986...

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts. The biggest figure which can be stored correctly in RAM by a variable is 2^32-1 = 4294967295.

#A real variable is defined with a "!" character postfix.

e.g.
<pre>a! = 3.141592654
</pre>
#A real number uses 5 bytes of memory as storage. The format is described above.
#The address of a real variable can be found in BASIC by:
<pre>PRINT @a!
</pre>

Where "a" should be replaced with the name of the variable.

 

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

 NOTES:

#A integer variable is defined with a "%" character postfix.

e.g.
<pre>a% = 3
</pre>
#A integer variable has a range of -32768 to 32767
#A integer variable always uses two bytes of memory as storage with the following format:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 2
| Integer number
|}

#The address of the integer variable can be found in BASIC by:
<pre>PRINT @a%
</pre>

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

 NOTES:

*A string variable is defined in BASIC with a "$" character postfix.

e.g.
<pre>a$ = "hello"
</pre>
*A string variable is described internally by a "string descriptor block" which has the following structure:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 1
| Length of string in bytes/characters
|-
| 1
| 2
| Location of start of string
|}

*The address of the "string descriptor block" for the string variable can be found in BASIC by typing:
<pre>PRINT @a$
</pre>

replacing "a$" with the name of the string variable.

*A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
*A string variable can contain any ASCII character code in the range 0-255.
*A string variable can store a minimum of 0 characters and a maximum of 255 characters.
*The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Technical information about Locomotive BASIC

2025-08-24T10:23:24Z

Arnoldemu: /* BASIC string variables */

[[Category:Cpctech.org]]

'''''This article originally came from Kevin Thackers' archive at [http://www.cpctech.org.uk http://www.cpctech.org.uk].'''''

= Technical information about Locomotive BASIC =

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== BASIC v1.0 only ==

There is a region of memory between AC00-AC1B which is filled with RET instructions. The BASIC ROM calls the following locations:
AC01,AC04,AC07,AC0A,AC0D,AC10,AC13,AC16,AC19

It almost looks like these were used for debugging the ROM but were left in.

They can be used to implement new BASIC commands.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR". A binary function is accessed through BASIC using the "CALL" command.

Both RSX and CALL commands work (are!) similar from the BASIC command line and invoke machine code - the only difference is: with the help of a RSX command you don't need to know the exact access address. You can pass up to 32 parameters with a CALL or RSX command. Possible parameters could be integer, floating points and strings. Just store the parameter into a variable:
Passing for integer:
<pre>
CALL &4000,32,34,&5E,&x10101010
|RSX-command,32,34,&5E,&x10101010
</pre>
Passing for floating points
<pre>
@a!=43.375
CALL or |RSX-command,@a!
</pre>

 Passing a string parameter:
 BASIC v1.0
<pre>a$="A":|DRIVE,@a$
</pre>
BASIC v1.1:
<pre>|DRIVE,"A"
</pre>
or
<pre>
b$="test"
CALL or |RSX-command,@b$
</pre>

The parameters will be stored inside the range of Stack:
<pre>
A=n -------> MSB PARAM1
LSB PARAM1
MSB PARAM2
LSB PARAM2
...
...
...
MSB PARAMn
IX+0 ------> LSB PARAMn
</pre>
with the help of that assembly code is it possible to find the parameters:
<pre>
ROUT1: CP x ;test register A if "x" parameters were given, e.g. x = 2
RET NZ ; if not exactly x parameters then do not execute RSX.
LD L,(IX+0)
LD H,(IX+1) ; HL = value of last parameter
LD E,(IX+2)
LD D,(IX+3) ; DE = value of next to last parameter
...
</pre>
A register holds the number of parameters. IX points to each parameter. IX+0/IX+1 is the last parameter. This happens because each parameter in order is pushed onto the stack and IX then points to the last parameter pushed. Each parameter is a 16-bit value.

If a parameter is a string, then IX holds the address of the string descriptor which point to a 3 byte block. The first byte of the string descriptor is the length. The next 2 bytes are an address that point to the string in memory.

With the help of the variable container "@" it is also possible to get a result from an invoked mc-code back to basic.
In this case the parameter contains the address of the integer, floating point or string. You can modify these to give the result.
BASIC allocates the strings, so when you modify a string, do not write more characters than the original string.

Hint: the first two bytes at the end of stack shows the internal return address from BASIC interpreter where it was executed.

== Additional keywords and variables in BASIC v1.1 ==

#BASIC v1.1 has the following additional keywords:
#*COPYCHR$
#*CURSOR
#*DEC$
#*FILL
#*FRAME
#*GRAPHICS
#*MASK
#BASIC v1.1 has the following additional predefined variables:
#*DERR

 

== BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

There are some rules for assigning names for variables:
: - it is not allowed to define a variable starting with a figure (the system expect then programming mode and interpret it as a program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - different sign e.g.: a slash (doesn't depend which direction), a 'minus' sign, a 'and' sign can't be used in a variable names
: - after a dollar sign (for defining string variables) it is not allowed to use further signs
: - different defining functions together are not allowed (e.g. use '%' together with '$')

: - you can use 40 characters for a variable name
: - use ! for defining a REAL value variable (like the function DEFREAL but only for the assigned variable) > It's also possible to omit the exlamation mark because it's the default system declaration after powering on then CPC.
: - use % for defining a INTEGER value variable (like the function DEFINT but only for the assigned variable)
: - use $ for defining a STRING variable (like the function DEFSTR but only for the assigned variable)
: - Minimum line number is 1. Maximum line number is 65535.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

 

== Speeding up BASIC programs ==

To speed up BASIC programs following rules could help:
: - Avoid loops or a branching program structure if possible. Internally the operating system searches for the right line number always from the beginning of the program 'listing'. Often recurring subroutines (if necessary) should be at the beginning of RAM to speed up things.
: - Avoid the index variable after the <code>NEXT</code> command/statement (although it isn't a good program style)
: - Avoid spaces inside program code or remarks
: - Put lots of statements as possible in ONE line
: - Use variables instead of constants. A constant has always to be converted in a binary/digital format. A variable is already converted.
: - Dimensioning at the beginning of the program
: - Dimensioning your variables & pre-calculate
: - Avoid AND/OR/XOR in IF-THEN statements. It's faster to write IF ... THEN (statement 1).. IF ... THEN (statement 2).
: - Minimise string/char manipulation as this often requires memory allocations. (e.g. joining strings with +, use of MID$, LEFT$, RIGHT$, SPACE$)

== Minimizing memory usage ==

To minimize memory usage in BASIC here are some things to consider.

The size of the tokenized program:
: - Difficult to measure without looking at the data in memory.
: - Use short variable names. The names are stored in the tokenized BASIC program as-is.
: - Minimize the number of variables. The names are stored in the tokenized BASIC program everywhere they are used.
: - Use as few lines as possible. It's a small saving of about 5 bytes per line.
: - Consider using numbers vs strings and potentially 8-bit or 16-bit values.

Minimising memory usage when the program is running:
: - Minimize string operations. (e.g. A$=SPACE$(30)+CHR$(28) in memory this first allocates a string of length 30 containing spaces, then it allocates a new string of length 31 with spaces and char 28 at the end and assigns it to A$. In this line at least 30 bytes have been wasted. So consider if you need strings or perhaps if possible pre-define them).

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences. Each line of the BASIC program has the form:

 

{| border="1"
|-
! Offset
! Size
! Description
|-
| 0
| 2
| Length of line data in bytes (note 1)
|-
| 2
| 2
| 16-bit decimal integer line number (note 2)
|-
| 4
| n
| BASIC line encoded into tokens (note 3)
|-
| n+1
| 1
| "0" the end of line marker (note 4)
|}

 Notes:

#This 16-bit value has two functions: if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data, otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
#This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
#This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
#This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| end of tokenised line marker
|-
| &01
| ":" statement seperator
|-
| &02
| integer variable definition (defined with "%" suffix)
|-
| &03
| string variable definition (defined with "$" suffix)
|-
| &04
| floating point variable definition (defined with "!" suffix)
|-
| &05
| var?
|-
| &06
| var?
|-
| &07
| var?
|-
| &08
| var?
|-
| &09
| var?
|-
| &0a
| var?
|-
| &0b
| variable definition (no suffix)
|-
| &0c
| variable definition (no suffix)
|-
| &0d
| variable definition (no suffix)
|-
| &0e
| number constant "0"
|-
| &0f
| number constant "1"
|-
| &10
| number constant "2"
|-
| &11
| number constant "3"
|-
| &12
| number constant "4"
|-
| &13
| number constant "5"
|-
| &14
| number constant "6"
|-
| &15
| number constant "7"
|-
| &16
| number constant "8"
|-
| &17
| number constant "9"
|-
| &18
| number constant "10"
|-
| &19
| 8-bit integer decimal value
|-
| &1a
| 16-bit integer decimal value
|-
| &1b
| 16-bit integer binary value (with "&X" prefix)
|-
| &1c
| 16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
| &1d
| 16-bit BASIC program line memory address pointer (see notes)
|-
| &1e
| 16-bit integer BASIC line number
|-
| &1f
| floating point value
|-
| &20
| " " (space) symbol
|-
| &21
| ASCII "!" symbol
|-
| &22
| quoted string value
|-
| &23-7b
| ASCII printable symbols
|-
| &7c
| "|" symbol; prefix for RSX commands
|-
| &80
| AFTER
|-
| &81
| AUTO
|-
| &82
| BORDER
|-
| &83
| CALL
|-
| &84
| CAT
|-
| &85
| CHAIN
|-
| &86
| CLEAR
|-
| &87
| CLG
|-
| &88
| CLOSEIN
|-
| &89
| CLOSEOUT
|-
| &8a
| CLS
|-
| &8b
| CONT
|-
| &8c
| DATA
|-
| &8d
| DEF
|-
| &8e
| DEFINT
|-
| &8f
| DEFREAL
|-
| &90
| DEFSTR
|-
| &91
| DEG
|-
| &92
| DELETE
|-
| &93
| DIM
|-
| &94
| DRAW
|-
| &95
| DRAWR
|-
| &96
| EDIT
|-
| &97
| ELSE
|-
| &98
| END
|-
| &99
| ENT
|-
| &9a
| ENV
|-
| &9b
| ERASE
|-
| &9c
| ERROR
|-
| &9d
| EVERY
|-
| &9e
| FOR
|-
| &9f
| GOSUB, GO SUB
|-
| &a0
| GOTO, GO TO
|-
| &a1
| IF
|-
| &a2
| INK
|-
| &a3
| INPUT
|-
| &a4
| KEY
|-
| &a5
| LET
|-
| &a6
| LINE
|-
| &a7
| LIST
|-
| &a8
| LOAD
|-
| &a9
| LOCATE
|-
| &aa
| MEMORY
|-
| &ab
| MERGE
|-
| &ac
| MID$
|-
| &ad
| MODE
|-
| &ae
| MOVE
|-
| &af
| MOVER
|-
| &b0
| NEXT
|-
| &b1
| NEW
|-
| &b2
| ON
|-
| &b3
| ON BREAK
|-
| &b4
| ON ERROR GOTO, ON ERROR GO TO
|-
| &b5
| ON SQ
|-
| &b6
| OPENIN
|-
| &b7
| OPENOUT
|-
| &b8
| ORIGIN
|-
| &b9
| OUT
|-
| &ba
| PAPER
|-
| &bb
| PEN
|-
| &bc
| PLOT
|-
| &bd
| PLOTR
|-
| &be
| POKE
|-
| &bf
| PRINT
|-
| &c0
| "'" symbol (same function as REM keyword)
|-
| &c1
| RAD
|-
| &c2
| RANDOMIZE
|-
| &c3
| READ
|-
| &c4
| RELEASE
|-
| &c5
| REM
|-
| &c6
| RENUM
|-
| &c7
| RESTORE
|-
| &c8
| RESUME
|-
| &c9
| RETURN
|-
| &ca
| RUN
|-
| &cb
| SAVE
|-
| &cc
| SOUND
|-
| &cd
| SPEED
|-
| &ce
| STOP
|-
| &cf
| SYMBOL
|-
| &d0
| TAG
|-
| &d1
| TAGOFF
|-
| &d2
| TROFF
|-
| &d3
| TRON
|-
| &d4
| WAIT
|-
| &d5
| WEND
|-
| &d6
| WHILE
|-
| &d7
| WIDTH
|-
| &d8
| WINDOW
|-
| &d9
| WRITE
|-
| &da
| ZONE
|-
| &db
| DI
|-
| &dc
| EI
|-
| &dd
| FILL (v1.1)
|-
| &de
| GRAPHICS (v1.1)
|-
| &df
| MASK (v1.1)
|-
| &e0
| FRAME (v1.1)
|-
| &e1
| CURSOR (v1.1)
|-
| &e2
| (note 2)
|-
| &e3
| ERL
|-
| &e4
| FN
|-
| &e5
| SPC
|-
| &e6
| STEP
|-
| &e7
| SWAP
|-
| &e8
| (note 2)
|-
| &e9
| (note 2)
|-
| &ea
| TAB
|-
| &eb
| THEN
|-
| &ec
| TO
|-
| &ed
| USING
|-
| &ee
| > (greater than)
|-
| &ef
| = (equal)
|-
| &f0
| &gt=, > =, => (greater or equal)
|-
| &f1
| < (less than)
|-
| &f2
| <&gt, < > (not equal)
|-
| &f3
| =<, <=, < = (less than or equal)
|-
| &f4
| + (addition)
|-
| &f5
| - (subtraction or unary minus)
|-
| &f6
| * (multiplication)
|-
| &f7
| / (division)
|-
| &f8
| ^ (x to the power of y)
|-
| &f9
| \ (integer division)
|-
| &fa
| AND
|-
| &fb
| MOD
|-
| &fc
| OR
|-
| &fd
| XOR
|-
| &fe
| NOT
|-
| &ff
| (prefix for additional keywords)
|}

 Notes:

*The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
*&e2,&e8 and &e9 are not used
*&7c ("|") is a character prefix used to identify an RSX command. e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| "|" character prefix
|-
| 1
| 1
| 8-bit byte offset to tokens following RSX name.
|-
| 2
| x
| RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
|}

*This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &1a,&2d,&00 represents the integer number "&002d"="45".
*This token (&0B) is changed at run-time to &0D
*This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
*This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
*This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| &1f (note 1)
|-
| 1
| 5
| Floating point number (note 2)
|}

*#This byte is the BASIC token identifying a floating point number
*#These 5 bytes define the floating point number.
*The space symbol is used as a command seperator
*Variable definitions:
**The variable definition has the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| Token defining variable type
|-
| 2
| 2
| 16-bit Byte offset to variable value within tokenised BASIC program.
|-
| 4
| x
| Variable name
|}

 The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.

**The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
**The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
*String values:
**Each string value is prefixed with &22 token.
**All strings must be enclosed by double quote symbols (&quot). This symbols define the start and end of the string value.
**The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.

*After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

 This table list the BASIC tokens with a &ff prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| ABS
|-
| &01
| ASC
|-
| &02
| ATN
|-
| &03
| CHR$
|-
| &04
| CINT
|-
| &05
| COS
|-
| &06
| CREAL
|-
| &07
| EXP
|-
| &08
| FIX
|-
| &09
| FRE
|-
| &0a
| INKEY
|-
| &0b
| INP
|-
| &0c
| INT
|-
| &0d
| JOY
|-
| &0e
| LEN
|-
| &0f
| LOG
|-
| &10
| LOG10
|-
| &11
| LOWER$
|-
| &12
| PEEK
|-
| &13
| REMAIN
|-
| &14
| SGN
|-
| &15
| SIN
|-
| &16
| SPACE$
|-
| &17
| SQ
|-
| &18
| SQR
|-
| &19
| STR$
|-
| &1a
| TAN
|-
| &1b
| UNT
|-
| &1c
| UPPER$
|-
| &1d
| VAL
|-
|  
| (note 2)
|-
| &40
| EOF
|-
| &41
| ERR
|-
| &42
| HIMEM
|-
| &43
| INKEY$
|-
| &44
| PI
|-
| &45
| RND
|-
| &46
| TIME
|-
| &47
| XPOS
|-
| &48
| YPOS
|-
| &49
| DERR (v1.1)
|-
|  
| (note 3)
|-
| &71
| BIN$
|-
| &72
| DEC$ (v1.1)
|-
| &73
| HEX$
|-
| &74
| INSTR
|-
| &75
| LEFT$
|-
| &76
| MAX
|-
| &77
| MIN
|-
| &78
| POS
|-
| &79
| RIGHT$
|-
| &7a
| ROUND
|-
| &7b
| STRING$
|-
| &7c
| TEST
|-
| &7d
| TESTR
|-
| &7e
| COPYCHR$ (v1.1)
|-
| &7f
| VPOS
|-
|  
| (note 4)
|}

 NOTES:

*These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence: <pre>&FF,&00</pre>
*Codes &1e...&3f inclusive are not used
*Codes &4a...&6f inclusive are not used
*Codes &80...&ff inclusive are not used

*When a BASIC program is in memory, the BASIC ROM can replace "16-bit BASIC program line number" tokens with "16-bit BASIC program line memory address pointer".

When a program is loaded or saved, there will only be "16-bit BASIC program line number" tokens followed by a 16-bit number of the line.

When a program is running, BASIC will replace the "16-bit BASIC program line number" with the "16-bit BASIC program line memory address pointer" token, and replace the 16-bit line number with the memory address of the start of that line.

It does this to avoid having to lookup the address of the line each time.

* When a REM or ' is seen, the characters following it are output directly (i.e. the bytes are not tokenized) until the end of line or a ':' is seen.

* When a BASIC program is listed each line is converted to a string (this includes the line number and the tokens converted to their strings). There is a maximum length for this string of 256 characters. This means that if the BASIC line is LISTed or EDITed, then the line will be displayed incorrectly with missing characters on the end. This is also noticed if you have a "10-liner" program that packs as much BASIC as possible into each line and renumber it so the line number has more digits.

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

 In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form: 1 x 2<exponent> The representation uses 5 bytes and is stored using the following structure:

 

{| border="1"
|-
! Byte
! colspan="8" | 0
! colspan="8" | 1
! colspan="8" | 2
! colspan="8" | 3
! colspan="8" | 4
|-
! Bit
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
|-
| Function
| colspan="8" | (LSB) mantissa (bits 31-24)
| colspan="8" | mantissa (bits 23-16)
| colspan="8" | mantissa (bits 15-8)
| colspan="1" | sign
| colspan="7" | (MSB) mantissa (bits 7-0)
| colspan="8" | exponent
|}

=== Sign ===

The sign is represented by bit 7 of byte 3. The value of the sign bit indicates the sign of the floating point number.

#*If the sign bit is "1", then the number is negative.
#*If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4. It is stored with a bias of 128.

#*128-255 are positive exponents,
#*1-127 are negative exponents.
#*0 means, the number is zero

To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 1 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^127.
A value of 0 just means, that the number is zero (0).

=== BASIC Display of Floating point numbers ===

* Numbers are displayed to 9 decimal places.
* If the number doesn't have a fractional part (e.g. .0) then the fractional part is not displayed.
* Trailing zeros (zero digits after the last digit in the fraction) are not displayed
* The value is rounded in the following way for display:

If the 10th fractional digit is 5 or above, then the number is rounded up.
If the 10th fractional digit is 4 or below, then the number is rounded down.
e.g.
0.1234567891 is displayed as 0.123456789
0.1234567895 is displayed as 0.12345679

=== floating point example in RAM by MaV ===

The initial figure = 43.375.
An example in BASIC:
<pre>
a!=43.375
READY
PRINT a!
43.375
PRINT @a!
374
FOR I=0 TO 4:PRINT HEX$(PEEK(374+I),2);:NEXT I
0000802D86
</pre>
the result for better readability: 
'''00 00 80 2D 86''' 
The first byte contains the least significant bits of the mantissa, and every following byte up to the fourth byte contain the bits following the first in significance and in exactly that order!

That means that you have to turn around the first four bytes if you want to read the mantissa correctly:
2D800000
or
0010.1101.1000.0000.0000.0000.0000.0000
in binary (the stops are inserted for better readability).

Now the highest significant bit here is 0, so the number is positive.
What's more, you need to clear that bit and substitute the implied highest bit (see description in the link), which is always 1 (regardless of the deleted sign bit!!!).
Thus you get:
AD800000
or
1010.1101.1000.0000.0000.0000.0000.0000
in binary.

The mantissa has an implied decimal point before the number. Since the number is 2^32 bits (i.e. 4 bytes) long you have to divide by 2^32 to get the proper decimal representation.

AD800000 (hex) = 2910846976 (dec)

2910846976 / 2^32 = 0.677734375

The mantissa in a decimal representation is: 0.677734375

Now, the last byte contains the exponent: 86 (hex) or 134 (dec). You need to subtract 128 to get the real exponent, the highest bit tells you that the exponent is positive (1) or negative (0). Your exponent is 6.

0.677734375 * 2^6 = 43.375

'''Another example:''' 
PI is represented in memory as: 
'''A2 DA 0F 49 82''' 
The mantissa is 
490FDAA2 (highest significant bit is zero => number is positive)
The exponent is 
82 (=positive mantissa, value=2 thus multiply mantissa with 2^2) 

Delete the sign bit (which is 0 anyway), and then add the implied 1 bit: 
C90FDAA2 (hex) = 3373259426 (dec) = 1100.1001.0000.1111.1101.1010.1010.0010 (bin) 

Calculate the decimal representation of the mantissa: 
3373259426 / 2^32 = 0,7853981633670628070831298828125 

Then add the exponent (82h - 80h = 2 thus 2^2) 
0,7853981633670628070831298828125 * 2^2 = 3,14159265346825122833251953125 

Voilà! The internal representation of the number PI on the CPC is: 3,14159265346825122833251953125 

If you compare to a (more) correct representation of PI, you'll see that the CPC is correct up to the 9th decimal place: 

CPC: 
3.14159265346825122833251953125 
more correctly: 
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986...

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts. The biggest figure which can be stored correctly in RAM by a variable is 2^32-1 = 4294967295.

#A real variable is defined with a "!" character postfix.

e.g.
<pre>a! = 3.141592654
</pre>
#A real number uses 5 bytes of memory as storage. The format is described above.
#The address of a real variable can be found in BASIC by:
<pre>PRINT @a!
</pre>

Where "a" should be replaced with the name of the variable.

 

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

 NOTES:

#A integer variable is defined with a "%" character postfix.

e.g.
<pre>a% = 3
</pre>
#A integer variable has a range of -32768 to 32767
#A integer variable always uses two bytes of memory as storage with the following format:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 2
| Integer number
|}

#The address of the integer variable can be found in BASIC by:
<pre>PRINT @a%
</pre>

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

 NOTES:

*A string variable is defined in BASIC with a "$" character postfix.

e.g.
<pre>a$ = "hello"
</pre>
*A string variable is described internally by a "string descriptor block" which has the following structure:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 1
| Length of string in bytes/characters
|-
| 1
| 2
| Location of start of string
|}

*The address of the "string descriptor block" for the string variable can be found in BASIC by typing: <pre>PRINT @a$
</pre>

replacing "a$" with the name of the string variable.

*A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
*A string variable can contain any ASCII character code in the range 0-255.
*A string variable can store a minimum of 0 characters and a maximum of 255 characters.
*The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Technical information about Locomotive BASIC

2025-08-24T10:23:12Z

Arnoldemu: /* BASIC string variables */

[[Category:Cpctech.org]]

'''''This article originally came from Kevin Thackers' archive at [http://www.cpctech.org.uk http://www.cpctech.org.uk].'''''

= Technical information about Locomotive BASIC =

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== BASIC v1.0 only ==

There is a region of memory between AC00-AC1B which is filled with RET instructions. The BASIC ROM calls the following locations:
AC01,AC04,AC07,AC0A,AC0D,AC10,AC13,AC16,AC19

It almost looks like these were used for debugging the ROM but were left in.

They can be used to implement new BASIC commands.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR". A binary function is accessed through BASIC using the "CALL" command.

Both RSX and CALL commands work (are!) similar from the BASIC command line and invoke machine code - the only difference is: with the help of a RSX command you don't need to know the exact access address. You can pass up to 32 parameters with a CALL or RSX command. Possible parameters could be integer, floating points and strings. Just store the parameter into a variable:
Passing for integer:
<pre>
CALL &4000,32,34,&5E,&x10101010
|RSX-command,32,34,&5E,&x10101010
</pre>
Passing for floating points
<pre>
@a!=43.375
CALL or |RSX-command,@a!
</pre>

 Passing a string parameter:
 BASIC v1.0
<pre>a$="A":|DRIVE,@a$
</pre>
BASIC v1.1:
<pre>|DRIVE,"A"
</pre>
or
<pre>
b$="test"
CALL or |RSX-command,@b$
</pre>

The parameters will be stored inside the range of Stack:
<pre>
A=n -------> MSB PARAM1
LSB PARAM1
MSB PARAM2
LSB PARAM2
...
...
...
MSB PARAMn
IX+0 ------> LSB PARAMn
</pre>
with the help of that assembly code is it possible to find the parameters:
<pre>
ROUT1: CP x ;test register A if "x" parameters were given, e.g. x = 2
RET NZ ; if not exactly x parameters then do not execute RSX.
LD L,(IX+0)
LD H,(IX+1) ; HL = value of last parameter
LD E,(IX+2)
LD D,(IX+3) ; DE = value of next to last parameter
...
</pre>
A register holds the number of parameters. IX points to each parameter. IX+0/IX+1 is the last parameter. This happens because each parameter in order is pushed onto the stack and IX then points to the last parameter pushed. Each parameter is a 16-bit value.

If a parameter is a string, then IX holds the address of the string descriptor which point to a 3 byte block. The first byte of the string descriptor is the length. The next 2 bytes are an address that point to the string in memory.

With the help of the variable container "@" it is also possible to get a result from an invoked mc-code back to basic.
In this case the parameter contains the address of the integer, floating point or string. You can modify these to give the result.
BASIC allocates the strings, so when you modify a string, do not write more characters than the original string.

Hint: the first two bytes at the end of stack shows the internal return address from BASIC interpreter where it was executed.

== Additional keywords and variables in BASIC v1.1 ==

#BASIC v1.1 has the following additional keywords:
#*COPYCHR$
#*CURSOR
#*DEC$
#*FILL
#*FRAME
#*GRAPHICS
#*MASK
#BASIC v1.1 has the following additional predefined variables:
#*DERR

 

== BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

There are some rules for assigning names for variables:
: - it is not allowed to define a variable starting with a figure (the system expect then programming mode and interpret it as a program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - different sign e.g.: a slash (doesn't depend which direction), a 'minus' sign, a 'and' sign can't be used in a variable names
: - after a dollar sign (for defining string variables) it is not allowed to use further signs
: - different defining functions together are not allowed (e.g. use '%' together with '$')

: - you can use 40 characters for a variable name
: - use ! for defining a REAL value variable (like the function DEFREAL but only for the assigned variable) > It's also possible to omit the exlamation mark because it's the default system declaration after powering on then CPC.
: - use % for defining a INTEGER value variable (like the function DEFINT but only for the assigned variable)
: - use $ for defining a STRING variable (like the function DEFSTR but only for the assigned variable)
: - Minimum line number is 1. Maximum line number is 65535.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

 

== Speeding up BASIC programs ==

To speed up BASIC programs following rules could help:
: - Avoid loops or a branching program structure if possible. Internally the operating system searches for the right line number always from the beginning of the program 'listing'. Often recurring subroutines (if necessary) should be at the beginning of RAM to speed up things.
: - Avoid the index variable after the <code>NEXT</code> command/statement (although it isn't a good program style)
: - Avoid spaces inside program code or remarks
: - Put lots of statements as possible in ONE line
: - Use variables instead of constants. A constant has always to be converted in a binary/digital format. A variable is already converted.
: - Dimensioning at the beginning of the program
: - Dimensioning your variables & pre-calculate
: - Avoid AND/OR/XOR in IF-THEN statements. It's faster to write IF ... THEN (statement 1).. IF ... THEN (statement 2).
: - Minimise string/char manipulation as this often requires memory allocations. (e.g. joining strings with +, use of MID$, LEFT$, RIGHT$, SPACE$)

== Minimizing memory usage ==

To minimize memory usage in BASIC here are some things to consider.

The size of the tokenized program:
: - Difficult to measure without looking at the data in memory.
: - Use short variable names. The names are stored in the tokenized BASIC program as-is.
: - Minimize the number of variables. The names are stored in the tokenized BASIC program everywhere they are used.
: - Use as few lines as possible. It's a small saving of about 5 bytes per line.
: - Consider using numbers vs strings and potentially 8-bit or 16-bit values.

Minimising memory usage when the program is running:
: - Minimize string operations. (e.g. A$=SPACE$(30)+CHR$(28) in memory this first allocates a string of length 30 containing spaces, then it allocates a new string of length 31 with spaces and char 28 at the end and assigns it to A$. In this line at least 30 bytes have been wasted. So consider if you need strings or perhaps if possible pre-define them).

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences. Each line of the BASIC program has the form:

 

{| border="1"
|-
! Offset
! Size
! Description
|-
| 0
| 2
| Length of line data in bytes (note 1)
|-
| 2
| 2
| 16-bit decimal integer line number (note 2)
|-
| 4
| n
| BASIC line encoded into tokens (note 3)
|-
| n+1
| 1
| "0" the end of line marker (note 4)
|}

 Notes:

#This 16-bit value has two functions: if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data, otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
#This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
#This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
#This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| end of tokenised line marker
|-
| &01
| ":" statement seperator
|-
| &02
| integer variable definition (defined with "%" suffix)
|-
| &03
| string variable definition (defined with "$" suffix)
|-
| &04
| floating point variable definition (defined with "!" suffix)
|-
| &05
| var?
|-
| &06
| var?
|-
| &07
| var?
|-
| &08
| var?
|-
| &09
| var?
|-
| &0a
| var?
|-
| &0b
| variable definition (no suffix)
|-
| &0c
| variable definition (no suffix)
|-
| &0d
| variable definition (no suffix)
|-
| &0e
| number constant "0"
|-
| &0f
| number constant "1"
|-
| &10
| number constant "2"
|-
| &11
| number constant "3"
|-
| &12
| number constant "4"
|-
| &13
| number constant "5"
|-
| &14
| number constant "6"
|-
| &15
| number constant "7"
|-
| &16
| number constant "8"
|-
| &17
| number constant "9"
|-
| &18
| number constant "10"
|-
| &19
| 8-bit integer decimal value
|-
| &1a
| 16-bit integer decimal value
|-
| &1b
| 16-bit integer binary value (with "&X" prefix)
|-
| &1c
| 16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
| &1d
| 16-bit BASIC program line memory address pointer (see notes)
|-
| &1e
| 16-bit integer BASIC line number
|-
| &1f
| floating point value
|-
| &20
| " " (space) symbol
|-
| &21
| ASCII "!" symbol
|-
| &22
| quoted string value
|-
| &23-7b
| ASCII printable symbols
|-
| &7c
| "|" symbol; prefix for RSX commands
|-
| &80
| AFTER
|-
| &81
| AUTO
|-
| &82
| BORDER
|-
| &83
| CALL
|-
| &84
| CAT
|-
| &85
| CHAIN
|-
| &86
| CLEAR
|-
| &87
| CLG
|-
| &88
| CLOSEIN
|-
| &89
| CLOSEOUT
|-
| &8a
| CLS
|-
| &8b
| CONT
|-
| &8c
| DATA
|-
| &8d
| DEF
|-
| &8e
| DEFINT
|-
| &8f
| DEFREAL
|-
| &90
| DEFSTR
|-
| &91
| DEG
|-
| &92
| DELETE
|-
| &93
| DIM
|-
| &94
| DRAW
|-
| &95
| DRAWR
|-
| &96
| EDIT
|-
| &97
| ELSE
|-
| &98
| END
|-
| &99
| ENT
|-
| &9a
| ENV
|-
| &9b
| ERASE
|-
| &9c
| ERROR
|-
| &9d
| EVERY
|-
| &9e
| FOR
|-
| &9f
| GOSUB, GO SUB
|-
| &a0
| GOTO, GO TO
|-
| &a1
| IF
|-
| &a2
| INK
|-
| &a3
| INPUT
|-
| &a4
| KEY
|-
| &a5
| LET
|-
| &a6
| LINE
|-
| &a7
| LIST
|-
| &a8
| LOAD
|-
| &a9
| LOCATE
|-
| &aa
| MEMORY
|-
| &ab
| MERGE
|-
| &ac
| MID$
|-
| &ad
| MODE
|-
| &ae
| MOVE
|-
| &af
| MOVER
|-
| &b0
| NEXT
|-
| &b1
| NEW
|-
| &b2
| ON
|-
| &b3
| ON BREAK
|-
| &b4
| ON ERROR GOTO, ON ERROR GO TO
|-
| &b5
| ON SQ
|-
| &b6
| OPENIN
|-
| &b7
| OPENOUT
|-
| &b8
| ORIGIN
|-
| &b9
| OUT
|-
| &ba
| PAPER
|-
| &bb
| PEN
|-
| &bc
| PLOT
|-
| &bd
| PLOTR
|-
| &be
| POKE
|-
| &bf
| PRINT
|-
| &c0
| "'" symbol (same function as REM keyword)
|-
| &c1
| RAD
|-
| &c2
| RANDOMIZE
|-
| &c3
| READ
|-
| &c4
| RELEASE
|-
| &c5
| REM
|-
| &c6
| RENUM
|-
| &c7
| RESTORE
|-
| &c8
| RESUME
|-
| &c9
| RETURN
|-
| &ca
| RUN
|-
| &cb
| SAVE
|-
| &cc
| SOUND
|-
| &cd
| SPEED
|-
| &ce
| STOP
|-
| &cf
| SYMBOL
|-
| &d0
| TAG
|-
| &d1
| TAGOFF
|-
| &d2
| TROFF
|-
| &d3
| TRON
|-
| &d4
| WAIT
|-
| &d5
| WEND
|-
| &d6
| WHILE
|-
| &d7
| WIDTH
|-
| &d8
| WINDOW
|-
| &d9
| WRITE
|-
| &da
| ZONE
|-
| &db
| DI
|-
| &dc
| EI
|-
| &dd
| FILL (v1.1)
|-
| &de
| GRAPHICS (v1.1)
|-
| &df
| MASK (v1.1)
|-
| &e0
| FRAME (v1.1)
|-
| &e1
| CURSOR (v1.1)
|-
| &e2
| (note 2)
|-
| &e3
| ERL
|-
| &e4
| FN
|-
| &e5
| SPC
|-
| &e6
| STEP
|-
| &e7
| SWAP
|-
| &e8
| (note 2)
|-
| &e9
| (note 2)
|-
| &ea
| TAB
|-
| &eb
| THEN
|-
| &ec
| TO
|-
| &ed
| USING
|-
| &ee
| > (greater than)
|-
| &ef
| = (equal)
|-
| &f0
| &gt=, > =, => (greater or equal)
|-
| &f1
| < (less than)
|-
| &f2
| <&gt, < > (not equal)
|-
| &f3
| =<, <=, < = (less than or equal)
|-
| &f4
| + (addition)
|-
| &f5
| - (subtraction or unary minus)
|-
| &f6
| * (multiplication)
|-
| &f7
| / (division)
|-
| &f8
| ^ (x to the power of y)
|-
| &f9
| \ (integer division)
|-
| &fa
| AND
|-
| &fb
| MOD
|-
| &fc
| OR
|-
| &fd
| XOR
|-
| &fe
| NOT
|-
| &ff
| (prefix for additional keywords)
|}

 Notes:

*The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
*&e2,&e8 and &e9 are not used
*&7c ("|") is a character prefix used to identify an RSX command. e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| "|" character prefix
|-
| 1
| 1
| 8-bit byte offset to tokens following RSX name.
|-
| 2
| x
| RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
|}

*This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &1a,&2d,&00 represents the integer number "&002d"="45".
*This token (&0B) is changed at run-time to &0D
*This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
*This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
*This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| &1f (note 1)
|-
| 1
| 5
| Floating point number (note 2)
|}

*#This byte is the BASIC token identifying a floating point number
*#These 5 bytes define the floating point number.
*The space symbol is used as a command seperator
*Variable definitions:
**The variable definition has the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| Token defining variable type
|-
| 2
| 2
| 16-bit Byte offset to variable value within tokenised BASIC program.
|-
| 4
| x
| Variable name
|}

 The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.

**The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
**The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
*String values:
**Each string value is prefixed with &22 token.
**All strings must be enclosed by double quote symbols (&quot). This symbols define the start and end of the string value.
**The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.

*After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

 This table list the BASIC tokens with a &ff prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| ABS
|-
| &01
| ASC
|-
| &02
| ATN
|-
| &03
| CHR$
|-
| &04
| CINT
|-
| &05
| COS
|-
| &06
| CREAL
|-
| &07
| EXP
|-
| &08
| FIX
|-
| &09
| FRE
|-
| &0a
| INKEY
|-
| &0b
| INP
|-
| &0c
| INT
|-
| &0d
| JOY
|-
| &0e
| LEN
|-
| &0f
| LOG
|-
| &10
| LOG10
|-
| &11
| LOWER$
|-
| &12
| PEEK
|-
| &13
| REMAIN
|-
| &14
| SGN
|-
| &15
| SIN
|-
| &16
| SPACE$
|-
| &17
| SQ
|-
| &18
| SQR
|-
| &19
| STR$
|-
| &1a
| TAN
|-
| &1b
| UNT
|-
| &1c
| UPPER$
|-
| &1d
| VAL
|-
|  
| (note 2)
|-
| &40
| EOF
|-
| &41
| ERR
|-
| &42
| HIMEM
|-
| &43
| INKEY$
|-
| &44
| PI
|-
| &45
| RND
|-
| &46
| TIME
|-
| &47
| XPOS
|-
| &48
| YPOS
|-
| &49
| DERR (v1.1)
|-
|  
| (note 3)
|-
| &71
| BIN$
|-
| &72
| DEC$ (v1.1)
|-
| &73
| HEX$
|-
| &74
| INSTR
|-
| &75
| LEFT$
|-
| &76
| MAX
|-
| &77
| MIN
|-
| &78
| POS
|-
| &79
| RIGHT$
|-
| &7a
| ROUND
|-
| &7b
| STRING$
|-
| &7c
| TEST
|-
| &7d
| TESTR
|-
| &7e
| COPYCHR$ (v1.1)
|-
| &7f
| VPOS
|-
|  
| (note 4)
|}

 NOTES:

*These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence: <pre>&FF,&00</pre>
*Codes &1e...&3f inclusive are not used
*Codes &4a...&6f inclusive are not used
*Codes &80...&ff inclusive are not used

*When a BASIC program is in memory, the BASIC ROM can replace "16-bit BASIC program line number" tokens with "16-bit BASIC program line memory address pointer".

When a program is loaded or saved, there will only be "16-bit BASIC program line number" tokens followed by a 16-bit number of the line.

When a program is running, BASIC will replace the "16-bit BASIC program line number" with the "16-bit BASIC program line memory address pointer" token, and replace the 16-bit line number with the memory address of the start of that line.

It does this to avoid having to lookup the address of the line each time.

* When a REM or ' is seen, the characters following it are output directly (i.e. the bytes are not tokenized) until the end of line or a ':' is seen.

* When a BASIC program is listed each line is converted to a string (this includes the line number and the tokens converted to their strings). There is a maximum length for this string of 256 characters. This means that if the BASIC line is LISTed or EDITed, then the line will be displayed incorrectly with missing characters on the end. This is also noticed if you have a "10-liner" program that packs as much BASIC as possible into each line and renumber it so the line number has more digits.

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

 In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form: 1 x 2<exponent> The representation uses 5 bytes and is stored using the following structure:

 

{| border="1"
|-
! Byte
! colspan="8" | 0
! colspan="8" | 1
! colspan="8" | 2
! colspan="8" | 3
! colspan="8" | 4
|-
! Bit
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
|-
| Function
| colspan="8" | (LSB) mantissa (bits 31-24)
| colspan="8" | mantissa (bits 23-16)
| colspan="8" | mantissa (bits 15-8)
| colspan="1" | sign
| colspan="7" | (MSB) mantissa (bits 7-0)
| colspan="8" | exponent
|}

=== Sign ===

The sign is represented by bit 7 of byte 3. The value of the sign bit indicates the sign of the floating point number.

#*If the sign bit is "1", then the number is negative.
#*If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4. It is stored with a bias of 128.

#*128-255 are positive exponents,
#*1-127 are negative exponents.
#*0 means, the number is zero

To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 1 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^127.
A value of 0 just means, that the number is zero (0).

=== BASIC Display of Floating point numbers ===

* Numbers are displayed to 9 decimal places.
* If the number doesn't have a fractional part (e.g. .0) then the fractional part is not displayed.
* Trailing zeros (zero digits after the last digit in the fraction) are not displayed
* The value is rounded in the following way for display:

If the 10th fractional digit is 5 or above, then the number is rounded up.
If the 10th fractional digit is 4 or below, then the number is rounded down.
e.g.
0.1234567891 is displayed as 0.123456789
0.1234567895 is displayed as 0.12345679

=== floating point example in RAM by MaV ===

The initial figure = 43.375.
An example in BASIC:
<pre>
a!=43.375
READY
PRINT a!
43.375
PRINT @a!
374
FOR I=0 TO 4:PRINT HEX$(PEEK(374+I),2);:NEXT I
0000802D86
</pre>
the result for better readability: 
'''00 00 80 2D 86''' 
The first byte contains the least significant bits of the mantissa, and every following byte up to the fourth byte contain the bits following the first in significance and in exactly that order!

That means that you have to turn around the first four bytes if you want to read the mantissa correctly:
2D800000
or
0010.1101.1000.0000.0000.0000.0000.0000
in binary (the stops are inserted for better readability).

Now the highest significant bit here is 0, so the number is positive.
What's more, you need to clear that bit and substitute the implied highest bit (see description in the link), which is always 1 (regardless of the deleted sign bit!!!).
Thus you get:
AD800000
or
1010.1101.1000.0000.0000.0000.0000.0000
in binary.

The mantissa has an implied decimal point before the number. Since the number is 2^32 bits (i.e. 4 bytes) long you have to divide by 2^32 to get the proper decimal representation.

AD800000 (hex) = 2910846976 (dec)

2910846976 / 2^32 = 0.677734375

The mantissa in a decimal representation is: 0.677734375

Now, the last byte contains the exponent: 86 (hex) or 134 (dec). You need to subtract 128 to get the real exponent, the highest bit tells you that the exponent is positive (1) or negative (0). Your exponent is 6.

0.677734375 * 2^6 = 43.375

'''Another example:''' 
PI is represented in memory as: 
'''A2 DA 0F 49 82''' 
The mantissa is 
490FDAA2 (highest significant bit is zero => number is positive)
The exponent is 
82 (=positive mantissa, value=2 thus multiply mantissa with 2^2) 

Delete the sign bit (which is 0 anyway), and then add the implied 1 bit: 
C90FDAA2 (hex) = 3373259426 (dec) = 1100.1001.0000.1111.1101.1010.1010.0010 (bin) 

Calculate the decimal representation of the mantissa: 
3373259426 / 2^32 = 0,7853981633670628070831298828125 

Then add the exponent (82h - 80h = 2 thus 2^2) 
0,7853981633670628070831298828125 * 2^2 = 3,14159265346825122833251953125 

Voilà! The internal representation of the number PI on the CPC is: 3,14159265346825122833251953125 

If you compare to a (more) correct representation of PI, you'll see that the CPC is correct up to the 9th decimal place: 

CPC: 
3.14159265346825122833251953125 
more correctly: 
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986...

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts. The biggest figure which can be stored correctly in RAM by a variable is 2^32-1 = 4294967295.

#A real variable is defined with a "!" character postfix.

e.g.
<pre>a! = 3.141592654
</pre>
#A real number uses 5 bytes of memory as storage. The format is described above.
#The address of a real variable can be found in BASIC by:
<pre>PRINT @a!
</pre>

Where "a" should be replaced with the name of the variable.

 

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

 NOTES:

#A integer variable is defined with a "%" character postfix.

e.g.
<pre>a% = 3
</pre>
#A integer variable has a range of -32768 to 32767
#A integer variable always uses two bytes of memory as storage with the following format:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 2
| Integer number
|}

#The address of the integer variable can be found in BASIC by:
<pre>PRINT @a%
</pre>

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

 NOTES:

#A string variable is defined in BASIC with a "$" character postfix.

e.g.
<pre>a$ = "hello"
</pre>
*A string variable is described internally by a "string descriptor block" which has the following structure:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 1
| Length of string in bytes/characters
|-
| 1
| 2
| Location of start of string
|}

*The address of the "string descriptor block" for the string variable can be found in BASIC by typing: <pre>PRINT @a$
</pre>

replacing "a$" with the name of the string variable.

*A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
*A string variable can contain any ASCII character code in the range 0-255.
*A string variable can store a minimum of 0 characters and a maximum of 255 characters.
*The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Technical information about Locomotive BASIC

2025-08-24T10:22:32Z

Arnoldemu: /* BASIC integer variables */

[[Category:Cpctech.org]]

'''''This article originally came from Kevin Thackers' archive at [http://www.cpctech.org.uk http://www.cpctech.org.uk].'''''

= Technical information about Locomotive BASIC =

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== BASIC v1.0 only ==

There is a region of memory between AC00-AC1B which is filled with RET instructions. The BASIC ROM calls the following locations:
AC01,AC04,AC07,AC0A,AC0D,AC10,AC13,AC16,AC19

It almost looks like these were used for debugging the ROM but were left in.

They can be used to implement new BASIC commands.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR". A binary function is accessed through BASIC using the "CALL" command.

Both RSX and CALL commands work (are!) similar from the BASIC command line and invoke machine code - the only difference is: with the help of a RSX command you don't need to know the exact access address. You can pass up to 32 parameters with a CALL or RSX command. Possible parameters could be integer, floating points and strings. Just store the parameter into a variable:
Passing for integer:
<pre>
CALL &4000,32,34,&5E,&x10101010
|RSX-command,32,34,&5E,&x10101010
</pre>
Passing for floating points
<pre>
@a!=43.375
CALL or |RSX-command,@a!
</pre>

 Passing a string parameter:
 BASIC v1.0
<pre>a$="A":|DRIVE,@a$
</pre>
BASIC v1.1:
<pre>|DRIVE,"A"
</pre>
or
<pre>
b$="test"
CALL or |RSX-command,@b$
</pre>

The parameters will be stored inside the range of Stack:
<pre>
A=n -------> MSB PARAM1
LSB PARAM1
MSB PARAM2
LSB PARAM2
...
...
...
MSB PARAMn
IX+0 ------> LSB PARAMn
</pre>
with the help of that assembly code is it possible to find the parameters:
<pre>
ROUT1: CP x ;test register A if "x" parameters were given, e.g. x = 2
RET NZ ; if not exactly x parameters then do not execute RSX.
LD L,(IX+0)
LD H,(IX+1) ; HL = value of last parameter
LD E,(IX+2)
LD D,(IX+3) ; DE = value of next to last parameter
...
</pre>
A register holds the number of parameters. IX points to each parameter. IX+0/IX+1 is the last parameter. This happens because each parameter in order is pushed onto the stack and IX then points to the last parameter pushed. Each parameter is a 16-bit value.

If a parameter is a string, then IX holds the address of the string descriptor which point to a 3 byte block. The first byte of the string descriptor is the length. The next 2 bytes are an address that point to the string in memory.

With the help of the variable container "@" it is also possible to get a result from an invoked mc-code back to basic.
In this case the parameter contains the address of the integer, floating point or string. You can modify these to give the result.
BASIC allocates the strings, so when you modify a string, do not write more characters than the original string.

Hint: the first two bytes at the end of stack shows the internal return address from BASIC interpreter where it was executed.

== Additional keywords and variables in BASIC v1.1 ==

#BASIC v1.1 has the following additional keywords:
#*COPYCHR$
#*CURSOR
#*DEC$
#*FILL
#*FRAME
#*GRAPHICS
#*MASK
#BASIC v1.1 has the following additional predefined variables:
#*DERR

 

== BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

There are some rules for assigning names for variables:
: - it is not allowed to define a variable starting with a figure (the system expect then programming mode and interpret it as a program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - different sign e.g.: a slash (doesn't depend which direction), a 'minus' sign, a 'and' sign can't be used in a variable names
: - after a dollar sign (for defining string variables) it is not allowed to use further signs
: - different defining functions together are not allowed (e.g. use '%' together with '$')

: - you can use 40 characters for a variable name
: - use ! for defining a REAL value variable (like the function DEFREAL but only for the assigned variable) > It's also possible to omit the exlamation mark because it's the default system declaration after powering on then CPC.
: - use % for defining a INTEGER value variable (like the function DEFINT but only for the assigned variable)
: - use $ for defining a STRING variable (like the function DEFSTR but only for the assigned variable)
: - Minimum line number is 1. Maximum line number is 65535.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

 

== Speeding up BASIC programs ==

To speed up BASIC programs following rules could help:
: - Avoid loops or a branching program structure if possible. Internally the operating system searches for the right line number always from the beginning of the program 'listing'. Often recurring subroutines (if necessary) should be at the beginning of RAM to speed up things.
: - Avoid the index variable after the <code>NEXT</code> command/statement (although it isn't a good program style)
: - Avoid spaces inside program code or remarks
: - Put lots of statements as possible in ONE line
: - Use variables instead of constants. A constant has always to be converted in a binary/digital format. A variable is already converted.
: - Dimensioning at the beginning of the program
: - Dimensioning your variables & pre-calculate
: - Avoid AND/OR/XOR in IF-THEN statements. It's faster to write IF ... THEN (statement 1).. IF ... THEN (statement 2).
: - Minimise string/char manipulation as this often requires memory allocations. (e.g. joining strings with +, use of MID$, LEFT$, RIGHT$, SPACE$)

== Minimizing memory usage ==

To minimize memory usage in BASIC here are some things to consider.

The size of the tokenized program:
: - Difficult to measure without looking at the data in memory.
: - Use short variable names. The names are stored in the tokenized BASIC program as-is.
: - Minimize the number of variables. The names are stored in the tokenized BASIC program everywhere they are used.
: - Use as few lines as possible. It's a small saving of about 5 bytes per line.
: - Consider using numbers vs strings and potentially 8-bit or 16-bit values.

Minimising memory usage when the program is running:
: - Minimize string operations. (e.g. A$=SPACE$(30)+CHR$(28) in memory this first allocates a string of length 30 containing spaces, then it allocates a new string of length 31 with spaces and char 28 at the end and assigns it to A$. In this line at least 30 bytes have been wasted. So consider if you need strings or perhaps if possible pre-define them).

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences. Each line of the BASIC program has the form:

 

{| border="1"
|-
! Offset
! Size
! Description
|-
| 0
| 2
| Length of line data in bytes (note 1)
|-
| 2
| 2
| 16-bit decimal integer line number (note 2)
|-
| 4
| n
| BASIC line encoded into tokens (note 3)
|-
| n+1
| 1
| "0" the end of line marker (note 4)
|}

 Notes:

#This 16-bit value has two functions: if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data, otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
#This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
#This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
#This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| end of tokenised line marker
|-
| &01
| ":" statement seperator
|-
| &02
| integer variable definition (defined with "%" suffix)
|-
| &03
| string variable definition (defined with "$" suffix)
|-
| &04
| floating point variable definition (defined with "!" suffix)
|-
| &05
| var?
|-
| &06
| var?
|-
| &07
| var?
|-
| &08
| var?
|-
| &09
| var?
|-
| &0a
| var?
|-
| &0b
| variable definition (no suffix)
|-
| &0c
| variable definition (no suffix)
|-
| &0d
| variable definition (no suffix)
|-
| &0e
| number constant "0"
|-
| &0f
| number constant "1"
|-
| &10
| number constant "2"
|-
| &11
| number constant "3"
|-
| &12
| number constant "4"
|-
| &13
| number constant "5"
|-
| &14
| number constant "6"
|-
| &15
| number constant "7"
|-
| &16
| number constant "8"
|-
| &17
| number constant "9"
|-
| &18
| number constant "10"
|-
| &19
| 8-bit integer decimal value
|-
| &1a
| 16-bit integer decimal value
|-
| &1b
| 16-bit integer binary value (with "&X" prefix)
|-
| &1c
| 16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
| &1d
| 16-bit BASIC program line memory address pointer (see notes)
|-
| &1e
| 16-bit integer BASIC line number
|-
| &1f
| floating point value
|-
| &20
| " " (space) symbol
|-
| &21
| ASCII "!" symbol
|-
| &22
| quoted string value
|-
| &23-7b
| ASCII printable symbols
|-
| &7c
| "|" symbol; prefix for RSX commands
|-
| &80
| AFTER
|-
| &81
| AUTO
|-
| &82
| BORDER
|-
| &83
| CALL
|-
| &84
| CAT
|-
| &85
| CHAIN
|-
| &86
| CLEAR
|-
| &87
| CLG
|-
| &88
| CLOSEIN
|-
| &89
| CLOSEOUT
|-
| &8a
| CLS
|-
| &8b
| CONT
|-
| &8c
| DATA
|-
| &8d
| DEF
|-
| &8e
| DEFINT
|-
| &8f
| DEFREAL
|-
| &90
| DEFSTR
|-
| &91
| DEG
|-
| &92
| DELETE
|-
| &93
| DIM
|-
| &94
| DRAW
|-
| &95
| DRAWR
|-
| &96
| EDIT
|-
| &97
| ELSE
|-
| &98
| END
|-
| &99
| ENT
|-
| &9a
| ENV
|-
| &9b
| ERASE
|-
| &9c
| ERROR
|-
| &9d
| EVERY
|-
| &9e
| FOR
|-
| &9f
| GOSUB, GO SUB
|-
| &a0
| GOTO, GO TO
|-
| &a1
| IF
|-
| &a2
| INK
|-
| &a3
| INPUT
|-
| &a4
| KEY
|-
| &a5
| LET
|-
| &a6
| LINE
|-
| &a7
| LIST
|-
| &a8
| LOAD
|-
| &a9
| LOCATE
|-
| &aa
| MEMORY
|-
| &ab
| MERGE
|-
| &ac
| MID$
|-
| &ad
| MODE
|-
| &ae
| MOVE
|-
| &af
| MOVER
|-
| &b0
| NEXT
|-
| &b1
| NEW
|-
| &b2
| ON
|-
| &b3
| ON BREAK
|-
| &b4
| ON ERROR GOTO, ON ERROR GO TO
|-
| &b5
| ON SQ
|-
| &b6
| OPENIN
|-
| &b7
| OPENOUT
|-
| &b8
| ORIGIN
|-
| &b9
| OUT
|-
| &ba
| PAPER
|-
| &bb
| PEN
|-
| &bc
| PLOT
|-
| &bd
| PLOTR
|-
| &be
| POKE
|-
| &bf
| PRINT
|-
| &c0
| "'" symbol (same function as REM keyword)
|-
| &c1
| RAD
|-
| &c2
| RANDOMIZE
|-
| &c3
| READ
|-
| &c4
| RELEASE
|-
| &c5
| REM
|-
| &c6
| RENUM
|-
| &c7
| RESTORE
|-
| &c8
| RESUME
|-
| &c9
| RETURN
|-
| &ca
| RUN
|-
| &cb
| SAVE
|-
| &cc
| SOUND
|-
| &cd
| SPEED
|-
| &ce
| STOP
|-
| &cf
| SYMBOL
|-
| &d0
| TAG
|-
| &d1
| TAGOFF
|-
| &d2
| TROFF
|-
| &d3
| TRON
|-
| &d4
| WAIT
|-
| &d5
| WEND
|-
| &d6
| WHILE
|-
| &d7
| WIDTH
|-
| &d8
| WINDOW
|-
| &d9
| WRITE
|-
| &da
| ZONE
|-
| &db
| DI
|-
| &dc
| EI
|-
| &dd
| FILL (v1.1)
|-
| &de
| GRAPHICS (v1.1)
|-
| &df
| MASK (v1.1)
|-
| &e0
| FRAME (v1.1)
|-
| &e1
| CURSOR (v1.1)
|-
| &e2
| (note 2)
|-
| &e3
| ERL
|-
| &e4
| FN
|-
| &e5
| SPC
|-
| &e6
| STEP
|-
| &e7
| SWAP
|-
| &e8
| (note 2)
|-
| &e9
| (note 2)
|-
| &ea
| TAB
|-
| &eb
| THEN
|-
| &ec
| TO
|-
| &ed
| USING
|-
| &ee
| > (greater than)
|-
| &ef
| = (equal)
|-
| &f0
| &gt=, > =, => (greater or equal)
|-
| &f1
| < (less than)
|-
| &f2
| <&gt, < > (not equal)
|-
| &f3
| =<, <=, < = (less than or equal)
|-
| &f4
| + (addition)
|-
| &f5
| - (subtraction or unary minus)
|-
| &f6
| * (multiplication)
|-
| &f7
| / (division)
|-
| &f8
| ^ (x to the power of y)
|-
| &f9
| \ (integer division)
|-
| &fa
| AND
|-
| &fb
| MOD
|-
| &fc
| OR
|-
| &fd
| XOR
|-
| &fe
| NOT
|-
| &ff
| (prefix for additional keywords)
|}

 Notes:

*The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
*&e2,&e8 and &e9 are not used
*&7c ("|") is a character prefix used to identify an RSX command. e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| "|" character prefix
|-
| 1
| 1
| 8-bit byte offset to tokens following RSX name.
|-
| 2
| x
| RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
|}

*This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &1a,&2d,&00 represents the integer number "&002d"="45".
*This token (&0B) is changed at run-time to &0D
*This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
*This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
*This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| &1f (note 1)
|-
| 1
| 5
| Floating point number (note 2)
|}

*#This byte is the BASIC token identifying a floating point number
*#These 5 bytes define the floating point number.
*The space symbol is used as a command seperator
*Variable definitions:
**The variable definition has the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| Token defining variable type
|-
| 2
| 2
| 16-bit Byte offset to variable value within tokenised BASIC program.
|-
| 4
| x
| Variable name
|}

 The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.

**The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
**The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
*String values:
**Each string value is prefixed with &22 token.
**All strings must be enclosed by double quote symbols (&quot). This symbols define the start and end of the string value.
**The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.

*After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

 This table list the BASIC tokens with a &ff prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| ABS
|-
| &01
| ASC
|-
| &02
| ATN
|-
| &03
| CHR$
|-
| &04
| CINT
|-
| &05
| COS
|-
| &06
| CREAL
|-
| &07
| EXP
|-
| &08
| FIX
|-
| &09
| FRE
|-
| &0a
| INKEY
|-
| &0b
| INP
|-
| &0c
| INT
|-
| &0d
| JOY
|-
| &0e
| LEN
|-
| &0f
| LOG
|-
| &10
| LOG10
|-
| &11
| LOWER$
|-
| &12
| PEEK
|-
| &13
| REMAIN
|-
| &14
| SGN
|-
| &15
| SIN
|-
| &16
| SPACE$
|-
| &17
| SQ
|-
| &18
| SQR
|-
| &19
| STR$
|-
| &1a
| TAN
|-
| &1b
| UNT
|-
| &1c
| UPPER$
|-
| &1d
| VAL
|-
|  
| (note 2)
|-
| &40
| EOF
|-
| &41
| ERR
|-
| &42
| HIMEM
|-
| &43
| INKEY$
|-
| &44
| PI
|-
| &45
| RND
|-
| &46
| TIME
|-
| &47
| XPOS
|-
| &48
| YPOS
|-
| &49
| DERR (v1.1)
|-
|  
| (note 3)
|-
| &71
| BIN$
|-
| &72
| DEC$ (v1.1)
|-
| &73
| HEX$
|-
| &74
| INSTR
|-
| &75
| LEFT$
|-
| &76
| MAX
|-
| &77
| MIN
|-
| &78
| POS
|-
| &79
| RIGHT$
|-
| &7a
| ROUND
|-
| &7b
| STRING$
|-
| &7c
| TEST
|-
| &7d
| TESTR
|-
| &7e
| COPYCHR$ (v1.1)
|-
| &7f
| VPOS
|-
|  
| (note 4)
|}

 NOTES:

*These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence: <pre>&FF,&00</pre>
*Codes &1e...&3f inclusive are not used
*Codes &4a...&6f inclusive are not used
*Codes &80...&ff inclusive are not used

*When a BASIC program is in memory, the BASIC ROM can replace "16-bit BASIC program line number" tokens with "16-bit BASIC program line memory address pointer".

When a program is loaded or saved, there will only be "16-bit BASIC program line number" tokens followed by a 16-bit number of the line.

When a program is running, BASIC will replace the "16-bit BASIC program line number" with the "16-bit BASIC program line memory address pointer" token, and replace the 16-bit line number with the memory address of the start of that line.

It does this to avoid having to lookup the address of the line each time.

* When a REM or ' is seen, the characters following it are output directly (i.e. the bytes are not tokenized) until the end of line or a ':' is seen.

* When a BASIC program is listed each line is converted to a string (this includes the line number and the tokens converted to their strings). There is a maximum length for this string of 256 characters. This means that if the BASIC line is LISTed or EDITed, then the line will be displayed incorrectly with missing characters on the end. This is also noticed if you have a "10-liner" program that packs as much BASIC as possible into each line and renumber it so the line number has more digits.

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

 In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form: 1 x 2<exponent> The representation uses 5 bytes and is stored using the following structure:

 

{| border="1"
|-
! Byte
! colspan="8" | 0
! colspan="8" | 1
! colspan="8" | 2
! colspan="8" | 3
! colspan="8" | 4
|-
! Bit
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
|-
| Function
| colspan="8" | (LSB) mantissa (bits 31-24)
| colspan="8" | mantissa (bits 23-16)
| colspan="8" | mantissa (bits 15-8)
| colspan="1" | sign
| colspan="7" | (MSB) mantissa (bits 7-0)
| colspan="8" | exponent
|}

=== Sign ===

The sign is represented by bit 7 of byte 3. The value of the sign bit indicates the sign of the floating point number.

#*If the sign bit is "1", then the number is negative.
#*If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4. It is stored with a bias of 128.

#*128-255 are positive exponents,
#*1-127 are negative exponents.
#*0 means, the number is zero

To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 1 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^127.
A value of 0 just means, that the number is zero (0).

=== BASIC Display of Floating point numbers ===

* Numbers are displayed to 9 decimal places.
* If the number doesn't have a fractional part (e.g. .0) then the fractional part is not displayed.
* Trailing zeros (zero digits after the last digit in the fraction) are not displayed
* The value is rounded in the following way for display:

If the 10th fractional digit is 5 or above, then the number is rounded up.
If the 10th fractional digit is 4 or below, then the number is rounded down.
e.g.
0.1234567891 is displayed as 0.123456789
0.1234567895 is displayed as 0.12345679

=== floating point example in RAM by MaV ===

The initial figure = 43.375.
An example in BASIC:
<pre>
a!=43.375
READY
PRINT a!
43.375
PRINT @a!
374
FOR I=0 TO 4:PRINT HEX$(PEEK(374+I),2);:NEXT I
0000802D86
</pre>
the result for better readability: 
'''00 00 80 2D 86''' 
The first byte contains the least significant bits of the mantissa, and every following byte up to the fourth byte contain the bits following the first in significance and in exactly that order!

That means that you have to turn around the first four bytes if you want to read the mantissa correctly:
2D800000
or
0010.1101.1000.0000.0000.0000.0000.0000
in binary (the stops are inserted for better readability).

Now the highest significant bit here is 0, so the number is positive.
What's more, you need to clear that bit and substitute the implied highest bit (see description in the link), which is always 1 (regardless of the deleted sign bit!!!).
Thus you get:
AD800000
or
1010.1101.1000.0000.0000.0000.0000.0000
in binary.

The mantissa has an implied decimal point before the number. Since the number is 2^32 bits (i.e. 4 bytes) long you have to divide by 2^32 to get the proper decimal representation.

AD800000 (hex) = 2910846976 (dec)

2910846976 / 2^32 = 0.677734375

The mantissa in a decimal representation is: 0.677734375

Now, the last byte contains the exponent: 86 (hex) or 134 (dec). You need to subtract 128 to get the real exponent, the highest bit tells you that the exponent is positive (1) or negative (0). Your exponent is 6.

0.677734375 * 2^6 = 43.375

'''Another example:''' 
PI is represented in memory as: 
'''A2 DA 0F 49 82''' 
The mantissa is 
490FDAA2 (highest significant bit is zero => number is positive)
The exponent is 
82 (=positive mantissa, value=2 thus multiply mantissa with 2^2) 

Delete the sign bit (which is 0 anyway), and then add the implied 1 bit: 
C90FDAA2 (hex) = 3373259426 (dec) = 1100.1001.0000.1111.1101.1010.1010.0010 (bin) 

Calculate the decimal representation of the mantissa: 
3373259426 / 2^32 = 0,7853981633670628070831298828125 

Then add the exponent (82h - 80h = 2 thus 2^2) 
0,7853981633670628070831298828125 * 2^2 = 3,14159265346825122833251953125 

Voilà! The internal representation of the number PI on the CPC is: 3,14159265346825122833251953125 

If you compare to a (more) correct representation of PI, you'll see that the CPC is correct up to the 9th decimal place: 

CPC: 
3.14159265346825122833251953125 
more correctly: 
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986...

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts. The biggest figure which can be stored correctly in RAM by a variable is 2^32-1 = 4294967295.

#A real variable is defined with a "!" character postfix.

e.g.
<pre>a! = 3.141592654
</pre>
#A real number uses 5 bytes of memory as storage. The format is described above.
#The address of a real variable can be found in BASIC by:
<pre>PRINT @a!
</pre>

Where "a" should be replaced with the name of the variable.

 

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

 NOTES:

#A integer variable is defined with a "%" character postfix.

e.g.
<pre>a% = 3
</pre>
#A integer variable has a range of -32768 to 32767
#A integer variable always uses two bytes of memory as storage with the following format:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 2
| Integer number
|}

#The address of the integer variable can be found in BASIC by:
<pre>PRINT @a%
</pre>

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

 NOTES:

#A string variable is defined in BASIC with a "$" character postfix.

e.g.
<pre>a$ = "hello"
</pre>
#A string variable is described internally by a "string descriptor block" which has the following structure:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 1
| Length of string in bytes/characters
|-
| 1
| 2
| Location of start of string
|}

#The address of the "string descriptor block" for the string variable can be found in BASIC by typing: <pre>PRINT @a$
</pre>

replacing "a$" with the name of the string variable.

#A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
#A string variable can contain any ASCII character code in the range 0-255.
#A string variable can store a minimum of 0 characters and a maximum of 255 characters.
#The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Technical information about Locomotive BASIC

2025-08-24T10:22:21Z

Arnoldemu: /* BASIC floating-point/real variables */

[[Category:Cpctech.org]]

'''''This article originally came from Kevin Thackers' archive at [http://www.cpctech.org.uk http://www.cpctech.org.uk].'''''

= Technical information about Locomotive BASIC =

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== BASIC v1.0 only ==

There is a region of memory between AC00-AC1B which is filled with RET instructions. The BASIC ROM calls the following locations:
AC01,AC04,AC07,AC0A,AC0D,AC10,AC13,AC16,AC19

It almost looks like these were used for debugging the ROM but were left in.

They can be used to implement new BASIC commands.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR". A binary function is accessed through BASIC using the "CALL" command.

Both RSX and CALL commands work (are!) similar from the BASIC command line and invoke machine code - the only difference is: with the help of a RSX command you don't need to know the exact access address. You can pass up to 32 parameters with a CALL or RSX command. Possible parameters could be integer, floating points and strings. Just store the parameter into a variable:
Passing for integer:
<pre>
CALL &4000,32,34,&5E,&x10101010
|RSX-command,32,34,&5E,&x10101010
</pre>
Passing for floating points
<pre>
@a!=43.375
CALL or |RSX-command,@a!
</pre>

 Passing a string parameter:
 BASIC v1.0
<pre>a$="A":|DRIVE,@a$
</pre>
BASIC v1.1:
<pre>|DRIVE,"A"
</pre>
or
<pre>
b$="test"
CALL or |RSX-command,@b$
</pre>

The parameters will be stored inside the range of Stack:
<pre>
A=n -------> MSB PARAM1
LSB PARAM1
MSB PARAM2
LSB PARAM2
...
...
...
MSB PARAMn
IX+0 ------> LSB PARAMn
</pre>
with the help of that assembly code is it possible to find the parameters:
<pre>
ROUT1: CP x ;test register A if "x" parameters were given, e.g. x = 2
RET NZ ; if not exactly x parameters then do not execute RSX.
LD L,(IX+0)
LD H,(IX+1) ; HL = value of last parameter
LD E,(IX+2)
LD D,(IX+3) ; DE = value of next to last parameter
...
</pre>
A register holds the number of parameters. IX points to each parameter. IX+0/IX+1 is the last parameter. This happens because each parameter in order is pushed onto the stack and IX then points to the last parameter pushed. Each parameter is a 16-bit value.

If a parameter is a string, then IX holds the address of the string descriptor which point to a 3 byte block. The first byte of the string descriptor is the length. The next 2 bytes are an address that point to the string in memory.

With the help of the variable container "@" it is also possible to get a result from an invoked mc-code back to basic.
In this case the parameter contains the address of the integer, floating point or string. You can modify these to give the result.
BASIC allocates the strings, so when you modify a string, do not write more characters than the original string.

Hint: the first two bytes at the end of stack shows the internal return address from BASIC interpreter where it was executed.

== Additional keywords and variables in BASIC v1.1 ==

#BASIC v1.1 has the following additional keywords:
#*COPYCHR$
#*CURSOR
#*DEC$
#*FILL
#*FRAME
#*GRAPHICS
#*MASK
#BASIC v1.1 has the following additional predefined variables:
#*DERR

 

== BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

There are some rules for assigning names for variables:
: - it is not allowed to define a variable starting with a figure (the system expect then programming mode and interpret it as a program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - different sign e.g.: a slash (doesn't depend which direction), a 'minus' sign, a 'and' sign can't be used in a variable names
: - after a dollar sign (for defining string variables) it is not allowed to use further signs
: - different defining functions together are not allowed (e.g. use '%' together with '$')

: - you can use 40 characters for a variable name
: - use ! for defining a REAL value variable (like the function DEFREAL but only for the assigned variable) > It's also possible to omit the exlamation mark because it's the default system declaration after powering on then CPC.
: - use % for defining a INTEGER value variable (like the function DEFINT but only for the assigned variable)
: - use $ for defining a STRING variable (like the function DEFSTR but only for the assigned variable)
: - Minimum line number is 1. Maximum line number is 65535.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

 

== Speeding up BASIC programs ==

To speed up BASIC programs following rules could help:
: - Avoid loops or a branching program structure if possible. Internally the operating system searches for the right line number always from the beginning of the program 'listing'. Often recurring subroutines (if necessary) should be at the beginning of RAM to speed up things.
: - Avoid the index variable after the <code>NEXT</code> command/statement (although it isn't a good program style)
: - Avoid spaces inside program code or remarks
: - Put lots of statements as possible in ONE line
: - Use variables instead of constants. A constant has always to be converted in a binary/digital format. A variable is already converted.
: - Dimensioning at the beginning of the program
: - Dimensioning your variables & pre-calculate
: - Avoid AND/OR/XOR in IF-THEN statements. It's faster to write IF ... THEN (statement 1).. IF ... THEN (statement 2).
: - Minimise string/char manipulation as this often requires memory allocations. (e.g. joining strings with +, use of MID$, LEFT$, RIGHT$, SPACE$)

== Minimizing memory usage ==

To minimize memory usage in BASIC here are some things to consider.

The size of the tokenized program:
: - Difficult to measure without looking at the data in memory.
: - Use short variable names. The names are stored in the tokenized BASIC program as-is.
: - Minimize the number of variables. The names are stored in the tokenized BASIC program everywhere they are used.
: - Use as few lines as possible. It's a small saving of about 5 bytes per line.
: - Consider using numbers vs strings and potentially 8-bit or 16-bit values.

Minimising memory usage when the program is running:
: - Minimize string operations. (e.g. A$=SPACE$(30)+CHR$(28) in memory this first allocates a string of length 30 containing spaces, then it allocates a new string of length 31 with spaces and char 28 at the end and assigns it to A$. In this line at least 30 bytes have been wasted. So consider if you need strings or perhaps if possible pre-define them).

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences. Each line of the BASIC program has the form:

 

{| border="1"
|-
! Offset
! Size
! Description
|-
| 0
| 2
| Length of line data in bytes (note 1)
|-
| 2
| 2
| 16-bit decimal integer line number (note 2)
|-
| 4
| n
| BASIC line encoded into tokens (note 3)
|-
| n+1
| 1
| "0" the end of line marker (note 4)
|}

 Notes:

#This 16-bit value has two functions: if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data, otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
#This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
#This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
#This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| end of tokenised line marker
|-
| &01
| ":" statement seperator
|-
| &02
| integer variable definition (defined with "%" suffix)
|-
| &03
| string variable definition (defined with "$" suffix)
|-
| &04
| floating point variable definition (defined with "!" suffix)
|-
| &05
| var?
|-
| &06
| var?
|-
| &07
| var?
|-
| &08
| var?
|-
| &09
| var?
|-
| &0a
| var?
|-
| &0b
| variable definition (no suffix)
|-
| &0c
| variable definition (no suffix)
|-
| &0d
| variable definition (no suffix)
|-
| &0e
| number constant "0"
|-
| &0f
| number constant "1"
|-
| &10
| number constant "2"
|-
| &11
| number constant "3"
|-
| &12
| number constant "4"
|-
| &13
| number constant "5"
|-
| &14
| number constant "6"
|-
| &15
| number constant "7"
|-
| &16
| number constant "8"
|-
| &17
| number constant "9"
|-
| &18
| number constant "10"
|-
| &19
| 8-bit integer decimal value
|-
| &1a
| 16-bit integer decimal value
|-
| &1b
| 16-bit integer binary value (with "&X" prefix)
|-
| &1c
| 16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
| &1d
| 16-bit BASIC program line memory address pointer (see notes)
|-
| &1e
| 16-bit integer BASIC line number
|-
| &1f
| floating point value
|-
| &20
| " " (space) symbol
|-
| &21
| ASCII "!" symbol
|-
| &22
| quoted string value
|-
| &23-7b
| ASCII printable symbols
|-
| &7c
| "|" symbol; prefix for RSX commands
|-
| &80
| AFTER
|-
| &81
| AUTO
|-
| &82
| BORDER
|-
| &83
| CALL
|-
| &84
| CAT
|-
| &85
| CHAIN
|-
| &86
| CLEAR
|-
| &87
| CLG
|-
| &88
| CLOSEIN
|-
| &89
| CLOSEOUT
|-
| &8a
| CLS
|-
| &8b
| CONT
|-
| &8c
| DATA
|-
| &8d
| DEF
|-
| &8e
| DEFINT
|-
| &8f
| DEFREAL
|-
| &90
| DEFSTR
|-
| &91
| DEG
|-
| &92
| DELETE
|-
| &93
| DIM
|-
| &94
| DRAW
|-
| &95
| DRAWR
|-
| &96
| EDIT
|-
| &97
| ELSE
|-
| &98
| END
|-
| &99
| ENT
|-
| &9a
| ENV
|-
| &9b
| ERASE
|-
| &9c
| ERROR
|-
| &9d
| EVERY
|-
| &9e
| FOR
|-
| &9f
| GOSUB, GO SUB
|-
| &a0
| GOTO, GO TO
|-
| &a1
| IF
|-
| &a2
| INK
|-
| &a3
| INPUT
|-
| &a4
| KEY
|-
| &a5
| LET
|-
| &a6
| LINE
|-
| &a7
| LIST
|-
| &a8
| LOAD
|-
| &a9
| LOCATE
|-
| &aa
| MEMORY
|-
| &ab
| MERGE
|-
| &ac
| MID$
|-
| &ad
| MODE
|-
| &ae
| MOVE
|-
| &af
| MOVER
|-
| &b0
| NEXT
|-
| &b1
| NEW
|-
| &b2
| ON
|-
| &b3
| ON BREAK
|-
| &b4
| ON ERROR GOTO, ON ERROR GO TO
|-
| &b5
| ON SQ
|-
| &b6
| OPENIN
|-
| &b7
| OPENOUT
|-
| &b8
| ORIGIN
|-
| &b9
| OUT
|-
| &ba
| PAPER
|-
| &bb
| PEN
|-
| &bc
| PLOT
|-
| &bd
| PLOTR
|-
| &be
| POKE
|-
| &bf
| PRINT
|-
| &c0
| "'" symbol (same function as REM keyword)
|-
| &c1
| RAD
|-
| &c2
| RANDOMIZE
|-
| &c3
| READ
|-
| &c4
| RELEASE
|-
| &c5
| REM
|-
| &c6
| RENUM
|-
| &c7
| RESTORE
|-
| &c8
| RESUME
|-
| &c9
| RETURN
|-
| &ca
| RUN
|-
| &cb
| SAVE
|-
| &cc
| SOUND
|-
| &cd
| SPEED
|-
| &ce
| STOP
|-
| &cf
| SYMBOL
|-
| &d0
| TAG
|-
| &d1
| TAGOFF
|-
| &d2
| TROFF
|-
| &d3
| TRON
|-
| &d4
| WAIT
|-
| &d5
| WEND
|-
| &d6
| WHILE
|-
| &d7
| WIDTH
|-
| &d8
| WINDOW
|-
| &d9
| WRITE
|-
| &da
| ZONE
|-
| &db
| DI
|-
| &dc
| EI
|-
| &dd
| FILL (v1.1)
|-
| &de
| GRAPHICS (v1.1)
|-
| &df
| MASK (v1.1)
|-
| &e0
| FRAME (v1.1)
|-
| &e1
| CURSOR (v1.1)
|-
| &e2
| (note 2)
|-
| &e3
| ERL
|-
| &e4
| FN
|-
| &e5
| SPC
|-
| &e6
| STEP
|-
| &e7
| SWAP
|-
| &e8
| (note 2)
|-
| &e9
| (note 2)
|-
| &ea
| TAB
|-
| &eb
| THEN
|-
| &ec
| TO
|-
| &ed
| USING
|-
| &ee
| > (greater than)
|-
| &ef
| = (equal)
|-
| &f0
| &gt=, > =, => (greater or equal)
|-
| &f1
| < (less than)
|-
| &f2
| <&gt, < > (not equal)
|-
| &f3
| =<, <=, < = (less than or equal)
|-
| &f4
| + (addition)
|-
| &f5
| - (subtraction or unary minus)
|-
| &f6
| * (multiplication)
|-
| &f7
| / (division)
|-
| &f8
| ^ (x to the power of y)
|-
| &f9
| \ (integer division)
|-
| &fa
| AND
|-
| &fb
| MOD
|-
| &fc
| OR
|-
| &fd
| XOR
|-
| &fe
| NOT
|-
| &ff
| (prefix for additional keywords)
|}

 Notes:

*The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
*&e2,&e8 and &e9 are not used
*&7c ("|") is a character prefix used to identify an RSX command. e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| "|" character prefix
|-
| 1
| 1
| 8-bit byte offset to tokens following RSX name.
|-
| 2
| x
| RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
|}

*This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &1a,&2d,&00 represents the integer number "&002d"="45".
*This token (&0B) is changed at run-time to &0D
*This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
*This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
*This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| &1f (note 1)
|-
| 1
| 5
| Floating point number (note 2)
|}

*#This byte is the BASIC token identifying a floating point number
*#These 5 bytes define the floating point number.
*The space symbol is used as a command seperator
*Variable definitions:
**The variable definition has the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| Token defining variable type
|-
| 2
| 2
| 16-bit Byte offset to variable value within tokenised BASIC program.
|-
| 4
| x
| Variable name
|}

 The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.

**The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
**The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
*String values:
**Each string value is prefixed with &22 token.
**All strings must be enclosed by double quote symbols (&quot). This symbols define the start and end of the string value.
**The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.

*After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

 This table list the BASIC tokens with a &ff prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| ABS
|-
| &01
| ASC
|-
| &02
| ATN
|-
| &03
| CHR$
|-
| &04
| CINT
|-
| &05
| COS
|-
| &06
| CREAL
|-
| &07
| EXP
|-
| &08
| FIX
|-
| &09
| FRE
|-
| &0a
| INKEY
|-
| &0b
| INP
|-
| &0c
| INT
|-
| &0d
| JOY
|-
| &0e
| LEN
|-
| &0f
| LOG
|-
| &10
| LOG10
|-
| &11
| LOWER$
|-
| &12
| PEEK
|-
| &13
| REMAIN
|-
| &14
| SGN
|-
| &15
| SIN
|-
| &16
| SPACE$
|-
| &17
| SQ
|-
| &18
| SQR
|-
| &19
| STR$
|-
| &1a
| TAN
|-
| &1b
| UNT
|-
| &1c
| UPPER$
|-
| &1d
| VAL
|-
|  
| (note 2)
|-
| &40
| EOF
|-
| &41
| ERR
|-
| &42
| HIMEM
|-
| &43
| INKEY$
|-
| &44
| PI
|-
| &45
| RND
|-
| &46
| TIME
|-
| &47
| XPOS
|-
| &48
| YPOS
|-
| &49
| DERR (v1.1)
|-
|  
| (note 3)
|-
| &71
| BIN$
|-
| &72
| DEC$ (v1.1)
|-
| &73
| HEX$
|-
| &74
| INSTR
|-
| &75
| LEFT$
|-
| &76
| MAX
|-
| &77
| MIN
|-
| &78
| POS
|-
| &79
| RIGHT$
|-
| &7a
| ROUND
|-
| &7b
| STRING$
|-
| &7c
| TEST
|-
| &7d
| TESTR
|-
| &7e
| COPYCHR$ (v1.1)
|-
| &7f
| VPOS
|-
|  
| (note 4)
|}

 NOTES:

*These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence: <pre>&FF,&00</pre>
*Codes &1e...&3f inclusive are not used
*Codes &4a...&6f inclusive are not used
*Codes &80...&ff inclusive are not used

*When a BASIC program is in memory, the BASIC ROM can replace "16-bit BASIC program line number" tokens with "16-bit BASIC program line memory address pointer".

When a program is loaded or saved, there will only be "16-bit BASIC program line number" tokens followed by a 16-bit number of the line.

When a program is running, BASIC will replace the "16-bit BASIC program line number" with the "16-bit BASIC program line memory address pointer" token, and replace the 16-bit line number with the memory address of the start of that line.

It does this to avoid having to lookup the address of the line each time.

* When a REM or ' is seen, the characters following it are output directly (i.e. the bytes are not tokenized) until the end of line or a ':' is seen.

* When a BASIC program is listed each line is converted to a string (this includes the line number and the tokens converted to their strings). There is a maximum length for this string of 256 characters. This means that if the BASIC line is LISTed or EDITed, then the line will be displayed incorrectly with missing characters on the end. This is also noticed if you have a "10-liner" program that packs as much BASIC as possible into each line and renumber it so the line number has more digits.

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

 In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form: 1 x 2<exponent> The representation uses 5 bytes and is stored using the following structure:

 

{| border="1"
|-
! Byte
! colspan="8" | 0
! colspan="8" | 1
! colspan="8" | 2
! colspan="8" | 3
! colspan="8" | 4
|-
! Bit
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
|-
| Function
| colspan="8" | (LSB) mantissa (bits 31-24)
| colspan="8" | mantissa (bits 23-16)
| colspan="8" | mantissa (bits 15-8)
| colspan="1" | sign
| colspan="7" | (MSB) mantissa (bits 7-0)
| colspan="8" | exponent
|}

=== Sign ===

The sign is represented by bit 7 of byte 3. The value of the sign bit indicates the sign of the floating point number.

#*If the sign bit is "1", then the number is negative.
#*If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4. It is stored with a bias of 128.

#*128-255 are positive exponents,
#*1-127 are negative exponents.
#*0 means, the number is zero

To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 1 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^127.
A value of 0 just means, that the number is zero (0).

=== BASIC Display of Floating point numbers ===

* Numbers are displayed to 9 decimal places.
* If the number doesn't have a fractional part (e.g. .0) then the fractional part is not displayed.
* Trailing zeros (zero digits after the last digit in the fraction) are not displayed
* The value is rounded in the following way for display:

If the 10th fractional digit is 5 or above, then the number is rounded up.
If the 10th fractional digit is 4 or below, then the number is rounded down.
e.g.
0.1234567891 is displayed as 0.123456789
0.1234567895 is displayed as 0.12345679

=== floating point example in RAM by MaV ===

The initial figure = 43.375.
An example in BASIC:
<pre>
a!=43.375
READY
PRINT a!
43.375
PRINT @a!
374
FOR I=0 TO 4:PRINT HEX$(PEEK(374+I),2);:NEXT I
0000802D86
</pre>
the result for better readability: 
'''00 00 80 2D 86''' 
The first byte contains the least significant bits of the mantissa, and every following byte up to the fourth byte contain the bits following the first in significance and in exactly that order!

That means that you have to turn around the first four bytes if you want to read the mantissa correctly:
2D800000
or
0010.1101.1000.0000.0000.0000.0000.0000
in binary (the stops are inserted for better readability).

Now the highest significant bit here is 0, so the number is positive.
What's more, you need to clear that bit and substitute the implied highest bit (see description in the link), which is always 1 (regardless of the deleted sign bit!!!).
Thus you get:
AD800000
or
1010.1101.1000.0000.0000.0000.0000.0000
in binary.

The mantissa has an implied decimal point before the number. Since the number is 2^32 bits (i.e. 4 bytes) long you have to divide by 2^32 to get the proper decimal representation.

AD800000 (hex) = 2910846976 (dec)

2910846976 / 2^32 = 0.677734375

The mantissa in a decimal representation is: 0.677734375

Now, the last byte contains the exponent: 86 (hex) or 134 (dec). You need to subtract 128 to get the real exponent, the highest bit tells you that the exponent is positive (1) or negative (0). Your exponent is 6.

0.677734375 * 2^6 = 43.375

'''Another example:''' 
PI is represented in memory as: 
'''A2 DA 0F 49 82''' 
The mantissa is 
490FDAA2 (highest significant bit is zero => number is positive)
The exponent is 
82 (=positive mantissa, value=2 thus multiply mantissa with 2^2) 

Delete the sign bit (which is 0 anyway), and then add the implied 1 bit: 
C90FDAA2 (hex) = 3373259426 (dec) = 1100.1001.0000.1111.1101.1010.1010.0010 (bin) 

Calculate the decimal representation of the mantissa: 
3373259426 / 2^32 = 0,7853981633670628070831298828125 

Then add the exponent (82h - 80h = 2 thus 2^2) 
0,7853981633670628070831298828125 * 2^2 = 3,14159265346825122833251953125 

Voilà! The internal representation of the number PI on the CPC is: 3,14159265346825122833251953125 

If you compare to a (more) correct representation of PI, you'll see that the CPC is correct up to the 9th decimal place: 

CPC: 
3.14159265346825122833251953125 
more correctly: 
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986...

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts. The biggest figure which can be stored correctly in RAM by a variable is 2^32-1 = 4294967295.

#A real variable is defined with a "!" character postfix.

e.g.
<pre>a! = 3.141592654
</pre>
#A real number uses 5 bytes of memory as storage. The format is described above.
#The address of a real variable can be found in BASIC by:
<pre>PRINT @a!
</pre>

Where "a" should be replaced with the name of the variable.

 

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

 NOTES:

#A integer variable is defined with a "%" character postfix.

e.g.
<pre>a% = 3
</pre>
#A integer variable has a range of -32768 to 32767
#A integer variable always uses two bytes of memory as storage with the following format:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 2
| Integer number
|}

#The address of the integer variable can be found in BASIC by: <pre>PRINT @a%
</pre>

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

 NOTES:

#A string variable is defined in BASIC with a "$" character postfix.

e.g.
<pre>a$ = "hello"
</pre>
#A string variable is described internally by a "string descriptor block" which has the following structure:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 1
| Length of string in bytes/characters
|-
| 1
| 2
| Location of start of string
|}

#The address of the "string descriptor block" for the string variable can be found in BASIC by typing: <pre>PRINT @a$
</pre>

replacing "a$" with the name of the string variable.

#A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
#A string variable can contain any ASCII character code in the range 0-255.
#A string variable can store a minimum of 0 characters and a maximum of 255 characters.
#The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Technical information about Locomotive BASIC

2025-08-24T10:21:58Z

Arnoldemu: /* BASIC floating-point/real variables */

[[Category:Cpctech.org]]

'''''This article originally came from Kevin Thackers' archive at [http://www.cpctech.org.uk http://www.cpctech.org.uk].'''''

= Technical information about Locomotive BASIC =

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== BASIC v1.0 only ==

There is a region of memory between AC00-AC1B which is filled with RET instructions. The BASIC ROM calls the following locations:
AC01,AC04,AC07,AC0A,AC0D,AC10,AC13,AC16,AC19

It almost looks like these were used for debugging the ROM but were left in.

They can be used to implement new BASIC commands.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR". A binary function is accessed through BASIC using the "CALL" command.

Both RSX and CALL commands work (are!) similar from the BASIC command line and invoke machine code - the only difference is: with the help of a RSX command you don't need to know the exact access address. You can pass up to 32 parameters with a CALL or RSX command. Possible parameters could be integer, floating points and strings. Just store the parameter into a variable:
Passing for integer:
<pre>
CALL &4000,32,34,&5E,&x10101010
|RSX-command,32,34,&5E,&x10101010
</pre>
Passing for floating points
<pre>
@a!=43.375
CALL or |RSX-command,@a!
</pre>

 Passing a string parameter:
 BASIC v1.0
<pre>a$="A":|DRIVE,@a$
</pre>
BASIC v1.1:
<pre>|DRIVE,"A"
</pre>
or
<pre>
b$="test"
CALL or |RSX-command,@b$
</pre>

The parameters will be stored inside the range of Stack:
<pre>
A=n -------> MSB PARAM1
LSB PARAM1
MSB PARAM2
LSB PARAM2
...
...
...
MSB PARAMn
IX+0 ------> LSB PARAMn
</pre>
with the help of that assembly code is it possible to find the parameters:
<pre>
ROUT1: CP x ;test register A if "x" parameters were given, e.g. x = 2
RET NZ ; if not exactly x parameters then do not execute RSX.
LD L,(IX+0)
LD H,(IX+1) ; HL = value of last parameter
LD E,(IX+2)
LD D,(IX+3) ; DE = value of next to last parameter
...
</pre>
A register holds the number of parameters. IX points to each parameter. IX+0/IX+1 is the last parameter. This happens because each parameter in order is pushed onto the stack and IX then points to the last parameter pushed. Each parameter is a 16-bit value.

If a parameter is a string, then IX holds the address of the string descriptor which point to a 3 byte block. The first byte of the string descriptor is the length. The next 2 bytes are an address that point to the string in memory.

With the help of the variable container "@" it is also possible to get a result from an invoked mc-code back to basic.
In this case the parameter contains the address of the integer, floating point or string. You can modify these to give the result.
BASIC allocates the strings, so when you modify a string, do not write more characters than the original string.

Hint: the first two bytes at the end of stack shows the internal return address from BASIC interpreter where it was executed.

== Additional keywords and variables in BASIC v1.1 ==

#BASIC v1.1 has the following additional keywords:
#*COPYCHR$
#*CURSOR
#*DEC$
#*FILL
#*FRAME
#*GRAPHICS
#*MASK
#BASIC v1.1 has the following additional predefined variables:
#*DERR

 

== BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

There are some rules for assigning names for variables:
: - it is not allowed to define a variable starting with a figure (the system expect then programming mode and interpret it as a program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - different sign e.g.: a slash (doesn't depend which direction), a 'minus' sign, a 'and' sign can't be used in a variable names
: - after a dollar sign (for defining string variables) it is not allowed to use further signs
: - different defining functions together are not allowed (e.g. use '%' together with '$')

: - you can use 40 characters for a variable name
: - use ! for defining a REAL value variable (like the function DEFREAL but only for the assigned variable) > It's also possible to omit the exlamation mark because it's the default system declaration after powering on then CPC.
: - use % for defining a INTEGER value variable (like the function DEFINT but only for the assigned variable)
: - use $ for defining a STRING variable (like the function DEFSTR but only for the assigned variable)
: - Minimum line number is 1. Maximum line number is 65535.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

 

== Speeding up BASIC programs ==

To speed up BASIC programs following rules could help:
: - Avoid loops or a branching program structure if possible. Internally the operating system searches for the right line number always from the beginning of the program 'listing'. Often recurring subroutines (if necessary) should be at the beginning of RAM to speed up things.
: - Avoid the index variable after the <code>NEXT</code> command/statement (although it isn't a good program style)
: - Avoid spaces inside program code or remarks
: - Put lots of statements as possible in ONE line
: - Use variables instead of constants. A constant has always to be converted in a binary/digital format. A variable is already converted.
: - Dimensioning at the beginning of the program
: - Dimensioning your variables & pre-calculate
: - Avoid AND/OR/XOR in IF-THEN statements. It's faster to write IF ... THEN (statement 1).. IF ... THEN (statement 2).
: - Minimise string/char manipulation as this often requires memory allocations. (e.g. joining strings with +, use of MID$, LEFT$, RIGHT$, SPACE$)

== Minimizing memory usage ==

To minimize memory usage in BASIC here are some things to consider.

The size of the tokenized program:
: - Difficult to measure without looking at the data in memory.
: - Use short variable names. The names are stored in the tokenized BASIC program as-is.
: - Minimize the number of variables. The names are stored in the tokenized BASIC program everywhere they are used.
: - Use as few lines as possible. It's a small saving of about 5 bytes per line.
: - Consider using numbers vs strings and potentially 8-bit or 16-bit values.

Minimising memory usage when the program is running:
: - Minimize string operations. (e.g. A$=SPACE$(30)+CHR$(28) in memory this first allocates a string of length 30 containing spaces, then it allocates a new string of length 31 with spaces and char 28 at the end and assigns it to A$. In this line at least 30 bytes have been wasted. So consider if you need strings or perhaps if possible pre-define them).

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences. Each line of the BASIC program has the form:

 

{| border="1"
|-
! Offset
! Size
! Description
|-
| 0
| 2
| Length of line data in bytes (note 1)
|-
| 2
| 2
| 16-bit decimal integer line number (note 2)
|-
| 4
| n
| BASIC line encoded into tokens (note 3)
|-
| n+1
| 1
| "0" the end of line marker (note 4)
|}

 Notes:

#This 16-bit value has two functions: if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data, otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
#This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
#This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
#This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| end of tokenised line marker
|-
| &01
| ":" statement seperator
|-
| &02
| integer variable definition (defined with "%" suffix)
|-
| &03
| string variable definition (defined with "$" suffix)
|-
| &04
| floating point variable definition (defined with "!" suffix)
|-
| &05
| var?
|-
| &06
| var?
|-
| &07
| var?
|-
| &08
| var?
|-
| &09
| var?
|-
| &0a
| var?
|-
| &0b
| variable definition (no suffix)
|-
| &0c
| variable definition (no suffix)
|-
| &0d
| variable definition (no suffix)
|-
| &0e
| number constant "0"
|-
| &0f
| number constant "1"
|-
| &10
| number constant "2"
|-
| &11
| number constant "3"
|-
| &12
| number constant "4"
|-
| &13
| number constant "5"
|-
| &14
| number constant "6"
|-
| &15
| number constant "7"
|-
| &16
| number constant "8"
|-
| &17
| number constant "9"
|-
| &18
| number constant "10"
|-
| &19
| 8-bit integer decimal value
|-
| &1a
| 16-bit integer decimal value
|-
| &1b
| 16-bit integer binary value (with "&X" prefix)
|-
| &1c
| 16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
| &1d
| 16-bit BASIC program line memory address pointer (see notes)
|-
| &1e
| 16-bit integer BASIC line number
|-
| &1f
| floating point value
|-
| &20
| " " (space) symbol
|-
| &21
| ASCII "!" symbol
|-
| &22
| quoted string value
|-
| &23-7b
| ASCII printable symbols
|-
| &7c
| "|" symbol; prefix for RSX commands
|-
| &80
| AFTER
|-
| &81
| AUTO
|-
| &82
| BORDER
|-
| &83
| CALL
|-
| &84
| CAT
|-
| &85
| CHAIN
|-
| &86
| CLEAR
|-
| &87
| CLG
|-
| &88
| CLOSEIN
|-
| &89
| CLOSEOUT
|-
| &8a
| CLS
|-
| &8b
| CONT
|-
| &8c
| DATA
|-
| &8d
| DEF
|-
| &8e
| DEFINT
|-
| &8f
| DEFREAL
|-
| &90
| DEFSTR
|-
| &91
| DEG
|-
| &92
| DELETE
|-
| &93
| DIM
|-
| &94
| DRAW
|-
| &95
| DRAWR
|-
| &96
| EDIT
|-
| &97
| ELSE
|-
| &98
| END
|-
| &99
| ENT
|-
| &9a
| ENV
|-
| &9b
| ERASE
|-
| &9c
| ERROR
|-
| &9d
| EVERY
|-
| &9e
| FOR
|-
| &9f
| GOSUB, GO SUB
|-
| &a0
| GOTO, GO TO
|-
| &a1
| IF
|-
| &a2
| INK
|-
| &a3
| INPUT
|-
| &a4
| KEY
|-
| &a5
| LET
|-
| &a6
| LINE
|-
| &a7
| LIST
|-
| &a8
| LOAD
|-
| &a9
| LOCATE
|-
| &aa
| MEMORY
|-
| &ab
| MERGE
|-
| &ac
| MID$
|-
| &ad
| MODE
|-
| &ae
| MOVE
|-
| &af
| MOVER
|-
| &b0
| NEXT
|-
| &b1
| NEW
|-
| &b2
| ON
|-
| &b3
| ON BREAK
|-
| &b4
| ON ERROR GOTO, ON ERROR GO TO
|-
| &b5
| ON SQ
|-
| &b6
| OPENIN
|-
| &b7
| OPENOUT
|-
| &b8
| ORIGIN
|-
| &b9
| OUT
|-
| &ba
| PAPER
|-
| &bb
| PEN
|-
| &bc
| PLOT
|-
| &bd
| PLOTR
|-
| &be
| POKE
|-
| &bf
| PRINT
|-
| &c0
| "'" symbol (same function as REM keyword)
|-
| &c1
| RAD
|-
| &c2
| RANDOMIZE
|-
| &c3
| READ
|-
| &c4
| RELEASE
|-
| &c5
| REM
|-
| &c6
| RENUM
|-
| &c7
| RESTORE
|-
| &c8
| RESUME
|-
| &c9
| RETURN
|-
| &ca
| RUN
|-
| &cb
| SAVE
|-
| &cc
| SOUND
|-
| &cd
| SPEED
|-
| &ce
| STOP
|-
| &cf
| SYMBOL
|-
| &d0
| TAG
|-
| &d1
| TAGOFF
|-
| &d2
| TROFF
|-
| &d3
| TRON
|-
| &d4
| WAIT
|-
| &d5
| WEND
|-
| &d6
| WHILE
|-
| &d7
| WIDTH
|-
| &d8
| WINDOW
|-
| &d9
| WRITE
|-
| &da
| ZONE
|-
| &db
| DI
|-
| &dc
| EI
|-
| &dd
| FILL (v1.1)
|-
| &de
| GRAPHICS (v1.1)
|-
| &df
| MASK (v1.1)
|-
| &e0
| FRAME (v1.1)
|-
| &e1
| CURSOR (v1.1)
|-
| &e2
| (note 2)
|-
| &e3
| ERL
|-
| &e4
| FN
|-
| &e5
| SPC
|-
| &e6
| STEP
|-
| &e7
| SWAP
|-
| &e8
| (note 2)
|-
| &e9
| (note 2)
|-
| &ea
| TAB
|-
| &eb
| THEN
|-
| &ec
| TO
|-
| &ed
| USING
|-
| &ee
| > (greater than)
|-
| &ef
| = (equal)
|-
| &f0
| &gt=, > =, => (greater or equal)
|-
| &f1
| < (less than)
|-
| &f2
| <&gt, < > (not equal)
|-
| &f3
| =<, <=, < = (less than or equal)
|-
| &f4
| + (addition)
|-
| &f5
| - (subtraction or unary minus)
|-
| &f6
| * (multiplication)
|-
| &f7
| / (division)
|-
| &f8
| ^ (x to the power of y)
|-
| &f9
| \ (integer division)
|-
| &fa
| AND
|-
| &fb
| MOD
|-
| &fc
| OR
|-
| &fd
| XOR
|-
| &fe
| NOT
|-
| &ff
| (prefix for additional keywords)
|}

 Notes:

*The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
*&e2,&e8 and &e9 are not used
*&7c ("|") is a character prefix used to identify an RSX command. e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| "|" character prefix
|-
| 1
| 1
| 8-bit byte offset to tokens following RSX name.
|-
| 2
| x
| RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
|}

*This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &1a,&2d,&00 represents the integer number "&002d"="45".
*This token (&0B) is changed at run-time to &0D
*This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
*This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
*This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| &1f (note 1)
|-
| 1
| 5
| Floating point number (note 2)
|}

*#This byte is the BASIC token identifying a floating point number
*#These 5 bytes define the floating point number.
*The space symbol is used as a command seperator
*Variable definitions:
**The variable definition has the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| Token defining variable type
|-
| 2
| 2
| 16-bit Byte offset to variable value within tokenised BASIC program.
|-
| 4
| x
| Variable name
|}

 The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.

**The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
**The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
*String values:
**Each string value is prefixed with &22 token.
**All strings must be enclosed by double quote symbols (&quot). This symbols define the start and end of the string value.
**The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.

*After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

 This table list the BASIC tokens with a &ff prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| ABS
|-
| &01
| ASC
|-
| &02
| ATN
|-
| &03
| CHR$
|-
| &04
| CINT
|-
| &05
| COS
|-
| &06
| CREAL
|-
| &07
| EXP
|-
| &08
| FIX
|-
| &09
| FRE
|-
| &0a
| INKEY
|-
| &0b
| INP
|-
| &0c
| INT
|-
| &0d
| JOY
|-
| &0e
| LEN
|-
| &0f
| LOG
|-
| &10
| LOG10
|-
| &11
| LOWER$
|-
| &12
| PEEK
|-
| &13
| REMAIN
|-
| &14
| SGN
|-
| &15
| SIN
|-
| &16
| SPACE$
|-
| &17
| SQ
|-
| &18
| SQR
|-
| &19
| STR$
|-
| &1a
| TAN
|-
| &1b
| UNT
|-
| &1c
| UPPER$
|-
| &1d
| VAL
|-
|  
| (note 2)
|-
| &40
| EOF
|-
| &41
| ERR
|-
| &42
| HIMEM
|-
| &43
| INKEY$
|-
| &44
| PI
|-
| &45
| RND
|-
| &46
| TIME
|-
| &47
| XPOS
|-
| &48
| YPOS
|-
| &49
| DERR (v1.1)
|-
|  
| (note 3)
|-
| &71
| BIN$
|-
| &72
| DEC$ (v1.1)
|-
| &73
| HEX$
|-
| &74
| INSTR
|-
| &75
| LEFT$
|-
| &76
| MAX
|-
| &77
| MIN
|-
| &78
| POS
|-
| &79
| RIGHT$
|-
| &7a
| ROUND
|-
| &7b
| STRING$
|-
| &7c
| TEST
|-
| &7d
| TESTR
|-
| &7e
| COPYCHR$ (v1.1)
|-
| &7f
| VPOS
|-
|  
| (note 4)
|}

 NOTES:

*These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence: <pre>&FF,&00</pre>
*Codes &1e...&3f inclusive are not used
*Codes &4a...&6f inclusive are not used
*Codes &80...&ff inclusive are not used

*When a BASIC program is in memory, the BASIC ROM can replace "16-bit BASIC program line number" tokens with "16-bit BASIC program line memory address pointer".

When a program is loaded or saved, there will only be "16-bit BASIC program line number" tokens followed by a 16-bit number of the line.

When a program is running, BASIC will replace the "16-bit BASIC program line number" with the "16-bit BASIC program line memory address pointer" token, and replace the 16-bit line number with the memory address of the start of that line.

It does this to avoid having to lookup the address of the line each time.

* When a REM or ' is seen, the characters following it are output directly (i.e. the bytes are not tokenized) until the end of line or a ':' is seen.

* When a BASIC program is listed each line is converted to a string (this includes the line number and the tokens converted to their strings). There is a maximum length for this string of 256 characters. This means that if the BASIC line is LISTed or EDITed, then the line will be displayed incorrectly with missing characters on the end. This is also noticed if you have a "10-liner" program that packs as much BASIC as possible into each line and renumber it so the line number has more digits.

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

 In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form: 1 x 2<exponent> The representation uses 5 bytes and is stored using the following structure:

 

{| border="1"
|-
! Byte
! colspan="8" | 0
! colspan="8" | 1
! colspan="8" | 2
! colspan="8" | 3
! colspan="8" | 4
|-
! Bit
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
|-
| Function
| colspan="8" | (LSB) mantissa (bits 31-24)
| colspan="8" | mantissa (bits 23-16)
| colspan="8" | mantissa (bits 15-8)
| colspan="1" | sign
| colspan="7" | (MSB) mantissa (bits 7-0)
| colspan="8" | exponent
|}

=== Sign ===

The sign is represented by bit 7 of byte 3. The value of the sign bit indicates the sign of the floating point number.

#*If the sign bit is "1", then the number is negative.
#*If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4. It is stored with a bias of 128.

#*128-255 are positive exponents,
#*1-127 are negative exponents.
#*0 means, the number is zero

To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 1 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^127.
A value of 0 just means, that the number is zero (0).

=== BASIC Display of Floating point numbers ===

* Numbers are displayed to 9 decimal places.
* If the number doesn't have a fractional part (e.g. .0) then the fractional part is not displayed.
* Trailing zeros (zero digits after the last digit in the fraction) are not displayed
* The value is rounded in the following way for display:

If the 10th fractional digit is 5 or above, then the number is rounded up.
If the 10th fractional digit is 4 or below, then the number is rounded down.
e.g.
0.1234567891 is displayed as 0.123456789
0.1234567895 is displayed as 0.12345679

=== floating point example in RAM by MaV ===

The initial figure = 43.375.
An example in BASIC:
<pre>
a!=43.375
READY
PRINT a!
43.375
PRINT @a!
374
FOR I=0 TO 4:PRINT HEX$(PEEK(374+I),2);:NEXT I
0000802D86
</pre>
the result for better readability: 
'''00 00 80 2D 86''' 
The first byte contains the least significant bits of the mantissa, and every following byte up to the fourth byte contain the bits following the first in significance and in exactly that order!

That means that you have to turn around the first four bytes if you want to read the mantissa correctly:
2D800000
or
0010.1101.1000.0000.0000.0000.0000.0000
in binary (the stops are inserted for better readability).

Now the highest significant bit here is 0, so the number is positive.
What's more, you need to clear that bit and substitute the implied highest bit (see description in the link), which is always 1 (regardless of the deleted sign bit!!!).
Thus you get:
AD800000
or
1010.1101.1000.0000.0000.0000.0000.0000
in binary.

The mantissa has an implied decimal point before the number. Since the number is 2^32 bits (i.e. 4 bytes) long you have to divide by 2^32 to get the proper decimal representation.

AD800000 (hex) = 2910846976 (dec)

2910846976 / 2^32 = 0.677734375

The mantissa in a decimal representation is: 0.677734375

Now, the last byte contains the exponent: 86 (hex) or 134 (dec). You need to subtract 128 to get the real exponent, the highest bit tells you that the exponent is positive (1) or negative (0). Your exponent is 6.

0.677734375 * 2^6 = 43.375

'''Another example:''' 
PI is represented in memory as: 
'''A2 DA 0F 49 82''' 
The mantissa is 
490FDAA2 (highest significant bit is zero => number is positive)
The exponent is 
82 (=positive mantissa, value=2 thus multiply mantissa with 2^2) 

Delete the sign bit (which is 0 anyway), and then add the implied 1 bit: 
C90FDAA2 (hex) = 3373259426 (dec) = 1100.1001.0000.1111.1101.1010.1010.0010 (bin) 

Calculate the decimal representation of the mantissa: 
3373259426 / 2^32 = 0,7853981633670628070831298828125 

Then add the exponent (82h - 80h = 2 thus 2^2) 
0,7853981633670628070831298828125 * 2^2 = 3,14159265346825122833251953125 

Voilà! The internal representation of the number PI on the CPC is: 3,14159265346825122833251953125 

If you compare to a (more) correct representation of PI, you'll see that the CPC is correct up to the 9th decimal place: 

CPC: 
3.14159265346825122833251953125 
more correctly: 
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986...

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts. The biggest figure which can be stored correctly in RAM by a variable is 2^32-1 = 4294967295.

#A real variable is defined with a "!" character postfix.

e.g.
<pre>a! = 3.141592654
</pre>
#A real number uses 5 bytes of memory as storage. The format is described above.
#The address of a real variable can be found in BASIC by: <pre>PRINT @a!
</pre>

Where "a" should be replaced with the name of the variable.

 

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

 NOTES:

#A integer variable is defined with a "%" character postfix.

e.g.
<pre>a% = 3
</pre>
#A integer variable has a range of -32768 to 32767
#A integer variable always uses two bytes of memory as storage with the following format:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 2
| Integer number
|}

#The address of the integer variable can be found in BASIC by: <pre>PRINT @a%
</pre>

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

 NOTES:

#A string variable is defined in BASIC with a "$" character postfix.

e.g.
<pre>a$ = "hello"
</pre>
#A string variable is described internally by a "string descriptor block" which has the following structure:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 1
| Length of string in bytes/characters
|-
| 1
| 2
| Location of start of string
|}

#The address of the "string descriptor block" for the string variable can be found in BASIC by typing: <pre>PRINT @a$
</pre>

replacing "a$" with the name of the string variable.

#A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
#A string variable can contain any ASCII character code in the range 0-255.
#A string variable can store a minimum of 0 characters and a maximum of 255 characters.
#The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Technical information about Locomotive BASIC

2025-08-24T10:21:47Z

Arnoldemu: /* BASIC integer variables */

[[Category:Cpctech.org]]

'''''This article originally came from Kevin Thackers' archive at [http://www.cpctech.org.uk http://www.cpctech.org.uk].'''''

= Technical information about Locomotive BASIC =

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== BASIC v1.0 only ==

There is a region of memory between AC00-AC1B which is filled with RET instructions. The BASIC ROM calls the following locations:
AC01,AC04,AC07,AC0A,AC0D,AC10,AC13,AC16,AC19

It almost looks like these were used for debugging the ROM but were left in.

They can be used to implement new BASIC commands.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR". A binary function is accessed through BASIC using the "CALL" command.

Both RSX and CALL commands work (are!) similar from the BASIC command line and invoke machine code - the only difference is: with the help of a RSX command you don't need to know the exact access address. You can pass up to 32 parameters with a CALL or RSX command. Possible parameters could be integer, floating points and strings. Just store the parameter into a variable:
Passing for integer:
<pre>
CALL &4000,32,34,&5E,&x10101010
|RSX-command,32,34,&5E,&x10101010
</pre>
Passing for floating points
<pre>
@a!=43.375
CALL or |RSX-command,@a!
</pre>

 Passing a string parameter:
 BASIC v1.0
<pre>a$="A":|DRIVE,@a$
</pre>
BASIC v1.1:
<pre>|DRIVE,"A"
</pre>
or
<pre>
b$="test"
CALL or |RSX-command,@b$
</pre>

The parameters will be stored inside the range of Stack:
<pre>
A=n -------> MSB PARAM1
LSB PARAM1
MSB PARAM2
LSB PARAM2
...
...
...
MSB PARAMn
IX+0 ------> LSB PARAMn
</pre>
with the help of that assembly code is it possible to find the parameters:
<pre>
ROUT1: CP x ;test register A if "x" parameters were given, e.g. x = 2
RET NZ ; if not exactly x parameters then do not execute RSX.
LD L,(IX+0)
LD H,(IX+1) ; HL = value of last parameter
LD E,(IX+2)
LD D,(IX+3) ; DE = value of next to last parameter
...
</pre>
A register holds the number of parameters. IX points to each parameter. IX+0/IX+1 is the last parameter. This happens because each parameter in order is pushed onto the stack and IX then points to the last parameter pushed. Each parameter is a 16-bit value.

If a parameter is a string, then IX holds the address of the string descriptor which point to a 3 byte block. The first byte of the string descriptor is the length. The next 2 bytes are an address that point to the string in memory.

With the help of the variable container "@" it is also possible to get a result from an invoked mc-code back to basic.
In this case the parameter contains the address of the integer, floating point or string. You can modify these to give the result.
BASIC allocates the strings, so when you modify a string, do not write more characters than the original string.

Hint: the first two bytes at the end of stack shows the internal return address from BASIC interpreter where it was executed.

== Additional keywords and variables in BASIC v1.1 ==

#BASIC v1.1 has the following additional keywords:
#*COPYCHR$
#*CURSOR
#*DEC$
#*FILL
#*FRAME
#*GRAPHICS
#*MASK
#BASIC v1.1 has the following additional predefined variables:
#*DERR

 

== BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

There are some rules for assigning names for variables:
: - it is not allowed to define a variable starting with a figure (the system expect then programming mode and interpret it as a program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - different sign e.g.: a slash (doesn't depend which direction), a 'minus' sign, a 'and' sign can't be used in a variable names
: - after a dollar sign (for defining string variables) it is not allowed to use further signs
: - different defining functions together are not allowed (e.g. use '%' together with '$')

: - you can use 40 characters for a variable name
: - use ! for defining a REAL value variable (like the function DEFREAL but only for the assigned variable) > It's also possible to omit the exlamation mark because it's the default system declaration after powering on then CPC.
: - use % for defining a INTEGER value variable (like the function DEFINT but only for the assigned variable)
: - use $ for defining a STRING variable (like the function DEFSTR but only for the assigned variable)
: - Minimum line number is 1. Maximum line number is 65535.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

 

== Speeding up BASIC programs ==

To speed up BASIC programs following rules could help:
: - Avoid loops or a branching program structure if possible. Internally the operating system searches for the right line number always from the beginning of the program 'listing'. Often recurring subroutines (if necessary) should be at the beginning of RAM to speed up things.
: - Avoid the index variable after the <code>NEXT</code> command/statement (although it isn't a good program style)
: - Avoid spaces inside program code or remarks
: - Put lots of statements as possible in ONE line
: - Use variables instead of constants. A constant has always to be converted in a binary/digital format. A variable is already converted.
: - Dimensioning at the beginning of the program
: - Dimensioning your variables & pre-calculate
: - Avoid AND/OR/XOR in IF-THEN statements. It's faster to write IF ... THEN (statement 1).. IF ... THEN (statement 2).
: - Minimise string/char manipulation as this often requires memory allocations. (e.g. joining strings with +, use of MID$, LEFT$, RIGHT$, SPACE$)

== Minimizing memory usage ==

To minimize memory usage in BASIC here are some things to consider.

The size of the tokenized program:
: - Difficult to measure without looking at the data in memory.
: - Use short variable names. The names are stored in the tokenized BASIC program as-is.
: - Minimize the number of variables. The names are stored in the tokenized BASIC program everywhere they are used.
: - Use as few lines as possible. It's a small saving of about 5 bytes per line.
: - Consider using numbers vs strings and potentially 8-bit or 16-bit values.

Minimising memory usage when the program is running:
: - Minimize string operations. (e.g. A$=SPACE$(30)+CHR$(28) in memory this first allocates a string of length 30 containing spaces, then it allocates a new string of length 31 with spaces and char 28 at the end and assigns it to A$. In this line at least 30 bytes have been wasted. So consider if you need strings or perhaps if possible pre-define them).

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences. Each line of the BASIC program has the form:

 

{| border="1"
|-
! Offset
! Size
! Description
|-
| 0
| 2
| Length of line data in bytes (note 1)
|-
| 2
| 2
| 16-bit decimal integer line number (note 2)
|-
| 4
| n
| BASIC line encoded into tokens (note 3)
|-
| n+1
| 1
| "0" the end of line marker (note 4)
|}

 Notes:

#This 16-bit value has two functions: if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data, otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
#This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
#This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
#This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| end of tokenised line marker
|-
| &01
| ":" statement seperator
|-
| &02
| integer variable definition (defined with "%" suffix)
|-
| &03
| string variable definition (defined with "$" suffix)
|-
| &04
| floating point variable definition (defined with "!" suffix)
|-
| &05
| var?
|-
| &06
| var?
|-
| &07
| var?
|-
| &08
| var?
|-
| &09
| var?
|-
| &0a
| var?
|-
| &0b
| variable definition (no suffix)
|-
| &0c
| variable definition (no suffix)
|-
| &0d
| variable definition (no suffix)
|-
| &0e
| number constant "0"
|-
| &0f
| number constant "1"
|-
| &10
| number constant "2"
|-
| &11
| number constant "3"
|-
| &12
| number constant "4"
|-
| &13
| number constant "5"
|-
| &14
| number constant "6"
|-
| &15
| number constant "7"
|-
| &16
| number constant "8"
|-
| &17
| number constant "9"
|-
| &18
| number constant "10"
|-
| &19
| 8-bit integer decimal value
|-
| &1a
| 16-bit integer decimal value
|-
| &1b
| 16-bit integer binary value (with "&X" prefix)
|-
| &1c
| 16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
| &1d
| 16-bit BASIC program line memory address pointer (see notes)
|-
| &1e
| 16-bit integer BASIC line number
|-
| &1f
| floating point value
|-
| &20
| " " (space) symbol
|-
| &21
| ASCII "!" symbol
|-
| &22
| quoted string value
|-
| &23-7b
| ASCII printable symbols
|-
| &7c
| "|" symbol; prefix for RSX commands
|-
| &80
| AFTER
|-
| &81
| AUTO
|-
| &82
| BORDER
|-
| &83
| CALL
|-
| &84
| CAT
|-
| &85
| CHAIN
|-
| &86
| CLEAR
|-
| &87
| CLG
|-
| &88
| CLOSEIN
|-
| &89
| CLOSEOUT
|-
| &8a
| CLS
|-
| &8b
| CONT
|-
| &8c
| DATA
|-
| &8d
| DEF
|-
| &8e
| DEFINT
|-
| &8f
| DEFREAL
|-
| &90
| DEFSTR
|-
| &91
| DEG
|-
| &92
| DELETE
|-
| &93
| DIM
|-
| &94
| DRAW
|-
| &95
| DRAWR
|-
| &96
| EDIT
|-
| &97
| ELSE
|-
| &98
| END
|-
| &99
| ENT
|-
| &9a
| ENV
|-
| &9b
| ERASE
|-
| &9c
| ERROR
|-
| &9d
| EVERY
|-
| &9e
| FOR
|-
| &9f
| GOSUB, GO SUB
|-
| &a0
| GOTO, GO TO
|-
| &a1
| IF
|-
| &a2
| INK
|-
| &a3
| INPUT
|-
| &a4
| KEY
|-
| &a5
| LET
|-
| &a6
| LINE
|-
| &a7
| LIST
|-
| &a8
| LOAD
|-
| &a9
| LOCATE
|-
| &aa
| MEMORY
|-
| &ab
| MERGE
|-
| &ac
| MID$
|-
| &ad
| MODE
|-
| &ae
| MOVE
|-
| &af
| MOVER
|-
| &b0
| NEXT
|-
| &b1
| NEW
|-
| &b2
| ON
|-
| &b3
| ON BREAK
|-
| &b4
| ON ERROR GOTO, ON ERROR GO TO
|-
| &b5
| ON SQ
|-
| &b6
| OPENIN
|-
| &b7
| OPENOUT
|-
| &b8
| ORIGIN
|-
| &b9
| OUT
|-
| &ba
| PAPER
|-
| &bb
| PEN
|-
| &bc
| PLOT
|-
| &bd
| PLOTR
|-
| &be
| POKE
|-
| &bf
| PRINT
|-
| &c0
| "'" symbol (same function as REM keyword)
|-
| &c1
| RAD
|-
| &c2
| RANDOMIZE
|-
| &c3
| READ
|-
| &c4
| RELEASE
|-
| &c5
| REM
|-
| &c6
| RENUM
|-
| &c7
| RESTORE
|-
| &c8
| RESUME
|-
| &c9
| RETURN
|-
| &ca
| RUN
|-
| &cb
| SAVE
|-
| &cc
| SOUND
|-
| &cd
| SPEED
|-
| &ce
| STOP
|-
| &cf
| SYMBOL
|-
| &d0
| TAG
|-
| &d1
| TAGOFF
|-
| &d2
| TROFF
|-
| &d3
| TRON
|-
| &d4
| WAIT
|-
| &d5
| WEND
|-
| &d6
| WHILE
|-
| &d7
| WIDTH
|-
| &d8
| WINDOW
|-
| &d9
| WRITE
|-
| &da
| ZONE
|-
| &db
| DI
|-
| &dc
| EI
|-
| &dd
| FILL (v1.1)
|-
| &de
| GRAPHICS (v1.1)
|-
| &df
| MASK (v1.1)
|-
| &e0
| FRAME (v1.1)
|-
| &e1
| CURSOR (v1.1)
|-
| &e2
| (note 2)
|-
| &e3
| ERL
|-
| &e4
| FN
|-
| &e5
| SPC
|-
| &e6
| STEP
|-
| &e7
| SWAP
|-
| &e8
| (note 2)
|-
| &e9
| (note 2)
|-
| &ea
| TAB
|-
| &eb
| THEN
|-
| &ec
| TO
|-
| &ed
| USING
|-
| &ee
| > (greater than)
|-
| &ef
| = (equal)
|-
| &f0
| &gt=, > =, => (greater or equal)
|-
| &f1
| < (less than)
|-
| &f2
| <&gt, < > (not equal)
|-
| &f3
| =<, <=, < = (less than or equal)
|-
| &f4
| + (addition)
|-
| &f5
| - (subtraction or unary minus)
|-
| &f6
| * (multiplication)
|-
| &f7
| / (division)
|-
| &f8
| ^ (x to the power of y)
|-
| &f9
| \ (integer division)
|-
| &fa
| AND
|-
| &fb
| MOD
|-
| &fc
| OR
|-
| &fd
| XOR
|-
| &fe
| NOT
|-
| &ff
| (prefix for additional keywords)
|}

 Notes:

*The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
*&e2,&e8 and &e9 are not used
*&7c ("|") is a character prefix used to identify an RSX command. e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| "|" character prefix
|-
| 1
| 1
| 8-bit byte offset to tokens following RSX name.
|-
| 2
| x
| RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
|}

*This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &1a,&2d,&00 represents the integer number "&002d"="45".
*This token (&0B) is changed at run-time to &0D
*This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
*This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
*This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| &1f (note 1)
|-
| 1
| 5
| Floating point number (note 2)
|}

*#This byte is the BASIC token identifying a floating point number
*#These 5 bytes define the floating point number.
*The space symbol is used as a command seperator
*Variable definitions:
**The variable definition has the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| Token defining variable type
|-
| 2
| 2
| 16-bit Byte offset to variable value within tokenised BASIC program.
|-
| 4
| x
| Variable name
|}

 The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.

**The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
**The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
*String values:
**Each string value is prefixed with &22 token.
**All strings must be enclosed by double quote symbols (&quot). This symbols define the start and end of the string value.
**The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.

*After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

 This table list the BASIC tokens with a &ff prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| ABS
|-
| &01
| ASC
|-
| &02
| ATN
|-
| &03
| CHR$
|-
| &04
| CINT
|-
| &05
| COS
|-
| &06
| CREAL
|-
| &07
| EXP
|-
| &08
| FIX
|-
| &09
| FRE
|-
| &0a
| INKEY
|-
| &0b
| INP
|-
| &0c
| INT
|-
| &0d
| JOY
|-
| &0e
| LEN
|-
| &0f
| LOG
|-
| &10
| LOG10
|-
| &11
| LOWER$
|-
| &12
| PEEK
|-
| &13
| REMAIN
|-
| &14
| SGN
|-
| &15
| SIN
|-
| &16
| SPACE$
|-
| &17
| SQ
|-
| &18
| SQR
|-
| &19
| STR$
|-
| &1a
| TAN
|-
| &1b
| UNT
|-
| &1c
| UPPER$
|-
| &1d
| VAL
|-
|  
| (note 2)
|-
| &40
| EOF
|-
| &41
| ERR
|-
| &42
| HIMEM
|-
| &43
| INKEY$
|-
| &44
| PI
|-
| &45
| RND
|-
| &46
| TIME
|-
| &47
| XPOS
|-
| &48
| YPOS
|-
| &49
| DERR (v1.1)
|-
|  
| (note 3)
|-
| &71
| BIN$
|-
| &72
| DEC$ (v1.1)
|-
| &73
| HEX$
|-
| &74
| INSTR
|-
| &75
| LEFT$
|-
| &76
| MAX
|-
| &77
| MIN
|-
| &78
| POS
|-
| &79
| RIGHT$
|-
| &7a
| ROUND
|-
| &7b
| STRING$
|-
| &7c
| TEST
|-
| &7d
| TESTR
|-
| &7e
| COPYCHR$ (v1.1)
|-
| &7f
| VPOS
|-
|  
| (note 4)
|}

 NOTES:

*These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence: <pre>&FF,&00</pre>
*Codes &1e...&3f inclusive are not used
*Codes &4a...&6f inclusive are not used
*Codes &80...&ff inclusive are not used

*When a BASIC program is in memory, the BASIC ROM can replace "16-bit BASIC program line number" tokens with "16-bit BASIC program line memory address pointer".

When a program is loaded or saved, there will only be "16-bit BASIC program line number" tokens followed by a 16-bit number of the line.

When a program is running, BASIC will replace the "16-bit BASIC program line number" with the "16-bit BASIC program line memory address pointer" token, and replace the 16-bit line number with the memory address of the start of that line.

It does this to avoid having to lookup the address of the line each time.

* When a REM or ' is seen, the characters following it are output directly (i.e. the bytes are not tokenized) until the end of line or a ':' is seen.

* When a BASIC program is listed each line is converted to a string (this includes the line number and the tokens converted to their strings). There is a maximum length for this string of 256 characters. This means that if the BASIC line is LISTed or EDITed, then the line will be displayed incorrectly with missing characters on the end. This is also noticed if you have a "10-liner" program that packs as much BASIC as possible into each line and renumber it so the line number has more digits.

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

 In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form: 1 x 2<exponent> The representation uses 5 bytes and is stored using the following structure:

 

{| border="1"
|-
! Byte
! colspan="8" | 0
! colspan="8" | 1
! colspan="8" | 2
! colspan="8" | 3
! colspan="8" | 4
|-
! Bit
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
|-
| Function
| colspan="8" | (LSB) mantissa (bits 31-24)
| colspan="8" | mantissa (bits 23-16)
| colspan="8" | mantissa (bits 15-8)
| colspan="1" | sign
| colspan="7" | (MSB) mantissa (bits 7-0)
| colspan="8" | exponent
|}

=== Sign ===

The sign is represented by bit 7 of byte 3. The value of the sign bit indicates the sign of the floating point number.

#*If the sign bit is "1", then the number is negative.
#*If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4. It is stored with a bias of 128.

#*128-255 are positive exponents,
#*1-127 are negative exponents.
#*0 means, the number is zero

To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 1 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^127.
A value of 0 just means, that the number is zero (0).

=== BASIC Display of Floating point numbers ===

* Numbers are displayed to 9 decimal places.
* If the number doesn't have a fractional part (e.g. .0) then the fractional part is not displayed.
* Trailing zeros (zero digits after the last digit in the fraction) are not displayed
* The value is rounded in the following way for display:

If the 10th fractional digit is 5 or above, then the number is rounded up.
If the 10th fractional digit is 4 or below, then the number is rounded down.
e.g.
0.1234567891 is displayed as 0.123456789
0.1234567895 is displayed as 0.12345679

=== floating point example in RAM by MaV ===

The initial figure = 43.375.
An example in BASIC:
<pre>
a!=43.375
READY
PRINT a!
43.375
PRINT @a!
374
FOR I=0 TO 4:PRINT HEX$(PEEK(374+I),2);:NEXT I
0000802D86
</pre>
the result for better readability: 
'''00 00 80 2D 86''' 
The first byte contains the least significant bits of the mantissa, and every following byte up to the fourth byte contain the bits following the first in significance and in exactly that order!

That means that you have to turn around the first four bytes if you want to read the mantissa correctly:
2D800000
or
0010.1101.1000.0000.0000.0000.0000.0000
in binary (the stops are inserted for better readability).

Now the highest significant bit here is 0, so the number is positive.
What's more, you need to clear that bit and substitute the implied highest bit (see description in the link), which is always 1 (regardless of the deleted sign bit!!!).
Thus you get:
AD800000
or
1010.1101.1000.0000.0000.0000.0000.0000
in binary.

The mantissa has an implied decimal point before the number. Since the number is 2^32 bits (i.e. 4 bytes) long you have to divide by 2^32 to get the proper decimal representation.

AD800000 (hex) = 2910846976 (dec)

2910846976 / 2^32 = 0.677734375

The mantissa in a decimal representation is: 0.677734375

Now, the last byte contains the exponent: 86 (hex) or 134 (dec). You need to subtract 128 to get the real exponent, the highest bit tells you that the exponent is positive (1) or negative (0). Your exponent is 6.

0.677734375 * 2^6 = 43.375

'''Another example:''' 
PI is represented in memory as: 
'''A2 DA 0F 49 82''' 
The mantissa is 
490FDAA2 (highest significant bit is zero => number is positive)
The exponent is 
82 (=positive mantissa, value=2 thus multiply mantissa with 2^2) 

Delete the sign bit (which is 0 anyway), and then add the implied 1 bit: 
C90FDAA2 (hex) = 3373259426 (dec) = 1100.1001.0000.1111.1101.1010.1010.0010 (bin) 

Calculate the decimal representation of the mantissa: 
3373259426 / 2^32 = 0,7853981633670628070831298828125 

Then add the exponent (82h - 80h = 2 thus 2^2) 
0,7853981633670628070831298828125 * 2^2 = 3,14159265346825122833251953125 

Voilà! The internal representation of the number PI on the CPC is: 3,14159265346825122833251953125 

If you compare to a (more) correct representation of PI, you'll see that the CPC is correct up to the 9th decimal place: 

CPC: 
3.14159265346825122833251953125 
more correctly: 
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986...

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts. The biggest figure which can be stored correctly in RAM by a variable is 2^32-1 = 4294967295.

#*A real variable is defined with a "!" character postfix.

e.g.
<pre>a! = 3.141592654
</pre>
#*A real number uses 5 bytes of memory as storage. The format is described above.
#*The address of a real variable can be found in BASIC by: <pre>PRINT @a!
</pre>

Where "a" should be replaced with the name of the variable.

 

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

 NOTES:

#A integer variable is defined with a "%" character postfix.

e.g.
<pre>a% = 3
</pre>
#A integer variable has a range of -32768 to 32767
#A integer variable always uses two bytes of memory as storage with the following format:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 2
| Integer number
|}

#The address of the integer variable can be found in BASIC by: <pre>PRINT @a%
</pre>

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

 NOTES:

#A string variable is defined in BASIC with a "$" character postfix.

e.g.
<pre>a$ = "hello"
</pre>
#A string variable is described internally by a "string descriptor block" which has the following structure:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 1
| Length of string in bytes/characters
|-
| 1
| 2
| Location of start of string
|}

#The address of the "string descriptor block" for the string variable can be found in BASIC by typing: <pre>PRINT @a$
</pre>

replacing "a$" with the name of the string variable.

#A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
#A string variable can contain any ASCII character code in the range 0-255.
#A string variable can store a minimum of 0 characters and a maximum of 255 characters.
#The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Technical information about Locomotive BASIC

2025-08-24T10:21:32Z

Arnoldemu: /* BASIC string variables */

[[Category:Cpctech.org]]

'''''This article originally came from Kevin Thackers' archive at [http://www.cpctech.org.uk http://www.cpctech.org.uk].'''''

= Technical information about Locomotive BASIC =

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== BASIC v1.0 only ==

There is a region of memory between AC00-AC1B which is filled with RET instructions. The BASIC ROM calls the following locations:
AC01,AC04,AC07,AC0A,AC0D,AC10,AC13,AC16,AC19

It almost looks like these were used for debugging the ROM but were left in.

They can be used to implement new BASIC commands.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR". A binary function is accessed through BASIC using the "CALL" command.

Both RSX and CALL commands work (are!) similar from the BASIC command line and invoke machine code - the only difference is: with the help of a RSX command you don't need to know the exact access address. You can pass up to 32 parameters with a CALL or RSX command. Possible parameters could be integer, floating points and strings. Just store the parameter into a variable:
Passing for integer:
<pre>
CALL &4000,32,34,&5E,&x10101010
|RSX-command,32,34,&5E,&x10101010
</pre>
Passing for floating points
<pre>
@a!=43.375
CALL or |RSX-command,@a!
</pre>

 Passing a string parameter:
 BASIC v1.0
<pre>a$="A":|DRIVE,@a$
</pre>
BASIC v1.1:
<pre>|DRIVE,"A"
</pre>
or
<pre>
b$="test"
CALL or |RSX-command,@b$
</pre>

The parameters will be stored inside the range of Stack:
<pre>
A=n -------> MSB PARAM1
LSB PARAM1
MSB PARAM2
LSB PARAM2
...
...
...
MSB PARAMn
IX+0 ------> LSB PARAMn
</pre>
with the help of that assembly code is it possible to find the parameters:
<pre>
ROUT1: CP x ;test register A if "x" parameters were given, e.g. x = 2
RET NZ ; if not exactly x parameters then do not execute RSX.
LD L,(IX+0)
LD H,(IX+1) ; HL = value of last parameter
LD E,(IX+2)
LD D,(IX+3) ; DE = value of next to last parameter
...
</pre>
A register holds the number of parameters. IX points to each parameter. IX+0/IX+1 is the last parameter. This happens because each parameter in order is pushed onto the stack and IX then points to the last parameter pushed. Each parameter is a 16-bit value.

If a parameter is a string, then IX holds the address of the string descriptor which point to a 3 byte block. The first byte of the string descriptor is the length. The next 2 bytes are an address that point to the string in memory.

With the help of the variable container "@" it is also possible to get a result from an invoked mc-code back to basic.
In this case the parameter contains the address of the integer, floating point or string. You can modify these to give the result.
BASIC allocates the strings, so when you modify a string, do not write more characters than the original string.

Hint: the first two bytes at the end of stack shows the internal return address from BASIC interpreter where it was executed.

== Additional keywords and variables in BASIC v1.1 ==

#BASIC v1.1 has the following additional keywords:
#*COPYCHR$
#*CURSOR
#*DEC$
#*FILL
#*FRAME
#*GRAPHICS
#*MASK
#BASIC v1.1 has the following additional predefined variables:
#*DERR

 

== BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

There are some rules for assigning names for variables:
: - it is not allowed to define a variable starting with a figure (the system expect then programming mode and interpret it as a program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - different sign e.g.: a slash (doesn't depend which direction), a 'minus' sign, a 'and' sign can't be used in a variable names
: - after a dollar sign (for defining string variables) it is not allowed to use further signs
: - different defining functions together are not allowed (e.g. use '%' together with '$')

: - you can use 40 characters for a variable name
: - use ! for defining a REAL value variable (like the function DEFREAL but only for the assigned variable) > It's also possible to omit the exlamation mark because it's the default system declaration after powering on then CPC.
: - use % for defining a INTEGER value variable (like the function DEFINT but only for the assigned variable)
: - use $ for defining a STRING variable (like the function DEFSTR but only for the assigned variable)
: - Minimum line number is 1. Maximum line number is 65535.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

 

== Speeding up BASIC programs ==

To speed up BASIC programs following rules could help:
: - Avoid loops or a branching program structure if possible. Internally the operating system searches for the right line number always from the beginning of the program 'listing'. Often recurring subroutines (if necessary) should be at the beginning of RAM to speed up things.
: - Avoid the index variable after the <code>NEXT</code> command/statement (although it isn't a good program style)
: - Avoid spaces inside program code or remarks
: - Put lots of statements as possible in ONE line
: - Use variables instead of constants. A constant has always to be converted in a binary/digital format. A variable is already converted.
: - Dimensioning at the beginning of the program
: - Dimensioning your variables & pre-calculate
: - Avoid AND/OR/XOR in IF-THEN statements. It's faster to write IF ... THEN (statement 1).. IF ... THEN (statement 2).
: - Minimise string/char manipulation as this often requires memory allocations. (e.g. joining strings with +, use of MID$, LEFT$, RIGHT$, SPACE$)

== Minimizing memory usage ==

To minimize memory usage in BASIC here are some things to consider.

The size of the tokenized program:
: - Difficult to measure without looking at the data in memory.
: - Use short variable names. The names are stored in the tokenized BASIC program as-is.
: - Minimize the number of variables. The names are stored in the tokenized BASIC program everywhere they are used.
: - Use as few lines as possible. It's a small saving of about 5 bytes per line.
: - Consider using numbers vs strings and potentially 8-bit or 16-bit values.

Minimising memory usage when the program is running:
: - Minimize string operations. (e.g. A$=SPACE$(30)+CHR$(28) in memory this first allocates a string of length 30 containing spaces, then it allocates a new string of length 31 with spaces and char 28 at the end and assigns it to A$. In this line at least 30 bytes have been wasted. So consider if you need strings or perhaps if possible pre-define them).

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences. Each line of the BASIC program has the form:

 

{| border="1"
|-
! Offset
! Size
! Description
|-
| 0
| 2
| Length of line data in bytes (note 1)
|-
| 2
| 2
| 16-bit decimal integer line number (note 2)
|-
| 4
| n
| BASIC line encoded into tokens (note 3)
|-
| n+1
| 1
| "0" the end of line marker (note 4)
|}

 Notes:

#This 16-bit value has two functions: if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data, otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
#This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
#This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
#This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| end of tokenised line marker
|-
| &01
| ":" statement seperator
|-
| &02
| integer variable definition (defined with "%" suffix)
|-
| &03
| string variable definition (defined with "$" suffix)
|-
| &04
| floating point variable definition (defined with "!" suffix)
|-
| &05
| var?
|-
| &06
| var?
|-
| &07
| var?
|-
| &08
| var?
|-
| &09
| var?
|-
| &0a
| var?
|-
| &0b
| variable definition (no suffix)
|-
| &0c
| variable definition (no suffix)
|-
| &0d
| variable definition (no suffix)
|-
| &0e
| number constant "0"
|-
| &0f
| number constant "1"
|-
| &10
| number constant "2"
|-
| &11
| number constant "3"
|-
| &12
| number constant "4"
|-
| &13
| number constant "5"
|-
| &14
| number constant "6"
|-
| &15
| number constant "7"
|-
| &16
| number constant "8"
|-
| &17
| number constant "9"
|-
| &18
| number constant "10"
|-
| &19
| 8-bit integer decimal value
|-
| &1a
| 16-bit integer decimal value
|-
| &1b
| 16-bit integer binary value (with "&X" prefix)
|-
| &1c
| 16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
| &1d
| 16-bit BASIC program line memory address pointer (see notes)
|-
| &1e
| 16-bit integer BASIC line number
|-
| &1f
| floating point value
|-
| &20
| " " (space) symbol
|-
| &21
| ASCII "!" symbol
|-
| &22
| quoted string value
|-
| &23-7b
| ASCII printable symbols
|-
| &7c
| "|" symbol; prefix for RSX commands
|-
| &80
| AFTER
|-
| &81
| AUTO
|-
| &82
| BORDER
|-
| &83
| CALL
|-
| &84
| CAT
|-
| &85
| CHAIN
|-
| &86
| CLEAR
|-
| &87
| CLG
|-
| &88
| CLOSEIN
|-
| &89
| CLOSEOUT
|-
| &8a
| CLS
|-
| &8b
| CONT
|-
| &8c
| DATA
|-
| &8d
| DEF
|-
| &8e
| DEFINT
|-
| &8f
| DEFREAL
|-
| &90
| DEFSTR
|-
| &91
| DEG
|-
| &92
| DELETE
|-
| &93
| DIM
|-
| &94
| DRAW
|-
| &95
| DRAWR
|-
| &96
| EDIT
|-
| &97
| ELSE
|-
| &98
| END
|-
| &99
| ENT
|-
| &9a
| ENV
|-
| &9b
| ERASE
|-
| &9c
| ERROR
|-
| &9d
| EVERY
|-
| &9e
| FOR
|-
| &9f
| GOSUB, GO SUB
|-
| &a0
| GOTO, GO TO
|-
| &a1
| IF
|-
| &a2
| INK
|-
| &a3
| INPUT
|-
| &a4
| KEY
|-
| &a5
| LET
|-
| &a6
| LINE
|-
| &a7
| LIST
|-
| &a8
| LOAD
|-
| &a9
| LOCATE
|-
| &aa
| MEMORY
|-
| &ab
| MERGE
|-
| &ac
| MID$
|-
| &ad
| MODE
|-
| &ae
| MOVE
|-
| &af
| MOVER
|-
| &b0
| NEXT
|-
| &b1
| NEW
|-
| &b2
| ON
|-
| &b3
| ON BREAK
|-
| &b4
| ON ERROR GOTO, ON ERROR GO TO
|-
| &b5
| ON SQ
|-
| &b6
| OPENIN
|-
| &b7
| OPENOUT
|-
| &b8
| ORIGIN
|-
| &b9
| OUT
|-
| &ba
| PAPER
|-
| &bb
| PEN
|-
| &bc
| PLOT
|-
| &bd
| PLOTR
|-
| &be
| POKE
|-
| &bf
| PRINT
|-
| &c0
| "'" symbol (same function as REM keyword)
|-
| &c1
| RAD
|-
| &c2
| RANDOMIZE
|-
| &c3
| READ
|-
| &c4
| RELEASE
|-
| &c5
| REM
|-
| &c6
| RENUM
|-
| &c7
| RESTORE
|-
| &c8
| RESUME
|-
| &c9
| RETURN
|-
| &ca
| RUN
|-
| &cb
| SAVE
|-
| &cc
| SOUND
|-
| &cd
| SPEED
|-
| &ce
| STOP
|-
| &cf
| SYMBOL
|-
| &d0
| TAG
|-
| &d1
| TAGOFF
|-
| &d2
| TROFF
|-
| &d3
| TRON
|-
| &d4
| WAIT
|-
| &d5
| WEND
|-
| &d6
| WHILE
|-
| &d7
| WIDTH
|-
| &d8
| WINDOW
|-
| &d9
| WRITE
|-
| &da
| ZONE
|-
| &db
| DI
|-
| &dc
| EI
|-
| &dd
| FILL (v1.1)
|-
| &de
| GRAPHICS (v1.1)
|-
| &df
| MASK (v1.1)
|-
| &e0
| FRAME (v1.1)
|-
| &e1
| CURSOR (v1.1)
|-
| &e2
| (note 2)
|-
| &e3
| ERL
|-
| &e4
| FN
|-
| &e5
| SPC
|-
| &e6
| STEP
|-
| &e7
| SWAP
|-
| &e8
| (note 2)
|-
| &e9
| (note 2)
|-
| &ea
| TAB
|-
| &eb
| THEN
|-
| &ec
| TO
|-
| &ed
| USING
|-
| &ee
| > (greater than)
|-
| &ef
| = (equal)
|-
| &f0
| &gt=, > =, => (greater or equal)
|-
| &f1
| < (less than)
|-
| &f2
| <&gt, < > (not equal)
|-
| &f3
| =<, <=, < = (less than or equal)
|-
| &f4
| + (addition)
|-
| &f5
| - (subtraction or unary minus)
|-
| &f6
| * (multiplication)
|-
| &f7
| / (division)
|-
| &f8
| ^ (x to the power of y)
|-
| &f9
| \ (integer division)
|-
| &fa
| AND
|-
| &fb
| MOD
|-
| &fc
| OR
|-
| &fd
| XOR
|-
| &fe
| NOT
|-
| &ff
| (prefix for additional keywords)
|}

 Notes:

*The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
*&e2,&e8 and &e9 are not used
*&7c ("|") is a character prefix used to identify an RSX command. e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| "|" character prefix
|-
| 1
| 1
| 8-bit byte offset to tokens following RSX name.
|-
| 2
| x
| RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
|}

*This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &1a,&2d,&00 represents the integer number "&002d"="45".
*This token (&0B) is changed at run-time to &0D
*This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
*This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
*This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| &1f (note 1)
|-
| 1
| 5
| Floating point number (note 2)
|}

*#This byte is the BASIC token identifying a floating point number
*#These 5 bytes define the floating point number.
*The space symbol is used as a command seperator
*Variable definitions:
**The variable definition has the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| Token defining variable type
|-
| 2
| 2
| 16-bit Byte offset to variable value within tokenised BASIC program.
|-
| 4
| x
| Variable name
|}

 The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.

**The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
**The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
*String values:
**Each string value is prefixed with &22 token.
**All strings must be enclosed by double quote symbols (&quot). This symbols define the start and end of the string value.
**The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.

*After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

 This table list the BASIC tokens with a &ff prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| ABS
|-
| &01
| ASC
|-
| &02
| ATN
|-
| &03
| CHR$
|-
| &04
| CINT
|-
| &05
| COS
|-
| &06
| CREAL
|-
| &07
| EXP
|-
| &08
| FIX
|-
| &09
| FRE
|-
| &0a
| INKEY
|-
| &0b
| INP
|-
| &0c
| INT
|-
| &0d
| JOY
|-
| &0e
| LEN
|-
| &0f
| LOG
|-
| &10
| LOG10
|-
| &11
| LOWER$
|-
| &12
| PEEK
|-
| &13
| REMAIN
|-
| &14
| SGN
|-
| &15
| SIN
|-
| &16
| SPACE$
|-
| &17
| SQ
|-
| &18
| SQR
|-
| &19
| STR$
|-
| &1a
| TAN
|-
| &1b
| UNT
|-
| &1c
| UPPER$
|-
| &1d
| VAL
|-
|  
| (note 2)
|-
| &40
| EOF
|-
| &41
| ERR
|-
| &42
| HIMEM
|-
| &43
| INKEY$
|-
| &44
| PI
|-
| &45
| RND
|-
| &46
| TIME
|-
| &47
| XPOS
|-
| &48
| YPOS
|-
| &49
| DERR (v1.1)
|-
|  
| (note 3)
|-
| &71
| BIN$
|-
| &72
| DEC$ (v1.1)
|-
| &73
| HEX$
|-
| &74
| INSTR
|-
| &75
| LEFT$
|-
| &76
| MAX
|-
| &77
| MIN
|-
| &78
| POS
|-
| &79
| RIGHT$
|-
| &7a
| ROUND
|-
| &7b
| STRING$
|-
| &7c
| TEST
|-
| &7d
| TESTR
|-
| &7e
| COPYCHR$ (v1.1)
|-
| &7f
| VPOS
|-
|  
| (note 4)
|}

 NOTES:

*These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence: <pre>&FF,&00</pre>
*Codes &1e...&3f inclusive are not used
*Codes &4a...&6f inclusive are not used
*Codes &80...&ff inclusive are not used

*When a BASIC program is in memory, the BASIC ROM can replace "16-bit BASIC program line number" tokens with "16-bit BASIC program line memory address pointer".

When a program is loaded or saved, there will only be "16-bit BASIC program line number" tokens followed by a 16-bit number of the line.

When a program is running, BASIC will replace the "16-bit BASIC program line number" with the "16-bit BASIC program line memory address pointer" token, and replace the 16-bit line number with the memory address of the start of that line.

It does this to avoid having to lookup the address of the line each time.

* When a REM or ' is seen, the characters following it are output directly (i.e. the bytes are not tokenized) until the end of line or a ':' is seen.

* When a BASIC program is listed each line is converted to a string (this includes the line number and the tokens converted to their strings). There is a maximum length for this string of 256 characters. This means that if the BASIC line is LISTed or EDITed, then the line will be displayed incorrectly with missing characters on the end. This is also noticed if you have a "10-liner" program that packs as much BASIC as possible into each line and renumber it so the line number has more digits.

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

 In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form: 1 x 2<exponent> The representation uses 5 bytes and is stored using the following structure:

 

{| border="1"
|-
! Byte
! colspan="8" | 0
! colspan="8" | 1
! colspan="8" | 2
! colspan="8" | 3
! colspan="8" | 4
|-
! Bit
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
|-
| Function
| colspan="8" | (LSB) mantissa (bits 31-24)
| colspan="8" | mantissa (bits 23-16)
| colspan="8" | mantissa (bits 15-8)
| colspan="1" | sign
| colspan="7" | (MSB) mantissa (bits 7-0)
| colspan="8" | exponent
|}

=== Sign ===

The sign is represented by bit 7 of byte 3. The value of the sign bit indicates the sign of the floating point number.

#*If the sign bit is "1", then the number is negative.
#*If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4. It is stored with a bias of 128.

#*128-255 are positive exponents,
#*1-127 are negative exponents.
#*0 means, the number is zero

To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 1 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^127.
A value of 0 just means, that the number is zero (0).

=== BASIC Display of Floating point numbers ===

* Numbers are displayed to 9 decimal places.
* If the number doesn't have a fractional part (e.g. .0) then the fractional part is not displayed.
* Trailing zeros (zero digits after the last digit in the fraction) are not displayed
* The value is rounded in the following way for display:

If the 10th fractional digit is 5 or above, then the number is rounded up.
If the 10th fractional digit is 4 or below, then the number is rounded down.
e.g.
0.1234567891 is displayed as 0.123456789
0.1234567895 is displayed as 0.12345679

=== floating point example in RAM by MaV ===

The initial figure = 43.375.
An example in BASIC:
<pre>
a!=43.375
READY
PRINT a!
43.375
PRINT @a!
374
FOR I=0 TO 4:PRINT HEX$(PEEK(374+I),2);:NEXT I
0000802D86
</pre>
the result for better readability: 
'''00 00 80 2D 86''' 
The first byte contains the least significant bits of the mantissa, and every following byte up to the fourth byte contain the bits following the first in significance and in exactly that order!

That means that you have to turn around the first four bytes if you want to read the mantissa correctly:
2D800000
or
0010.1101.1000.0000.0000.0000.0000.0000
in binary (the stops are inserted for better readability).

Now the highest significant bit here is 0, so the number is positive.
What's more, you need to clear that bit and substitute the implied highest bit (see description in the link), which is always 1 (regardless of the deleted sign bit!!!).
Thus you get:
AD800000
or
1010.1101.1000.0000.0000.0000.0000.0000
in binary.

The mantissa has an implied decimal point before the number. Since the number is 2^32 bits (i.e. 4 bytes) long you have to divide by 2^32 to get the proper decimal representation.

AD800000 (hex) = 2910846976 (dec)

2910846976 / 2^32 = 0.677734375

The mantissa in a decimal representation is: 0.677734375

Now, the last byte contains the exponent: 86 (hex) or 134 (dec). You need to subtract 128 to get the real exponent, the highest bit tells you that the exponent is positive (1) or negative (0). Your exponent is 6.

0.677734375 * 2^6 = 43.375

'''Another example:''' 
PI is represented in memory as: 
'''A2 DA 0F 49 82''' 
The mantissa is 
490FDAA2 (highest significant bit is zero => number is positive)
The exponent is 
82 (=positive mantissa, value=2 thus multiply mantissa with 2^2) 

Delete the sign bit (which is 0 anyway), and then add the implied 1 bit: 
C90FDAA2 (hex) = 3373259426 (dec) = 1100.1001.0000.1111.1101.1010.1010.0010 (bin) 

Calculate the decimal representation of the mantissa: 
3373259426 / 2^32 = 0,7853981633670628070831298828125 

Then add the exponent (82h - 80h = 2 thus 2^2) 
0,7853981633670628070831298828125 * 2^2 = 3,14159265346825122833251953125 

Voilà! The internal representation of the number PI on the CPC is: 3,14159265346825122833251953125 

If you compare to a (more) correct representation of PI, you'll see that the CPC is correct up to the 9th decimal place: 

CPC: 
3.14159265346825122833251953125 
more correctly: 
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986...

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts. The biggest figure which can be stored correctly in RAM by a variable is 2^32-1 = 4294967295.

#*A real variable is defined with a "!" character postfix.

e.g.
<pre>a! = 3.141592654
</pre>
#*A real number uses 5 bytes of memory as storage. The format is described above.
#*The address of a real variable can be found in BASIC by: <pre>PRINT @a!
</pre>

Where "a" should be replaced with the name of the variable.

 

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

 NOTES:

#*A integer variable is defined with a "%" character postfix.

e.g.
<pre>a% = 3
</pre>
#*A integer variable has a range of -32768 to 32767
#*A integer variable always uses two bytes of memory as storage with the following format:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 2
| Integer number
|}

#*The address of the integer variable can be found in BASIC by: <pre>PRINT @a%
</pre>

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

 NOTES:

#A string variable is defined in BASIC with a "$" character postfix.

e.g.
<pre>a$ = "hello"
</pre>
#A string variable is described internally by a "string descriptor block" which has the following structure:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 1
| Length of string in bytes/characters
|-
| 1
| 2
| Location of start of string
|}

#The address of the "string descriptor block" for the string variable can be found in BASIC by typing: <pre>PRINT @a$
</pre>

replacing "a$" with the name of the string variable.

#A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
#A string variable can contain any ASCII character code in the range 0-255.
#A string variable can store a minimum of 0 characters and a maximum of 255 characters.
#The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Technical information about Locomotive BASIC

2025-08-24T10:20:53Z

Arnoldemu: /* BASIC floating-point/real variables */

[[Category:Cpctech.org]]

'''''This article originally came from Kevin Thackers' archive at [http://www.cpctech.org.uk http://www.cpctech.org.uk].'''''

= Technical information about Locomotive BASIC =

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== BASIC v1.0 only ==

There is a region of memory between AC00-AC1B which is filled with RET instructions. The BASIC ROM calls the following locations:
AC01,AC04,AC07,AC0A,AC0D,AC10,AC13,AC16,AC19

It almost looks like these were used for debugging the ROM but were left in.

They can be used to implement new BASIC commands.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR". A binary function is accessed through BASIC using the "CALL" command.

Both RSX and CALL commands work (are!) similar from the BASIC command line and invoke machine code - the only difference is: with the help of a RSX command you don't need to know the exact access address. You can pass up to 32 parameters with a CALL or RSX command. Possible parameters could be integer, floating points and strings. Just store the parameter into a variable:
Passing for integer:
<pre>
CALL &4000,32,34,&5E,&x10101010
|RSX-command,32,34,&5E,&x10101010
</pre>
Passing for floating points
<pre>
@a!=43.375
CALL or |RSX-command,@a!
</pre>

 Passing a string parameter:
 BASIC v1.0
<pre>a$="A":|DRIVE,@a$
</pre>
BASIC v1.1:
<pre>|DRIVE,"A"
</pre>
or
<pre>
b$="test"
CALL or |RSX-command,@b$
</pre>

The parameters will be stored inside the range of Stack:
<pre>
A=n -------> MSB PARAM1
LSB PARAM1
MSB PARAM2
LSB PARAM2
...
...
...
MSB PARAMn
IX+0 ------> LSB PARAMn
</pre>
with the help of that assembly code is it possible to find the parameters:
<pre>
ROUT1: CP x ;test register A if "x" parameters were given, e.g. x = 2
RET NZ ; if not exactly x parameters then do not execute RSX.
LD L,(IX+0)
LD H,(IX+1) ; HL = value of last parameter
LD E,(IX+2)
LD D,(IX+3) ; DE = value of next to last parameter
...
</pre>
A register holds the number of parameters. IX points to each parameter. IX+0/IX+1 is the last parameter. This happens because each parameter in order is pushed onto the stack and IX then points to the last parameter pushed. Each parameter is a 16-bit value.

If a parameter is a string, then IX holds the address of the string descriptor which point to a 3 byte block. The first byte of the string descriptor is the length. The next 2 bytes are an address that point to the string in memory.

With the help of the variable container "@" it is also possible to get a result from an invoked mc-code back to basic.
In this case the parameter contains the address of the integer, floating point or string. You can modify these to give the result.
BASIC allocates the strings, so when you modify a string, do not write more characters than the original string.

Hint: the first two bytes at the end of stack shows the internal return address from BASIC interpreter where it was executed.

== Additional keywords and variables in BASIC v1.1 ==

#BASIC v1.1 has the following additional keywords:
#*COPYCHR$
#*CURSOR
#*DEC$
#*FILL
#*FRAME
#*GRAPHICS
#*MASK
#BASIC v1.1 has the following additional predefined variables:
#*DERR

 

== BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

There are some rules for assigning names for variables:
: - it is not allowed to define a variable starting with a figure (the system expect then programming mode and interpret it as a program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - different sign e.g.: a slash (doesn't depend which direction), a 'minus' sign, a 'and' sign can't be used in a variable names
: - after a dollar sign (for defining string variables) it is not allowed to use further signs
: - different defining functions together are not allowed (e.g. use '%' together with '$')

: - you can use 40 characters for a variable name
: - use ! for defining a REAL value variable (like the function DEFREAL but only for the assigned variable) > It's also possible to omit the exlamation mark because it's the default system declaration after powering on then CPC.
: - use % for defining a INTEGER value variable (like the function DEFINT but only for the assigned variable)
: - use $ for defining a STRING variable (like the function DEFSTR but only for the assigned variable)
: - Minimum line number is 1. Maximum line number is 65535.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

 

== Speeding up BASIC programs ==

To speed up BASIC programs following rules could help:
: - Avoid loops or a branching program structure if possible. Internally the operating system searches for the right line number always from the beginning of the program 'listing'. Often recurring subroutines (if necessary) should be at the beginning of RAM to speed up things.
: - Avoid the index variable after the <code>NEXT</code> command/statement (although it isn't a good program style)
: - Avoid spaces inside program code or remarks
: - Put lots of statements as possible in ONE line
: - Use variables instead of constants. A constant has always to be converted in a binary/digital format. A variable is already converted.
: - Dimensioning at the beginning of the program
: - Dimensioning your variables & pre-calculate
: - Avoid AND/OR/XOR in IF-THEN statements. It's faster to write IF ... THEN (statement 1).. IF ... THEN (statement 2).
: - Minimise string/char manipulation as this often requires memory allocations. (e.g. joining strings with +, use of MID$, LEFT$, RIGHT$, SPACE$)

== Minimizing memory usage ==

To minimize memory usage in BASIC here are some things to consider.

The size of the tokenized program:
: - Difficult to measure without looking at the data in memory.
: - Use short variable names. The names are stored in the tokenized BASIC program as-is.
: - Minimize the number of variables. The names are stored in the tokenized BASIC program everywhere they are used.
: - Use as few lines as possible. It's a small saving of about 5 bytes per line.
: - Consider using numbers vs strings and potentially 8-bit or 16-bit values.

Minimising memory usage when the program is running:
: - Minimize string operations. (e.g. A$=SPACE$(30)+CHR$(28) in memory this first allocates a string of length 30 containing spaces, then it allocates a new string of length 31 with spaces and char 28 at the end and assigns it to A$. In this line at least 30 bytes have been wasted. So consider if you need strings or perhaps if possible pre-define them).

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences. Each line of the BASIC program has the form:

 

{| border="1"
|-
! Offset
! Size
! Description
|-
| 0
| 2
| Length of line data in bytes (note 1)
|-
| 2
| 2
| 16-bit decimal integer line number (note 2)
|-
| 4
| n
| BASIC line encoded into tokens (note 3)
|-
| n+1
| 1
| "0" the end of line marker (note 4)
|}

 Notes:

#This 16-bit value has two functions: if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data, otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
#This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
#This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
#This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| end of tokenised line marker
|-
| &01
| ":" statement seperator
|-
| &02
| integer variable definition (defined with "%" suffix)
|-
| &03
| string variable definition (defined with "$" suffix)
|-
| &04
| floating point variable definition (defined with "!" suffix)
|-
| &05
| var?
|-
| &06
| var?
|-
| &07
| var?
|-
| &08
| var?
|-
| &09
| var?
|-
| &0a
| var?
|-
| &0b
| variable definition (no suffix)
|-
| &0c
| variable definition (no suffix)
|-
| &0d
| variable definition (no suffix)
|-
| &0e
| number constant "0"
|-
| &0f
| number constant "1"
|-
| &10
| number constant "2"
|-
| &11
| number constant "3"
|-
| &12
| number constant "4"
|-
| &13
| number constant "5"
|-
| &14
| number constant "6"
|-
| &15
| number constant "7"
|-
| &16
| number constant "8"
|-
| &17
| number constant "9"
|-
| &18
| number constant "10"
|-
| &19
| 8-bit integer decimal value
|-
| &1a
| 16-bit integer decimal value
|-
| &1b
| 16-bit integer binary value (with "&X" prefix)
|-
| &1c
| 16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
| &1d
| 16-bit BASIC program line memory address pointer (see notes)
|-
| &1e
| 16-bit integer BASIC line number
|-
| &1f
| floating point value
|-
| &20
| " " (space) symbol
|-
| &21
| ASCII "!" symbol
|-
| &22
| quoted string value
|-
| &23-7b
| ASCII printable symbols
|-
| &7c
| "|" symbol; prefix for RSX commands
|-
| &80
| AFTER
|-
| &81
| AUTO
|-
| &82
| BORDER
|-
| &83
| CALL
|-
| &84
| CAT
|-
| &85
| CHAIN
|-
| &86
| CLEAR
|-
| &87
| CLG
|-
| &88
| CLOSEIN
|-
| &89
| CLOSEOUT
|-
| &8a
| CLS
|-
| &8b
| CONT
|-
| &8c
| DATA
|-
| &8d
| DEF
|-
| &8e
| DEFINT
|-
| &8f
| DEFREAL
|-
| &90
| DEFSTR
|-
| &91
| DEG
|-
| &92
| DELETE
|-
| &93
| DIM
|-
| &94
| DRAW
|-
| &95
| DRAWR
|-
| &96
| EDIT
|-
| &97
| ELSE
|-
| &98
| END
|-
| &99
| ENT
|-
| &9a
| ENV
|-
| &9b
| ERASE
|-
| &9c
| ERROR
|-
| &9d
| EVERY
|-
| &9e
| FOR
|-
| &9f
| GOSUB, GO SUB
|-
| &a0
| GOTO, GO TO
|-
| &a1
| IF
|-
| &a2
| INK
|-
| &a3
| INPUT
|-
| &a4
| KEY
|-
| &a5
| LET
|-
| &a6
| LINE
|-
| &a7
| LIST
|-
| &a8
| LOAD
|-
| &a9
| LOCATE
|-
| &aa
| MEMORY
|-
| &ab
| MERGE
|-
| &ac
| MID$
|-
| &ad
| MODE
|-
| &ae
| MOVE
|-
| &af
| MOVER
|-
| &b0
| NEXT
|-
| &b1
| NEW
|-
| &b2
| ON
|-
| &b3
| ON BREAK
|-
| &b4
| ON ERROR GOTO, ON ERROR GO TO
|-
| &b5
| ON SQ
|-
| &b6
| OPENIN
|-
| &b7
| OPENOUT
|-
| &b8
| ORIGIN
|-
| &b9
| OUT
|-
| &ba
| PAPER
|-
| &bb
| PEN
|-
| &bc
| PLOT
|-
| &bd
| PLOTR
|-
| &be
| POKE
|-
| &bf
| PRINT
|-
| &c0
| "'" symbol (same function as REM keyword)
|-
| &c1
| RAD
|-
| &c2
| RANDOMIZE
|-
| &c3
| READ
|-
| &c4
| RELEASE
|-
| &c5
| REM
|-
| &c6
| RENUM
|-
| &c7
| RESTORE
|-
| &c8
| RESUME
|-
| &c9
| RETURN
|-
| &ca
| RUN
|-
| &cb
| SAVE
|-
| &cc
| SOUND
|-
| &cd
| SPEED
|-
| &ce
| STOP
|-
| &cf
| SYMBOL
|-
| &d0
| TAG
|-
| &d1
| TAGOFF
|-
| &d2
| TROFF
|-
| &d3
| TRON
|-
| &d4
| WAIT
|-
| &d5
| WEND
|-
| &d6
| WHILE
|-
| &d7
| WIDTH
|-
| &d8
| WINDOW
|-
| &d9
| WRITE
|-
| &da
| ZONE
|-
| &db
| DI
|-
| &dc
| EI
|-
| &dd
| FILL (v1.1)
|-
| &de
| GRAPHICS (v1.1)
|-
| &df
| MASK (v1.1)
|-
| &e0
| FRAME (v1.1)
|-
| &e1
| CURSOR (v1.1)
|-
| &e2
| (note 2)
|-
| &e3
| ERL
|-
| &e4
| FN
|-
| &e5
| SPC
|-
| &e6
| STEP
|-
| &e7
| SWAP
|-
| &e8
| (note 2)
|-
| &e9
| (note 2)
|-
| &ea
| TAB
|-
| &eb
| THEN
|-
| &ec
| TO
|-
| &ed
| USING
|-
| &ee
| > (greater than)
|-
| &ef
| = (equal)
|-
| &f0
| &gt=, > =, => (greater or equal)
|-
| &f1
| < (less than)
|-
| &f2
| <&gt, < > (not equal)
|-
| &f3
| =<, <=, < = (less than or equal)
|-
| &f4
| + (addition)
|-
| &f5
| - (subtraction or unary minus)
|-
| &f6
| * (multiplication)
|-
| &f7
| / (division)
|-
| &f8
| ^ (x to the power of y)
|-
| &f9
| \ (integer division)
|-
| &fa
| AND
|-
| &fb
| MOD
|-
| &fc
| OR
|-
| &fd
| XOR
|-
| &fe
| NOT
|-
| &ff
| (prefix for additional keywords)
|}

 Notes:

*The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
*&e2,&e8 and &e9 are not used
*&7c ("|") is a character prefix used to identify an RSX command. e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| "|" character prefix
|-
| 1
| 1
| 8-bit byte offset to tokens following RSX name.
|-
| 2
| x
| RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
|}

*This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &1a,&2d,&00 represents the integer number "&002d"="45".
*This token (&0B) is changed at run-time to &0D
*This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
*This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
*This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| &1f (note 1)
|-
| 1
| 5
| Floating point number (note 2)
|}

*#This byte is the BASIC token identifying a floating point number
*#These 5 bytes define the floating point number.
*The space symbol is used as a command seperator
*Variable definitions:
**The variable definition has the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| Token defining variable type
|-
| 2
| 2
| 16-bit Byte offset to variable value within tokenised BASIC program.
|-
| 4
| x
| Variable name
|}

 The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.

**The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
**The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
*String values:
**Each string value is prefixed with &22 token.
**All strings must be enclosed by double quote symbols (&quot). This symbols define the start and end of the string value.
**The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.

*After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

 This table list the BASIC tokens with a &ff prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| ABS
|-
| &01
| ASC
|-
| &02
| ATN
|-
| &03
| CHR$
|-
| &04
| CINT
|-
| &05
| COS
|-
| &06
| CREAL
|-
| &07
| EXP
|-
| &08
| FIX
|-
| &09
| FRE
|-
| &0a
| INKEY
|-
| &0b
| INP
|-
| &0c
| INT
|-
| &0d
| JOY
|-
| &0e
| LEN
|-
| &0f
| LOG
|-
| &10
| LOG10
|-
| &11
| LOWER$
|-
| &12
| PEEK
|-
| &13
| REMAIN
|-
| &14
| SGN
|-
| &15
| SIN
|-
| &16
| SPACE$
|-
| &17
| SQ
|-
| &18
| SQR
|-
| &19
| STR$
|-
| &1a
| TAN
|-
| &1b
| UNT
|-
| &1c
| UPPER$
|-
| &1d
| VAL
|-
|  
| (note 2)
|-
| &40
| EOF
|-
| &41
| ERR
|-
| &42
| HIMEM
|-
| &43
| INKEY$
|-
| &44
| PI
|-
| &45
| RND
|-
| &46
| TIME
|-
| &47
| XPOS
|-
| &48
| YPOS
|-
| &49
| DERR (v1.1)
|-
|  
| (note 3)
|-
| &71
| BIN$
|-
| &72
| DEC$ (v1.1)
|-
| &73
| HEX$
|-
| &74
| INSTR
|-
| &75
| LEFT$
|-
| &76
| MAX
|-
| &77
| MIN
|-
| &78
| POS
|-
| &79
| RIGHT$
|-
| &7a
| ROUND
|-
| &7b
| STRING$
|-
| &7c
| TEST
|-
| &7d
| TESTR
|-
| &7e
| COPYCHR$ (v1.1)
|-
| &7f
| VPOS
|-
|  
| (note 4)
|}

 NOTES:

*These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence: <pre>&FF,&00</pre>
*Codes &1e...&3f inclusive are not used
*Codes &4a...&6f inclusive are not used
*Codes &80...&ff inclusive are not used

*When a BASIC program is in memory, the BASIC ROM can replace "16-bit BASIC program line number" tokens with "16-bit BASIC program line memory address pointer".

When a program is loaded or saved, there will only be "16-bit BASIC program line number" tokens followed by a 16-bit number of the line.

When a program is running, BASIC will replace the "16-bit BASIC program line number" with the "16-bit BASIC program line memory address pointer" token, and replace the 16-bit line number with the memory address of the start of that line.

It does this to avoid having to lookup the address of the line each time.

* When a REM or ' is seen, the characters following it are output directly (i.e. the bytes are not tokenized) until the end of line or a ':' is seen.

* When a BASIC program is listed each line is converted to a string (this includes the line number and the tokens converted to their strings). There is a maximum length for this string of 256 characters. This means that if the BASIC line is LISTed or EDITed, then the line will be displayed incorrectly with missing characters on the end. This is also noticed if you have a "10-liner" program that packs as much BASIC as possible into each line and renumber it so the line number has more digits.

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

 In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form: 1 x 2<exponent> The representation uses 5 bytes and is stored using the following structure:

 

{| border="1"
|-
! Byte
! colspan="8" | 0
! colspan="8" | 1
! colspan="8" | 2
! colspan="8" | 3
! colspan="8" | 4
|-
! Bit
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
|-
| Function
| colspan="8" | (LSB) mantissa (bits 31-24)
| colspan="8" | mantissa (bits 23-16)
| colspan="8" | mantissa (bits 15-8)
| colspan="1" | sign
| colspan="7" | (MSB) mantissa (bits 7-0)
| colspan="8" | exponent
|}

=== Sign ===

The sign is represented by bit 7 of byte 3. The value of the sign bit indicates the sign of the floating point number.

#*If the sign bit is "1", then the number is negative.
#*If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4. It is stored with a bias of 128.

#*128-255 are positive exponents,
#*1-127 are negative exponents.
#*0 means, the number is zero

To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 1 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^127.
A value of 0 just means, that the number is zero (0).

=== BASIC Display of Floating point numbers ===

* Numbers are displayed to 9 decimal places.
* If the number doesn't have a fractional part (e.g. .0) then the fractional part is not displayed.
* Trailing zeros (zero digits after the last digit in the fraction) are not displayed
* The value is rounded in the following way for display:

If the 10th fractional digit is 5 or above, then the number is rounded up.
If the 10th fractional digit is 4 or below, then the number is rounded down.
e.g.
0.1234567891 is displayed as 0.123456789
0.1234567895 is displayed as 0.12345679

=== floating point example in RAM by MaV ===

The initial figure = 43.375.
An example in BASIC:
<pre>
a!=43.375
READY
PRINT a!
43.375
PRINT @a!
374
FOR I=0 TO 4:PRINT HEX$(PEEK(374+I),2);:NEXT I
0000802D86
</pre>
the result for better readability: 
'''00 00 80 2D 86''' 
The first byte contains the least significant bits of the mantissa, and every following byte up to the fourth byte contain the bits following the first in significance and in exactly that order!

That means that you have to turn around the first four bytes if you want to read the mantissa correctly:
2D800000
or
0010.1101.1000.0000.0000.0000.0000.0000
in binary (the stops are inserted for better readability).

Now the highest significant bit here is 0, so the number is positive.
What's more, you need to clear that bit and substitute the implied highest bit (see description in the link), which is always 1 (regardless of the deleted sign bit!!!).
Thus you get:
AD800000
or
1010.1101.1000.0000.0000.0000.0000.0000
in binary.

The mantissa has an implied decimal point before the number. Since the number is 2^32 bits (i.e. 4 bytes) long you have to divide by 2^32 to get the proper decimal representation.

AD800000 (hex) = 2910846976 (dec)

2910846976 / 2^32 = 0.677734375

The mantissa in a decimal representation is: 0.677734375

Now, the last byte contains the exponent: 86 (hex) or 134 (dec). You need to subtract 128 to get the real exponent, the highest bit tells you that the exponent is positive (1) or negative (0). Your exponent is 6.

0.677734375 * 2^6 = 43.375

'''Another example:''' 
PI is represented in memory as: 
'''A2 DA 0F 49 82''' 
The mantissa is 
490FDAA2 (highest significant bit is zero => number is positive)
The exponent is 
82 (=positive mantissa, value=2 thus multiply mantissa with 2^2) 

Delete the sign bit (which is 0 anyway), and then add the implied 1 bit: 
C90FDAA2 (hex) = 3373259426 (dec) = 1100.1001.0000.1111.1101.1010.1010.0010 (bin) 

Calculate the decimal representation of the mantissa: 
3373259426 / 2^32 = 0,7853981633670628070831298828125 

Then add the exponent (82h - 80h = 2 thus 2^2) 
0,7853981633670628070831298828125 * 2^2 = 3,14159265346825122833251953125 

Voilà! The internal representation of the number PI on the CPC is: 3,14159265346825122833251953125 

If you compare to a (more) correct representation of PI, you'll see that the CPC is correct up to the 9th decimal place: 

CPC: 
3.14159265346825122833251953125 
more correctly: 
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986...

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts. The biggest figure which can be stored correctly in RAM by a variable is 2^32-1 = 4294967295.

#*A real variable is defined with a "!" character postfix.

e.g.
<pre>a! = 3.141592654
</pre>
#*A real number uses 5 bytes of memory as storage. The format is described above.
#*The address of a real variable can be found in BASIC by: <pre>PRINT @a!
</pre>

Where "a" should be replaced with the name of the variable.

 

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

 NOTES:

#*A integer variable is defined with a "%" character postfix.

e.g.
<pre>a% = 3
</pre>
#*A integer variable has a range of -32768 to 32767
#*A integer variable always uses two bytes of memory as storage with the following format:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 2
| Integer number
|}

#*The address of the integer variable can be found in BASIC by: <pre>PRINT @a%
</pre>

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

 NOTES:

#**A string variable is defined in BASIC with a "$" character postfix.

e.g.
<pre>a$ = "hello"
</pre>
#**A string variable is described internally by a "string descriptor block" which has the following structure:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 1
| Length of string in bytes/characters
|-
| 1
| 2
| Location of start of string
|}

#**The address of the "string descriptor block" for the string variable can be found in BASIC by typing: <pre>PRINT @a$
</pre>

replacing "a$" with the name of the string variable.

#**A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
#**A string variable can contain any ASCII character code in the range 0-255.
#**A string variable can store a minimum of 0 characters and a maximum of 255 characters.
#**The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Technical information about Locomotive BASIC

2025-08-24T10:18:53Z

Arnoldemu: /* Maximizing memory usage */

[[Category:Cpctech.org]]

'''''This article originally came from Kevin Thackers' archive at [http://www.cpctech.org.uk http://www.cpctech.org.uk].'''''

= Technical information about Locomotive BASIC =

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== BASIC v1.0 only ==

There is a region of memory between AC00-AC1B which is filled with RET instructions. The BASIC ROM calls the following locations:
AC01,AC04,AC07,AC0A,AC0D,AC10,AC13,AC16,AC19

It almost looks like these were used for debugging the ROM but were left in.

They can be used to implement new BASIC commands.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR". A binary function is accessed through BASIC using the "CALL" command.

Both RSX and CALL commands work (are!) similar from the BASIC command line and invoke machine code - the only difference is: with the help of a RSX command you don't need to know the exact access address. You can pass up to 32 parameters with a CALL or RSX command. Possible parameters could be integer, floating points and strings. Just store the parameter into a variable:
Passing for integer:
<pre>
CALL &4000,32,34,&5E,&x10101010
|RSX-command,32,34,&5E,&x10101010
</pre>
Passing for floating points
<pre>
@a!=43.375
CALL or |RSX-command,@a!
</pre>

 Passing a string parameter:
 BASIC v1.0
<pre>a$="A":|DRIVE,@a$
</pre>
BASIC v1.1:
<pre>|DRIVE,"A"
</pre>
or
<pre>
b$="test"
CALL or |RSX-command,@b$
</pre>

The parameters will be stored inside the range of Stack:
<pre>
A=n -------> MSB PARAM1
LSB PARAM1
MSB PARAM2
LSB PARAM2
...
...
...
MSB PARAMn
IX+0 ------> LSB PARAMn
</pre>
with the help of that assembly code is it possible to find the parameters:
<pre>
ROUT1: CP x ;test register A if "x" parameters were given, e.g. x = 2
RET NZ ; if not exactly x parameters then do not execute RSX.
LD L,(IX+0)
LD H,(IX+1) ; HL = value of last parameter
LD E,(IX+2)
LD D,(IX+3) ; DE = value of next to last parameter
...
</pre>
A register holds the number of parameters. IX points to each parameter. IX+0/IX+1 is the last parameter. This happens because each parameter in order is pushed onto the stack and IX then points to the last parameter pushed. Each parameter is a 16-bit value.

If a parameter is a string, then IX holds the address of the string descriptor which point to a 3 byte block. The first byte of the string descriptor is the length. The next 2 bytes are an address that point to the string in memory.

With the help of the variable container "@" it is also possible to get a result from an invoked mc-code back to basic.
In this case the parameter contains the address of the integer, floating point or string. You can modify these to give the result.
BASIC allocates the strings, so when you modify a string, do not write more characters than the original string.

Hint: the first two bytes at the end of stack shows the internal return address from BASIC interpreter where it was executed.

== Additional keywords and variables in BASIC v1.1 ==

#BASIC v1.1 has the following additional keywords:
#*COPYCHR$
#*CURSOR
#*DEC$
#*FILL
#*FRAME
#*GRAPHICS
#*MASK
#BASIC v1.1 has the following additional predefined variables:
#*DERR

 

== BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

There are some rules for assigning names for variables:
: - it is not allowed to define a variable starting with a figure (the system expect then programming mode and interpret it as a program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - different sign e.g.: a slash (doesn't depend which direction), a 'minus' sign, a 'and' sign can't be used in a variable names
: - after a dollar sign (for defining string variables) it is not allowed to use further signs
: - different defining functions together are not allowed (e.g. use '%' together with '$')

: - you can use 40 characters for a variable name
: - use ! for defining a REAL value variable (like the function DEFREAL but only for the assigned variable) > It's also possible to omit the exlamation mark because it's the default system declaration after powering on then CPC.
: - use % for defining a INTEGER value variable (like the function DEFINT but only for the assigned variable)
: - use $ for defining a STRING variable (like the function DEFSTR but only for the assigned variable)
: - Minimum line number is 1. Maximum line number is 65535.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

 

== Speeding up BASIC programs ==

To speed up BASIC programs following rules could help:
: - Avoid loops or a branching program structure if possible. Internally the operating system searches for the right line number always from the beginning of the program 'listing'. Often recurring subroutines (if necessary) should be at the beginning of RAM to speed up things.
: - Avoid the index variable after the <code>NEXT</code> command/statement (although it isn't a good program style)
: - Avoid spaces inside program code or remarks
: - Put lots of statements as possible in ONE line
: - Use variables instead of constants. A constant has always to be converted in a binary/digital format. A variable is already converted.
: - Dimensioning at the beginning of the program
: - Dimensioning your variables & pre-calculate
: - Avoid AND/OR/XOR in IF-THEN statements. It's faster to write IF ... THEN (statement 1).. IF ... THEN (statement 2).
: - Minimise string/char manipulation as this often requires memory allocations. (e.g. joining strings with +, use of MID$, LEFT$, RIGHT$, SPACE$)

== Minimizing memory usage ==

To minimize memory usage in BASIC here are some things to consider.

The size of the tokenized program:
: - Difficult to measure without looking at the data in memory.
: - Use short variable names. The names are stored in the tokenized BASIC program as-is.
: - Minimize the number of variables. The names are stored in the tokenized BASIC program everywhere they are used.
: - Use as few lines as possible. It's a small saving of about 5 bytes per line.
: - Consider using numbers vs strings and potentially 8-bit or 16-bit values.

Minimising memory usage when the program is running:
: - Minimize string operations. (e.g. A$=SPACE$(30)+CHR$(28) in memory this first allocates a string of length 30 containing spaces, then it allocates a new string of length 31 with spaces and char 28 at the end and assigns it to A$. In this line at least 30 bytes have been wasted. So consider if you need strings or perhaps if possible pre-define them).

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences. Each line of the BASIC program has the form:

 

{| border="1"
|-
! Offset
! Size
! Description
|-
| 0
| 2
| Length of line data in bytes (note 1)
|-
| 2
| 2
| 16-bit decimal integer line number (note 2)
|-
| 4
| n
| BASIC line encoded into tokens (note 3)
|-
| n+1
| 1
| "0" the end of line marker (note 4)
|}

 Notes:

#This 16-bit value has two functions: if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data, otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
#This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
#This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
#This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| end of tokenised line marker
|-
| &01
| ":" statement seperator
|-
| &02
| integer variable definition (defined with "%" suffix)
|-
| &03
| string variable definition (defined with "$" suffix)
|-
| &04
| floating point variable definition (defined with "!" suffix)
|-
| &05
| var?
|-
| &06
| var?
|-
| &07
| var?
|-
| &08
| var?
|-
| &09
| var?
|-
| &0a
| var?
|-
| &0b
| variable definition (no suffix)
|-
| &0c
| variable definition (no suffix)
|-
| &0d
| variable definition (no suffix)
|-
| &0e
| number constant "0"
|-
| &0f
| number constant "1"
|-
| &10
| number constant "2"
|-
| &11
| number constant "3"
|-
| &12
| number constant "4"
|-
| &13
| number constant "5"
|-
| &14
| number constant "6"
|-
| &15
| number constant "7"
|-
| &16
| number constant "8"
|-
| &17
| number constant "9"
|-
| &18
| number constant "10"
|-
| &19
| 8-bit integer decimal value
|-
| &1a
| 16-bit integer decimal value
|-
| &1b
| 16-bit integer binary value (with "&X" prefix)
|-
| &1c
| 16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
| &1d
| 16-bit BASIC program line memory address pointer (see notes)
|-
| &1e
| 16-bit integer BASIC line number
|-
| &1f
| floating point value
|-
| &20
| " " (space) symbol
|-
| &21
| ASCII "!" symbol
|-
| &22
| quoted string value
|-
| &23-7b
| ASCII printable symbols
|-
| &7c
| "|" symbol; prefix for RSX commands
|-
| &80
| AFTER
|-
| &81
| AUTO
|-
| &82
| BORDER
|-
| &83
| CALL
|-
| &84
| CAT
|-
| &85
| CHAIN
|-
| &86
| CLEAR
|-
| &87
| CLG
|-
| &88
| CLOSEIN
|-
| &89
| CLOSEOUT
|-
| &8a
| CLS
|-
| &8b
| CONT
|-
| &8c
| DATA
|-
| &8d
| DEF
|-
| &8e
| DEFINT
|-
| &8f
| DEFREAL
|-
| &90
| DEFSTR
|-
| &91
| DEG
|-
| &92
| DELETE
|-
| &93
| DIM
|-
| &94
| DRAW
|-
| &95
| DRAWR
|-
| &96
| EDIT
|-
| &97
| ELSE
|-
| &98
| END
|-
| &99
| ENT
|-
| &9a
| ENV
|-
| &9b
| ERASE
|-
| &9c
| ERROR
|-
| &9d
| EVERY
|-
| &9e
| FOR
|-
| &9f
| GOSUB, GO SUB
|-
| &a0
| GOTO, GO TO
|-
| &a1
| IF
|-
| &a2
| INK
|-
| &a3
| INPUT
|-
| &a4
| KEY
|-
| &a5
| LET
|-
| &a6
| LINE
|-
| &a7
| LIST
|-
| &a8
| LOAD
|-
| &a9
| LOCATE
|-
| &aa
| MEMORY
|-
| &ab
| MERGE
|-
| &ac
| MID$
|-
| &ad
| MODE
|-
| &ae
| MOVE
|-
| &af
| MOVER
|-
| &b0
| NEXT
|-
| &b1
| NEW
|-
| &b2
| ON
|-
| &b3
| ON BREAK
|-
| &b4
| ON ERROR GOTO, ON ERROR GO TO
|-
| &b5
| ON SQ
|-
| &b6
| OPENIN
|-
| &b7
| OPENOUT
|-
| &b8
| ORIGIN
|-
| &b9
| OUT
|-
| &ba
| PAPER
|-
| &bb
| PEN
|-
| &bc
| PLOT
|-
| &bd
| PLOTR
|-
| &be
| POKE
|-
| &bf
| PRINT
|-
| &c0
| "'" symbol (same function as REM keyword)
|-
| &c1
| RAD
|-
| &c2
| RANDOMIZE
|-
| &c3
| READ
|-
| &c4
| RELEASE
|-
| &c5
| REM
|-
| &c6
| RENUM
|-
| &c7
| RESTORE
|-
| &c8
| RESUME
|-
| &c9
| RETURN
|-
| &ca
| RUN
|-
| &cb
| SAVE
|-
| &cc
| SOUND
|-
| &cd
| SPEED
|-
| &ce
| STOP
|-
| &cf
| SYMBOL
|-
| &d0
| TAG
|-
| &d1
| TAGOFF
|-
| &d2
| TROFF
|-
| &d3
| TRON
|-
| &d4
| WAIT
|-
| &d5
| WEND
|-
| &d6
| WHILE
|-
| &d7
| WIDTH
|-
| &d8
| WINDOW
|-
| &d9
| WRITE
|-
| &da
| ZONE
|-
| &db
| DI
|-
| &dc
| EI
|-
| &dd
| FILL (v1.1)
|-
| &de
| GRAPHICS (v1.1)
|-
| &df
| MASK (v1.1)
|-
| &e0
| FRAME (v1.1)
|-
| &e1
| CURSOR (v1.1)
|-
| &e2
| (note 2)
|-
| &e3
| ERL
|-
| &e4
| FN
|-
| &e5
| SPC
|-
| &e6
| STEP
|-
| &e7
| SWAP
|-
| &e8
| (note 2)
|-
| &e9
| (note 2)
|-
| &ea
| TAB
|-
| &eb
| THEN
|-
| &ec
| TO
|-
| &ed
| USING
|-
| &ee
| > (greater than)
|-
| &ef
| = (equal)
|-
| &f0
| &gt=, > =, => (greater or equal)
|-
| &f1
| < (less than)
|-
| &f2
| <&gt, < > (not equal)
|-
| &f3
| =<, <=, < = (less than or equal)
|-
| &f4
| + (addition)
|-
| &f5
| - (subtraction or unary minus)
|-
| &f6
| * (multiplication)
|-
| &f7
| / (division)
|-
| &f8
| ^ (x to the power of y)
|-
| &f9
| \ (integer division)
|-
| &fa
| AND
|-
| &fb
| MOD
|-
| &fc
| OR
|-
| &fd
| XOR
|-
| &fe
| NOT
|-
| &ff
| (prefix for additional keywords)
|}

 Notes:

*The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
*&e2,&e8 and &e9 are not used
*&7c ("|") is a character prefix used to identify an RSX command. e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| "|" character prefix
|-
| 1
| 1
| 8-bit byte offset to tokens following RSX name.
|-
| 2
| x
| RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
|}

*This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &1a,&2d,&00 represents the integer number "&002d"="45".
*This token (&0B) is changed at run-time to &0D
*This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
*This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
*This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| &1f (note 1)
|-
| 1
| 5
| Floating point number (note 2)
|}

*#This byte is the BASIC token identifying a floating point number
*#These 5 bytes define the floating point number.
*The space symbol is used as a command seperator
*Variable definitions:
**The variable definition has the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| Token defining variable type
|-
| 2
| 2
| 16-bit Byte offset to variable value within tokenised BASIC program.
|-
| 4
| x
| Variable name
|}

 The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.

**The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
**The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
*String values:
**Each string value is prefixed with &22 token.
**All strings must be enclosed by double quote symbols (&quot). This symbols define the start and end of the string value.
**The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.

*After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

 This table list the BASIC tokens with a &ff prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| ABS
|-
| &01
| ASC
|-
| &02
| ATN
|-
| &03
| CHR$
|-
| &04
| CINT
|-
| &05
| COS
|-
| &06
| CREAL
|-
| &07
| EXP
|-
| &08
| FIX
|-
| &09
| FRE
|-
| &0a
| INKEY
|-
| &0b
| INP
|-
| &0c
| INT
|-
| &0d
| JOY
|-
| &0e
| LEN
|-
| &0f
| LOG
|-
| &10
| LOG10
|-
| &11
| LOWER$
|-
| &12
| PEEK
|-
| &13
| REMAIN
|-
| &14
| SGN
|-
| &15
| SIN
|-
| &16
| SPACE$
|-
| &17
| SQ
|-
| &18
| SQR
|-
| &19
| STR$
|-
| &1a
| TAN
|-
| &1b
| UNT
|-
| &1c
| UPPER$
|-
| &1d
| VAL
|-
|  
| (note 2)
|-
| &40
| EOF
|-
| &41
| ERR
|-
| &42
| HIMEM
|-
| &43
| INKEY$
|-
| &44
| PI
|-
| &45
| RND
|-
| &46
| TIME
|-
| &47
| XPOS
|-
| &48
| YPOS
|-
| &49
| DERR (v1.1)
|-
|  
| (note 3)
|-
| &71
| BIN$
|-
| &72
| DEC$ (v1.1)
|-
| &73
| HEX$
|-
| &74
| INSTR
|-
| &75
| LEFT$
|-
| &76
| MAX
|-
| &77
| MIN
|-
| &78
| POS
|-
| &79
| RIGHT$
|-
| &7a
| ROUND
|-
| &7b
| STRING$
|-
| &7c
| TEST
|-
| &7d
| TESTR
|-
| &7e
| COPYCHR$ (v1.1)
|-
| &7f
| VPOS
|-
|  
| (note 4)
|}

 NOTES:

*These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence: <pre>&FF,&00</pre>
*Codes &1e...&3f inclusive are not used
*Codes &4a...&6f inclusive are not used
*Codes &80...&ff inclusive are not used

*When a BASIC program is in memory, the BASIC ROM can replace "16-bit BASIC program line number" tokens with "16-bit BASIC program line memory address pointer".

When a program is loaded or saved, there will only be "16-bit BASIC program line number" tokens followed by a 16-bit number of the line.

When a program is running, BASIC will replace the "16-bit BASIC program line number" with the "16-bit BASIC program line memory address pointer" token, and replace the 16-bit line number with the memory address of the start of that line.

It does this to avoid having to lookup the address of the line each time.

* When a REM or ' is seen, the characters following it are output directly (i.e. the bytes are not tokenized) until the end of line or a ':' is seen.

* When a BASIC program is listed each line is converted to a string (this includes the line number and the tokens converted to their strings). There is a maximum length for this string of 256 characters. This means that if the BASIC line is LISTed or EDITed, then the line will be displayed incorrectly with missing characters on the end. This is also noticed if you have a "10-liner" program that packs as much BASIC as possible into each line and renumber it so the line number has more digits.

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

 In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form: 1 x 2<exponent> The representation uses 5 bytes and is stored using the following structure:

 

{| border="1"
|-
! Byte
! colspan="8" | 0
! colspan="8" | 1
! colspan="8" | 2
! colspan="8" | 3
! colspan="8" | 4
|-
! Bit
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
|-
| Function
| colspan="8" | (LSB) mantissa (bits 31-24)
| colspan="8" | mantissa (bits 23-16)
| colspan="8" | mantissa (bits 15-8)
| colspan="1" | sign
| colspan="7" | (MSB) mantissa (bits 7-0)
| colspan="8" | exponent
|}

=== Sign ===

The sign is represented by bit 7 of byte 3. The value of the sign bit indicates the sign of the floating point number.

#*If the sign bit is "1", then the number is negative.
#*If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4. It is stored with a bias of 128.

#*128-255 are positive exponents,
#*1-127 are negative exponents.
#*0 means, the number is zero

To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 1 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^127.
A value of 0 just means, that the number is zero (0).

=== BASIC Display of Floating point numbers ===

* Numbers are displayed to 9 decimal places.
* If the number doesn't have a fractional part (e.g. .0) then the fractional part is not displayed.
* Trailing zeros (zero digits after the last digit in the fraction) are not displayed
* The value is rounded in the following way for display:

If the 10th fractional digit is 5 or above, then the number is rounded up.
If the 10th fractional digit is 4 or below, then the number is rounded down.
e.g.
0.1234567891 is displayed as 0.123456789
0.1234567895 is displayed as 0.12345679

=== floating point example in RAM by MaV ===

The initial figure = 43.375.
An example in BASIC:
<pre>
a!=43.375
READY
PRINT a!
43.375
PRINT @a!
374
FOR I=0 TO 4:PRINT HEX$(PEEK(374+I),2);:NEXT I
0000802D86
</pre>
the result for better readability: 
'''00 00 80 2D 86''' 
The first byte contains the least significant bits of the mantissa, and every following byte up to the fourth byte contain the bits following the first in significance and in exactly that order!

That means that you have to turn around the first four bytes if you want to read the mantissa correctly:
2D800000
or
0010.1101.1000.0000.0000.0000.0000.0000
in binary (the stops are inserted for better readability).

Now the highest significant bit here is 0, so the number is positive.
What's more, you need to clear that bit and substitute the implied highest bit (see description in the link), which is always 1 (regardless of the deleted sign bit!!!).
Thus you get:
AD800000
or
1010.1101.1000.0000.0000.0000.0000.0000
in binary.

The mantissa has an implied decimal point before the number. Since the number is 2^32 bits (i.e. 4 bytes) long you have to divide by 2^32 to get the proper decimal representation.

AD800000 (hex) = 2910846976 (dec)

2910846976 / 2^32 = 0.677734375

The mantissa in a decimal representation is: 0.677734375

Now, the last byte contains the exponent: 86 (hex) or 134 (dec). You need to subtract 128 to get the real exponent, the highest bit tells you that the exponent is positive (1) or negative (0). Your exponent is 6.

0.677734375 * 2^6 = 43.375

'''Another example:''' 
PI is represented in memory as: 
'''A2 DA 0F 49 82''' 
The mantissa is 
490FDAA2 (highest significant bit is zero => number is positive)
The exponent is 
82 (=positive mantissa, value=2 thus multiply mantissa with 2^2) 

Delete the sign bit (which is 0 anyway), and then add the implied 1 bit: 
C90FDAA2 (hex) = 3373259426 (dec) = 1100.1001.0000.1111.1101.1010.1010.0010 (bin) 

Calculate the decimal representation of the mantissa: 
3373259426 / 2^32 = 0,7853981633670628070831298828125 

Then add the exponent (82h - 80h = 2 thus 2^2) 
0,7853981633670628070831298828125 * 2^2 = 3,14159265346825122833251953125 

Voilà! The internal representation of the number PI on the CPC is: 3,14159265346825122833251953125 

If you compare to a (more) correct representation of PI, you'll see that the CPC is correct up to the 9th decimal place: 

CPC: 
3.14159265346825122833251953125 
more correctly: 
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986...

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts. The biggest figure which can be stored correctly in RAM by a variable is 2^32-1 = 4294967295.

#*A integer variable is defined with a "!" character postfix.

e.g.
<pre>a! = 3.141592654
</pre>
#*A real number uses 5 bytes of memory as storage. The format is described above.
#*The address of a real variable can be found in BASIC by: <pre>PRINT @a!
</pre>

Where "a" should be replaced with the name of the variable.

 

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

 NOTES:

#*A integer variable is defined with a "%" character postfix.

e.g.
<pre>a% = 3
</pre>
#*A integer variable has a range of -32768 to 32767
#*A integer variable always uses two bytes of memory as storage with the following format:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 2
| Integer number
|}

#*The address of the integer variable can be found in BASIC by: <pre>PRINT @a%
</pre>

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

 NOTES:

#**A string variable is defined in BASIC with a "$" character postfix.

e.g.
<pre>a$ = "hello"
</pre>
#**A string variable is described internally by a "string descriptor block" which has the following structure:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 1
| Length of string in bytes/characters
|-
| 1
| 2
| Location of start of string
|}

#**The address of the "string descriptor block" for the string variable can be found in BASIC by typing: <pre>PRINT @a$
</pre>

replacing "a$" with the name of the string variable.

#**A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
#**A string variable can contain any ASCII character code in the range 0-255.
#**A string variable can store a minimum of 0 characters and a maximum of 255 characters.
#**The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Technical information about Locomotive BASIC

2025-08-24T09:13:37Z

Arnoldemu: /* Maximizing memory usage */

[[Category:Cpctech.org]]

'''''This article originally came from Kevin Thackers' archive at [http://www.cpctech.org.uk http://www.cpctech.org.uk].'''''

= Technical information about Locomotive BASIC =

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== BASIC v1.0 only ==

There is a region of memory between AC00-AC1B which is filled with RET instructions. The BASIC ROM calls the following locations:
AC01,AC04,AC07,AC0A,AC0D,AC10,AC13,AC16,AC19

It almost looks like these were used for debugging the ROM but were left in.

They can be used to implement new BASIC commands.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR". A binary function is accessed through BASIC using the "CALL" command.

Both RSX and CALL commands work (are!) similar from the BASIC command line and invoke machine code - the only difference is: with the help of a RSX command you don't need to know the exact access address. You can pass up to 32 parameters with a CALL or RSX command. Possible parameters could be integer, floating points and strings. Just store the parameter into a variable:
Passing for integer:
<pre>
CALL &4000,32,34,&5E,&x10101010
|RSX-command,32,34,&5E,&x10101010
</pre>
Passing for floating points
<pre>
@a!=43.375
CALL or |RSX-command,@a!
</pre>

 Passing a string parameter:
 BASIC v1.0
<pre>a$="A":|DRIVE,@a$
</pre>
BASIC v1.1:
<pre>|DRIVE,"A"
</pre>
or
<pre>
b$="test"
CALL or |RSX-command,@b$
</pre>

The parameters will be stored inside the range of Stack:
<pre>
A=n -------> MSB PARAM1
LSB PARAM1
MSB PARAM2
LSB PARAM2
...
...
...
MSB PARAMn
IX+0 ------> LSB PARAMn
</pre>
with the help of that assembly code is it possible to find the parameters:
<pre>
ROUT1: CP x ;test register A if "x" parameters were given, e.g. x = 2
RET NZ ; if not exactly x parameters then do not execute RSX.
LD L,(IX+0)
LD H,(IX+1) ; HL = value of last parameter
LD E,(IX+2)
LD D,(IX+3) ; DE = value of next to last parameter
...
</pre>
A register holds the number of parameters. IX points to each parameter. IX+0/IX+1 is the last parameter. This happens because each parameter in order is pushed onto the stack and IX then points to the last parameter pushed. Each parameter is a 16-bit value.

If a parameter is a string, then IX holds the address of the string descriptor which point to a 3 byte block. The first byte of the string descriptor is the length. The next 2 bytes are an address that point to the string in memory.

With the help of the variable container "@" it is also possible to get a result from an invoked mc-code back to basic.
In this case the parameter contains the address of the integer, floating point or string. You can modify these to give the result.
BASIC allocates the strings, so when you modify a string, do not write more characters than the original string.

Hint: the first two bytes at the end of stack shows the internal return address from BASIC interpreter where it was executed.

== Additional keywords and variables in BASIC v1.1 ==

#BASIC v1.1 has the following additional keywords:
#*COPYCHR$
#*CURSOR
#*DEC$
#*FILL
#*FRAME
#*GRAPHICS
#*MASK
#BASIC v1.1 has the following additional predefined variables:
#*DERR

 

== BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

There are some rules for assigning names for variables:
: - it is not allowed to define a variable starting with a figure (the system expect then programming mode and interpret it as a program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - different sign e.g.: a slash (doesn't depend which direction), a 'minus' sign, a 'and' sign can't be used in a variable names
: - after a dollar sign (for defining string variables) it is not allowed to use further signs
: - different defining functions together are not allowed (e.g. use '%' together with '$')

: - you can use 40 characters for a variable name
: - use ! for defining a REAL value variable (like the function DEFREAL but only for the assigned variable) > It's also possible to omit the exlamation mark because it's the default system declaration after powering on then CPC.
: - use % for defining a INTEGER value variable (like the function DEFINT but only for the assigned variable)
: - use $ for defining a STRING variable (like the function DEFSTR but only for the assigned variable)
: - Minimum line number is 1. Maximum line number is 65535.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

 

== Speeding up BASIC programs ==

To speed up BASIC programs following rules could help:
: - Avoid loops or a branching program structure if possible. Internally the operating system searches for the right line number always from the beginning of the program 'listing'. Often recurring subroutines (if necessary) should be at the beginning of RAM to speed up things.
: - Avoid the index variable after the <code>NEXT</code> command/statement (although it isn't a good program style)
: - Avoid spaces inside program code or remarks
: - Put lots of statements as possible in ONE line
: - Use variables instead of constants. A constant has always to be converted in a binary/digital format. A variable is already converted.
: - Dimensioning at the beginning of the program
: - Dimensioning your variables & pre-calculate
: - Avoid AND/OR/XOR in IF-THEN statements. It's faster to write IF ... THEN (statement 1).. IF ... THEN (statement 2).
: - Minimise string/char manipulation as this often requires memory allocations. (e.g. joining strings with +, use of MID$, LEFT$, RIGHT$, SPACE$)

== Maximizing memory usage ==

To maximize memory usage in BASIC here are some things to consider:
: - Minimize the size of your program by minimizing variable name length
: - Minimize the number of variables
: - Use as few lines as possible.
: - Use 8-bit/16-bit values in DATA statements if storing numbers. String data can also be a good way to store 8-bit data.
: - Minimize string operations. (e.g. A$=SPACE$(30)+CHR$(28) in memory this first allocates a string of length 30 containing spaces, then it allocates a new string of length 31 with spaces and char 28 at the end and assigns it to A$. In this line at least 30 bytes have been wasted. So consider if you need strings or perhaps if possible pre-define them).

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences. Each line of the BASIC program has the form:

 

{| border="1"
|-
! Offset
! Size
! Description
|-
| 0
| 2
| Length of line data in bytes (note 1)
|-
| 2
| 2
| 16-bit decimal integer line number (note 2)
|-
| 4
| n
| BASIC line encoded into tokens (note 3)
|-
| n+1
| 1
| "0" the end of line marker (note 4)
|}

 Notes:

#This 16-bit value has two functions: if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data, otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
#This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
#This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
#This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| end of tokenised line marker
|-
| &01
| ":" statement seperator
|-
| &02
| integer variable definition (defined with "%" suffix)
|-
| &03
| string variable definition (defined with "$" suffix)
|-
| &04
| floating point variable definition (defined with "!" suffix)
|-
| &05
| var?
|-
| &06
| var?
|-
| &07
| var?
|-
| &08
| var?
|-
| &09
| var?
|-
| &0a
| var?
|-
| &0b
| variable definition (no suffix)
|-
| &0c
| variable definition (no suffix)
|-
| &0d
| variable definition (no suffix)
|-
| &0e
| number constant "0"
|-
| &0f
| number constant "1"
|-
| &10
| number constant "2"
|-
| &11
| number constant "3"
|-
| &12
| number constant "4"
|-
| &13
| number constant "5"
|-
| &14
| number constant "6"
|-
| &15
| number constant "7"
|-
| &16
| number constant "8"
|-
| &17
| number constant "9"
|-
| &18
| number constant "10"
|-
| &19
| 8-bit integer decimal value
|-
| &1a
| 16-bit integer decimal value
|-
| &1b
| 16-bit integer binary value (with "&X" prefix)
|-
| &1c
| 16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
| &1d
| 16-bit BASIC program line memory address pointer (see notes)
|-
| &1e
| 16-bit integer BASIC line number
|-
| &1f
| floating point value
|-
| &20
| " " (space) symbol
|-
| &21
| ASCII "!" symbol
|-
| &22
| quoted string value
|-
| &23-7b
| ASCII printable symbols
|-
| &7c
| "|" symbol; prefix for RSX commands
|-
| &80
| AFTER
|-
| &81
| AUTO
|-
| &82
| BORDER
|-
| &83
| CALL
|-
| &84
| CAT
|-
| &85
| CHAIN
|-
| &86
| CLEAR
|-
| &87
| CLG
|-
| &88
| CLOSEIN
|-
| &89
| CLOSEOUT
|-
| &8a
| CLS
|-
| &8b
| CONT
|-
| &8c
| DATA
|-
| &8d
| DEF
|-
| &8e
| DEFINT
|-
| &8f
| DEFREAL
|-
| &90
| DEFSTR
|-
| &91
| DEG
|-
| &92
| DELETE
|-
| &93
| DIM
|-
| &94
| DRAW
|-
| &95
| DRAWR
|-
| &96
| EDIT
|-
| &97
| ELSE
|-
| &98
| END
|-
| &99
| ENT
|-
| &9a
| ENV
|-
| &9b
| ERASE
|-
| &9c
| ERROR
|-
| &9d
| EVERY
|-
| &9e
| FOR
|-
| &9f
| GOSUB, GO SUB
|-
| &a0
| GOTO, GO TO
|-
| &a1
| IF
|-
| &a2
| INK
|-
| &a3
| INPUT
|-
| &a4
| KEY
|-
| &a5
| LET
|-
| &a6
| LINE
|-
| &a7
| LIST
|-
| &a8
| LOAD
|-
| &a9
| LOCATE
|-
| &aa
| MEMORY
|-
| &ab
| MERGE
|-
| &ac
| MID$
|-
| &ad
| MODE
|-
| &ae
| MOVE
|-
| &af
| MOVER
|-
| &b0
| NEXT
|-
| &b1
| NEW
|-
| &b2
| ON
|-
| &b3
| ON BREAK
|-
| &b4
| ON ERROR GOTO, ON ERROR GO TO
|-
| &b5
| ON SQ
|-
| &b6
| OPENIN
|-
| &b7
| OPENOUT
|-
| &b8
| ORIGIN
|-
| &b9
| OUT
|-
| &ba
| PAPER
|-
| &bb
| PEN
|-
| &bc
| PLOT
|-
| &bd
| PLOTR
|-
| &be
| POKE
|-
| &bf
| PRINT
|-
| &c0
| "'" symbol (same function as REM keyword)
|-
| &c1
| RAD
|-
| &c2
| RANDOMIZE
|-
| &c3
| READ
|-
| &c4
| RELEASE
|-
| &c5
| REM
|-
| &c6
| RENUM
|-
| &c7
| RESTORE
|-
| &c8
| RESUME
|-
| &c9
| RETURN
|-
| &ca
| RUN
|-
| &cb
| SAVE
|-
| &cc
| SOUND
|-
| &cd
| SPEED
|-
| &ce
| STOP
|-
| &cf
| SYMBOL
|-
| &d0
| TAG
|-
| &d1
| TAGOFF
|-
| &d2
| TROFF
|-
| &d3
| TRON
|-
| &d4
| WAIT
|-
| &d5
| WEND
|-
| &d6
| WHILE
|-
| &d7
| WIDTH
|-
| &d8
| WINDOW
|-
| &d9
| WRITE
|-
| &da
| ZONE
|-
| &db
| DI
|-
| &dc
| EI
|-
| &dd
| FILL (v1.1)
|-
| &de
| GRAPHICS (v1.1)
|-
| &df
| MASK (v1.1)
|-
| &e0
| FRAME (v1.1)
|-
| &e1
| CURSOR (v1.1)
|-
| &e2
| (note 2)
|-
| &e3
| ERL
|-
| &e4
| FN
|-
| &e5
| SPC
|-
| &e6
| STEP
|-
| &e7
| SWAP
|-
| &e8
| (note 2)
|-
| &e9
| (note 2)
|-
| &ea
| TAB
|-
| &eb
| THEN
|-
| &ec
| TO
|-
| &ed
| USING
|-
| &ee
| > (greater than)
|-
| &ef
| = (equal)
|-
| &f0
| &gt=, > =, => (greater or equal)
|-
| &f1
| < (less than)
|-
| &f2
| <&gt, < > (not equal)
|-
| &f3
| =<, <=, < = (less than or equal)
|-
| &f4
| + (addition)
|-
| &f5
| - (subtraction or unary minus)
|-
| &f6
| * (multiplication)
|-
| &f7
| / (division)
|-
| &f8
| ^ (x to the power of y)
|-
| &f9
| \ (integer division)
|-
| &fa
| AND
|-
| &fb
| MOD
|-
| &fc
| OR
|-
| &fd
| XOR
|-
| &fe
| NOT
|-
| &ff
| (prefix for additional keywords)
|}

 Notes:

*The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
*&e2,&e8 and &e9 are not used
*&7c ("|") is a character prefix used to identify an RSX command. e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| "|" character prefix
|-
| 1
| 1
| 8-bit byte offset to tokens following RSX name.
|-
| 2
| x
| RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
|}

*This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &1a,&2d,&00 represents the integer number "&002d"="45".
*This token (&0B) is changed at run-time to &0D
*This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
*This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
*This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| &1f (note 1)
|-
| 1
| 5
| Floating point number (note 2)
|}

*#This byte is the BASIC token identifying a floating point number
*#These 5 bytes define the floating point number.
*The space symbol is used as a command seperator
*Variable definitions:
**The variable definition has the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| Token defining variable type
|-
| 2
| 2
| 16-bit Byte offset to variable value within tokenised BASIC program.
|-
| 4
| x
| Variable name
|}

 The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.

**The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
**The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
*String values:
**Each string value is prefixed with &22 token.
**All strings must be enclosed by double quote symbols (&quot). This symbols define the start and end of the string value.
**The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.

*After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

 This table list the BASIC tokens with a &ff prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| ABS
|-
| &01
| ASC
|-
| &02
| ATN
|-
| &03
| CHR$
|-
| &04
| CINT
|-
| &05
| COS
|-
| &06
| CREAL
|-
| &07
| EXP
|-
| &08
| FIX
|-
| &09
| FRE
|-
| &0a
| INKEY
|-
| &0b
| INP
|-
| &0c
| INT
|-
| &0d
| JOY
|-
| &0e
| LEN
|-
| &0f
| LOG
|-
| &10
| LOG10
|-
| &11
| LOWER$
|-
| &12
| PEEK
|-
| &13
| REMAIN
|-
| &14
| SGN
|-
| &15
| SIN
|-
| &16
| SPACE$
|-
| &17
| SQ
|-
| &18
| SQR
|-
| &19
| STR$
|-
| &1a
| TAN
|-
| &1b
| UNT
|-
| &1c
| UPPER$
|-
| &1d
| VAL
|-
|  
| (note 2)
|-
| &40
| EOF
|-
| &41
| ERR
|-
| &42
| HIMEM
|-
| &43
| INKEY$
|-
| &44
| PI
|-
| &45
| RND
|-
| &46
| TIME
|-
| &47
| XPOS
|-
| &48
| YPOS
|-
| &49
| DERR (v1.1)
|-
|  
| (note 3)
|-
| &71
| BIN$
|-
| &72
| DEC$ (v1.1)
|-
| &73
| HEX$
|-
| &74
| INSTR
|-
| &75
| LEFT$
|-
| &76
| MAX
|-
| &77
| MIN
|-
| &78
| POS
|-
| &79
| RIGHT$
|-
| &7a
| ROUND
|-
| &7b
| STRING$
|-
| &7c
| TEST
|-
| &7d
| TESTR
|-
| &7e
| COPYCHR$ (v1.1)
|-
| &7f
| VPOS
|-
|  
| (note 4)
|}

 NOTES:

*These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence: <pre>&FF,&00</pre>
*Codes &1e...&3f inclusive are not used
*Codes &4a...&6f inclusive are not used
*Codes &80...&ff inclusive are not used

*When a BASIC program is in memory, the BASIC ROM can replace "16-bit BASIC program line number" tokens with "16-bit BASIC program line memory address pointer".

When a program is loaded or saved, there will only be "16-bit BASIC program line number" tokens followed by a 16-bit number of the line.

When a program is running, BASIC will replace the "16-bit BASIC program line number" with the "16-bit BASIC program line memory address pointer" token, and replace the 16-bit line number with the memory address of the start of that line.

It does this to avoid having to lookup the address of the line each time.

* When a REM or ' is seen, the characters following it are output directly (i.e. the bytes are not tokenized) until the end of line or a ':' is seen.

* When a BASIC program is listed each line is converted to a string (this includes the line number and the tokens converted to their strings). There is a maximum length for this string of 256 characters. This means that if the BASIC line is LISTed or EDITed, then the line will be displayed incorrectly with missing characters on the end. This is also noticed if you have a "10-liner" program that packs as much BASIC as possible into each line and renumber it so the line number has more digits.

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

 In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form: 1 x 2<exponent> The representation uses 5 bytes and is stored using the following structure:

 

{| border="1"
|-
! Byte
! colspan="8" | 0
! colspan="8" | 1
! colspan="8" | 2
! colspan="8" | 3
! colspan="8" | 4
|-
! Bit
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
|-
| Function
| colspan="8" | (LSB) mantissa (bits 31-24)
| colspan="8" | mantissa (bits 23-16)
| colspan="8" | mantissa (bits 15-8)
| colspan="1" | sign
| colspan="7" | (MSB) mantissa (bits 7-0)
| colspan="8" | exponent
|}

=== Sign ===

The sign is represented by bit 7 of byte 3. The value of the sign bit indicates the sign of the floating point number.

#*If the sign bit is "1", then the number is negative.
#*If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4. It is stored with a bias of 128.

#*128-255 are positive exponents,
#*1-127 are negative exponents.
#*0 means, the number is zero

To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 1 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^127.
A value of 0 just means, that the number is zero (0).

=== BASIC Display of Floating point numbers ===

* Numbers are displayed to 9 decimal places.
* If the number doesn't have a fractional part (e.g. .0) then the fractional part is not displayed.
* Trailing zeros (zero digits after the last digit in the fraction) are not displayed
* The value is rounded in the following way for display:

If the 10th fractional digit is 5 or above, then the number is rounded up.
If the 10th fractional digit is 4 or below, then the number is rounded down.
e.g.
0.1234567891 is displayed as 0.123456789
0.1234567895 is displayed as 0.12345679

=== floating point example in RAM by MaV ===

The initial figure = 43.375.
An example in BASIC:
<pre>
a!=43.375
READY
PRINT a!
43.375
PRINT @a!
374
FOR I=0 TO 4:PRINT HEX$(PEEK(374+I),2);:NEXT I
0000802D86
</pre>
the result for better readability: 
'''00 00 80 2D 86''' 
The first byte contains the least significant bits of the mantissa, and every following byte up to the fourth byte contain the bits following the first in significance and in exactly that order!

That means that you have to turn around the first four bytes if you want to read the mantissa correctly:
2D800000
or
0010.1101.1000.0000.0000.0000.0000.0000
in binary (the stops are inserted for better readability).

Now the highest significant bit here is 0, so the number is positive.
What's more, you need to clear that bit and substitute the implied highest bit (see description in the link), which is always 1 (regardless of the deleted sign bit!!!).
Thus you get:
AD800000
or
1010.1101.1000.0000.0000.0000.0000.0000
in binary.

The mantissa has an implied decimal point before the number. Since the number is 2^32 bits (i.e. 4 bytes) long you have to divide by 2^32 to get the proper decimal representation.

AD800000 (hex) = 2910846976 (dec)

2910846976 / 2^32 = 0.677734375

The mantissa in a decimal representation is: 0.677734375

Now, the last byte contains the exponent: 86 (hex) or 134 (dec). You need to subtract 128 to get the real exponent, the highest bit tells you that the exponent is positive (1) or negative (0). Your exponent is 6.

0.677734375 * 2^6 = 43.375

'''Another example:''' 
PI is represented in memory as: 
'''A2 DA 0F 49 82''' 
The mantissa is 
490FDAA2 (highest significant bit is zero => number is positive)
The exponent is 
82 (=positive mantissa, value=2 thus multiply mantissa with 2^2) 

Delete the sign bit (which is 0 anyway), and then add the implied 1 bit: 
C90FDAA2 (hex) = 3373259426 (dec) = 1100.1001.0000.1111.1101.1010.1010.0010 (bin) 

Calculate the decimal representation of the mantissa: 
3373259426 / 2^32 = 0,7853981633670628070831298828125 

Then add the exponent (82h - 80h = 2 thus 2^2) 
0,7853981633670628070831298828125 * 2^2 = 3,14159265346825122833251953125 

Voilà! The internal representation of the number PI on the CPC is: 3,14159265346825122833251953125 

If you compare to a (more) correct representation of PI, you'll see that the CPC is correct up to the 9th decimal place: 

CPC: 
3.14159265346825122833251953125 
more correctly: 
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986...

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts. The biggest figure which can be stored correctly in RAM by a variable is 2^32-1 = 4294967295.

#*A integer variable is defined with a "!" character postfix.

e.g.
<pre>a! = 3.141592654
</pre>
#*A real number uses 5 bytes of memory as storage. The format is described above.
#*The address of a real variable can be found in BASIC by: <pre>PRINT @a!
</pre>

Where "a" should be replaced with the name of the variable.

 

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

 NOTES:

#*A integer variable is defined with a "%" character postfix.

e.g.
<pre>a% = 3
</pre>
#*A integer variable has a range of -32768 to 32767
#*A integer variable always uses two bytes of memory as storage with the following format:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 2
| Integer number
|}

#*The address of the integer variable can be found in BASIC by: <pre>PRINT @a%
</pre>

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

 NOTES:

#**A string variable is defined in BASIC with a "$" character postfix.

e.g.
<pre>a$ = "hello"
</pre>
#**A string variable is described internally by a "string descriptor block" which has the following structure:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 1
| Length of string in bytes/characters
|-
| 1
| 2
| Location of start of string
|}

#**The address of the "string descriptor block" for the string variable can be found in BASIC by typing: <pre>PRINT @a$
</pre>

replacing "a$" with the name of the string variable.

#**A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
#**A string variable can contain any ASCII character code in the range 0-255.
#**A string variable can store a minimum of 0 characters and a maximum of 255 characters.
#**The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Technical information about Locomotive BASIC

2025-08-24T09:05:48Z

Arnoldemu: /* Speeding up BASIC programs */

[[Category:Cpctech.org]]

'''''This article originally came from Kevin Thackers' archive at [http://www.cpctech.org.uk http://www.cpctech.org.uk].'''''

= Technical information about Locomotive BASIC =

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== BASIC v1.0 only ==

There is a region of memory between AC00-AC1B which is filled with RET instructions. The BASIC ROM calls the following locations:
AC01,AC04,AC07,AC0A,AC0D,AC10,AC13,AC16,AC19

It almost looks like these were used for debugging the ROM but were left in.

They can be used to implement new BASIC commands.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR". A binary function is accessed through BASIC using the "CALL" command.

Both RSX and CALL commands work (are!) similar from the BASIC command line and invoke machine code - the only difference is: with the help of a RSX command you don't need to know the exact access address. You can pass up to 32 parameters with a CALL or RSX command. Possible parameters could be integer, floating points and strings. Just store the parameter into a variable:
Passing for integer:
<pre>
CALL &4000,32,34,&5E,&x10101010
|RSX-command,32,34,&5E,&x10101010
</pre>
Passing for floating points
<pre>
@a!=43.375
CALL or |RSX-command,@a!
</pre>

 Passing a string parameter:
 BASIC v1.0
<pre>a$="A":|DRIVE,@a$
</pre>
BASIC v1.1:
<pre>|DRIVE,"A"
</pre>
or
<pre>
b$="test"
CALL or |RSX-command,@b$
</pre>

The parameters will be stored inside the range of Stack:
<pre>
A=n -------> MSB PARAM1
LSB PARAM1
MSB PARAM2
LSB PARAM2
...
...
...
MSB PARAMn
IX+0 ------> LSB PARAMn
</pre>
with the help of that assembly code is it possible to find the parameters:
<pre>
ROUT1: CP x ;test register A if "x" parameters were given, e.g. x = 2
RET NZ ; if not exactly x parameters then do not execute RSX.
LD L,(IX+0)
LD H,(IX+1) ; HL = value of last parameter
LD E,(IX+2)
LD D,(IX+3) ; DE = value of next to last parameter
...
</pre>
A register holds the number of parameters. IX points to each parameter. IX+0/IX+1 is the last parameter. This happens because each parameter in order is pushed onto the stack and IX then points to the last parameter pushed. Each parameter is a 16-bit value.

If a parameter is a string, then IX holds the address of the string descriptor which point to a 3 byte block. The first byte of the string descriptor is the length. The next 2 bytes are an address that point to the string in memory.

With the help of the variable container "@" it is also possible to get a result from an invoked mc-code back to basic.
In this case the parameter contains the address of the integer, floating point or string. You can modify these to give the result.
BASIC allocates the strings, so when you modify a string, do not write more characters than the original string.

Hint: the first two bytes at the end of stack shows the internal return address from BASIC interpreter where it was executed.

== Additional keywords and variables in BASIC v1.1 ==

#BASIC v1.1 has the following additional keywords:
#*COPYCHR$
#*CURSOR
#*DEC$
#*FILL
#*FRAME
#*GRAPHICS
#*MASK
#BASIC v1.1 has the following additional predefined variables:
#*DERR

 

== BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

There are some rules for assigning names for variables:
: - it is not allowed to define a variable starting with a figure (the system expect then programming mode and interpret it as a program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - different sign e.g.: a slash (doesn't depend which direction), a 'minus' sign, a 'and' sign can't be used in a variable names
: - after a dollar sign (for defining string variables) it is not allowed to use further signs
: - different defining functions together are not allowed (e.g. use '%' together with '$')

: - you can use 40 characters for a variable name
: - use ! for defining a REAL value variable (like the function DEFREAL but only for the assigned variable) > It's also possible to omit the exlamation mark because it's the default system declaration after powering on then CPC.
: - use % for defining a INTEGER value variable (like the function DEFINT but only for the assigned variable)
: - use $ for defining a STRING variable (like the function DEFSTR but only for the assigned variable)
: - Minimum line number is 1. Maximum line number is 65535.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

 

== Speeding up BASIC programs ==

To speed up BASIC programs following rules could help:
: - Avoid loops or a branching program structure if possible. Internally the operating system searches for the right line number always from the beginning of the program 'listing'. Often recurring subroutines (if necessary) should be at the beginning of RAM to speed up things.
: - Avoid the index variable after the <code>NEXT</code> command/statement (although it isn't a good program style)
: - Avoid spaces inside program code or remarks
: - Put lots of statements as possible in ONE line
: - Use variables instead of constants. A constant has always to be converted in a binary/digital format. A variable is already converted.
: - Dimensioning at the beginning of the program
: - Dimensioning your variables & pre-calculate
: - Avoid AND/OR/XOR in IF-THEN statements. It's faster to write IF ... THEN (statement 1).. IF ... THEN (statement 2).
: - Minimise string/char manipulation as this often requires memory allocations. (e.g. joining strings with +, use of MID$, LEFT$, RIGHT$, SPACE$)

== Maximizing memory usage ==

To maximize memory usage in BASIC:
: - Minimize the size of your BASIC program by minimizing variable name length
: - Use 8-bit/16-bit for storing DATA where possible
: - Minimize string operations. (e.g. joining strings allocates memory for the result)

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences. Each line of the BASIC program has the form:

 

{| border="1"
|-
! Offset
! Size
! Description
|-
| 0
| 2
| Length of line data in bytes (note 1)
|-
| 2
| 2
| 16-bit decimal integer line number (note 2)
|-
| 4
| n
| BASIC line encoded into tokens (note 3)
|-
| n+1
| 1
| "0" the end of line marker (note 4)
|}

 Notes:

#This 16-bit value has two functions: if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data, otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
#This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
#This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
#This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| end of tokenised line marker
|-
| &01
| ":" statement seperator
|-
| &02
| integer variable definition (defined with "%" suffix)
|-
| &03
| string variable definition (defined with "$" suffix)
|-
| &04
| floating point variable definition (defined with "!" suffix)
|-
| &05
| var?
|-
| &06
| var?
|-
| &07
| var?
|-
| &08
| var?
|-
| &09
| var?
|-
| &0a
| var?
|-
| &0b
| variable definition (no suffix)
|-
| &0c
| variable definition (no suffix)
|-
| &0d
| variable definition (no suffix)
|-
| &0e
| number constant "0"
|-
| &0f
| number constant "1"
|-
| &10
| number constant "2"
|-
| &11
| number constant "3"
|-
| &12
| number constant "4"
|-
| &13
| number constant "5"
|-
| &14
| number constant "6"
|-
| &15
| number constant "7"
|-
| &16
| number constant "8"
|-
| &17
| number constant "9"
|-
| &18
| number constant "10"
|-
| &19
| 8-bit integer decimal value
|-
| &1a
| 16-bit integer decimal value
|-
| &1b
| 16-bit integer binary value (with "&X" prefix)
|-
| &1c
| 16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
| &1d
| 16-bit BASIC program line memory address pointer (see notes)
|-
| &1e
| 16-bit integer BASIC line number
|-
| &1f
| floating point value
|-
| &20
| " " (space) symbol
|-
| &21
| ASCII "!" symbol
|-
| &22
| quoted string value
|-
| &23-7b
| ASCII printable symbols
|-
| &7c
| "|" symbol; prefix for RSX commands
|-
| &80
| AFTER
|-
| &81
| AUTO
|-
| &82
| BORDER
|-
| &83
| CALL
|-
| &84
| CAT
|-
| &85
| CHAIN
|-
| &86
| CLEAR
|-
| &87
| CLG
|-
| &88
| CLOSEIN
|-
| &89
| CLOSEOUT
|-
| &8a
| CLS
|-
| &8b
| CONT
|-
| &8c
| DATA
|-
| &8d
| DEF
|-
| &8e
| DEFINT
|-
| &8f
| DEFREAL
|-
| &90
| DEFSTR
|-
| &91
| DEG
|-
| &92
| DELETE
|-
| &93
| DIM
|-
| &94
| DRAW
|-
| &95
| DRAWR
|-
| &96
| EDIT
|-
| &97
| ELSE
|-
| &98
| END
|-
| &99
| ENT
|-
| &9a
| ENV
|-
| &9b
| ERASE
|-
| &9c
| ERROR
|-
| &9d
| EVERY
|-
| &9e
| FOR
|-
| &9f
| GOSUB, GO SUB
|-
| &a0
| GOTO, GO TO
|-
| &a1
| IF
|-
| &a2
| INK
|-
| &a3
| INPUT
|-
| &a4
| KEY
|-
| &a5
| LET
|-
| &a6
| LINE
|-
| &a7
| LIST
|-
| &a8
| LOAD
|-
| &a9
| LOCATE
|-
| &aa
| MEMORY
|-
| &ab
| MERGE
|-
| &ac
| MID$
|-
| &ad
| MODE
|-
| &ae
| MOVE
|-
| &af
| MOVER
|-
| &b0
| NEXT
|-
| &b1
| NEW
|-
| &b2
| ON
|-
| &b3
| ON BREAK
|-
| &b4
| ON ERROR GOTO, ON ERROR GO TO
|-
| &b5
| ON SQ
|-
| &b6
| OPENIN
|-
| &b7
| OPENOUT
|-
| &b8
| ORIGIN
|-
| &b9
| OUT
|-
| &ba
| PAPER
|-
| &bb
| PEN
|-
| &bc
| PLOT
|-
| &bd
| PLOTR
|-
| &be
| POKE
|-
| &bf
| PRINT
|-
| &c0
| "'" symbol (same function as REM keyword)
|-
| &c1
| RAD
|-
| &c2
| RANDOMIZE
|-
| &c3
| READ
|-
| &c4
| RELEASE
|-
| &c5
| REM
|-
| &c6
| RENUM
|-
| &c7
| RESTORE
|-
| &c8
| RESUME
|-
| &c9
| RETURN
|-
| &ca
| RUN
|-
| &cb
| SAVE
|-
| &cc
| SOUND
|-
| &cd
| SPEED
|-
| &ce
| STOP
|-
| &cf
| SYMBOL
|-
| &d0
| TAG
|-
| &d1
| TAGOFF
|-
| &d2
| TROFF
|-
| &d3
| TRON
|-
| &d4
| WAIT
|-
| &d5
| WEND
|-
| &d6
| WHILE
|-
| &d7
| WIDTH
|-
| &d8
| WINDOW
|-
| &d9
| WRITE
|-
| &da
| ZONE
|-
| &db
| DI
|-
| &dc
| EI
|-
| &dd
| FILL (v1.1)
|-
| &de
| GRAPHICS (v1.1)
|-
| &df
| MASK (v1.1)
|-
| &e0
| FRAME (v1.1)
|-
| &e1
| CURSOR (v1.1)
|-
| &e2
| (note 2)
|-
| &e3
| ERL
|-
| &e4
| FN
|-
| &e5
| SPC
|-
| &e6
| STEP
|-
| &e7
| SWAP
|-
| &e8
| (note 2)
|-
| &e9
| (note 2)
|-
| &ea
| TAB
|-
| &eb
| THEN
|-
| &ec
| TO
|-
| &ed
| USING
|-
| &ee
| > (greater than)
|-
| &ef
| = (equal)
|-
| &f0
| &gt=, > =, => (greater or equal)
|-
| &f1
| < (less than)
|-
| &f2
| <&gt, < > (not equal)
|-
| &f3
| =<, <=, < = (less than or equal)
|-
| &f4
| + (addition)
|-
| &f5
| - (subtraction or unary minus)
|-
| &f6
| * (multiplication)
|-
| &f7
| / (division)
|-
| &f8
| ^ (x to the power of y)
|-
| &f9
| \ (integer division)
|-
| &fa
| AND
|-
| &fb
| MOD
|-
| &fc
| OR
|-
| &fd
| XOR
|-
| &fe
| NOT
|-
| &ff
| (prefix for additional keywords)
|}

 Notes:

*The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
*&e2,&e8 and &e9 are not used
*&7c ("|") is a character prefix used to identify an RSX command. e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| "|" character prefix
|-
| 1
| 1
| 8-bit byte offset to tokens following RSX name.
|-
| 2
| x
| RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
|}

*This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &1a,&2d,&00 represents the integer number "&002d"="45".
*This token (&0B) is changed at run-time to &0D
*This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
*This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
*This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| &1f (note 1)
|-
| 1
| 5
| Floating point number (note 2)
|}

*#This byte is the BASIC token identifying a floating point number
*#These 5 bytes define the floating point number.
*The space symbol is used as a command seperator
*Variable definitions:
**The variable definition has the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| Token defining variable type
|-
| 2
| 2
| 16-bit Byte offset to variable value within tokenised BASIC program.
|-
| 4
| x
| Variable name
|}

 The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.

**The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
**The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
*String values:
**Each string value is prefixed with &22 token.
**All strings must be enclosed by double quote symbols (&quot). This symbols define the start and end of the string value.
**The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.

*After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

 This table list the BASIC tokens with a &ff prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| ABS
|-
| &01
| ASC
|-
| &02
| ATN
|-
| &03
| CHR$
|-
| &04
| CINT
|-
| &05
| COS
|-
| &06
| CREAL
|-
| &07
| EXP
|-
| &08
| FIX
|-
| &09
| FRE
|-
| &0a
| INKEY
|-
| &0b
| INP
|-
| &0c
| INT
|-
| &0d
| JOY
|-
| &0e
| LEN
|-
| &0f
| LOG
|-
| &10
| LOG10
|-
| &11
| LOWER$
|-
| &12
| PEEK
|-
| &13
| REMAIN
|-
| &14
| SGN
|-
| &15
| SIN
|-
| &16
| SPACE$
|-
| &17
| SQ
|-
| &18
| SQR
|-
| &19
| STR$
|-
| &1a
| TAN
|-
| &1b
| UNT
|-
| &1c
| UPPER$
|-
| &1d
| VAL
|-
|  
| (note 2)
|-
| &40
| EOF
|-
| &41
| ERR
|-
| &42
| HIMEM
|-
| &43
| INKEY$
|-
| &44
| PI
|-
| &45
| RND
|-
| &46
| TIME
|-
| &47
| XPOS
|-
| &48
| YPOS
|-
| &49
| DERR (v1.1)
|-
|  
| (note 3)
|-
| &71
| BIN$
|-
| &72
| DEC$ (v1.1)
|-
| &73
| HEX$
|-
| &74
| INSTR
|-
| &75
| LEFT$
|-
| &76
| MAX
|-
| &77
| MIN
|-
| &78
| POS
|-
| &79
| RIGHT$
|-
| &7a
| ROUND
|-
| &7b
| STRING$
|-
| &7c
| TEST
|-
| &7d
| TESTR
|-
| &7e
| COPYCHR$ (v1.1)
|-
| &7f
| VPOS
|-
|  
| (note 4)
|}

 NOTES:

*These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence: <pre>&FF,&00</pre>
*Codes &1e...&3f inclusive are not used
*Codes &4a...&6f inclusive are not used
*Codes &80...&ff inclusive are not used

*When a BASIC program is in memory, the BASIC ROM can replace "16-bit BASIC program line number" tokens with "16-bit BASIC program line memory address pointer".

When a program is loaded or saved, there will only be "16-bit BASIC program line number" tokens followed by a 16-bit number of the line.

When a program is running, BASIC will replace the "16-bit BASIC program line number" with the "16-bit BASIC program line memory address pointer" token, and replace the 16-bit line number with the memory address of the start of that line.

It does this to avoid having to lookup the address of the line each time.

* When a REM or ' is seen, the characters following it are output directly (i.e. the bytes are not tokenized) until the end of line or a ':' is seen.

* When a BASIC program is listed each line is converted to a string (this includes the line number and the tokens converted to their strings). There is a maximum length for this string of 256 characters. This means that if the BASIC line is LISTed or EDITed, then the line will be displayed incorrectly with missing characters on the end. This is also noticed if you have a "10-liner" program that packs as much BASIC as possible into each line and renumber it so the line number has more digits.

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

 In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form: 1 x 2<exponent> The representation uses 5 bytes and is stored using the following structure:

 

{| border="1"
|-
! Byte
! colspan="8" | 0
! colspan="8" | 1
! colspan="8" | 2
! colspan="8" | 3
! colspan="8" | 4
|-
! Bit
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
|-
| Function
| colspan="8" | (LSB) mantissa (bits 31-24)
| colspan="8" | mantissa (bits 23-16)
| colspan="8" | mantissa (bits 15-8)
| colspan="1" | sign
| colspan="7" | (MSB) mantissa (bits 7-0)
| colspan="8" | exponent
|}

=== Sign ===

The sign is represented by bit 7 of byte 3. The value of the sign bit indicates the sign of the floating point number.

#*If the sign bit is "1", then the number is negative.
#*If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4. It is stored with a bias of 128.

#*128-255 are positive exponents,
#*1-127 are negative exponents.
#*0 means, the number is zero

To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 1 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^127.
A value of 0 just means, that the number is zero (0).

=== BASIC Display of Floating point numbers ===

* Numbers are displayed to 9 decimal places.
* If the number doesn't have a fractional part (e.g. .0) then the fractional part is not displayed.
* Trailing zeros (zero digits after the last digit in the fraction) are not displayed
* The value is rounded in the following way for display:

If the 10th fractional digit is 5 or above, then the number is rounded up.
If the 10th fractional digit is 4 or below, then the number is rounded down.
e.g.
0.1234567891 is displayed as 0.123456789
0.1234567895 is displayed as 0.12345679

=== floating point example in RAM by MaV ===

The initial figure = 43.375.
An example in BASIC:
<pre>
a!=43.375
READY
PRINT a!
43.375
PRINT @a!
374
FOR I=0 TO 4:PRINT HEX$(PEEK(374+I),2);:NEXT I
0000802D86
</pre>
the result for better readability: 
'''00 00 80 2D 86''' 
The first byte contains the least significant bits of the mantissa, and every following byte up to the fourth byte contain the bits following the first in significance and in exactly that order!

That means that you have to turn around the first four bytes if you want to read the mantissa correctly:
2D800000
or
0010.1101.1000.0000.0000.0000.0000.0000
in binary (the stops are inserted for better readability).

Now the highest significant bit here is 0, so the number is positive.
What's more, you need to clear that bit and substitute the implied highest bit (see description in the link), which is always 1 (regardless of the deleted sign bit!!!).
Thus you get:
AD800000
or
1010.1101.1000.0000.0000.0000.0000.0000
in binary.

The mantissa has an implied decimal point before the number. Since the number is 2^32 bits (i.e. 4 bytes) long you have to divide by 2^32 to get the proper decimal representation.

AD800000 (hex) = 2910846976 (dec)

2910846976 / 2^32 = 0.677734375

The mantissa in a decimal representation is: 0.677734375

Now, the last byte contains the exponent: 86 (hex) or 134 (dec). You need to subtract 128 to get the real exponent, the highest bit tells you that the exponent is positive (1) or negative (0). Your exponent is 6.

0.677734375 * 2^6 = 43.375

'''Another example:''' 
PI is represented in memory as: 
'''A2 DA 0F 49 82''' 
The mantissa is 
490FDAA2 (highest significant bit is zero => number is positive)
The exponent is 
82 (=positive mantissa, value=2 thus multiply mantissa with 2^2) 

Delete the sign bit (which is 0 anyway), and then add the implied 1 bit: 
C90FDAA2 (hex) = 3373259426 (dec) = 1100.1001.0000.1111.1101.1010.1010.0010 (bin) 

Calculate the decimal representation of the mantissa: 
3373259426 / 2^32 = 0,7853981633670628070831298828125 

Then add the exponent (82h - 80h = 2 thus 2^2) 
0,7853981633670628070831298828125 * 2^2 = 3,14159265346825122833251953125 

Voilà! The internal representation of the number PI on the CPC is: 3,14159265346825122833251953125 

If you compare to a (more) correct representation of PI, you'll see that the CPC is correct up to the 9th decimal place: 

CPC: 
3.14159265346825122833251953125 
more correctly: 
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986...

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts. The biggest figure which can be stored correctly in RAM by a variable is 2^32-1 = 4294967295.

#*A integer variable is defined with a "!" character postfix.

e.g.
<pre>a! = 3.141592654
</pre>
#*A real number uses 5 bytes of memory as storage. The format is described above.
#*The address of a real variable can be found in BASIC by: <pre>PRINT @a!
</pre>

Where "a" should be replaced with the name of the variable.

 

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

 NOTES:

#*A integer variable is defined with a "%" character postfix.

e.g.
<pre>a% = 3
</pre>
#*A integer variable has a range of -32768 to 32767
#*A integer variable always uses two bytes of memory as storage with the following format:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 2
| Integer number
|}

#*The address of the integer variable can be found in BASIC by: <pre>PRINT @a%
</pre>

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

 NOTES:

#**A string variable is defined in BASIC with a "$" character postfix.

e.g.
<pre>a$ = "hello"
</pre>
#**A string variable is described internally by a "string descriptor block" which has the following structure:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 1
| Length of string in bytes/characters
|-
| 1
| 2
| Location of start of string
|}

#**The address of the "string descriptor block" for the string variable can be found in BASIC by typing: <pre>PRINT @a$
</pre>

replacing "a$" with the name of the string variable.

#**A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
#**A string variable can contain any ASCII character code in the range 0-255.
#**A string variable can store a minimum of 0 characters and a maximum of 255 characters.
#**The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Technical information about Locomotive BASIC

2025-08-24T09:04:39Z

Arnoldemu: /* Speeding up BASIC programs */

[[Category:Cpctech.org]]

'''''This article originally came from Kevin Thackers' archive at [http://www.cpctech.org.uk http://www.cpctech.org.uk].'''''

= Technical information about Locomotive BASIC =

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== BASIC v1.0 only ==

There is a region of memory between AC00-AC1B which is filled with RET instructions. The BASIC ROM calls the following locations:
AC01,AC04,AC07,AC0A,AC0D,AC10,AC13,AC16,AC19

It almost looks like these were used for debugging the ROM but were left in.

They can be used to implement new BASIC commands.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR". A binary function is accessed through BASIC using the "CALL" command.

Both RSX and CALL commands work (are!) similar from the BASIC command line and invoke machine code - the only difference is: with the help of a RSX command you don't need to know the exact access address. You can pass up to 32 parameters with a CALL or RSX command. Possible parameters could be integer, floating points and strings. Just store the parameter into a variable:
Passing for integer:
<pre>
CALL &4000,32,34,&5E,&x10101010
|RSX-command,32,34,&5E,&x10101010
</pre>
Passing for floating points
<pre>
@a!=43.375
CALL or |RSX-command,@a!
</pre>

 Passing a string parameter:
 BASIC v1.0
<pre>a$="A":|DRIVE,@a$
</pre>
BASIC v1.1:
<pre>|DRIVE,"A"
</pre>
or
<pre>
b$="test"
CALL or |RSX-command,@b$
</pre>

The parameters will be stored inside the range of Stack:
<pre>
A=n -------> MSB PARAM1
LSB PARAM1
MSB PARAM2
LSB PARAM2
...
...
...
MSB PARAMn
IX+0 ------> LSB PARAMn
</pre>
with the help of that assembly code is it possible to find the parameters:
<pre>
ROUT1: CP x ;test register A if "x" parameters were given, e.g. x = 2
RET NZ ; if not exactly x parameters then do not execute RSX.
LD L,(IX+0)
LD H,(IX+1) ; HL = value of last parameter
LD E,(IX+2)
LD D,(IX+3) ; DE = value of next to last parameter
...
</pre>
A register holds the number of parameters. IX points to each parameter. IX+0/IX+1 is the last parameter. This happens because each parameter in order is pushed onto the stack and IX then points to the last parameter pushed. Each parameter is a 16-bit value.

If a parameter is a string, then IX holds the address of the string descriptor which point to a 3 byte block. The first byte of the string descriptor is the length. The next 2 bytes are an address that point to the string in memory.

With the help of the variable container "@" it is also possible to get a result from an invoked mc-code back to basic.
In this case the parameter contains the address of the integer, floating point or string. You can modify these to give the result.
BASIC allocates the strings, so when you modify a string, do not write more characters than the original string.

Hint: the first two bytes at the end of stack shows the internal return address from BASIC interpreter where it was executed.

== Additional keywords and variables in BASIC v1.1 ==

#BASIC v1.1 has the following additional keywords:
#*COPYCHR$
#*CURSOR
#*DEC$
#*FILL
#*FRAME
#*GRAPHICS
#*MASK
#BASIC v1.1 has the following additional predefined variables:
#*DERR

 

== BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

There are some rules for assigning names for variables:
: - it is not allowed to define a variable starting with a figure (the system expect then programming mode and interpret it as a program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - different sign e.g.: a slash (doesn't depend which direction), a 'minus' sign, a 'and' sign can't be used in a variable names
: - after a dollar sign (for defining string variables) it is not allowed to use further signs
: - different defining functions together are not allowed (e.g. use '%' together with '$')

: - you can use 40 characters for a variable name
: - use ! for defining a REAL value variable (like the function DEFREAL but only for the assigned variable) > It's also possible to omit the exlamation mark because it's the default system declaration after powering on then CPC.
: - use % for defining a INTEGER value variable (like the function DEFINT but only for the assigned variable)
: - use $ for defining a STRING variable (like the function DEFSTR but only for the assigned variable)
: - Minimum line number is 1. Maximum line number is 65535.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

 

== Speeding up BASIC programs ==

To speed up BASIC programs following rules could help:
: - Avoid loops or a branching program structure if possible. Internally the operating system searches for the right line number always from the beginning of the program 'listing'. Often recurring subroutines (if necessary) should be at the beginning of RAM to speed up things.
: - Avoid the index variable after the <code>NEXT</code> command/statement (although it isn't a good program style)
: - Avoid spaces inside program code or remarks
: - Put lots of statements as possible in ONE line
: - Use variables instead of constants. A constant has always to be converted in a binary/digital format. A variable is already converted.
: - Dimensioning at the beginning of the program
: - Dimensioning your variables & pre-calculate
: - Avoid AND/OR/XOR in IF-THEN statements. It's faster to write IF ... THEN (statement 1).. IF ... THEN (statement 2).
: - Avoid lots of string/char operations (e.g. joining strings with +, MID$)

== Maximizing memory usage ==

To maximize memory usage in BASIC:
: - Minimize the size of your BASIC program by minimizing variable name length
: - Use 8-bit/16-bit for storing DATA where possible
: - Minimize string operations. (e.g. joining strings allocates memory for the result)

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences. Each line of the BASIC program has the form:

 

{| border="1"
|-
! Offset
! Size
! Description
|-
| 0
| 2
| Length of line data in bytes (note 1)
|-
| 2
| 2
| 16-bit decimal integer line number (note 2)
|-
| 4
| n
| BASIC line encoded into tokens (note 3)
|-
| n+1
| 1
| "0" the end of line marker (note 4)
|}

 Notes:

#This 16-bit value has two functions: if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data, otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
#This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
#This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
#This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| end of tokenised line marker
|-
| &01
| ":" statement seperator
|-
| &02
| integer variable definition (defined with "%" suffix)
|-
| &03
| string variable definition (defined with "$" suffix)
|-
| &04
| floating point variable definition (defined with "!" suffix)
|-
| &05
| var?
|-
| &06
| var?
|-
| &07
| var?
|-
| &08
| var?
|-
| &09
| var?
|-
| &0a
| var?
|-
| &0b
| variable definition (no suffix)
|-
| &0c
| variable definition (no suffix)
|-
| &0d
| variable definition (no suffix)
|-
| &0e
| number constant "0"
|-
| &0f
| number constant "1"
|-
| &10
| number constant "2"
|-
| &11
| number constant "3"
|-
| &12
| number constant "4"
|-
| &13
| number constant "5"
|-
| &14
| number constant "6"
|-
| &15
| number constant "7"
|-
| &16
| number constant "8"
|-
| &17
| number constant "9"
|-
| &18
| number constant "10"
|-
| &19
| 8-bit integer decimal value
|-
| &1a
| 16-bit integer decimal value
|-
| &1b
| 16-bit integer binary value (with "&X" prefix)
|-
| &1c
| 16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
| &1d
| 16-bit BASIC program line memory address pointer (see notes)
|-
| &1e
| 16-bit integer BASIC line number
|-
| &1f
| floating point value
|-
| &20
| " " (space) symbol
|-
| &21
| ASCII "!" symbol
|-
| &22
| quoted string value
|-
| &23-7b
| ASCII printable symbols
|-
| &7c
| "|" symbol; prefix for RSX commands
|-
| &80
| AFTER
|-
| &81
| AUTO
|-
| &82
| BORDER
|-
| &83
| CALL
|-
| &84
| CAT
|-
| &85
| CHAIN
|-
| &86
| CLEAR
|-
| &87
| CLG
|-
| &88
| CLOSEIN
|-
| &89
| CLOSEOUT
|-
| &8a
| CLS
|-
| &8b
| CONT
|-
| &8c
| DATA
|-
| &8d
| DEF
|-
| &8e
| DEFINT
|-
| &8f
| DEFREAL
|-
| &90
| DEFSTR
|-
| &91
| DEG
|-
| &92
| DELETE
|-
| &93
| DIM
|-
| &94
| DRAW
|-
| &95
| DRAWR
|-
| &96
| EDIT
|-
| &97
| ELSE
|-
| &98
| END
|-
| &99
| ENT
|-
| &9a
| ENV
|-
| &9b
| ERASE
|-
| &9c
| ERROR
|-
| &9d
| EVERY
|-
| &9e
| FOR
|-
| &9f
| GOSUB, GO SUB
|-
| &a0
| GOTO, GO TO
|-
| &a1
| IF
|-
| &a2
| INK
|-
| &a3
| INPUT
|-
| &a4
| KEY
|-
| &a5
| LET
|-
| &a6
| LINE
|-
| &a7
| LIST
|-
| &a8
| LOAD
|-
| &a9
| LOCATE
|-
| &aa
| MEMORY
|-
| &ab
| MERGE
|-
| &ac
| MID$
|-
| &ad
| MODE
|-
| &ae
| MOVE
|-
| &af
| MOVER
|-
| &b0
| NEXT
|-
| &b1
| NEW
|-
| &b2
| ON
|-
| &b3
| ON BREAK
|-
| &b4
| ON ERROR GOTO, ON ERROR GO TO
|-
| &b5
| ON SQ
|-
| &b6
| OPENIN
|-
| &b7
| OPENOUT
|-
| &b8
| ORIGIN
|-
| &b9
| OUT
|-
| &ba
| PAPER
|-
| &bb
| PEN
|-
| &bc
| PLOT
|-
| &bd
| PLOTR
|-
| &be
| POKE
|-
| &bf
| PRINT
|-
| &c0
| "'" symbol (same function as REM keyword)
|-
| &c1
| RAD
|-
| &c2
| RANDOMIZE
|-
| &c3
| READ
|-
| &c4
| RELEASE
|-
| &c5
| REM
|-
| &c6
| RENUM
|-
| &c7
| RESTORE
|-
| &c8
| RESUME
|-
| &c9
| RETURN
|-
| &ca
| RUN
|-
| &cb
| SAVE
|-
| &cc
| SOUND
|-
| &cd
| SPEED
|-
| &ce
| STOP
|-
| &cf
| SYMBOL
|-
| &d0
| TAG
|-
| &d1
| TAGOFF
|-
| &d2
| TROFF
|-
| &d3
| TRON
|-
| &d4
| WAIT
|-
| &d5
| WEND
|-
| &d6
| WHILE
|-
| &d7
| WIDTH
|-
| &d8
| WINDOW
|-
| &d9
| WRITE
|-
| &da
| ZONE
|-
| &db
| DI
|-
| &dc
| EI
|-
| &dd
| FILL (v1.1)
|-
| &de
| GRAPHICS (v1.1)
|-
| &df
| MASK (v1.1)
|-
| &e0
| FRAME (v1.1)
|-
| &e1
| CURSOR (v1.1)
|-
| &e2
| (note 2)
|-
| &e3
| ERL
|-
| &e4
| FN
|-
| &e5
| SPC
|-
| &e6
| STEP
|-
| &e7
| SWAP
|-
| &e8
| (note 2)
|-
| &e9
| (note 2)
|-
| &ea
| TAB
|-
| &eb
| THEN
|-
| &ec
| TO
|-
| &ed
| USING
|-
| &ee
| > (greater than)
|-
| &ef
| = (equal)
|-
| &f0
| &gt=, > =, => (greater or equal)
|-
| &f1
| < (less than)
|-
| &f2
| <&gt, < > (not equal)
|-
| &f3
| =<, <=, < = (less than or equal)
|-
| &f4
| + (addition)
|-
| &f5
| - (subtraction or unary minus)
|-
| &f6
| * (multiplication)
|-
| &f7
| / (division)
|-
| &f8
| ^ (x to the power of y)
|-
| &f9
| \ (integer division)
|-
| &fa
| AND
|-
| &fb
| MOD
|-
| &fc
| OR
|-
| &fd
| XOR
|-
| &fe
| NOT
|-
| &ff
| (prefix for additional keywords)
|}

 Notes:

*The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
*&e2,&e8 and &e9 are not used
*&7c ("|") is a character prefix used to identify an RSX command. e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| "|" character prefix
|-
| 1
| 1
| 8-bit byte offset to tokens following RSX name.
|-
| 2
| x
| RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
|}

*This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &1a,&2d,&00 represents the integer number "&002d"="45".
*This token (&0B) is changed at run-time to &0D
*This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
*This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
*This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| &1f (note 1)
|-
| 1
| 5
| Floating point number (note 2)
|}

*#This byte is the BASIC token identifying a floating point number
*#These 5 bytes define the floating point number.
*The space symbol is used as a command seperator
*Variable definitions:
**The variable definition has the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| Token defining variable type
|-
| 2
| 2
| 16-bit Byte offset to variable value within tokenised BASIC program.
|-
| 4
| x
| Variable name
|}

 The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.

**The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
**The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
*String values:
**Each string value is prefixed with &22 token.
**All strings must be enclosed by double quote symbols (&quot). This symbols define the start and end of the string value.
**The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.

*After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

 This table list the BASIC tokens with a &ff prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| ABS
|-
| &01
| ASC
|-
| &02
| ATN
|-
| &03
| CHR$
|-
| &04
| CINT
|-
| &05
| COS
|-
| &06
| CREAL
|-
| &07
| EXP
|-
| &08
| FIX
|-
| &09
| FRE
|-
| &0a
| INKEY
|-
| &0b
| INP
|-
| &0c
| INT
|-
| &0d
| JOY
|-
| &0e
| LEN
|-
| &0f
| LOG
|-
| &10
| LOG10
|-
| &11
| LOWER$
|-
| &12
| PEEK
|-
| &13
| REMAIN
|-
| &14
| SGN
|-
| &15
| SIN
|-
| &16
| SPACE$
|-
| &17
| SQ
|-
| &18
| SQR
|-
| &19
| STR$
|-
| &1a
| TAN
|-
| &1b
| UNT
|-
| &1c
| UPPER$
|-
| &1d
| VAL
|-
|  
| (note 2)
|-
| &40
| EOF
|-
| &41
| ERR
|-
| &42
| HIMEM
|-
| &43
| INKEY$
|-
| &44
| PI
|-
| &45
| RND
|-
| &46
| TIME
|-
| &47
| XPOS
|-
| &48
| YPOS
|-
| &49
| DERR (v1.1)
|-
|  
| (note 3)
|-
| &71
| BIN$
|-
| &72
| DEC$ (v1.1)
|-
| &73
| HEX$
|-
| &74
| INSTR
|-
| &75
| LEFT$
|-
| &76
| MAX
|-
| &77
| MIN
|-
| &78
| POS
|-
| &79
| RIGHT$
|-
| &7a
| ROUND
|-
| &7b
| STRING$
|-
| &7c
| TEST
|-
| &7d
| TESTR
|-
| &7e
| COPYCHR$ (v1.1)
|-
| &7f
| VPOS
|-
|  
| (note 4)
|}

 NOTES:

*These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence: <pre>&FF,&00</pre>
*Codes &1e...&3f inclusive are not used
*Codes &4a...&6f inclusive are not used
*Codes &80...&ff inclusive are not used

*When a BASIC program is in memory, the BASIC ROM can replace "16-bit BASIC program line number" tokens with "16-bit BASIC program line memory address pointer".

When a program is loaded or saved, there will only be "16-bit BASIC program line number" tokens followed by a 16-bit number of the line.

When a program is running, BASIC will replace the "16-bit BASIC program line number" with the "16-bit BASIC program line memory address pointer" token, and replace the 16-bit line number with the memory address of the start of that line.

It does this to avoid having to lookup the address of the line each time.

* When a REM or ' is seen, the characters following it are output directly (i.e. the bytes are not tokenized) until the end of line or a ':' is seen.

* When a BASIC program is listed each line is converted to a string (this includes the line number and the tokens converted to their strings). There is a maximum length for this string of 256 characters. This means that if the BASIC line is LISTed or EDITed, then the line will be displayed incorrectly with missing characters on the end. This is also noticed if you have a "10-liner" program that packs as much BASIC as possible into each line and renumber it so the line number has more digits.

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

 In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form: 1 x 2<exponent> The representation uses 5 bytes and is stored using the following structure:

 

{| border="1"
|-
! Byte
! colspan="8" | 0
! colspan="8" | 1
! colspan="8" | 2
! colspan="8" | 3
! colspan="8" | 4
|-
! Bit
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
|-
| Function
| colspan="8" | (LSB) mantissa (bits 31-24)
| colspan="8" | mantissa (bits 23-16)
| colspan="8" | mantissa (bits 15-8)
| colspan="1" | sign
| colspan="7" | (MSB) mantissa (bits 7-0)
| colspan="8" | exponent
|}

=== Sign ===

The sign is represented by bit 7 of byte 3. The value of the sign bit indicates the sign of the floating point number.

#*If the sign bit is "1", then the number is negative.
#*If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4. It is stored with a bias of 128.

#*128-255 are positive exponents,
#*1-127 are negative exponents.
#*0 means, the number is zero

To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 1 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^127.
A value of 0 just means, that the number is zero (0).

=== BASIC Display of Floating point numbers ===

* Numbers are displayed to 9 decimal places.
* If the number doesn't have a fractional part (e.g. .0) then the fractional part is not displayed.
* Trailing zeros (zero digits after the last digit in the fraction) are not displayed
* The value is rounded in the following way for display:

If the 10th fractional digit is 5 or above, then the number is rounded up.
If the 10th fractional digit is 4 or below, then the number is rounded down.
e.g.
0.1234567891 is displayed as 0.123456789
0.1234567895 is displayed as 0.12345679

=== floating point example in RAM by MaV ===

The initial figure = 43.375.
An example in BASIC:
<pre>
a!=43.375
READY
PRINT a!
43.375
PRINT @a!
374
FOR I=0 TO 4:PRINT HEX$(PEEK(374+I),2);:NEXT I
0000802D86
</pre>
the result for better readability: 
'''00 00 80 2D 86''' 
The first byte contains the least significant bits of the mantissa, and every following byte up to the fourth byte contain the bits following the first in significance and in exactly that order!

That means that you have to turn around the first four bytes if you want to read the mantissa correctly:
2D800000
or
0010.1101.1000.0000.0000.0000.0000.0000
in binary (the stops are inserted for better readability).

Now the highest significant bit here is 0, so the number is positive.
What's more, you need to clear that bit and substitute the implied highest bit (see description in the link), which is always 1 (regardless of the deleted sign bit!!!).
Thus you get:
AD800000
or
1010.1101.1000.0000.0000.0000.0000.0000
in binary.

The mantissa has an implied decimal point before the number. Since the number is 2^32 bits (i.e. 4 bytes) long you have to divide by 2^32 to get the proper decimal representation.

AD800000 (hex) = 2910846976 (dec)

2910846976 / 2^32 = 0.677734375

The mantissa in a decimal representation is: 0.677734375

Now, the last byte contains the exponent: 86 (hex) or 134 (dec). You need to subtract 128 to get the real exponent, the highest bit tells you that the exponent is positive (1) or negative (0). Your exponent is 6.

0.677734375 * 2^6 = 43.375

'''Another example:''' 
PI is represented in memory as: 
'''A2 DA 0F 49 82''' 
The mantissa is 
490FDAA2 (highest significant bit is zero => number is positive)
The exponent is 
82 (=positive mantissa, value=2 thus multiply mantissa with 2^2) 

Delete the sign bit (which is 0 anyway), and then add the implied 1 bit: 
C90FDAA2 (hex) = 3373259426 (dec) = 1100.1001.0000.1111.1101.1010.1010.0010 (bin) 

Calculate the decimal representation of the mantissa: 
3373259426 / 2^32 = 0,7853981633670628070831298828125 

Then add the exponent (82h - 80h = 2 thus 2^2) 
0,7853981633670628070831298828125 * 2^2 = 3,14159265346825122833251953125 

Voilà! The internal representation of the number PI on the CPC is: 3,14159265346825122833251953125 

If you compare to a (more) correct representation of PI, you'll see that the CPC is correct up to the 9th decimal place: 

CPC: 
3.14159265346825122833251953125 
more correctly: 
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986...

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts. The biggest figure which can be stored correctly in RAM by a variable is 2^32-1 = 4294967295.

#*A integer variable is defined with a "!" character postfix.

e.g.
<pre>a! = 3.141592654
</pre>
#*A real number uses 5 bytes of memory as storage. The format is described above.
#*The address of a real variable can be found in BASIC by: <pre>PRINT @a!
</pre>

Where "a" should be replaced with the name of the variable.

 

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

 NOTES:

#*A integer variable is defined with a "%" character postfix.

e.g.
<pre>a% = 3
</pre>
#*A integer variable has a range of -32768 to 32767
#*A integer variable always uses two bytes of memory as storage with the following format:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 2
| Integer number
|}

#*The address of the integer variable can be found in BASIC by: <pre>PRINT @a%
</pre>

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

 NOTES:

#**A string variable is defined in BASIC with a "$" character postfix.

e.g.
<pre>a$ = "hello"
</pre>
#**A string variable is described internally by a "string descriptor block" which has the following structure:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 1
| Length of string in bytes/characters
|-
| 1
| 2
| Location of start of string
|}

#**The address of the "string descriptor block" for the string variable can be found in BASIC by typing: <pre>PRINT @a$
</pre>

replacing "a$" with the name of the string variable.

#**A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
#**A string variable can contain any ASCII character code in the range 0-255.
#**A string variable can store a minimum of 0 characters and a maximum of 255 characters.
#**The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Technical information about Locomotive BASIC

2025-08-24T09:03:00Z

Arnoldemu: /* Speeding up BASIC programs */

[[Category:Cpctech.org]]

'''''This article originally came from Kevin Thackers' archive at [http://www.cpctech.org.uk http://www.cpctech.org.uk].'''''

= Technical information about Locomotive BASIC =

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== BASIC v1.0 only ==

There is a region of memory between AC00-AC1B which is filled with RET instructions. The BASIC ROM calls the following locations:
AC01,AC04,AC07,AC0A,AC0D,AC10,AC13,AC16,AC19

It almost looks like these were used for debugging the ROM but were left in.

They can be used to implement new BASIC commands.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR". A binary function is accessed through BASIC using the "CALL" command.

Both RSX and CALL commands work (are!) similar from the BASIC command line and invoke machine code - the only difference is: with the help of a RSX command you don't need to know the exact access address. You can pass up to 32 parameters with a CALL or RSX command. Possible parameters could be integer, floating points and strings. Just store the parameter into a variable:
Passing for integer:
<pre>
CALL &4000,32,34,&5E,&x10101010
|RSX-command,32,34,&5E,&x10101010
</pre>
Passing for floating points
<pre>
@a!=43.375
CALL or |RSX-command,@a!
</pre>

 Passing a string parameter:
 BASIC v1.0
<pre>a$="A":|DRIVE,@a$
</pre>
BASIC v1.1:
<pre>|DRIVE,"A"
</pre>
or
<pre>
b$="test"
CALL or |RSX-command,@b$
</pre>

The parameters will be stored inside the range of Stack:
<pre>
A=n -------> MSB PARAM1
LSB PARAM1
MSB PARAM2
LSB PARAM2
...
...
...
MSB PARAMn
IX+0 ------> LSB PARAMn
</pre>
with the help of that assembly code is it possible to find the parameters:
<pre>
ROUT1: CP x ;test register A if "x" parameters were given, e.g. x = 2
RET NZ ; if not exactly x parameters then do not execute RSX.
LD L,(IX+0)
LD H,(IX+1) ; HL = value of last parameter
LD E,(IX+2)
LD D,(IX+3) ; DE = value of next to last parameter
...
</pre>
A register holds the number of parameters. IX points to each parameter. IX+0/IX+1 is the last parameter. This happens because each parameter in order is pushed onto the stack and IX then points to the last parameter pushed. Each parameter is a 16-bit value.

If a parameter is a string, then IX holds the address of the string descriptor which point to a 3 byte block. The first byte of the string descriptor is the length. The next 2 bytes are an address that point to the string in memory.

With the help of the variable container "@" it is also possible to get a result from an invoked mc-code back to basic.
In this case the parameter contains the address of the integer, floating point or string. You can modify these to give the result.
BASIC allocates the strings, so when you modify a string, do not write more characters than the original string.

Hint: the first two bytes at the end of stack shows the internal return address from BASIC interpreter where it was executed.

== Additional keywords and variables in BASIC v1.1 ==

#BASIC v1.1 has the following additional keywords:
#*COPYCHR$
#*CURSOR
#*DEC$
#*FILL
#*FRAME
#*GRAPHICS
#*MASK
#BASIC v1.1 has the following additional predefined variables:
#*DERR

 

== BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

There are some rules for assigning names for variables:
: - it is not allowed to define a variable starting with a figure (the system expect then programming mode and interpret it as a program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - different sign e.g.: a slash (doesn't depend which direction), a 'minus' sign, a 'and' sign can't be used in a variable names
: - after a dollar sign (for defining string variables) it is not allowed to use further signs
: - different defining functions together are not allowed (e.g. use '%' together with '$')

: - you can use 40 characters for a variable name
: - use ! for defining a REAL value variable (like the function DEFREAL but only for the assigned variable) > It's also possible to omit the exlamation mark because it's the default system declaration after powering on then CPC.
: - use % for defining a INTEGER value variable (like the function DEFINT but only for the assigned variable)
: - use $ for defining a STRING variable (like the function DEFSTR but only for the assigned variable)
: - Minimum line number is 1. Maximum line number is 65535.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

 

== Speeding up BASIC programs ==

To speed up BASIC programs following rules could help:
: - Avoid loops or a branching program structure if possible. Internally the operating system searches for the right line number always from the beginning of the program 'listing'. Often recurring subroutines (if necessary) should be at the beginning of RAM to speed up things.
: - Avoid the index variable after the <code>NEXT</code> command/statement (although it isn't a good program style)
: - Avoid spaces inside program code or remarks
: - Put lots of statements as possible in ONE line
: - Use variables instead of constants. A constand has always to be converted in a binary/digital format. A variable is already converted.
: - Dimensioning at the beginning of the program
: - Dimensioning your variables & pre-calculate
: - Avoid AND/OR/XOR in IF-THEN statements. It's faster to write IF ... THEN (statement 1).. IF ... THEN (statement 2).
: - Avoid lots of string/char operations (e.g. joining strings with +, MID$)

== Maximizing memory usage ==

To maximize memory usage in BASIC:
: - Minimize the size of your BASIC program by minimizing variable name length
: - Use 8-bit/16-bit for storing DATA where possible
: - Minimize string operations. (e.g. joining strings allocates memory for the result)

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences. Each line of the BASIC program has the form:

 

{| border="1"
|-
! Offset
! Size
! Description
|-
| 0
| 2
| Length of line data in bytes (note 1)
|-
| 2
| 2
| 16-bit decimal integer line number (note 2)
|-
| 4
| n
| BASIC line encoded into tokens (note 3)
|-
| n+1
| 1
| "0" the end of line marker (note 4)
|}

 Notes:

#This 16-bit value has two functions: if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data, otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
#This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
#This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
#This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| end of tokenised line marker
|-
| &01
| ":" statement seperator
|-
| &02
| integer variable definition (defined with "%" suffix)
|-
| &03
| string variable definition (defined with "$" suffix)
|-
| &04
| floating point variable definition (defined with "!" suffix)
|-
| &05
| var?
|-
| &06
| var?
|-
| &07
| var?
|-
| &08
| var?
|-
| &09
| var?
|-
| &0a
| var?
|-
| &0b
| variable definition (no suffix)
|-
| &0c
| variable definition (no suffix)
|-
| &0d
| variable definition (no suffix)
|-
| &0e
| number constant "0"
|-
| &0f
| number constant "1"
|-
| &10
| number constant "2"
|-
| &11
| number constant "3"
|-
| &12
| number constant "4"
|-
| &13
| number constant "5"
|-
| &14
| number constant "6"
|-
| &15
| number constant "7"
|-
| &16
| number constant "8"
|-
| &17
| number constant "9"
|-
| &18
| number constant "10"
|-
| &19
| 8-bit integer decimal value
|-
| &1a
| 16-bit integer decimal value
|-
| &1b
| 16-bit integer binary value (with "&X" prefix)
|-
| &1c
| 16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
| &1d
| 16-bit BASIC program line memory address pointer (see notes)
|-
| &1e
| 16-bit integer BASIC line number
|-
| &1f
| floating point value
|-
| &20
| " " (space) symbol
|-
| &21
| ASCII "!" symbol
|-
| &22
| quoted string value
|-
| &23-7b
| ASCII printable symbols
|-
| &7c
| "|" symbol; prefix for RSX commands
|-
| &80
| AFTER
|-
| &81
| AUTO
|-
| &82
| BORDER
|-
| &83
| CALL
|-
| &84
| CAT
|-
| &85
| CHAIN
|-
| &86
| CLEAR
|-
| &87
| CLG
|-
| &88
| CLOSEIN
|-
| &89
| CLOSEOUT
|-
| &8a
| CLS
|-
| &8b
| CONT
|-
| &8c
| DATA
|-
| &8d
| DEF
|-
| &8e
| DEFINT
|-
| &8f
| DEFREAL
|-
| &90
| DEFSTR
|-
| &91
| DEG
|-
| &92
| DELETE
|-
| &93
| DIM
|-
| &94
| DRAW
|-
| &95
| DRAWR
|-
| &96
| EDIT
|-
| &97
| ELSE
|-
| &98
| END
|-
| &99
| ENT
|-
| &9a
| ENV
|-
| &9b
| ERASE
|-
| &9c
| ERROR
|-
| &9d
| EVERY
|-
| &9e
| FOR
|-
| &9f
| GOSUB, GO SUB
|-
| &a0
| GOTO, GO TO
|-
| &a1
| IF
|-
| &a2
| INK
|-
| &a3
| INPUT
|-
| &a4
| KEY
|-
| &a5
| LET
|-
| &a6
| LINE
|-
| &a7
| LIST
|-
| &a8
| LOAD
|-
| &a9
| LOCATE
|-
| &aa
| MEMORY
|-
| &ab
| MERGE
|-
| &ac
| MID$
|-
| &ad
| MODE
|-
| &ae
| MOVE
|-
| &af
| MOVER
|-
| &b0
| NEXT
|-
| &b1
| NEW
|-
| &b2
| ON
|-
| &b3
| ON BREAK
|-
| &b4
| ON ERROR GOTO, ON ERROR GO TO
|-
| &b5
| ON SQ
|-
| &b6
| OPENIN
|-
| &b7
| OPENOUT
|-
| &b8
| ORIGIN
|-
| &b9
| OUT
|-
| &ba
| PAPER
|-
| &bb
| PEN
|-
| &bc
| PLOT
|-
| &bd
| PLOTR
|-
| &be
| POKE
|-
| &bf
| PRINT
|-
| &c0
| "'" symbol (same function as REM keyword)
|-
| &c1
| RAD
|-
| &c2
| RANDOMIZE
|-
| &c3
| READ
|-
| &c4
| RELEASE
|-
| &c5
| REM
|-
| &c6
| RENUM
|-
| &c7
| RESTORE
|-
| &c8
| RESUME
|-
| &c9
| RETURN
|-
| &ca
| RUN
|-
| &cb
| SAVE
|-
| &cc
| SOUND
|-
| &cd
| SPEED
|-
| &ce
| STOP
|-
| &cf
| SYMBOL
|-
| &d0
| TAG
|-
| &d1
| TAGOFF
|-
| &d2
| TROFF
|-
| &d3
| TRON
|-
| &d4
| WAIT
|-
| &d5
| WEND
|-
| &d6
| WHILE
|-
| &d7
| WIDTH
|-
| &d8
| WINDOW
|-
| &d9
| WRITE
|-
| &da
| ZONE
|-
| &db
| DI
|-
| &dc
| EI
|-
| &dd
| FILL (v1.1)
|-
| &de
| GRAPHICS (v1.1)
|-
| &df
| MASK (v1.1)
|-
| &e0
| FRAME (v1.1)
|-
| &e1
| CURSOR (v1.1)
|-
| &e2
| (note 2)
|-
| &e3
| ERL
|-
| &e4
| FN
|-
| &e5
| SPC
|-
| &e6
| STEP
|-
| &e7
| SWAP
|-
| &e8
| (note 2)
|-
| &e9
| (note 2)
|-
| &ea
| TAB
|-
| &eb
| THEN
|-
| &ec
| TO
|-
| &ed
| USING
|-
| &ee
| > (greater than)
|-
| &ef
| = (equal)
|-
| &f0
| &gt=, > =, => (greater or equal)
|-
| &f1
| < (less than)
|-
| &f2
| <&gt, < > (not equal)
|-
| &f3
| =<, <=, < = (less than or equal)
|-
| &f4
| + (addition)
|-
| &f5
| - (subtraction or unary minus)
|-
| &f6
| * (multiplication)
|-
| &f7
| / (division)
|-
| &f8
| ^ (x to the power of y)
|-
| &f9
| \ (integer division)
|-
| &fa
| AND
|-
| &fb
| MOD
|-
| &fc
| OR
|-
| &fd
| XOR
|-
| &fe
| NOT
|-
| &ff
| (prefix for additional keywords)
|}

 Notes:

*The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
*&e2,&e8 and &e9 are not used
*&7c ("|") is a character prefix used to identify an RSX command. e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| "|" character prefix
|-
| 1
| 1
| 8-bit byte offset to tokens following RSX name.
|-
| 2
| x
| RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
|}

*This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &1a,&2d,&00 represents the integer number "&002d"="45".
*This token (&0B) is changed at run-time to &0D
*This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
*This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
*This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| &1f (note 1)
|-
| 1
| 5
| Floating point number (note 2)
|}

*#This byte is the BASIC token identifying a floating point number
*#These 5 bytes define the floating point number.
*The space symbol is used as a command seperator
*Variable definitions:
**The variable definition has the following structure:

{| border="1"
|-
! Offset
! Count
! Description
|-
| 0
| 1
| Token defining variable type
|-
| 2
| 2
| 16-bit Byte offset to variable value within tokenised BASIC program.
|-
| 4
| x
| Variable name
|}

 The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.

**The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
**The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
*String values:
**Each string value is prefixed with &22 token.
**All strings must be enclosed by double quote symbols (&quot). This symbols define the start and end of the string value.
**The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.

*After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

 This table list the BASIC tokens with a &ff prefix byte.

 

{| border="1"
|-
! Code (hexidecimal)
! BASIC keyword
|-
| &00
| ABS
|-
| &01
| ASC
|-
| &02
| ATN
|-
| &03
| CHR$
|-
| &04
| CINT
|-
| &05
| COS
|-
| &06
| CREAL
|-
| &07
| EXP
|-
| &08
| FIX
|-
| &09
| FRE
|-
| &0a
| INKEY
|-
| &0b
| INP
|-
| &0c
| INT
|-
| &0d
| JOY
|-
| &0e
| LEN
|-
| &0f
| LOG
|-
| &10
| LOG10
|-
| &11
| LOWER$
|-
| &12
| PEEK
|-
| &13
| REMAIN
|-
| &14
| SGN
|-
| &15
| SIN
|-
| &16
| SPACE$
|-
| &17
| SQ
|-
| &18
| SQR
|-
| &19
| STR$
|-
| &1a
| TAN
|-
| &1b
| UNT
|-
| &1c
| UPPER$
|-
| &1d
| VAL
|-
|  
| (note 2)
|-
| &40
| EOF
|-
| &41
| ERR
|-
| &42
| HIMEM
|-
| &43
| INKEY$
|-
| &44
| PI
|-
| &45
| RND
|-
| &46
| TIME
|-
| &47
| XPOS
|-
| &48
| YPOS
|-
| &49
| DERR (v1.1)
|-
|  
| (note 3)
|-
| &71
| BIN$
|-
| &72
| DEC$ (v1.1)
|-
| &73
| HEX$
|-
| &74
| INSTR
|-
| &75
| LEFT$
|-
| &76
| MAX
|-
| &77
| MIN
|-
| &78
| POS
|-
| &79
| RIGHT$
|-
| &7a
| ROUND
|-
| &7b
| STRING$
|-
| &7c
| TEST
|-
| &7d
| TESTR
|-
| &7e
| COPYCHR$ (v1.1)
|-
| &7f
| VPOS
|-
|  
| (note 4)
|}

 NOTES:

*These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence: <pre>&FF,&00</pre>
*Codes &1e...&3f inclusive are not used
*Codes &4a...&6f inclusive are not used
*Codes &80...&ff inclusive are not used

*When a BASIC program is in memory, the BASIC ROM can replace "16-bit BASIC program line number" tokens with "16-bit BASIC program line memory address pointer".

When a program is loaded or saved, there will only be "16-bit BASIC program line number" tokens followed by a 16-bit number of the line.

When a program is running, BASIC will replace the "16-bit BASIC program line number" with the "16-bit BASIC program line memory address pointer" token, and replace the 16-bit line number with the memory address of the start of that line.

It does this to avoid having to lookup the address of the line each time.

* When a REM or ' is seen, the characters following it are output directly (i.e. the bytes are not tokenized) until the end of line or a ':' is seen.

* When a BASIC program is listed each line is converted to a string (this includes the line number and the tokens converted to their strings). There is a maximum length for this string of 256 characters. This means that if the BASIC line is LISTed or EDITed, then the line will be displayed incorrectly with missing characters on the end. This is also noticed if you have a "10-liner" program that packs as much BASIC as possible into each line and renumber it so the line number has more digits.

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

 In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form: 1 x 2<exponent> The representation uses 5 bytes and is stored using the following structure:

 

{| border="1"
|-
! Byte
! colspan="8" | 0
! colspan="8" | 1
! colspan="8" | 2
! colspan="8" | 3
! colspan="8" | 4
|-
! Bit
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
! 7
! 6
! 5
! 4
! 3
! 2
! 1
! 0
|-
| Function
| colspan="8" | (LSB) mantissa (bits 31-24)
| colspan="8" | mantissa (bits 23-16)
| colspan="8" | mantissa (bits 15-8)
| colspan="1" | sign
| colspan="7" | (MSB) mantissa (bits 7-0)
| colspan="8" | exponent
|}

=== Sign ===

The sign is represented by bit 7 of byte 3. The value of the sign bit indicates the sign of the floating point number.

#*If the sign bit is "1", then the number is negative.
#*If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4. It is stored with a bias of 128.

#*128-255 are positive exponents,
#*1-127 are negative exponents.
#*0 means, the number is zero

To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 1 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^127.
A value of 0 just means, that the number is zero (0).

=== BASIC Display of Floating point numbers ===

* Numbers are displayed to 9 decimal places.
* If the number doesn't have a fractional part (e.g. .0) then the fractional part is not displayed.
* Trailing zeros (zero digits after the last digit in the fraction) are not displayed
* The value is rounded in the following way for display:

If the 10th fractional digit is 5 or above, then the number is rounded up.
If the 10th fractional digit is 4 or below, then the number is rounded down.
e.g.
0.1234567891 is displayed as 0.123456789
0.1234567895 is displayed as 0.12345679

=== floating point example in RAM by MaV ===

The initial figure = 43.375.
An example in BASIC:
<pre>
a!=43.375
READY
PRINT a!
43.375
PRINT @a!
374
FOR I=0 TO 4:PRINT HEX$(PEEK(374+I),2);:NEXT I
0000802D86
</pre>
the result for better readability: 
'''00 00 80 2D 86''' 
The first byte contains the least significant bits of the mantissa, and every following byte up to the fourth byte contain the bits following the first in significance and in exactly that order!

That means that you have to turn around the first four bytes if you want to read the mantissa correctly:
2D800000
or
0010.1101.1000.0000.0000.0000.0000.0000
in binary (the stops are inserted for better readability).

Now the highest significant bit here is 0, so the number is positive.
What's more, you need to clear that bit and substitute the implied highest bit (see description in the link), which is always 1 (regardless of the deleted sign bit!!!).
Thus you get:
AD800000
or
1010.1101.1000.0000.0000.0000.0000.0000
in binary.

The mantissa has an implied decimal point before the number. Since the number is 2^32 bits (i.e. 4 bytes) long you have to divide by 2^32 to get the proper decimal representation.

AD800000 (hex) = 2910846976 (dec)

2910846976 / 2^32 = 0.677734375

The mantissa in a decimal representation is: 0.677734375

Now, the last byte contains the exponent: 86 (hex) or 134 (dec). You need to subtract 128 to get the real exponent, the highest bit tells you that the exponent is positive (1) or negative (0). Your exponent is 6.

0.677734375 * 2^6 = 43.375

'''Another example:''' 
PI is represented in memory as: 
'''A2 DA 0F 49 82''' 
The mantissa is 
490FDAA2 (highest significant bit is zero => number is positive)
The exponent is 
82 (=positive mantissa, value=2 thus multiply mantissa with 2^2) 

Delete the sign bit (which is 0 anyway), and then add the implied 1 bit: 
C90FDAA2 (hex) = 3373259426 (dec) = 1100.1001.0000.1111.1101.1010.1010.0010 (bin) 

Calculate the decimal representation of the mantissa: 
3373259426 / 2^32 = 0,7853981633670628070831298828125 

Then add the exponent (82h - 80h = 2 thus 2^2) 
0,7853981633670628070831298828125 * 2^2 = 3,14159265346825122833251953125 

Voilà! The internal representation of the number PI on the CPC is: 3,14159265346825122833251953125 

If you compare to a (more) correct representation of PI, you'll see that the CPC is correct up to the 9th decimal place: 

CPC: 
3.14159265346825122833251953125 
more correctly: 
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986...

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts. The biggest figure which can be stored correctly in RAM by a variable is 2^32-1 = 4294967295.

#*A integer variable is defined with a "!" character postfix.

e.g.
<pre>a! = 3.141592654
</pre>
#*A real number uses 5 bytes of memory as storage. The format is described above.
#*The address of a real variable can be found in BASIC by: <pre>PRINT @a!
</pre>

Where "a" should be replaced with the name of the variable.

 

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

 NOTES:

#*A integer variable is defined with a "%" character postfix.

e.g.
<pre>a% = 3
</pre>
#*A integer variable has a range of -32768 to 32767
#*A integer variable always uses two bytes of memory as storage with the following format:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 2
| Integer number
|}

#*The address of the integer variable can be found in BASIC by: <pre>PRINT @a%
</pre>

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

 NOTES:

#**A string variable is defined in BASIC with a "$" character postfix.

e.g.
<pre>a$ = "hello"
</pre>
#**A string variable is described internally by a "string descriptor block" which has the following structure:

{| border="1"
|-
! Offset
! Length
! Description
|-
| 0
| 1
| Length of string in bytes/characters
|-
| 1
| 2
| Location of start of string
|}

#**The address of the "string descriptor block" for the string variable can be found in BASIC by typing: <pre>PRINT @a$
</pre>

replacing "a$" with the name of the string variable.

#**A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
#**A string variable can contain any ASCII character code in the range 0-255.
#**A string variable can store a minimum of 0 characters and a maximum of 255 characters.
#**The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

[[Category:Programming]]
[[Category:BASIC| ]]
[[Category:CPC Internal Components]]
[[Category:Operating System| ]]
[[Category:Software]]
[[Category:Programming software| ]]

Vortex Disc Drives

2025-08-23T08:45:03Z

Arnoldemu: /* Clone of the F1-D controller */

A series of external 3,5" and 5,25" floppy disc drives from [[Vortex_Computersysteme|Vortex]] providing up to 720K capacity (704K available). The Vortex drives were most popular in Germany. For more information regarding [[VDOS]] and the Vortex Disk Format, see the dedicated [[VDOS]] Wiki page.

== S- and D-Drives (720K) ==

These are the first generation of 720K floppy disc drives from Vortex. They came in variants having either a single drive ("S" variant) or two drives ("D" variant). The "S" variant (as well as the less expensive "Z" variant) was delivered with the same double-height casing as the "D" variant, so that a second drive could be retrofitted.

The F1-S, F1-D, M1-S, M1-D drives have their own FDC765 in the controller, and this one supports all DS0 up to DS3. The Vortex interface can manage 4 floppy drives in total.

=== F1-S and F1-D (5,25") ===

The F1-S and F1-D models are based on BASF 6138 (81690-001) type 5,25" disk drives, i.e. double-sided, 80 tracks per side, 96 tpi density.

<gallery>
Image:IMG 3163.JPG|F1-D
Image:Vortex f1d front.jpg|F1-D front view
Image:Vortex f1d back.jpg|F1-D backside
</gallery>
<gallery>
Image:Vortex fd-1 interface 664.jpg|F1-D interface (CPC 664)
Image:Fd1 interface 664 platine front.jpg|F1-D interface board (CPC 664)
Image:Fd1 interface 664 platine back.jpg|F1-D interface board (CPC 664)
Image:F1DCONT.jpg|F1-D interface board (CPC 6128)
</gallery>
<gallery>
Image:Vortex f1 manual.jpg|F1-S/D manual
Image:Vortex F1 SystemDisk 464.jpg|F1-S/D system disk (CPC 464)
Image:Vortex f1 manual disk.jpg|F1-S/D system disk (CPC 664/6128)
</gallery>

The floppy controller of the F1-D / F1-S was cloned by Hans Hübner of FutureSoft with MX4 connector and without ROM slot. It supports four drives. Under FutureOS they are named E-H.

=== A1-S Upgrade Kit (5,25") ===

Vortex offered an upgrade kit consisting of a single bare drive and an installation manual, allowing to upgrade a F1-S (single) drive to a F1-D (dual) drive. To do this, one simply had to install the additional drive in the free slot of the drive case.

<gallery>
Image:Basf 6138 spare drive.jpg|BASF 6138 spare drive
</gallery>

=== M1-S and M1-D (3,5") ===

The M1-S and M1-D models are based on 3,5" disk drives. Controller and DOS were identical for 5,25" and 3,5" devices.

=== FDA-1 3" Drive Adapter ===

This adapter allows to connect an external FD-1 3" drive on Vortex F1/M1 setups on the CPC 464. Since only two drives can be used at the same time, the external 3" drive first had to be selected manually with the RSX command '''|S'''. This RSX command worked also with VDOS 2.11 on CPC6128.

{| class="wikitable"
|-
! RSX !! Description
|-
| |S,1 || Use 3" drive as drive A, upper Vortex drive is disabled
|-
| |S,2 || Use 3" drive as drive B, lower Vortex drive is disabled
|-
| |S,0 || Disable the 3" drive (default)
|}

<gallery>
Image:Vortex 3rd drive adapter.jpg|FDA-1 Adapter
Image:Vortex 3rd drive adapter insides.jpg|Inside the adapter box
Image:Vortex 3rd drive adapter insides closeup.jpg|Inside the adapter box (closeup)
Image:Vortex 3rd drive adapter plug cable.jpg|Plug (cable side)
Image:Vortex 3rd drive adapter plug floppy.jpg|FD-1 3" floppy drive plug
</gallery>

=== Clone of the F1-D controller ===
A clone of the F1-D controller was created by [[Hans Hübner]] of [[FutureSoft]] in 2024. The card fits on the Mother X4 board and doesn't contain an extra ROM slot. Using [[FutureOS]] this card allows to add four additional floppy disc drives to the CPC, being called E, F, G and H.

[[https://github.com/hanshuebner]] Github of Hans Hübner

=== FDC I/O Ports ===

All types of floppy disk controllers for the F1-S/D and M1-S/D series are based on the NEC 765 chip.

On the F1-D Reproduction board the ports FA7E, FB7E/FB7F and FBF6/FBF7 are fully decoded. FB7E/FBF6 is chosen with a link/switch on the PCB.

On the F1-D original device the I/O ports are partially decoded (use of the full I/O address given below avoids conflict with other devices):

'''CPC 464:'''

{| class="wikitable"
|-
! Address !! Description
|-
| 0xFB7E || uPD control
|-
| 0xFB7F || uPD data
|-
| 0xFA7E || motor on/off
|}

Legend:
x = not decoded. don't care, 0 or 1 can be used.
0 = must be 0
1 = must be 1

FDC:

I/O address A15-A0:
xxxx x0x1 0xxx xxxr

A10=0, A8=1 and A7=0

r = connected to A0 on NEC765 and selects status register or data register.

Motor:

I/O address A15-A0:
xxxx x0x0 0xxx xxxr
A10=0, A8=0 and A7=0

x = not decoded. don't care, 0 or 1 can be used.

only bit 0 of the data written to the port controls motor state.

'''CPC 664/6128:'''

{| class="wikitable"
|-
! Address !! Description
|-
| 0xFBF6 || uPD control
|-
| 0xFBF7 || uPD data
|-
| 0xFA7E || motor on/off
|}

On the board above marked 664 there is a patch wire which disconnects A7 and connects A3. This changes the decoding from FB7E/FB7F to FBF6/FBF7 for FDC.

FDC:

I/O address A15-A0:
xxxx x0x1 xxxx 0xxr

A10=0, A8=1 and A3=0

r = connected to A0 on NEC765 and selects status register or data register.

Motor:

I/O address A15-A0:
xxxx x0x0 0xxx xxxr

A10=0, A8=0 and A7=0

only bit 0 of the data written to the port controls motor state.

The I/O port decoding for the 6128 specific board is currently unknown.

=== Downloads ===

* [[Media:Vortex Floppy Disk Station F1 für den Schneider CPC 464 - Benutzerhandbuch.pdf|Benutzerhandbuch für die Vortex Floppy Disk Station F1 für den Schneider CPC 464]] {{DE}} (Vortex F1 user manual)
* [[Media:Vortex_Vdos_2.0_Manual.pdf|Benutzerhandbuch für das Diskettenbetriebssystem VDOS 2.0]] {{DE}} (VDOS 2.0 user manual)
* [[Media:3-Zoll-Adapter zur VORTEX-Diskettenstation.pdf|Benutzerhandbuch für den FDA-1 3"-Adapter]] {{DE}} (3" adapter user manual)
* [[Media:VTXF1464.DSK|Vortex F1-S/D Systemdiskette für CPC 464]] (system disk, 720k image, bootable)
* [[Media:VORTF1.DSK|Vortex F1-S/D Systemdiskette für CPC 664/6128]] (system disk, 720k image)
* [[Media:Vortex10.zip|VDOS 1.0 ROM]] {{DE}}
* [[Media:Vortex20.zip|VDOS 2.0 ROM]] {{DE}}
* [[Media:80307-058 BASF 6138 Mini Disk Apr83.zip|BASF 6138 Datasheet (F1-S/D/Z Floppy Disk Drive)]]

 

== Z-Drives (180K/side) ==

These are less expensive drives and were meant to be directly connected as B drive to a CPC 464 with DDI-1 or a CPC 664/6128. Since these drives ship neither with an own controller nor a [[VDOS]] ROM, they do rely fully on AMSDOS and thus only 40 tracks on one side can be accessed, resulting in the same capacity (180K/side) as the 3" drives.

=== F1-Z (5,25") ===

The F1-Z model is based on a later revision of the BASF 6138 type disk drive (81757-001), which offers more configuration options using jumpers. The drive was shipped in a "double step" configuration to use only 40 tracks, and thus the cheaper and more widely available DS DD floppy disks (48 tpi, 180K/side) could be used.

<gallery>
Image:Basf 6138 81757 001.jpg|BASF AG 6138 (81757-001) drive
Image:Basf 6138 81757 001 jumpers.jpg|BASF AG 6138 (81757-001) 40 track jumper configuration
</gallery>

=== A1-Z Upgrade Kit (5,25") ===

Vortex offered an upgrade kit consisting of a controller, a manual, a CP/M license and an utility disk which allows a F1-Z drive to be upgraded to a F1-S drive.

=== M1-Z (3,5") ===

The M1-Z model is equipped with a single 3,5" disk drive.

 

== X-Drives (720K) ==

These are the latest drives from Vortex for use with a CPC 464 with DDI-1 or a CPC 664/6128 (ie. on systems that already have a floppy disc controller); no additional controller was required anymore. Instead, a ROM module was supplied together with the drive, which provided VDOS 2.0-X. Only single-drive variants were available. The |S command (for accessing a third drive) is no longer used, the new |X command allows to swap drive A and B (same as [[X-DDOS]] from Dobbertin).

=== F1-X and F1-XRS (5,25") ===

The F1-X model is based on either a single BASF 6138 (81690-001 or 81757-001) or a single BASF 6139 5,25" disk drive. The BASF 6139 is a revisioned version which is slightly more compact (~1cm shorter), and also a number of electronical and mechanical design flaws that affected durability were corrected. The F1-XRS variant is equipped with an additional RS232-C interface.

<gallery>
File:F1-x front.jpg|F1-X
File:Vortex f1-x cpc464 backside.jpg|F1-X backside, showing IDC connector (CPC 464)
File:Vortex f1-x cpc664 backside edge.jpg|F1-X backside, showing edge connector (CPC 664)
File:F1-x inside.jpg|F1-X inside view, showing a BASF 6139 drive
File:F1x m1x manual.jpg|F1-X/M1-X manual and system utilities disk
</gallery>

=== M1-X and M1-XRS (3,5") ===

The M1-X model is based on a single NEC FD1035 type 3,5" disk drive. The M1-XRS variant is equipped with an additional RS232-C interface.

<gallery>
File:vortex-m1-x-front.png|M1-X
File:vortex-m1-x-back.png|M1-X backside
File:vortex-m1-x-connector.png|M1-X backside, showing IDC connector (CPC 464)
File:vortex-m1-x-under.png|M1-X underside
File:vortex-m1-x-inside.png|M1-X inside view, showing the drive and power
File:vortex-m1-x-drive-close.png|M1-X inside view, close-up of the drive from above
File:vortex-m1-x-drive-details.png|M1-X inside view, close-up from the backside
</gallery>

=== X(RS)-Modul ===

The X-drives for the CPC 664/6128 are connected directly to the floppy port. In order to provide [[VDOS]], the "X-Modul" (sometimes also called "VDOS module") must be connected additionally to the expansion port. This contains a ROM board that provides a VDOS 2.0-X ROM. The ROM board supplied for the CPC 464 came together with a chunky housing in which both the "X-Modul" and the DDI-1 controller were installed. All variants were also available with an additional RS232-C interface (in this case called either "XRS-Modul" or "X-Modul/RS").

<gallery>
Image:Vortex fd1 464 controller 1.jpg|XRS-Modul (CPC 464)
Image:Vortex fd1 464 controller 2.jpg|XRS-Modul with built-in DDI-1 visible (CPC 464)
Image:Xrs 464.jpg|XRS-Modul board beneath the DDI-1 (CPC 464)
Image:Vortex xrs 464 board backside.jpg|XRS-Modul board backside (CPC 464)
</gallery>
<gallery>
Image:Vortex X-Modul 6128.jpg|X-Modul (CPC 6128)
Image:Vortex X-Modul 6128 Board Front.jpg|X-Modul board (CPC 6128)
Image:Vortex X-Modul 6128 Board Backside.jpg|X-Modul board backside (CPC 6128)
</gallery>

=== RS232 I/O Ports ===

The RS232-C interface of the "XRS-Modul" was advertised to be compatible with Amstrad/Pace interfaces, but offers only one channel (so no channel B).

{| class="wikitable"
|-
! Address !! Description
|-
| 0xFADC || SIO data (R/W)
|-
| 0xFADD || SIO control (R/W)
|-
| 0xFBDC || 8253 counter 0 (R/W)
|-
| 0xFBDD || 8253 counter 1 (R/W)
|-
| 0xFBDE || 8253 counter 2 (R/W)
|-
| 0xFBDF || Mode word (W)
|}

=== Downloads ===

* [https://www.cpcwiki.eu/manuals/Vortex%20X-Laufwerke%20Manual.de.rar Benutzerhandbuch für die Vortex X-Laufwerke] {{DE}} (manual)
* [[Media:Vortex RS232-C Manual.pdf|Benutzerhandbuch für die Vortex RS232-C Schnittstelle]] {{DE}} (RS232-C user manual)
* [[Media:Manual de las Unidades Vortex.pdf|Manual de las Unidades Vortex]] {{ES}} (manual)
* [[Media:VORTF1X.DSK|Systemdiskette für Vortex X-Laufwerke]] (system disk, 720k disk image, original)
* [[Media:VTXF1XB.DSK|Systemdiskette für Vortex X-Laufwerke]] (system disk, 720k disk image, modified to boot CP/M 2.2)
* [[Media:VDOS20X.ROM|VDOS 2.0-X ROM]] {{DE}} (German VDOS 2.0-X ROM for CPC 664/6128)
* [[Media:NEC_FD1035_Floppy.pdf|NEC FD1035 Datasheet (M1-X Floppy Disk Drive)]]

 

== Software Accessories ==

=== DOSCOPY ===

DOSCOPY is a CP/M 2.2 utility which allows to read and write files from IBM and Atari ST formatted 5,25" disks. It was written in 1987 by Peter Höpfner.

<gallery>
Image:Vortex_DOSCOPY_Manual.JPG|DOSCOPY physical manual
Image:Vortex_DOSCOPY_Disk.JPG|DOSCOPY 5,25" disk
Image:Vortex_DOSCOPY_Screenshot.JPG|DOSCOPY screenshot
</gallery>

==== Downloads ====

* [[Media:DOSCOPY.DSK|DOSCOPY 1.1]] {{DE}} (Vortex 360k disk image)
* [[Media:Vortex_DOSCOPY_Benutzerhandbuch.pdf|DOSCOPY 1.1 Benutzerhandbuch]] {{DE}} (manual)

=== PARA 3.0 ===

PARA 3.0 is a CP/M 2.2 utility allowing to exchange files between the CPC and other CP/M based systems. It claims to support "reading, writing and formatting of 99% of all CP/M formats" and provides a comprehensive disk format analzer. It was written in 1987 by Peter Höpfner.

<gallery>
Image:Vortex_PARA_3.0_Manual.JPG|PARA 3.0 physical manual
Image:Vortex PARA 3.0 Disk.JPG|PARA 3.0 5,25" disk
Image:Vortex PARA 3.0 Screenshot 1.JPG|PARA 3.0 loading screen
</gallery>

==== Downloads ====

* [[Media:PARA30.DSK|PARA 3.0]] {{DE}} (Vortex 720k disk image)
* [[Media:Vortex_PARA_3.0_Benutzerhandbuch.zip|PARA 3.0 Benutzerhandbuch]] {{DE}} (manual)

=== PARA 3.0 PLUS ===

PARA 3.0 PLUS (or PARA PLUS) is an enhanced distribution of PARA 3.0 which also integrates DOSCOPY 1.3 into a single software suite.

<gallery>
Image:Para 30 plus intro.jpg|PARA 3.0+ loading screen
Image:Para 30 plus mainmenu.jpg|PARA 3.0+ main menu
Image:Para 30 plus analyzer.jpg|PARA 3.0+ format analyzer
</gallery>

==== Downloads ====

* [[Media:PARAPLUS.DSK|PARA 3.0+]] {{DE}} (Vortex 720k disk image, bootable)

=== SPARA ===

SPARA was either the predecessor or a cut-down version of PARA 3.0 and was supplied with the F1-Z drives, only supporting 40 track formats.

=== FileCopy ===
FileCopy 3.0 is a comprehensive tool to copy files with up to 16 different devices (using letters A to P), it supports the Vortex 704 KB format for 80 Track drives.

 

== 3rd Party Software ==

=== dBASE II ===

Markt & Technik released a version of Ashton-Tate dBASE II 2.41 for owners of a Vortex disk drive.

=== FutureOS ===

[[FutureOS]] has support for Vortex drives, it uses the Vortex 704 KB format for 80 Track drives.

=== House of Usher ===

Besides tape and 3 inch floppy disk release, the game [[House of Usher]] has been officially released on 5.25 inch floppy disk for the Schneider CPC with Vortex F1 floppy drive.

<gallery>
House of Usher ads.jpeg
House-of-usher-floppy-cover.png
House-of-usher-floppy-no-cover.png
</gallery>

=== Multiplan ===

Markt & Technik released a version of Microsoft Multiplan 1.06 for owners of a Vortex disk drive.

==== Downloads ====

* [[Media:MPLAN106.DSK|Microsoft Multiplan 1.06]] {{DE}} (Vortex 720k disk image, bootable CP/M Plus)

=== ParaDOS ===

[[ParaDOS]] supports Vortex X-drives and can be used as a replacement for the VDOS-X ROM. There is also a patched version called VaraDOS, which is configured to use a Vortex X-drive as drive B per default. ParaDOS does not provide a way too boot CP/M from drive B.

=== WordStar 3.0 ===

A version of MicroPro WordStar 3.0 was released by Markt & Technik for owners of a Vortex disk drive.
 

== Media Coverage ==

<gallery>
Image:Vortex Schneider CPC International 1985-09.JPG|Schneider CPC International 1985/09
Image:Vortex schneider cpc international 1986-02.JPG|Schneider CPC International 1986/02
Image:Vortex schneider cpc international 1986-04.JPG|Schneider CPC International 1986/04
Image:Vortex schneider cpc international 1986-07.JPG|Schneider CPC International 1986/07
Image:Vortex schneider cpc international 1986-08.JPG|Schneider CPC International 1986/08
</gallery>

[[Category:Peripherals]] [[Category:Manual]][[Category:DATA Storage]][[Category:Vortex Computersysteme]]

Vortex Disc Drives

2025-08-23T08:43:28Z

Arnoldemu: /* FDC I/O Ports */

A series of external 3,5" and 5,25" floppy disc drives from [[Vortex_Computersysteme|Vortex]] providing up to 720K capacity (704K available). The Vortex drives were most popular in Germany. For more information regarding [[VDOS]] and the Vortex Disk Format, see the dedicated [[VDOS]] Wiki page.

== S- and D-Drives (720K) ==

These are the first generation of 720K floppy disc drives from Vortex. They came in variants having either a single drive ("S" variant) or two drives ("D" variant). The "S" variant (as well as the less expensive "Z" variant) was delivered with the same double-height casing as the "D" variant, so that a second drive could be retrofitted.

The F1-S, F1-D, M1-S, M1-D drives have their own FDC765 in the controller, and this one supports all DS0 up to DS3. The Vortex interface can manage 4 floppy drives in total.

=== F1-S and F1-D (5,25") ===

The F1-S and F1-D models are based on BASF 6138 (81690-001) type 5,25" disk drives, i.e. double-sided, 80 tracks per side, 96 tpi density.

<gallery>
Image:IMG 3163.JPG|F1-D
Image:Vortex f1d front.jpg|F1-D front view
Image:Vortex f1d back.jpg|F1-D backside
</gallery>
<gallery>
Image:Vortex fd-1 interface 664.jpg|F1-D interface (CPC 664)
Image:Fd1 interface 664 platine front.jpg|F1-D interface board (CPC 664)
Image:Fd1 interface 664 platine back.jpg|F1-D interface board (CPC 664)
Image:F1DCONT.jpg|F1-D interface board (CPC 6128)
</gallery>
<gallery>
Image:Vortex f1 manual.jpg|F1-S/D manual
Image:Vortex F1 SystemDisk 464.jpg|F1-S/D system disk (CPC 464)
Image:Vortex f1 manual disk.jpg|F1-S/D system disk (CPC 664/6128)
</gallery>

The floppy controller of the F1-D / F1-S was cloned by Hans Hübner of FutureSoft with MX4 connector and without ROM slot. It supports four drives. Under FutureOS they are named E-H.

=== A1-S Upgrade Kit (5,25") ===

Vortex offered an upgrade kit consisting of a single bare drive and an installation manual, allowing to upgrade a F1-S (single) drive to a F1-D (dual) drive. To do this, one simply had to install the additional drive in the free slot of the drive case.

<gallery>
Image:Basf 6138 spare drive.jpg|BASF 6138 spare drive
</gallery>

=== M1-S and M1-D (3,5") ===

The M1-S and M1-D models are based on 3,5" disk drives. Controller and DOS were identical for 5,25" and 3,5" devices.

=== FDA-1 3" Drive Adapter ===

This adapter allows to connect an external FD-1 3" drive on Vortex F1/M1 setups on the CPC 464. Since only two drives can be used at the same time, the external 3" drive first had to be selected manually with the RSX command '''|S'''. This RSX command worked also with VDOS 2.11 on CPC6128.

{| class="wikitable"
|-
! RSX !! Description
|-
| |S,1 || Use 3" drive as drive A, upper Vortex drive is disabled
|-
| |S,2 || Use 3" drive as drive B, lower Vortex drive is disabled
|-
| |S,0 || Disable the 3" drive (default)
|}

<gallery>
Image:Vortex 3rd drive adapter.jpg|FDA-1 Adapter
Image:Vortex 3rd drive adapter insides.jpg|Inside the adapter box
Image:Vortex 3rd drive adapter insides closeup.jpg|Inside the adapter box (closeup)
Image:Vortex 3rd drive adapter plug cable.jpg|Plug (cable side)
Image:Vortex 3rd drive adapter plug floppy.jpg|FD-1 3" floppy drive plug
</gallery>

=== Clone of the F1-D controller ===
A clone of the F1-D controller was created by [[Hans Hübner]] of [[FutureSoft]] in 2024. The card fits on the Mother X4 board and doesn't contain an extra ROM slot. Using [[FutureOS]] this card allows to add four additional floppy disc drives to the CPC, being called E, F, G and H.

=== FDC I/O Ports ===

All types of floppy disk controllers for the F1-S/D and M1-S/D series are based on the NEC 765 chip.

On the F1-D Reproduction board the ports FA7E, FB7E/FB7F and FBF6/FBF7 are fully decoded. FB7E/FBF6 is chosen with a link/switch on the PCB.

On the F1-D original device the I/O ports are partially decoded (use of the full I/O address given below avoids conflict with other devices):

'''CPC 464:'''

{| class="wikitable"
|-
! Address !! Description
|-
| 0xFB7E || uPD control
|-
| 0xFB7F || uPD data
|-
| 0xFA7E || motor on/off
|}

Legend:
x = not decoded. don't care, 0 or 1 can be used.
0 = must be 0
1 = must be 1

FDC:

I/O address A15-A0:
xxxx x0x1 0xxx xxxr

A10=0, A8=1 and A7=0

r = connected to A0 on NEC765 and selects status register or data register.

Motor:

I/O address A15-A0:
xxxx x0x0 0xxx xxxr
A10=0, A8=0 and A7=0

x = not decoded. don't care, 0 or 1 can be used.

only bit 0 of the data written to the port controls motor state.

'''CPC 664/6128:'''

{| class="wikitable"
|-
! Address !! Description
|-
| 0xFBF6 || uPD control
|-
| 0xFBF7 || uPD data
|-
| 0xFA7E || motor on/off
|}

On the board above marked 664 there is a patch wire which disconnects A7 and connects A3. This changes the decoding from FB7E/FB7F to FBF6/FBF7 for FDC.

FDC:

I/O address A15-A0:
xxxx x0x1 xxxx 0xxr

A10=0, A8=1 and A3=0

r = connected to A0 on NEC765 and selects status register or data register.

Motor:

I/O address A15-A0:
xxxx x0x0 0xxx xxxr

A10=0, A8=0 and A7=0

only bit 0 of the data written to the port controls motor state.

The I/O port decoding for the 6128 specific board is currently unknown.

=== Downloads ===

* [[Media:Vortex Floppy Disk Station F1 für den Schneider CPC 464 - Benutzerhandbuch.pdf|Benutzerhandbuch für die Vortex Floppy Disk Station F1 für den Schneider CPC 464]] {{DE}} (Vortex F1 user manual)
* [[Media:Vortex_Vdos_2.0_Manual.pdf|Benutzerhandbuch für das Diskettenbetriebssystem VDOS 2.0]] {{DE}} (VDOS 2.0 user manual)
* [[Media:3-Zoll-Adapter zur VORTEX-Diskettenstation.pdf|Benutzerhandbuch für den FDA-1 3"-Adapter]] {{DE}} (3" adapter user manual)
* [[Media:VTXF1464.DSK|Vortex F1-S/D Systemdiskette für CPC 464]] (system disk, 720k image, bootable)
* [[Media:VORTF1.DSK|Vortex F1-S/D Systemdiskette für CPC 664/6128]] (system disk, 720k image)
* [[Media:Vortex10.zip|VDOS 1.0 ROM]] {{DE}}
* [[Media:Vortex20.zip|VDOS 2.0 ROM]] {{DE}}
* [[Media:80307-058 BASF 6138 Mini Disk Apr83.zip|BASF 6138 Datasheet (F1-S/D/Z Floppy Disk Drive)]]

 

== Z-Drives (180K/side) ==

These are less expensive drives and were meant to be directly connected as B drive to a CPC 464 with DDI-1 or a CPC 664/6128. Since these drives ship neither with an own controller nor a [[VDOS]] ROM, they do rely fully on AMSDOS and thus only 40 tracks on one side can be accessed, resulting in the same capacity (180K/side) as the 3" drives.

=== F1-Z (5,25") ===

The F1-Z model is based on a later revision of the BASF 6138 type disk drive (81757-001), which offers more configuration options using jumpers. The drive was shipped in a "double step" configuration to use only 40 tracks, and thus the cheaper and more widely available DS DD floppy disks (48 tpi, 180K/side) could be used.

<gallery>
Image:Basf 6138 81757 001.jpg|BASF AG 6138 (81757-001) drive
Image:Basf 6138 81757 001 jumpers.jpg|BASF AG 6138 (81757-001) 40 track jumper configuration
</gallery>

=== A1-Z Upgrade Kit (5,25") ===

Vortex offered an upgrade kit consisting of a controller, a manual, a CP/M license and an utility disk which allows a F1-Z drive to be upgraded to a F1-S drive.

=== M1-Z (3,5") ===

The M1-Z model is equipped with a single 3,5" disk drive.

 

== X-Drives (720K) ==

These are the latest drives from Vortex for use with a CPC 464 with DDI-1 or a CPC 664/6128 (ie. on systems that already have a floppy disc controller); no additional controller was required anymore. Instead, a ROM module was supplied together with the drive, which provided VDOS 2.0-X. Only single-drive variants were available. The |S command (for accessing a third drive) is no longer used, the new |X command allows to swap drive A and B (same as [[X-DDOS]] from Dobbertin).

=== F1-X and F1-XRS (5,25") ===

The F1-X model is based on either a single BASF 6138 (81690-001 or 81757-001) or a single BASF 6139 5,25" disk drive. The BASF 6139 is a revisioned version which is slightly more compact (~1cm shorter), and also a number of electronical and mechanical design flaws that affected durability were corrected. The F1-XRS variant is equipped with an additional RS232-C interface.

<gallery>
File:F1-x front.jpg|F1-X
File:Vortex f1-x cpc464 backside.jpg|F1-X backside, showing IDC connector (CPC 464)
File:Vortex f1-x cpc664 backside edge.jpg|F1-X backside, showing edge connector (CPC 664)
File:F1-x inside.jpg|F1-X inside view, showing a BASF 6139 drive
File:F1x m1x manual.jpg|F1-X/M1-X manual and system utilities disk
</gallery>

=== M1-X and M1-XRS (3,5") ===

The M1-X model is based on a single NEC FD1035 type 3,5" disk drive. The M1-XRS variant is equipped with an additional RS232-C interface.

<gallery>
File:vortex-m1-x-front.png|M1-X
File:vortex-m1-x-back.png|M1-X backside
File:vortex-m1-x-connector.png|M1-X backside, showing IDC connector (CPC 464)
File:vortex-m1-x-under.png|M1-X underside
File:vortex-m1-x-inside.png|M1-X inside view, showing the drive and power
File:vortex-m1-x-drive-close.png|M1-X inside view, close-up of the drive from above
File:vortex-m1-x-drive-details.png|M1-X inside view, close-up from the backside
</gallery>

=== X(RS)-Modul ===

The X-drives for the CPC 664/6128 are connected directly to the floppy port. In order to provide [[VDOS]], the "X-Modul" (sometimes also called "VDOS module") must be connected additionally to the expansion port. This contains a ROM board that provides a VDOS 2.0-X ROM. The ROM board supplied for the CPC 464 came together with a chunky housing in which both the "X-Modul" and the DDI-1 controller were installed. All variants were also available with an additional RS232-C interface (in this case called either "XRS-Modul" or "X-Modul/RS").

<gallery>
Image:Vortex fd1 464 controller 1.jpg|XRS-Modul (CPC 464)
Image:Vortex fd1 464 controller 2.jpg|XRS-Modul with built-in DDI-1 visible (CPC 464)
Image:Xrs 464.jpg|XRS-Modul board beneath the DDI-1 (CPC 464)
Image:Vortex xrs 464 board backside.jpg|XRS-Modul board backside (CPC 464)
</gallery>
<gallery>
Image:Vortex X-Modul 6128.jpg|X-Modul (CPC 6128)
Image:Vortex X-Modul 6128 Board Front.jpg|X-Modul board (CPC 6128)
Image:Vortex X-Modul 6128 Board Backside.jpg|X-Modul board backside (CPC 6128)
</gallery>

=== RS232 I/O Ports ===

The RS232-C interface of the "XRS-Modul" was advertised to be compatible with Amstrad/Pace interfaces, but offers only one channel (so no channel B).

{| class="wikitable"
|-
! Address !! Description
|-
| 0xFADC || SIO data (R/W)
|-
| 0xFADD || SIO control (R/W)
|-
| 0xFBDC || 8253 counter 0 (R/W)
|-
| 0xFBDD || 8253 counter 1 (R/W)
|-
| 0xFBDE || 8253 counter 2 (R/W)
|-
| 0xFBDF || Mode word (W)
|}

=== Downloads ===

* [https://www.cpcwiki.eu/manuals/Vortex%20X-Laufwerke%20Manual.de.rar Benutzerhandbuch für die Vortex X-Laufwerke] {{DE}} (manual)
* [[Media:Vortex RS232-C Manual.pdf|Benutzerhandbuch für die Vortex RS232-C Schnittstelle]] {{DE}} (RS232-C user manual)
* [[Media:Manual de las Unidades Vortex.pdf|Manual de las Unidades Vortex]] {{ES}} (manual)
* [[Media:VORTF1X.DSK|Systemdiskette für Vortex X-Laufwerke]] (system disk, 720k disk image, original)
* [[Media:VTXF1XB.DSK|Systemdiskette für Vortex X-Laufwerke]] (system disk, 720k disk image, modified to boot CP/M 2.2)
* [[Media:VDOS20X.ROM|VDOS 2.0-X ROM]] {{DE}} (German VDOS 2.0-X ROM for CPC 664/6128)
* [[Media:NEC_FD1035_Floppy.pdf|NEC FD1035 Datasheet (M1-X Floppy Disk Drive)]]

 

== Software Accessories ==

=== DOSCOPY ===

DOSCOPY is a CP/M 2.2 utility which allows to read and write files from IBM and Atari ST formatted 5,25" disks. It was written in 1987 by Peter Höpfner.

<gallery>
Image:Vortex_DOSCOPY_Manual.JPG|DOSCOPY physical manual
Image:Vortex_DOSCOPY_Disk.JPG|DOSCOPY 5,25" disk
Image:Vortex_DOSCOPY_Screenshot.JPG|DOSCOPY screenshot
</gallery>

==== Downloads ====

* [[Media:DOSCOPY.DSK|DOSCOPY 1.1]] {{DE}} (Vortex 360k disk image)
* [[Media:Vortex_DOSCOPY_Benutzerhandbuch.pdf|DOSCOPY 1.1 Benutzerhandbuch]] {{DE}} (manual)

=== PARA 3.0 ===

PARA 3.0 is a CP/M 2.2 utility allowing to exchange files between the CPC and other CP/M based systems. It claims to support "reading, writing and formatting of 99% of all CP/M formats" and provides a comprehensive disk format analzer. It was written in 1987 by Peter Höpfner.

<gallery>
Image:Vortex_PARA_3.0_Manual.JPG|PARA 3.0 physical manual
Image:Vortex PARA 3.0 Disk.JPG|PARA 3.0 5,25" disk
Image:Vortex PARA 3.0 Screenshot 1.JPG|PARA 3.0 loading screen
</gallery>

==== Downloads ====

* [[Media:PARA30.DSK|PARA 3.0]] {{DE}} (Vortex 720k disk image)
* [[Media:Vortex_PARA_3.0_Benutzerhandbuch.zip|PARA 3.0 Benutzerhandbuch]] {{DE}} (manual)

=== PARA 3.0 PLUS ===

PARA 3.0 PLUS (or PARA PLUS) is an enhanced distribution of PARA 3.0 which also integrates DOSCOPY 1.3 into a single software suite.

<gallery>
Image:Para 30 plus intro.jpg|PARA 3.0+ loading screen
Image:Para 30 plus mainmenu.jpg|PARA 3.0+ main menu
Image:Para 30 plus analyzer.jpg|PARA 3.0+ format analyzer
</gallery>

==== Downloads ====

* [[Media:PARAPLUS.DSK|PARA 3.0+]] {{DE}} (Vortex 720k disk image, bootable)

=== SPARA ===

SPARA was either the predecessor or a cut-down version of PARA 3.0 and was supplied with the F1-Z drives, only supporting 40 track formats.

=== FileCopy ===
FileCopy 3.0 is a comprehensive tool to copy files with up to 16 different devices (using letters A to P), it supports the Vortex 704 KB format for 80 Track drives.

 

== 3rd Party Software ==

=== dBASE II ===

Markt & Technik released a version of Ashton-Tate dBASE II 2.41 for owners of a Vortex disk drive.

=== FutureOS ===

[[FutureOS]] has support for Vortex drives, it uses the Vortex 704 KB format for 80 Track drives.

=== House of Usher ===

Besides tape and 3 inch floppy disk release, the game [[House of Usher]] has been officially released on 5.25 inch floppy disk for the Schneider CPC with Vortex F1 floppy drive.

<gallery>
House of Usher ads.jpeg
House-of-usher-floppy-cover.png
House-of-usher-floppy-no-cover.png
</gallery>

=== Multiplan ===

Markt & Technik released a version of Microsoft Multiplan 1.06 for owners of a Vortex disk drive.

==== Downloads ====

* [[Media:MPLAN106.DSK|Microsoft Multiplan 1.06]] {{DE}} (Vortex 720k disk image, bootable CP/M Plus)

=== ParaDOS ===

[[ParaDOS]] supports Vortex X-drives and can be used as a replacement for the VDOS-X ROM. There is also a patched version called VaraDOS, which is configured to use a Vortex X-drive as drive B per default. ParaDOS does not provide a way too boot CP/M from drive B.

=== WordStar 3.0 ===

A version of MicroPro WordStar 3.0 was released by Markt & Technik for owners of a Vortex disk drive.
 

== Media Coverage ==

<gallery>
Image:Vortex Schneider CPC International 1985-09.JPG|Schneider CPC International 1985/09
Image:Vortex schneider cpc international 1986-02.JPG|Schneider CPC International 1986/02
Image:Vortex schneider cpc international 1986-04.JPG|Schneider CPC International 1986/04
Image:Vortex schneider cpc international 1986-07.JPG|Schneider CPC International 1986/07
Image:Vortex schneider cpc international 1986-08.JPG|Schneider CPC International 1986/08
</gallery>

[[Category:Peripherals]] [[Category:Manual]][[Category:DATA Storage]][[Category:Vortex Computersysteme]]

Vortex Disc Drives

2025-08-23T08:42:52Z

Arnoldemu: /* FDC I/O Ports */

A series of external 3,5" and 5,25" floppy disc drives from [[Vortex_Computersysteme|Vortex]] providing up to 720K capacity (704K available). The Vortex drives were most popular in Germany. For more information regarding [[VDOS]] and the Vortex Disk Format, see the dedicated [[VDOS]] Wiki page.

== S- and D-Drives (720K) ==

These are the first generation of 720K floppy disc drives from Vortex. They came in variants having either a single drive ("S" variant) or two drives ("D" variant). The "S" variant (as well as the less expensive "Z" variant) was delivered with the same double-height casing as the "D" variant, so that a second drive could be retrofitted.

The F1-S, F1-D, M1-S, M1-D drives have their own FDC765 in the controller, and this one supports all DS0 up to DS3. The Vortex interface can manage 4 floppy drives in total.

=== F1-S and F1-D (5,25") ===

The F1-S and F1-D models are based on BASF 6138 (81690-001) type 5,25" disk drives, i.e. double-sided, 80 tracks per side, 96 tpi density.

<gallery>
Image:IMG 3163.JPG|F1-D
Image:Vortex f1d front.jpg|F1-D front view
Image:Vortex f1d back.jpg|F1-D backside
</gallery>
<gallery>
Image:Vortex fd-1 interface 664.jpg|F1-D interface (CPC 664)
Image:Fd1 interface 664 platine front.jpg|F1-D interface board (CPC 664)
Image:Fd1 interface 664 platine back.jpg|F1-D interface board (CPC 664)
Image:F1DCONT.jpg|F1-D interface board (CPC 6128)
</gallery>
<gallery>
Image:Vortex f1 manual.jpg|F1-S/D manual
Image:Vortex F1 SystemDisk 464.jpg|F1-S/D system disk (CPC 464)
Image:Vortex f1 manual disk.jpg|F1-S/D system disk (CPC 664/6128)
</gallery>

The floppy controller of the F1-D / F1-S was cloned by Hans Hübner of FutureSoft with MX4 connector and without ROM slot. It supports four drives. Under FutureOS they are named E-H.

=== A1-S Upgrade Kit (5,25") ===

Vortex offered an upgrade kit consisting of a single bare drive and an installation manual, allowing to upgrade a F1-S (single) drive to a F1-D (dual) drive. To do this, one simply had to install the additional drive in the free slot of the drive case.

<gallery>
Image:Basf 6138 spare drive.jpg|BASF 6138 spare drive
</gallery>

=== M1-S and M1-D (3,5") ===

The M1-S and M1-D models are based on 3,5" disk drives. Controller and DOS were identical for 5,25" and 3,5" devices.

=== FDA-1 3" Drive Adapter ===

This adapter allows to connect an external FD-1 3" drive on Vortex F1/M1 setups on the CPC 464. Since only two drives can be used at the same time, the external 3" drive first had to be selected manually with the RSX command '''|S'''. This RSX command worked also with VDOS 2.11 on CPC6128.

{| class="wikitable"
|-
! RSX !! Description
|-
| |S,1 || Use 3" drive as drive A, upper Vortex drive is disabled
|-
| |S,2 || Use 3" drive as drive B, lower Vortex drive is disabled
|-
| |S,0 || Disable the 3" drive (default)
|}

<gallery>
Image:Vortex 3rd drive adapter.jpg|FDA-1 Adapter
Image:Vortex 3rd drive adapter insides.jpg|Inside the adapter box
Image:Vortex 3rd drive adapter insides closeup.jpg|Inside the adapter box (closeup)
Image:Vortex 3rd drive adapter plug cable.jpg|Plug (cable side)
Image:Vortex 3rd drive adapter plug floppy.jpg|FD-1 3" floppy drive plug
</gallery>

=== Clone of the F1-D controller ===
A clone of the F1-D controller was created by [[Hans Hübner]] of [[FutureSoft]] in 2024. The card fits on the Mother X4 board and doesn't contain an extra ROM slot. Using [[FutureOS]] this card allows to add four additional floppy disc drives to the CPC, being called E, F, G and H.

=== FDC I/O Ports ===

All types of floppy disk controllers for the F1-S/D and M1-S/D series are based on the NEC 765 chip.

On the F1-D Reproduction board the ports FA7E, FB7E/FB7F and FBF6/FBF7 are fully decoded. FB7E/FBF6 is chosen with a link/switch on the PCB.

On the F1-D original device the I/O ports are partially decoded:

'''CPC 464:'''

{| class="wikitable"
|-
! Address !! Description
|-
| 0xFB7E || uPD control
|-
| 0xFB7F || uPD data
|-
| 0xFA7E || motor on/off
|}

Legend:
x = not decoded. don't care, 0 or 1 can be used.
0 = must be 0
1 = must be 1

FDC:

I/O address A15-A0:
xxxx x0x1 0xxx xxxr

A10=0, A8=1 and A7=0

r = connected to A0 on NEC765 and selects status register or data register.

Motor:

I/O address A15-A0:
xxxx x0x0 0xxx xxxr
A10=0, A8=0 and A7=0

x = not decoded. don't care, 0 or 1 can be used.

only bit 0 of the data written to the port controls motor state.

'''CPC 664/6128:'''

{| class="wikitable"
|-
! Address !! Description
|-
| 0xFBF6 || uPD control
|-
| 0xFBF7 || uPD data
|-
| 0xFA7E || motor on/off
|}

On the board above marked 664 there is a patch wire which disconnects A7 and connects A3. This changes the decoding from FB7E/FB7F to FBF6/FBF7 for FDC.

FDC:

I/O address A15-A0:
xxxx x0x1 xxxx 0xxr

A10=0, A8=1 and A3=0

r = connected to A0 on NEC765 and selects status register or data register.

Motor:

I/O address A15-A0:
xxxx x0x0 0xxx xxxr

A10=0, A8=0 and A7=0

only bit 0 of the data written to the port controls motor state.

The I/O port decoding for the 6128 specific board is currently unknown.

=== Downloads ===

* [[Media:Vortex Floppy Disk Station F1 für den Schneider CPC 464 - Benutzerhandbuch.pdf|Benutzerhandbuch für die Vortex Floppy Disk Station F1 für den Schneider CPC 464]] {{DE}} (Vortex F1 user manual)
* [[Media:Vortex_Vdos_2.0_Manual.pdf|Benutzerhandbuch für das Diskettenbetriebssystem VDOS 2.0]] {{DE}} (VDOS 2.0 user manual)
* [[Media:3-Zoll-Adapter zur VORTEX-Diskettenstation.pdf|Benutzerhandbuch für den FDA-1 3"-Adapter]] {{DE}} (3" adapter user manual)
* [[Media:VTXF1464.DSK|Vortex F1-S/D Systemdiskette für CPC 464]] (system disk, 720k image, bootable)
* [[Media:VORTF1.DSK|Vortex F1-S/D Systemdiskette für CPC 664/6128]] (system disk, 720k image)
* [[Media:Vortex10.zip|VDOS 1.0 ROM]] {{DE}}
* [[Media:Vortex20.zip|VDOS 2.0 ROM]] {{DE}}
* [[Media:80307-058 BASF 6138 Mini Disk Apr83.zip|BASF 6138 Datasheet (F1-S/D/Z Floppy Disk Drive)]]

 

== Z-Drives (180K/side) ==

These are less expensive drives and were meant to be directly connected as B drive to a CPC 464 with DDI-1 or a CPC 664/6128. Since these drives ship neither with an own controller nor a [[VDOS]] ROM, they do rely fully on AMSDOS and thus only 40 tracks on one side can be accessed, resulting in the same capacity (180K/side) as the 3" drives.

=== F1-Z (5,25") ===

The F1-Z model is based on a later revision of the BASF 6138 type disk drive (81757-001), which offers more configuration options using jumpers. The drive was shipped in a "double step" configuration to use only 40 tracks, and thus the cheaper and more widely available DS DD floppy disks (48 tpi, 180K/side) could be used.

<gallery>
Image:Basf 6138 81757 001.jpg|BASF AG 6138 (81757-001) drive
Image:Basf 6138 81757 001 jumpers.jpg|BASF AG 6138 (81757-001) 40 track jumper configuration
</gallery>

=== A1-Z Upgrade Kit (5,25") ===

Vortex offered an upgrade kit consisting of a controller, a manual, a CP/M license and an utility disk which allows a F1-Z drive to be upgraded to a F1-S drive.

=== M1-Z (3,5") ===

The M1-Z model is equipped with a single 3,5" disk drive.

 

== X-Drives (720K) ==

These are the latest drives from Vortex for use with a CPC 464 with DDI-1 or a CPC 664/6128 (ie. on systems that already have a floppy disc controller); no additional controller was required anymore. Instead, a ROM module was supplied together with the drive, which provided VDOS 2.0-X. Only single-drive variants were available. The |S command (for accessing a third drive) is no longer used, the new |X command allows to swap drive A and B (same as [[X-DDOS]] from Dobbertin).

=== F1-X and F1-XRS (5,25") ===

The F1-X model is based on either a single BASF 6138 (81690-001 or 81757-001) or a single BASF 6139 5,25" disk drive. The BASF 6139 is a revisioned version which is slightly more compact (~1cm shorter), and also a number of electronical and mechanical design flaws that affected durability were corrected. The F1-XRS variant is equipped with an additional RS232-C interface.

<gallery>
File:F1-x front.jpg|F1-X
File:Vortex f1-x cpc464 backside.jpg|F1-X backside, showing IDC connector (CPC 464)
File:Vortex f1-x cpc664 backside edge.jpg|F1-X backside, showing edge connector (CPC 664)
File:F1-x inside.jpg|F1-X inside view, showing a BASF 6139 drive
File:F1x m1x manual.jpg|F1-X/M1-X manual and system utilities disk
</gallery>

=== M1-X and M1-XRS (3,5") ===

The M1-X model is based on a single NEC FD1035 type 3,5" disk drive. The M1-XRS variant is equipped with an additional RS232-C interface.

<gallery>
File:vortex-m1-x-front.png|M1-X
File:vortex-m1-x-back.png|M1-X backside
File:vortex-m1-x-connector.png|M1-X backside, showing IDC connector (CPC 464)
File:vortex-m1-x-under.png|M1-X underside
File:vortex-m1-x-inside.png|M1-X inside view, showing the drive and power
File:vortex-m1-x-drive-close.png|M1-X inside view, close-up of the drive from above
File:vortex-m1-x-drive-details.png|M1-X inside view, close-up from the backside
</gallery>

=== X(RS)-Modul ===

The X-drives for the CPC 664/6128 are connected directly to the floppy port. In order to provide [[VDOS]], the "X-Modul" (sometimes also called "VDOS module") must be connected additionally to the expansion port. This contains a ROM board that provides a VDOS 2.0-X ROM. The ROM board supplied for the CPC 464 came together with a chunky housing in which both the "X-Modul" and the DDI-1 controller were installed. All variants were also available with an additional RS232-C interface (in this case called either "XRS-Modul" or "X-Modul/RS").

<gallery>
Image:Vortex fd1 464 controller 1.jpg|XRS-Modul (CPC 464)
Image:Vortex fd1 464 controller 2.jpg|XRS-Modul with built-in DDI-1 visible (CPC 464)
Image:Xrs 464.jpg|XRS-Modul board beneath the DDI-1 (CPC 464)
Image:Vortex xrs 464 board backside.jpg|XRS-Modul board backside (CPC 464)
</gallery>
<gallery>
Image:Vortex X-Modul 6128.jpg|X-Modul (CPC 6128)
Image:Vortex X-Modul 6128 Board Front.jpg|X-Modul board (CPC 6128)
Image:Vortex X-Modul 6128 Board Backside.jpg|X-Modul board backside (CPC 6128)
</gallery>

=== RS232 I/O Ports ===

The RS232-C interface of the "XRS-Modul" was advertised to be compatible with Amstrad/Pace interfaces, but offers only one channel (so no channel B).

{| class="wikitable"
|-
! Address !! Description
|-
| 0xFADC || SIO data (R/W)
|-
| 0xFADD || SIO control (R/W)
|-
| 0xFBDC || 8253 counter 0 (R/W)
|-
| 0xFBDD || 8253 counter 1 (R/W)
|-
| 0xFBDE || 8253 counter 2 (R/W)
|-
| 0xFBDF || Mode word (W)
|}

=== Downloads ===

* [https://www.cpcwiki.eu/manuals/Vortex%20X-Laufwerke%20Manual.de.rar Benutzerhandbuch für die Vortex X-Laufwerke] {{DE}} (manual)
* [[Media:Vortex RS232-C Manual.pdf|Benutzerhandbuch für die Vortex RS232-C Schnittstelle]] {{DE}} (RS232-C user manual)
* [[Media:Manual de las Unidades Vortex.pdf|Manual de las Unidades Vortex]] {{ES}} (manual)
* [[Media:VORTF1X.DSK|Systemdiskette für Vortex X-Laufwerke]] (system disk, 720k disk image, original)
* [[Media:VTXF1XB.DSK|Systemdiskette für Vortex X-Laufwerke]] (system disk, 720k disk image, modified to boot CP/M 2.2)
* [[Media:VDOS20X.ROM|VDOS 2.0-X ROM]] {{DE}} (German VDOS 2.0-X ROM for CPC 664/6128)
* [[Media:NEC_FD1035_Floppy.pdf|NEC FD1035 Datasheet (M1-X Floppy Disk Drive)]]

 

== Software Accessories ==

=== DOSCOPY ===

DOSCOPY is a CP/M 2.2 utility which allows to read and write files from IBM and Atari ST formatted 5,25" disks. It was written in 1987 by Peter Höpfner.

<gallery>
Image:Vortex_DOSCOPY_Manual.JPG|DOSCOPY physical manual
Image:Vortex_DOSCOPY_Disk.JPG|DOSCOPY 5,25" disk
Image:Vortex_DOSCOPY_Screenshot.JPG|DOSCOPY screenshot
</gallery>

==== Downloads ====

* [[Media:DOSCOPY.DSK|DOSCOPY 1.1]] {{DE}} (Vortex 360k disk image)
* [[Media:Vortex_DOSCOPY_Benutzerhandbuch.pdf|DOSCOPY 1.1 Benutzerhandbuch]] {{DE}} (manual)

=== PARA 3.0 ===

PARA 3.0 is a CP/M 2.2 utility allowing to exchange files between the CPC and other CP/M based systems. It claims to support "reading, writing and formatting of 99% of all CP/M formats" and provides a comprehensive disk format analzer. It was written in 1987 by Peter Höpfner.

<gallery>
Image:Vortex_PARA_3.0_Manual.JPG|PARA 3.0 physical manual
Image:Vortex PARA 3.0 Disk.JPG|PARA 3.0 5,25" disk
Image:Vortex PARA 3.0 Screenshot 1.JPG|PARA 3.0 loading screen
</gallery>

==== Downloads ====

* [[Media:PARA30.DSK|PARA 3.0]] {{DE}} (Vortex 720k disk image)
* [[Media:Vortex_PARA_3.0_Benutzerhandbuch.zip|PARA 3.0 Benutzerhandbuch]] {{DE}} (manual)

=== PARA 3.0 PLUS ===

PARA 3.0 PLUS (or PARA PLUS) is an enhanced distribution of PARA 3.0 which also integrates DOSCOPY 1.3 into a single software suite.

<gallery>
Image:Para 30 plus intro.jpg|PARA 3.0+ loading screen
Image:Para 30 plus mainmenu.jpg|PARA 3.0+ main menu
Image:Para 30 plus analyzer.jpg|PARA 3.0+ format analyzer
</gallery>

==== Downloads ====

* [[Media:PARAPLUS.DSK|PARA 3.0+]] {{DE}} (Vortex 720k disk image, bootable)

=== SPARA ===

SPARA was either the predecessor or a cut-down version of PARA 3.0 and was supplied with the F1-Z drives, only supporting 40 track formats.

=== FileCopy ===
FileCopy 3.0 is a comprehensive tool to copy files with up to 16 different devices (using letters A to P), it supports the Vortex 704 KB format for 80 Track drives.

 

== 3rd Party Software ==

=== dBASE II ===

Markt & Technik released a version of Ashton-Tate dBASE II 2.41 for owners of a Vortex disk drive.

=== FutureOS ===

[[FutureOS]] has support for Vortex drives, it uses the Vortex 704 KB format for 80 Track drives.

=== House of Usher ===

Besides tape and 3 inch floppy disk release, the game [[House of Usher]] has been officially released on 5.25 inch floppy disk for the Schneider CPC with Vortex F1 floppy drive.

<gallery>
House of Usher ads.jpeg
House-of-usher-floppy-cover.png
House-of-usher-floppy-no-cover.png
</gallery>

=== Multiplan ===

Markt & Technik released a version of Microsoft Multiplan 1.06 for owners of a Vortex disk drive.

==== Downloads ====

* [[Media:MPLAN106.DSK|Microsoft Multiplan 1.06]] {{DE}} (Vortex 720k disk image, bootable CP/M Plus)

=== ParaDOS ===

[[ParaDOS]] supports Vortex X-drives and can be used as a replacement for the VDOS-X ROM. There is also a patched version called VaraDOS, which is configured to use a Vortex X-drive as drive B per default. ParaDOS does not provide a way too boot CP/M from drive B.

=== WordStar 3.0 ===

A version of MicroPro WordStar 3.0 was released by Markt & Technik for owners of a Vortex disk drive.
 

== Media Coverage ==

<gallery>
Image:Vortex Schneider CPC International 1985-09.JPG|Schneider CPC International 1985/09
Image:Vortex schneider cpc international 1986-02.JPG|Schneider CPC International 1986/02
Image:Vortex schneider cpc international 1986-04.JPG|Schneider CPC International 1986/04
Image:Vortex schneider cpc international 1986-07.JPG|Schneider CPC International 1986/07
Image:Vortex schneider cpc international 1986-08.JPG|Schneider CPC International 1986/08
</gallery>

[[Category:Peripherals]] [[Category:Manual]][[Category:DATA Storage]][[Category:Vortex Computersysteme]]

Vortex Disc Drives

2025-08-22T15:14:26Z

Arnoldemu: /* FDC I/O Ports */

A series of external 3,5" and 5,25" floppy disc drives from [[Vortex_Computersysteme|Vortex]] providing up to 720K capacity (704K available). The Vortex drives were most popular in Germany. For more information regarding [[VDOS]] and the Vortex Disk Format, see the dedicated [[VDOS]] Wiki page.

== S- and D-Drives (720K) ==

These are the first generation of 720K floppy disc drives from Vortex. They came in variants having either a single drive ("S" variant) or two drives ("D" variant). The "S" variant (as well as the less expensive "Z" variant) was delivered with the same double-height casing as the "D" variant, so that a second drive could be retrofitted.

The F1-S, F1-D, M1-S, M1-D drives have their own FDC765 in the controller, and this one supports all DS0 up to DS3. The Vortex interface can manage 4 floppy drives in total.

=== F1-S and F1-D (5,25") ===

The F1-S and F1-D models are based on BASF 6138 (81690-001) type 5,25" disk drives, i.e. double-sided, 80 tracks per side, 96 tpi density.

<gallery>
Image:IMG 3163.JPG|F1-D
Image:Vortex f1d front.jpg|F1-D front view
Image:Vortex f1d back.jpg|F1-D backside
</gallery>
<gallery>
Image:Vortex fd-1 interface 664.jpg|F1-D interface (CPC 664)
Image:Fd1 interface 664 platine front.jpg|F1-D interface board (CPC 664)
Image:Fd1 interface 664 platine back.jpg|F1-D interface board (CPC 664)
Image:F1DCONT.jpg|F1-D interface board (CPC 6128)
</gallery>
<gallery>
Image:Vortex f1 manual.jpg|F1-S/D manual
Image:Vortex F1 SystemDisk 464.jpg|F1-S/D system disk (CPC 464)
Image:Vortex f1 manual disk.jpg|F1-S/D system disk (CPC 664/6128)
</gallery>

The floppy controller of the F1-D / F1-S was cloned by Hans Hübner of FutureSoft with MX4 connector and without ROM slot. It supports four drives. Under FutureOS they are named E-H.

=== A1-S Upgrade Kit (5,25") ===

Vortex offered an upgrade kit consisting of a single bare drive and an installation manual, allowing to upgrade a F1-S (single) drive to a F1-D (dual) drive. To do this, one simply had to install the additional drive in the free slot of the drive case.

<gallery>
Image:Basf 6138 spare drive.jpg|BASF 6138 spare drive
</gallery>

=== M1-S and M1-D (3,5") ===

The M1-S and M1-D models are based on 3,5" disk drives. Controller and DOS were identical for 5,25" and 3,5" devices.

=== FDA-1 3" Drive Adapter ===

This adapter allows to connect an external FD-1 3" drive on Vortex F1/M1 setups on the CPC 464. Since only two drives can be used at the same time, the external 3" drive first had to be selected manually with the RSX command '''|S'''. This RSX command worked also with VDOS 2.11 on CPC6128.

{| class="wikitable"
|-
! RSX !! Description
|-
| |S,1 || Use 3" drive as drive A, upper Vortex drive is disabled
|-
| |S,2 || Use 3" drive as drive B, lower Vortex drive is disabled
|-
| |S,0 || Disable the 3" drive (default)
|}

<gallery>
Image:Vortex 3rd drive adapter.jpg|FDA-1 Adapter
Image:Vortex 3rd drive adapter insides.jpg|Inside the adapter box
Image:Vortex 3rd drive adapter insides closeup.jpg|Inside the adapter box (closeup)
Image:Vortex 3rd drive adapter plug cable.jpg|Plug (cable side)
Image:Vortex 3rd drive adapter plug floppy.jpg|FD-1 3" floppy drive plug
</gallery>

=== Clone of the F1-D controller ===
A clone of the F1-D controller was created by [[Hans Hübner]] of [[FutureSoft]] in 2024. The card fits on the Mother X4 board and doesn't contain an extra ROM slot. Using [[FutureOS]] this card allows to add four additional floppy disc drives to the CPC, being called E, F, G and H.

=== FDC I/O Ports ===

All types of floppy disk controllers for the F1-S/D and M1-S/D series are based on the NEC 765 chip.

On the F1-D Reproduction board the ports FA7E, FB7E/FB7F and FBF6/FBF7 are fully decoded. FB7E/FBF6 is chosen with a link/switch on the PCB.

On the F1-D device the I/O ports are partially decoded:

'''CPC 464:'''

{| class="wikitable"
|-
! Address !! Description
|-
| 0xFB7E || uPD control
|-
| 0xFB7F || uPD data
|-
| 0xFA7E || motor on/off
|}

FDC:

A15-A0
xxxx x0x1 0xxx xxxr
A10=0, A8=1 and A7=0

x = not decoded. don't care, 0 or 1 can be used.
r = connected to A0 on NEC765 and selects status register or data register.

Motor:

A15-A0
xxxx x0x0 0xxx xxxr
A10=0, A8=0 and A7=0

x = not decoded. don't care, 0 or 1 can be used.

only bit 0 of the data written to the port controls motor state.

'''CPC 664/6128:'''

{| class="wikitable"
|-
! Address !! Description
|-
| 0xFBF6 || uPD control
|-
| 0xFBF7 || uPD data
|-
| 0xFA7E || motor on/off
|}

On the board above marked 664 there is a patch wire which disconnects A7 and connects A0. This changes the decoding from FB7E/FB7F to FBF6/FBF7.

FDC:

A15-A0
xxxx x0x1 xxxx 0xxr
A10=0, A8=1 and A3=0

x = not decoded. don't care, 0 or 1 can be used.
r = connected to A0 on NEC765 and selects status register or data register.

Motor:

A15-A0
xxxx x0x0 0xxx xxxr
A10=0, A8=0 and A7=0

x = not decoded. don't care, 0 or 1 can be used.

only bit 0 of the data written to the port controls motor state.

The I/O port decoding for the 6128 specific board is unknown.

=== Downloads ===

* [[Media:Vortex Floppy Disk Station F1 für den Schneider CPC 464 - Benutzerhandbuch.pdf|Benutzerhandbuch für die Vortex Floppy Disk Station F1 für den Schneider CPC 464]] {{DE}} (Vortex F1 user manual)
* [[Media:Vortex_Vdos_2.0_Manual.pdf|Benutzerhandbuch für das Diskettenbetriebssystem VDOS 2.0]] {{DE}} (VDOS 2.0 user manual)
* [[Media:3-Zoll-Adapter zur VORTEX-Diskettenstation.pdf|Benutzerhandbuch für den FDA-1 3"-Adapter]] {{DE}} (3" adapter user manual)
* [[Media:VTXF1464.DSK|Vortex F1-S/D Systemdiskette für CPC 464]] (system disk, 720k image, bootable)
* [[Media:VORTF1.DSK|Vortex F1-S/D Systemdiskette für CPC 664/6128]] (system disk, 720k image)
* [[Media:Vortex10.zip|VDOS 1.0 ROM]] {{DE}}
* [[Media:Vortex20.zip|VDOS 2.0 ROM]] {{DE}}
* [[Media:80307-058 BASF 6138 Mini Disk Apr83.zip|BASF 6138 Datasheet (F1-S/D/Z Floppy Disk Drive)]]

 

== Z-Drives (180K/side) ==

These are less expensive drives and were meant to be directly connected as B drive to a CPC 464 with DDI-1 or a CPC 664/6128. Since these drives ship neither with an own controller nor a [[VDOS]] ROM, they do rely fully on AMSDOS and thus only 40 tracks on one side can be accessed, resulting in the same capacity (180K/side) as the 3" drives.

=== F1-Z (5,25") ===

The F1-Z model is based on a later revision of the BASF 6138 type disk drive (81757-001), which offers more configuration options using jumpers. The drive was shipped in a "double step" configuration to use only 40 tracks, and thus the cheaper and more widely available DS DD floppy disks (48 tpi, 180K/side) could be used.

<gallery>
Image:Basf 6138 81757 001.jpg|BASF AG 6138 (81757-001) drive
Image:Basf 6138 81757 001 jumpers.jpg|BASF AG 6138 (81757-001) 40 track jumper configuration
</gallery>

=== A1-Z Upgrade Kit (5,25") ===

Vortex offered an upgrade kit consisting of a controller, a manual, a CP/M license and an utility disk which allows a F1-Z drive to be upgraded to a F1-S drive.

=== M1-Z (3,5") ===

The M1-Z model is equipped with a single 3,5" disk drive.

 

== X-Drives (720K) ==

These are the latest drives from Vortex for use with a CPC 464 with DDI-1 or a CPC 664/6128 (ie. on systems that already have a floppy disc controller); no additional controller was required anymore. Instead, a ROM module was supplied together with the drive, which provided VDOS 2.0-X. Only single-drive variants were available. The |S command (for accessing a third drive) is no longer used, the new |X command allows to swap drive A and B (same as [[X-DDOS]] from Dobbertin).

=== F1-X and F1-XRS (5,25") ===

The F1-X model is based on either a single BASF 6138 (81690-001 or 81757-001) or a single BASF 6139 5,25" disk drive. The BASF 6139 is a revisioned version which is slightly more compact (~1cm shorter), and also a number of electronical and mechanical design flaws that affected durability were corrected. The F1-XRS variant is equipped with an additional RS232-C interface.

<gallery>
File:F1-x front.jpg|F1-X
File:Vortex f1-x cpc464 backside.jpg|F1-X backside, showing IDC connector (CPC 464)
File:Vortex f1-x cpc664 backside edge.jpg|F1-X backside, showing edge connector (CPC 664)
File:F1-x inside.jpg|F1-X inside view, showing a BASF 6139 drive
File:F1x m1x manual.jpg|F1-X/M1-X manual and system utilities disk
</gallery>

=== M1-X and M1-XRS (3,5") ===

The M1-X model is based on a single NEC FD1035 type 3,5" disk drive. The M1-XRS variant is equipped with an additional RS232-C interface.

<gallery>
File:vortex-m1-x-front.png|M1-X
File:vortex-m1-x-back.png|M1-X backside
File:vortex-m1-x-connector.png|M1-X backside, showing IDC connector (CPC 464)
File:vortex-m1-x-under.png|M1-X underside
File:vortex-m1-x-inside.png|M1-X inside view, showing the drive and power
File:vortex-m1-x-drive-close.png|M1-X inside view, close-up of the drive from above
File:vortex-m1-x-drive-details.png|M1-X inside view, close-up from the backside
</gallery>

=== X(RS)-Modul ===

The X-drives for the CPC 664/6128 are connected directly to the floppy port. In order to provide [[VDOS]], the "X-Modul" (sometimes also called "VDOS module") must be connected additionally to the expansion port. This contains a ROM board that provides a VDOS 2.0-X ROM. The ROM board supplied for the CPC 464 came together with a chunky housing in which both the "X-Modul" and the DDI-1 controller were installed. All variants were also available with an additional RS232-C interface (in this case called either "XRS-Modul" or "X-Modul/RS").

<gallery>
Image:Vortex fd1 464 controller 1.jpg|XRS-Modul (CPC 464)
Image:Vortex fd1 464 controller 2.jpg|XRS-Modul with built-in DDI-1 visible (CPC 464)
Image:Xrs 464.jpg|XRS-Modul board beneath the DDI-1 (CPC 464)
Image:Vortex xrs 464 board backside.jpg|XRS-Modul board backside (CPC 464)
</gallery>
<gallery>
Image:Vortex X-Modul 6128.jpg|X-Modul (CPC 6128)
Image:Vortex X-Modul 6128 Board Front.jpg|X-Modul board (CPC 6128)
Image:Vortex X-Modul 6128 Board Backside.jpg|X-Modul board backside (CPC 6128)
</gallery>

=== RS232 I/O Ports ===

The RS232-C interface of the "XRS-Modul" was advertised to be compatible with Amstrad/Pace interfaces, but offers only one channel (so no channel B).

{| class="wikitable"
|-
! Address !! Description
|-
| 0xFADC || SIO data (R/W)
|-
| 0xFADD || SIO control (R/W)
|-
| 0xFBDC || 8253 counter 0 (R/W)
|-
| 0xFBDD || 8253 counter 1 (R/W)
|-
| 0xFBDE || 8253 counter 2 (R/W)
|-
| 0xFBDF || Mode word (W)
|}

=== Downloads ===

* [https://www.cpcwiki.eu/manuals/Vortex%20X-Laufwerke%20Manual.de.rar Benutzerhandbuch für die Vortex X-Laufwerke] {{DE}} (manual)
* [[Media:Vortex RS232-C Manual.pdf|Benutzerhandbuch für die Vortex RS232-C Schnittstelle]] {{DE}} (RS232-C user manual)
* [[Media:Manual de las Unidades Vortex.pdf|Manual de las Unidades Vortex]] {{ES}} (manual)
* [[Media:VORTF1X.DSK|Systemdiskette für Vortex X-Laufwerke]] (system disk, 720k disk image, original)
* [[Media:VTXF1XB.DSK|Systemdiskette für Vortex X-Laufwerke]] (system disk, 720k disk image, modified to boot CP/M 2.2)
* [[Media:VDOS20X.ROM|VDOS 2.0-X ROM]] {{DE}} (German VDOS 2.0-X ROM for CPC 664/6128)
* [[Media:NEC_FD1035_Floppy.pdf|NEC FD1035 Datasheet (M1-X Floppy Disk Drive)]]

 

== Software Accessories ==

=== DOSCOPY ===

DOSCOPY is a CP/M 2.2 utility which allows to read and write files from IBM and Atari ST formatted 5,25" disks. It was written in 1987 by Peter Höpfner.

<gallery>
Image:Vortex_DOSCOPY_Manual.JPG|DOSCOPY physical manual
Image:Vortex_DOSCOPY_Disk.JPG|DOSCOPY 5,25" disk
Image:Vortex_DOSCOPY_Screenshot.JPG|DOSCOPY screenshot
</gallery>

==== Downloads ====

* [[Media:DOSCOPY.DSK|DOSCOPY 1.1]] {{DE}} (Vortex 360k disk image)
* [[Media:Vortex_DOSCOPY_Benutzerhandbuch.pdf|DOSCOPY 1.1 Benutzerhandbuch]] {{DE}} (manual)

=== PARA 3.0 ===

PARA 3.0 is a CP/M 2.2 utility allowing to exchange files between the CPC and other CP/M based systems. It claims to support "reading, writing and formatting of 99% of all CP/M formats" and provides a comprehensive disk format analzer. It was written in 1987 by Peter Höpfner.

<gallery>
Image:Vortex_PARA_3.0_Manual.JPG|PARA 3.0 physical manual
Image:Vortex PARA 3.0 Disk.JPG|PARA 3.0 5,25" disk
Image:Vortex PARA 3.0 Screenshot 1.JPG|PARA 3.0 loading screen
</gallery>

==== Downloads ====

* [[Media:PARA30.DSK|PARA 3.0]] {{DE}} (Vortex 720k disk image)
* [[Media:Vortex_PARA_3.0_Benutzerhandbuch.zip|PARA 3.0 Benutzerhandbuch]] {{DE}} (manual)

=== PARA 3.0 PLUS ===

PARA 3.0 PLUS (or PARA PLUS) is an enhanced distribution of PARA 3.0 which also integrates DOSCOPY 1.3 into a single software suite.

<gallery>
Image:Para 30 plus intro.jpg|PARA 3.0+ loading screen
Image:Para 30 plus mainmenu.jpg|PARA 3.0+ main menu
Image:Para 30 plus analyzer.jpg|PARA 3.0+ format analyzer
</gallery>

==== Downloads ====

* [[Media:PARAPLUS.DSK|PARA 3.0+]] {{DE}} (Vortex 720k disk image, bootable)

=== SPARA ===

SPARA was either the predecessor or a cut-down version of PARA 3.0 and was supplied with the F1-Z drives, only supporting 40 track formats.

=== FileCopy ===
FileCopy 3.0 is a comprehensive tool to copy files with up to 16 different devices (using letters A to P), it supports the Vortex 704 KB format for 80 Track drives.

 

== 3rd Party Software ==

=== dBASE II ===

Markt & Technik released a version of Ashton-Tate dBASE II 2.41 for owners of a Vortex disk drive.

=== FutureOS ===

[[FutureOS]] has support for Vortex drives, it uses the Vortex 704 KB format for 80 Track drives.

=== House of Usher ===

Besides tape and 3 inch floppy disk release, the game [[House of Usher]] has been officially released on 5.25 inch floppy disk for the Schneider CPC with Vortex F1 floppy drive.

<gallery>
House of Usher ads.jpeg
House-of-usher-floppy-cover.png
House-of-usher-floppy-no-cover.png
</gallery>

=== Multiplan ===

Markt & Technik released a version of Microsoft Multiplan 1.06 for owners of a Vortex disk drive.

==== Downloads ====

* [[Media:MPLAN106.DSK|Microsoft Multiplan 1.06]] {{DE}} (Vortex 720k disk image, bootable CP/M Plus)

=== ParaDOS ===

[[ParaDOS]] supports Vortex X-drives and can be used as a replacement for the VDOS-X ROM. There is also a patched version called VaraDOS, which is configured to use a Vortex X-drive as drive B per default. ParaDOS does not provide a way too boot CP/M from drive B.

=== WordStar 3.0 ===

A version of MicroPro WordStar 3.0 was released by Markt & Technik for owners of a Vortex disk drive.
 

== Media Coverage ==

<gallery>
Image:Vortex Schneider CPC International 1985-09.JPG|Schneider CPC International 1985/09
Image:Vortex schneider cpc international 1986-02.JPG|Schneider CPC International 1986/02
Image:Vortex schneider cpc international 1986-04.JPG|Schneider CPC International 1986/04
Image:Vortex schneider cpc international 1986-07.JPG|Schneider CPC International 1986/07
Image:Vortex schneider cpc international 1986-08.JPG|Schneider CPC International 1986/08
</gallery>

[[Category:Peripherals]] [[Category:Manual]][[Category:DATA Storage]][[Category:Vortex Computersysteme]]

Vortex Disc Drives

2025-08-22T15:13:35Z

Arnoldemu: /* FDC I/O Ports */

A series of external 3,5" and 5,25" floppy disc drives from [[Vortex_Computersysteme|Vortex]] providing up to 720K capacity (704K available). The Vortex drives were most popular in Germany. For more information regarding [[VDOS]] and the Vortex Disk Format, see the dedicated [[VDOS]] Wiki page.

== S- and D-Drives (720K) ==

These are the first generation of 720K floppy disc drives from Vortex. They came in variants having either a single drive ("S" variant) or two drives ("D" variant). The "S" variant (as well as the less expensive "Z" variant) was delivered with the same double-height casing as the "D" variant, so that a second drive could be retrofitted.

The F1-S, F1-D, M1-S, M1-D drives have their own FDC765 in the controller, and this one supports all DS0 up to DS3. The Vortex interface can manage 4 floppy drives in total.

=== F1-S and F1-D (5,25") ===

The F1-S and F1-D models are based on BASF 6138 (81690-001) type 5,25" disk drives, i.e. double-sided, 80 tracks per side, 96 tpi density.

<gallery>
Image:IMG 3163.JPG|F1-D
Image:Vortex f1d front.jpg|F1-D front view
Image:Vortex f1d back.jpg|F1-D backside
</gallery>
<gallery>
Image:Vortex fd-1 interface 664.jpg|F1-D interface (CPC 664)
Image:Fd1 interface 664 platine front.jpg|F1-D interface board (CPC 664)
Image:Fd1 interface 664 platine back.jpg|F1-D interface board (CPC 664)
Image:F1DCONT.jpg|F1-D interface board (CPC 6128)
</gallery>
<gallery>
Image:Vortex f1 manual.jpg|F1-S/D manual
Image:Vortex F1 SystemDisk 464.jpg|F1-S/D system disk (CPC 464)
Image:Vortex f1 manual disk.jpg|F1-S/D system disk (CPC 664/6128)
</gallery>

The floppy controller of the F1-D / F1-S was cloned by Hans Hübner of FutureSoft with MX4 connector and without ROM slot. It supports four drives. Under FutureOS they are named E-H.

=== A1-S Upgrade Kit (5,25") ===

Vortex offered an upgrade kit consisting of a single bare drive and an installation manual, allowing to upgrade a F1-S (single) drive to a F1-D (dual) drive. To do this, one simply had to install the additional drive in the free slot of the drive case.

<gallery>
Image:Basf 6138 spare drive.jpg|BASF 6138 spare drive
</gallery>

=== M1-S and M1-D (3,5") ===

The M1-S and M1-D models are based on 3,5" disk drives. Controller and DOS were identical for 5,25" and 3,5" devices.

=== FDA-1 3" Drive Adapter ===

This adapter allows to connect an external FD-1 3" drive on Vortex F1/M1 setups on the CPC 464. Since only two drives can be used at the same time, the external 3" drive first had to be selected manually with the RSX command '''|S'''. This RSX command worked also with VDOS 2.11 on CPC6128.

{| class="wikitable"
|-
! RSX !! Description
|-
| |S,1 || Use 3" drive as drive A, upper Vortex drive is disabled
|-
| |S,2 || Use 3" drive as drive B, lower Vortex drive is disabled
|-
| |S,0 || Disable the 3" drive (default)
|}

<gallery>
Image:Vortex 3rd drive adapter.jpg|FDA-1 Adapter
Image:Vortex 3rd drive adapter insides.jpg|Inside the adapter box
Image:Vortex 3rd drive adapter insides closeup.jpg|Inside the adapter box (closeup)
Image:Vortex 3rd drive adapter plug cable.jpg|Plug (cable side)
Image:Vortex 3rd drive adapter plug floppy.jpg|FD-1 3" floppy drive plug
</gallery>

=== Clone of the F1-D controller ===
A clone of the F1-D controller was created by [[Hans Hübner]] of [[FutureSoft]] in 2024. The card fits on the Mother X4 board and doesn't contain an extra ROM slot. Using [[FutureOS]] this card allows to add four additional floppy disc drives to the CPC, being called E, F, G and H.

=== FDC I/O Ports ===

All types of floppy disk controllers for the F1-S/D and M1-S/D series are based on the NEC 765 chip.

On the F1-D Reproduction board the ports FA7E, FB7E/FB7F and FBF6/FBF7 are fully decoded. FB7E/FBF6 is chosen with a link/switch on the PCB.

On the F1-D device the I/O ports are partially decoded:

'''CPC 464:'''

{| class="wikitable"
|-
! Address !! Description
|-
| 0xFB7E || uPD control
|-
| 0xFB7F || uPD data
|-
| 0xFA7E || motor on/off
|}

FDC:

A15-A0
xxxx x0x1 0xxx xxxr
A10=0, A8=1 and A7=0

x = not decoded. don't care, 0 or 1 can be used.
r = connected to A0 on NEC765 and selects status register or data register.

Motor:

A15-A0
xxxx x0x0 0xxx xxxr
A10=0, A8=0 and A7=0

x = not decoded. don't care, 0 or 1 can be used.

only bit 0/D0 controls motor state.

'''CPC 664/6128:'''

{| class="wikitable"
|-
! Address !! Description
|-
| 0xFBF6 || uPD control
|-
| 0xFBF7 || uPD data
|-
| 0xFA7E || motor on/off
|}

On the board above marked 664 there is a patch wire which disconnects A7 and connects A0. This changes the decoding from FB7E/FB7F to FBF6/FBF7.

FDC:

A15-A0
xxxx x0x1 xxxx 0xxr
A10=0, A8=1 and A3=0

x = not decoded. don't care, 0 or 1 can be used.
r = connected to A0 on NEC765 and selects status register or data register.

Motor:

A15-A0
xxxx x0x0 0xxx xxxr
A10=0, A8=0 and A7=0

x = not decoded. don't care, 0 or 1 can be used.

only bit 0/D0 controls motor state.

The I/O port decoding for the 6128 specific board is unknown.

=== Downloads ===

* [[Media:Vortex Floppy Disk Station F1 für den Schneider CPC 464 - Benutzerhandbuch.pdf|Benutzerhandbuch für die Vortex Floppy Disk Station F1 für den Schneider CPC 464]] {{DE}} (Vortex F1 user manual)
* [[Media:Vortex_Vdos_2.0_Manual.pdf|Benutzerhandbuch für das Diskettenbetriebssystem VDOS 2.0]] {{DE}} (VDOS 2.0 user manual)
* [[Media:3-Zoll-Adapter zur VORTEX-Diskettenstation.pdf|Benutzerhandbuch für den FDA-1 3"-Adapter]] {{DE}} (3" adapter user manual)
* [[Media:VTXF1464.DSK|Vortex F1-S/D Systemdiskette für CPC 464]] (system disk, 720k image, bootable)
* [[Media:VORTF1.DSK|Vortex F1-S/D Systemdiskette für CPC 664/6128]] (system disk, 720k image)
* [[Media:Vortex10.zip|VDOS 1.0 ROM]] {{DE}}
* [[Media:Vortex20.zip|VDOS 2.0 ROM]] {{DE}}
* [[Media:80307-058 BASF 6138 Mini Disk Apr83.zip|BASF 6138 Datasheet (F1-S/D/Z Floppy Disk Drive)]]

 

== Z-Drives (180K/side) ==

These are less expensive drives and were meant to be directly connected as B drive to a CPC 464 with DDI-1 or a CPC 664/6128. Since these drives ship neither with an own controller nor a [[VDOS]] ROM, they do rely fully on AMSDOS and thus only 40 tracks on one side can be accessed, resulting in the same capacity (180K/side) as the 3" drives.

=== F1-Z (5,25") ===

The F1-Z model is based on a later revision of the BASF 6138 type disk drive (81757-001), which offers more configuration options using jumpers. The drive was shipped in a "double step" configuration to use only 40 tracks, and thus the cheaper and more widely available DS DD floppy disks (48 tpi, 180K/side) could be used.

<gallery>
Image:Basf 6138 81757 001.jpg|BASF AG 6138 (81757-001) drive
Image:Basf 6138 81757 001 jumpers.jpg|BASF AG 6138 (81757-001) 40 track jumper configuration
</gallery>

=== A1-Z Upgrade Kit (5,25") ===

Vortex offered an upgrade kit consisting of a controller, a manual, a CP/M license and an utility disk which allows a F1-Z drive to be upgraded to a F1-S drive.

=== M1-Z (3,5") ===

The M1-Z model is equipped with a single 3,5" disk drive.

 

== X-Drives (720K) ==

These are the latest drives from Vortex for use with a CPC 464 with DDI-1 or a CPC 664/6128 (ie. on systems that already have a floppy disc controller); no additional controller was required anymore. Instead, a ROM module was supplied together with the drive, which provided VDOS 2.0-X. Only single-drive variants were available. The |S command (for accessing a third drive) is no longer used, the new |X command allows to swap drive A and B (same as [[X-DDOS]] from Dobbertin).

=== F1-X and F1-XRS (5,25") ===

The F1-X model is based on either a single BASF 6138 (81690-001 or 81757-001) or a single BASF 6139 5,25" disk drive. The BASF 6139 is a revisioned version which is slightly more compact (~1cm shorter), and also a number of electronical and mechanical design flaws that affected durability were corrected. The F1-XRS variant is equipped with an additional RS232-C interface.

<gallery>
File:F1-x front.jpg|F1-X
File:Vortex f1-x cpc464 backside.jpg|F1-X backside, showing IDC connector (CPC 464)
File:Vortex f1-x cpc664 backside edge.jpg|F1-X backside, showing edge connector (CPC 664)
File:F1-x inside.jpg|F1-X inside view, showing a BASF 6139 drive
File:F1x m1x manual.jpg|F1-X/M1-X manual and system utilities disk
</gallery>

=== M1-X and M1-XRS (3,5") ===

The M1-X model is based on a single NEC FD1035 type 3,5" disk drive. The M1-XRS variant is equipped with an additional RS232-C interface.

<gallery>
File:vortex-m1-x-front.png|M1-X
File:vortex-m1-x-back.png|M1-X backside
File:vortex-m1-x-connector.png|M1-X backside, showing IDC connector (CPC 464)
File:vortex-m1-x-under.png|M1-X underside
File:vortex-m1-x-inside.png|M1-X inside view, showing the drive and power
File:vortex-m1-x-drive-close.png|M1-X inside view, close-up of the drive from above
File:vortex-m1-x-drive-details.png|M1-X inside view, close-up from the backside
</gallery>

=== X(RS)-Modul ===

The X-drives for the CPC 664/6128 are connected directly to the floppy port. In order to provide [[VDOS]], the "X-Modul" (sometimes also called "VDOS module") must be connected additionally to the expansion port. This contains a ROM board that provides a VDOS 2.0-X ROM. The ROM board supplied for the CPC 464 came together with a chunky housing in which both the "X-Modul" and the DDI-1 controller were installed. All variants were also available with an additional RS232-C interface (in this case called either "XRS-Modul" or "X-Modul/RS").

<gallery>
Image:Vortex fd1 464 controller 1.jpg|XRS-Modul (CPC 464)
Image:Vortex fd1 464 controller 2.jpg|XRS-Modul with built-in DDI-1 visible (CPC 464)
Image:Xrs 464.jpg|XRS-Modul board beneath the DDI-1 (CPC 464)
Image:Vortex xrs 464 board backside.jpg|XRS-Modul board backside (CPC 464)
</gallery>
<gallery>
Image:Vortex X-Modul 6128.jpg|X-Modul (CPC 6128)
Image:Vortex X-Modul 6128 Board Front.jpg|X-Modul board (CPC 6128)
Image:Vortex X-Modul 6128 Board Backside.jpg|X-Modul board backside (CPC 6128)
</gallery>

=== RS232 I/O Ports ===

The RS232-C interface of the "XRS-Modul" was advertised to be compatible with Amstrad/Pace interfaces, but offers only one channel (so no channel B).

{| class="wikitable"
|-
! Address !! Description
|-
| 0xFADC || SIO data (R/W)
|-
| 0xFADD || SIO control (R/W)
|-
| 0xFBDC || 8253 counter 0 (R/W)
|-
| 0xFBDD || 8253 counter 1 (R/W)
|-
| 0xFBDE || 8253 counter 2 (R/W)
|-
| 0xFBDF || Mode word (W)
|}

=== Downloads ===

* [https://www.cpcwiki.eu/manuals/Vortex%20X-Laufwerke%20Manual.de.rar Benutzerhandbuch für die Vortex X-Laufwerke] {{DE}} (manual)
* [[Media:Vortex RS232-C Manual.pdf|Benutzerhandbuch für die Vortex RS232-C Schnittstelle]] {{DE}} (RS232-C user manual)
* [[Media:Manual de las Unidades Vortex.pdf|Manual de las Unidades Vortex]] {{ES}} (manual)
* [[Media:VORTF1X.DSK|Systemdiskette für Vortex X-Laufwerke]] (system disk, 720k disk image, original)
* [[Media:VTXF1XB.DSK|Systemdiskette für Vortex X-Laufwerke]] (system disk, 720k disk image, modified to boot CP/M 2.2)
* [[Media:VDOS20X.ROM|VDOS 2.0-X ROM]] {{DE}} (German VDOS 2.0-X ROM for CPC 664/6128)
* [[Media:NEC_FD1035_Floppy.pdf|NEC FD1035 Datasheet (M1-X Floppy Disk Drive)]]

 

== Software Accessories ==

=== DOSCOPY ===

DOSCOPY is a CP/M 2.2 utility which allows to read and write files from IBM and Atari ST formatted 5,25" disks. It was written in 1987 by Peter Höpfner.

<gallery>
Image:Vortex_DOSCOPY_Manual.JPG|DOSCOPY physical manual
Image:Vortex_DOSCOPY_Disk.JPG|DOSCOPY 5,25" disk
Image:Vortex_DOSCOPY_Screenshot.JPG|DOSCOPY screenshot
</gallery>

==== Downloads ====

* [[Media:DOSCOPY.DSK|DOSCOPY 1.1]] {{DE}} (Vortex 360k disk image)
* [[Media:Vortex_DOSCOPY_Benutzerhandbuch.pdf|DOSCOPY 1.1 Benutzerhandbuch]] {{DE}} (manual)

=== PARA 3.0 ===

PARA 3.0 is a CP/M 2.2 utility allowing to exchange files between the CPC and other CP/M based systems. It claims to support "reading, writing and formatting of 99% of all CP/M formats" and provides a comprehensive disk format analzer. It was written in 1987 by Peter Höpfner.

<gallery>
Image:Vortex_PARA_3.0_Manual.JPG|PARA 3.0 physical manual
Image:Vortex PARA 3.0 Disk.JPG|PARA 3.0 5,25" disk
Image:Vortex PARA 3.0 Screenshot 1.JPG|PARA 3.0 loading screen
</gallery>

==== Downloads ====

* [[Media:PARA30.DSK|PARA 3.0]] {{DE}} (Vortex 720k disk image)
* [[Media:Vortex_PARA_3.0_Benutzerhandbuch.zip|PARA 3.0 Benutzerhandbuch]] {{DE}} (manual)

=== PARA 3.0 PLUS ===

PARA 3.0 PLUS (or PARA PLUS) is an enhanced distribution of PARA 3.0 which also integrates DOSCOPY 1.3 into a single software suite.

<gallery>
Image:Para 30 plus intro.jpg|PARA 3.0+ loading screen
Image:Para 30 plus mainmenu.jpg|PARA 3.0+ main menu
Image:Para 30 plus analyzer.jpg|PARA 3.0+ format analyzer
</gallery>

==== Downloads ====

* [[Media:PARAPLUS.DSK|PARA 3.0+]] {{DE}} (Vortex 720k disk image, bootable)

=== SPARA ===

SPARA was either the predecessor or a cut-down version of PARA 3.0 and was supplied with the F1-Z drives, only supporting 40 track formats.

=== FileCopy ===
FileCopy 3.0 is a comprehensive tool to copy files with up to 16 different devices (using letters A to P), it supports the Vortex 704 KB format for 80 Track drives.

 

== 3rd Party Software ==

=== dBASE II ===

Markt & Technik released a version of Ashton-Tate dBASE II 2.41 for owners of a Vortex disk drive.

=== FutureOS ===

[[FutureOS]] has support for Vortex drives, it uses the Vortex 704 KB format for 80 Track drives.

=== House of Usher ===

Besides tape and 3 inch floppy disk release, the game [[House of Usher]] has been officially released on 5.25 inch floppy disk for the Schneider CPC with Vortex F1 floppy drive.

<gallery>
House of Usher ads.jpeg
House-of-usher-floppy-cover.png
House-of-usher-floppy-no-cover.png
</gallery>

=== Multiplan ===

Markt & Technik released a version of Microsoft Multiplan 1.06 for owners of a Vortex disk drive.

==== Downloads ====

* [[Media:MPLAN106.DSK|Microsoft Multiplan 1.06]] {{DE}} (Vortex 720k disk image, bootable CP/M Plus)

=== ParaDOS ===

[[ParaDOS]] supports Vortex X-drives and can be used as a replacement for the VDOS-X ROM. There is also a patched version called VaraDOS, which is configured to use a Vortex X-drive as drive B per default. ParaDOS does not provide a way too boot CP/M from drive B.

=== WordStar 3.0 ===

A version of MicroPro WordStar 3.0 was released by Markt & Technik for owners of a Vortex disk drive.
 

== Media Coverage ==

<gallery>
Image:Vortex Schneider CPC International 1985-09.JPG|Schneider CPC International 1985/09
Image:Vortex schneider cpc international 1986-02.JPG|Schneider CPC International 1986/02
Image:Vortex schneider cpc international 1986-04.JPG|Schneider CPC International 1986/04
Image:Vortex schneider cpc international 1986-07.JPG|Schneider CPC International 1986/07
Image:Vortex schneider cpc international 1986-08.JPG|Schneider CPC International 1986/08
</gallery>

[[Category:Peripherals]] [[Category:Manual]][[Category:DATA Storage]][[Category:Vortex Computersysteme]]

Vortex Disc Drives

2025-08-22T15:13:11Z

Arnoldemu: /* FDC I/O Ports */

A series of external 3,5" and 5,25" floppy disc drives from [[Vortex_Computersysteme|Vortex]] providing up to 720K capacity (704K available). The Vortex drives were most popular in Germany. For more information regarding [[VDOS]] and the Vortex Disk Format, see the dedicated [[VDOS]] Wiki page.

== S- and D-Drives (720K) ==

These are the first generation of 720K floppy disc drives from Vortex. They came in variants having either a single drive ("S" variant) or two drives ("D" variant). The "S" variant (as well as the less expensive "Z" variant) was delivered with the same double-height casing as the "D" variant, so that a second drive could be retrofitted.

The F1-S, F1-D, M1-S, M1-D drives have their own FDC765 in the controller, and this one supports all DS0 up to DS3. The Vortex interface can manage 4 floppy drives in total.

=== F1-S and F1-D (5,25") ===

The F1-S and F1-D models are based on BASF 6138 (81690-001) type 5,25" disk drives, i.e. double-sided, 80 tracks per side, 96 tpi density.

<gallery>
Image:IMG 3163.JPG|F1-D
Image:Vortex f1d front.jpg|F1-D front view
Image:Vortex f1d back.jpg|F1-D backside
</gallery>
<gallery>
Image:Vortex fd-1 interface 664.jpg|F1-D interface (CPC 664)
Image:Fd1 interface 664 platine front.jpg|F1-D interface board (CPC 664)
Image:Fd1 interface 664 platine back.jpg|F1-D interface board (CPC 664)
Image:F1DCONT.jpg|F1-D interface board (CPC 6128)
</gallery>
<gallery>
Image:Vortex f1 manual.jpg|F1-S/D manual
Image:Vortex F1 SystemDisk 464.jpg|F1-S/D system disk (CPC 464)
Image:Vortex f1 manual disk.jpg|F1-S/D system disk (CPC 664/6128)
</gallery>

The floppy controller of the F1-D / F1-S was cloned by Hans Hübner of FutureSoft with MX4 connector and without ROM slot. It supports four drives. Under FutureOS they are named E-H.

=== A1-S Upgrade Kit (5,25") ===

Vortex offered an upgrade kit consisting of a single bare drive and an installation manual, allowing to upgrade a F1-S (single) drive to a F1-D (dual) drive. To do this, one simply had to install the additional drive in the free slot of the drive case.

<gallery>
Image:Basf 6138 spare drive.jpg|BASF 6138 spare drive
</gallery>

=== M1-S and M1-D (3,5") ===

The M1-S and M1-D models are based on 3,5" disk drives. Controller and DOS were identical for 5,25" and 3,5" devices.

=== FDA-1 3" Drive Adapter ===

This adapter allows to connect an external FD-1 3" drive on Vortex F1/M1 setups on the CPC 464. Since only two drives can be used at the same time, the external 3" drive first had to be selected manually with the RSX command '''|S'''. This RSX command worked also with VDOS 2.11 on CPC6128.

{| class="wikitable"
|-
! RSX !! Description
|-
| |S,1 || Use 3" drive as drive A, upper Vortex drive is disabled
|-
| |S,2 || Use 3" drive as drive B, lower Vortex drive is disabled
|-
| |S,0 || Disable the 3" drive (default)
|}

<gallery>
Image:Vortex 3rd drive adapter.jpg|FDA-1 Adapter
Image:Vortex 3rd drive adapter insides.jpg|Inside the adapter box
Image:Vortex 3rd drive adapter insides closeup.jpg|Inside the adapter box (closeup)
Image:Vortex 3rd drive adapter plug cable.jpg|Plug (cable side)
Image:Vortex 3rd drive adapter plug floppy.jpg|FD-1 3" floppy drive plug
</gallery>

=== Clone of the F1-D controller ===
A clone of the F1-D controller was created by [[Hans Hübner]] of [[FutureSoft]] in 2024. The card fits on the Mother X4 board and doesn't contain an extra ROM slot. Using [[FutureOS]] this card allows to add four additional floppy disc drives to the CPC, being called E, F, G and H.

=== FDC I/O Ports ===

All types of floppy disk controllers for the F1-S/D and M1-S/D series are based on the NEC 765 chip.

On the F1-D Reproduction board the ports FA7E, FB7E/FB7F and FBF6/FBF7 are fully decoded. FB7E/FBF6 is chosen with a link/switch on the PCB.

On the F1-D device the I/O port is partially decoded:

'''CPC 464:'''

{| class="wikitable"
|-
! Address !! Description
|-
| 0xFB7E || uPD control
|-
| 0xFB7F || uPD data
|-
| 0xFA7E || motor on/off
|}

FDC:

A15-A0
xxxx x0x1 0xxx xxxr
A10=0, A8=1 and A7=0

x = not decoded. don't care, 0 or 1 can be used.
r = connected to A0 on NEC765 and selects status register or data register.

Motor:

A15-A0
xxxx x0x0 0xxx xxxr
A10=0, A8=0 and A7=0

x = not decoded. don't care, 0 or 1 can be used.

only bit 0/D0 controls motor state.

'''CPC 664/6128:'''

{| class="wikitable"
|-
! Address !! Description
|-
| 0xFBF6 || uPD control
|-
| 0xFBF7 || uPD data
|-
| 0xFA7E || motor on/off
|}

On the board above marked 664 there is a patch wire which disconnects A7 and connects A0. This changes the decoding from FB7E/FB7F to FBF6/FBF7.

FDC:

A15-A0
xxxx x0x1 xxxx 0xxr
A10=0, A8=1 and A3=0

x = not decoded. don't care, 0 or 1 can be used.
r = connected to A0 on NEC765 and selects status register or data register.

Motor:

A15-A0
xxxx x0x0 0xxx xxxr
A10=0, A8=0 and A7=0

x = not decoded. don't care, 0 or 1 can be used.

only bit 0/D0 controls motor state.

The I/O port decoding for the 6128 specific board is unknown.

=== Downloads ===

* [[Media:Vortex Floppy Disk Station F1 für den Schneider CPC 464 - Benutzerhandbuch.pdf|Benutzerhandbuch für die Vortex Floppy Disk Station F1 für den Schneider CPC 464]] {{DE}} (Vortex F1 user manual)
* [[Media:Vortex_Vdos_2.0_Manual.pdf|Benutzerhandbuch für das Diskettenbetriebssystem VDOS 2.0]] {{DE}} (VDOS 2.0 user manual)
* [[Media:3-Zoll-Adapter zur VORTEX-Diskettenstation.pdf|Benutzerhandbuch für den FDA-1 3"-Adapter]] {{DE}} (3" adapter user manual)
* [[Media:VTXF1464.DSK|Vortex F1-S/D Systemdiskette für CPC 464]] (system disk, 720k image, bootable)
* [[Media:VORTF1.DSK|Vortex F1-S/D Systemdiskette für CPC 664/6128]] (system disk, 720k image)
* [[Media:Vortex10.zip|VDOS 1.0 ROM]] {{DE}}
* [[Media:Vortex20.zip|VDOS 2.0 ROM]] {{DE}}
* [[Media:80307-058 BASF 6138 Mini Disk Apr83.zip|BASF 6138 Datasheet (F1-S/D/Z Floppy Disk Drive)]]

 

== Z-Drives (180K/side) ==

These are less expensive drives and were meant to be directly connected as B drive to a CPC 464 with DDI-1 or a CPC 664/6128. Since these drives ship neither with an own controller nor a [[VDOS]] ROM, they do rely fully on AMSDOS and thus only 40 tracks on one side can be accessed, resulting in the same capacity (180K/side) as the 3" drives.

=== F1-Z (5,25") ===

The F1-Z model is based on a later revision of the BASF 6138 type disk drive (81757-001), which offers more configuration options using jumpers. The drive was shipped in a "double step" configuration to use only 40 tracks, and thus the cheaper and more widely available DS DD floppy disks (48 tpi, 180K/side) could be used.

<gallery>
Image:Basf 6138 81757 001.jpg|BASF AG 6138 (81757-001) drive
Image:Basf 6138 81757 001 jumpers.jpg|BASF AG 6138 (81757-001) 40 track jumper configuration
</gallery>

=== A1-Z Upgrade Kit (5,25") ===

Vortex offered an upgrade kit consisting of a controller, a manual, a CP/M license and an utility disk which allows a F1-Z drive to be upgraded to a F1-S drive.

=== M1-Z (3,5") ===

The M1-Z model is equipped with a single 3,5" disk drive.

 

== X-Drives (720K) ==

These are the latest drives from Vortex for use with a CPC 464 with DDI-1 or a CPC 664/6128 (ie. on systems that already have a floppy disc controller); no additional controller was required anymore. Instead, a ROM module was supplied together with the drive, which provided VDOS 2.0-X. Only single-drive variants were available. The |S command (for accessing a third drive) is no longer used, the new |X command allows to swap drive A and B (same as [[X-DDOS]] from Dobbertin).

=== F1-X and F1-XRS (5,25") ===

The F1-X model is based on either a single BASF 6138 (81690-001 or 81757-001) or a single BASF 6139 5,25" disk drive. The BASF 6139 is a revisioned version which is slightly more compact (~1cm shorter), and also a number of electronical and mechanical design flaws that affected durability were corrected. The F1-XRS variant is equipped with an additional RS232-C interface.

<gallery>
File:F1-x front.jpg|F1-X
File:Vortex f1-x cpc464 backside.jpg|F1-X backside, showing IDC connector (CPC 464)
File:Vortex f1-x cpc664 backside edge.jpg|F1-X backside, showing edge connector (CPC 664)
File:F1-x inside.jpg|F1-X inside view, showing a BASF 6139 drive
File:F1x m1x manual.jpg|F1-X/M1-X manual and system utilities disk
</gallery>

=== M1-X and M1-XRS (3,5") ===

The M1-X model is based on a single NEC FD1035 type 3,5" disk drive. The M1-XRS variant is equipped with an additional RS232-C interface.

<gallery>
File:vortex-m1-x-front.png|M1-X
File:vortex-m1-x-back.png|M1-X backside
File:vortex-m1-x-connector.png|M1-X backside, showing IDC connector (CPC 464)
File:vortex-m1-x-under.png|M1-X underside
File:vortex-m1-x-inside.png|M1-X inside view, showing the drive and power
File:vortex-m1-x-drive-close.png|M1-X inside view, close-up of the drive from above
File:vortex-m1-x-drive-details.png|M1-X inside view, close-up from the backside
</gallery>

=== X(RS)-Modul ===

The X-drives for the CPC 664/6128 are connected directly to the floppy port. In order to provide [[VDOS]], the "X-Modul" (sometimes also called "VDOS module") must be connected additionally to the expansion port. This contains a ROM board that provides a VDOS 2.0-X ROM. The ROM board supplied for the CPC 464 came together with a chunky housing in which both the "X-Modul" and the DDI-1 controller were installed. All variants were also available with an additional RS232-C interface (in this case called either "XRS-Modul" or "X-Modul/RS").

<gallery>
Image:Vortex fd1 464 controller 1.jpg|XRS-Modul (CPC 464)
Image:Vortex fd1 464 controller 2.jpg|XRS-Modul with built-in DDI-1 visible (CPC 464)
Image:Xrs 464.jpg|XRS-Modul board beneath the DDI-1 (CPC 464)
Image:Vortex xrs 464 board backside.jpg|XRS-Modul board backside (CPC 464)
</gallery>
<gallery>
Image:Vortex X-Modul 6128.jpg|X-Modul (CPC 6128)
Image:Vortex X-Modul 6128 Board Front.jpg|X-Modul board (CPC 6128)
Image:Vortex X-Modul 6128 Board Backside.jpg|X-Modul board backside (CPC 6128)
</gallery>

=== RS232 I/O Ports ===

The RS232-C interface of the "XRS-Modul" was advertised to be compatible with Amstrad/Pace interfaces, but offers only one channel (so no channel B).

{| class="wikitable"
|-
! Address !! Description
|-
| 0xFADC || SIO data (R/W)
|-
| 0xFADD || SIO control (R/W)
|-
| 0xFBDC || 8253 counter 0 (R/W)
|-
| 0xFBDD || 8253 counter 1 (R/W)
|-
| 0xFBDE || 8253 counter 2 (R/W)
|-
| 0xFBDF || Mode word (W)
|}

=== Downloads ===

* [https://www.cpcwiki.eu/manuals/Vortex%20X-Laufwerke%20Manual.de.rar Benutzerhandbuch für die Vortex X-Laufwerke] {{DE}} (manual)
* [[Media:Vortex RS232-C Manual.pdf|Benutzerhandbuch für die Vortex RS232-C Schnittstelle]] {{DE}} (RS232-C user manual)
* [[Media:Manual de las Unidades Vortex.pdf|Manual de las Unidades Vortex]] {{ES}} (manual)
* [[Media:VORTF1X.DSK|Systemdiskette für Vortex X-Laufwerke]] (system disk, 720k disk image, original)
* [[Media:VTXF1XB.DSK|Systemdiskette für Vortex X-Laufwerke]] (system disk, 720k disk image, modified to boot CP/M 2.2)
* [[Media:VDOS20X.ROM|VDOS 2.0-X ROM]] {{DE}} (German VDOS 2.0-X ROM for CPC 664/6128)
* [[Media:NEC_FD1035_Floppy.pdf|NEC FD1035 Datasheet (M1-X Floppy Disk Drive)]]

 

== Software Accessories ==

=== DOSCOPY ===

DOSCOPY is a CP/M 2.2 utility which allows to read and write files from IBM and Atari ST formatted 5,25" disks. It was written in 1987 by Peter Höpfner.

<gallery>
Image:Vortex_DOSCOPY_Manual.JPG|DOSCOPY physical manual
Image:Vortex_DOSCOPY_Disk.JPG|DOSCOPY 5,25" disk
Image:Vortex_DOSCOPY_Screenshot.JPG|DOSCOPY screenshot
</gallery>

==== Downloads ====

* [[Media:DOSCOPY.DSK|DOSCOPY 1.1]] {{DE}} (Vortex 360k disk image)
* [[Media:Vortex_DOSCOPY_Benutzerhandbuch.pdf|DOSCOPY 1.1 Benutzerhandbuch]] {{DE}} (manual)

=== PARA 3.0 ===

PARA 3.0 is a CP/M 2.2 utility allowing to exchange files between the CPC and other CP/M based systems. It claims to support "reading, writing and formatting of 99% of all CP/M formats" and provides a comprehensive disk format analzer. It was written in 1987 by Peter Höpfner.

<gallery>
Image:Vortex_PARA_3.0_Manual.JPG|PARA 3.0 physical manual
Image:Vortex PARA 3.0 Disk.JPG|PARA 3.0 5,25" disk
Image:Vortex PARA 3.0 Screenshot 1.JPG|PARA 3.0 loading screen
</gallery>

==== Downloads ====

* [[Media:PARA30.DSK|PARA 3.0]] {{DE}} (Vortex 720k disk image)
* [[Media:Vortex_PARA_3.0_Benutzerhandbuch.zip|PARA 3.0 Benutzerhandbuch]] {{DE}} (manual)

=== PARA 3.0 PLUS ===

PARA 3.0 PLUS (or PARA PLUS) is an enhanced distribution of PARA 3.0 which also integrates DOSCOPY 1.3 into a single software suite.

<gallery>
Image:Para 30 plus intro.jpg|PARA 3.0+ loading screen
Image:Para 30 plus mainmenu.jpg|PARA 3.0+ main menu
Image:Para 30 plus analyzer.jpg|PARA 3.0+ format analyzer
</gallery>

==== Downloads ====

* [[Media:PARAPLUS.DSK|PARA 3.0+]] {{DE}} (Vortex 720k disk image, bootable)

=== SPARA ===

SPARA was either the predecessor or a cut-down version of PARA 3.0 and was supplied with the F1-Z drives, only supporting 40 track formats.

=== FileCopy ===
FileCopy 3.0 is a comprehensive tool to copy files with up to 16 different devices (using letters A to P), it supports the Vortex 704 KB format for 80 Track drives.

 

== 3rd Party Software ==

=== dBASE II ===

Markt & Technik released a version of Ashton-Tate dBASE II 2.41 for owners of a Vortex disk drive.

=== FutureOS ===

[[FutureOS]] has support for Vortex drives, it uses the Vortex 704 KB format for 80 Track drives.

=== House of Usher ===

Besides tape and 3 inch floppy disk release, the game [[House of Usher]] has been officially released on 5.25 inch floppy disk for the Schneider CPC with Vortex F1 floppy drive.

<gallery>
House of Usher ads.jpeg
House-of-usher-floppy-cover.png
House-of-usher-floppy-no-cover.png
</gallery>

=== Multiplan ===

Markt & Technik released a version of Microsoft Multiplan 1.06 for owners of a Vortex disk drive.

==== Downloads ====

* [[Media:MPLAN106.DSK|Microsoft Multiplan 1.06]] {{DE}} (Vortex 720k disk image, bootable CP/M Plus)

=== ParaDOS ===

[[ParaDOS]] supports Vortex X-drives and can be used as a replacement for the VDOS-X ROM. There is also a patched version called VaraDOS, which is configured to use a Vortex X-drive as drive B per default. ParaDOS does not provide a way too boot CP/M from drive B.

=== WordStar 3.0 ===

A version of MicroPro WordStar 3.0 was released by Markt & Technik for owners of a Vortex disk drive.
 

== Media Coverage ==

<gallery>
Image:Vortex Schneider CPC International 1985-09.JPG|Schneider CPC International 1985/09
Image:Vortex schneider cpc international 1986-02.JPG|Schneider CPC International 1986/02
Image:Vortex schneider cpc international 1986-04.JPG|Schneider CPC International 1986/04
Image:Vortex schneider cpc international 1986-07.JPG|Schneider CPC International 1986/07
Image:Vortex schneider cpc international 1986-08.JPG|Schneider CPC International 1986/08
</gallery>

[[Category:Peripherals]] [[Category:Manual]][[Category:DATA Storage]][[Category:Vortex Computersysteme]]

3½" & 5¼" Disk Drives

2025-08-12T07:54:22Z

Arnoldemu: /* Guides */

3½" & 5¼" Floppy Disc Drives are not the Amstrad standard yet the media and drives were far cheaper so they were common especially when used as a 2nd drive.

During the lifetime of the CPC both drives were advertised in UK magazines with the 3½" becoming much more common in it's later years due to it's use in the PC. In Germany 5¼" were advertised and well supported by Vortex for much longer. Magazines also promoted the use of these drives especially with the use of another DOS or C/PM to be able to use their full capacity.

Both 3½" & 5¼" drives were often double sided and supported double density and high density although the Amstrad could only support Double Density.

Nowadays the 5¼" drives are hard to find and are expensive, media is not made anymore and new-old-stock media is also hard to find. The 3½" drives can be found from old PC computers and there is still a read supply of new-old-stock media.

Increasingly however it is often easier to use a disc drive emulator or one of the devices that can run games from SD cards.

==Comparison of media costs==

3" disc (each) - £3.99
3.5" disc (each) - 50p
5.25" disc (each) - 50p

==Usage of Media==

To make full use of the capacity of the media you need to use another DOS or C/PM on your CPC which can support more tracks and two sides. Then you can use around 720KB per disc.

Without another DOS you can still use some of the capacity:

* 3½" discs can't be turned like 3" discs therefore with [[AMSDOS|AMSDOS]] you can use a manual side switch to choose the sides giving 2 x 178KB per side. Without the side switch it's just 178KB. Using discs like this back in the day was still useful as the media was cheaper.

* 5¼" discs can be turned over like a 3" and you can write both sides if you cut a write protect hole on the other side of each disc OR like the 3½" a manual side switch can be used.

[[image:3.5.jpg|200px|thumb|Internal 3.5" drive]]
[[image:5,25_cable.jpg|200px|thumb|advertisement for 5,25" drive cable for CPC in 1990]]

==Scavenged 3½"==

It is worth noting that 3½" scavenged from PCs will lack the drive selection and ready signal. Often these drives will need a modification to make them useable OR you can make sure the drive motor is always on.

==Common PC Formats ==

3½":

*DD = 720KB
*HD : 1,44 MB

5¼":

*DD = 360KB
*HD = 1.2MB

== Beware : HD ==

Nowaday the most common 3½" disk is HD. These can be found as used or new old stock on auction sites.

But our beloved CPC can't understand easily the concept of High Density Disk with 1,44MB available... so you have to cheat to use the media: just put some opaque duct-tape (scotch-tape, whatever...) on the HD Hole.

Tada the drive will think DD media is used and now it's usable.

PC users used to do the opposite : cut/drill a HD hole on DD disk...this worked well sometimes.

You can also modify your HD drive to behave as a DD one (but this would be permanent of course).. Check for appropriate jumpers on your drive!

== A clever choice ==

A great advantage at the time (in the 80's) was to get access to CP/M sofware library, as most of those were on such Floppy Disks.

Also, those Floppy Disks were far cheaper than the exotic 3", but... few CPC users actually own such drives.

Mostly professionnal users...The common snotling Gamer couldn't even dream of this (nor even knew it possible)... until nowadays.

As the magnetic disk is bigger...well the format is bigger too.
It is common to get 720KB disk (using the 2 sides, so 80 tracks)

== Software's issues ==

Many Modern CPC users replace their old 3" with an external 3"1/2, often adding a Disk drive A-B / B-A switcher (allowing the use of an external disk Drive as if it were the internal one = Drive A) and/or a side switcher to allow the use of a 3"1/2 disk like a 3" disk... switching manually the sides as needed by good old 3" disk drives (yet a decent software can do it).

The side switcher and A-B drive's switchers are needed only if you use old software (using [[AMSDOS|AMSDOS]]), as most of them couldn't really figure they were loaded from B drives, or had no such feature as double sided drives.

They were designed for good old 3" drive so the 720KB DD external 3"1/2 is not implemented.

But modern software designers can allow this fairly easily.

Orion Prime uses the Double side feature, enabling a simple 720KB disk with no manual side switches.

Rick Dangerous 128+ (1.1 add-on) seems to allow the game to be loaded from the B drive.

It is up to the CPC-scene to design their software to include those options, allowing more un-modded drives to be simply used as external B drives with no need to add extra buttons and cable assemblies on the Amstrad.

As modifying all the software library of the good old times seems impractical, yet modern era software have to use this.

== Software released on 3.5" disk==

* [[Orion Prime]] - This pure awsomeness even uses a full DD disk's 80 tracks with more than 700KB of Data, but you have to have a proper DD disk drive, as some older models may lack this feature...

== Software released on 5.25" disk==

* [[Data Media]] released several software titles for use with their [[Data Media Disc System]]

== Non 3" CPC disk drives ==

* [[Data Media Disc System]]
* [[Jasmin AM5D 5 "1/4 floppy drive]]
* [[KDS 5¼" Disc Drive]] ([[KDS Electronics]])
* [[F1|Vortex Disc Drives]] ([[Vortex Computersysteme|Vortex]])

*any scavenged rusty junk may be good enough nowaday, if you have a 664 or 6128...

== Connections and Wiring ==

[[DIY:Floppy_Drives]]

== Guides ==
[[Guide on how to connect a 3.5]] 
[[Guide on how to connect a 3.5" drive to a CPC6128/664]] with photos

[[Amstrad Computer User]] magazine published a two-page guide on how to connect a 5.25" drive to a CPC 464:
<gallery>
image:ACU8505-082.jpg
image:ACU8505-085.jpg
</gallery>
[[Category:Hardware]][[Category:Peripherals]][[Category:DATA Storage]]

3½" & 5¼" Disk Drives

2025-08-12T07:53:30Z

Arnoldemu:

3½" & 5¼" Floppy Disc Drives are not the Amstrad standard yet the media and drives were far cheaper so they were common especially when used as a 2nd drive.

During the lifetime of the CPC both drives were advertised in UK magazines with the 3½" becoming much more common in it's later years due to it's use in the PC. In Germany 5¼" were advertised and well supported by Vortex for much longer. Magazines also promoted the use of these drives especially with the use of another DOS or C/PM to be able to use their full capacity.

Both 3½" & 5¼" drives were often double sided and supported double density and high density although the Amstrad could only support Double Density.

Nowadays the 5¼" drives are hard to find and are expensive, media is not made anymore and new-old-stock media is also hard to find. The 3½" drives can be found from old PC computers and there is still a read supply of new-old-stock media.

Increasingly however it is often easier to use a disc drive emulator or one of the devices that can run games from SD cards.

==Comparison of media costs==

3" disc (each) - £3.99
3.5" disc (each) - 50p
5.25" disc (each) - 50p

==Usage of Media==

To make full use of the capacity of the media you need to use another DOS or C/PM on your CPC which can support more tracks and two sides. Then you can use around 720KB per disc.

Without another DOS you can still use some of the capacity:

* 3½" discs can't be turned like 3" discs therefore with [[AMSDOS|AMSDOS]] you can use a manual side switch to choose the sides giving 2 x 178KB per side. Without the side switch it's just 178KB. Using discs like this back in the day was still useful as the media was cheaper.

* 5¼" discs can be turned over like a 3" and you can write both sides if you cut a write protect hole on the other side of each disc OR like the 3½" a manual side switch can be used.

[[image:3.5.jpg|200px|thumb|Internal 3.5" drive]]
[[image:5,25_cable.jpg|200px|thumb|advertisement for 5,25" drive cable for CPC in 1990]]

==Scavenged 3½"==

It is worth noting that 3½" scavenged from PCs will lack the drive selection and ready signal. Often these drives will need a modification to make them useable OR you can make sure the drive motor is always on.

==Common PC Formats ==

3½":

*DD = 720KB
*HD : 1,44 MB

5¼":

*DD = 360KB
*HD = 1.2MB

== Beware : HD ==

Nowaday the most common 3½" disk is HD. These can be found as used or new old stock on auction sites.

But our beloved CPC can't understand easily the concept of High Density Disk with 1,44MB available... so you have to cheat to use the media: just put some opaque duct-tape (scotch-tape, whatever...) on the HD Hole.

Tada the drive will think DD media is used and now it's usable.

PC users used to do the opposite : cut/drill a HD hole on DD disk...this worked well sometimes.

You can also modify your HD drive to behave as a DD one (but this would be permanent of course).. Check for appropriate jumpers on your drive!

== A clever choice ==

A great advantage at the time (in the 80's) was to get access to CP/M sofware library, as most of those were on such Floppy Disks.

Also, those Floppy Disks were far cheaper than the exotic 3", but... few CPC users actually own such drives.

Mostly professionnal users...The common snotling Gamer couldn't even dream of this (nor even knew it possible)... until nowadays.

As the magnetic disk is bigger...well the format is bigger too.
It is common to get 720KB disk (using the 2 sides, so 80 tracks)

== Software's issues ==

Many Modern CPC users replace their old 3" with an external 3"1/2, often adding a Disk drive A-B / B-A switcher (allowing the use of an external disk Drive as if it were the internal one = Drive A) and/or a side switcher to allow the use of a 3"1/2 disk like a 3" disk... switching manually the sides as needed by good old 3" disk drives (yet a decent software can do it).

The side switcher and A-B drive's switchers are needed only if you use old software (using [[AMSDOS|AMSDOS]]), as most of them couldn't really figure they were loaded from B drives, or had no such feature as double sided drives.

They were designed for good old 3" drive so the 720KB DD external 3"1/2 is not implemented.

But modern software designers can allow this fairly easily.

Orion Prime uses the Double side feature, enabling a simple 720KB disk with no manual side switches.

Rick Dangerous 128+ (1.1 add-on) seems to allow the game to be loaded from the B drive.

It is up to the CPC-scene to design their software to include those options, allowing more un-modded drives to be simply used as external B drives with no need to add extra buttons and cable assemblies on the Amstrad.

As modifying all the software library of the good old times seems impractical, yet modern era software have to use this.

== Software released on 3.5" disk==

* [[Orion Prime]] - This pure awsomeness even uses a full DD disk's 80 tracks with more than 700KB of Data, but you have to have a proper DD disk drive, as some older models may lack this feature...

== Software released on 5.25" disk==

* [[Data Media]] released several software titles for use with their [[Data Media Disc System]]

== Non 3" CPC disk drives ==

* [[Data Media Disc System]]
* [[Jasmin AM5D 5 "1/4 floppy drive]]
* [[KDS 5¼" Disc Drive]] ([[KDS Electronics]])
* [[F1|Vortex Disc Drives]] ([[Vortex Computersysteme|Vortex]])

*any scavenged rusty junk may be good enough nowaday, if you have a 664 or 6128...

== Guides ==
[[Guide on how to connect a 3.5]] 
[[Guide on how to connect a 3.5" drive to a CPC6128/664]] with photos
[[DIY:Floppy_Drives]]

[[Amstrad Computer User]] magazine published a two-page guide on how to connect a 5.25" drive to a CPC 464:
<gallery>
image:ACU8505-082.jpg
image:ACU8505-085.jpg
</gallery>
[[Category:Hardware]][[Category:Peripherals]][[Category:DATA Storage]]

DIY:Floppy Drives

2025-08-12T07:52:20Z

Arnoldemu:

=== Preface ===

This document shows pinning list, wiring diagrams and signal descriptions found on a CPC6128.

 

=== Multi-Adaptor Cable for External Floppies / HxC emulator ===

[[Image:Floppy_Cable.png|800px|centre]]

=== Adaptor Cable for Internal Floppies / HxC emulator ===

This cable assumes that the drive has been set to DS0 / ID0 and provides a ready signal. For the HxC not a problem, just a simple jumper setting, for floppies this may involve making some mods to the drive.

[[Image:Internal_HxC_Cable.png|800px|centre]]

I've shown the cable from several views to highlight the fact that the connectors don't face the same way on the cable.

First crimp the 26way connector as shown in the diagram. Then split the first 6 wires starting from the side of the red wire. These 6 wires need to be shifted 2 cavities further over before being crimped into the 36way connector. Wire 26 goes directly to pin 34 of the floppy connector. Make sure the keyways / orientation slots of both connectors are as shown in the diagram. The cable needs no bridges, switches or anything else. When you are finished, you should have a cable looking something like this:

[[Image:HxC Adaptor.jpg|600px|centre]]

=== Signal assignment on connectors ===

==== Standard floppy connector 34pin ====
{| class="wikitable"
! Floppy connector !!colspan="2"| Signal description
|-
| 1..33 || GND || Ground
|-
| 2 || /DCD || Disk Change Detect
|-
| 4 || /DS3 || Drive select 3 (Not always supported)
|-
| 6 || /INUSE || Open collector LED driver
|-
| 8 || /IND || Index
|-
| 10 || /DS0 || Drive select 0
|-
| 12 || /DS1 || Drive select 1
|-
| 14 || /DS2 || Drive select 2
|-
| 16 || /MTRON || Motor enable
|-
| 18 || /DIR || Direction select
|-
| 20 || /STEP || Head step
|-
| 22 || /WDAT || Write data
|-
| 24 || /WGAT || Write gate
|-
| 26 || /TRK0 || Track 0
|-
| 28 || /WPT || Write protect
|-
| 30 || /RDAT || Read data
|-
| 32 || /S1 || Side select
|-
| 34 || /RDY || Ready/Disk change depending on drive configuration
|}

 

==== CPC-CD201 (internal floppy 26pin connector) ====

{| class="wikitable"
!CPC-CD201 !!colspan="2"| Signal description (numbering from Amstrads repair manual)
|-
| 1..25 || GND || Ground
|-
| 2 || /IND || Index
|-
| 4 || /DRV1 || Drive select 1
|-
| 6 || NC
|-
| 8 || /MED1 || Motor enable drive 1
|-
| 10 || /DIR || Direction select
|-
| 12 || /STEP || Head step
|-
| 14 || /WDAT || Write data
|-
| 16 || /WGAT || Write gate
|-
| 18 || /TRK0 || Track 0
|-
| 20 || /WPT || Write protect
|-
| 22 || /RDAT || Read data
|-
| 24 || /S1 || Side 1 select
|-
| 26 || /RDY || Ready (or /DSKCHG) depending on model or drive configuration
|}

 

==== CPC-PL-9 (external floppy 34pin centronics connector) ====

{| class="wikitable"
! CPC-PL-9 !!colspan="2"| Signal description external (numbering from Amstrads repair manual)
|-
| 2..34 || GND || Ground
|-
| 33 || +5V ||
|-
| 31 || +5V ||
|-
| 29 || +5V ||
|-
| 27 || /IND || Index
|-
| 25 || NC ||
|-
| 23 || /DRV1 || Drive select 1
|-
| 21 || +5V
|-
| 19 || /MED1 || Motor enable drive 1
|-
| 17 || /DIR || Direction select
|-
| 15 || /STEP || Head step
|-
| 13 || /WDAT || Write data
|-
| 11 || /WGAT || Write gate
|-
| 9 || /TRK0 || Track 0
|-
| 7 || /WPT || Write protect
|-
| 5 || /RDAT || Read data
|-
| 3 || /S1 || Side 1 select
|-
| 1 || /RDY || Ready (or /DSKCHG) depending on model or drive configuration
|}

 

=== Pinning translation between different connectors (CPC-PL-9, Centronics 36pin, Floppy connector 34pin) ===
<pre>Translation from CPC-PL-9 via Centronics 36 pin connector to floppy connector 34pin
===================================================================================
(flat cable / crimp variant view)

+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---- GND
| | | | | | | | | | | | | | | | |
Floppy connector 34pin 33 31 29 27 25 23 21 19 17 15 13 11 09 07 05 03 01 NC
Centronics 36pin 18 17 16 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01
Amstard CPC-PL-9 02 04 06 08 10 12 14 16 18 20 22 24 26 28 30 32 34 NC
**++**++**++**++**++**++**++**++**++**++**++**++**++**++**++**++**++**++
Amstard CPC-PL-9 01 03 05 07 09 11 13 15 17 19 21 23 25 27 29 31 33 NC
Centronics 36pin 36 35 34 33 32 31 30 29 28 27 26 25 24 23 22 21 20 19
Floppy connector 34pin 34 32 30 28 26 24 22 20 18 16 14 12 10 08 06 04 02 NC
| | | | | | | | | | | | | | | | | |
| | | | | | | | | | | | | | | | | +-- NC
| | | | | | | | | | | | | | | | +------ +5V
| | | | | | | | | | | | | | | +---------- +5V
| | | | | | | | | | | | | | +-------------- +5V
| | | | | | | | | | | | | +------------------ /IND
| | | | | | | | | | | | +---------------------- NC
| | | | | | | | | | | +-------------------------- /DRV1
| | | | | | | | | | +------------------------------ +5V
| | | | | | | | | +---------------------------------- /MED1
| | | | | | | | +-------------------------------------- /DIR
| | | | | | | +------------------------------------------ /STEP
| | | | | | +---------------------------------------------- /WDAT
| | | | | +-------------------------------------------------- /WGAT
| | | | +------------------------------------------------------ /TRK0
| | | +---------------------------------------------------------- /WPT
| | +-------------------------------------------------------------- /RDAT
| +------------------------------------------------------------------ /S1
+---------------------------------------------------------------------- /RDY

**/++ Flatcable signal</pre>
 

=== Wiring diagrams ===

==== External floppy connector CPC-PL-9 to standard floppy connector 34pin ====

(flat cable / crimp variant view)

Note: Disconnect wire 03-35-32 /S1 if you use a side selector switch which is connected to the floppy drive.

{| class="wikitable"
!width="25%"| PL-9 !!width="25%"| CEN !!width="25%"| PCF !!width="25%"| SIGNAL
|-
| 01 || 36 || 34 || /RDY
|-
| 02 || 18 || 33 || GND
|-
| 03 || 35 || 32 || /S1
|-
| 04 || 17 || 31 || GND
|-
| 05 || 34 || 30 || /RDAT
|-
| 06 || 16 || 29 || GND
|-
| 07 || 33 || 28 || /WPT
|-
| 08 || 15 || 27 || GND
|-
| 09 || 32 || 26 || /TRK0
|-
| 10 || 14 || 25 || GND
|-
| 11 || 31 || 24 || /WGAT
|-
| 12 || 13 || 23 || GND
|-
| 13 || 30 || 22 || /WDAT
|-
| 14 || 12 || 21 || GND
|-
| 15 || 29 || 20 || /STEP
|-
| 16 || 10 || 19 || GND
|-
| 17 || 28 || 18 || /DIR
|-
| 18 || 10 || 17 || GND
|-
| 19 || 27 || 16 || /MED1
|-
| 20 || 09 || 15 || GND
|-
| 21 || 26 || 14 || NC
|-
| 22 || 08 || 13 || GND
|-
| 23 || 25 || 12 || /DRV1
|-
| 24 || 07 || 11 || GND
|-
| 25 || 24 || 10 || NC
|-
| 26 || 06 || 09 || GND
|-
| 27 || 23 || 08 || /IND
|-
| 28 || 05 || 07 || GND
|-
| 29 || 22 || 06 || NC
|-
| 30 || 04 || 05 || GND
|-
| 31 || 21 || 04 || NC
|-
| 32 || 03 || 03 || GND
|-
| 33 || 20 || 02 || NC
|-
| 34 || 02 || 01 || GND
|-
| || 19 || || NC
|-
| || 01 || || NC
|}

 

==== Internal floppy connector CD201 to standard floppy connector 34pin ====

(flat cable / crimp variant view)

Note: Disconnect wire 24-32 /S1 if you use a side selector switch which is connected to the floppy drive.

{| class="wikitable"
!width="33%"| CD201 !!width="33%"| PCF !!width="33%"| SIGNAL
|-
| 26 || 34 || /RDY
|-
| 25 || 33 || GND
|-
| 24 || 32 || /S1
|-
| 23 || 31 || GND
|-
| 22 || 30 || /RDAT
|-
| 21 || 29 || GND
|-
| 20 || 28 || /WPT
|-
| 19 || 27 || GND
|-
| 18 || 26 || /TRK0
|-
| 17 || 25 || GND
|-
| 16 || 24 || /WGAT
|-
| 15 || 23 || GND
|-
| 14 || 22 || /WDAT
|-
| 13 || 21 || GND
|-
| 12 || 20 || /STEP
|-
| 11 || 19 || GND
|-
| 10 || 18 || /DIR
|-
| 09 || 17 || GND
|-
| 08 || 16 || /MED1
|-
| 07 || 15 || GND
|-
| 06 || 14 || NC
|-
| 05 || 13 || GND
|-
| 04 || 12 || /DRV1
|-
| || 11 || GND
|-
| || 10 || NC
|-
| 03 || 09 || GND
|-
| 02 || 08 || /IND
|-
| 01 || 07 || GND
|-
| || 06 || NC
|-
| || 05 || NC
|-
| || 04 || NC
|-
| || 03 || NC
|-
| || 02 || NC
|-
| || 01 || NC
|}

=== Issues ===

==== Floppy drive ====

* This cables work for drive which are jumpered as drive 1/DS1. This is normally the default selection on drive delivery.
* Make sure you find a drive which has the possibility to generate a ready signal instead of a disc change signal.

==== Disk issues ====

If you think about to use a HD drive, make sure to close the HD detection hole on your disk. Still, be aware that the magnetic properties of SD disk and HD disk are different (the HD ones need a stronger magnetic field). When you close the HD detection hole, the drive assumes a SD disk and applies the weaker magnetic field. As a result, HD disks used as SD tend to work but not as reliably as real DD disk (discussed on
[https://www.lemonamiga.com/forum/viewtopic.php?t=14829 Using 1.44MB HD Disks in the Amiga... - Lemon Amiga]
[https://groups.google.com/g/comp.sys.apple2/c/9mUL0vZwx6Q?pli=1 HD floppies in a DD drive.]
[https://www.vogons.org/viewtopic.php?t=46934 High density diskette in low-density drive? \ VOGONS] ).

[[Category:Hardware]][[Category:DIY]][[Category:DATA Storage]]

DIY:Floppy Drives

2025-08-12T07:51:12Z

Arnoldemu:

=== Preface ===

This document shows pinning list, wiring diagrams and signal descriptions found on a CPC6128.

 

=== Multi-Adaptor Cable for External Floppies / HxC emulator ===

[[Image:Floppy_Cable.png|800px|centre]]

=== Adaptor Cable for Internal Floppies / HxC emulator ===

This cable assumes that the drive has been set to DS0 / ID0 and provides a ready signal. For the HxC not a problem, just a simple jumper setting, for floppies this may involve making some mods to the drive.

[[Image:Internal_HxC_Cable.png|800px|centre]]

I've shown the cable from several views to highlight the fact that the connectors don't face the same way on the cable.

First crimp the 26way connector as shown in the diagram. Then split the first 6 wires starting from the side of the red wire. These 6 wires need to be shifted 2 cavities further over before being crimped into the 36way connector. Wire 26 goes directly to pin 34 of the floppy connector. Make sure the keyways / orientation slots of both connectors are as shown in the diagram. The cable needs no bridges, switches or anything else. When you are finished, you should have a cable looking something like this:

[[Image:HxC Adaptor.jpg|600px|centre]]

=== Signal assignment on connectors ===

==== Standard floppy connector 34pin ====
{| class="wikitable"
! Floppy connector !!colspan="2"| Signal description
|-
| 1..33 || GND || Ground
|-
| 2 || /DCD || Disk Change Detect
|-
| 4 || /DS3 || Drive select 3 (Not always supported)
|-
| 6 || /INUSE || Open collector LED driver
|-
| 8 || /IND || Index
|-
| 10 || /DS0 || Drive select 0
|-
| 12 || /DS1 || Drive select 1
|-
| 14 || /DS2 || Drive select 2
|-
| 16 || /MTRON || Motor enable
|-
| 18 || /DIR || Direction select
|-
| 20 || /STEP || Head step
|-
| 22 || /WDAT || Write data
|-
| 24 || /WGAT || Write gate
|-
| 26 || /TRK0 || Track 0
|-
| 28 || /WPT || Write protect
|-
| 30 || /RDAT || Read data
|-
| 32 || /S1 || Side select
|-
| 34 || /RDY || Ready/Disk change depending on drive configuration
|}

 

==== CPC-CD201 (internal floppy 26pin connector) ====

{| class="wikitable"
!CPC-CD201 !!colspan="2"| Signal description (numbering from Amstrads repair manual)
|-
| 1..25 || GND || Ground
|-
| 2 || /IND || Index
|-
| 4 || /DRV1 || Drive select 1
|-
| 6 || NC
|-
| 8 || /MED1 || Motor enable drive 1
|-
| 10 || /DIR || Direction select
|-
| 12 || /STEP || Head step
|-
| 14 || /WDAT || Write data
|-
| 16 || /WGAT || Write gate
|-
| 18 || /TRK0 || Track 0
|-
| 20 || /WPT || Write protect
|-
| 22 || /RDAT || Read data
|-
| 24 || /S1 || Side 1 select
|-
| 26 || /RDY || Ready (or /DSKCHG) depending on model or drive configuration
|}

 

==== CPC-PL-9 (external floppy 34pin centronics connector) ====

{| class="wikitable"
! CPC-PL-9 !!colspan="2"| Signal description external (numbering from Amstrads repair manual)
|-
| 2..34 || GND || Ground
|-
| 33 || +5V ||
|-
| 31 || +5V ||
|-
| 29 || +5V ||
|-
| 27 || /IND || Index
|-
| 25 || NC ||
|-
| 23 || /DRV1 || Drive select 1
|-
| 21 || +5V
|-
| 19 || /MED1 || Motor enable drive 1
|-
| 17 || /DIR || Direction select
|-
| 15 || /STEP || Head step
|-
| 13 || /WDAT || Write data
|-
| 11 || /WGAT || Write gate
|-
| 9 || /TRK0 || Track 0
|-
| 7 || /WPT || Write protect
|-
| 5 || /RDAT || Read data
|-
| 3 || /S1 || Side 1 select
|-
| 1 || /RDY || Ready (or /DSKCHG) depending on model or drive configuration
|}

 

=== Pinning translation between different connectors (CPC-PL-9, Centronics 36pin, Floppy connector 34pin) ===
<pre>Translation from CPC-PL-9 via Centronics 36 pin connector to floppy connector 34pin
===================================================================================
(flat cable / crimp variant view)

+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---- GND
| | | | | | | | | | | | | | | | |
Floppy connector 34pin 33 31 29 27 25 23 21 19 17 15 13 11 09 07 05 03 01 NC
Centronics 36pin 18 17 16 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01
Amstard CPC-PL-9 02 04 06 08 10 12 14 16 18 20 22 24 26 28 30 32 34 NC
**++**++**++**++**++**++**++**++**++**++**++**++**++**++**++**++**++**++
Amstard CPC-PL-9 01 03 05 07 09 11 13 15 17 19 21 23 25 27 29 31 33 NC
Centronics 36pin 36 35 34 33 32 31 30 29 28 27 26 25 24 23 22 21 20 19
Floppy connector 34pin 34 32 30 28 26 24 22 20 18 16 14 12 10 08 06 04 02 NC
| | | | | | | | | | | | | | | | | |
| | | | | | | | | | | | | | | | | +-- NC
| | | | | | | | | | | | | | | | +------ +5V
| | | | | | | | | | | | | | | +---------- +5V
| | | | | | | | | | | | | | +-------------- +5V
| | | | | | | | | | | | | +------------------ /IND
| | | | | | | | | | | | +---------------------- NC
| | | | | | | | | | | +-------------------------- /DRV1
| | | | | | | | | | +------------------------------ +5V
| | | | | | | | | +---------------------------------- /MED1
| | | | | | | | +-------------------------------------- /DIR
| | | | | | | +------------------------------------------ /STEP
| | | | | | +---------------------------------------------- /WDAT
| | | | | +-------------------------------------------------- /WGAT
| | | | +------------------------------------------------------ /TRK0
| | | +---------------------------------------------------------- /WPT
| | +-------------------------------------------------------------- /RDAT
| +------------------------------------------------------------------ /S1
+---------------------------------------------------------------------- /RDY

**/++ Flatcable signal</pre>
 

=== Wiring diagrams ===

==== External floppy connector CPC-PL-9 to standard floppy connector 34pin ====

(flat cable / crimp variant view)

Note: Disconnect wire 03-35-32 /S1 if you use a side selector switch which is connected to the floppy drive.

{| class="wikitable"
!width="25%"| PL-9 !!width="25%"| CEN !!width="25%"| PCF !!width="25%"| SIGNAL
|-
| 01 || 36 || 34 || /RDY
|-
| 02 || 18 || 33 || GND
|-
| 03 || 35 || 32 || /S1
|-
| 04 || 17 || 31 || GND
|-
| 05 || 34 || 30 || /RDAT
|-
| 06 || 16 || 29 || GND
|-
| 07 || 33 || 28 || /WPT
|-
| 08 || 15 || 27 || GND
|-
| 09 || 32 || 26 || /TRK0
|-
| 10 || 14 || 25 || GND
|-
| 11 || 31 || 24 || /WGAT
|-
| 12 || 13 || 23 || GND
|-
| 13 || 30 || 22 || /WDAT
|-
| 14 || 12 || 21 || GND
|-
| 15 || 29 || 20 || /STEP
|-
| 16 || 10 || 19 || GND
|-
| 17 || 28 || 18 || /DIR
|-
| 18 || 10 || 17 || GND
|-
| 19 || 27 || 16 || /MED1
|-
| 20 || 09 || 15 || GND
|-
| 21 || 26 || 14 || NC
|-
| 22 || 08 || 13 || GND
|-
| 23 || 25 || 12 || /DRV1
|-
| 24 || 07 || 11 || GND
|-
| 25 || 24 || 10 || NC
|-
| 26 || 06 || 09 || GND
|-
| 27 || 23 || 08 || /IND
|-
| 28 || 05 || 07 || GND
|-
| 29 || 22 || 06 || NC
|-
| 30 || 04 || 05 || GND
|-
| 31 || 21 || 04 || NC
|-
| 32 || 03 || 03 || GND
|-
| 33 || 20 || 02 || NC
|-
| 34 || 02 || 01 || GND
|-
| || 19 || || NC
|-
| || 01 || || NC
|}

 

==== Internal floppy connector CD201 to standard floppy connector 34pin ====

(flat cable / crimp variant view)

Note: Disconnect wire 24-32 /S1 if you use a side selector switch which is connected to the floppy drive.

{| class="wikitable"
!width="33%"| CD201 !!width="33%"| PCF !!width="33%"| SIGNAL
|-
| 26 || 34 || /RDY
|-
| 25 || 33 || GND
|-
| 24 || 32 || /S1
|-
| 23 || 31 || GND
|-
| 22 || 30 || /RDAT
|-
| 21 || 29 || GND
|-
| 20 || 28 || /WPT
|-
| 19 || 27 || GND
|-
| 18 || 26 || /TRK0
|-
| 17 || 25 || GND
|-
| 16 || 24 || /WGAT
|-
| 15 || 23 || GND
|-
| 14 || 22 || /WDAT
|-
| 13 || 21 || GND
|-
| 12 || 20 || /STEP
|-
| 11 || 19 || GND
|-
| 10 || 18 || /DIR
|-
| 09 || 17 || GND
|-
| 08 || 16 || /MED1
|-
| 07 || 15 || GND
|-
| 06 || 14 || NC
|-
| 05 || 13 || GND
|-
| 04 || 12 || /DRV1
|-
| || 11 || GND
|-
| || 10 || NC
|-
| 03 || 09 || GND
|-
| 02 || 08 || /IND
|-
| 01 || 07 || GND
|-
| || 06 || NC
|-
| || 05 || NC
|-
| || 04 || NC
|-
| || 03 || NC
|-
| || 02 || NC
|-
| || 01 || NC
|}

=== Issues ===

==== Floppy drive ====

* This cables work for drive which are jumpered as drive 1/DS1. This is normally the default selection on drive delivery.
* Make sure you find a drive which has the possibility to generate a ready signal instead of a disc change signal.

==== Disk issues ====

If you think about to use a HD drive, make sure to close the HD detection hole on your disk. Still, be aware that the magnetic properties of SD disk and HD disk are different (the HD ones need a stronger magnetic field). When you close the HD detection hole, the drive assumes a SD disk and applies the weaker magnetic field. As a result, HD disks used as SD tend to work but not as reliably as real DD disk (discussed on
[https://www.lemonamiga.com/forum/viewtopic.php?t=14829 Using 1.44MB HD Disks in the Amiga... - Lemon Amiga]
[https://groups.google.com/g/comp.sys.apple2/c/9mUL0vZwx6Q?pli=1 HD floppies in a DD drive.]
[https://www.vogons.org/viewtopic.php?t=46934 High density diskette in low-density drive? \ VOGONS] ).

[[Category:DIY]][[Category::Hardware]][[Category:DATA Storage]]

2025-07-14T17:14:16Z

Arnoldemu:

<pre>
org 09c40h

sub_9c40h:
call 0bd19h ;; mc wait flyback
di
ld bc,0f40eh ;; we want to select AY register 14
out (c),c
ld b,0f6h
in a,(c)
and 030h
ld c,a
or 0c0h ;; AY control select register.
out (c),a
out (c),a ;; BUG. Should be out (c),c to be compatible with Plus.
inc b
ld a,092h
out (c),a
push bc
ld bc,0f649h ;; AY control read from register and select keyboard line 9 (joystick)
out (c),c
out (c),c ;; BUG? No need to do this twice.
ld b,0f4h

;; loop reading joystick until input seen or timeout

ld hl,0fa66h ;; timeout is 0-FA66 because it counts up from this starting point.
;; timeout is 59A loops.
l9c68:
in a,(c)
cp 0fdh ;; 11111101. Bits are '1' if 'no press', but '0' if pressed. checking joy 0 down.
jr z,l9c79
inc l
jr nz,l9c68
inc h
jr nz,l9c68

;; timeout. not detected
ld hl,0ffffh
jr l9cbdh
l9c79:
;; detected.
ld de,00420h
add hl,de
l9cbd:
ld (0a410h),hl ;; detected 'position' or 'ffff' for not detected
pop bc
ld a,082h
out (c),a
dec b
out (c),c ;; Set AY control inactive.
ei
ret

sub_9c8ah:
call sub_9da6h ;; screen to buffer

call sub_9ce4h

call sub_9db2h ;; buffer to screen
ret

sub_9c94:
ld a,h
ld c,l
ld b,010h ;; 16 bits.
ld hl,00000h
l9cdbh:
rl c
rla
adc hl,hl
sbc hl,de
jr nc,l9ce5h
add hl,de
l9ce5h:
ccf
djnz l9cdbh
rl c
rla
ld h,a
ld l,c
ret

sub_9caeh:
ld a,l
ld c,h
ld b,010h ;; 16 bits
ld hl,00000h
l9cf5h:
srl c
rra
jr nc,l9cfbh
add hl,de
l9cfbh:
ex de,hl
add hl,hl
ex de,hl
djnz l9cf5h
ret

sub_9cc1h:
call sub_9c40h ;; detect
ld a,0ffh
cp h
ret z

;; detected.
ld de,00002h
call sub_9c94h
ld de,00064h
call sub_9caeh
ld de,00084h
call sub_9c94h
ex de,hl
ld hl,0018fh
sbc hl,de
ld (0a410h),hl
ret

sub_9ce4:
ld a,000h
ld bc,01a1ah
call 0bc32h ;; scr set ink
call 0bc14h ;; scr clear
ld a,001h
call 0bbdeh ;; gra set pen
call sub_9cc1h ;; get position
ld a,0ffh
cp h
ret z
ld de,0000ah
and a
sbc hl,de

;; BUG? This is jumping just after 0x021 of LD HL and then executing two nops before LD DE,0000h
;;jr nc,$+2
jr nc,l9d06
ld hl,00000h
l9d06:
ld de,00000h
call 0bbc0h ;; gra move absolute
ld a,001h
ld bc,01a1ah
call 0bc32h ;; scr set ink
ld a,000h
ld bc,00000h
call 0bc32h ;; scr set ink
ld b,00ah
l9d1e:
call 0bd19h ;; mc wait flyback

;; BUG? this is jumping back to the 0x0a in LD B,0ah
;; djnz $-4
djnz l9d1e

ld b,020h ;; number of lines
l9d65h:
push bc
call sub_9d35h ;; draw lines
call sub_9c40h ;;detect
pop bc
ld a,0ffh
cp h
jr nz,l9d91h
djnz l9d65h
ret

sub_9d35h:
ld bc,(0a418h)
l9d79h:
push bc
ld de,00000h
ld hl,00014h
call 0bbf9h ;; gra line relative
ld de,(0a416h)
ld hl,0ffech
call 0bbc3h ;; gra move relative
pop bc
djnz l9d79h
ret
l9d91h:
ld de,0ffech ;; -20
ld hl,00000h
call 0bbc3h ;; gra move relative
l9d9ah:
ld a,000h
call 0bbdeh ;; gra set pen
call sub_09d35h ;; lines
ld a,001h
call 0bbdeh ;; gra set pen
ld de,0ffech ;; -20
ld hl,00000h
call 0bbc3h ;; gra move relative
ld bc,(0a420h)
l9db4h:
push bc
call sub_9cc1h ;; get position
ld a,0ffh
cp h
jr nz,sub_9d9ah
ld de,00000h
ld hl,00014h
call 0bbf9h ;; gra line relative
ld de,(0a416h)
ld hl,0ffech ;; -20
call 0bbc3h ;; gra move relative
pop bc
djnz l9db4h
ld hl,0ffffh
ld (0a410h),hl
ret
sub_9d9ah:
pop bc
ld (0a410h),hl
call 0bbc6h ;; gra ask cursor
ld (0a412h),de
ret

;; screen to buffer
;; c000->5bfe length 3fd0
sub_9da6h:
ld bc,03fd0h
ld hl,0c000h
ld de,05bfeh
ldir
ret

;; buffer to screen
;; 5bfe->c000 length 3fd0

sub_9db2h:
ld bc,03fd0h
ld hl,05bfeh
ld de,0c000h
ldir
ret

sub_9dbeh:
push hl
push de
call sub_09e08h
ld (0a414h),hl
ld de,05398h
ld b,004h
l9e0bh:
push bc
ld hl,(0a414h)
ld c,b
ld b,000h
inc hl
and a
sbc hl,bc
ld b,00bh
l9e18h:
ld a,(hl)
ld (de),a
inc de
call 0bc29h ;; scr prev line
djnz l9e18h
pop bc
djnz l9e0bh
pop de
pop hl
ret

sub_9de6h:
push hl
push de
ld de,05398h
ld b,004h
l9e2dh:
push bc
ld hl,(0a414h)
ld c,b
ld b,000h
inc hl
and a
sbc hl,bc
ld b,00bh
l9e3ah:
ld a,(de)
ld (hl),a
inc de
call 0bc29h ;; scr prev line
djnz l9e3ah
pop bc
djnz l9e2dh
pop de
pop hl
ret

sub_9e08h:
push de
ld de,00002h
call sub_9c94h
pop de
push hl
ex de,hl
ld de,(0a416h)
call sub_9c94h
ex de,hl
pop hl
call 0bc1dh ;; scr dot position
ret

sub_9e1fh:
call sub_9c8ah
ld hl,(0a418h)
ld (0a420h),hl
ld hl,(0a410h)
ld a,0ffh
cp h
ret z
ld (0a41ch),hl
ld de,(0a412h)
ld (0a41ah),de
l9e7ah:
ld de,0000ah
and a
sbc hl,de
jr nc,l9e85h
ld hl,00000h
l9e85h:
push hl
ld hl,(0a412h)
add hl,de
ex de,hl
pop hl
call sub_09dbeh
call 0bbc0h ;; gra move absolute
sub_9e52h:
call sub_09ed2h
call sub_09de6h
ld hl,(0a410h)
ld a,0ffh
cp h
jr nz,l9ea9h
ld a,02fh
call 0bb1eh ;; km test key
ret z
jp sub_9e52h

l9ea9h:
call sub_09eb7h
ld a,02fh
call 0bb1eh ;; km test key
ret z
ld hl,(0a41ch)
ld de,(0a41ah)
call 0bbc0h ;; gra move absolute
ld hl,(0a410h)
ld de,(0a412h)
ld a,(0a41eh)
call 0bbdeh ;; gra set pen
ld (0a41ch),hl
ld (0a41ah),de
call 0bbf6h ;; gra line absolute
ld hl,(0a410h)
jr l9e7ah

sub_09e98h:
ld de,0ffech
ld hl,00000h
call 0bbc3h ;; gra move relative
ld a,001h
call 0bbdeh ;; gra set pen
call sub_09d35h
ld a,000h
call 0bbdeh ;; gra set pen
call sub_9cc1h ;; get position
ld a,0ffh
cp h
ret nz
pop de
ret

sub_9eb7h:
ld hl,(0a41ah)
ld de,(0a412h)
and a
sbc hl,de
ret z
jp p,l9ecbh

ld hl,l9f15h
jp l09eceh

l9ecbh:
ld hl,sub_9ed2h
l9eceh:
ld (l9e52h+1),hl
ret

sub_9ed2h:
call sub_9e98h

ld de,0ffech
ld hl,00000h
call 0bbc3h ;; gra move relative
ld bc,(0a420h)
push bc
ld de,00000h
ld hl,00014h
call 0bbf9h ;; gra line relative
call sub_9cc1h
ld a,0ffh
cp h
jp nz,sub_9efeh
sub_9ef5h:
ld hl,(0a422h)
ld (0a410h),hl
jp sub_9d9ah

sub_9efeh:
ld (0a422h),hl
ld de,(0a416h)
ld hl,0ffech
call 0bbc3h ;; gra move relative
pop bc
djnz l9f22h
ld hl,0ffffh
ld (0a410h),hl
ret

sub_9f82h:
call sub_9e98h
ld bc,(0a420h)
l9f5ch:
push bc
ld de,00000h
ld hl,00014h
call 0bbf9h ;; gra line relative
call sub_9cc1h
ld a,0ffh
cp h
jp z,sub_9ef5h

ld (0a422h),hl
ld de,(0a416h)
ld hl,00000h
and a
sbc hl,de
push hl
pop de
ld hl,0ffech
call 0bbc3h ;; gra move relative
pop bc
djnz l9f5ch
ld hl,00000h
ld de,00014h
call 0bbc3h ;; gra move relative
jp l9f0eh
db 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
db 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
db 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
db 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
db 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
db 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
db 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0

;; screen dump to printer.
sub_0a028h:
ld a,013h
ld (0a124h),a
ld a,00eh
ld (0a0e2h),a
ld a,(0a133h)
bit 1,a
jr z,la083h
ld a,000h
ld (0a124h),a
ld a,007h
ld (0a0e2h),a
la083h:
call 0bd28h ;; mc reset printer

ld de,00000h
ld hl,00000h
ld (0a12dh),de
sub_a050h:
ld a,000h
ld (0a12ch),a ;; accumulated pixels.

ld de,(0a12dh)
call sub_a10dh ;; store current graphics position

call 0bbf0h ;; gra test absolute
ld de,00001h
call sub_a11dh ;; get pixel
ld de,00002h
call sub_a11dh ;; get pixel
ld de,00004h
call sub_a11dh ;; get pixel
ld de,00008h
call sub_a11dh ;; get pixel
ld de,00010h
call sub_a11dh ;; get pixel
ld de,00020h
call sub_a11dh ;; get pixel
ld de,00040h
call sub_a0ffh ;; get pixel
la0c9h:
call 0bd2eh ;; mc busy printer
jr c,la0c9h
call 0bd28h ;; mc reset printer
ld a,01bh ;; ESC
call 0bd2bh ;; mc print char
ld a,04bh ;; K
call 0bd2bh ;; mc print char
ld a,000h ;; number of columns low byte
call 0bd2bh ;; mc print char
ld a,(0a133h)
bit 0,a
jr z,la0b4h
ld a,002h ;; number of columns high byte?
call 0bd2bh ;; mc print char

ld a,(0a12ch) ;; pixel data
call 0bd2bh ;; mc print char
jr la0f9h
la0b4h:
ld a,001h ;; number of columns high byte?
call 0bd2bh ;; mc print char
la0f9h:
ld a,(0a12ch) ;; pixel data
call 0bd2bh ;; mc print char

call sub_a115h
inc hl
inc hl
call sub_a10dh
ld a,h
cp 001h
jp nz,sub_a050h
ld a,l
cp 090h
jp nz,sub_a050h
ld a,00ah ;; next line
call 0bd2bh ;; mc print char

ld a,02fh ;; 47 - space
call 0bb1eh ;; km test key
ret nz
ld hl,(0a12dh)
ld de,0000eh
add hl,de
ld (0a12dh),hl
ld hl,00000h
call sub_a10dh
ld de,(0a12dh)
ld a,d
cp 002h
jp nz,sub_a050h
ld a,e
cp 084h
jp nz,sub_a050h
ret

;; accumulate pixels
sub_a0ffh:
ld b,a

call 0bb99h ;; txt get paper
cp b ;; was the colour read the same as the paper?
ret z

;; any pixel which is not the same as the paper will be considered foreground
;; and the printer will draw a dot. Any pixel the same as the paper will
;; be considered background and no dot is drawn by the printer.

;; pixel is set to foreground. accumulate it into the pixel data so far
ld hl,(0a12ch)
add hl,de
ld (0a12ch),hl
ret

sub_a10dh:
ld (0a12fh),hl
ld (0a131h),de
ret

sub_a115h:
ld hl,(0a12fh)
ld de,(0a131h)
ret

sub_a11dh:
call sub_a0ffh ;; accumulate a pixel for printing.
call sub_a115h ;; get current X/Y graphics position
inc de ;; increment X to next pixel accross screen.
inc de
call sub_a10dh ;; set current X/Y graphics position
call 0bbf0h ;; gra test absolute
ret

la10ch:
nop
add a,h
ld (bc),a
nop
nop
ld c,000h
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
nop
sub_a154h:
call 0bc11h ;; scr get mode
cp 000h
jr nz,la19dh
ld b,004h
la19dh:
cp 001h
jr nz,la1a3h
ld b,002h
la1a3h:
cp 002h
jr nz,la1a9h
ld b,001h
la1a9h:
ld a,b
la1aah:
ld (0a254h),a
call 0bbc6h ;; gra ask cursor
ld (0a250h),hl
ld (0a250h+2),de
la1b7h:
call 0bb99h ;; txt get paper
ld (0a1f9h),a
ld bc,00000h
ld (0a24ch),bc
ld (0a24eh),bc
call sub_a210
ld a,02fh ;; 47 - space
call 0bb1eh ;; km test key
ret nz
ld hl,(0a24eh)
inc hl
inc hl
ld a,004h
cp h
jr nz,la1deh
ld hl,00000h
la1deh:
ld (0a24eh),hl
ld bc,05398h
add hl,bc
ld (0a1aah),hl
ld de,(055e0h)
ld hl,(0a24eh)
sub_a1efh:
ld bc,057e4h
add hl,bc
ld (0a1b7h),hl
ld hl,(05a2ch)
la1f9h:
ld (la257h),hl
ld (0a255h),de
ld bc,00000h
ld a,(0a254h)
ld c,a
ex de,hl
add hl,bc
ex de,hl
call sub_a1efh
and a
ex de,hl
sbc hl,bc
ex de,hl
call sub_a1efh
inc hl
inc hl
call sub_a1efh
dec hl
dec hl
call sub_a1efh
ld hl,(0a24eh)
ld de,(0a24ch)
inc hl
inc hl
and a
sbc hl,de
ret z
jp la18bh
sub_a1efh:
push de
push hl
push bc
call 0bbf0h ;; gra test absolute
pop bc
pop hl
pop de
cp 000h
jr nz,la248h
ld (0a250h),hl
ld (0a250h+2),de
push bc
call sub_0a210h
pop bc
la248h:
ld hl,(0a257h)
ld de,(0a255h)
ret
sub_a210:
ld hl,(0a250h)
ld de,(0a250h+2)
call 0bbeah ;; gra plot absolute
ld hl,(0a24ch)
inc hl
inc hl
ld a,004h
cp h
jr nz,la267h
ld hl,00000h
la267h:
ld (0a24ch),hl
ld bc,05398h
add hl,bc
ld de,(0a250h+2)
ld (0a237h),hl
ld (05648h),de
ld hl,(0a24ch)
ld bc,057e4h
add hl,bc
ld de,(0a250h)
ld (0a249),hl
ld (05a94h),de
ret
la24ch:
or b
ld (bc),a
ld c,b
ld (bc),a
cp (hl)
nop
jr nz,la295h
inc b
jr nz,$+3
cp h

end
</pre>

[[Category:Source code]]