NOTICE:
The Arnor products for the Amstrad CPC and Amstrad PCW are © Copyright 1997-2001 Brian Watson. All rights reserved
For support and printed manuals for these products please contact Brian at:
Brian Watson,or
brian@spheroid.demon.co.ukBrian Watson has given permission for this document to be made available through the "Unofficial Amstrad WWW Resource". The original document was provided by Richard Wildey, then scanned and OCR'ed by Kevin Thacker.
As a sideways ROM, PROTEXT takes 512 bytes for its own workspace when it is initialised. The location of this workspace depends on the number and positioning of other sideways ROMS, so any references to this workspace must be dynamically evaluated. The IY register is set by the firmware to contain the start of this workspace when PROTEXT is entered, so the IY-relative instructions can be used. However, this is VERY inconvenient when coding the program, so PROTEXT uses a different technique. A static workspace area is chosen (at present this is &AC00, which is the start of the BASIC workspace). Whenever PROTEXT is entered the contents of this static workspace area is swapped with part of the dynamic workspace area (pointed to by IY). On exit from PROTEXT they are swapped back again. This does not affect BASIC because the BASIC memory is always restored before BASIC needs it. The advantage is that the coding of PROTEXT is much easier, and the resulting code is probably considerably shorter.
There are four sections to this documentation:
Each routine has a number. Routine n is called by executing the external command CTRL-P n (i.e. the two character name 16 n). The firmware routine KL FAR PCHL may be used.
Care must be taken that the PROTEXT workspace has been swapped into the static area before calling routines 5 to 12, or before changing vectors. If this is not the case the SWAPIN routine must be called first and the SWAPOUT routine afterwards. The rules for determining whether this is necessary are:
For all these calls PROTEXT version 1.00 or later is required.
| n | name | input | output and effect |
|---|---|---|---|
| 0 | PROBE | none | CHL=version number DE=dynamic workspace address B=static workspace address (high byte) |
| 1 | SWAPIN | none | Swaps workspace areas - to put PROTEXT workspace in static area. Flags: NC if not enough memory to run PROTEXT. |
| 2 | SWAPOUT | none | Swaps workspace areas - to return PROTEXT workspace to dynamic area. |
| 3 | VECTORS | none | HL=address of first vector. |
| 4 | ENVIRONMENT | none | HL=address of environment. BC=length of environment. |
| 5 | LOCATE | DE=memory addr | Sets current page/line/column corresponding to address within text. |
| 6 | SET LINE | DE=line number | Sets current line number. |
| 7 | SET COLUMN | DE=column number | Sets current column number. |
| 8 | INSERT | DE=number | Insert a number of spaces at the current position. HL=current position (address) Flags: NC if not enough memory. |
| 9 | DELETE | DE=number | Delete a number of characters forwards from the current position. |
| 10 | GET TEXT | none | HL=start of text DE=end of text |
| 11 | reserved | ||
| 12 | GET CURSOR | none | HL=current position (address) |
| 13 | GET COMMANDS | none | HL=address of PROTEXT command table (each command is followed by its abbreviation) DE=jump table (2 bytes addresses) |
The addresses of the vectors are given as an offset to the address returned by the call CTRL-P 3. User routines called via these vectors should preserve the ROM states and selection and, except where indicated, preserve all registers (especially IX and IY!).
These vectors are present in PROTEXT version 1.00 or later.
| address | name | description | ||||||
|---|---|---|---|---|---|---|---|---|
| 0 | DRIVER ADDR | Contains the two byte address of the printer driver in memory. | ||||||
| 2 | DRIVER LEN | Contains the two byte length of the printer driver in memory (by default this is &100). | ||||||
| 4 | PRONVEC | This address is called at the start of any PRINT command (P, PS, PF, PB, etc.). It initially contains a RET instruction, and can be changed to any 3 byte instruction (esp. JP, RST 3, etc. ). The new routine may corrupt AF, BC, DE, and HL. | ||||||
| 7 | PROFFVEC | This is similar to PRONVEC and is called at the end of any PRINT command. The new routine may corrupt AF, BC, DE, and HL. | ||||||
| 10 | PRINVEC | This is called to print every character. It
initially contains a jump to the PROTEXT routine, and can be changed to jump to a substitute routine,
or to a routine which does something before printing and then jumps to the PROTEXT routine (the address of which was saved when the vector was intercepted).
Entry conditions are as follows: A=character to print. If the routine completely replaces the PROTEXT routine it should return flags as follows:
Alternatively, jump to the PROTEXT routine, preserving all registers (careful with the ROM state!). | ||||||
| 13 | FINDVEC | Called when COPY is pressed for next find. Initially contains a RET instruction. | ||||||
| 16 | COMMVEC | Called before PROTEXT processes a command (command mode). Initially contains RET.
Entry conditions: HL=address of command string, terminated by zero. Exit conditions:
| ||||||
| 19 | EDITVEC | Called to interpret edit mode command. Initially contains jump to PROTEXT routine. Enters with A=character from keyboard. Can be intercepted to add command. Currently CTRL-U, and CTRL-Y are unused. New routine must jump to PROTEXT routine if it is not acting on the character so that PROTEXT performs the command normally. | ||||||
| 22 | READVEC | Called to read command string. Initially jumps to PROTEXT routine. | ||||||
| 25 | SCSYNVEC | Stored command syntax check. Initially contains RET.
Called during pre-printing syntax check. Can be
intercepted to add stored commands.
Entry conditions: HL=address of first byte of string after stored command name (i.e. after >XX). To check the command the routine must:
Exit conditions: C=1 if command recognised. Otherwise PROTEXT will check its own list of stored commands. | ||||||
| 28 | SCPRINVEC | Stored command processor. Initially contains RET. Called during printing.
Entry conditions: HL=address of first byte of string after stored command name (i.e. after >XX). Exit conditions: HL=address of next byte in text to be printed/interpreted. So if the command is not intercepted, return preserving all registers. If the command is acted on, return with HL pointing to the first byte of the line after the stored command line. |
An enlarged printer driver can be set up by changing the DRIVER ADDR and DRIVER LEN (see VECTORS, above). The driver must be at least 256 bytes long.
| byte | default | description |
|---|---|---|
| 0-1 | 20 | Offset of first redefined character. |
| 2-3 | 94 | The number of free bytes in the printer driver. |
| 4-5 | 0 | Reserved |
| 6 | 66 | Page length |
| 7 | 3 | Top margin |
| 8 | 2 | Header margin |
| 9 | 2 | Footer margin |
| 10 | 3 | Bottom margin |
| 11 | 1 | Flags. Effect if bit set:
0=continuous printing, 1=Page number at top |
| 12 | 5 | Even side margin |
| 13 | 5 | Odd side margin |
| 14 | 1 | Line spacing |
| 15-16 | 1 | Start page number |
| 17-18 | 65535 | End page number |
| 19 | 1 | Number of copies |
| (20) | Character definitions. Each definition takes the form: ASCII code being redefined, length of code sequence, code sequence. A zero byte marks the end of the definitions. | |
| Followed by:
Printer control code definitions. Each code consists of a sequence of codes for off, followed by a sequence of codes for on. Each sequence is preceded by the length of the sequence. If a code is undefined there are two zero bytes, if there is an on code and no off code there is a zero byte followed by the sequence for on. The end of the table is marked by -1. | ||
The default key translation table is not suitable for PROTEXT to use because various key combinations return the same tokens (e.g. COPY and SHIFT-COPY), while PROTEXT needs different tokens. The tokens listed below can be put in function key expansions to enable the easy entry of a string of PROTEXT commands.
| CTRL-@ | 0 | CTRL-[ | 27 |
| CTRL-A | 1 | CTRL-\ | 28 |
| CTRL-B | 2 | CTRL-] | 29 |
| CTRL-C | 3 | CTRL-£ | 30 |
| CTRL-D | 4 | CTRL-0 | 31 |
| CTRL-E | 5 | CTRL-< | 2 |
| CTRL-F | 6 | CTRL-> | 31 |
| CTRL-G | 7 | COPY | &E0 |
| CTRL-H | 8 | CTRL-TAB | &E1 |
| CTRL-I | &ED | CTRL-hyphen | &E3 |
| CTRL-J | 10 | SHIFT-TAB | &E4 |
| CTRL-K | 11 | SHIFT-CLR | &E5 |
| CTRL-L | 12 | CTRL-CLR | &E6 |
| CTRL-M | &EE | CTRL-/ | &E7 |
| CTRL-N | 14 | CTRL-DEL | &E8 |
| CTRL-O | 15 | SHIFT-COPY | &E9 |
| CTRL-P | &E2 | CTRL-COPY | &EA |
| CTRL-Q | 17 | CTRL-space | &EB |
| CTRL-R | 18 | SHIFT-ENTER | &EC |
| CTRL-S | 19 | CTRL-ENTER | &EC |
| CTRL-T | 20 | cursor-up | &F0 |
| CTRL-U | 21 | cursor-down | &F1 |
| CTRL-V | 22 | cursor-left | &F2 |
| CTRL-W | 23 | cursor-right | &F3 |
| CTRL-X | 24 | SHIFT-up | &F4 |
| CTRL-Y | 25 | SHIFT-down | &F5 |
| CTRL-Z | 26 | SHIFT-left | &F6 |
| SHIFT-right | &F7 | ||
| ESC | &FC | CTRL-up | &F8 |
| CTRL-down | &F9 | ||
| CTRL-left | &FA | ||
| CTRL-right | &FB |
Copyright (c) Arnor Ltd., 1985 Issue 3 06/12/1985