6 Filing system commands

This section describes the filing system commands available. These
commands are only active when HDFS is the current filing system. The
syntax of each command is given in the section title. All of these
commands may be prefixed by 'H' to distinguish them from similar commands
in other ROMs. The output of these commands cannot be *SPOOLed (the *SPOOL
file is actually turned off if output is generated by these commands).

6.1 *ACCESS afsp (LXWR)
 This command changes the permissions on the files or directories
specified.

6.2 *ATTRIB fsp (load exec) (len) (LXWR)
 The attributes of a file can be changes with this command. The file's
length cannot be made longer than the space available for it. As files are
held in contiguous blocks, the space available is the number of sectors
used by the file plus the number of sectors free immediately after it.

6.3 *BUILD fsp (A)
 Simple text files can be created with this command. Lines are read in,
and written to the file. The A flag indicates that the file should be
appended to, rather than overwritten. Due to space limitations, there is a
limit of 63 characters per input line. The execution address of files
created with *BUILD is set to &FFFFFFFF, because it is assumed that they
will be used for *EXECing.

6.4 *COMPACT (dsp) (D)
 This command compacts the directory specified, or the current directory
if no directory is given. Files are moved together so that the maximum
amount of free space is left in the directory. If the D flag is given,
the directory specified will be shortened so that there is no free space
left. This command overwrites the contents of the I/O processor memory,
so it should not be issued if there is valuable data in memory which has
not been saved.

6.5 *COPY <fsp fsp/afsp dsp> (C)
 Files or directories can be copied between different directories or discs
with this command. Files or directories can also be copied to a dif ferent
name on the same disc with the command. There are two different forms for
this command; if two filenames are specified, the contents of the first
file will be copied into to the second. If an ambiguous file specification
and a directory specification are given, all of the files matching the
ambiguous file specification will be copied into the directory . Either a
DNFS or an HDFS directory can be given, and files can be copied between
HDFS and DNFS discs. The C flag prompts to change the disc between reading
and writing files, so files can be transferred to other discs with one
disc drive. The maximum amount of information is read or written each time
the disc is changed, so the fewest number of disc changes possible will be
used. This command overwrites the contents of the I/O processor memory ,
so it should not be issued if there is valuable data in memory which has
not been saved.

6.6 *CREATE fsp (load exec) (len) (LXWR) (D)
 This command creates a new file entry or directory, but does not actually
write any data into it. If the load and execution addresses and the length
are not specified, they default to zero. The D flag indicates that a
directory is to be created; in this case, the length must be a whole
number of sectors, greater than two. A new catalogue is initialised in the
first two sectors of the directory . Note: when creating directories, at
least one of the attributes LXWR should be given, otherwise the D flag may
be mistaken for the directory's length. It is a good idea to make
directories bigger than required initially, as they can be shrunk to fit
the files easily later, and files can be shuffled around inside them. The
file or directory's length cannot be made longer than the space available
for it.

6.7 *DEDIT (drv) start (+) ((+) (R)
 This command invokes the disc, file, and memory editor on the section of
the disc specified by the start sector, up to but not including the end
sector. If an offset is supplied, the cursor will be placed at that point
initially. The R flag invokes the editor in read-only mode, which can be
used to view the data but not change it. If no disc drive is specified,
the current drive is used.

6.8 *DELETE fsp
 This command deletes the file or directory specified. Directories cannot
be deleted unless they are empty. Locked files or directories cannot be
deleted.

6.9 *DFIND (drv) start (+) <string/{ hex }>
 Data on a disc can be searched for with this command. The sector and byte
address of each occurrence of the data is displayed. The search performed
by this command is optimal. The data to search for is specified by a
string or a sequence of hex numbers. The maximum length of the string or
sequence of hex numbers is 31 bytes. The area of the disc to search is
delimited by the start and end sector addresses. If no disc drive is
specified, the current drive is used.

6.10 *DIR (dsp)
 This command sets the current directory to the directory name specified.
If no directory name is specified, it lists the contents of the current
directory.

6.11 *DRIVE drv (S/D/A) (C)
 This command sets the current drive, or affects the parameters of a
drive. If the S, D, or A flags are given, the drive is set into single
step, double step, or auto-step mode. Single step mode should be used for
40 track drives; HDFS otherwise assumes that 80 track drives are used, and
will try to double step. The double step mode allows 40 track discs to be
read on 80 track disc drives. Normally auto mode is enabled, in which
double stepping will be used for 40 track discs. The single or double-step
modes may also be necessary when a disc has a copy protection scheme which
alters the normal track layout or number of sectors per disc. The default
value of the single and double step mode for all drives can be set with
the keyboard links described in appendix B. The C flag disables sector
address checks, which normally prevent access to sectors outside the range
on the disc. This may be needed to allow some elaborate copy-protection
schemes to work.

6.12 *DUMP fsp
 A hexadecimal dump of the file is displayed by this command, with an
ASCII representation beside it. In 80-column display modes, 16 bytes are
shown per row . In 40 and 20-column display mode, 8 bytes are shown. The
dump shows the address of the row (relative to the start of the file) the
byte values in hexadecimal, and then their ASCII representation. Non-
printable characters appear as dots. Bytes past the end of the file appear
as asterisks.

6.13 *ENABLE
 This command does nothing; it is allowed for compatibility with DNFS.

6.14 *EXTEND fsp
 This command ensures that the file or directory specified has the largest
space possible to grow into, without shuffling other files around. This
may involve moving the file itself. The sequence *COMPACT, then *EXTEND,
and then *COMPACT again will usually create the maximum space possible for
growth. This command overwrites the contents of the I/O processor memory,
so it should not be issued if there is valuable data in memory which has
not been saved.

6.15 *FEDIT fsp (offs) (R)
 This command invokes the disc, file, and memory editor on the file
specified. If an of fset is supplied, the cursor will initially be placed
at that point relative to the start of the file. The cursor will not be
allowed to move outside the bounds of the file. The R flag invokes the
editor in read-only mode, which can be used to view the data but not
change it.

6.16 *FFIND fsp (offs) <string/{ hex }>
 Data in a file can be searched for with this command. The address of each
occurrence of the data relative to the start of the file is displayed. The
search performed by this command is optimal. The data to search for is
specified by a string or a sequence of hex numbers. The maximum length of
the string or sequence of hex numbers is 31 bytes. An offset can be given
to start the search part way through the file. Note that if a sequence of
hex numbers is given the of fset must be specified, otherwise the first
number will be treated as the offset.

6.17 *FORMAT drv <40/80> <X/A> <S/D> (skew)
 New discs can be formatted using this command. The drive must be
specified, as well as the number of tracks to use, whether the extended
HDFS catalogue (X) or the Acorn catalogue (A) are to be used, and whether
to format single or double sided (S or D). Track numbers are printed as
each disc track is formatted. The skew parameter is a measure of how many
sectors are skipped when the drive steps between tracks. The default skew
value is 3. If a disc which is already formatted is in the specified
drive, the command will ask for confirmation before formatting.

6.18 *FREE (dsp)
 This command lists the available free spaces in the directory specified,
or in the current directory if no name is given. The start sector and
length in sectors of each free block is displayed, with a summary of the
total space available.

6.19 *INFO afsp
 Information on the files and directories which match an ambiguous file
specification is displayed by this command. This information displayed is
the name, permissions, load address, execution address, length, and start
sector of the file or directory.

6.20 *LIB (dsp)
 This command sets the current library to the directory name specified. If
no directory name is specified, it lists the contents of the current
library. The current library is searched for commands which are *RUN if
they are not found in the current directory.

6.21 *READ (drv) addr start (+) (D)
 This command reads sectors from a disc into memory. Data from the start
sector address up to but not including the end sector address will be read
into memory, starting at the address given. The D flag reads sectors which
have been saved with the 8271 disc controller chip's "deleted data" mode.
The current drive is used if none is given.

6.22 *RENAME <fsp fsp/afsp dsp> (C)
 Files can be renamed or moved between different directories or discs with
this command. There are two different forms for this command; if two
filenames are specified, the first file will be renamed to the second.
Note that this may involve moving data around if the files are in
different directories. If an ambiguous file specification and a directory
specification are given, all of the files matching the ambiguous file
specification will be moved into the directory. Either a DNFS or an HDFS
directory can be given. The C flag prompts to change the disc between
reading and writing files, so files can be transferred to other discs with
one disc drive. The maximum amount of information is read or written each
time the disc is changed, so the fewest number of disc changes possible
will be used. This command overwrites the contents of the I/O processor
memory, so it should not be issued if there is valuable data in memory
which has not been saved.

6.23 *TITLE string (dsp)
 The title of a directory can be set with this command. If no directory
name is given, the current directory is used. The title is displayed when
the directory is listed. The maximum length of a directory title is 12
characters.

6.24 *TYPE fsp (C)
 This command displays a file as text. All characters are sent to the
operating system OSASCI entry, so control characters in the file may cause
unexpected (or perhaps, desired) effects, such as changing colour, display
mode, etc. The C flag causes non-printing characters to be displayed as
their equivalent operating system escape sequence. Newlines are generated
after each RETURN (&0D) character.

6.25 *VERIFY drv <40/80> <X/A> <S/D>
 This command verifies that the data on a disc is not damaged. The drive
number, number of tracks, catalogue type, and number of sides to check are
required. The catalogue type is either the HDFS extended catalogue (X) or
the Acorn (A) catalogue. Single (S) and double sided (D) discs can be
checked. The track numbers are printed as the command executes, and a
question mark is displayed after any track number on which a verification
error occurred.

6.26 *WILD :$^.*?
 The special characters which divide file specifications can be altered
with this command. Six different characters must be specified, to replace
the default characters shown below:
 : This is the drive prefix character, which is used before drive
	specifications in contexts where they are optional.
 $ This is the root directory character, which refers to the root
	directory of the current drive.
 ^ This is the parent directory character, which is used to refer to the
	parent directory of the current directory.
 . This is the directory separator character , which is used to separate
	drive specifications from directory specifications, directory names
	from each other, and directory specifications from file names.
 * This is the glob character, which matches any number of characters in
	ambiguous file specifications.
 ? This is the query character, which matches any single character in
	ambiguous file specifications.

6.27 *WIPE afsp (A)
 This command attempts to delete the files specified. It prompts for
confirmation of deletion for each unlocked file which matches the file
specification. If this command is interrupted, no files will be deleted.
The A flag may be used to confirm all of the files for deletion; this has
a similar effect to the *DESTROY command in DNFS.

6.28 *WRITE (drv) addr start (+) (D)
 This command writes sectors to a disc from memory . Data is written at
the start sector address up to but not including the end sector address,
from the memory address given. The D flag writes sectors using the 8271
disc controller chip's "deleted data" mode. The current drive is used if
none is given.