Binary ][ protocol

developed by
Gary B. Little

Version History
---------------
November 24, 1986 : Initial release.

Background
----------
Transferring Apple II files in binary form to commercial information
services like CompuServe, Delphi, GEnie, and The Source is, to put it
mildly, a frustrating exercise. (For convenience, I'll refer to such
services, and any other non-Apple II systems, as "hosts.") Although
most hosts are able to receive a file's *data* in binary form (using
the Xmodem protocol, for example), they don't receive the file's all-
important attribute bytes. All the common Apple II operating systems,
notably ProDOS, store the attributes inside the disk directory, not
inside the file itself.

The ProDOS attributes are the access code, file type code, auxiliary
type code, storage type code, date of creation and last modification,
time of creation and last modification, the file size, and the name of
the file itself. (All these terms are defined in Apple's "ProDOS
Technical Reference Manual" or in the book "Apple ProDOS: Advanced
Features for Programmers" by Gary Little.) It is usually not possible
to use a ProDOS file's data without knowing what the file's attributes
are (particularly the file type code, auxiliary type code, and size).
This means ProDOS files uploaded in binary form to a host are useless
to those who download them. The same is true for DOS 3.3 and Pascal
files.

Most Apple II communications programs use special protocols for

transferring file attributes during a binary file transfer, but none
of these protocols have been implemented by hosts. These programs are
only useful for exchanging files with another Apple II running the
same program.

At present, the only acceptable way to transfer an Apple II file to a

host is to convert it into lines of text and send it as a textfile.
Such a textfile would contain a listing of an Applesoft program, or a
series of Apple II system monitor "enter" commands (e.g., 0300:A4 32
etc.). Someone downloading such a file can convert it to binary form
using the Applesoft EXEC command.

The main disadvantage of this technique is that the text version of

the file is over three times the size of the original binary file,
making it expensive (in terms of time and $$$) to upload and download.
It is also awkward, and sometimes impossible, to perform the binary-
to-text or text-to-binary conversion.

The solution to the problem is to upload an encoded binary file which

contains not just the file's data, but the file's attributes as well.
Someone downloading such a file, say using Xmodem, can then use a
conversion program to strip the attributes from the file and create a
file with the required attributes.

To make this technique truly useful, however, the Apple II community

must agree on a format for this encoded binary file. A variety of
incompatible formats, all achieving the same general result, cannot be
allowed to appear.

It is proposed that the Binary II format described in this document be

adopted. What follows is a description of the Binary II format in
sufficient detail to allow software developers to implement it in
Apple II communications programs.

The Binary II File Format

-------------------------
The Binary II form of a standard file consists of a 128-byte file
information header followed by the file's data. The data portion of
the file is padded with nulls ($00 bytes), if necessary, to ensure the
data length is an even multiple of 128. As a result, the Binary II
form of a file is never more than 255 bytes longer than the original
file.

The file information header contains four ID bytes, the attributes of

the file (in ProDOS 8 form), and some control information. Here is the
structure of the header:

Offset Length Contents

------ ------ ---------------------------------------
+0 1 ID byte: always $0A
+1 1 ID byte: always $47
+2 1 ID byte: always $4C
+3 1 access code
+4 1 file type code
+5 2 auxiliary type code
+7 1 storage type code
+8 2 size of file in 512-byte blocks
+10 2 date of modification
+12 2 time of modification
+14 2 date of creation
+16 2 time of creation
+18 1 ID byte: always $02
+19 1 [reserved]
+20 3 end-of-file (EOF) position
+23 1 length of filename/partial pathname
+24 64 ASCII filename or partial pathname
+88 23 [reserved, must be zero]
+111 1 ProDOS 16 access code (high)
+112 1 ProDOS 16 file type code (high)
+113 1 ProDOS 16 storage type code (high)
+114 2 ProDOS 16 size of file in blocks (high)
+116 1 ProDOS 16 end-of-file position (high)
+117 4 disk space needed
+121 1 operating system type
+122 2 native file type code
+124 1 phantom file flag
+125 1 data flags
+126 1 Binary II version number
+127 1 number of files to follow

Multi-byte numeric quantities are stored with their low-order bytes

first, the same order expected by ProDOS. All reserved bytes must be
set to zero; they may be used in future versions of the protocol.
To determine the values of the attributes to be put into a file
information header for a ProDOS file, you can use the ProDOS
GET_FILE_INFO and GET_EOF MLI commands.

Note: Some file attributes returned by ProDOS 16 commands

are one or two bytes longer than the attributes
returned by the corresponding ProDOS 8 commands. At
present, these extra bytes are always zero, and
probably will remain zero forever. In any event,
place the extra bytes returned by ProDOS 16 in the
header at +114 to +119. ProDOS 8 communications
programs should zero these header locations.

The "disk space needed" bytes contain the number of 512-byte disk
blocks the files inside the Binary II file will occupy after they've
been removed from the Binary II file. (The format of a Binary II file
containing multiple files is described below.) If the number is zero,
the person uploading the file did not bother to calculate the space
needed. The "disk space needed" must be placed in the file information
header for the first file inside the Binary II file; it can be set to
zero in subsequent headers. A downloading program can inspect "disk
space needed" and abort the transfer immediately if there isn't enough
disk free space.

The value of the "operating system type" byte indicates the native
operating system of the file:

$00 = ProDOS 8, ProDOS 16, or SOS

$01 = DOS 3.3
$02 = Pascal
$03 = CP/M
$04 = MS-DOS

Note that even if a file is not a ProDOS file, the attributes in the
file information header, including the name, must be inserted in
ProDOS form. Instructions on how to do this for DOS 3.3 files are
given later in this document. Similar considerations apply for the
files of other operating systems.

The "native file type code" has meaning only if the "operating system
type" is non-zero. It is set to the actual file type code assigned to
the file by its native operating system. (Some operating systems, such
as CP/M and MS-DOS, do not use file type codes, however.) Contrast
this with the file type code at +4, which is the closest equivalent
ProDOS file type code. The "native file type code" is needed to
distinguish files which have the same *ProDOS* file type, but which
may have different file types in their native operating system. Note
that if the file type code is only byte long (the usual case), the
high-order byte of "native file type code" is set to zero.

The "phantom file flag" byte indicates whether a receiver of the

Binary II file should save the file which follows (flag is zero) or
ignore it (flag is non-zero). It is anticipated that some
communications programs will use phantom files to pass non-essential
explanatory notes or encoded information which would be understood
only by a receiver using the same communications program. Such
programs must not rely on receiving a phantom file, however, since
this would mean they couldn't handle Binary II files created by other
communications programs.
The first two bytes in a phantom file *must* contain an ID code unique
to the communications program. Developers must obtain ID codes from
Gary Little to ensure uniqueness (see below for his address). Here is
a current list of approved ID codes for phantom files used by Apple II
communications programs:

$00 $00 = [generic]

$00 $01 = Point-to-Point
$00 $02 = Tele-Master Communications System

Developers of communications programs are responsible for defining and

publishing the structures of their phantom files.

The ID bytes appear in the first two bytes of the phantom file.
Phantom files having a generic ID code of zero must contain lines of
text terminated by a $00 byte. The text must begin at the third byte
in the file.

The "data flags" byte is a bit vector indicating whether the data
portion of the Binary II file has been compressed, encrypted, or
packed. If bit 7 (the high-order bit) is set to 1, the file is
compressed. If bit 6 is 1, the file is encrypted. If bit 0 is 1, the
file is a sparse file that is packed. A Binary II downloading program
can examine this byte and warn the user, when necessary, that the file
must be expanded, decrypted, or unpacked. The person uploading a
Binary II file may use any convenient method for compressing,
encrypting, or packing the file but is responsible for providing
instructions on how to restore the file to its original state.

This initial release of Binary II has a "Binary II version number" of

$00.

Handling Multiple Files

-----------------------
An appealing feature of Binary II is that a single Binary II file can
hold multiple disk files, making it easy to keep a group of related
files "glued" together when they're sent to a host.

The structure of a Binary II file containing multiple disk files is

what you might expect: it is a series of images of individual Binary
II files. For example, here is the general structure of a Binary II
file containing three disk files:

start end
-------------------------------------------------------------------
| Header #1 | #1 Data | Header #2 | #2 Data | Header #3 | #3 Data |
-------------------------------------------------------------------
+127 = 2 +127 = 1 +127 = 0

The data areas following each header end on a 128-byte boundary.

The "number of files to follow" byte (at offset 127) in the file
information header for each disk file contains the number of disk
files that follow it in the Binary II file. It will be zero in the
header for the last disk file in the group.

Filenames and Partial Pathnames

-------------------------------
Notice that you can put a standard ProDOS filename or a partial
pathname in the file information header (but never a complete
pathname). *Beware!* Don't use a partial pathname unless you've
included, earlier on in the Binary II file, file information headers
for each of the directories referred to in the partial pathname. Such
a header must have its "end of file position" bytes set to zero, and
no data blocks for the subdirectory file must follow it.

For example, if you want to send a file whose partial pathname is

HELP/GS/READ.ME, first send a file information header defining the
HELP/ subdirectory, then one defining the HELP/GS/ subdirectory. If
you don't, someone downloading the Binary II file won't be able to
convert it because the necessary subdirectories will not exist.

Filename Convention
-------------------
Whenever a file is sent to a host, the host asks the sender to provide
a name for it. If it's a Binary II file, the name provided should end
in .BNY so that its special form will be apparent to anyone viewing a
list of filenames.

Identifying Binary II Files

---------------------------
ose the ProDOS
file. You would repeat this for each file contained inside the Binary
II file.

Note: The number of 128-byte data blocks following the

file information header must be derived from the
"end-of-file position" attribute (EOF) not the "size
of file in blocks" attribute. Calculate the number
by dividing EOF by 128 and adding one to the result
if EOF is not 0 or an exact multiple of 128.

Exception: If the file information header defines a subdirectory (the

file type code is 15), simply CREATE the subdirectory file. Do not
OPEN it and do not set its size with SET_EOF.

Ideally, all this conversion work will be done automatically by a

communications program during an Xmodem (or other binary protocol)
download. If not, a separate conversion program will have to be run
after the Binary II file has been received and saved to disk. Gary
Little has published a public domain program, called BINARY.DWN, that
will do this for you. (A related program, BINARY.UP, combines multiple
ProDOS files into one Binary II file which can then be uploaded to a
host.)

DOS 3.3 Considerations

----------------------
With a little extra effort, you can also convert DOS 3.3 files to
Binary II form. This involves translating the DOS 3.3 file attributes
to the corresponding ProDOS attributes so that you can build a proper
file information header. Here is how to do this:

(1) Set the name to one that adheres to the stricter ProDOS naming
rules.

(2) Set the ProDOS file type code, auxiliary type code, and access
code to values which correspond to the DOS 3.3 file type:
 DOS 3.3 | ProDOS ProDOS ProDOS
file type | file type aux type access
-----------|----------- ---------- --------
$00 ( T) | $04 (TXT) $0000 $E3
$80 (*T) | $04 (TXT) $0000 $21
$01 ( I) | $FA (INT) $0C00 $E3
$81 (*I) | $FA (INT) $0C00 $21
$02 ( A) | $FC (BAS) $0801 $E3
$82 (*A) | $FC (BAS) $0801 $21
$04 ( B) | $06 (BIN) (*) $E3
$84 (*B) | $06 (BIN) (*) $21
$08 ( S) | $06 (BIN) $0000 $E3
$88 (*S) | $06 (BIN) $0000 $21
$10 ( R) | $FE (REL) $0000 $E3
$90 (*R) | $FE (REL) $0000 $21
$20 ( A) | $06 (BIN) $0000 $E3
$A0 (*A) | $06 (BIN) $0000 $21
$40 ( B) | $06 (BIN) $0000 $E3
$C0 (*B) | $06 (BIN) $0000 $21

(*) Set the aux type for a B file to the

value stored in the first two bytes
of the file (this is the default load
address).

(3) Set the storage type code to $01.

(4) Set the size of file in blocks, date of creation, date of

modification, time of creation, and time of modification to
$0000.

(5) Set the end-of-file position to the length of the DOS 3.3
file, in bytes. For a B file (code $04 or $84), this number is
stored in the third and fourth bytes of the file. For an I
file (code $01 or $81) or an A file (code $02 or $82), this
number is stored in the first and second bytes of the file.

(6) Set the operating system type to $01.

(7) Set the native file type code to the value of the DOS 3.3 file
type code.

Attribute bytes inside a DOS 3.3 file (if any) must *not* be included
in the data portion of the Binary II file. This includes the first
four bytes of a B (Binary) file, and the first two bytes of an A
(Applesoft) or I (Integer BASIC) file.

Acknowledgements
----------------
Thanks to Glen Bredon for suggesting that partial pathnames be allowed
in file information headers. Thanks also to Shawn Quick for suggesting
the "phantom file" byte, to Scott McMahan for suggesting the
compression and encryption bits in the "data flags" byte, and to
William Bond for suggesting the "disk space needed" bytes. Finally, a
big thank you to Neil Shapiro, Chief Sysop of MAUG, for supporting the
development of the Binary II format and helping it become a true
standard.
Feedback and Support
--------------------
Send any comments or questions concerning the Binary II file format
to:

Gary B. Little
#210 - 131 Water Street
Vancouver, British Columbia
Canada V6B 4M3
(604) 681-3371

CompuServe : 70135,1007
Delphi : GBL
MCI Mail : 658L6

Gary developed the Point-to-Point telecommunications program published

by Pinpoint Publishing. He has also written several books on how to
program Apple computers: "Inside the Apple IIe," "Inside the Apple
IIc," "Apple ProDOS: Advanced Features for Programmers," and "Mac
Assembly Language: A Guide for Programmers." He is currently a
Contributing Editor for A+ magazine and writes A+'s monthly Rescue
Squad column. Gary has also published articles in Nibble, Micro, Call
-A.P.P.L.E, and Softalk.