home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / files / a / fsvars / FSVarsDoc < prev    next >
Encoding:
Text File  |  1989-07-17  |  9.2 KB  |  246 lines
  1. >&.Text.Document.FSVarsDoc
  2.  
  3. Filing System Variables Module Documentation
  4.  
  5. Package Version 1.00 17th July 1989
  6.  
  7. This file documents the module FSVars (1.21, 17th July 1989)
  8.  
  9. It contains three sections:
  10.  
  11.         - Using the FSVars Module
  12.                 Information about the module from the user's point of view
  13.         - Technical notes
  14.                 Some information about the program and OS Bugs that were
  15.                 discovered during its writing
  16.         * Package Documentation
  17.                 Information about the package in general. Read this.
  18.  
  19. Document Version 1.01 17th July 1989
  20.  
  21. --- Using the FSVars Module
  22.  
  23.         To install the FSVars module simply type
  24. *FSVars
  25. at any prompt. You can include it in your boot file if you want. As soon as the
  26. module is installed then the following OS variables are available
  27.  
  28. - FS$Name
  29.  
  30.         This holds the name of the currently selected filing system. It can be
  31. both read from and written to:
  32.  
  33. Examples:
  34.  
  35. >*SHOW FS$Name
  36. FS$Name : ram
  37. >*SET FS$Name adfs
  38. >
  39.  
  40. - FS$Disc
  41.  
  42.         This holds the name of the currently selected disc. It can only be
  43. read.
  44.  
  45. Example
  46.  
  47. >*SHOW FS$Disc
  48. FS$Disc : MainHard
  49. >
  50.  
  51. - FS$Path
  52.  
  53.         This holds the current full path as related to $ (the root directory).
  54. It can only be read.
  55.  
  56. Examples:
  57.  
  58. >*SHOW FS$Path
  59. FS$Path : $.M/Code.Source
  60. >*DIR $.old.c.c
  61. >*SHOW FS$Path
  62. FS$Path : $.Old.C.C
  63. >*DIR $.a*
  64. >*SHOW FS$Path
  65. FS$Path : $.Aasm
  66. >
  67.  
  68. - FS$Dir
  69.  
  70.         This holds the current directory name only. It can be written to.
  71.  
  72. Examples:
  73.  
  74. >*SHOW FS$Dir
  75. FS$Dir : Source
  76. >*DIR $.old.c.c
  77. >*SHOW FS$Dir
  78. FS$Dir : C
  79. >*DIR $.a*
  80. >*SHOW FS$Dir
  81. FS$Dir : Aasm
  82. >
  83.  
  84. - FS$Full
  85.  
  86.         This holds the current full currently selected directory specification.
  87. It is in fact defined as '<FS$Name>::<FS$Disc>.<FS$Path>'. It cannot be written
  88. to.
  89.  
  90. Examples:
  91.  
  92. >*SHOW FS$Full
  93. FS$Full : adfs::MainHard.$.M/Code.Source
  94. >*DIR $.old.c.c
  95. >*SHOW FS$Full
  96. FS$Full : adfs::MainHard.$.Old.C.C
  97. >*dir ram:$.Library
  98. >*SHOW FS$Full
  99. FS$Full : Ram::RamDisc0.$.Library
  100. >
  101.  
  102. - Suggested uses
  103.  
  104.         My use for this module is in setting up a Cli$Prompt. My current one is
  105. *SetMacro Cli$Prompt <Sys$Date> <Sys$Time><13><10><FS$Full> *
  106. which I like. I have also used
  107. *SetMacro Cli$Prompt <Sys$Date> <Sys$Time> <FS$Full><13><10><FS$Dir> *
  108. which leaves more space on the input line.
  109.  
  110.         If you used to use a BBC Master and still prefer the -adfs- convention
  111. rather than adfs: then you can always change FS$Full (even in the source code
  112. if you want) to
  113. *SetMacro FS$Full -<FS$Name>-:<FS$Disc>.<FS$Path>
  114.  
  115. - Thanks
  116.  
  117.         I'd like to thank Alan Glover of Eureka II (01 683 0629, 3-24 8N1) for
  118. helping me check that the OS bug described later really was an OS bug, and
  119. Philip Colmer of Acorn for his help in providing the solution to this.
  120.  
  121. --- Technical Notes
  122.  
  123.         The hardest part of this program is getting FS$Path. The problem with
  124. the Arthur/RISC OS operating systems is that there are holes in the read info
  125. type calls at various places. For instance, you can't read the name of a
  126. directory except the current one and the current library. This means that it is
  127. impossible to find the name of the parent of a directory without changing
  128. dir/lib oneself. Changing directory is no good: Some filing systems maintain
  129. a previously selected directory (psd) and since you can't read this *at all* 
  130. any change of directory loses the last psd *for ever*. This means that the
  131. only thing we can change is the library. Fortunately there is no previously 
  132. selected libaray!
  133.  
  134.         To find a directory, then this is what we do:
  135. Make sure we always know the *full path* of the library. This is done by
  136. building a path by calling getlibname followed by doing Lib %.^ until lib is
  137. $. This means we can always move the library and get back to it (with some
  138. checks on the *NoLib status).
  139. When we need to know the full path of the currently selected directory (csd)
  140. do *Lib @ followed by getting the full library path to a different buffer. We
  141. can get back to the old library by using the already known library.
  142.  
  143.         As can now be seen, we have to change the lib in the read entry of our
  144. variable now. (OS_FSControl 1). At this point a bug in Arthur/RISC OS became
  145. apparent. Changing Library within FSControl 1 caused a crash due to a clash of
  146. workspace. Consultation with Acorn revealed a solution to this which is rather
  147. messy: You have to copy the whole of &4000 to &7FFF to a storage area as the
  148. variable code begins and restore it at the end. Fortunately the ARM is fast and
  149. the delay isn't very great.
  150.  
  151.         When trying to check when the Filing System changed I discovered that,
  152. at least in RISC OS, Service_StartUpFS is never issued. In the end I hooked 
  153. onto FSControl 14 and 19 instead, but the lack of this service is odd: 
  154. I haven't seen its death docced anywhere.
  155.  
  156.         Implementing FS$Name opened another can of worms. There is a well
  157. documented call to get the current filing system number but no call in the PRM
  158. to get the filing system name or to convert this FS number to a name. So I
  159. disassembled *Configure FileSystem. In RISC OS this calls FSControl 33 which (I
  160. later remembered) is in the provisional RISC OS documentation I have here. I 
  161. then wanted to find something to use in Arthur 1.2, so I loaded up a copy of
  162. FileSwitch 1.04 from Arthur and disassembled Configure FileSystem from there.
  163. This code uses the fact that the FS name is stored &3d into the FS control
  164. block returned by FSControl 13. This assertion is also true in RISC OS but
  165. for best compatibility I used this method if FX0,1 returned less than 6 (the
  166. value it returns for RISC OS).
  167.  
  168. --- Package Documentation
  169.  
  170. *** Users of other shareware written by me please note - the text below may
  171. *** look the same as others but it is not. Take a few moments to look through
  172. *** it for differences, please.
  173.  
  174. This package contains:
  175. FSVarsDoc 1.01 (17th July 1989) : This text file
  176. FSVars    1.21 (17th July 1989) : Module
  177. SFSVars   1.21 (17th July 1989) : BASIC Asm Source code for module
  178. Macros         (26th April 1989): BASIC m/code Macros 
  179.  
  180.    The software contained in this package is Shareware. The word 'Shareware'
  181. means many things to many people, so I'll explain what I mean. In fact, some
  182. people would call this 'freeware' or 'public domain software' but it hardly
  183. matters what you call it - your obligations are set out below.
  184.    The program is free. You may make any number of copies and give them away to
  185. anyone (subject to the condition that you give them ALL the files in the
  186. package). You may not sell this software, or use it otherwise for personal gain
  187. without my permission. If you wish to post it on your Bulletin Board or include
  188. it in your Shareware library then that, too, is fine.
  189.    If you want to add any part of the code or data to one of your programs for
  190. your own use, then that's fine too. If you want to add it to something you plan
  191. to sell, or otherwise release as copyright material (whether for gain or not)
  192. then you'll need my permission - I retain copyright on this program.
  193.    If you like this program and find it useful then I would appreciate a small
  194. donation (say 5 or 10 pounds) (since this took a lot of labour to get working).
  195. This donation is a voluntary contribution.
  196.    If you send a donation and say which version of the package you have then I
  197. will send you an update if there is one. This disc will also contain up-to-date
  198. copies of as much of my shareware as will fit, plus any other stuff I can fit.
  199. There may be no update, since, for the moment, I've done all I want to to this
  200. program. Thus I don't guarantee that, if you send me money, I'll send you a
  201. new version of the program. You will, however, get a disc with things on it. If
  202. you'd prefer to wait until there is a disc with a new version on it then please
  203. say so. In this case you'll get a thankyou note.
  204.    This program has been tested with RISC OS. It should be suitable for both
  205. Arthur 1.2 and RISC OS. Please state, when sending for updates, whether you
  206. have RISC OS.
  207.    The diversity of Filing Systems and other modules means that I am unable to
  208. test this module as fully as I might like. However, it has been running bug
  209. free on my machine (even under RISC OS) for some time now.
  210.    This software carries no warranty, either express or implied. I've tested it
  211. and, to the best of my knowledge, there are no bugs. If you come across a bug
  212. then I'd be delighted if you got in touch with me. I can't guarantee to fix it
  213. but I'll probably have a good try.
  214. My address is:
  215.         Martyn Lovell
  216.         16, Fairwater Park,
  217.         Barnwood,
  218.         Gloucester.
  219.         GL4 7HF
  220. No telephone calls please.
  221. However, I can be contacted as:
  222. Cix:       MartynL
  223. Janet:     ZCEEB02@UK.AC.UCL.EUCLID
  224. Interspan: Contact via Janet at above address
  225. Eureka II: Martyn Lovell (112)
  226. Note that, during university terms, I read all this EMail sites regularly but
  227. in the holiday periods I may read them less regularly.
  228. For bug reports please send the following information:
  229.         Machine Type
  230.         Arthur Version
  231.         Software Version
  232.         Screenmode in use
  233.         Had the code been modified (if so, try to explain how)
  234.         What *exactly* happened
  235.         Modules Installed
  236.         Modules Unplugged
  237.         Podules Installed
  238.         Drives Installed
  239.         RAM Available
  240.         Monitor Type
  241.         Path values
  242.         Filing Systems and versions
  243.         Variable in use
  244.         Is the bug repeatable?
  245. and everything else that seems relevant.
  246.