home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / z / zregister / Guide next >
Text File  |  1994-10-23  |  7KB  |  184 lines
  1. ¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤                         =========================
  2. ZeriRegister 1.00 user guide                          This module is FREEWARE
  3. ¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤                         =========================
  4.  
  5. ----------------
  6. - Introduction -
  7. ----------------
  8.  
  9. ZeriRegister is a module that enables clean and automatic disposal of modules
  10. that are no longer in use by the system, so they do not needlessly clog up
  11. the RMA. It not only enables new applications to exit cleanly, but can also
  12. be used to tidy up existing applications that leave their modules behind
  13. after quitting. This may usually be achieved by simply editing the 'naughty'
  14. application's !Run file.
  15.  
  16. To do its work, ZeriRegister maintains a small database of modules and their
  17. use counts. It allows modules to be 'registered' or 'unregistered' for use by
  18. a caller, using either a *-command or an SWI. After the last user of a given
  19. module unregisters, the module is automatically killed.
  20.  
  21. This module has an Acorn registered SWI chunk number.
  22.  
  23.  
  24. ---------------
  25. - The package -
  26. ---------------
  27.  
  28. There are two files in the ZeriRegister package :
  29.  
  30. 'ZRegister'
  31. ~~~~~~~~~~~
  32. Is the ZeriRegister module.
  33.  
  34. 'Guide'
  35. ~~~~~~~
  36. Is what you're reading now, the 'user guide'.
  37.  
  38.  
  39. ---------------
  40. - Quick start -
  41. ---------------
  42.  
  43. If you want to tidy up your 'naughty' applications right away, without
  44. reading the rest of this guide, simply do the following :
  45.  
  46. - Ensure ZRegister is loaded in your boot sequence.
  47. - Then, for all the modules used by the application, bracket the ...!RunImage
  48.   line in your apps' !Run files with *RegisterModule <module name> and
  49.   *UnregisterModule <module name>, i.e. place these before and behind the
  50.   ...!RunImage line, respectively.
  51.  
  52. If you need more detailed usage information, read the rest of this guide.
  53.  
  54.  
  55. ---------
  56. - Usage -
  57. ---------
  58.  
  59. Simply *RMLoad ZRegister in your system's boot sequence. It is possible to
  60. indicate the amount of memory that is to be used for the module database by
  61. using
  62.  
  63. *RMLoad ZRegister <K's>
  64.  
  65. where <K's> indicates the number of Kbytes to use for the database. <K's> may
  66. be from 1-9, else it defaults to 1. 1k is sufficient for roughly 50 entries,
  67. which should be enough in normal use.
  68.  
  69.  
  70. ------------
  71. - Commands -
  72. ------------
  73.  
  74. *RegisterModule <module name> registers the given module for use by the
  75. caller. If this is the first registration for the module, a new entry for it
  76. is created in the database and its use count is set to 1. If the module is
  77. already registered, its use count is incremented.
  78.  
  79. *UnregisterModule <module name> unregisters the given module for use by the
  80. caller. Its use count in the database is decremented. If the use count
  81. becomes 0, the module is deleted using SWI OS_Module 4. If the deletion
  82. fails, the module's entry in the database remains, with a use count of 0.
  83.  
  84. *RegisteredModules will list all the registered modules and their use counts.
  85.  
  86. The SWIs "ZeriRegister_RegisterModule" and "ZeriRegister_UnregisterModule",
  87. with r0 pointing to the module name, are fully equivalent to their
  88. corresponding *-command.
  89.  
  90. Module names may be terminated by a CTRL-character or a space, and any
  91. matches against the database are case insensitive. The exact name given
  92. during the first registration is the one stored in the database, and
  93. therefore the one listed by *RegisteredModules.
  94.  
  95.  
  96. --------------
  97. - Tidying up -
  98. --------------
  99.  
  100. To 'tidy' an application (e.g. an existing one which leaves its modules
  101. lingering behind), simply 'bracket' the ...!RunImage command line in its !Run
  102. file (assuming it is an Obey file) by a *RegisterModule and *UnregisterModule
  103. command. E.g. if an existing !Run file would look like :
  104.  
  105. ...
  106. RMEnsure Blah 1.23 RMLoad <Blah$Dir>.Blah
  107. ...
  108. Run <App$Dir>.!RunImage
  109. ...
  110.  
  111. it would become :
  112.  
  113. ...
  114. RMEnsure Blah 1.23 RMLoad <Blah$Dir>.Blah
  115. ...
  116. RegisterModule Blah
  117. Run <App$Dir>.!RunImage
  118. UnregisterModule Blah
  119. ...
  120.  
  121. Simply add these lines for every module that is used by the application.
  122.  
  123. Note that for the above to work properly, the applications you run must be
  124. 'well-behaved' in the desktop, i.e. specifically they must never use *Close
  125. or CLOSE#0, or anything like that, because such a command will also close any
  126. open !Run files, so the *Unregister commands of any running applications will
  127. never be executed. There shouldn't be any of these 'misbehaving' applications
  128. around, but be aware of this if module tidying doesn't seem to work.
  129.  
  130. To 'tidy' a new application, you may do the same as described above, or issue
  131. the register and unregister commands inside the application code (using the
  132. equivalent SWI would possibly be more convenient in this case).
  133.  
  134.  
  135. -----------------
  136. - Final remarks -
  137. -----------------
  138.  
  139. This software is Freeware. It may be copied freely, as long as it is not
  140. charged for beyond coverage of incurred media and moderate handling costs, and
  141. is copied completely and unchanged. All rights to this software remain the
  142. author's at all times. You may not change this software or use any part of it
  143. in other products without the author's approval.
  144.  
  145. Implicit approval is given for use of the software in non-commercial products,
  146. provided the software is issued completely (i.e. including documentation) and
  147. unchanged, a proper credit to the author is given in the documentation of the
  148. product, and the author is notified of the use.
  149.  
  150. This software is provided 'as is'. It is not guaranteed to be useful for any
  151. particular purpose. I cannot be held responsible for any damages, either
  152. direct or consequential, arising out of the use or the inability to use this
  153. software.
  154.  
  155. If you want to contact the author, e.g. for any comments or bug reports you
  156. might like to make, or to obtain the latest version of the software, you are
  157. welcome to do so. Details are included below, please read them carefully.
  158.  
  159. Snail mail
  160. ~~~~~~~~~~
  161. John Kortink
  162. Nutterbrink 31
  163. 7544 WJ Enschede
  164. The Netherlands
  165.  
  166. Please include an SAE, coverage of return postage, and, if you want a new
  167. version of the software, a floppy disc. If any of these are missing, I may
  168. choose not to reply. Examples of postage coverage : sufficient Dutch stamps,
  169. IRC's, or small cash (e.g. £1). Never send any type of cheque. If you send a
  170. floppy disc, send a DD one, as I cannot yet handle HD discs on my Archimedes.
  171.  
  172. Please note I cannot hold on to floppy discs awaiting new versions of the
  173. software, i.e. always first check with me that there is a new version.
  174.  
  175. Email
  176. ~~~~~
  177. J.Kortink@inter.NL.net
  178. john@dialis.xs4all.nl
  179. FIDO 2:283/307.7
  180.  
  181. Email is preferred over snail mail.
  182.  
  183.  
  184.