OPEN and USE Command Keywords for TCP Devices

Default: 0

Specifies read timeout behavior. Determines whether TCP should reinitialize the timeout period when data is received. If /ABSTIMEOUT=0 (the default) timeout is reset to its original value each time data is received. If /ABSTIMEOUT or /ABSTIMEOUT=1 the timeout period continues to count down while data is received.

Or:

/ACC[=n]

Default: 0

Corresponds to the A mode parameter character, which specifies that the initial read on the server terminates with a zero length string as soon as the connection from the client job is accepted. /ACCEPT and /ACCEPT=n for nonzero values of n enable A mode. /ACCEPT=n for a zero value of n disables A mode.

Default: 1

Specifies handling of data remaining in the output buffer when the device is closed. /CLOSEFLUSH and /CLOSEFLUSH=n for nonzero values of n flushes remaining data. /CLOSEFLUSH=n for a zero value of n discards remaining data.

Default: ""

Specifies the stream data compression type. You can enable a compression type of ZLIB or ZSTD. You can specify /COMPRESS="" to disable compression. /COMPRESS="zlib" is equivalent to /GZIP=1. To compress a string, use %SYSTEM.Util.Compress()Opens in a new tab.

Default: 0

Corresponds to the C mode parameter character, which modifies processing of carriage returns on input and output. /CRLF and /CRLF=n for nonzero values of n enable C mode. /CRLF=n for a zero value of n disables C mode.

Or:

/ESC[=n]

Default: 0

Corresponds to the E mode parameter character, which specifies that escape sequences in the input stream are parsed and placed into $ZB. /ESCAPE and /ESCAPE=n for nonzero values of n enable E mode. /ESCAPE=n for a zero value of n disables E mode.

Default: 1

Specifies GZIP-compatible stream data compression. /GZIP or /GZIP=n (for nonzero values of n) enables compression on WRITE and decompression on READ. /GZIP=0 disables compression and decompression. Before issuing /GZIP=0 to disable compression and decompression, check the $ZEOS special variable to make sure that a stream data read is not in progress. /GZIP compression has no effect on I/O translation, such as translation established using /IOTABLE. This is because compression is applied after all other translation (except encryption) and decompression is applied before all other translation (except encryption). For further information on WRITE with compressed data, see WRITE Control Characters.

Or:

/IOT[=name]

Default: If name is not specified, the default I/O translation table for the device is used.

Establishes an I/O translation table for the device.

Default: system default

(Windows, AIX, and Linux only) Allows you to set a keepalive timer for this device that is different than the system default. An integer that specifies the number of seconds to keep alive the TCP connection. Same as the keepalivetime positional parameter. 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 default is used. This setting can be disabled using /NOKEEPALIVE; once disabled, it cannot be re-enabled until this TCP device is closed.

Default: 1

Specifies whether packets should be bundled or sent individually. If /NODELAY=1 (the default) each packet is immediately transmitted. If /NODELAY=0 the TCP driver bundles packages together using an optimization algorithm. This can cause a slight transmission delay for an individual packet, but by reducing network traffic it can improve overall performance. /NODELAY has no corresponding mode parameter character. Use of /NODELAY should be coordinated with use of /SENDIMMEDIATE.

If specified, the system-wide TCP keepalive timer is disabled for this device. InterSystems IRIS enables this timer by default when opening any TCP device; issuing the /NOKEEPALIVE option on OPEN or USE overrides this default. If /KEEPALIVE has been used to set a non-default keepalive timer, /NOKEEPALIVE disables that keepalive timer. Once you disable a keepalive timer there is no way to re-enable it until the TCP device is closed. See /KEEPALIVE.

Default: 0

No $X and $Y processing: /NOXY or /NOXY=n (for nonzero values of n) disables $X and $Y processing. This option can improve performance when device $X/$Y is not used, for example with CSP. It can substantially improve performance of READ and WRITE operations. This option is the default setting for superserver worker jobs. When /NOXY=1, the values of the $X and $Y variables are indeterminate, and margin processing (which depends on $X) is disabled. /NOXY=0 enables $X and $Y processing; this is the default. /TCPNOXY is a deprecated synonym for /NOXY.

Default: 16

The number of output buffers to use with /ZEROCOPY. The default number of output buffers is 16. The minimum number of output buffers is 2 and the maximum is 128. The value of n must be power of 2; if a non-power-of-2 value is specified, it is rounded up to a power of 2.

Default: 0

Corresponds to the P mode parameter character, which specifies that output is padded with record terminator characters when WRITE ! (LF terminator) or WRITE # (FF terminator) is executed. /PAD and /PAD=n for nonzero values of n enable P mode. /PAD=n for a zero value of n disables P mode.

Or:

/PAR=str

No default. Corresponds to the mode positional parameter. (It provides a way to specify a mode string in a position-independent way.)

Or:

/POLLDISCON[=n]

Corresponds to the D mode parameter character, which specifies asynchronous monitoring for disconnect. /POLL or /POLL=1 corresponds to +D. /POLL=0 corresponds to -D.

Default: 0

Corresponds to the M mode parameter character, which is a shorthand way to specify the P, S, T and E mode parameter characters. /PSTE and /PSTE=n for nonzero values of n enable P, S, T and E modes. /PSTE=n for a zero value of n disables these modes.

Or:

/SEN[=n]

Default: 0

Corresponds to the Q mode parameter character, which specifies Send Immediate Mode.

Or:

/TLS="cfg[|pw] [|DNShost]"

No default.

From a client, specifies that the device attempts to negotiate an SSL/TLS-secured connection according to the client’s specified configuration and server requirements. When securing a socket as a server, specifies that the server requires a SSL/TLS-secured connection according to the server’s specified configuration and any client requirements.

The value of the /SSL or /TLS keyword parameter is a quoted string. This string can have one, two, or three components, separated by the '|' character:

• cfg specifies the name of the configuration for the connection or socket. pw specifies the optional private key file password. DNShost specifies the fully qualified DNS hostname of a specific server, for use with the Server Name Indication (SNI) TLS extension.

  This configuration name is used only the first time I/O is performed after the OPEN or USE command. Subsequent invocations are ignored. /SSL="" or /TLS="" is ignored. For more information, see InterSystems TLS Guide.

• pw (optional) is the password for the local private key file. This is intended for interactive applications only, when a user is being prompted to enter the password at run time. It should not be used with a persistently stored password. Use the Security.SSLConfigs.PrivateKeyPassword property for persistent storage.

  IMPORTANT: The ability to include a password when opening a new or securing an existing TCP connection using SSL/TLS is for real-time interactive use only. You should never store a private key password persistently without protecting it. If you need to store such a password, use the PrivateKeyPassword property of the Security.SSLConfigsOpens in a new tab class.

• DNShost (optional) for SSL clients only, specifies the fully qualified DNS hostname of a specific server (for Server Name Indication). If you omit pw you must specify the placeholder '|' character.

  Server Name Indication (SNI) is a feature that allows the client to submit the hostname it's asking for to the server. This allows a server which handles multiple domains to select one of its multiple certificates to return. The server can select one which will match hostname checking on the client.

The following are examples of valid /TLS keyword parameters:

/TLS="Client"
/TLS="Client|password"
/TLS="Client||www.intersystems.com"
/TLS="Client|password|www.intersystems.com" 

Or:

/STR[=n]

Default: 0

Corresponds to the S mode parameter character, which specifies a stream mode of handling data that does not preserve TCP message boundaries. /STREAM and /STREAM=n for nonzero values of n enable S mode. /STREAM=n for a zero value of n disables S mode.

Deprecated. A synonym for /NOXY.

Default: Default receive buffer size

Set receive queue buffer size, in bytes. Can be used to increase the buffer size from the default value to support TCP protocol large windows. Large windows improve performance over links with long latencies or very high bandwidth. For appropriate values, consult your OS/hardware documentation.

Default: Default send buffer size

Set send queue buffer size, in bytes. Can be used to increase the buffer size from the default value to support TCP protocol large windows. Large windows improve performance over links with long latencies or very high bandwidth. For appropriate values, consult your OS/hardware documentation.

Or:

/TER=str

No default.

Corresponds to the terminators positional parameter, which establishes user-defined terminators.

Or:

/TMO[=n]

Default: 0

Corresponds to the T mode parameter character, which specifies CR, LF, and FF as standard read terminators. /TMODE and /TMODE=n for nonzero values of n enable T mode. /TMODE=n for a zero value of n disables T mode.

Or:

/TRA[=n]

Default: 1

/TRANSLATE or /TRANSLATE=n for nonzero values of n enable I/O translation for the device. /TRANSLATE=n for a zero value of n disables I/O translation for the device.

Default: 0

Corresponds to the W mode parameter character, which causes output buffers not to be flushed by the WRITE ! and WRITE # commands. Rather, flushing waits until the next WRITE *-3 command. /WAIT and /WAIT=n for nonzero values of n enable W mode. /WAIT=n for a zero value of n disables W mode.

Default: –1

Establishes a timeout (in seconds) for TCP write operations. If a write does not complete within n seconds, InterSystems IRIS issues a <TCPWRITE> error. If a <TCPWRITE> error is issued, your application should immediately close the TCP device to prevent data loss. InterSystems IRIS will not attempt a TCP write operation following a <TCPWRITE> error. The minimum n value is system-dependent. If n is smaller than the minimum timeout value for the platform, InterSystems IRIS uses the platform minimum. No n value should be less than 2. The default (-1) indicates no timeout is enforced.

Or:

/XYT[=name]

Default: If name is not specified, the default $X/$Y action table for the device is used.

Establishes a $X/$Y action table for the device. See /NOXY.

Default: 0

If /ZEROCOPY or /ZEROCOPY=1 is specified, enable the ZEROCOPY feature for this TCP device. ZEROCOPY supports multiple output buffers for the TCP device in order to take advantage of MSG_ZEROCOPY on send(); the TCP device cannot re-use the output buffer until the buffer has been acknowledged by notification from the TCP stack. To set the number of output buffers for the TCP device use the /OBCOUNT keyword. If /ZEROCOPY=0 is specified, disable the ZEROCOPY feature for this TCP device. MSG_ZEROCOPY is supported in Linux 4.15 and later. If the operating system does not support MSG_ZEROCOPY, the ZEROCOPY of the TCP device is always disabled.