Changes
/* BASIC tokens */ typo
[[Category:Cpctech.org]]
'''''This artikel 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 works work (are!) similar from the BASIC command line and invokes a 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>
...
MSB PARAMn
IX+2 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 hand-overedgiven, e.g. "x" = 2 RET NZ ; if no > failure and returnnot exactly x parameters then do not execute RSX. LD L,(IX+20) LD H,(IX+31) ; HL = value of last parameter LD E,(IX+42) LD D,(IX+53) ; 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 16-bit value is an address of a "the string descriptor which point to a 3 byte block". The first byte of the string description or 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 param 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.
<br> <br>
== Entering 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 programm program line number)
: - no space (or 'under' as it is common today) between variable names are allowed
: - BASIC keywords can't be used
: - 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.
<br>
== 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).
== Structure of a BASIC program ==
<br> 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 ==
|-
| &1d
| 16-bit BASIC program line memory address pointer(see notes)
|-
| &1e
| INPUT
|-
| &a4
| KEY
|-
|-
| &b5
| ON SQ
|-
| &b6
<br> Notes:
{| border="1"
|}
{| border="1"
|}
{| border="1"
<br> 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.
<br> This table list the BASIC tokens with a &ff prefix byte.
<br> NOTES:
== Floating Point data definition ==
To obtain the signed exponent, you must subtract 128 from the stored exponent. The minimum exponent is 0 and this describes a number of 2^-127. The maximum exponent is 255 and this describes a number of 2^128.
=== 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 ===
== 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.
Where "a" should be replaced with the name of the variable.
<br>
== BASIC integer variables ==
#**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| ]]