sockmsg - a simple message packet protocol for socket connections


package require Humelib
sockmsg_server {port 7377} {which_IP {}}
sockmsg_client {port 7377} {which_IP {}} {client_name sockclient}
sockmsg_sendcmd tcl_code {client_name sockclient}


Hume Integration has devised a simple message packet protocol for integrating applications with Tcl through socket connection(s).

The socket connection ordinarily stays open to avoid the overhead of setting up and taking down the connection. The length and EOT character are used by the receiving logic to verify reception of a complete message. Message size is limited to less than 99999 characters.

Some applications will use two socket connections - one for the client to send commands and receive replies, and a second for the client to receive commands and send replies. With two connections, the client does not need to deal with the possibility of receiving a command on the same connection that he is waiting for a reply on.

Here is the on the wire message packet format. A command message starts with the text sockcmd, space, 5 ascii character total length, space, variable length data, and ends with the EOT character (0x04).

The data content of a command is expected to be tcl code and the receiver is expected to send a reply message. The 5 ascii character total length is space padded and right aligned; it is a count of total bytes in the packet.

A reply message starts with token sockrep and is otherwise the same. The data of a reply message is expected to be the Tcl execution return code, space, and the Tcl result string.

An asynchronous command with no reply expected starts with the text socksnd and is otherwise the same. The data content is expected to be tcl code, which is executed, but no reply message is expected or sent.

The message data is always ASCII text, and should not include null characters. International characters using UTF-8 encoding such as used by Java and Tcl are ok.

 Example messages:

 "sockcmd    29 set pi 3.14159\x04"

 "sockrep    24 0 3.14159\x04"

 "socksnd    56 mbx put TRACE {Barcode reader 12 startup}\x04"

  NOTES:  The \x04 represents a single character, ASCII 4.  
          A trailing null character is not sent.

The sockmsg_server command implements this protocol as a TCP/IP server on a designated port. If you have more than one IP address or hostname on your computer, you may optionally specify which IP address to serve. The server receives sockcmd or socksnd messages, executes them as Tcl code, and replies with sockrep messages when appropriate.

The sockmsg_client command creates a client connection to a sockmsg server. The server should already be online when the client connection is attempted. The command creates a new Tcl command client_name which is actually a comm connection object.

The sockmsg_sendcmd command is a working example of the logic needed to send a sockcmd message, and perform a modal wait for the sockrep reply, or a TIMEOUT error reply.

Unlike the DMH message system, there is no queuing other than the buffering provided by TCP/IP communication. The protocol is intended for use is contexts where the use of DMH is not possible. The simple packet protocol is intended to be easily implemented on different platforms, by developers who are experienced with TCP/IP programming.

These commands are part of the Humelib package and reside in the global namespace.


# the server process
package require Humelib

  # the client process 
  package require Humelib
  sockmsg_client 7377 $server_host
  set reply [sockmsg_sendcmd {localtime 15}]
  set rc [string index $reply 0]
  set data [string range $reply 2 end]
  puts "server local time=$data (return code=$rc)"


Hume Integration Software,


comm DMH socket


inter-process communication, IPC, protocol, sockets, TCP/IP