Terminal I/O

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:

Enable or disable the echo of incoming characters.
Send and receive ANSI-standard escape sequences.
Control keyboard interruptions and program special user interactions, including formatted screens, reverse video, and special keys for skipping fields.
Enable and disable recognition of Ctrl-C interrupts.
Control the flow of incoming and outgoing data by XON (Ctrl-Q) and XOFF (Ctrl-S).
Specify COM port state parameters and modem baud rate.
Conform to foreign protocols when you specify your own set of termination characters.
Communicate with non-terminal devices, such as automated instruments.

Windows and UNIX systems differ in how they handle printer I/O. 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. UNIX systems always handle printers as terminal I/O devices.

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:

$IO contains the name of the current device.
$TEST contains a boolean value that shows whether the most recent timed operation was successful.
$X and $Y show the position of the cursor.
$ZA, $ZB, and $KEY show information about READ operations. $ZB and $KEY are similar, but not identical.

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 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. Two factors control this effect:

Your operating system, which sets the default behavior.
The functions $ZUTIL(68,22) and $ZUTIL(69,22), which you can use to alter this behavior at the process and system level, respectively.

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 one of the $ZUTIL functions that alters 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 a non-default method of updating $X for your process, issue $ZUTIL(68,22,n).

The system manager can alter the system-wide default method of updating $X by issuing $ZUTIL(69,22,n).

For both functions, n has a value from 0 through 4, as follows:

Value	Default Method of 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, READ, and CLOSE. The value of $TEST can be set to 1 or 0:

$TEST is set to 1 if the timed command succeeded before the timeout expired.
$TEST is set to 0 if the timeout expires on a timed command.

Note:

OPEN, READ, and CLOSE 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 chapter Error Processing in 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:

A termination character, such as a carriage return
An escape sequence
Character number y of a fixed-length READ x#y
The single character of READ *x
An empty string after a timed READ expires

$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:

margin is an integer that specifies the number of characters per line by specifying the right margin.
protocols is a string of letter codes that specifies terminal options.
terminator is a string of one or more characters that terminate a READ operation.
portstate is a string that specifies the COM port state.
baud is an integer that specifies the baud rate for a COM port.

You can specify these optional parameters as either positional parameters (in the order shown), or as keyword parameters (in any order) with the syntax /KEYWORD=value. 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 (in any order) with the syntax /KEYWORD=value. 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 System 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 System Management Portal. Go to System Configuration, Advanced Settings, Devices options and select the Subtypes option. When you click on “Edit” for each listed device sub-type, it displays a RightMargin: 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 and can be listed in any order. For a table of letter codes, see Letter Code Protocols.

A preceding plus or minus affects protocols as follows:

No preceding plus or minus: New string replaces prior protocol string.
Plus (+) precedes letter code string: Protocols in new string are added to prior protocol string.
Minus (-) precedes letter code string: Protocols in new string are turned off, but other protocols remain in effect.

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 protocol. 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] or /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] or /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.
/IMAGE[=n] or /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] or /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 or /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.
/PARAMS=str or /PAR=str	No default		Corresponds to the protocol positional parameter. (This keyword provides a way to specify a protocol 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 or /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] or /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] or /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] or /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] or /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.

The following table describes additional printer keyword parameters for controlling printers on UNIX systems with the OPEN command.

Additional OPEN Keyword Parameters for UNIX and Serial Printers

Keyword	Default	Description
/DOCNAME= “name”	“Cache”	/DOCNAME enables you to redefine the printer job name.
/OUTPUTFILE= “filename”	NULL	/OUTPUTFILE redirects print to a file. Specify a fully-qualified pathname.
/DATATYPE= “type”	“RAW”	/DATATYPE enables you to redefine the datatype of the printer spool data. One frequently-used datatype is TEXT.

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 protocol 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. With breaks disabled (-B), no interrupt occurs 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 (/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 (/break) protocol specified in the OPEN or USE command.
C	CRT terminal	The ASCII Delete character echoes as a destructive backspace, that is, it backspaces and erases the preceding character. 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	A device in image mode accepts all 256 eight bit characters, treating none as terminators except the termination characters that you explicitly specify. The exception to this is that the output control characters Ctrl-Q and Ctrl-S retain their functions even in image mode. In image mode, Caché ignores the protocol characters P, C and B; characters F, N, R, S, and T remain in effect When not in image mode, the device is in normal mode. In image mode, Caché recognizes only the termination characters specified with the T protocol or explicitly in the list of terminators (listed in following section). When you do not specify terminators, use only single character and fixed length READ operations; an ordinary READ results in a <TERMINATOR> error.
K\name\ or 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	Disable read line recall mode	The N protocol disables read line recall for a device. Read line recall is enabled by the R protocol.
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. You can set the default systemwide using $ZUTIL(69,11), and for the current process using $ZUTIL(68,11); 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	Any control character (ASCII characters with decimal values from 0 to 31, 127 to 160, and 224 to 255) terminates a READ, except that in normal (non image) mode the following control characters take precedence over terminator processing: Output control characters are Ctrl-C, Ctrl-Q, and Ctrl-S. Input control characters are Ctrl-H and Ctrl-Y. For example, under the IT protocol, Ctrl-Q terminates a READ, but under protocol T it resumes output suspended by Ctrl-S. You can use the terminator string to override the input control characters in other ways, so that you can use them as terminators. Output control characters Ctrl-Q and Ctrl-S are intercepted by most terminals and do not terminate a READ even in image mode.
Y\name\ or 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.

Image Mode Ignores Some Protocol Characters

On UNIX and Windows systems, Caché ignores the protocol characters P, C, and B when in image mode. Characters F, K, N, R, S, T, and Y remain in effect.

Using Terminators to End I/O Operations

The terminator parameter in the OPEN command lets you define specific characters as terminators to a READ command. These terminators apply in addition to those built into the protocol.

You can use any character except ASCII NUL, whose decimal value is 0. In normal (nonimage) mode, however, the characters reserved for input control, output control, and command line editing and recall, produce their own effects and do not end input or output operations.

See Letter Code Protocols for OPEN and USE for a complete list of control characters that you cannot use as terminators.

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:

Clears its list of explicit terminators.
Sets protocols according to the protocol string.
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
U 0:(80:"C":$CHAR(27))	The Escape character terminates a READ rather than beginning an escape sequence.
U 0:(80:"C":"")	The empty string clears all terminators.
U 0:(80:"C")	Omitting the terminator parameter when you specify protocol clears all terminators.
U 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:

Return
Any character in the terminator string except ASCII NUL and the characters Ctrl-C, Ctrl-O, Ctrl-Q, and Ctrl-S.
With the T protocol in effect, any control character except the output control characters. Control characters are nonprinting characters with decimal values 0 to 31, 127 to 160, and 224 to 255.
Any escape sequence.
Character number y of a fixed-length READ x#y.

The following characters end an image-mode READ:

Any character specified in the terminator string except ASCII NUL.
With the T protocol in effect, any control character.
Character number y of a fixed-length READ x#y.

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.

Input control characters affect input. Image mode 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.
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	Unless you have selected the T protocol, Tab echoes as a space, increases $X by one, and is returned as a Tab character in the string returned by the READ.

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 *-1
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	An input buffer holds characters as they arrive from the keyboard, even those you type before the routine executes a READ command. This method lets you 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 cancel these answers. WRITE *1 clears from the input buffer any characters that READ commands have not yet used.
#	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,*1

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. The predefined mnemonic space ^%X364 is specified in the OPEN command. See Pre-Defined Mnemonic Spaces for Terminals for a description of ^%X364.

   OPEN "|LAT|SERVER_1:PORT_3:":(80:"BP"):"%X364"
   USE "LAT|SERVER_1:PORT_3:"
   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.

Pre-Defined Mnemonic Spaces for Terminals

Caché provides two pre-defined mnemonic spaces for use with terminals:

^%X364 for ANSI X3.64 terminals
^%XDTM for DTM PC Console

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:

Have your Caché system manager enter %X364 as the default mnemonic space in the MnemonicTerminal configuration setting. From the System Management Portal, go to System Configuration, Advanced Settings, IO options.

Issue an OPEN command specifying this mnemonic space:

 OPEN "terminal"::"^%X364"

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:

Configure ^%XDTM as the default mnemonic space for terminals (MnemonicTerminal) in the System Management Portal, or
Reference the ^%XDTM mnemonic space in the OPEN or USE command.

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:

  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:

Use WRITE * to send control sequences easily.
Use READ to receive escape-sequence responses.
Use SET $X = expression and SET $Y = expression to update the current cursor position.

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

An ESC.
Optionally the character “O” (the letter), decimal value 79.
Zero or more characters with decimal values 3247.
One character with decimal value 48126.

Control form

An ESC.
One “[” character, decimal value 91.
Zero or more characters with decimal values 4863.
Zero or more characters with decimal values 3247.
One character with decimal value 64126.

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:

Make ESC a terminator.
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 reenable 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:

Turn off echo at both ends by including the S protocol in OPEN or USE, or by using the operating system's terminal parameters.
Unless your communication protocol supports XON/XOFF flow control (Ctrl-Q and Ctrl-S), be sure it limits unacknowledged transmissions to the limit of the operating system's input buffering; otherwise you may lose data.
In image mode, Caché does not support XON/XOFF. In nonimage (normal) mode, the operating system's terminal parameters determine whether the computer issues an XOFF if the operating system's input buffer is almost full. If XOFF and XON are not supported, make the buffer large enough that you do not need them.
Test $ZA after read operations to detect transmission errors such as parity or data overrun conditions.
On an OpenVMS Alpha platform, you can use the OpenVMS Alternate Typeahead buffer parameter to give some terminals larger buffers than others.