Utility commands
			     ================
			J.G.Harston - jgh@mdfs.net
		70 Camm Street, Walkley, Sheffield S6 3TR


Most of these utilities have an embedded version number or date in them at
the end of them. If you *DUMP them, you can check the version to see if it's
newer than a version you already have.

*Break (^)<text>                                 Set Break key message v1.02
----------------------------------------------------------------------------
Puts a message on the Break key, using the Break Intercept Vector. If the
'^' prefix is given, the string appears at the top of the screen. If there
if no '^' prefix, the message appears just before the filing system message.
You can use any string that can be put on a function key, ie you can use '|'
to specify control characters.


*Close                                                 Close all files v0.01
----------------------------------------------------------------------------
*Close closes all open files on the current filing system by doing CLOSE#0.


*CLoad <afsp> (<char>/VDU)                             Load characters v1.03
----------------------------------------------------------------------------
*CLoad loads in a set of character definitions from a file. The optional
start parameter is the hex code of the character to start at.

If the 'V' parameter is given or the file has a load address of &FFFFF7xx
(ie is file-typed to &FF7), then the file is loaded as a RISC OS font file
with ten bytes per character definition, with the actual VDU 23 sequence in
the file, so no start parameter is needed.

Otherwise, then the file is loaded as binary in groups of eight bytes for
each character. If no start character is given, then the length of the file
rounded up to 256 bytes is examined. If the file length is &300 bytes or is
greater than &400 bytes then loading starts at character 32 (20), otherwise
loading starts at character 128 (80).


*CSave <fsp> <first char> <last char> (VDU)            Save characters v1.03
----------------------------------------------------------------------------
*CSave saves a set of character definitions. You must give the hex code of
the first character to be saved and the hex code of the last character to be
saved.

If the 'VDU' (or 'V') parameter is not given, then the file is saved in
binary as eight bytes for each character. If the 'V' parameter is given, the
file is saved as a RISC OS BBC Font file with ten bytes per character as the
VDU 23 sequence needed to define each character, and is file-typed to &FF7
by setting the load address to &FFFFF700 and the execution address to
&FFFFFFFF. This means that you can *RUN the file from ADFS, ANFS or HADFS
and have it *Exec'd instead.


*Explode (ON|OFF)                                Explode character set v0.02
----------------------------------------------------------------------------
Explode the character set and allows all the characters to be defined.
*Explode on its own just does the same as *FX20,6, ie explodes the
characters. *Explode ON explodes the character set and sets up a Break
Intercept to re-explode the set on Break. *Explode OFF disconnects this
Break intercept. The command exits by re-entering the current language if
it needs to take account of any change in PAGE. On a Tube system or a Master
series, the command is ignored, as the character set is already fully
exploded. Code resides at &131 to &13C.


*FInfo (-|=)<afsp>                          Read full file information v1.03
----------------------------------------------------------------------------
Reads the file information with OSFILE 5 and displays it all, including any
parts not used by the filing system being used. The information is displayed
in the following format:

	name       loadaddr execaddr   length attrs   date     xx tt type
eg:	Hello      FFFF1900 FFFF8023   00125F WR/WR   12/10/87 00 01 File

If TT is 00, 01 or 02, the type is Not Found, File or Directory. xx is the
fourth byte of the attributes (blk+17) that is unused in most filing
systems. If the fourth byte of the length (blk+13) is not zero, ie the
length if larger than &FFFFFF, then that byte is displayed as well. The
attributes are read from blk+14, and the date from blk+15 and blk+16.

You will notice on DFS that only the 'L' bit gets set, and so files appear
to have no 'R' and 'W' setting.

If the filename is preceded by '=', the control block is not blanked before
use, so you can see if any parts are not actually changed. So if you use
*FInfo =file where the file does not exist it will show an example of
out-of-range values.


*LoadCMOS <afsp>                           Load configuration settings v1.00
----------------------------------------------------------------------------
Loads a CMOS configuration file and writes it to configuration RAM/EEPROM.
Gives the error 'Bad file' if the file is too long or too short.


*MCode <afsp> (<addr>)                    Makes BASIC program *RUNable v1.35
----------------------------------------------------------------------------
Adds a machine code footer to a BASIC program so it can be called with *RUN.
If an address is given, it is used as the file's load address, otherwise the
file relocates down to the value of PAGE when run.

On running, the program has Q% set to the original PAGE, and the full
command line, including the command used to start the program, is placed in
the general string accumulator, (at $&600 in 6502 BBC BASIC) where it can be
retrieved with the standard FNOS_GetEnv function. To exit to the previous
environment if no -quit processing is carried out, the program can use:

        PAGE=Q%:END

MCoded programs will run in a standalone I/O processor or will copy over the
Tube to whatever language processor is being used. Note, that if the MCoded
program itself relies on specifiy CPU facilities, such as the 6502
assembler, then it will only run on that appropriate second processor.

*MCode itself, as it assembles a piece of 6502 code, will only work on a BBC
or 6502 CoPro, and will give an appropriate error in other CPU environments.


*MDump (-<cols>) <start> <end>|+<length>                   Dump memory v1.06
----------------------------------------------------------------------------
Displays an area of memory in a similar way to *Dump. If the -<cols>
parameter is given it specifies the number of columns to display. If it is
not given, the dump lists in 16 columns in MODE 0 and 3, and 8 columns in
other MODEs. The <start> address can specify various sections of memory in a
similar way to *SAVE.

	FFFFmmmm I/O memory      at &0000-&FFFF
	FFFEmmmm screen memory   at &3000-&7FFF
	FFFDmmmm shadow memory   at &3000-&7FFF
	FFxRmmmm sideways ROM R  at &8000-&BFFF
	FF8xmmmm workspace RAM   at &8000-&9FFF and &C000-&DFFF
	FFCxmmmm hidden MOS ROM  at &C000-&FFFF
      <>FFmmmmmm Language memory


*Mouse (ON/OFF)                                           Mouse driver v1.20
----------------------------------------------------------------------------
*MOUSE enables mouse support routines. Once the mouse is turned on, its
position and button state can be read using OSBYTE or OSWORD. The OSBYTE
routines are accessible using the INKEY and ADVAL calls.

	ADVAL(7)  OSBYTE &80,&07,&00  Mouse X position
	ADVAL(8)  OSBYTE &80,&08,&00  Mouse Y position
	INKEY-10  OSBYTE &81,&F6,&FF  Mouse left button
	INKEY-11  OSBYTE &82,&F5,&FF  Mouse middle button
	INKEY-12  OSBYTE &82,&F4,&FF  Mouse right button

For compatibility, the mouse state can also be read using OSWORD 64, which
returns the following information:

	XY+0,1	Mouse X coord
	XY+2,3	Mouse Y coord
	XY+4	Text X coord (POS)
	XY+5	Text Y coord (VPOS)
	XY+6	button state, %rml00000, 0 - button pressed

INKEY-107, INKEY-108 and INKEY-109 will also return the state of the left,
middle and right buttons.

*MOUSE configures itself for the appropriate wiring for the BBC/Master or
for the Compact. This can be overridden with *MOUSE AMX to use the AMX
wiring or *MOUSE COMPACT, *MOUSE MARCONI or *MOUSE RB5 to use the Compact
wiring, which is also used by the Marconi RB5 trackerball.

The code resides in page &A.


*Repeat <cmd> (<dir>) -r -v -f -d -a -t <tail> -quit <command>         v0.13
----------------------------------------------------------------------------
Repeatedly performs the command with the command tail on all the entries in
the current or optionally specified directory. The following options can be
used:

-recurse recurses into directories
-verbose displays each command before executing it
-file    only act on files
-dir     only act on directories
-app     only descend into applications (directories starting with !)


*ROMS (*)                                                    List ROMs v1.12
----------------------------------------------------------------------------
Lists the ROMs in the machine. If any parameter is given, the copyright
message is displayed and duplicate and empty banks are listed. Any RAM banks
will be listed as 'RAM'. To run on a machine with a built-in *ROMS command,
use */ROMS. Works correctly with Electron sideways ROMs and with EEPROMs.


*SaveCMOS <fsp>                            Save configuration settings v1.01
----------------------------------------------------------------------------
Saves the CMOS configuration settings to the specified file, so they can be
reloaded with *CMOSLoad. Saves the number of locations specified by reading
CMOS location 255, defaulting to 50.


*ScrLoad <afsp>                            Load compressed screen dump v1.07
----------------------------------------------------------------------------
Loads in a compressed screen picture saved with *ScrSave with its palette
information. Works with shadow screen on: Master, Aries-B32 and Watford 32K
RAM Card. If a shadow screen MODE is currently being displayed, then any
MODE change will remain a shadow MODE. On a B+ non-shadow MODEs are forced.
Shadow screen cannot be supported on the B+ as the hardware only allows the
VDU driver code between &C000 and &DFFF to access the shadow screen memory.


*ScrSave <fsp>                             Save compressed screen dump v1.06
----------------------------------------------------------------------------
Saves a screen picture, and attempts to compress it. If compressing it would
make a longer file (as a very detailed picture would), then the picture is
saved without compressing it. Works with shadow screen on: Master, Aries-B32
and Watford 32K RAM Card.

The palette information, screen mode and compression information is saved in
the load and execution addresses of the file as follows:

Load address:      &FFFFabbbb
    a:   currently unused and ignored
    bbb: colours 4 to 7 held as %777666555444 in sixteen colour MODE

Execution address: &iiipmcccc
    iii:  000 for compressed, FFF for uncompressed
    p:    if compressed, number of passes-1 otherwise F
    m:    screen MODE
    ccc:  colours 0 to 3 held as %333222111000

For example, the file:

    JARRE   FFFF3000 FFFF10CC 5000

is uncompressed, screen MODE 1, palette entries 4, 1, 3, 0.

The file:

    PYRAMID FFFF0FAC 00002248 0A94

is compressed, one pass, MODE 2, palette entries 0, 1, 1, 1, 4, 5, 6, 7.

With a sixteen colour screen MODE, the first four bytes of the file are
replaced with palette colours 8 to 15. On loading with *ScrLoad, these four
bytes are set to the same as the following four bytes.

Compressed file contents are run-length encoded. The file is a series of
pairs of bytes, each pair being {run},{value}. A run of &00 means a run of
256 bytes.


*SetAddr <afsp> <load> <exec>           Set file load and exec address v1.00
----------------------------------------------------------------------------
Sets the specified file's load and execution addresses.


*SetExec <afsp> <addr>                           Set file exec address v1.00
----------------------------------------------------------------------------
Sets the specified file's execution address.


*SetLoad <afsp> <addr>                           Set file load address v1.00
----------------------------------------------------------------------------
Sets the specified file's load address.


*SetType <afps> <type>                                   Set file type v1.00
----------------------------------------------------------------------------
Sets the specified file's filetype by setting the load address to &FFFttt00.


*Show (<keynum>)                                   Show key definition v1.01
----------------------------------------------------------------------------
*Show displays function key definitions in GSTrans format suitable for
setting the key strings. If no <keynum> is given, all key definitions are
listed.


*SMFree                   Lists free space in sideways RAM/ROM modules v0.10
----------------------------------------------------------------------------
Lists the free space in sideways ROM/RAM banks that relocatable modules
could be loaded to in the following format:

FFFFBFF8 + 0008 TERMINAL
FFFEBFF5 + 000B BASIC   
FFFD8000 + 4000
FFFCBEF6 + 010A VIEW
etc.
Total: 0000B019, 45081 bytes


*SMList                                 Lists sideways RAM/ROM modules v0.16
----------------------------------------------------------------------------
Lists all relocatable modules in the following format:

No. Position Name                Version
  1 FFFF8000 TERMINAL             1.00               (C)1984 Acorn
  2 FFFC8000 BASIC                4.00               (C)1984 Acorn
  3 FFF78000 HADFS                5.62 (17 Feb 2012) (C)J.G.Harston
  4 FFF7B7E0 NullKeyboard         0.12 (01 Aug 1998) (C)JGH
  5 FFF4976D Library Maximiser    0.11 (28 Feb 1999) (C)JJR,JGH


*SMLoad <filename>                 Load relocatable sideway RAM module v0.13
----------------------------------------------------------------------------
*SMLoad loads a relocatable module or sideways ROM to the highest available
area of sideways RAM large enough.

If the loaded file has a relocation table it is relocated and linked into
the module chain. If it does not have a relocation table then it will only
be enabled if it is loaded to the start of a bank or SRAM at &8000. If there
is no more free SRAM the error 'Not enough SRAM' (ERR 133) is given. See the
ModInfo file for more information.


*SpoolOn (<filename>)                             Spool to end of file v1.00
----------------------------------------------------------------------------
Replicates the Master MOS *SpoolOn command. Spools to a file by appending to
the end of it. *SpoolOn with no parameter closes any open Spool file.


*SrLoad <afsp> (<addr>) (<rom>) (I)(R)(P)(Q)            Load ROM image v1.05
----------------------------------------------------------------------------
Loads a ROM image into sideways RAM or EEPROM. Any address is ignored and
8000 is always used. The ROM number can be given in hex or in decimal.
If the ROM number is not given, the highest available unused bank is used.
If no RAM can be found, the error 'No free SRAM found' (ERR 133) is given.
If the bank selected is unwritable the error 'Bank not writable' (ERR 135)
is given. The following parameters can also be used:

	I: Insert.  If the ROM has a valid header the ROM's type byte is
		    placed into the MOS's ROM type table.
	R: Run.     The ROM is entered as a language after loading. The ROM
		    has to have been inserted for the option to have an
		    effect.
	P: Pause.   The user is prompted to press a key before loading.
		    This option can allow you to change disks before
		    loading.
	Q: Quick.   The ROM is loaded quickly by loading the whole image to
		    main memory in the 16K of memory below screen memory
		    before being copied into sideways RAM. If there is not
		    enough free memory shadow MODE 7 is selected before
		    loading.

The 'Q' option is always selected in the current version. Works correctly
with Electron sideways ROMs and with EEPROMs.


*SrSave <fsp> (<addr>(+)<addr>) <rom> (P)(Q)            Save ROM image v1.05
----------------------------------------------------------------------------
Saves a sideways ROM image. Any addresses are ignored and the whole ROM is
saved, from 8000 to BFFF. The ROM number can be given in hex or in decimal.
The following parameters can also be used:

	P: Pause.   The user is prompted to press a key before saving. This
		    option can allow you to change disks before saving.
	Q: Quick.   The ROM is saved quickly by being copied to main memory
		    in the 16K of memory below screen memory before being
		    copied into sideways RAM. If there is not enough free
		    memory shadow MODE 7 is selected before saving.

The 'Q' option is always selected in the current version. If the ROM being
saved has a second processor relocation address, then the load and execution
address of the saved file is set to this, otherwise, they are set to &8000
if it is a language ROM, or &FFFF8000 if it is a service ROM. Works
correctly with Electron sideways ROMs and EEPROMs.


*SrWipe <rom>                                        Wipe sideways RAM v1.04
----------------------------------------------------------------------------
*SrWipe wipes the specified sideways RAM bank and clears its entry in the
ROM type table. The ROM number can be given in hex or in decimal. Works
correctly with Electron sideways ROMs.


*Stamp <afsp>                                            Set file date v1.04
----------------------------------------------------------------------------
Sets the specified file's modification date to 'today'.


*TreeCopy (<fs>:)<src> (<fs>:)<dest> ACEFPRS (-dest) (-quit (*)<name>) v1.63
----------------------------------------------------------------------------
TreeCopy will copy files between filing systems, preserving the directory
structure, file attributes and creation/modification dates as much as
possible. The program is quite easy and self-explanatary to use. It has been
completely written to be fully error-trapped, allow disk swapping, and it
reads as many files as possible before writing, thereby reducing disk swaps.
When asked for filing systems or directory names, you can enter a *command
by starting it with a *.

When run you are prompted for the source and destination filing systems and
directories, and a set of copying options. TreeCopy can also take the
following command line parameters, which must be in this order:

  *TreeCopy (<fs>:)<src> (<fs>:)<dest> ACEFPRS (-dest) (-quit (*)<name>)

An example command line would be:

    *TreeCopy HADFS::0.$ NET::USER.$.Disk1 ~C~PR -quit &.MenuProg
or
    CHAIN "TreeCopy DISK::0.$ HADFS::4.BACKUP.Disk1 A~C~PS -quit $.MenuProg"

The <src> and <dest> directories can be prefixed by a filing system
selection command terminated with a :, eg ADFS::0.$ The single character
options control the level of copying:

		A - Copy all DFS directories	(default off)
		C - Confirm			(default off)
		E - Expand DFS directories	(default off)
		F - Force overwriting		(default off)
		P - Pause to change disk	(default off)
		R - Recurse			(default on)
		S - Put DFS files in subdirs	(default on)

They can be prefixed with '~' to turn off the option, eg ~C means no
confirm. If the -dest option is given, then TreeCopy will terminate with the
destination filing system selected. Otherwise, the source filing system
remains selected.

The -quit option can give a file to run on exit. If the name starts with a
*, then it is called as a *Command, otherwise it is CHAINed.

* When 'C'onfirm is selected, you are prompted Yes/No/All to copy each file
  and directory. If you select 'All', then confirmation is turned off and
  all further files are copied.

* When 'F'orce is selected any locked destination files are unlocked before
  overwriting them. If 'F'orce is not selected you are prompted 'File
  locked. Overwrite? Yes/No/All'. If you select 'All' all future locked
  files are overwritten.

* When copying to DFS or DFS-like filing systems filenames are shortened to
  seven characters.

* When copying from DFS or DFS-like filing systems the 'Copy all DFS
  directories' option allows you to copy the whole disk, creating an
  approximation of the DFS directory structure by putting all the non-$
  directories into subdirectories.

* Selecting the 'Put into subdirs' option will copy DFS files into
  subdirectories for each non-$ DFS directory. Turning this option off will
  save files in the destination directory prefixed with "x/", where x is the
  DFS directory. For example, the DFS file "B.Prog" becomes "B/Prog".

* When copying to DFS or DFS-like filing systems selecting the 'Expand into
  DFS directories' option will copy files with a "x/" prefix into the DFS
  directory "x". For example, the file "B/Prog" becomes the DFS file
  "B.Prog".

Creation and modification metadata is recognised on Acorn File Server, SJ
MDFS File Server and HADFS. If copying to a filing system with less metadata
then the unsupported metadata will be lost. If copying to a filing system
with more metadata then the creation and modification dates are set the
same.

When running LoBASIC on the 6502 CoPro, TreeCopy will relocate itself to
maximise available memory.


*TxSave <afsp>                                Save screen as text file v0.01
----------------------------------------------------------------------------
Saves the current screen as a *PRINTable text file. The resultant file
starts with a MODE selection and contains all the characters on the screen.
Any top-bit-set characters have a VDU 23 definition sequence saved with
them. Any character that is unrecognised is defined as the pixels on screen
and the resulting VDU 23 definition is saved.


*XTree -apps -count -files -grain <size> -info -list -mask <mask> -print path
-----------------------------------------------------------------------------
Displays directory tree, v1.17. Takes the following options:

-apps	descend into RISC OS !AppName application directories
-count	display a count of all files
-grain	specify grain size for counting files, default is 256 bytes
-info	display full object infomation
-list	display single-line listing of full pathnames
-mask	attribute bitmask
-print	use PC-8 lindraw characters