READ Command for TCP Devices
Issue the READ command from either the server or the client to read any characters set by either the client or the server.
The syntax is as follows:
READ var:timeout
READ *var:timeout
READ var#length:timeout
The timeout argument, though optional, is strongly recommended because the success or failure of the READ is indicated by the value of the $TEST special variable if timeout is specified. $TEST is set to 1 if the read attempt succeeds before the timeout expires; if the timeout expires, $TEST is set to 0.
The timeout argument supports seconds and fractions of a second to 1/100th of a second. For example, 10, 10.5, .5, .05.
For an SSL connection, a job can wait in the first read or first write command if the other party never issues a read or write command after the connection is established. In this circumstance, InterSystems IRIS supports the read timeout for a READ command and write timeout (with /WRITETIMEOUT=n option) for a WRITE command. If there is no read or write timeout specified, then the job will wait until the other party issue a read or write command.
You can determine the number of reads performed by the current TCP connection using the TCPStats()Opens in a new tab method of the %SYSTEM.INetInfoOpens in a new tab class.
READ Modifies $ZA and $ZB
Your application can learn about how the connection and read succeeded by testing the values of $ZA and $ZB.
$ZA and READ Command
$ZA reports the state of the connection. When the 0x1000 bit (4096) is set, this TCP device is functioning in Server mode. When the 0x2000 bit (8192) is set, the device is currently in the Connected state talking to a remote host.
For example, assume that a server-side TCP device is expected to accept a new TCP connection. By looking at $ZA and $TEST after an initial timed read, the InterSystems IRIS program can distinguish among three cases:
| $ZA Value |
$TEST Value |
Meaning |
| 4096 |
0 |
No connection has been accepted. |
| 12288 |
0 |
Connection accepted, no data received. |
| 12288 |
1 |
Connection accepted and data received. |
The following table shows what each bit in $ZA represents.
| Decimal Value of $ZA |
Hexadecimal Value of $ZA |
Meaning |
| 2 |
0x2 |
Read timed out. |
| 4 |
0x4 |
I/O error. |
| 256 |
0x80 |
Bad escape sequence received. |
| 4096 |
0x1000 |
Server mode. |
| 8192 |
0x2000 |
Connected. |
$ZB and READ Command
$ZB holds the character that terminated the read. This character can be one of the following:
-
A termination character, such as a carriage return
-
The yth character of a fixed-length READ x#y
-
The single character of READ *X
-
An empty string after a timed read expires
-
An escape sequence
Note that if a string is terminated with CR LF, then only the CR is placed in $ZB.
