Overview

CPC Basic is an integrated environment for developing programs for Amstrad CPC 464, 664 and 6128. Works on Windows and other operating systems that allow compatibility with Windows applications, such as Linux with Mono or Mac OS with Wine.

CPC Basic function is to allow input and editing a program and compile it to to generate the necessary machine code and run it on a Amstrad CPC computer or an emulator.

Programs are written in Basic language based on Locomotive Basic with a number of differences required because it is a compiler and optimize the speed of code produced.

CPC Basic usage is free and freely distributable, grateful for the mention of its author.

Description of the environment

The display comprises three areas:

• The top allows you to set compilation options for generating code from the program entered.
• The main part is the output window, where they will show the sentences and lines introduced, the results they produce, error messages, etc.. You can scroll the contents of this window to view its contents before clicking on it and using the arrow keys or page up and page down.
• The bottom is the input window, where you enter editing commands and program lines.

The CPC Basic application window is resizable and division between the input and output windows can be moved to accommodate the user's taste.

To exit the environment is necessary to close the program window by clicking on the cross at the top right.

Compilation options

At the top of the CPC Basic window is:

• CPC type list: Amstrad CPC model (464, 664 or 6128) for which to generate the code. Depending on the model chosen there are some commands and functions that are not supported.
• Output list: type of output generated by the compilation process.
• Real numbers value: number of real values to be used by the program.
• Programs button: opens the file browser to the default storage directory for Basic programs.
• Output button: opens the file browser for file storage directory resulting from the compilation.

Output types

• Binary file: produces a file with the machine code for the Basic program.
• Assembler code: produces a file with Z80 assembler code for the Basic program.This file may modify and assemble to produce the binary code needed to run on an Amstrad CPC or emulator.
• ccz80 code: produces a file with code ccz80 for the Basic program. This file can be modified and compiled with ccz80 to produce the binary code needed to run on an Amstrad CPC or emulator.
• CDT file: produces a tape image CDT file that includes a file OUTPUT.BIN with machine code for the Basic program. CDT file can be used in an emulator and run the file included with RUN "".
• DSK file: produces a disk image file DSK that includes a file OUTPUT.BIN with machine code for the Basic program. DSK file can be used in an emulator and run the file included with RUN"OUTPUT.BIN".
• Snap file: produces a memory image snap file that includes machine code for the Basic program. This file SNA can be used in an emulator and run the program by pressing the Enter key after loading the snap file.
• Run in Emulator: same functionality as the output Snap file, and also runs the emulator image already loaded snap. The snap image is not stored on disk. To continue using Basic CPC to exit the emulator.

The generated files are in the Output subdirectory under the directory where you installed CPC Basic. When a file is generated after compilation, deleted files created in previous compilations.

Using the input window

In this window you can enter the editing commands and lines of the program and make the amendments thereto.

You can enter a single line or several separated by Control + Enter. Pressing Enter will interpret all existing lines in the input window. Pressing the Escape key cancels the entire contents of the input window. You can also paste in this window clipboard content that was copied previously, with the corresponding option from the context menu displayed by pressing the right mouse button or key combination Ctrl + V or Ctrl + Ins, and if pressing Enter will be interpreted as if it had been typed manually pasted content. This feature can be useful for example to insert lines or hand lines that exist in the output window or full program listings.

Each line entered can contain one or more editing commands, separated by a colon or a program line, starting by a line number.

Editing commands supported are:

• AUTO: same syntax and functionality in Locomotive Basic.
• CAT: same syntax and functionality in Locomotive Basic.
• CLS: same syntax and functionality in Locomotive Basic, but not specifying a channel.
• DELETE: same syntax and functionality in Locomotive Basic.
• LIST: same syntax and functionality in Locomotive Basic, but not specifying a channel.
• EDIT: same syntax and functionality in Locomotive Basic.
• LOAD: same functionality as Locomotive Basic, but only supports loading of Basic files, with the syntax LOAD "filename". You can specify a path to the file name, if not specified, the file is loaded from the Programs subdirectory within the installation directory of CPC Basic. If specified as a filename an empty string will open the file dialog box to select it.
• MERGE: same syntax and functionality in Locomotive Basic. You can specify a path to the file name, if not specified, the file is loaded from the Programs subdirectory within the installation directory of CPC Basic. If specified as a filename an empty string will open the file dialog box to select it.
• MODE: same syntax and functionality in Locomotive Basic.
• NEW: same syntax and functionality in Locomotive Basic.
• RENUM: same syntax and functionality in Locomotive Basic.
• RUN: compile the program currently in memory and produces the file for the output type is selected. The resulting file is stored in the Output subdirectory within the installation directory of CPC Basic.
• SAVE: same functionality as Locomotive Basic, but only supports recording Basic files, with syntax SAVE "filename". You can specify a path to the file name, if not specified the file is written in the subdirectory Programs within the installation directory of CPC Basic. If specified as a filename an empty string will open the file dialog to select the directory and name.

Lines introduced in the input window will be added to the program. If you enter a line with a number that will replace existed that was stored. If you enter only a line number line is removed from the program if they exist.

Differences Locomotive Basic

There is great support in the syntax of the commands, but there are some differences due to CPC Basic is a compiler and not an interpreter and also because we have sought a code generation as quickly as possible. The main differences, and other minors can be found, are:

• In CPC Basic unchecked errors during program execution. If an error occurs the program still works but possibly incorrectly.
• Any numeric expression that produces a negative value will be transformed to equivalent positive value in two's complement, which is equivalent to adding 256 if assigned to a variable byte and 65536 if assigned to a variable word, the negative value produced. It is advisable to avoid an expression produces a negative value unless it is found that the equivalent value in two's complement is valid for the operation to be used.
• An expression that produces a value exceeding the limit of the variable that stores will change to that value subtracted 256 if assigned to a variable byte and 65536 if assigned to a variable word.
• Also keep in mind these concepts in the loop downward to end in 0 (eg FOR n%=10 TO 0 step -1, where n% never can take the value -1 indicating the end of the loop, since after treat the value 0, would decrease to 1 in 255) or upward to end in the upper limit for a variable (eg FOR n!=60000 to 65535, where n! can never take the value 65536 would indicate the end of the loop because after trying value 65535, increasing to 1 would be at 0), or increases or decreases of variables to produce results under 0 (for example, a%=10:a%=a%-11:IF a% = -1 THEN PRINT "Negative" does not give the expected result, since 10 - 11 produces -1, which becomes 255, so that the condition is not true) or above the upper limit of the variable (for example a!=60000:a!=a!+10000:IF a!=70000 THEN PRINT "OK", which produces 60000+10000=70000, which becomes 70000 - 65536 = 4464).
• As mentioned above, the suffix % is used to specify the type byte, and the suffix ! to specify the kind word to a variable identifier, user-defined function, function argument, and so on.
• The default type for variables and identifiers in Basic CPC's word is not used or DEFSTR DEFBYTE for changing, while in Locomotive Basic the default type is real.
• In CPC Basic are statements DEFWORD and DEFBYTE replacing DEFREAL and DEFINT in Locomotive BASIC, with the same syntax and functionality for byte and word identifiers respectively.
• Largely because CPC Basic produces machine code rather than interpreted, because it does not check for errors that may occur and because the data types used vary with respect to Locomotive Basic does not support the following commands in lines program: AUTO, CHAIN, CHAIN MERGE, CLEAR, CONT, DEFINT, DEFREAL, DEG, DELETE, EDIT, ERASE, ERROR, LIST, MEMORY, MERGE, NEW, ON BREAK CONT, ON BREAK GOSUB, ON BREAK STOP, ON ERROR GOTO, RAD, RENUM, RESUME, RESUME NEXT, RUN, WIDTH. The compiler recognizes these keywords, but fails when used in a program.
• For the same reasons stated in the previous point, CPC Basic does not support the following functions: ATN, CINT, COS, CREAL, DERR, ERL, ERR, EXP, FIX, FRE, INT, LOG, LOG10, PI, ROUND, SIN, TAN, UNT. The compiler recognizes these keywords, but fails when used in an expression.
• Statements DATA, DEF FN, DEFBYTE, DEFSTR, DEFWORD, DIM, SYMBOL AFTER, TROFF, TRON act anywhere in the program where used, regardless of whether the program flow passes through them or not to perform this action or definition concerned. For example IF a=0 THEN DEF FNf(x, y)=x+y defines the function f regardless of the value of the variable a; a=0:WHILE a> 0:TRON:WEND active monitoring of the program although the flow does not come within the loop; END:DIM n$(20) declares the table n$ although the program ends in the previous statement.
• The string variables are longer than 255 characters. If content is going to be shorter and you want to use less memory space can be used to specify the DIM statement, the syntax DIM variable*length. For example, to define the length of the variable a$ to 10 characters would be indicated by DIM a$*10. The same can be applied to tables of string where each element will default to 255 characters, you can use the DIM statement with the syntax DIM table(index)*length. For example, to define the length of all elements of the table of elements 16 table$ to 25 would be indicated by DIM table$(15)*25.
• The indexes specified in the declaration of a table must be constant expressions, you can not use variables in them. For example DIM a (10* 3) is correct, but it is not DIM a(10*n).
• Not allowed redefinciones tables, may be declared only once.
• The operators / and \ are equivalent because the values with which they operate are always integers.
• The step expression of a FOR loop is always interpreted positive if not constant, for example s=-2:FOR i = 10 TO 1 STEP s not work as expected, but it will FOR i=10 to 1 step -2.
• The RND function returns a value from 0 to 65535. To obtain a value in the range n to m must use the expression RND MOD (m - n + 1) + n. For example, to obtain a random value between 7 and 10 would RND MOD 4+7; for a random value between 1 and 5 would RND MOD 5+1, for a random value between 0 and 20 would RND MOD 21.
• The TIME function returns a value in the range 0 to 65535, returning to zero when it reaches the limit approximately every 218 seconds.
• Expressions with relational operators conditions (low, less than or equal, greater, greater or equal, equal and different) and functions with boolean result (eg EOF) return a value 0 to indicate false and value 65535 to indicate true that can be interpreted as -1 to perform other arithmetic operations.
• Functions ABS and SGN interpret values greater than 32767 as negative.
• The length range for the function BIN$ is 1 to 4.
• The length range for HEX$ function is 1 to 16.
• The template can be specified for the function DEC$ and in PRINT USING clause has a different syntax than that used in Locomotive Basic. You can use the following symbols: number sign (#) specifies a digit is significant or a space if it is not; asterisk (*) specifies a digit if significant or an asterisk if not, zero (0) always specifies digit, dot (.) and comma (,) respectively specified dot or comma if there is a significant digit before them, any other character specifies the same character. For example DEC$(123,"#.##0") produced " 123" (two spaces at the beginning), DEC$(123,"00000") produces "00123", DEC$(123,'***** EUR") produces "**123 EUR".
• The USING clause can only apply to numeric values, no string, and a template can only specify the format for a numeric expression, although there may be several numerical expressions that apply formatting, such as Locomotive Basic.
• The STR$ function does not generate the space reserved for the sign if the number is positive.
• The PRINT command does not print a leading space reserved for the sign if the number is positive or the back space after a numeric expression.
• The PRINT command does not take into account the screen width for a line break when an expression can not be printed in the current line or must advance to the next area with the use of coma separator or is advanced the position specified by the TAB clause.
• The PRINT command separator comma and TAB clause no functionality for channels 8 and 9 of printer and file respectively.
• A character code 0 in a string truncates the string at that point. If necessary use the term CHR$(0).
• RANDOMIZE command always requires an expression as a parameter, you can skip to the user prompted.
• POS and VPOS functions do not have functionality for channels 8 and 9 of printer and file respectively.
• The code for the routines called by EVERY and AFTER should be very brief at runtime.
• Do not exit from a FOR loop with the GOTO statement whether the value end of the loop or stop have been specified with a non-constant expression, for example FOR i=1 TO 10 STEP n or FOR j=100 TO f*2. To do this you can set the value of the loop control variable equal to the value end of the loop and jump to the corresponding NEXT statement.
• Within each set of sentences true or false part of an IF statement can not just open a FOR or WHILE or just WEND or NEXT closure, but must be opened and closed within the same party. For example, error occurs IF a=0 THEN WHILE a>10, as in the real part of IF only opens the loop will not close, but close in another line later.
• In the statements ON .. GOSUB and ON .. GOTO not verified that the selector value is greater than the number of lines specified program, only proves that if zero is not jumping to any line.
• ENT and ENV statements do not accept parameters with the syntax = to specify the control of envelope by hardware.
• The syntax for declaring a table and to specify an element does not support the use of brackets as Locomotive Basic, only parentheses.
• The @ operator applied to a string variable or string table element returns the address of its descriptor, as in Locomotive Basic, but the descriptor is temporary, it is not conviente store that address for later use, but use only on the current command.
• When using the @ operator for numeric or string variable is not necessary to declare in advance.

Library to use real values

To overcome the inability to use real values in CPC Basic is the possibility of installing a set of RSX commands that allow their use. At the top of the application window you can specify the number of real values to be used by the application. If zero indicates the commands are not installed, if other value n is specified they are installed, saving memory space for a table of n real variables, identified with indexes from 0 to n - 1, to be covered by RSX commands. Commands that work with the table of real variables are:

• |ABS,i1,i2: equivalent to the operation table(i1)=ABS(table(i2)).
• |ADD,i1,i2,i3: equivalent to the operation table(i1)=table(i2)+table(i3).
• |ATN,i1,i2: equivalent to the operation table(i1)=ATN(table(i2)).
• |CINT,@variable,i: corresponds to the operation variable=CINT(table(i)), storing the index value i in the specified variable, ignoring the sign. Useful to pass the value of an item in the table of real values to a CPC Basic program variable.
• |CMP,@variable,i1,i2: stored in variable a value 1 if table(i1)>table(i2), a value 0 if table(i1)=table(i2), or a value 255, interpetable as -1 if table(i1)<table(i2).
• |COS,i1,i2: equivalent to the operation table(i1)=COS(table(i2)).
• |CREAL,i,expression is equivalent to the operating table(i)=expression. Useful to pass a value of CPC Basic program to an item in the table of real values.
• |DEG: equivalent to the command DEG.
• |DIV,i1,i2,i3: equivalent to the operation table(i1)=table(i2)/table(i3).
• |EXP,i1,i2: equivalent to the operation table(i1)=EXP(table(i2)).
• |FIX,i1,i2: equivalent to the operation table(i1)=FIX(table(i2)).
• |INT,i1,i2: equivalent to the operation table(i1)=INT(table(i2)).
• |LET,i1,i2: equivalent to the operation table(i1)=table(i2).
• |LOG,i1,i2: equivalent to the operation table (i1)=LOG(table(i2)).
• |LOG10,i1,i2: equivalent to the operation table(i1)=LOG10(table(i2)).
• |MUL,i1,i2,i3: equivalent to the operation table(i1)=table(i2)*table(i3).
• |PI,i: corresponds to the operation table(i)=PI.
• |POW,i1,i2,i3: equivalent to the operation table(i1)=table(i2)^table(i3).
• |RAD: equivalent to the command RAD.
• |REV,i1,i2: equivalent to the operation table(i1)=-table(i2).
• |ROUND,i1,i2,expression: equivalent to the operation table(i1)=ROUND(table(i2),expression).
• |SGN,@variable,i: corresponds to the variable operation=SGN(table(i)).
• |SIN,i1,i2: equivalent to the operation table(i1)=SIN(table(i2)).
• |SQR,i1,i2: equivalent to the operation table(i1)=SQR(table(i2)).
• |STR,@variable,i: corresponds to the operation variable=STR$(table(i)), where variable is of type string and with a minimum length of 11 characters.
• |SUB,i1,i2,i3: equivalent to the operation table(i1)=table(i2)-table(i3).
• |TAN,i1,i2: equivalent to the operation table(i1)=TAN(table(i2)).
• |VAL,i,@variable: equal to the operating table(i)=VAL(variable) where variable is of type string or can also be a string constant without the @ operator.

To specify the parameters that correspond to indices of the elements in the table of real values​may indicate constant values, variables or expressions that produce a numerical value in the range 0 to n - 1. If items are to be used as independent variables and not as a table of values, it is advisable to give value to variables with a descriptive name and use that variable to improve code readability. For example, if the index value 0 will stored result speed calculating with other values​index 1 for the distance and index 2 for the time, it could speed=0:distance=1:time=2:|DIV,speed,distance,time.

Requirements and installation of CPC Basic

You must have a computer with:

Description of files and folders in the application

After installing CPC Basic, within the directory is selected for it, are the following:

• File cpcbasic.exe: the main application file.
• web.url and forum.url files: direct access to the website and forum dedicated to CPC Basic respectively.
• Directory Files: here is the configuration file, the font files for the application and the base memory image files for each model based Amstrad CPC.
• Output directory: it generates the files resulting from compilation depending on the selected output, which can be either binary, assembly, ccz80, CDT, DSK, snap. Also stored in this folder the trace file LOG extension that can be created if during the use of the various utilities that use CPC Basic (ccz80 compiler, generator image files to tape, disk, memory or execution of the emulator) is an error.
• Directory Programs: is the default location for programs that are saved with SAVE and are loaded with LOAD or MERGE from CPC Basic. Initially this directory contains several example programs that can be loaded in CPC Basic.
• Utils directory: contains a number of subdirectories with different CPC Basic utilities used to generate the desired result: compiler ccz80, CDT, DSK and snap file generator and emulator.

It is recommended not to change anything in this structure, except access the Output directory to get the resulting files from compiling and edit the contents of the configuration file if necessary.

Configuration file

Within the directory where you install CPC Basic, in the subdirectory Files is the file cpcbasic.ini that can be modified to customize the appearance of the application. You can set the color of each element when viewed in the output window and the font size for the input and output windows. This requires modifying the numerical values assigned to each variable in the file. The amounts related to colors are those of the color palette of Amstrad CPC, in the range 0 to 26. For example, to use CPC Basic with red background and white text color in the input windows would change PenInput and PaperInput variables with the values 3 and 13 respectively.

To give effect to the change in this file is necessary to record to disk and restart the application CPC Basic.

Command line

CPC Basic can be used from the command line by running the cpcbasic.exe found in the directory where you installed the application. The syntax for this mode of use is:

where:

• /cpc specifies the Amstrad CPC model for which you want to generate the result.
• /out specifies the type of result that will be generated: binary file (bin), assembly code (asm), code ccz80 (ccz80), file CDT (cdt), file DSK (DSK), file snap (snap) or execution program in the emulator (run).
• /real specifies the number of real values​to be used by the program.

The resulting file compilation online mode is not generated in the Output directory, but in the same directory as the Basic source file, including the trace file LOG. The output of error messages from the compilation is done by the console. If the build fails in any of its phases CPC Basic returns exit code 1, if all returns correct exit code 0.

For online compilation is necessary to have the entire directory structure of the application, it is not enough cpcbasic.exe file.

Related links

Technical Notes

Basic CPC is written in C#.

It is created completely from scratch, with nothing in common with earlier versions of Basic CPC, which was more as a result of an investigation into product compilers as useful in programming practice.

Its inner workings are based on converting the source file Basic to ccz80 code that is compiled and converted into binary code.

For compilation ccz80 used with standard libraries and Amstrad CPC libraries as specified model over a library of additional functions to emulate some of the commands and functions of Locomotive Basic.

Thereafter, as requested, the binary code is embedded in an image file from tape, disk or memory. If specified the emulator is launched automatically loading a memory image that contains the binary code.

The machine code is generated to load into memory address &H4000, occupying continuous memory as the code length. With the function HIMEM can know which is the last address of memory occupied by the program, from which memory can be considered free. In addition, the machine code generated uses memory from &H170 to &H3FFF as dynamic memory for internal operations, so this space can not be used.

Initially CPC Basic admitted integer and real numbers as Locomotive Basic, but during its development was that the rate of expression evaluation not only improved the earlier versions of CPC Basic or Locomotive Basic, for almost all expressions any real value used as either variable or by using an intrinsic function, and this meant that all expression values should be converted to real to operate properly. It was therefore decided to dispense with such variables as it also found that a majority of Basic programs, gaming applications that are not needed to use them, because the data they use are coordinates, scores, identifiers of elements, etc., which are always positive integers. In any case, was developed using RSX commands that manage real values in order to use this data type struts at such times as necessary.

Acknowledgements

• Wesley Clarke by it Amstrad CPC font, which are based those used by CPC Basic.
• Julián Albo by the assembler pasmo with which the files CDT are generated.
• Ludovic Deplanque (Demoniak) by the utility ManageDSK with which the files DSK are generated.
• Cesar Nicolas Gonzalez (CNGSoft) by the CPCE emulator to run the machine code generated.

History

• 11 March 2012: Publication of CPC Basic version 3.0.0.
• 11 March 2012: Publication of CPC Basic version 3.0.1. Fix declaration of tables for code ccz80.
• 14 March 2012: Publication of CPC Basic version 3.0.2. Show version number in the window title.
• 17 March 2012: Publication of CPC Basic version 3.0.3. Correction to avoid blocking when the result of compiling the file ccz80 produces too much text. Added buttons to access to directories of programs and ouput.
• 19 March 2012: Publication of CPC Basic 3.0.4. Correction in the output format of the CAT command.
• 17 May 2014: Updated ccz80.