comm_wire(n)                 Remote communication                 comm_wire(n)



______________________________________________________________________________

NAME
       comm_wire - The comm wire protocol

SYNOPSIS
       package require comm

_________________________________________________________________

DESCRIPTION
       The comm command provides an inter-interpreter remote execution
       facility much like Tk's send(n), except that it uses sockets rather
       than the X server for the communication path.  As a result, comm works
       with multiple interpreters, works on Windows and Macintosh systems, and
       provides control over the remote execution path.

       This document contains a specification of the various versions of the
       wire protocol used by comm internally for the communication between its
       endpoints. It has no relevance to users of comm, only to developers who
       wish to modify the package, write a compatible facility in a different
       language, or some other facility based on the same protocol.

WIRE PROTOCOL VERSION 3
   BASIC LAYER
       The basic encoding for all data is UTF-8. Because of this binary data,
       including the NULL character, can be sent over the wire as is, without
       the need for armoring it.

   BASIC MESSAGE LAYER
       On top of the Basic Layer we have a message oriented exchange of data.
       The totality of all characters written to the channel is a Tcl list,
       with each element a separate message, each itself a list. The messages
       in the overall list are separated by EOL. Note that EOL characters can
       occur within the list as well. They can be distinguished from the
       message-separating EOL by the fact that the data from the beginning up
       to their location is not a valid Tcl list.

       EOL is signaled through the linefeed character, i.e LF, or, hex 0x0a.
       This is following the unix convention for line-endings.

       As a list each message is composed of words. Their meaning depends on
       when the message was sent in the overall exchange. This is described in
       the upcoming sections.

   NEGOTIATION MESSAGES - INITIAL HANDSHAKE
       The command protocol is defined like this:

       o      The first message send by a client to a server, when opening the
              connection, contains two words. The first word is a list as
              well, and contains the versions of the wire protocol the client
              is willing to accept, with the most preferred version first. The
              second word is the TCP port the client is listening on for
              connections to itself. The value 0 is used here to signal that
              the client will not listen for connections, i.e. that it is
              purely for sending commands, and not receiving them.

       o      The first message sent by the server to the client, in response
              to the message above contains only one word. This word is a
              list, containing the string vers as its first element, and the
              version of the wire protocol the server has selected from the
              offered versions as the second.

   SCRIPT/COMMAND MESSAGES
       All messages coming after the initial handshake consist of three words.
       These are an instruction, a transaction id, and the payload. The valid
       instructions are shown below. The transaction ids are used by the
       client to match any incoming replies to the command messages it sent.
       This means that a server has to copy the transaction id from a command
       message to the reply it sends for that message.

       send

       async

       command
              The payload is the Tcl script to execute on the server. It is
              actually a list containing the script fragments. These fragment
              are concatenated together by the server to form the full script
              to execute on the server side.  This emulates the Tcl "eval"
              semantics.  In most cases it is best to have only one word in
              the list, a list containing the exact command.

              Examples:


                  (a)     {send 1 {{array get tcl_platform}}}
                  (b)     {send 1 {array get tcl_platform}}
                  (c)     {send 1 {array {get tcl_platform}}}

                  are all valid representations of the same command. They are
                  generated via

                  (a')    send {array get tcl_platform}
                  (b')    send array get tcl_platform
                  (c')    send array {get tcl_platform}

                  respectively


       Note that (a), generated by (a'), is the usual form, if only single
       commands are sent by the client.  For example constructed using list,
       if the command contains variable arguments. Like


                  send [list array get $the_variable]


       These three instructions all invoke the script on the server side.
       Their difference is in the treatment of result values, and thus
       determines if a reply is expected.

              send   A reply is expected. The sender is waiting for the
                     result.

              async  No reply is expected, the sender has no interest in the
                     result and is not waiting for any.

              command
                     A reply is expected, but the sender is not waiting for
                     it. It has arranged to get a process-internal
                     notification when the result arrives.

       reply  Like the previous three command, however the tcl script in the
              payload is highly restricted.  It has to be a syntactically
              valid Tcl return command. This contains result code, value,
              error code, and error info.

              Examples:


                  {reply 1 {return -code 0 {}}}
                  {reply 1 {return -code 0 {osVersion 2.4.21-99-default byteOrder littleEndian machine i686 platform unix os Linux user andreask wordSize 4}}}


BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will undoubtedly contain
       bugs and other problems.  Please report such in the category comm of
       the Tcllib SF Trackers
       [http://sourceforge.net/tracker/?group_id=12883].  Please also report
       any ideas for enhancements you may have for either package and/or
       documentation.

SEE ALSO
       comm

KEYWORDS
       comm, communication, ipc, message, remote communication, remote
       execution, rpc, socket

CATEGORY
       Programming tools

COPYRIGHT
       Copyright (c) 2005 Docs. Andreas Kupries <andreas_kupries@users.sourceforge.net>




comm                                   3                          comm_wire(n)
