 |
DEC Text Processing Utility Reference Manual
Compaq recommends that you use GET_INFO (window, "length",
visible_window) to retrieve this information.
"visible_top"
Returns an integer that is the screen line number of the visible top of
the window. Use the ADJUST_WINDOW built-in procedure, create other
windows, or map a window on top of the current window to change this
value.
Compaq recommends that you use GET_INFO (window, "top", visible_window)
to retrieve this information.
"width"
Returns an integer that is the number of columns or the number of
visible columns in the specified window or the specified window's text
area. The number of columns returned depends on the keyword you specify
as the third parameter. If you do not specify a keyword, the default is
TEXT. Valid keywords are shown in Table 2-6.
Use the SET built-in procedure to establish or change this parameter.
Return Values
buffer
Returns requested information about the buffer you specify.
integer
Returns requested information about the array you specify.
keyword
Returns requested information about the keyword you specify.
string
Returns requested information about the string you specify.
widget
Returns requested information about the widget you specify.
window
Returns requested information about the window you specify.
Description
The GET_INFO (window_variable) procedure returns information about a
specified window.
For general information about using all forms of GET_INFO built-in
procedures, see the description of GET_INFO.
Examples
The following example returns the last line of the window
bottom_window. The value returned is the line that contains
the status line or scroll bar, whichever comes last, if the window has
a status line or scroll bar.
| #1 |
last_line := GET_INFO (bottom_window, "bottom", WINDOW);
|
The following example returns the number of the rightmost column in the
current window. The column whose number is returned can be occupied by
a vertical scroll bar if one is present. Also, the returned value
changes if you widen the window, but not if you move the window without
widening it.
| #2 |
last_column := GET_INFO (CURRENT_WINDOW, "right", WINDOW);
|
The following example returns the number of the first row in the
current window. The row number returned is relative to the top of the
DECTPU screen. Thus, if the current window is not the top window on the
DECTPU screen, the row number returned is not 1.
| #3 |
first_row := GET_INFO (CURRENT_WINDOW, "top", WINDOW);
|
HELP_TEXT
Format
HELP_TEXT (library-file, topic, {ON |OFF |1 |0} ,buffer)
Parameters
library-file
A string that is the file specification of the help library. The string
can be a logical name.
topic
A string that is the initial library topic. If this string is empty,
the top level of help is displayed.
ON, 1
A keyword or integer that specifies that the VMS Help utility should
prompt you for input.
OFF, 0
A keyword or integer that specifies that prompting should be turned off.
buffer
The buffer to which the help information is written.
Description
The HELP_TEXT procedure provides help information on the topic you
specify. You must specify the help library to be used for help
information, the initial library topic, the prompting mode for the Help
utility, and the buffer to which DECTPU will write the help
information. You can enter a complete file specification for the help
library as the first parameter. However, if you enter only a file name,
the Help utility provides a default device (SYS$HELP) and default file
type (.HLB).
If you do not specify an initial topic as the second parameter, you
must enter a null string as a placeholder. The Help utility then
displays the top level of help available in the specified library.
When the prompting mode is ON for the HELP_TEXT built-in procedure, the
following prompt appears if the help text contains more than one window
of information:
Press RETURN to continue ...
|
Before DECTPU invokes the Help utility, it erases the buffer specified
as the help buffer. (In EVE, the buffer to which the help information
is written is represented by the variable help_buffer.) If the
help buffer is associated with a window that is mapped to the screen,
the window is updated each time DECTPU prompts you for input. If you
set the prompting mode to OFF, the window is not updated.
If help_buffer is not associated with a window that is mapped
to the screen, the information from the Help utility is not visible.
Signaled Errors
|
TPU$_BADKEY
|
ERROR
|
Only ON and OFF are allowed.
|
|
TPU$_INVPARAM
|
ERROR
|
One or more of the specified parameters have the wrong type.
|
|
TPU$_NOTMODIFIABLE
|
WARNING
|
The output buffer is currently unmodifiable.
|
|
TPU$_OPENIN
|
ERROR
|
Error opening help library.
|
|
TPU$_SYSERROR
|
ERROR
|
Error activating the help library.
|
|
TPU$_TOOFEW
|
ERROR
|
The HELP_TEXT built-in requires four parameters.
|
|
TPU$_TOOMANY
|
ERROR
|
You specified more than four parameters.
|
Examples
The following example causes the top level of help information from the
SYS$HELP:TPUHELP.HLB library to be written to the help buffer. The Help
utility prompting mode is not turned on.
| #1 |
HELP_TEXT ("tpuhelp", "", OFF ,help_buffer)
|
This procedure displays information about getting out of help mode on
the status line, prompts you for input, and maps help_buffer
to the screen:
| #2 |
! Interactive HELP
PROCEDURE user_help
SET (STATUS_LINE, info_window, UNDERLINE,
"Press Ctrl/Z to leave prompts then Ctrl/F to resume editing");
MAP (info_window, help_buffer);
HELP_TEXT ("USERHELP", READ_LINE ("Topic: "), ON, help_buffer);
ENDPROCEDURE;
|
INDEX
Format
integer := INDEX (string, substring)
Parameters
string
The string within which you want to find a character or a substring.
substring
A character or a substring whose leftmost character location you want
to find within string1.
Return Value
An integer that shows the character position within a string of the
substring you specify.
Description
The INDEX procedure locates a character or a substring within a string
and returns its location within the string. INDEX finds the leftmost
occurrence of substring within string. It returns an
integer that indicates the character position in string at
which substring was found. If string is not found,
DECTPU returns a 0. The character positions within string
start at the left with 1.
Signaled Errors
|
TPU$_NEEDTOASSIGN
|
ERROR
|
INDEX must be on the right-hand side of an assignment statement.
|
|
TPU$_TOOFEW
|
ERROR
|
INDEX requires two arguments.
|
|
TPU$_TOOMANY
|
ERROR
|
INDEX accepts only two arguments.
|
|
TPU$_INVPARAM
|
ERROR
|
The arguments to INDEX must be strings.
|
Examples
The following example stores an integer value of 6 in the variable
loc because the substring "67" is found starting at character
position 6 within the string "1234567":
| #1 |
loc := INDEX ("1234567","67")
|
The following example uses the INDEX built-in procedure to return true
if a given item is an alphanumeric character; otherwise, it returns
false. (The list of characters in this example does not include
characters that are not in the ASCII range of the DEC Multinational
Character Set. However, you can write a procedure that uses such
characters because DECTPU supports the DEC Multinational Character
Set.) The parameter that is passed to this procedure is assumed to be a
single character.
| #2 |
PROCEDURE user_is_character (c)
LOCAL symbol_characters;
symbol_characters :=
"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890";
RETURN INDEX( symbol_characters, c ) > 0;
ENDPROCEDURE;
|
INT
Format
integer3 := INT ({integer1 |keyword |string [[, integer2 ]] })
Parameters
integer1
Any integer value. INT accepts a parameter of type integer so you need
not check the type of the parameter you supply.
keyword
A keyword whose internal value you want.
string
A string that consists of numeric characters.
integer2
An integer that specifies the radix (base) of the string being
converted. The default radix is 10. The other allowable values are 8
and 16.
Return Value
The integer equivalent of the parameter you specify.
Description
The INT procedure converts a keyword or a string that consists of
numeric characters into an integer. You can use INT to store an integer
value for a keyword or a string of numeric characters in a variable.
You can then use the variable name in operations that require integer
data types.
INT signals a warning and returns 0 if the string is not a number.
Signaled Errors
|
TPU$_NEEDTOASSIGN
|
ERROR
|
INT returns a value that must be used.
|
|
TPU$_TOOFEW
|
ERROR
|
INT requires one parameter.
|
|
TPU$_TOOMANY
|
ERROR
|
INT accepts only one parameter.
|
|
TPU$_ARGMISMATCH
|
ERROR
|
The parameter to INT was not a keyword or string.
|
|
TPU$_INVNUMSTR
|
WARNING
|
The string you passed to INT was not a number.
|
|
TPU$_NULLSTRING
|
WARNING
|
You passed a string of length 0 to INT.
|
|
TPU$_BADVALUE
|
ERROR
|
You specified a value other than 8, 10, or 16 for the radix parameter.
|
Examples
The following example converts the string "12345" into an integer value
and stores it in the variable user_int:
| #1 |
user_int := INT ("12345")
|
The following example is used by commands that prompt for integers. The
procedure returns true if prompting worked or was not needed; otherwise
it returns false. The number that is returned is returned in the output
parameter.
| #2 |
! Parameters:
!
! new_number New integer value - output
! prompt_string Text of prompt - input
! no_value_message Message printed if you press the
! RETURN key to get out of the command - input
PROCEDURE user_prompt_number (new_number, prompt_string,
no_value_message)
LOCAL read_line_string;
ON_ERROR
IF ERROR = TPU$_NULLSTRING
THEN
MESSAGE (no_value_message);
ELSE
IF ERROR = TPU$_INVNUMSTR
THEN
MESSAGE (FAO ("Don't understand !AS",
read_line_string));
ELSE
MESSAGE (ERROR_TEXT);
ENDIF;
ENDIF;
user_prompt_number := 0;
ENDON_ERROR;
user_prompt_number := 1;
read_line_string := READ_LINE (prompt_string);
EDIT (read_line_string, TRIM);
TRANSLATE (read_line_string, "1", "l");
new_number := INT (read_line_string);
ENDPROCEDURE;
|
JOURNAL_CLOSE
Format
JOURNAL_CLOSE
Parameters
None.
Description
The JOURNAL_CLOSE procedure closes an open keystroke journal file (if
one exists for your session) and saves the journal file. JOURNAL_CLOSE
applies only to keystroke journaling. Once you specify
JOURNAL_CLOSE, DECTPU does not keep a keystroke journal of your work
until you specify JOURNAL_OPEN. Calling the JOURNAL_OPEN built-in
procedure causes DECTPU to open a new keystroke journal file for your
session.
To turn off buffer-change journaling, see the description of the SET
(JOURNALING) built-in procedure.
Caution
Journal files contain a record of all information being
edited. Therefore, when editing files that contain secure or
confidential data, be sure to keep the journal files secure as well.
|
Signaled Error
|
TPU$_TOOMANY
|
ERROR
|
JOURNAL_CLOSE accepts no arguments.
|
JOURNAL_OPEN
Format
[[string := ]] JOURNAL_OPEN (file-name)
Parameter
file-name
A string that is the name of the keystroke journal file created for
your editing session.
Return Value
The file specification of the file journaled.
Description
The JOURNAL_OPEN procedure opens a keystroke journal file and starts
making a copy of your editing session by recording every keystroke you
make. If you invoked DECTPU with the /RECOVER qualifier, then DECTPU
recovers the previous aborted session before recording new keystrokes.
JOURNAL_OPEN optionally returns a string that contains the file
specification of the file journaled. JOURNAL_OPEN applies only to
keystroke journaling.
DECTPU saves the keystrokes of your editing session by storing them in
a buffer. DECTPU writes the contents of this buffer to the file that
you specify as a journal file. If DECTPU terminates unexpectedly, you
can recover your editing session by using this journal file. To do
this, invoke DECTPU with the /RECOVER qualifier. See the Guide to
the DEC Text Processing Utility for information on recovering
files.
To turn on buffer-change journaling, see the description of the SET
(JOURNALING) built-in procedure.
By default, DECTPU writes keystrokes to the journal file whenever the
journal buffer contains 500 bytes of data. DECTPU also tries to write
keystrokes to the journal file when it aborts.
When you recover a DECTPU session, your terminal characteristics should
be the same as they were when the journal file was created. If they are
not the same, DECTPU informs you what characteristics are different and
asks whether you want to continue recovering. If you answer yes, DECTPU
tries to recover; however, the different terminal settings may cause
differences between the recovered session and the original session.
There are no keystrokes in batch mode. You can use JOURNAL_OPEN
nodisplay mode with the /NODISPLAY qualifier; however, when you do
this, nothing is journaled.
Caution
Journal files contain a record of all information being
edited. Therefore, when editing files that contain secure or
confidential data, be sure to keep the journal files secure as well.
|
Signaled Errors
|
TPU$_BADJOUFILE
|
ERROR
|
JOURNAL_OPEN could not open the journal file.
|
|
TPU$_TOOFEW
|
ERROR
|
JOURNAL_OPEN requires one argument.
|
|
TPU$_TOOMANY
|
ERROR
|
JOURNAL_OPEN accepts only one argument.
|
|
TPU$_INVPARAM
|
ERROR
|
The parameter to JOURNAL_OPEN must be a string.
|
|
TPU$_ASYNCACTIVE
|
WARNING
|
You cannot journal with asynchronous handlers declared.
|
|
TPU$_JNLOPEN
|
ERROR
|
A journal file is already open.
|
Examples
The following example causes DECTPU to open a file named TEST.FIL as
the journal file for your editing session. DECTPU uses your current
default device and directory to complete the file specification.
| #1 |
JOURNAL_OPEN ("test.fil")
|
The following example starts journaling. It can be called from the
TPU$INIT_PROCEDURE after a file is read into the current buffer.
| #2 |
PROCEDURE user_start_journal
LOCAL default_journal_name, ! Default journal name
aux_journal_name; ! Auxiliary journal name derived
! from file name
IF (GET_INFO (COMMAND_LINE, "journal") = 1)
AND
(GET_INFO (COMMAND_LINE, "read_only") <> 1)
THEN
aux_journal_name := GET_INFO (CURRENT_BUFFER, "file_name");
IF aux_journal_name = ""
THEN
aux_journal_name := GET_INFO (CURRENT_BUFFER, "output_file");
ENDIF;
IF (aux_journal_name = "") or (aux_journal_name = 0)
THEN
default_journal_name := "user.TJL";
ELSE
default_journal_name := ".TJL";
ENDIF;
journal_file := GET_INFO (COMMAND_LINE, "journal_file");
journal_file := FILE_PARSE (journal_file, default_journal_name,
aux_journal_name);
JOURNAL_OPEN (journal_file);
ENDIF;
ENDPROCEDURE;
|
KEY_NAME
Format
keyword2 := KEY_NAME ({integer |key_name |string}
[[, {SHIFT_KEY
|SHIFT_MODIFIED |ALT_MODIFIED |CTRL_MODIFIED |HELP_MODIFIED} [[, ...]]
]], [[, FUNCTION |, KEYPAD]])
Parameters
integer
An integer that is either the integer representation of a keyword for a
key, or is a value between 0 and 255 that DECTPU interprets as the
value of a character in the DEC Multinational Character Set.
key_name
A keyword that is the DECTPU name for a key.
string
A string that is the value of a key from the main keyboard.
SHIFT_KEY
A keyword that specifies that the key name created includes one or more
shift keys. The SHIFT_KEY keyword specifies the DECTPU shift key, not
the key on the keyboard marked Shift. The shift key is also referred to
as the GOLD key in EVE. (See the description of the SET (SHIFT_KEY)
built-in procedure in the VAX Text Processing Utility Manual.)
SHIFT_MODIFIED
A keyword that specifies that the key name created by the built-in
includes the key marked Shift on the keyboard that toggles between
uppercase and lowercase, not the key known as the GOLD key.
Compaq recommends that you avoid using this keyword in the
non-DECwindows version of DECTPU. In non-DECwindows DECTPU, when you
use this keyword to create a key name, the keyboard cannot generate a
corresponding key.
ALT_MODIFIED
A keyword that specifies that the key name created by the built-in
includes the Alt key. On most Compaq keyboards, the Alt key is labeled
Compose Character.
ALT_MODIFIED modifies only function keys and keypad keys.
Compaq recommends that you avoid using this keyword in the
non-DECwindows version of DECTPU. In non-DECwindows DECTPU, when you
use this keyword to create a key name, the keyboard cannot generate a
corresponding key.
CTRL_MODIFIED
A keyword that specifies that the key name created by the built-in
includes the Ctrl key.
CTRL_MODIFIED modifies only function keys and keypad keys.
Compaq recommends that you avoid using this keyword in the
non-DECwindows version of DECTPU. In non-DECwindows DECTPU, when you
use this keyword to create a key name, the keyboard cannot generate a
corresponding key.
HELP_MODIFIED
A keyword that specifies that the key name created by the built-in
includes the Help key.
HELP_MODIFIED modifies only function keys and keypad keys.
Compaq recommends that you avoid using this keyword in the
non-DECwindows version of DECTPU. In non-DECwindows DECTPU, when you
use this keyword to create a key name, the keyboard cannot generate a
corresponding key.
FUNCTION
A parameter that specifies that the resulting key name is to be that of
a function key.
KEYPAD
A parameter that specifies that the resulting key name is to be that of
a keypad key.
Return Value
A DECTPU keyword to be used as the name of a key.
Description
The KEY_NAME procedure returns a DECTPU keyword for a key or a
combination of keys, or creates a keyword used as a key name by DECTPU.
With KEY_NAME, you can create key names that are modified by more than
one key. For example, you can create a name for a key sequence that
consists of the GOLD key, the Ctrl key, and an alphanumeric or keypad
key.
The GET_INFO (key_name, "key_modifiers") built-in procedure returns a
bit-encoded integer whose value represents the key modifier or
combination of key modifiers used to create a given key name. For more
information about interpreting the integer returned, see the
description of GET_INFO (key_name, "key_modifiers").
The GET_INFO (keyword, "name") built-in procedure has been extended to
return a string that includes all the key modifier keywords used to
create a key name. For more information about fetching the string
equivalent of a key name, see the description of GET_INFO (keyword,
"name").
If you specify only one DECTPU key name as an argument to KEY_NAME,
KEY_NAME is sensitive to the case of the argument. For example, the
following expressions do not evaluate to the same value:
KEY_NAME ("Z");
KEY_NAME ("z");
|
When you use the optional parameter SHIFT_KEY with KEY_NAME, however,
KEY_NAME is case insensitive and the following statements return the
same keyword:
KEY_NAME ("Z", SHIFT_KEY);
KEY_NAME ("z", SHIFT_KEY);
|
Signaled Errors
|
TPU$_INCKWDCOM
|
WARNING
|
Inconsistent keyword combination.
|
|
TPU$_MUSTBEONE
|
WARNING
|
String must be one character long.
|
|
TPU$_NOTDEFINABLE
|
WARNING
|
Second argument is not a valid reference to a key.
|
|
TPU$_NEEDTOASSIGN
|
ERROR
|
KEY_NAME call must be on the right-hand side of an assignment statement.
|
|
TPU$_ARGMISMATCH
|
ERROR
|
Wrong type of data sent to the KEY_NAME built-in.
|
|
TPU$_BADKEY
|
ERROR
|
KEY_NAME accepts SHIFT_KEY, FUNCTION, or KEYPAD as a keyword argument.
|
|
TPU$_TOOFEW
|
ERROR
|
Too few arguments passed to the KEY_NAME built-in.
|
|
TPU$_TOOMANY
|
ERROR
|
Too many arguments passed to the KEY_NAME built-in.
|
Examples
The following example creates a name for the key sequence GOLD/Ctrl/KP4
and binds the EVE FILL command to the resulting key sequence:
| #1 |
new_key := KEY_NAME (KP4, Ctrl_MODIFIED, SHIFT_KEY);
DEFINE_KEY ("eve_fill", new_key);
|
|
