Retro1.org codex

SCAN                                                      CMS User Area command

Use the SCAN command to search for text patterns in one or more files.  SCAN
will prompt you for the search pattern, which is case insensitive by default.
The format of the SCAN command is:
+----------+------------------------------------------------------------------+
| SCAN     | [*|fn [*|ft [A|fm]]] [(options...[)]]                            |
|          | options:                                                         |
|          |   ALL            CAse              CNtl            COPy [fname]  |
|          |   COUnt nnn      Display nnn       Endcol nnn      EXec          |
|          |   FIles nnn      FLagrc            FOr nnn         FRom nnn      |
|          |   FSumm          Hex               Library         None          |
|          |   Reverse        Startcol nnn      Tsumm                         |
+----------+------------------------------------------------------------------+
where:

fn | *   specifies the filename of the file[s] to search.  '*' is the default
         and causes all filenames to be searched.

ft | *   specifies the filetype of the file[s] to search.  '*' is the default
         and causes all filetypes to be searched.

fm | A   specifies the filemode of the file[s] to search.  'A' is the default
         and causes files on the A disk to be searched.

Options:

All      displays a file summary even for files that do not match the pattern.

CAse     enables case sensitive searching.
CNtl     'SCANIN EXEC A' has list of files to search.  When CNTL is specified,
         SCANIN EXEC A must have each fileid as if created by the command:
            LISTFILE <file-spec> (EXEC
COPy [fname]
         copies records containing the pattern into 'fname SCANOUT A'.  The
         file created by SCAN has variable format records and does not have any
         indication of which file the record came from nor the relative record
         number.  If fname is not supplied, 'SCAN SCANOUT A' is used.

COUnt nnn
         stops scanning after nnn total occurrences are found.  COUNT stops
         the search after the specified number of matches occurs, regardless of
         the number of files searched.  Other options may stop the search
         before the specified number of occurrences are found.

Display nnn
         displays output lines to nnn bytes only.  When DISPLAY is specified,
         each line matched is displayed in full if it is less than or equal to
         the number specified; otherwise, the terminal output is truncated to
         that length.

ENdcol nnn
         is last byte of record to search.  ENDCOL defines the virtual last
         byte if the current record is longer than the specified value.

EXec     copies names of files containing the pattern into 'CMS EXEC A1'.  EXEC
         copies only the fileid of files in which matches occur.

FIles nnn
         is the maximum number of files to search.  Other options may terminate
         the search before the specified number of files is reached.

FLagrc   sets the return code to the negative of the total number of records
         matched.

FOr nnn  searches only nnn records in each file.

FRom nnn starts the search at record nnn in each file.  This is ignored if
         LIBRARY is specified.

FSumm    displays records with pattern and file summary.  FSUMM is the default
         output option.  Each file that contains matches is summarized and each
         record that is matched is displayed.  The overall search summary is
         also displayed.

Hex      displays lines as if by DISPLAY command of CP.

Library  treats MACLIBs, TXTLIBs, and LOADLIBs as libraries.  If LIBRARY is
         specified, the FROM option is ignored.  Each member of the library is
         treated as a separate file.  Aliases are included in the search and
         are counted as separate files.

None     displays only error messages to the terminal.

Reverse  finds all records which do not contain the pattern.

Startcol nnn
         specifies the first byte of each record at which to begin the search.

Tsumm    displays a total summary of files searched.


Usage Notes:

1.  Two wildcards exist: %@ and %$.  %@ must precede the pattern and indicates
    that the pattern must start the line to be a valid match.  %$ must follow
    the pattern and indicates that the pattern must be at the end of the line
    to match.

    Both use the virtual beginning of line and end of line defined by STARTCOL
    and/or ENDCOL if they are specified.  Thus %@abc matches only lines that
    start with abc and XYZ%$ matches only lines that end in XYZ. This means
    that %@GHI%$ matches a line of length three containing only GHI.  If either
    %@ or %$ is not at the beginning or the  end of the pattern, respectively,
    then they lose their special meaning and are taken as a literal string of
    two characters.  All blanks entered are significant including leading and
    trailing ones.

2.  It is possible to call SCAN from a program via SVC 202 or the BALR
    instruction.  Programs that do so may specify the INTERNAL(DW) option.

    This option allows the program to supply a 24 word save area pointed to by
    R13 and a standard CMS tokenized PLIST pointed to by R1.  The flag byte of
    R1 must be zero.  The first full word immediately following the INTERNAL
    option must contain the length of the pattern and the second fullword must
    contain a pointer to the first byte of the pattern.

    This option suppresses prompting for the pattern.  All other options can be
    used.

    When called via BALR, the calling program must use DMSKEY to change storage
    keys to SYSTEM unless it was GENMOD'ed with the SYSTEM option.  SCAN is a
    transient routine and must be already located in the transient area when
    called.

3.  SCAN was written by Herb Chong while at the University of Waterloo.