|
|
Updated:
11 December 1998
|
DEC Text Processing Utility Reference Manual
You use SET (DEBUG) to write or use user-written debuggers. You cannot
freely mix parameters when using SET (DEBUG). The only valid usages are
those shown in the format sections of this built-in.
Signaled Errors
-
TPU$_NOCURRENTBUF
|
WARNING
|
There is no current buffer.
|
TPU$_NONAMES
|
WARNING
|
No names match the one requested.
|
TPU$_BADKEY
|
ERROR
|
An unknown keyword was used as an argument.
|
TPU$_ARGMISMATCH
|
ERROR
|
You specified an unsupported data type.
|
Examples
The following example causes the debugger to be invoked each time the
procedure "user_remove" is called:
#1 |
SET (DEBUG, ON, "user_remove")
|
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").
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;
|
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, )
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 (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
:= SET
(ERASE_UNMODIFIABLE, buffer )
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.
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);
|