Hisoft C
Written by: Hisoft
categories: application (programming)
Platforms: Sinclair ZX Spectrum 48K
Sections: Instructions
Hisoft C for the ZX Spectrum
Summary of instructions
This is a condensed version of the Hisoft C reference manual. The main sections not covered are:
The compiler is based entirely in RAM, together with an editor, the source text which is being developed, and the resulting machine code. There is no intermediate pass through assembly language or linkers such as is normally found in C compilation systems.
After loading the program and typing 'n' in response to the "copy to Microdrive?" question, C code can be entered directly; type SymbolShift-I (end of file) to finish and the compiler will ask you "type y to run program" (any other key will return to the sign-on message). This is the simplest way of entering a program, without using the editor.
The keyboard is used in lower-case mode all the time. Pressing a key usually returns the ASCII code of the lower-case letter or digit on that key. However, pressing Enter returns 10 rather than 13, as C uses Newline/Linefeed at the end of a line, not Carriage-Return.
Pressing SymbolShift plus another key returns the ASCII code of the red symbol engraved on or by the key, rather than the BASIC keyword. This includes <=, <> and >= on the Q, W and E keys, which have been assigned values of 29, 31 and 30 respectively. SymbolShift-I returns the EOF value -1 and is echoed as CHR$(137) on the display; this is used to terminate files typed in from the keyboard.
CapsShift is also altered slightly. CapsShift-6 now returns 16 (not 10, which has been used by Enter); CapsShift-0 returns 8 (not 12) and CapsShift-5 returns 12 (not 8).
The three standard C files "stdin", "stdout" and "stderr" are assigned to the Spectrum keyboard stream, upper display screen and upper display screen (again) respectively. Some translations are done on the characters.
Input and output to other devices is done to files using "file- pointers". The file-pointers used for I/O in C are used to represent stream numbers on the Spectrum. They have type pointer-to-FILE so that they are compatible with file-pointers on other systems, but actually their value (as a bit pattern) is just the Spectrum stream number. Keyboard I/O uses getchar() and putchar() respectively; these correspond to getc(0) and putc(0).
Before using getc or putc you must have a file-pointer. For the keyboard and display 0 can be used as mentioned above. You can also use stream 1 for the keyboard / lower screen, 2 for the upper screen, and 3 for the printer.
For cassette and Microdrive you must call "fopen" to get the file- pointer. The file-pointer for cassette is 16; for Microdrive it will be the highest unopened stream number (normally 15). In addition, you can open streams in some other way - from BASIC or by a machine code routine - and then just pass the stream number to getc or putc.
All I/O on cassette or Microdrive is done at a character level using getc(fp) and putc(c,fp). Before any tape I/O it is necessary to call fopen(filename,mode). On output this constructs a header block and writes it to tape, whilst on input it searches the tape for a matching header block. putc and getc can then be used for character I/O and finally fclose tidies up and writes the last block of an output file.
When the system is about to write to cassette it changes the border colour to RED for about five seconds before doing so; the cassette should be started in RECORD when this happens. On input a RED border is displayed for about a second to indicate that the cassette should be started in PLAY. When the program has read a block the cassette should be stopped so that the program can process the contents of the block, and then restarted when it requests the next block. The compiler is capable of compiling source from a block even if the cassette is left running.
The compiler uses the Spectrum temporary colour attributes to control the Ink and Paper colours on-screen, which are set up from the permanent colour attributes when the compiler displays the sign-on message. To use different colours simply set INK and PAPER prior to loading the compiler (or use the editor B command to return to BASIC).
To enter the editor from the compiler, type CapsShift-1 (or EDIT) then Enter. You will see a vertical block when you press EDIT, and the message "edit:" when you press Enter, followed by the prompt '>'.
To enter the editor after a compiler error, select the EDIT key while the compiler is waiting for a keypress after the error message, and the editor will start on the line causing the error. To return to the C compiler type C-Enter, or to return to BASIC type B-Enter.
In response to the '>' prompt the command format is:
????C N1, N2, S1, S2
C???the command to be executed
N1??a number in the range 1-32767
N2??a number in the range 1-32767
S1??a maximum 20 character string
S2??a maximum 20 character string
Most editor commands do not expect all five parts of a command line. The editor remembers previous numbers and strings and will use these former values if you do not enter them when required. N1 and N2 are initially 10 and S1 and S2 are initially empty. The comma is the default argument separator and spaces are ignored, except in strings.
Text may be entered into the text file either by typing a line number, a space and then the required text, or by using the 'I' command. If you type a line number without any text, followed by Enter, then that line will be deleted from the text file.
Insert Text I m,n
Insert text from line m to line n (replacing any text already there).
Display Text L m,n
List lines m through n on-screen. This command does not use previously
entered defaults. Defaults are always 1 for m and 32767 for n, thus
'L' on its own will always list the entire file. After each screen is
displayed press EDIT to return to the editor or any other key to
continue with the listing.
List Length K n
Set the display length before a pause to n lines.
Print Text W m,n
Write lines m through n to the printer; defaults are as for 'L' above.
Press BREAK to abandon printing and return to the editor.
View Defaults V
Displays the current argument delimiter and default values for N1, N2,
S1 and S2. This command also displays the start and end addresses of
the text file in decimal.
Set Delimiter S,,d
Change the argument delimiter to character d.
To Compiler C
To finish editing and return to the C compiler, press C-Enter.
To BASIC B
To finish editing and return to the BASIC, press B-Enter.
To return to the C compiler type: RANDOMIZE USR 25200
Delete Lines D m,n
Delete lines m through n from the text file.
Move Line M m,n
Move line m to line n, replacing whatever was there before. Line m is
left unchanged (thus this is really Copy, not Move).
Renumber Text N m,n
Renumber the entire text file starting with a first line number of m
and in steps of n.
Edit a Line E n
Edit line number n. The special editing commands are:
=> | CapsShift-8 - move to the next character |
<= | CapsShift-5 - move to the previous character |
Enter | finish editing and save the changes |
Q | finish editing and ignore the changes |
R | restore the line as it was before any changes |
L | list the rest of the line being edited |
K | delete the character at the current cursor position |
Z | delete all characters from the current cursor position to the end of the line |
I | insert characters at the current cursor position - pressing Enter will return to the main Edit mode |
X | insert at the end of the line |
C | overtype characters until Enter is pressed to return to main Edit mode |
F | find the next occurrence of the 'find' string previously defined using the 'F' command below. This will end Edit on the current line if it does not find another occurrence of the 'find' string. If an occurrence is found within the previously specified 'F' line range then Edit mode will be entered for the next matching line, with the cursor positioned at the start of the matched string. |
S | substitute the previously defined 'F' command 'substitute' string for the 'find' string where the cursor is and then search for the next occurrence of the 'find' string. Together with the 'F' sub-command above, this allows stepping through the file and optionally replacing occurrences of the 'find' with 'substitute' string. |
Find String F m,n,f,s
Search text in the line range m through n for string f; enter Edit
mode on the first matching line.
These commands use the same simple scheme as the compiler to
distinguish between cassette and Microdrive files. To use a Microdrive
file called, say, FRED, on Microdrive 2, put the drive number and a
colon before the file name in commands, thus:
????2:FRED
Write Text P m,n,s
Put text lines m through n onto cassette or Microdrive with file name s.
The line numbers are not recorded in the file. Make sure that your
tape recorder is set to RECORD before entering this command.
Read Text G,,s
The cassette or Microdrive is searched for file name s, which if found
will be loaded at the end of the current text. Line numbers are
attached to the lines as they are read in, increasing in steps of 10.
#define identifier macro
This command allows for limited 'macro expansion' - the definition of
constants. #define macro arguments are not supported, nor the #undef
command.
#error
This frees space in memory by removing compiler error messages.
#list
Followed by a '+' or '-' sign, switches the compiler listing mode on
or off as appropriate.
#direct
Followed by a '+' or '-' sign, turns direct execution mode on or off.
Direct execution mode allows programs and functions to be tested as
they are written. Once this mode is enabled, functions can be invoked,
variables may be assigned, loops can be run and any other statement
can be executed. Typing a function name followed by its required
parameters and a semi-colon will execute the function.
#include
This command is probably most usefully seen as a command to initiate a
compilation, although its more precise effect is to include a
specified file in the compilation of another. The three main forms
are:
#include
Compiles the current source text in memory.
#include filename -or- #include "filename" -or- #include <filename>
Causes the named file to be included in the current compilation.
#include ?filename?
This allows for library file inclusion, and only compiles those
functions in the named file which have been used somewhere in the main
file.
#translate filename
This tells the compiler to save the product of the compilation to
cassette or Microdrive under the file name given. The resultant file
can be loaded and run with LOAD "filename" CODE and RANDOMIZE USR 25200
instructions.