Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

DEC Text Processing Utility Reference Manual


Previous Contents Index

To search a range for all occurrences of a pattern, you must define the range dynamically after each successful match; otherwise, SEARCH_QUIETLY positions to the beginning of the range and finds the same occurrence over and over. See the example section for a procedure that searches for all occurrences of a pattern in a range.

Return Value


The range that contains characters that match the pattern or string specified as a parameter.

Description

The SEARCH_QUIETLY procedure looks for a particular arrangement of characters in a buffer or range and returns a range that contains those characters. Unlike the SEARCH built-in procedure, SEARCH_QUIETLY does not signal TPU$_STRNOTFOUND when it fails to find a string.

SEARCH_QUIETLY looks for text that matches the string, pattern, or keyword specified as its first parameter. If it finds such text, it creates a range that contains this text and returns it. If SEARCH_QUIETLY does not find a match, the built-in returns 0 without signaling TPU$_STRNOTFOUND.

The starting position for the search depends on the optional fourth parameter and the search direction. If you do not specify the fourth parameter, the search starts at the editing point.

If you specify a range for the fourth parameter, the search starts at the beginning of the range for a forward search or the end of the range for a reverse search. When searching a range, SEARCH_QUIETLY matches only text inside the range. It does not look at text outside the range.

If you specify a buffer for the fourth parameter, the search starts at the beginning of the buffer for a forward search or the end of the buffer for a reverse search.

To determine whether the searched text contains a match, SEARCH_QUIETLY examines the character at the starting position and attempts to match the character against the pattern, text, or keyword specified. By default, the search is unanchored. This allows SEARCH_QUIETLY to move one character in the direction of the search if the character at the start position does not match. SEARCH_QUIETLY continues in this manner until it finds a match or reaches the bounds of the buffer or range.

To prevent SEARCH_QUIETLY from moving the starting position in the direction of the search, use the ANCHOR keyword when you define the pattern to be matched.

SEARCH_QUIETLY does not change the current buffer or the editing point in that buffer.

For more information about searching, see the Guide to the DEC Text Processing Utility.

Signaled Errors

TPU$_TOOFEW ERROR SEARCH_QUIETLY requires at least two arguments.
TPU$_TOOMANY ERROR SEARCH_QUIETLY accepts no more than four arguments.
TPU$_ARGMISMATCH ERROR One of the parameters to SEARCH_QUIETLY is of the wrong type.
TPU$_INVPARAM ERROR One of the parameters to SEARCH_QUIETLY is of the wrong type.
TPU$_BADKEY WARNING You specified an incorrect keyword to SEARCH_QUIETLY.
TPU$_MINVALUE WARNING The integer parameter to SEARCH_QUIETLY must be greater than or equal to --1.
TPU$_MAXVALUE WARNING The integer parameter to SEARCH_QUIETLY must be less than or equal to 3.
TPU$_NOCURRENTBUF ERROR If you do not specify a buffer or range to search, you must position to a buffer before searching.
TPU$_CONTROLC ERROR You pressed Ctrl/C while SEARCH_QUIETLY was executing.
TPU$_ILLPATAS ERROR The pattern to SEARCH_QUIETLY contained a partial pattern assignment to a variable not defined in the current context.

Example

The following example searches the range the_range for all occurrences of the pattern "blue skies". If SEARCH_QUIETLY finds the pattern, the procedure redefines the_range to begin after the end of the pattern just found. If the procedure did not redefine the range, SEARCH_QUIETLY would keep finding the first occurrence over and over. The procedure reports the number of occurrences of the pattern. A procedure that uses SEARCH_QUIETLY does not trap the TPU$_STRNOTFOUND error because SEARCH_QUIETLY does not signal this error.

PROCEDURE user_search_range 
   LOCAL found_count; 
 
   ON_ERROR 
     [TPU$_CONTROLC]: 
       MESSAGE ( FAO ("Found !SL occurrences.", found_count)); 
       RETURN; 
     [OTHERWISE]: 
       ABORT; 
   ENDON_ERROR; 
 
   found_count := 0; 
   the_pattern := "blue skies"; 
   the_range := CREATE_RANGE (BEGINNING_OF (CURRENT_BUFFER), 
                              END_OF (CURRENT_BUFFER), NONE); 
 
   found_range := CREATE_RANGE (BEGINNING_OF (CURRENT_BUFFER), 
                                BEGINNING_OF (CURRENT_BUFFER), NONE); 
 
   LOOP 
      the_range := CREATE_RANGE (END_OF (found_range), 
                   END_OF (the_range), NONE); 
   
      found_range := SEARCH_QUIETLY (the_pattern, FORWARD, 
                     NO_EXACT, the_range); 
 
      found_count := found_count + 1; 
   ENDLOOP; 
ENDPROCEDURE; 
 
      


SELECT


Format

marker := SELECT ( {BLINK |BOLD |NONE |REVERSE |UNDERLINE})


Parameters

BLINK

Specifies that the selected characters are to blink.

BOLD

Specifies that the selected characters are to be bolded.

NONE

Applies no video attributes to selected characters.

REVERSE

Specifies that the selected characters are to be displayed in reverse video.

UNDERLINE

Specifies that the selected characters are to be underlined.

Return Value


A marker for the editing point in the current buffer.

Description

The SELECT procedure returns a marker for the editing point in the current buffer. You must specify how the marker is to be displayed on the screen (no special video, reverse video, bolded, blinking, or underlined).

The marker returned by SELECT indicates the first character position in a select range. The video attribute that you specify for the marker applies to all the characters in a select range. For information on creating a select range, see SELECT_RANGE.

SELECT returns a special marker that establishes the beginning of a select range. The marker is positioned at the character position that is the editing point when the SELECT built-in procedure is executed. (The marker is actually positioned between character positions, rather than on a character position.) A select range includes all the characters between the select marker and the current position, but not the character at the current position.

Using SELECT may cause DECTPU to insert padding spaces or blank lines in the buffer. SELECT causes the screen manager to place the editing point at the cursor position if the current buffer is mapped to a visible window. For more information on the distinction between the cursor position and the editing point, see Appendix C.

If the cursor is not located on a character (that is, if the cursor is before the beginning of a line, beyond the end of a line, in the middle of a tab, or below the end of the buffer), DECTPU inserts padding spaces or blank lines into the buffer to fill the space between the cursor position and the nearest text.

Only one select marker for a buffer can be active at any one time. If a buffer is associated with more than one visible window, the select range is displayed in only one window (the current or most recent window).

If the buffer in which you are selecting text is associated with the current window, as you move from the select marker to another character position in the same buffer, all the characters over which you move the cursor are included in the select range, and the video attribute that you specify for the select marker is applied to the characters in the range. The video attribute of a selected character is not visible when you are positioned on the character, but once you move beyond the character, the character is displayed with the attribute you specify.

If two or more windows are mapped to the same buffer and one of the windows is the current window, only the current window displays the select area. If two or more windows are mapped to different buffers, you can have more than one visible select area on the screen at the same time. If none of the windows on the screen is the current window, the visible window that was most recently current displays the select area.

If the current character is deleted, the marker moves to the nearest character position. The nearest character position is determined in the following way:

  1. If there is a character position on the same line to the right, the marker moves to this position, even if the position is at the end of the line.
  2. If the line on which the marker is located is deleted, the marker moves to the first position on the following line.

If you are positioned at the select marker and you insert text, the select marker moves to the first character of the inserted text. You can move one column past the last character in a line. (With free cursor motion, you can move even further beyond the last character of a line.) However, if you establish a select marker beyond the last character in a line, no video attribute is visible for the marker.

Signaled Errors

TPU$_ONESELECT WARNING SELECT is already active in the current buffer.
TPU$_TOOFEW ERROR SELECT requires one argument.
TPU$_TOOMANY ERROR SELECT accepts only one argument.
TPU$_NEEDTOASSIGN ERROR SELECT must be on the right-hand side of an assignment statement.
TPU$_NOCURRENTBUF ERROR You must position to a buffer before using SELECT.
TPU$_BADKEY WARNING You specified the wrong keyword to SELECT.
TPU$_INVPARAM ERROR SELECT's parameter is not a keyword.

Examples

The following example places a marker at the editing point. Because NONE is specified, no video attributes are applied to a select range that has this marker as its beginning.
#1

select_mark := SELECT (NONE) 
      

The following example creates a bold marker that is used as the beginning of a select region. As you move the cursor, the characters that you select are bolded. To turn off the selection of characters, set the variable user_v_beginning_of_select to 0.

#2

!  Bold selected text 
 
PROCEDURE user_start_select 
 
   user_v_beginning_of_select := SELECT (BOLD); 
 
ENDPROCEDURE; 
 
      


SELECT_RANGE


Format

range := SELECT_RANGE


Parameters

None.

Return Value


A range that contains all the characters between the marker established with SELECT and the editing point.

Description

The SELECT_RANGE procedure returns a range that contains all the characters between the marker established with the SELECT built-in procedure and the editing point. SELECT_RANGE does not include the current character.

If you select text in a forward direction, the select range includes the marked character and all characters up to but not including the current character. If you select text in a reverse direction from the marker, the select range includes the current character and all characters up to but not including the marked character.

You use SELECT_RANGE in conjunction with SELECT to let you mark a section of text for treatment as an entity.

Using SELECT_RANGE may cause DECTPU to insert padding spaces or blank lines in the buffer. SELECT_RANGE causes the screen manager to place the editing point at the cursor position if the current buffer is mapped to a visible window. For more information on the distinction between the cursor position and the editing point, see Appendix C.

If the cursor is not located on a character (that is, if the cursor is before the beginning of a line, beyond the end of a line, in the middle of a tab, or below the end of the buffer), DECTPU inserts padding spaces or blank lines into the buffer to fill the space between the cursor position and the nearest text.

Signaled Errors

TPU$_NOSELECT WARNING There is no active select range in the current buffer.
TPU$_SELRANGEZERO WARNING The select range contains no selected characters.
TPU$_NEEDTOASSIGN ERROR SELECT_RANGE must be on the right-hand side of an assignment statement.
TPU$_TOOMANY ERROR SELECT_RANGE takes no arguments.
TPU$_NOCURRENTBUF WARNING There is no current buffer.

Examples

The following example puts the range for the currently selected characters in the variable select_1:
#1

select_1 := SELECT_RANGE 
      

The following example shows the use of SELECT_RANGE multiple times in the same procedure:

#2

PROCEDURE user_select 
 
! Start a select region 
 
    user_select_position := SELECT (REVERSE); 
    MESSAGE ("Selection started."); 
 
! Move 5 lines and create a select region 
 
    MOVE_VERTICAL (5); 
    SR1 := SELECT_RANGE; 
 
! Move 5 lines and create another select region 
 
    MOVE_VERTICAL (5); 
    SR2 := SELECT_RANGE; 
 
! Stop the selection by setting the select marker to 0. 
 
    user_select_position := 0; 
 
ENDPROCEDURE; 
 
      


SEND


Format

SEND ( {buffer |range |string}, process)


Parameters

buffer

The buffer whose contents you want to send to the subprocess.

range

The range whose contents you want to send to the subprocess.

string

The string that you want to send to the subprocess.

process

The process to which you want to send data.

Description

The SEND procedure passes data to an OpenVMS subprocess. All output from the process is stored in the buffer that was associated with the process when you created it. See the CREATE_PROCESS built-in procedure. Your editing stops until the process responds to what is sent.

If you specify a buffer or a range as the data to pass to a process, the lines of the buffer or range are sent as separate records.

The maximum length of data that you can send in one SEND statement is 1024 characters. If you are constructing a command line for DCL processing that is longer than the maximum limit of a DCL line, the subprocess outputs a message stating that the record you are sending is too large for DCL to process. The process then terminates.

Note

At this time, the DCL line limit is 256 characters. This is less than the character length that the SEND built-in procedure is capable of sending to a process.

Before you send a string to a process that is running DCL, you should verify that the length of the string does not exceed the limit specified in your OpenVMS documentation. If your string is longer than that limit, you must break the string into two or more strings, use the DCL line continuation character, and send each string separately.

Signaled Errors

TPU$_NOPROCESS WARNING Subprocess that you tried to send to has already terminated.
TPU$_SENDFAIL WARNING Unable to send input to a subprocess.
TPU$_TOOFEW ERROR Too few arguments passed to the SEND built-in.
TPU$_TOOMANY ERROR Too many arguments passed to the SEND built-in.
TPU$_INVPARAM ERROR Wrong type of data sent to the SEND built-in.
TPU$_NOTMODIFIABLE WARNING Attempt to change unmodifiable buffer. The buffer to which a subprocess writes output must be modifiable.
TPU$_DELETEFAIL WARNING Unable to terminate the subprocess.
TPU$_NOSENDBUF WARNING Input buffer is the same as the output buffer.
TPU$_CONTROLC ERROR The execution of the command you sent terminated because you pressed Ctrl/C.

Examples

The following example sends the DCL DIRECTORY command to the OpenVMS process named user_process. The process must already be created with the CREATE_PROCESS built-in procedure so that the output can be stored in the buffer associated with the process.
#1

SEND ("directory", user_process) 
      


SEND_CLIENT_MESSAGE


Format

SEND_CLIENT_MESSAGE ( {STUFF_SELECTION |KILL_SELECTION})


Parameters

STUFF_SELECTION

A keyword that indicates that the client message to be sent is the STUFF_SELECTION client message.

KILL_SELECTION

A keyword that indicates that the client message to be sent is the KILL_SELECTION client message.

Description

The SEND_CLIENT_MESSAGE procedure sends either of two client messages---STUFF_SELECTION or KILL_SELECTION---to other DECwindows applications. The EVE layered application cannot designate the application that is to receive the client message. DECTPU handles sending the message to the correct DECwindows application.

Signaled Errors

TPU$_NORETURNVALUE ERROR Does not return a value.
TPU$_TOOFEW ERROR SEND_CLIENT_MESSAGE requires one argument.
TPU$_TOOMANY ERROR SEND_CLIENT_MESSAGE accepts only one argument.
TPU$_BADKEY WARNING Keyword must be either KILL_SELECTION or STUFF_SELECTION.
TPU$_INVPARAM ERROR The parameter must be a keyword.
TPU$_NOGBLSELDATA WARNING There is no owner of the PRIMARY global selection to send a client message to.
TPU$_NOFOCUSOWNER WARNING There is no owner of the input focus to send a client message to.

SEND_EOF


Format

SEND_EOF (process)


Parameter

process

The process to which the end-of-file message is being sent.

Description

The SEND_EOF procedure uses features of the mailbox driver to send an end-of-file message (IO$_WRITEOF) to a subprocess. The end-of-file message causes a pending read from a subprocess to be completed with an SS$_ENDOFFILE status.

Signaled Errors

TPU$_SENDFAIL WARNING Unable to send input to a subprocess.
TPU$_NOPROCESS WARNING No subprocess to send to.
TPU$_TOOFEW ERROR Too few arguments passed to the SEND_EOF built-in.
TPU$_TOOMANY ERROR Too many arguments passed to the SEND_EOF built-in.
TPU$_INVPARAM ERROR Wrong type of data sent to the SEND_EOF built-in.
TPU$_NOTMODIFIABLE WARNING Attempt to change unmodifiable buffer. The buffer to which a subprocess writes output must be modifiable.
TPU$_DELETEFAIL WARNING Unable to terminate the subprocess.

Example

The following example sends an end-of-file to sub_proc1:

SEND_EOF (sub_proc1) 
      


SET


Format

SET (keyword, parameter [[,...]])


Parameters

keyword

The keyword used as the first parameter specifies which feature is being established or changed. Following are the valid keywords for SET:

These keywords and the parameters that follow them are described on the following pages. The descriptions of the keywords are organized alphabetically.

parameter [[,...]]

The number of parameters following the first parameter varies according to the keyword you use. The parameters are listed in the format section of the applicable keyword description.

Description

With the SET procedure, you can establish or change certain features of a DECTPU session. SET requires a keyword as its first parameter. The keyword indicates which feature of the editor is being set. You can set the mode for entering text, the text that is to be displayed on certain parts of the screen, the direction of a buffer, the status of a buffer, and so on.

Both the programmer creating an editing interface and the person using the interface can use SET. The programmer can establish certain default behavior and screen displays for an editing interface. The user can change the default behavior and do some simple customizing of an existing DECTPU interface.


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
6020PRO_024.HTML