
Examples of commonly used commands:
 
    <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.
    ---             Start printing one and one-half screens back.
    <esc>           Hitting escape prints from 2 screens back.
    $-9             Print the last 10 lines in the file.
    /SUBR/          Locate the string SUBR and print from there.
    //              Locate the default pattern and print from there.
    1/SUBR/         Locate SUBR at or after line 1 and print from there.
    /ERR/-5         Print starting 5 lines before the next occurrence of ERR.
    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 *.FTN /`N`/,$?X  would print all occurrences of the variable N in *.FTN
 
Help on advanced use of LIST follows (type ^Z to exit help).


     LIST's simplest use is to display lines from a file at the terminal,  usu-
ally  a screen at a time.  LIST can also search for character strings and write
portions of a file to disk.  Finally, LIST can be postioned to any  line  in  a
file using line (record) numbers.

This manual explains how to use LIST.

Running LIST:

     The LIST command line has the following syntax (optional parts of the com-
mand line are enclosed in square brackets):

        LIST[/switches] fspec[,fspec...] [commands][>[>]file]


Switches:

        /HD         Write a header record containing each file's name  and  the
                    date to the standard output before listing the file.

        /GO         List all files selected by "fspec" without  prompting  (see
                    below:  FSPEC).



Fspec:

     "Fspec" may be a simple file name, an indirect command file name  preceded
by @, or in some installations, a file name containing SRD wild card characters
and/or switches.  If "fspec" is an indirect file name, LIST will list the named
files  in  the indirect file one at a time.  The default extension for indirect
file names  is  ".CMD".   If  "fspec"  contains  wild  card  characters  and/or
switches,  LIST will list the files which match the wild cards and/or switches.
When "fspec" contains wild cards and/or switches or is an indirect  file  name,
LIST will prompt you with each of the selected file names to see if you want it
listed, unless /GO was selected  (see  above:   Switches).   Responses  to  the
prompt are:

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

     If commands are given on LIST's command line, they will be  executed  once
for each file selected by "fspec".  If the standard output is redirected by the
command line, it will remain redirected for  each  file  selected  (See  below:
Redirecting Output From LIST).



Note:  Normal SRD wild card characters and switches may be  used  in  an
       SRD-type  file  name;   however,  do not use the /SE:  switch, as
       this is the default switch.  Also, only the most recent  versions
       will be selected unless ;* is specified.


Default fields in file names:

     More than one file may be listed during the same LIST  session  by  typing
LIST and then a carriage-return.  LIST will prompt for a file name.  After each
file has been listed, LIST will prompt for a new file name.

     Whenever LIST attempts to open a file, the device, uic, name,  and  exten-
sion  are remembered and become the defaults.  The defaults are used to replace
missing fields of subsequent file names entered for listing.  For example:

        PDS> LIST
        FILE? LB:[22,2]LIST.DOC

When  you  are  finished  listing  LB:[22,2]LIST.DOC,  if  you  wanted  to  see
LB:[22,2]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 open a file after supplying the defaults, it tries the  file
name  as  entered.  Initially, the defaults are "SY:" for the device and ".LST"
for the extension.


Numbers:

     Numbers are used to position LIST in the file and  as  arguments  to  com-
mands.  Numbers always precede the command they affect.  A number may be a sim-
ple number, one of several special line number variables, or a search  pattern.
The  value  of a search pattern is the number of the line that matches the pat-
tern.  Some commands optionally take two numbers as arguments;  when specifying
more than one number, separate the two numbers by a comma, e.g.  1,45 .  In ad-
dition, numbers may be added and subtracted from one another, e.g.  $-9 is  the
10th line from the end of the file.

     LIST scans the input on a command line from left to  right.   Whenever  it
encounters  a  number,  dot  (the  current  line number) is set to that number.
Multiple line numbers may appear next to each other;  LIST positions to each in
turn, e.g.  1/SUBR/ searches for SUBR after line 1.










Line number variables:

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

        %       Percent sign is the first line of the file.

        $       Dollar is the last line of the file.

        #       Sharp is the line number displayed by the most recent prompt.

        @       At-sign is the line number of the top of the last  screen  dis-
                played by LIST.

        *       Star is set by the = command and is equal to the value  of  dot
                when the = command was last issued.  * serves to mark a line of
                interest for future reference.








Search patterns:

     A search pattern is a string of characters bracketed  by  slashes  (/)  or
backwards slashes (\):

        /string/    causes LIST to search forward from dot  for  a  line  which
                    matches "string".
        \string\    causes LIST to search backwards from dot-1 for a line which
                    matches "string".

Case is not significant in search patterns, eg.  /X/ and  /x/  will  match  the
same  lines.   There  are  several characters which have a special meaning when
they appear inside a search pattern:

      "     causes all following characters until the next " to be  treated  as
            themselves,  not  as  special characters.  Case is significant when
            the characters appear within double quotes.  Two double quote char-
            acters in a row are interpreted as one literal double quote.
      %     specifies that the match must occur at the beginning  of  the  line
            only.  % itself must appear at the beginning of the pattern, other-
            wise it has no special meaning.
      $     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.  Thus /%$/ searches for a line with nothing in it.
      *     is a wild card character that matches any sequence of characters.
      ?     is a wild card character that matches any single character.
      ^     causes the next character to be interpreted as a control character.
            Thus /^Z/ matches the end-of-file character.
      |     logical OR.  Causes a match if the sub-pattern  before  it  or  the
            sub-pattern  after  it match the line.  For instance, /x|y/ matches
            lines containing an x or a y.
      &     logical AND.  Causes a match if the sub-pattern before it  and  the
            sub-pattern after it match the line.
      ~     negation.  Causes a match if the sub-pattern  does  not  match  the
            line.   ~  must appear at the beginning of a sub-pattern, otherwise
            it has no special meaning.  Thus /x&~y/ matches lines which contain
            an x but no y.
      `     accent matches a break character.  Break characters are:  beginning
            of  line,  end  of  line,  and  any non-alphanumeric character.  To
            search for all occurrences of the variable "i" you  could  use  the
            following pattern with the ?  command:  /`i`/?

Once specified, a pattern becomes the default pattern and may be invoked by  //
or \\.  Patterns may be used anywhere a number may appear;  the value of a pat-
tern is the line number of the matched line.



Examples of line numbers:

        .-10        10 lines before the current line.
        1,$         Line 1 through the last line of the file.
        /SUBR/      Next line which has the string SUBR in it.
        /%SUBR/     Next line which has SUBR at the beginning of the line.
        \\          Next line which matches the default pattern while  scanning
                    backwards.
        /`I`&`J`/   Next line on which the characters I and J both appear  each
                    surrounded by break characters.
        /"""/He"""/ Next line which contains  "/He"
        1/SUBR/-1   The line before the first occurrence of SUBR after line 1.


     It is possible to specify fairly complex line numbers;   the  value  of  a
line number is always the last number evaluated.  For instance,

        1/SUBR/+1//,.+3/END/+1//

specifies two line numbers;  the first is the second occurrence of SUBR  at  or
after line one;  the second is the second occurrence of END at or after 3 after
the first line number.


Commands:

     LIST accepts commands on it's command line or when  it  prompts  with  the
current  line  number  and a ">" character.  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.   Other commands "eat up" the
number(s) that are their arguments;  in other words, dot is reset to the  value
it had before the command, with it's 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.  Thus   /SUBR/   is equivalent
to   /SUBR/P  ;  both cause printing to begin at the next occurrence of SUBR.







Commands that print:

    P   Displays lines from the file.  Dot is always  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.

    G   Like "P", "G" displays lines from the file, however with  zero  or  one
        arguments G only prints one line, and the value of dot is not changed.
            G       Print the current line.
            nG      Print line n.
            n1,n2G  Print lines n1-n2.









Commands that print (continued):

    ?   Displays only lines matching the current search pattern.
            ?       Display a screen-full of lines matching  the  current  pat-
                    tern.   If  the  end of the file is reached, dot is left at
                    line 1, else dot is left at the next line matching the cur-
                    rent pattern.
            n?      Display a screen-full of lines matching  the  current  pat-
                    tern,  starting  at  line n.  If the end of the file is re-
                    ached, 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.


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, (eg.  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 char-
       acters.


Other commands:

    L   The L command causes the last command line to be reexecuted.

    =   The = command sets the line number variable, *, to dot.   *  serves  to
        mark a line for later reference.
            =       Set * to dot.
            n=      Set * to n.

    S   Sets the screen size.
            S       Reset the screen size to 23.
            nS      Set the screen size to n.
            n1,n2S  Set the screen size to (n2-n1)+1.

    C   Sets the column range which will be read from the input file.
            C       Reset the column range to 1-512.
            nC      Set the column range to 1-n.
            n1,n2C  Set the column range to n1-n2.







Other commands (continued):

    F   Create a "virtual file" by restricting LIST to a contiguous  subset  of
        the lines in the file.
            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.

    N   Turn prompt mode on/off.  When prompt mode is off, LIST will not prompt
        with  the current line number, but will leave the cursor after the last
        line printed.  If the screen size is set to one and prompt mode is  set
        off  (1SN accomplishes this) then LIST will be in line-by-line mode, in
        which one line is printed for each carriage-return.

    R   Resets the screen size to 23, the screen width to it's original  value,
        the  column  range to 1-512, the virtual file to the full, actual file,
        and prompt mode to on.

    X   Finish listing the file.  X is identical to ^Z (EOF).

    " " Space (blank) is the null command, and does nothing.


Installation specific commands:

Not all installations have the following commands.

    W   Sets the screen width.
            W       Reset the screen width to it's original value.
            nW      Set the screen width to n.

    H   Invokes LIST as a subtask to print a help file.

    V   Routes all the following output from the command line  to  the  printer
        port of the DT80 (a VT100 look-alike).













Defining and using the macro:

     LIST has a simple text replacement macro facility.  A macro  is  a  remem-
bered  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  re-
placed 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 com-
mand line.

     The text of the macro is not executed when it is defined.  It is not  exe-
cuted  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.  The macro, M, may be used more than once on a command line.





Redirecting output from LIST:

     The output from a line of LIST commands, which normally goes to the termi-
nal, may be redirected to a file.  To write a new file, put >FILE at the end of
the commands, where FILE is a standard file name.  To  append  to  an  existing
file,  put  >>FILE  at  the end of the command line.  If FILE doesn't exist, it
will be created.  The default extension for FILE is ".LST".   The  carriagecon-
trol  type  of  newly created files is identical to the carriagecontrol type of
the file being listed, while that of appended files is the same as that of  the
file being appended to.

     Once a file name has been specified using >FILE or >>FILE, that file  name
becomes the default file name for file redirection only, and need not be speci-
fied again, i.e.  > or >> alone is all that is needed  to  redirect  output  to
that file.

     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.









