A2TOOLS Manual for MS-DOS
NAME
A2TOOLS.EXE - tools to move data to and from Apple DOS
3.3 disk images (Tip: To reduce typing on the command line
it is better to shorten the program name to something like
A2.EXE.)
SYNOPSIS
a2 dir disk_image
a2 out [-r] disk_image a2_file [target_file]
a2 in [-r] filetype disk_image a2_file [source_file]
a2 del filename
DESCRIPTION
a2tools is a set of commands that facilitates the transfer
of data between DOS and the Apple II environment via disk
images (.dsk files). It is intended for use mainly with
Apple II emulators.
Features
- Works with DOS 3.3-order .dsk disk images.
- Expands tokenized Integer and Applesoft BASIC pro-
grams.
- Knows about sparse files.
"dir" shows the directory contents of the specified image,
including the disk volume and number of free sectors.
"out" writes the file contained in the image to the target
file if specified, or to the standard output otherwise.
If the target file exists, it is overwritten. Unless the
-r option is given, the data will be processed according
to the file type as follows:
Text: Output all data from the beginning of the file up
to the first zero byte. The high bit is cleared
and linefeeds are substituted for carriage returns.
BASIC (Integer and Applesoft):
Expand (detokenize) the program and output it as
readable ASCII.
Binary:
Ignore the first two file bytes (base address), and
use the next two bytes (length) to produce a binary
file of the exact original size in bytes.
Other types:
Not accepted unless in raw mode (see below).
If the -r (raw mode) option is given, no postprocessing of
file data is done. For files of type other than T (text),
the first 0/0 pair in the track/ sector list is assumed to
mark the end of file. However, type T files may be
sparse, with 0/0 pairs marking unwritten segments. Hence,
this mode will always output type T files in multiples of
31232 bytes, and others in multiples of 256 bytes.
"in" writes to a new file in the image the source file if
specified, or the standard input otherwise. The file must
not already exist. The filetype argument must consist of
a single letter denoting the type of the new file. Valid
values are:
T,t - text
I,i - Integer BASIC
A,a - Applesoft BASIC
B,b[.addr] - binary (optional base address in hex)
R,r - relocatable binary
S,s - type S (obscure)
X,x - "new A" (obscure)
Y,y - "new B" (obscure)
Unless the -r (raw mode) option is given, only types T and
B are acceptable to a2in. Input processing is as follows:
Text: Set the high bit and substitute carriage returns
for linefeeds.
Binary:
Set the base address to that given in the filetype
argument, or to the default of 0x2000. Set the
file length to the exact length of the standard
input stream. Since the length field is only two
bytes wide, file lengths of 64K or more are ille-
gal.
In raw mode, the standard input is written directly to the
file. Zeroes are used to pad any partial last sectors.
If the new file is type T, blocks containing all zeroes
are denoted by a 0/0 entry in the track/sector list
instead of being allocated a sector. That is, sparse
files will be created.
MS-DOS NOTES
Apple DOS 3.3 file names may contain spaces, which are
separators for command-line arguments in DOS. To prevent
this interpretation, enclose the entire name in "double
quotes". A double quote itself may be included by pre-
ceding it with a backslash.
Standard input and output cannot be used to transfer
binary data in DOS, in which case a source or destination
filename is required.
EXAMPLES
Send a readable copy of the BASIC program "PLOT FUNCTION"
on the disk image "basic.dsk" to the printer:
C> a2 out basic.dsk "PLOT FUNCTION" prn
Import the binary file "pics\airplane" into the disk image
"pics.dsk". Assign it a name of "AIRPLANE" and a base
address of 0x4000 (second hi- res graphics page):
C> a2 in b.4000 pics.dsk AIRPLANE pics\airplane
BUGS
- Works with 143360-byte DOS 3.3-order images only.
- Does not tokenize plain-text BASIC source files,
although this is easily accomplished using the DOS
3.3 EXEC command on such a file.
- Doesn't handle multiple files, although it can eas-
ily be wrapped in shell scripts to enhance conve-
nience.
AUTHOR
Terry Kyriacopoulos <terryk@echo-on.net>
7 April 2001