Using the OPEN Command
The OPEN command reserves a TCP binding device for your use. The syntax is:
OPEN devicename:parameters:timeout:mnespace
where:
devicename
A string of the form |TCP| followed by some number of numeric digits. The numeric portion of the device name is called the device identifier. If the port number is not specified in the OPEN parameters, this device identifier must be a unique five-digit TCP port number. If the port number is specified in the OPEN parameters (which is the preferred practice), this device identifier can be any unique number (up to a maximum of 2147483647), so long as all the TCP device names used by a single job are distinct.
parameters
Optional — A series of one or more device parameters, enclosed by parentheses and separated by colons (:). If a parameter is omitted, specify the colon separator for the missing parameter. (For a server-side OPEN the first parameter is always omitted.) The specific parameters are described below.
If you specify only the first parameter (hostname), you can omit the parentheses. For example, the client-side open: OPEN "|TCP|7000":"127.0.0.1":10. If you specify no parameters, you can omit the parentheses, but you must retain the colon as a separator character. For example, the server-side open: OPEN "|TCP|7000"::10.
timeout
Optional — Maximum number of seconds InterSystems IRIS attempts to open the TCP device. If it does not succeed within this interval, it sets $TEST to 0 and returns control to the process. If it succeeds, it sets $TEST to 1. Including a timeout in OPEN commands from the client prevents the client system from hanging if it tries to open a connection while the server is busy with another client. The server can have only one connection open at a time.
mnespace
Optional — Supported as it is for all ObjectScript OPEN commands. There is no predefined mnemonic space for TCP bindings.
If you omit an OPEN argument, you can indicate its absence by specifying the colon separator.
The timeout argument, though optional, is strongly recommended because the success or failure of OPEN is indicated by the value of the $TEST special variable, and $TEST is only set if timeout is specified. $TEST is set to 1 if the open attempt succeeds before the timeout expires; if the timeout expires, $TEST is set to 0.
If a TCP connection attempt fails on Windows systems, the TCP connection error is written to the InterSystems IRIS system error log (see InterSystems IRIS System Error Log), for example, error code 10061 = WSAECONNREFUSED.
The following is an example of a client-side OPEN, where 7000 is the port number and "127.0.0.1" is the parameters argument (the hostname, specified as an IPv4 address):
SET dev="|TCP|7000"
OPEN dev:("127.0.0.1":7000)
hostname Parameter
The hostname parameter is required for a client-side OPEN. The client-side parameters argument may be just the hostname, or the hostname followed by other colon-separated parameters. If you specify just the hostname parameter, you can omit the parameters parentheses.
The server-side parameters argument omits the hostname.
The hostname can be either the name of an IP host (from the local system’s database of remote hosts) or an IP address in either IPv4 or IPv6 protocol format. Because these protocols are incompatible, both the server and the client must use the same Internet protocol or the transmission will fail.
An IPv4 address has the following format. n is a decimal integer in the range 0 through 255:
n.n.n.n
An IPv6 address has the following full format. h is a hexadecimal number with four hexadecimal digits:
h:h:h:h:h:h:h:h
Commonly, IPv6 addresses are abbreviated by eliminating leading zeros and replacing consecutive sections of zeros with a double colon (::); only one double colon may be used in an IPv6 address. By using IPv4 abbreviation rules, you can specify the IPv6 loopback address as "::1" (meaning that the first seven consecutive h sections all have the value 0000, and the leading zeros from the eighth section are eliminated).
You can use the OPEN keyword /USEIPV6 to specify which protocol to use. Further details on IPv4 and IPv6 formats can be found in Use of IPv6 Addressing.
Supported Parameters
The parameters argument can be in either of the following formats:
hostname
(hostname{:port{:mode{:terminators{:ibufsiz{:obufsiz{:queuesize{:keepalivetime}}}}}}})
The parameters within the parameters argument are as follows:
hostname
Optional — Either the name of an IP host, an IP address in IPv4 protocol format, or an IP address in IPv6 protocol format. Specified as a quoted string. A hostname is required for a client-side OPEN; omitted (represented by a placeholder colon) for a server-side OPEN.
port
Optional — If present, this is the TCP port number to use for the connection. If this port number is null or omitted, then the port number is derived from the numeric portion of the devicename. This parameter can either be a decimal port number or a service name, which is submitted to the local system’s TCP service name resolver.
mode
Optional — A string of letter code characters enclosed in quotes. Letter codes may be specified in any order; because InterSystems IRIS executes them in left-to-right order, interactions between letter codes may dictate a preferred order in some cases. The default is packet mode. A mode string can consist of one or more of the following letter codes:
-
A — Accept mode. If A is on, the initial read on the server terminates with a zero-length string as soon as the connection from the client job is accepted. If A is off, the read blocks until the timeout is reached, or until data is available, whichever occurs first.
-
C — See Carriage Return Mode below.
-
D — See Monitoring for Disconnect Mode below.
-
E — See Escape Sequence Processing Mode below.
-
G — Causes the port parameter to be interpreted as the socket descriptor of an already opened data socket.
-
M — Standard InterSystems IRIS device in stream mode. This mode is a shorthand for invoking the PSTE set of options. It yields a device that acts like a standard InterSystems IRIS device that can be used to pass arbitrary lines of data in both directions. You turn on stream mode so that you can send or receive any arbitrary sequence of strings, without overrunning the buffers. Line feeds are added to output and stripped from input. READ commands block until one of the following occurs: a terminator character is seen, the timeout is reached, or the read length specified has been filled.
-
P — Pad output with record terminator characters. When this mode is set, WRITE ! sends LF (line feed) and WRITE # sends FF (form feed), in addition to flushing the write buffer. The WRITE *-3 command can be used to initiate the sending of buffered data without inserting any characters into the data stream. Note that WRITE *-3 just flushes the write buffer without sending any terminator character, and thus does not signal the recipient program that the data is complete. WRITE *-3 is more commonly used in Wait (W) mode, which does not require a terminator.
-
Q — See Send Immediate Mode below.
-
S — See Stream Mode below.
-
T — Standard terminators on input. When this is set, the CR, LF, and FF control characters function as read terminators.
-
W — Wait mode. In this mode, WRITE ! and WRITE # commands will not cause a TCP device to flush the network output buffers. Wait mode causes a TCP device to wait until the next WRITE *-3 command to flush the buffers and transmit the data.
terminators
Optional — A list of up to eight user terminator characters that will terminate reads on the TCP binding device. If you specify both T mode and terminators at the same time, T mode is ignored.
ibufsiz
Optional — Input buffer size. Internally, characters that have been read from the network but not yet delivered to the InterSystems IRIS program are buffered in a data area that can hold ibufsiz bytes.
obufsiz
Optional — Output buffer size. The maximum amount of data the TCP device can buffer between successive SEND operations. A SEND operation means to send the buffered data out to the network. WRITE !, WRITE #, and WRITE *-3 commands can generate SEND operations.
When S mode is specified, SEND operations are generated automatically to send the contents of the output buffer whenever it gets too full. When done creating a message, however, the programmer must still use one of the SEND operations to make sure the message is sent.
When S mode is not specified, if a WRITE operation would place enough data in the buffer to exceed the output buffer size, then a <WRITE> error occurs. Note that attempting to write a string that is in itself longer than the output buffer size always fails.
queuesize
Optional — An integer that specifies how many client jobs can queue for a connection to the server. Used for server-side OPEN only. The default is 5. The maximum value depends on the TCP implementation, but cannot exceed 1000.
keepalivetime
Optional — (Windows, AIX, and Linux only) Allows you to set a keepalive timer for this device that is different than the system default. Specify an integer number of seconds to keep alive the TCP connection. Valid values range from 30 to 432000. (432000 seconds is 5 days.) A value less than 30 defaults to 30. If omitted or set to 0, the system-wide default keepalive timer is used. See the /KEEPALIVE keyword option for further details.
The keepalive timer does not necessarily start timing when the TCP device is opened. It typically begins timing when the connection has been established. That is, when the initial read-for-connect has completed successfully.
Packet Mode
Packet mode is the default if no mode is specified. If stream mode is disabled, the mode defaults to packet mode.
In packet mode READ commands complete as soon as there is some data to return. Packet mode allows you to build an entire TCP segment in the output buffer, and then send it all at one time by issuing a WRITE *-3 or WRITE ! command.
If you issue WRITE *-1 to initiate a TCP SEND operation when there are no characters to be sent, you receive a <WRITE> error. If you issue WRITE of an empty string, you receive a <COMMAND> error.
The maximum size of the string you can send in packet mode is 1024 characters. If you exceed this limit without flushing the buffer, you receive a <WRITE> error.
Because TCP/IP ignores records with a length of 0, you receive a <WRITE> error if you flush the write buffer when there are no characters in it.
A WRITE command from server to client before the server has received a connection request produces a <WRITE> error on the server.
Carriage Return Mode (C mode)
This mode modifies processing of carriage returns on input and output.
On Output, WRITE ! generates CR LF and WRITE # generates CR FF.
On input, with T mode enabled, the server tries to record an adjacent CR and LF or an adjacent CR and FF as a single terminator in $ZB. CR and LF are processed as separate terminators if they do not arrive within a short interval of each other. By default, the interval is 1 second.
Monitoring for Disconnect Mode (D mode)
This mode turns on or off asynchronous disconnect monitoring. This mode is activated by specifying the “D” mode character, or the /POLL or /POLLDISCON keyword parameter. When you specify +D, TCP disconnect monitoring is activated; when you specify –D, TCP disconnect monitoring is deactivated.
While activated, InterSystems IRIS polls the TCP connection roughly every 60 seconds. When it detects a disconnect, InterSystems IRIS issues a <DISCONNECT> error. Disconnect detection does not occur in idle jobs, such as a job suspended by a HANG command or a job waiting on a READ operation. InterSystems IRIS suspends all disconnect monitoring during a rollback operation to prevent a <DISCONNECT> error being issued. InterSystems IRIS resumes disconnect monitoring once the rollback concludes. This suspension applies both to a current TCP device with disconnect monitoring activated, and to a current device without disconnect monitoring that is connected to a TCP device with disconnect monitoring activated.
You can also check for TCP disconnect by using the Connected()Opens in a new tab method of the %SYSTEM.INetInfoOpens in a new tab class.
Escape Sequencing Processing Mode (E mode)
When the E mode is set, escape sequences in the input stream are parsed and placed into the $ZB special variable. Escape sequences must be 15 characters or less and must match the following syntax:
esc_seq::=type1 | type2
where:
type1 ::= '['['0':'?']*['':'/']*{'@':DEL}
type2 ::= [';'|'?'|'O']['':'/']*{'0':DEL}
The syntactic symbols used here mean:
Symbol |
Description |
: |
x:y means a specified range of characters from x through y in the ASCII sequence. |
| |
x|y means specify either x or y. |
[ ] |
Specify zero or one members of the specified set. |
[ ]* |
Specify zero, one, or more members of the specified set. |
{ } |
Specify exactly one member of the specified set. |
When InterSystems IRIS sees an ESCAPE, it waits up to 1 second for the rest of the escape sequence to arrive. If the escape sequence does not match this syntax, or if it is longer than 15 characters, or if a valid escape sequence does not arrive within 1 second, InterSystems IRIS places the partial escape sequence in $ZB and sets the BADESC bit (256) in $ZA.
Stream Mode (S mode)
In stream mode, InterSystems IRIS does not attempt to preserve TCP message boundaries in the data stream. On sending, if the data does not fit in the message buffer, InterSystems IRIS flushes the buffer before placing the data in it.
On receiving, data up to the maximum string length can be received. All reads wait for the full timeout for terminators to be reached or for the buffer to become full. When this mode is disabled (the default), you are in packet mode.
Jobbed processes that inherit TCP devices are automatically set to Stream format. You can reset the format with the USE command.
Buffer Sizes
The ibufsiz and obufsiz parameters for TCP devices specify the sizes of the internal InterSystems IRIS buffers for TCP input and output. They can take values between 1KB and 1MB on all supported platforms. However, operating system platforms may use different sizes for their own input and output buffers. If the operating system platform buffer is smaller than the InterSystems IRIS buffer (for example, 64KB vs 1MB), performance may be affected: a WRITE operation may require several trips to the OS to send the entire InterSystems IRIS buffer; a READ operation may return smaller chunks that are limited by the OS buffer size. For optimal performance, a user should experiment with the current OS to determine which values for ibufsiz and obufsiz produce optimal results.
Server-Side OPEN Command
When the server-side OPEN is processed, it establishes a TCP socket and listens on the socket for incoming connection requests on the appropriate port number. The port number is either specified explicitly in the parameter list, or derived from the numeric portion of the devicename. The OPEN returns immediately after the socket has been set up to listen.
If the OPEN does not succeed, another process may already be listening for connection requests on that port number.
The following example of a server-side OPEN shows a device specification that allows reading and writing of terminated strings up to the maximum string size, and uses maximum length read and write operations to consolidate use of the TCP channel.
OPEN "|TCP|4":(:4200:"PSTE"::32767:32767)
The parameters argument in this example is as follows: because this is a server-side OPEN, the first parameter (hostname) is omitted. The second parameter explicitly specifies the port number (4200). The third parameter is the mode code characters. The fourth parameter (terminators) is omitted. The fifth parameter is the input buffer size. The sixth parameter is the output buffer size.
In the following example the port number is not specified as a parameter; it is derived from the numeric portion of the devicename. This example opens port 4200 with no specified parameters and a timeout of 10 seconds:
OPEN "|TCP|4200"::10
A server-side OPEN has default input buffer size (ibufsiz) and output buffer size (obufsiz) parameter values of 1,048,576 bytes (1 MB).
A server-side OPEN supports the optional queuesize parameter, and the optional G mode parameter. These options are not available to a client-side OPEN.
A server-side OPEN supports the optional /CLOSELISTEN keyword parameter. This option is not available to a client-side OPEN.
Client-Side OPEN Command
A client-side OPEN command differs from the server-side OPEN command in only one respect: the first device parameter must specify the host to which you are connecting. To specify the host, you include either a name that the client recognizes as a host, or an Internet address.
The OPEN succeeds as soon as the connection is established. At this point, you can read or write to the TCP device. However, if the server side of the connection is another InterSystems IRIS process, the server does not complete its side of the connection until some data has been sent from the client to the server with the WRITE command. Therefore, you must issue a WRITE command before you issue any READ commands.
For details, see WRITE Command for TCP Devices.
Some examples of client-side OPEN commands are:
OPEN "|TCP|4":("hal":4200::$CHAR(3,4)):10
This command opens a connection to host hal on port 4200. It specifies no mode string. It specifies two terminators (ASCII $CHAR(3) and $CHAR(4)), and default input and output buffer sizes. It specifies a timeout of 10 seconds.
The following command is the same as the previous one, except that the destination is an explicit IP address in IPv4 format.
OPEN "|TCP|4":("129.200.3.4":4200::$CHAR(3,4)):10
You can use the OPEN keyword /USEIPV6 to specify which protocol to use. Further details on IPv4 and IPv6 formats can be found in Use of IPv6 Addressing.
The following command connects to time-of-day server on remote host larry and prints the remote host’s time of day in ASCII format on the principal input device. It uses the service name daytime, which the local system resolves to a port number:
OPEN "|TCP|4":("larry":"daytime":"M")
USE "|TCP|4"
READ x
USE 0
WRITE x
The following command sets x to hello:
OPEN "|TCP|4":("larry":"echo":"M")
USE "|TCP|4"
WRITE "hello",!
READ x
The following command opens a connection to Internet address 128.41.0.73, port number 22101, with a 30-second timeout.
OPEN "|TCP|22101":"128.41.0.73":30