@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
