Contains status information for the current I/O device.
contains status information specific to the current I/O device following a READ
When reading from a terminal, sequential file, or other character-based I/O device, $ZB
contains the terminating
character of the read operation. This can be a terminator character (such as <RETURN>), the final character of the input data if the read operation does not require a terminator character, or the null string if a terminator character is required but was not received (for example, if the read operation timed out).
When reading from a block-based I/O device $ZB
contains the number of bytes remaining in the I/O buffer. $ZB
also contains the number of bytes in the I/O buffer when writing to a block-based I/O device.
This special variable cannot be modified using the SET
command. Attempting to do so results in a <SYNTAX> error.
can both be used to return the READ
termination character when reading from a character-based device or file. For character-based reads, these two special variables are very similar, but not identical. For block-based reads and writes use $ZB
does not provide support for block-based read and write operations. See $KEY
for further details.
By default, InterSystems IRIS handles an end-of-file on a sequential file by issuing an <ENDOFFILE> error; it does not set $ZB
. You can configure $ZB
end-of-file behavior so that when an end-of-file is encountered, InterSystems IRIS does not issue an error, but sets $ZB
to "" (the null string), and sets $ZEOF
Reading from a Terminal or File
contains the terminating character (or character sequence) from a read operation involving a terminal, sequential file, or other character-based I/O device. $ZB
can contain any of the following:
A termination character, such as a carriage return.
An escape sequence (up to 16 characters).
th character in a fixed-length READ x
. (In this case, the $KEY
special variable returns the null string.)
The single character of READ
A null string ("") after a timed READ
For example, consider the following variable-length read with a five-second timeout:
READ !,"Enter number:",num:5
WRITE !, num
WRITE !, $ASCII($ZB)
If the user types 123 at the READ
prompt and presses <RETURN>, InterSystems IRIS stores 123 in the num
variable and stores <RETURN> (ASCII decimal code 13, hexadecimal 0D) in $ZB
. If the READ
times out, $ZB
contains the null string; $ASCII("")
returns a value of 1.
When issuing commands interactively from the Terminal command line, you press <RETURN> to issue each command line. The $ZB
special variables record this command line terminator character. Therefore, when using $ZB
to return the termination status of a read operation, you must set a variable as part of the same command line.
For example, if you issue the command:
from the command line, then check $ZB
it will not
contain the results of the read operation; it will contain the <RETURN> character that executed the command line. To return the results of the read operation, set a local variable with $ZB
in the same command line, as follows:
This preserves the value of $ZB
set by the read operation. To display this read operation value, issue either of the following command line statements:
; returns -1 for null string (time out),
; returns ASCII decimal value for terminator character
; returns blank line for null string (time out)
; returns hexadecimal value for terminator character