💾 Archived View for mirrors.apple2.org.za › archive › apple.cabi.net › Utilities › BinHQX.BXY.DOCS.t… captured on 2023-01-29 at 04:55:20.
-=-=-=-=-=-=-
Info about the �BinHQX� XCMD BinHQX XCMD copyright � 1995-98 by Ewen Wannop
General command form: External BinHQX <FunctionNumber> <parameters>
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 <null> = 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... <return>--- end of part xx ---<return> (processing stops)
any data found here is ignored... <return>---<return>
(processing continues) new hex data...
The <return> in this case is any occurence of a <CR> or <LF>. 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.