beneath-apple-dos/D2S1/APPENDIX.A#064000.txt

.ec^
.m11
.m22
.m48
.na
.ll60
.fo ''-%-
.pn5
.pi0
.br
.np
.ce
APPENDIX A - EXAMPLE PROGRAMS
.sp1

This section is intended to supply
the reader with utility programs
which can be used to examine and
repair diskettes.  These programs are
provided in their source form to
serve as examples of the programming
necessary to interface practical
programs to DOS.  The reader who
does not know assembly language may
also benefit from these programs by
entering them from the monitor in
their binary form and saving them to
disk for later use.   It should be
pointed out that the use of 16 sector
diskettes is assumed, although most of
the programs can be easily modified
to work under any version of DOS.
It is recommended that, until the
reader is completely familiar with
the operation of these programs, he
would be well advised to use them
only on an "expendable" diskette.
None of the programs can physically
damage a diskette, but they can, if
used improperly, destroy the data on
a diskette, requiring it to be
re-INITialized.
.sp1
Five programs are provided:
.sp1
.nf
DUMP    TRACK DUMP UTILITY
.pi8
.in8

This is an example of how to directly
access the disk drive through its I/O
select addresses.  DUMP may be used
to dump any given track in its raw,
prenibbilized form, to memory for
examination. This can be useful both
to understand how disks are formatted
and in diagnosing clobbered
diskettes.
.sp1
.in0
.nf
ZAP     DISK UPDATE UTILITY
.pi8
.in8

This program is the backbone of any
attempt to patch a diskette directory
back together.  It is also useful in
examining the structure of files
stored on disk and in applying
patches to files or DOS directly.
ZAP allows its user to read, and
optionally write, any sector on a
diskette.  As such, it serves as a
good example of a program which calls
Read/Write Track/Sector (RWTS).
.sp1
.in0
.nf
INIT    REFORMAT A SINGLE TRACK
.pi8
.in8

This program will initialize a single
track on a diskette.  Any volume
number ($00-$FF) may be specified.
INIT is useful in restoring a track
whose sectoring has been damaged
without reinitializing the entire
diskette.  DOS 3.3 and 48K is assumed.
.bp
.in0
.nf
FTS     FIND T/S LISTS UTILITY
.pi8
.in8

FTS may be used when the directory
for a diskette has been destroyed.
It searches every sector on a
diskette for what appear to be
Track/Sector Lists, printing the
track and sector location of each it
finds.  Knowing the locations of the
T/S Lists can help the user patch
together a new catalog using ZAP.
.sp1
.in0
.nf
COPY    CONVERT FILES
.pi8
.in8

COPY is provided as an example of
direct use of the DOS File Manager
package from assembly language.  The
program will read an input B-type
file and copy its contents to an
output T-type file.  Although it
could be used, for example,
to convert files used
by the Programma
PIE editor for use by the
Apple Toolkit assembler,
it is not included as a utility
program but rather as an example of
the programming necessary to access
the File Manager.
.sp2
.pi0
.in0
STORING THE PROGRAMS ON DISKETTE
.pp
The enterprising programmer may wish
to type the source code for each
program into an assembler and
assemble the programs onto disk.  The
Apple Toolkit assembler was used to
produce the listings presented here,
and interested programmers should
consult the documentation for that
assembler for more information on the
pseudo-opcodes used.  For the
non-assembly language programmer, the
binary object code of each program
may be entered from the monitor using
the following procedure.

The assembly language listings
consist of columns of information as
follows:
.sp1
        The address of some object
code
        The object code which should
be stored there
        The statement number
        The statement itself
.sp1
For example...
.sp1
.nf
0800:20 DC 03  112 COPY    JSR  LOCFPL      FIND PARMLIST
.sp1
.fi
indicates that the binary code
"20DC03" should be stored at 0800 and
that this is statement 112.  To enter
a program in the monitor, the reader
must type in each address and its
corresponding object code.  The
following is an example of how to
enter the DUMP program:
.bp
.nf
CALL -151               (Enter the monitor from BASIC)
0800:20 E3 03
0803:84 00
0805:85 01
0807:A5 02
.sp1
 ...etc...
.sp1
0879:85 3F
087B:4C B3 FD
BSAVE DUMP,A$800,L$7E   (Save program to disk)

Note that if a line (such as line 4
in DUMP) has no object bytes
associated with it, it may be
ignored.
When the program is to be run...
.sp1
.nf
BLOAD DUMP              (Load program)
CALL -151               (Get into monitor)
02:11 N 800G            (Store track to dump, run program)
.pp
The BSAVE commands which must be used
with the other programs are:
.sp1
BSAVE ZAP,A$900,L$6C
.br
BSAVE INIT,A$800,L$89
.br
BSAVE FTS,A$900,L$DC
.br
BSAVE COPY,A$800,L$1EC
.bp
DUMP -- TRACK DUMP UTILITY
.sp1

The DUMP program will dump any track
on a diskette in its raw,
pre-nibbilized format, allowing the
user to examine the sector address
and data fields and the formatting of
the track.  This allows the curious
reader to examine his own diskettes
to better understand the concepts
presented in the preceeding chapters.
DUMP may also be used to examine
most protected disks to see how they
differ from normal ones and to
diagnose diskettes with clobbered
sector address or data fields with
the intention of recovering from disk
I/O errors.  The DUMP program serves
as an example of direct use of the
DISK II hardware from assembly
language, with little or no use of
DOS.

To use DUMP, first store the number
of the track you wish dumped at
location $02, then begin execution at
$800.  DUMP will return to the
monitor after displaying the first
part of the track in hexadecimal on
the screen.  The entire track image
is stored, starting at $1000.
For example:
.sp1
.nf
CALL -151               (Get into the monitor from BASIC)
BLOAD DUMP              (Load the DUMP program)
 ...Now insert the diskette to be dumped...
02:11 N 800G            (Store a 11 (track 17, the catalog
                         track) in $02, N terminates the store
                         command, go to location $800)
.sp1
The output might look like this...
.sp1
1000- D5 AA 96 AA AB AA BB AB   (Start of sector address)
1008- AA AB BA DE AA E8 C0 FF
1010- 9E FF FF FF FF FF D5 AA   (Start of sector data)
1018- AD AE B2 9D AC AE 96 96   (Sector data)
 ...etc...

Quite often, a sector with an I/O
error will have only one bit which is
in error, either in the address or
data header or in the actual data
itself.  A particularly patient
programmer can, using DUMP and
perhaps a half hour of hand
"nibbilizing" determine the location
of the error and record the data on
paper for later entry via ZAP.  A
thorough understanding of Chapter 3
is necessary to accomplish this feat.
.bp
ZAP -- DISK UPDATE UTILITY
.sp1

The next step up the ladder from DUMP
is to access data on the diskette at
the sector level.  The ZAP program
allows its user to specify a track
and sector to be read into memory.
The programmer can then make changes
in the image of the sector in memory
and subsequently use ZAP to write the
modified image back over the sector
on disk.  ZAP is particularly useful
when it is necessary to patch up a
damaged directory.  Its use in this
regard will be covered in more detail
when FTS is explained.

To use ZAP, store the number of the
track and sector you wish to access
in $02 and $03 respectively.  Tracks
may range from $00 to $22 and sectors
from $00 to $0F.  For example,
the Volume Table of
Contents (VTOC) for the diskette may
be examined by entering $11 for the
track and $00 for the sector.  $04
should be initialized with either a
$01 to indicate that the sector is to
be read into memory, or $02 to ask
that memory be written out to the
sector.  Other values for location
$04 can produce damaging results
($04 in location $04 will INIT your
diskette!).  When these three memory
locations have been set up, begin
execution at $900.  ZAP will read or
write the sector into or from the 256
bytes starting at $800.  For example:
.sp1
.nf
CALL -151               (Get into the monitor from BASIC)
BLOAD ZAP               (Load the ZAP program)
 ...Now insert the diskette to be zapped...
02:11 00 01 N 900G      (Store a 11 (track 17, the catalog
                         track) in $02, a 00 (sector 0) at $03,
                         and a 01 (read) at $04.  N ends the
                         store command and 900G runs ZAP.)
.sp1
The output might look like this...
.sp1
0800- 04 11 0F 03 00 00 01 00   (Start of VTOC)
0808- 00 00 00 00 00 00 00 00
0810- 00 00 00 00 00 00 00 00
0818- 00 00 00 00 00 00 00 00
 ...etc...

In the above example, if the byte at
offset 3 (the version of DOS which
INITed this diskette) is to be
changed, the following would be
entered...
.sp1
.nf
803:02                  (Change 03 to 02)
04:02 N 900G            (Change ZAP to write mode and do it)
.pp
Note that ZAP will remember the
previous
values in $02, $03, and $04.
.bp

If something is wrong with the sector
to be read (an I/O error, perhaps),
ZAP will print an error message of
the form:
.sp1
RC=10
.sp1
A return code of 10, in this case,
means that the diskette was write
protected and a write operation was
attempted.  Other error codes are 20
- volume mismatch, 40 - drive error,
and 80 - read error.  Refer to the
documentation on RWTS given in
Chapter 6 for more information on
these errors.
.bp
INIT -- REFORMAT A SINGLE TRACK
.sp1

Occasionally the sectoring information
on a diskette can become damaged so
that one or more sectors can no
longer be found by DOS.  To correct
this problem requires that the sector
address and data fields be
re-formatted for the entire track
thus affected.  INIT can be used to
selectively reformat a single track,
thus avoiding a total re-INIT of the
diskette.  Before using INIT, the
user should first attempt to write on
the suspect sector (using ZAP).  If
RWTS refuses to write to the sector
(RC=40),
then INIT must be run on the entire
track.  To avoid losing data, all
other sectors on the track should be
read and copied to another diskette
prior to reformatting.  After INIT is
run they can be copied back to the
repaired diskette and data can be
written to the previously damaged
sector.

To run INIT, first store the number
of the track you wish reformatted at
location $02, the volume number of
the disk at location $03, and then
begin execution at $800.  INIT will
return to the monitor upon
completion.  If the track can not be
formatted for some reason (eg.
physical damage or problems with the
disk drive itself) a return code is
printed.  For example:
.sp1
.nf
CALL -151               (Get into the monitor from BASIC)
BLOAD INIT              (Load the INIT program)
 ...Now insert the disk to be INIT-ed...
02:11 FE N 800G         (Store a 11 (track 17, the catalog
                        track) in $02, a volume number of
                        $FE (254) in $03, N terminates the
                        store command, go to location $800)
.sp1
.fi
WARNING: DOS 3.3 must be loaded in
the machine before running INIT and a
48K Apple is assumed.  INIT will not work with other
versions of DOS or other memory
sizes.
.bp
FTS -- FIND T/S LISTS UTILITY
.sp1

From time to time one of your
diskettes will develop an I/O error
smack in the middle of the catalog
track.  When this occurs, any attempt
to use the diskette will result in an
I/O ERROR message from DOS.
Generally, when this happens, the
data stored in the files on the
diskette is still intact; only the
pointers to the files are gone.  If
the data absolutely must be
recovered, a knowledgeable Apple user
can reconstruct the catalog from
scratch.  Doing this involves first
finding the T/S Lists for each file,
and then using ZAP to patch a catalog
entry into track 16 for each file
which was found.  FTS is a utility
which will scan a diskette for T/S
Lists.  Although it may flag some
sectors which are not T/S Lists as
being such, it will never miss a
valid T/S List.  Therefore, after
running FTS the programmer must use
ZAP to examine each track/sector
printed by FTS to see if it is really
a T/S List.  Additionally, FTS will
find every T/S List image on the
diskette, even some which were for
files which have since been deleted.
Since it is difficult to determine
which files are valid and which are
old deleted files, it is usually
necessary to restore all the files
and copy them to another diskette,
and later delete the duplicate or
unwanted ones.

To run FTS, simply load the program
and start execution at $900.  FTS
will print the track and sector
number of each sector it finds which
bears a resemblance to a T/S List.
For example:
.sp1
.nf
CALL -151               (Get into the monitor from BASIC)
BLOAD FTS               (Load the FTS program)
 ...Now insert the disk to be scanned...
900G                    (Run the FTS program on this diskette)
.sp1
The output might look like this...
.sp1
T=12 S=0F
T=13 S=0F
T=14 S=0D
T=14 S=0F
.bp

Here, only four possible files were
found.  ZAP should now be used to
read track $12, sector $0F.  At +$0C
is the track and sector of the first
sector in the file.  This sector can
be read and examined to try to
identify the file and its type.
Usually a BASIC program can be
identified, even though it is stored
in tokenized form, from the text
strings contained in the PRINT
statements.  An ASCII conversion
chart (see page 8 in the APPLE II
REFERENCE MANUAL) can be used to
decode these character strings.
Straight T-type files will also
contain ASCII text, with each line
separated from the others with $8D
(carriage returns).  B-type files are
the hardest to identify, unless the
address and length stored in the
first 4 bytes are recognizable.  If
you cannot identify the file, assume
it is APPLESOFT BASIC.  If this
assumption turns out to be incorrect,
you can always go back and ZAP the
file type in the CATALOG to try
something else.  Given below is an
example ZAP to the CATALOG to create
an entry for the file whose T/S List
is at T=12 S=0F.
.sp1
.nf
CALL -151
BLOAD ZAP
 ...insert disk to be ZAPped...
800:00 N 801<800.8FEM   (Zero sector area of memory)
80B:12 0F 02            (Track 12, Sector 0F, Type-A)
:C1 A0 A0 A0 A0 A0 A0   (Name is "A")
:A0 A0 A0 A0 A0 A0 A0   (fill name out with 29 blanks)
:A0 A0 A0 A0 A0 A0 A0
:A0 A0 A0 A0 A0 A0 A0
:A0 A0
02:11 0F 02 N 900G      (Write new sector image out as
                         first (and only) catalog sector)

The file should immediately be copied
to another diskette and then the
process repeated for each T/S List
found by FTS until all of the files
have been recovered.  As each file is
recovered, it may be RENAMEd to its
previous name.  Once all the files
have been copied to another disk,
and successfully tested, the
damaged disk may be re-INITialized.
.bp
COPY -- CONVERT FILES
.sp1

The COPY program demonstrates the use
of the DOS File Manager subroutine
package from assembly language.  COPY
will read as input a Binary type
file, stripping off the address and
length information, and write the
data out as a newly created Text type
file.  The name of the input file is
assumed to be "INPUT", although this
could just as easily have been
inputted from the keyboard, and the
name of the output file is "OUTPUT".
COPY is a single drive operation,
using the last drive which was
referenced.

To run COPY, load it and begin
execution at $800:
.sp1
.nf
CALL -151               (Get into the monitor from BASIC)
BLOAD COPY              (Load the COPY program)
 ...Now insert the disk containing INPUT...
900G                    (Run the COPY program)

When COPY finishes, it will return to
BASIC.  If any errors occur, the
return code passed back from the File
Manager will be printed.  Consult the
documentation on the File Manager
parameter list in Chapter 6
for a list of these return codes.
.br
.nx appendix b