=======
sortatr
=======

----------------------------------------
sort Atari DOS directory in an ATR image
----------------------------------------

.. include:: manhdr.rst

SYNOPSIS
========
sortatr *imagefile.atr*

DESCRIPTION
===========

**sortatr** sorts the directory entries in an Atari DOS 2.0S or MyDOS
compatible ATR images. The sort is alphabetical, and the disk image
is modified in place.

**sortatr** does not take any options.

XFD format images are not supported.

WARNINGS
========

**DO NOT USE** this utility with DOS 2.5 disk images!

**DO NOT USE** this utility with MyDOS images containing subdirectories!

**DATA LOSS** will occur if these warnings are not heeded! The
modified directory in the  image will  not contain any
references to DOS 2.5 files using sectors above 720, or to MyDOS
subdirectories. This effectively deletes these files from the image.

If in doubt, list the image's directory with **atrdir**. If you see
files marked with a *:* (colon) or *<* (less-than), then **sortatr**
should not be used on the image. Even if your purpose is actually to
delete these files/dirs, you should use some other utility (or DOS
on a real or emulated Atari) to delete them, because **sortatr**
doesn't free the sectors occupied by the files/dirs.

If you ignore these warnings and manage to delete files or directories
from your disk image, it should be possible to recover them with
a good Atari undelete or disk-repair utility. Although the affected
files/dirs have been removed from the disk directory, the data
sectors have not been overwritten nor marked as free (meaning they
won't be overwritten by later write operations, unlike most "undelete"
situations). First, you have to find the starting sector of the
missing file/dir and create a directory entry for it in the directory
at sectors 36-368. You will probably also have to change the file
number in the sector link bytes, or else delete the file in the new
directory that's using the file number of the old (deleted) file.

Further warnings
----------------

**DO NOT USE** this utility with any non-standard (non-AtariDOS, non-MyDOS
compatible) disk image.

Boot  disks  with no directory, SpartaDOS, Atari DOS 3/4, DOS XE,
or other non-standard DOS formatted disks might (if you're lucky)
just cause an error message. If you're  not  lucky, they  may  be
corrupted. There is no easy way to recover an image that gets damaged
in this way.

**DO NOT USE** this utility with any image without creating a backup first!

Any image you use with **sortatr** is modified in-place, and no backup is
made by **sortatr**. Always make a backup copy of an ATR image before you
use **sortatr** on it. You have been warned.


EXIT STATUS
===========

Exit status is zero if the sort was successful, or non-zero if any
errors occurred. In case of a non-zero return, the disk image may be
truncated, or its directory sectors may be damaged. Hope you had a
backup of that image!

.. include:: manftr.rst