home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / dosfs / !DosFS / ReadMe1 < prev    next >
Encoding:
Text File  |  1990-10-22  |  10.6 KB  |  241 lines
  1. | >!DosFS.ReadMe1
  2.  
  3. DOCUMENTATION OF DosFS MODULE
  4. -----------------------------
  5.  
  6. Author         : Rob Schrauwen
  7. Acknowledgement: A few important routines were programmed by
  8.                  Erik Admiraal
  9. Remark         : This documentation applies to versions 1.20 or later.
  10.                  Earlier versions did not implement a full filing system.
  11.  
  12. © R. Schrauwen 1990
  13.  
  14.  
  15. PUBLIC DOMAIN STATUS
  16.  
  17. This software is public domain. It may be copied and given away, provided
  18. that the *complete* !DosFS application directory is copied.
  19.  
  20.  
  21. DOSFS
  22.  
  23. DosFS is a filing system which is able to read and write RSDOS (i.e. MSDOS
  24. and Atari ST-compatible) floppy discs.
  25.  
  26. The DosFS module is a real filing system, like adfs:, ram:, scsi: etc.. It
  27. can be used from the desktop as well as outside the desktop. For example,
  28. you can type
  29.  
  30.   *. dosfs:
  31.  
  32. to get a catalogue of the root directory;
  33.  
  34.   *dump dosfs::fred.$.jim
  35.  
  36. to see the contents the file jim in the root directory of the disc fred;
  37. in Basic you can type
  38.  
  39.   x%=OPENUP("dosfs:sheila");
  40.  
  41. and so on.
  42.  
  43. DosFS has to interact with RiscOS using RiscOS's rules and conventions. This
  44. gives some discrepancies compared to the use on an MSDOS machine:
  45.  
  46. 1) File names: The RiscOS rules apply. Hence  $  denotes the root directory
  47.    and dots are used to separate directories in a path name. In RiscOS there
  48.    are no extensions. A separator, called the ExtSep fulfils the role of the
  49.    dot which in Dos separates file name and extension. The ExtSep defaults
  50.    to "_", but this can be changed (e.g. if a filename contains "_", you
  51.    might find it useful to change the ExtSep into something else).
  52.    
  53.    Examples:
  54.    \CONFIG.SYS   is called dosfs:$.CONFIG_SYS under DosFS.
  55.    \DIR\FILE.EXT is called dosfs:$.DIR.FILE_EXT under DosFS.
  56.    \AUTOEXEC.BAT is called dosfs:$.AUTOEXEC_BAT, but is also possible
  57.                  to use AUTOEXECBAT.
  58.  
  59.    A problem is that file names may become longer than the 10 characters
  60.    allowed by existing filing systems. Note that on the command line, files
  61.    can be accessed at all times, since the 10 characters are not a limitation
  62.    of Risc-OS but only of the existing filing systems. It is not the task of
  63.    DosFS to cut file names, it should always provide a 1-1 mapping of names
  64.    under both systems. Therefore copying a file whose name hase 12 characters
  65.    to adfs: will result in a Bad Name error given by adfs: and not by File-
  66.    Switch. BUT the DosFS-Filer provides several name conversions, see
  67.    !DosFS.ReadMe2.
  68.    
  69. 2) File types: Dos does not support file types. DosFS gives all files the
  70.    type DosFile (&111) because it cannot know which file type is meant.
  71.    The DosFS philosophy is, that DosFS cannot know the file type, but that
  72.    programs working with DosFS might deduce filetypes e.g. from the file's
  73.    extension. For example, the DosFS-Filer uses this. DosFS itself *must*
  74.    treat all files equally.
  75.  
  76. 3) Disc names: RiscOS uses disc names extensively. DosFS uses the volume
  77.    label as disc name. Some DosFS-operations will complain if your disc does
  78.    not have a volume label. NOTE: this name is the only reference that
  79.    DosFS uses, so two discs with the same name will not be distinguished!
  80.    You can access a disc in the usual way:
  81.  
  82.    *. dosfs::volume.$.dir
  83.  
  84.    will give a catalogue of the directory dir on a disc called 'volume'.
  85.    Since UpCalls are fully implemented, DosFS will prompt for disc changes
  86.    if necessary.
  87.  
  88. 4) Access information: Risc-OS and Dos do not have the same possibilities
  89.    for access information. On DosFS you always have read-access. The read-
  90.    only attribute is observed. Hidden files appear as "locked", but other
  91.    files cannot be locked against deletion.
  92.  
  93. 5) Ownership of the floppy drive: ADFS thinks it owns the floppy drive. If
  94.    you by accident try to access a DosFS disc under ADFS you will get the
  95.    "Bad free space map" error. The other way around, you will get the "Unable
  96.    to read disc" error of DosFS after prompting for (a sometimes completely
  97.    irrelevant) disc. You will hear the drive try three times, which is one
  98.    of the *many* "features" of FileSwitch which the user thinks are strange
  99.    properties of DosFS.
  100.  
  101. The philosophy of DosFS is that it cannot assume anything of a file that
  102. is not supported by Dos. For example, as a filing system, DosFS will never
  103. convert end-of-line characters of a text file: suppose you use an SWI to
  104. determine the file's length, then DosFS won't of course count the carriage
  105. returns in the file and subtract that from the length as stored in the
  106. directory. Other ADFS--Dos transfer utilities, which are only programs, can
  107. do this. Obviously, the DosFS-Filer (see ReadMe2) supports this, too.
  108.  
  109.  
  110. COMMANDS PROVIDED
  111.  
  112. Apart from the commands implemented in order to serve FileSwitch, including
  113. almost all filing system commands (see further below), DosFS implements
  114. the follwing *commands:
  115.  
  116. *BytesFree:  Shows the number of bytes free on an RSDOS disc.
  117. *DosFS    :  Selects DosFS as the current filing system (cf. *ADFS)
  118. *DosMap   :  Shows a list of free clusters on an RSDOS disc.
  119. *DosVolume:  Changes the name (volume label) of an RSDOS disc.
  120. *ExtSep   :  Shows or changes the current extension separator used to
  121.              separate the file name and the extension. Default "_".
  122.  
  123.  
  124. RESTRICTIONS
  125.  
  126. 1) Only 720K floppy discs in drive 0 are supported. Other floppies and drives
  127.    could be supported, but I cannot test this. The hard disc is not supported
  128.    either.
  129.  
  130. 2) Copying from DosFS to adfs::0 (the same drive) won't work unless the P
  131.    (prompt) option is used. This is because adfs will hasten to access the
  132.    disc before you get the chance to remove it.
  133.  
  134. 3) DosFS supports "buffered files" (cf. PRM vol 3), for ease of implemen-
  135.    tation. Unfortunately, FileSwitch does not like to have more than one
  136.    buffer for DosFS, so some operations involving TWO files open on DosFS
  137.    ONLY, take a *very* long time to complete (one on DosFS and one somewhere
  138.    else works fine).
  139.  
  140.  
  141. OPERATIONS SUPPORTED
  142.  
  143. DosFS supports almost ALL sensible FileSwitch operations.
  144. NOT supported are library directories, boot options and "directory
  145. contexts".
  146.  
  147. Note that older versions of DosFS had many more restrictions, often resulting
  148. in the dreaded "DosFS does not support this operation" error.
  149.  
  150.  
  151. TECHNICAL DETAILS, WARNINGS & PECULIARITIES
  152.  
  153.  -- A DosFS file name consists of the name, the ExtSep character, and
  154.     the extension. RiscOS's rules always apply, and there is always a
  155.     1-1 mapping of files. Note that from adfs to dosfs there is no problem
  156.     in the length of the file names. This is because DosFS allows the user
  157.     to omit the ExtSep whenever a file has a 8-character part before the
  158.     extension. In the command line you can always use filenames as long as
  159.     you like. In the Filer, renaming of files is possible even if the
  160.     'Not a heap block' message is given (just ignore this). If you want to
  161.     overcome these problems, you can always use the transfer icon provided
  162.     by the desktop. 
  163.  
  164.  -- A DosFS path name follows the rules of RiscOS, so "." is used to
  165.     separate directory names, not "\". A disc name, prepended with ":" can
  166.     be included. Wildcarded names also follow the rules of RiscOS. In
  167.     particular, file* matches file1, but also file1_abc (where abc
  168.     is an extension). Of course  file*a_*  does NOT match fileb_ext
  169.     (try this on an MSDOS machine :-))
  170.  
  171.  -- Subdirectories can be of arbitrary length. Note, however, that
  172.     a very large subdirectory may cause a 'No room in RMA' error,
  173.     if claiming more memory to load the subdirectory fails.
  174.     [Very large is in this case 'larger than the root directory'
  175.     (which, allowing for "." and "..", corresponds to 112 files in a
  176.     subdirectory)]. In general, DosFS claims 6.25K memory for workspace,
  177.     FAT and directories.
  178.  
  179.  -- To speed up some operations, it is assumed that the user never
  180.     removes the disc if the light is still on. If someone knows how to
  181.     intercept the DiscChanged-DeviceVector, I would be glad to hear;
  182.     in that case DosFS could implement a really good UpCall.
  183.  
  184.  -- Sometimes in error conditions, DosFS will UpCall to insert a disc
  185.     when you don't want that. Press Cancel, or Escape when outside the
  186.     desktop, until you get "Unable to read disc" (DosFS's universal
  187.     error message).
  188.  
  189.  -- There are programs that mistakenly reserve not more than 10 characters
  190.     for a file name. Even the SharedCLibrary does not reserve enough
  191.     characters. This means that if you try to load directly from the
  192.     Dos-disc (without piping through the DosFS-Filer's transfer icon), these
  193.     programs will fail. With DosFS a maximum-length name such as AUTOEXEC_BAT
  194.     has 12 characters, excluding termination character.
  195.  
  196.  -- If you copy an application directory to a Dos disc, then it is possible
  197.     that the Filer shows the correct sprite. Double clicking does not run
  198.     the program, because in reality all files have lost their types.
  199.  
  200. The following comments follow the implementation rules of PRM/3, pages
  201. 973--999.
  202.  
  203.  -- DosFS can have 8 files open. Note that your disc *must* have a volume
  204.     label to enable opening a file. Operations such as *Type, *Dump and
  205.     *Build use this. Also *Copy sometimes makes use of this. If a file is
  206.     opened for output or update, the length of the file will always reflect
  207.     the allocated disc space which is useful in case something goes wrong
  208.     (Dos itself does not always do this).
  209.  
  210.  -- BPut and BGet are supported. FileSwitch unfortunately maintains only
  211.     one buffer for DosFS. This means that if two files are open on DosFS
  212.     FileSwitch will urge DosFS to perform extensive buffer swapping: in
  213.     order to copy  n  bytes  2n  disc operations are performed. In
  214.     a future release, DosFS will provide its own buffer for input files.
  215.     Transferring bytes to or from another filing system works OK.
  216.  
  217.  -- The access attributes are translated as follows: hidden=LR, read only
  218.     =R. Directories are never locked. Changing attributes *only* looks
  219.     for the presence of the "W" attribute in *Access, all the other options
  220.     are ignored. In particular you have always read access.
  221.  
  222.  -- Files are always time stamped and have file type &111 (DosFile).
  223.     Load and execution addresses are not supported.
  224.  
  225.  -- Observe that there is a difference between *dosfs:dir $ and *dir dosfs:$
  226.     (some operations can be prefixed with dosfs:, such as *dosfs:close).
  227.  
  228.  
  229. If you have any comments or remarks, please contact me.
  230.  
  231. Rob Schrauwen
  232. Email: schrauw@math.ruu.nl
  233.  
  234. -----------------------------------------------------------------------------
  235. DISCLAIMER                                                         
  236.  
  237. This module has been thoroughly tested. However, in no circumstances
  238. the author will be liable for any damage or loss of data, etc..
  239. RS
  240.  
  241.