HP OpenVMS Systems Documentation

Content starts here

DEC Text Processing Utility Reference Manual

Previous Contents Index

The following example prompts you for the DECTPU statements to be bound to the key that you specify:


PROCEDURE user_define_key

   def := READ_LINE ("Definition: ");
   key := READ_LINE ("Press key to define.",1);

   IF LENGTH (key) > 0
       key := KEY_NAME (key)
       key := LAST_KEY;

   DEFINE_KEY (def,key);


The following example changes the mode of text entry from insert to overstrike, or from overstrike to insert:


PROCEDURE user_change_mode

! Toggle mode between insert and overstrike


! The following statement binds this procedure to the
! key combination Ctrl/A. This emulates the OpenVMS key binding
! that toggles between insert and overstrike for text entry
! in command line editing.

DEFINE_KEY ("user_change_mode", Ctrl_A_KEY);



integer := DEFINE_WIDGET_CLASS (class_name
[[ , creation_routine_name
[[ , creation_routine_image_name ]] ]])



A string that is the name of the desired widget class record. This string is a universal symbol exported by the Toolkit or the widget writer.


A string that is the name of the low-level widget creation routine for this widget class.

If you do not specify this parameter, DECTPU uses the X Toolkit XtCreateWidget routine to create the widget. The routine you specify must have the same calling sequence as the Motif Toolkit widget creation routines.

You can specify a C-binding or OpenVMS binding name for this parameter, as follows:

  • C-binding name
    If you specify a C-binding name for this parameter, be sure not to use a dollar sign ($) in your binding name. C-binding creation routine names are case sensitive. For example, XmCreateScrollBar is not identical to xmcreatescrollbar. To determine the correct case of the string, consult the documentation for the widget whose class you are defining.
  • OpenVMS binding name
    If you specify an OpenVMS binding name for this parameter, you can use the dollar sign ($) character in the name. OpenVMS binding names are not case sensitive.


A string that is the name of the shareable image that contains the widget class record. If you specify a low-level creation routine in the second parameter, DEFINE_WIDGET_CLASS also looks for the routine in the program image. If you do not specify an image, DECTPU assumes the widget is defined in the Motif image SYS$LIBRARY:DECW$XMLIBSHR.EXE. This parameter can specify only the name of the shareable image. If the parameter contains anything else, such as a device name, directory name, file type, or version number, DECTPU signals an error.

Return Value

An integer used by the CREATE_WIDGET built-in to identify the class of widget to be created.


The DEFINE_WIDGET_CLASS procedure defines a widget class and optional creation routine for later use in creating widgets of that class.

Defining a class that is already defined returns the existing class integer. Defining a new class also defines the widget creation routine as the second parameter, if specified, or the X toolkit routine XtCreateWidget.

Signaled Errors

TPU$_ARGMISMATCH ERROR The data type of the indicated parameter is not supported by DEFINE_WIDGET_CLASS.
TPU$_TOOFEW ERROR Too few arguments passed to DEFINE_WIDGET_CLASS.
TPU$_TOOMANY ERROR Too many arguments passed to DEFINE_WIDGET_CLASS.
TPU$_REQUIRESDECW ERROR You can use DEFINE_WIDGET_CLASS only if you are using DECwindows DECTPU.
TPU$_SYSERROR ERROR Could not find class record or creation routine in shareable image.
TPU$_INVWIDGETCLASS ERROR The widget class cannot be defined.


For a sample procedure using the DEFINE_WIDGET_CLASS built-in, see Example A-1.



DELETE ({array|buffer|integer|keyword|learn |marker|pattern|process|program|range |string|unspecified|widget|window})



The array that you want to delete. The memory used by the array is freed for later use. If some other data structure, such as a pattern, is referenced only in the array, then that data structure is deleted when the array is deleted.


The buffer that you want to delete. Any ranges or markers that point to this buffer, any subprocess that is associated with this buffer, the memory for the buffer control structure, the pages for storing text, and the memory for ranges and markers associated with the buffer are deleted also. If the buffer is associated with a window that is mapped to the screen, the window is unmapped. Any associated buffer-change journal file is also closed and deleted.


The integer that you want to delete. Integers use no internal structures or resources, so deleting a variable of type integer simply changes that variable to type unspecified.


The keyword that you want to delete. Keywords use no internal structures or resources, so deleting a variable of type keyword simply assigns to that variable the type unspecified.


The learn sequence that you want to delete. The memory used by the learn sequence is freed for later use.


The marker that you want to delete. The memory for the marker control structure is deleted also.


The pattern that you want to delete. The memory used by the pattern is freed for later use. If you delete a pattern that has multiple references to it, the pattern does not go away. If you delete a pattern that has no other references to it, the pattern goes away.


The process that you want to delete. The memory for the process control structure and the subprocess are deleted also.


The program that you want to delete. The memory for the program control structure and the memory for the program code are deleted also.


The range that you want to delete. The memory for the range control structure is deleted also. The text in a range does not belong to the range; rather, it belongs to the buffer in which it is located. A range is merely a way of manipulating sections of text within a buffer. When you delete a range, the text delimited by the range is not deleted. See the ERASE built-in procedure for a description of how to remove the text in a range.


The string that you want to delete. The memory used by the string is freed for later use.


Deleting a variable of type unspecified is allowed but does nothing.


The widget that you want to delete. When you use the DELETE (widget) built-in, all variables and array elements that refer to the widget are set to unspecified. If an array element is indexed by the deleted widget, the array element is deleted as well.


The window that you want to delete. Along with the window, the memory for the window control structure and the record history associated with the window are deleted. If you delete a window that is mapped to the screen, DECTPU unmaps the window before deleting it. The screen appears just as it does when you use the UNMAP built-in procedure.


The DELETE procedure removes DECTPU structures from your editing context. When you delete a structure (for example, a range), all variables that refer to that structure are reset to unspecified. If the deleted structure had any associated resources, these resources are returned to the editor. When a buffer is deleted, the associated journal file (if any) is closed and deleted.

Depending upon how many variables are referencing an entity, or how many other entities are associated with the entity you are deleting, processing the DELETE built-in procedure can be time consuming. DELETE cannot be terminated by a Ctrl/C.

Any variables that reference the deleted entity are set to unspecified and all other entities that are associated with the deleted entity are also deleted. Use the DELETE built-in procedure with caution.

Signaled Errors

TPU$_TOOFEW ERROR DELETE requires one argument.
TPU$_TOOMANY ERROR DELETE accepts only one argument.
TPU$_BADDELETE ERROR You attempted to delete a constant.
TPU$_DELETEFAIL WARNING DELETE could not delete the process.
TPU$_INVBUFDELETE WARNING You cannot delete a permanent buffer.


The following example deletes the main buffer and any associated resources that DECTPU allocated for the main buffer. As a result of this command, the SHOW (BUFFERS) command does not list MAIN_BUFFER as one of the buffers in your editing context.

DELETE (main_buffer)

The following example creates a modal dialog box widget and later deletes it. For purposes of this example, the procedure user_callback_dispatch_routine is assumed to be a user-written procedure that handles widget callbacks. For a sample DECwindows User Interface Language (UIL) file to be used with DECTPU code creating a modal dialog box widget, see the example in the description of the CREATE_WIDGET built-in procedure.


PROCEDURE sample_create_and_delete

LOCAL example_widget,

example_hierarchy := SET (UID, "mynode$dua0:[smith]example.uid");
example_widget_name := "EXAMPLE_BOX";
example_widget := CREATE_WIDGET (example_widget_name,
                                 example_hierarchy, SCREEN,
!     .
!     .
!     .

DELETE (example_widget);





{buffer1|range1|string1}:= EDIT ({buffer2|range2|string2}, keyword1[[,...]] [[,keyword2]] [[,keyword3]] )



The buffer in which you want DECTPU to edit text. You cannot use the NOT_IN_PLACE keyword if you specify a buffer for the first parameter.


The range in which you want DECTPU to edit text. You cannot use the NOT_IN_PLACE keyword if you specify a range for the first parameter.


The string that you want to modify. If you specify a return value, the returned string consists of the string you specify for the first parameter, modified in the way you specify in the second and subsequent parameters. If you specify IN_PLACE for the third parameter, EDIT makes the specified change to the string specified in the first parameter. If string2 is a constant, IN_PLACE has no effect.


A keyword specifying the editing operation that you want to perform on the string. The valid keywords and their meaning are as follows.
Keyword Meaning
COLLAPSE Removes all spaces and tabs.
COMPRESS Replaces multiple spaces and tabs with a single space.
TRIM Removes leading and trailing spaces and tabs.
TRIM_LEADING Removes leading spaces and tabs.
TRIM_TRAILING Removes trailing spaces and tabs.
LOWER Converts all uppercase characters to lowercase.
UPPER Converts all lowercase characters to uppercase.
INVERT Changes the current case of the specified characters; uppercase characters become lowercase and lowercase characters become uppercase.


A keyword specifying whether DECTPU quote characters are used as quote characters or as regular text. The valid keywords are ON, OFF, 1, or 0. The integer 1 is equivalent to ON. The integer 0 is equivalent to OFF. The default is ON or 1.


A keyword indicating where DECTPU is to make the indicated change. The valid keywords and their meanings are as follows:
Keyword Meaning
IN_PLACE Makes the indicated change in place. This is the default.
NOT_IN_PLACE Leaves the specified string unchanged and returns a string that is the result of the specified editing. You cannot use NOT_IN_PLACE if the first parameter is specified as a range or buffer. To use NOT_IN_PLACE, you must specify a return value for EDIT.

This keyword is ignored if string2 is a string constant. EDIT never edits string constants in place. It does return the edited string.

Return Values


A variable of type buffer pointing to the buffer containing the modified text, if you specify a buffer for the first parameter. The variable returned_buffer points to the same buffer pointed to by the buffer variable specified as the first parameter.


A range containing the modified text, if you specify a range for the first parameter. The returned range spans the same text as the range specified as a parameter, but they are two separate ranges. If you subsequently change or delete one of the ranges, this has no effect on the other range.


A string containing the modified text, when you specify a string for the first parameter. EDIT can return a string even if you specify IN_PLACE.


The EDIT procedure modifies a string according to the keywords you specify. EDIT is similar (although not identical) to the DCL lexical function F$EDIT. DECTPU modifies the first parameter of the EDIT built-in in place. EDIT does not modify a literal string.

By default, EDIT does not modify quoted text that occurs within a string. For example, the following code does not change the case of WELL:

string_to_change := 'HE SANG "WELL"';
edit (string_to_change, LOWER);

The variable string_to_change has the value he sang "WELL".

If you specify more than one of the TRIM keywords (TRIM, TRIM_LEADING, TRIM_TRAILING), all of the TRIM operations you specify are performed.

If you specify more than one of the case conversion keywords (UPPER, LOWER, INVERT), the last keyword that you specify determines how the characters in the string are modified.

If you specify both of the quote recognition keywords (ON, OFF), the last keyword you specify determines whether EDIT modifies quoted text.

If you specify no keywords, EDIT does nothing to the passed string.

You can disable the recognition of quotation marks and apostrophes as DECTPU quote characters by using the OFF keyword as a parameter for EDIT. When you use the OFF keyword, DECTPU preserves any quotation marks and apostrophes in the edited text and performs the editing tasks you specify on the text within the quotation marks and apostrophes. OFF may appear anywhere in the keyword list. It need not be the final parameter.

If the string you specify has opening quotation marks but not closing quotation marks, the status TPU$_MISSINGQUOTE is returned. All text starting at the unclosed opening quotation mark and continuing to the end of the string is considered to be part of the quoted string and is not modified.

EDIT is similar to the DCL lexical function F$EDIT, with the following differences:

  • EDIT modifies the characters in place, while F$EDIT returns a result.
  • EDIT takes keywords as parameters, while F$EDIT requires that the edit commands be specified by a string.

Signaled Errors

TPU$_MISSINGQUOTE ERROR Character string is missing terminating quotation marks.
TPU$_TOOFEW ERROR EDIT requires at least one parameter.
TPU$_TOOMANY ERROR You supplied keywords that are the same or contradictory.
TPU$_ARGMISMATCH ERROR One of the parameters to EDIT is of the wrong data type.
TPU$_INVPARAM ERROR One of the parameters to EDIT is of the wrong data type.
TPU$_BADKEY WARNING You gave the wrong keyword to EDIT.


The following example edits the string "PRODUCT NAME" by changing it to lowercase, and displays the edited string in the message window:


The following example shows a generalized way of changing any input string to lowercase:


PROCEDURE user_edit_string (input_string)

   is := input_string;

   EDIT (is, LOWER);
   MESSAGE (is);

After compiling the preceding procedure, you can direct DECTPU to print the lowercase word zephyr in the message area by entering the following command:

user_edit_string ("ZEPHYR")



marker := END_OF ({buffer|range})



The buffer whose last character position you want to mark.


The range whose last character position you want to mark.

Return Value

A marker pointing to the last character position in a buffer or range.


The END_OF procedure returns a marker that points to the last character position in a buffer or a range. If you use the marker returned by the END_OF built-in as a parameter for the POSITION built-in procedure, the editing point moves to this marker.

Signaled Errors

TPU$_NEEDTOASSIGN ERROR END_OF must appear on the right-hand side of an assignment statement.
TPU$_TOOFEW ERROR END_OF requires one argument.
TPU$_TOOMANY ERROR END_OF accepts only one argument.
TPU$_ARGMISMATCH ERROR You passed something other than a range or a buffer to END_OF.


The following example stores the last position in the current buffer in the variable the_end:


The following example implements a simple INSERT HERE function. The variable paste_buffer points to a buffer that holds previously cut text.


PROCEDURE user_paste

   LOCAL paste_text;

   IF (BEGINNING_OF (paste_buffer) <> END_OF (paste_buffer))
       COPY_TEXT (paste_buffer);



ERASE ({buffer|range})



The buffer whose contents you want to remove.


The range whose contents you want to remove.


The ERASE procedure removes the contents of the buffer or range that you specify. However, the buffer structure still remains a part of your editing context and the editing point remains in the buffer even if you remove the contents of the buffer. The space that was occupied by the contents of the buffer is returned to the system and is available for reuse. Only the end-of-buffer line remains.

When you erase a range, the contents of the range are removed from the buffer. The range structure is still a part of your editing context. You can use the range structure later in your editing session to delimit an area of text within a buffer.

Note that text does not belong to a range; it belongs to a buffer. Ranges are merely a way of manipulating portions of text within a buffer. For more information on ranges, see the Guide to the DEC Text Processing Utility.

Signaled Errors

TPU$_TOOFEW ERROR ERASE requires one argument.
TPU$_TOOMANY ERROR ERASE accepts only one argument.
TPU$_INVPARAM ERROR The argument to ERASE is of the wrong type.
TPU$_NOTMODIFIABLE WARNING You cannot erase text in an unmodifiable buffer.


The following example erases all the text in the buffer referenced by main_buffer. Because the buffer still exists, you can select the buffer by using the POSITION built-in or by mapping the buffer to a window. The procedure simply removes all text from the buffer. All markers in the buffer now mark the end of the buffer.

ERASE (main_buffer)

The following example deletes embedded carriage-return/line-feed pairs:


PROCEDURE user_remove_crlfs

   LOCAL crlf,

   crlf := ASCII (13) + ASCII (10);
   here := MARK (NONE);

      cr_range := SEARCH_QUIETLY (crlf, FORWARD, EXACT);
      EXITIF cr_range = 0;
      ERASE (cr_range);
      POSITION (cr_range);

   POSITION (here);



[[string := ]] ERASE_CHARACTER (integer)



An expression that evaluates to an integer, which may be signed. The value indicates which characters, and how many of them, are to be erased.

Return Value

A string that represents the characters deleted by ERASE_CHARACTER.


The ERASE_CHARACTER procedure deletes up to the number of characters that you specify and optionally returns a string that represents the characters you deleted.

If the argument to ERASE_CHARACTER is a positive integer, ERASE_CHARACTER deletes that many characters, starting at the current position and continuing toward the end of the line. If the argument is negative, ERASE_CHARACTER deletes characters to the left of the current character. It uses the absolute value of the parameter to determine the number of characters to delete. ERASE_CHARACTER stops deleting characters if it reaches the beginning or the end of the line before deleting the specified number of characters.

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

Previous Next Contents Index