1 VTL
This program is used to list file(s) on  a  VT100  family  terminal.
The  file(s)  are  displayed  one screen at a time for easy viewing.
Various commands can be entered to change listing parameters  or  to
position  to a particular portion of the file.  Many of the commands
are the same as the Digital editor EDT.   Commands  can  be  entered
either by using keys on the VT100 keypad, or by entering commands to
the prompt at the bottom of the screen.

2 FEATURES
Some of the major features of the program are outlined below:

  1.  Delete the file being displayed.
  2.  Print the file being displayed.
  3.  Split screen mode to display two files.
  4.  CTRL/C detection for aborting searches, etc.
  5.  Write portions of the file being displayed.
  6.  Skipping to the next directory when using wildcards.
  7.  Displaying the file header of the file being displayed.
  8.  Teco compatible see-all mode.
  9.  Search forward/backward for a string.
 10.  Working message displayed when searching.

  Enhancments requested but not implemented yet:

  1.  Backing up to the previous file.
  2.  Swapping to auxillary file with full screen display.
  3.  Initialization file to define the keypad keys.
  4.  /FIND, /RECORD, and /PAGE options at startup.
  5.  Repetition count for commands.

The maximum record size that can be  displayed  is  512  characters.
All  commands have a repetition count of one.  Relative, indexed and
stream LF files are not supported.

2 INSTALLATION
There are three files used  with  this  program.   The  VTL  program
written  in Macro-11, the VTLNATIVE program written in Macro-32, and
the error message file.  These files must be copied to the following
directorys:

  SYS$SYSTEM:VTL.EXE - This is  the  main  program  which  can  be
  started  with  either  the  "MCR  VTL"  or  "RUN SYS$SYSTEM:VTL"
  commands.

  SYS$SYSTEM:VTLNATIVE.EXE - This program is used to  do  the  VMS
  wildcard   lookup   using   the   run   time   library   routine
  LIB$FIND_FILE.   It  is  executed  by  the  VTL   program   from
  compatibility  (PDP-11)  mode  using  the  unsupported  elephant
  directive.  This program  CAN  NOT  be  started  using  the  RUN
  command.  Obviously, this program is not needed for RSX-11M/M+.

  If the native mode routine is not located in SYS$SYSTEM,  define
  the  logical  name SYS$NORDEN pointing to the directory where it
  resides.  If the routine is not found in  either  directory,  an
  error is reported to the terminal, the user is prompted, and the
  program continues using the normal RSX-11M file lookup routines.

  LB:[1,2]RSX11M.MSG  -  This  file  contains  the  RSX-11M  error
  messages.  If the error message file is not located in LB:[1,2],
  the program  attempts  to  lookup  the  file  in  DUA0:[MILLER].
  Unfortunatly,  since  the  error  message routine uses QIO$'s to
  perform directory lookup, a logical name can not be  used.   You
  can  edit  file  RSXMSG.MAC  in  routine  GERMSG to point to any
  alternate   directory   you   want.    You   can't   specify   a
  sub-directory.

2 GETTING_STARTED
  There are three methods of starting the VTL program.   The  sections
  described  below  presume  you  have the following symbol defined in
  your login command file on VMS, or VTL is installed on RSX-11M/M+:

  $ VTL :== $SYS$SYSTEM:VTL

  1.  The most common way of starting the program is to  pass  a  file
      specification  to  the  program on the command line.  When using
      this method, the file(s) specified are displayed and the program
      exits when there are no more files to display.

      Example:
             $ VTL [ROBIN...]A%C*.DAT

      Multiple  file  specifications  separated  by commas can also be
      specified.

      Example:
             $ VTL DL0:[*]*.CMD,DL1:[*]*.CMD

  2.  The second method is to allow the program to prompt for the file
      specification.   Using  this  method allows you to remain in the
      program until you type  CTRL/Z  to  exit.   After  starting  the
      program,  the  screen  is cleared and the "File(s):  " prompt is
      displayed at the bottom of the screen.  At this point, the  file
      specification can be entered.

      Example:
             $ VTL
             (The screen is cleared)
             File(s):

  3.  The last method allows you to use a command file as input to the
      program.   The  command file contains a list of all the files to
      be displayed.  This method is useful when using a  program  such
      as  "DIRECTORY"  to display all files created since a particular
      date.  The length of the command lines can be up to a maximum of
      256  characters.   The  continuation character "-" is allowed at
      the end of a line to continue the command line on the next line.
      If  the  file  extension  isn't specified the default is .CMD on
      RSX-11M and .COM on VAX/VMS.  When the end of the  command  file
      is reached, the program exits.

      Example:
             $ DIRECTORY/NOHEADER/NOTRAILER/SINCE/OUTPUT=TODAY.COM
             $ VTL @TODAY

Once you've started displaying a file, typing the  PF2  key  on  the
keypad  displays the keypad diagram.  There is no other online help.
This document will be converted to the  help  file  format  at  some
point so HELP at DCL level is possible.

2 STARTUP_OPTIONS
There are a number of options which can be specified at startup time
by  specifying  option  on  the  command  line.   The options can be
specified anywhere on the command  line  which  allows  them  to  be
appended  to  the  VTL symbol defined in your login command file (if
desired).

Options can not be specified on the command line when using  command
file  input.  When using command file input, the options must reside
within the command file or before the command  file  line  within  a
command procedure.

All options are preceded with a slash "/"  and  can  be  negated  by
preceding  the  option  with either a minus sign "-" or a "NO".  All
startup options can be changed after the program is started with the
"SET"   command.   If  the  option  is  not  followed  by  the  word
"(default)", then the  option  must  be  specified  to  enable  that
option.  The following are the valid startup options:

3 AVO
The  VT100 has the advanced video option.  If your VT100 doesn't
have  the  AVO,  the  terminal  can only display 14 lines of 132
column text.

3 BINARY
When  displaying  a  binary  file,  the option suppresses escape
seqeuences  and  all  control  characters so the text within the
binary file can be displayed properly.

3 FEXIT
This  controls  whether  the  program automatically displays the
next file or exits at the end of file. If enabled, the user must
type either "EXIT" or "NEXT" to stop displaying the current file.

3 FF
This  controls  whether formfeeds are passed to the VT100.  This
option is useful when the VT100 has a hardcopy attached to allow
formfeeds to skip to the top of a new page.

3 HEADER
Controls  whether  the  file  header  is automatically displayed
before displaying the first page (screen) of the file.  The file
header is displayed in a format similar to the "ANALYZE/RMS" DCL
command.

3 LINES
This controls the number of lines to display on the screen.  The
default  number  of lines displayed is 20 lines if the file name
display is enabled or 22 or it is disabled.  When operating over
a  dialup  modem,  it is often desirable to display fewer lines.
The  command format is "/LINES=n" where "n" can  be from 5 to 20
(or 22 if the file name is disabled).

3 MARK
This  command  is  used  to override how often the program marks
record  positions.  These  record  positions are used to quickly
reposition  to  records  within the file.  The program  has 1000
entrys  for  saving the record positions.  If this switch is not
specified,  the  following  algorithm  is  used to calculate the
record marking count:

   ((blocks_used * records/block)/mark_entrys) = mark_count.

The worst case records/block is based upon the maximum record size.

     max_record > 256 use (512/32) = 16 records/block.
     max_record > 100 use (512/16) = 32 records/block.
     max_record >  32 use (512/8)  = 64 records/block.
     max_record >  16 use (512/4)  = 128 records/block.
     max_record <  16 use (512/2)  = 256 records/block.

The mark count is limited to a  maximum  of  50  records  unless
overridden.  If the file you are displaying has more than 50,000
records, you will want to specify a mark count.  Otherwise,  all
records  after  50,000  will  have to be skipped to sequentially
from the last record marked.  The command format is "/MARK=n".

3 OUTPUT
This  allows  you  to  specify  an  output  file  for subsequent
write  commands.  The  output file is not opened until the first
write command is issued,  thus  errors  are  deferred until that
time.  The command format is "/OUTPUT=filename". The output file
remains open until the CLOSE command is issued or until you exit
the program.

3 NARROW
This  forces all files to be displayed on a  narrow  (80 column)
screen. Normally the maximum record size within the file is used
to determine whether the screen should be NARROW or WIDE.

3 NAME
This  controls  whether the file name is displayed at the top of
the  screen.  Disabling  the  file  name display allows two more
lines for the file display.

3 NUMBERS
This  controls  whether the record number is displayed along the
left  hand  margin  preceeding  each display line.  These record
numbers are useful when specifying a range for the write command.

3 PROTECT
The  controls  whether  the  file  protection  is changed before
deleting  a  file  using  the  DELETE command.  If protection is
disabled,  the  file  protection  is  changed to  allow deletion
before  deleting the file.  This is useful if you want to delete
a  file whose protection  is  set  to  read-only  which causes a
"Protection Violation" when trying to delete it.

3 QUIET
This controls whether bells  are appended to messages displayed. 
If  bells  are  disabled,  then  bells  within the file are also
suppressed.

3 RULER
This controls whether a ruler is displayed on the line following
the  file  name line.  If the file name display is disabled then
the ruler is also disabled.

3 SCREEN
This  is  used  to  specify  the screen display  width.  It also
controls  the number of characters displayed on each line before
the line is truncated.  Specifying a screen width overrides  the
NARROW or WIDE options.  The command format is "/SCREEN=n" where
the range for "n" is from 1 to 512.

3 SCROLL
This  controls whether both  files  should  be  scrolled when in
split  screen mode.  This is useful when you want to do a visual
comparison of two files.  You  can  only  scroll  in the forward
direction  using  either  the down arrow key, section, enter, or
the return key.  All other commands only affect the active file.

3 SEEALL
This  allows non-printable characters such as control characters
to  be displayed.  Control characters are displayed as ^char and
tabs, carriage  return,  linefeed,  and  formfeed  are displayed
by  the VT100 graphics HT, CR, LF, or FF respectivly.
Escapes are displayed as dollar signs ($).

3 SECTION
This  specifies  the number of  lines  advanced  by  the SECTION
command.  The  default  section  size  is  normally  (max_lines-
(max_lines/5)+1)  where  max_lines  depends  on  whether  you've
specified  the /LINES options or if the you've disabled the file
name  display.  The command format is "/SECTION=n" where "n" can
be  any  number.  If  you  specify  zero,  the  section  size is
calculated using the algorithm above.

3 TECO
This  is  a  sub-option  to  the  SEEALL command.  This controls
whether  control  characters  are  displayed  using the graphics
character +/-char instead of the ^char format.

3 VERSION
This displays the current version of the program.

3 WIDE
This forces all files to be  displayed  on  a  wide (132 column)
screen.   Normally  the  maximum  record size within the file is
used to determine whether the screen should be NARROW or WIDE.

3 WAIT
This controls whether the program  waits  for  a response to the
prompt "Type any character to continue: " when a file open error
occurs when wildcards are specified. If this option is disabled,
the  program  waits  three seconds to give the user time to read
the  error message displayed and then continues to open the next
file.   This  option  is  useful when doing a wildcard list of a
directory  which  has  files protected which normally results in
the error "Protection Violation" being displayed.

2 COMMANDS
There are a number of commands  available  while  a  file  is  being
displayed.   The command prompt is displayed on the last line of the
screen and is constructed from the last record number displayed.  If
the  file  is positioned at the end of file, then the command prompt
is preceeded with the string "EOF-".  Commands can also be issued by
using  various  keys  on  the VT100 keypad.  A keypad diagram can be
displayed by using the PF2 key.  The  keypad  commands  CAN  NOT  be
modified  by  an  initialization  file  such as EDT keys.  The valid
commands are described below:

3 ADVANCE
This command sets the direction to the forward direction.

3 BOTTOM
This  command positions to the end of file and then displays the
last part of the file on the screen.

3 BACKUP
This command sets the direction to the backward direction.

3 CLOSE
This  command  is used to close an output file which is open for
the WRITE command.

3 DELETE
This command is used to delete the current file being displayed.

3 EXIT
This  command  is used to exit from the program or to exit split
screen  mode  when the bottom file is active.  You can also exit
by typing CTRL/Z.

3 FIND
This command is used to find a search string. The command format
is  "FIND search_string".  If  a search string is not specified,
you are prompted for one.

3 FNDNXT
This  command  is  used  to  find the next occurance of a search
string.  If  a search string doesn't exist, you are prompted for
one.

3 LEFT
This  command moves the margin left  if  previously  moved right
with  the  RIGHT command.  This command is equivalent to the EDT
SHR (shift screen right) command. The command format is "LEFT n"
where "n" is from 1 to 512.

3 LINE
This  command is used to advance or backup a single display line
depending of the direction.  The plus sign or minus sign is used
to advance or backup overriding the current direction.

3 NDIR
This  command  is used to display  the  next  directory  or sub-
directory when wildcard directorys have been specified.

3 NEXT
This command is used to display the next file (if any). If there
are no further files the program exits.

3 PAGE
This  command  is  used  to  find  the  next page.  The formfeed 
character  defines  the  start the next page.  FORTRAN formfeeds
and print file formfeeds are not detected (future version).

3 PRINT
This  command  is  used to spool the current  file  to  the line
printer.   On   RSX-11M,  the file is always spooled to LP0.  On
VAX/VMS,  the file is spooled to SYS$PRINT which can be assigned
to  any  line  printer.  The file is left open for display after
the  file  is  spooled.  Thus, you must use the NEXT  command to
display the next file if desired.

3 RIGHT
This command is used to move the margin right to display part of
the text  truncated  due to the terminal width.  This command is
equivalent  to  the  EDT SHL (shift display left) command.   The
command format is "RIGHT n" where "n" can be from 1 to 512.

3 REFRESH
This command is used  to  refresh  the  entire screen displayed.
The keypad is re-enabled (incase the terminal was reset) and the
entire  screen  is redisplayed.  If two  files  are displayed in
split screen mode, then both files are redisplayed. This command
is used for screen refresh instead of  CTRL/W  used in EDT since
CTRL/W is not recognized by the program.

3 RESET
This  command  is used to reset the select range selected by the
SELECT command.

3 SELECT
This  command  selects a portion of the file to be written.  The
lines  selected are displayed in reverse video just like EDT.  A
"WRITE SELECT"  command  is  then  used  to  write  the selected
lines.   When  this  command  is  issued  the  current  page  is
automatically selected.  The select point starts at the  top  of
the  current  page.  Because of this implementation, the minimum
that can be written is a single page.   To  write  less  than  a
page,  enable  the record number display and use a "WRITE range"
command.

3 SECTION
This command is used to advance or backup a section depending on
the current direction.

3 SET
This command is used to  change  the  listing  parameters.  This
command is used to change  any  of the startup options described
early plus the following commands;  SET  SEARCH EXACT or GENERAL
(default), SET TAB n (defines the size of a tab, the default is 8).

3 SHOW
This  command  is used to display a particular parameter.  Valid
keywords for SHOW are:

     FILE    - Displays the file name.
     HEADER  - Displays the file header.
     KEYPAD  - Displays the keypad diagram.
     MARK    - Displays the record marking count.
     SEARCH  - Displays the search string and general/exact.
     VERSION - Displays the version number.

3 SHL
Same as the RIGHT command.

3 SHR
Same as the LEFT command.

3 SPLIT
This  command  is used to enter split screen mode.  If you don't
enter a file name on the command line, you are prompted for one.
After the file is successfully opened, the screen is redisplayed
with  the  file  specified  at  the  bottom  of the screen.  The
"Active"  message is displayed to the right of the file  name to
show  which  file  is currently active.  If commands to override
the screen width were not specified (such as NARROW  and  WIDE),
then  the  screen  width is controlled by the active file at the
time the REFRESH command is executed.

To exit from  split  screen  mode,  make  the  bottom  file  the
"Active"  file  and  then type EXIT or CTRL/Z.  After the bottom
screen is exited, the top file is then  redisplayed  on  a  full
screen.

3 SWAP
This command is used to swap between the two files displayed  in
split  screen  mode.  The  "Active"  message is displayed to the
right  of the active file or the "SHOW FILE" command is executed
if the file name display is disabled.

3 TOP
This  command  is used to positions to the top of  the  file and
displays the first page on the screen.

3 WRITE
This command is used to write a portion of the active file to an
output file. If an output file is not open or you didn't specify
an  output  file  at  startup  time  with the "/OUTPUT=filename"
option,  you  are  prompted  for a file name.  The range for the
WRITE command are descibed in a later section. The default range
for the write command is "WRITE PAGE".

If  you type the carriage return or ENTER key on the keypad, the
program displays the next page of the file. A page is defined as
the  text displayed on the screen as opposed to the text between
two formfeeds as in EDT.

You can also enter a record number at the command  prompt.  This
allows  you to skip quickly to a position within the file.  This
is useful if you don't know what to search for and don't want to
repeatedly type the carriage return or section key.

2 RANGE_FORMAT
The range for the WRITE command is a subset of the ranges allowed by
EDT.  The normal range format is:

    beginning_line:ending_line
            or
    beginning_line THRU ending_line

The following keywords can be used for the ranges:

    . - The ending line number on the current page.
    line_number - A line number within the file.
    BEGIN - The beginning line number of the file (line 1).
    BPAGE - The beginning line number on the current page.
    EPAGE - The ending line number on the current page.
    END - The ending line number in the file.

    PAGE - The current page displayed.  Same as BPAGE:EPAGE.
    WHOLE - The whole file.  Same as BEGIN:END.
    SELECT - The lines selected by the SELECT command.

2 OUTPUT_FILE
The output file is created with the file type and file attributes of
the  active  input  file.   This  means  that  if  the input file is
variable length with print-file-format, the output file will be  the
same  format.   This  should be rememebered when writing portions of
multiple input file.  No checking is  done  to  insure  the  current
input  file  attributes  are  the  same  as  the output file.  Thus,
writing  a  FORTRAN  file   to   an   output   file   created   with
print-file-format  will  not  PRINT or TYPE the way you expect after
closing the output file.

2 FILE_FORMATS
Currently, only  implied  (carriage-return)  and  embedded  carriage
control  files  are  formatted  properly for output to the terminal.
The first character of each record in FORTRAN files and the sequence
field used for print-files for carriage control are not interpreted.
This support will be added in a future version of the program.

3 EMBEDDED
For files with embedded carriage control  (carriage-return/line-feed
in the file), scrolling backwards doesn't always backup a section or
a single page.  This is because a single record may be displayed  on
several  lines  on  the  screen.   To accuratly display these files,
display the file in SEEALL mode (this is what  EDT  actually  does).
Also,  when  scrolling  backwards  through embedded carriage control
file, the entire screen is redisplayed since this is the only way to
accuratly redisplay the previous page.

2 ABNORMAL_TERMINATION
If the program aborts abnormally or by your typing  CTRL/Y  to  stop
it,  a  software  terminal characteristic must be changed.  When the
program starts, the escape sequence characteristic is enabled.  This
tells the terminal driver to expect escape sequences.  By having the
terminal driver interpret the escape sequences, the program  doesn't
have  to  do  single  character  reads  which results in less system
overhead (EDT does single character reads).

The   following   DCL   command   disables   the   escape   sequence
characteristic:

    $ SET TERMINAL/NOESCAPE

2 CONTROL_Y
Since  this  program  is  written  in  PDP-11  Macro  and  runs   in
compatibility mode, CTRL/Y detection is not possible.  If you are in
the habit of typing CTRL/Y to abort programs, this program should be
run  from  a  command  procedure which handles CTRL/Y or disables it
altogether.

2 CONTINUATION_PROMPT
Whenever  file  open  errors  occur  with  wildcards  active,  after
displaying  the  file  header,  or  after displaying the keypad, the
program prompts with the message "Type any  character  to  continue:
".   At  this prompt, typing "E" or CTRL/Z will exit the program and
typing "N" will display the next file.  The "N"ext feature is useful
if you want to display just the file header (/HEADER option) of each
file when using wildcards.
