DEC Text Processing Utility Reference Manual

Updated: 11 December 1998

DEC Text Processing Utility Reference Manual

Contents

Index

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

For more information on patterns or pattern searching, see the Guide to the DEC Text Processing Utility.

Signaled Errors

UNANCHOR is a keyword and has no completion codes.

Examples

The following example creates a pattern that matches any text beginning with the letter a and ending with the digits 123. Any amount of text may appear between the a and the 123.

#1
pat1 := "a" + UNANCHOR + "123"

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;

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;

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

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;

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.

Previous Next Contents Index

Copyright © Compaq Computer Corporation 1998. All rights reserved.
Legal

6020PRO_038.HTML

DEC Text Processing Utility Reference Manual

Signaled Errors

Examples

UNDEFINE_KEY

Format

UNDEFINE_KEY (keyword , key-map-list-name key-map-name)

Parameters

keyword

key-map-list-name

key-map-name

Description

Signaled Errors

Examples

UNMANAGE_WIDGET

Format

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

Parameter

widget

Description

Signaled Errors

Example

UNMAP

Format

UNMAP ( widget window)

Parameters

widget

window

Description

Signaled Errors

Examples

UPDATE

Format

UPDATE ( ALL window)

Parameters

ALL

window

Description

Signaled Errors

Examples

WRITE_CLIPBOARD

Format

WRITE_CLIPBOARD ( clipboard_label, buffer range string)

Parameters

clipboard_label

buffer

range

string

Description

Signaled Errors

Example

WRITE_FILE

Format

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

Parameters

buffer

range

string1

ON

OFF

Return Value

Description

Signaled Errors

Examples

WRITE_GLOBAL_SELECT

Format

WRITE_GLOBAL_SELECT ( array buffer integer range string NONE)

Parameters

array

UNDEFINE_KEY (keyword
,

key-map-list-name
key-map-name
)

UNMAP (

widget
window
)

UPDATE (

ALL
window
)

WRITE_CLIPBOARD ( clipboard_label,

buffer
range
string
)

[[string2 := ]] WRITE_FILE (

buffer
range
[[,string1 ]] [[,

ON
OFF
1
0
]])

WRITE_GLOBAL_SELECT (

array
buffer
integer
range
string
NONE
)