TCP-IP management functions

The following functions enable management of TCP-IP sockets for building client or server applications over ETHERNET network:

tcpListen        create a listening server socket
tcpAccept        accept client connections
tcpConnect       create a client socket and connect it to a server
tcpIsConnected   test if a client socket is connected
tcpClose         close a socket
tcpSend          send characters
tcpReceive       receive characters
tcpIsValid       test if a socket is valid

Each socket is identified in the application by a unique handle manipulated as a DINT value.

Important notes

  • Although the system provides a simplified interface, you must be familiar with the socket interface such as existing in other programming languages such as "C".

  • Socket management may be not available on some targets. Please refer to OEM instructions for further details about available features.

tcpListen: create a "listening" server socket

SOCK := tcpListen (PORT, MAXCNX);

PORT : DINT     TCP port number to be attached to the server socket
MAXCNX : DINT   maximum number of client sockets that can be accepted
SOCK : DINT     ID of the new server socket

This functions creates a new socket performs the "bind" and "listen" operations using default TCP settings. You will have to call the tcpClose function to release the socket returned by this function.

tcpAccept: accept a new client connection

SOCK := tcpAccept (LSOCK);

LSOCK : DINT    ID of a server socket returned by the tcpListen function
SOCK : DINT     ID of a new client socket accepted, or invalid ID if no new connection

This functions performs the "accept" operation using default TCP settings. You will have to call the tcpClose function to release the socket returned by this function.

tcpConnect: create a client socket and connect it to a server

SOCK := tcpConnect (ADDRESS, PORT);

ADDRESS : STRING  IP address of the remote server
PORT : DINT       wished port number on the server
SOCK : DINT       ID of the new client socket

This functions creates a new socket performs the "connect" operation using default TCP settings and specified server address and port. You will have to call the tcpClose function to release the socket returned by this function.

Warning: It is possible that the functions returns a valid socket ID even if the connection to the server is not yet actually performed. After calling this function, you must call tcpIsConnected function to know if the connection is ready.

tcpIsConnected: test if a client socket is connected

OK := tcpIsConnected (SOCK);

SOCK : DINT   ID of the client socket
 OK : BOOL     TRUE if connection is correctly established

Warning: It is possible that the socket becomes invalid after this function is called, if an error occurs in the TCP connection. You must call the tcpIsValid function after calling this function. If the socket is not valid anymore then you must close it by calling tcpClose.

tcpClose: release a socket

OK := tcpClose (SOCK);

SOCK : DINT   ID of any socket
 OK : BOOL     TRUE if successful

You are responsible for closing any socket created by tcpListen, tcpAccept or tcpConnect functions, even if they have become invalid.

tcpSend: send characters

NBSENT := tcpSend (SOCK, NBCHR, DATA);

SOCK : DINT     ID of a socket
 NBCHAR : DINT   number of characters to be sent
DATA : STRING   string containing characters to send
NBSENT : DINT   number of characters actually sent

It is possible that the number of characters actually sent is less than the number expected. In that case, you will have to call again the function on the next cycle to send the pending characters.

Warning: It is possible that the socket becomes invalid after this function is called, if an error occurs in the TCP connection. You must call the tcpIsValid function after calling this function. If the socket is not valid anymore then you must close it by calling tcpClose.

tcpReceive: receive characters

NBRCV := tcpReceive (SOCK, MAXCHR, DATA);

SOCK : DINT     ID of a socket
 MAXCHR : DINT   maximum number of characters wished
DATA : STRING   string where to store received characters
NBRCV : DINT    number of characters actually received

It is possible that the number of characters actually received is less than the number expected. In that case, you will have to call again the function on te next cycle to receive the pending characters.

Warning: It is possible that the socket becomes invalid after this function is called, if an error occurs in the TCP connection. You must call the tcpIsValid function after calling this function. If the socket is not valid anymore then you must close it by calling tcpClose.

tcpIsValid: test if a socket is valid

OK := tcpIsValid (SOCK);

SOCK : DINT   ID of the socket
 OK : BOOL     TRUE if specified socket is still valid