 |
DEC Text Processing Utility Reference Manual
READ_CHAR does not process escape sequences. If a DECTPU procedure uses
READ_CHAR for an escape sequence, only part of the escape sequence is
read. The remaining part of the escape sequence is treated as text
characters. If control then returns to DECTPU, or a READ_KEY or
READ_LINE built-in procedure is executed, the results may be
unpredictable.
In DECwindows DECTPU, READ_CHAR maps the main window if it is not
already mapped.
In the DECwindows environment, READ_CHAR cannot read a keypad or
function key. If a DECTPU procedure uses READ_CHAR and you press a
keypad or function key, READ_CHAR returns a null string and signals the
warning TPU$_NOCHARREAD.
DECwindows applications that execute READ_CHAR built-ins should use
error handlers that contain the TPU$_READABORTED selector. DECTPU
signals that error if a READ_CHAR built-in is aborted by any of the
following events: resize, widget callback, loss of primary selection,
and client message.
The code associated with that selector should return from the procedure
by executing either an ABORT or RETURN statement. If instead of
returning, the procedure executes another READ_CHAR built-in, DECTPU
enters an infinite loop.
READ_CHAR does not abort for input focus events.
When you use the /NODISPLAY qualifier to invoke DECTPU, READ_CHAR
signals TPU$_REQUIRESTERM, "Feature requires a terminal", if SYS$INPUT
is not a terminal.
Signaled Errors
|
TPU$_NOCHARREAD
|
WARNING
|
READ_CHAR did not read a character.
|
|
TPU$_NEEDTOASSIGN
|
ERROR
|
READ_CHAR must be on the right-hand side of an assignment statement.
|
|
TPU$_TOOMANY
|
ERROR
|
READ_CHAR takes no arguments.
|
Examples
The following example stores the next character that is entered on the
keyboard in the string new_char:
The following example enters the next character that is entered from
the keyboard in the current buffer. If a key that sends an escape
sequence is pressed, the first character of the escape sequence is
copied into the buffer. Subsequent keystrokes are interpreted as
self-inserting characters, defined keys, or undefined keys, as
appropriate.
| #2 |
PROCEDURE user_quote
COPY_TEXT (READ_CHAR);
ENDPROCEDURE;
|
The following example uses a coding style that avoids an infinite loop.
In this example, DECTPU aborts a READ_CHAR built-in when a widget
callback occurs. The error handler then returns from that procedure.
| #3 |
procedure get_a_char (the_char)
on_error
[TPU$_READABORTED]:
message ("Prompt terminated.", 0);
return;
endon_error;
loop
...
the_key := read_char;
...
endloop;
endprocedure;
|
READ_CLIPBOARD
Format
[[range |unspecified]] := READ_CLIPBOARD
Parameters
None.
Return Values
range
A range that contains the text copied into the current buffer.
unspecified
A data type that indicates that no data was obtained from the clipboard.
Description
The READ_CLIPBOARD procedure reads string format data from the
clipboard and copies it into the current buffer, at the editing point,
using the buffer's current text mode (insert or overstrike). If DECTPU
finds a line-feed character in the data, it removes the line feed and
any adjacent carriage returns and puts the data after the line feed on
the next line of the buffer. If DECTPU must truncate the data from the
clipboard, DECTPU copies the truncated text into the current buffer.
All text read from the clipboard is copied into the buffer starting at
the editing point. If DECTPU must start a new line to fit all the text
into the buffer, the new line starts at column 1, even if the current
left margin is not set at column 1.
Signaled Errors
|
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$_CLIPBOARDFAIL
|
WARNING
|
The clipboard did not return any data.
|
|
TPU$_REQUIRESDECW
|
ERROR
|
You can use the READ_CLIPBOARD built-in only if you are using
DECwindows TPU.
|
|
TPU$_STRTOOLARGE
|
ERROR
|
The amount of data in the clipboard exceeds 65535 characters.
|
|
TPU$_TOOMANY
|
ERROR
|
Too many arguments passed to the READ_CLIPBOARD built-in.
|
Example
The following example shows one possible way that an application can
use the READ_CLIPBOARD built-in procedure. This procedure is a modified
version of the EVE procedure EVE$$INSERT_CLIPBOARD. The original
version is in SYS$EXAMPLES:EVE$DECWINDOWS.TPU.
|
PROCEDURE eve$$insert_clipboard
ON_ERROR
[TPU$_CLIPBOARDNODATA]:
eve$message (EVE$_NOINSUSESEL);
eve$learn_abort;
RETURN (FALSE);
[TPU$_CLIPBOARDLOCKED]:
eve$message (EVE$_CLIPBDREADLOCK);
eve$learn_abort;
RETURN (FALSE);
[TPU$_TRUNCATE]:
[OTHERWISE]:
eve$learn_abort;
ENDON_ERROR;
IF eve$test_if_modifiable (CURRENT_BUFFER)
THEN
READ_CLIPBOARD; ! This statement using
! READ_CLIPBOARD reads
! data from the clipboard
! and copies it into the
! current buffer.
RETURN (TRUE);
ENDIF;
eve$learn_abort;
RETURN (FALSE);
ENDPROCEDURE;
|
EVE$$INSERT_CLIPBOARD fetches the contents of the clipboard and places
them in the current buffer.
READ_FILE
Format
[[string2 := ]] READ_FILE (string1)
Parameter
string1
A string that is the name of the file you want to read and include in
the current buffer.
Return Value
A string that is the specification of the file read.
Description
The READ_FILE procedure reads a file and inserts the contents of the
file immediately before the current line in the current buffer.
READ_FILE optionally returns a string that contains the file
specification of the file read.
If the current buffer is mapped to a visible window, the READ_FILE
built-in procedure causes the screen manager to synchronize the editing
point (which is a buffer location) with the cursor position (which is a
window location). This may result in the insertion of padding spaces or
lines into the buffer if the cursor position is before the beginning of
a line, in the middle of a tab, beyond the end of a line, or after the
last line in the buffer.
DECTPU writes a message that indicates how many records (lines) were
read.
If you try to read a file that contains lines longer than 32767
characters, DECTPU truncates the lines to the first 32767 characters
and issues a warning.
Note
If you delete a file after using READ-FILE to insert the file into a
buffer, you will not be able to recover the buffer. This is because
DECTPU requires the original source file to recover when using a
buffer-change journal file.
|
Signaled Errors
|
TPU$_NOCURRENTBUF
|
WARNING
|
You are not positioned in a buffer.
|
|
TPU$_CONTROLC
|
ERROR
|
The execution of the read terminated because you pressed Ctrl/C.
|
|
TPU$_NOCACHE
|
ERROR
|
There is not enough memory to allocate a new cache.
|
|
TPU$_TOOFEW
|
ERROR
|
READ_FILE requires at least one parameter.
|
|
TPU$_TOOMANY
|
ERROR
|
READ_FILE accepts no more than one parameter.
|
|
TPU$_INVPARAM
|
ERROR
|
The parameter to READ_FILE must be a string.
|
|
TPU$_TRUNCATE
|
WARNING
|
One of the lines in the file was too long to fit in a DECTPU buffer.
|
The following errors, warnings, and messages can be signaled by
DECTPU's file I/O routine. You can provide your own file I/O routine by
using DECTPU's callable interface. If you do so, READ_FILE's signaled
errors, warnings, and messages depend upon what status you signaled in
your file I/O routine.
|
TPU$_OPENIN
|
ERROR
|
READ_FILE could not open the file you specified.
|
|
TPU$_READERR
|
ERROR
|
READ_FILE did not finish reading the file because it encountered a file
system error.
|
|
TPU$_CLOSEIN
|
ERROR
|
READ_FILE did not finish closing the file because it encountered a file
system error.
|
Examples
The following example reads the file LOGIN.COM and adds it to your
current buffer:
| #1 |
READ_FILE ("login.com")
|
The following example creates a second window and a second buffer and
maps the window to the screen. The procedure also prompts you for a
file name to include in the buffer and defines the key sequence Shift/W
(the Shift key follow by W) as the sequence with which to move to the
second window. (The default shift key is PF1.)
| #2 |
PROCEDURE user_two_windows
w := CREATE_WINDOW (1, 10, ON);
b := CREATE_BUFFER ("buf2");
MAP (w, b);
READ_FILE (READ_LINE ("Enter file name for 2nd window : "));
POSITION (BEGINNING_OF (b));
DEFINE_KEY ("POSITION (w)", KEY_NAME ("W", SHIFT_KEY));
ENDPROCEDURE;
|
READ_GLOBAL_SELECT
Format
[[ {range |unspecified} := ]] READ_GLOBAL_SELECT ( {PRIMARY |SECONDARY
|selection_name} , selection_property_name )
Parameters
PRIMARY
A keyword that indicates that the application is requesting information
about a property of the primary global selection.
SECONDARY
A keyword that indicates that the application is requesting information
about a property of the secondary global selection.
selection_name
A string that identifies the global selection whose property is the
subject of the 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 that specifies the property whose value the application is
requesting.
Return Values
range
A range that contains the text copied into the current buffer.
unspecified
A data type that indicates that the information requested by the
application was not available.
Description
The READ_GLOBAL_SELECT procedure requests information about the
specified global selection from the owner of the global selection. For
example, you can ask about the global selection's font, the number of
lines it contains, or the string-formatted data it contains, if any. If
the owner provides the information, READ_GLOBAL_SELECT reads it and
copies it into the current buffer at the editing point, using the
buffer's current text mode (insert or overstrike). The
READ_GLOBAL_SELECT built-in procedure also puts line breaks in the text
copied into the buffer.
All text read from the global selection is copied into the current
buffer, starting at the editing point. If DECTPU must start a new line
to fit all the text into the buffer, the new line starts at column 1,
even if the current left margin is not set at column 1.
If the global selection information requested is an integer, the
built-in converts the integer into a string before copying it into the
current buffer. If the information requested is a string, the built-in
copies the string into the buffer, replacing any line feeds with line
breaks.
Carriage returns adjacent to line feeds are not copied into the buffer.
Signaled Errors
|
TPU$_BADKEY
|
WARNING
|
You specified an invalid keyword as a parameter.
|
|
TPU$_GBLSELOWNER
|
WARNING
|
DECTPU owns the global selection.
|
|
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.
|
|
TPU$_ARGMISMATCH
|
ERROR
|
Wrong type of data sent to the READ_GLOBAL_SELECT built-in.
|
|
TPU$_REQUIRESDECW
|
ERROR
|
You can use the READ_GLOBAL_SELECT built-in only if you are using
DECwindows DECTPU.
|
|
TPU$_TOOFEW
|
ERROR
|
Too few arguments passed to the READ_GLOBAL_SELECT built-in.
|
|
TPU$_TOOMANY
|
ERROR
|
Too many arguments passed to the READ_GLOBAL_SELECT built-in.
|
Example
The following example reads the string-formatted contents of the
primary global selection and copies it into the current buffer at the
current location:
|
READ_GLOBAL_SELECTION (PRIMARY, "STRING");
|
READ_KEY
Format
keyword := READ_KEY
Parameters
None.
Return Value
A key name for the key just pressed.
Description
The READ_KEY procedure waits for you to press a key and then returns
the key name for that key. READ_KEY should be used rather than
READ_CHAR when you are entering escape sequences, control characters,
or any characters other than text characters. READ_KEY processes escape
sequences and DECTPU's shift key (PF1 by default).
The key that is read by READ_KEY is not echoed on the terminal screen.
When you invoke DECTPU with the /NODISPLAY qualifier, READ_KEY signals
TPU$_REQUIRESTERM, "Feature requires a terminal", if SYS$INPUT is not a
terminal.
In DECwindows DECTPU, READ_KEY maps the main window if it is not
already mapped.
DECwindows applications that execute READ_KEY built-ins should use
error handlers that contain the TPU$_READABORTED selector. DECTPU
signals that error if a READ_KEY built-in is aborted by any of the
following events: resize, widget callback, loss of primary selection,
and client message.
The code associated with that selector should return from the procedure
by executing either an ABORT or RETURN statement. If instead of
returning, the procedure executes another READ_KEY built-in, DECTPU
enters an infinite loop.
READ_KEY does not abort for input focus events.
Signaled Errors
|
TPU$_NEEDTOASSIGN
|
ERROR
|
READ_KEY must be on the right-hand side of an assignment statement.
|
|
TPU$_TOOMANY
|
ERROR
|
READ_KEY accepts no arguments.
|
|
TPU$_CONTROLC
|
ERROR
|
You pressed Ctrl/C during the execution of READ_KEY.
|
|
TPU$_REQUIRESTERM
|
ERROR
|
You cannot use READ_KEY when DECTPU is in NODISPLAY mode.
|
Examples
The following example reads the next key that is entered and stores the
keyword for that key in the variable my_key:
The following example looks in the current key map list for the next
key pressed. If the key is found, any comment associated with that key
is put into the message buffer.
| #2 |
PROCEDURE user_help_on_key
LOCAL key_pressed,
key_comment;
MESSAGE ("Press the key you want help on.");
key_pressed := READ_KEY;
key_comment := LOOKUP_KEY (key_pressed, COMMENT);
IF key_comment = 0
THEN
MESSAGE ("That key is not defined.");
ELSE
IF key_comment = ""
THEN
MESSAGE ("There is no comment for that key.");
ELSE
MESSAGE (key_comment);
ENDIF;
ENDIF;
ENDPROCEDURE;
|
The following example uses a coding style that avoids an infinite loop.
In this example, DECTPU aborts a READ_KEY built-in when a widget
callback occurs. The error handler then returns from that procedure.
| #3 |
procedure get_a_key (the_key)
on_error
[TPU$_READABORTED]:
message ("Prompt terminated.", 0);
return;
endon_error;
loop
...
the_key := read_key;
...
endloop;
endprocedure;
|
READ_LINE
Format
string2 := READ_LINE [[ (string1 [[ ,integer ]] ) ]]
Parameters
string1
A string that is the text used as a prompt for input. The maximum
length is 255 characters. This parameter is optional.
integer
The integer value that indicates how many characters to read from the
input entered in response to the prompt. The maximum number is 132.
This parameter is optional. If not present, control of execution passes
from READ_LINE to DECTPU's main loop when you press Return, Ctrl/Z, or
the one hundred thirty-second character.
Return Value
A string that stores your response to a prompt.
Description
The READ_LINE procedure displays the text that you specify as a prompt
for input and reads the information entered in response to the prompt.
You can optionally specify the maximum number of characters to be read.
READ_LINE returns your data string response to the prompt.
The terminators for READ_LINE are the standard OpenVMS terminators such
as Ctrl/Z and the Return key. READ_LINE is not affected by DECTPU key
definitions; the built-in takes literally all keys except standard
OpenVMS terminators.
By default, the text you specify as a prompt is written in the prompt
area on the screen. The prompt area is established with the SET
(PROMPT_AREA) built-in procedure. See SET (PROMPT_AREA) for more
information.
If no prompt area is defined, the text specified as a prompt is
displayed at the current location on the device pointed to by
SYS$OUTPUT (usually your terminal).
If READ_LINE terminates because it reaches the limit of characters
specified as the second parameter, the last character read becomes the
last key. See the example section for a procedure that tests for the
last key entered in a prompt string.
In DECwindows DECTPU, READ_LINE maps the main widget if it is not
already mapped.
When you invoke DECTPU with the /NODISPLAY qualifier, terminal
functions such as screen display and key definitions are not used. The
READ_LINE built-in procedure calls the LIB$GET_INPUT routine to issue a
prompt to SYS$INPUT and accept input from you. A read done this way
does not terminate when the number of keys you specified as the second
parameter (integer) are entered. However, string2
contains the number of characters specified by the integer parameter,
and LAST_KEY contains the value of the key that corresponds to the
integer specified as the last key to be read, except in the following
cases: If the read is terminated by Ctrl/Z, LAST_KEY has the value
Ctrl/Z; if the read is terminated by a carriage return before the
specified integer limit is reached, LAST_KEY has the value of the
Return key.
Signaled Errors
|
TPU$_NEEDTOASSIGN
|
ERROR
|
READ_LINE must appear on the right-hand side of an assignment statement.
|
|
TPU$_TOOMANY
|
ERROR
|
READ_LINE accepts no more than two arguments.
|
|
TPU$_INVPARAM
|
ERROR
|
One of the arguments to READ_LINE has the wrong data type.
|
Examples
The following example displays the text "Enter key definition:" in the
prompt area, and stores the first character of your response in the
variable my_prompt:
| #1 |
my_prompt := READ_LINE ("Enter key definition:", 1)
|
The following example prompts for three characters and stores them in
the variable my_input:
| #2 |
PROCEDURE user_test_lastkey
LOCAL my_key,
k;
my_input := READ_LINE ("Enter 3 characters:", 3);
! Press the keys "ABC"
my_key := LAST_KEY;
IF my_key = KEY_NAME ("C")
THEN
MESSAGE (" C key ");
ELSE
MESSAGE (" Error ");
ENDIF;
ENDPROCEDURE;
|
It then tests for the last key entered.
The following example is used by commands that prompt for integers. The
procedure returns true if prompting worked or was not needed; it
returns false otherwise. The returned value is passed back as an output
parameter.
| #3 |
! Parameters:
!
! old_number Old integer value - input
! new_number New integer value - output
! prompt_string Text of prompt - input
! no_value_message Message printed if user hits RETURN to
! get out of the command - input
PROCEDURE user_prompt_number (old_number, new_number,
prompt_string, no_value_message)
! String read after prompt
LOCAL read_line_string;
new_number := old_number;
IF old_number < 0
THEN
read_line_string := READ_LINE (prompt_string);
EDIT (read_line_string, TRIM);
IF read_line_string = "
THEN
MESSAGE (no_value_message);
new_number := 0;
RETURN (0);
ELSE
! Change lowercase l to #1
TRANSLATE (read_line_string, "1", "l");
new_number := INT (read_line_string);
IF (new_number = 0) and (read_line_string <> "0")
THEN
MESSAGE (FAO ("Don't understand !AS",
read_line_string));
RETURN (0);
ELSE
RETURN (1);
ENDIF;
ENDIF;
ELSE
RETURN (1);
ENDIF;
ENDPROCEDURE;
|
REALIZE_WIDGET
Format
REALIZE_WIDGET (widget)
Parameter
widget
The widget you want DECTPU to realize.
Description
The REALIZE_WIDGET procedure creates a widget window for the specified
widget and, if a composite widget, recursively realizes all the
widget's managed children. REALIZE_WIDGET interacts with the widget's
mapped_when_managed bit. The setting of this bit determines whether or
not DECTPU maps the widget window to the display. See the OpenVMS
DECwindows Toolkit Routines Reference Manual for a complete
explanation.
Signaled Errors
|
TPU$_NEEDTOASSIGN
|
ERROR
|
REALIZE_WIDGET must return a value.
|
|
TPU$_TOOMANY
|
ERROR
|
Too many arguments specified.
|
|
TPU$_TOOFEW
|
ERROR
|
Too few arguments specified.
|
|
TPU$_INVPARAM
|
ERROR
|
The argument to REALIZE_WIDGET has the wrong data type.
|
|
TPU$_REQUIRESDECW
|
ERROR
|
Requires the DECTPU DECwindows screen updater.
|
RECOVER_BUFFER
Format
buffer1 := RECOVER_BUFFER (string1 {[[,string2 ]] |[[,buffer2 ]]})
Parameters
string1
The name of the buffer you are trying to recover.
string2
The name of the journal file you want DECTPU to use to recover your
buffer. If you did not use SET (JOURNALING) to set a journal file name,
in most cases DECTPU will have created the journal file by using its
default journal file naming algorithm. If the journal file was named by
default, you need not specify a journal file name with RECOVER_BUFFER.
If you specified a journal file name by using SET (JOURNALING), use the
same name with RECOVER_BUFFER.
|
