1 LIST
 LIST is a utility for examining the contents of files.  It's  simplest
 use  is to display records at the terminal a screen at a time, however
 it can also search for character strings and write portions  of  files
 to other files.  Any record in a file may be accessed directly by line
 number or by a search.

 The LIST command line has the following syntax.   (Optional  parts  of
 the command line are enclosed in square brackets):

      LIST[/qualifiers] input_file[,...] [commands][>[>]output_file]
2 Input_file
      Each "input_file" may be a simple file name, an indirect  command
 file  name  preceded by @, or a file name containing standard RMS wild
 card characters.   More  than  one  "input_file"  may  be  entered  by
 separating them by commas.

      If "input_file" is a simple file name, LIST lists the file.   The
 default file extension is ".lis".  For example,

      $ list abc.dat

 lists the file abc.dat.

      If "input_file" is an indirect file name, LIST  lists  the  named
 files  in the indirect file one at a time.  Each file name must appear
 on a line by itself and may not have wild card characters in it.   The
 default extension for indirect file names is ".com".  For example,

      $ list/noprompt @files

 lists each file specified in files.com .

      If "input_file" contains wild  card  characters  LIST  lists  the
 files  which  match  the wild cards.  The wild card character matching
 works identically to the way it works in the TYPE  command,  ie.   the
 initial  default  file type is ".lis" and only the most recent version
 of the file is selected unless ;* is specified.

      When more than one "input_file" is specified or when "input_file"
 contains  wild  cards  or  is an indirect file name, LIST prompts with
 each of the selected file names to see if you want them listed, unless
 /NOPROMPT was specified (see HELP LIST QUALIFIERS) .  Responses to the
 prompt are:

      Y           List the file.
      <cr> or N   Don't list the file.
      G           (GO) List this and remaining files with no prompting.
      ^Z          Don't list this file and remaining files.


      When commands are given on LIST's command line, they are executed
 once  for  each  file selected by the input file specifications.  When
 output is redirected by the command line, it  remains  redirected  for
 each file selected (see HELP LIST OUTPUT_FILE) .  For example,

      $ list * 1,$px >all.lis

 prints *.lis into the file all.lis .
3 Defaults
      More than one file may be listed during the same LIST session  by
 typing  LIST  and  then a carriage-return.  LIST then prompts with the
 "File? " prompt for one or more file name(s).  After the file(s)  have
 been listed, LIST prompts for a new file name.

      Whenever LIST encounters an input file name,  the  node,  device,
 uic,  name,  and  extension  fields  are  remembered  and  become  the
 defaults, even if the field has  wild  card  characters  in  it.   The
 defaults  are  used to replace missing fields of subsequent file names
 entered for listing.  For example:

      $ list
      File? icr$document:list.doc

 When you are  finished  listing  icr$document:list.doc,  then  to  see
 icr$document:vg3.doc you would only have to type:

      File? vg3

 and LIST would supply the missing fields of the file name.

      If LIST can't find a file after supplying the defaults, it  tries
 the file name as entered.  Initially, the defaults are "sys$disk:" for
 the device and ".lis" for the extension.
2 Searching
      LIST can search backwards and forwards  in  the  input  file  for
 lines  which  match a specified search pattern.  A search pattern is a
 string of characters bracketed by slashes  (/)  or  backwards  slashes
 (\):

      /string/    causes LIST to search forward from the  current  line
                  for a line which matches "string".

      \string\    causes LIST to search backwards from the current line
                  - 1 for a line which matches "string".

 Case is not significant in search patterns, eg.  /X/ and /x/ match the
 same  lines,  unless  the  characters  are  inside  double quotes (see
 below).  Once specified, a pattern becomes the default pattern and may
 be invoked by // or \\.  For example,

      /john doe/

 searches forwards for a line with "john doe" in it in upper  or  lower
 case.

 There are several characters which have a special  meaning  when  they
 appear inside a search pattern:

3 "
 All characters within enclosing double quotes are  treated  literally,
 not  as  special  characters.   The case of a character is significant
 when it appears within double quotes.  Two double quote characters  in
 a  row  within  enclosing double quotes are interpreted as one literal
 double quote.  For example,

      /"John Doe"/

 matches only lines which contain literally John Doe .

3 ~
 negation.  Causes a match if the pattern does not match the  line.   ~
 must  appear  at  the beginning of a pattern (unless a column range is
 specified (see HELP LIST SEARCHING COLUMN_RANGE) ), otherwise  it  has
 no special meaning.  For example,

      /~abc/

 matches lines which don't contain abc.

3 %
 specifies that the match must occur at the beginning of the line only.
 % itself must appear at the beginning of the pattern, otherwise it has
 no special meaning, unless a column range  (see  HELP  LIST  SEARCHING
 COLUMN_RANGE)  or  negation  (~)  is desired;  in this case the column
 range and/or  the  negation  character  must  appear  before  %.   For
 example,

      /%10/

 matches only lines with a 10 in the first two columns, and

      /~%10/

 matches lines without a 10 in the first two columns.

3 $
 specifies that the match must occur at the end of the  line  only.   $
 itself  must  appear  at  the  end of the pattern, otherwise it has no
 special meaning.  For example,

      /%$/

 matches only empty lines.

3 *
 is a wild card character that  matches  any  sequence  of  characters,
 including the empty sequence.  For example,

      /john*doe/

 matches lines containing johndoe or john doe or johnabcdoe etc.

3 ?
 is a wild card character  that  matches  any  single  character.   For
 example,

      /a?c/

 matches lines containing abc or acc or a c etc.

3 @
 matches any one alphabetic (a-z or A-Z) character.  For example,

      /a@c/

 matches lines containing abc or acc but not a c.

3 #
 matches any one numeric (0-9) character.  For example,

      /%#/

 matches lines with a number in column 1.

3 `
 accent matches a break character.  Break characters are:  beginning of
 line,  end  of line, and any non-alphanumeric character.  For example,
 the ?  command can be  used  with  the  following  search  pattern  to
 display lines which contain the variable I:

      /`i`/?


3 ^
 causes the next character to be interpreted as  a  control  character.
 For example,

      /^z$/

 matches lines containing control Z at the end of the line.

3 |
 logical OR.  Causes a match  if  the  sub-pattern  before  it  or  the
 sub-pattern after it match the line.  For example,

      /abc|xyz|%#/

 matches lines containing abc or xyz or a number in the  first  column.
 The  negation  character  (~)  may  be  used  at  the  beginning  of a
 sub-pattern;  for example,

      /~x|~y/

 matches lines which don't contain an x or don't contain a y.

3 &
 logical AND.  Causes a match if the  sub-pattern  before  it  and  the
 sub-pattern after it match the line.  For example,

      /x|y&abc/

 matches lines containing abc and an x or a y.  The negation  character
 (~) may be used at the beginning of a sub-pattern;  for example,

      /~x&~y/

 matches lines which don't contain an x and don't contain a y.
3 Column_range
      Search patterns can restrict the range of columns  in  the  input
 record  in  which  the  search  is  to  take place.  A column range is
 specified by placing the special character "<" at the beginning  of  a
 pattern  or  subpattern, followed by two column numbers separated by a
 comma, followed by a ">" character.  The rest of  the  search  pattern
 follows the column range specification.  For example,

      /<11,15>123/

 searches for 123 in columns 11 through 15.

 Subpatterns can also specify a column range, for example:

      /<30,31>10&<40,41>20/

 searches for a record with 10 in columns 30 and 31 and 20  in  columns
 40 and 41.

 The special characters ~ (negation) and % (match at beginning)  should
 appear after a column range specification.  For example,

      /<10,20>~abc/

 searches for lines which don't contain abc in columns 10  through  20.
 When  %  or $ is used with a column range, the match must occur at the
 beginning or end, respectively, of the column range.  For example,

      /<10,50>%abc*xyz$/

 matches lines with abc starting at column 10 and xyz ending at  column
 50 (or the end of the record, whichever is shorter).

 The characters "<" and ">" and the other characters in a column  range
 specification  are only special at the beginning of a pattern, and may
 be used freely elsewhere in a pattern, for example:

      /~<10,20>/

 matches lines which don't contain <10,20>.
2 Numbers
      Numbers are used to position LIST in the file and as arguments to
 commands.   Numbers  always precede the command they affect.  A number
 may be a simple integer, one of several special line number  variables
 (see  HELP LIST NUMBERS VARIABLES) , or a search pattern.  The numeric
 value of a search pattern is the number of the line that  matches  the
 pattern.

      LIST scans the command line from  left  to  right.   Whenever  it
 encounters  a  number,  the  current  line number, dot, is set to that
 number.  When multiple line numbers appear next to  each  other,  LIST
 positions to each in turn, for example:

      1/abc/

 searches for abc at or after line 1.

      Some commands optionally take two  numbers  as  arguments;   when
 specifying  more than one number, separate the two numbers by a comma.
 For example, the P command may be used to print lines 1-45:

      1,45p

 Numbers may be added and subtracted from one another, for example:

      /x/-1,+2p

 prints three lines around the next line which contains an x.
3 Variables
 Following is a description of each line number variable:

  .    Dot is the current line number.  Whenever LIST encounters a line
       number,  the  value  of  dot  is reset to that line number.  For
       example,

            /x/,.p

       prints the next line containing an x.

  $    Dollar is the last line of the file.  For example,

            1,$p

       prints the whole input file.

  #    Sharp is the line number displayed by the  most  recent  prompt.
       For  example,  if LIST was positioned at line 10 as indicated by
       the prompt "10>" then

            10>1,#/x/p

       would print from line 1 to the next line containing an x  at  or
       after line 10.

  @    At-sign is the line  number  of  the  top  of  the  last  screen
       displayed by LIST.  For example,

            @+1//p

       searches for the next line matching the  current  pattern  after
       the  top  of the last displayed screen, and prints a screen from
       there.

  *    Star is set by the "=" command and is equal to the value of  dot
       when  the  "="  command  was  last  issued.   *  marks a line of
       interest for future reference.  For example,

            =\subroutine\,*/end/p

       marks the current line, then searches backwards for  subroutine,
       then  returns to the marked line, searches forwards for end, and
       finally prints the lines between the two matched lines.
2 Commands
      LIST accepts commands on it's initial command  line  or  when  it
 prompts with the current line number, for example:

      24>

 Commands are single characters and are preceded by zero, one,  or  two
 numbers which are arguments to the command.  More than one command may
 be entered on a command line;  LIST scans the command line  from  left
 to right, positioning to line numbers and executing commands.

      There are two types of commands;  those that print and those that
 affect  LIST's  state  without  printing.  Commands that print usually
 print from dot (the current line number) unless two line numbers  were
 specified, in which case printing occurs from the first line number to
 the second.  Other commands "eat up"  the  number(s)  that  are  their
 arguments;   in  other  words, dot retains the value it had before the
 command, with its numeric argument(s), was executed.

      If a line number appears at the end of the command line  with  no
 command after it, the default command (P) is executed.  For example,

      /abc/

 at the end of a line of commands is equivalent to

      /abc/p

 since both  cause  a  screen  to  be  displayed  from  the  next  line
 containing abc.


 Note: LIST usually changes most control  characters  to  nulls  before
       writing  out a line, however when two line numbers are specified
       or when the G command is executed,  (for  example  the  commands
       "1,$P"  or  "100G")  all  characters  are written out unchanged.
       Thus it is possible to write out  portions  of  a  file  without
       losing any characters.
3 P
 Displays lines from the file.  Dot is left at the  last  line  printed
 plus  1.   P is the default command, and is optional at the end of the
 command line.

     P       Print as many lines as will fit within the current  screen
             size (initially 23), starting at the current line (dot).

     nP      Print as many lines as will fit within the current  screen
             size starting at line n.

     n1,n2P  Print lines n1-n2.

 Example:

      1,10p

 prints lines 1 through 10.
3 G
 Like "P", "G" displays lines from the file, however with zero  or  one
 arguments  G  only  prints one line, and dot is left at the first line
 printed.

     G       Print the current line.  The current line is not changed.

     nG      Position to and print line n.  Dot is left at line n.

     n1,n2G  Print lines n1-n2.  Dot is left at n1.

 Example:

      /subroutine/g

 prints the next line with the string "subroutine" in it.
3 ?
 Displays lines matching the current search  pattern,  and  their  line
 numbers (unless /NONUMBERS is specified on LIST's command line).

     ?       Display  a  screen-full  of  lines  matching  the  current
             pattern.   If  the end of the file is reached, dot is left
             at line 1, else dot is left at the next line matching  the
             current pattern.

     n?      Display  a  screen-full  of  lines  matching  the  current
             pattern,  starting  at  line n.  If the end of the file is
             reached, dot is left at line 1, else dot is  left  at  the
             next line matching the current pattern.

     n1,n2?  Display all lines matching  the  current  pattern  between
             lines n1 and n2.  Dot is left at n1.

 Example:

      1/xyz/,$?

 displays all occurrences of xyz in the input file.
3 L
 The L command causes the last line of commands to be reexecuted.
3 =
 The = command sets the line number variable, *, to  dot.   =  marks  a
 line for later reference.

     =       Set * to dot.

     n=      Set * to n.  Dot is left at line n.

 Example:

      /x/=

 marks the next line containing an x.
3 S
 Sets the screen size.  The value of dot is unchanged.

     S       Reset the screen size to 23.  The screen  size  and  width
             help determine how many lines LIST prints per screen.

     nS      Set the screen size to n.

     n1,n2S  Set the screen size to (n2-n1)+1.

 Example:

      7s

 sets the screen size to 7.
3 C
 Sets the column range which will  be  read  from  each  input  record.
 Initially  the  column  range  is 1-513.  LIST can only read up to the
 first 512 characters in a record, however when the column range is set
 to  be  greater  than  512,  then  LIST reports an error when an input
 record is more than 512 characters  long.   If  the  column  range  is
 restricted  to  512  or less then LIST does not report record too long
 errors.  The value of dot is unchanged.

     C       Reset the column range to 1-513.

     nC      Set the column range to 1-n.

     n1,n2C  Set the column range to n1-n2.

 Example:

      1,10c

 causes LIST to read and display only columns 1-10 of each record.
3 F
 Creates a "virtual file" by restricting LIST to a contiguous  subrange
 of the lines in the file.  Dot is left at line 1.

     F       Reset the virtual file to correspond to the actual file.

     nF      Make a virtual file between dot and dot+n-1.  Dot  becomes
             the new line 1 of the virtual file.

     n1,n2F  Make a virtual file between n1 and n2.  N1 becomes the new
             line 1 of the virtual file.

 Example:

      /subroutine/,/end/f

 creates a "virtual file" which contains a subroutine.  Line 1  of  the
 virtual  file  is  the first line of the subroutine, and $ is the last
 line of the subroutine.
3 N
 Turn prompt mode on/off.  When prompt  mode  is  off,  LIST  does  not
 prompt  with  the current line number, but leaves the cursor after the
 last line printed.  The value of dot is unchanged.

 Example:

      1sn

 sets the screen size to  1  and  prompt  mode  off,  placing  LIST  in
 line-by-line mode, in which one record is printed per carriage-return.
3 R
 Resets dot to 1, the screen size to  23,  the  screen  width  to  it's
 original  value,  the  column  range to 1-513, the virtual file to the
 full, actual file, and prompt  mode  to  on.   The  value  of  dot  is
 unchanged.
3 X
 Finish listing the file.  X is identical to ^Z (EOF).
3 ' '
 Space (blank) is the null command, and does nothing.  It may  be  used
 to  position  to a line without printing and to separate commands on a
 line for readability.  If a line number  is  given  before  the  space
 command, dot is left at that line number, else dot is unchanged.

 Example:

      1,10f p

 creates a "virtual file" between lines 1 and 10 and prints starting at
 line 1.
3 W
 Sets the screen width.  The screen size and width help  determine  how
 many lines LIST prints per screen.  The value of dot is unchanged.

     W       Reset the screen width to it's original value,  read  from
             the host operating system when LIST was started.

     nW      Set the screen width to n.

 Example:

      132w

 sets the screen width to 132 columns.
3 V
 Routes all the following output from the command line to  the  printer
 port of the DT80 (a VT100 look-alike).  The value of dot is unchanged.

 Example:

      v 1,100p

 turns on the printer port, prints lines 1-100  on  the  printer,  then
 turns the printer port off.
3 Looping
      A sequence of commands may be repeated in a loop by  placing  the
 commands  within  parentheses  with a repetition count in front of the
 left parenthesis.  The commands are then executed  as  many  times  as
 indicated  by  the  repetition  count  or  until  a  search within the
 commands fails.  In either case,  after  exiting  the  loop  execution
 continues  with  the  next statement after the loop.  If no repetition
 count is specified, the loop is executed forever  or  until  a  search
 failure occurs within the loop.  For example,

      (/`i`/+1\subroutine|function|program\,.p /end$/)

 loops finding all Fortran modules which contain  the  variable  I  and
 prints the line containing each module's name.

 Loops may be nested up to four levels.
3 Macro
      LIST has a simple text replacement macro facility.  A macro is  a
 remembered  set  of  commands.   The macro is defined by enclosing the
 commands in square brackets ([]).  When M is specified on the  command
 line, the M is replaced by the macro text.

 For example,

      [@+1//P]

 defines a macro to search for the current pattern  starting  from  the
 top  of  the  last  screen  +  1, and print from there.  To invoke the
 macro, type M on the command line.

      The text of the macro is not executed when it is defined.  It  is
 not  executed  until  an M is typed.  M may appear with other commands
 and line numbers on the command line;  first the macro  text  replaces
 the  M,  then  the  command line is executed.  M may be used more than
 once on a command line.

      Initially, the macro is defined  as  1SNP;   this  puts  LIST  in
 line-by-line mode and prints one line (see HELP LIST COMMANDS N) .
2 Output_file
      The output from a line of LIST commands, which normally  goes  to
 the  terminal,  may be redirected to a file.  To write a new file, put
 >output_file at the end of the commands;  to  append  to  an  existing
 file,  put >>output_file at the end of the commands.  If "output_file"
 doesn't exist during an append, it will be created.

      The default file  name  for  "output_file"  is  "list",  and  the
 default  extension  is ".lis".  If "output_file" contains asterisks in
 it, then each field  of  "output_file"  with  an  asterisk  in  it  is
 replaced by the corresponding field in the input file name.

      When output is redirected  by  the  initial  command  line  which
 selected  the  file(s)  to be listed, it remains redirected as long as
 the file(s) are being listed.  For example,

      $ list/noprompt/header *.dat /xyz/,$?x >xyz

 lists all occurrences of the string xyz in *.dat to the file xyz.lis .

 However if the output file specification  contains  asterisks,  a  new
 output  file  is  created  for each input file listed, with the fields
 with asterisks in them replaced by the corresponding fields  from  the
 input file name.  For example,

      $ list/noprompt/trim [murphy.proj...]*.for 1,72c 1,$px >[*]*.for

 trims   the   sequence    numbers    and    trailing    blanks    from
 [murphy.proj...]*.for  and  rewrites  each  file with a higher version
 number in its original UIC.

 When output is redirected from a command line while  listing  a  file,
 redirection  is  only  in  effect  while  that  command  line is being
 processed.  For example,

      24>1,10p>t.tmp

 writes lines 1-10 to the file t.tmp and then closes it.

      The carriagecontrol type of newly created files is  identical  to
 the  carriagecontrol  type  of the file being listed (except for print
 file format files, which  are  written  with  carriage  return  (list)
 carriagecontrol),  while that of appended files is the same as that of
 the file being appended to.

      Once an output file name has been specified using >output_file or
 >>output_file,  that  file name becomes the default file name for file
 redirection only, and need not be specified again, i.e.  > or >> alone
 is  all  that  is needed to redirect output to that file.  The name of
 the file is remembered as it was typed in, so that asterisk fields are
 replaced with the fields from the current input file.
2 Bugs
 1.  Logical names must have  a  colon  after  them  to  be  translated
     properly in input and output file specifications.  For example:

          $ assign file.dat data
          $ list data:

 2.  When  output  is  appended  to  a  file  with  print  file  format
     carriagecontrol,  the  proper  carriage control information is not
     written to the file.

2 Examples

     <cr>            Hitting return prints the next screen.
     45              Start printing at line 45.
     -5              Print from 5 lines back.
     -               Print starting half a screen back.
     ---             Print starting one and one-half screens back.
     <esc>           Hitting escape prints from 2 screens back.
     $               Print the last line in the file.
     /xyz/           Locate the string xyz and print from there.
     //              Locate the current pattern and print from there.
     1/xyz/          Locate xyz at or after line 1 and print from there.
     /abc/-5         Print starting 5 lines before abc.
     1,10            Print lines 1-10.
     /subr/,/end$/   Print the next subroutine.
     /subr/?         Display lines containing subr.
     ?               Display lines containing the current pattern.
     1/`i`/,$?       Print all occurences of the variable "i".
     10,$>t.tmp      Write lines 10 through the end of the file to t.tmp

  $ list *.for /`n`/,$?x
       prints all occurrences of the variable N in *.for
2 Keys
      VAX RMS indexed and relative files may be listed by key  and  the
 starting  record may be based on a key match.  For example, to list an
 indexed file by key 2 starting at the first  record  where  key  2  is
 greater than or equal to "   10":

      $ list/key=2/keyge="   10" indexed.dat

 The defaults for indexed and relative files are to list by primary key
 (key number 0) starting at the first record in the file.

      In the key qualifier descriptions, "n" stands for an integer  and
 "key" stands for a key value, where a key value may be an integer or a
 character string enclosed by double quotes.  A double quote  within  a
 key  value may be specified by placing two double quotes in a row.  If
 the length, N, of a character key value is less than the source file's
 defined  key  length  then  the  match  is  made  based on the first N
 characters of the key.  Key matches  on  unsigned  binary  and  packed
 decimal keys are not supported at this time.
2 Qualifiers

/PROMPT
/NOPROMPT
     Prompt with each file name selected by the command line to see  if
     the  file  should  be  listed.  By default, LIST prompts when more
     than one file is selected by the command line or when an  indirect
     file is specified.  (see HELP LIST INPUT_FILE) .

/HEADER
/NOHEADER (D)
     Write a header record containing each file's  name  and  the  date
     before listing each source file.

/NUMBERS (D)
/NONUMBERS
     Display the line number of each line selected by the "?"  command.
     (see HELP LIST COMMANDS ?)

/TRIM
/NOTRIM (D)
     Trim trailing blanks and tabs from the source file.  By  selecting
     /Trim  and  restricting  the  column  range of the file to columns
     1-72, Fortran files can be stripped  of  sequence  numbers.   (see
     HELP LIST COMMANDS C)

/DELETE
/NODELETE (D)
     Allows the user to delete a file after listing it.   When  /DELETE
     is specified, LIST prompts with

          Delete?

     after each file selected by the command line has been listed.   If
     Y is entered, then the file is deleted.

/KEY=n
     List an indexed source file by key number  n.   By  default,  LIST
     lists the file by the primary key (key 0).

/KEYEQ=key
     List an indexed or relative source  file  starting  at  the  first
     record whose key equals the specified key.

/KEYGE=key
     List an indexed or relative source  file  starting  at  the  first
     record whose key is greater than or equal to the specified key.

/KEYGT=key
     List an indexed or relative source  file  starting  at  the  first
     record whose key is greater than the specified key.

