Updated: 11 December 1998

DEC Text Processing Utility Reference Manual

Whenever you extend EVE by writing a procedure that can be bound to a key, the procedure must return true or false, as needed, to indicate whether execution of the procedure completed successfully. EVE's REPEAT command relies on this return value to determine whether to halt repetition of a command, a procedure bound to a key, or a learn sequence.

Signaled Errors

• TPU$_NOTDEFINABLE	WARNING	Second argument is not a valid reference to a key.
  TPU$_RECURLEARN	WARNING	This key definition was used as a part of a learn sequence. You cannot use it in this context.
  TPU$_NOKEYMAP	WARNING	Fourth argument is not a defined key map.
  TPU$_NOKEYMAPLIST	WARNING	Fourth argument is not a defined key map list.
  TPU$_KEYMAPNTFND	WARNING	The key map listed in the fourth argument is not found.
  TPU$_EMPTYKMLIST	WARNING	The key map list specified in the fourth argument contains no key maps.
  TPU$_TOOFEW	ERROR	Too few arguments passed to the DEFINE_KEY built-in.
  TPU$_TOOMANY	ERROR	Too many arguments passed to the DEFINE_KEY built-in.
  TPU$_INVPARAM	ERROR	Wrong type of data sent to the DEFINE_KEY built-in.
  TPU$_COMPILEFAIL	WARNING	Compilation aborted.
  TPU$_UNKKEYWORD	ERROR	An unknown keyword has been used as an argument.
  TPU$_BADKEY	ERROR	An unknown keyword has been used as an argument.
  TPU$_KEYSUPERSEDED	INFORMATIONAL	Key definition superseded.

Examples

The following example associates the DECTPU statement POSITION (main_window) with the key combination Ctrl/B. You must use quotation marks around the DECTPU statement.

DEFINE_KEY ("POSITION (main_window)", Ctrl_B_KEY) 
      

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 
   THEN 
       key := KEY_NAME (key) 
   ELSE 
       key := LAST_KEY; 
   ENDIF; 
   
   DEFINE_KEY (def,key); 
ENDPROCEDURE; 
 
      

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 
 
   IF GET_INFO (CURRENT_BUFFER, "mode") = OVERSTRIKE 
   THEN 
       SET (INSERT, CURRENT_BUFFER); 
   ELSE 
       SET (OVERSTRIKE, CURRENT_BUFFER); 
   ENDIF; 
ENDPROCEDURE; 
 
! 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); 
      

Format

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

Parameters

class_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.

creation_routine_name

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.

creation_routine_image_name

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

Description

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$_NEEDTOASSIGN	ERROR	DEFINE_WIDGET_CLASS must return a value.
  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.

Example

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

Format

DELETE (

• array
• buffer
• integer
• keyword
• learn
• marker
• pattern
• process
• program
• range
• string
• unspecified
• widget
• window

)

Parameters

array

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.

buffer

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.

integer

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.

keyword

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.

learn

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

marker

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

pattern

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.

process

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

program

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

range

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.

string

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

unspecified

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

widget

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.

window

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.

Description

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

Examples

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_widget_name, 
      example_hierarchy; 
 
example_hierarchy := SET (UID, "mynode$dua0:[smith]example.uid"); 
example_widget_name := "EXAMPLE_BOX"; 
example_widget := CREATE_WIDGET (example_widget_name, 
                                 example_hierarchy, SCREEN, 
                                 "user_callback_dispatch_routine"); 
!     . 
!     . 
!     . 
 
DELETE (example_widget); 
 
ENDPROCEDURE; 
 
      

Format

• buffer1
• range1
• string1

:= EDIT (

• buffer2
• range2
• string2

, keyword1[[,...]] [[,keyword2]] [[,keyword3]] )

Parameters

buffer2

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.

range2

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.

string2

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.

keyword1

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.

keyword2

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.

keyword3

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

buffer1

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.

range1

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.

string1

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.

Description

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.

Examples

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

pn := "PRODUCT NAME"; 
EDIT (pn, LOWER); 
MESSAGE (pn); 
 

 
 
      

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); 
ENDPROCEDURE; 
      

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")

Format

marker := END_OF (

• buffer
• range

)

Parameters

buffer

The buffer whose last character position you want to mark.

range

The range whose last character position you want to mark.

Return Value

Description

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

Examples

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

the_end := END_OF (CURRENT_BUFFER) 
 
 
 
      

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)) 
   THEN 
       COPY_TEXT (paste_buffer); 
   ENDIF; 
ENDPROCEDURE; 
      

Format

ERASE (

• buffer
• range

)

Parameters

buffer

The buffer whose contents you want to remove.

range

The range whose contents you want to remove.

Description

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

Examples

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) 
 



 

  

    
Previous
    
Next
    
Contents
    
Index




 

     
 
   
     

 
 
     
 
         
 
 
 
 
 
 
 
 
 
 
 
 
 
 
     
 
         
 
         
 
     
 
 
     
 
         
 
              
 
              
           
 
Copyright © Compaq Computer Corporation 1998. All rights reserved. 
           
 
Legal
         
 
     
 
 
     
 
         
 
           
           
6020PRO_007.HTML