$Y contains the current vertical position of the cursor. As characters are written to a device, InterSystems IRIS updates $Y to reflect the vertical cursor position.
Each line feed (newline) character (ASCII 10) that is output increments $Y by 1. A form feed character (ASCII 12) resets $Y to 0.
$Y is a 16-bit unsigned integer. $Y wraps to 0 when its value reaches 65536. In other words, if $Y is 65535, the next output character resets it to 0.
You can use the SET command to give a value to $X and $Y. For example, you may use special escape sequences that alter the physical cursor position without updating the $X and $Y values. In this case, use SET to assign the correct values to $X and $Y after you use the escape sequences.
NLS Character Mapping
The National Language Support (NLS) utility $X/$Y tab defines the $X and $Y cursor movement characters for the current locale. For further details, refer to the section on “System Classes for National Language Support” in Specialized System Tools and Utilities.
$Y with Terminal I/O
The following table shows the effects of different characters on $Y.
|Echoed Character||ASCII Code||Effect on $Y|
|Any printable ASCII character||32-126||$Y=$Y|
The S(ecret) protocol of the OPEN and USE commands turns off echoing. It also prevents $Y from being changed during input, so it indicates the true cursor position.
A WRITE $CHAR() that changes vertical position also changes $Y. A WRITE * that changes vertical position does not change $Y. For example, WRITE $Y,$CHAR(10),$Y performs the line feed and increments $Y. In contrast, WRITE $Y,*10,$Y performs the line feed but does not increment $Y. (See the WRITE command for further details.)
Because WRITE * does not change $Y, you can send a control sequence to your terminal and $Y will still reflect the true cursor position. Since some control sequences do move the cursor, you can use the SET command to set $Y directly. For example, the following commands move the cursor to column 20 and line 10 on a VT100-type terminal and set $X and $Y accordingly:
SET dy=10,dx=20 WRITE *27,*91,dy+1,*59,dx+1,*72 SET $Y=dy,$X=dx
ANSI standard control sequences (such as escape sequences) that the device acts on but does not output can produce a discrepancy between the $X and $Y values and the true cursor position. To avoid this problem, use the WRITE * statement and specify the ASCII value of each character in the string. For example, instead of using the following code:
use this equivalent form:
As a rule, after any escape sequence that explicitly moves the cursor, you should update $X and $Y to reflect the actual cursor position.
$X special variable
I/O Devices and Commands in I/O Device Guide
Terminal I/O in I/O Device Guide
Interprocess Communication in I/O Device Guide