@database binhex.guide @author nsoggia@telnetwork.it @smartwrap @$VER: BinHex.guide 37.02 (18.10.96) by Nicola Soggia @rem ******************************************************************** @rem * * @rem * the "title" macro under kickstart 1.3 and 2.0 is drawn as a link * @rem * instead of a centered bold text, this could be confusing. * @rem * real links have at least a space before and after the string. * @rem * * @rem ******************************************************************** @macro title "@{jcenter}@{b}@{par}$1@{par}@{ub}@{jleft}" @macro rev "@{par}@{b}@{fg shine}$1@{ub} $2 public release.@{fg text}@{par}" @macro arg "@{par}@{b}$1@{ub}@{par}" @node "main" "The Nik Soggia BinHex Toolkit" @{code}@{jcenter}@{b} The Nik Soggia _______________________________________________________________________________ __@{bg shadow}_____@{bg back}__@{bg shadow}__@{bg back}________@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}________________@{bg shadow}______@{bg back}_____________@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}_____@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}___ __@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}___________@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}__________________@{bg shadow}__@{bg back}_______________@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}_________@{bg shadow}__@{bg back}___ __@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}_@{bg shadow}_____@{bg back}__@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}__@{bg shadow}____@{bg back}__@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}____@{bg shadow}__@{bg back}__@{bg shadow}____@{bg back}___@{bg shadow}____@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}_@{bg shadow}____@{bg back}__ __@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}____@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}___ __@{bg shadow}_____@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}______@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}____@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}_@{bg shadow}____@{bg back}___@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}___ __@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}______@{bg back}__@{bg shadow}____@{bg back}_____@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}_@{bg shadow}___@{bg back}____@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}___ __@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}_____@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}____@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}_@{bg shadow}____@{bg back}___@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}___ __@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}___@{bg shadow}_@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}____@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}___ __@{bg shadow}_____@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}__@{bg shadow}____@{bg back}__@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}____@{bg shadow}__@{bg back}__@{bg shadow}____@{bg back}___@{bg shadow}____@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}_@{bg shadow}__@{bg back}__@{bg shadow}__@{bg back}___ "Easy to use BinHex 4.0 encoding and decoding programs for the Amiga" BHD v37.02 (18-Oct-96) - BHE v37.02 (18-Oct-96) @{fg shine}_______________________________________________________________________________@{fg text} ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ @{ub}@{jleft} @{" Foreword " link "fore"} About programs and BinHex format @{" BHD " link "deco"} Decoding BinHex files using BHD @{" BHE " link "enco"} Encoding BinHex files using BHE @{" Tech notes " link "tech"} Technical matters for I/O files @{" History " link "hist"} Programs' history @{body} @{title "DISTRIBUTION"} This package is released under the concept of freeware, the package must be distributed as one whole. The distributor may charge a fee up to the cost of the medium for the entire package. @{title "NO WARRANTY"} This package is provided as is, without warranty of any kind, either expressed or implied. Should the package prove defective, you assume the entire cost of all necessary servicing, repair or correction even if I have been advised of the possibility of such damages. I'm not responsible of the results of the use of the package. @{title "SUPPORT"} If you have any suggestions, bug reports, or wish to let me know something about the package feel free to contact me at nsoggia@telnetwork.it @endnode @node "fore" "Foreword on the BinHex Toolkit" @{title "ABOUT MAC FILING SYSTEM"} Mac files consist of two parts called forks: the data fork is the most important for non-Mac users as it contains the meaningful data, the resource fork contains data such as program segments information, the icon bitmap and other arbitrary data that can resemble Amiga's icon tooltypes. Then, each Mac file has some more additional information stored in a hidden file called the "desktop database".@{par} Transferring such complicated files from one Mac to another without using Mac specific media needed a way to keep together all the above information, so BinHex was born.@{par} This format is now so popular that Mac users use it to send their data even to other platform users who basically need only the data fork. Even Windows users seem to like it as their default encoding format: "it makes bigger files so it must be good" =8-O @{title "ABOUT BINHEX 4.0"} BinHex 4.0 merges the original file name, the desktop database information, the data fork and the resource fork in a single file, then compresses repeated bytes and encodes the binary data in printable ASCII to safely transfer it by e.g. E-Mail. It also provides an error checking mechanism to check if the file got corrupted during the transfer. @{title "BINHEX VS BASE64"} BinHex is essential only when data has to be exchanged between Macs, In all other cases Base64 encoded MIME messages can do the same things BinHex does with less CPU overhead, less bandwidth and improved inter-platform compatibility. @{title "AMIGA IMPLEMENTATION"} The BinHex Toolkit is able to preserve all the information a BinHex 4.0 file can contain: @{par} @{b}FILE NAME:@{ub} Amiga file names can be up to 30 characters in length, Mac names can be up to 63 characters long. When importing, the BinHex Toolkit translates the Mac character set to 7-bit ASCII, strips unprintable characters, eventually truncates the name length to 30 characters. When exporting, the BinHex Toolkit translates the Amiga character set to 7-bit ASCII. @{par} @{b}FILE TYPE:@{ub} The BinHex Toolkit stores (and searches) the Mac file type in the Amiga file comment. @{par} @{b}FILE CREATOR:@{ub} The BinHex Toolkit stores (and searches) the Mac file creator in the Amiga file comment. @{par} @{b}FINDER FLAGS:@{ub} The BinHex Toolkit stores (and searches) the Mac Finder flags (bozo, system, bundle, invisible, locked) in the Amiga file comment. @{par} @{b}DATA AND RESOURCE FORKS:@{ub} The BinHex Toolkit reads and writes an Amiga file for each fork in the BinHex file. @{par} @{title "AMIGA VS MAC"} The BinHex Toolkit is faster, more fault tolerant, compresses better, needs less resources, has more options than the original Mac 4.0 binary (no kidding, I can demonstrate it).@{par} It lacks the GUI, but can be interfaced easily with mail and news readers. @endnode @node "deco" "BinHex_decode (BHD) User's manual" BHD stands for BinHex Decoder, it accepts a BinHex 4.0 encoded file and generates up to two files containing the data and resource forks. @{title "REQUIREMENTS"} BHD runs under Kickstart 2.0 and above from any Shell (it does not support Workbench directly) on any Amiga, it needs at least 4 Kb of stack memory and at least about 25 Kb of free memory. @{title "USAGE"} @{arg "INFILE/A"} This required argument is the name of the input file (wildcards are not supported). The file must be in BinHex format. @{arg "DATA/K"} This keyword argument designates the file name where the data fork will be stored. If the argument contains a "%s" token (without quotes), the token will be replaced with the filename stored in the BinHex file plus a "_d" suffix. Only one "%s" token can be specified, specifying more than one token will lead to randomly messed up names. @{arg "RES=RSRC/K"} This keyword argument designates the file name where the resource fork will be stored. If the argument contains a "%s" token (without quotes), the token will be replaced with the filename stored in the BinHex file plus a "_r" suffix. Only one "%s" token can be specified, specifying more than one token will lead to randomly messed up names. @{arg "BUFSIZE/K/N"} This keyword numeric argument designates the size in bytes of each work buffer. The buffers are 3 and equal in size, allocated in a contiguous chunk of memory. Minimum value is 8192, maximum value depends on the largest free memory chunk in your system, default size for each buffer is 16 Kb. @{arg "NOTE/S"} If this switch is set then each output file will be commented with the file type, the file creator and the Finder flags. See also the @{" file comment format " link "tech"} chapter. @{title "OPERATION"} INFILE doesn't need to start with a BinHex header string, BHD will scan the whole file until it finds one. If INFILE contains more BinHex documents, only the first one will be extracted.@{par} @{par} The data and resource forks will be extracted only if their name has been specified by the DATA/K,RES=RSRC/K arguments: in this way you can extract only the forks you really need (most of the times the data one). BHD will never create empty files: if you need empty files, you can generate a couple of empty files and let BHD overwrite them.@{par} @{par} Using a large (100 Kb or more) BUFSIZE can improve decoding time when reading or writing large files from CD-Rom's or similar relatively slow media, but it needs much memory and uses intensively the CPU for larger time intervals.@{par} @{par} The NOTE switch allows to write the output files directly on Mac media (such as ShapeShifter's mac-handler) or simply to preserve the Mac file attributes for a future re-encoding: it comments the output files with the type/creator pair followed by the active Finder flags. Should the type/creator pair be invalid, the ????/???? default will be used. @{title "ERROR MESSAGES"} BHD shows the standard AmigaDOS messages on its standard output in case of file I/O error or memory allocation failure. BHD will set return code to FAIL (20) if something goes wrong, ERROR (10) if command line options are wrong, OK (0) if all goes flawlessly. @{arg "[INFILE]: not a hqx7 file"} Infile hasn't the BinHex header string "(This file must be converted with BinHex 4.0)" or its data doesn't start with a ":", or the header string is not separated by at least a "end of line" character (ASCII CR or LF) from the encoded data, or the file header and data are indented from the left margin.@{par} You can recover the file removing the indentation in front of the header line and the first data line, or adding the missing header string, ":" or end-of-line characters. @{arg "[INFILE]: unexpected end of file"} Infile hasn't a ":" character at the end of its data chunk. If you add one by hand after the last data character and then you get a CRC error, then the file really got truncated and there is no way to recover lost data. @{arg "crc error in [HEAD|DATA|RSRC] (expected [XXXX], found [YYYY])"} If the CRC error is in the BinHex header no extraction will be attempted. If the CRC error is in the forks, corrupted forks will not be deleted. @endnode @node "enco" "BinHex_encode (BHE) User's manual" BHE stands for BinHex Encoder, it generates a BinHex 4.0 encoded file reading up to two files containing the data and resource forks. @{title "REQUIREMENTS"} BHE runs under Kickstart 2.0 and above from any Shell (it does not support Workbench directly) on any Amiga, it needs at least 4 Kb of stack memory and at least about 25 Kb of free memory. @{title "USAGE"} @{arg "OUTFILE/A"} This required argument is the name of the BinHex output file. @{arg "DATA/K"} This keyword argument designates the file name containing the data fork. See also the @{" file comment format " link "tech"} chapter. @{arg "RES=RSRC/K"} This keyword argument designates the file name containing the resource fork. See also the @{" file comment format " link "tech"} chapter. @{arg "BUFSIZE/K/N"} This keyword numeric argument designates the size in bytes of each work buffer. The buffers are 3 and equal in size, allocated in a contiguous chunk of memory. Minimum value is 8192, maximum value depends on the largest free memory chunk in your system, default size for each buffer is 16 Kb. @{arg "NOTE/S"} If this switch is set then the output file will be commented "TEXT/BNHQ". See also the @{" file comment format " link "tech"} chapter. @{arg "MIME/S"} If this switch is set then the appropriate MIME header will be prepended to the BinHex header string. @{arg "CR/S"} If this switch is set then each line will be terminated by a Carriage Return character (Mac end of line marker) instead of a Line Feed character (Amiga end of line marker). @{arg "APPEND/S"} If this switch is set then the data generated by the program will be stored starting at the end of the already existing outfile instead of overwriting the outfile. @{title "OPERATION"} The OUTFILE/A value will be used also as the default BinHex file name. It will be stored in the BinHex header in 7 bit ASCII format, if the value has a 3 characters extension to the right, the extension will be stripped (examples of such extensions may be: ".out", ".hqx", ".mac", or any other string starting with a "." followed by 3 characters) so a outfile named "Test.hqx" will save the data in a file called "Test.hqx" and will generate the "Test" default BinHex file name, and a outfile named "Test.hqx7" will save the data in a file called "Test.hqx7" and will generate the "Test.hqx7" default BinHex file name.@{par} @{par} The data and resource forks will be saved only if their name has been specified by the DATA/K,RES=RSRC/K arguments: in this way you can generate BinHex files containing just one fork, both forks, or no forks at all.@{par} @{par} The NOTE and CR switches are designed to write directly the output file directly on Mac media (such as ShapeShifter's mac-handler).@{par} @{par} The MIME and APPEND switches can be used when invoking BHE from scripts to compose E-Mail bodies, note that the MIME name preserves the 3 characters file name extension if present.@{par} @{par} Using a large (100 Kb or more) BUFSIZE can improve encoding time when reading or writing large files from CD-Rom's or similar relatively slow media, but it needs much memory and uses intensively the CPU for larger time intervals. @{par} @{par} When getting the desktop database information from the file comment, Finder flags will be OR-combined, so if a flag is present in the data fork file comment and another flag is present in the resource fork comment, the resulting BinHex header will contain both flags.@{par} When getting file type and file creator from file comments, BHE tries to use the ones stored in the data file comment, if the data file is not specified, not found, or its comment is not set, BHE will check the resource fork file, if the resource file is not specified, not found, or its comment is not set a default ????/???? type/creator pair will be set in the BinHex header.@{par} @{title "ERROR MESSAGES"} BHE shows the standard AmigaDOS messages on its standard output in case of file I/O error or memory allocation failure. BHE will set return code to FAIL (20) if something goes wrong, ERROR (10) if command line options are wrong, OK (0) if all goes flawlessly. @endnode @node "tech" "Technical matters" @{title "FILE COMMENT FORMAT"} File comment contains strings separated by white spaces. The first string that is 9 characters long and has a "/" character in the middle will be considered the file type/creator pair, if the 5th character of the comment string is a "/" then no further check will be made and the first 9 characters of the comment will be considered the type/creator pair (so that type and creator may contain spaces).@{par} All the 3 characters long strings will be (case insensitively) matched with "loc", "inv", "bun", "sys", "boz" to set active the "locked", "invisible", "bundle", "system" and "bozo" Finder flags.@{par} @{title "WHAT FINDER FLAGS NEED TO BE SET"} Leave them unset, as they may sound familiar they are not. The only purpose BHD stores those flags in the file comment is to allow BHE to rebuild the same BinHex file BHD decoded... @endnode @node "hist" "History of the BinHex Toolkit" @{title "DEVELOPMENT"} I write and test the BinHex Toolkit on an A3000/030-25, Before releasing each new version to the public I test the program under Enforcer and Mungwall on Kickstart 3.1. @{title "RELEASE HISTORY"} @{rev "BHD 37.01 (10-Oct-96)" "First"} @{b}BUG:@{ub} BHD can't accept more than one "%s" token for each output file name format string but it does not check for multiple tokens. @{rev "BHE 37.01 (10-Oct-96)" "First"} @{b}BUG:@{ub} file comment interpreter doesn't support spaces in type/creator strings. @{rev "BHD 37.02 (18-Oct-96)" "Second"} @{b}BUGFIX:@{ub} v37.01 failed with "not an hqx7 file" error if the BinHex header was not found within the first BUFSIZE/K/N bytes of the INFILE/A.@{par} @{b}BUGFIX:@{ub} v37.01 had a flacky "%s" token interpreter. I rewrote the token handling routine, now it ignores extra "%s" tokens.@{par} @{b}ADDED:@{ub} "%s" token is replaced with default BinHex name plus "_d" or "_r". "%S" token is replaced with plain default BinHex name. @{rev "BHE 37.02 (18-Oct-96)" "Second"} @{b}CHANGED:@{ub} made a smarter file comment parser, type/creator can now contain spaces if the type/creator string starts at the beginning of the file comment. @endnode