Document revision date: 30 March 2001

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

Examples

The following example stores the next character that is entered on the keyboard in the string new_char:

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.

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.

procedure get_a_char (the_char) 
on_error 
    [TPU$_READABORTED]: 
        message ("Prompt terminated.", 0); 
        return; 
endon_error; 
loop 
... 
    the_key := read_char; 
... 
endloop; 
endprocedure; 
      

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

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.

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

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

Examples

The following example reads the file LOGIN.COM and adds it to your current buffer:

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

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; 
      

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

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"); 
      

Format

keyword := READ_KEY

Parameters

None.

Return Value

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

Examples

The following example reads the next key that is entered and stores the keyword for that key in the variable my_key:

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.

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.

procedure get_a_key (the_key) 
on_error 
    [TPU$_READABORTED]: 
        message ("Prompt terminated.", 0); 
        return; 
endon_error; 
loop 
... 
    the_key := read_key; 
... 
endloop; 
endprocedure; 
      

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

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

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:

my_prompt := READ_LINE ("Enter key definition:", 1) 
      

The following example prompts for three characters and stores them in the variable my_input:

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.

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

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

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

	privacy and legal statement
6020PRO_021.HTML