Special Variables Show I/O Conditions

$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. InterSystems IRIS 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

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.

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

• Your operating system, which sets the default behavior.

• Whether /NOXY (which disables $X and $Y processing) was specified in the OPEN or USE command.

• You can set how $X handles escape sequences for the current process using the DX()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class. The system-wide default behavior can be established by setting the DXOpens in a new tab property of the Config.MiscellaneousOpens in a new tab class.

Escape Sequences 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), InterSystems IRIS 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() method 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)Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class.

The system manager can alter the system-wide default behavior by setting the DXOpens in a new tab property of the Config.MiscellaneousOpens in a new tab class.

In both cases, n has a value from 0 through 4, as follows:

Value	Default Behavior for Updating $X
0	Default for InterSystems IRIS
1	DSM behavior
2	DTM/MSM behavior

For more information, see $X in the 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:

• $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.

For more information, see $TEST in the 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; InterSystems IRIS 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 ObjectScript Language Reference.)

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 Error Processing and $ZTRAP in the 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; InterSystems IRIS 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>