mirror of
https://github.com/iKarith/beneath-apple-dos.git
synced 2024-06-02 22:41:31 +00:00
27bcf5f79c
PIEWriter dot codes are case-insensitive, and I've deciphered that .pp is a paragraph break. Replace those with blank lines. The NUL at EOF was escaped, but it can be simply deleted. Did so.
575 lines
16 KiB
Plaintext
575 lines
16 KiB
Plaintext
.ec^
|
|
.m11
|
|
.m22
|
|
.m48
|
|
.na
|
|
.ll60
|
|
.fo ''-%-
|
|
.pn 5
|
|
.pi 0
|
|
.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
|