The connection is a single bi-directional socket.

All communication from the DataHub to the client is non-blocking and asynchronous. It is possible to use blocking I/O in the client, and to wait for a response from the DataHub as well, but we don't advise doing either.

Since TCP is streamed, there are no packets as such. Each message starts with an open parenthesis and ends with a matching closing parenthesis. Messages should be terminated with a newline (\n) character. If they are not, then the DataHub will hold off on processing the incoming messages until it receives a newline character, and then it processes all messages in order, in a batch. There is a maximum character length allowed (around 1 MB) for a batch of messages, after which the DataHub will discard data until it sees a newline.

Parameters within a message can themselves be parenthesized expressions. For example, the following message contains a command and five parameters:

(OPCAddItem server1 item1 0 default:server1.item1
 (default server1 item1))

The fifth parameter is itself a command: (default server1 item1).

All strings in a message are surrounded by double quotes. Inside the double quotes, the sequence \" embeds a double quote, \\ embeds a \ character, \n embeds a newline, \t embeds a tab, \f embeds a form feed, \r embeds a carriage return. \ followed by any other character produces that character with the \ removed. Parentheses inside double quotes do not match parentheses outside double quotes.

You can embed any character inside a non-quoted string by putting a \ in front of that character, so the string abc\ def would be the same as "abc def".

Example of using a TCP socket directly without going through the Cogent C API:

SOCKET s;
char buf[256];
int len;
char *pointname = "testpoint";
double value = 1.0;

len = sprintf(buf, "(cset \"default:%s\" %g)\n", pointname, value);
send(s, buf, len, 0);