A TCP listener provides TCP server socket support at a specific port within the node. The socket will accept connections and receive messages from a TCP client application. The TCP client application will send messages to the TCP listener in an XML format and ASCII delimited messages. TCP listeners can receive the messages on the server socket, format the messages internally, and then use the contents of the message to execute a trigger. The results of the trigger execution and the values of any requested device variables can optionally be returned to the TCP client application that sent the message.
A TCP listener is different than other listeners because the TCP listener acts as a server application accessible by various client applications. Other listeners such as WMQ listeners and JMS listener types are clients that connect to message brokers who funnel messages to the listener component. For TCP listeners, the Transaction Server will create a server application that will accept and deny connection requests from outside clients. The TCP listener will receive and validate any messages that are sent to it once a connection is established.
A TCP listener is created much like other listeners but have parameters that support inbound messages sent across a TCP connection.
TCP Client programming
If the TCP client you are using to send a request to the TCP Listener is using a Connect/Send/Disconnect pattern without waiting for a reply, you will need to ensure that you call a shutdown/flush on the socket prior to closing it. This allows the TCP stack to send all the data frames before initiating the close of the connection. If this is not done the TCP listener may not receive the entire request in case the request payload is large enough to span multiple Ethernet frames.
To create a TCP listener, follow these steps:
- From the Workbench left pane, expand the node that you want to add the listener to.
- Expand Enterprise, right-click the
Listeners icon to display its pop-up
menu, and then click New.
The Listener window appears. - Use the Name box to type a unique name for the listener. The name can be up to 64 characters in length and can include letters, numbers, and the underscore character. Spaces are not allowed.
- Click the Listener Type down-arrow, and then select TCP.
The Listener window changes to accommodate the TCP
listener.
The following describes the parameter values to create a TCP listener.
| Parameter | Description |
|---|---|
| Port | This is the port on the node that the TCP listener will be listening on. |
| Max Msg Size (KB) | The parameter indicates a size at which the listener should reject a message and report back an error to the TCP client application.The default setting for this parameter is 1 KB. The setting for this parameter will protect the system when a client application maliciously sends data or sends data that is missing termination characters. |
| Max Connections | The default value is 1 connection. The TCP listener is designed to allow multiple client applications to connect to it at one time. This parameter will determine how many concurrent connections a particular TCP listener will allow. Subsequent client application connection requests received by the TCP listener will be rejected once the maximum number of connections has been reached. Connections will become available when client applications close their connection with the listener. |
| Msg Timeout (Sec) | This parameter provides a means for
the system to close a socket that is
waiting for the end of a transmission.
For example, suppose a TCP listener
began to receive a message from a
client application and the transmission
of the message stopped prior to
receiving the termination characters.
For that example, the TCP listener has
received a partial message and could be
caught waiting endlessly for additional
characters that might not be coming.
Rather then having the connection wait
endlessly, a timeout value can be set
that will cause the connection to the
client application to close in this
partial transmission situation. An
error condition for this TCP listener
will be reported if the timeout value
is reached. The value for this parameter will be represented as the number of seconds between a message pause that the system will wait. The default value is 60 seconds. The smallest this value is 30 seconds and the largest this value should be is 300 seconds (5 minutes). |
| Filter Addresses | |
| New Subnet | In the New Subnet
box, type the IP address, and then
click Add. You can
also type an optional subnet
address. To delete an address, select it, and then click Remove. |
| Defined Subnets | This parameter will contain a list
of allowable IP addresses and subnet
masks that will provide the ability to
restrict access to the TCP listener to
only those addresses that are defined
in this parameter. The TCP listener will create a server socket that will be available for the client application to connect to.The default behavior is to allow all connections to access this socket.  From the Defined Subnets pane, select the address, and then click Allow or Deny. For more information, see Allowing and Denying access to the subnet for the TCP listener. |
| Send reply message | This parameter indicates whether or
not the TCP listener will be sending a
reply message to the client
application. Select the Send reply message check box to set the TCP listener to reply to all incoming messages. By default, the check box is selected Clear the check box to set the TCP listener to not send a reply message. |
| Encoding | This is the UTF encoding scheme used
to translate the ASCII bytes
received. |
Related topics
What's Inside