Extra features of FileSwitch, introduced in version 1.70
========================================================

i) Path variables work properly. Whenever <thing>: prefixes a path the
relevant path variable will be used (<thing>$Path). Paths in path variables
will be resolved in the same way. The following new errors may occur:
 * Path variable had multiple entries and was used for a write operation
 * One of the path variables used refers to itself

ii) FileSwitch manages directories. From now on FileSwitch will process a
path, resolving out wildcards, absolute directory references (%, @, \ and &)
and sorting out parent references (^). There should be minimal impact on how
things work, except for the following:
 * All filing systems will get all absolute directories working the same.
 * It may be possible to delete current and library directories.
 * Paths which go through non-existant directories, but end up at an
        existing object will work (eg a.b.c.d.^.^.^.f will end at a.f even
        if b, c or d don't exist).

iii) FileSwitch provides support for MultiFS-like filing systems. The
support provided by FileSwitch means that 'seamless' access to MS-DOS hard
disc partition files, or MS-DOS discs, can be implemented. In effect, the
foreign disc format is not noticed by the user when it is accessed from the
desktop. As a consequence of this the object type has been extended:
Object type     Meaning
0               Not present
1               File
2               Directory
3               File and Directory - this means this file has been
                identified as a MultiFS file, and hence can be treated as a
                directory too. Objects of this type may be treated as both
                files and directories.

An alternative way to think of the object type is as a bit field:
Bit             Meaning when set
0               Object may have file-like operations done to it
1               Object may have directory-like operations done to it

iv) Given a filename, FileSwitch can be asked to process it to produce a
mostly canonical form (mostly in the sense that the case may be different,
and wildcards may not be sorted out if the wildcarded object doesn't
exist!). So
 * 'a' may be resolved to 'adfs::HardDisc4.$.current.a' if the current
        directory is 'adfs::HardDisc4.$.current'.
 * 'a*' may be resolved to the same thing if 'a' exists and is the first
        match for 'a*', but, if there is no match for 'a*', then
        'adfs::HardDisc4.$.current.a*' will be returned.
 * 'A' may be resolved to 'adfs::HardDisc4.$.current.A', which should be
        considered the same as 'adfs::HardDisc4.$.current.a'.

OS_FSControl 37 (FSControl_CanonicalisePath)

On entry
 r0 = 37
 r1 = Pointer to path to be canonicalised
 r2 = Pointer to buffer to be filled in
 r3 = Pointer to system variable name of path to use, or 0 if none
 r4 = Pointer to default path to use if no system variable is specified
        or if that variable doesn't exist, or 0 if no path is the default
 r5 = Buffer length

On exit
 Buffer filled in with 0-terminated canonicalised name, and
 r5 = number of spare bytes in the buffer after and including
        the 0 terminator. If the buffer would have overflowed,
        then this will be taken to negative the overflow, but
        the overflow won't actually have happened. This
        provides a machanism for finding out how much buffer
        is needed.

This may be used as a two-pass process:
  Pass 1:
    In:
      r0 = 37
      r1 = Pointer to path
      r2 = 0
      r5 = 0
  Out:
      r5 = -(length of canonicalised path)
 Pass 2:
  Claim buffer of the right size (1-r5, not just -r5 as a space for the terminator is needed)
    In:
      r0 = 37
      r1 = Pointer to path
      r2 = Pointer to claimed buffer
      r5 = size of claimed buffer
    Out:
      r5 should be 0, but check to make sure!

v) Given a file handle, fileswitch will return the name of the file.

OS_Args 7 (OSArgs_ReadPath)
On entry
 r0 = 7
 r1 = file handle
 r2 = Pointer to buffer to be filled in
 r5 = Buffer length
On exit
 Buffer filled in with 0-terminated canonicalised name, and
 r5 = number of spare bytes in the buffer after the 0 terminator.
        If the buffer would have overflowed, then this will be
        taken to negative the overflow, but the overflow won't
        actually have happened. This provides a machanism for
        finding out how much buffer is needed.

This call can be used in the same way as OS_FSControl 37.

vi) FileSwitch now processes the conversion of file info into filetype
information.

OS_FSControl 38 (FSControl_InfoToFileType)
On entry
 r0 = 38
 r1 = a pointer to the object's name
 r2 = object's load address
 r3 = object's execute address
 r4 = object's length
 r5 = objects's attributes
 r6 = object's type (file/directory)
On exit
 r2 = object's type:
        Special values:
        -1      untyped
        &1000   directory
        &2000   application directory (directory whose name starts with a '!').

OS_File 20-23 (OSFile_ReadWithType, _ReadWithTypePath, _ReadWithTypePathVar
                and _ReadWithTypeNoPath)

On Entry
 r0 = 20, 21, 22 or 23
 r1 = Pointer to name of object
On exit
 r0 = object's type
 r1 unchanged
 r2 = Object's load address or top word of date stamp
 r3 = Object's execute address or bottom word of date stamp
 r4 = Object's length
 r5 = object's attributes
 r6 = Object's type:
        Special values:
        -1      untyped         (r2, r3 are load and execute address)
        &1000   directory
        &2000   application directory (directory whose name starts with a '!').

OS_GBPB 12 (OSGBPB_ReadDirEntriesFileType)

On entry
 r0 = 12
 r1 = pointer to directory name
 r2 = start address of data in memory (word aligned)
 r3 = number of names to read from directory
 r4 = offset of first item to read from directory (0 for start)
 r5 = buffer length
 r6 = Pointer to (Wildcarded) name to match

On exit
 r0-r2 unchanged
 r3 = number of objects read
 r4 = offset of next item to read
 r5, r6 unchanged

This call is similar in function to OS_GBPB 10, except the buffer is filled
in with entries like this:

Offset  Contents
0       Load address or high word of date stamp
4       Execute address of low word of date stamp
8       Length
12      File attributes
16      Object type
20      Object's file type (as for OS_File 20-23)
24      Object's name (null terminated)

