Document revision date: 30 March 2001

## DEC Text Processing Utility Reference Manual

Previous | Contents | Index

The following example puts the text from the scratch buffer before the editing point in the main buffer. The text in the scratch buffer is removed; no copy of it is left there.

#2
    PROCEDURE user_move_text

       LOCAL this_mode;

    ! Save mode of current buffer in this_mode
       this_mode := GET_INFO (CURRENT_BUFFER, "mode");

    ! Set current buffer to insert mode
       SET (INSERT, CURRENT_BUFFER);

    ! Move the scratch buffer text to the current buffer
       MOVE_TEXT (scratch_buffer);

    ! Reset current buffer to original mode
       SET (this_mode, CURRENT_BUFFER);
    ENDPROCEDURE;

## MOVE_VERTICAL

### Format

> MOVE_VERTICAL (integer)

### Parameter

> #### integer

> The signed integer value that indicates the number of lines that the editing point should be moved. A positive integer specifies movement toward the end of the buffer. A negative integer specifies movement toward the beginning of the buffer.

### Description

> The MOVE_VERTICAL procedure modifies the editing point in the current buffer by the number of lines you specify. The adjustment that MOVE_VERTICAL makes is tied to text. DECTPU tries to retain the same character offset relative to the beginning of the line when moving vertically. However, if there are tabs in the lines, or the lines have different margins, the editing point does not necessarily retain the same column position on the screen.

> By default, DECTPU keeps the cursor at the same offset on each line. However, because DECTPU counts a tab as one character regardless of how wide the tab is, the cursor's column position may vary greatly even though the offset is the same.

> To keep the cursor in approximately the same column on each line, use the following statement:

>     SET (COLUMN_MOVE_VERTICAL, ON)

> This statement directs DECTPU to keep the cursor in the same column unless a tab character makes this impossible. If a tab occupies the column position, DECTPU moves the cursor to the beginning of the tab.

> You cannot see the adjustment caused by MOVE_VERTICAL unless the current buffer is mapped to a visible window. If it is, DECTPU scrolls text in the window, if necessary, so that the editing point you establish with MOVE_VERTICAL is within the scrolling limits set for the window.

> Using MOVE_VERTICAL may cause DECTPU to insert padding spaces or blank lines in the buffer. MOVE_VERTICAL 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.

> If you try to move past the beginning or end of a buffer, DECTPU signals a warning message.

#### Signaled Errors

TPU$_TOOFEW | ERROR | MOVE_VERTICAL requires at least one parameter.
TPU$_TOOMANY | ERROR | You specified more than one parameter.
TPU$_INVPARAM | ERROR | One or more of the specified parameters have the wrong type.
TPU$_BEGOFBUF | WARNING | You are trying to move backward past the first character of the buffer.
TPU$_ENDOFBUF | WARNING | You are trying to move forward past the last character of the buffer.
TPU$_NOCURRENTBUF | WARNING | You are not positioned in a buffer.

### Examples

> The following example moves the editing point in the current buffer down five lines toward the end of the buffer:

#1
    MOVE_VERTICAL (+5)

> The following example moves the editing point by sections that are eight lines long:

#2
    PROCEDURE user_move_8_lines

       IF CURRENT_DIRECTION = FORWARD
       THEN
           MOVE_VERTICAL (8);
       ELSE
           MOVE_VERTICAL (- 8);
       ENDIF;
       MOVE_HORIZONTAL(- CURRENT_OFFSET);
    ENDPROCEDURE;

## NOTANY

### Format

> pattern := NOTANY ( {buffer |range |string} [[, integer1 ]])

### Parameters

> #### buffer

> An expression that evaluates to a buffer. NOTANY matches any character not in the resulting buffer.

> #### range

> An expression that evaluates to a range. NOTANY matches any character not in the resulting range.

> #### string

> An expression that evaluates to a string. NOTANY matches any character not in the resulting string.

> #### integer1

> This integer value indicates how many contiguous characters NOTANY matches. The default value for this integer is 1.

### Return Value

A pattern that matches characters not in the string, buffer, or range used as a parameter.

### Description

> The NOTANY procedure returns a pattern that matches a specific number of contiguous characters not in the string, buffer, or range that is used as the first parameter. The second parameter determines the number of characters NOTANY must match. NOTANY does not match across line breaks.

#### Signaled Errors

TPU$_NEEDTOASSIGN | ERROR | NOTANY must appear on the right-hand side of an assignment statement.
TPU$_TOOFEW | ERROR | NOTANY requires at least one argument.
TPU$_TOOMANY | ERROR | NOTANY accepts no more than two arguments.
TPU$_ARGMISMATCH | ERROR | NOTANY was given an argument of the wrong type.
TPU$_INVPARAM | ERROR | NOTANY was given an argument of the wrong type.
TPU$_MINVALUE | WARNING | NOTANY was given an argument less than the minimum value.
TPU$_CONTROLC | ERROR | You pressed Ctrl/C during the execution of NOTANY.

### Examples

> The following example creates a pattern that matches the first character that is not an X, a Y, or a Z. The match fails if no character other than X, Y, or Z is found.

#1
    pat1 := NOTANY ("XYZ")

> The following example creates a pattern that matches any single character other than one of the characters a, b, c, x, and y:

#2
    a_buf := CREATE_BUFFER ("new buffer");
    POSITION (a_buf);
    COPY_TEXT ("xy");
    SPLIT_LINE;
    COPY_TEXT ("abc");
    pat1 := NOTANY (a_buf);

> The following example starts at the current location and looks for the first nonalphabetic, nonlowercase character. The variable non_alpha_range stores the character that matches these conditions.

#3
    !
    ! The following procedure returns a marker pointing to
    ! the next nonalphabetic character or the integer zero
    ! if there are no more nonalphabetic characters.  You
    ! call the procedure in the following way:
    !
    !   non_alpha_marker := user_search_for_nonalpha;

    PROCEDURE user_search_for_nonalpha

       LOCAL pat,
             first_non_alpha;

       pat := NOTANY ("abcdefghijklmnopqrstuvwxyz");

       first_non_alpha := SEARCH_QUIETLY (pat, FORWARD, NO_EXACT);

       IF first_non_alpha <> 0
       THEN
           first_non_alpha := BEGINNING_OF (first_non_alpha);
       ENDIF;

       RETURN first_non_alpha;
    ENDPROCEDURE;

## PAGE_BREAK

### Format

> PAGE_BREAK

### Parameters

> None.

### Description

> The PAGE_BREAK procedure specifies the form-feed character, ASCII(12), as a portion of a pattern to be matched. This character has an ASCII value of 12.

> Although PAGE_BREAK behaves much like a built-in, it is actually a keyword.

> If the form-feed character is the only character on a line, PAGE_BREAK matches the whole line. If the form-feed character is not the only character on a line, PAGE_BREAK matches only the form-feed character.

#### Signaled Error

PAGE_BREAK is a keyword and has no completion codes.

### Example

> The following example places the cursor on the next page in the current buffer. If you are already on the last page of a document, it places the cursor at the end of that document.

    PROCEDURE user_next_page

       LOCAL next_page;

       next_page := SEARCH_QUIETLY (PAGE_BREAK, FORWARD);
       IF next_page <> 0
       THEN
           POSITION (next_page);
       ELSE
           POSITION (end_of (current_buffer));
       ENDIF;
    ENDPROCEDURE;

## POSITION

### Format

> POSITION ({buffer |BUFFER_BEGIN |BUFFER_END |integer |LINE_BEGIN |LINE_END |marker |MOUSE |range |TEXT |window})

### Parameters

> #### buffer

> The buffer in which you want to establish the editing point.

> DECTPU maintains an editing point in each buffer even when the buffer is not the current buffer. When you position to a buffer, the editing point that DECTPU maintains becomes the active editing point. The location at which POSITION establishes the editing point is the last character that the cursor was on when the buffer was most recently current.

> #### BUFFER_BEGIN

> A keyword that directs DECTPU to establish the editing point at the beginning of the current buffer. This is more efficient than using POSITION (BEGINNING_OF (CURRENT_BUFFER)).

> #### BUFFER_END

> A keyword that directs DECTPU to establish the editing point at the end of the current buffer. This is more efficient than using POSITION (END_OF (CURRENT_BUFFER)).

> #### integer

> The number of the record where you want DECTPU to position the editing point.

> A record number indicates the location of a record in a buffer. Record numbers are dynamic; as you add or delete records, DECTPU changes the number associated with a particular record, as appropriate. DECTPU counts each record in a buffer, regardless of whether the line is visible in a window, or whether the record contains text.

> To position the editing point to a given record, specify the record number. The number can be in the range from 1 to the number of records in the buffer plus 1. For example, the following statement positions the editing point to record number 8 in the current buffer:

>     POSITION (8);

> DECTPU places the editing point on the first character of the record.

> Specifying a value of 0 has no effect. Specifying a negative number or a number greater than the number of records in the buffer plus 1 causes DECTPU to signal an error.

> #### LINE_BEGIN

> A keyword that directs DECTPU to establish the editing point at the beginning of the current line.

> #### LINE_END

> A keyword that directs DECTPU to establish the editing point at the end of the current line.

> #### marker

> The marker to which you want to tie the editing point. You can position to either a bound marker or a free marker. (For more information on the distinction between bound and free markers, see the Guide to the DEC Text Processing Utility.) Positioning to a free marker does not cause DECTPU to insert padding blanks between the nearest text and the free marker; such positioning establishes the editing point as free. (For more information on the distinction between free and detached editing points, see Appendix C.)

> #### MOUSE

> A keyword that directs DECTPU to associate the editing point with the location of the pointer cursor.

> In DECwindows DECTPU, you can use the statement POSITION (MOUSE) at any point after the first keyboard or mouse button event. The statement positions the editing point to the location occupied by the pointer cursor at the time of the most recent keyboard or mouse-button event.

> If the pointer cursor is on a window's status line when POSITION (MOUSE) is executed, DECTPU positions the editing point at the line just above the status line.

> Note Be sure that you do not have scroll margins active when you execute POSITION (MOUSE). If scroll margins are active, the result can be unpredictable. Use the SET (CROSS_WINDOW_BOUNDS, OFF) command prior to using POSITION (MOUSE).

> If the pointer cursor is not located in a DECTPU window at the time of the most recent keyboard or mouse-button event, POSITION (MOUSE) returns the status TPU$_NOWINDOW.

> In non-DECwindows DECTPU, POSITION (MOUSE) is valid only during a procedure that is executed as the result of a mouse click. At all other times, the mouse position is not updated.

> The statement POSITION (MOUSE) makes the window in which the pointer cursor is located the current window, and the buffer in which the pointer cursor is located the current buffer.

> #### range

> The range in which you want to place the editing point. The editing point is established at the beginning of the range. To establish the editing point at the end of the range, use the statement POSITION (END_OF (range)).

> #### TEXT

> A keyword that indicates that if the editing point is at a free-cursor location (a portion of the screen where there is no text), the POSITION built-in procedure is to establish the editing point at the nearest location that has a text character in it. The character may be a space or an end of line. If you use POSITION (TEXT) when the editing point is already bound to a character, the built-in has no effect.

> #### window

> The window in which you want to establish the editing point. The window must be mapped to the screen.

> The location at which POSITION establishes the editing point is the last character that the cursor was on when the window was most recently current. If that character has been deleted, the editing point is the character closest to the last character that the cursor was on when the window was current.

> Positioning to a window causes the buffer associated with the window to become the current buffer. This is true whether you directly position to a window, or a new window is mapped as the result of a POSITION (MOUSE) statement.

### Description

> The POSITION procedure ties the editing point to a specific character in a specific buffer, and moves the editing point to a specified record in the current buffer. The character and buffer in which POSITION establishes the editing point depend on which parameter you pass to POSITION.

> The editing point is the location in the current buffer where most editing operations are carried out. DECTPU maintains a marker pointing to an editing point in each buffer, but only the editing point in the current buffer is active. An editing point, whose location is always tied to a character in a buffer, is not necessarily the same as the cursor position, whose location is always tied to a position in a window.

> The POSITION built-in procedure synchronizes the editing point and the cursor position if the current buffer is mapped to a visible window. POSITION also moves the editing point to the specified record in the current buffer.

> When you pass the MOUSE keyword to POSITION, the built-in establishes the mouse pointer's location as the cursor position. POSITION also establishes the window in which the mouse pointer is located as the current window, and establishes the buffer mapped to that window as the current buffer.

> Positioning to a buffer, a marker, or a range does not necessarily move the cursor. DECTPU does not change the cursor position unless the cursor is in a window that is mapped to the buffer specified or implied by the POSITION parameter. For example, if you use POSITION to establish the editing point in a buffer that is not mapped to a window, the cursor is unaffected by the POSITION operation. If you want to do visible editing, you should position to a window rather than a buffer.

> If you try to position to an invisible window, DECTPU issues a warning message.

> For more information on the relationship between the editing point and the cursor position, see Appendix C.

#### Signaled Errors

TPU$_TOOFEW | ERROR | POSITION requires one parameter.
TPU$_TOOMANY | ERROR | You specified more than one parameter.
TPU$_INVPARAM | ERROR | One or more of the specified parameters have the wrong type.
TPU$_ARGMISMATCH | ERROR | Wrong type of data sent to the built-in.
TPU$_BADKEY | WARNING | You specified an invalid keyword.
TPU$_UNKKEYWORD | ERROR | You specified an unknown keyword.
TPU$_BADVALUE | ERROR | You specified a record number less than 0 or greater than the length of the buffer plus 1.
TPU$_MOUSEINV | WARNING | The mouse position is not currently valid.
TPU$_NOWINDOW | WARNING | The pointer cursor was not located in a DECTPU window at the time of the most recent keyboard or mouse-button event.
TPU$_WINDNOTMAPPED | WARNING | Window is not mapped to the screen.
TPU$_WINDNOTVIS | WARNING | Window is totally occluded.

### Examples

> The following example establishes the editing point in the message window. Your position in the window is the same character position you occupied when you were last positioned in the window.

#1
    POSITION (message_window)

> The following example toggles the active editing point between two windows:

#2
    PROCEDURE user_change_windows

       IF CURRENT_WINDOW = main_window
       THEN
           POSITION (extra_window);
       ELSE
           POSITION (main_window);
       ENDIF;
    ENDPROCEDURE;

## QUIT

### Format

> QUIT [[ ({ON |OFF |1 |0} [[, severity ]])]]

### Parameters

> #### ON, 1

> Either keyword, ON or 1, indicates that DECTPU should prompt you to find out whether you want to quit with modified buffers. This is the default value.

> #### OFF, 0

> Either keyword, OFF or 0, indicates that DECTPU should quit without asking you whether to quit with modified buffers.

> #### severity

> If present, the least significant two bits of this integer are used as the severity of the status DECTPU returns to whatever invoked it. The following shows the values and their severity:

> Value | Severity
> --- | ---
> 0 | Warning
> 1 | Success
> 2 | Error
> 3 | Informational

> You cannot force DECTPU to return a fatal severity status.

### Description

> The QUIT procedure leaves the editor without writing to a file. If you modify any buffers that are not set to NO_WRITE and you do not specify OFF as the first parameter to the QUIT built-in procedure, DECTPU tells you that you have modified buffers and asks whether you want to quit. Enter Y (YES) if you want to quit without writing out any modified buffers. Enter N (NO) if you want to retain the modifications you have made and return to the editor. If you specify OFF as the first parameter to QUIT, DECTPU quits without informing you that you have modified buffers. All modifications are lost because DECTPU does not write out buffers when quitting.

> Journal files (if any) are deleted upon quitting.

> Use the EXIT built-in procedure when you have made changes and want to save them when you leave the editor. (For more information, see the description of EXIT.)

> When DECTPU quits, it usually returns a status of TPU$_QUITTING to whatever invoked it. This is a success status.

> This feature is useful if you are using DECTPU to create an application in which quitting, especially before the end of a series of statements executing in batch mode, is an error.

> A special use of QUIT is at the end of your section file when you are compiling it for the first time. See the Guide to the DEC Text Processing Utility for information on creating section files.

#### Signaled Errors

TPU$_CANCELQUIT | WARNING | A NO response was received from the "...continue quitting?" prompt.
TPU$_TOOMANY | ERROR | QUIT accepts no more than two arguments.
TPU$_INVPARAM | ERROR | One of the arguments to QUIT has the wrong data type.
TPU$_BADKEY | WARNING | QUIT accepts only the keywords ON and OFF.
TPU$_NORETURNVALUE | ERROR | QUIT does not return a value.

### Examples

> The following example returns control of execution from an editor layered on DECTPU to the program, application, or operating system that called DECTPU:

#1
    QUIT;

> If you have modified any buffers, you see the following prompt:

>     Buffer modifications will not be saved, continue quitting (Y or N)?

> Enter YES if you want to quit and not save the modifications. Enter NO if you want to return to the editor.

> The following example turns off the display of the success message "Editor successfully quitting" when you use QUIT to leave an editing interface:

#2
    PROCEDURE user_quit

       SET (SUCCESS, OFF);
       QUIT;

    ! Turn message back on in case user answers "No" to the
    ! prompt "Buffer modifications will not be saved, continue
    ! quitting (Y or N)?"

       SET (SUCCESS, ON);
    ENDPROCEDURE;

## RAISE_WIDGET

### Format

> RAISE_WIDGET (widget)

### Parameter

> #### widget

> The widget you want DECTPU to raise. The specified widget must be a subclass of WindowObjClass.

### Description

> The RAISE_WIDGET procedure places the widget at the top of a viewing stack above all sibling widgets. This ensures that the widget window associated with the widget is not obscured by any sibling windows. It calls the XLIB routine XRaiseWindow.

> The widget window is mapped if it is not already mapped.

#### Signaled Errors

TPU$_INVPARAM | ERROR | The parameter to LOWER_WIDGET has the wrong data type.
TPU$_NORETURNVALUE | ERROR | This built-in does not return a result.
TPU$_NOTSUBCLASS | WARNING | The parameter to LOWER_WIDGET is not a widget that has an associated widget window.
TPU$_TOOFEW | ERROR | You specified too few parameters.
TPU$_TOOMANY | ERROR | You specified too many parameters.

## READ_CHAR

### Format

> string := READ_CHAR

### Parameters

> None.

### Return Value

A variable of type string that contains a character entered from the keyboard.

### Description

> The READ_CHAR procedure stores the next character entered from the keyboard in a string variable. The character read by READ_CHAR is not echoed on the screen; therefore, the cursor position does not move.

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 6020PRO_020.HTML