Carousel Volume 2 #1/carousel.iso/mactosh/tech/report_a.txt

Text File | 1987-09-05 | 14KB | 317 lines

24-Aug-87 13:38:41-PDT,14289;000000000001
Return-Path: <[e-mail]>
Received: from sdcsvax.UCSD.EDU by SUMEX-AIM.STANFORD.EDU with TCP; Mon, 24 Aug 87 13:37:48 PDT
Received: by sdcsvax.UCSD.EDU (5.57/5.0)
    id AA13723 for [e-mail]; Mon, 24 Aug 87 12:35:53 PST
To: comp-sys-mac-digest
Path: sdcsvax!jww
From: [e-mail] (Joel West)
Newsgroups: comp.sys.mac.digest
Subject: Remote Macintosh file representation
Message-Id: <[e-mail]>
Date: 24 Aug 87 20:35:51 GMT
Organization: Palomar Software, Inc., Vista, CA
Lines: 300


For those of you who don't normally follow the INFO-APPLETALK newsgroup,
Apple has made an important proposal that affects all Macintosh programs
in hetereogeneous computing environments.  A copy of the proposal
is being included for the INFO-MAC archives.

Apple proposes two file formats, AppleSingle and AppleDouble, which
represent a file on another file system (e.g. UNIX or MS-DOS) as
either one file, or two files, respectively.  In the two-file mode,
the data fork is in a separate file that should be locally readable.

Further comments should be sent to [e-mail].
If you want to be added to the mailing list, of course, send
mail to [e-mail].

    Joel West
    Palomar Software, Inc., P.O. Box 2635, Vista, CA  92083
    ihnp4!crash!palomar!joel    [e-mail]

(Dwayne: you might archive this as APPLEDOUBLE.TXT)


From [e-mail] Sat Aug 22 15:36:51 1987
Path: sdcsvax!ames!aurora!labrea!decwrl!nsc!voder!apple!andrews
From: [e-mail] (Richard Andrews)
Newsgroups: comp.protocols.appletalk
Subject: Mac File Representation
Message-ID: <[e-mail]>
Date: 22 Aug 87 22:36:51 GMT
Reply-To: [e-mail] (Richard Andrews)
Distribution: usa
Organization: Apple Computer Inc., Cupertino, USA
Lines: 265


Here is our first attempt at a proposal for representing Mac files
on other file systems.  Please circulate it freely.  I welcome
comments and suggestions, with the following caveat:

PLEASE KEEP YOUR COMMENTS BRIEF AND CONCISE.  I EXPECT A LOT OF
FEEDBACK AND I CAN'T POSSIBLY WADE THROUGH A WHOLE LOT OF MATERIAL.
I CANNOT REPLY TO EVERYONE PERSONALLY.

Please send useful comments and suggestions directly to me.  Look to
this bulletin board for further drafts.

--------------------------------------------------------------------



AppleSingle and AppleDouble formats for file representation



A Draft Proposal from Apple Computer, Inc.

21 August, 1987



Apple Computer is proposing two standards for representing
Macintosh files on non-Macintosh file systems, with the goal of
preserving all attributes characteristic of Macintosh files
(Finder info, icons, comments) on file systems that do not
support such attributes ("foriegn" file systems).  Experience
seemed to indicate that a single format could not be devised that
would be adequate for all cases, but that with two
closely-related formats most needs could be served.  A secondary
goal in designing these formats was to make them general enough
so that they could be used to represent a file from any file
system on any other file system.

Note that this is a draft and is subject to change.

The two formats are called AppleSingle and AppleDouble.  In
AppleSingle format, all contents and attributes of a Macintosh
file are kept in a single file on the foriegn file system.  Both
forks, Finder info, icons, etc. are arranged in a single file
with a simple structure.  This format is intended to be used
primarily as a storage format; i.e., for those cases in which the
Macintosh file must be stored on a foriegn file system and later
reconstructed into a true Macintosh file.

For those applications in which the users of the foriegn file
system wish to access and perhaps modify the contents of the
Macintosh file, AppleDouble format would be more appropriate.
Since most Macintosh applications keep the file "data" in the
data fork, AppleDouble format saves the contents of the data fork
in a separate foriegn file.  All other file attributes are kept
in another file.

Specifically, Apple's proposal does not rule out the possibility
of building applications that wish to access and modify
MacSingle-format files.  Nor does it preclude using AppleDouble
format for simple storage of Macintosh files.  We merely present
them as alternatives.

The only assumption we have made is that each file system on
which these file formats will be supported allows the creation of
a simple file; an uninterpreted stream of bytes.  We have ruled
out designing a format that relied on the creation of
subdirectories, since some file systems do not support them.

Before getting into the discussion of the formats, some terms
will be defined.  The term home file system will be used to
mean the file system for which the file's contents were created.
A Unix application could create an AppleSingle file that holds a
resource and data fork in which is contained a MacWrite-formatted
document.  The home file system for such a file will be Macintosh
Hierarchical File System (HFS).  In most cases, where a file is
created and used on the same file system, the home file system
will be that system.  An AppleSingle or AppleDouble file is
usually another representation of the file's contents on a
foriegn file system.


AppleSingle

An AppleSingle file contains a header followed by data.  The
header is composed of several fixed fields and a list of entry
descriptors, each pointing to an "entry".  Standard entries that
Apple will define include:  Data Fork, Resource Fork, Real Name
(name in the home file system), Comment, Icon, File Info, etc.
Each entry would be optional and may or may not appear in the
file.

   Header:             Magic Number      (4 bytes)
                       Version Number    (2 bytes)
                       Home File System  (4 bytes, ASCII encoded)
                       Number of entries (2 bytes)
                   /   Entry ID          (2 bytes)
   for each entry: |   Offset            (4 bytes)
                   \   Length            (4 bytes)

The "Magic Number" field is modeled after the feature in Unix.
It is intended to be used in whatever way each foriegn file
system desires to distinguish this file as one in AppleSingle
format.  The Magic Number for AppleSingle format is $00051600 or
0x00051600.

The "Version Number" field is used to denote the version of
AppleSingle format in case the format evolves (perhaps more
fields would be added to the header).  The version described here
is version $0001 or 0x1.

The "Home File System" is explained above.  For Macintosh files,
the value of this field is 'mac ' or $6D616320 or 6D616320.
Others are shown below:

     Macintosh    'mac ' or $6D616320 or 0x6D616320
     ProDOS       'pdos' or $70646F73 or 0x70646F73
     MS-DOS       'mdos' or $6D646F73 or 0x6D646F73.
     Unix         'unix' or $756E6978 or 0x756E6978.

We welcome suggestions for other file systems that should be
included in this list.

The "Number of entries" field tells how many different entries
are included in the file.  It is an unsigned 16-bit number, and
may be zero.  If non-zero, then that number of entry descriptors
will immediately follow this field.

For each entry, the entry descriptor indicates just what the
entry is, where the entry is located in the file, and how big the
entry is.  Apple will define a set of Entry IDs and their values:

     Data Fork      1 (standard Mac Data Fork)
     Resource Fork  2 (standard Mac Resource Fork)
     Real Name      3 (the file's name in the home file system)
     Comment        4 (standard Mac comment)
     Icon, B&W      5 (standard Mac Black & White Icon)
     Icon, Color    6 (standard Mac color icon)
     File Info      7 (file information)
     Dates          8 (Create, Modification, and Backup dates)

Apple reserves the range of Entry IDs from 0 to 32767 ($7FFF or
0x7FFF) for future use.  Apple will not arbitrate the use of the
rest of the range; these values can be used by other systems to
define their own types of entries.

The File Info entry will be different for each home file system.
For Macintosh HFS, the entry is 32 bytes long and consists of the
standard Finder Info and Extended Finder Info fields.  [To be
defined:  formats for MS-DOS, Unix, and ProDOS, etc.]

Icon entries will probably not appear in most files since they
are typically stored as a bundle in the application file's
resource fork.

The actual data representing the entry must be in a single
contiguous block.  It is pointed to by the offset field, which is
an unsigned 32-bit number indicating the byte offset from the
start of the file to the start of the entry.  The entry length is
also an unsigned 32-bit number representing the length in bytes.
The length may be zero.

After some number of entry descriptors, the actual entry data
would appear.  The entries could appear in any order, but since
the data fork is the entry that would be most commonly extended,
Apple strongly recommends that the data fork entry always be kept
last in the file to facilitate its extension.

It is possible to have holes in the file (unused space between
entries).  To find where the holes are, one must take the list of
entry descriptors and sort them into increasing offset order.  If
the offset field of an entry is greater that the offset plus
length of the previous entry, then a hole exists between the
entries.  This may be used to one's advantage; for example:  if a
file's comment is 10 bytes long, one could create a hole of 190
bytes after the comment field to easily allow for the comment to
later expand to its maximum length of 200 bytes.  Because an
AppleSingle file may contain holes, every entry must be found by
getting its offset from its entry descriptor - not by assuming
that it begins after the previous entry.

Byte ordering in the file will follow 68xxx convention.  This is
somewhat of a religious issue, but it was decided that picking
one format was better than adding a flag to the file to indicate
which ordering was being used, so that applications wouldn't have
to have code to handle both cases.


AppleDouble

AppleDouble format is now easily described:  it is the same as
AppleSingle format except that the data fork is kept in a
separate foriegn file.  The file containing the data fork will be
called the AppleDouble Data File, and the other file will be
called the AppleDouble Header File.

The AppleDouble Data File consists of just the standard Macintosh
Data Fork with no extra header at all.  The AppleDouble Header
File has exactly the same format as the AppleSingle file, except
that it does not contain a data fork entry.  The Magic Number of
an AppleDouble Header File differs from that of an AppleSingle
file so that applications can tell whether or not they need to
look elsewhere for the data fork.  The Magic Number for
AppleDouble format is $00051607 or 0x00051607.

The entries in the Header File could appear in any order, but
since the resource fork (in this case) is the entry that would be
most commonly extended, Apple strongly recommends that the
resource fork entry always be kept last in the file to facilitate
its extension.  The data fork is easily extended since it resides
by itself in the Data File.

If it is possible on the foriegn file system, one could create a
new type of entry that "pointed" to the AppleDouble Data File to
make it easy to find.

-----------------------

AppleSingle format specifically will not include an algorithm for
generating the AppleSingle file name from the "real" Macintosh
name.  This was done because the foriegn file systems of interest
differ quite a bit in the area of file name syntax, and since the
file's real name can be kept as an entry within the AppleSingle
file.

The same is true for AppleDouble Data File names, yet we would
like to propose a standard for deriving the AppleDouble Header
File name from the AppleDouble Data File name.  Again, due to
differing file name syntax, a standard per foriegn file system is
proposed.  For example:

   On Unix systems, take the file's real name and by character
   substitution, deletion, or truncation, derive an AppleDouble
   Data File name that is at least one character less than the
   maximum file name length.  The AppleDouble Header File name
   will be the same as the AppleDouble Data File name with a
   preceding percent sign '%'.

   On ProDOS systems, take the file's real name and by character
   substitution, deletion, or truncation, derive an AppleDouble
   Data File name that is at least two characters less than the
   maximum file name length.  The AppleDouble Header File name
   will be the same as the AppleDouble Data File name with a
   preceding 'R.' (ASCII-R, period).

   On MS-DOS systems, take the file's real name and by character
   substitution, deletion, or truncation, derive a name that is
   at most eight characters long.  The AppleDouble Header File
   name will be the derived name plus an extension of '.ADF'
   (AppleDouble File).  The AppleDouble Data File name will be
   the derived name plus whatever extension is most appropriate
   in the MS-DOS world.  If the data fork is pure text (CR, LF)
   the the Data File extension would be '.TXT'.  If the data fork
   conformed to some other standard MS-DOS file format, it would
   be given the appropriate extension.  This would have to be
   decided by whatever application created the AppleDouble files.

And so on.  AppleDouble name derivations, to coin a term, would
be defined for all the file systems of interest.  This would
allow applications running on the foriegn file system (and human
users as well) to easily see which files are AppleDouble pairs.
Knowledgeable users, if they know the derivation, could even
rename the files in such a way so as to preserve the connection
between the two.  There is no way to prevent one file of the pair
from being inconsistently renamed, moved or deleted.