READ Command
Reads from 0 to 32 KB from the keyboard into the named variable. The timeout argument is optional. The command cannot end with a pound sign (#) or colon (:)
Syntax
READ variable:timeout ; Variable-length read
READ variable#length:timeout ; Fixed-length read
READ *variable:timeout ; Single-character read
For more information, see READ in the ObjectScript Language Reference.
Examples
The following table gives several examples of how you use these arguments.
READ Command Arguments: Examples
| Example |
Effect |
| READ ^GLO |
Reads characters from the current device until it finds a terminator, and puts the resulting string in the global ^GLO. |
| READ X:60 |
Reads from the current device until it finds a terminator, and puts the string read into the variable X. Waits up to 60 seconds for the input to end before timing out. Striking a key does not reset the timeout value. |
| READ *X |
Reads a single character from the current device and puts its decimal value in the local variable X. |
| READ X#1 |
Reads a single character from the current device and puts its string value into the local variable X. |
| READ X#45:60 |
Reads up to 45 characters from the current device and puts the string value into the local variable X. Waits up to 60 seconds for the input to end before timing out. |
Read Line Recall
Read line recall mode provides line recall of editable lines as input for READ operations from a terminal. These recallable lines include both previous READ input lines and previous command lines. Echoing of input lines is a necessary precondition for read line recall.
InterSystems IRIS supports read line recall for both variable-length terminal reads (READ variable) and fixed-length terminal reads (READ variable#length). InterSystems IRIS does not support read line recall for single-character terminal reads (READ *varaiable). Read line recall supports the optional timeout argument.
For a fixed-length terminal read, the recalled line is truncated to one character less than the number of characters specified in the READ. This final READ character position is reserved for typing a line termination character, specifying an edit character, or adding one more data character.
When read line recall is active, you can provide input to a READ by using the Up Arrow and Down Arrow keys to recall a previous terminal input line. You can then use the Left Arrow, Right Arrow, Home, and End keys to position the cursor for editing the recalled line. You can use the Backspace key to delete a character, Ctrl-X to delete the entire line, or Ctrl-U to delete all of the line to the left of the cursor.
When read line recall is not active, the four Arrow keys, the Home key, and the End key all issue a line termination character. You can use the Backspace key to delete a single input character, and Ctrl-X (or Ctrl-U) to delete the entire input line.
You can use the OPEN or USE command to activate read line recall by specifying the R protocol, or to deactivate read line recall by specifying the N, I, S, or T protocol.
Special Protocol Characters Affect Terminal I/O
Each operating system intercepts certain protocol characters (UNIX®) or key combinations (such as CTR-ALT-DEL on Windows platforms), preventing these characters from affecting InterSystems IRIS. The console for Windows makes no attempt to override these operating system characteristics.
Other special characters can alter the way your routines execute, but do not appear in the READ command variable. Operating your terminal in image mode cancels these effects and causes InterSystems IRIS to treat these characters like any others.
READ is affected by output and input control characters. READ simply reads all other control characters, except termination characters. It does not echo them.
Output control characters affect both the flow and the output of a routine. These are described in the following table:
Output Control Characters
| Output Control Character |
Decimal Value |
Definition |
| Ctrl-C |
3 |
If breaks are enabled, Ctrl-C interrupts a routine’s execution. The routine behaves as though an <INTERRUPT> error has occurred. If breaks are disabled, Ctrl-C causes InterSystems IRIS to discard anything entered thus far in the current READ. You can use Ctrl-C to interrupt global module requests that require network operations. To trap Ctrl-C, set the special variable $ZTRAP. For additional information, see the section on enabling breaks. |
| Ctrl-S |
19 |
Ctrl-S suspends output to the terminal. Output to the terminal resumes when InterSystems IRIS encounters a Ctrl-Q. |
| Ctrl-Q |
17 |
Ctrl-Q resumes output suspended by Ctrl-S. |
Input control characters affect input. Image mode (I protocol) treats these characters as data, but in normal mode they affect input to the current READ command. These characters are described in the following table:
Input Control Characters
| Input Control Character |
Decimal Values |
Definition |
| Delete |
127 |
The Delete character removes the last character entered. If you press Delete repeatedly, you remove characters from right to left, but not beyond the beginning of the current READ. Delete uses a backspace to erase the last character on a CRT screen. Delete echoes as a backslash character ("\") on a printing terminal (such as a teletype). |
| Ctrl-U |
21 |
Deletes either all characters you have entered since the start of the current READ or the contents of theUNIX® type-ahead buffer until the last carriage return. Ctrl-U erases the deleted characters on a CRT; on a printer it echoes ^U and sends a Return and LineFeed To flush the typeahead buffer completely, use Ctrl-X. |
| Ctrl-H |
8 |
Performs the same function as Delete on some systems. |
| Return |
13 |
A carriage return ends a READ in all protocols except “I” (image mode). |
| Escape |
27 |
Begins an escape sequence. The sequence itself ends the READ, and $ZB contains the full sequence, including the leading Escape. InterSystems IRIS does not echo the characters of the sequence, but it does change $X and $Y unless you include the escape sequence in a WRITE * command. See $X and $Y and Cursor Position earlier on this page. An invalid escape sequence sets bit 8 of $ZA. Consider the example, READ X. After you enter the characters “AB”, Escape, and “E”, X will contain the two characters “AB”, while $ZB contains the two characters Escape E. $X increases by two for the AB, but does not increase for the E. |
| LineFeed |
10 |
InterSystems IRIS interprets LineFeed as a terminator for all terminal I/O. |
| Tab |
9 |
Tab is a data value that echoes as a space, increases $X by one, and is stored as a Tab character in the string returned by the READ. This is true for all protocols except “T” (terminator). In “T” protocol, a tab is a terminator control character. |
Disabling UNIX® Job Control
Using the UNIX® job control character, Ctrl-Z, within InterSystems IRIS can cause serious problems. For this reason, InterSystems IRIS disables Ctrl-Z automatically when you enter InterSystems IRIS on platforms whose UNIX® shell supports job control. InterSystems IRIS reenables Ctrl-Z when you exit InterSystems, and when you issue a $ZF(-1) call to execute a UNIX® shell command.
How the READ Command Processes Input
The READ command processes each character as it arrives from the input buffer. The following table shows how this processing occurs in normal mode. The figure below shows how the READ command processes image mode data.
READ Command Processing Normal (Non-Image) Mode
READ Command Processing Image Mode
