TCP_RECEIVE

Type	Function block
Description	The function block is used to receive data via TCP (Transmission Control Protocol) from a TCP-capable Ethernet device. This is done using an IP socket. The socket must first be opened using the TCP_SOCKET function block before data can be received. If the EN_R input (EN_R - ENable_Receive) is TRUE, the function block receives data. If data has been successfully received, the NDR output (NDR = New Data Received) is set to TRUE for each cycle in which the specified amount of data has been copied to the DATA buffer. If EN_R is still set to TRUE and new data is received in the next cycle, NDR remains TRUE and the new data is copied to the variable connected to the DATA parameter. If no new data is received, NDR is set to FALSE. The device from which data are received is indicated at the outputs SOURCE_IP (IP address of the sending device) and SOURCE_PORT (port number of the sending device). WARNING Unintended machine operation Verify that the influence of the output data cannot result in an unintended or hazardous behavior of the entire system.1 1 When running the application logic in simulation mode, the function blocks for Ethernet communication establish a real connection to other devices/servers. Thus, outputs and variables connected to real hardware may be set and therefore may cause real damage to the machine.
Notes	The IP socket opened by the TCP_SOCKET function block can only be used for subsequent calls of the TCP_RECEIVE function block as long as the ACTIVE output of the TCP_SOCKET function block is TRUE. Calling the TCP_RECEIVE function block while ACTIVE = FALSE causes an error at the TCP_RECEIVE function block (ERROR = TRUE and STATUS code = 0xC210 issued). For controllers with integrated firewall, make sure that the firewall does not block the ports involved in the communication. Otherwise, the connection cannot be established. Function blocks have to be instantiated. The instance name of the function block has to be declared in the 'Variables' table of the POU where the FB is going to be used. The instance name must be unique within the POU.
Parameters	Inputs EN_R Data type: BOOL Description: With a rising edge at the EN_R input (EN_R = ENable_Receive), the data reception is started. As long as EN_R = TRUE, receiving data is possible. HANDLE Data type: DWORD Description: Socket handle that has been opened with the TCP_SOCKET function block (see also the notes above). The parameter is only evaluated in the cycle in which the EN_R parameter switches to TRUE. EXP_DATA_CNT Data type: UDINT Description: Number of bytes of the data to be received (EXP_DATA_CNT = EXPected DATA CouNT). The number of bytes is less or equal to the number of bytes provided with the variable connected to the DATA buffer. The following applies: If the value is greater than 0, only the specified number of bytes is copied to the variable connected to the DATA buffer. If less than the specified number of bytes have been received, these bytes are appended to the already received bytes in the variable connected to the DATA buffer. The output DATA_CNT is incremented accordingly. If the EXP_DATA_CNT bytes have been received, the output NDR is set to TRUE. Otherwise further calls of this instance are necessary to receive all expected data. If more than the specified number of bytes have been received, only EXP_DATA_CNT bytes are copied to the variable connected to the DATA buffer. The output DATA_CNT is incremented accordingly and NDR is set to TRUE. The remaining bytes (received but not yet copied) can be read by the next calls of the instance. If the value is 0, all data that have been received since the last call are copied to the variable connected to the DATA buffer (with the number of copied bytes being restricted to the size of the connected variable). The output DATA_CNT is incremented accordingly. If one or more bytes have been received (DATA_CNT > 0), the output NDR is set to TRUE. The parameter is only evaluated in the cycle in which the EN_R parameter switches to TRUE. Tip: You can use the SIZEOF function to determine the size of a variable (number of bytes reserved for the variable in the controller memory). Input/Output DATA Data type: ANY Description: Data buffer which contains the received data. Data is transmitted as byte stream. There is no Little-/Big-Endian conversion. If the data type of the connected variable is a STRUCT (or ARRAY OF STRUCT), the variable in the controller memory may contain padding bytes which have to be considered in the incoming data stream. Outputs NDR Data type: BOOL Description: NDR (New Data Received) is set to TRUE for one cycle once the data has been received successfully. You can only evaluate the success of the transmission during the cycle while NDR = TRUE. If NDR is TRUE, the next call (if some bytes were received) will overwrite DATA (NDR may be TRUE again) If NDR is FALSE, the next call (if some bytes were received) will append the received bytes to DATA. DATA_CNT will be incremented accordingly. If the expected number of bytes is reached, NDR will be TRUE ERROR Data type: BOOL Description: If an error occurs, the ERROR output is set to TRUE. The corresponding error code is indicated at the STATUS output. See Error Codes / Status Codes for Ethernet FBs. STATUS Data type: WORD Description: Provides the error code in the event of an error (ERROR = TRUE) or the current status of the function block (ERROR = FALSE). Error codes start with 16#Cxxx and status codes with 16#8xxx. See Error Codes / Status Codes for Ethernet FBs. SOURCE_IP Data type: STRING Description: IP address of the device from which data have been received. Note The string contains an IPv4 address that consists of four numbers (0 to 255) separated by dot. SOURCE_PORT Data type: UINT Description: Port number of the device from which data have been received. DATA_CNT Data type: UDINT Description: Number of successfully received bytes. The number of bytes is less or equal to the number of bytes provided with the variable connected to the DATA buffer. The parameter has to be evaluated in the cycle in which NDR = TRUE. The maximum number of bytes which can be received is limited to the maximum value of 2147483647 bytes. Tip: You can use the SIZEOF function to determine the size of a variable (number of bytes reserved for the variable in the controller memory).