Apple-2-SW
/
beneath-apple-dos
mirror of https://github.com/iKarith/beneath-apple-dos.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Clean up appendix A paragraphs

This commit is contained in:
T. Joseph Carter 2017-07-21 05:56:25 -07:00
parent 7db5e6054a
commit a7d599869d
1 changed files with 165 additions and 361 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

526
appendixA.txt
View File

@ -1,126 +1,72 @@
# APPENDIX A - EXAMPLE PROGRAMS # APPENDIX A - EXAMPLE PROGRAMS
This section is intended to supply This section is intended to supply the reader with utility programs which can be
the reader with utility programs used to examine and repair diskettes. These programs are provided in their
which can be used to examine and source form to serve as examples of the programming necessary to interface
repair diskettes. These programs are practical programs to DOS. The reader who does not know assembly language may
provided in their source form to also benefit from these programs by entering them from the monitor in their
serve as examples of the programming binary form and saving them to disk for later use. It should be pointed out
necessary to interface practical that the use of 16 sector diskettes is assumed, although most of the programs
programs to DOS. The reader who can be easily modified to work under any version of DOS. It is recommended
does not know assembly language may that, until the reader is completely familiar with the operation of these
also benefit from these programs by programs, he would be well advised to use them only on an "expendable" diskette.
entering them from the monitor in None of the programs can physically damage a diskette, but they can, if used
their binary form and saving them to improperly, destroy the data on a diskette, requiring it to be re-INITialized.
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.
Five programs are provided: Five programs are provided:
DUMP TRACK DUMP UTILITY DUMP TRACK DUMP UTILITY
This is an example of how to directly This is an example of how to directly access the disk drive through its I/O
access the disk drive through its I/O select addresses. DUMP may be used to dump any given track in its raw,
select addresses. DUMP may be used prenibbilized form, to memory for examination. This can be useful both to
to dump any given track in its raw, understand how disks are formatted and in diagnosing clobbered diskettes.
prenibbilized form, to memory for
examination. This can be useful both
to understand how disks are formatted
and in diagnosing clobbered
diskettes.
ZAP DISK UPDATE UTILITY ZAP DISK UPDATE UTILITY
This program is the backbone of any This program is the backbone of any attempt to patch a diskette directory back
attempt to patch a diskette directory together. It is also useful in examining the structure of files stored on disk
back together. It is also useful in and in applying patches to files or DOS directly. ZAP allows its user to read,
examining the structure of files and optionally write, any sector on a diskette. As such, it serves as a good
stored on disk and in applying example of a program which calls Read/Write Track/Sector (RWTS).
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).
INIT REFORMAT A SINGLE TRACK INIT REFORMAT A SINGLE TRACK
This program will initialize a single This program will initialize a single track on a diskette. Any volume number
track on a diskette. Any volume ($00-$FF) may be specified. INIT is useful in restoring a track whose sectoring
number ($00-$FF) may be specified. has been damaged without reinitializing the entire diskette. DOS 3.3 and 48K is
INIT is useful in restoring a track assumed.
whose sectoring has been damaged
without reinitializing the entire
diskette. DOS 3.3 and 48K is assumed.
FTS FIND T/S LISTS UTILITY FTS FIND T/S LISTS UTILITY
FTS may be used when the directory FTS may be used when the directory for a diskette has been destroyed. It
for a diskette has been destroyed. searches every sector on a diskette for what appear to be Track/Sector Lists,
It searches every sector on a printing the track and sector location of each it finds. Knowing the locations
diskette for what appear to be of the T/S Lists can help the user patch together a new catalog using ZAP.
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.
COPY CONVERT FILES COPY CONVERT FILES
COPY is provided as an example of COPY is provided as an example of direct use of the DOS File Manager package
direct use of the DOS File Manager from assembly language. The program will read an input B-type file and copy its
package from assembly language. The contents to an output T-type file. Although it could be used, for example, to
program will read an input B-type convert files used by the Programma PIE editor for use by the Apple Toolkit
file and copy its contents to an assembler, it is not included as a utility program but rather as an example of
output T-type file. Although it the programming necessary to access the File Manager.
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.
STORING THE PROGRAMS ON DISKETTE STORING THE PROGRAMS ON DISKETTE
The enterprising programmer may wish The enterprising programmer may wish to type the source code for each program
to type the source code for each into an assembler and assemble the programs onto disk. The Apple Toolkit
program into an assembler and assembler was used to produce the listings presented here, and interested
assemble the programs onto disk. The programmers should consult the documentation for that assembler for more
Apple Toolkit assembler was used to information on the pseudo-opcodes used. For the non-assembly language
produce the listings presented here, programmer, the binary object code of each program may be entered from the
and interested programmers should monitor using the following procedure.
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 The assembly language listings consist of columns of information as follows:
consist of columns of information as
follows:
The address of some object The address of some object code
code The object code which should be stored there
The object code which should
be stored there
The statement number The statement number
The statement itself The statement itself
@ -128,14 +74,10 @@ For example...
0800:20 DC 03 112 COPY JSR LOCFPL FIND PARMLIST 0800:20 DC 03 112 COPY JSR LOCFPL FIND PARMLIST
indicates that the binary code indicates that the binary code "20DC03" should be stored at 0800 and that this
"20DC03" should be stored at 0800 and is statement 112. To enter a program in the monitor, the reader must type in
that this is statement 112. To enter each address and its corresponding object code. The following is an example of
a program in the monitor, the reader how to enter the DUMP program:
must type in each address and its
corresponding object code. The
following is an example of how to
enter the DUMP program:
CALL -151 (Enter the monitor from BASIC) CALL -151 (Enter the monitor from BASIC)
0800:20 E3 03 0800:20 E3 03
@ -149,18 +91,14 @@ CALL -151 (Enter the monitor from BASIC)
087B:4C B3 FD 087B:4C B3 FD
BSAVE DUMP,A$800,L$7E (Save program to disk) BSAVE DUMP,A$800,L$7E (Save program to disk)
Note that if a line (such as line 4 Note that if a line (such as line 4 in DUMP) has no object bytes associated with
in DUMP) has no object bytes it, it may be ignored. When the program is to be run...
associated with it, it may be
ignored.
When the program is to be run...
BLOAD DUMP (Load program) BLOAD DUMP (Load program)
CALL -151 (Get into monitor) CALL -151 (Get into monitor)
02:11 N 800G (Store track to dump, run program) 02:11 N 800G (Store track to dump, run program)
The BSAVE commands which must be used The BSAVE commands which must be used with the other programs are:
with the other programs are:
BSAVE ZAP,A$900,L$6C BSAVE ZAP,A$900,L$6C
BSAVE INIT,A$800,L$89 BSAVE INIT,A$800,L$89
@ -168,37 +106,20 @@ BSAVE FTS,A$900,L$DC
BSAVE COPY,A$800,L$1EC BSAVE COPY,A$800,L$1EC
DUMP -- TRACK DUMP UTILITY DUMP -- TRACK DUMP UTILITY
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.
The DUMP program will dump any track To use DUMP, first store the number of the track you wish dumped at location
on a diskette in its raw, $02, then begin execution at $800. DUMP will return to the monitor after
pre-nibbilized format, allowing the displaying the first part of the track in hexadecimal on the screen. The entire
user to examine the sector address track image is stored, starting at $1000. For example:
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:
CALL -151 (Get into the monitor from BASIC) CALL -151 (Get into the monitor from BASIC)
BLOAD DUMP (Load the DUMP program) BLOAD DUMP (Load the DUMP program)
@ -215,58 +136,33 @@ The output might look like this...
1018- AD AE B2 9D AC AE 96 96 (Sector data) 1018- AD AE B2 9D AC AE 96 96 (Sector data)
...etc... ...etc...
Quite often, a sector with an I/O Quite often, a sector with an I/O error will have only one bit which is in
error will have only one bit which is error, either in the address or data header or in the actual data itself. A
in error, either in the address or particularly patient programmer can, using DUMP and perhaps a half hour of hand
data header or in the actual data "nibbilizing" determine the location of the error and record the data on paper
itself. A particularly patient for later entry via ZAP. A thorough understanding of Chapter 3 is necessary to
programmer can, using DUMP and accomplish this feat.
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.
ZAP -- DISK UPDATE UTILITY ZAP -- DISK UPDATE UTILITY
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.
The next step up the ladder from DUMP To use ZAP, store the number of the track and sector you wish to access in $02
is to access data on the diskette at and $03 respectively. Tracks may range from $00 to $22 and sectors from $00 to
the sector level. The ZAP program $0F. For example, the Volume Table of Contents (VTOC) for the diskette may be
allows its user to specify a track examined by entering $11 for the track and $00 for the sector. $04 should be
and sector to be read into memory. initialized with either a $01 to indicate that the sector is to be read into
The programmer can then make changes memory, or $02 to ask that memory be written out to the sector. Other values
in the image of the sector in memory for location $04 can produce damaging results ($04 in location $04 will INIT
and subsequently use ZAP to write the your diskette!). When these three memory locations have been set up, begin
modified image back over the sector execution at $900. ZAP will read or write the sector into or from the 256 bytes
on disk. ZAP is particularly useful starting at $800. For example:
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:
CALL -151 (Get into the monitor from BASIC) CALL -151 (Get into the monitor from BASIC)
BLOAD ZAP (Load the ZAP program) BLOAD ZAP (Load the ZAP program)
@ -284,75 +180,43 @@ The output might look like this...
0818- 00 00 00 00 00 00 00 00 0818- 00 00 00 00 00 00 00 00
...etc... ...etc...
In the above example, if the byte at In the above example, if the byte at offset 3 (the version of DOS which INITed
offset 3 (the version of DOS which this diskette) is to be changed, the following would be entered...
INITed this diskette) is to be
changed, the following would be
entered...
803:02 (Change 03 to 02) 803:02 (Change 03 to 02)
04:02 N 900G (Change ZAP to write mode and do it) 04:02 N 900G (Change ZAP to write mode and do it)
Note that ZAP will remember the Note that ZAP will remember the previous values in $02, $03, and $04.
previous
values in $02, $03, and $04.
If something is wrong with the sector If something is wrong with the sector to be read (an I/O error, perhaps), ZAP
to be read (an I/O error, perhaps), will print an error message of the form:
ZAP will print an error message of
the form:
RC=10 RC=10
A return code of 10, in this case, A return code of 10, in this case, means that the diskette was write protected
means that the diskette was write and a write operation was attempted. Other error codes are 20 - volume
protected and a write operation was mismatch, 40 - drive error, and 80 - read error. Refer to the documentation on
attempted. Other error codes are 20 RWTS given in Chapter 6 for more information on these errors.
- 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.
INIT -- REFORMAT A SINGLE TRACK INIT -- REFORMAT A SINGLE TRACK
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.
Occasionally the sectoring information To run INIT, first store the number of the track you wish reformatted at
on a diskette can become damaged so location $02, the volume number of the disk at location $03, and then begin
that one or more sectors can no execution at $800. INIT will return to the monitor upon completion. If the
longer be found by DOS. To correct track can not be formatted for some reason (eg. physical damage or problems
this problem requires that the sector with the disk drive itself) a return code is printed. For example:
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:
CALL -151 (Get into the monitor from BASIC) CALL -151 (Get into the monitor from BASIC)
BLOAD INIT (Load the INIT program) BLOAD INIT (Load the INIT program)
@ -362,58 +226,32 @@ BLOAD INIT (Load the INIT program)
$FE (254) in $03, N terminates the $FE (254) in $03, N terminates the
store command, go to location $800) store command, go to location $800)
WARNING: DOS 3.3 must be loaded in WARNING: DOS 3.3 must be loaded in the machine before running INIT and a 48K
the machine before running INIT and a Apple is assumed. INIT will not work with other versions of DOS or other memory
48K Apple is assumed. INIT will not work with other
versions of DOS or other memory
sizes. sizes.
FTS -- FIND T/S LISTS UTILITY FTS -- FIND T/S LISTS UTILITY
From time to time one of your From time to time one of your diskettes will develop an I/O error smack in the
diskettes will develop an I/O error middle of the catalog track. When this occurs, any attempt to use the diskette
smack in the middle of the catalog will result in an I/O ERROR message from DOS. Generally, when this happens, the
track. When this occurs, any attempt data stored in the files on the diskette is still intact; only the pointers to
to use the diskette will result in an the files are gone. If the data absolutely must be recovered, a knowledgeable
I/O ERROR message from DOS. Apple user can reconstruct the catalog from scratch. Doing this involves first
Generally, when this happens, the finding the T/S Lists for each file, and then using ZAP to patch a catalog entry
data stored in the files on the into track 16 for each file which was found. FTS is a utility which will scan a
diskette is still intact; only the diskette for T/S Lists. Although it may flag some sectors which are not T/S
pointers to the files are gone. If Lists as being such, it will never miss a valid T/S List. Therefore, after
the data absolutely must be running FTS the programmer must use ZAP to examine each track/sector printed by
recovered, a knowledgeable Apple user FTS to see if it is really a T/S List. Additionally, FTS will find every T/S
can reconstruct the catalog from List image on the diskette, even some which were for files which have since been
scratch. Doing this involves first deleted. Since it is difficult to determine which files are valid and which are
finding the T/S Lists for each file, old deleted files, it is usually necessary to restore all the files and copy
and then using ZAP to patch a catalog them to another diskette, and later delete the duplicate or unwanted ones.
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 To run FTS, simply load the program and start execution at $900. FTS will print
and start execution at $900. FTS the track and sector number of each sector it finds which bears a resemblance to
will print the track and sector a T/S List. For example:
number of each sector it finds which
bears a resemblance to a T/S List.
For example:
CALL -151 (Get into the monitor from BASIC) CALL -151 (Get into the monitor from BASIC)
BLOAD FTS (Load the FTS program) BLOAD FTS (Load the FTS program)
@ -427,37 +265,20 @@ T=13 S=0F
T=14 S=0D T=14 S=0D
T=14 S=0F T=14 S=0F
Here, only four possible files were Here, only four possible files were found. ZAP should now be used to read track
found. ZAP should now be used to $12, sector $0F. At +$0C is the track and sector of the first sector in the
read track $12, sector $0F. At +$0C file. This sector can be read and examined to try to identify the file and its
is the track and sector of the first type. Usually a BASIC program can be identified, even though it is stored in
sector in the file. This sector can tokenized form, from the text strings contained in the PRINT statements. An
be read and examined to try to ASCII conversion chart (see page 8 in the APPLE II REFERENCE MANUAL) can be used
identify the file and its type. to decode these character strings. Straight T-type files will also contain
Usually a BASIC program can be ASCII text, with each line separated from the others with $8D (carriage
identified, even though it is stored returns). B-type files are the hardest to identify, unless the address and
in tokenized form, from the text length stored in the first 4 bytes are recognizable. If you cannot identify the
strings contained in the PRINT file, assume it is APPLESOFT BASIC. If this assumption turns out to be
statements. An ASCII conversion incorrect, you can always go back and ZAP the file type in the CATALOG to try
chart (see page 8 in the APPLE II something else. Given below is an example ZAP to the CATALOG to create an entry
REFERENCE MANUAL) can be used to for the file whose T/S List is at T=12 S=0F.
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.
CALL -151 CALL -151
BLOAD ZAP BLOAD ZAP
@ -472,49 +293,32 @@ BLOAD ZAP
02:11 0F 02 N 900G (Write new sector image out as 02:11 0F 02 N 900G (Write new sector image out as
first (and only) catalog sector) first (and only) catalog sector)
The file should immediately be copied The file should immediately be copied to another diskette and then the process
to another diskette and then the repeated for each T/S List found by FTS until all of the files have been
process repeated for each T/S List recovered. As each file is recovered, it may be RENAMEd to its previous name.
found by FTS until all of the files Once all the files have been copied to another disk, and successfully tested,
have been recovered. As each file is the damaged disk may be re-INITialized.
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.
COPY -- CONVERT FILES COPY -- CONVERT FILES
The COPY program demonstrates the use The COPY program demonstrates the use of the DOS File Manager subroutine package
of the DOS File Manager subroutine from assembly language. COPY will read as input a Binary type file, stripping
package from assembly language. COPY off the address and length information, and write the data out as a newly
will read as input a Binary type created Text type file. The name of the input file is assumed to be "INPUT",
file, stripping off the address and although this could just as easily have been inputted from the keyboard, and the
length information, and write the name of the output file is "OUTPUT". COPY is a single drive operation, using
data out as a newly created Text type the last drive which was referenced.
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 To run COPY, load it and begin execution at $800:
execution at $800:
CALL -151 (Get into the monitor from BASIC) CALL -151 (Get into the monitor from BASIC)
BLOAD COPY (Load the COPY program) BLOAD COPY (Load the COPY program)
...Now insert the disk containing INPUT... ...Now insert the disk containing INPUT...
900G (Run the COPY program) 900G (Run the COPY program)
When COPY finishes, it will return to When COPY finishes, it will return to BASIC. If any errors occur, the return
BASIC. If any errors occur, the code passed back from the File Manager will be printed. Consult the
return code passed back from the File documentation on the File Manager parameter list in Chapter 6 for a list of
Manager will be printed. Consult the these return codes.
documentation on the File Manager
parameter list in Chapter 6
for a list of these return codes.
.nx appendix b .nx appendix b