.im staffset
.* .im cmdset         ;.cm not needed with staffset for script 3.5
.ur .cp &$trigger
.cs 8 include         ;.cm use .cs 8's for parts NOT wanted in HELP
.cs 9 ignore          ;.cm don't mess with .cs 9's -- HELP needs them
...helpim             ;.cm imbed for HELP starts here (line 6)
.cs 9 on
.br;.li .fo off
.br;.li .cs 1 on
.br
.cs 9 off
.br;.bd on
.head2 'BINHEX'
.bd off
Use the BINHEX command to work with Macintosh files containing
binary data which are stored in CMS.
BINHEX may be used with HQX files, such as those created by
BinHex 4.0 on the Macintosh, and also with BIN files, such
as those created by BinHex 5.0.
BINHEX checks files in these formats, describes the contents
of the files, and converts between the two formats.
.cs 9 on
.br;.li .cs 1 off
.br;.li .cs 2 on
.br
.cs 9 off
The format of the BINHEX command is:
.br;.* xxx Insert $boxol, $boxolo, $boxbb, or $boxbbo after this line.
.* $boxolo
.sp 2
.tb 14
.ur .bx 1 12 &sysll
.sp
.ur &$vert.^BINHEX#? | Check | Describe | COnvert  fn <ft <fm >>^^^&$lbr.(options...&$lbr.)&$rbr.&$rbr.
.sp 1
.tb 14   18 30   33 45   48 60
.us #Options!:
.ur ##&$ulc.#&$urc.#&$ulc.#&$urc.#&$ulc.#&$urc.
.br
##&$vert.To fm#&$vert. #&$vert.Stack#&$vert. #&$vert.Fifo#&$vert.
.br
##&$vert.Rate cps#&$vert. #&$vert.Lifo#&$vert. #&$vert.STEm stm#&$vert.
.br
.ur ##&$llc.#&$lrc.#&$llc.#&$lrc.#&$llc.#&$lrc.
.br
.* xxx replace with $opt
.sp 1
.bx off
.br
.cs 9 on
.br;.li .cs 2 off
.br;.li .cs 3 on
.br
.cs 9 off
.br;.cp 7;.sk 2;.uc Operands;.sk 1
.tentry '?' 10
causes BINHEX to type a brief description of the command format,
including all the valid operands and options.
When "?" is specified, the remainder of the command line is
ignored.
.tentry 'Check'
cause BINHEX to check the input file for errors, such as missing
or corrupted data.  BINHEX will either report there are no errors,
or respond with an error message describing the problem.
BINHEX also checks the input file when the Describe or COnvert
operand is specified.
.tentry 'Describe'
causes BINHEX to display information about the input file,
including the full Macintosh filename, the type, creator,
flags values, and the sizes of the data and resource forks.
See the "Responses" section below for examples of the information
which is displayed.
.tentry 'COnvert'
causes BINHEX to convert the input file from BinHex to MacBinary
format or vice-versa.
The resulting file has the same filename as the input file, and
a filetype of either BIN (for MacBinary format) or HQX
(for BinHex format).
The file is written to the same disk as the input file, unless
the "To" option has been specified.
.tentry 'fn'
specifies the filename of the input file.
.tentry 'ft'
specifies the filetype of the input file.
When "ft" is omitted or specified as "*", all filetypes will be
searched to find a match for "fn".
.tentry 'fm'
specifies the filemode of the input file.
When "fm" is omitted or specified as "*", all accessed disks will
be searched for a file matching "fn" and "ft".
.tend
.br;.cp 7;.sk 2;.uc Options;.sk 1
.tentry 'To fm'
specifies the disk to which the output file will be written when
the "COnvert" operand is specified.  When "To" is omitted, the
output file is written to the same disk as the input file.
.tentry 'Rate cps'
specifies a file transfer rate in characters per second.
When a rate is specified, the information displayed by the
"Describe" function will include an estimate of the time
required to download the file.
.tentry 'Stack'
cause the output from the "Describe" function to be stacked
in FIFO order.  "Fifo" is a synonym for "Stack".
.tentry 'Lifo'
causes the output from the "Describe" function to be stacked
in LIFO order.
.tentry 'Fifo'
cause the output from the "Describe" function to be stacked
in FIFO order.  "Stack" is a synonym for "Fifo".
.tentry 'STEm stm'
causes the output from the "Describe" function to be stored
directly into REXX or EXEC2 variables.  "stm" is the name of
the stem for these variables, i.e. the characters preceding
a period in their names.  Only the first eight characters of
"stm" are significant.  The following variables are defined:
.exam
stm.FN         CMS filename
stm.FT         CMS filetype
stm.FM         CMS filemode
stm.FORMAT     BinHex or MacBinary
stm.NAME       Mac filename
stm.TYPE       Mac type
stm.CREATOR    Mac creator
stm.FLAGS      Mac flags
stm.DATASIZE   Mac data fork size
stm.RESCSIZE   Mac resource fork size
stm.CRDATE     Mac creation date
stm.MDDATE     Mac last modified date
stm.CHARCNT    Total character count
stm.TIMEEST    Download time estimate
.exam end
The creation and last modified dates are not defined for BinHex format
files, which do not include them.  The time estimate is defined only
when the Rate option has been specified.
.tend
.br;.cp 7;.sk 2;.uc Using the BINHEX Command;.sk 1
.pp
The BINHEX command allows Macintosh users to obtain information
about files stored in CMS which would ordinarily not be available
until the files had been downloaded to a Macintosh.
The Check function verifies that a file will be accepted by BinHex
on the Macintosh, and
the Describe function provides detailed information about a file.
With this information, a Macintosh user can often avoid spending
time downloading unwanted files or files which contain errors.
The COnvert function provides conversion between the two file
formats BINHEX accepts: BinHex format and MacBinary format.
Conversion is useful because each of these formats offers advantages
for storing Macintosh programs.
.pp
BinHex format is used by BinHex 4.0 on the Macintosh.
It consists of a header, the data fork, and the resource fork of a
Macintosh file, compressed and converted to printable characters.
Converting a file from binary to printable characters increases
its size (in spite of the inclusion of file compression).
However, since
they contain only printable characters, BinHex files can
be included in electronic mail, and can be uploaded and downloaded
in nearly any environment.
In CMS, BinHex files usually are given filetypes containing "HQX",
and may have fixed or variable-length records.
The files usually begin with the line
.exam
(This file must be converted with BinHex 4.0)
.exam end
.pp
MacBinary format is used by BinHex 5.0 and MacTerminal on the
Macintosh.
It is similar to BinHex format, but retains the file contents in
binary form instead of converting to printable characters.
It also includes the dates the Macintosh file was created and last
modified, and some extra flag bits.
MacBinary is the most compact format for storing a Macintosh file.
However,
because MacBinary files retain binary data, they can be uploaded
and downloaded only by programs which use an 8-bit data path.
Usually, such a path is not available for VM/CMS systems.
Programs such as Kermit can simulate an 8-bit path using printable
characters, but only at the expense of a much longer transfer time.
MacBinary files in CMS usually are given filetypes containing "BIN".
They consist of fixed-length 128-byte records.
.br;.cp 7;.sk 2;.uc Usage Notes;.sk 1
.seq 1
Although the filetype of the input file will usually indicate which
format it is in, BINHEX determines the file's format by examining
its characteristics.
If the file has fixed-length 128-byte records, BINHEX assumes
MacBinary format.
Otherwise, BINHEX assumes BinHex format.
.seq
The data in a BinHex format file begins with a line containing
a colon in column one, and ends with a line having a colon as the
last character.
CMS BINHEX skips any other lines in the file.
However, BinHex on the Macintosh only skips the comment line
"(This file must be converted with BinHex 4.0)".
Thus, even when the Check function reports no errors, it may
still be necessary to delete extraneous lines from the BinHex
file before BinHex on the Macintosh will accept the file.
.seq
BinHex format files do not contain all the information
included in MacBinary files.  In particular, the creation and
last modified dates, and some flag bits are not stored.
As a result, this information is lost when the COnvert
function is used to convert from MacBinary to BinHex format.
.seq
BINHEX cannot detect if the input file is not in either MacBinary
or BinHex format.  In this case, BINHEX will usually assume the
file is in BinHex format, and give an "unexpected end-of-file"
message when it fails to find the first line of BinHex data.
.seq
For a BinHex file, the maximum line length BINHEX can process is 256.
.seq end
.br;.cp 7;.sk 2;.uc Responses;.sk 1
.fo off
'fn ft fm': No errors detected.
.fo on
.sk 1
.in +10
This is the normal response from the Check function.
This response is omitted when BINHEX is called from a CMS command,
or from an exec file with "address COMMAND" in effect.
.in -10
.sk 1
.fo off
File: 'STARS16 HQX T1'  Format: BinHex
Filename: 'Stars 1.6'
Type: 'DFIL'  Creator: 'DMOV'  Flags: none
Data fork size: 0; Resource fork size: 6,054
Character count: 10,140.
.fo on
.sk 1
.in +10
This is the response from the Describe function for a BinHex file
when the Rate option is not used.  This is the shortest possible
description.
.in -10
.sk 1
.fo off
File: 'TERM412 BIN M1'  Format: MacBinary
Filename: 'Term 4.12'
Type: 'APPL'  Creator: 'TRMA'  Flags: Bndl+Init
Data fork size: 0; Resource fork size: 52,947
      Created: Thu, May 28, 1987  2:01:25 AM
Last Modified: Thu, May 28, 1987  2:02:04 AM
Character count: 53,120 (4 minutes, 55 seconds at 180 cps).
.fo on
.sk 1
.in +10
This is the response from the Describe function for a MacBinary file
when the Rate option is used.  This is the longest possible description.
.in -10
.br;.cp 7;.sk 2;.uc Other Messages and Return Codes;.sk 1
.exam
DMSBIN631E 'STEM' option is only available from an EXEC2 or REXX exec.
           RC=4
DMSBIN001E Error in command after 'token'.^^RC=24
DMSBIN002I Issue BINHEX ? or HELP CMS BINHEX for more information.
DMSBIN003E Invalid option 'xxxxxxxx'.^^RC=24
DMSBIN010E Invalid rate 'xxxxxxxx'.^^RC=24
DMSBIN048E Invalid mode 'xxxxxxxx'.^^RC=24
DMSBIN637E Missing value for the 'STEM' option.^^RC=24
DMSBIN002E File 'fn ft fm' not found.^^RC=28
DMSBIN024E File 'fn ft fm' already exists.^^RC=28
DMSBIN044E Record length exceeds allowable maximum.^^RC=32
DMSBIN005E Invalid character 'x' in 'fn ft fm' at line mmmmmm position
           nnn.^^RC=36
DMSBIN006E Unexpected end-of-file reading 'fn ft fm'.^^RC=36
DMSBIN037E Disk 'mode' is read-only.^^RC=36
DMSBIN069E Disk 'mode' not accessed.^^RC=36
DMSBIN007E 'fn ft fm': CRC error for BinHex header.^^RC=44
DMSBIN008E 'fn ft fm': CRC error for BinHex data fork.^^RC=44
DMSBIN009E 'fn ft fm': CRC error for BinHex resource fork.^^RC=44
DMSBIN104S Error 'nn' reading file 'fn ft fm' from disk.^^RC=1nn
DMSBIN105S Error 'nn' writing file 'fn ft fm' on disk.^^RC=1nn
DMSBIN632E Error setting EXEC variable: RC=nnnnn from 'EXECCOMM'.^^RC=200
.exam end
.cs 9 on
.br;.li .cs 3 off
.br
.cs 9 off