home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilst / zap / !Zap / Docs / E-Zapcalls < prev    next >
Text File  |  1995-06-19  |  46KB  |  1,093 lines
  1. *************************************************************************
  2. * >E-ZapCalls    Documentation of Zap entry points (how to call Zap)    *
  3. *************************************************************************
  4.  
  5. Zap does NOT have a SWI interface as it uses registers R8-R10 to point to
  6. data blocks, and these cannot be passed to swi's. To call Zap you will need
  7. to know the address of the Zap module workspace (ie it's private word). If
  8. you are an extension mode then this will be passed to you in R12 whenever you
  9. are called by one of your entry points. However, for the first call you make
  10. to Zap, when you add your module to it's list via Zap_Addmode, you will not
  11. know it. Then you should use OS_Module 18 to find it. Eg,
  12.  
  13.  SYS "XOS_Module",18,"Zap" TO R0,R1,R2,R3,workspace%
  14.  
  15. Now, the first word in Zap's workspace contains the address of a table of
  16. Zap's entry points. Thus to call the entry point (documented below) at offset
  17. a% I suggest you use the basic macro given below.
  18.  
  19.     REM Call Zap at entry offset a%
  20.     REM Entry: R0-R11=args R12=zap workspace
  21.     REM Exit : R0-R11=returned values R12 preserved R14 corrupted
  22.     
  23.     DEF FNcall(a%)
  24.     [OPTpass
  25.     LDR R14,[R12]        \ get start of zap table
  26.     ADD R14,R14,#a%        \ address of the sub
  27.     STMFD R13!,{R14}        \ save address on stack
  28.     MOV R14,PC            \ return address (with flags)
  29.     LDMFD R13!,{PC}        \ call the sub 
  30.     ]:=""
  31.  
  32. The names of the routines are listed below in the order in which they appear
  33. in the table. Thus the first, Zap_AddMode, is at offset 0. The second,
  34. Zap_Claim is at offset 4, etc. These values are defined for you in the
  35. program E-Library.
  36.  
  37. In general these routines have the following entry/exit conditions:
  38.  
  39.  \E R0-R11=arguments R12=Zap's workspace R13=user stack R14=return address
  40.  \X R1-R13 preserved. R0 and Flags ALTERED. V set if error and R0=error block
  41.  
  42. Thus if I write:
  43.  
  44.  \E R8
  45.  \X R1=3
  46.  
  47. Then I mean that on entry R8 was the window block pointer, R12 zap's
  48. workspace etc. And on exit that R1=3, R2-R13 saved, R0 corrupted etc. If I
  49. omit the \E or \X then I mean the standard entry/exit conditions hold.
  50.  
  51. Errors should be passed back to Zap by the entry point through which the
  52. module was called (with V flag set and R0=error block pointer). Please note
  53. that for most calls, Zap must be paged in as the current task! This will be
  54. so if you are an extension mode.
  55.  
  56. For a table/summary of the zap call names for including in your source, see
  57. the file E-Library.
  58.  
  59. Zap_AddMode
  60. Adds a new Zap extension mode. This should be called after the module Zap is
  61. loaded, but before it starts up as a new task. Zap need not be paged in for
  62. this call.
  63.     \E R0=address of table of entry points (see file E-Entry)
  64.  
  65. Zap_Claim
  66. Claims a block of workspace in Zap's heap.
  67.     \E R0=number of bytes required
  68.     \X R0=pointer to the heap block
  69.  
  70. Zap_Ensure
  71. Ensures a zap heap block is of a given size.
  72.     \E R0=pointer to the heap block
  73.        R1=number of bytes required.
  74.     \X R0=new heap block pointer of (possibly moved) extended block.
  75.        (An error is returned if the block couldn't be enlarged).
  76.  
  77. Zap_Free
  78. Free a zap heap block after use.
  79.     \E R0=pointer to heap block to free
  80.  
  81. Zap_MoveBytes
  82. Moves a block of memory. The movement may be up or down by any amount. The
  83. data is ALWAYS preserved no matter where the destination is. This routine is
  84. highly optimised and should be used for moving any large block of data. Zap
  85. need not be paged in.
  86.     \E R1=source byte address
  87.        R2=destination byte address
  88.        R3=number of bytes to move
  89.     \X R1-R3 corrupted
  90.  
  91. Zap_SplitBuffer
  92. This splits a file held in Zap at the indicated file offset ready for
  93. insertion/deletion of data. It also ensures that file buffer has a given
  94. amount of room free. See E-File.
  95.     \E R0=file offset to split at (new value for f_splito)
  96.        R1=minimum number of bytes to have free in the split
  97.        R9=file to be split
  98.  
  99. Zap_NewTxtStatus
  100. This updates the screen after changes are made to a file. This is very low
  101. level and you should use Zap_Command when possible. Zap_SaveTxtStatus should
  102. be called first.
  103.     \E R0/R1 as for SaveTxtStatus and R2=new input caret offset.
  104.  
  105. Zap_SaveTxtStatus
  106. This is a low level call used by Zap_DoCommand when changing a file. You
  107. should use Zap_Command/Zap_DoCommand in preference. Any file changes done
  108. using this call are NOT saved in the undo buffer. Ie, don't use it. To use it
  109. you specify the area of the file to be changed (R0 to R2) and the amount of
  110. the change (in R1). After making the change you use Zap_NewTxtStatus to
  111. update the screen. Set f_docom to 0 if in doubt.
  112.     \E R0=file offset of first byte in file to be changed.
  113.        R1=proposed signed change in size of file.
  114.        R2=file offset of first character which is unchanged.
  115.        f_docom,f_dolen,f_dodata must be set up - see e_prevline.
  116.  
  117. Zap_Command
  118. This should be used for inserting/deleting/replacing data in a file. Its 
  119. action is to call the mode entry point named e_command. See E-Entry. The
  120. mode's default action is then to call Zap_DoCommand. The commands are
  121. automatically placed in the undo buffer. If you are doing a sequence of
  122. insertions/deletions then please use Zap_Start/StopOp. Note that the cursor
  123. is automatically updated to the end of the inserted/deleted region. To
  124. prevent this, set b14 of f_flags, but you MUST restore it after the command
  125. returns.
  126.     \E R0=command number: 1=insert 2=delete 3=replace (forward)
  127.         4=replace (backward). Add &10 if command is to be buffered
  128.         in one block (and thus undone in one key press).
  129.        R1=file offset for command to take place at.
  130.        R2=number of bytes being inserted/deleted/replaced.
  131.        R3=data to insert/replace with for commands 1,3,4.
  132.        R8=window on file to be altered/0 if none.
  133.        R9=file to be altered.
  134.     NB If you don't specify the window then it won't know which mode to
  135.     call, so this command will just call Zap_DoCommand.
  136.  
  137. Zap_NewWinStatus
  138. This recreates a window after some display parameters have changed. Use
  139. Zap_SaveWinStatus before changing any parameters.
  140.     \E R8/R9
  141.     
  142. Zap_SaveWinStatus
  143. This is used before changing any of the 'w_*' window parameters which would
  144. effect the display. See E-Window. The current cursor position, scroll offsets
  145. etc are saved. After changing the window parameters call Zap_NewWinStatus.
  146. Zap will do it's best to recreate the window with the new attributes,
  147. preserving the position of the cursor on screen.
  148.     \E R8/R9
  149.  
  150. Zap_ReplaceArea
  151. This command replaces one area of text with another (not necessarily of the
  152. same length) by performing the minimum number of insertions/deletions/simple
  153. replaces using Zap_Command. In BASIC mode it also retokenises the line as
  154. necessary. This is used during a search and replace. See mode entry point
  155. e_replace.
  156.     \E R1=file offset of original data
  157.        R2=length of original data
  158.        R3=address of replacement data
  159.        R4=length of replacement data R8/R9
  160.        
  161. Zap_PlotCaret
  162. This command plots a caret in its new position automatically removing it from
  163. its old position. Ie, it just calls Zap_ClearCaret then Zap_SetCaret.
  164.     \E R10=caret block
  165.  
  166. Zap_ReflectCaret
  167. This acts as Zap_PlotCaret but only uses c_off, updating the c_loff and c_col
  168. offsets from this. Ie, it just calls Zap_UpdateCaret then Zap_PlotCaret.
  169.     \E R10=caret block
  170.  
  171. Zap_SetCaret
  172. This updates the area of the window containing the the caret given on entry.
  173. Hence it's effect is usually to draw the caret at it's (new) position. See
  174. E-Cursors.
  175.     \E R10=caret block
  176.  
  177. Zap_ClearCaret
  178. As for Zap_SetCaret, but it updates the area of the window where the caret
  179. last was (stored in the c_o* variables). Hence the caret is in effect removed
  180. from its old position. See E-Cursors.
  181.     \E R10=caret block
  182.  
  183. Zap_DoCommand
  184. This acts as Zap_Command but actually performs the action rather than
  185. calling the extension mode.
  186.     \E As for Zap_Command.
  187.  
  188. Zap_ShowCursor
  189. This call makes sure that a given cursor can be seen in its window (by
  190. changing the scroll offsets if necessary). It does not redraw the cursor
  191. in general (though changing the scroll offsets may cause it to be redrawn).
  192.     \E R10=cursor block of cursor to show
  193.  
  194. Zap_ReadVar
  195. Reads one of Zaps internal variables. See the file E-Vars for the numbers.
  196.     \E R1=variable number.
  197.     \X R0=variable value.
  198.  
  199. Zap_