================================
.D80 esxDOS dot command - MANUAL
================================

Supported disk(image) formats:
  MDOS1.x, MDOS2.x (D40/D80)

Developed and tested on:
  eLeMeNt ZX computer
  and MB03+ interface

Version limitations:
  0.7f  not tested with MDOS3
        disk images 

2026  SCjoe / eZX / MB

Warning:
  Do not use the old esxDOS
  v.0.8.8 (eg. in the the Omni
  computer). You may corrupt
  files or your SD card !

================================
USAGE
================================
.D80 image[.ext]  directory list

.D80 [switches] image[.ext]

If no extension is given, the
command tries appending .D80
first, then .D40. If neither
exists, an error is reported.

Accepted filename variants:
  FLOPPY
  FLOPPY.
  FLOPPY.D80
  FLOPPY.D40

================================
SWITCHES
================================
-x  Export files from image
    to SD card.

-c  Create a new blank disk
    image file (.D80 only).

-n  No Scroll? disables the
    prompt after printing the
    entire page.

-d  Write directory listing to
    a file instead of screen.
  Output filename:
    FLOPPY       -> FLOPPY.DIR
    FLOPPY.      -> FLOPPY.DIR
    FLOPPY.EXT   -> FLOPPY.EXT
      (EXT is any other
       extension, LST,PRN,OUT,
       except the D80,D40)
    If the file already exists,
    you will be asked:
      Overwrite? Y/N

-i  Display disk image info:
    format, capacity, FAT
    statistics and directory
    slot counts by file type.

================================
DIRECTORY LISTING
================================
When called without a switch,
only with an image name, the
command displays a directory
listing of the disk image:

  Filename   Bytes Start Attrib.
P name          82     0 ----RWED
B file        1024 49152 ----RWED

Columns:
 type    MDOS file type letter
 name    filename (up to 10ch.)
 Bytes   file size in bytes
 Start   for type P: BASIC
         start line number
         for others: load
         address in memory
 Attrib. HSPARWED, dash means
         bit is not set

Footer shows total file count
and free space in bytes.

================================
MDOS FILE TYPES
================================
MDOS uses single-letter types:

P  BASIC program
B  Bytes (binary data)
N  Number array
C  Character array
S  Snapshot (48K memory)
Q  Sequence (large file)

================================
EXPORT (-x) FILE CONVERSION
================================
On export, each file on the
disk image is converted to an
esxDOS file.

The output format depends on
the original MDOS type:

P  -> .BAS  with +3DOS header
       type 0 (BASIC program)

B  -> .SCR  RAW, no header
       if length = 6912 bytes
       (screen dump, any addr)

B  -> .COD  with +3DOS header
       type 3 (Code)

N  -> .NAR  with +3DOS header
       type 2 (Number array)

C  -> .CAR  with +3DOS header
       type 1 (Char array)

S  -> .SNP  RAW, no header
       (48K snapshot, 49152B)

Q  -> .BIN  RAW, no header

other -> .BIN  RAW, no header

================================
FILENAME CONVERSION
================================
MDOS filenames are 10 characters
long. esxDOS (FAT) filenames are
limited to 8 characters plus
extension (8.3 format).

Conversion rules:
- Up to 8 valid FAT chars are
  taken from the MDOS name.
- Alphabet chars and numbers,
  '-' and '_' are preserved,
  other chars including spaces
  and dots are dropped.
- The result is uppercased.
- Extension is appended (.BAS,
  .COD, .SCR etc.) as above.

Name collision handling:
If a file with the same output
name already exists on the SD
card, a two-digit numeric suffix
is inserted before the extension
(e.g. GAME01.BAS, GAME02.BAS).
Up to 99 collisions are handled.

================================
EXPORT DIRECTORY STRUCTURE
================================
When -x is used, a directory is
first created on the SD card.
Its name comes from the image
FILE name (not the disk name
stored inside the image),
up to 8 chars, no extension.
Example:
  GAMES.D80 -> GAMES/

All files are then exported
into this directory.

If the directory already exists,
you will be asked:
  Directory GAMES exists.
  Overwrite? Y/N
  Y: enter it and overwrite
     any files with same names.
  N: export is cancelled.

BASIC programs (type P) get an
additional subdirectory named
after the BASIC file itself.
This groups multi-part programs
together. Example:
  GAMES/
    GAME1/
      START.BAS
      ...
    GAME2/
      CAST1.BAS
      ...

All other file types are placed
directly in the image directory:
  GAMES/
    GAME.BAS
    SCREEN.SCR
    DATA.COD

================================
CREATE IMAGE (-c)
================================
Creates a new blank formatted
disk image D80:
  80 tracks, 1440 sectors
  capacity: 728064 bytes
  9 sectors/track
  512 bytes per sector
  double sided
  standard MDOS format

The image contains:
  Sector 0:    Boot sector
  Sectors 1-5: FAT (free)
  Sectors 6-13: Directory
               (128 empty slots)
  Sectors 14+: Data area

Disk name is set to "EMPTY".
All directory slots are blank
($E5 filled, 32 bytes each).

================================
DISK INFO (-i)
================================
Displays a summary of the disk
image structure and contents.

Diskimage filename (or MDOS
version prefix and disk name
for MDOS 2.1/2.2), plus the
random disk ID in hex

Examples:
  FLOPPY.D80         ID: $A3F2
  MDOS21: NAME.D80   ID: $A3F2

capacity: total KB and number
          of directory slots.

format:   sided, tracks/sectors
          per track, total
          sectors.

sectors:
  system   sectors 0-13 (boot,
           FAT, directory)
  pad/bad  FAT padding markers
           /sectors marked bad
           at format time
  used     sectors in use by
           files
  free     sectors available

directory:
  counts by file type (P,B,N,
  C,S,Q and other)
  hidden, read-only, system
  attribute counts
  slots used / slots free
  (deleted files counted as
  free; a slot is "deleted"
  if byte 0 is $E5 but the
  rest of the entry remains,
  as MDOS only overwrites the
  first byte on deletion)

bytes used / bytes free:
  total used and free space in
  the data area in bytes.

================================
ERROR MESSAGES
================================
Not a D80/D40 image
  The file does not contain a
  valid MDOS "SDOS" signature.

File read/write error
  An I/O error occurred while
  reading or writing the image
  or output file.

Only extensions d80/d40 allowed
  You specified an extension
  other than .D80 or .D40
  (without the -d switch).

Only D80 extension expected
  The -c switch requires .D80.

DIR extension expected
  With -d, an image extension
  (.D80 or .D40) was given as
  the output filename.

File NAME.EXT not found
  The disk image file does not
  exist (neither .D80 nor .D40
  version was found).

Invalid switch
  An unrecognised letter was
  given after the dash.

================================
NOTES
================================

- Switches may be combined,
  e.g.: .D80 -n -d IMAGE.D40
  (list to file, no Scroll?).

- -x and -d may be combined
  to export files AND save
  the directory listing
  to a file simultaneously.

- MDOS 2.1/2.2 images show a
  MDOS21 or MDOS22 prefix
  followed by the disk name
  stored inside the image.

- Older MDOS diskimages may not
  have any diskname.

================================
END OF MANUAL
================================
