
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.
    //              // alone defaults to the last search pattern specified.
    45/SUBR/        Locate SUBR at or after line 45 and display a screen.
    /ERR/-5         Display starting 5 lines before next occurrence of ERR.
    $-50/SUBR/      Look for a subroutine in the last 51 lines of the file.
    1,10            Print lines 1-10.
    /SUBR/,/END/    Print the next subroutine.
    1/SUB/,.+5/END/ Print from SUB at or after 1 to END at or after 5 after SUB
    /SUBR/?         Display lines containing SUBR.
    ?               Display lines containing the current pattern.
    10,$>T.TMP      Write lines 10 through the end of the file to T.TMP.
LIST *.FTN /XVAL/,$?X  would print all occurrences of XVAL in *.FTN.
 
Help on advanced use of LIST follows (type ^Z to exit help).


     LIST is a utility for displaying selected portions of a file.  It provides
facilities  for  displaying  lines,  positioning in the file, and searching for
character strings.  In addition, output from LIST can be  redirected  from  the
terminal to a file.

     This manual explains how to use LIST.   Throughout  the  manual,  optional
parts of a command are enclosed in square brackets.

Running LIST:

     The LIST command line has the following syntax:

        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 each 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
or switches.  If the file name is an indirect file name,  LIST  will  list  the
named  files  in  the  indirect  file one at a time.  If it is an SRD-type file
name, LIST will list the files selected by SRD.   In  either  case,  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 the fspec.  If the standard output is redirected by a
command line, it will remain redirected for each file selected.

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.

        $       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.

        ;       Semi-colon is equal to the current screen size.








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 string.
        \string\    causes LIST to search backwards from dot-1 for string.

There are several characters which have a special meaning when they appear  in-
side a search string:

        '           means that the following character is to be treated as  it-
                    self, not as a special character.
        %           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.
        ^           causes the next character to be interpreted  as  a  control
                    character.

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 and the last line of the file.
        /SUBR/      First line which matches SUBR.
        /%SUBR/     First line which matches SUBR at the beginning of the line.
        \\          First line which matches the default pattern while scanning
                    backwards.
        /'/He''s/   First line which matches  /He's
        2/HELLO/-5  5 lines before first occurrence of HELLO at or  after  line
                    2.


     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 first 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  argu-
        ments 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
       printing a record, however when two line numbers are specified or
       when the G command is executed, all characters  are  written  out
       unchanged.   Thus  it is possible to write out portions of a file
       without losing any characters.





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.  The  macro  is  remem-
bered text from a line of LIST commands.  The macro is defined by enclosing the
text 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 com-
mand line.

     The text of the macro is not executed when it is defined by  enclosing  it
in square brackets.  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  re-
places  the  M,  then the command line is executed.  In addition, 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 carriagecontrol 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.














