DEC Text Processing Utility Reference Manual

Updated: 11 December 1998

DEC Text Processing Utility Reference Manual

Contents

Index

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:

#1
new_char := READ_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;

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;

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:

#1
my_key := READ_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;

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;

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;

! 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.

Previous Next Contents Index

Copyright © Compaq Computer Corporation 1998. All rights reserved.
Legal

6020PRO_021.HTML

DEC Text Processing Utility Reference Manual

Signaled Errors

Examples

READ_CLIPBOARD

Format

rangeunspecified := READ_CLIPBOARD

Parameters

Return Values

range

unspecified

Description

Signaled Errors

Example

READ_FILE

Format

[[string2 := ]] READ_FILE (string1)

Parameter

string1

Return Value

Description

Signaled Errors

Examples

READ_GLOBAL_SELECT

Format

[[ range unspecified := ]] READ_GLOBAL_SELECT ( PRIMARY SECONDARY selection_name, selection_property_name )

Parameters

PRIMARY

SECONDARY

selection_name

selection_property_name

Return Values

range

unspecified

Description

Signaled Errors

Example

READ_KEY

Format

keyword := READ_KEY

Parameters

Return Value

Description

Signaled Errors

Examples

READ_LINE

Format

string2 := READ_LINE [[ (string1 [[ ,integer ]] ) ]]

Parameters

string1

integer

Return Value

Description

Signaled Errors

Examples

REALIZE_WIDGET

Format

REALIZE_WIDGET (widget)

Parameter

widget

Description

Signaled Errors

RECOVER_BUFFER

Format

buffer1 := RECOVER_BUFFER (string1 [[,string2 ]] [[,buffer2 ]])

Parameters

string1

string2

range
unspecified
:= READ_CLIPBOARD

[[

range
unspecified
:= ]] READ_GLOBAL_SELECT (

PRIMARY
SECONDARY
selection_name
, selection_property_name )

buffer1 := RECOVER_BUFFER (string1

[[,string2 ]]
[[,buffer2 ]]
)