SEARCH

  Looks for the sequence of characters you specify and returns a range
  containing those characters.

  Syntax

     [range := ] SEARCH ({string | pattern | keyword1} ,keyword2
                         [{,keyword3 | ,integer} [,buffer | ,range]])

  Parameters

     string               The string you want to match.

     pattern              The pattern you want to match.

     keyword1             One of the following keywords:  ANCHOR,
                          LINE_BEGIN, LINE_END, PAGE_BREAK, REMAIN,
                          UNANCHOR.

     keyword2             One of the following keywords:

                          FORWARD -- Specifies a search in the forward
                          direction.

                          REVERSE -- Specifies a search in the reverse
                          direction.

     keyword3             One of the following keywords:

                          EXACT -- Specifies the search must match case and
                          diacritical information exactly.

                          NO_EXACT -- Makes the search insensitive to case
                          and diacritical marks.  This keyword is optional.

     integer              An integer specifying exactly what characteristics
                          the SEARCH built-in is to match.  Rather than
                          specifying the integers directly, you should use
                          the following pre-defined constants:

                          TPU$K_SEARCH_CASE -- Specifies a search that is
                          sensitive to case but may not be insensitive to
                          diacritical markings.

                          TPU$K_SEARCH_DIACRITICAL -- Specifies a search
                          that is sensitive to diacritical markings but may
                          not be insensitive to case.

                          You can perform Boolean operations to combine
                          these constants.  For example:

                          tpu$k_search_diacritical OR tpu$k_search_case

     buffer               The buffer in which to search.  The search will
                          start at the beginning of the buffer if a forward
                          search, or the end of the buffer if a reverse
                          search.  If the fourth parameter is not specified,
                          SEARCH operates on the current buffer, starting at
                          the current editing point

     range                The range in which to search.  The search will
                          start at the beginning of the range if a forward
                          search, or at the end of the range if a reverse
                          search.  If the fourth parameter is not specified,
                          SEARCH operates on the current buffer.

  Examples

  1.  The following statement causes DECTPU to search the current buffer for
      the string 'Reflections of MONET'.  If the search is successful, the
      location of the matched characters is stored in the range
      'user_range'.  The search would match the characters regardless of
      their case since NO_EXACT is specified.

      user_range := SEARCH ("Reflections of MONET", FORWARD, NO_EXACT);

  2.  The following procedure searches for the word 'CHAPTER' appearing at
      the beginning of a line.  If the word is found, the procedure
      positions the cursor to the beginning of the word.  Otherwise, it
      places a message in the message buffer.

      PROCEDURE user_find_chap
         LOCAL chap,
               found_range;
         ON_ERROR
             IF ERROR = TPU$_STRNOTFOUND
                THEN
                   MESSAGE ('CHAPTER not found. ');
                ELSE
                   MESSAGE (MESSAGE_TEXT (ERROR));
             ENDIF;
         ENDON_ERROR;
         chap := LINE_BEGIN & 'CHAPTER';
         found_range := SEARCH (CHAP, FORWARD, NO_EXACT);
         IF found_range <> 0
            THEN
               POSITION (found_range);
         ENDIF;
      ENDPROCEDURE;