GT.M intrinsic special variables provide a mean for application code to communicate and manage the state of a device.
GT.M provides three intrinsic special variables that identify devices.
$I[O] contains the name of the current device specified by the last USE command. A SET command cannot modify $IO. USE produces the same $IO as USE $PRINCIPAL, but $P is the preferred construct.
A process inherits three open file descriptors from its parent - STDIN, STDOUT and STDERR - which can all map to different files or devices. GT.M provides no way for M application to access STDERR. Although STDIN and STDOUT may map to different devices, files, sockets, pipes, etc. in the operating system, M provides for only device $PRINCIPAL, to refers to both. At process startup, and when $PRINCIPAL is selected with a USE command, READ commands apply to STDIN and WRITE commands apply to STDOUT. The device type of the standard input determines which USE deviceparameters apply to $PRINCIPAL.
For an interactive process, $PRINCIPAL is the user's terminal. GT.M ignores a CLOSE of the principal device. GT.M does not permit a SET command to modify $PRINCIPAL.
0 is an alternate for $PRINCIPAL (for example, USE 0). FIS recommends that application code use $PRINCIPAL. The environment variable gtm_principal can be used to set a string reported by GT.M for $PRINCIPAL and which can be used in lieu of $PRINCIPAL for the USE command.
$ZIO contains the translated name of the current device, in contrast to $IO, which contains the name as specified by the USE command.
When $PRINCIPAL has different input/output devices, the USE command recognizes intrinsic special variable $ZPIN to apply appropriate deviceparameters to the input side of $PRINCIPAL. A USE with $ZPIN sets $IO to $PRINCIPAL for READs and WRITEs from the input and output side of $PRINCIPAL. $ZSOCKET() also accepts $ZPIN as its first argument and, if the device is a split SOCKET device, supplies information on the input SOCKET device. In any context other than USE or $ZSOCKET(), or if $PRINCIPAL is not a split device, $PRINCIPAL, $ZPIN and $ZPOUT are synonyms. In the case of a split $PRINCIPAL, $ZPIN returns the value of $PRINCIPAL followed by the string "< /" Any attempt to OPEN $ZPIN results in a DEVOPENFAIL error.
When $PRINCIPAL has different input/output devices, the USE command recognizes intrinsic special variables $ZPOUT to apply appropriate deviceparameters to the output side of $PRINCIPAL. A USE with $ZPOUT sets $IO to $PRINCIPAL for READs and WRITEs from the input and output side of $PRINCIPAL. $ZSOCKET() also accepts $ZPOUT as its first argument and, if the device is a split SOCKET device, supplies information on the output SOCKET device. In any context other than USE or $ZSOCKET(), or if $PRINCIPAL is not a split device, $PRINCIPAL, $ZPIN and $ZPOUT are synonyms. In the case of a split $PRINCIPAL, $ZPOUT returns the value of $PRINCIPAL followed by the string "> /" Any attempt to OPEN $ZPOUT results in a DEVOPENFAIL error.
GT.M provides two intrinsic special variables for determining the virtual cursor position. $X refers to the current column, while $Y refers to the current row.
$X contains an integer value ranging from 0 to 65,535, specifying the horizontal position of a virtual cursor in the current output record. $X=0 represents the initial position on a new record or row.
Every OPENed device has a $X. However, GT.M only has access to $X of the current device.
Generally, in M mode GT.M increments $X for every character written to and read from the current device; see below for behavior of a UTF-8 mode device. GT.M format control characters, FILTER, and the device WIDTH and WRAP also have an effect on $X.
As $X is only a counter to help a program track output, SET $X does not reposition the cursor or perform any other IO. Conversely, if a sequence of characters sent to a terminal or other device with a WRITE causes it to be repositioned except as described below, $X will not reflect this change.
$Y contains an integer value ranging from 0 to 65,535, specifying the vertical position of a virtual cursor in the current output record. $Y=0 represents the top row or line.
Every OPEN device has a $Y. However, GT.M only accesses $Y of the current device.
When GT.M finishes the logical record in progress, it generally increments $Y. GT.M recognizes the end of a logical record when it processes certain GT.M format control characters, or when the record reaches its maximum size, as determined by the device WIDTH, and the device is set to WRAP. The definition of "logical record" varies from device to device. For an exact definition, see the sections on each device type. FILTER and the device LENGTH also have an effect on $Y.
As $Y is only a counter to help a program track output, SET $Y does not reposition the cursor or perform any other IO. Conversely, if a sequence of characters sent to a terminal or other device with a WRITE causes it to be repositioned except as described below, $Y will not reflect this change.
The following factors affect the maintenance of the virtual cursor position ($X and $Y):
The bounds of the virtual "page"
Format control characters
GT.M character filtering
Each device has a WIDTH and a LENGTH that define the virtual "page." The WIDTH determines the maximum size of a record for a device, while the LENGTH determines how many records fit on a page. GT.M starts a new record when the current record size ($X) reaches the maximum WIDTH and the device has WRAP enabled. When the current line ($Y) reaches the maximum LENGTH, GT.M starts a new page.
GT.M has several format control characters (used in the context of a WRITE command) that allow the manipulation of the virtual cursor. For all I/O devices, the GT.M format control characters do the following:
! Sets $X to zero (0) and increments $Y, and terminates the logical record in progress. The definition of "logical record" varies from device to device, and is discussed in each device section.
# Sets $X and $Y to zero (0), and terminates the logical record in progress.
?n If n is greater than $X, writes n-$X spaces to the device, bringing $X to n. If n is less than or equal to $X, ?n has no effect. When WRAP is enabled and n exceeds the WIDTH of the line, WRITE ?n increments $Y and sets $X equal to n#WIDTH, where # is the GT.M modulo operator.
In UTF-8 mode, GT.M maintains $X in the following measurement units:
|
Devices |
Input |
Output |
|---|---|---|
|
FIFO |
code points |
display columns |
|
PIPE |
code points |
display columns |
|
SD |
code points |
display columns |
|
SOC |
code points |
code points |
|
TRM |
display columns |
display columns |
GT.M provides two modes of character filtering. When filtering is enabled, certain <CTRL> characters and/or escape sequences have special effects on the cursor position (for example, <BS> (ASCII 8) may decrement $X, if $X is non-zero). For more information on write filtering, refer to “FILTER”.
GT.M provides several I/O status variables that convey information about the commands operating on the device.
If the last commanded resulted in no error-condition, the value of $DEVICE, when interpreted as a truth-value is 0 (FALSE). If the status of the device reflect any error-condition, the value of $DEVICE, when interpreted as a truth-value is 1 (TRUE). When $DEVICE starts with 1, it's followed by a comma (,) and then by the text that would be in $ZSTATUS at the time of the error.
Examples:
0 indicates for READ with a zero (0) timeout that available data has been read.
"1,Device detected EOF" indicates the device reached an end-of-file condition.
$K[EY] contains the string that terminated the most recent READ command from the current device (including any introducing and terminating characters). If no READ command is issued to the current device or if no terminator is used, the value of $KEY is an empty string.
For PIPE:
$KEY contains the UNIX process id of the created process shell which executes the command connected to the PIPE.
For more information, refer to “$Key”.
$ZA contains the status of the last read on the device. The value is a decimal integer with a meaning as follows:
For Terminal I/O:
0: Indicates normal termination of a read operation
1: Indicates a parity error
2: Indicates the terminator sequence was too long
9: Indicates a default for all other errors
For Sequential Disk :
0: Indicates normal termination of a read operation
9: Indicates a failure of a read operation
For FIFO:
0: Indicates normal termination or time out
9: Indicates a failure of a read operation
For SOCKET:
0: Indicates normal termination or time out
9: Indicates failure of a read operation
For PIPE:
0: Indicates normal termination or time out when using READ x:n, where n >0
9: Indicates failure of a READ x or READ x:n, where n>0
9: Indicates failure of a WRITE where the pipe is full and the WRITE would block
![[Caution]](../common/images/caution.jpg) | Caution |
|---|---|
$ZA refers to the status of the current device. Therefore, exercise care in sequencing USE commands and references to $ZA. |
$ZB contains a string specifying the input terminator for the last terminal READ. $ZB is null, and it is not maintained for devices other than terminals. $ZB may contain any legal input terminator, such as <CR> (ASCII 13) or an escape sequence starting with <ESC> (ASCII 27), from zero (0) to 15 bytes in length. $ZB is null for any READ terminated by a timeout or any fixed-length READ terminated by input reaching the maximum length.
$ZB contains the actual character string, not a sequence of numeric ASCII codes.
If a device is opened with CHSET set to UTF-8 or UTF-16*, $ZB contains the bad character if one is encountered. This holds true for sockets, sequential files (and thus FIFOs and PIPEs) and terminals.
Example:
set zb=$zb for i=1:1:$length(zb) write !,i,?5,$ascii(zb,i)
This example displays the series of ASCII codes for the characters in $ZB.
$ZB refers to the last READ terminator of the current device. Therefore, be careful when sequencing USE commands and references to $ZB.
$ZEOF contains a truth-valued expression indicating whether the last READ operation reached the end-of-file. $ZEOF is TRUE(1) at EOF and FALSE (0) at other positions. GT.M does not maintain $ZEOF for terminal devices.
$ZEOF refers to the end-of-file status of the current device. Therefore, be careful when sequencing USE commands and references to $ZEOF.
$ZEOF is set for terminals if the connection dropped on read.
