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, with-
       out 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 char-
       acters 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  ver-
	      sions 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)