A2TOOLS(6)

NAME
a2tools - tools to move data to and from Apple DOS 3.3 disk images
a2ls - show directory of disk image
a2out - read a file from disk image
a2in - write a file into disk image
a2rm - remove a file from disk image

SYNOPSIS
a2ls disk_image
a2out [-r] disk_image a2_file [target_file]
a2in [-r] filetype disk_image a2_file [source_file]
a2rm filename

DESCRIPTION
a2tools is a set of commands that facilitates the transfer of data between Unix and the Apple II environment via disk images (.dsk files). It is intended for use mainly with Apple II emulators such as apple2(6).

  Features

-   Works with DOS 3.3-order .dsk disk images.

-   Expands tokenized Integer and Applesoft BASIC programs.

-   Knows about sparse files.

a2ls shows the directory contents of the specified image, including the disk volume and number of free sectors.

a2out 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.
a2in 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 illegal.

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.

EXAMPLES
Send a readable copy of the BASIC program "PLOT FUNCTION" on the disk image "basic.dsk" to the printer:
% a2out basic.dsk 'PLOT FUNCTION' | lpr
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):
% a2in b.4000 pics.dsk 'AIRPLANE' pics/airplane
Copy the Applesoft program "ROOT FINDER" from disk image "math.dsk" to "demo.dsk":
% a2out -r math.dsk 'ROOT FINDER'|a2in -r a demo.dsk 'ROOT FINDER'
Import the sparse database "ACCOUNTS" from a gzip-compressed file:
% zcat accounts.gz | a2in -r t shop.dsk ACCOUNTS

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 easily be wrapped in shell scripts to enhance convenience.

AUTHOR
Terry Kyriacopoulos <terryk@echo-on.net>

SEE ALSO
apple2(6)