TCPIPServerReceive node

Use the TCPIPServerReceive node to receive data over a server TCP/IP connection.

The TCPIPServerReceive 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:

For information about configuring the TCPIPServerReceive node, see Configuring the TCPIPServerReceive node.

Purpose

The TCPIPServerReceive node waits for data to be received on a TCP/IP connection, and retrieves the data. If the connection is closed, an exception is thrown.

When a connection is established, the data is sent to the TCPIPServerReceive node. If the TCPIPServerReceive node fails to receive all the data within the time specified in the Timeout waiting for a data record property, the message is sent to the Timeout terminal; if no Timeout terminal is connected, an exception is thrown.

You can configure the Integration node 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.

Table 1. Input local environment properties
Location in local environment for input to node	Description
$LocalEnvironment//TCPIP/Receive/Hostname	The host name used to make a connection.
$LocalEnvironment//TCPIP/Receive/Port	The port number used to make a connection.
$LocalEnvironment/TCPIP/Receive/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/TCPIP/Receive/ReplyId	The Reply ID to be stored on this connection. This ID can then be used when data is returned on an input node. The Reply ID can be any text string.
$LocalEnvironment/TCPIP/Receive/Timeout	The timeout value used when waiting for data on the TCP/IP server connection. This value overrides the Timeout waiting for a data record property specified on the node.
$LocalEnvironment/TCPIP/Receive/Length	The value used to override the number of bytes to be read when using fixed size records. This value overrides the Length (bytes) property specified on the node. If the Record detection property is set to anything other than Fixed Length, the local environment field is ignored. If this field is not present or evaluates to null, it is ignored and the value on the node is used.

These properties enable the connection details (host name and port number) and the connection used (ID) to be selected dynamically. 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. In this way, you can store Reply IDs from other TCPIP nodes or from other transports, such as WebSphere® MQ.

When a record has been retrieved, the ConnectionDetails field in the local environment tree is populated with the details of the connection that is being used.

Table 2. Output local environment properties
Location in local environment for output from node	Description
$LocalEnvironment/TCPIP/Receive/ConnectionDetails/Type	The Server.
$LocalEnvironment/TCPIP/Receive/ConnectionDetails/Hostname	The host name used to make a connection.
$LocalEnvironment/TCPIP/Receive/ConnectionDetails/Port	The port number used to make a connection.
$LocalEnvironment/TCPIP/Receive/ConnectionDetails/OpenTimestamp	The time stamp when the connection was first opened.
$LocalEnvironment/TCPIP/Receive/ConnectionDetails/CloseTimestamp	The time stamp when the connection was closed (null if not yet closed).
$LocalEnvironment/TCPIP/Receive/ConnectionDetails/SequenceNumber/InputRecord	The sequence number of the message that is received on this connection. The first record has a sequencing number of 1; the second record is 2; and so on.
$LocalEnvironment/TCPIP/Receive/ConnectionDetails/SequenceNumber/OutputRecord	The sequence number of the message that is sent on this connection. The first record has a sequencing number of 1; the second record is 2; and so on.
$LocalEnvironment/TCPIP/Receive/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/TCPIP/Receive/ConnectionDetails/ReplyId	The Reply ID that is stored on this connection. It can be any text string.
$LocalEnvironment/TCPIP/Receive/ConnectionDetails/ClientDetails/Hostname	The fully qualified domain name of the computer from which the client connected.
$LocalEnvironment/TCPIP/Receive/ConnectionDetails/ClientDetails/Address	The IP address of the computer from which the client connected.

The TCPIPServerReceive node is contained in the TCPIP drawer of the palette, and is represented in the IBM Integration Toolkit by the following icon:

Message structure

The TCPIPServerReceive node handles messages in the following message domains:

DFDL
XMLNSC
DataObject
JSON
BLOB
MIME
MRM
JMSMap
JMSStream
XMLNS

Terminals and properties

The terminals of the TCPIPServerReceive node are described in the following table.

Terminal	Description
In	The input terminal that accepts a message for processing by the node.
Out	The output terminal to which the message is routed if it is successfully retrieved from an external resource. If no errors occur within the input node, a message received from an external resource is always sent to the Out terminal first.
Timeout	The terminal to which a message is sent when the time specified in the Timeout waiting for a data record property has been exceeded. The message text is `Timeout value is exceeded`.
Failure	The output terminal to which the message is routed if an error occurs. These errors include failures caused by retry processing. Even if the Validation property is set, messages propagated to this terminal are not validated.

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 TCPIPServerReceive node are described in the following table.

Property	M	C	Default	Description
Node name	No	No	TCPIPServerReceive	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 TCPIPServerReceive node determine how the TCP/IP connection is controlled, and 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 TCPIPServer configurable service. The following formats are supported: Configurable service name. This value is used to look up the port and host name 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.	connectionDetails
Timeout waiting for a data record (seconds)	Yes	Yes	60	Specifies how long the node listens on a connection for more data after the first byte of data has arrived. You can specify any length of time in seconds. The default is 60 seconds. When the specified time has been exceeded, all available data is sent to the Failure terminal.	timeoutWaitingForData

The Advanced properties of the TCPIPServerReceive node determine how the data stream is controlled, and 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: 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 received to close the connection when the end of the record is found.
Close input stream after a record has been received	Yes	No	Cleared	Specifies whether to close the input stream as soon as the data has been retrieved. When the connection input stream is reserved, no other node can use it without knowing the ID. By default this property is not selected.
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: 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.
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. 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.

The Request properties of the TCPIPServerReceive node 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 run by clicking Edit to the right of each property. The Request properties are described in the following table:

Property	M	C	Default	Description
Port location	Yes	No	$LocalEnvironment/TCPIP/Receive/Port	The message element location that contains the Port. 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/TCPIP/Receive/Port.
ID location	Yes	No	$LocalEnvironment/TCPIP/Receive/Id	The message element location that contains the ID. Specify the location of the Id of the socket that is being used. This internal identifier is used by IBM Integration Bus to uniquely identify a connection. If you do not specify a location, the default value is $LocalEnvironment/TCPIP/Receive/Id.
Reply ID location	Yes	No	$LocalEnvironment/TCPIP/Receive/ReplyId	The message element location that contains the Reply ID. Specify the location of the Reply ID that is stored on the connection 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/TCPIP/Receive/ReplyId.
Record length location	No	No	$LocalEnvironment/TCPIP/Receive/Length	The message element location that contains the record length to be read. Specify the location of the value to override the Length (bytes) property on the Records and elements tab. If you do not specify a location, the default value is $LocalEnvironment/TCPIP/Receive/Length.

The Result properties of the TCPIPServerReceive node determine where the reply is to be stored, and are described in the following table:

Property	M	C	Default	Description
Output data location	No	No	$OutputRoot	The start location in the output message tree where the parsed elements from the bit string of the message are stored. See Combining a result message with an input message when fetching data from external systems.
Copy local environment	No	No	Selected	Specifies whether the local environment is copied to the output message. If Copy local environment is selected, a new copy of the local environment is created in the tree, and it is populated with the contents of the local environment from the preceding node. Therefore, that if a node changes the local environment, the upstream nodes are not affected by those changes because they have their own copies. This value is the default. If Copy local environment is not selected, the node does not generate its own copy of the local environment, but uses the local environment that is passed to it by the preceding node. Therefore, if a node changes the local environment, the changes are reflected by the upstream nodes.

The Input Message Parsing properties of the TCPIPServerReceive node determine how to parse the incoming message.

If the incoming message has an MQRFH2 header, you do not have to set values for the Input Message Parsing properties because the values are derived from the <mcd> folder in the MQRFH2 header; for example:

<mcd><Msd>MRM</Msd><Set>DHM4UO906S001</Set><Type>receiptmsg1</Type>
<Fmt>XML</Fmt></mcd>

If you set values, and if they differ from the values in the MQRFH2 header, the values in the MQRFH2 header take precedence.

The TCPIPServerReceive node Input Message Parsing properties are described in the following table.

Property	M	C	Default	Description	mqsiapplybaroverride command property
Message domain	No	No	BLOB	The domain that is used to parse the incoming message.
Message model	No	No		The name or location of the message model in which the incoming message is defined.
Message	No	No		The name or location of a global element that models an entire document of data, and is contained in your message model schema file. This list is populated with all available messages that are defined in the Message model that you have selected.
Physical Format	No	No		The name of the physical format of the incoming message.
Message coded character set ID	Yes	No	Broker System Default	The ID of the coded character set used to interpret the data being read.	messageCodedCharSetIdProperty
Message encoding	Yes	No	Broker System Determined	The encoding scheme for numbers and large characters used to interpret the data being read. Valid values are Broker System Determined or a numeric encoding value. For more information about encoding, see Data conversion.	messageEncodingProperty

The Parser Options properties of the TCPIPServerReceive node are described in the following table.

Property	M	C	Default	Description
Parse timing	No	No	On Demand	This property controls when an input message is parsed. Valid values are: On Demand Immediate Complete Parse timing is, by default, set to On Demand, which causes parsing of the message to be delayed. To cause the message to be parsed immediately, see Parsing on demand.
Build tree using XML schema data types	No	No	Cleared	This property controls whether the syntax elements in the message tree have data types taken from the XML Schema.
Use XMLNSC compact parser for XMLNS domain	No	No	Cleared	This property controls whether the XMLNSC Compact Parser is used for messages in the XMLNS Domain. If you set this property, the message data is displayed under XMLNSC in nodes that are connected to the output terminal when the input MQRFH2 header or Input Message Parsing property, Message Domain, is XMLNS.
Retain mixed content	No	No	Cleared	This property controls whether the XMLNSC parser creates elements in the message tree when it encounters mixed text in an input message. If you select the check box, elements are created for mixed text. If you clear the check box, mixed text is ignored and no elements are created.
Retain comments	No	No	Cleared	This property controls whether the XMLNSC parser creates elements in the message tree when it encounters comments in an input message. If you select the check box, elements are created for comments. If you clear the check box, comments are ignored and no elements are created.
Retain processing instructions	No	No	Cleared	This property controls whether the XMLNSC parser creates elements in the message tree when it encounters processing instructions in an input message. If you select the check box, elements are created for processing instructions. If you clear the check box, processing instructions are ignored and no elements are created.
Opaque elements	No	No	Blank	This property is used to specify a list of elements in the input message that are to be opaquely parsed by the XMLNSC parser.

The Records and Elements properties of the TCPIPServerReceive node specify how the data is interpreted as records, and are described in the following table:

Property	M	C	Default	Description
Record detection	Yes	No	Connection Closed	The mechanism used to identify records in the input data. Valid options are: Connection Closed Fixed Length Delimited Parsed Record Sequence
Length (bytes)	Yes	No	0	The length of each record, in bytes, when Fixed Length record detection is selected.
Delimiter	Yes	No	DOS or UNIX Line End	The type of delimiter bytes that separate, or ends, each record when Delimited record detection is selected. Valid options are: DOS or UNIX Line End Custom Delimiter (Hexadecimal)
Custom delimiter (hexadecimal)	No	No		The delimiter bytes, expressed in hexadecimal, when Delimited record detection and Custom Delimiter (Hexadecimal) are selected. This property is mandatory only if the Delimiter property is set to Custom Delimiter (Hexadecimal).
Delimiter type	Yes	No	Postfix	The location of the delimiter when Delimited record detection and Custom Delimiter (Hexadecimal) are selected. Valid options are: Infix Postfix This property is ignored unless the Delimiter property is set to Custom Delimiter (Hexadecimal).

The Validation properties of the TCPIPServerReceive 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	None	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.