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:

or

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

# PROTEXT TECHNICAL INFORMATION

## Introduction: how the PROTEXT workspace is organised

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:

1. calls that can be made to PROTEXT which either return some information or perform some function.
2. vectors that may be intercepted to change the operation of some feature of PROTEXT or to add a new feature.
3. printer driver format.
4. PROTEXT key translation table

## (i) CALLS

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:

1. if your code has been called as an external command, or has been called in any way from outside PROTEXT you will need to use SWAPIN and SWAPOUT.
2. if your code has been called by intercepting a vector then do not use SWAPIN and SWAPOUT.

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)

## (ii) VECTORS

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. D bit 0 is set if PRINT (to printer). D bit 1 is set if PRINTF (to file). D bit 2 is set if PRINTS (to screen). If the routine completely replaces the PROTEXT routine it should return flags as follows:
C | if successful.
NC, NZ | to retry (e.g. printer not online).
NC, Z | to abort printing.
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:
C, Z | if command processed, return to command mode.
NC | if command processed, enter edit mode.
C, NZ | if PROTEXT should interpret command. All registers must be preserved.
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: step back from HL until it finds one of: 0 (start of text) , &A (line feed) , &8A (soft line feed). Move forwards ignoring &80-&89 (place markers) and &8B,&8C (block markers). 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. All other registers preserved. 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.

## (iii) PRINTER DRIVER FORMAT

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 2=Page number at bottom, 3=form feeds on, 4=NLQ on 7=New page after print
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. There are 27 of these: @, then a-z. 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.

## (iv) PROTEXT key translation table

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