View source for Dir Doktor

[[Category:Applications]]
[[Image:DIRDOKTOR screen shot 1.JPG|right|thumb|250px|Disk Doktor]]
[[Image:DIRDOKTOR screen shot 2.JPG|right|thumb|250px|Example view]]

''Copied from readme.txt on destribution disc''

'''Dir Doktor 1.1 T&J of GPA (c) 2003, 2005'''

Dir Doktor is a tool designed as an help to rebuild a crashed directory
on your precious diskettes. This kind of problem seems to be more and more
frequent for all CPC users using tree inches diskettes (tired drives ?).

This idea of this program is old. It has grown in my mind during the Byte'98
CPC meeting after having seen Madram spending two hours repairing a damaged 
directory on a Targhan/Ramlaid' diskette.

A few years ago, I had the same problem, a crashed directory on a important
disk ("Citadelle", a future french adventure game). So, I definitly decided 
to create this tool. When a early preview has been presented during the
amazing "Bordelik meeting '5', many people seemed to be very interested by
this program :-). In just one evening, it has saved files of three sceners
(Hello Beb, Mat & Yan !).

Dir Doktor needs a little knowledges about disk organisation, so you are
welcome to read this notice to understand how it works. You will have to
suffer my awful english... 

For comments, bug(s) report or wedding project :-), write to my new E-mail
address : herve.buggos@free.fr

== What's new in the 1.1 release ? ==

Some minor bugs have been removed. The sector display routine is faster (no
more CALL &BB5A inside !). Dir Doktor now recognizes Starkos headers. And
finaly, the function "Display selected blocks" is in the code !


== How Dir Doktor can repair a directory ? ==

Files on a diskette are physically saved on blocks (a block is a group of two
sectors). These blocks are registered in a special area of the diskette named
the directory.

On a DATA disk, the directory is located on the fourth primary sectors of the
track 0 (sectors &C1 to &C4).

On a VENDOR or SYSTEM disk, the directory is located on the fourth primary
sectors of the track 2 (sectors &41 to &44).

When just a directory is destroyed, all the datas are not lost, the blocks are 
still present on the diskette. The goal is to find them and to create again 
files that are using these blocks.

'''BASIC and BINARY files''' : CPC helps us because it always saves in the first
file's block a 128 bytes header. In this one, we can read important 
imformations :  the filename, its type, its length, its loading and
run adresses.

Dir Doktor reads all blocks to find these headers. With their informations,
it calculates the length in sectors of each file. The program can 
automatically allocate blocks to the restored files (not always successfully)
or you can do this boring but necessary job by yourself.

'''STARKOS files''' : they are ASCII files with a special header that always begins
by "STK1.0". Dir Doktor can only find this header, not the whole file. It
considers it as an empty file and names it as STFILExx.STK.
Like an ASCII file, you must find the  blocks that are attached to each file.

'''ASCII files''' : restoring this kind of file is more complicated, because they
don't have headers.

Dir Doktor looks for special ASCII string in each block (&0A &00, end of
line and &1A, end of ASCII file). If such informations are found, the
program considers that the block contains ASCII datas. Unfortunately, it is
not always the case. So, Dir Doktor can display on screen all bytes of a
sector. For an human being, it is easier to 'see' if it is ASCII datas or
binary code !

'''CPM files''' : Theses damned ones have no header, but contain machine code. So
it is quite difficult to restore them properly if you don't know exactly
what you are looking for...

Dir Doktor has no special research facility for this kind of file, so, 
your only hope is the sectors editor and patience...

When you have found the first block of a file, how can we know where are the
following ones ? When a file has been written several times, there is a risk
that its blocks are not "just behind" the first one : this phenomenum is 
called fragmentation.

Fortunately, even when a file is fragmented, its blocks are obligatory 'after'
the first one (thanks Amsdos !). So, the idea is to restore in the first step 
'normal' files, and in the second step the fragmented files using the free 
blocks available.

If you have not understand everything, you can train yourself with an example
if the chapter 5).


== Menus ==

All commands are called by pressing a key (letter or digit). They are always 
printed in the menus between the symbols '<' and '>'. 

== The main menu ==

<D>iscover sectors

Investigates the disk sectors. Program asks you for a disk in the
working drive. It displays all informations found in a kind of map.

* grey square  : free sector
* black square : datas found is the sector
* yellow 'H'   : BINARY or BASIC header
* yellow 'S'   : STARKOS header
* grey 'X'     : damaged sector, not readable
* blue 'A'     : ASCII end of line string found
* blue 'E'     : ASCII end of file string found

Note that a "E" or "A" sector does not necessarily means it is an
ASCII one.

It can be machine code.

[S]ave map

Save a map. If you wan to make tests and restore files one by one,
it will be useful not to loose time making sectors analysis each 
time you make a try.

You can save 9 different maps. The .MAP files are always saved on
the 'program disk', not on the disk to repair ! So, it it really
interesting to work with two drives. Look at function '<C>hange
working drive' for further informations.

[L]oad map

Loads in memory a saved map.

[A]llocate blocks

Displays another menu, that help you to choose the blocks of each
files. Use it after having made a disk map.

[W]rite directory

Writes the 'new' directory on the damaged diskette.

For ASCII or CPM files, Dir Doktor does not calculate exactly the
amount of records (always the same reason, it does not know the real
length of the file), but uses this formula : number of blocks of the
file x 8.
In all cases, it does not make trouble when you load a restored file,
even if its records number is too high.     

Warning ! If one of the directory sectors is damaged, Dir Doktor will
not be able to repair it. Run first the WRITECAT.BAS program. 
It formats the directory track after saving datas of its data sectors.


[C]hange working drive

Allows you to choose the 'working drive'. If you own two drives, it is
better to define the first one as the 'Program drive' and the second one
as the 'Working drive'. Like this, you won't spend all your time
swapping diskettes !
        
Drives status is displayed in the main menu. 

== Allocate blocks menu ==

In this sub-menu, Dir Doktor gives you many commands helping you to make the
link between files found in the discover process and blocks.

Found files are displayed one by one under the cartography window. For each
one, Dir Doktor shows it loading address, its length, and the number of
sectors it needs (very important information).

Use arrow keys [UP] and [DOWN] to choose a file. 
Use arrow keys [LEFT] and [RIGHT] to select the first or last file.

In the cartography, the blue '#' allows you to see the current file header.
Of course, for ASCII or CPM files, there is no sharp (no header !).

[R]estore file

Automatically allocates blocks neccessary for the current file. 
If the file is fragmented, Dir Doktor  stops when a header is found
in the choosen blocks. Then, it displays the number of missing
sectors.

So, this command works fine if the files are not fragmented.

[U]ndo restore

Cancels the previous command. It also clear the manual allocations of
blocks for the current file.

[D]isplay blocks

Shows in the window map all blocks of a restored files. They are
printed on screen with blue squares.

[S]elect block

Manually selects a block. With this command, you access another menu,
where you control a cursor in the map window (see menu 2.3).

[N]ew file

Adds an 'empty' file in the file list. It is necessary to restore ASCII
or CPM files. File lenght will ALWAYS be 0, even if blocks are 
associated with.
Program asks first for the filename, and its extension.

[C]hange filename

Try to guess... It is really usefull not to have duplicate files in
the directory. How can it be possible ? When you save a program two
times, the first saved one is renamed with the .BAK extension. BUT,
this change is only made in the directory, not in the file header !

If you omit to change duplicate filenames, in the rejuvenated 
directory, only one name is be displayed by the CAT command, and
the file length is be wrong. So...

[M]enu

Goes back to the main menu.

== Manually select block ==

In this sub-sub-menu, Dir Doktor gives you commands helping you to make 
manually the link between files found in the discover process and blocks.
Unfortunatelly, it is the only way to restore ASCII and CPM files.

On this screen, the 'working' sector is plotted by a grey lozenge in the map
window. You can move it with the arrow keys.
        
[COPY] Select block

Choose a block (two sectors) for the current file.

[ENTER]

Cancel previous command.

[V]iew sector datas

Displays datas of the current sector, in two mode 2 screens. Thanks
to this function, it is easier to know if a block contains ASCII
datas.
Byte values under 32 (blank char) are replaced by spaces.

[M]enu

Goes back to the 'Allocate block menu'

== Hints and tricks ==

Even if Dir Doktor cannot make data loss, you should ALWAYS work with a backup
copy of a damaged diskette. It gives you the possibility to verify that only
the diskette directory is destroyed...

When you start a repair procedure, try first to restore files using the
'[R]estore file' option. Save your work before to write the new catalog,
then verify that all rejuvenated files are correct.
After this first step, try to restore the fragmented files one by one.

If a file has an uneven number of sectors, and the next sector is empty,
there is a really good chance that the block is the end of the file.

== Dir Doktor lakes... ==

Dir Doktor cannot repair damaged sectors. Try to make a copy of your broken
disk with backup tools like Discology or Hercule.

It doesn't recognize non standard formats. You can only use it with DATA,
VENDOR or SYSTEM diskettes (40 tracks).
 
Maybe in a distant future, I could release another version of the program.
The main problem is the bad legibility of the window map in MODE 2...

== Let's try with an example ==

=== Prepare a example disk ===

Format a diskette (DATA format) and label it EXAMPLE.

Load in memory the program EXAMPLE.BAS, then launch it with the EXAMPLE
disk in the drive.

-> This program creates the following deleted files :

<pre>
        ROMBASIC.BIN
        GPA.TXT
        SCREEN.BIN
        VECTORS.BIN
</pre>

Files ROMBASIC.BIN, GPA.TXT and VECTORS are saved normally.

File SCREEN.BIN is saved in a way it has fragmented blocks. 

=== Diskette analysis ===

Load Dir Doktor, make a disk Analysis with the command <D>iscover.

-> Dir Doktor finds three headers :

<pre>
1 - track 0, sector &C5
2 - track 4, sector &C7
3 - track 7, sector &C5
</pre>

=== Restore binary files ===

Choose [A]llocate to choose blocks for these headers.

First file : ROMBASE - 33 sectors

Choose [R]estore file option

-> 17 blocks are selected (34 sectors).
        
Push [Down] key to display the second file informations.

Second file : SCREEN.BIN - 33 sectors

Choose [R]estore file option
Only 26 sectors are allocated. Seven sectors are missing. 
Yes, the file is fragmented !

Push [Down] key to display the third file informations.

Third file : VECTORS.BIN - 4 sectors
        
Choose [R]estore file option

-> 2 blocks are selected (4 sectors).

Studying the map window, you can notice that after the file VECTORS.BIN, there
is 7 sectors unallocated. Well, it might be the one we needs for the file
SCREEN.BIN, don't you think so ? :-)

Push [Up] key to display the second file informations.

Choose [S]elect block option.

Move the cursor on the first free sector on track 8 and push the
[COPY] key to associate the four blocks to the SCREEN.BIN file.

Push [M]enu key to come back to the Allocate menu.

To verify your work, choose the [D]isplay block option.

=== Restore the ASCII file ===

We must now restore the ASCII file GPA.TXT. Of course, Dir Doktor has
not found its header (no header in ASCII files, remenber !). But, looking
at the window map, there is a little area of 3 sectors considered by
Dir Doktor as ASCII datas. 

First step, we must create the new file.

In the menu [A]llocate blocks :

Choose [N]ew file option.

Filename  : type GPA then press <ENTER>
Extension : type TXT then press <ENTER>

If you have done it right, you shoud find a new file in the list in fourth
position. 

Push [S]elect block

Allocate the two blocks to the file (track 4, sector &C3 to &C6).

Push [M] twice to go back to the main menu.

=== Save the map ===

Now, you must save your work before to generate the directory. If you have
made some errors, you can load the saved map and change your selections
easily.

In the main menu :

Choose [S]ave map option.

Choose the first location pushing the key [0].

=== Generate the directory ===

In the main menu :

Choose [W]rite directory option.

When the catalog is written on the working diskette, just type the Basic
CAT command. You should find four files.

Unfortunately, we can just verify one file, the screen. Load it in &C000.
You should normaly see MODE 1 text. If the CPC displays stranges things,
you have made an error !

Finished ! Of course, if your crashed diskette if full of fragmented ASCII and
CPM files, it will be more complicated. But, in most cases, with little 
perseverance, it is possible to find back files !