B Macintosh Binary Transfer Format ("MacBinary") Standard ProposalB ---------------------------------------------------------------- $ Dennis F. Brothers - 13 March 1985= (Revision 1 - 10 April 1985 - Miscellaneous clarifications)tH (Revision 2 - 12 April 1985 - Corrected reversal of icon position v,h)D (Revision 3 -  6 May   1985 - Added processor ID, general cleanup)    N The following notes are a proposal for a standard format for binary transferO of arbitrary Macintosh documents via a telecommunication link. It is intended	H for use both between Macintoshes running (possibly different) terminalK programs which adhere to the standard, and for use in uploading arbitrary O Macintosh documents to remote systems (where it is presumed that they will be P stored as an exact image of the data transmitted). A proposal is also made forO standard processing to be performed on text files transferred via a protocol, P to maximize the likelihood that text files transmitted to a remote system willM be usable by that system, and that text files received from a remote system-" will be usable by the Macintosh. M It is recommended that the format and procedures described here be referrediK to as "MacBinary", and that any terminal program implementing this formats2 and procedures be called "MacBinary-Compatible". O The binary format described is independent of the communication protocol usedpH to accomplish the transfer, and assumes only that an 8-bit transparentO transfer can be accomplished. Such protocols as Christensen (usually referredcO to as XMODEM or MODEM7), Kermit, and CompuServe A or B meet this requirement.aL Because of the proposed standard's MacTerminal/XMODEM heritage, there is aL requirement that the transmitted data be padded (with nulls) to a 128-byteN boundary at certain points, but this in no way implies that a block-orientedO protocol must be used. The basic format proposed is identical to that used bydP MacTerminal, by Mike Boich and Martin Haeberli, and can be used with a versionO of MacTerminal that has had a patch applied to "normalize" its implementationt of the XMODEM protocol.  N In brief, the binary format consists of a 128-byte header containing all theJ information necessary to reproduce the document's directory entry on theL receiving Macintosh; followed by the document's Data Fork (if it has one),N padded with nulls to a multiple of 128 bytes (if necessary); followed by theM document's Resource Fork (again, padded if necessary). The lengths of thesesK forks (either or both of which may be zero) are contained in the header. m P The format of the 128-byte header is as follows (offsets and lengths are given in decimal):   $         Offset   Length   Contents$         ------   ------   --------;         000      1        Zero. This is a "version" byte.i/         001      1        Length of filename.uK         002      63       Filename (only "length" bytes are significant).bC        (the following 16 bytes are a standard Finder Info record)f&         065      4        File type.)         069      4        File creator.t)         073      1        Finder flags:i2                                  Bit 7 - Locked.5                                  Bit 6 - Invisible.m2                                  Bit 5 - Bundle.2                                  Bit 4 - System.0                                  Bit 3 - Bozo.0                                  Bit 2 - Busy.3                                  Bit 1 - Changed.o2                                  Bit 0 - Inited.!         074      1        Zero. G         075      2        File's vertical position within its window.sI         077      2        File's horizontal position within its window. 7         079      2        File's window or folder ID.         (End of Finder Info)y@         081      1        "Protected" flag (in low order bit).!         082      1        Zero.eK         083      4        Data Fork length (bytes, zero if no Data Fork).rI         087      4        Resource Fork lenth (bytes, zero if no R.F.).61         091      4        File's creation date.18         095      4        File's "last modified" date.K         099      27       Zero fill (reserved for expansion of standard). @         126      2        Reserved for computer type and OS IDP                           (this field will be zero for the current Macintosh). I Note that it is the responsibility of the receiving terminal program to I resolve file name conflicts, generally by somehow modifying the name of.L received file if there already exists a file with the original name on the target volume. L Note also that, while the original window or folder ID and position may beP transmitted, the receiving terminal program would not normally set these itemsJ for the received file, but would instead accept the values that the File/ Manager assigns when it creates the new file.  I It is suggested that Macintosh terminal programs implement two modes of O protocol transfer: text and document. Text mode is used for unformatted files K of type TEXT (with only a data fork), and document mode (using the binarytN format proposed here) is used for all other files. Document mode may also beP used on text files, of course, if it is desired to preserve such things as the% file's creator ID or creation date.  N The intent of text mode is to provide compatibility with text files on otherO systems. Toward that end, it is recommended that a linefeed be inserted after N each return character as the text file is transmitted, and that, in the caseN of block-oriented protocols, the last block be explicitely padded with nullsL if the text does not end on a block boundary. When receiving in text mode,Q linefeeds and trailing nulls should be stripped. If a CTRL-Z (Hex 1A) characterwO is received following all other text (and before any null padding), it shouldhM also be stripped (Ctrl-Z is a common text terminator on CP/M and smoe othertQ systems). Note that the above discussion applies only to text files transferredtK under some protocol, where an exact image of the transmitted data will bet( stored in a file on the remote system. J When receiving a file via a protocol, a terminal program may distinguishO between text and document modes by examining bytes 0, 74, and 82 of the firstoM 128 bytes received. If they are each zero (and at least 128 bytes have beeniM received), then it is a safe assumption that a MacBinary-formatted documentiO is being received. Terminal programs implementing possible future versions of,N the proposed standard would, of course, accept an appropriate set of versionM numbers in byte 0. Note also that compatible extensions of Version 0 of the K proposed standard are possible (one such is suggested below) that involveeR transmission of additional information following the information described here.L For this reason, a terminal program should be implemented so as to performO the proper receive procedures for all data sent to it, but to ignore any data ( that it does not know what to do with. O Since a text-mode document does not contain a file name, it is suggested thatoH when text-mode is detected, a file be opened under a dummy name on theO receiving Macintosh, the text written to that file, and the file renamed to a I name selected by the user (via an SFPutFile box) after the reception is M completed. This will avoid problems caused by indeterminate delays for namey2 selection at the beginning of the file transfer. P It is desirable to allow the user to specify the destination volume in advanceN of the actual start of transfer for either type of transfer. Two methods areK suggested for this: provide a "Select Destination Volume" menu selection,eN presumably in the menu containing the "Receive File" selection; or query theM user immediately after the "Receive File" menu selection is made. Either or N both of these methods could be implemented in a given terminal program - theM independent "Select Receive Volume" method is particularly desirable if thetO ESC-a/ESC-b automatic receive facility (see below) is implemented. The volumesO selection procedure should provide the same functions as the volume selection 6 portion of the SFGetFile and SFPutFile dialog boxes.  4 First proposed extension to the proposed standard:4 -------------------------------------------------- P It is proposed that the binary format described above be extended to allow theO transmission of descriptive text with a Macintosh document (specifically, theoF descriptive text from the Finder's "Get Info" box for the file beingO transferred). This is to be accomplished in a transparent manner by assigning N bytes 99 and 100 of the header described above to be used to hold the lengthO of the descriptive text (or zero, if there is none). The descriptive text, ifeN any, will begin on the 128-boundary immediately following the Resource Fork,L if present, else the Data Fork, if present, else immediately following theM header if neither fork is present. It is hoped that methods for reading and E setting a file's "Get Info" text will be made public at some point.   I Notes on MacTerminal's XMODEM implementation, and a proposed extension:iI -----------------------------------------------------------------------r P Familiarity with the Christensen (XMODEM) protocol is assumed in the following
 discussion.  M When doing "Mac-to-Mac" transfers, using the binary format described above,vN unmodified MacTerminal does not use a true XMODEM protocol, and is thereforeO incompatible with most non-Mac systems. The differences lie in two specifics:pJ the transmitting Macintosh initiates the transfer by sending the the twoI characters ESCAPE (hex 1B) and "a" (hex 61); the receiving Macintosh is O expected to reply with the character ACK (hex 06). The transfer then proceeds1L using normal XMODEM procedures, except that each of the header and the twoG forks (if present) is treated as a separate XMODEM transfer, with the O transmitting Macintosh waiting for a NAK (hex 15), then sending the blocks ofeN that phase (beginning with a block number of one), then sending EOT (hex 04)? and waiting for an ACK (hex 06) from the receiving Macintosh.- K It is proposed that a modified procedure be accepted as a standard, to be J implemented instead of or in addition to the above-described MacTerminalO "Mac-to-Mac" protocol in complying terminal programs. The modified procedure,dH which is compatible with standard XMODEM implementations, functions asN follows: The transmitting Macintosh sends the two characters ESCAPE (hex 1B)N and "b" (hex 62). The receiving Macintosh may optionally reply with ACK (hex? 06) (this is allowed so as to have minimum impact on existingrJ MacTerminal-compatible implementations). The transmitting Macintosh thenH awaits receipt of a NAK (hex 15) (or optionally a "C" (hex 43), if theN receiving terminal program supports CRC checking), following which a single,M normal XMODEM transfer occurs. The transfer may be in text mode or document,J mode, will begin with block number one, and block numbers will increment1 uniformly (modulo 256) throughout the transfer.  P It is expected that a patch to MacTerminal making it compatible with the above: proposed procedure will be available in the near future.   Responses to proposals:e -----------------------M A Please address comments or questions on the above proposals to:u          Dennis F. Brothers"         197 Old Connecticut Path         Wayland, MA 01778s         617-358-2863          CompuServe: 70065,172         Delphi:     DBROTHERSa         MCI Mail:   DBROTHERS     MacBinary Working Group: ------------------------ P An informal working group, consisting of Macintosh terminal program developersQ and others with interests or expertise in the field of computer communications, N was formed during April, 1985 to discuss and refine this proposal. The groupP met in the MAUG (Micro-networked Apple User's Group) Special Interest Group onN the CompuServe Information Service. The present form of the MacBinary formatO standard represents a consensus of this group as a whole, but may not reflectl8 the opinion of a given individual member of the group.  The working group included:r    Christopher Allen    William Bond-    Steve Brecher    Dennis Brothers    Ward Christensens    Dan Cochran    Mike Cohen    Bill Cook
    Ed Edell     Duane Harrisc    Yves Lempereur     Neil Shapiro     Dan Smith    Bill Steinberg     Scott Watson7