Info about the ÒBinHQXÓ XCMD BinHQX XCMD copyright © 1995-98 by Ewen Wannop General command form: External BinHQX The BinHQX XCMD gives a script control over the encoding/decoding processes associated with BinSCII (Apple II), BinHex 4.0 (Macintosh), Base64 (MIME) and UUencoded (Unix) files. In Spectrum v2.1 or later, this XCMD also incorporates itself into Spectrum's menus: "Encode a File" and "Decode a File" will be added to the solid Apple menu; "Encode Settings" will be added to the Settings/File Transfer sub-menu. Any errors generated during the encoding or decoding process are displayed in a standard Alert window. BinSCII, BinHex 4.0, Base64 and UUencoded files allow the transfer of 8 bit data files over a 7 bit ASCII network. The 8 bit data is reduced to printable ASCII text and the transmission can therefore ignore any control characters (other than CRs or LFs) introduced within the transmitted data. The encoded data can be stored and transmitted on all current networks and host systems. Typically these encoding methods are used to send files as attachments to messages over Internet message systems. BinSCII is specifically tailored to the Apple II ProDOS (GS/OS) file system and preserves the filetype and auxtype information of these files. Because it was defined before extended files were created for use with the IIgs, it does not allow the encoding of forked files. Such files must first be packed into a single data fork using an archiving program like ShrinkIt. BinHex 4.0 is specifically tailored to the Macintosh file system and preserves the Type and Creator of the Macintosh file, as well as both the data and resource forks of the file. However BinHex 4.0 can be used to pack forked GS/OS files as well as Macintosh files. This allows forked files to be directly encoded under the GS/OS file system. Base64 is a common format for email message files on the Internet. In its simplest format, it does not preserve filetypes. However it is capable of extension and supporting the Multipart AppleSingle and AppleDouble files. To use this extra feature, check the 'Forked Base64' checkbox in 'Encoding Options'. UUencoding is very common for Internet messages. However it is not capable of preserving file types. An attempt will be made to 'guess' the file type from any suffix in the embedded filename. Note that BinHex 4.0 was originally intended for encoding Macintosh forked files. Because a Macintosh file can have an empty data or an empty resource fork, ProDOS or GS/OS data files encoded with BinHex 4.0 may have an empty resource fork when they are decoded. This may or may not be a problem if used within the GS/OS environment. It is not a problem for files that are decoded on a Macintosh. If you are encoding ProDOS or GS/OS files with only a data fork, it is usually better to use the BinSCII method. The BinHQX XCMD will attempt to save ProDOS files with only a data fork, without a corresponding resource fork. Whether this is successful or not depends on how the file was encoded into BinHex 4.0 format in the first place. If encoded with the BinHQX XCMD, or the ProDOS file was encoded by a Macintosh application from an HFS partition, then the files should decode without a resource fork. After a file has been decoded, an IPC message is broadcast by the BinHQX XCMD in the same way that Spectrum notifies a successfully downloaded file. If Balloon (or a similar program) is present it will respond as if the file had been downloaded. In the case of multiple BINSCII files being decoded in one session, the IPC message will only refer to the last file that was decoded. BinHQX v1.1 fixes a bug that caused some BinHex 4.0 files encoded with BinHQX to fail to unwrap. It also fixes a myriad of other small bugs and adds support for Base64 and UUencoded files. FUNCTION = Set Parameter dialog External BinHQX With no function specified, and with the SHR 640 desktop showing, a dialog opens that lets the user change the settings that are used when manually encoding a file (that is, when using Function 3 or the Menu control, not when using Function 1). FUNCTION 0 = Get Version External BinHQX 0 Varname Varname is optional; if given it will contain the version number Use this function (with or without Varname) to determine if the BinHQX XCMD is installed in the system (the Failed flag will be set if not). FUNCTION 1 = Encode File External BinHQX 1 Kind Parts EndLine SrcFile OutPath {OutName} Kind is a number: 1 (BinSCII) 2 (BinHex 4.0) 3 (Base64 AppleDouble or AppleSingle) 4 (UUencode) 5 (Base64 plain files) Parts is a number indicating the maximum parts in the output file EndLine is a number indicating the line termination character SrcFile identifies the source file OutPath identifies the folder in which to put the encoded file OutName is optional; if given it will receive the first output filename This function encodes a single file using one of the four encoding methods. When encoding a file the encoded output can be split automatically into several smaller segments, rather than one large output file. The meaning of the Parts parameter depends upon the encoding scheme being used: BinSCII encoding: The source file is processed in 12K segments. Each 12K segment is encoded then stored in an output file. If Parts is 0 then all output segments will be stored in a single output file. If Parts is 1 or more then one output file will contain no more than the specified number of segments, and additional output files will be created as needed. For example, if a source file is 48K it will be encoded in 4 segments. If Parts is 0 then all 4 segments will be stored in a single output file. If Parts is 1 then 4 output files will be created, each containing a single segment. If Parts is 3 then 2 output files will be created; the first will hold segments 1-3, the second will have segment 4. BinHex 4.0, Base64 and UUencoded encoding: If Parts is 0 then a single output file is created. Any other number indicates the number of lines to include in each file. For example, if an encoded file would be 500 lines and Parts was 200, then 3 files would be created, two with 200 lines and the third with 100 lines. EndLine denotes the method used to separate each line in the output file: 09 = Tab (BinHex only!) 10 = LineFeed 13 = Return 32 = Space (BinHex only!) Most systems use a standard Return ($0D) as their end of line character. The Macintosh and the Apple II both use this value. Some systems, such as Unix, expect an LineFeed ($0A) as their end of line character. SrcFile indicates the file to encode. The name can be provided in any of the following formats: "FoldernameFilename" (e.g., ":Hard1:Upload:Scripts.BXY") ScriptEditorNumber (e.g., 1) ScriptEditorHandle (e.g., $EditorHandle3 or ~E01234) Whatever method is used, only a single file can be specified for encoding. OutputPath is the Foldername in which to store the output file(s). The path can be provided in any of the following formats: "Foldername" (e.g., ":Hard1:Upload:BinSCIIed:") ScriptEditorNumber (e.g., 6) ScriptEditorHandle (e.g., $EditorHandle2 or ~E01432) Whatever method is used, the Foldername must end with a colon (as usual) otherwise an error will occur. If the optional {OutputName} variable is given, it will return the first or root name used for the output file (this will be some variation based on the input filename). If an error occurs in the input parameters, or a disk error occurs, the Failed flag will be set. FUNCTION 2 = Decode File External BinHQX 2 SourceFile OutputPath {OutputName} SourceFile identifies the source file(s) OutputPath identifies the folder in which to put the decoded file OutputName is optional; if given it receives the last decoded filename SourceFile is the FoldernameFilename of the file(s) to decode. The name(s) can be provided in any of the following formats: "FoldernameFilename" (e.g., ":Hard1:Received:Scripts.000" ScriptEditorNumber (e.g., 1) ScriptEditorHandle (e.g., $EditorHandle3 or ~E01234) SourceFile identifies the file(s) to decode. A series of filenames to decode can be specified in a ScriptEditor, and those files will be decoded in the sequence they are listed. If the encoding process created 4 separate files, each and every file must be decoded before the result file is complete. Decoding separate BinSCII files can be done in any order. Decoding separate BinHex 4.0, Base64 and UUencoded files should always be done in the order the files were created, otherwise the resulting file will not be usable. When the ScriptEditor is parsed by the BinHQX XCMD, it considers each file entry as being separated by the current Quote character, or by spaces. If you use quotes around each filename then you must temporarily change the quote character to something else in order to set the contents of the script editor, then change it to the quote character you used. For example: Set Quote ¥ Create ScriptEditor 0 Ext ScriptEditor 7 0 ¥":Path:File1" ":Path:File2" ":Path:File3"¥ Set Quote " Ext BinHQX 2 0 "OutputPath" {OutputName} OutputPath is the Foldername in which to store the decoded file. The path can be provided in any of the following formats: "Foldername" (e.g., ":Hard1:Upload:BinSCIIed:") ScriptEditorNumber (e.g., 6) ScriptEditorHandle (e.g., $EditorHandle2 or ~E01432) Whatever method is used, the Foldername must end with a colon (as usual) otherwise an error will occur. The decoded file(s) will be stored in the OutputPath using the filename embedded within the BinSCII or BinHex 4.0 data. If the optional {OutputName} variable is given, it will return the name of the last output file that was decoded. Note that BinSCII encoded files can contain one or more segments of the final output file. The decoding process will decode each segment as it is found and save this to the target file. If not all the segments are present, the resulting file may be incomplete. If the target file name already exists, but is not the real target file, then any data it contains may be overwritten. There is no way of checking for this as the normal operation of BinSCII decoding is to write portions of the file to the target file as they are found. It is wise to always decode into an empty directory. BinHex 4.0, Base64 and UUencoded split files are handled differently. For instance a BinHex 4.0 split is designated by the following sequence. This can occur one or more times within a single file, or may be used at the end and start of two or more files. It is important that the files are seen and processed sequentially, or the data will be seen as being corrupted. previous hex data... --- end of part xx --- (processing stops) any data found here is ignored... --- (processing continues) new hex data... The in this case is any occurence of a or . Data between the two markers is ignored. Base64 can produce quite complex headers depending on the method chosen to encode the file, and whether the file isa single or double forked file. UUencoded files produce headers in this format: BEGIN --------- cut here --------- CUT HERE -------- PART 8/9 If SourceFile is neither a valid BinSCII, BinHex 4.0, Base64 or UUencoded file, or a disk or other error occurs, the Failed flag will be set. Note: When decoding a file, an attempt is made to show an accurate thermometer indicating progress. The thermometer actually shows the data being written out rather than the data being read. In some cases, the thermometer will not neccessarily reach its full extent. As long as no error message is shown, you can be assured that the decoded file is being written fully. FUNCTION 3 = Manual Encode External BinHQX 3 {OutputName} OutputName is optional; if given it receives the first output filename Standard File dialogs are presented to select the source file and target folder (just like selecting "Encode a File" from the solid Apple menu in Spectrum v2.1 or later). The encoding method can be selected in the first dialog box. The settings used to encode can be changed by using "External BinHQX" with no function specified. If disk or other error occurs, the error will be displayed in an Alert window, and the Failed flag will be set. FUNCTION 4 = Manual Decode External BinHQX 4 {OutputName} OutputName is optional; if given it receives the last decoded filename Standard File dialogs are presented to select the source file(s) and target folder (just like selected "Decode a File" from the solid Apple menu in Spectrum v2.1 or later). The source file(s) are selected in the dialog and will be decoded in the sequence they are listed in the dialog. If the optional OutputName variable is given, it will return the name used for the output file. Only TXT, SRC and TEA files will normally show in the dialog, but for compatibility with certain Macintosh files, those with a filetype of $00 will also show. The Failed flag will be set if any error occurs.