********************************************************************************
                                    uBeeDisk

        A tool for converting disks/images from one to another with auto
                      detection options for Microbee disks.

                      Copyright (C) 2008-2010 Stewart Kay

For contact details please see the 'Contact' section at the end of this file.
********************************************************************************

Distribution License
====================
See license.txt in this distribution.

Overview
========
This program copies disks and images from one to another, formats disks and
can scan a disk to help determine the physical layout. The program's primary
development goal was to archive Microbee floppy disks to images and to write
these back to floppy, other disk formats can be added to a ubeedisk.ini
file.  The intended audience is mainly for users of computer emulators.

As the program makes use of the 'LibDsk' library there are many options for
image types.  The program provides some data recovery methods along with
'info' files for each disk image file created.  An 'info' file contains
information about the disk image, a status map of all sectors read from the
disk and an MD5 stamp of the associated disk image.

The program makes use of the 'LibDsk' library.  It can be found here:
http://www.seasip.demon.co.uk/Unix/LibDsk/

This README file is updated for each new release and may contain additional
examples and corrections.

You can get the packages from here:
https://sourceforge.net/projects/ubeedisk/

Platforms
---------
The source should be able to be built and run under Linux, and Windows 2000
and up platforms.  Windows 95/98/Me systems are not supported.  Other Unix
systems may work but depends on what host floppy driver code is available in
the LibDsk library.

Overall features
----------------
* Very easy to use with the built in auto detection.
* Can be run from USB Flash drives under a Linux 'Live CD'
* Copy Microbee and Honeysoft disks.
* Scan disk tracks for sector ID header information.
* Format disks.
* Access to remote floppy disks on your Microbee.
* Based on the 'LibDsk' library providing many disk types and formats.
* Configurable retry counts.
* Unattended or operator interactive copy mode.
* Prompt operator for corrective action on read errors when using
  interactive mode.
* Creation of information files with a retry count for each sector and
  other information used to create the image.
* Option to set level of logging for disk read errors.
* Auto drive type sensing.

IMPORTANT INFORMATION
=====================
Differences in systems, drivers, floppy drives, FD Controllers exist.  How
well the imaging process works can depend on these and many other factors.

It is important to realize that an unsuccessful read on one set-up may work
on another and even if the disk can't be read without error does not mean
the disk is bad.  There are other alternative methods to recover data from
disks if this program can not.

Using the '--log=2' option will log all read errors in the 'err' file that
occur during the imaging process and can be used as a diagnostic tool.  Most
errors will be recovered from without even the operator even being aware of
it.  If the error can not be recovered from the operator will be prompted
for the next action to be taken if using the interactive mode or will be
handled automatically if the unattended mode (default) is being used.

Please keep in mind that logged errors at the end of the file DOES NOT mean
a disk is bad, a successful read can occur on a retry and the error
information provided is really just a guide to the condition of the disk
and/or hardware.  Always refer to the 'Sector errors' and the 'SECTOR STATUS
MAP' to determine how much of the disk is in error.

Using uBeeDisk
==============
On Windows machines you MUST have the Fdrawcmd.sys filter driver installed,
without it floppy access will not work correctly.

Fdrawcmd.sys is a floppy filter driver for Windows 2000/XP/2003/Vista.

This driver will be referred to as the 'ntwdm' floppy driver in this
documentation.

You can get it from here:

http://simonowen.com/fdrawcmd/

Windows examples are shown below.  On Unix systems drives 'A:' - 'Z:' will
be translated to '/dev/fd0' - '/dev/fd25'.

A generic 'fd' driver type name may be used to represent the host's floppy
driver.  On Windows this will be translated to 'ntwdm' and on Unices to
the 'floppy' driver.

Disk Detection
--------------
The software can detect most Microbee format disks from a bunch of Microbee
disks.  It can't be expected to detect Microbee formats from an assortment
of CP/M and/or other disks.  CP/M disks don't have a consistent layout
format from one to another to make this possible in a reliable manner.

Disk copying
------------
The default process is to copy disks.  This will use a known disk format or
options to set each parameter.  The copy process does not blindly try to
copy disks as this would mean that errors on disks would not be able to
distinguished between deliberate (copy protection) or damaged disks.  A disk
dump process may be added at a later stage for this method but should be
avoided if a standard copy process can be used.

Driver types
------------
The '--itype' and '--otype' options allow the driver to be set for input and
output.

Specifying these won't normally be necessary.  The input and output driver
types can be determined by ubeedisk from the input and output file names
specified.

Where a floppy device is specified for the file name the appropriate floppy
driver will be used.  On Windows drives 'X:' will use the 'ntwdm' driver and
on Unices drives 'X:' and '/dev/fd' drives will use the 'floppy' driver.

The driver used for disk images will use one of the following if the 'ext'
part of the file name is recognised and must use lower case as shown:

ext     driver
---     ------
.dsk    dsk
.edsk   edsk
.qm     qm
.tel    tele
.cfi    cfi  
.nw     nanowasp  
.raw    raw
.ss40   raw
.ss80   raw
.ds40   raw
.ds80   raw
.ds82   raw
.ds84   raw
.ds8x   raw

It is recommended that all images created use the CPCEMU DSK format.

CREATE A DISK IMAGE
-------------------
As the most common and important use of this program will be for making disk
images of Microbee disks the program has been targeted to make the command
line parameters as simple as possible.

To make a disk image from a floppy in drive A: on Windows and /dev/fd0 on
Unices:

ubeedisk --of=myimage.dsk

The '--of' option is the name of the image to be created and uses the '.dsk'
extension which will cause the CPCEMU DSK driver to be used.  Disk detection
for 'mbee' is the default.

To make an image from another floppy drive will require using another
option.  To make a disk image from floppy drive B: instead:

ubeedisk --if=B: --of=myimage.dsk

Accessing disks on a Microbee computer is also possible by running a
Microbee floppy disk server application that serves disk data over a serial
port.  See 'Access to remote disks on your Microbee' further on.

When creating images you will be prompted for a description of the disk
contents before the imaging process starts unless turned off with a
'--entdesc=off' option or --diskdesc or --diskdescf options are used.  The
last 2 options provide an alternative way to pass the information to the
program and are mainly intended to be used by a GUI program.

When creating disk images the '--count=n' option can be added to cause the
imaging process to loop and automatically create file names for each image. 
See the '--count' option under section 'Command Line Options'.

See the 'COPY PROCESS AND RETRIES' and 'THE 3 RETRY LEVELS' section for an
explanation of how the error recovery works when copying if more detailed
information is required.  If running the program in Interactive mode (not
the default) then the error recovery options will need to be understood but
in the unattended mode (default) this can be ignored and just let the
program handle this.

CREATE A FLOPPY FROM AN IMAGE
-----------------------------
To make a floppy from a Microbee DS80 DSK image you can use the '--format'
option as follows:

ubeedisk --format=ds80 --if=myimage.dsk --of=A:

or use a '--detect=mbee3' option:

ubeedisk --detect=mbee3 --if=myimage.dsk --of=A:

Note: 'mbee' can only be used when detecting input from floppy drives.  The
--detect won't work on 'raw' images types, you will need to use the --format
option for 'raw' types.

ACCESS TO REMOTE DISKS ON YOUR MICROBEE
---------------------------------------
The 'remote' disk type should allow reading/writing sectors over a serial
port to any floppy disk based Microbee Z80 computer (except dreamdisk
model).

The FDS.COM program, sources and documentation containing some examples can
be found here:

http://www.microbee.co.cc/microbee_utils.html

SCANNING A DISK/IMAGE
---------------------
Scanning a disk will show the sector headers for each track.  This can be
used to determine the structure of a disk:

Since version 1.3.0 this process will use auto detection of the data rate
(250, 300, 500 and 1000 KHz) and encoding mode (mfm and fm) for each track
that is scanned and report this along with the other data.  The common modes
are tried first to speed up the detection process.

The --iside=n option may be used with the scanning process to force the
scanning of only 'side n' of the disk.  By default both sides are scanned.

This example will scan the first 10 cylinders.  You should provide a
finishing cylinder or the drive may attempt to step in too far:

ubeedisk --disk=scan --if=a: --finish=9

The next example will scan a sub-section of a disk using the --start,
--finish and --iside options:

ubeedisk --disk=scan --if=a: --start=10 --finish=11 --iside=0

Scanning disks can be deceptive,  you may see sectors on side 1 (as opposed
to side 0) that may lead you to think the disk has a double sided layout. 
These may just be the result of left overs or unused portions of the disk. 
A good example of this would be a 720K IBM factory formatted disk then
formatted to use Microbee SS80 format.  In this case one will observe
sectors 1-10 on side 0 and sectors 1-9 on side 1.  The disk may also not
have used all the tracks so left over tracks could also be evident.

If the disk is truly single side then you will only see side 0 sector
headers if formatted.  True single sided disks have no magnetic surface on
side 1 but disks can also appear to be a true singled sided if never
formatted on side 1 (i.e. contains random noise).  A disk that has never
been formatted will show no output during the scan.

Here is an example of the output from this command using the following
command line and a 720K 3.5" MSDOS disk in drive A:

ubeedisk --disk=scan --if=a: --finish=0

Cylinder:   0  Head:  0  Sectors:  9  Data rate KHz:  300  Encoding: mfm
------------------------------------------------------------------------
Track:   0  Side:  0  Sector:   1  Bytes/sector:  512
Track:   0  Side:  0  Sector:   2  Bytes/sector:  512
Track:   0  Side:  0  Sector:   3  Bytes/sector:  512
Track:   0  Side:  0  Sector:   4  Bytes/sector:  512
Track:   0  Side:  0  Sector:   5  Bytes/sector:  512
Track:   0  Side:  0  Sector:   6  Bytes/sector:  512
Track:   0  Side:  0  Sector:   7  Bytes/sector:  512
Track:   0  Side:  0  Sector:   8  Bytes/sector:  512
Track:   0  Side:  0  Sector:   9  Bytes/sector:  512

Cylinder:   0  Head:  1  Sectors:  9  Data rate KHz:  300  Encoding: mfm
------------------------------------------------------------------------
Track:   0  Side:  1  Sector:   1  Bytes/sector:  512
Track:   0  Side:  1  Sector:   2  Bytes/sector:  512
Track:   0  Side:  1  Sector:   3  Bytes/sector:  512
Track:   0  Side:  1  Sector:   4  Bytes/sector:  512
Track:   0  Side:  1  Sector:   5  Bytes/sector:  512
Track:   0  Side:  1  Sector:   6  Bytes/sector:  512
Track:   0  Side:  1  Sector:   7  Bytes/sector:  512
Track:   0  Side:  1  Sector:   8  Bytes/sector:  512
Track:   0  Side:  1  Sector:   9  Bytes/sector:  512

FORMATTING A DISK/IMAGE
-----------------------
This will format a disk/image to the format type requested.  As a safety
precaution you will be asked to enter 'format' before formatting will
proceed unless a '--force' option is also specified:

This example will format the disk in drive A: to Microbee DS80 format:

ubeedisk --disk=format --format=ds80 --of=A:

See the 'ubeedisk.ini.sample' file for some examples of Microbee formatting
entries.

REPORTING THE DISK GEOMETRY
---------------------------
To report the geometry of a known floppy disk format in drive A: use the
following command:

ubeedisk --disk=info --if=a:

This is the output of the command:

Detecting 'mbee' disk format...
hs350: Microbee Honeysoft 3.5"

       Sidedness: 0 (alt)
       Cylinders: 40 (may vary)
           Heads: 1
   Sectors/track: 10x512 and 5x1024
     Sector base: 1
     Sector size: 512 and 1024
 Input data rate: 2 (sd)
Output data rate: 2 (sd)
         R/W gap: 12
      Format gap: 23
         FM mode: 0 (no)
   No multi mode: 1 (yes)
     No skip del: 1 (yes)
       iside1as0: 0
       secbase1s: 1
       secbase2c: -1
       secbase2s: 1
   special flags: 1

TESTING DSK IMAGES
------------------
Testing of DSK images including Microbee copy protected types is possible
using my Microbee emulator program 'uBee512' (v4.4.0 or later).

This is a fairly straight forward process if the disk has a system to boot
from:

ubee512 -a diskimage.dsk

Disks that do not have a system can also be tested but describing how to do
this is beyond the scope of this document.

KNOWN PROBLEMS
--------------
When attempting to read a floppy disk and no disk is in the drive will
result in an input/output error.  This error can not be recovered from and
requires the imaging process to be repeated.

COPY PROCESS AND RETRIES
========================
The copy process provides two methods to handle errors during disk reads. 
The default method is for unattended operation unless an --unattended=off is
specified.

Interactive mode
----------------
The interaction mode (--unattended=off) will prompt the operator what to do
when 'retries_l1' and 'retries_l2' expire.  The four options presented to
the operator are as follows:

[T] reTry (don't seek T0) [R] Retry (seek T0) [I] Ignore [A] Abort ?:

The operator selects one of the above options and the process continues as
follows:

[T]: Causes a retry with no track 0 seek.
[R]: Causes a retry but seeks to track 0 first.  It is common practice for
     bad sector reads to try to recover on a retry by first doing a seek to
     track 0 before returning and trying again.
[I]: Ignore the error and proceed.  The sector will be marked as bad in the
     'info' file.
[A]: Abort the entire disk copy process.

Unattended mode
---------------
In the unattended mode all disk read errors will be handled automatically by
using one of the four options described in the interactive mode above.

This mode is designed to handle errors in such a way to avoid excessive disk
wear and will abort if too many retries are made.

The 'auto_retry_sector' variable counts the number of retries for a given
sector and is reset to 0 for each new sector.  When this reaches the maximum
allowed value the 'auto_retry_abort' variable counter is incremented and if
that reaches the maximum allowed value then the read process is aborted.

Each time an error occurs a check will be made to see if a retry using a
seek track 0 should be initiated first (only 1 seek to T0 per head/track is
allowed) or simply just retry reading the same sector without any track 0
seek.  Once the maximum number of track 0 seeks have been used up only
retries without seeking to T0 are issued. (This is to reduce wear on disks)

The 3 options to control the operation of this mode are as follows:

  --unattended-rab=n
  --unattended-rps=n
  --unattended-seek=n

See the 'Command Line Options' section for detailed information on each
option.  It is unlikely that any of these will need to be changed.

THE 3 RETRY LEVELS
==================
This is a technical explanation of how the 3 levels of retries works in the
code of uBeeDisk for those that may need to know.  These retry values can be
set with options as described below:

LibDsk (level 1)
----------------
A LibDsk retry level is set here to help make sure there is plenty of time
for a sector to be read successfully at the LibDsk level.  This should not
be set to a too low value as it can cause many soft errors and possibly
causes read problems on some disks (especially Microbee disks).  The value
can be changed using the --retry-l1 option if required.

read_sector() (level 2)
-----------------------
The 2nd level of retries are performed in the read_sector() function which
can be changed using the --level-l2 option if required.  If the LibDsk
retries fail then this 2nd retry level comes into play.

read_sector_retry() (level 3)
-----------------------------
If level 2 fails to read a sector then this 3rd level comes into play.

If the Unattended mode is in use (default) then some more retries (with
and without T0 seeks), ignore or abort operations will be issued. 
The exact way this works depends on the count of previous errors and seek
counts that have already occurred.

Command Line Options
====================
Usage: ubeedisk [options]

  --append-error          This option is used to append the error log to the
                          'info' file instead of creating an 'err' file.

  --autorate=x            Test if drive is a 5.25" HD or 5.25" DD type if
                          x=on, if x=off no drive type detection will be used.
                          When enabled and the disk is a DD type and the drive
                          is a HD type then the data rate will be set to the
                          appropriate rate. If the disk is a 48TPI type then
                          double stepping will also be set. This only affects
                          'floppy' and 'ntwdm' driver types and has no affect
                          on other types. Default is on.

  --config=file           Allows an alternative configuration file to be used
                          or if file='none' then no configuration file will be
                          used.  This option if used must be the first option
                          declared on the command line.  The default file used
                          for configuration is 'ubeedisk.ini' and must be
                          located in the ubeedisk directory.

  --count=n               Count value is a number appended to the output file
                          name base. Using this option makes the copy process
                          prompt the user for disk changes. i.e. if the output
                          file name requested is disk.dsk and n=0 then the
                          name becomes disk000.dsk.  The number is incremented
                          by one for each iteration.

  --cylinders=n, -c       Set/override the number of cylinders.

  --datarate=x, -d        Set/override the data rate. The value is based on
                          rates defined by LibDsk. The allowed values are:

                          hd : data rate for 1.4Mb/1.2Mb in 3.5/5.25" drive.
                          dd : data rate for 360k 5.25" in 1.2Mb drive.
                          sd : data rate for 720k 3.5" in 3.5" drive.
                          ed : data rate for 2.8Mb 3.5" in 3.5" drive.

  --description=str       Set/override the format description.

  --detect=x              Use disk format detection. x determines what disks
                          should be tested. Currently the supported detection
                          types are:

                            off : disable detection.
                           mbee : Microbee disks.
                          mbee3 : Microbee 3.5" disks (forces).
                          mbee5 : Microbee 5.25" disks (forces).

  --disk=x                Select the required process. Default process is the
                          'copy' process if not specified. The processes
                          supported are:

                            copy : copy standard layout disks.
                            dump : not currently implemented.
                            info : show disk format information only.
                            scan : scan disk tracks for sector ID information.
                          format : format disk tracks.

  --diskdesc=x            Pass a disk description. Repeat this option for as
                          many lines of text that are required.  Each line may
                          have up to 100 characters.  This option causes the
                          prompting for a description to be disabled.

  --diskdescf=fn          Pass the name of a file containing a disk
                          description.  Each line may have up to 100
                          characters. This option causes the prompting for a
                          description to be disabled.

  --entdesc=x             Prompt operator to enter a disk description if x=on
                          or bypass if x=off when using the copy process.
                          Default is on.

  --finish=n              Set/override the finish cylinder for processes.
                          Default value is set to the highest value found by
                          --detect, --format or --cylinder options.

  --fm=n                  Set/override the use of FM mode.  n=1 if the disk
                          uses an FM format or n=0 if MFM.

  --fmtgap=n              Set/override the format gap value.

  --force                 Use this option to stop confirmation of any requested
                          actions. i.e. when formatting a disk.

  --forceside=x           Forces writing the output side value to match the
                          physical head value if x=on.  If x=off the input
                          side value read is used. Default is off.

  --format=x, -f          Specify the disk format to use. The value is first
                          checked against built in values and if no matches
                          are found then against values in LibDsk and
                          the 'libdskrc' file.  The built in Microbee disk
                          formats are:

                                user : default user configurable set-up
                                ss40 : SS DD 40T
                                ss80 : SS DD 80T (CIAB)
                                ds40 : DS DD 40T (SBC)
                                ds80 : DS DD 80T (Microbee)
                                ds82 : DS DD 80T (Dreamdisk)
                                ds84 : DS DD 80T (PJB)
                                ds8x : Same as 'ds82' and 'ds84'
                               hs350 : Microbee Honeysoft 3.5"
                               hs525 : Microbee Honeysoft 5.25"
                          c5h0s0_350 : Microbee C5 H0 S0 3.5"

  --heads=n, -h           Set/override the number of heads.

  --help                  Send this help information to stdout.

  --idstep=x              Determine if the input drive should use double
                          stepping.  x=on to enable, x=off to disable.
                          Default is off.
  --if=name               Input file name.  This may be a floppy device or
                          name of a disk image.  On Windows and Unices systems
                          floppy devices 'A:', 'B:', etc. and on Unices
                          '/dev/fd0', '/dev/fd1', etc. may be used. Default
                          for input file will be 'A:' or '/dev/fd0'.

  --info=x                Determine if an 'info' file should be created. The
                          'info' file uses the output name with '.info'
                          appended. x=on to enable, x=off to disable. Default
                          is on.  The 'info' file contains very important
                          information about the disk image and should always
                          be enabled and the file kept.

  --iside=n               Force side n of input. n may be 0 or 1.

  --itype=x, -i           Set/override the input driver type.  If no type is
                          given the input file name will be used to determine
                          the appropriate type.  The following types are
                          supported by the LibDsk library, see the LibDsk
                          documentation for further details: dsk, edsk, raw,
                          logical, floppy, ntwdm, myz80, cfi, qm, teledisk,
                          nanowasp, rcpmfs, remote.

                          If 'fd' is specified for x then this will be
                          translated to the host system's floppy driver. On
                          Windows this is 'ntwdm' and Unices is the 'floppy'
                          driver.  This is useful for making scripts portable.

  --lcon                  List the [section] names found in the configuration
                          file.
  --lconw                 Same as --lcon option except uses a wide format.
  --lcons=n               Sets the list start point for --lcon and --lconw
                          options. Default value is 1.

  --lformat               Lists all the LibDsk built-in and external disk
                          formats that are available.

  --log=n                 Logging level, set the log level when 'info' files
                          are created to one of the following. Default is 1.

                          0 : No read errors are logged.
                          1 : Read errors are logged only after the retry
                              count expires.
                          2 : All read errors are logged. Very useful for
                              checking for floppy drive and HW problems.

  --ltype                 Lists all the LibDsk driver types that are available.

  --noformat=n, -n        Set n=1 to prevent or n=0 to allow formatting of
                          the output drive/image.  Default is 0.

  --nomulti=n             Set/Override no multi-track mode. Set n=1 to prevent
                          or n=0 to allow multi-track mode.

  --noskip=n              Set/Override no skipping of deleted data. Set n=1
                          to prevent or n=0 to allow skipping.

  --odstep=x              Determine if the output drive should use double
                          stepping.  x=on to enable, x=off to disable.
                          Default is off.
  --of=name               Output file name.  This may be a floppy device or
                          name of a disk image.  On Windows and Unices systems
                          floppy devices 'A:', 'B:', etc. and on Unices
                          '/dev/fd0', '/dev/fd1', etc. may be used.

  --oside=n               Force side n of output. n may be 0 or 1.

  --otype=x, -o           Set/override the output driver type.  If no type is
                          given the output file name will be used to determine
                          the appropriate type.  The following types are
                          supported by the LibDsk library, see the LibDsk
                          documentation for further details: dsk, edsk, raw,
                          logical, floppy, ntwdm, myz80, cfi, qm, teledisk,
                          nanowasp, rcpmfs, remote.

                          If 'fd' is specified for x then this will be
                          translated to the host system's floppy driver. On
                          Windows this is 'ntwdm' and Unices is the 'floppy'
                          driver.  This is useful for making scripts portable.

  --retry-l1=n            Set the number of read tries at the lowest level
                          before level 2 comes into play. Default value is 10.
  --retry-l2=n, --retry=n Set the 2nd level of read tries before the 3rd level
                          comes into play.  The 3rd and final level is an
                          unattended or interactive mode. Default value is 3.

  --rwgap=n               Set/override the read/write sector gap value.

  --secbase=n             Set/override the sector base number.

  --secbase2s=n           Set/override the sector base2 number.

  --secbase2c=n           Set/override the sector base2 cylinder start number.

  --secsize=n             Set/override the sector size. Must be >= 128 and
                          a power of 2.

  --sectors=n, -s         Set/override the number of sectors per track

  --side1as0=n            Set/override the physical properties of side 1
                          sector header ID side information. n=1 indicates the
                          header uses 0 instead of 1. n=1 indicates the side
                          information matches the head 1 number.

  --sidedness=x           Set/override the sidedness of the disk. The allowed
                          values are:

                              alt : Track n is cylinder (n/heads) head
                                    (n%heads)
                          outback : Tracks go (head 0) 0,1,2,3,...37,38,39,
                                    then (head 1) 39,38,37,...,2,1,0
                           outout : Tracks go (head 0) 0,1,2,3,...37,38,39,
                                    then (head 1) 0,1,2,3,...37,38,39

  --signature=name        The archiver's signature can appear in the 'info'
                          file by setting a name.

  --start=n               Set/override the start cylinder for processes. By
                          default this value is set to 0.

  --unattended=x          Use this option to enable/disable automated error
                          handling. x=on to enable, x=off to disable.
                          Default is on.
  --unattended-rab=n      Set number of sector errors allowed before aborting
                          the copy process when the unattended mode is in use.
                          Default value is 300.
  --unattended-rps=n      Set number of retries per sector allowed when the
                          unattended mode is in use.  Default value is 2.
  --unattended-seek=n     Set the maximum number of error seeks per disk read
                          allowed when the unattended mode is in use. After
                          this no more seeks to track 0 will occur between
                          read errors. Default value is 10.

  --verbose=n             Set the reporting level. The default level is 1
                          which makes all console messages active. If set to 0
                          then only error messages, interaction prompts and
                          processes intended to convey information will be
                          output.

  --version, -v           Output the program version number to stdout.

Error file structure
====================
By default an error file '.err' will be created if 'info' files are enabled
and any disk errors occur.

Below is an example of an error log file and using a '--log=2' option.  The
example shows where 2 bad sectors caused problems.  An understanding of the
'Unattended mode' and 'THE 3 RETRY LEVELS' is required to follow what is
happening. The example below used the unattended mode and default values for
all retry levels and unattended mode.

The 'Try #' numbers shown are occurring at Level 2.  Level 1 errors are not
reported as these are at the LibDsk level.  The same 3 retries at a
particular sector repeat when the unattended mode attempts further retries.

LOG OF READ ERRORS
------------------
This log contains errors that were encountered during the imaging process.
Read errors may have been corrected on further retries.

The sector count at 'Sector errors' and the 'SECTOR STATUS MAP' in the
'info' file should be used to determine what bad sectors the disk (image)
may have.

The frequency of log entries recorded here is determined by the logging
level option '--log=n'.

Try #: 01/03 Cylinder: 78 Head: 1 Sector: 006 Error: (-15) Missing address mark.
Try #: 02/03 Cylinder: 78 Head: 1 Sector: 006 Error: (-15) Missing address mark.
Try #: 03/03 Cylinder: 78 Head: 1 Sector: 006 Error: (-15) Missing address mark.
Try #: 01/03 Cylinder: 78 Head: 1 Sector: 006 Error: (-15) Missing address mark.
Try #: 02/03 Cylinder: 78 Head: 1 Sector: 006 Error: (-15) Missing address mark.
Try #: 03/03 Cylinder: 78 Head: 1 Sector: 006 Error: (-15) Missing address mark.
Try #: 01/03 Cylinder: 78 Head: 1 Sector: 006 Error: (-15) Missing address mark.
Try #: 02/03 Cylinder: 78 Head: 1 Sector: 006 Error: (-15) Missing address mark.
Try #: 03/03 Cylinder: 78 Head: 1 Sector: 006 Error: (-15) Missing address mark.
Try #: 01/03 Cylinder: 79 Head: 1 Sector: 005 Error: (-13) Data error.
Try #: 02/03 Cylinder: 79 Head: 1 Sector: 005 Error: (-13) Data error.
Try #: 03/03 Cylinder: 79 Head: 1 Sector: 005 Error: (-13) Data error.
Try #: 01/03 Cylinder: 79 Head: 1 Sector: 005 Error: (-13) Data error.
Try #: 02/03 Cylinder: 79 Head: 1 Sector: 005 Error: (-13) Data error.
Try #: 03/03 Cylinder: 79 Head: 1 Sector: 005 Error: (-13) Data error.
Try #: 01/03 Cylinder: 79 Head: 1 Sector: 005 Error: (-13) Data error.
Try #: 02/03 Cylinder: 79 Head: 1 Sector: 005 Error: (-13) Data error.
Try #: 03/03 Cylinder: 79 Head: 1 Sector: 005 Error: (-13) Data error.

Info file structure
===================
'Info' files are created by default when making images from floppy disks.
These 'info' files are important as they contain vital information about
each disk image.  Any bad sectors will be recorded along with other physical
attributes about the disk and the parameters used to make the image.

Read errors will also be appended to this file if '--append-error' has been
specified, the level including turning off error logging can be set using
the '--log' option.

The 'info' file will be the output image file name with '.info' appended.

The following is an info file created from a Microbee DS80 disk.

The command line used was:
ubeedisk --of=test.dsk

DISK/IMAGE INFORMATION
----------------------
File output        test.dsk
File output MD5    cc2d3a040ea26dbf921201258d33de8f
Disk name          ds80
Disk name desc     Microbee DS DD 80T 3.5" (Microbee)
Archived by        Not specified
Creation date      29 March 2010  19:18:11

DISK DESCRIPTION
----------------
test disk

PROGRAM PARAMETERS
------------------
Image program      ubeedisk-1.4.0
Detection req      mbee
Disk format req    
File input         fd0
Input type         floppy
Output type        dsk
Input dstep        no
Output dstep       no
Input side         both
Output side        both
Start cylinder     0
Finish cylinder    79
Force side ID      no
Input comp         
Output comp        
Retries lev1 (max) 10
Retries lev2 (max) 3
Logging level      1
Input data rate    sd
Output data rate   sd

UNATTENDED MODE SETTINGS
------------------------
Used unattended    yes
Sector ret/abort   300
Retries/sector max 2
Error seeks max    10

PHYSICAL ATTRIBUTES
-------------------
Sidedness          alt
Data rate          sd
Cylinders          80
Heads              2
Sectors/track      10
Sector size        512
Sector base #1     1
Sector base #2     21

DISK COPY RESULTS
-----------------
Sector errors      0
Sector retries     0

SECTOR STATUS MAP
-----------------
A sector position containing a '.' indicates the sector read correctly first
time. An 'X' indicates the sector was not read (terminated early). An 'ERR'
indicates the sector had a read error and a value from '1-999' indicates the
number of level 2 retries that were needed to successfully read the sector.

Cylinder  Head   (10x512)  001 002 003 004 005 006 007 008 009 010 
   0       0                .   .   .   .   .   .   .   .   .   .  
   0       1                .   .   .   .   .   .   .   .   .   .  
   1       0                .   .   .   .   .   .   .   .   .   .  
   1       1                .   .   .   .   .   .   .   .   .   .  
Cylinder  Head   (10x512)  021 022 023 024 025 026 027 028 029 030 
   2       0                .   .   .   .   .   .   .   .   .   .  
   2       1                .   .   .   .   .   .   .   .   .   .  
   3       0                .   .   .   .   .   .   .   .   .   .  
   3       1                .   .   .   .   .   .   .   .   .   .  
   4       0                .   .   .   .   .   .   .   .   .   .  
   4       1                .   .   .   .   .   .   .   .   .   .  
   5       0                .   .   .   .   .   .   .   .   .   .  
   5       1                .   .   .   .   .   .   .   .   .   .  
   6       0                .   .   .   .   .   .   .   .   .   .  
   6       1                .   .   .   .   .   .   .   .   .   .  
   7       0                .   .   .   .   .   .   .   .   .   .  
   7       1                .   .   .   .   .   .   .   .   .   .  
   8       0                .   .   .   .   .   .   .   .   .   .  
   8       1                .   .   .   .   .   .   .   .   .   .  
   9       0                .   .   .   .   .   .   .   .   .   .  
   9       1                .   .   .   .   .   .   .   .   .   .  
  10       0                .   .   .   .   .   .   .   .   .   .  
  10       1                .   .   .   .   .   .   .   .   .   .  
  11       0                .   .   .   .   .   .   .   .   .   .  
  11       1                .   .   .   .   .   .   .   .   .   .  
  12       0                .   .   .   .   .   .   .   .   .   .  
  12       1                .   .   .   .   .   .   .   .   .   .  
  13       0                .   .   .   .   .   .   .   .   .   .  
  13       1                .   .   .   .   .   .   .   .   .   .  
  14       0                .   .   .   .   .   .   .   .   .   .  
  14       1                .   .   .   .   .   .   .   .   .   .  
  15       0                .   .   .   .   .   .   .   .   .   .  
  15       1                .   .   .   .   .   .   .   .   .   .  
  16       0                .   .   .   .   .   .   .   .   .   .  
  16       1                .   .   .   .   .   .   .   .   .   .  
  17       0                .   .   .   .   .   .   .   .   .   .  
  17       1                .   .   .   .   .   .   .   .   .   .  
  18       0                .   .   .   .   .   .   .   .   .   .  
  18       1                .   .   .   .   .   .   .   .   .   .  
  19       0                .   .   .   .   .   .   .   .   .   .  
  19       1                .   .   .   .   .   .   .   .   .   .  
  20       0                .   .   .   .   .   .   .   .   .   .  
  20       1                .   .   .   .   .   .   .   .   .   .  
  21       0                .   .   .   .   .   .   .   .   .   .  
  21       1                .   .   .   .   .   .   .   .   .   .  
  22       0                .   .   .   .   .   .   .   .   .   .  
  22       1                .   .   .   .   .   .   .   .   .   .  
  23       0                .   .   .   .   .   .   .   .   .   .  
  23       1                .   .   .   .   .   .   .   .   .   .  
  24       0                .   .   .   .   .   .   .   .   .   .  
  24       1                .   .   .   .   .   .   .   .   .   .  
  25       0                .   .   .   .   .   .   .   .   .   .  
  25       1                .   .   .   .   .   .   .   .   .   .  
  26       0                .   .   .   .   .   .   .   .   .   .  
  26       1                .   .   .   .   .   .   .   .   .   .  
  27       0                .   .   .   .   .   .   .   .   .   .  
  27       1                .   .   .   .   .   .   .   .   .   .  
  28       0                .   .   .   .   .   .   .   .   .   .  
  28       1                .   .   .   .   .   .   .   .   .   .  
  29       0                .   .   .   .   .   .   .   .   .   .  
  29       1                .   .   .   .   .   .   .   .   .   .  
  30       0                .   .   .   .   .   .   .   .   .   .  
  30       1                .   .   .   .   .   .   .   .   .   .  
  31       0                .   .   .   .   .   .   .   .   .   .  
  31       1                .   .   .   .   .   .   .   .   .   .  
  32       0                .   .   .   .   .   .   .   .   .   .  
  32       1                .   .   .   .   .   .   .   .   .   .  
  33       0                .   .   .   .   .   .   .   .   .   .  
  33       1                .   .   .   .   .   .   .   .   .   .  
  34       0                .   .   .   .   .   .   .   .   .   .  
  34       1                .   .   .   .   .   .   .   .   .   .  
  35       0                .   .   .   .   .   .   .   .   .   .  
  35       1                .   .   .   .   .   .   .   .   .   .  
  36       0                .   .   .   .   .   .   .   .   .   .  
  36       1                .   .   .   .   .   .   .   .   .   .  
  37       0                .   .   .   .   .   .   .   .   .   .  
  37       1                .   .   .   .   .   .   .   .   .   .  
  38       0                .   .   .   .   .   .   .   .   .   .  
  38       1                .   .   .   .   .   .   .   .   .   .  
  39       0                .   .   .   .   .   .   .   .   .   .  
  39       1                .   .   .   .   .   .   .   .   .   .  
  40       0                .   .   .   .   .   .   .   .   .   .  
  40       1                .   .   .   .   .   .   .   .   .   .  
  41       0                .   .   .   .   .   .   .   .   .   .  
  41       1                .   .   .   .   .   .   .   .   .   .  
  42       0                .   .   .   .   .   .   .   .   .   .  
  42       1                .   .   .   .   .   .   .   .   .   .  
  43       0                .   .   .   .   .   .   .   .   .   .  
  43       1                .   .   .   .   .   .   .   .   .   .  
  44       0                .   .   .   .   .   .   .   .   .   .  
  44       1                .   .   .   .   .   .   .   .   .   .  
  45       0                .   .   .   .   .   .   .   .   .   .  
  45       1                .   .   .   .   .   .   .   .   .   .  
  46       0                .   .   .   .   .   .   .   .   .   .  
  46       1                .   .   .   .   .   .   .   .   .   .  
  47       0                .   .   .   .   .   .   .   .   .   .  
  47       1                .   .   .   .   .   .   .   .   .   .  
  48       0                .   .   .   .   .   .   .   .   .   .  
  48       1                .   .   .   .   .   .   .   .   .   .  
  49       0                .   .   .   .   .   .   .   .   .   .  
  49       1                .   .   .   .   .   .   .   .   .   .  
  50       0                .   .   .   .   .   .   .   .   .   .  
  50       1                .   .   .   .   .   .   .   .   .   .  
  51       0                .   .   .   .   .   .   .   .   .   .  
  51       1                .   .   .   .   .   .   .   .   .   .  
  52       0                .   .   .   .   .   .   .   .   .   .  
  52       1                .   .   .   .   .   .   .   .   .   .  
  53       0                .   .   .   .   .   .   .   .   .   .  
  53       1                .   .   .   .   .   .   .   .   .   .  
  54       0                .   .   .   .   .   .   .   .   .   .  
  54       1                .   .   .   .   .   .   .   .   .   .  
  55       0                .   .   .   .   .   .   .   .   .   .  
  55       1                .   .   .   .   .   .   .   .   .   .  
  56       0                .   .   .   .   .   .   .   .   .   .  
  56       1                .   .   .   .   .   .   .   .   .   .  
  57       0                .   .   .   .   .   .   .   .   .   .  
  57       1                .   .   .   .   .   .   .   .   .   .  
  58       0                .   .   .   .   .   .   .   .   .   .  
  58       1                .   .   .   .   .   .   .   .   .   .  
  59       0                .   .   .   .   .   .   .   .   .   .  
  59       1                .   .   .   .   .   .   .   .   .   .  
  60       0                .   .   .   .   .   .   .   .   .   .  
  60       1                .   .   .   .   .   .   .   .   .   .  
  61       0                .   .   .   .   .   .   .   .   .   .  
  61       1                .   .   .   .   .   .   .   .   .   .  
  62       0                .   .   .   .   .   .   .   .   .   .  
  62       1                .   .   .   .   .   .   .   .   .   .  
  63       0                .   .   .   .   .   .   .   .   .   .  
  63       1                .   .   .   .   .   .   .   .   .   .  
  64       0                .   .   .   .   .   .   .   .   .   .  
  64       1                .   .   .   .   .   .   .   .   .   .  
  65       0                .   .   .   .   .   .   .   .   .   .  
  65       1                .   .   .   .   .   .   .   .   .   .  
  66       0                .   .   .   .   .   .   .   .   .   .  
  66       1                .   .   .   .   .   .   .   .   .   .  
  67       0                .   .   .   .   .   .   .   .   .   .  
  67       1                .   .   .   .   .   .   .   .   .   .  
  68       0                .   .   .   .   .   .   .   .   .   .  
  68       1                .   .   .   .   .   .   .   .   .   .  
  69       0                .   .   .   .   .   .   .   .   .   .  
  69       1                .   .   .   .   .   .   .   .   .   .  
  70       0                .   .   .   .   .   .   .   .   .   .  
  70       1                .   .   .   .   .   .   .   .   .   .  
  71       0                .   .   .   .   .   .   .   .   .   .  
  71       1                .   .   .   .   .   .   .   .   .   .  
  72       0                .   .   .   .   .   .   .   .   .   .  
  72       1                .   .   .   .   .   .   .   .   .   .  
  73       0                .   .   .   .   .   .   .   .   .   .  
  73       1                .   .   .   .   .   .   .   .   .   .  
  74       0                .   .   .   .   .   .   .   .   .   .  
  74       1                .   .   .   .   .   .   .   .   .   .  
  75       0                .   .   .   .   .   .   .   .   .   .  
  75       1                .   .   .   .   .   .   .   .   .   .  
  76       0                .   .   .   .   .   .   .   .   .   .  
  76       1                .   .   .   .   .   .   .   .   .   .  
  77       0                .   .   .   .   .   .   .   .   .   .  
  77       1                .   .   .   .   .   .   .   .   .   .  
  78       0                .   .   .   .   .   .   .   .   .   .  
  78       1                .   .   .   .   .   .   .   .   .   .  
  79       0                .   .   .   .   .   .   .   .   .   .  
  79       1                .   .   .   .   .   .   .   .   .   .  

Configuration Files
===================
The configuration file uses the same options that are possible on the
command line.  Customised sections can be added making invoking ubeedisk
with options much easier.  Command line parameters may be used in addition
and more than one customised section can be invoked from the same command
line.

A 'ubeedisk.ini' text file (the default) is required to hold the
configuration script. The supplied 'ubeedisk.ini.sample' file can be used as
a template.

Alternative configuration files may also be used if the first option on the
command line is --config=my_config.

The default path for configuration files is where the ubeedisk.exe program
is located on Windows and in the '.ubeedisk' directory on Unix home
accounts.

File structure
--------------
- Comments lines are preceded by '#' or ';' and must be the first non-space
  character on the line. Blank lines are ignored.

- A definition name must be surrounded with square bracket characters '['
  and ']'. All lines below this are part of the definition until a new
  definition name or the end of file is reached.  A maximum of 5000
  definitions are allowed.

- A definition's contents can NOT reference any other definitions.  The
  command line options may include any number of references to definitions
  contained in the file and may be mixed with options.

- Values contained in the [global-start] and [global-end] sections are
  always referenced but their use is optional.  It is not the intention that
  these be used directly by the user.  The [global-start] section is applied
  before any command line options or customised sections are processed.  The
  [global_end] section allows options to override what resulted from a
  command line or a customised section.  i.e. the --model option sets
  default values and the [global-end] section can globally override the
  settings if this is required on a global basis.

- Names used for a definition section must be unique.  If any command line
  option parameters that contains a space before it matches the definition
  name then it will be treated as file definition instead.

- Options may be divided up and placed onto new lines to make for easier
  reading.

Listing the definitions
-----------------------
Use the --lcon or lconw option or use the 'listall' entry found in the
sample file to list all the definition names contained in the configuration
file.  A 'list' entry is also included that will list all entries except for
some early administration entries.

Projects by this author
=======================

uBee512
-------
An emulator for the Microbee Z80 ROM, FDD and HDD based models.

https://sourceforge.net/projects/ubee512/

uBeeDisk
--------
A tool for converting disks/images from one to another with
auto detection options for Microbee disks.

https://sourceforge.net/projects/ubeedisk/

z80em86
-------
A Z80 CPU emulator coded in Intel 86 assembly language.

https://sourceforge.net/projects/z80em86/
http://www.z80em86.co.cc/

Contact
=======
If you have any new feature suggestions, bug reports, etc. then please send
an email to: ubee512@gmail.com

For bug reports please provide the following information:
1) Version number of the uBeeDisk program.
2) The platform it was running on, for example if running on Windows then
   state if W95, W98, Me, W2000, XP, Vista, W7, etc.  Same for Linux, state
   the actual Linux distribution used and version.
3) Command line start up options used (cut and paste if possible)
4) Description of the problem.

Stewart
