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 VAXTPU 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;