DEC Text Processing Utility Reference Manual

Updated: 11 December 1998

DEC Text Processing Utility Reference Manual

Contents

Index

In the following example, if paragraph_range references a range that contains a paragraph, this statement fills a paragraph. FILL uses a left margin of 5 and a right margin of 65. It indents the first line of the paragraph an additional five characters. The space character and the hyphen are the two word separators. If the paragraph contains a hyphenated word, FILL breaks the word after the hyphen if necessary.

#2

FILL (paragraph_range, "-", 5, 65, 5)

#2
FILL (paragraph_range, "-", 5, 65, 5)

The next example is like the previous one except that FILL unindents the first line of the paragraph by three characters. This is useful for filling numbered paragraphs.

#3
FILL (paragraph_range, "-", 10, 65, -3)

GET_CLIPBOARD

Format

string := GET_CLIPBOARD

Parameters

None.

Return Value

A string that consists of the data read from the clipboard. Line breaks are indicated by a line-feed character (ASCII (10)).

Description

The GET_CLIPBOARD procedure reads STRING format data from the clipboard and returns a string that contains this data. DECwindows provides a clipboard that lets you move data between applications. Applications can write to the clipboard to replace previous data, and can read from the clipboard to get a copy of existing data. The data in the clipboard can be in multiple formats, but all the information in the clipboard must be written at the same time.
DECTPU provides no clipboard support for applications not written for DECwindows.

Signaled Errors

TPU$_NEEDTOASSIGN	ERROR	GET_CLIPBOARD must return a value.
TPU$_TOOMANY	ERROR	Too many arguments passed to GET_CLIPBOARD.
TPU$_CLIPBOARDFAIL	WARNING	The clipboard did not return any data.
TPU$_CLIPBOARDLOCKED	WARNING	DECTPU cannot read from the clipboard because some other application has locked it.
TPU$_CLIPBOARDNODATA	WARNING	There is no string format data in the clipboard.
TPU$_TRUNCATE	WARNING	Characters were truncated because you tried to add text that would exceed the maximum line length.
TPU$_STRTOOLARGE	ERROR	The amount of data in the clipboard exceeds 65535 characters.
TPU$_REQUIRESDECW	ERROR	You can use GET_CLIPBOARD only if you are using DECwindows DECTPU.

Example

The following statement reads what is currently in the clipboard and assigns it to new_string:


new_string := GET_CLIPBOARD;

GET_DEFAULT

Format

string3
integer
:= GET_DEFAULT (string1, string2 )

Parameters

string1
The name of the resource whose value you want GET_DEFAULT to fetch. Resource names are case sensitive.
string2
The class of the resource. Resource class names are case sensitive.

Return Value

The string equivalent of the resource value or 0 if the specified resource is not defined. If necessary, the application must convert the string to the data type appropriate to the resource.

Description

The GET_DEFAULT procedure returns the value of an X resource from the X resources database. GET_DEFAULT is useful for initializing a layered application that uses an X defaults file. You can use GET_DEFAULT only in the DECwindows environment.
If you use the SET (DEFAULT_FILE) built-in to merge a new X resource database into the display's database, this affects the values returned by GET_DEFAULT.

Signaled Errors

TPU$_INVPARAM	ERROR	One of the parameters was specified with data of the wrong type.
TPU$_TOOFEW	ERROR	Too few arguments passed to GET_DEFAULT.
TPU$_TOOMANY	ERROR	Too many arguments passed to GET_DEFAULT.
TPU$_NEEDTOASSIGN	ERROR	GET_DEFAULT must return a value.
TPU$_REQUIRESDECW	ERROR	You can use GET_DEFAULT only if you are using DECwindows DECTPU.

Example

The following example shows the portion of a module_init procedure directing DECTPU to fetch the value of a resource from the X resources database. For more information on module_init procedures, see the Extensible Versatile Editor Reference Manual.
If you want to create an extension of EVE that enables use of an X defaults file to choose a keypad setting, you can use a GET_DEFAULT statement in a module_init procedure.


PROCEDURE application_module_init LOCAL keypad_name; : : : keypad_name := GET_DEFAULT ("user.keypad", "User.Keypad"); EDIT (keypad_name, UPPER); ! Convert the returned string to uppercase. IF keypad_name <> '0' THEN CASE keypad_name "EDT" : eve_set_keypad_edt (); "NOEDT" : eve_set_keypad_noedt (); "WPS" : eve_set_keypad_wps (); "NOWPS" : eve_set_keypad_nowps (); "NUMERIC" : eve_set_keypad_numeric (); "VT100" : eve_set_keypad_vt100 (); [INRANGE, OUTRANGE] : eve_set_keypad_numeric; ! If you have ! used invalid value, ! set the keypad to ! NUMERIC setting. ENDCASE; ENDIF; : : : ENDPROCEDURE;

PROCEDURE application_module_init 
 
LOCAL 
    keypad_name; 
 
    : 
    : 
    : 
 
keypad_name := GET_DEFAULT ("user.keypad", "User.Keypad"); 
 
EDIT (keypad_name, UPPER); ! Convert the returned string to uppercase. 
 
IF keypad_name <> '0' 
THEN 
 
   CASE keypad_name 
 
      "EDT"      :  eve_set_keypad_edt (); 
      "NOEDT"    :  eve_set_keypad_noedt (); 
      "WPS"      :  eve_set_keypad_wps (); 
      "NOWPS"    :  eve_set_keypad_nowps (); 
      "NUMERIC"  :  eve_set_keypad_numeric (); 
      "VT100"    :  eve_set_keypad_vt100 (); 
      [INRANGE, OUTRANGE]  :  eve_set_keypad_numeric; ! If you have 
                                                      ! used invalid value, 
                                                      ! set the keypad to 
                                                      ! NUMERIC setting. 
 
   ENDCASE; 
 
ENDIF; 
 
    : 
    : 
    : 
 
ENDPROCEDURE;

To provide a value for the GET_DEFAULT statement to fetch, an X defaults file would contain an entry similar to the following:


User.Keypad : EDT

GET_GLOBAL_SELECT

Format

array
integer
string
unspecified
:= GET_GLOBAL_SELECT (

PRIMARY
SECONDARY
selection_name
, selection_property_name)

Parameters

PRIMARY
A keyword indicating that the layered application is requesting information about a property of the primary global selection.
SECONDARY
A keyword indicating that the layered application is requesting information about a property of the secondary global selection.
selection_name
A string identifying the global selection whose property is the subject of the layered application's information request. Specify the selection name as a string if the layered application needs information about a selection other than the primary or secondary global selection.
selection_property_name
A string specifying the property whose value the layered application is requesting.

Return Values

array
An array that passes information about a global selection whose contents describe information that is not of a data type supported by DECTPU.
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 receive information from other DECwindows applications, all applications that exchange information whose data type is not supported by DECTPU must adopt a convention on how the information is to be used.
The element array {0} contains a string that names 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, but rather is a series of bytes of information. As mentioned, the meaning and use of the information is agreed upon by convention among the DECwindows applications. To interpret this string, the application can use the SUBSTR built-in procedure to obtain substrings one at a time, and the ASCII built-in procedure to convert the data to integer format if necessary. For more information about using these DECTPU elements, see the description of the SUBSTR and ASCII built-in procedures.
If array {1} contains the value 32, the element array {2} and any subsequent elements contain integers. The number of integers in the array is determined by the application that responded to the request for information about the global selection. The interpretation of the data is a convention that must be agreed upon by the cooperating application. 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}.)
integer
The value of the specified global selection property. The return value is of type integer if the value of the specified global selection property is of type integer.
string
The value of the specified global selection property. The return value is of type string if the value of the specified global selection property is of type string.
unspecified
A data type that indicates that the information requested by the layered application was not available.

Description

The GET_GLOBAL_SELECT procedure supplies information about a global selection. If an owner for the global selection exists, and if the owner provides the information requested in a format that DECTPU can recognize, GET_GLOBAL_SELECT returns the information.

Signaled Errors

TPU$_ARGMISMATCH	ERROR	Wrong type of data sent to GLOBAL_SELECT.
TPU$_NEEDTOASSIGN	ERROR	GLOBAL_SELECT must return a value.
TPU$_INVPARAM	ERROR	One of the parameters was specified with data of the wrong type.
TPU$_REQUIRESDECW	ERROR	You can use GLOBAL_SELECT only if you are using DECwindows DECTPU.
TPU$_TOOFEW	ERROR	Too few arguments passed to GLOBAL_SELECT.
TPU$_TOOMANY	ERROR	Too many arguments passed to GLOBAL_SELECT.
TPU$_GBLSELOWNER	WARNING	DECTPU owns the global selection.
TPU$_BADKEY	WARNING	You specified an invalid keyword as a parameter.
TPU$_INVGBLSELDATA	WARNING	The global selection owner provided data that DECTPU cannot process.
TPU$_NOGBLSELDATA	WARNING	The global selection owner indicated that it cannot provide the information requested.
TPU$_NOGBLSELOWNER	WARNING	You requested information about an unowned global selection.
TPU$_TIMEOUT	WARNING	The global selection owner did not respond before the timeout period expired.

Example

The following example fetches the text in the primary global selection and assigns it to the variable string_to_paste:


string_to_paste := GET_GLOBAL_SELECT (PRIMARY, "STRING");

For another example of how to use the GET_GLOBAL_SELECT built-in procedure, see Example A-3.

GET_INFO

Description

The GET_INFO procedure returns information about the current status of the editor.
For information on how to get a screen display of the status of your editor, see the description of the SHOW built-in procedure.
This description provides general information on the GET_INFO built-in procedures. Included are descriptions of individual GET_INFO built-ins. The individual GET_INFO built-ins are grouped according to the value of their first parameter. For a list of the groups of GET_INFO built-ins, see Table 2-3.
All GET_INFO built-in procedures have the following two characteristics in common:
They return a value that is the piece of information you have requested.
They consist of the GET_INFO statement followed by at least two parameters, as follows:
The first parameter specifies the general topic about which you want information. If you want the GET_INFO built-in to return information on a given variable, use that variable as the first parameter. For example, if you want to know what row contains the cursor in a window stored in the variable command_window, you would specify the variable command_window as the first parameter. For example:
the_row := GET_INFO (command_window, "current_row");
Otherwise, the first parameter is a keyword specifying the general subject about which GET_INFO is to return information. The valid keywords for the first parameter are as follows:
ARRAY
BUFFER
COMMAND_LINE
DEBUG
DEFINED_KEY
KEY_MAP
KEY_MAP_LIST
mouse_event_keyword
PROCEDURES
PROCESS
SCREEN
SYSTEM
WIDGET
WINDOW

For a list of valid mouse event keywords, see Table 2-4.
Do not confuse a GET_INFO built-in whose first parameter is a keyword (such as ARRAY) with a GET_INFO built-in whose first parameter is a variable of a given data type, such as array_variable. For example, the GET_INFO (array_variable) built-in procedure shows what string constants can be used when the first parameter is an array variable; the GET_INFO (ARRAY) built-in shows what can be used when the first parameter is the ARRAY keyword.
The second parameter (a DECTPU string) specifies the exact piece of information you want.
The third and subsequent parameters, if necessary, provide additional information that DECTPU uses to identify and return the requested value or structure.
Each GET_INFO built-in procedure in this section shows the possible return values for a given combination of the first and second parameters. For example, the GET_INFO (any_variable) built-in shows that when you use any variable as the first parameter and the string "type" as the second parameter, GET_INFO returns a keyword for the data type of the variable.
Depending upon the kind of information requested, GET_INFO returns any one of the following:

An array
A buffer
An integer
A keyword
A marker
A process
A range
A string
A window

DECTPU maintains internal lists of the following items:

Arrays
Array elements
Breakpoints
Buffers
Defined keys
Key maps
Key map lists
Processes
Windows

You can step through an internally maintained list by using "first", "next", "previous", or "last" as the second parameter to GET_INFO. The order in which DECTPU maintains these lists is private and may change in a future version. Do not write code that depends on a list being maintained in a particular order. When you write code to search a list, remember that DECTPU keeps only one pointer for each list. If you create nested loops that attempt to search the same list, the results are unpredictable.
For example, suppose that a program intended to search two key map lists for common key maps sets up a loop within a loop. The outer loop might contain the following statement:
GET_INFO (KEY_MAP, "previous", name_of_second_key_map)
The inner loop might contain the following statement:
GET_INFO (KEY_MAP, "next", name_of_first_key_map)
In DECTPU, the behavior of such a nested loop is unpredictable.
Unless documented otherwise, the order of the internal list is not defined.
The syntax of GET_INFO depends on the kind of information you are trying to get. For more information on specific GET_INFO built-in procedures, see the descriptions in this section. GET_INFO built-ins whose first parameter is a keyword are grouped separately from GET_INFO built-ins whose first parameter is a variable.

Table 2-3 GET_INFO Built-In Procedures by First Parameter
Variable Keyword Any Keyword or Key Name

GET_INFO (any_variable) GET_INFO (ARRAY) GET_INFO (any_keyname)

GET_INFO (array_variable) GET_INFO (BUFFER) GET_INFO (any_keyword)

GET_INFO (buffer_variable) GET_INFO (COMMAND_LINE)

GET_INFO (integer_variable) GET_INFO (DEBUG)

GET_INFO (marker_variable) GET_INFO (DEFINED_KEY)

GET_INFO (process_variable) GET_INFO (KEY_MAP)

GET_INFO (range_variable) GET_INFO (KEY_MAP_LIST)

GET_INFO (string_variable) GET_INFO (mouse_event_keyword)

GET_INFO (widget_variable) GET_INFO (PROCEDURES)

GET_INFO (window_variable) GET_INFO (PROCESS)

GET_INFO (SCREEN)

GET_INFO (SYSTEM)

GET_INFO (WIDGET)

GET_INFO (WINDOW)

**Table 2-3 GET_INFO Built-In Procedures by First Parameter**
Variable	Keyword	Any Keyword or Key Name
GET_INFO (any_variable)	GET_INFO (ARRAY)	GET_INFO (any_keyname)
GET_INFO (array_variable)	GET_INFO (BUFFER)	GET_INFO (any_keyword)
GET_INFO (buffer_variable)	GET_INFO (COMMAND_LINE)
GET_INFO (integer_variable)	GET_INFO (DEBUG)
GET_INFO (marker_variable)	GET_INFO (DEFINED_KEY)
GET_INFO (process_variable)	GET_INFO (KEY_MAP)
GET_INFO (range_variable)	GET_INFO (KEY_MAP_LIST)
GET_INFO (string_variable)	GET_INFO (mouse_event_keyword)
GET_INFO (widget_variable)	GET_INFO (PROCEDURES)
GET_INFO (window_variable)	GET_INFO (PROCESS)
	GET_INFO (SCREEN)
	GET_INFO (SYSTEM)
	GET_INFO (WIDGET)
	GET_INFO (WINDOW)

Signaled Errors

TPU$_BADREQUEST	WARNING	Request represented by second argument is not understood for data type of first argument.
TPU$_BADKEY	WARNING	Bad keyword value or unrecognized data type is passed as the first argument.
TPU$_NOCURRENTBUF	WARNING	Current buffer is not defined.
TPU$_NOKEYMAP	WARNING	Key map is not defined.
TPU$_NOKEYMAPLIST	WARNING	Key map list is not defined.
TPU$_INVPARAM	ERROR	One or more of the specified parameters have the wrong data type.
TPU$_NEEDTOASSIGN	ERROR	The GET_INFO built-in can be used only on the right-hand side of an assignment statement.
TPU$_NOBREAKPOINT	WARNING	This string constant is valid only after a breakpoint.
TPU$_NONAMES	WARNING	There are no names matching the one requested.
TPU$_TOOFEW	ERROR	Too few arguments passed to the GET_INFO built-in.
TPU$_TOOMANY	ERROR	Too many arguments passed to the GET_INFO built-in.
TPU$_UNKKEYWORD	ERROR	An unknown keyword was used as an argument.

Examples

The following example stores the pointer to the current buffer in the variable my_buffer:

#1
my_buffer := GET_INFO (BUFFERS, "current");

The following example stores the integer 1 or 0 in the variable is_buf_mod. A value of 1 means the current buffer has been modified. A value of 0 means the current buffer has not been modified.

#2
is_buf_mod := GET_INFO (CURRENT_BUFFER, "modified");

The following example uses GET_INFO to find the top of the current window. It then removes the top five lines and replaces them with an example window.

#3
PROCEDURE user_getinfo top_of_window := GET_INFO (CURRENT_WINDOW, "top", visible_window); ! Remove the top five lines from the main window ADJUST_WINDOW (CURRENT_WINDOW, +5, 0); ! Replace removed lines with an example window example_window := CREATE_WINDOW (top_of_window, 5, ON); example_buffer := CREATE_BUFFER ("EXAMPLE", "sys$login:template.txt"); MAP (example_window, example_buffer); ENDPROCEDURE;

PROCEDURE user_getinfo 
 
   top_of_window := GET_INFO (CURRENT_WINDOW, "top", visible_window); 
 
       ! Remove the top five lines from the main window 
   ADJUST_WINDOW (CURRENT_WINDOW, +5, 0); 
 
       ! Replace removed lines with an example window 
   example_window := CREATE_WINDOW (top_of_window, 5, ON); 
   example_buffer := CREATE_BUFFER ("EXAMPLE", 
                                    "sys$login:template.txt"); 
   MAP (example_window, example_buffer); 
ENDPROCEDURE;

The following example shows whether the key map list associated with the current buffer inserts undefined printable characters:

#4
PROCEDURE show_self_insert LOCAL key_map_list_name; key_map_list_name := GET_INFO (CURRENT_BUFFER, "key_map_list"); IF GET_INFO (key_map_list_name, "self_insert") THEN MESSAGE ("Undefined printable characters will be inserted"); ELSE MESSAGE ("Undefined printable characters will cause an error"); ENDIF; ENDPROCEDURE;

PROCEDURE show_self_insert 
      
   LOCAL key_map_list_name; 
 
   key_map_list_name := GET_INFO (CURRENT_BUFFER, "key_map_list"); 
 
   IF GET_INFO (key_map_list_name, "self_insert") 
   THEN 
      MESSAGE ("Undefined printable characters will be inserted"); 
   ELSE 
      MESSAGE ("Undefined printable characters will cause an error"); 
   ENDIF; 
ENDPROCEDURE;

Contents

Index

Legal

 
6020PRO_010.HTML

DEC Text Processing Utility Reference Manual

GET_CLIPBOARD

Format

string := GET_CLIPBOARD

Parameters

Return Value

Description

Signaled Errors

Example

GET_DEFAULT

Format

string3
integer
:= GET_DEFAULT (string1, string2 )

Parameters

string1

string2

Return Value

Description

Signaled Errors

Example

GET_GLOBAL_SELECT

Format

array
integer
string
unspecified
:= GET_GLOBAL_SELECT (

PRIMARY
SECONDARY
selection_name
, selection_property_name)

Parameters

PRIMARY

SECONDARY

selection_name

selection_property_name

Return Values

array

integer

string

unspecified

Description

Signaled Errors

Example

GET_INFO

Description

Signaled Errors

Examples

DEC Text Processing Utility Reference Manual

GET_CLIPBOARD

Format

string := GET_CLIPBOARD

Parameters

Return Value

Description

Signaled Errors

Example

GET_DEFAULT

Format

string3 integer := GET_DEFAULT (string1, string2 )

Parameters

string1

string2

Return Value

Description

Signaled Errors

Example

GET_GLOBAL_SELECT

Format

array integer string unspecified := GET_GLOBAL_SELECT ( PRIMARY SECONDARY selection_name , selection_property_name)

Parameters

PRIMARY

SECONDARY

selection_name

selection_property_name

Return Values

array

integer

string

unspecified

Description

Signaled Errors

Example

GET_INFO

Description

Signaled Errors

Examples

string3
integer
:= GET_DEFAULT (string1, string2 )

array
integer
string
unspecified
:= GET_GLOBAL_SELECT (

PRIMARY
SECONDARY
selection_name
, selection_property_name)