------------------------------------------------------------------------------- | The New Archive Standard for the Apple II -- "NuFX" -- NuFile eXchange | ------------------------------------------------------------------------------- NuFX Documentation - 12/2/88 by Andy Nicholas Final Revision Three - 2/3/89 Please distribute as widely as possible Send questions/comments to: Paper Bag Productions CSNET: nicholaA@moravian.edu c/o Andy Nicholas InterNET: nicholaA%batman.moravian.edu@relay.cs.net Box 435 nicholaA@batman.moravian.edu.csnet Moravian College ProLine: andyn@pro-sol.cts.com [619-670-5379] Bethlehem, PA 18018 AppleLink PE: ShrinkIt NuFX Documentation 2/3/89 - Page 2 - Preface ------- The first copy of this proposal that was circulated was preliminary revision 10. Since then I have had many requests for a more flexible solution to the archival problem. To do so meant the removal of such features as the alignment to 128-byte boundaries of all data blocks and so forth, and the re-definition of the header block so that it is less rigid in its format (extensible). To do this makes it at least a factor more complex for programs which can extract records from NuFX archives on-the-fly (such as telecommunications programs). While this may be seen as a hardship by some, I believe the additional power provided by all formats after revision 10 justifies the additional complexity. Standalone utility programs should have no problems adjusting to the new format. This final revision of the documentation fixes the master_header's size at 48 bytes, eliminates the archive_create_program and archive_mod_program fields, increases the size of the access field to a longword, and introduces a new name for the archive, NFX, or NuFX, for "NuFile eXchange." I am also almost finished an archive program which places files or disks into NuFX archives using dynamic LZW compression, ShrinkIt. Any reference to ShrinkIt in the text is a reference to this program. Final Rev 2 corrects the all the algorithms to include the length of the thread list in their calculations, includes some notes on how to properly include threads and directories, and standardizes on the use of "NuFX" to describe the archive name so as to distinguish it from Sun Microsystems' "NFS" network product. Final Rev 3 changes some of the terminology used, changes the date labels to xx_when instead of xxx_date_time, assigns the resource_fork of a file to be stored as a thread_kind in a data_thread instead of having it's own thread available. An attempt at further clarity has been undertaken. andy (2/3/89) NuFX Documentation 2/3/89 - Page 3 - History ------- The Apple II community has always been sorely lacking a well-defined method for archiving files. NuFX is an attempt to rectify the situation by providing for a flexible, consistent standard for archiving files, disks, and other computer medium. The Binary II standard, authored by Gary B. Little, for placing multiple files within a single file has been rendered obsolete by the (now) recent release of GS/OS(tm) which provides access to multiple filing systems. Since GS/OS can (or will) use HFS files, Binary II does NOT provide for: o filenames larger than 64 characters (GS/OS can create 8000 character filenames) o a convenient way to add to, remove from, and other ways work on an archive. o including HFS-style files which contain resource forks. o including of entire disk images. o including messages along with a file. o a convenient way to represent that a file is compressed or encrypted by a specific application. (an excess secondary header must be attached to the beginning of files, such is the case with SQueezed files) o a true archive standard. Binary II's original intent was to make transfer of Apple II files from local machines to large information services like The Source, Delphi, CompuServe, and GEnie, possible. Otherwise, a file's attribute information would be lost. Binary II is now being stretched beyond what it was originally meant to do. o no support for multiple data threads or structures. Adding all of these features to the existing Binary II standard would not only be nerve-racking, but nearly impossible without violating the existing standard and causing a great deal of confusion (ie, "did you say it was Binary II, first revision or the second one?") Although Binary II is flexible, it is simply unable to address all of these concerns without alienating existing Binary II extraction programs. So, to provide some differentiation between standards and provide a better functioning format, I have defined a new standard called "NuFX" (NuFile eXchange for the Apple II). NuFX fixes the problems that Apple IIgs(tm) users would soon be experiencing as other filing systems become available for GS/OS(tm). I am trying to stop a set of problems before they have a chance to develop. NuFX provides all of the features of Binary II, but doesn't stop there... it goes farther to allow the user the ultimate in flexibility, usefulness and performance. NuFX Documentation 2/3/89 - Page 4 - Implementation -------------- The basic structure of a NuFX archive is as follows: [First record] [Next Record] +---------------------------------------------------------------------------+ | Master Header | Header | Data . . . . . . . . | Header | Data . . . . | +---------------------------------------------------------------------------+ A single master header block contains values which describe the entire archive (those of you who are into structured programming can consider them archive globals). Each of the succeeding header blocks contain only information about the record they precede (consider them archive locals). Each header block may be followed by a series of "threads." Each thread may be a portion of data, a message, the resource part of an extended file, a control sequence for a NuFX utility program, or almost any sort of sequential data. The number of threads is described as a longword (32-bit word), so it is also possible to properly archive and store the data portions of sparse files. NuFX Documentation 2/3/89 - Page 5 - Master header block contents: All word and double-word values are byte-reversed. Offset Length Content ------ ------ --------------------------------------------------------------- +0 1 $4E Master ID Byte #1 +1 1 $F5 Master ID Byte #2 +2 1 $46 Master ID Byte #3 spells the word "NuFile" in +3 1 $E9 Master ID Byte #4 alternating ASCII (high, low) for +4 1 $6C Master ID Byte #5 uniqueness. +5 1 $E5 Master ID Byte #6 +6 2 master_crc 16-bit CRC of the remaining fields in this block. (bytes +8 through +47) Any programs which modify the master header block *MUST* recalculate the CRC for the master header. +8 4 total_records Total number of records in this archive file. It is possible to chain multiple records (Files or Disks) together. It is also possible to chain different types of records together (Files and Disks mixed). NuFX Documentation 2/3/89 - Page 6 - +12 8 archive_create_when The date and time on which this archive was initially created. This field should never be changed once initially written. The format of this field is as follows: +12 second - 0 through 59 +13 minute - 0 through 59 +14 hour - 0 through 23 +15 current Year minus 1900 +16 day - 0 through 30 +17 month - 0 through 11, with 0=January +18 filler byte - reserved must be null (00). +19 weekDay - 1 through 7, with 1=Sunday The format of this field is identical to that described in the _ReadTimeHex ($0D03) call described on page 14-14 of the Apple_IIgs_Toolbox_Reference:_Volume_1. If the date is not known, or is unable to be calculated, this field should be set to null (00). If the weekDay is not known, or is unable to be calculated, this field should be set to null (00). +20 8 archive_mod_when The date of the last modification to this archive. This field should be changed every time a change is made to any of the records in the archive. The format of this field is as follows: +20 second - 0 through 59 +21 minute - 0 through 59 +22 hour - 0 through 23 +23 current Year minus 1900 +24 day - 0 through 30 +25 month - 0 through 11, with 0=January +26 filler byte - reserved, must be null (00). +27 weekDay - 1 through 7, with 1=Sunday The format of this field is identical to that described in the _ReadTimeHex ($0D03) call described on page 14-14 of the Apple_IIgs_Toolbox_Reference:_Volume_1. If the date is not known, or is unable to be calculated, this field should be set to null (00). If the weekDay is not known, or is unable to be calculated, this field should be set to null (00). NuFX Documentation 2/3/89 - Page 7 - +28 . . *** RESERVED, MUST BE SET TO NULL (00) *** . Do NOT use any of these fields. . +47 NuFX Documentation 2/3/89 - Page 8 - The following header block must precede each record within the NuFX archive. The cyclic redundancy check (CRC) has been provided to detect archives which have possibly been corrupted. The only time the CRC should be included in in a block is for the master header and for each of the regular header blocks. The CRC functions to ensure reliability and record integrity. Header Block contents: All word and double-word values are byte-reversed. Offset Length Content ------ ------ --------------------------------------------------------------- +0 1 $4E - Header ID Byte #1 +1 1 $F5 - Header ID Byte #2 Spells "NuFX" in alternating ascii +2 1 $46 - Header ID Byte #3 (high/low) for uniqueness. +3 1 $D8 - Header ID Byte #4 +4 2 header_crc 16-bit CRC of the remaining fields of this block. (bytes 6 through the end of the attributes, filename, and any threads.) This field is used to verify the integrity of the rest of the block. Programs which make NuFX archives *MUST* include this in every header. It is up to the discretion of the extracting program to check the validity of these bytes. Any programs which might modify the header of a particular record *MUST* recalculate the CRC for the header block. +6 2 attrib_count This field describes the length of the attribute section of each header in bytes. This count measures the distance in bytes from the first field (offset +0) to and including the filename_length field. By convention, the filename_length field will always be the last 2 bytes of the attribute section regardless of what has preceded it. NuFX Documentation 2/3/89 - Page 9 - +8 2 version_number Minimum NuFX version number needed for extraction. (Currently $0000) This field is used to detect the possible existence of other as-of-yet undefined fields and features. Utility programs should check this value to be certain that they are capable of extracting a record with this minimum version. +10 4 total_threads The number of thread sub-records which should be expected immediately following the end of the file/path name. This field is extremely important because it contains the information about the length of the last 1/3 of the header. +14 2 file_sys_id Native file system identifier: $0000 reserved $0001 ProDOS/SOS $0002 DOS 3.3 $0003 DOS 3.2 $0004 Apple II Pascal $0005 Macintosh(tm) (HFS) $0006 Macintosh (MFS) $0007 LISA(tm) file system $0008 Apple CP/M $0009 reserved, do not use $000A MS-DOS $000B High-Sierra/ISO 9660 $000C . . reserved . $FFFF Disk: if the file system of a disk is not known, then this field should be set to null (0000). NuFX Documentation 2/3/89 - Page 10 - +16 2 file_sys_info Information about the current filing system: [$00xx] Native file system separator. Under Prodos, the "/" ($2F) character is used to separate paths. Under HFS, the ":" ($3A) character is used to separate paths. Under MS-DOS, the "\" ($5C) character is used to separate paths. The low byte of this word is used to store the file system's separator. The primary reason for including this field is that the receiving file system (say, to Prodos 8 from GS/OS running an HFS File System Translator) must know how to parse a valid file/path name from the filename field for the receiving file system. [$xx00] Sparse byte. If the high-byte of this word is $01, then the image which follows is a sparse file (and the threads should have been filled in properly to indicate this). If a more "normal" image follows, this byte will be null (00). NuFX Documentation 2/3/89 - Page 11 - +18 4 access [0000 0000 0000 0000 DRB00IWR] bits 31-8 reserved, must be zero bit 7 D=0, destroy disabled D=1, destroy enabled bit 6 R=0, rename disabled R=1, rename enabled bit 5 B=0, backup not needed B=1, backup needed bits 4-3 reserved, must be zero bit 2 I=0, file is visible I=1, file is invisible bit 1 W=0, write disabled W=1, write enabled bit 0 R=0, read disabled R=1, read enabled Disk: this field should be set to null (00). +22 4 file_type Disk: this field should be set to null (00). +26 4 extra_type ProDOS aux_type or HFS creator_type Disk: this field *MUST* be set to the total number of blocks on the device. This information must be present so that the extracting program can place the record on the proper type of device. +30 2 storage_type $0 - $3 = standard file $5 = extended (gs/os) file $d = subdirectory Disk: file_sys_block_size This should only be used if a disk is being archived. The block size used by the device should be placed in this field. For example, under Prodos, this field will be 512, while HFS would set it to 524. NuFX Documentation 2/3/89 - Page 12 - +32 8 create_when The date and time on which this record was initially created. If the creation date and time is available from a disk device, this information should be included. The format of this field is as follows: +32 second - 0 through 59 +33 minute - 0 through 59 +34 hour - 0 through 23 +35 current Year minus 1900 +36 day - 0 through 30 +37 month - 0 through 11, with 0=January +38 filler byte - reserved, must be set to null (00). +39 weekDay - 1 through 7, with 1=Sunday The format of this field is identical to that described in the _ReadTimeHex ($0D03) call described on page 14-14 of the Apple_IIgs_Toolbox_Reference:_Volume_1. If the date is not known, or is unable to be calculated, this field should be set to null (00). If the weekDay is not known, or is unable to be calculated, this field should be set to null (00). +40 8 mod_when The date and time on which this record was last modified. If the modification date is available from a disk device, this information should be included. The format of this field is as follows: +40 second - 0 through 59 +41 minute - 0 through 59 +42 hour - 0 through 23 +43 current Year minus 1900 +44 day - 0 through 30 +45 month - 0 through 11, with 0=January +46 filler byte - reserved, must be set to null (00). +47 weekDay - 1 through 7, with 1=Sunday The format of this field is identical to that described in the _ReadTimeHex ($0D03) call described on page 14-14 of the Apple_IIgs_Toolbox_Reference:_Volume_1. If the date is not known, or is unable to be calculated, this field should be set to null (00). If the weekDay is not known, or is unable to be calculated, this field should be set to null (00). NuFX Documentation 2/3/89 - Page 13 - +48 8 archive_when The date and time on which this record was placed in this archive. The format of this field is as follows: +48 second - 0 through 59 +49 minute - 0 through 59 +50 hour - 0 through 23 +51 current Year minus 1900 +52 day - 0 through 30 +53 month - 0 through 11, with 0=January +54 filler byte - reserved, must be set to null (00). +55 weekDay - 1 through 7, with 1=Sunday The format of this field is identical to that described in the _ReadTimeHex ($0D03) call described on page 14-14 of the Apple_IIgs_Toolbox_Reference:_Volume_1. If the date is not known, or is unable to be calculated, this field should be set to null (00). If the weekDay is not known, or is unable to be calculated, this field should be set to null (00). Any other attributes which are needed may be added at the discretion of the NuFX application programmer. The attrib_count field should be modified accordingly. NuFX Documentation 2/3/89 - Page 14 - attrib_count-2 filename_length (xx bytes) Length of filename. Under Prodos, this will not exceed 64 characters. If HFS or another filing system is used, this field may exceed 64 characters. This is the last field considered included in the attributes section. To allow the inclusion of future additional parameters in the attributes section, NuFX utility programs should rely on the attribs_count field to find the filename_length field. ------------------------- End of attributes section xx Bytes Filename or partial pathname if applicable. If this is a disk which is being archived, then the volume_name should be included in this field. If a volume name is included in this field, a separator ("/" or ":") should *NOT* be included in, or precede the name. If a volume name is not available, then this field should be set to nulls. (00's) If a partial pathname is specified, the directories to which the current pathname refers need not have preceded this particular record. The extraction program must test each referenced directory individually. If the directory in question does not exist, the extracting program should create it. Any utility which extracts files from a NuFX archive *MUST NOT* assume that this field will be in a format it is able to handle. In particular, extraction programs should check for mixed case text in a file/path name and do whatever conversions are necessary to parse a legal file/path name. In general, assume nothing. ----------------------- End of filename section NuFX Documentation 2/3/89 - Page 15 - Threads ------- Thread records are 16 byte records which immediately follow the filename and describe the types of data structures which are included with a given record. The number of thread records is described in the attribute section by a longword, total_threads. Each thread record should be checked for the type of information that a given utility program can extract. If a utility is incapable of extracting a particular thread, that thread should be skipped. If a utility finds a redundancy in a thread_record, it must decide whether to skip the record or to do something with that particular thread (ie, if a utility finds 2 message_threads it can either ignore the second thread or display it. Likewise, if a utility finds 2 resource threads, it can either overwrite the first thread which was extracted, or warn the user and skip the errant thread). A thread record can be represented as follows: Offset Length Content ------ ------ --------------------------------------------------------------- +0 2 thread_class +2 2 thread_format +4 2 thread_kind +6 2 reserved +8 4 thread_eof +12 4 comp_thread_eof "thread_class" describes the classification of the thread --------------------------------------------------------- $0000 = message_thread $0001 = control_thread $0002 = data_thread $0003 = sparse_thread NuFX Documentation 2/3/89 - Page 16 - "thread_format" is the format of the data within the thread. ------------------------------------------------------------ $0000 = Uncompressed [Not application specific] $0001 = SQueezed (SQ/USQ) [Not application specific] $0002 = Dynamic LZW [ShrinkIt] $0003 . . RESERVED, contact the author . $FFFF "thread_kind" describes the kind of data which is contained in the thread ------------------------------------------------------------------------- if thread_class $0000 = message_thread thread_kind $0000 = ASCII text $xxxx = all others undefined $0001 = control_thread thread_kind $0000 = create directory $xxxx = all others undefined $0002 = data_thread thread_kind $0000 = data_fork of file thread_kind $0001 = disk image thread_kind $0002 = resource_fork of file $xxxx = all others undefined "thread_eof" is the length of the uncompressed thread ----------------------------------------------------- "comp_thread_eof" is the length of the compressed thread -------------------------------------------------------- Current ideas for messages include static pictures, sounds, sound & pictures, animations, and possibly executable files. I encourage writers of NuFX utility programs to be able to handle messages of the lowest common denominator, ASCII text. NuFX Documentation 2/3/89 - Page 17 - Finding the start of the thread list ------------------------------------ The beginning of the thread records can be found by using the following algorithm: Threads := (mark at beginning of header) + (attrib_count) + (filename_length) Finding the end of the thread list ---------------------------------- The end of the thread records can be found by applying the following algorithm: endOfThreads := (mark at beginning of header) + (attrib_count) + (filename_length) + (16 * total_threads) Finding the start of a data_thread ---------------------------------- The beginning of a data_thread can be found using the following algorithm: Data Mark := (mark at beginning of header) + (attrib_count) + (filename_length) + (16 * total_threads) + (comp_thread_eof of all threads in the thread list which are not data prior to finding a data_thread) Finding the start of a resource_thread -------------------------------------- The beginning of a resource_thread can be found using the following algorithm: Resource Mark := (mark at beginning of header) + (attrib_count) + (filename_length) + (16 * total_threads) + (comp_thread_eof of all the threads in the thread list which are not resources prior to finding a resource_thread) Finding the next record ----------------------- The next record can be found using the following algorithm: Next Mark := (mark at beginning of header) + (attrib_count) + (filename_length) + (16 * total_threads) + (comp_thread_eof of each thread) NuFX Documentation 2/3/89 - Page 18 - Misc notes on threads --------------------- There must *ALWAYS* be at least 1 thread attached to each record, whether the thread has any physical length or not. Phantom files and directories will have both the thread_eof and comp_thread_eof fields set to null (00). If a control_thread indicates that a directory should be created on the destination device, the path to be created must take the form of a prodos partial pathname. That is, the path must *NOT* be preceded with a volume name. ie, /STUFF/SUBDIR is an invalid path, while SUBDIR/ANOTHERSUB is a legal path. If a control_thread indicates that a directory is to be created, *ALL* the subdirectories that are contained in the pathname must be created. Control_threads will be eventually used to control the execution of utility programs by allowing for directory creation, renaming, deleting, moving, or modifying files. A form of scripting language will eventually be available to allow utility programs to perform these actions automatically. Control_threads will allow extraction programs to perform operations akin to Apple's GS/OS installer program, allowing updates to program sets dependent upon such things as date of creation or modification, version number, etc. NuFX Documentation 2/3/89 - Page 19 - Normal Files ------------ Normal Prodos files (sub_types $01,$02,$03) should be handled in the following manner: the data portion of the file will occupy the first data_thread. Sample header block for a normal file record: 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F +-------------------------------------------------+ created 01:10:00 00 | 4E F5 46 D8 55 34 3A 00 00 00 01 00 00 00 01 00 | 10/22/88 10 | 2f 00 00 00 c3 00 04 00 00 00 00 00 00 00 01 00 | saturday 20 | 00 0a 01 58 16 0a 00 07 00 10 0b 58 11 0b 00 05 | 30 | 00 0c 01 28 16 0a 00 07 05 00 53 54 55 46 46 02 | last mod 11:16:00 40 | 00 02 00 00 00 00 00 00 20 00 00 00 10 00 00 | 11/17/88 +-------------------------------------------------+ thursday archived 01:12:00 header_id = "NuFX" 10/22/88 header_crc = $3455 saturday attrib_count = $003A (58 bytes in attrib section) version = $0000 total_threads = $00000001 file_sys_id = $0001 (Prodos) file_sys_info = $002f (not sparse, / = separator) access = $000000C3 (full access, not invis) filetype = $00000004 (Prodos BIN) aux_type = $00000000 storage_type = $0001 (Prodos sapling file) create_when = 00 0a 01 58 16 0a 00 07 mod_when = 00 10 0b 58 11 0b 00 05 archive_when = 00 0c 01 58 16 0a 00 07 filename_length = $0005 filename = "STUFF" thread_class = $0002 (data_thread) thread_format = $0002 (compressed with ShrinkIt) thread_kind = $0000 (file) reserved = $0000 thread_eof = $00002000 comp_thread_eof = $00001000 (file is 50% of original size) NuFX Documentation 2/3/89 - Page 20 - Extended Files -------------- Sample header block for an extended file record: 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F +-------------------------------------------------+ created 01:10:00 00 | 4E F5 46 D8 65 78 3A 00 00 00 02 00 00 00 01 00 | 10/22/88 10 | 2f 00 00 00 c3 00 b3 00 00 00 00 00 00 00 05 00 | saturday 20 | 00 0a 01 58 16 0a 00 07 00 10 0b 58 11 0b 00 05 | 30 | 00 0c 01 58 16 0a 00 07 09 00 45 58 54 2e 53 54 | last mod 11:16:00 40 | 55 46 46 02 00 02 00 00 00 00 00 00 20 00 00 00 | 11/17/88 50 | 08 00 00 02 00 02 00 00 00 00 00 00 10 00 00 00 | thursday 60 | 08 00 00 | +-------------------------------------------------+ archived 01:12:00 10/22/88 header_id = "NuFX" saturday header_crc = $7865 attrib_count = $003A (58 bytes in attrib section) version = $0000 total_threads = $00000002 file_sys_id = $0001 (Prodos) file_sys_info = $002f (not sparse, / = separator) access = $000000C3 (full access, not invis) filetype = $000000B3 (Prodos S16) aux_type = $00000000 storage_type = $0005 (extended file) create_when = 00 0a 01 58 16 0a 00 07 mod_when = 00 10 0b 58 11 0b 00 05 archive_when = 00 0c 01 58 16 0a 00 07 filename_length = $0009 filename = "EXT.STUFF" thread_class = $0002 (data_thread) thread_format = $0002 (compressed by ShrinkIt) thread_kind = $0000 (file) reserved = $0000 thread_length = $00002000 comp_thread_length = $00000800 (data_fork is 25% of original size) thread_class = $0002 (data_thread) thread_format = $0002 (compressed by ShrinkIt) thread_kind = $0002 (resource_fork) reserved = $0000 thread_eof = $00001000 comp_thread_eof = $00000800 (resource is 50% of original size) NuFX Documentation 2/3/89 - Page 21 - Disks ----- If the file system of a particular disk is not known, the file_sys_id field should be set to null, the volume name should also be set to null, and all the other fields pertaining only to files should be set to null. If the file system of a particular disk *IS* known, as many of the fields as possible should be filled with the correct information. Fields which do not pertain to an archived disk should remain set to null. If an entire disk is added to the archive without some form of compression (ie, record_format = uncompressed), then the blocks which comprise the disk image *MUST* be added sequentially from the first through the last block. Since there will be no character included in the data stream to mark the end/beginning of a block, extraction programs should rely on the file_sys_block_size field to determine how many bytes to read from the record to properly fill a block. NuFX Documentation 2/3/89 - Page 22 - Sample header block for a disk record: 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F +-------------------------------------------------+ created 01:10:00 00 | 4E F5 46 D8 67 05 3A 00 00 00 01 00 00 00 01 00 | 10/22/88 10 | 2f 00 00 00 00 00 00 00 00 00 40 06 00 00 00 02 | saturday 20 | 00 0a 01 58 16 0a 00 07 00 10 0b 58 11 0b 00 05 | 30 | 00 0c 01 58 16 0a 00 07 04 00 44 49 53 4B 02 00 | last mod 11:16:00 40 | 02 00 01 00 00 00 00 00 00 00 51 45 07 00 | 11/17/88 +-------------------------------------------------+ thursday archived 01:12:00 header_id = "NuFX" 10/22/88 header_crc = $0567 saturday attrib_count = $003A (58 bytes in attrib section) version = $0000 total_threads = $00000001 (one thread) file_sys_id = $0001 (Prodos) file_sys_info = $002f (not sparse, / = separator) access = $00000000 (none) filetype = $00000000 (none) aux_type/creator_type = $00000640 (1600 blocks on device -- 3.5" disk) storage_type = $0200 (block size = 512 bytes) create_when = 00 0a 01 58 16 0a 00 07 mod_when = 00 10 0b 58 11 0b 00 05 archive_when = 00 0c 01 58 16 0a 00 07 filename_length = $0004 filename = "DISK" thread_class = $0002 (data_thread) thread_format = $0002 (compressed with ShrinkIt) thread_kind = $0001 (disk image) reserved = $0000 thread_eof = $00000000 (unknown size before compressing) comp_thread_eof = $00074551 (size after compression) NuFX Documentation 2/3/89 - Page 23 - Directories ----------- Directories are handled almost the same way that normal files are handled with the exception that there will be no data in the thread which follows the entry. A thread_record *MUST* exist to inform a utility that a directory is to be created through the use of the proper control_thread value. Directories do not necessarily have to precede a record which references a directory. ie, if a record contains STUFF/MY.STUFF, the directory "STUFF" need not exist for the extracting program to properly extract the record. The extracting program must check to see if each of the directories referenced exist, and if they do not exist, create them. While this method places a great burden on the abilities of the extraction program, it avoids the anomalies associated with the deletion of directories within an archive. NuFX Documentation 2/3/89 - Page 24 - Cyclic Redundancy Checks (CRC's) -------------------------------- Many people are not aware of how to calculate a CRC, so to provide this function, I am providing source code to a very fast routine which does the crc calculation. The routine "makeLookup" needs to be called only once. After this, the routine "doByte" should be called repeatedly with each new byte in succession to generate the cumulative CRC for the block. The CRC word should be reset to null (0000) before beginning each new CRC. This is the same CRC calculation which is done for CRC/Xmodem, and Ymodem. The code is easily portable to a 16-bit environment like the Apple IIgs. The only detrimental factor with this routine is that it requires 512 bytes of main memory to operate. If you can spare the space, this is one of the fastest routines I know to generate a CRC-16 on a 6502-type machine. *------------------------------- * fast crc routine based on table lookups by * Andy Nicholas - 03/30/88 - merlin 'c02 - easily portable to nmos 6502 also. * easily portable into orca/m format, just snip and save. xc turn 65c02 opcodes on *------------------------------- * routine to make the lookup tables *------------------------------- makeLookup LDX #0 zero first page zeroLoop STZ crclo,x zero crc lo bytes STZ crchi,x zero crc hi bytes INX BNE zeroLoop *------------------------------- * the following is the normal bitwise computation * tweeked a little to work in the table-maker docrc LDX #0 number to do crc for fetch TXA EOR crchi,x add byte into high STA crchi,x of crc LDY #8 do 8 bits loop ASL crclo,x shift current crc-16 left ROL crchi,x BCC loop1 NuFX Documentation 2/3/89 - Page 25 - * if previous high bit wasn't set, then don't add crc * polynomial ($1021) into the cumulative crc. else add it. LDA crchi,x add hi part of crc poly into EOR #$10 cumulative crc hi STA crchi,x LDA crclo,x add lo part of crc poly into EOR #$21 cumulative crc lo STA crclo,x loop1 DEY do next bit BNE loop done? nope, loop INX do next number in series (0-255) BNE fetch didn't roll over, so fetch more RTS done crclo ds 256 space for low byte of crc table crchi ds 256 space for high bytes of crc table *------------------------------- * do a crc on 1 byte/fast * on initial entry, CRC should be initialized to 0000 * on entry, A = byte to be included in CRC * on exit, CRC = new CRC *------------------------------- doByte EOR crc+1 add byte into crc hi byte TAX to make offset into tables LDA crc get previous lo byte back EOR crchi,x add it to the proper table entry STA crc+1 save it LDA crclo,x get new lo byte STA crc save it back RTS all done crc dw 0000 cumulative crc for all data NuFX Documentation 2/3/89 - Page 26 - Possible Block Combinations --------------------------- The blocks *MUST* occur in the following fashion: Master Header block containing N entries Header block threads (message, control, data, or resource) . . . Next Header block (notice no second Master Header block) threads (message, control, data, or resource) . . . Nth Header Block threads (message, control, data, or resource) NuFX Documentation 2/3/89 - Page 27 - Known NuFX utility programs: --------------------------- Name Author Description Current Ver ------------- -------------- ------------------------------------ ----------- ShrinkIt Andy Nicholas Compresses files/disks, provides 0.95 archive and file utilities. NuList Andy Nicholas Lists contents of NuFX files for 1.1 the GBBS "Pro" (tm) BBS, online. NuFX Documentation 2/3/89 - Page 28 - Legal Stuff ----------- Apple, Apple IIGS, AppleLink, GS/OS, Macintosh, and Lisa are registered trademarks of Apple Computer, Inc. GBBS "Pro" is a registered trademark of L&L Productions. About the Author ---------------- I am currently a Junior attending Moravian College in Bethlehem, Pennsylvania, majoring in Computer Science. Any comments or suggestions you have about NuFX are more than welcome, or if you wish to request that any of the fields be assigned your own value, or if you would like to inform me of a NuFX utility you have written, you can contact me at: Paper Bag Productions c/o Andy Nicholas Box 435 Moravian College Bethlehem, PA 18018 CSNET : nicholaA@moravian.edu InterNET : nicholaA%batman.moravian.edu@relay.cs.net nicholaA@batman.moravian.edu.csnet ProLine : andyn@pro-sol.cts.com [619-670-5379] AppleLink PE: ShrinkIt I would like to thank the following people for their help and input during the design phase of the NuFX proposal: Jason Blochowiak, Morgan Davis, Don Elton, Dave Lyons, Jon Davidson, Vince Cooper, Lance Taylor-Warren, Floyd Zink, Kent Dickey, John Brooks, Doug Brandon, Todd South, Larry Hawkins, Kevin Keller