1 LIBSEARCH
LIBSEARCH is a program which duplicates the functions of the VMS SEARCH
command, but acts instead on text,macro or help libraries on a module-by-
-module basis. Amongst other things, LIBSEARCH makes it easy to find help
text when you know the word that you want help with (e.g. compare) but
don't know what HELP topic to look in for it (DIFFERENCES, in this case.)

It also makes it much easier to find which module in a macro or include
library defines which symbol, just by using LIBSEARCH to search for the
symbol name.

LIBSEARCH takes arguments which, as much as possible, are the same as those
for SEARCH, and produces output which looks very similar. The restrictions
and additions are documented below.

Format
 LIBSEARCH library-spec,... search-string,...
 
2 Parameters
library-spec[,...]

 Specification(s) of library(s) to be searched. Wild card characters are
 allowed. Only text,macro or help libraries can be searched. The filetype
 will be defaulted appropriately if the /HELP,/MACRO or /TEXT qualifiers
 are used. /HELP is assumed if no qualifier is present. Separate multiple
 filenames with commas.

search-string[,...]

 Character string to be located. Enclose strings containing lowercase
 letters, blanks or other nonalphanumeric characters in quotation marks.
 Up to 100 search strings may be specified, and there is no explicit limit
 on the length of strings. A limit is imposed, however, by DCL on the
 maximum length of the total command. You can use the /MATCH and /EXACT
 qualifiers to alter the way LIBSEARCH matches text strings.
2 Restrictions
The /EXCLUDE qualifier, to exclude specific files, is not yet available.

Only 10 different input file specifications may be supplied, although
all can use wildcards to match an unrestricted number of files.

All other restrictions are also present in SEARCH.

2 Release_Notes
3 V1.6
A minor bug seen when /WINDOW is greater than 1, or when /MATCH=NAND or NOR
is usd, and the output includes zero-length records, is corrected. The
bug did not prevent the program working unless it was compiled 
with /CHECK=BOUNDS, but I've fixed it all the same. Thanks to Brendan Welch
at U. Lowell for bringing this to my attention.
3 V1.5
Version 1.5 incorporates some small changes and a performance improvement
again due to Pat Rankin (thanks, Pat !)

Statistics output now also includes files matched and modules matched.

The output file type is defaulted to .LIS (as with SEARCH).

The way /HIGHLIGHT is implemented is defaulted based on the terminal
type of the output device (like SEARCH.)

Detection of non-alphabetic strings is made somewhat faster by not
uppercasing the input, using code supplied by Pat Rankin.
3 V1.4
Version 1.4 of LIBSEARCH incorporates a number of additional facilities
and corrects a number of problems with LIBSEARCH. Thanks are due to Pat
Rankin for providing helpful suggestions and code.

V1.4 supports most of the qualifiers for SEARCH new with version 5.
In particular, highlighting is supported, exclusion of files or
modules based on dates and times, and the /CONFIRM switch is present.

Handling of the /WINDOW parameter has been corrected to be identical
to SEARCH. Modules with numeric subtopics are correctly handled, as are
those with lines starting with numeric data. When searching help
libraries, the subtopic location is also provided.

The HELP qualifier is assumed by default. Trailing spaces are trimmed on
subtopic names, and long subtopic names are truncated. Qualifier subtopics
are treated properly.
3 V1.2
Version 1.2 of LIBSEARCH supports the /FORMAT qualifier in full
and also correctly implements message generation using VMS signals
rather than TYPE statements. The SET MESSAGE command now affects
its output, and status codes are correctly returned on failure.

The /SUBTOPIC switch has been added, and changes made to the handling
of difficulties opening input files.
2 Copyright
LIBSEARCH is Copyright (C) 1989,1990, 1992 by the University of London
Computer Centre and Kevin Ashley.  No warranty, express or implied,
is offered as to the suitability of the software for any purpose.
The software is provided "as is". You may copy, modify or provide this
software to others, provided that this notice appears in all copies, and
also in any supporting documentation supplied with such copies.
2 Additions
The following switches and features exist in LIBSEARCH, additional to those
provided by SEARCH.

The /MEXCLUDE qualifier allows you exclude a particular module, or
wildcarded modules, from a search. It can be global (affecting all libraries
in the command) or local, affecting only one, or both.

The /MODULE qualifier allows you to specify that only certain modules are to
be searched.

The /MEXCLUDE and /MODULE qualifiers can be used together.

The /STATISTICS and /LOG qualifiers produce information pertaining to
modules searched, as well as files. /STATISTICS also reports on the match
criteria used in the search.

The /MACRO,/HELP and /TEXT qualifiers cause filetype defaulting.

The /SUBTOPICS qualifier controls whether information is output on the
HELP subtopic in which a target is found when searching HELP libraries.

The /BEFORE and /SINCE qualifiers apply to MODULES by default. If one of
the /CREATED,/BACKUP,/BEFORE or /SINCE qualifiers is present, the dates
and times of the library files are used instead.

The output format of LIBSEARCH is slightly different from SEARCH. See topic
Output_format for more information.
2 Output_Format
 The format of output from LIBSEARCH differs slightly from that produced
by the SEARCH command. LIBSEARCH outputs 40 asterisks between hits from
different files, and 30 asterisks between hits from different modules. The
module name is displayed on a separate line, after the file name, before the
first hit from a specific module. In addition, if a HELP library is being
searched, and the /SUBTOPIC qualifier is present, then the subtopic(s) in
which the target was found are displayed after the module name, on the same
line.

 20 asterisks delimit output from different HELP subtopics within a single
 HELP module if the /SUBTOPIC qualifier is present (which it is by default.)

 15 asterisks are present between different target windows if the /WINDOW
 qualifier is present with a non-zero value.
2 Qualifiers
/BACKUP
 /BACKUP

 Selects files according to the dates of  their  most  recent  backup.
  This qualifier is only relevant when used with the /BEFORE or /SINCE
  qualifier.  Use  of  the  /BACKUP  qualifier  is  incompatible  with
  /CREATED, /EXPIRED, and /MODIFIED.  The default is none, which means
  that the revision date of modules is used instead of that of files.

/BEFORE
 /BEFORE[=time]

 Selects only those files or modules that are dated before the specified
 time. Module time is used by default, unless /CREATED,/BACKUP,/EXPIRED
 or /MODIFIED are specified.

  You can specify either an absolute time or a combination of absolute
  and delta times.  See the  VMS  DCL  Concepts  Manual  for  complete
  information on specifying time values. You can also use the keywords
  TODAY,  TOMORROW,  and YESTERDAY.  If no time is specified, TODAY is
  assumed.
/CONFIRM
 /CONFIRM
 /NOCONFIRM (default)

  Controls whether a request is issued  before  each  individual file
  or module to confirm that the operation should be performed on that
  file or module.

  When the system  issues  the  prompt,  you  can  issue  any  of  the
  following responses:

       YES      NO     QUIT

       TRUE     FALSE  <CTRL/Z>

       1        0      ALL

                <RET>  

  You can use any combination of upper- and lowercase letters for word
  responses.  Word responses can be abbreviated to one or more letters
  (for example, T, TR, or TRU for TRUE).  Affirmative answers are YES,
  TRUE, and 1.  Negative answers are NO, FALSE, 0, and <RET>.  QUIT or
  CTRL/Z indicates that you want to stop  processing  the  command  at
  that  point.   When  you  respond with ALL, the command continues to
  process, but no further prompts are given.  If you type  a  response
  other than one of those in the list, the prompt will be reissued.
/CREATED
 /CREATED

 Selects files based on their dates of creation.   This  qualifier  is
  relevant  only  when used with the /BEFORE or /SINCE qualifier.  Use
  of the /CREATED qualifier is incompatible  with  /BACKUP,  /EXPIRED,
  and /MODIFIED.   The default is none, which means that the revision
  date of modules is used instead of that of files.
/EXACT
 /EXACT
 /NOEXACT (default)

  Controls whether the LIBSEARCH command  matches  the  search  string
  exactly,  or  treats uppercase and lowercase letters as equivalents.
  The default qualifier, /NOEXACT, causes LIBSEARCH  to  ignore  case
  differences in letters.

  Specifying the /EXACT qualifier causes the system to  use  less  CPU
  time.   Therefore, if you are sure of the case of the letters in the
  string, it is more efficient to use /EXACT.
/EXPIRED
 /EXPIRED

 Selects files according to the dates on which they will expire.  This
  qualifier  is  relevant  only  when  used with the /BEFORE or /SINCE
  qualifier.  Use of  the  /EXPIRED  qualifier  is  incompatible  with
  /BACKUP, /CREATED, and /MODIFIED. The default is none, which means
  that the revision date of modules is used instead of that of files.
/FORMAT
 /FORMAT=option

  Controls reformatting of records during output.  You can specify one
  of the following formatting options:

  TEXT      Replaces  control  characters  in  the  text   with   ANSI
            mnemonics  (for  example,  CTRL/C is replaced with <ETX>).
            The terminal formatting characters <HT>, <CR>, <LF>, <VT>,
            and <FF> are passed without change.

            TEXT is the default format.

  NOFF      Replaces  control  characters  in  the  text   with   ANSI
            mnemonics  (for  example,  CTRL/C is replaced with <ETX>).
            The terminal formatting characters  <HT>,  <CR>, <LF>  and
            <VT> are passed without change.  Form feeds   are replaced
            with <FF>.  It is otherwise identical to TEXT.

            /FORMAT=NOFF is useful to prevent form feeds from breaking
            up the output file, for example when a match finds a head-
            ing in a listing file.

  PASSALL   Moves characters to the output device with no  translation
            whatsoever.   You  can use /FORMAT=PASSALL whenever you do
            not  want  the  SEARCH  command  to  substitute  the  ANSI
            mnemonic  for  control  characters (for example, <BEL> for
            CTRL/G).   The  terminal  driver  cannot  send   eight-bit
            characters    to    the   terminal   unless   either   SET
            TERMINAL/PASSALL or SET TERMINAL/EIGHT_BIT is  already  in
            effect.

  DUMP      DUMP format is very similar to TEXT format.  However, with
            DUMP format, all control characters (including <HT>, <CR>,
            and <LF>) are displayed as ANSI mnemonics.

  NONULLS   NONULLS is identical to the DUMP option, except  that  all
            null  characters  are  removed  from the input file before
            reformatting.   In  DUMP  mode,  the  null  character   is
            displayed  as  <NUL>.

/HEADING (default)
 /NOHEADING
 Includes module and file names in the output file and displays 40
 asterisks as a window separator between groups of lines that belong
 to different files, and 30 asterisks between groups of lines from different
 modules. (The /WINDOW qualifier displays 15 asterisks as a separator
 between windows.) 
/HELP
 The /HELP,/MACRO and /TEXT qualifiers indicate the type of library to be
 searched. Their only effect is to default the filetype to .HLB,.MLB or
 .TLB appropriately. /HELP is assumed if not present.
/HIGHLIGHT
 /HIGHLIGHT(=option)
 /HIGHLIGHT=BOLD    (default on ANSI video terminal with advanced video)
 /HIGHLIGHT=REVERSE (default on ANSI terminal without advanced video)
 /NOHIGHLIGHT       (default for all other output)

  Controls whether the actual strings which are matched are emphasized
  in the output.  The emphasis, or highlighting, can be one of several
  options:

  BLINK     The matched  strings are  highlighted using the ANSI blink
            character attribute.  (advanced video only)

  BOLD      The  matched strings  are highlighted  using the ANSI bold
            character attribute.  (advanced video only)
            If /HIGHLIGHT is used without an option, BOLD is assumed.

  REVERSE   The matched strings are highlighted using the ANSI reverse
            video attribute.  (possible without advanced video)

  UNDERLINE The matched  strings are  highlighted with the ANSI under-
            line video attribute.  (possible without advanced video)

            (Note  that  without  the  advanced  video  option, either
            REVERSE or UNDERLINE will appear depending  on whether the
            cursor is selected as block or underline.  The two options
            REVERSE and UNDERLINE have the same effect.)

  HARDCOPY(=option)
            This specifies that the strings should be highlighted in a
            manner  suitable for  most  hardcopy  printers.   Hardcopy
            highlighting has two options:

            OVERSTRIKE  With overstrike highlighting,  matched strings
                        are double-printed, so that they should appear
                        darker.

            UNDERLINE   The  matched  strings are  underlined with the
                        underscore character.

            Hardcopy  printing  is  accomplished by  adding a carriage
            return and spacing back over  the  line to  overprint  the
            string  or  underlines.   Note  that  this  can as much as
            double the length  of the line,  and perhaps lead to trun-
            cation if the device buffer size is too small.

  The DIGITAL LN01 printer understands the ANSI video UNDERLINE attri-
  bute, it is therefore recommended that /HIGHLIGHT=UNDERLINE  be used
  with this printer instead of /HIGHLIGHT=HARDCOPY=UNDERLINE. The LN01
  does not understand OVERSTRIKE highlighting, and ignores it.

  The  DIGITAL  LN03 printer understands  both the ANSI video BOLD and
  UNDERLINE attributes, it is  recommended that either /HIGHLIGHT=BOLD
  or  /HIGHLIGHT=UNDERLINE  be used with  this printer  instead of the
  /HIGHLIGHT=HARDCOPY=UNDERLINE.  The  LN03  does  not  understand the
  OVERSTRIKE highlighting, and ignores it.

/LOG
 /NOLOG (default)
 Types a message to SYS$OUTPUT for each file and module searched. The
 message includes the file or module name, the number of records, and
 the number of matches for each file or module searched.
/MACRO
 The /HELP,/MACRO and /TEXT qualifiers indicate the type of library to be
 searched. Their only effect is to default the filetype to .HLB,.MLB or
 .TLB appropriately.
/MATCH
 /MATCH=option

 Indicates how the SEARCH command  matches  multiple  search  strings.
  The /MATCH qualifier has four options:

  OR        A match occurs if a record  contains  any  of  the  search
            strings.

  AND       A match occurs if and only if all of  the  search  strings
            are present in the single record.

  NOR       The negation of AND.  A match occurs only  if  the  record
            does not contain any of the search strings.

  NAND      The negation of OR.  A match occurs  only  if  the  record
            does not contain all of the search strings.

  When only one search string is specified, the  OR  and  AND  options
  produce   identical   results.   Similarly,  NOR  and  NAND  produce
  identical results for a single search string.

 
/MEXCLUDE=module
 Excludes the specified module(s) from the search. Module can be a wildcard.
 If specified after the command verb, but before any libraries, applies
 to all libraries searched. If specified after a specific library name,
 applies only to that library.
 A local specification overrides any global specification.

/MODIFIED
 /MODIFIED

 Selects files  according  to  the  dates  on  which  they  were  last
  modified.   This  qualifier  is  relevant  only  when  used with the
  /BEFORE or /SINCE qualifier.  Use  of  the  /MODIFIED  qualifier  is
  incompatible  with  /BACKUP, /CREATED, and /EXPIRED.  The default is
  none, which means that the revision date of modules is used instead
  of that of files.
/MODULE=module
 Only searches the specified module(s). Module can be a wildcard.
 If specified after the command verb, but before any libraries, applies
 to all libraries searched. If specified after a specific library name,
 applies only to that library.
 A local specification overrides any global specification.
/NUMBERS
 /NONUMBERS (default)
 Includes source line numbers in the output.
/OUTPUT[=file-spec] 
 /NOOUTPUT
 Specifies an output file. The default is SYS$OUTPUT.
/REMAINING
 /NOREMAINING (default)
 Includes in the output all records from the first matched record to
 the end of the module. This qualifier overrides n2 in /WINDOW, but
 allows /WINDOW=n1.
/SINCE
 /SINCE[=time]

 Selects only those files or modules that are dated after the specified
 time. Module time is used by default, unless /CREATED,/BACKUP,/EXPIRED
 or /MODIFIED are specified.

  You can specify either an absolute time or a combination of absolute
  and delta times.  See the  VMS  DCL  Concepts  Manual  for  complete
  information on specifying time values. You can also use the keywords
  TODAY,  TOMORROW,  and YESTERDAY.  If no time is specified, TODAY is
  assumed.
/STATISTICS
 /STATISTICS
 /NOSTATISTICS (default)

  Controls whether LIBSEARCH displays statistics about the  search. The
  statistics displayed are:

  o  Number of files searched

  o  Number of modules searched

  o  Number of records searched

  o  Number of characters searched

  o  Number of records matched

  o  Number of lines printed

  o  Buffered I/O count

  o  Direct I/O count

  o  Number of page faults

  o  Elapsed CPU time

  o  Elapsed time

  o  Value of /MATCH and /EXACT switches
/SUBTOPICS
 /SUBTOPICS (default)
 /NOSUBTOPICS
 Determines, when searching HELP libraries, whether the subtopic(s) as
 well as the module in which targets are found is output. Has no effect
 if /NOHEADER is used.
/TEXT
 The /HELP,/MACRO and /TEXT qualifiers indicate the type of library to be
 searched. Their only effect is to default the filetype to .HLB,.MLB or
 .TLB appropriately.
/WINDOW
 /WINDOW[=(n1,n2)]
 /NOWINDOW (default)

  Controls the number of lines that are listed  along  with  the  line
  containing the matching string.

  If you specify the /WINDOW qualifier with a  single  number  n,  n-1
  additional  lines are displayed with each line containing the search
  string.  Half of the additional lines  are  listed  above  the  line
  containing  the  match, and half are listed below.  If n-1 is an odd
  number, the extra line is listed below the search string.

  For example, if you specify /WINDOW=10, nine  additional  lines  are
  listed  along with the line containing the search string, four lines
  are listed above the line containing  the  search  string  and  five
  lines are listed below it, making a total of ten lines.

  If you specify /WINDOW without  specifying  a  number,  the  default
  number  of five lines---two above, one containing the search string,
  and two below---is used.

  If the form /WINDOW=(n1,n2) is used, n1  refers  to  the  number  of
  lines  above  the  matched line and n2 refers to the number of lines
  below.  Either of these numbers can be zero.

  If /WINDOW=0 is specified, SEARCH will display the file name of each
  file  containing  a  match,  but  no  records.   You  can  use  this
  specification to create a file (using the  /OUTPUT  qualifier)  that
  can  be  inserted  into  a  command  file  to  manipulate  the files
  containing matches.

  If you omit the /WINDOW qualifier entirely, only the line  in  which
  the match is satisfied is displayed.
2 Examples

   1. $ LIBSEARCH/HELP SYS$HELP:HELPLIB/WINDOW=0 compar

This command searches the system help library to find all help topics
which refer to compar (in order to find references to compare and
comparison, for instance.) By specifying /WINDOW=0 only the topic and
subtopic names appear, without the actual matching lines.

   2. $ LIBSEARCH/text SYS$LIBRARY:FORSYSDEF FAB/exact

This command searches FORSYSDEF.TLB, the system include file for FORTRAN
programmers, to find which module or modules reference FABs. By specify-
ing /EXACT, only matches involving actual definitions or references are
likely to be found, rather than comments.

