Using TCP Adapters with Ensemble
Settings for the TCP Inbound Adapters
[Home]  [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

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.CountedXMLInboundAdapter.
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 named IP addresses, IPV4 addresses, or IPV6 addresses. 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.CountedInboundAdapter, EnsLib.TCP.CountedXMLInboundAdapter, and EnsLib.TCP.TextLineInboundAdapter.
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:
For background information on character translation in Caché, see Localization Support in the Caché Programming Orientation Guide.
Endian
Applies to EnsLib.TCP.CountedInboundAdapter and EnsLib.TCP.CountedXMLInboundAdapter.
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.CountedInboundAdapter, EnsLib.TCP.CountedXMLInboundAdapter, and EnsLib.TCP.TextLineInboundAdapter.
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.
If StayConnected is a positive value, the adapter stays connected to the remote system for this number of seconds between input events. A zero value means to disconnect immediately after every input event. The default of –1 means to stay permanently connected, even during idle times. Adapters are assumed idle at startup and therefore only auto-connect if they are configured with a StayConnected value of –1.
The value of StayConnected controls how the TCP adapter treats disconnections. If StayConnected has a value of –1, the TCP adapter treats a disconnection as an error. If it has a value of 0 or a positive integer, the TCP adapter does not consider a disconnection an error.