Commit 93c7e2e0 authored by Neil Turton's avatar Neil Turton
Browse files

Import from cleaned 360 CD

hdr/** gitlab-language=armasm linguist-language=armasm linguist-detectable=true
s/** gitlab-language=armasm linguist-language=armasm linguist-detectable=true
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:
r0 = 37
r1 = Pointer to path
r2 = 0
r5 = 0
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)
r0 = 37
r1 = Pointer to path
r2 = Pointer to claimed buffer
r5 = size of claimed buffer
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
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)
This diff is collapsed.
A new UpCall_Modifying file reason code:
R0 = 3 (UpCall_ModifyingFile)
R1 = external handle
R2 = size to ensure
R8 = filing system information word
R9 = 512 (upfsfile_EnsureSize)
Called when a file's size is ensured.
PRM Bugs
FSEntry_Func 11 (page 992)
r6 = 0 (cannot specify a context) is wrong. A context can be specified.
OS_FSControl 1 (page 886)
The default library is typically & (this being the default for FileCore
based filing systems), not $.Library as stated in the PRM.
OS_FSControl 11 (page 897)
r2 0 : old filing system to be selected
should read
r2 > 0 : filing system number specified
The following should be noted about OS_FSControl 11:
r1 in Regs out
blah.blah vlsgf r1=r1 in
r2 = -1
r3 = 0
<FS>:blah r1 past :
r2 = number of <FS>
r3 = 0
<FS>#fred:blah r1 past :
r2 = number of <FS>
r3 past #
<path>:blah r1 = r1 in
r2 = -1
r3 = 0
<path>#fred:blah r1 = r1 in
r2 = -1
r3 past #
#fred:blah r1 = r1 in
r2 = -1
r3 past #
This diff is collapsed.
New service calls specific to or used by FileSwitch:
This is used by FileSwitch to Unset directories on eht dismounted disc. For
details of this new service call see FileCore.doc.Services
Service_CloseFile (&68)
To request that any module with a file open which is, or is a child of the
named object, that can also be closed without causing too much hassle should
close it. This would be issued to cause, for example, a DOSFS partition file
to be closed by FileSwitch. This doesn't cause problems as the partition
would be spontaneously reopened when needed later.
To issue this service call:
SWI OS_ServiceCall
r1 = &68 (Service_CloseFile)
r2 = object needing to be closed
r3 = 0
r1,r2 preserved
r3 = number of files closed as a result of this service call.
The value in r2 should be a pointer to a nul-terminated string which is a
canonical path of the object to be closed.
To respond to this service call:
r1 = &68 (Service_CloseFile)
r2 = object needing to be closed
r3 = number of files closed so far this service call
r1,r2 preserved
r3 incremented by the number of files you closed.
The spec of r2 is as above. This service call should not be claimed. If you,
the receiver of this service call, has any file open which is, or is a child
of the named object which you can close without much bother, then this
should be done. Increment r3 by the number of files you closed before
passing this service on.
I would suggest supporting RISC OS 3.10 properly as it saves you lots of
faff. Although more entry points may be needed, the effort to provide full
functionality (directory setting, processing of ^.s in paths and the such)
is much reduced as it is handled mostly by FileSwitch. I would recommend the
following settings (assuming a network flavour filing system).
Filing system information word:
Bit Setting Meaning
31 ? If set you suport special fields - probably want this clear
30 0 Streams aren't interactive (information bit only)
29 0 Null length file names are not allowed
28 0 Don't allow an open call if the file doesn't exist
27 0 Don't tell the filing system about flush calls (may want 1 instead)
26 0 FSEntry_File 9 (read info, no length) not provided
25 0 FSEntry_Func 20 (*FileInfo) not provided
24 0 FSEntry_Func 18 (set contexts) not provided
23 1 MultiFS extensions supported
22 0 Paths always given to filing system from $. onwards
21 0 FileSwitch stores directory settings (*Dir, *Lib etc) for this filing system
20 1 FileSwitch does *Load with Open, GBPB, close
19 1 FileSwitch does *Save with Open, GBPB, close
18 0 FileSwitch should process *Access strings itself
17 0 No extra info word
16 0 Filing system isn't read only
15-8 ? Limit on number of open files - 0 for no limit
7-0 ? Your filing system's number
The following Filing system entry points will be used:
0 read
2 update
Return when a file is opened with the file information word set to:
Bit Setting Meaning
31 ? Write permitted to file - return as appropriate
30 ? As above, for Read
29 0 Object isn't a directory
28 0 Buffered GBPB only
27 0 Stream isn't interractive
And quote a buffer size which is a power of 2 (256 bytes?) and the
length of the file. If you can get the allocate space too then
return that, otherwise round up the file's size to the next multiple
of the buffer size and return that.
These settings mean the following interfaces will be used:
These will be the multiple byte varieties. You will be asked to read
beyond the file's end - simply read to the file's end and don't
return an error. This happens as FileSwitch thinks it's driving a
disc-based filing system and reads the half-filled block at a
file's end just before modifying it and writing the whole block
3 Write file extent (size) (just before the file is closed
after modification)
6 Notify of flush (happens just before close after modification)
7 Ensure file size - return without error if no appropriate
8 Write zeroes
9 Read file datestamp
10 ImageStampIs. Return without error as this is only
appropriate to removable disc based filing systems (FileCore)
1 Write catalogue information
5 Read catalogue information
6 Delete object
7 Create file
8 Create directory
*10 ReadBlockSize - error this if you want
(7 Set filing system options replaced by _Func 28)
8 Rename
*10 Boot filing system - do nothing if booting inappropriate
(11 Read name and boot option of disc replaced by _Func 23 and 27)
14 Read directory entries
15 Read directory entries and information
16 Shutdown
*17 Print start up banner - depends on entry in FS info block being -1
*19 Read diretory entries and information - can error this one
23 CanonicaliseSpecialAndDisc
*24 Resolve wildcard - return with r4=-1 to get FileSwitch to do this
*25 ReadDefectList - error this if you want
*26 AddDefect - error this if you want
27 ReadBootOption - don't error this, return 0 instead
28 WriteBootOption - error this, or do nothing, it's up to you
*29 UsedSpaceMap - error this
30 ReadFreeSpace - this might be useful to support
*31 NameDisc - inappropriate for network - error it?
32 StampImage - don't error this, do an appropriate action, or do nothing
*33 ObjectAtOffset - error this
Those entries in () are for information only - they won't be called. Those
entries with a * can have trivial implementations.
All paths will be fully canonicalised by FileSwitch before the filing system
gets them, that is where appropriate will include special field (optional
as determined by CanonicaliseSpecialAndDisc and FS infor word bit), disc
name (as determined by CanonicaliseSpecialAndDisc), and path from $. The
filing system need not handle any of:
Directory setting - *Dir, *Lib etc
Parsing paths relative to set directories (@.thing.blah or %.doofa)
Performing catalogue listings of any sort (*Cat, *Ex etc)
Parsing *Access strings
^.s in paths
As these are handled by FileSwitch.
I believe writing such a filing system is less work than the RISC OS 2.00
way where the large gaps in calls used are needed to be supported.
UnknownFilingSystem:Filing system or path '%0:' not present
International-wise only: UnknownActionType:No %0 action specified for this file type
NoSelectedFilingSystem:No selected filing system
IsADirectory:Object is a directory
FSNotSpecial:Filing system does not support special fields
MultipartPathUsed:Path variable had multiple entries and was used for a write operation
Isn't, but should be used:
WildCards:'%0' contains wild cards
Hard to test:
CantSetLibOrURD:Can't set URD or library on %0
FileSwitchDataLost:Data lost
UnalignedFSEntry:Unaligned filing system entry point
NotEnoughStackForFSEntry:Not enough stack to call filing system
BadBufferSizeForStream:Bad buffer size
UnknownFilingSystem:Unknown filing system
NoRoomForTransient:No room to run transient
CantStartApplication:Unable to start application
NothingToCopy:Nothing to copy
NothingToDelete:Nothing to delete
NotEnoughMemoryForWildcardResolution:Not enough memory for wildcard resolution
NotEnoughStackForWildcardResolution:Not enough stack for wildcard resolution
MultiFSDoesNotSupportGBPB11:The OS_GBPB 11 call is not supported by MultiFS images
FSGAError:%0: FileSwitch GetArea
FSFAError:%0: FileSwitch FreeArea
FSGRError:%0: FileSwitch GetRMA
OnFileHandle:%0 on file handle %1
InvalidErrorBlock:Invalid error block
CantOpenFile:Can't open '%0'
Util_FilesDone (r1=tag for single string with %0=util_nfiles and %1=bytes)
Util_PrintName (r7=1st record (subst into %0), r8=2nd record (subst into %1), r2 = tag)
Util_GetConfirmYN doesn't print anything now
Util_PrintNameNL (r7=1st record (subst into %0), r8=2nd record (subst into %1), r2 = tag)
Util_PrintNameWithSize NL (r7=1st record (subst into %0), r8=2nd record (subst into %1), r9=size (bytes), r2 = tag)
To Do:
make sure disc option appears on cat title
International stuff:
1. 8 bit characters in names on *ALL* filing systems !!!
2. Text direction for names.
3. New interfaces for above.
4. Time and date in * commands (info ex fileinfo)
5. Territory_TextToString
6. Uppercasing for UpperCase macro
JC's unusual app$path corrupting linked strings? Maybe caused by memory shortage.
Add namedisc interface
Add 'access level' interface (public/private)
file left open after *load to memory
5069 - daft error message from filer
5140 *OPT 4,n info not handled - Add boot option interface
5148 Moving files to Econet produces error 'File Y not found'
5158 net:!ArmBoot file not found
5159 Heap Full: Fileswitch get area
5163 *Mount interaction - check this
5164 More URD problems with Econet
Ensure don't OS_File 5 on adfs::0.$
New open flag: 'Enable open on disc image' to get adfs::0.$ to open properly
Pending external reponses:
5179 Fileinfo no longer gives hex for file size.
5196 FileInfo does not work as it did before!
ro-5028 - filecore in use when using task window
5038 - system$path not consistent
5050 - open $ fails
5051 *EX gets dates wrong
5080 - *remove gives error
5082 can't find root
5088 not found error for existing file
5089 !apps not runnable from fileservers
5090 renaming to change case fails
5095 econet dir viewing gives file not found msgs for apps dirs
5096 file can not be loaded from net
Add NoDir, NoURD, NoLib swi interfaces & add commands
5094 dir no args changed functionality
5173 *Nolib doesn't work
5139 *EX prints "directory which should be "Directory"
5150 inellegant variable names
5133 FileInfo gives incorrect information
5194 bad handling of * in *copy.
5160 FileSwitch doesn't build full pathnames
Fix *Cat/Ex etc to display MultiFS images as directories, not files.
Add defect interface
5097 filer window update failing
5098 more update failure - can't see new files created outside desktop
5142 MultiFS files don't get upcalled properly
The Truncate Feature.
This feature is a scheme whereby filing systems which cannot handle long
filenames for one reason or another can be controlled as to what they do
about it. Under normal circumstances they used to give a 'Bad name' error if
a long filename was passed to them. Under the new scheme this property can
be changed so that when they are given a long filename they truncate it
before using it.
This is controlled by the *configure Truncate command. Two possible
parameters are allowed: Configure Truncate on and Configure Truncate off.
This controls the CMOS byte &1c, bit 0. Bit 0 being 0 means off and 1 means
on. When the Truncate bit is on then filenames will be truncated instead of
errors being generated.
As a filing system this bit should be read (and other bits in that byte
masked off) when the filing system is initialised.
Clarifications of openning a file in the new FileSwitch:
open_nodir on File+Directories should open the object without an error. So,
I suppose the bit has to mean 'Give me an error if this object, when opened
has no data that can be read from it using GBPBs and related calls'.
Access:*Access changes the attributes of all objects matching the wildcarded specification.|MAttributes:|ML(ock)|I|ILock object against deletion|MR(ead)|I|IRead permission|MW(rite)|I|IWrite permission|M/R,/W,/RW|IPublic read and write permission|MSyntax: *Access <object> [<attributes>]
Cat:*Cat lists all the objects in a directory (default is current directory).|MSyntax: *Cat [<directory>]
CDir:*CDir creates a directory of given name (and size on Net only).|MSyntax: *CDir <directory> [<size in entries>]
Copy:*Copy copies one or more objects that match the given wildcarded specification between directories. Options are taken from the system variable Copy$Options and those given to the command.|MOptions: (use ~ to force off,eg. ~C)|MA(ccess)|IForce destination access to same as source {on}|MC(onfirm)|IPrompt for confirmation of each copy {on}|MD(elete)|IDelete the source object after copy {off}|MF(orce)|I|IForce overwriting of existing objects {off}|ML(ook)|I|ILook at destination before loading source file {off}|MN(ewer)|I|ICopy only if source is more recent than destination {off}|MP(rompt)|IPrompt for the disc to be changed as needed in copy {off}|MQ(uick)|I|IUse application workspace to speed file transfer {off}|MR(ecurse)|ICopy subdirectories and contents {off}|MS(tamp)|I|IRestamp datestamped files after copying {off}|MsT(ructure)|ICopy only the directory structure {off}|MV(erbose)|IPrint information on each object copied {on}|MSyntax: *Copy <source spec> <destination spec> [<options>]
Count:*Count adds up the size of one or more files that match the given wildcarded specification. Options are taken from the system variable Count$Options and those given to the command.|MOptions: (use ~ to force off,eg. ~R)|MC(onfirm)|IPrompt for confirmation of each count {off}|MR(ecurse)|ICount subdirectories and contents {on}|MV(erbose)|IPrint information on each file counted {off}|MSyntax: *Count <file spec> [<options>]
Dir:*Dir selects a directory as the current directory (default is user root directory).|MSyntax: *Dir [<directory>]
EnumDir:*EnumDir creates a file of filenames from a directory that match the supplied wildcarded specification (default is *).|MSyntax: *EnumDir <directory> <output file> [<pattern>]
Ex:*Ex lists all the objects in a directory together with their file information (default is current directory).|MSyntax: *Ex [<directory>]
FileInfo:*FileInfo yields the full file information of an object.|MSyntax: *FileInfo <object>
Info:*Info lists the file information of all objects matching the given wildcarded specification.|MSyntax: *Info <object>
LCat:*LCat lists all the objects in a subdirectory relative to the library (default is current library).|MSyntax: *LCat [<directory>]
LEx:*LEx lists all the objects in a subdirectory of the library together with their file information (default is current library).|MSyntax: *LEx [<directory>]
Lib:*Lib selects a directory as the current library (default is filing system dependent).|MSyntax: *Lib [<directory>]
Rename:*Rename changes the name of an object. It cannot be used to move objects between filing systems or between discs on the same filing system; *Copy with the D(elete) option must be used instead.|MSyntax: *Rename <object> <new name>
Run:*Run loads and executes the named file, passing optional parameters to it.|MSyntax: *Run <filename> [<parameters>]
SetType:*SetType sets the file type of the named file to the given textual file type or hexadecimal number. If the file is not already datestamped then it is also stamped with the current time and date.|M"*Show File$Type*" displays currently known file types.|MSyntax: *SetType <filename> <file type>
Shut:*Shut closes all open files on all filing systems.|MSyntax: *Shut
ShutDown:*ShutDown closes all open files on all filing systems, logs off file servers and causes hard discs to be parked.|MSyntax: *ShutDown
Stamp:*Stamp sets the datestamp on a file to the current time and date. If the file is not already datestamped then it is given file type Data (&FFD).|MSyntax: *Stamp <filename>
Up:*Up moves the current directory up the directory structure by the specified number of levels.|MSyntax: *Up [<levels>]
Wipe:*Wipe deletes one or more objects that match the given wildcard specification. Options are taken from the system variable Wipe$Options and those given to the command.|MOptions: (use ~ to force off,eg. ~V)|MC(onfirm)|IPrompt for confirmation of each deletion {on}|MF(orce)|I|IForce deletion of locked objects {off}|MR(ecurse)|IDelete subdirectories and contents {off}|MV(erbose)|IPrint information on each object deleted {on}|MSee also *Delete.|MSyntax: *Wipe <file spec> [<options>]
Back:*Back swaps the current and previous directories.|MSyntax: *Back
URD:*URD selects a directory as the user root directory (default restores the URD to & or $ as appropriate).|MSyntax: *URD [<directory>]
NoDir:*NoDir unsets the currently selected directory on the temporary filing system.|MSyntax: *NoDir
NoURD:*NoURD unsets the user root directory on the temporary filing system.|MSyntax: *NoURD
NoLib:*NoLib unsets the library directory on the temporary filing system.|MSyntax: *NoLib
FileSystem:*Configure FileSystem sets the default filing system.|MSyntax: *Configure FileSystem <fs name>|<fs number>
Truncate:*Configure Truncate sets whether filenames should be truncated when too long.|MSyntax: *Configure Truncate on|off
SUBT > Sources.HelpSrc
[ International_Help <> 0
Access_Help = "HFLSACC",0
Access_Syntax = "SFLSACC",0
Cat_Help = "HFLSCAT",0
Cat_Syntax = "SFLSCAT",0
CDir_Help = "HFLSCDR",0
CDir_Syntax = "SFLSCDR",0
[ hascopy
Copy_Help = "HFLSCPY",0
Copy_Syntax = "SFLSCPY",0
[ hascount
Count_Help = "HFLSCNT",0
Count_Syntax = "SFLSCNT",0
Dir_Help = "HFLSDIR",0
Dir_Syntax = "SFLSDIR",0
EnumDir_Help = "HFLSEDR",0
EnumDir_Syntax = "SFLSEDR",0
Ex_Help = "HFLSEX",0
Ex_Syntax = "SFLSEX",0
FileInfo_Help = "HFLSFIN",0
FileInfo_Syntax = "SFLSFIN",0
Info_Help = "HFLSINF",0
Info_Syntax = "SFLSINF",0
LCat_Help = "HFLSLCT",0
LCat_Syntax = "SFLSLCT",0
LEx_Help = "HFLSLEX",0
LEx_Syntax = "SFLSLEX",0
Lib_Help = "HFLSLIB",0
Lib_Syntax = "SFLSLIB",0
Rename_Help = "HFLSREN",0
Rename_Syntax = "SFLSREN",0
Run_Help = "HFLSRUN",0
Run_Syntax = "SFLSRUN",0
SetType_Help = "HFLSSTY",0
SetType_Syntax = "SFLSSTY",0
Shut_Help = "HFLSSHT",0
Shut_Syntax = "SFLSSHT",0
ShutDown_Help = "HFLSSHD",0
ShutDown_Syntax = "SFLSSHD",0
Stamp_Help = "HFLSSTM",0
Stamp_Syntax = "SFLSSTM",0
Up_Help = "HFLSUP",0
Up_Syntax = "SFLSUP",0
[ haswipe
Wipe_Help = "HFLSWIP",0
Wipe_Syntax = "SFLSWIP",0
[ Version >= 170
Back_Help = "HFLSBCK",0
Back_Syntax = "SFLSBCK",0
URD_Help = "HFLSURD",0
URD_Syntax = "SFLSURD",0
NoDir_Help = "HFLSNDR",0
NoDir_Syntax = "SFLSNDR",0
NoURD_Help = "HFLSNUR",0
NoURD_Syntax = "SFLSNUR",0
NoLib_Help = "HFLSNLB",0
NoLib_Syntax = "SFLSNLB",0