tclSurrogate Protocol |
The so called tclSurrogate protocol is so named because it was first used to connect a Tcl applet to the SIMPL framework. Since that time the embedded protocol has been used in many other instances than tcl applets (Tcl/Tk Windows -> SIMPL, VB Windows -> SIMPL, IO Anywhere network appliance -> SIMPL).
The concept of the tclSurrogate is really very straightward.
The tclSurrogate parent is started up and listens for connections on
a defined TCP/IP port. (default to port 8000).
When a connection is made and accepted the tclSurrogate forks a child process
whose purpose in life is to act as the SIMPL interface to the rest of the
SIMPL application. The process making the
connection and this child communicate with each other over the TCP/IP socket
which exists between them. The structures they
use to communicate on this socket is what we are terming the tclSurrogate
protocol.
General Message format |
The basic protocol message format is as follows:
| token(2) | nbytes(2) | ID(4) | data(token dependant) |
where the number in brackets represents the size of the field in bytes.
Some terminology |
We also need to decide on some naming conventions for the various elements involved in a message pass via the tclSurrogate child process.
There are basically 3 players that are involved:
Tokens |
The following tokens form the basis of this protocol.
The master source for this information is in the C header located at $SIMPL_HOME/tcl/include/surroMsgs.h
| Token | Value |
| NAME_ATTACH | 0 |
| NAME_DETACH | 1 |
| NAME_LOCATE | 2 |
| SEND | 3 |
| REPLY | 4 |
| RELAY | 5 |
| IS_LOGGER_UP | 6 |
| LOGIT | 7 |
| SEND_NO_REPLY | 8 |
| ACK | 9 |
| PING | 10 |
NAME_ATTACH |
sockapp -> child
| 0 | 32 | n/a(4) | SIMPL name(20) | n/a(4) | n/a(4) |
child -> sockapp
| 4 | 32 | -1 | SIMPL name(20) | pid(4) | slot(4) |
When the sockapp issues the NAME_ATTACH message it has the effect of
setting the SIMPL name on the child process.
NAME_DETACH |
sockapp -> child
| 1 | 0 |
child -> sockapp
| 4 | 4 | -1 |
The NAME_DETACH causes the child process to exit after a 2 second delay.
NAME_LOCATE |
sockapp -> child
| 2 | 28 | n/a(4) | SIMPL name(20) | n/a(4) |
child -> sockapp
| 4 | 28 | -1 | SIMPL name(20) | rc(4) |
The NAME_LOCATE will have the effect of performing a local name_locate()
for the SIMPL name. The rc field will contain the
result of that call.
SEND |
sockapp -> child
| 3 | 4+sbytes | toWhom(4) | sdata(sbytes) |
child -> SIMPL receiver(toWhom)
| sdata(sbytes) |
SIMPL receiver -> child
| rdata(rbytes) |
child -> sockapp
| 4 | 4+rbytes | -1 | rdata(rbytes) |
REPLY |
The use of this token has been detailed in the other paragraphs.
RELAY |
SIMPL sender(fromWhom) -> child
| sdata(sbytes) |
child -> sockapp
| 5 | 4+sbytes | fromWhom(4) | sdata(sbytes) |
sockapp -> child
| 4 | 4+rbytes | fromWhom(4) | rdata(rbytes) |
child -> SIMPL sender(fromWhom)
| rdata(rbytes) |
IS_LOGGER_UP |
sockapp -> child
| 6 | 28 | n/a(4) | trace logger name(20) | n/a(4) |
child -> sockapp
| 4 | 28 | -1 | trace logger name(20) | loggerID(4) |
NOTE: the trace logger name isn't currently checked in the child
code, so this call will return the global loggerID variable for the
tclSurrogate parent's trace logger irrespective of the supplied trace logger
name.
LOGIT |
sockapp -> child
| 7 | 52+msglen | loggerID(4) | fileName(20) | funcName20) | mask(4) | globalMask(4) | msg(msglen) |
There is no response to the LOGIT call.
SEND_NO_REPLY |
sockapp -> child
| 8 | 4+sbytes | toWhom(4) | sdata(sbytes) |
child -> SIMPL receiver(toWhom)
| sdata(sbytes) |
The Reply() from the SIMPL receiver is simply discarded in this instance.
ACK |
sockapp -> child
| 9 |
The ACK is not responded to.
PING |
sockapp -> child
| 10 |
child -> sockapp
| 4 | 4 | -1 |