diff options
Diffstat (limited to 'support/vvcode/doc/vvfiles.tex')
-rw-r--r-- | support/vvcode/doc/vvfiles.tex | 1287 |
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 + + |