TCP_SOCKET

Type	Function block
Description	The function block opens and closes an IP socket which is used for IP communication between a server and a client via Transmission Control Protocol (TCP). The IP socket is represented by the HANDLE output parameter. This handle has to be forwarded to the function blocks TCP_SEND and TCP_RECEIVE, which require the socket handle for the data exchange with a communication partner. With a rising edge at the ACTIVATE input, the system starts to open a socket. Once the socket has been opened and the connection has been established successfully, the ACTIVE output is set to TRUE. Only while ACTIVE = TRUE, the socket handle provided at the HANDLE output can be used for subsequent calls of the TCP_SEND/TCP_RECEIVE function blocks. A falling edge at ACTIVATE closes the socket. The connection is terminated in the form of a three-way handshake, i.e. three telegrams are exchanged between client and server. During the termination process a new rising edge results in a function block error. While ACTIVE = FALSE, calling the TCP_SEND/TCP_RECEIVE function blocks with the socket handle causes an error at the function blocks. The socket is kept open as long as the ACTIVATE input is TRUE. The BUSY output is set to TRUE while ACTIVATE is TRUE and the socket is still not open. If the ACTIVATE input switches to FALSE, the socket is closed and the ACTIVE output is set to FALSE (see also the notes below). If the connection is lost, the function block tries to re-establish the connection as long as ACTIVATE = TRUE. The IS_SRV input defines whether the function block implements server or client functionality. With IS_SRV = TRUE, the function block creates a listening (server) socket. The socket can be bound to the specified local Ethernet adapter (BIND_IP input) and the port (BIND_PORT input) and waits for incoming requests from remote clients. If necessary the accepted clients can be limited by specifying the DEST_IP/DEST_PORT inputs. With opened (server) socket, only 1:1 connections are possible, i.e., the listening socket can accept only one incoming TCP connection. With IS_SRV = FALSE, a client socket is created. In case of a client socket, the DEST_IP/DEST_PORT inputs are used to specify the IP address and IP port of the server to communicate with. 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 function blocks for TCP communication are processed asynchronously. This means, the function blocks issue commands and wait for their processing. In case of a warm start or cold start or a controller reset, the firmware closes all sockets that have been opened with the corresponding instance of the TCP_SOCKET instance. 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. All IP addresses used are IPv4 addresses that consist of four numbers (0 to 255) separated by dot. The number of IP sockets that are currently opened is indicated by the system variable IP_ACTIVE_SOCKETS (contained in the Data List of the controller node and 'IEC 61131-3' node in the PLANT). 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 ACTIVATE Data type: BOOL Description: The function block starts opening a socket when a rising edge is detected at the input. The socket is kept open as long as the ACTIVATE input is TRUE. A falling edge triggers the closing of the socket. As closing the socket takes some time (three-way handshake between client and server), the next rising edge should be applied to ACTIVATE only after the outputs ACTIVE and BUSY are both FALSE. Otherwise, i.e., if a new connection is requested while the previous socket termination is not yet completed, an error occurs and the error code 16#C205 is shown at the STATUS output. IS_SRV Data type: BOOL Description: Defines whether the function block implements server or client functionality. TRUE: the function block creates a listening (server) socket. FALSE: the function block creates a client socket. The function block evaluates this parameter only in the task cycle in which a rising edge at the ACTIVATE input is detected. BIND_IP Data type: STRING Description: IS_SRV = TRUE: This parameter specifies the IP address of the controller at which the server listens for incoming connections. Clients, which want to connect to this server, have to specify the same IP address as their DEST_IP input. If this string is empty (= initial value of the parameter) or contains the value '0.0.0.0', the server listens at every Ethernet adapter of the controller. IS_SRV = FALSE: In this case, the parameter is optional. If specified, it identifies which Ethernet adapter of the controller is used to establish the communication. Otherwise (if the string is empty or contains the value '0.0.0.0'), the controller selects an appropriate Ethernet adapter using the DEST_IP parameter. The function block evaluates this parameter only in the task cycle in which a rising edge at the ACTIVATE input is detected. BIND_PORT Data type: UINT Description: Defines the local port number to which the created socket is bound (necessary for setting up TCP servers). The selected port number is used by the TCP server for incoming data. Clients, which want to connect to this server, have to specify the same port number as their DEST_PORT input. If the value is 0 (= initial value of the parameter), the stack assigns a temporary port. The function block evaluates this parameter only in the task cycle in which a rising edge at the ACTIVATE input is detected. DEST_IP Data type: STRING Description: Depending on whether the function block implements server or client functionality (set with the IS_SRV input), the input has the following meaning: With IS_SRV = TRUE (FB creates a listening socket), only requests from the client with this IP address are accepted. If the string is empty (= initial value of the parameter), any client IP address is accepted. With IS_SRV = FALSE (FB creates a client socket), the parameter contains the IP address of the partner server to communicate with. The function block evaluates this parameter only in the task cycle in which a rising edge at the ACTIVATE input is detected. DEST_PORT Data type: UINT Description: Depending on whether the function block implements server or client functionality (set with the IS_SRV input), the input has the following meaning: With IS_SRV = TRUE (FB creates a listening socket), only requests from the client with this IP port are accepted. If the value is 0 (= initial value of the parameter), any client IP port is accepted. With IS_SRV = FALSE (FB creates a client socket), the parameter contains the IP port of the partner server to communicate with. The function block evaluates this parameter only in the task cycle in which a rising edge at the ACTIVATE input is detected. Outputs HANDLE Data type: DWORD Description: Created IP socket handle. The socket handle is required by subsequently calls to the function blocks TCP_RECEIVE and TCP_SEND in order to send or receive data, for example, to or from a TCP server. The socket handle can only be used for subsequent calls of the TCP_SEND/TCP_RECEIVE function blocks as long as ACTIVE = TRUE. Calling the TCP_* function blocks while ACTIVE = FALSE causes an error at the function blocks (see the description of the TCP_* function blocks for the generated STATUS code). ACTIVE Data type: BOOL Description: Indicates whether a socket is open. TRUE: Connection established successfully and socket is open. As long as ACTIVE = TRUE, the socket HANDLE can be used for calls of the TCP_SEND/TCP_RECEIVE function blocks for send/receive operations. FALSE: Socket is closed. While ACTIVE = FALSE, calling the TCP_SEND/TCP_RECEIVE function blocks with the socket HANDLE causes an error at the function blocks. BUSY Data type: BOOL Description: Set to TRUE if the ACTIVATE input is TRUE and the socket is still not open. When the socket has been opened, BUSY is set to FALSE and remains FALSE while ACTIVE = TRUE. ERROR Data type: BOOL Description: If an error occurs, the ERROR output is set to TRUE. The corresponding error code can be read at the STATUS output as long as ERROR = TRUE. 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. USED_PORT Data type: UINT Description: Indicates the port that is used for socket creation (automatically assigned or port number specified with the BIND_PORT input). The output can be used for diagnostic purposes, if needed.