TCPIPClientOutput node

Use the TCPIPClientOutput node to create a client connection to a raw TCP/IP socket, and to send data over that connection to an external application.

The TCPIPClientOutput node is available in the following operation modes:

Developer
Application Integration Suite
Standard
Advanced
Express
Adapter

For more information, see Operation modes.

This topic contains the following sections:

Purpose

The TCPIPClientOutput node opens connections to a remote server application that is listening on a TCP/IP port. The connections are not made directly by the node but are obtained from a connection pool managed by the IBM® Integration Bus integration server. The integration server uses the default TCPIPClient configurable service to determine which attributes are used for the socket connection. However, if the configurable service is set on the node, the configurable service is used for all the properties, including the host and port number.

You can configure the Integration node to use SSL for TCP/IP nodes; see SSL and the TCP/IP nodes.

The TCPIPClient configurable service is used to create a pool of client connections ready for processing. To use this function, the minimumConnections property must be set to a value larger than zero. The integration server ensures that the specified number of connections are always available by creating them at the start, and continuing to create the connections until the minimum value is reached.

The node requests a client connection, and, if no connections are available for sending data, the output node requests that the pool creates a new connection. If the maximumConnections property has not been exceeded, a new connection is created.

When the connection has been established, the data is sent. If the data has not been sent successfully within the time limit specified by the node's Timeout sending a data record property, an exception is thrown.

Properties in the local environment can override the TCP/IP connection used by the node:

Table 1. Input local environment properties
Location in local environment	Description
$LocalEnvironment/Destination/TCPIP/Output/Hostname	The host name used to make a connection.
$LocalEnvironment/Destination/TCPIP/Output/Port	The port number used to make a connection.
$LocalEnvironment/Destination/TCPIP/Output/Id	The ID of the socket being used. This value is an internal identifier used by IBM Integration Bus to uniquely identify a connection.
$LocalEnvironment/Destination/TCPIP/Output/ReplyId	The Reply ID that has been stored on this connection. It can be any text string.
$LocalEnvironment/Destination/TCPIP/Output/Timeout	The timeout value used when sending data to the TCP/IP client connection. This value overrides the Timeout sending a data record property specified on the node.

You can dynamically choose the connection details (host name and port number), and the connection used (ID), by using this property. You can also set the Reply ID on the connection. The Reply ID enables a string to be stored in the connection and to be seen in the local environment. You can use this connection to store Reply IDs from other TCPIP nodes or from other transports, such as WebSphere® MQ

The output of the node contains the same information as the input, and any fields that were missing from the input are updated with details from the connection used. For example, if the Id property is not provided as input (because you want to create a new connection or reuse a pool connection), the output local environment contains the ID of the connection that is used.

Table 2. Output local environment properties
Location in local environment	Description
$LocalEnvironment/WrittenDestination/TCPIP/Output/ConnectionDetails/Hostname	The host name used to make a connection.
$LocalEnvironment/WrittenDestination/TCPIP/Output/ConnectionDetails/Port	The port number used to make a connection.
$LocalEnvironment/WrittenDestination/TCPIP/Output/ConnectionDetails/OpenTimestamp	The time stamp when the connection was first opened.
$LocalEnvironment/WrittenDestination/TCPIP/Output/ConnectionDetails/CloseTimestamp	The time stamp when the connection was closed (null if not yet closed).
$LocalEnvironment/WrittenDestination/TCPIP/Output/ConnectionDetails/SequenceNumber	The sequence number of the message received on this connection. The first record has a sequencing number of 1; the second record has a sequencing number of 2, and so on.
$LocalEnvironment/WrittenDestination/TCPIP/Output/ConnectionDetails/Id	The ID of the socket being used. This ID is an internal identifier used by IBM Integration Bus to uniquely identify a connection.
$LocalEnvironment/WrittenDestination/TCPIP/Output/ConnectionDetails/ReplyId	The Reply ID that has been stored on this connection. It can be any text string.

If the connection closes (or any other type of exception occurs) while using the TCP/IP transport, an exception is thrown. This exception goes to the Failure terminal if it is connected, otherwise the exception returns back down the flow.

The node also has a Close input terminal. If a message is sent to this terminal, the connection is closed using a combination of the details provided in the node and the local environment.

The TCPIPClientOutput node is contained in the TCPIP drawer of the palette and is represented in the workbench by the following icon:

TCPIPClientOutput node icon

Using the TCPIPClientOutput node in a message flow

The TCPIPClientOutput node can be used in any message flow that needs to send data to an external application.

Terminals and properties

The TCPIPClientOutput node terminals are described in the following table.

Terminal	Type	Description
In	Input data	The input terminal that accepts a message for processing by the node.
Close	Input control	The input terminal to which a message is routed when the connection given in the local environment is closed.
Out	Output data	The output terminal to which the message is routed if it is successfully sent to an external resource. The message received on the In terminal is propagated to the Out terminal and is left unchanged except for the addition of status information.
Close	Output control	The output terminal to which a message propagated from the Close input terminal is routed.
Failure	Output data	The output terminal to which the message is routed if a failure is detected in the node.

The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the BAR file to deploy it).

The Description properties of the TCPIPClientOutput node are described in the following table:

Property	M	C	Default	Description
Node name	No	No	TCPIPClientOutput	The name of the node.
Short description	No	No		A brief description of the node.
Long description	No	No		Text that describes the purpose of the node in the message flow.

The Basic properties of the TCPIPClientOutput node are described in the following table:

Property	M	C	Default	Description	mqsiapplybaroverride command property
Connection details	Yes	Yes		A string containing either the host name and port number to be used, or the name of a TCPIPClient configurable service.	connectionDetails
Timeout sending a data record (seconds)	Yes	Yes	60	Specifies how long the node waits when attempting to send data. You can specify any length of time in seconds.	timeoutSendingData

The Advanced properties of the TCPIPClientOutput node are described in the following table.

Property	M	C	Default	Description
Close connection	Yes	No	No	Controls when the connection is closed, or if it remains open. Valid options are: No After Timeout After Data has been Sent
Close output stream after a record has been sent	Yes	No	Cleared	Specifies whether to close the output stream as soon as the data has been sent. This property is not selected by default.
Output Stream Modification	No	No	Leave unchanged	Specifies whether to reserve this output stream or release it and return it to the pool for use by any output node. Valid options are: Leave unchanged Release output stream Reserve output stream (for use by future TCPIP nodes) Reserve output stream (for use by future TCPIP nodes) then release at end of flow
Input Stream Modification	No	No	Leave unchanged	Specifies whether to reserve the input stream for use only by input and receive nodes that specify the connection ID, or to release it at the end of the message flow. Valid options are: Leave unchanged Release input stream Reserve input stream (for use by future TCPIP nodes) Reserve input stream (for use by future TCPIP nodes) then release at end of flow When the connection input stream is reserved, no other nodes can use it without specifying the correct connection ID. If the input stream is released after the message has been propagated, it is returned to the pool and becomes available for use by any input or receive node.
Send to:	Yes	No	One Connection	Specifies whether the data is to be sent to one connection or to available connections. Valid options are: One Connection All Available Connections

The Request properties of the TCPIPClientOutput node are described in the following table:

Property	M	C	Default	Description
Data location	Yes	No	$Body	The location in the input message tree containing the record to be written.
Hostname location	Yes	No	$LocalEnvironment/Destination/TCPIP/Output/Hostname	The message element location containing the host name.
Port location	Yes	No	$LocalEnvironment/Destination/TCPIP/Output/Port	The message element location containing the port.
ID location	Yes	No	$LocalEnvironment/Destination/TCPIP/Output/Id	The message element location containing the ID.
Reply ID location	Yes	No	$LocalEnvironment/Destination/TCPIP/Output/ReplyId	The message element location containing the reply ID.

The Records and Elements properties of the TCPIPClientOutput node are described in the following table:

Property	M	C	Default	Description
Record definition	Yes	No	Record is Unmodified Data	This property controls how the records derived from the message are written. Valid options are: Record is Unmodified Data Record is Fixed Length Data Record is Delimited Data
Length (bytes)	Yes	No	0	The required length of the output record. This property applies only when Record is Fixed Length Data is specified in Record definition.
Padding byte (hexadecimal)	Yes	No	20	The two-digit hexadecimal byte to be used to pad short messages when Record is Fixed Length Data is specified in Record definition.
Delimiter	Yes	No	Broker System Line End	The delimiter to be used when Record is Delimited Data is specified in Record definition. Valid options are: Broker System Line End Custom Delimiter (Hexadecimal)
Custom delimiter (hexadecimal)	No	No	None	The delimiter byte sequence to be used when Record is Delimited Data is specified in the Record definition property and Custom Delimiter (Hexadecimal) is specified in the Delimiter property.
Delimiter type	Yes	No	Postfix	This property specifies the way in which the delimiters are to be inserted between records when Record is Delimited Data is specified in Record definition. Valid options are: Infix Postfix

The Validation properties of the TCPIPClientOutput node are described in the following table.

For a full description of these properties, see Validation properties.

Property	M	C	Default	Description	mqsiapplybaroverride command property
Validate	No	Yes	Inherit	This property controls whether validation takes place. Valid values are: None Content and Value Content Inherit	validateMaster
Failure action	No	No	Exception	This property controls what happens if validation fails. You can set this property only if you set Validate to Content or Content and Value. Valid values are: User Trace Local Error Log Exception Exception List

The Monitoring properties of the node are described in the following table.

Property	M	C	Default	Description
Events	No	No	None	Events that you have defined for the node are displayed on this tab. By default, no monitoring events are defined on any node in a message flow. Use Add, Edit, and Delete to create, change or delete monitoring events for the node; see Configuring monitoring event sources by using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box.