From 6d574ad8c9cf4c63a576b5bbda89a076c55efec0 Mon Sep 17 00:00:00 2001 From: Pat Thoyts Date: Wed, 3 Apr 2002 00:59:48 +0000 Subject: [PATCH] Updated documentation --- winsend.html | 200 +++++++++++++++++++++++++++++++++++++++------------ winsend.man | 126 +++++++++++++++++++++++++++++--- 2 files changed, 271 insertions(+), 55 deletions(-) diff --git a/winsend.html b/winsend.html index 0e229d9..d9f673d 100644 --- a/winsend.html +++ b/winsend.html @@ -1,26 +1,136 @@ - - - -WinSend 0.3 - - - - -
WinSend - A COM Implementation of the Tk Send Command.

- -
This is a first go at implementing the Tk send command for -Tk under MS Windows using COM to handle the registration and -interprocess communication for us. Briefly this package when loaded -into an interpreter will automatically register the interp in the -system's running object table. The winsend interps command -can be used to show all the registered interpreters and unlike using -DDE this command will not be blocked by badly behaving windows -applications.
- -
+
+
+winsend - winsend 
+
+
+
+
+
+ winsend(n) 0.4 winsend "winsend"
+NAME
+ winsend - send implementation for windows platform
+
+
+
SYNOPSIS

+package require Tcl 8.3

+package require winsend ?0.4?

+

+winsend command ?arguments ...?
+DESCRIPTION
+
+
+The winsend package is an attempt to provide the complete
+functionality of the Tk send command using the Microsoft Windows
+platform. The two key points are inter-process communications between
+one interpreter and another, and automatic registration of
+interpreters with a central source. With the Tk send command this is
+done via the X Windows server. The winfo interps command returns
+a list of registered interpreters and the send command allows
+you to execute Tcl commands in the named interpreter. Finally tk
+appname allows the programmer to select the registration name.
+
+

+
+There are alternative methods for providing remote command xecution on
+the windows platform. The comm package that is now part of 
+tcllib provides cross-platform remote command execution by the
+use of TCP sockets. The disadvantage of this package is the lack of
+interpreter registration. Potential clients need to be told of the
+port number to use to communicate with the server application.
+
+

+
+The other method is the dde package which is supplied as part of
+the Tcl core. This provides automatic registration and the available
+interpreters can be listed by excuting 
+dde servers TclEval {}. The disadvantage if the DDE system 
+is that a badly written
+windows application can hang your application. DDE uses windows
+messages to do its work. If an application isn't processing it's
+message queue then the dde command given above will never complete.
+
+

+
+An alternative is available using Microsoft's COM technology. COM is
+designed to permit interprocess communication through the use of
+interfaces. There is also a system provided registration object where
+a reference to a running interpreter can be lodged. Querying the list
+of available servers only communicates with the Running Object Table
+(the ROT) and doesn't need to send messages to any
+applications. Sending commands does require the server interpreter to
+be processing events - but if the server is not processing these
+events then the command will time out. This is a significant advantage
+over DDE. Also, because we are using standard OLE automation
+interfaces it becomes possible for any other Automation capable
+application to send commands to Tcl for execution. Such applications
+include Microsoft Office applications, Internet Explorer and many
+others. For instance the following VB script can be run using the
+Windows Scripting Host cscript application using 
+cscript test.vbs
+
  + Set interp = GetObject("\\.\TclInterp\tkcon.tcl")
+ interp.Send "puts {Hello from VB Script}"
+ WScript.Echo interp.Send("info tcl")
+
+Provided you have an instance of Tcl running registered with 
+winsend appname tkcon.tcl you should see the message appear in
+the Tcl window and the Tcl version should be printed to the cscript
+console window.
+
+
+
+COMMANDS
+
+
+
+winsend command ?arguments ...?

+
+
+
+interps

+   Get the list of registered interpreter names for use with
+send. Similar to the Tk winfo interps command.
+
+


+
appname ?name?

+   When called with no arguments this returns the registered name of
+this interpreter. If a single argument is given, this is used to
+re-register the application using the new name. If the registration
+fails for some reason, such as the name is already in use, then an
+error is returned and the old appname remains in use.
+
+


+
send appname cmd ?arg arg ...?

+   As for the Tk send command this concatenates cmd and
+all args and passes the resulting string to the appname
+interpreter for evaluation. It returns the result or error from this
+command evaluation.
+
+
+
+
+
+
+
+EXAMPLES
+
+
+
  +% package require winsend
+0.4
+% winsend appname MyApp
+MyApp
+% winsend send MyApp info tcl
+8.3
+
+
+
+
+An example session between two interpreters
+
   An example (from tkcon):         from a concurrent tclsh:
   % package require winsend  |     % package require winsend
-  0.3                        |     0.3
+  0.4                        |     0.4
   % winsend interps          |     % winsend interps
   tkcon.tcl                  |     tkcon.tcl TCLSH.EXE
                              |     % winsend send tkcon.tcl set x 1
@@ -34,35 +144,35 @@ An example (from tkcon):         from a concurrent tclsh:
                              |     % exit
   % winsend interps          |
   tkcon.tcl                  |
-
+
+
+
+
+DOWNLOAD and INSTALLATION
+
+The latest version is available at
+http://prdownloads.sourceforge.net/tclsoap/winsend-0.4.zip
+This includes the source and the DLLs. To install, copy the DLLs and
+the "pkgIndex.tcl" file to a subdirectory of your auto_path
+variable. For instance, to "c:/Program Files/Tcl/lib/winsend04/"
 
-As you can see from the above session - we require an event loop to be
-running to handle the incoming send. Technically, this is because we
-are using an Apartment threaded object and COM apartments serialize
-access to object by using the Windows message queue. A future version
-could side-step this by creating a free-threaded object but we are
-trying to implement Tk's send here.
+
 
-
An interesting side-effect is that we can access the running Tcl
-interpreter from any COM using scripting language. Here is an example
-of a VB script file you can run using cscript test.vbs under
-windows. It will also work from MS Words macro editor etc. You need to
-start up an interpreter and load the winsend package (for instance -
-using tkcon):
+Documentation is located at 
+http://tclsoap.sourceforge.net/winsend.html
 
-Set interp = GetObject("\\.\TclInterp\tkcon.tcl")
-interp.Send "puts {Hello from VB Script}"
-WScript.Echo interp.Send("info tcl")
+
 
-You should see the message printed in your tkcon window and see your
-Tcl version printed in your DOS box.
+SEE ALSO
+send(n), winfo(n), tk(n)
 
-The package containing binaries and source is available from 
-
-http://tclsoap.sf.net/winsend.zip
+
 
-Pat Thoyts.
+AUTHORS
+Pat Thoyts
 
+
 
-
-
+KEYWORDS
+send, appname, tk, winfo, COM, Automation
+
diff --git a/winsend.man b/winsend.man
index 09b485e..abced4e 100644
--- a/winsend.man
+++ b/winsend.man
@@ -1,19 +1,72 @@
+[comment {winsend.man - Copyright (C) 2002 Pat Thoyts <Pat.Thoyts@bigfoot.com>}]
+[comment {$Id$}]
 [manpage_begin winsend n 0.4]
 [moddesc   {winsend}]
-[titledesc {Windows send Command}]
+[titledesc {send implementation for windows platform}]
 [require Tcl 8.3]
 [require winsend [opt 0.4]]
 [description]
 [para]
 
-The [cmd winsend] package is an attempt to provide the complete
+The [package winsend] package is an attempt to provide the complete
 functionality of the Tk [cmd send] command using the Microsoft Windows
 platform. The two key points are inter-process communications between
 one interpreter and another, and automatic registration of
-interpreters with a central source. With the Tk send command this is
-done via the X Windows server. The [cmd winfo interps] command returns
+interpreters with a central source. With the Tk [cmd send] command this is
+done via the X Windows server. The [cmd "winfo interps"] command returns
 a list of registered interpreters and the [cmd send] command allows
-you to execute Tcl commands in the named interpreter.
+you to execute Tcl commands in the named interpreter. Finally [cmd "tk
+appname"] allows the programmer to select the registration name.
+
+[para]
+
+There are alternative methods for providing remote command xecution on
+the windows platform. The [package comm] package that is now part of 
+[package tcllib] provides cross-platform remote command execution by the
+use of TCP sockets. The disadvantage of this package is the lack of
+interpreter registration. Potential clients need to be told of the
+port number to use to communicate with the server application.
+
+[para]
+
+The other method is the [package dde] package which is supplied as part of
+the Tcl core. This provides automatic registration and the available
+interpreters can be listed by excuting 
+[cmd "dde servers TclEval {}"]. The disadvantage if the DDE system 
+is that a badly written
+windows application can hang your application. DDE uses windows
+messages to do its work. If an application isn't processing it's
+message queue then the dde command given above will never complete.
+
+[para]
+
+An alternative is available using Microsoft's COM technology. COM is
+designed to permit interprocess communication through the use of
+interfaces. There is also a system provided registration object where
+a reference to a running interpreter can be lodged. Querying the list
+of available servers only communicates with the Running Object Table
+(the ROT) and doesn't need to send messages to any
+applications. Sending commands does require the server interpreter to
+be processing events - but if the server is not processing these
+events then the command will time out. This is a significant advantage
+over DDE. Also, because we are using standard OLE automation
+interfaces it becomes possible for any other Automation capable
+application to send commands to Tcl for execution. Such applications
+include Microsoft Office applications, Internet Explorer and many
+others. For instance the following VB script can be run using the
+Windows Scripting Host cscript application using 
+[cmd "cscript test.vbs"]
+[example {
+ Set interp = GetObject("\\.\TclInterp\tkcon.tcl")
+ interp.Send "puts {Hello from VB Script}"
+ WScript.Echo interp.Send("info tcl")
+}]
+Provided you have an instance of Tcl running registered with 
+[cmd {winsend appname tkcon.tcl}] you should see the message appear in
+the Tcl window and the Tcl version should be printed to the cscript
+console window.
+
+[comment {----------------------------------------------------------}]
 
 [section COMMANDS]
 
@@ -23,19 +76,28 @@ you to execute Tcl commands in the named interpreter.
 
 [list_begin definitions]
 [lst_item "[cmd interps]"]
-   Get the list of registered interpreter names for use with send.
+   Get the list of registered interpreter names for use with
+send. Similar to the Tk [cmd "winfo interps"] command.
+
 [lst_item "[cmd appname] [opt [arg name]]"]
    When called with no arguments this returns the registered name of
 this interpreter. If a single argument is given, this is used to
 re-register the application using the new name. If the registration
 fails for some reason, such as the name is already in use, then an
 error is returned and the old appname remains in use.
-[lst_item "[cmd send]"]
-   send
+
+[lst_item "[cmd send] [arg appname] [arg cmd] [opt [arg {arg arg ...}]]"]
+   As for the Tk [cmd send] command this concatenates [arg cmd] and
+all [arg args] and passes the resulting string to the [arg appname]
+interpreter for evaluation. It returns the result or error from this
+command evaluation.
+
 [list_end]
 
 [list_end]
 
+[comment {----------------------------------------------------------}]
+
 [section EXAMPLES]
 
 [para]
@@ -48,9 +110,53 @@ MyApp
 8.3
 }]
 
-[see_also send(n)]
+[para]
+
+An example session between two interpreters
+[example {
+An example (from tkcon):         from a concurrent tclsh:
+  % package require winsend  |     % package require winsend
+  0.4                        |     0.4
+  % winsend interps          |     % winsend interps
+  tkcon.tcl                  |     tkcon.tcl TCLSH.EXE
+                             |     % winsend send tkcon.tcl set x 1
+                             |     1
+  % set x                    |
+  1                          |
+  % winsend send TCLSH.EXE set y 2
+                             |     % after 2000 {set zx 1} ; vwait zx
+  2                          |     % set y
+                             |     2
+                             |     % exit
+  % winsend interps          |
+  tkcon.tcl                  |
+}]
+
+[comment {----------------------------------------------------------}]
+
+[section {DOWNLOAD and INSTALLATION}]
+
+The latest version is available at
+[uri {http://prdownloads.sourceforge.net/tclsoap/winsend-0.4.zip}]
+This includes the source and the DLLs. To install, copy the DLLs and
+the [file pkgIndex.tcl] file to a subdirectory of your [var auto_path]
+variable. For instance, to [file {c:/Program Files/Tcl/lib/winsend04/}]
+
+[para]
+
+Documentation is located at 
+[uri {http://tclsoap.sourceforge.net/winsend.html}]
+
+[comment {----------------------------------------------------------}]
+
+[see_also send(n) winfo(n) tk(n)]
+
+[comment {----------------------------------------------------------}]
+
 [section AUTHORS]
 Pat Thoyts
 
-[keywords send appname]
+[comment {----------------------------------------------------------}]
+
+[keywords send appname tk winfo COM Automation]
 [manpage_end]
-- 
2.23.0