summaryrefslogtreecommitdiff
path: root/support/vvcode/doc/vvfiles.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/vvcode/doc/vvfiles.tex')
-rw-r--r--support/vvcode/doc/vvfiles.tex1287
1 files changed, 1287 insertions, 0 deletions
diff --git a/support/vvcode/doc/vvfiles.tex b/support/vvcode/doc/vvfiles.tex
new file mode 100644
index 0000000000..bf019f4ddb
--- /dev/null
+++ b/support/vvcode/doc/vvfiles.tex
@@ -0,0 +1,1287 @@
+@c *************************************************************************
+@c CHAPTER: Definition of VVcode-related file formats
+@c *************************************************************************
+@c node-name, next, previous, up
+@node File Formats, File Formats, Top, Top
+@chapter Definition of VVcode-related file formats
+
+
+@c =========================================================================
+@c SECTION: Format of the VVE file
+@c =========================================================================
+@section Format of the VVE file
+
+A VVE file consists of three logical sections in the following logical
+format:
+
+@example
+<VVE file> ::= <initial preamble>
+ <encoded data lines>
+ <terminal postamble>
+@end example
+
+The @code{<initial preamble>} and @code{<terminal postamble>} sections
+contain VVE "header" lines used to record and control the characteristics
+of the encoding/decoding process. The @code{<encoded data lines>} section
+contains the data from the original file, encoded using the VVcode scheme.
+
+It is sometimes desirable to transmit the VVE file in more than one part,
+so the logical format is extended to cater for multi-part files:
+
+@example
+<first part> ::= <initial preamble>
+ <encoded data lines>
+ <continuation postamble>
+
+<middle part> ::= <continuation preamble>
+ <encoded data lines>
+ <continuation postamble>
+
+<last part> ::= <continuation preamble>
+ <encoded data lines>
+ <terminal postamble>
+@end example
+
+There is always one @code{<first part>} and one @code{<last part>} part in
+a multi-part VVE file. There may be zero (for a two part file) or more
+@code{<middle part>} parts.
+
+The sections are described in more detail below.
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: Line Prefix and Suffix
+@c -------------------------------------------------------------------------
+@subsection Line Prefix and Suffix
+@itemize @bullet
+ @item each line has a "Vv" prefix and "V" suffix
+
+ @item prefix - elimination of mailer lines
+
+ @item postfix - avoid space stripping by certain mailers
+@end itemize
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: Preamble Sections
+@c -------------------------------------------------------------------------
+@subsection Preamble Sections
+The preamble sections are used to initialize VVdecode before it starts to
+decode the encoded file data. Each preamble consists of a set of VVE
+header lines, each specifying a particular parameter relevant to the
+encoding/decoding operation. Each preamble section comprises a set of
+optional header lines followed by the set of required header lines. the
+syntax and use of the header lines is described in section 1.4.
+
+
+@subsubsection Preamble
+The initial preamble is used to initialize VVdecode parameters before it
+starts to decode the encoded file (e.g. the file mode and timestamp). The
+logical format of this section is:
+
+@example
+<initial preamble> ::= <optional initialization headers>
+ <begin header>
+@end example
+
+The @code{mode}, @code{format} and optional headers may be in any order,
+but the @code{begin} header must be the last header in this preamble
+section. None, any or all of the following optional headers may be present
+in the initial preamble section:
+
+@example
+<optional initializiation headers> ::= <characterset header>
+ <comment header>
+ <decodeversion header>
+ <format header>
+ <mode header>
+ <operatingsystem header>
+ <recordlength header>
+ <table header>
+ <timestamp header>
+@end example
+
+Note that only the @code{comment} header line may appear more than once in
+this section.
+
+@subsubsection Continuation Preamble
+
+The initial preamble is used to reset certain VVdecode parameters before it
+starts to decode the next section of the VVE file. The logical format of
+this section is:
+
+@example
+<continuation preamble> ::= <optional continuation headers>
+ <skipfrom header>
+@end example
+
+The optional headers may be in any order, but the @code{skipfrom} header
+must be the last header in this preamble section. None, any or all of the
+following optional headers may be present in this section:
+
+@example
+<optional initializiation headers> ::= <comment header>
+ <table header>
+@end example
+
+Note that only the @code{comment} header line may appear more than once in
+this section.
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: Postamble Sections
+@c -------------------------------------------------------------------------
+@subsection Postamble Sections
+The preamble sections are used to initialize VVdecode before it starts to
+decode the encoded file data. Each preamble consists of a set of VVE
+header lines, each specifying a particular parameter relevant to the
+encoding/decoding operation. Each preamble section comprises a set of
+optional header lines followed by the set of required header lines.
+
+@subsubsection Postamble
+[TODO] put in some text here
+@example
+<continuation postamble> ::= <skipto header>
+ <comment header>
+@end example
+
+The @code{comment} header line is optional and may appear more than once in
+this section.
+
+@subsubsection Terminal Postamble
+[TODO] put in some text here
+@example
+<continuation preamble> ::= <end header>
+ <optional terminal headers>
+
+<optional initializiation headers> ::= <bytecount header>
+ <comment header>
+ <crc32 header>
+@end example
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: Encoded Data Lines
+@c -------------------------------------------------------------------------
+@subsection Encoded Data Lines
+[TODO] put in some text here
+@itemize @bullet
+ @item describe what these lines are used for
+
+ @item format of the encoded line
+
+ @item termination of each section of encoded data (zero length line)
+
+ @item describe the different underlying data formats for fixed, stream
+ and variable format records
+@end itemize
+
+
+@c =========================================================================
+@c SECTION: VVE Header Lines
+@c =========================================================================
+@section VVE Header Lines
+
+A VVE header line takes the form
+
+@example
+<header-name> <parameter-1> <parameter-2> ... <parameter-N>
+@end example
+
+Most headers take only one parameter and parameters are normally separated
+by whitespace, though certain headers (e.g. @code{begin}) take more than one
+parameter and can include whitespace in the parameters. The format of each
+of the VVE header lines is described below. Two important symbols used in
+the description are:
+
+@table @code
+ @item <WS>
+ used to denote whitespace which may include spaces, tabs but not
+ the end of the line. The syntax
+
+ @example
+ xyz <WS> parameter <WS> <EOL>
+ @end example
+
+ states that header @code{xyz} takes a parameter which starts at the
+ first non-whitespace character after the @code{xyz} header name and
+ is terminated by the first whitespace character after that or the
+ end of line. This syntax is used to specify parameters which do
+ not contain whitespace.
+
+ @item <EOL>
+ used to denote the end of the line. The syntax
+
+ @example
+ xyz <WS> parameter <EOL>
+ @end example
+
+ states that header @code{xyz} takes a parameter which starts at the
+ first non-whitespace character after the @code{xyz} header name and
+ is terminated by the end of the line. This format would be used to
+ specify that parameters can include whitespace.
+
+ @item <NXT-HDR>
+ used to denote the next VVE header in the file. The syntax
+
+ @example
+ xyz <WS> parameter <NXT-HDR>
+ @end example
+
+ states that the header @code{xyz} takes a parameter which starts at
+ the first non-whitespace character after the @code{xyz} header
+ name and is terminated by the start of the next VVE header. This
+ format would be used to specify that parameters can span several
+ lines.
+
+ NOTE: the @code{<EOL>} characters are removed when the contents of
+ the lines are joined together.
+@end table
+
+Following is a detailed description of each VVE header. For each header
+there is a set of headings in the format shown below for the @code{example}
+header.
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: @code{example}
+@c -------------------------------------------------------------------------
+@page
+@subsection @code{example}
+
+@table @strong
+ @item Purpose:
+ Brief summary of the purpose of this header.
+
+ @item Location:
+ Describe where in the VVE file that this header will be found. The
+ locations are:
+
+ @itemize @bullet
+ @item initial preamble
+ @item continuation preamble
+ @item continuation postamble
+ @item terminal postamble
+ @end itemize
+
+ Also indicated is whether the header is required or optional.
+
+ @item Syntax:
+ @code{example <WS> parameter <WS> <EOL>}
+
+ This part shows the syntax of the header including the header name,
+ the number of parameters and the delimiters used to separate the
+ parameters.
+
+ @item Remarks:
+ This part provides extra information on the use of the header and
+ includes any limits that are imposed on the parameter value.
+
+ @item VVencode:
+ The header will be written to the VVE file by Vvencode and this
+ part describes the circumstances under which VVencode will write
+ the header line.
+
+ @item VVdecode:
+ This part describes how VVdecode should behave when it encounters
+ the header in a VVE file. In addition, specific processing rules
+ are documented for specific cases, namely:
+
+ @table @code
+ @item OK
+ what VVdecode should do if a valid header line is found in
+ the VVE file.
+
+ @item MISSING
+ what VVdecode should do if the header line was not found in
+ the VVE file.
+
+ @item INVALID
+ what VVdecode should do if the header line was found, but
+ with missing or invalid parameter values.
+ @end table
+
+ @item Example:
+ @code{example parameter}
+
+ Here you'll find a simple example of a valid example header line.
+@end table
+
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: @code{begin}
+@c -------------------------------------------------------------------------
+@page
+@subsection @code{begin}
+@table @strong
+ @item Purpose:
+ Signifies the absolute start of the VVencoded data.
+
+ @item Location:
+ Initial preamble (required).
+
+ @item Syntax:
+ @code{begin <WS> file-specification <EOL>}
+
+ @item Remarks:
+ The file specification may include spaces, though leading and
+ trailing spaces will be lost. There is no restriction on the
+ characters used in the file specification, but characters outside
+ the VVcode default encoding table may be corrupted when passing
+ through mail gateways or systems with differing character sets.
+
+ @item VVencode:
+ The file specification recorded in the VVE file is usually derived
+ from the input file specification stripped of any preamble or
+ postamble components and will therefore consist only of a name
+ and/or extension component. The value recorded can be explicitly
+ specified with the @code{header_filespec} command qualifier.
+
+ @item VVdecode:
+ VVdecode will use the file specification recorded to construct the
+ default file specification for the output file. If the output file
+ is specified on the VVdecode command line, the value specified on
+ the @code{begin} header will only be used if the implementation of
+ VVcode for the operating system has been defined to use "sticky
+ defaults".
+
+ The file specification may have been derived from a different
+ operating system and may therefore be invalid on the local system.
+ Before it is used VVdecode will convert the file specification to
+ one that is valid.
+
+ Processing rules:
+
+ @table @code
+ @item OK
+ If required, convert the file specification so that it is
+ legal on the local operating system and use the legal value
+ as the default file specification for the output file.
+
+ @item MISSING
+ Issue a fatal error message and stop.
+
+ @item INVALID
+ Issue a fatal error message and stop.
+ @end table
+
+ @item Example:
+ @code{begin input-file.txt}@*
+ @code{begin input file name with spaces}
+@end table
+
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: @code{bytecount}
+@c -------------------------------------------------------------------------
+@page
+@subsection @code{bytecount}
+@table @strong
+ @item Purpose:
+ Records the total number of bytes read by VVencode.
+
+ @item Location:
+ Final postamble (optional).
+
+ @item Syntax:
+ @code{bytecount <WS> total-bytes-read <WS> <EOL>}
+
+ @item Remarks:
+ The total is a positive signed 32 decimal bit number and must
+ therefore be in the range 0 - 2147483647. On systems which
+ differentiate between binary and text files, this number is likely
+ to be dependent on the mode (i.e. binary/text) used to read and
+ encode the file.
+
+ @item VVencode:
+ VVencode keeps a cumulative total of the bytes read and record this
+ total in the terminal postamble of VVE file.
+
+ @item VVdecode:
+ VVdecode keeps a cumulative total of the bytes decoded and written
+ and compare it with the VVE recorded value as a confidence check.
+
+ Processing rules:
+
+ @table @code
+ @item OK
+ Compare the VVE recorded value with the total bytes written
+ by VVdecode. Issue a warning if the two totals are
+ different.
+
+ @item MISSING
+ Don't attempt the comparison.
+
+ @item INVALID
+ Issue a non-fatal error message and assume that the header
+ is missing.
+ @end table
+
+ @item Example:
+ @code{bytecount 8388608}
+@end table
+
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: @code{characterset}
+@c -------------------------------------------------------------------------
+@page
+@subsection @code{characterset}
+@table @strong
+ @item Purpose:
+ Records the character set of the VVencoded data.
+
+ @item Location:
+ Initial preamble (optional).
+
+ @item Syntax:
+ @code{characterset <WS> charset-string <WS> <EOL>}
+
+ @item Remarks:
+ The parameter string records the character set of the encoded data
+ in the VVE file. There are no formal controls on the string to use
+ for a particular character set, the string is simply compared
+ against a local value. Eventually, an informal directory of
+ character set strings may evolve.
+
+ @item VVencode:
+ VVencode will record the character set of the encoded data which
+ under normal circumstances the character set will be the local
+ character set for the operating system. If the
+ @code{translation_file} command line qualifier is specified,
+ VVencode will translate the original data from the local character
+ set to a new character set specified by the translation file. In
+ this case, VVencode will record the new character set.
+
+ @item VVdecode:
+ VVdecode uses this header to determine whether the encoded data in
+ the VVE file is of the same character set as that used on the local
+ operating system. If the character sets are different, a warning
+ will be issued.
+
+ If the @code{translation_file} command line qualifier is specified,
+ VVdecode will translate the VVE encoded data to a new character set
+ specified by the translation file. In this case, VVdecode will
+ compare the VVE file character set with the "from" character set
+ expected by the translation file.
+
+ Processing rules:
+
+ @table @code
+ @item OK
+ Compare the VVE character set with the local operating
+ system character set (or the translation file "from"
+ character set if appropriate). Issue a warning message if
+ the two character sets are different.
+
+ @item MISSING
+ Assume that the VVE character set is the same as the local
+ operating system character set.
+
+ @item INVALID
+ Issue a non-fatal error message and assume that the header
+ is missing.
+ @end table
+
+ @item Example:
+ @code{characterset ASCII}
+@end table
+
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: @code{comment}
+@c -------------------------------------------------------------------------
+@page
+@subsection @code{comment}
+@table @strong
+ @item Purpose:
+ Records commentary information deemed to be of sufficient
+ importance to warrant displaying it when VVdecoding the file.
+
+ @item Location:
+ Initial preamble, continuation preamble, continuation postamble,
+ final postamble (optional).
+
+ @item Syntax:
+ @code{comment <WS> comment-string <EOL>}
+
+ @item Remarks:
+ The comment string is free form text, but care should be taken not
+ to use characters that may be corrupted by mail gateways or when
+ passing through systems with different character sets.
+
+ @item VVencode:
+ VVencode will record information deemed (by the programmer) to be
+ important and worth flagging to the VVdecode user. Currently this
+ facility is only used to record the original character set when
+ VVencode has been invoked with @code{translation_file} command line
+ qualifier to convert the original data to a new character set
+ before VVencoding.
+
+ @item VVdecode:
+ Generally VVdecode will display any comments encountered on the log
+ file.
+
+ Processing rules:
+
+ @table @code
+ @item OK
+ If the @code{log} command line qualifier was specified,
+ display the comment on the log file, otherwise ignore the
+ comment.
+
+ @item MISSING
+ No action.
+
+ @item INVALID
+ Issue a non-fatal error message and ignore the comment.
+ @end table
+
+ @item Example:
+ @code{comment This file is only useful on Unix systems}@*
+ @code{Original character set was `EBCDIC'}
+@end table
+
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: @code{crc32}
+@c -------------------------------------------------------------------------
+@page
+@subsection @code{crc32}
+@table @strong
+ @item Purpose:
+ Records the 32 bit CRC of the bytes read by VVencode.
+
+ @item Location:
+ Final postamble (optional).
+
+ @item Syntax:
+ @code{crc32 <WS> input-file-crc32 <WS> <EOL>}
+
+ @item Remarks:
+ The CRC value is an unsigned 32 bit hexadecimal number and must
+ therefore be in the range 0 - FFFFFFFF. On systems which
+ differentiate between binary and text files, this number is likely
+ to be dependent on the mode (i.e. binary/text) used to read and
+ encode the file.
+
+ The CRC polynomial used is the same as that used by the popular ZIP
+ and ARJ archiving programs. When encoding in binary mode, the CRC
+ recorded should be identical to that computed by ARJ and ZIP.
+
+ @item VVencode:
+ VVencode computes a 32 bit CRC of the bytes read and record this
+ CRC in the terminal postamble of VVE file.
+
+ @item VVdecode:
+ VVdecode computes a 32 bit CRC of the bytes decoded and written and
+ compare it with the VVE recorded value as a confidence check.
+
+ Processing rules:
+
+ @table @code
+ @item OK
+ Compare the VVE recorded value with the total bytes written
+ by VVdecode. Issue a warning if the two CRCs are
+ different.
+
+ @item MISSING
+ Don't attempt the comparison.
+
+ @item INVALID
+ Issue a non-fatal error message and assume that the header
+ is missing.
+ @end table
+
+
+ @item Example:
+ @code{crc32 1e0cb8a7}
+@end table
+
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: @code{decodeversion}
+@c -------------------------------------------------------------------------
+@page
+@subsection @code{decodeversion}
+@table @strong
+ @item Purpose:
+ Records the minimum major version number of VVcode required to
+ decode the VVE file.
+
+ @item Location:
+ Initial preamble (optional).
+
+ @item Syntax:
+ @code{decodeversion <WS> min-decode-version <WS> <EOL>}
+
+ @item Remarks:
+ The minimum decode version is a positive integer and records the
+ minimum major version of VVcode required to decode the VVE file.
+
+ The VVcode version number has a "major" and "minor" version. For
+ example, VVcode version 1.2 has a major version of 1 and a minor
+ version of 2 and the header
+
+ @example
+ decodeversion 2
+ @end example
+
+ signifies that VVdecode version 2.0 or later is required to decode
+ the file.
+
+ Whenever a change is made to the VVE file format that is not
+ backwards compatible, the major version number of VVcode will be
+ incremented.
+
+ @item VVencode:
+ VVencode records the minimum major version number required to
+ decode the VVE file in the initial preamble of the VVE file.
+
+ @item VVdecode:
+ VVdecode uses the recorded value to check whether it can decode the
+ file.
+
+ Processing rules:
+
+ @table @code
+ @item OK
+ Check that the major version of VVdecode is not less than
+ the recorded value. If it is, issue a fatal error message
+ and stop.
+
+ @item MISSING
+ Assume that the current version of VVdecode is OK and
+ proceed.
+
+ @item INVALID
+ Issue a non-fatal error message and assume that the header
+ is missing.
+ @end table
+
+ @item Example:
+ @code{decodeversion 1}
+@end table
+
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: @code{end}
+@c -------------------------------------------------------------------------
+@page
+@subsection @code{end}
+@table @strong
+ @item Purpose:
+ Signifies the absolute end of the VVencoded data.
+
+ @item Location:
+ Final postamble (required).
+
+ @item Syntax:
+ @code{end <WS> <EOL>}
+
+ @item Remarks:
+ This header signifies that there are no more encoded data lines to
+ process and that the terminal preamble is about to start.
+
+ @item VVencode:
+ After the complete input file has been encoded, VVencode will write
+ a "zero length" encoded line followed by the @code{end} header line
+ and the terminal postamble section.
+
+ @item VVdecode:
+ After reading this header, VVdecode will cease decoding the encoded
+ data bytes and start to read the terminal postamble.
+
+ Processing rules:
+
+ @table @code
+ @item OK
+ Cease decoding the encoded data bytes and start to read the
+ terminal postamble.
+
+ @item MISSING
+ Issue a fatal error message and stop.
+
+ @item INVALID
+ This shouldn't be possible, but if so issue a fatal error
+ message and stop.
+ @end table
+
+ @item Example:
+ @code{end}
+@end table
+
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: @code{format}
+@c -------------------------------------------------------------------------
+@page
+@subsection @code{format}
+@table @strong
+ @item Purpose:
+ Records the file organization format of the VVencoded file.
+
+ @item Location:
+ Initial preamble (optional).
+
+ @item Syntax:
+ @code{format <WS> format-string <WS> <EOL>}
+
+ @item Remarks:
+ The format string must be one of "fixed", "stream" or "variable",
+ though the value may be lower, upper or mixed case. VVcode
+ supports these three type of file organization, though not all
+ operating systems will support all three. Note that the internal
+ format of the encoded data will depend on the file organization.
+
+ @item VVencode:
+ VVencode records the organization of the encoded file. Note that
+ this is the format used by VVencode to read the file which may not
+ necessarily be the real format of the original file.
+
+ @item VVdecode:
+ VVdecode will use this header to identify the internal format of
+ the encoded data to enable it to be decoded correctly. The format
+ will also be used as the default format to create the output file.
+
+ If the VVE file format is not supported by the local operating
+ system, VVdecode will create the output file using the default file
+ format for the operating system. The @code{format} command line
+ qualifier may be used to override the format of the output file.
+
+ Processing rules:
+
+ @table @code
+ @item OK
+ Use the header value to decode the encoded data bytes and
+ to determine the default format of the output file.
+
+ @item MISSING
+ Issue a fatal error message and stop.
+
+ @item INVALID
+ Issue a fatal error message and stop.
+ @end table
+
+ @item Example:
+ @code{format stream}
+@end table
+
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: @code{mode}
+@c -------------------------------------------------------------------------
+@page
+@subsection @code{mode}
+@table @strong
+ @item Purpose:
+ Records the mode of the VVencoded file.
+
+ @item Location:
+ Initial preamble (optional).
+
+ @item Syntax:
+ @code{mode <WS> mode-string <WS> <EOL>}
+
+ @item Remarks:
+ The format string must be one of "binary" or "text", though the
+ value may be lower, upper or mixed case. VVcode supports both
+ binary and text mode files, though not all operating systems will
+ support both modes. The mode will often influence the default file
+ format used by the operating system. Most operating systems
+ distinguish between text and binary files, though Unix is a notable
+ exception.
+
+ @item VVencode:
+ VVencode records the mode of the encoded file. Note that this is
+ the mode used by VVencode to read the file which may not
+ necessarily be the real mode of the original file.
+
+ @item VVdecode:
+ VVdecode will use this header to mode of the encoded file. The
+ mode will also be used as the default mode for the output file.
+
+ If the VVE file mode is not supported by the local operating
+ system, VVdecode will create the output file using the default file
+ mode for the operating system. The @code{mode} command line
+ qualifier may be used to override the mode of the output file.
+
+ Processing rules:
+
+ @table @code
+ @item OK
+ Use the header value to determine the default mode of the
+ output file.
+
+ @item MISSING
+ Issue a fatal error message and stop.
+
+ @item INVALID
+ Issue a fatal error message and stop.
+ @end table
+
+ @item Example:
+ @code{mode binary}
+@end table
+
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: @code{operatingsystem}
+@c -------------------------------------------------------------------------
+@page
+@subsection @code{operatingsystem}
+@table @strong
+ @item Purpose:
+ Records the operating system on which the file was VVencoded.
+
+ @item Location:
+ Initial preamble (optional).
+
+ @item Syntax:
+ @code{operatingsystem <WS> operating-system-name <WS> <EOL>}
+
+ @item Remarks:
+ The parameter string records the operating system on which the
+ version of VVencode used to create the VVE file was running. There
+ are no formal controls on the string to use for a particular
+ character set, the string is simply compared against a local value.
+ The string is coded into the VVcode machine dependent header file
+ so this shouldn't be too much of a problem.
+
+ It is useful for the decoder to know whether the file was encoded
+ on the same operating system to influence the decoding process.
+ For example, if the original operating system is different any
+ private data would usually be ignored.
+
+ @item VVencode:
+ VVencode will record the string for the local operating system as
+ coded in the machine dependent header file (machine.h).
+
+ @item VVdecode:
+ VVdecode will compare the header value with that recorded for the
+ local operating system in the machine dependent header file
+ (machine.h) to determine whether the original file was encoded on
+ the same operating system.
+
+ Processing rules:
+
+ @table @code
+ @item OK
+ Compare the header value with the local operating system
+ string to determine whether the two operating systems are
+ different. Parts of the decoding process will be affected
+ by this decision.
+
+ @item MISSING
+ Assume that the operating system on which the file was
+ encoded is the same as the local operating system.
+
+ @item INVALID
+ Issue a non-fatal error message and assume that the header
+ is missing.
+ @end table
+
+ @item Example:
+ @code{operatingsystem MS-DOS}@*
+ @code{operatingsystem Unix}
+@end table
+
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: @code{recordlength}
+@c -------------------------------------------------------------------------
+@page
+@subsection @code{recordlength}
+@table @strong
+ @item Purpose:
+ Records the maximum and longest length records in the VVencoded
+ file.
+
+ @item Location:
+ Initial preamble (optional).
+
+ @item Syntax:
+ @code{recordlength <WS> max-rec-len <WS> long-rec-len <WS> <EOL>}
+
+ @item Remarks:
+ Both versions of the record length must be either a decimal number
+ within the VVcode supported range of 0 - 65535 or -1. The value -1
+ has a special meaning for each of the record lengths:
+
+ max-rec-len the maximum record length is unknown or there is no
+ explicit maximum record length for this file
+ (this usually defaults to the maximum record
+ length supported by the operating system).
+
+ lng-rec-len the length of the longest record in the file is
+ unknown.
+
+ The record length is usually relevant only for fixed and variable
+ length record format files. The maximum record length is that
+ allowed by the operating system for the file, whereas the longest
+ is the length of the longest record in the file. For variable
+ length record files the longest length must be less than or equal
+ to the maximum record length, whereas for fixed length record
+ files, the longest record length should be equal to the maximum
+ record length.
+
+ @item VVencode:
+ Where possible, VVencode will attempt to determine these parameters
+ and record them in the VVE file. Note that the @code{recordlength}
+ header is in the initial preamble so these parameters must be
+ determined before the file is opened for encoding. The value may
+ be overridden by the @code{record_length} command line qualifier.
+
+ @item VVdecode:
+ If the output file format is fixed or variable length records,
+ Vvdecode will use these values to create a file of the correct
+ type. The parameter values will be checked, even if they will not
+ be used during the subsequent decoding activities. If the
+ parameter values are unknown or invalid, VVdecode will use default
+ values appropriate to the file format and the local operating
+ system.
+
+ Note that the record length might be valid for the VVE file (i.e.
+ in the range 0 - 65535), but be invalid for the file format and
+ local operating system.
+
+ Processing rules:
+
+ @table @code
+ @item OK
+ Use the values to create a file of the correct type and
+ format.
+
+ @item MISSING
+ Use appropriate default values for the file format and
+ local operating system.
+
+ @item INVALID
+ Issue a non-fatal error message and assume that the header
+ is missing.
+ @end table
+
+ @item Example:
+ @code{recordlength -1 132}@*
+ @code{recordlength 255 -1}@*
+ @code{recordlength 32256 32256}
+@end table
+
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: @code{skipfrom}
+@c -------------------------------------------------------------------------
+@page
+@subsection @code{skipfrom}
+@table @strong
+ @item Purpose:
+ Signifies the start of a segment of VVencoded data.
+
+ @item Location:
+ Continuation preamble (required).
+
+ @item Syntax:
+ @code{skipfrom <WS> part-number <WS> file-specification <EOL>}
+
+ @item Remarks:
+ The @code{skipfrom} header is used when VVencode creates a
+ multi-part VVE file and is analogous to the @code{begin} header in
+ the first part. The part-number parameter records the number of
+ the previous VVE file part. Both parameters are included in the
+ header to provide a reasonable degree of confidence that the wanted
+ part of the encoded file has been found.
+
+ @item VVencode:
+ A @code{skipfrom} header will only be written if VVencode was
+ invoked with the @code{split_size} command line qualifier and the
+ VVE file is long enough to require more than one part. The file
+ specification recorded in the VVE file is the same as that in the
+ @code{begin} header. The number of the previous VVE file part is
+ also recorded.
+
+ @item VVdecode:
+ VVdecode will check that the file specification and part number
+ match those expected for the next part. If both do not match,
+ VVdecode will continue to look for the wanted VVE file part.
+
+ Processing rules:
+
+ @table @code
+ @item OK
+ If the wanted part has been found, start to decode the next
+ section of encoded data lines. If this @code{skipfrom}
+ does not correspond to the wanted part, continue to search
+ for the correct @code{skipfrom} header.
+
+ @item MISSING
+ Issue a fatal error message and stop.
+
+ @item INVALID
+ Issue a non-fatal error message and ignore the header.
+ @end table
+
+ @item Example:
+ @code{skipfrom 2 input-file.txt}@*
+ @code{skipfrom 2 file name with spaces}
+@end table
+
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: @code{skipto}
+@c -------------------------------------------------------------------------
+@page
+@subsection @code{skipto}
+@table @strong
+ @item Purpose:
+ Signifies the end of a segment of VVencoded data with more data
+ still to come.
+
+ @item Location:
+ Continuation postamble (required).
+
+ @item Syntax:
+ @code{skipto <WS> part-number <WS> <EOL>}
+
+ @item Remarks:
+ The @code{skipto} is used when VVencode creates a multi-part VVE
+ file and is analogous to the @code{end} header in the last part.
+ The parameter records the number of the next VVE file part.
+
+ @item VVencode:
+ A @code{skipto} header will only be written if VVencode was invoked
+ with the @code{split_size} command line qualifier and the VVE file
+ is long enough to require more than one part. The number of the
+ next VVE file part is recorded.
+
+ After the section of encoded files has been completed, VVencode
+ will write a "zero length" encoded line followed by the @code{skipto}
+ header line.
+
+ @item VVdecode:
+ After reading this header, VVdecode will check that the part number
+ recorded is correct. If it is, VVdecode will start to search for
+ the next VVE file part.
+
+ Processing rules:
+
+ @table @code
+ @item OK
+ Start to search for the next VVE file part.
+
+ @item MISSING
+ Issue a fatal error message and stop.
+
+ @item INVALID
+ Issue a fatal error message and stop.
+ @end table
+
+ @item Example:
+ @code{skipto 2}
+@end table
+
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: @code{table}
+@c -------------------------------------------------------------------------
+@page
+@subsection @code{table}
+@table @strong
+ @item Purpose:
+ Records the character table used to encode the file data bytes.
+
+ @item Location:
+ Initial preamble, continuation preamble (optional).
+
+ @item Syntax:
+ @code{table <WS> table-contents <NXT-HDR>}
+
+ @item Remarks:
+ The encoding table is recorded along with the data to enable the
+ decoding program to detect any simple character translations or
+ corruptions that may have occurred during the transmission of the
+ VVE file. There is no restriction on the characters that may be
+ used in the encoding table, but it is sensible to use characters
+ that are normally immune to network corruptions.
+
+ The table comprises 64 characters which are used to represent the
+ codes 0 - 63 of the VVcode encoding character set. The table
+ contents may be presented on the same line as the @code{table}
+ header or preferably split over several lines to avoid the wrapping
+ of long lines performed by some mail gateways. If the table
+ contents are split over several lines, the newline characters are
+ removed before the lines are concatenated. The next valid header
+ line encountered will terminate the reading of the table contents.
+
+ Note that whitespace characters at the end of a line may be removed
+ in transmission by certain systems that strip trailing whitespace
+ from files. It is strongly recommended that whitespace characters
+ are not used in encoding tables.
+
+ @item VVencode:
+ VVencode will record the contents of the encoding table used to
+ encode the original file.
+
+ @item VVdecode:
+ VVdecode will use the contents of the encoding table to construct
+ (by inversion) the table to decode the VVE file data. The table
+ contents will be checked for length and repeated characters which
+ would prevent the construction of a valid decoding table.
+
+ Processing rules:
+
+ @table @code
+ @item OK
+ Use the table contents to construct the decoding table and
+ thus decode the VVE file.
+
+ @item MISSING
+ Assume the default VVcode table.
+
+ @item INVALID
+ Issue a fatal error message and stop.
+ @end table
+
+ @item Example:
+ @code{table}@*
+ @code{+-0123456789}@*
+ @code{abcdefghijklmnopqrstuvwxyz}@*
+ @code{ABCDEFGHIJKLMNOPQRSTUVWXYZ}@*
+ @code{begin file-specification}
+@end table
+
+
+
+@c -------------------------------------------------------------------------
+@c SUBSECTION: @code{timestamp}
+@c -------------------------------------------------------------------------
+@page
+@subsection @code{timestamp}
+@table @strong
+ @item Purpose:
+ Records the modification time of the VVencoded file.
+
+ @item Location:
+ Initial preamble (optional).
+
+ @item Syntax:
+ @code{timestamp <WS> VVcode-timestamp <WS> <EOL>}
+
+ @item Remarks:
+ This header is used to record the modification time of the encoded
+ file so that it can be preserved when the file is decoded. The
+ timestamp is recorded in the format:
+
+ @example
+ YYYY.MM.DD-HH:MM:SS
+ @end example
+
+ where each of the components are defined as:
+
+ @table @code
+ @item YYYY
+ year (range: 1970 - 2037)
+ @item MM
+ month (range: 01 -12)
+ @item DD
+ day of month (range: 01 - 31)
+ @item HH
+ hour (range: 00 - 23)
+ @item MM
+ minutes (range: 00 - 59)
+ @item SS
+ seconds (range: 00 - 59)
+ @end table
+
+ The time is based on the Unix internal time format which represents
+ the time as a signed 32 bit integer recording the number of seconds
+ since 1-Jan-1970 00:00 GMT. The VVE timestamp recorded must be in
+ the range:
+
+ 1970.01.01-00:00:00 to 2037.12.31-23:59:59 GMT
+
+ Some operating systems support a wider range of system times (e.g.
+ VAX/VMS) and some support only a narrower range (e.g. MS-DOS) but
+ implementations of VVcode for these systems must ensure that
+ timestamps in the VVcode range can be handled when encoding and
+ decoding.
+
+ Note: The timestamp is always recorded as a GMT (or Coordinated
+ Universal Time) time.
+
+ @item VVencode:
+ VVencode will record the modification time of the encoded file or
+ that specified with the @code{timestamp} command line qualifier.
+ If VVencode cannot determine the modification time of the encoded
+ file and the time is not specified using the @code{timestamp}
+ command line qualifier, the @code{timestamp} VVE header line will
+ not be recorded. If the timestamp of the file is outside the range
+ of times supported by the VVE file, VVencode should either
+ "truncate" the time value to a value that is within the range or
+ not record the timestamp. In either case, a warning should be
+ issued.
+
+ @item VVdecode:
+ VVdecode will use the @code{timestamp} header value to set the
+ modification of the decoded file to that recorded. If the
+ implementation of VVdecode is unable to do this, it should issue a
+ warning.
+
+ If the timestamp recorded in the VVE file is outside the range of
+ times supported by the operating system, VVdecode should either
+ "truncate" the time value to a value that is within the range or
+ not set the file timestamp. In either case, a warning should be
+ issued.
+
+ Processing rules:
+
+ @table @code
+ @item OK
+ Use the header value to set the modification time of the
+ decoded file.
+
+ @item MISSING
+ Do not attempt to set the modification time of the output
+ file (it will probably be created with a timestamp of the
+ current date and time).
+
+ @item INVALID
+ Issue a non-fatal error message and assume that the header
+ is missing.
+ @end table
+
+ @item Example:
+ @code{timestamp 1991.12.01-12:10:34 GMT}
+@end table
+
+
+@c =========================================================================
+@c SECTION: VVE encoded data format
+@c =========================================================================
+@section VVE encoded data format
+
+
+@c =========================================================================
+@c SECTION: XLT translation file format
+@c =========================================================================
+@section XLT translation file format
+
+
+@c =========================================================================
+@c SECTION: TBL encoding table file format
+@c =========================================================================
+@section TBL encoding table file format
+
+