Document revision date: 30 March 2001

## DEC Text Processing Utility Reference Manual

Previous | Contents | Index

The following example removes all parenthesized text from a buffer. The text may span several lines. It does not handle multiple levels of parentheses.

#2
    PROCEDURE user_remove_paren_text (paren_buffer)

       LOCAL pat1,
             paren_text,
             searched_text;

       pat1 := "(" + UNANCHOR + ")";
       searched_text := paren_buffer;
       LOOP
          paren_text := SEARCH_QUIETLY (pat1, FORWARD, EXACT,
                                       searched_text);
          EXITIF paren_text = 0;
          ERASE (paren_text);
          searched_text := CREATE_RANGE (END_OF (paren_text),
                                        END_OF (paren_buffer), NONE);
      ENDLOOP;
    ENDPROCEDURE;

## UNDEFINE_KEY

### Format

> UNDEFINE_KEY (keyword [[, {key-map-list-name|key-map-name}]])

### Parameters

> #### keyword

> The name of a key or key combination that you can define. See the Guide to the DEC Text Processing Utility for a list of the valid DECTPU key names.

> #### key-map-list-name

> Specifies a key map list in which the key is defined. The first definition of the key in the key maps that make up the key map list is deleted. If neither a key map nor a key map list is specified, the key map list bound to the current buffer is used.

> #### key-map-name

> Specifies a key map in which the key is defined. The first definition of the key in the key map is deleted. If neither a key map nor a key map list is specified, the key map list bound to the current buffer is used.

### Description

> The UNDEFINE_KEY procedure removes the current binding from the key that you specify. After you use UNDEFINE_KEY, the key you specify is no longer defined. DECTPU does not save any previous definitions that you may have associated with the key. However, any definitions of the specified key in key maps or key map lists other than the ones you specified are not removed.

> DECTPU writes a message to the message buffer telling you that the key is undefined if you try to use it after you have undefined it.

#### Signaled Errors

TPU$_NODEFINITION | WARNING | There is no definition for this key.
TPU$_NOTDEFINABLE | WARNING | First argument is not a valid reference to a key.
TPU$_NOKEYMAP | WARNING | Second argument is not a defined key map.
TPU$_NOKEYMAPLIST | WARNING | Second argument is not a defined key map list.
TPU$_KEYMAPNTFND | WARNING | The key map listed in the second argument is not found.
TPU$_EMPTYKMLIST | WARNING | The key map list specified in the second argument contains no key maps.
TPU$_TOOFEW | ERROR | Too few arguments passed to the UNDEFINE_KEY built-in.
TPU$_TOOMANY | ERROR | Too many arguments passed to the UNDEFINE_KEY built-in.
TPU$_INVPARAM | ERROR | Wrong type of data sent to the UNDEFINE_KEY built-in.

### Examples

> The following example undefines a key. You can use this kind of procedure for keypad initialization procedures.

#1
    ! Parameters:
    !
    !     Name         Function                   Input or Output?
    !     ----         --------                   ----------------
    !     which_key    Keyword for key to clear     input

    PROCEDURE user_clear_key (which_key)

       IF (LOOKUP_KEY (which_key, PROGRAM) <> 0)
       THEN
           UNDEFINE_KEY (which_key);
       ELSE
           MESSAGE ("Key not defined");
       ENDIF;
    ENDPROCEDURE;

> The following example deletes all of the key definitions in the key map TPU$KEY_MAP:

#2
    PROCEDURE delete_all_definitions

       LOCAL key;

       LOOP
          key := GET_INFO (DEFINED_KEY, "first", "tpu$key_map");
          EXITIF key = 0;
          UNDEFINE_KEY (key, "tpu$key_map");
       ENDLOOP;
    ENDPROCEDURE;

## UNMANAGE_WIDGET

### Format

> UNMANAGE_WIDGET (widget [[, widget... ]])

### Parameter

> #### widget

> The widget to be unmanaged.

### Description

> The UNMANAGE_WIDGET procedure makes the specified widget and all of its children invisible. If you want to unmanage several widgets that are children of the same parent, but you do not want to unmanage the parent, include all the children in a single call to UNMANAGE_WIDGET. Unmanaging several widgets at once is more efficient than unmanaging one widget at a time.

#### Signaled Errors

TPU$_INVPARAM | ERROR | You specified a parameter of the wrong type.
TPU$_TOOFEW | ERROR | Too few arguments passed to the UNMANAGE_WIDGET built-in.
TPU$_NORETURNVALUE | ERROR | UNMANAGE_WIDGET cannot return a value.
TPU$_REQUIRESDECW | ERROR | You can use the UNMANAGE_WIDGET built-in only if you are using DECwindows DECTPU.
TPU$_WIDMISMATCH | ERROR | You have specified a widget whose class is not supported.

### Example

> The following example removes EVE's FIND dialog box from the screen:

    UNMANAGE_WIDGET (eve$x_find_dialog);

## UNMAP

### Format

> UNMAP ({widget|window})

### Parameters

> #### widget

> The widget you want to make invisible.

> #### window

> The window you want to remove from the screen.

### Description

> The UNMAP procedure disassociates a window from its buffer and removes the window or widget from the screen. If you unmap the current window, DECTPU tries to move the cursor position to the window that was most recently the current window. The window in which DECTPU positions the cursor becomes the current window, and the buffer that is associated with this window becomes the current buffer.

> The screen area of the window you unmap is either erased or returned to any windows that were occluded by the window you unmapped. DECTPU returns lines to adjacent windows if the size of the windows requires the lines that were used for the window you unmap. The size of a window is determined by the values you specified for the CREATE_WINDOW built-in procedure when you created the window, or by the values you specified for the ADJUST_WINDOW built-in procedure if you changed the size of the window. If adjacent windows do not require the lines that were used by the window you unmap, the lines that the window occupied on the screen remain blank.

> The window that you unmap is not deleted from the list of available windows. You can cause the window to appear on the screen again with MAP. UNMAP does not have any effect on the buffer that was associated with the window being unmapped.

> Unmapping a widget does not delete the widget. Future MAP operations will make the widget visible again.

#### Signaled Errors

TPU$_TOOFEW | ERROR | UNMAP requires one parameter.
TPU$_TOOMANY | ERROR | UNMAP accepts only one parameter.
TPU$_INVPARAM | ERROR | One or more of the specified parameters have the wrong type.
TPU$_WINDNOTMAPPED | WARNING | Window is not mapped to a buffer.

### Examples

> The following example removes the main window from the screen and disassociates from the main window the buffer that was mapped to it:

#1
    UNMAP (main_window)

> The following example unmaps the current window and puts two new windows in its place. (If the window that you are replacing has a status line, this line is not included in the screen area used by the two new windows. This is because GET_INFO (window, "visible_bottom") does not take the status line into account.)

#2
    PROCEDURE user_one_window_to_two

       LOCAL wind_length,
             wind_half,
             first_line,
            last_line;

       cur_wind := CURRENT_WINDOW;

    ! If it exists
       IF (cur_wind <> 0)
       THEN
           first_line := GET_INFO (cur_wind, "visible_top");
           last_line := GET_INFO (cur_wind, "visible_bottom");
           wind_buf := GET_INFO (cur_wind, "buffer");
           UNMAP (cur_wind);
       ELSE
    ! If there is no current window then create an empty buffer

           first_line := 1;
           last_line := GET_INFO (SCREEN, "visible_length");
           wind_buf := CREATE_BUFFER ("Empty Buffer");
        ENDIF;

       wind_length := (last_line - first_line) + 1;
       wind_half := wind_length/2;
       new_window_1 := CREATE_WINDOW (first_line, wind_half, OFF);

       SET (VIDEO, new_window_1, UNDERLINE);
       new_window_2 := CREATE_WINDOW (wind_half+1,
                       last_line-wind_half, OFF);

    ! Associate the same buffer with both windows
    ! and map the windows to the screen

       MAP (new_window_1, wind_buf);
       MAP (new_window_2, wind_buf);
    ENDPROCEDURE;

## UPDATE

### Format

> UPDATE ({ALL|window})

### Parameters

> #### ALL

> A keyword that directs DECTPU to make all visible windows reflect the current state of the buffers mapped to them.

> #### window

> The window that you want updated. The window must be mapped to the screen for the update to occur.

### Description

> The UPDATE procedure causes the screen manager to make a window reflect the current internal state of the buffer that is associated with the window. One important task that UPDATE performs is to move the cursor to the editing point if the cursor and the editing point are not synchronized when the UPDATE built-in procedure is executed.

> The screen manager updates windows after each keystroke. However, if a key has a procedure bound to it, DECTPU may execute many statements when that key is pressed. By default, UPDATE does not reflect the result of any statement in a procedure bound to a key until all the statements in the procedure have been executed. As a result, the screen may not reflect the current state of the buffer during execution of a procedure bound to a key. If you want the screen to reflect changes before the entire procedure is executed, you can force an immediate update by adding an UPDATE statement to the procedure.

> UPDATE (window) affects a single window that is visible on the screen. If the buffer associated with the window you use as a parameter is associated with other windows that are mapped to the screen, all of these windows may be updated.

> UPDATE (ALL) updates all visible windows. The difference between the UPDATE (ALL) built-in procedure and the REFRESH built-in procedure is that UPDATE (ALL) makes whatever changes are necessary on a window-by-window basis. REFRESH clears the screen and repaints everything from scratch, as well as reinitializing scrolling regions and other terminal-dependent settings.

> For more information on how the DECTPU screen manager uses the UPDATE built-in in various circumstances, see Appendix C. For more information on the results of the REFRESH built-in, see the description of REFRESH in this chapter.

#### Signaled Errors

TPU$_TOOFEW | ERROR | UPDATE requires one parameter.
TPU$_TOOMANY | ERROR | You specified more than one parameter.
TPU$_INVPCARAM | ERROR | The specified parameter has the wrong type.
TPU$_BADKEY | ERROR | The keyword must be ALL.
TPU$_UNKKEYWORD | ERROR | You specified an unknown keyword.
TPU$_WINDNOTMAPPED | WARNING | You cannot update a window that is not on the screen.

### Examples

> The following example causes the screen manager to make new_window reflect the current internal state of the buffer associated with new_window:

#1
    UPDATE (new_window)

> The following example updates the screen to display the new line of text that you are inserting before the top line of the window. (When you insert text in front of the top of a window, the included text is not visible on the screen unless you use a procedure such as this one to ensure that the text is displayed.)

#2
    PROCEDURE user_show_first_line

       LOCAL old_position,         ! Marker of position before scroll
             new_position;         ! Marker of position after scroll

       UPDATE (CURRENT_WINDOW);
       IF (GET_INFO (CURRENT_WINDOW, "current_row") =
          GET_INFO (CURRENT_WINDOW, "visible_top"))
          AND
             (CURRENT_COLUMN = 1)
       THEN
           old_position := MARK (NONE);
           SCROLL (CURRENT_WINDOW, -1);
           new_position := MARK (NONE);

    ! Make sure we scrolled before doing the CURSOR_VERTICAL

          IF new_position <> old_position
          THEN
              CURSOR_VERTICAL (1);
          ENDIF;
       ENDIF;
    ENDPROCEDURE;

## WRITE_CLIPBOARD

### Format

> WRITE_CLIPBOARD ( clipboard_label, {buffer |range |string})

### Parameters

> #### clipboard_label

> The label for multiple entries in the clipboard. Because the clipboard does not currently support multiple labels, use any string, including the null string, to specify this parameter.

> #### buffer

> The buffer that contains text to be written to the clipboard. DECTPU represents line breaks by a line-feed character (ASCII (10)). If you specify a buffer, DECTPU converts the buffer to a string, replacing line breaks with line feeds and replacing the white space before the left margin with padding blanks.

> The buffer must contain at least one character or line break. If it does not, DECTPU signals TPU$_CLIPBOARDZERO.

> #### range

> The range that contains text to be written to the clipboard. DECTPU represents line breaks by a line-feed character (ASCII (10)). If you specify a range, DECTPU converts the range to a string, replacing line breaks with line feeds and replacing the white space before the left margin with padding blanks.

> The range must contain at least one character or line break. If it does not, DECTPU signals TPU$_CLIPBOARDZERO.

> #### string

> The string that contains text to be written to the clipboard. The string must contain at least one character. If it does not, DECTPU signals TPU$_CLIPBOARDZERO.

### Description

> The WRITE_CLIPBOARD procedure writes string format data to the clipboard. The clipboard_label parameter provides support for multiple entries on the clipboard; at present, however, the clipboard does not support multiple entries.

#### Signaled Errors

TPU$_CLIPBOARDLOCKED | WARNING | The clipboard is locked by another process.
TPU$_CLIPBOARDZERO | WARNING | The data to be written to the clipboard have zero length.
TPU$_TRUNCATE | WARNING | DECTPU has truncated characters from the data written because you specified a buffer or range that contains more than 65535 characters.
TPU$_INVPARAM | ERROR | One of the parameters was specified with data of the wrong type.
TPU$_NORETURNVALUE | ERROR | WRITE_CLIPBOARD cannot return a value.
TPU$_REQUIRESDECW | ERROR | You can use the WRITE_CLIPBOARD built-in only if you are using DECwindows DECTPU.
TPU$_TOOFEW | ERROR | Too few arguments passed to the WRITE_CLIPBOARD built-in.
TPU$_TOOMANY | ERROR | Too many arguments passed to the WRITE_CLIPBOARD built-in.

### Example

> The following example writes the contents of the range this_range to the clipboard:

    WRITE_CLIPBOARD ("", this_range);

## WRITE_FILE

### Format

> [[string2 := ]] WRITE_FILE ( {buffer|range} [[,string1 ]] [[, {ON |OFF |1 |0} ]])

### Parameters

> #### buffer

> The buffer whose contents you want to write to a file.

> #### range

> The range whose contents you want to write to a file.

> If you use WRITE_FILE on a range that does not start at the left margin of a line, DECTPU does the following:

> - Determines the left margin of the line in which the range starts
> - Writes the range to the output file starting at the same left margin as the margin of the line where the range starts

> For example, if you write a range that starts in column 30 of a line whose left margin is 10, WRITE_FILE writes the range in the output file starting at column 10.

> #### string1

> A string that specifies the file to which the contents of the buffer are to be written. If you do not specify a full file specification, DECTPU determines the output file specification by using the current device and directory as defaults. The string is case insensitive.

> This parameter is optional. If you omit it, DECTPU uses the associated output file name for the buffer. If there is no associated file name, DECTPU prompts you for one. If you do not give a file name at the prompt, DECTPU does not write to a file. In that case, the optional string2 that is returned is a null string.

> #### ON

> A keyword specifying that output is padded with spaces to keep the first character of each record at the same column as the text in the buffer. This is the default.

> #### OFF

> A keyword specifying that no padding spaces are inserted when writing to the file.

### Return Value

A string that represents the file specification of the file created.

### Description

> The WRITE_FILE procedure writes data to the file that you specify. WRITE_FILE optionally returns a string that is the file specification of the file created. If you specify a result, WRITE_FILE returns a string that is the file specification of the file to which the data was written.

> DECTPU uses a flag to mark a buffer as modified or not modified. When you write data from a buffer to an external file, DECTPU clears the modified flag for that buffer. If you do not make any further modifications to that buffer, DECTPU does not consider the buffer as being modified and does not write out the file by default when you exit. If an error occurs while DECTPU is writing a file, DECTPU does not clear the modified flag.

> When the contents of a buffer are written to a file, the associated journal file (if any) is closed and deleted and a new journal file is created. The new file contains the name of the file to which the buffer was written.

> Deleting the file that has been written out invalidates the buffer-change journal.

#### Signaled Errors

TPU$_CONTROLC | ERROR | The execution of the write operation terminated because you pressed Ctrl/C.
TPU$_TOOFEW | ERROR | WRITE_FILE requires at least one parameter.
TPU$_TOOMANY | ERROR | WRITE_FILE accepts no more than two parameters.
TPU$_ARGMISMATCH | ERROR | One of the parameters to WRITE_FILE is of the wrong type.
TPU$_INVPARAM | ERROR | One of the parameters to WRITE_FILE is of the wrong type.

DECTPU's file I/O routine can signal the following completion codes. You can provide your own file I/O routine by using the DECTPU callable interface. If you do so, WRITE_FILE's completion status depends upon what status you signaled in your file I/O routine.

TPU$_OPENOUT | ERROR | WRITE_FILE could not create the output file.
TPU$_NOFILEACCESS | ERROR | WRITE_FILE could not connect to the newly created output file.
TPU$_WRITEERR | ERROR | WRITE_FILE could not write the text to the file because it encountered a file system error during the operation.
TPU$_CLOSEOUT | ERROR | WRITE_FILE encountered a file system error when closing the file.

### Examples

> The following example writes the contents of the paste buffer to the file named MYFILE.TXT:

#1
    WRITE_FILE (paste_buffer, "myfile.txt")

> The following example writes the contents of a buffer called extra_buf to a file. (Because you do not specify a file name, the associated file for the buffer is used.) The procedure then removes the extra window and buffer from your editing context.

#2
    PROCEDURE user_write_file

       WRITE_FILE (extra_buf);
       DELETE (extra_window);
       DELETE (extra_buf);

    ! Return the lines from extra_window to the main window

       ADJUST_WINDOW (main_window, -11, 0);

    ENDPROCEDURE;

## WRITE_GLOBAL_SELECT

### Format

> WRITE_GLOBAL_SELECT ( {array |buffer |integer |range |string |NONE})

### Parameters

> #### array

> An array that passes information about a global selection whose contents describe information that is not of a data type supported by DECTPU. For example, the array could pass information about a pixmap, an icon, or a span.

> DECTPU does not use or alter the information in the array; the application layered on DECTPU is responsible for determining how the information is used, if at all. Because the array is used to pass information to and from other DECwindows applications, all applications that send or receive information whose data type is not supported by DECTPU must agree on how the information is to be sent and used.

> The application sending the information is responsible for creating the array and giving it the proper structure. The array's structure is as follows:

> - The element array {0} contains a string naming the data type of the information being passed. For example, if the information being passed is a span, the element contains the string "SPAN".
> - The element array {1} contains either the integer 8, indicating that the information is passed as a series of bytes, or the integer 32, indicating that the information is passed as a series of longwords.
> - If array {1} contains the value 8, the element array {2} contains a string, and there are no array elements after array {2}. The string does not name anything; rather it is a series of bytes. The meaning and use of the information is agreed upon by convention among the DECwindows applications.
> - If array {1} contains the value 32, the remaining elements of the array contain integer data. In this case, the array can have any number of elements after array {2}. These elements must be numbered sequentially, starting at array {3}. All the elements contain integers. Each integer represents a longword of data. To determine how many longwords are being passed, an application can determine the length of the array and subtract 2 to allow for elements array {0} and array {1}.

> #### buffer

> The buffer that contains the information to be sent to the requesting application as the response to the global selection information request. If you specify a buffer, DECTPU converts the buffer to a string, converts line breaks to line feeds, and inserts padding blanks before text to fill any unoccupied space before the left margin.

> #### integer

> An integer whose value is to be sent to the requesting application as the response to the global selection information request. DECTPU sends the information in integer format.

> #### range

> The range that contains the information to be sent to the requesting application as the response to the global selection information request. If you specify a range, DECTPU converts the buffer to a string, converts line breaks to line feeds, and inserts padding blanks before and after text to fill any unoccupied space before the left margin.

> #### string

> The string that contains the information to be sent to the requesting application as the response to the global selection information request. DECTPU sends the information in string format.

> #### NONE

> A keyword indicating that no information about the global selection is available.

### Description

> The WRITE_GLOBAL_SELECT procedure sends requested information about a global selection from the DECTPU layered application to the application that issued the information request. WRITE_GLOBAL_SELECT is valid only inside a routine that responds to requests for information about a global selection.

> Previous | Next | Contents | Index

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