DEC Text Processing Utility Reference Manual

Document revision date: 19 July 1999

DEC Text Processing Utility Reference Manual

Contents

Index

The following example causes the user-written program "user_debugger" to be called as the program to help locate programming errors:

#2
SET (DEBUG, PROGRAM, "user_debugger")

SET (DEFAULT_DIRECTORY)

Format

[[old_default_string := ]] SET (DEFAULT_DIRECTORY, new_default_string)

Parameters

DEFAULT_DIRECTORY
A keyword that indicates that the SET built-in procedure is being used to control which directory is used as the default.
new_default_string
A string that names the directory to which you want the default changed.

Return Value

The string that you optionally specify returns the current default directory.

Description

The SET (DEFAULT_DIRECTORY) procedure determines the directory that will be used as the default for file operations. When you exit from DECTPU, the default directory is not restored to the default that was set when you invoked DECTPU.
When you issue the EVE DCL SHOW DEFAULT command, the default shown is not always the new default directory, even though the setting has actually been changed. To update DCL tracking of the current default directory, use the EVE DCL SET DEFAULT command instead of calling this built-in procedure directly.

Signaled Errors

TPU$_TOOMANY	ERROR	You specified more than two parameters.
TPU$_TOOFEW	ERROR	SET (DEFAULT_DIRECTORY) requires two parameters.
TPU$_SYSERROR	ERROR	One of the system routines used has failed. The system routine's error message will be in the message buffer.
TPU$_INVPARAM	ERROR	The second parameter must be a string.
TPU$_PARSEFAIL	WARNING	Parameter is not a valid RMS file specification.

Example

The following example sets the default directory to [WALSH.PINK] on the device DISK1. The variable prev_dir contains the string that names the previous default directory.


prev_dir := SET (DEFAULT_DIRECTORY, "DISK1:[WALSH.PINK]");

SET (DEFAULT_FILE)

Format

SET (DEFAULT_FILE, string)

Parameters

DEFAULT_FILE
A keyword that indicates that the SET built-in procedure is being used to merge a new X resource file into the display's resource database.
string
A file specification for the X resource file.

Description

The SET (DEFAULT_FILE) procedure sets a new file specification as the X resource file to merge into the display's resource database. The current database, merged during editor initialization or by a previous SET (DEFAULT_FILE), is lost.
The new resource file will affect values returned from the GET_DEFAULT built-in procedure.

Signaled Errors

TPU$_TOOMANY	ERROR	You specified more than two parameters.
TPU$_TOOFEW	ERROR	SET (DEFAULT_FILE) requires two parameters.
TPU$_INVPARAM	ERROR	The second parameter must be a string.

SET (DETACHED_ACTION)

Format

SET (DETACHED_ACTION, SCREEN
[[, {buffer |learn |program |range |string} ]])

Parameters

DETACHED_ACTION
A keyword that indicates that the SET built-in procedure is being used to designate the detached cursor action routine.
SCREEN
A keyword that indicates that the detached action routine is being set for all buffers and windows used during the session.
buffer
The buffer that contains the detached cursor action routine.
learn
The learn sequence that is executed as the detached cursor action routine.
program
The program that contains the detached cursor action routine.
range
The range that contains the detached cursor action routine.
string
The string that contains the detached cursor action routine.

Description

The SET (DETACHED_ACTION) procedure specifies the code to be executed when the DECTPU main input loop detects that the current cursor position is detached (that is, that the cursor position cannot accurately represent the editing point in the current window).
If DECTPU determines that the current editing point is on a record that is not visible in the current window, the screen updater positions the cursor on the next visible record, placing the cursor in the comparable screen column. This condition is known as a detached cursor. Use SET (DETACHED_ACTION) to designate code to be executed when the cursor is detached.
There are five reasons for a detached cursor. The following table shows these reasons, along with their constants and values.

Constant Value Reason

TPU$K_OFF_LEFT 1 The editing point is off the left side of the current window.

TPU$K_OFF_RIGHT 2 The editing point is off the right side of the current window.

TPU$K_INVISIBLE 4 The editing point is on a record that is invisible in the current window.

TPU$K_DISJOINT 8 The current buffer is not mapped to the current window.

TPU$K_UNMAPPED 16 No current window exists.

If you do not specify the optional third parameter, SET (DETACHED_ACTION) deletes the current detached action routine.
To fetch the current detached action routine, use GET_INFO (SCREEN, "detached_action"). To find out which of the five possible detached states the cursor is in, use GET_INFO (SCREEN, "detached_reason").

Constant	Value	Reason
TPU$K_OFF_LEFT	1	The editing point is off the left side of the current window.
TPU$K_OFF_RIGHT	2	The editing point is off the right side of the current window.
TPU$K_INVISIBLE	4	The editing point is on a record that is invisible in the current window.
TPU$K_DISJOINT	8	The current buffer is not mapped to the current window.
TPU$K_UNMAPPED	16	No current window exists.

Signaled Errors

TPU$_TOOMANY	ERROR	You specified too many parameters.
TPU$_TOOFEW	ERROR	You specified too few parameters.
TPU$_INVPARAM	ERROR	The second parameter must be a keyword.
TPU$_ARGMISMATCH	ERROR	The third parameter must be a program or a learn key sequence.
TPU$_BADKEY	WARNING	The second parameter must be SCREEN.
TPU$_COMPILEFAIL	WARNING	The third parameter did not compile successfully.
TPU$_COMPILED	SUCCESS	The third parameter successfully compiled.

Example

The following example designates the procedure as an application's detached action routine:


SET (DETACHED_ACTION, SCREEN, "detached_routine");

In the following example, the detached action routine shifts the current window to the right if the editing point is to the right of the last displayed column:


PROCEDURE detached_routine LOCAL rightmost_column, the_offset; IF GET_INFO (SCREEN, "detached_reason") < > tpu$k_off_right THEN RETURN; ENDIF; rightmost_column := GET_INFO (CURRENT_WINDOW, "right", VISIBLE_TEXT); the_offset := GET_INFO (CURRENT_BUFFER, "offset_column"); IF the_offset > rightmost_column THEN SHIFT (CURRENT_WINDOW, the_offset - rightmost_column + 2) ENDIF; UPDATE (CURRENT_WINDOW); ENDPROCEDURE;

PROCEDURE detached_routine 
 
LOCAL rightmost_column, 
      the_offset; 
 
IF GET_INFO (SCREEN, "detached_reason") < > tpu$k_off_right 
 
   THEN RETURN; 
 
ENDIF; 
 
rightmost_column := GET_INFO (CURRENT_WINDOW, "right", VISIBLE_TEXT); 
 
the_offset := GET_INFO (CURRENT_BUFFER, "offset_column"); 
 
IF the_offset > rightmost_column 
 
   THEN SHIFT (CURRENT_WINDOW, the_offset - rightmost_column + 2) 
 
ENDIF; 
 
UPDATE (CURRENT_WINDOW); 
 
ENDPROCEDURE;

SET (DISPLAY_VALUE)

Format

SET (DISPLAY_VALUE,window,display_value_integer)

Parameters

DISPLAY_VALUE
A keyword that indicates that the SET built-in procedure is being used to set the display value for a window.
window
The window whose display value you want to set.
display_value_integer
An integer from -127 to +127.

Description

The SET (DISPLAY_VALUE) procedure sets the display value of the specified window. DECTPU uses a window's display value, which is an integer value, to determine if a given record in a buffer should be made visible in the window mapped to the buffer. If the record's display value is greater than or equal to the window's setting, DECTPU makes the record visible in that window; otherwise, DECTPU makes the record invisible.
You use SET (RECORD_ATTRIBUTES) to set the record's display values.

Signaled Errors

TPU$_TOOMANY	ERROR	You specified too many parameters.
TPU$_TOOFEW	ERROR	You specified too few parameters.
TPU$_INVPARAM	ERROR	The second parameter must be a window.
TPU$_BADDISPVAL	WARNING	Display values must be between -127 and +127.

Example

The following example gives the current window a display value of 10. This means that any record whose display value is less than 10 is invisible in the specified window.


SET (DISPLAY_VALUE, CURRENT_WINDOW, 10);

SET (DRM_HIERARCHY)

Format

integer := SET (DRM_HIERARCHY, filespec
[[, filespec... ]])

Parameter

filespec
A string that specifies the UID file to be used. DECTPU does not apply a default file specification to the UID file specification. You must specify at least one file name.

Return Value

An integer that is the identification number for the Motif Resource Manager hierarchy.

Description

The SET (DRM_HIERARCHY) procedure sets the user interface definition (UID) file or files to be used with DECTPU. However, the preferred built-in for UID files is SET (UID).
Using UID files to specify hierarchies makes it easy to translate the product into other languages and to modify an application's interface without recompiling all the code implementing the application.
For more information about UID files, see the VMS DECwindows Guide to Application Programming.

Signaled Errors

TPU$_ARGMISMATCH	ERROR	The data type of the indicated parameter is not supported by the SET (DRM_HIERARCHY) built-in.
TPU$_TOOFEW	ERROR	Too few arguments passed to the SET (DRM_HIERARCHY) built-in.
TPU$_TOOMANY	ERROR	Too many arguments passed to the SET (DRM_HIERARCHY) built-in.
TPU$_FAILURE_STATUS	ERROR	The DIGITAL Resource Manager returned an error status.
TPU$_INVPARAM	ERROR	You specified an invalid parameter.
TPU$_REQUIRESDECW	ERROR	Requires the DECTPU DECwindows screen updater.

Example

The following example designates the OpenVMS user interface definition (UID) file MYNODE$DUA0:[SMITH]EXAMPLE.UID as a file to be used with DECTPU to create widgets needed by the layered application:


example_hierarchy := SET (DRM_HIERARCHY, "mynode$dua0:[smith]example.uid");

SET (ENABLE_RESIZE)

Format

SET (ENABLE_RESIZE, {ON |OFF |1 |0} )

Parameters

ENABLE_RESIZE
A keyword that directs DECTPU to enable or disable screen resizing.
ON, 1
Enables screen resizing.
OFF, 0
Disables screen resizing.

Description

The SET (ENABLE_RESIZE) procedure enables or disables resizing of the DECTPU screen. If you specify the ON or 1 keyword, DECTPU gives the DECwindows window manager hints (parameters that the window manager is free to use or ignore) on the allowable maximum and minimum sizes for the DECTPU screen. The hints are set by the SET (SCREEN_LIMITS, array) built-in procedure. If you specify the OFF or 0 keyword, DECTPU uses the screen's current width and length as the maximum and minimum size.

Signaled Errors

TPU$_BADKEY	WARNING	You specified an invalid keyword as a parameter.
TPU$_INVPARAM	ERROR	One of the parameters was specified with data of the wrong type.
TPU$_NORETURNVALUE	ERROR	SET (ENABLE_RESIZE) cannot return a value.
TPU$_REQUIRESDECW	ERROR	You can use the SET (ENABLE_RESIZE) built-in only if you are using DECwindows DECTPU.
TPU$_TOOFEW	ERROR	Too few arguments passed to the SET (ENABLE_RESIZE) built-in.
TPU$_TOOMANY	ERROR	Too many arguments passed to the SET (ENABLE_RESIZE) built-in.

Example

The following example enables screen resizing. For a sample of this statement used in an initializing procedure, see the example in the description of the SET (SCREEN_LIMITS) built-in procedure.


SET (ENABLE_RESIZE, ON);

SET (EOB_TEXT)

Format

SET (EOB_TEXT, buffer, string)

Parameters

EOB_TEXT
A keyword that indicates that SET is to determine the text displayed at the end of a buffer. This text is merely a visual marker in a buffer and does not become part of the file that is written when a buffer is saved. The default end-of-buffer text is [EOB].
buffer
The buffer in which the text for the end-of-buffer is being set.
string
The text that is displayed to indicate the end-of-buffer.

Description

The SET (EOB_TEXT) procedure sets the end-of-buffer text for the specified buffer. You may specify ranges that include the end-of-buffer text, but you cannot set the record_attributes of the end-of-buffer "record." Therefore, the end-of-buffer text is always visible, is left-justified on the screen, and cannot be modified using normal editing operations.
Setting a blank EOB_TEXT is the only way to remove the end-of-buffer text. Note, however, that a blank line will still remain.

Signaled Errors

TPU$_TOOFEW	ERROR	This SET built-in requires three parameters.
TPU$_TOOMANY	ERROR	You specified more than three parameters.
TPU$_INVPARAM	ERROR	One or more of the specified parameters have the wrong type.
TPU$_FAILURE	FATAL	DECTPU could not create the record for the EOB text.

Example

The following example causes [END OF MAIN EDITING BUFFER] to be displayed as the end-of-buffer text for the main buffer:


SET (EOB_TEXT, main_buffer, "[END OF MAIN EDITING BUFFER]")

SET (ERASE_UNMODIFIABLE)

Format

{ON|OFF} := SET (ERASE_UNMODIFIABLE, buffer {ON |OFF |1 |0})

Parameters

ERASE_UNMODIFIABLE
A keyword that indicates that the SET built-in procedure is being used to control whether unmodifiable records are deleted in response to built-ins that erase lines in a buffer.
buffer
The buffer for which you want to turn on or turn off erasing of unmodifiable records.
ON, 1
Enables erasing of unmodifiable records.
OFF, 0
Disables erasing of unmodifiable records.

Return Value

The keyword ON (1) or OFF (0), indicating the previous setting of ERASE_UNMODIFIABLE.

Description

The SET (ERASE_UNMODIFIABLE) procedure controls whether DECTPU erases unmodifiable records in response to built-ins that delete lines from a buffer.
The default setting lets you use built-ins such as ERASE_LINE to delete unmodifiable records. For example, ERASE_LINE deletes an unmodifiable record only if ERASE_UNMODIFIABLE is turned on. If ERASE_UNMODIFIABLE is turned off when ERASE_LINE or a similar built-in encounters an unmodifiable record, the built-in returns an error and does not delete the record.
Some built-ins delete records as a side effect of their normal action. Table 2-10 shows the built-ins that can delete records as a side effect and shows what these built-ins do instead when the ERASE_UNMODIFIABLE setting is turned off. The SET (ERASE_UNMODIFIABLE) built-in procedure prevents these built-ins from unintentionally deleting unmodifiable records.

Table 2-10 Selected Built-In Actions with ERASE_UNMODIFIABLE Turned Off
Built-In Action

APPEND_LINE Signals a warning if an attempt is made to append to an unmodifiable line.

CHANGE_CASE Signals a warning if any of the lines in the range or buffer are unmodifiable.

COPY_TEXT Copies all records, preserving modifiability attribute while in insert mode.

Signals a warning if the current editing position is in an unmodifiable line.

Signals a warning if in overstrike mode and any of the lines to be overstruck are unmodifiable.

EDIT Signals a warning if any of the lines in the range or buffer are unmodifiable.

ERASE (buffer) Signals a warning if any line in the buffer is unmodifiable.

ERASE (range) Signals a warning if the start or the end of the range is in the middle of an unmodifiable line.

Signals a warning if any of the lines in the range are unmodifiable.

ERASE_CHARACTER Signals a warning if the current character is unmodifiable.

ERASE_LINE Signals a warning if the current line is unmodifiable.

FILL Signals a warning if any of the lines in the range or buffer are unmodifiable.

MOVE_TEXT Moves all records, preserving modifiability attribute while in insert mode.

Signals a warning if the current editing point is in an unmodifiable line.

Signals a warning if in overstrike mode and any of the lines to be overstruck are unmodifiable.

If the start or the end of the range is in the middle of an unmodifiable line, the MOVE_TEXT is turned into a COPY_TEXT and a warning is issued.

If any of the lines in the buffer or range are unmodifiable, the MOVE_TEXT is turned into a COPY_TEXT and a warning is issued.

SPLIT_LINE Signals a warning if the current editing position is in the middle of an unmodifiable line.

If the current editing position is at the beginning of an unmodifiable line, a new modifiable line is created before it.

If the current editing position is at the end of an unmodifiable line, a new modifiable line is created after it.

If the current editing position is on an empty unmodifiable line, then a new modifiable line is created after it.

TRANSLATE Signals a warning if any of the lines in the range or buffer are unmodifiable.

SET (ERASE_UNMODIFIABLE) optionally returns an integer (0 or 1) indicating whether ERASE_UNMODIFIABLE was turned on before the current call was executed. This makes it easier to return to the previous setting later in the program.

**Table 2-10 Selected Built-In Actions with ERASE_UNMODIFIABLE Turned Off**
Built-In	Action
APPEND_LINE	Signals a warning if an attempt is made to append to an unmodifiable line.
CHANGE_CASE	Signals a warning if any of the lines in the range or buffer are unmodifiable.
COPY_TEXT	Copies all records, preserving modifiability attribute while in insert mode.
	Signals a warning if the current editing position is in an unmodifiable line.
	Signals a warning if in overstrike mode and any of the lines to be overstruck are unmodifiable.
EDIT	Signals a warning if any of the lines in the range or buffer are unmodifiable.
ERASE (buffer)	Signals a warning if any line in the buffer is unmodifiable.
ERASE (range)	Signals a warning if the start or the end of the range is in the middle of an unmodifiable line.
	Signals a warning if any of the lines in the range are unmodifiable.
ERASE_CHARACTER	Signals a warning if the current character is unmodifiable.
ERASE_LINE	Signals a warning if the current line is unmodifiable.
FILL	Signals a warning if any of the lines in the range or buffer are unmodifiable.
MOVE_TEXT	Moves all records, preserving modifiability attribute while in insert mode.
	Signals a warning if the current editing point is in an unmodifiable line.
	Signals a warning if in overstrike mode and any of the lines to be overstruck are unmodifiable.
	If the start or the end of the range is in the middle of an unmodifiable line, the MOVE_TEXT is turned into a COPY_TEXT and a warning is issued.
	If any of the lines in the buffer or range are unmodifiable, the MOVE_TEXT is turned into a COPY_TEXT and a warning is issued.
SPLIT_LINE	Signals a warning if the current editing position is in the middle of an unmodifiable line.
	If the current editing position is at the beginning of an unmodifiable line, a new modifiable line is created before it.
	If the current editing position is at the end of an unmodifiable line, a new modifiable line is created after it.
	If the current editing position is on an empty unmodifiable line, then a new modifiable line is created after it.
TRANSLATE	Signals a warning if any of the lines in the range or buffer are unmodifiable.

Signaled Errors

TPU$_TOOMANY	ERROR	You specified too many parameters.
TPU$_TOOFEW	ERROR	You specified too few parameters.
TPU$_INVPARAM	ERROR	One or more of the specified parameters have the wrong type.
TPU$_BADKEY	WARNING	The third parameter must be ON or OFF.

Example

The following example turns off erasing of unmodifiable records in the current buffer and returns the previous setting of ERASE_UNMODIFIABLE:


old_setting := SET (ERASE_UNMODIFIABLE, CURRENT_BUFFER, OFF);

SET (FACILITY_NAME)

Format

SET (FACILITY_NAME, string)

Parameters

FACILITY_NAME
A keyword that indicates that the SET built-in procedure is being used to set the first item (the facility name) in a message generated by DECTPU.
string
The string that you specify as the facility name for messages. The maximum length of this name is 10 characters.

Description

The SET (FACILITY_NAME) procedure sets the facility name for messages. The facility name appears in messages if you have used the SET (MESSAGE_FLAGS) built-in procedure either to explicitly include the facility name in messages or to include the facility name only if enabled by the default message flags for your OpenVMS process.

Signaled Errors

TPU$_FACTOOLONG	WARNING	Name specified is longer than maximum allowed.
TPU$_MINVALUE	WARNING	Argument specified is less than the minimum allowed.
TPU$_ARGMISMATCH	ERROR	The second parameter must be a string.
TPU$_INVPARAM	ERROR	One or more of the specified parameters have the wrong type.

Example

The following example causes "new_editor" to be used as the facility name in messages:


SET (FACILITY_NAME, "new_editor")

Previous Next Contents Index

privacy and legal statement

6020PRO_026.HTML

DEC Text Processing Utility Reference Manual

SET (DEFAULT_DIRECTORY)

Format

[[old_default_string := ]] SET (DEFAULT_DIRECTORY, new_default_string)

Parameters

DEFAULT_DIRECTORY

new_default_string

Return Value

Description

Signaled Errors

Example

SET (DEFAULT_FILE)

Format

SET (DEFAULT_FILE, string)

Parameters

DEFAULT_FILE

string

Description

Signaled Errors

SET (DETACHED_ACTION)

Format

SET (DETACHED_ACTION, SCREEN [[, {buffer |learn |program |range |string} ]])

Parameters

DETACHED_ACTION

SCREEN

buffer

learn

program

range

string

Description

Signaled Errors

Example

SET (DISPLAY_VALUE)

Format

SET (DISPLAY_VALUE,window,display_value_integer)

Parameters

DISPLAY_VALUE

window

display_value_integer

Description

Signaled Errors

Example

SET (DRM_HIERARCHY)

Format

integer := SET (DRM_HIERARCHY, filespec [[, filespec... ]])

Parameter

filespec

Return Value

Description

Signaled Errors

Example

SET (ENABLE_RESIZE)

Format

SET (ENABLE_RESIZE, {ON |OFF |1 |0} )

Parameters

ENABLE_RESIZE

ON, 1

OFF, 0

Description

Signaled Errors

Example

SET (EOB_TEXT)

Format

SET (EOB_TEXT, buffer, string)

Parameters

EOB_TEXT

buffer

string

Description

Signaled Errors

Example

SET (ERASE_UNMODIFIABLE)

Format

{ON|OFF} := SET (ERASE_UNMODIFIABLE, buffer {ON |OFF |1 |0})

Parameters

ERASE_UNMODIFIABLE

buffer

ON, 1

OFF, 0

SET (DETACHED_ACTION, SCREEN
[[, {buffer |learn |program |range |string} ]])

integer := SET (DRM_HIERARCHY, filespec
[[, filespec... ]])