$ PEEK/FORMAT in_file out_file PEEK> FORMAT in_file out_file
The PEEK/FORMAT command may be used to convert the format of log
files so that they may be more easily displayed or printed.
The Peek/Spy FORMAT subcommand converts a log file containing
terminal-control sequences (which might otherwise be difficult
to display, print or analyze) into distinct pages of plain-text
output, It also separates out redundant output (e.g., when a
later output segment overlays an earlier output segment).
Example:
$ PEEK /USER=SMITH /LOG=SMITH.LOG ! Make Peek log file.
$! Watch SMITH for a while, then exit from PEEK.
$ PEEK /FORMAT SMITH.LOG SMITH.FMT ! Format log file.
The output file (SMITH.FMT) will contain screens which are in
a plain-text sequential format. This is useful for typing,
printing, or searching.
Each output screen is a series of 24 lines (by default, or as
specified by /PAGE=n). The initial output-screen width can be
specified with /WIDTH=n (the default is 80 columns).
The actions of, and some qualfiers for, the FORMAT subcommand
differ for AXP and VAX. See the PEEK Commands FORMAT Subtopics:
AXP-Only and VAX-Only.
1 – Overview
There is an inherent problem in creating an ASCII-stream log file of terminal output, whether it is created by PEEK/LOG, SET HOST/LOG or KERMIT's LOG SESSION command, etc. The problem is that records in a stream output file either have an arbitrary length (as do those made by KERMIT) or no maximum length at all. In the case where an arbitrary length is imposed on the log file, you will see extra carriage-returns embedded in the file when it is typed. In the case of PEEK, which does NOT arbitrarily end a line after 256 bytes (or some such size), the TYPE command, EDT, TPU, etc., all have varying degrees of success in displaying the file's contents. VMS's TYPE command will usually abort if you attempt to type a file which has records longer than 2048 bytes. EDT and TPU have similar record-length limitations. Thus we have added a format command which will process an arbitrary sequence of text and escape and control sequences into a series of output screens.
2 – AXP-Only
With PEEK/FORMAT on AXP, a full, new, output screen is appended
to the formatted output file whenever any one of the following
conditions occurs:
1. A clear-screen sequence in found in the input file.
2. A selective-erase sequence in found in the input file.
3. The screen is cleared because the screen width is changed.
4. Enough lines are scrolled on the screen that some are about
to be lost off of the top or bottom of the screen.
The output-file format may be varied to take advantage of different
printer formats. The default output format is plain text, but other
formats are available through the /PRINTER_TYPE=keyword qualifier.
The following PRINTER_TYPE keywords are currently defined for AXP:
FILE - For plain text into file (this is the default).
VT100 - For paged output to a VTxxx type terminal.
The output file will have form-feed characters inserted at the page
breaks.
2.1 – Qualifiers
2.1.1 /WIDTH
/WIDTH = page_width Used to specify the initial page width. If /WIDTH is not specified, the default is 80 columns. If /WIDTH is specified without a value, the width of the current terminal is used.
3 – VAX-Only
With PEEK/FORMAT on VAX, a full, new, output screen is appended
to the formatted output file whenever any one of the following
conditions occurs:
1. A clear-screen sequence in found in the input file.
2. A selective-erase sequence in found in the input file.
3. The screen is cleared because the screen width is changed.
4. Enough lines are scrolled on the screen that some are about
to be lost off of the top or bottom of the screen.
5. /CURSOR_FLUSH was specified as a negative number and the
cursor moves up more than the specified number of lines.
6. /CURSOR_FLUSH was specified as a positive number and the
cursor is positioned to the specified line number.
These latter two options can be useful for formatting output from
programs which don't erase the screen, but just re-position the
cursor and overwrite existing text.
The output file format may be varied to take advantage of several
different printer formats. The default output format is plain text,
but other formats are available which will display bolded and
underlined sequences as they originally appeared in the file.
The following PRINTER_TYPE keywords are currently defined on VAX
for use with the /PRINTER_TYPE=keyword qualifier:
FILE - For plain text into file (this is the default).
VT100 - For paged output to a VTxxx type terminal.
DUMB_BS - Overprint BOLD & underline using backspace.
DUMB_CR - Overprint BOLD & underline using carriage-returns.
LA100, LA120, LA180, LA210, LA50, LA75, LN03,
VT200, VT300, VT400
The output file will have form-feed characters inserted at the page
breaks.
By default these form-feeds are inserted on a separate line, but
one can get the form-feeds appended to the last line of text on a
page by using the /[NO]CONTINUOUS_PAGES qualifier. This could be
useful when one wants to use all lines of a page, but the form-
feed on a separate line would cause a page to be skipped between
each page of text.
3.1 – Qualifiers
3.1.1 /CONTINUOUS_PAGES
/[NO]CONTINUOUS_PAGES Specify /CONTINUOUS_PAGES if you want pages separated by a form feed appended to the end of the last line of the page. This is useful when one wants to use all lines of a page, where the form-feed on a separate line could cause a page to be skipped between each page of text. Specify /NOCONTINUOUS_PAGES if you want pages separated by a form feed which is on a line by itself. This is the default.
3.1.2 /CURSOR_FLUSH
/CURSOR_FLUSH=n
Specify a line number which, if the cursor is positioned back
to that line after being on a different line, the current
screen contents will be flushed to the output file.
This is useful for formatting screens which display data over
the top of prior data, rather than clearing the screen before
displaying the new data.
The default value is zero. This means the cursor position
is ignored.
If specified as a negative number, this indicates that, if the
cursor moves up that number of lines, the current screen
contents will be flushed to the output file.
Example:
$ KERMIT ! Start program.
Kermit-32> LOG SESSION PRICES.LOG ! Start log file.
Kermit-32> CONNECT TXA6: ! Connect to modem line.
ATDT-1-800-234-1998 ! Dial DEC's store.
etc.
$ PEEK /FORMAT PRICES.LOG PRICES.LIS /CURSOR_FLUSH=3
When DEC's Electronic Store is accessed to look up prices,
it positions to line 3, outputs a line of price information,
then positions to line 4, etc., until the screen is full.
When you tell it to display the next screen, it repeats this
process. Using /CURSOR_FLUSH=3 tells the FORMAT command to
output the prior screen before figuring out what the next
screen will be.
3.1.3 /FORM_FEED
/[NO]FORM_FEED Specify /FORM_FEED if you wish to have output pages separated by a form feed character. This is the default. Specify /NOFORM_FEED if you do not wish to have output pages separated by a form feed character.
3.1.4 /RECORD_END
/[NO]RECORD_END PEEK/FORMAT tries to intelligently cope with log files which have overly-long lines which have been arbitrary split into more than one log-file record. This is most commonly encountered with Kermit log files, as covered in the PEEK Commands FORMAT Subtopic: Overview. The FORMAT /RECORD_END qualifier specifies that newlines should be inserted between records in the input file. This is the default for all input files, except those with variable-length, maximum 256-byte records and CR carriage- control. Kermit log files have this latter file format. For such files only, the default is /NORECORD_END. Specifying /NORECORD_END directs the FORMAT command not to insert a newline between records if the previous line ends at or before the screen's right margin. This commonly has the effect of concatenating all records in the input file into one continuous stream of input characters, without the FORMAT command adding any newlines. The presumption here is that the log-file contains in it the needed carriage-control characters, and none need to be added at the end of each log-file record.
4 – Qualifiers
4.1 /PAGE
/PAGE = page_length Specify the height of the screen. This value is used to determine where to insert form feeds in the output file. The default value if /PAGE is not specified is 24 lines. If /PAGE is specified without a value, the value defaults to the length of the current terminal. This qualfier should be specified if you are using a 36 or 48 line screen on a VT420 or other terminal.
4.2 /PRINTER_TYPE
/PRINTER_TYPE=keyword /PRINTER_TYPE is used to specify the printer type. The default PRINTER_TYPE is FILE. This produces a plain-text output file with all terminal-control sequences removed. PRINTER_TYPEs available differ for AXP and VAX. for details, see the PEEK Commands FORMAT Subtopics: AXP-Only and VAX-Only.
4.3 /SCREEN_SIZE
/SCREEN_SIZE = page_length Synonymous for /PAGE. See PEEK Commands FORMAT Subtopic: /PAGE.