Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

DEC Text Processing Utility Reference Manual


Previous Contents Index

The widget window is mapped if it is not already mapped.

Signaled Errors

TPU$_INVPARAM ERROR The parameter to LOWER_WIDGET has the wrong data type.
TPU$_NORETURNVALUE ERROR This built-in does not return a result.
TPU$_NOTSUBCLASS WARNING The parameter to LOWER_WIDGET is not a widget that has an associated widget window.
TPU$_TOOFEW ERROR You specified too few parameters.
TPU$_TOOMANY ERROR You specified too many parameters.

READ_CHAR


Format

string := READ_CHAR


Parameters

None.

Return Value


A variable of type string that contains a character entered from the keyboard.

Description

The READ_CHAR procedure stores the next character entered from the keyboard in a string variable. The character read by READ_CHAR is not echoed on the screen; therefore, the cursor position does not move.

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; 
      

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:
#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; 
      

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; 
 
 
 
      


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
6020PRO_021.HTML