*************************************************************************
* >E-ZapCalls	Documentation of Zap entry points (how to call Zap)	*
*************************************************************************

Zap does NOT have a SWI interface as it uses registers R8-R10 to point to
data blocks, and these cannot be passed to swi's. To call Zap you will need
to know the address of the Zap module workspace (ie it's private word). If
you are an extension mode then this will be passed to you in R12 whenever you
are called by one of your entry points. However, for the first call you make
to Zap, when you add your module to it's list via Zap_Addmode, you will not
know it. Then you should use OS_Module 18 to find it. Eg,

 SYS "XOS_Module",18,"Zap" TO R0,R1,R2,R3,workspace%

Now, the first word in Zap's workspace contains the address of a table of
Zap's entry points. Thus to call the entry point (documented below) at
offset a% if you are using the BASIC assembler then the use of the following
macro is recommended:

    REM Call Zap at entry offset a%
    REM Entry: R0-R11=args R12=zap workspace
    REM Exit : R0-R11=returned values R12 preserved R14 corrupted
    
    DEF FNcall(a%)
    [OPTpass
    LDR R14,[R12]		\ get start of zap table
    ADD R14,R14,#a%		\ address of the sub
    STMFD R13!,{R14}		\ save address on stack
    MOV R14,PC			\ return address (with flags)
    LDMFD R13!,{PC}		\ call the sub 
    ]:=""

The names of the routines are listed below in the order in which they appear
in the table. Thus the first, Zap_AddMode, is at offset 0. The second,
Zap_Claim is at offset 4, etc. These values are defined for you in the
program E-Library.

In general these routines have the following entry/exit conditions:

 \E R0-R11=arguments R12=Zap's workspace R13=user stack R14=return address
 \X R1-R13 preserved. R0 and Flags ALTERED. V set if error and R0=error block

Thus if I write:

 \E R8
 \X R1=3

Then I mean that on entry R8 was the window block pointer, R12 zap's
workspace etc. And on exit that R1=3, R2-R13 saved, R0 corrupted etc. If I
omit the \E or \X then I mean the standard entry/exit conditions hold.

Errors should be passed back to Zap by the entry point through which the
module was called (with V flag set and R0=error block pointer). Please note
that for most calls, Zap must be paged in as the current task! This will be
so if you are an extension mode.

For a table/summary of the zap call names for including in your source, see
the file E-Library.

Zap_AddMode
Adds a new Zap extension mode. This should be called after the module Zap is
loaded, but before it starts up as a new task. Zap need not be paged in for
this call.
	\E R0=address of table of entry points (see file E-Entry)

Zap_Claim
Claims a block of workspace in Zap's heap.
	\E R0=number of bytes required
	\X R0=pointer to the heap block

Zap_Ensure
Ensures a zap heap block is of a given size.
	\E R0=pointer to the heap block
	   R1=number of bytes required.
	\X R0=new heap block pointer of (possibly moved) extended block.
	   (An error is returned if the block couldn't be enlarged).

Zap_Free
Free a zap heap block after use.
	\E R0=pointer to heap block to free

Zap_MoveBytes
Moves a block of memory. The movement may be up or down by any amount. The
data is ALWAYS preserved no matter where the destination is. This routine is
highly optimised and should be used for moving any large block of data. Zap
need not be paged in.
	\E R1=source byte address
	   R2=destination byte address
	   R3=number of bytes to move
	\X R1-R3 corrupted

Zap_SplitBuffer
This splits a file held in Zap at the indicated file offset ready for
insertion/deletion of data. It also ensures that file buffer has a given
amount of room free. See E-File.
	\E R0=file offset to split at (new value for f_splito)
	   R1=minimum number of bytes to have free in the split
	   R9=file to be split

Zap_NewTxtStatus
This updates the screen after changes are made to a file. This is very low
level and you should use Zap_Command when possible. Zap_SaveTxtStatus should
be called first.
	\E R0/R1 as for SaveTxtStatus and R2=new input caret offset.

Zap_SaveTxtStatus
This is a low level call used by Zap_DoCommand when changing a file. You
should use Zap_Command/Zap_DoCommand in preference. Any file changes done
using this call are NOT saved in the undo buffer. Ie, don't use it. To use it
you specify the area of the file to be changed (R0 to R2) and the amount of
the change (in R1). After making the change you use Zap_NewTxtStatus to
update the screen. Set f_docom to 0 if in doubt.
	\E R0=file offset of first byte in file to be changed.
	   R1=proposed signed change in size of file.
	   R2=file offset of first character which is unchanged.
	   f_docom,f_dolen,f_dodata must be set up - see e_prevline.

Zap_Command
This should be used for inserting/deleting/replacing data in a file. Its 
action is to call the mode entry point named e_command. See E-Entry. The
mode's default action is then to call Zap_DoCommand. The commands are
automatically placed in the undo buffer. If you are doing a sequence of
insertions/deletions then please use Zap_Start/StopOp. Note that the cursor
is automatically updated to the end of the inserted/deleted region. To
prevent this, set b14 of f_flags, but you MUST restore it after the command
returns.
	\E R0=command number:
	    1=insert 2=delete 3=replace (forward) 4=replace (backward).
	    5=delete 6=insert (the last two leave the cursor at the start).
	    Add &10 if command is to be buffered in one block
	      (and thus undone in one key press).
	    Add &20 if you do not wish the input caret to be updated
	    Add &40 if the region is/was/should be selected
	   R1=file offset for command to take place at.
	   R2=number of bytes being inserted/deleted/replaced.
	   R3=data to insert/replace with for commands 1,3,4.
	   R8=window on file to be altered/0 if none.
	   R9=file to be altered.
	NB If you don't specify the window then it won't know which mode to
	call, so this command will just call Zap_DoCommand.

Zap_NewWinStatus
This recreates a window after some display parameters have changed. Use
Zap_SaveWinStatus before changing any parameters.
	\E R8/R9

Zap_SaveWinStatus
This is used before changing any of the 'w_*' window parameters which would
effect the display. See E-Window. The current cursor position, scroll offsets
etc are saved. After changing the window parameters call Zap_NewWinStatus.
Zap will do it's best to recreate the window with the new attributes,
preserving the position of the cursor on screen.
	\E R8/R9

Zap_ReplaceArea
This command replaces one area of text with another (not necessarily of the
same length) by performing the minimum number of insertions/deletions/simple
replaces using Zap_Command. In BASIC mode it also retokenises the line as
necessary. This is used during a search and replace. See mode entry point
e_replace.
	\E R1=file offset of original data
	   R2=length of original data
	   R3=address of replacement data
	   R4=length of replacement data R8/R9

Zap_PlotCaret
This command plots a caret in its new position automatically removing it from
its old position. Ie, it just calls Zap_ClearCaret then Zap_SetCaret.
	\E R10=caret block

Zap_ReflectCaret
This acts as Zap_PlotCaret but only uses c_off, updating the c_loff and c_col
offsets from this (c_charoff is set to 0). Ie, it just calls Zap_UpdateCaret
and then Zap_PlotCaret.
	\E R10=caret block

Zap_SetCaret
This updates the area of the window containing the the caret given on entry.
Hence its effect is usually to draw the caret at its (new) position. It
calculates a value for c_charoff.  See E-Cursors.
	\E R10=caret block

Zap_ClearCaret
As for Zap_SetCaret, but it updates the area of the window where the caret
last was (stored in the c_o* variables). Hence the caret is in effect removed
from its old position. See E-Cursors.
	\E R10=caret block

Zap_DoCommand
This acts as Zap_Command but actually performs the action rather than
calling the extension mode.
	\E As for Zap_Command.

Zap_ShowCursor
This call makes sure that a given cursor can be seen in its window (by
changing the scroll offsets if necessary). It does not redraw the cursor
in general (though changing the scroll offsets may cause it to be redrawn).
	\E R10=cursor block of cursor to show

Zap_ReadVar
Reads one of Zaps internal variables. See the file E-Vars for the numbers.
	\E R1=variable number.
	\X R0=variable value.

Zap_WriteVar
Writes one of zaps internal variables. See the file E-Vars for the numbers.
	\E R1=variable number
	   R0=new value

Zap_SaveFile
This saves a file to disc (using f_name as the file name). The file may not
actually be saved if a dialogue box is opened. (Eg: 'file is older than
version on disc box'). Please note the value of R0 on exit!
	\E R8/R9 = window to save
	\X R0=0  => File has been saved to disc - you can now delete it.
	   R0=-1 => File has not yet been saved - warning window opened /
		    data transfer initiated.

Zap_FillWords
Fast word filling code. The block must be word aligned. Zap need not be paged
in.
	\E R1=word to fill with.
	   R2=address of memory to fill (word aligned).
	   R3=number of bytes to fill (a multiple of 4).
	\X R0-R3 corrupted.

Zap_UpdateLns
This updates the line numbers column of a given window. This is usually done
automatically by Zap_Command. This is used by the BASIC mode on a renumber.
	\E R0=first physical line to start from R8/R9

Zap_EachWindow
This sub calls a given sub for each window on a given file. Each time it
calls the sub pointed to in R10, it sets up R8 for that window.
	\E R0-R7=args to pass to the sub.
	   R9=file (whose windows you are to call).
	   R10=address of sub to call for each window on this file.
	The sub called has:
		\E R0-R7 as set up by you
		   R8/R9 points to the given window
		\X Must preserve R1-R11 and VS on error etc.

Zap_UpdateCaret
This sub is called to update a caret position from a given file offset. Save
the new offset of the caret in c_off. Call this. Then c_col, c_line, c_loff,
c_charoff and c_width will be set up. See E-Cursors.
	\E R10=caret block

Zap_GetWindState
Updates the window block R8 (first few entries) by calling
Wimp_GetWindowState.
	\E R8

Zap_StartOp
Starts a sequence of operations. This should be used when performing a
sequence of calls to Zap_Command. It causes all the file changes to be made
with only ONE screen refresh, thus giving a much smoother update. After this
has been called, all subsequent calls to Zap_Command before a Zap_StopOp call
have their actions concatenated. When you call Zap_StopOp the screen is then
updated. You MUST call Zap_StopOp before returning to Wimp_Poll. StartOp/
StopOp's can be nested to any depth (so only the last StopOp actually causes
the screen to be updated).
	\E R9=file which will be operated on.

Zap_StopOp
Ends a StartOp/StopOp structure.
	\E R9=file which has been operated on.
	\X If VC on entry then R0 corrupted and R1-R11 preserved as usual.
	   If VS on entry then error pointer in R0 and V flag status are
	   also preserved.

Zap_CallMode
Calls a mode entry point. See E-Entry for a list of entry points. The mode
called is the mode of the window given in R8.
	\E R0-R10=parameters R8 R11=mode entry point offset
	\X As for the given mode entry point.

Zap_CallGivenMode
Calls a mode entry point of a specified mode.
	\E R0-R9=parameters R10=mode number R11=entry point offset
	\X As for the given mode entry point.

Zap_ReadMode
Read the address of the mode entry point tables. Two pointers are returned.
The first (R0) is a pointer to the mode table as stored in the extension
module and documented in E-Entry. The second (R1) points to a table of actual
addresses to be called, with entry points which were null in the original
table converted to addresses and all offsets converted to addresses. In this
table, each entry consists of 8 bytes. The first 4 bytes gives the address of
the entry point, and the next 4 the value to pass in R11 when the entry point
is called. This will obviously vary if some mode entry points are based on
other modes. Thus the linked table has the form:
	e_module	#0	module address,	module workspace address
	e_title		#8	title address,	mode variable table address
	e_author	#16	author address,	undefined
	e_basemode	#24	basemode,	clone basemode
	e_mode		#32	mode number,	mode e.p. suppliers list
	e_init		#40	init code addr,	value to pass in R11
	e_menu		#48	wimp menu data,	undefined
	e_len		#56	undefined,	undefined
	e_postload	#64	postload addr,	value to pass in R11
	 and the rest as for e_postload.
I reserved the right to use the undefined words in future. You can change the
table entries pointer to in R1, but I don't advise it :-)
The mode entry points suppliers list contains a mode number (byte) per entry
point.
	\E R0=mode number.
	\X R0=pointer to unlinked table in modes module / <=0 if invalid
	   R1=pointer to linked table in zaps workspace / <=0 if invalid

Zap_FindFile
Given the name of a file, this call produces a window on that file (loading
it if necessary). Path is canonicalised before comparing with currently
loaded files.
	\E R0=file name.
	\X R8/R9=window on that file.

Zap_FindWindow
Given a file block pointer of a file already loaded, this call produces a
window block pointer of a window on that file (opening it if necessary).
	\E R9
	\X R8

Zap_ConvWindOff
Converts a window offset to a window block pointer. See E-Windows.
	\E R0=offset of a window in the window list /-ve
	\X R8/R9=window and file /0

Zap_ConvFileOff
Converts a file offset to a file block pointer. See E-File.
	\E R0=offset of a file in the file list/-ve
	\X R9=pointers to the file block/0

Zap_GetWindOff
Converts a window block pointer to a window offset. See E-Windows.
	\E R8=window block pointer/0
	\X R0=offset in the window list/-ve

Zap_GetFileOff
Converts a file block pointer to a file offset. See E-File.
	\E R9=file block pointer/0
	\X R0=offset in the file list/-ve

Zap_GotoOffset
This call causes the given cursor to jump to a given file offset, leaving a
mark behind at the previous position.
	\E R0=offset to go to R8-R9=file R10=cursor

Zap_JumptoOffset
As for GotoOffset but no mark left on jumping.
	\E R0=offset to go to R8-R9=file R10=cursor

Zap_FindOffset
Given the (x,y) position in work area characters, finds the file offset of
the 'nearest' point in the file. See E-Windows.
	\E R2=x column (inc margin) R3=y row (from top)
	\X R0=file offset R1=file offset of physical line start R2/R3 clipped

Zap_NewFileTitle
Update the titlebars of all windows on a given file.
	\E R9=file

Zap_InsertString
Inserts a string at the end of a buffer using Zap_Command.
	\E R0=zero terminated string R8/R9

Zap_CreateFile
Creates an empty file, possibly changing the opt_flags/format via BIC 'mask'
EOR 'eor' when creating it. See E-Flags, E-Windows. It calls
Zap_CreateWindBlock and Zap_CreateFileBlock etc.
	\E R0=file type
	   R1=flags mask
	   R2=flags eor
	   R3=format mask
	   R4=format eor
	\X R8/R9=newly created file (with open window).

Zap_NewLinkEntry
Adds a new link entry to the f_links list. See E-File for description of the
links list format. This is a low-level call. Use Zap_Throwback in preference.
This is used by throwback. A new block is created if the file name does not
match that of the previous link block, or the flags differ. The point of the
links is that they are updated when changes are made to the indicated file.
	\E R0=data word (Ie file offset of link / line number of link
	      depending on flags in R5).
	   R1=filename (Of the file that R0 is an offset in).
	   R4=file offset/-1 (Ie, offset in file list of the file named in
	       R1 if the file is loaded, or -1 if you don't know if the file
	       is loaded or not - usually safest to put as -1).
	   R5=flags (as documented under f_links in E-File).
	   R9=file to which the link should be added - ie this is the
	      throwback buffer file as opposed to R1 which is the file giving
	      the C program / file which was searched through.
	\X R0=0 if link added to last list entry/1 if new entry created.

Zap_DefaultClick
Calls the default mouse click handling code. See the entry point e_click.
	\E R1=depth (0=drag 1=click 2=double click etc)
	   R2=x R3=y
	   R4=buttons
	   R8/R9 as for e_click.

Zap_PutCaret
Sets standard cursor editing mode and puts the cursor caret at a given file
offset in a given file.
	\E R0=file offset R8/R9=file

Zap_DiscardFile
Kill a file and all windows on that file without prompting user.
	\E R9=file

Zap_DeleteFile
As for Zap_DiscardFile but prompts user if file altered etc.
	\E R9=file

Zap_DiscardWindow
Kill a window, and the file if auto-delete is on and this is the last window
on that file. Don't prompt user.
	\E R8/R9

Zap_DeleteWindow
As for Zap_DiscardWindow but prompts user if file altered etc.
	\E R8/R9

Zap_BuildMenu
This is Zap's 'variable length menu' building sub. See E-Menu for details on
Zap's menu format. If you want to be able to specify help text, use
Zap_BuildMenuWithHelp instead.
	\E R0=menu name (max 12 chars)
	   R1=address of sub to generate the menu entries
	      b0 set if the menu name is a MessageTrans token
	         (no parameters, no GS translation)
	   R2=address of menu updating sub/0 if none (see E-Menu)
	   R3=address of menu interpret sub for all entries/0 (see E-Menu)
	   R4=menu width in chars
	   R6=flags for each menu entry (see E-Menu offset #-16)
	   R8-R11=values to call the sub in R1 with on the first call.
	\X R0=pointer to wimp menu structure
	The sub passed in R1 has the following conditions:
	     \E R0=buffer for you to put the next menu entry in (48 bytes)
		R5=address of menu structure start }
		R6=address of current menu entry   } you don't need these
		R7=address of current buf entry	   }
		R8-R11=as returned from last call
	     \X R0=index for this entry/-1 if no more entries (see E-Menu)
		R1-R7 saved
		R8-R11=updated (ie for your own use).

Zap_ClearSel
Clears currently selected area.

Zap_CreateFileBlock
Creates a new file block with currently configured options. f_ptr etc are set
up for you. See E-File. Use Zap_Install file to load a file.
	\E R0=size to make buffer
	   R1=filename of buffer
	   R2/R3=load/exec
	\X R9=new file block (with file filled with rubbish).

Zap_CreateWindBlk
Creates a new window block with currently configured options. Window is
opened on the screen etc.
	\E R9=file window is to be on.
	\X R8=New window on this file.
	   R0=Block of info on the mode used (see Zap_WhichMode).

Zap_GetSel
Find out what area is selected.
	\X If CS then no valid selection.
	   If CC then R1=file offset R2=selection length R8/R9=file.

Zap_InsertMark
Insert a marker.
	\E R0=file offset of mark R8/R9

Zap_InstallFile
Load a file into zap.
	\E R0=filename
	\X R0=window offset of created window / -1 if not loaded.

Zap_NewMode
Change the display mode of a window.
	\E R0=new mode number R8/R9 (R8=0 to change options mode)

Zap_NewTitle
Update the titlebar on a given window. See also Zap_NewFileTitle.
	\E R8/R9

Zap_CallBaseMode
DO NOT USE THIS. This call is now obsolete. Use the call Zap_BaseMode
instead. If you use this call it will appear to work perfectly until someone
tries to use your mode as a base mode. When this happens an infinite loop
occurs which I can't fix. The docs are kept for backwards compatibility.
--------------------------------------------------------------------------
As for Zap_CallMode except it calls the base mode instead. The window in R8
identifies the current mode. The entry point called is that of the base mode
associated to this current mode. Hence, it would be used by a mode to call
a base mode entry point which the current mode has redefined.
	\E R0-R10=parameters R8 R11=mode entry point offset (see E-Entry)
	\X As for the given mode entry point.

Zap_NewView
As for Zap_CreateWindBlk but 'clones' a given window image. The cursor is not
put in the window.
	\E R8/R9=window to clone from (R8=0 then don't clone)

Zap_ReadSel
Reads the currently selected region into a heap block. You must free the heap
block when you have finished with the selection.
	\X R3=heap block with data and R2=length / R3=0 if no selection

Zap_Replace
Calls the Zap file search and replace code using the current search string
and current replace string.
	\E R1=0 for selective/1 for global
	   R3=start offset in file
	   R4=direction (+1/-1)
	   R5=search flags (as for Zap_Search)
	   R8/R9=current window

Zap_Search
Calls the Zap wildcard search code.
 \E R0=pointer to search string
    R1=output 0=to cursor 1=to buffer 2=no output 3=count
       OR &100+offset of throwback window to add search matches to.
    R3=start offset of the search (in the file)
       (NB The first offset actually tested is R3+R4 so use R3=-1 to search
	from the start of the file).
    R4=search direction +1/0/-1; if 0 the given offset only is examined.
    R5=search flags b31=set for a raw search (don't search by lines)
		    b30=set if case sensitive
		    b29=set if macros shouldn't be expanded
		    b28=set if \commands should be ignored (and `s etc)
		    b27=set to search all windows (move to next one after)
		    b26=don't update hourglass in search_text
		    b25=don't beep if no match found
		    b24=return end of match offset in R1 (if one found)
		    b23=rsvd (search_init sets if wild_conv_chars found \s)
		    b22=don't display hourglass percentage if set
		    b21=ignore supplied R3/R4; try to match at cursor/point
    R8/R9=current window of search
 \X If R1=0 or 1 then output displayed
    If R1=0 or 2 then R0=match offset on exit / -ve if none
    If R1=1 then R0=offset of throwback window / -ve if none
    If R1=3 then R0=number of matches
    R1=offset of end of match (if b24 of R5)

Zap_Select
Selects a given region, and puts carets back to default mode.
	\E R2=start offset R3=end offset R8/R9

Zap_AlterSel
As for Zap_Select but doesn't restore caret modes.
	\E R2=start offset R3=end offset R8/R9

Zap_OffLineCol
Converts a file offset to an x,y coordinate pair in the window work area. See
also Zap_FindOffset. See E-Windows.
	\E R0=file offset R8/R9
	\X R0=start of line offset
	   R2=column (inc margin)
	   R3=row

Zap_AddCommands
Adds a table of commands to zap's list. Zap can currently cope with up to 32
tables of commands. This should be called when a module initialises as for
Zap_AddMode. Zap need not be mapped into memory for this call. See E-Commands
for the table format.
	\E R0=address of command table (R12=Zaps workspace).

Zap_MiniWrite
This call sends a stream of characters to the minibuffer. The minibuffer
contents is changed but not updated on screen. However, if this call is used
within a command, then the minibuffer will updated on screen automatically
by Zap. Use Zap_MiniUpdate to force an update, but you shouldn't have to use
this. The minibuffer takes the form:
	<prompt string><mark><user editable field>.
The user cannot move the cursor before the 'invisible' mark. The string
passed to Zap_MiniWrite may contain the following control codes:
	0=string terminator
	1=move cursor to mark (ctrl a)
	2=8=move cursor back one character (ctrl b)
	4=delete character after cursor (ctrl d)
	5=move to end of string (ctrl e)
	6=9=move cursor forward one character (ctrl f)
	11=clear buffer from cursor (ctrl k)
	12=clear whole buffer (ctrl l)
	21=clear buffer from mark (ctrl u)
	28=set mark to current cursor offset
	127=delete character before cursor
When a command with string parameter is called, R0 points to the user
editable part of the string. (See also Zap_MiniWriteToken.)
	\E R0=pointer to zero terminated string

Zap_MiniPrompt
This replaces the prompt string in the minibuffer with the given string. It's
main use is for reason code R2=6 when a command with string parameter is
called (see E-Commands). The buffer is not updated on screen (see
Zap_MiniWrite). Unlike Zap_MiniWrite, the minibuffer cursor is not affected
by this call (It remains the same number of characters after the mark).
": " is automatically appended (taking note of whether the string already
ends with ": ").
	\E R0=new prompt string

Zap_MiniUpdate
This call updates the minibuffer on screen (if open). This will usually be
done automatically by Zap.

Zap_AddYankRegion
This call adds a region to the cut/paste kill ring. The region you pass it
is not copied so must be stable (eg in a heap block).
	\E R0 = address of region:
	   R1 = block length + flags
		b31 MUST BE SET (If clear then denotes an undo buffer ref).
		b30 If set, then after yanking this block, it will move onto
			the block before (ie, yanks many blocks at once).

Zap_FindCommand
This call converts a command name into a command address by looking it up
in Zap's command tables. If the command is in an extension module then that
module is loaded as well.
	\E R0=command name terminated by <=32 or :,&,"
	\X R0=command address / 0 if not found

Zap_ProcessCommand (see also Zap_CommandString).
 This makes a call to a Zap command. It should be used for all calls to
commands. You can find the address of a command via Zap_FindCommand. You
may also call commands which may not have a name - it just considers the
command address.
 The data the command takes is pointed to in R0. The data format depends on
the command. It should point to a list of bytes/word or a string depending on
whether the command takes a byte/word or string parameter. It is undefined if
the command takes no parameter. See E-Commands for more details. Put R0=0
instead of the pointer to a string to open the minibuffer instead.
 The number of times the key has 'auto-repeated' is passed in R1. This will
be the length of the byte/word list if the command takes byte or word
parameters. Usually put R1=1.
 R2 holds the action code of the command. Action code 0 executes the command.
The other action codes are used to read information about the command and are
mainly used internally by Zap. See E-Commands for the details.
 NB The mode e_aligncaret entry point will be called before all command calls
using R2=0,1 on entry.
 \E R0=pointer to command data (0 if there is no data)
	   R1=length of the command data if byte or word list (in bytes or
	      words). Number of times key has auto-repeated otherwise.
	   R2=Command action code:
		b0-b23 = Action code to be passed to the command. 0 to
			 execute it - see E-Command.
		b24-b31= Flags to tell Zap_ProcessCommand things. These are
			 filtered out before R2 is passed to the command.
			 b31=Set if command should not be learnt even
			     if in learn mode.
			 b30=Internal use; must be 0
			 b28-29 reserved
			 b24-27=parameter type
				(use R6 returned by Zap_ReadValidateCommand)
		    command table, but must conform to the specs in the
		    file E-Command. Eg, [R7,#-4] must be the flags word).
	   R8=window block pointer or 0 if none applicable (options menu)
	   R9=file block pointer or 0 if none applicable (options menu)
	   R10=input cursor (or cursor you wish command to act on) or 0
	       if not applicable.
 \X R1-R13 preserved.
    If action code=0 on entry then R0=0 or -1 if minibuffer opened.
    If action code>0 on entry then R0=value in R0 when command returned.

Zap_FindKeyEntry
This finds the entry corresponding to a given key and keymap. You might use
it for redefining the key for instance. The block pointed to on exit has the
format:
	#0 Command address (or 0 if none - key is passed on to wimp)
	   (The module containing the command is loaded if necessary).
	#4 Command parameter, this depends on the command flags b3-7. If
	   these bits are:
	   0   => #4 undefined (should be 0)
	   1/2 => #4 is the byte or word to be added to the list to be
		  passed to the command when the key is pressed.
	   3   => #4=address of string parameter /0 if minibuffer should be
		  used.
	   4   => #4=address of the data block.
	#8 Command parameter type
	   As for b3-5 of command flags word, with 8=int expr 9=str expr
	\E R0=keymap number R1=zaps key number (0-&1FF)
	\X R0=entry for this key / 0 if keymap does not exist or key is
	   out of range.

Zap_FindLeafName
This works out which part of a filename is the leafname.
	\E R0=filename pointer
	\X R0=pointer to the leafname part (within the filename).

Zap_NewFileName
Change the name of a given file. You may have to call Zap_NewFileTitle to
update the titlebars (this will usually be done by Zap_SaveFile).
	\E R0=new file name R9
	
Zap_CheckFileName
Decides whether a filename is a full path name (eg "ADFS::$.Wibble") or just
the leaf name of a file (eg "Text1"). Should be used in conjunction with
Zap_SaveFile as this will not save files without full path names.
	\E R0=filename
	\X R0=0 if it is a full path name / 1 otherwise

Zap_GetCurrDir
Returns current directory (of the temporary filing system) which should be
used as default string in minibuffer file operations. On RISC OS 2, there is
no way of reading the current directory so this call returns the root
directory on the current disc (via OS_Args 0, OS_FSControl 33, OS_GBPB 5). On
RISC OS 3, the current directory is read via OS_Args 0, OS_FSControl 33, and
OS_FSControl 54. NB The block it is returned in is not stable over calls to
Zap. You may call Zap_MiniWrite passing this block but should copy the
string for other calls.
	\X R0=pointer to 256 byte buffer containing the directory name

Zap_MiniWriteC
Writes a single character to the minibuffer. See Zap_MiniWrite for the
character codes.
	\E R0=character to insert in minibuffer.

Zap_MiniClear
Clears minibuffer contents without updating on screen. Resets marks etc. You
should use this before using Zap_MiniStart.

Zap_MiniStart
This starts up the minibuffer. Do not use this call when writing a Zap
command. Read the file E-Command to see how the minibuffer works in this
case. You never need this call, Zap_ProcessCommand can open a minibuffer at
any time if you feed it a string type command and R0=R2=0.
	\E R7=address of command to be called when return pressed in
	   minibuffer. [R7,#-4] must contain the command flags word as
	   documented in E-Command.
	   R8/R9=window minibuffer should appear at.

Zap_MiniEval
This turns a string into a number via OS_EvaluateExpression. It is usually
called near the start of a command which expects to find a number in the
minibuffer.
	\E R0=string pointer (usually minibuffer pointer passed to you)
	\X R0=number stored in string/CS if not a valid number.

Zap_CommandString (see also Zap_ProcessCommand)
This call takes a command (or colon separated list of commands) in string
form and executes them as typed. For example if R0="MODE 0" on entry then
first of all a call to Zap_FindCommand will be made to find the address of
the command "MODE" and then the command will be called via
Zap_ProcessCommand with R2=0.
	\E R0 = command string (zero terminated)
	   R1 = flags
	        b31 set if you don't want the commands to be learnt even if
	            in learn mode.
	\X R0 = 0 or -1 if the minibuffer has been opened.

Zap_ProcessKeys
This entry point accesses Zap's main key handling sub so you can simulate
keypresses. If you just wish to simulate one key press, then it is easier to
use the next call. This call is for multiple keypresses and buffers the data
as much as possible before it has to call a command. You must keep calling
this command until it returns R0<0 (as it will do if you put R5=-1 on entry -
it uses the R5=-1 call to execute the buffered data).
	\E R0=zap key number of next key to execute (if R5>=0)
	   R5=-1     => there are no more keys to buffer (R0 not defined).
	      0-&1FF => wimp key number of key to send to Wimp_ProcessKey
			if no command is attached to the key.
	      &200   =>	if Wimp_ProcessKey should never be called.
	   R6=length of current buffering (set to 0 on first call)
	   R7=command currently being buffered (if R6>0)
	   R8-R10=input cursor
	\X R0>=0 if you should call this sub again with the next key (or
	      R5=-1 if there are no more).
	   R0<0 if the command has finished processing all buffered data
	      so you needn't call it again.
	   R6/R7 are updated for the next call.

Zap_ProcessAKey
This command simulates a key press by calling the above command twice, once
with the key and then once with R5=-1.
	\E R0=zap key number
	   R5=wimp key number (see Zap_ProcessKeys)
	   R8-R10=input caret

Zap_OpenWindow
The current position of a Zap window can be read easily using the code:
 MOV R1,R8 : SWI "XWimp_GetWindowState". However, you should not call
Wimp_OpenWindow to open a window as Zap has to keep track of the title length
and position of the minibuffer etc. You should use this call instead. Use
call 0 where possible as it prevents titlebar flicker.
	\E R0=type of open:
		0 => Just changing scroll offsets or height in window stack.
		     Size/position of window NOT changing.
		1 => Window may move/change size. Minibuffer, title bar
		     and cursors dealt with accordingly.
		2 => Window is a new window. Toggle size data etc reset.
		3 => Bring window to front of stack (ignore R1)
		4 => Put window to back of stack (ignore R1)
		5 => As for 0, but cursor kept within the window if the
		     'constrict cursor' option is on.
		(NB type 2 calls type 1 calls type 5 calls type 0)
	   R1=open block (as for Wimp_OpenWindow)
	   R8=window block (NB Usually alter this block and let R1=R8)

Zap_RestoreModeWord
This call should be used by your e_start entry point. If R8<>0 on entry then
it reads the reads the options for the given mode from w_datablock using the
call Zap_ModeData, and sets them as the current options. If R8=0 then it does
the same thing but sets the default options.
	\E R0=mode number
	   R8=window to restore options on / 0 for the default options.

Zap_SaveModeWord
This call should be used by your e_end entry point. If R8<>0 on entry then it
reads the words w_flags and w_format and stores the current options in the
w_modedata block by use of the call Zap_ModeData. If R8=0 on entry then it
reads opt_flags and opt_format and stores them as the default option etc.
	\E R0=mode number
	   R8=window to save options on / 0 for the default options.

Zap_GetModeWord
This call reads the contents of your mode word. If R8=0 then it reads
opt_mode<n>, otherwise it reads [R8,#w_mode<n>]. This is useful for menu
options.
	\E R1=mode number
	   R8=window to get mode word / 0 for default options mode word
	\X R0=mode word contents.

Zap_PutModeWord
As above, but write the value.
	\E R0=new value for the word
	   R1=mode number
	   R8=window to put mode word / 0 for default options mode word

Zap_BaseMode
This call replaces Zap_CallBaseMode. It differs in that you must specify
which mode is calling. This information is not necessarily available from
the block in R8 if another mode is based on yours. The basemode of the mode
named in R9 is called via the entry point offset given in R11. Before the
entry point is actually called, R9 is converted to the file block pointer
of the window specified in R8. Hence any entry point requiring R8 and R9
set up on entry can be called ok.
	\E R0-R7=parameters for the call
	   R8=window block to be used by the call.
	   R9=mode number making this call (your mode number).
	   R10=parameter for the call (usually cursor block pointer).
	   R11=mode entry point offset (see E-Entry) to call.
	\X As for the given mode entry point.

Zap_ReadWord
This call can be used for reading 4 byte from a file buffer. Note that
although the offset of the word in the file may be word aligned, it's offset
in the buffer may not be due to the split. This call reverses the word if the
Big Endian flag is set.
	\E R0=File offset of the word to be read
	   R8=window (for big endian flag to be read)
	   R9=file
	\X R0=the word read (padded with zeros if it went off the file end).

Zap_ReplaceWord
This call replaces a word at the given file offset (inserting if the file
offset+4>file length) via Zap_Command. The word is reversed if the big endian
flag is set.
	\E R0=word to replace
	   R1=file offset
	   R8/R9 (R8 used for the big endian flag).

Zap_ModeColour
This call reads or writes the colour definition table. It will not usually
have immediate effect unless you recreate the window (eg Zap_NewWinStatus).
You shouldn't usually access this data as Zap handles it all for you, except
to write sensible default values (using R8=0) if your mode starts up and
finds its mode word is zero.
	\E R0=colour to write:
	      -1   => Don't write anything (just read the value)
	      b0-b7 <16 => Write this wimp colour (converting it to RGB)
	      b0-b7 >15 => Write 24 bit colour of the form &BBGGRRZZ
			   where ZZ is the Zap style:
			   Bit 4=1
			   Bits 5, 6 and 7 : sub-style:
				bit 5 : Bold
				bit 6 : Italic
				bit 7 : Underlined
	   R1=mode number
	   R2=Zap colour number of the colour to write/read:
	      0/1=Background 2=Foreground 3=Selection background
	      4=selection foreground 5=cursor back 6=cursor for
	      7=line numbers 8=control chars
	      9+ mode dependent extension colours.
	   R8=Window block to read from / 0 for default (!Config) settings.
	\X R0=colour value read / old value if writing it. This is of the
	      form &BBGGRRZZ as above.

Zap_FindInput
This call works out the current position of the 'input focus' in a window. If
the input caret is in this window then it returns it's offset. Otherwise it
returns the 'point' position (usually marked by an empty square).
	\E R8/R9
	\X R0=most suitable offset to insert data.

Zap_ClipCache
This call moves the cache reference point (w_cline/coff/clogl etc) to a given
point (using e_clnoff).
	\E R0=Offset in line to move the cache reference point to. R8/R9

Zap_ModeData
This call reads or write the mode dependent options that Zap handles
automatically for you. See also Zap_ModeColour. Currently there is only one
word per mode storing the width and things like whether auto-indent is on or
not. You should use this call with R8=0 to write sensible default values if
your mode starts up and finds its mode word is zero. If you don't then the
default Text mode values will be used.
	\E R0=value to write / -1 to read
	   R1=mode number
	   R2=variable number to read write
	   R8=window concerned / 0 for the default (!Config) settings.
	\X R0=variable value if read / old value if written
	Variables num:	0	b0-b15  stores the "width" for this mode
				b16	auto indent bit     (w_format b16)
				b17	auto width bit      (w_flags  b6)
				b18	strip spaces bit    (w_format b18)
				b19-b21 tab mode bits       (w_flags  b9-11)
					b19-b20 0=Unix 1=Edit 2=Coltab
					b21=insert tabs as spaces
				b22	hex entry mode bit  (w_flags  b5)
				b23	overwrite bit       (w_flags  b1)
				b24-b31	display bits        (w_format b8-15)
					b24=line numbers shown
					b25=line numbers as lines (not addr)
					b26=line numbers in hex
					b27=logical line nums (not physical)
					b28-29 0=no tabs 1=spaces 2=> 3=->
					b30=line edit paradigm
					b31=non standard editing
			1	b0-b2	Line number width
				b3	Line number colons
				b4	Internal use : font sub-styles off
				b5	Infinite window wrap
				b6	Use line selection paradigm
				b7	Spell-as-you-type
				b8	Big endian	    (w_format b17)
				b9	Strong soft wrap
				b10	Block edit
				b11	Reserved
				b12	Set if linewrap mode on	(w_flags b26)
				b13	Set if wordwrap mode on	(w_flags b13)
				b14	Reserved
				b15	Reserved
				b21	Free mouse clicks   (w_format b21)
				b22	Auto soft wrap	    (w_format b22)
				b23	Confined cursor U/D (w_format b23)
				b24	Confined cursor ->  (w_format b24)
				b25	Smart shift-cursor  (w_format b25)
				b26	Window-wrap	    (w_format b26)
				b27	Soft-wrap	    (w_format b27)
				b28	Buttons enabled     (w_info b12)
				b29-b31 Buttons bits	    (w_info b13-b15)
				...other bits reserved...
			2	b0-7	Reserved (was base keymap number)
				b8-15	Display colour block number
				b16-23	Printer colour block number
				b24-31	Number of colours per block
			3	b0-7	Number of extra system colours
				...other bits reserved...
			4+	reserved.

Zap_WhichMode
This call decides which mode a given file should be displayed in.
	\E R0=load address of file (containing the filetype)
	   R1=filename pointer / 0 if not known
	   R2=flag to determine the meaning of R10 on exit
	\X R0=address of a data block of info about this file mode. 
	   R10=If R2 was 0 on entry then this is the mode number
	       of the default mode the file is loaded into (the mode is
	       loaded if necessary). If it was non-zero then this is a 
	       pointer to the mode name (mode not necessarily loaded).

Zap_ModeNumber
This calls turns a mode name (given by a string) into a mode number. The mode
is loaded if not already resident in memory.
	\E R0=mode name string terminated by <= space (&20)
	\X R0=mode number or -1 if not found.

Zap_SendDataSave
This call initiates the save protocol, saving data to another window or
application via RAM transfer or WimpScrap. It sends the data_save message and
all replies are handled automatically.
	\E R2=proposed file/leaf name of the data (or 0 to use the file's)
	   R3=destination window handle or task handle
	   R4=destination icon handle (if R3=-2)
	   R5/R6=destination mouse coords (if applicable)
	   R7=routine to call after save finished (or 0 if none).
	   R8/R9=R8<>0 => Save whole file R8=window block R9=file block
		 R8=0  => Save currently selected region.
		 (or set b1 of R10 to save an arbitrary region).
	   R10=b0-b15 flags:
	       b0 set => External edit flag. In this case R3=ext edit
			 job handle and R4=ext edit task handle and
			 external edit message sent instead.
	       b1 set => R8=start address of data to save
			 R9=size of the data to save
			 b16-b31 of R10=filetype of data to save.
	       b16-b31 = extra data (see b1)
	   R11=data to pass to routine in R7 (if used).
	\X Data transfer protocol initiated.
	Sub pointed to by R7 is called with R11 as passed above and should
	preserve R1+ as usual.

Zap_Warning
Warns the user without generating an error. This opens a window with the
given message and pauses for the message to be seen before returning. Wimp
Poll is not called.
	\E R0=warning message
	   R1=time to leave message open in cs (0 for default delay)
	      + flags:
		b31 => Don't beep when opening the window
		b30 => no "Warning: " prefix.
		b29 => call Zap_LookupTokenR0 first
	   R4-R7=parameters for %0..%3 (if R1 b29 set)
	   R8/R9=window in which to show the warning.

Zap_AllWindow
Calls a given subroutine once for each valid Zap window. See also
Zap_EachWindow.
	\E R0-R7=arguments to pass to the sub
	   R10=address of the sub to call (which must preserve all registers
	       except R0, and is called once for each window with R8/R9
	       set up to be that window).

Zap_ReadMenu
Converts a text file of the same format of Zap's 'Menu' file into a Zap menu
structure.
	\E R0=start of a zero terminated menu text file (stored in memory)
	\X R0=pointer to heap block containing the following information
		#0 Number of valid menu handles for this file (first
		   number appearing in the file)
		#4 Pointer to the menu structure (in Zap-Wimp format) for
		   handle 0 (or 0 if handle 0 not used)
		#8 Pointer to structure for handle 1
		#12 Pointer to structure for handle 2 etc.

Zap_LoadMenu
Converts a text menu file to a Zap menu structure.
	\E R0=pointer to filename of the menu file
	\X R0=list of menu handles as for Zap_ReadMenu

Zap_OpenMenu
Opens a menu on the screen. The menu structure is handled automatically once
it has been opened.
	\E R1=pointer to Zap-Wimp menu structure
	   R2=mouse x to open at
	   R3=mouse y to open at
	   R8/R9=window the menu is being opened on or 0's for none (eg the
		 iconbar menu).

Zap_CallBack
Schedules a subroutine to be called again at a certain time but using wimp
null events.
	\E R1=(earliest) monotonic time to call back at (>0)
	      or -(smallest delay before calling back) =< 0.
	   R2=address of routine to call.
	   R3=data to pass to the routine in R11.
	The routine pointed to by R2 has conditions:
	 \E R1=current time R11=value passed in R3
	 \X (must save R1+ as usual)

Zap_DragBox
Starts a wimp drag box making sure you get called when it's finished.
	\E R0=b0 set if you wish to be called repeatedly during the drag
	      b1+ reserved (set to 0)
	   R1=drag box block to be passed to Wimp_DragBox
	   R2=address of routine to call.
	   R3=data to pass to the routine in R11.
	The routine pointed to by R2 has conditions:
	 \E R0=reason code 1=drag in progress 2=drag has just finished
	    R1=drag box posn as returned by wimp if R0=2
	    R11=value passed in R3
	 \X (must save R1+ as usual)

Zap_SendMessage
Sends a wimp message and logs the message number (my_ref) so that any reply
can be forwarded to you. The message reference is held for at least a minute
and only deleted on a null event.
 E R0=b0-b27 message action number (to go in R1,#16)
      b28    set if you are interested in the reply.
      b29    set if you want to be called when message deleted
      b30-31 00 => Just send the message (with code 17)
	     01 => Just acknowledge the message (with code 19)
	     10 => Send the message recorded (with code 18) and call the
		   reply code if the message replied to.
	     11 => Send the message recorded (with code 18) and call the
		   reply code if the message replied to or bounces.
   R1=message block
   R2=dest task handle/window handle
   R3=b31 clear => This is the message length (is rounded up to next word)
      b31 set	=> This is the offset of a string ending the message.
   R4=icon handle if R2=-2 (iconbar) [not used otherwise]
   R5=address of routine to call when message replied to [if b28 of R0]
      (zero as a value means that you want any replies to be dealt with
       as if they were normal messages and not a reply)
   R6=private word to pass to routine on a reply [if b28 of R0]
 X The message is sent as an original message. Hence the my_ref, length
   and message action fields are filled in for you. R0=task handle of the
   dest task (R2 on exit from Wimp_SendMessage)
	Routine in R5 called with:
		;E R0=message type
			0 => message being removed from log list (see b29)
			17 => message replied to as normal
			19 => message bounced
		   R1=message block
		   R2=message number (R1!16) R11=private word R12=Zap's etc
		;X You can corrupt R0-R11 if R0=17,19
		   You should save R1-R11 if R0=0

Zap_Reply
Replies to a message. It copies my_ref to your_ref for you can reads the task
handle of the task to reply to from the message block. The length word is
assumed to be unchanged.
 E R0=message action number (as for SendMessage)
   R1=message block (with ref etc)
   R5/R6=routine to handle the reply if b28 of R0 (as for SendMessage)

Zap_Extend
Changes the size of a heap block, making it smaller or bigger as for OS_Heap
with the extend action code.
 \E R0=pointer to the heap block R1=signed change in the size
 \X R0=new heap block pointer (it may have moved)

Zap_ModeColourNum
Reads/writes the size of the colour palette used by a given mode. Maximum
size of a palette is currently 256 colours. Use R8=0 to read the default
values. NB If you enlarge the palette then please write some sensible values
for the new entries!
 \E R0=new size of palette (in number of colours) / -1 to read
    R1=mode number R8/R9=window or R8=0 for the default options.
 \X R0=old size / read size.

Zap_CreateThrowback
Creates a throwback buffer ready for lines being inserted by Zap_Throwback.
 \E R0=suggested width of window / 0 to use default width
       b31,30 = 01  R1 = task handle
	      = 10  R1 = filename
	      = 11  R1 = name token
       b29 set	    R2 = list of those tokens which the mode supplies to
			 Zap_Throwback for use at various line starts. Note
			 that codes < 32 are *not* ignored.
			 Format: each entry consists of
				+0  0
				+4  Throwback colour number
				    + special value in top 4 bits
				+8  Token name (NUL term, padded to align)
			 The list is terminated by 0,0,<anything>.
			 The special value must be either 0 or 6; set it to 6
			 if the colour must be reset after a colon.
 \X R0=window offset of window R8/R9=newly created throwback window

Zap_Throwback
Inserts a line in a throwback file for you.
 \E R0=file offset or line number of line with info on it
       set b31 to suppress this being printed automatically.
    R1=filename (of the file that R0 is an offset in)
    R2=information string to print after the line number (eg "Bad syntax")
       b31 set if this is a MessageTrans token
    R3=string to precede filename  (eg "Errors in file:")
       b31 set if this is a MessageTrans token
    R4=file offset of linked file / -1 if may not be loaded
    R5=flags to use for the new entry (see f_links,#12)
    R6=string to precede new info block (eg "Line num  Error")
       b31 set if this is a MessageTrans token
    R7=string to go after filename (eg 10,"Search string: fred")
       b31 set if this is a MessageTrans token
    R8/R9=throwback window to add entry to
    (MessageTrans tokens: no GS translation, no parameters.)
 \X Throwback entry added and new title block given if file (or flags)
    have changed KB #
    The line number field is 10 characters wide if not suppressed.

Zap_TestModeName
This calls determines whether or not a given mode is loaded. It returns
the mode number of the given mode or -1 if the mode is not loaded.
	\E R0=mode name string terminated by <= space (&20)
	\X R0=mode number or -1 if not loaded.

Zap_UpdateArea   *** DEPRECATED
Forces an immediate redraw of a window area. The area in given in x,y
character col, row coordinates.
	\E R1=redraw block (as for Wimp but in character coords -
	      ie window handle, min x col, min y row, max x col, max y row)
	   R8/R9 = window
	\X Coordinates in R1 changed to OS coords and window updated

Zap_UpdateWindow    *** DEPRECATED
Forces an immediate redraw of a window area. Entry and exit as for
Zap_UpdateArea except that coordinates are given in Window work area
OS coords. (Internally UpdateArea calls UpdateWindow after coordinate
conversion).

Zap_UpdateWholeWindow
Force immediate update of the text cache and redraw of the window.
	\E R8/R9 = window

Zap_AllFiles
Calls a given subroutine once for each valid Zap file. See also
Zap_AllWindows and Zap_EachWindow.
	\E R0-R7=arguments to pass to the sub
	   R10=address of the sub to call (which must preserve all registers
	       except R0, and is called once for each file with R9 set up
	       and R8 = 0.

Zap_ReadValidateCommand
Translates a string into an executable block of command information.
	 E R10=pointer to string terminated by <&20
	 X R0=-1 => args invalid (only tested if command loaded)
	      0  => all ok
	      1  => args valid for keymaps only (uses n form)
	   R1=parameter
	   R6=parameter type 0=none 1=num 2=usekeynum 3=stringblock 4=data
			     8=int expr 9=str expr
	   R7=command address
	   R10 updated to next non-white space which is not a ':'
	   CS if an external module has been loaded as a consequence
	   CC otherwise.
	   Error is generated if the command cannot be found.
	   (String of commands concatenated to a single Multicommand)
	   (:<return> skipped so can have multiple lines)

Zap_ProcessKeyCommand
Calls a command using the same routine as used when a command is bound to a
key.  For use mainly with Zap_ReadValidateCommand.
	 \E R0=data => The byte/word if mode 1/2 and ptr to data if mode 3+
	    R2=Command action code:
		b0-b23 = Action code to be passed to the command. 0 to
			 execute it - see E-Command.
		b24-b27= parameter type
			 (use R6 returned by Zap_ReadValidateCommand)
		b28-b31= 0
		(Bits 24-31 are filtered out before calling the command.)
	    R7=command address
	    R8-R10=window/file/cursor or 0
\X Command called once with R1=1

Zap_ReturnWord
Calls the text mode e_returnword entry with given delimiters. This is
mostly of use to commands such as SelectUntil. 
	\E R0=flags
	      b0 => list are non-delimiters not delimiters
	      b1 => control characters form an implicit list
	      b2 => control characters are non-delimiters not delimiters
	   R1=list (can include ranges, eg: "A-Za-z_" or "A-Z-") 
	   R8-R9
	   R2=offset to pass to e_returnword as R0
	\X R0=file offset
	   R1=length

Zap_DoReplaceArea
Acts like Zap_ReplaceArea, only does not involve the mode, i.e. it uses
Zap_DoCommand, rather than Zap_Command.
	\E R1=file offset of original data
	   R2=length of original data
	   R3=address of replacement data
	   R4=length of replacement data R9
Calls Zap_ReplaceArea with R8=0

Zap_LogicalLine
Replaces e_clnlog in a manner which allows processing of the returned
parameters.  Entry and exit conditions are exactly as for e_clnlog:
	\E R0=logical line number R8/R9
	\X R0=file offset of line start
	   R1=physical line number

Zap_PhysicalLine
Replaces e_clnphy in a manner which allows processing of the returned
parameters.  Entry and exit conditions are exactly as for e_clnphy:
	\E R0=physical line number R8/R9
	\X R0=file offset of line start
	   R1=logical line number

Zap_OffsetLine
Replaces e_clnoff in a manner which allows processing of the returned
parameters.  Entry and exit conditions are exactly as for e_clnoff:
	\E R0=file offset R8/R9
	\X R0=physical line number
	   R1=file offset of physical line start
	   R2=logical line number

Zap_NextLine
Replaces e_nextline in a manner which allows processing of the returned
parameters.  Entry and exit conditions are exactly as for e_nextline:
	\E R0=file offset of first 'shiftable' character
	   R1=signed change in file offset of this character R8/R9
	\X R0=file offset of first 'shiftable' line
	   R1=physical line number of this line #
	   You must preserve the split offset and split size of the file.

  Note that in the above four calls, the mode called is the mode specified by
  the window block in R8.  Calling the entry points of arbitrary modes is
  currently only possible with this mechanism by manually poking the required
  mode number in temporarily.

  Generally, these calls should be used in place of their low level
  equivalents in extension modules.

Zap_EvaluateExpression
Evaluates the supplied string via OS_EvaluateExpression, after parsing and
evaluation of any Zap functions that it may contain; for example, the string
"@MODEN LEFT 3" will return the leftmost three characters of the mode name as
a string.
	\E R0=zero terminated string (the expression)
	   R1=maximum length of result, if string (0 if you want int only)
	\X R0=0	      / address of string (in Zap's heap) / error
	   R1=integer / length of string		  / undefined
	   VS on error

Zap_ClaimMessage
Claims and forwards the next receipt of a given message. The claim is held
until it has been successfully forwarded (or an error occurs when a potential
claimant is called).
	\E R1=message number
	   R2=address of routine to call when message received
	   R3=private word to pass to routine
	      You should store sufficient data here in order that the routine
	      can check whether it's actually interested in this message and
	      return quickly if it isn't.
	\X Claim is logged; R1 corrupt.
		Routine in R2 called with:
		\E R1=address of message block
		   R2=message number
		   R11=private word R12=Zap's workspace
		\X R0=0 if uninterested; claim remains logged
		   R0<>0 if interested; claim removed from log
		     The routine must do any necessary processing of the
		     message before returning.
		   VS on error; claim removed from log

If the return type is string, then it is up to the calling code to free the
heap block at R0.

Zap_TestChanged
Tests to see if a file is modified, allowing for the possibility of "possibly
modified"; if the file is in this state (ie. >=16K, has its original length,
and is marked as modified) it will calculate the checksum to determine
whether the file is actually modified.
	\E R9=file
	\X R0 corrupt
	   Z set if file is unchanged

Zap_MarkChanged
Marks the file as changed or unchanged, recalculating the checksum
automatically.
	\E R0=0 (unchanged), <>0 (changed)
	   R9

Zap_CalculateChecksum
Calculates the checksum for the file.
	\E R9
	\X R0 = checksum for the file.

Zap_LookupToken
Looks up a token, placing the result in the supplied buffer; parameter
substitution is performed, and the string will be NUL-terminated. If no
buffer is supplied, then no substitution can be done and the string will be
LF (or possibly CR) terminated. (Uses MessageTrans_Lookup.)
	\E R1=token
	   R2=buffer (or 0 to use none)
	   R3=maximum length (ignored if R2==0)
	   R4-R7=parameters for %0..%3
	\X R1=token terminator
	   R2=result string
	   R3=length (exc. terminator)

Zap_LookupTokenGS
Looks up a token, placing the result in the supplied buffer; parameter
substitution and GS translation (eg. '|J' -> LF) is performed, and the string
will be NUL-terminated. If no buffer is supplied, then no substitution can be
done and the string will be LF (or possibly CR) terminated. (Uses
MessageTrans_GSLookup.)
	\E R1=token
	   R2=buffer (or 0 to use none)
	   R3=maximum length (ignored if R2==0)
	   R4-R7=parameters for %0..%3
	\X R1=token terminator
	   R2=result string
	   R3=length (exc. terminator)

Zap_LookupError
Looks up a token, placing the result in the supplied buffer or in a default
buffer. (Uses MessageTrans_ErrorLookup.)
	\E R0=error block containing the token
	   R2=buffer (or 0 to use default)
	   R3=maximum length (if R2<>0)
	   R4-R7 -> parameters for %0..%3
	\X R0=pointer to error buffer
	   V set

Zap_LookupTokenR0
Look up token, performing no GS translation or parameter substitution. (This
is equivalent to Zap_LookupToken with R2=0.)
	\E R0=token
	\X R0=string (LF terminated), or token if not found

Zap_ExpandMenu
This builds a Zap relocatable menu, which can be linked in for Zap to use
automatically for your mode by calling Zap_ReadMode then writing the menu
address to [R1,#2*e_menu]. The width is calculated automatically; if writable
items are present, they are ignored (not expanded) and are assumed to be of
the supplied width.
	\E R0=pointer to tokenised menu
	   R1=submenu handler subroutine (0 = use Zap_ExpandMenu)
	   R2=module base address
	\X R0=expanded menu
The subroutine pointed to by R1 is called whenever a submenu is found and the
warning flag is not set for it. It has the following conditions:
	\E R0=pointer to submenu
	   R1,R2 unchanged
	\X R0=expanded menu, or 0
The tokenised menu closely resembles the relocatable menu format (see
E-Menu), the differences being that all strings are MessageTrans tokens
except when *started* with a NUL (in which case a string literal follows,
unaligned), and the menu title is of variable length (to accomodate long
token names). No GS translation and no parameter substitution is performed.

Zap_MiniWriteToken
A MessageTrans token-using version of Zap_MiniWrite. GS translation is
performed (see Zap_LookupTokenGS).
	\E R0=token
	   R4-R7=parameters for %0..%3

Zap_MiniPromptToken
A MessageTrans token-using version of Zap_MiniPrompt. GS translation is
performed (see Zap_LookupTokenGS).
	\E R0=token
	   R4-R7=parameters for %0..%3

Zap_TestIfCloneBase
Tests to see if the given mode is the clone base of the current mode. This is
primarily of use by cloneable modes' configuration commands, which should do
nothing if this returns Z clear or if being used to update a menu (ie.
R2=15..20, but see E-Commands) and R0<>R14; this is to prevent you
accidentally configuring the wrong mode.
	\E R0=mode R8
	\X Z set if it's the clone base of the current mode
		 or if it's the current mode
	   R0=current mode
	   R14=menu mode

Zap_ReadVariable
Reads a user-controlled configuration variable. These are set per mode, and
in the future will be overridden per file. (See
ZapResources:Docs.Technical.TMFs for further discussion.)
 The variable name will be copied and stored in the variable table (don't
worry about this, you still control the buffer); the result is a pointer
directly into the variable table, so if you need to use it, COPY IT -
particularly if you expose it through a function, since the command system
will try to free the memory used for it when you do so.
 Note that V does *not* indicate an error condition.
 Use Z or R0=0 to indicate whether a variable returned or not.
	\E R0=variable name, r8/r9 optional
	\X R0=variable / 0 and Z set

Zap_BuildMenuWithHelp
This is Zap's 'variable length menu with help text' building sub. See E-Menu
for details on Zap's menu format.
The interface is as for Zap_BuildMenu, with the following additions:
	\E R5=pointer to help text / 0
	The sub passed in R1 has the following extra condition:
	     \X R1=pointer to help text / 0
If the first byte of the help text is ESC, then it is assumed to be a token.
Note that the help text must be permanently stored; if tokenised, no %
substitution will be performed.

Zap_CharDelDispatch
If the cursor is in the selection, then this will call the supplied routine
once for each (logical) line in the selection for which the cursor, at its
current column number, would still be in the selection. Otherwise, it will
just call the routine normally.
In your routine, you will most likely be using Zap_Command; you are advised
to set b5 of R0 (delink the cursor) and to move it yourself, if necessary, on
return from Zap_CharDelDispatch.
	\E R0 b31 clear if the routine in R3 inserts/overwrites, set if 
	      it deletes
	   R3 = routine
	   R4-R7 as for e_char or e_delete
	   R8/R9/R10
	\X R0-R2,R11 corrupt
	The routine passed in R3 has:
		\E R0=1 if dispatched, 0 if called normally (ie block editing
		        is not enabled or the cursor is not in the selection)
		   R4-R10 as above
		\X must preserve R1-R11; R0 = undefined or error (VS)

Zap_SelectHistoryBuffer
Selects (or creates) a history buffer for use in the minibuffer. It should be
used when your command is caled with R2=6.
	\E R0 = history buffer ID
	\X Buffer assigned, possibly also created
There are some preallocated buffer IDs:
	0	Default
	1	Search strings
	2	Replace strings
	3	Line numbers
	4	Filenames
	5	Numbers
	6	Strings (general)
	7	Expressions
	8	CLI
	9	Zap commands
	10	Help - command and function names
	11	Keymap names
	12	Mode names
	13	Date & time format strings
	14	Assembly code
(See h.ZapConsts for the label names.)
If you require a private buffer, it is recommended that you use the address
of your command or some other suitable resource within your module.

Zap_GetFileMode
As for Zap_WhichMode, but also uses FileId content matching.

Zap_AddFilter
Adds a routine to the list of filters that can intercept mode entry points.
There are two types of filter: pre filters are called before the mode entry
point, post filters are called after the mode has returned. The filters are
only called from Zap_CallMode, NOT Zap_CallGivenMode or Zap_BaseMode. This
means that where an entry point passes control to its base mode, your filter
will be called only once, for the mode the window is in.
It is not normally possible to filter e_redrawline or e_redrawlnum due to the
way these entry points are called.
	\E R0 = filter type  0 = pre filter  1 = post filter
	   R1 -> routine
	   R2 = private word
	   R3 = mode number to filter (or -1 for all modes)
	   R4 = e_ entry point
	   
	The filter code is called with:
		\E R0-R10 as for the mode entry point
		   R11 private word passed in R2 to Zap_AddFilter, R12 etc
		\X Can update R0-R10 and corrupt R11.
		   Prefilters can return R11 = 0 to claim the entry point, 
		   so the mode and subsequent filters aren't called.

Zap_RemoveFilter
Removes a filter code from the list of filters.
	\E R0 = filter type  0 = pre filter  1 = post filter
	   R1 -> routine
	   R2 = private word
	   R3 = mode number to filter (or -1 for all modes)
	   R4 = e_ entry point

R0-R4 should be the same as on the call to Zap_AddFilter.

Zap_AddCallTable
Adds an entry point in an extension which will be run when 
Zap_CallExtension is called which an appropriate reason code.
	\E R0 = base number
	   R1 -> routine to call
	   R2 = private word to be passed in R11
	   
	The code in R1 is called with
		\E R0-R6, R8-R10 parameters from caller
		   R7 call number offset
		   R11 private word
		\X R0-R10 return parameters
		   R11 corruptible

Zap_CallExtension
Calls an extension provided entry point, analogous to an SWI or
Toolbox_MiscOp call. The extension is loaded if necessary - see individual
help files for details of extension provided calls.
	\E R0-R6, R8-R10 parameters for call
	   R7 call number
	\X R0-R10 return parameters
	   R11 preserved

Zap_RedrawTab
To be called from within a mode's e_redrawline entry, this call redraws a tab
according to the appropriate flags and settings in the window block.
	\E R1 = current column
	   R6 = output buffer (as supplied to e_redrawline)
	        or zero to update the column without plotting anything
	   R8
	\X R1 = new column number
	   all others preserved

Zap_Query
An interface to the query side of the Wimp error box.
	\E R0 = message (error block)
	   R1 = title or 0 for default
	   R2 = buttons, or 0 for esc/cancel or 1 for yes/no
	   R3 = icon name (in WIMP sprite pool), or 0 for Zap's icon
	   R4-R7 = parameters for message, if needed
 	 Strings are currently *always* looked up via MessageTrans.
	 No expansion is done on title or buttons.
	 Error code must be 0.
	\X R1 = button number; Z set if R1=1 or R1=3.
	   R0 corrupted.
	   May return an error.

Zap_ReadC
Reads a character from a given offset in a file. If the window is in the
UTF-8 encoding, this returns the UCS-4 character code at the given offset,
otherwise it returns the byte at the offset. In both cases the offset is
updated to point to the next character. If the file contains a malformed
UTF-8 sequence, this call updates the pointer past it and returns &FFFD (the
replacement character).
	\E R1 = file offset
	   R8 / R9
	\X R0 = (32 bit) character
	   R1 updated to the file offset of the next character

Zap_ReadUTF8
As Zap_ReadC, but assumes the file is in UTF-8 and thus doesn't need the
window pointer.
	\E R1 = file offset
	   R9
	\X R0 = (32 bit) character
	   R1 updated to the file offset of the next character

Zap_ReadMinus
Given a file offset, this reads the _previous_ character, and updates the
offset to point to it. This isn't trivial if the file is in the UTF-8
encoding. This call checks whether the window is in UTF-8, and copes
correctly with malformed UTF-8 sequences (returning the relacement character
as per Zap_ReadC). This call is mainly used for its side effect of returning
the previous character offset, for example in e_delete or e_minus entry
points.
	\E R1 = file offset of character
	   R8 / R9
	\X R0 = previous (32 bit) character
	   R1 = offset of this character

Zap_ReadAddrUTF8
As Zap_ReadUTF8, but takes an address rather than a file offset.
	\E R7 = address
	\X R0 = (32 bit) character
	   R7 updated to the address of the next character

Zap_ReadAddrUTF8File
As Zap_ReadUTF8, but takes an address within a file rather than a file 
offset, and skips the split when encountered. It also updates two registers
depending on which half of the file it's in, useful for e_redrawline
entry points. If R10 is 0 on exit, the character in R0 is valid, but the
EOF has been reached so R7 no longer points within the file.
	\E R7 = address
	   R8 / R9
	   R10 = address of byte after end of this section
	         (ie. either f_buf+f_splito or f_buf+f_bufl)
	\X R0 = (32 bit) character
	   R5 has f_splits added if f_splito was reached (see e_redrawline)
	   R7 updated to the address of the next character
	   R10 updated to end of next section, or 0 if EOF

Zap_ReadAddrAuto
As Zap_ReadAddrUTF8File, but reads a single byte if the window is not in
UTF-8 mode.
	\E R7 = address
	   R8 / R9
	   R10 = address of byte after end of this section
	         (ie. either f_buf+f_splito or f_buf+f_bufl)
	\X R0 = (32 bit) character
	   R5 has f_splits added if f_splito was reached (see e_redrawline)
	   R7 updated to the address of the next character
	   R10 updated to end of next section, or 0 if EOF

