Skip to main content

Settings for the TCP Inbound Adapters

Provides reference information for settings of the TCP inbound adapters.

Summary

The inbound TCP adapters have the following settings:

Group Settings
Basic Settings Call Interval, Port
Connection Settings Job Per Connection, Allowed IP Addresses, OS Accept Connection Queue Size, Stay Connected, Read Timeout, SSL Configuration, Local Interface
Additional Settings Accept Classnames, Charset

The remaining settings are common to all business services. For information, see “Settings for All Business Services” in Configuring Ensemble Productions.

Accept Classnames

Applies to EnsLib.TCP.CountedXMLInboundAdapterOpens in a new tab.

Comma-separated list, giving the names of classes that this adapter will instantiate from XML blocks received.

Allowed IP Addresses

Applies to all inbound TCP adapters.

A comma-separated list of remote IP addresses from which to accept connections. The adapter accepts IPV4 addresses, IPV6 addresses, or server names that the domain host controller can resolve. An optional :port designation is supported; so, for example, both of the following address formats are acceptable: 192.168.1.22 or 192.168.1.22:3298.

Note:

IP address filtering is a means to control access on private networks, rather than for publicly accessible systems. InterSystems does not recommend relying on IP address filtering as a sole security mechanism, as it is possible for attackers to spoof IP addresses.

If a port number is specified, connections from other ports will be refused.

If the string starts with an exclamation point (!) character, the inbound adapter initiates the connection rather than waiting for an incoming connection request. The inbound adapter initiates the connection to the specified address and then waits for a message. In this case, only one address may be given, and if a port is specified, it supersedes the value of the Port setting; otherwise, the Port setting is used.

Call Interval

Applies to all inbound TCP adapters.

Number of seconds that the adapter will listen for incoming data from its configured source, before checking for a shutdown signal from the Ensemble framework.

If the adapter finds input, it acquires the data and passes it to the business service. The business service processes the data, and then the adapter immediately begins waiting for new input. This cycle continues whenever the production is running and the business service is enabled and scheduled to be active.

The default CallInterval is 5 seconds. The minimum is 0.1 seconds.

Charset

Applies to EnsLib.TCP.CountedInboundAdapterOpens in a new tab, EnsLib.TCP.CountedXMLInboundAdapterOpens in a new tab, and EnsLib.TCP.TextLineInboundAdapterOpens in a new tab.

Specifies the character set of the inbound data. Ensemble automatically translates the characters from this character encoding. The setting value is not case-sensitive. Use Binary for binary files, or for any data in which newline and line feed characters are distinct or must remain unchanged, for example in HL7 Version 2 or EDI messages. Other settings may be useful when transferring text documents. Choices include:

  • Binary — Binary transfer (the default)

  • Ascii — Ascii mode FTP transfer but no character encoding translation

  • Default — The default character encoding of the local Ensemble server

  • Latin1 — The ISO Latin1 8-bit encoding

  • ISO-8859-1 — The ISO Latin1 8-bit encoding

  • UTF-8 — The Unicode 8-bit encoding

  • UCS2 — The Unicode 16-bit encoding

  • UCS2-BE — The Unicode 16-bit encoding (Big-Endian)

  • Any other alias from an international character encoding standard for which NLS (National Language Support) is installed in Ensemble

For background information on character translation in Caché, see “Localization Support” in the Caché Programming Orientation Guide.

Endian

Applies to EnsLib.TCP.CountedInboundAdapterOpens in a new tab and EnsLib.TCP.CountedXMLInboundAdapterOpens in a new tab.

A choice of Big or Little indicates the byte order of the 4-byte block count prefix. Big endian means the most significant byte (MSB) goes over the wire first; Little endian means the least significant byte (LSB) goes over the wire first. The default value for this string is Big.

Job Per Connection

Applies to all inbound TCP adapters.

When True, the adapter spawns a new job to handle each incoming TCP connection and allows simultaneous handling of multiple connections. When False, it does not spawn a new job for each connection. False is usually the appropriate choice for HL7 or X12 connections. The default is True.

For TCP services, JobPerConnection causes each new incoming socket connection to be handled by a freshly spawned job rather than by the listener job itself. Only one job at a time can be the listener, and one job must be the listener, so TCP services configured with PoolSize greater than 1 still only start one listener job. However, this listener can spawn an unlimited number of connection jobs if JobPerConnection is set to True. If the PoolSize setting is configured to a value greater than 1, it serves as a limit on the number of simultaneous connection jobs that can exist. When this limit is reached, the listener does not accept any more connections until one or more of the existing connection jobs quits or dies. An Event Log warning appears when it first reaches the limit.

Local Interface

Applies to all inbound TCP adapters.

Specifies the network interface through which the TCP connection should go. Select a value from the list or type a value. An empty value means use any interface.

OS Accept Connection Queue Size

Applies to all inbound TCP adapters.

Specifies the number of incoming connections the operating system should hold in reserve on behalf of this business service. Set to 0 if only 1 connection at a time is expected. Set to a large number if you expect many clients to connect rapidly. The default is 100. The range is 0–1000.

Port

Applies to all inbound TCP adapters.

Identifies the TCP port on the local machine where the adapter is listening for TCP requests. Avoid specifying a port number that is in the range used by the operating system for ephemeral outbound connections. See “Inbound Ports May Conflict with Operating System Ephemeral Ports” in the Ensemble Release Notes for more information.

QSize

Applies to EnsLib.TCP.CountedInboundAdapterOpens in a new tab, EnsLib.TCP.CountedXMLInboundAdapterOpens in a new tab, and EnsLib.TCP.TextLineInboundAdapterOpens in a new tab.

Specifies the number of incoming connections the operating system should hold in reserve on behalf of this business service. Set to 0 if only 1 connection at a time is expected. Set to a large number if many clients will connecting rapidly. The default is 100. The range is 0–1000.

Read Timeout

Applies to all TCP adapters.

Number of seconds to wait for each successive incoming TCP read operation, following receipt of initial data from the remote TCP port. The default is 5 seconds. The range is 0–600 seconds (a maximum of 10 minutes).

SSLConfig

Applies to all TCP adapters.

The name of an existing SSL/TLS configuration to use to authenticate this connection. Choose a client SSL/TLS configuration, because the adapter initiates the communication.

To create and manage SSL/TLS configurations, use the Management Portal. See the chapter “Using SSL/TLS with Caché” in the Caché Security Administration Guide. The first field on the Edit SSL/TLS Configuration form is Configuration Name. Use this string as the value for the SSLConfig setting.

Stay Connected

Applies to all TCP adapters.

Specifies how long the adapter stays connected to a remote system after an input event and determines how the adapter handles disconnections.

You can specify any of the following values:

  • A positive value—The adapter remains connected to the remote system for this number of seconds. Disconnections are not handled like errors.

  • 0—The adapter disconnects immediately. Disconnections are not handled like errors.

  • –1—The adapter is permanently connected, including during idle times. Disconnections are handled like errors.

    Note:

    Adapters auto-connect at startup only if the Stay Connected value is –1.

The default value is –1.

Important:

If you set Stay Connected to -1 and Job Per Connection to False, then the adapter may not detect disconnections caused by network occurrences. Specifically, the following situation may arise:

  1. The adapter accepts an incoming connection from a remote system.

    Recall that when Job Per Connection is set to False, the listener job on the adapter handles each incoming connection rather than spawning new jobs to do so.

  2. A network occurrence causes a disconnection, and the adapter does not receive a TCP FIN or RST packet to terminate the connection.

    For example, a firewall between the remote system and adapter may close the connection after a certain amount of time.

  3. The remote system attempts to reestablish the connection, but cannot connect to the listening socket on the adapter.

  4. The remote system generates errors and continuously attempts to reestablish the connection.

To remedy the situation, you must stop and then restart the business service that uses the adapter.

To prevent the situation, set Stay Connected to a value other than -1. For example, if you set Stay Connected to 300, the adapter disconnects after five minutes. Additionally, if you do not need the adapter to process requests in order, you can set Job Per Connection to True, enabling the adapter to process multiple incoming connection requests at one time.

FeedbackOpens in a new tab