MkImg and UnImg - Make Disk Images and Extract from Disk Images
      ===============================================================
                         J.G.Harston - 1999-2020
                 mdfs.net/Apps/DiskTools -- jgh@mdfs.net
                70 Camm Street, Walkley, Sheffield S6 3TR


MkImg is a program that creates DFS, ADFS and HADFS disk images from a set
of files. UnImg is the complementary program that extracts files from DFS,
ADFS and HADFS disk images. They run on BBC/Master, RISC OS and DOS/Windows.
They can be called as a *command or CHAINed.


MkImg - create disk image
~~~~~~~~~~~~~~~~~~~~~~~~~
MkImg takes various parameters, displayed with the -? option. Where listed,
options can be specified with a single character.

Syntax: MkImg outfile inpath -c cycles -fs type -@ -i@file -o opt
        -p -q -r -R root -s size -t title -quit command

outfile         disk image file to create, will be filetyped to &B22 or &FCE
                on BBC or RISC OS.

inpath          source pathname to read files from.

-cycles num     Set disk cycle number.

-fs type        Specify the disk image type. Recognised disk types are:
                   DFS       Acorn 31-file DFS
                   DFS62     Watford 62-file DFS
                   ADFS      Acorn ADFS
                   HADFS     Harston ADFS 16-bit disk (up to 16M)
                   HADFS24   Harston ADFS 24-bit disk (up to 4G)

                If not specified, then defaults to DFS. If HADFS is
                specified but a large disk size is specified, then HADFS24
                is selected.

-i@file         Read a list of filenames to include from the specified text
                file. This list can include replacement filesnames to store
                in the disk image.

-@              Read a list of filename to include from standard input.

-opt num        Set the disk boot option.

-pad            Pad output file to full disk size.

-quiet          Suppress all display output.

-recurse        Recurse into subdirectories. This will also create two DFS
                disk images if the source directory has subdirectories '0'
                and '1' or '0' and '2'.

-R rootdir      Specify DFS root directory. This allows the creation of
                Atom/System DOS images with -R " " to place files in the " "
                directory instead of the "$" directory.

-size num       Specify maximum disk size in K or M, for example '-s 200K'
                specifies a maximum 200K disk image, as with a single-sided
                80-track DFS disk. If no size is specified, the final disk
                image's size will be the total size of the included files.

                The following table shows the maximum disk sizes:

                fs type     sector numbers    maximum disk size
                  DFS           10-bit              256K
                  DFS62         10-bit              256K
                  ADFS          21-bit              512M
                  HADFS         16-bit               16M
                  HADFS24       24-bit             4096M

-title string   Specify the disk title.

-quit command   Call the specified command on exit. If the command starts with
                a '*', then it is called as a *command, otherwise it is
                CHAINed. OSBYTE 1 or the DOS ERRORLEVEL is set to any error
                number. This will be 0 for no error. -quit must be the final
                option on the line.

Example commands
----------------
MkImg Utils1/ssd $.Disk.JGH.Utilities1 -o 3 -t Utilities1 -q -quit *Dir $.Image.JGH

MkImg -hostfs-$.DiskImages.Apps/ssd :Apps.$ -t Apps -fs hadfs -quit *Dir &.Makefiles

MkImg L3Util/adf $.L3FS.Utils -fs adfs -p -s 640K -t L3FSUtils -quit *Dir $.L3FS

You can include files listed in an Exec file with the -@ option, for example
with a file containing:

*MkImg outfile @ -@ -fs dfs -size 200K
BASIC1,%.BASIC1
Tiny65,TINY65

If you *EXEC this file, it will output to 'outfile', reading from '@' the
current directory, with -@ specifying the input is the standard input, which
will be the Exec file being read. The file list lists on each line the
source file to read, followed - after a comma - with the filename to use to
store the file. In this example, '%.BASIC1' specifies that the file should
be stored in the DFS '%' directory, and 'TINY65' will be stored in the '$'
directory.

Example DOS/Windows commands
----------------------------
MkImg L3Utils.adf H:\L3FS\Utils -fs adfs -t L3FSUtils

DFS disk images
---------------
When copying files to a DFS image, files are put in the DFS '$' directory
(or the directory specified with the -R option), unless the filename has a
"/xxx" extension. Then, the first character of the extension, is used as the
DFS directory. For instance, "HDInit" becomes the DFS filename "$.HDInit",
and "HDInit/txt" (or "HDInit.txt" on non-Acorn systems) becomes the DFS
filename "T.HDInit".

When copying recursively with the -r option, then files in single-character
subdirectories are placed in the equivalent single-character directories in
the DFS image. For instance, "A.Asm32" (or A/Asm32 on non-Acorn systems)
becomes the DFS file "A.Asm32".


UnImg - extract from disk image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
UnImg takes various parameters, displayed with the -? option. Where listed,
options can be specified with a single character.

Syntax: UnImg infile -d outdir -fs type -dsd -s -e -i -X -q -quit command

infile          disk image file to extract from.

-d outdir       optional destination directory to extract file to. By
                default all files are extracted to the current directory.

-fs type        Specify the disk image type. Recognised disk types are:
                   DFS       Acorn DFS
                   ADFS      Acorn ADFS
                   HADFS     Harston ADFS

                If not specified the image is examined to try and work out what
                filesystem it contains. If it cannot be recognised an error is
                returned.

-dsd            Treat the source file as an interleaved image. ADFS images
                are treated as 16*256 bytes per track, all other images are
                treated as 10*256 bytes per track.

-sub            Extract DFS files to subdirectories.
-ext            Extract DFS files with extensions.
                If neither of these options are uses, DFS files are
                extracted with the filename prefixed with the DFS directory
                character, eg T.ReadMe -> T/ReadMe on Acorn systems,
                T.ReadMe on non-Acorn systems. DFS directory '$' and ' '
                (space) are extracted with no directory character.

-inf            On non-Acorn systems .inf files are created containing the
                Acorn metadata (load/exec addresses, etc.) This option
                forces the creation of .inf files on Acorn systems.

-X              By default, .inf files are created with only the load, exec
                and length fields. With this option the attributes and any
                other metadata is output.

-quiet          Suppress all display output.

-quit command   Call the specified command on exit. If command starts with
                a '*', then it is called as a *command, otherwise it is
                CHAINed. OSBYTE 1 or the DOS ERRORLEVEL is set to any error
                number. This will be 0 for no error. -quit must be the final
                option on the line.

UnImg currently does not have an option to extract the second side from a
two-sided DFS disk. Only the first 31 files from Watford DFS62 images are
extracted.

Example commands
----------------
UnImg Utils1/ssd -d $.Disk.JGH.Utilities1 -fs dfs -q -quit *Dir $.Image.JGH

UnImg -hostfs-$.DiskImages.Apps/ssd -d :Apps.$ -fs hadfs -quit *Dir &.Makefiles

UnImg L3Util/adf -d $.L3FS.Utils -fs adfs

Example DOS/Windows commands
----------------------------
UnImg L3Utils.adf -d H:\L3FS\Utils -fs adfs


Running on DOS/Windows
~~~~~~~~~~~~~~~~~~~~~~
MkImg will read file metadata from .inf files with the same filename as the
source file with a ".inf" extension, and UnImg will create .inf files. A
.inf file is a text file with some of the following contents:

  filename(spc)loadaddr(spc)execaddr(spc)length(spc)access(spc)(any other metadata)

MkImg only looks for load/exec addresses and access, any length field is
ignored, eg:

  BACKUP FFFF5D80 FFFF7B00 00129A 13

If there is no .inf file, or the load address is missing, the load address
defaults to 0. If the exec address is missing it defaults to the same as the
load address. Any length field is ignored, the length of the actual file is
used. If the access field is missing it defaults to 33 for WR/wr. The access
byte is a bitfield of %0ewrLEWR for public exec/write/read, locked, owner
exec/write/read, for instance 13 is WR/r and 0B is LWR/. As a special case
the access byte can be replaced with L which represents 19 for LR/r.

Note that DFS uses a restricted set of access values, Locked and Unlocked.
When creating a DFS disk image only the Locked bit of the source file is
used.

When creating HADFS disk images, any mdate, mtime, cdate, ctime values will
be used. mdate and mtime default to 0, cdate defaults to mdate and ctime
defaults to mtime.

UnImg creates .inf files with the file metadata. By default, it outputs the
load and exec address, the object length, and the access, eg:

  BACKUP FFFF5D80 FFFF7B00 00129A 13

With the -X option any extra metadata the filesystem supports will be
output, the mdate, mtime, cdate, ctime, account info, eg:
  
  BACKUP FFFF5D80 FFFF7B00 00129A 13 7B23
  BACKUP FFFF1900 FFFF8023 001273 33 7B23 123106 7B20 112708

When running on non-Acorn platforms, the standard filename translation is
used on non-Acorn filenames, swapping:
  # <-> ?   . <-> /   $ <-> <   ^ <-> >   & <-> +   @ <-> =   % <-> ; 


Version History
~~~~~~~~~~~~~~~
MkImg:
v1.02 01-Jul-2003 -update option added.
v1.03 06-Jul-2003 -@ option added.
v1.04 30-Jul-2003 Catalogue stored in correct sector start order, uses
                  default maximum disk size.
v1.05 09-Apr-2010 Creates double-sided disk if source dir contains two
                  directories.
v1.06 09-Aug-2011 Pads to the end of partially used sectors.
v1.07 17-Aug-2012 Creates ADFS and HADFS images.
v1.08 12-Jan-2013 DFS disk images with files in non-$ directories have a
                  correct file count. Fixed a bug introduced in v1.07.
                  ADFS/HADFS image creation updated.
v1.09 05-Mar-2013 Can create an image from a single source file.
v1.10 03-Dec-2017 Non-BBC filenames translated, added -p option.
v1.11 17-Dec-2017 dfs62 done, fixed file.txt -> t.file translation.
v1.12 12-Aug-2019 -R option added.
v1.12a            DFS L access can be set, date/time read.

UnImg:
v1.10 18-Dec-2017 Initial version, doesn't translate filenames to non-Acorn
                  systems.
v1.11 19-Dec-2017 Filenames translated.
v1.12 09-Apr-2018 Added -sub, -ext, -X options.


Notes and bugs
--------------
MkImg does not create bootable HADFS disk images. You will need to *INSTALL
the boot sectors using HADFS or HADFSFiler.

Current directory must be specified explicity,
 eg MkImg out "" etc...
 or MkImg out @ etc...

Including from a list doesn't set subdirectory correctly.
ADT,SROM.ADT or ADT,SROM/ADT
creates a file called 'SROM/ADT'

MkImg needs an option to set in-image disk size without also padding file
to full size.