Caché I/O Device Guide
Terminal I/O
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter discusses terminal I/O in Caché.

Overview of Terminal I/O Capabilities
Caché ObjectScript provides commands that support serial asynchronous ASCII terminals. You can also use these commands with console I/O.
Using Caché terminal I/O, your routine can:
Printers are handled as terminal I/O devices on most platforms. UNIX® and OpenVMS systems always handle a printer as a terminal I/O device. On Windows, a printer connected through a serial communications port is handled as a terminal I/O device. Otherwise, Windows systems handle printers as sequential file I/O devices. For further details, refer to the Printers chapter in this manual.
Your Login Terminal or Console is Your Principal Device
The terminal or console on which you log in to Caché is your principal device. You need not open your principal device. If you have not issued an OPEN and a USE, the first time a process issues a READ or WRITE, Caché opens your principal device automatically, and establishes it as the current device, as if you had issued OPEN 0 USE 0 explicitly.
Note:
Through the rest of this chapter the word terminal is used to refer to both terminals and consoles.
Special Variables Show I/O Conditions
I/O commands can affect the values of special variables. You can test these variables to determine I/O conditions:
See the chapter I/O Devices and Commands for more information on the device-independent $IO special variable. The next sections describe terminal-specific information about the remaining special variables.
$X and $Y and Cursor Position
$X contains the horizontal position and $Y the vertical position of the cursor or print head. $X=0,$Y=0 denotes the upper left corner of the CRT screen or the printed page. Caché calculates both $X and $Y modulo 256; that is, they range from 0 to 255 and then begin again at 0.
The following table shows the effects of writing or echoing the characters
Effects of Echoing Characters
Character ASCII Code Effect on $X Effect on $Y
Form Feed 12 $X=0 $Y=0
Return 13 $X=0 $Y=$Y
Line Feed 10 $X=$X $Y=$Y+1
Backspace 8 $X=$X-1 $Y=$Y
Tab 9 $X=$X+1 $Y=$Y
Any printable ASCII character 32 through 126 $X=$X+1 $Y=$Y
The S protocol of OPEN and USE turns off the echo. This protocol also disables the changing of $X and $Y during input, so that they truly indicate the cursor's position.
WRITE * and $X and $Y
WRITE * does not change $X and $Y. Thus, you can send a control sequence to your terminal and $X and $Y will still reflect the true cursor position. Some control sequences do move the cursor, so you can set $X or $Y directly when you need to.
$X and $Y Example
In the following example, a control sequence moves the cursor in a VT100 terminal to line 10, column 20, and sets $X and $Y accordingly.
 ; set DY and DX to desired 
 ; values for $Y and $X 
 SET DY=10
 SET DX=20
 ; ...
 ; escape sequence moves
 ; cursor to desired position
 WRITE *27, *91, DY+1, *59, DX+1, *72
 ; ...
 ; updates $X and $Y
 SET $Y=DY
 SET $X=DX
Effect of Escape Sequences on $X and $Y Varies
Escape sequences can alter the effect of echoing on the values of $X and $Y. Three factors control this effect:
Escape Sequences Don't Affect $X and $Y on OpenVMS Systems
On OpenVMS, by default, when writing or echoing any string that includes the ASCII Escape character (decimal value 27), Escape and all the characters after it in the string leave $X and $Y unchanged. Thus, ANSI standard control sequences, acted on by the terminal but not displayed, cannot upset the relation of $X and $Y to the cursor's position, even though the sequence may contain graphic characters.
Escape Sequences Do Affect $X and $Y on Windows and UNIX® Systems
By default on UNIX® and Windows, when writing or echoing any string that includes the ASCII Escape character (decimal value 27), Caché updates $X and $Y just as it does for any other character sequence. Thus, ANSI standard control sequences, which the terminal acts on, but does not display, can upset the relationship of $X and $Y to the cursor's position.
The easiest way to avoid this problem is to use the DX() to alter the behavior (see the next section). Alternatively, you can use the ASCII value of each character in the string in a WRITE * statement.
Control Sequence Example
Instead of using the code:
%SYS>WRITE $CHAR(27)_"[lm"
you can use the following equivalent statement that does not update $X and $Y:
%SYS>WRITE *27,*91,*49,*109
Switches Control Updates of $X for Escape Sequences
To select non-default behavior for updating $X for your process, issue the DX(n) method of the %SYSTEM.Process class.
The system manager can alter the system-wide default behavior by setting the DX property of the Config.Miscellaneous class.
In both cases, n has a value from 0 through 4, as follows:
Value Default Behavior for Updating $X
0 Caché for UNIX® and Windows behavior (default on those systems)
1 DSM behavior
2 DTM/MSM behavior
3 Caché for OpenVMS VAX and Alpha behavior (default on those systems)
For more information, see $X in the Caché ObjectScript Language Reference.
$TEST Shows Timed Operation Results
The $TEST special variable is set by commands that take a timeout value. These commands include OPEN and READ. The value of $TEST can be set to 1 or 0:
Note:
OPEN and READ commands without a timeout have no effect on $TEST.
For more information, see $TEST in the Caché ObjectScript Language Reference.
$ZA Shows READ Status
The $ZA special variable contains a number of bit flags that show the status of the last READ on the current device. You cannot set $ZA; Caché controls its value. $ZA remains valid until the next READ. $ZA contains the sum of the values listed in the table, which shows how your program can test this variable. ($ZA also contains bit flags for modem connection status, which are not listed here. For a complete list of $ZA bit flag values, see $ZA in Caché ObjectScript Language Reference.)
$ZA Read Status Values
Value Test Meaning
1 $ZA#2 A Ctrl-C arrived, whether or not breaks were enabled.
2 $ZA\2#2 The READ timed out.
256 $ZA\256#2 Caché detected an invalid escape sequence.
512 $ZA\512#2 The hardware detected a parity or framing error.
While many of the conditions that $ZA shows are errors, they do not interrupt the program's flow by trapping to the $ZTRAP special variable. Programs that are concerned with these errors must examine $ZA after every READ. Of course, a Ctrl-C with breaks enabled will trap to $ZTRAP. For more on error trapping and $ZTRAP, see the Error Processing chapter of Using Caché ObjectScript and $ZTRAP in the Caché ObjectScript Language Reference.
$ZB Shows What Ended a READ
$ZB shows what character sequence or event ended the last READ operation on the current device. You cannot set $ZB; Caché sets the value of $ZB each time you perform a READ. You can use this value to act on non-printable characters such as the up arrow key or function keys.
$ZB can contain any of the following:
$ZB never contains more than 64 characters. A longer escape sequence is invalid.
$ZB Example
The following example assigns the user-specified input characters to the READ command variable x, and assigns the input terminator (usually the Return character) to the $ZB special variable. When issuing this command from the terminal prompt, you need to set a variable to trap the value of $ZB on the same command line as the READ command. This is because the line return used to issue a command line is written to $ZB as a terminator character. This example uses ZZDUMP to display the value of the characters trapped by $ZB.
USER>READ x SET y=$ZB
USER>ZZDUMP y

0000: 0D 
USER>
OPEN and USE Commands
OPEN Command
Establishes ownership of the terminal. An optional parameter list can set the right margin, specify device protocols, and specify one or more termination characters. Following the parameter list, you can optionally specify a timeout argument, and/or a mnespace argument. The mnespace argument specifies the Caché routine where control mnemonics for use with WRITE /mnemonic are defined.
OPEN pauses the process until the system finishes opening the device. If you press Ctrl-C to interrupt the OPEN command, a <NOTOPEN> error results.
OPEN retains control until the opening of the device is complete, unless you specify a timeout. With a timeout, if Caché cannot open the device in the number of seconds you specify, it sets $TEST to 0 and returns control to the process. Even if a device is unavailable at the operating-system level, OPEN keeps trying to obtain the device until it succeeds or the timeout expires.
OPEN Syntax
The OPEN command takes the following arguments:
OPEN terminal:(margin:protocols:terminator:portstate:baud):timeout:"mnespace"
Only the terminal argument is required. The terminal argument can be an expression whose value is the name of a terminal device. Zero (0) is the process's principal device. $IO is the current device. The maximum length of terminal is 256 characters for Windows and UNIX®, 245 characters for OpenVMS.
Arguments are separated by colons (:). If you omit an argument within the list, you must specify the colon as placeholder. However, trailing colons are not permitted; you must not end either the command or its parameter list with a colon.
The optional parameter list is enclosed in parentheses and can contain the following optional parameters:
You can specify these optional parameters as either positional parameters (in the order shown), or as keyword parameters with the syntax /KEYWORD=value. Keyword parameters may be specified in any order; because Caché executes parameters in left-to-right order, interactions between parameters may dictate a preferred order in some cases. You can mix positional parameters and keyword parameters in the same parameter list. The enclosing parentheses are required if you specify more than one parameter.
The following parameter lists are equivalent:
   OPEN $IO:(80:"BFU":$CHAR(13)) 
    ; all positional
   OPEN $IO:(80::$CHAR(13):/PARAMS="BFU") 
    ; mixed positional and keyword, using the /PARAMS keyword
    ; to specify a protocol letter code string.
   OPEN $IO:(/MARGIN=80:/TERMINATOR=$CHAR(13):/BREAK:/FLUSH:/UPCASE)
    ; all keyword, using separate keywords 
    ; for each protocol letter code.
Following the parameter list (or a placeholder colon, if no parameter list is specified), you can specify an optional timeout in seconds, and a mnespace argument to specify the routine that contains the control mnemonics for this device.
For more information, see OPEN in the Caché ObjectScript Language Reference.
USE Command
Makes the specified terminal the current device. In programmer mode, all subsequent I/O commands on the same line of code refer to that device. In application mode, the device you name in a USE command remains the current device until the next USE command.
USE Syntax
The USE command takes the following arguments:
USE terminal:(margin:protocols:terminator):"mnespace"
The terminal argument can be an expression whose value is the name of a terminal device. Zero (0) is the process's principal device. $IO is the current device. The maximum length of terminal is 256 characters for Windows and UNIX®, 245 characters for OpenVMS.
Arguments are separated by colons (:). If you omit an argument, you must specify the colon. You must not end either the command or its parameter list with a colon.
The optional parameter list is enclosed in parentheses and can contain the margin, protocols, and terminator parameters. You can specify the optional margin, protocols, and terminator parameters as either positional parameters (in the order shown), or as keyword parameters with the syntax /KEYWORD=value. Keyword parameters may be specified in any order; because Caché executes parameters in left-to-right order, interactions between parameters may dictate a preferred order in some cases. You can mix positional parameters and keyword parameters in the same parameter list. The enclosing parentheses are required if you specify more than one parameter.
To specify COM port state and baud rate with the USE command, use the appropriate keyword parameters.
Following the parameter list (or a placeholder colon, if no parameter list is specified), you can specify an optional mnespace argument, which identifies a Caché ObjectScript routine where control mnemonics for use with WRITE /mnemonic are defined.
For more information, see USE in the Caché ObjectScript Language Reference.
Positional Parameters for OPEN and USE Commands
The following positional parameters are available for the OPEN and USE commands. You can set these parameters for a device in either the OPEN or USE command, or take the defaults configured in the Management Portal. These parameters are positional; if you omit a parameter, you must include its preceding colon as a placeholder.
margin
The 1st positional parameter: An integer value specifying the right margin (and thus the number of characters per line). Values from 1 to 255 set the right margin for output; any other value disables the right margin. An empty string leaves the margin setting unchanged. On Windows platforms, you cannot use “:n” to control the print margin used. Such notation is ignored by Caché. Code such as “|PRN| :121” is ignored. To control the printer width, send the appropriate control characters for that printer. The notation does work on other platforms.
The default margins for various terminal types are defined in the Management Portal. Select [Home] > [Configuration] > [Device Settings] > [SubTypes]. When you click on “Edit” for each listed device sub-type, it displays a Right Margin: default option.
protocols
The 2nd positional parameter: A string of letter code characters enclosed in quotation marks (for example, "BNFU”), where each letter enables one of the terminal's rules for communicating. Letter codes are not case sensitive. Letter codes may be specified in any order; because Caché executes them in left-to-right order, interactions between letter codes may dictate a preferred order in some cases. For a table of letter codes, see Letter Code Protocols.
A preceding plus or minus affects protocols as follows:
The + and – options for turning protocols on and off are not available in DSM-11 or DSM for OpenVMS compatibility modes.
terminator
The 3rd positional parameter: A string of up to eight characters, any of which will terminate a READ. These terminators are in addition to those built into the protocols. See Using Terminators to End I/O Operations.
portstate
The 4th positional parameter: A string of up to eight bytes in positional order that govern the COM port state. The portstate bytes are as follows (bytes are numbered from 1 in left-to-right order):
Byte Meaning Values
1 Disconnect D=disconnect (hangup) the port. blank=don't disconnect the port.
2 Modem Control 1=use modem control. 0=don't use modem control. blank=no change to modem control.
3 Data Bits 5=five data bits. 6=six data bits. 7=seven data bits. 8=eight data bits. blank=no change to data bit setting.
4 Parity 0=no parity. 1=odd parity. 2=even parity. 3=mark parity. 4=space parity. blank=no change to parity setting.
5 Stop Bits 1=one stop bit. 5=1.5 stop bits. 2=two stop bits. blank=no change to stop bit setting.
6 Flow Control X=use Xon/Xoff flow control. C=use CTS/RTS flow control. D=use DSR/DTR flow control. N=disable flow control. blank=no change to flow control.
7 DTR Setting 0=disable DTR (set it off, keep it off). 1=enable DTR (set it on, keep it on). blank=no change to DTR state.
8 $ZA Error Reporting 0=disable $ZA error reporting (default). 1=enable $ZA error reporting. blank=no change to $ZA error reporting.
The following example shows a COM port state string:
  OPEN "COM2":(:::" 0801x0")
The string values are: blank (don't disconnect the port); 0 (don't use modem control); 8 (eight data bits); 0 (no parity); 1 (one stop bit); X (use Xon/Xoff flow control); 0 (disable DTR); default (disable $ZA error reporting).
The Disconnect parameter performs a hangup on modem-controlled ports by lowering the DTR signal for two seconds and then restoring it. A disconnect does not close the port; following a disconnect you can dial out again without reopening the COM device.
The Modem Control parameter determines how Caché responds to the state of the RLSD (Received Line Signal Detector) pin, also known as the DCD (Data Carrier Detect). If the line is modem controlled (modem control=1), Caché monitors the state of the RLSD, and generates an <ENDOFFILE> error if a READ command is issued when carrier is not present. Caché does not generate an error when a WRITE command is issued when carrier is not present. This is because it must be possible to send the dial command to the modem prior to a connection being established. Caché modem control can be enabled (1) or disabled (0) at any time. It is suggested that you disable modem control while sending commands to the modem, then enable modem control once carrier is detected and connection has been established.
The DTR Setting parameter is used to control login from an attached modem. If the DTR setting is 0 (zero), the DTR control signal is off, and modems cannot communicate with the computer. This prevents a dial-in connection from occurring. If the DTR setting is 1 (one), the DTR control signal is on, and modems can communicate with the computer. A dial-in connection can occur. If you configure DTR as off (0), then you must set it to on (1) with the OPEN command or USE command to be able to dial out using a connected modem. In most cases, the DTR setting is unimportant when using a null modem cable to connect directly to a terminal device or a serial printer. This is because the null modem cable should force the DTR control pin on.
The $ZA Error Reporting parameter enables reporting of the status of modem control pins to the $ZA special variable. This checking can be done regardless of the Modem Control byte setting for the COM port. If $ZA error reporting is enabled, COM port errors are cleared with a call to the Windows ClearCommError() function. The port error state is reported in the $ZA bits 16 through 22. For a table of $ZA bit values, refer to $ZA in the Caché ObjectScript Reference.
baud
The 5th positional parameter: an integer value that specifies the desired COM port baud rate. The following baud rates are supported: 110, 300, 600, 1200, 4800, 9600, 14400, 19200, 38400, 56000, 57600, 115200, 128000, 256000.
Keyword Parameters for OPEN and USE Commands
The following table describes the keyword parameters for controlling terminal devices with both OPEN and USE commands. For each keyword, the table lists the corresponding Letter Code Protocols for OPEN and USE. Additional information on the use of these protocols can be found in the Letter Code Protocols table.
OPEN and USE Keyword Parameters for Terminal Devices
Keyword Default Letter Code Protocols Description
/BAUD=n     Corresponds to the baud positional parameter. /BAUD=n sets the modem baud rate for a COM port. Supported values are 110, 300, 600, 1200, 4800, 9600, 14400, 19200, 38400, 56000, 57600, 115200, 128000, 256000.
/BREAK[=n]
/BRE[=n]
0 B /BREAK or /BREAK=n for nonzero values of n enable the protocol. /BREAK=n for a zero value of n disables the protocol.
/COMPARAMS=str     Corresponds to the portstate positional parameter. (This keyword provides a way to specify a COM port state byte code string in a position-independent way.) The portstate byte codes that you can include in str, are listed in a table in earlier in this chapter.
/CRT[=n] Depends on the operating system terminal setting C and P Associated with the C and P protocols. /CRT or /CRT=n for nonzero values of n enable the C protocol and disable the P protocol. /CRT=n for a zero value of n disables the C protocol and enables the P protocol.
/DISCONNECT     Corresponds to 1st byte of the portstate positional parameter. /DISCONNECT disconnects (hangs up) the COM port. It does not close the port; you can dial out again without reopening the COM device.
/ECHO[=n] 1 S /ECHO or /ECHO=n for nonzero values of n disable the protocol. /ECHO=n for a zero value of n enables the protocol.
/EDIT[=n] 0 R and N /EDIT or /EDIT=n for nonzero values of n enable the R protocol and disable the N protocol. /EDIT=n for a zero value of n disables the R protocol and enables the N protocol.
/FLUSH[=n]
/FLU[=n]
0 F /FLUSH or /FLUSH=n for nonzero values of n enable the protocol. /FLUSH=n for a zero value of n disables the protocol.
/GZIP[=n] 1   Specifies GZIP-compatible stream data compression. /GZIP or /GZIP=n (for nonzero values of n) enables compression on WRITE and decompression on READ. /GZIP=0 disables compression and decompression. Before issuing /GZIP=0 to disable compression and decompression, check the $ZEOS special variable to make sure that a stream data read is not in progress. /GZIP compression has no effect on I/O translation, such as translation established using /IOTABLE. This is because compression is applied after all other translation (except encryption) and decompression is applied before all other translation (except encryption).
/IMAGE[=n]
/IMA[=n]
0 I /IMAGE or /IMAGE=n for nonzero values of n enable the protocol. /IMAGE=n for a zero value of n disables the protocol.
/IOTABLE[=name]
/IOT[=name]
If name is not specified, the default I/O translation table for the device is used.   Corresponds to the K\name\ protocol, which establishes an I/O translation table for the device.
/MARGIN=n
/MAR=n
0 (no margin)   Corresponds to the margin positional parameter, which sets the right margin for the terminal device.
/MODE=n No default  
Resets protocols and sets the terminal mode according to the value of n.
n=0 sets CR and ESC as default terminators on OpenVMS platforms or LF and ESC as default terminators on non-OpenVMS platforms.
n=1 is the same as mode 0 and enables the S protocol (on OpenVMS platforms it also enables the I protocol if the terminal is a print device).
n=2 is the same as mode 0 and enables the T protocol.
/NOXY [=n] 0   No $X and $Y processing: /NOXY or /NOXY=n (for nonzero values of n) disables $X and $Y processing. This can substantially improve performance of READ and WRITE operations. The values of the $X and $Y variables are indeterminate, and margin processing (which depends on $X) is disabled. /NOXY=0 enables $X and $Y processing; this is the default.
/OBUFSIZE=nnn 256   Specifies the size of the terminal output buffer in bytes. Increasing the output buffer size can improve performance of screen painting with telnet over wide area networks with high latency. Valid values for /OBUFSIZE are 256 through 65536. The default is 256.
/PARAMS=str
/PAR=str
No default   Corresponds to the protocols positional parameter. (This keyword provides a way to specify a protocols letter code string in a position-independent way.) For a table of letter codes that you can include in str, see Letter Code Protocols.
/TERMINATOR=str
/TER=str
No default   Corresponds to the terminator positional parameter, which establishes user-defined terminators. To compose str, see Using Terminators to End I/O Operations.
/TPROTOCOL[=n]
/TPR[=n]
0 T /TPROTOCOL or /TPROTOCOL=n for nonzero values of n enable the protocol. /TPROTOCOL=n for a zero value of n disables the protocol.
/TRANSLATE[=n]
/TRA[=n]
1 K /TRANSLATE or /TRANSLATE=n for nonzero values of n enable I/O translation for the device. /TRANSLATE=n for a zero value of n disables I/O translation for the device.
/UPCASE[=n]
/UPC[=n]
0 U /UPCASE or /UPCASE=n for nonzero values of n enable the protocol. /UPCASE=n for a zero value of n disables the protocol.
/XYTABLE[=name]
/XYT[=name]
If name is not specified, the default $X/$Y action table for the device is used. Y\name\ Corresponds to the Y\name\ protocol, which establishes a $X/$Y action table for the device.
Testing the Success of OPEN Commands
To determine whether an OPEN command succeeded, your code should test $TEST and/or $ZE. $TEST is only set if the OPEN command was specified with a timeout argument. A <NOTOPEN> error occurs only when Ctrl-C interrupts an OPEN command. Therefore, your code must not depend on <NOTOPEN> errors.
Letter Code Protocols for OPEN and USE
Special situations or terminals can require different protocols. With the protocols letter code parameter (or the corresponding keyword parameters) you can change the rules by which Caché communicates with the terminal. Protocols affect normal and single-character reads alike.
Normal mode, with all special protocols disabled, suffices for most terminal I/O. In normal mode Caché echoes each incoming ASCII character, sending it back to appear on the terminal. A Return, or a valid escape sequence, ends a READ command.
Issuing OPEN for a terminal turns off all previous protocols, except when you use the + and - options.
The following table describes valid protocols characters and their effects.
Letter Code Protocols for OPEN and USE
Protocol Character Name Definition
B BREAK
If breaks are enabled (+B), Ctrl-C interrupts a running routine with an <INTERRUPT> error. If breaks are disabled (-B), Ctrl-C does not cause an interrupt and “^C” is not displayed. The use of this protocol is dependent upon the BREAK command default established by the login mode, as follows:
If you log in as programmer mode, interrupts are always enabled (BREAK 1). The B (or /BREAK) protocol specified in an OPEN or USE command has no effect.
If you log in as application mode, BREAK 0 is the default, and interrupts can be enabled or disabled by the B (or /BREAK) protocol specified in the OPEN or USE command.
C CRT terminal C mode accepts all eight bit characters as data, except for the following six: ASCII 3, 8, 10, 13, 21, and 127. The ASCII 127 Delete character echoes as a destructive backspace, that is, it backspaces and erases the preceding character. ASCII 21 (Ctrl-U) echoes enough destructive backspaces to bring the cursor to the start of the READ. If the setting for the right margin, or the nature of the terminal, forces echoed characters to begin a new line, Ctrl-U can erase only the characters on the last physical line. In any case, Ctrl-U cancels all input since the start of the READ. C is mutually exclusive with the P protocol.
F Flush Flush (empty) the input buffer before each READ. You can flush the input buffer to prohibit the user from typing ahead of READ operations on the terminal, because Caché discards anything typed between READ operations. Note that the command WRITE *–1 flushes the input buffer at any time, regardless of the F protocol.
I Image mode
I mode accepts all 256 eight bit characters as data, treating none as a READ terminator, except the termination character(s) (if any) that you explicitly specify in the terminator parameter. If you do not explicitly specify termination characters, you should use only single character and fixed length READ operations. Without defined termination characters, an ordinary READ results in a <TERMINATOR> error.
Image mode (I) protocol can be combined with other protocol characters. In image mode, Caché ignores the protocol characters P, C and B. In image mode, the protocol characters F, N, R, S, and T remain in effect. When not in image mode, the device is in N (normal) mode.
K\name\
Knum
I/O Translation Mode When you use the K protocol for a device, I/O translation will occur for that device if translation has been enabled system-wide. You identify the previously defined table on which the translation is based by specifying the table's name. (The older form Knum, where “num” represents the number of the slot the table is loaded in, is being phased out but is still supported.)
N Normal mode N mode accepts all eight bit characters as data, except for the following six: ASCII 3, 8, 10, 13, 21, and 127. These implicit terminator and command line editing control characters, are described later in this chapter. If R (read line recall) protocol is enabled, N disables R protocol. This mode is the default if no protocols value is specified.
P Print device The ASCII Delete character echoes as a backslash (\), and Ctrl-U echoes as “^U” followed by a carriage return and line feed. When you issue an OPEN command for a terminal, Caché invokes the protocol C or P automatically, depending on the operating system terminal setting. These protocols remain in effect until you change the protocols for the device explicitly. A protocol string containing neither C nor P does not cancel this protocol.
R Enable read line recall mode The R protocol enables read line recall mode for that device. To activate read line recall for the current process, use the LineRecall() method of the %SYSTEM.Process class. To set the system-wide read line recall default, use the LineRecall property of the Config.Miscellaneous class. The R protocol overrides these default settings for the specified device. To change read line recall for an already-open device, you must explicitly specify another OPEN command to that device. Read line recall is disabled by specifying the N protocol.
S Secret input Nothing echoes on a READ. READ commands do not change $X and $Y. Read line recall is disabled.
T Terminator
T mode does not treat any control characters as data. The following are control characters: ASCII characters with decimal values from 0 to 31 and 127 to 159. Most of these control characters are treated as READ terminator characters. The exceptions are the following control characters, which perform other control operations: ASCII 3 (Ctrl-C), ASCII 8 (backspace), ASCII 17 (Ctrl-Q), ASCII 19 (Ctrl-S), ASCII 21 (Ctrl-U), ASCII 24 (Ctrl-X), ASCII 27 (ESC), and ASCII 127 (DEL).
When T mode is combined with I mode (IT protocol) all control characters (ASCII 0 to 31 and 127 to 159) are treated as READ terminator characters, with the exceptions of the output control characters Ctrl-Q (XOFF), and Ctrl-S (XON), and the input control characters Ctrl-H and Ctrl-Y. Output control characters Ctrl-Q and Ctrl-S are intercepted by most terminals and do not terminate a READ even in IT mode.
U Upcase mode U mode converts all input letters to upper case.
Y\name\
Ynum
$X/$Y Action Mode When you use the Y protocol for a device, the system uses the named $X/$Y Action Table. You identify a previously defined $X/$Y Action Table on used to translate by specifying the table name. If you don't know it, you can get the name from the system manager. $X/$Y action is always enabled. If Y is not specified and a system default $X/$Y is not defined, a built in $X/$Y action table is used. The + option works for turning on the Y protocol, but the - option does not. In order to disable a $X/$Y association, you can issue the command: USE 0:(:"Y0") (The older form Ynum, where num represents the number of the slot the table is loaded in, is being phased out but is still supported.)
Examples of Protocol Strings
The following series of examples show how protocol strings function. Each of the following USE commands builds on the protocol established by the preceding USE commands:
   USE 0:(80:"BP" )
The letter codes BP turn on the B and P protocols. This example enables breaks (B) and tells Caché to treat the terminal as a printing device (P).
   USE 0:(80:"P")
When it follows the USE command in the example just above, this command leaves the P protocol in effect, but turns off the B protocol.
   USE 0:(80:"+R" )
+R turns on read line recall, without affecting other protocol settings.
   USE 0:(80:"")
The empty string turns off all protocols. However, the P or C protocol remains in effect.
   USE 0:(80)
Omitting the protocol parameter leaves the protocol and explicit terminators unchanged.
Protocol Terminator Characters
OPEN and USE protocols define what READ input characters, control sequences, and keystrokes are treated as implicit terminator characters. These four protocols are I (image mode), N (normal mode (the default)), R (read line recall mode), and T (terminator mode):
In any of these modes you can explicitly specify additional terminator characters using the terminator parameter. Because image mode is commonly used for bit stream data, designation of any character as a terminator is usually avoided.
Explicit Terminator Characters
The terminator parameter in the OPEN or USE command lets you define specific characters as terminators for a READ or WRITE command. These explicit terminators can be used to supplement the terminator characters supplied by the specified protocol. The terminator parameter can also be used to override the designation of a character by the protocol, and instead designate it a terminator character. The exceptions to this ability to redefine a character as a terminator are: ASCII 0 (NULL), ASCII 3 (Ctrl-C), and the two output control characters Ctrl-Q (XON) and Ctrl-S (XOFF). These retain their functionality, and cannot be redefined as terminator characters.
Example
This example defines Z, Backspace and Tab as terminators for the principal device. The underscore is the concatenate operator.
  USE 0:("":"":"Z"_$CHAR(8,9))
By issuing an OPEN command for an unowned terminal, you implicitly clear the Caché internal list of explicit terminators. When a protocol string appears, Caché then does the following:
  1. Clears its list of explicit terminators.
  2. Sets protocols according to the protocol string.
  3. Copies a terminator string, if any, into the internal list of explicit terminators.
    The following table gives examples of explicit terminator strings.
Terminator Strings: Examples
Terminator String Definition
USE 0:(80:"C":$CHAR(27)) The Escape character terminates a READ rather than beginning an escape sequence.
USE 0:(80:"C":"") The empty string clears all terminators.
USE 0:(80:"C") Omitting the terminator parameter when you specify protocol clears all terminators.
USE 0:(80) or U 0:80 Omitting both protocol and terminator leaves terminators unchanged.
Summary of Protocols and Terminators in Read Operations
The following characters end a normal (nonimage) mode READ:
The following characters end an image-mode READ:
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 Caché 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.
Caché supports read line recall for both variable-length terminal reads (READ variable) and fixed-length terminal reads (READ variable#length). Caché 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 (OpenVMS or UNIX®) or key combinations (such as CTR-ALT-DEL on Windows platforms), preventing these characters from affecting Caché. 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 Caché 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 Caché 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 Caché 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 the OpenVMS or UNIX® 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. On OpenVMS, Caché does not echo the characters of the sequence, and it does not change $X and $Y. On UNIX® and Windows, Caché 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 in this chapter. 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 Caché 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 Caché can cause serious problems. For this reason, Caché disables Ctrl-Z automatically when you enter Caché on platforms whose UNIX® shell supports job control. Caché reenables Ctrl-Z when you exit Caché, 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
WRITE Command
Writes zero or more characters to the terminal.
Syntax
WRITE *variable
WRITE *-n
WRITE #
WRITE /mnemonic
where
Argument Definition
(none) WRITE with no arguments writes all local variables on the current device.
*variable WRITE *variable writes one character, whose decimal value equals x. The value of variable should be an integer in the range 0 to 255 for ASCII characters, and >255 for Unicode characters. By convention, values from 0 to 127 signify 7 bit ASCII characters, while 128 to 255, which represent the extended ASCII character set, relate to the application itself. If the hardware and software are properly set, Caché can handle 8 bit data. Example : You can use the eighth bit to represent international character sets. Caché routines often use WRITE * to send control characters for device dependent functions. Example : WRITE *27,*91,*50,*74 clears the terminal screen. WRITE * does not change $X or $Y; the assumption is that WRITE * output is highly specific to the output device.
*-1
WRITE *-1 clears the input buffer when the next READ is issued. It clears any characters that are pending for the next READ command. Thus all type-ahead characters are cleared.
An input buffer holds characters as they arrive from the keyboard, even those you type before the routine executes a READ command. Thus you can answer questions even before they appear on the screen. When the READ command takes characters from the buffer, Caché echoes them back to the terminal so that questions and answers appear together. When a routine detects errors, it may issue WRITE *-1 to cancel these answers.
*-10
WRITE *-10 clears the input buffer immediately. It does not wait for the next READ command. Thus it clears all type-ahead characters issued before the WRITE *-10; type-ahead characters issed after the WRITE *-10 remain in the input buffer for use by the next READ.
# Issuing WRITE # to a CRT terminal clears the screen and sends the cursor to the home (0,0) position. For a hardcopy terminal, it writes a Carriage Return and Form Feed. WRITE # sets $Y to 0.
/mnemonic Issuing WRITE /mnemonic causes Caché to interpret mnemonic as defined in the active mnemonic space. If there is no active mnemonic space, an error results. You can specify the active mnemonic space in two ways: By naming a default mnemonic space for each device type using the Namespace and Network Configuration editor by specifying a mnemonic space in the OPEN or USE command for the device. For more information, see Controlling Devices with Mnemonic Spaces.
For more information, see WRITE in the Caché ObjectScript Language Reference.
Examples
In the following example, WRITE * rings the bell on the user's terminal, displays a prompt, and clears the input buffer of any characters received but not yet used.
   SET eek="No. I can't accept that reply" 
   WRITE *7,eek,*-10
 
The following two examples show the difference between WRITE *-1 and WRITE *-10. In both cases, the user responds to the first READ and presses ENTER, then types ahead during the two pauses caused by the HANG commands:
  READ "type:",x HANG 4 WRITE *-1 HANG 4 READ "type:",y
In the above example, Caché clears the input buffer when the second READ is issued. Thus any text typed during either HANG is cleared from the buffer.
  READ "type:",x HANG 4 WRITE *-10 HANG 4 READ "type:",y
In the above example, Caché immediately clears the input buffer when WRITE *-10 is issued. Thus any text typed during the first HANG is cleared, but any text typed during the second HANG is supplied to the second READ command.
In the following example, WRITE /mnemonic uses the control mnemonic CUP (CUrsor Position) to move the cursor to the third column of the fourth line on the terminal. In this example, the predefined mnemonic space ^%X364 is specified in the USE command, and the name of an open terminal device is specified using the terminal variable. See Predefined Mnemonic Spaces for Terminals for a description of ^%X364.
   USE terminal:(80:"BP"):"%X364"
   SET %1=3,%2=4
   WRITE /CUP(%1,%2)
CLOSE Command
Releases ownership of the device, which is gained with an OPEN command.
Syntax
CLOSE device
For more information, see CLOSE in the Caché ObjectScript Language Reference.
Predefined Mnemonic Spaces for Terminals
Caché provides two predefined mnemonic spaces for use with terminals:
If you make one of these mnemonic spaces active, you can use the control mnemonics associated with them in WRITE /mnemonic commands. You can also create your own mnemonic spaces. See Controlling Devices with Mnemonic Spaces in the chapter Terminal I/O for more information on mnemonic spaces.
The following sections describe the control mnemonics for these mnemonic spaces.
Mnemonic Space for X3.64
Caché provides a built-in mnemonic space for the ANSI X3.64 definition. This mnemonic space is the Caché routine %X364 in the manager's namespace. To use routine %X364, either:
The following table lists the mnemonics.
Control Mnemonics for %X364 Mnemonic Space
Calling Sequence Name System Variable Affected
APC Application Program Command
BEL Ring the bell
CBT(%1) Cursor Backward Tabulation $X
CCH Cancel Character
CHA(%1) Cursor Horizontal Absolute $X
CHT(%1) Cursor Horizontal Tabulation $X
CNL(%1) Cursor Next Line $X,$Y
CPL(%1) Cursor Preceding Line $X,$Y
CPR Cursor Position Report
CTC(%1,%2,%3,%4, %5,%6,%7,%8,%9) Cursor Tabulation Control
CUB(%1) Cursor Backward $X
CUD(%1) Cursor Down $Y
CUF(%1) Cursor Forward $X
CUP(%1,%2) Cursor Position $X, $Y
CUU(%1) Cursor Up $Y
CVT(%1) Cursor Vertical Tabulation $Y
DA Device Attributes
DAQ(%1,%2,%3,%4, %5,%6,%7,%8,%9) Define Area Qualification
DCH(%1) Delete Characters
DCS Device Control String
DL(%1) Delete Lines
DMI Disable Manual Input
DSR(%1) Device Status Report
EA(%1) Erase in Area
ECH(%1) Erase Characters
ED(%1) Erase in Display
EF(%1) Erase in Field
EL(%1) Erase in Line
EMI Enable Manual Input
EPA End of Protected Area
ESA End of Selected Area
FNT Font Selection
GSM Graphic Size Modification
GSS Graphic Size Selection
HPA(%1) Horizontal Position Attribute $X
HPR(%1) Horizontal Position Relative $X
HTJ Horizontal Tab with Justify $X
HTS Horizontal Tab Set $X
HVP(%1,%2) Horizontal and vertical position $X, $Y
ICH(%1) Insert Characters
IL(%1) Insert Lines
IND Index $Y
INT Interrupt
JFY Justify
MC Media Copy
MW Message Waiting
NEL Next Line $X, $Y
NP(%1) Next Page
OSC Operating System Command
PLD Partial Line Down $Y
PLU Partial Line Up $Y
PM Privacy Message
PP(%1) Preceding Page
PU1 Private Use 1
PU2 Private Use 2
QUAD QUAD
REP(%1) REPEAT $X, $Y
RI Reverse Index $Y
RIS Reset to Initial State $X=0 $Y=0
RM(%1,%2,%3,%4,% 5,%6,%7,%8,%9) Reset Mode
SEM Select Editing Extent Mode
SGR(%1,%2,%3,%4, %5,%6,%7,%8,%9) Select Graphic Rendition
SL Scroll Left
SM(%1,%2,%3,%4,% 5,%6,%7,%8,%9) Set Mode
SPA Start of Protected Area
SPI Spacing Increment
SR Scroll Right
SS2 Single Shift Two
SS3 Single Shift Three
SSA Start of Selected Area
ST String Terminator
STS Set Transmit State
SU Scroll Up
TBC Tabulation Clear
TSS Thin Space Specification
VPA(%1) Vertical Position Attribute $Y
VPR(%1) Vertical Position Relative $Y
VTS Vertical Tab Set
Mnemonic Space for DTM PC Console
Caché provides the Caché routine %XDTM to match the mnemonics used in developing applications for DTM. This mnemonic space is available but is not set up as the default mnemonic space for terminals. If you port applications created for DTM to Caché, you can either:
DTM Examples
OpenVMS
  OPEN "TTA1:"::"^%XDTM"
UNIX®
  OPEN "/dev/tty04/"::"^%XDTM"
Windows
  OPEN "c:\sys\user"::"^%XDTM"
Then Caché can correctly interpret the DTM control mnemonics in WRITE /mnemonic commands, shown in the following table.
Control Mnemonics for DTM PC Console
Mnemonic Description
AA Normal mode
AB Bold mode
AC Underlined mode
AD Bold, underlined mode
AE Reverse video
AF Reverse video/Bold mode
AG Reverse video/Underline mode
AH Reverse video/Bold, underlined mode
AI Blink mode
AJ Bold, blink mode
AK Underlined, blink mode
AL Bold, underlined, blink mode
AM Reverse video / Bold, blink mode
AN Reverse video / Bold, blink mode
AO Reverse video / Underlined, blink modes
AP Reverse video / Bold, underlined, blink modes
AZ Mode Z
B(%1,%2) Set video attributes: %1 provides attribute for characters, %2 provides attribute for clearing frames
BOX Draw a window-relative utility box
C(%1,%2) Position cursor at column %1, line %2
CLR Clear current frame
COLOR(%1,%2) Set IBM PC Color: Foreground %1, Background %2
DC(%1) Delete %1 characters
EC(%1) Erase %1 characters
EF Erase to end of frame
EL Erase to end of line
F(%1,%2,%3, %4,%5) Fill rectangular area with $CHAR(%1) at upper left corner, %4 columns wide by %5 lines high
GETCUR Return terminal cursor position
HF Screen half bright off
HIDECURSOR Hide mouse cursor
HN Screen half bright
IC(%1) Insert %1 characters
LF Disable literal mode
LN Enable literal mode, which displays control characters graphically on a PC screen.
MARK(%1) Make mark on screen
NORM Enable normal display attributes
PAD(%1) Write %1 NULLS for padding
PF Pause off
PN Pause on
RF Screen reverse video off
RN Screen reverse video
SD(%1,%2,%3) Scroll current frame down by %3 lines
SHOWCURSOR Show mouse cursor
SU(%1,%2,%3) Scroll current frame up by %3 lines, starting at line %1 down to but not including line %2
VF Visible cursor off
VN Visible cursor on
WBOX Draw a screen-relative utility box
WCLOSE Close utility window
WINDOW Set scrolling window
WOPEN Open utility window
Y(%1) Set binary frame attribute
PRINT and ZPRINT Commands
Writes one or more lines of the currently loaded Caché routine to the current device.
ZPRINT has the same effect and arguments as PRINT.
Syntax
PRINT
ZPRINT
PRINT x
ZPRINT x
PRINT x:y
ZPRINT x:y
where
Argument Definition
(none) The PRINT or ZPRINT command with no arguments prints the entire routine.
x,y The variables x and y indicate the range of lines to print. They can be either a line reference of the form TAG+OFFSET, or a line number of the form +7. Referring to a line not in the routine implies the empty line following the routine's last line. x = First or only line to print. y = Last line to print.
For more information, see PRINT in the Caché ObjectScript Language Reference.
Example
This example prints the first line of the current routine, four lines starting at INIT, and all the lines from FINI to the end:
INIT
  SET a=1
  SET b=2
  SET c=3
  SET d=4
FINI
  SET x=24
  SET y=25
  SET z=26
  PRINT +1,INIT:INIT+3,FINI:+9999
Programming Your Terminal
Using Caché to Program Formatted CRT Screens
Several features of Caché terminal I/O aid in programming formatted screens:
Fixed-length READ and programmer-specified termination characters make it convenient to read individual fields. You can use the Secret protocol to make passwords invisible.
Remember that WRITE * does not change $X or $Y. If you want to change them, use WRITE $C(X), or simply set them explicitly.
Example
This example sets the VT100 cursor to line 10, column 20
%SYS>SET DY=10,DX=20
%SYS>WRITE *27,*91,DY+1,*59,DX+1,*72 SET $Y=DY,$X=DX
Use CURRENT^%IS to Set Variables
The utility routine CURRENT^%IS sets some useful local variables to work for the current device. To call this routine, enter:
%SYS>DO CURRENT^%IS
This command sets the variables indicated in the following table.
Features Enabled By CURRENT^%IS
Code Definition
W @FF Clears the screen and moves the cursor to the upper left corner (column 0, line 0) leaving $X=0, $Y=0.
S DX=42,DY=10 X XY Moves the cursor directly to column 42, line 10, leaving $X=42, $Y=10.
Programming Escape Sequences
The ANSI standard for escape sequences makes programming of smart terminals practical.
For Windows and UNIX® Systems, the Escape character and all characters after it in a string do not display on the screen, but do update $X and $Y. Send escape sequences to the terminal with WRITE * statements and keep $X and $Y up to date by setting them directly.
For OpenVMS systems, the Escape character and all characters after it in a string do not display on the screen and do not update $X and $Y.
The ANSI standard establishes a standard syntax for escape sequences. The effect of a particular escape sequence depends on the type of terminal you are using.
Look for incoming escape sequences in $ZB after each READ. Caché puts ANSI-standard escape sequences and any others that use the ANSI forms in $ZB. Caché recognizes two forms of escape sequence:
Regular form
Control form
Furthermore, the sequence can be no longer than 16 characters. Escape sequences that violate these forms or rules set bit 8 of $ZA, whose value is 256.
Example
Assume that you are programming a terminal whose Help key sends the two-character sequence Escape-? (? has a decimal value of 63)
%SYS>SET HELP=$C(27,63)
ASK READ !,"Enter ID: ",X I $ZB=HELP Do GIVEHELP GoTo ASK
Your routine can detect nonstandard escape sequences as follows:
  1. Make ESC a terminator.
  2. When ESC appears in $ZB:
    1. Disable echo with the Secret protocol to prevent modification of $X/$Y.
    2. Read the rest of the sequence with READ *;
    3. Turn off Secret to re-enable echo.
      In the following figure, the user is asked to enter an ID. If the user presses Esc-?, a Help screen appears. The subroutine ESCSEQ assumes that nonstandard escape sequences end with an asterisk “*”.
DEMOS 
  SET HELP=$C(27,63) ;Get Help with <ESC>?
    SET ESC=$C(27) USE 0:("":"":ESC) ; Make <ESC> a READ terminator
                                     ; character
ASK READ !,"Enter ID: ",X I $ZB=ESC Do ESCSEQ G:SEQ=HELP ASK 
    . ;Input ID. Handle Help request. 
    .
    Quit
HELPSCR  ;Process Help request 
    . 
    Quit
ESCSEQ  USE 0:("":"S") SET SEQ=ESC ;Set terminal to no echo,init SEQ 
    FOR I=1:1 {
      READ *Y 
      SET SEQ=SEQ_$C(Y)
      QUIT:Y=42 }
    ; Read in Escape sequence, 
    ; end at "*" 
    USE 0:("":"":ESC) Quit ;Redefine terminator
Caché Supports Full or Half Duplex and Echo
Caché prefers that you use full duplex terminals; in other words, your keyboard should operate independently from your printer or screen.
Full duplex means simultaneous and independent transmission in both directions. Half duplex means transmission in only one direction at a time. Duplex has nothing to do with echo, although you may see a terminal marked full duplex for remote echo and half duplex for local echo. This designation means that the terminal displays the characters you type and does not expect Caché to echo them.
Set your terminal to local echo off or full duplex, letting Caché provide the echo. The echo comes not when the computer receives the character, but when the READ command takes it from the input buffer; therefore, the prompts and answers of a dialog keep their intended positions on the screen regardless of whether the user types ahead.
Some public networks provide their own echo to the terminal.
On Windows systems, consoles do not permit local echo setup changes. For terminals attached via a terminal emulator (e.g., VT220), refer to your terminal emulator documentation for instructions to disable local echo.
On UNIX® systems, use the stty command to avoid double echoes while keeping $X and $Y in agreement with the cursor's position.
On OpenVMS systems, use the OpenVMS SET TERMINAL command to avoid double echoes while keeping $X and $Y in agreement with the cursor's position.
Caché Supports Intercomputer Links and Special Devices
Caché provides flexible protocols and large independent buffers enable routines to deal with unusual devices and their protocols. For example, Caché easily supports full duplex communication between two computers on a terminal-to-terminal link. Two Caché systems require only a physical connection, the right protocols, and identical settings of speed, parity, and character length. With the aid of external converters, Caché communicates with IBM ports as a synchronous EBCDIC terminal.
Keep these points in mind when designing an intercomputer link: