See information about the latest product version
TCPIPServerOutput node
Use the TCPIPServerOutput node to create a server connection to a raw TCP/IP socket, and to send data over the connection to an external application.
Purpose
The TCPIPServerOutput node listens on a TCP/IP port and waits for a client node to make a connection with the port. When the client node connects to the port, the server node creates a connection for the client. The connections are not made directly by the node but are obtained from a connection pool managed by the WebSphere® Message Broker execution group.
The execution group uses the default TCPIPServer 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.
When the connection has been established, the data is sent. If the data is not sent successfully within the time limit specified by the node's Timeout sending a data record property, an exception is thrown.
You can configure the broker to use SSL for TCP/IP nodes; see SSL and the TCP/IP nodes.
Properties in the local environment can override the TCP/IP connection used by the node.
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 ID is an internal identifier used by WebSphere Message Broker to uniquely identify a connection. |
$LocalEnvironment/Destination/TCPIP/Output/ReplyId | The Reply ID that is 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 server connection. This value overrides the Timeout sending a data record property specified on the node. |
You can dynamically select the connection details (host name and port number), and the connection used (ID), using these properties. The Reply ID can also be set on the connection, which enables a string to be stored in the connection and to be displayed in the local environment. This behavior can be used 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 are 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 connection or reuse a pool connection), the output local environment contains the ID of the connection that is used.
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 1, the second record has a sequencing number 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 WebSphere Message Broker to uniquely identify a connection. |
$LocalEnvironment/WrittenDestination/TCPIP/Output/ConnectionDetails/ReplyId | The Reply ID that is stored on this connection. It can be any text string. |
$LocalEnvironment/WrittenDestination/TCPIP/Output/ConnectionDetails/ClientDetails/Hostname | The fully qualified domain name of the computer from which the client connected. |
$LocalEnvironment/WrittenDestination/TCPIP/Output/ConnectionDetails/ClientDetails/Address | The IP address of the computer from which the client connected. |
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 goes back down the message 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 TCPIPServerOutput node is contained in the TCPIP drawer of the palette and is represented in the workbench by the following icon:
Using the TCPIPServerOutput node in a message flow
You can view information about samples only when you use the information center that is integrated with the WebSphere Message Broker Toolkit or the online information center. You can run samples only when you use the information center that is integrated with the WebSphere Message Broker Toolkit.
Configuring the TCPIPServerOutput node
When you have put an instance of the TCPIPServerOutput node into a message flow, you can configure it (for more information, see Configuring a message flow node). The properties of the node are displayed in the Properties view. All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk in that view.
To configure the TCPIPServerOutput node:
- Optional: On the Description tab, enter a short description, a long description, or both. You can also rename the node on this tab.
- On the Basic tab, set the properties that
determine how the TCP/IP connection is controlled.
- Use the Connection details property
to specify the port number to be used, or the name of a configurable
service. This property is mandatory. The following formats are supported:
- Configurable service name. This value is used to look up the port number in configurable services; for example, TCPIPProfile1.
- <Port>. This value is the port number; for example, 1111
- <Port>. This value is the port number. In this case the host name is assumed to be localhost.
- Use the Timeout sending a data record (seconds) property to specify how long the node waits when trying to send data. You can specify any length of time in seconds. When the specified time has been exceeded, all available data is sent to the Failure terminal. The default is 60 seconds.
- Use the Connection details property
to specify the port number to be used, or the name of a configurable
service. This property is mandatory. The following formats are supported:
- On the Advanced tab, set the properties
that determine how the data stream is controlled.
- Use the Send to property
to specify whether the data is to be sent to one connection or to
all available connections.
- Select One connection to send the message to only one connection, as specified by the node properties and message overrides. This value is the default.
- Select All available connections to send the data to all available connections.
- Use the Close connection property
to specify when and how to close the connection.
- Select No to leave the connection open. This value is the default.
- Select After timeout to close the connection when a timeout occurs.
- Select After data has been sent to close the connection when the end of the record has been sent.
- Select Close output stream after a record has been sent to close the output stream as soon as the data has been sent. By default, this property is not selected.
- Use the Output Stream Modification property
to specify whether to reserve or release the output stream. These
options are available only if you have not selected the Close output stream after a record has
been sent property.
- Select Leave unchanged to leave the output stream as it was when it entered the node. This value is selected by default.
- Select Release output stream to specify that this output stream is returned to the pool and is available for use by any output node.
- Select Reserve output stream (for use by future TCPIP output nodes) to specify that this output stream can be used only by this node and by other output nodes that request it by specifying the connection ID. When the connection input stream is reserved, no other nodes can use it without specifying the correct connection ID.
- Select Reserve output stream (for use by future TCPIP output nodes) then release after propagate to specify that this output stream can be used only by this node and output nodes that request it by specifying the correct connection ID. After the message has been propagated, this output stream is returned to the pool and becomes available for use by any output node.
- Use the Input Stream Modification property
to reserve the input stream for use only by input and receive nodes
that specify the connection ID, or to release the input stream at
the end of the message flow.
- Select Leave unchanged to leave the input stream as it was when it entered the node. This value is selected by default.
- Select Release input stream to specify that this input stream is returned to the pool and is available for use by any input or receive node.
- Select Reserve input stream (for use by future TCPIP input and receive nodes) to specify that this input stream can be used only by this node and by other input or receive nodes that request it by specifying the connection ID. When the connection input stream is reserved, no other nodes can use it without specifying the correct connection ID.
- Select Reserve input stream (for use by future TCPIP input and receive nodes) then release after propagate to specify that this input stream can be used only by this node and receive nodes that request it by specifying the correct connection ID. After the message has been propagated, this input stream is returned to the pool and becomes available for use by any input or receive node.
- Use the Send to property
to specify whether the data is to be sent to one connection or to
all available connections.
- On the Request tab, specify
the location of the data to be written. You can specify the properties
on this tab as XPath or ESQL expressions. Content Assist is available
in the Properties view and also in the XPath Expression Builder, which
you can call by using the Edit button to the
right of each property.
- In Data location, specify
the input data location, which is the location in the input message
tree that contains the record to be written. The default value is $Body, which is the entire message
body ($InputRoot.Body). When you specify this property, if the data in the message tree that it identifies is owned by a model-driven parser (such as the MRM parser or XMLNSC parser,) be aware of the following considerations:
- If you are using MRM CWF format, ensure that the identified message tree exists as a message definition. If this message tree is defined as a global element only, exceptions BIP5180 and BIP5167 are generated.
- If you are using MRM TDS format, the serialization of the identified
message is successful if the element is defined as a global element
or message. However, if the identified field is not found as a global
element or message, note that:
- If this field is a leaf field in the message tree, the field is written as self-defining. No validation occurs even if validation is enabled.
- If this field is a complex element, an internal exception is generated, BIP5522, indicating that the logical type cannot be converted to a string.
- If you are using MRM XML, the events are similar to the MRM TDS format except that, if the field is a complex element, it is written as self-defining.
- If you use the XMLNSC parser, no validation occurs, even if validation is enabled.
- In Port location, specify the location of the value to override the Port that is set in the Connection details property of the Basic tab. If you do not specify a location, the default value is $LocalEnvironment/Destination/TCPIP/Output/Port.
- In ID location, specify the location of the Id of the socket being used. This internal identifier is used by WebSphere Message Broker to uniquely identify a connection. If you do not specify a location, the default value is $LocalEnvironment/Destination/TCPIP/Output/Id.
- In Reply ID location, specify the location of the Reply ID that is stored on the connection that is being used. The Reply ID can be used when data is returned in an input node. If you do not specify a location, the default value is $LocalEnvironment/Destination/TCPIP/Output/ReplyId.
- In Data location, specify
the input data location, which is the location in the input message
tree that contains the record to be written. The default value is $Body, which is the entire message
body ($InputRoot.Body).
- Use the Records and Elements tab to specify
how the TCPIPServerOutput node
writes the record that is derived from the message.
- In Record definition,
choose from the following values:
- Record is Unmodified Data specifies that records are left unchanged. This value is the default.
- Record is Fixed Length Data specifies that records are padded to a specified length if necessary. You specify this length in the Length property. If the record is longer than the value specified in Length, the node generates an exception. Use the Padding byte property to specify the byte to be used for padding the message to the required length.
- Record is Delimited Data specifies that records are separated by a delimiter and accumulated by concatenation. The delimiter is specified by the Delimiter, Custom delimiter, and Delimiter type properties. The file is finished only when a message is received on the Finish File terminal.
- In Length, specify the length (in bytes) of records when Record definition is set to Record is Fixed Length Data. Records longer than this value cause an exception to be thrown. This value must be in the range 1 byte through 100 MB. The default is 80 bytes.
- When Record definition is set to Record is Fixed Length Data, use Padding byte to specify the byte to be used when padding records to the specified length if they are shorter than this length. Specify this value as two hexadecimal digits. The default value is X'20'.
- In Delimiter, specify
the delimiter to be used if you set Record
definition to Record
is Delimited Data. Choose from:
- Broker System Line End specifies that a line end sequence of bytes is used as the delimiter as appropriate for the file system on which the broker is running. This value is the default. For example, on Windows systems, this line end is a 'carriage-return, line-feed' pair (X'0D0A'); on UNIX systems, it is a single 'line-feed' byte (X'0A'); on z/OS® systems, it is a 'newline' byte (X'15').
- Custom Delimiter specifies that the explicit delimiter sequence defined in the Custom delimiter property is to be used to delimit records.
- In Custom delimiter, specify the delimiter sequence of bytes to be used to delimit records when Delimiter is set to Custom Delimiter. Specify this value as an even-numbered string of hexadecimal digits. The default is X'0A' and the maximum length of the string is 16 bytes.
- If you set Record definition to Record is Delimited Data, use Delimiter type to specify how the
delimiter is to separate records. Choose from the following values:
- Postfix specifies that the delimiter is added after each record that is written. This value is the default.
- Infix specifies that the delimiter is inserted between any two adjacent records only.
- In Record definition,
choose from the following values:
- On the Validation tab, specify the parser validation properties of the node. For more information about validation, see Validating messages. For information about how to provide validation for this tab, see Validation tab properties.
Terminals and properties
The TCPIPServerOutput 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 for deployment).
Property | M | C | Default | Description |
---|---|---|---|---|
Node name | No | No | TCPIPServerOutput | 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 TCPIPServerOutput node are described in the following table:
Property | M | C | Default | Description | mqsiapplybaroverride command property |
---|---|---|---|---|---|
Connection details | Yes | Yes | A string containing the port number to be used, or the name of a configurable service. | connectionDetails | |
Timeout sending a data record (seconds) | Yes | Yes | 60 | Specifies how long the node waits when trying to send data. You can specify any length of time in seconds. | timeoutSendingData |
The Advanced properties of the TCPIPServerOutput 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:
|
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. By default, this property is not selected. |
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:
|
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 the input stream at the end of the flow. Valid options
are:
|
Send to: | Yes | No | One connection | Specifies whether the data is to be sent to
one connection or to all available connections. Valid options are:
|
The Request properties of the TCPIPServerOutput node are described in the following table:
Property | M | C | Default | Description |
---|---|---|---|---|
Data location | Yes | No | $Body | The location in the input message tree that contains the record to be written. |
Port location | Yes | No | $LocalEnvironment/Destination/TCPIP/Output/Port | The message element location that contains the port. |
ID | Yes | No | $LocalEnvironment/Destination/TCPIP/Output/Id | The message element location that contains the ID. |
Reply ID location | Yes | No | $LocalEnvironment/Destination/TCPIP/Output/ReplyId | The message element location that contains the Reply ID. |
The Records and Elements properties of the TCPIPServerOutput 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:
|
Length (bytes) | Yes | No | 0 | The required length of the output record. This property applies only when Record definition is set to Record is Fixed Length Data. |
Padding byte (hexadecimal) | Yes | No | 20 | The two-digit hexadecimal byte to be used to pad short messages when Record definition is set to Record is Fixed Length Data. |
Delimiter | Yes | No | Broker System Line End | The delimiter to be used when Record definition is set to Record is Delimited Data. Valid
options are:
|
Custom delimiter (hexadecimal) | No | No | None | The delimiter byte sequence to be used when Record definition is set to Record is Delimited Data and Delimiter is set to Custom Delimiter (Hexadecimal). |
Delimiter type | Yes | No | Postfix | This property specifies the way
in which the delimiters are inserted between records when Record definition is set to Record is Delimited Data. Valid
options are:
|
The Validation properties of the TCPIPServerOutput 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:
|
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:
|
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 using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box. |