util/src/TclTk/tcl8.6.12/doc/dde.n

   1 '\"
   2 '\" Copyright (c) 1997 Sun Microsystems, Inc.
   3 '\" Copyright (c) 2001 ActiveState Corporation.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH dde n 1.4 dde "Tcl Bundled Packages"
   9 .so man.macros
  10 .BS
  11 '\" Note:  do not modify the .SH NAME line immediately below!
  12 .SH NAME
  13 dde \- Execute a Dynamic Data Exchange command
  14 .SH SYNOPSIS
  15 .sp
  16 \fBpackage require dde 1.4\fR
  17 .sp
  18 \fBdde servername\fR ?\fB\-force\fR? ?\fB\-handler \fIproc\fR? ?\fB\-\|\-\fR? ?\fItopic\fR?
  19 .sp
  20 .VS 8.6
  21 \fBdde execute\fR ?\fB\-async\fR? ?\fB\-binary\fR? \fIservice topic data\fR
  22 .sp
  23 \fBdde poke\fR ?\fB\-binary\fR? \fIservice topic item data\fR
  24 .VE 8.6
  25 .sp
  26 \fBdde request\fR ?\fB\-binary\fR? \fIservice topic item\fR
  27 .sp
  28 \fBdde services \fIservice topic\fR
  29 .sp
  30 \fBdde eval\fR ?\fB\-async\fR? \fItopic cmd \fR?\fIarg arg ...\fR?
  31 .BE
  32
  33 .SH DESCRIPTION
  34 .PP
  35 This command allows an application to send Dynamic Data Exchange (DDE)
  36 command when running under Microsoft Windows. Dynamic Data Exchange is
  37 a mechanism where applications can exchange raw data. Each DDE
  38 transaction needs a \fIservice name\fR and a \fItopic\fR. Both the
  39 \fIservice name\fR and \fItopic\fR are application defined; Tcl uses
  40 the service name \fBTclEval\fR, while the topic name is the name of the
  41 interpreter given by \fBdde servername\fR. Other applications have their
  42 own \fIservice names\fR and \fItopics\fR. For instance, Microsoft Excel
  43 has the service name \fBExcel\fR.
  44 .PP
  45 .SH "DDE COMMANDS"
  46 .PP
  47 The following commands are a subset of the full Dynamic Data Exchange
  48 set of commands.
  49 .TP
  50 \fBdde servername \fR?\fB\-force\fR? ?\fB\-handler \fIproc\fR? ?\fB\-\|\-\fR? ?\fItopic\fR?
  51 .
  52 \fBdde servername\fR registers the interpreter as a DDE server with
  53 the service name \fBTclEval\fR and the topic name specified by \fItopic\fR.
  54 If no \fItopic\fR is given, \fBdde servername\fR returns the name
  55 of the current topic or the empty string if it is not registered as a
  56 service. If the given \fItopic\fR name is already in use, then a
  57 suffix of the form
  58 .QW " #2"
  59 or
  60 .QW " #3"
  61 is appended to the name to make it
  62 unique. The command's result will be the name actually used. The
  63 \fB\-force\fR option is used to force registration of precisely the
  64 given \fItopic\fR name.
  65 .RS
  66 .PP
  67 The \fB\-handler\fR option specifies a Tcl procedure that will be called to
  68 process calls to the dde server. If the package has been loaded into a
  69 safe interpreter then a \fB\-handler\fR procedure must be defined. The
  70 procedure is called with all the arguments provided by the remote
  71 call.
  72 .RE
  73 .TP
  74 \fBdde execute\fR ?\fB\-async\fR? ?\fB\-binary\fR? \fIservice topic data\fR
  75 .
  76 \fBdde execute\fR takes the \fIdata\fR and sends it to the server indicated
  77 by \fIservice\fR with the topic indicated by \fItopic\fR. Typically,
  78 \fIservice\fR is the name of an application, and \fItopic\fR is a file to
  79 work on.  The \fIdata\fR field is given to the remote application.
  80 Typically, the application treats the \fIdata\fR field as a script, and the
  81 script is run in the application.  The \fB\-async\fR option requests
  82 asynchronous invocation.  The command returns an error message if the
  83 script did not run, unless the \fB\-async\fR flag was used, in which case
  84 the command returns immediately with no error.
  85 .VS 8.6
  86 Without the \fB\-binary\fR option all data will be sent in unicode. For
  87 dde clients which don't implement the CF_UNICODE clipboard format, this
  88 will automatically be translated to the system encoding. You can use
  89 the \fB\-binary\fR option in combination with the result of
  90 \fBencoding convertto\fR to send data in any other encoding.
  91 .VE 8.6
  92 .TP
  93 \fBdde poke\fR ?\fB\-binary\fR? \fIservice topic item data\fR
  94 .
  95 \fBdde poke\fR passes the \fIdata\fR to the server indicated by
  96 \fIservice\fR using the \fItopic\fR and \fIitem\fR specified.  Typically,
  97 \fIservice\fR is the name of an application.  \fItopic\fR is application
  98 specific but can be a command to the server or the name of a file to work
  99 on.  The \fIitem\fR is also application specific and is often not used, but
 100 it must always be non-null.  The \fIdata\fR field is given to the remote
 101 application.
 102 .VS 8.6
 103 Without the \fB\-binary\fR option all data will be sent in unicode. For
 104 dde clients which don't implement the CF_UNICODE clipboard format, this
 105 will automatically be translated to the system encoding. You can use
 106 the \fB\-binary\fR option in combination with the result of
 107 \fBencoding convertto\fR to send data in any other encoding.
 108 .VE 8.6
 109 .TP
 110 \fBdde request\fR ?\fB\-binary\fR? \fIservice topic item\fR
 111 .
 112 \fBdde request\fR is typically used to get the value of something; the
 113 value of a cell in Microsoft Excel or the text of a selection in
 114 Microsoft Word. \fIservice\fR is typically the name of an application,
 115 \fItopic\fR is typically the name of the file, and \fIitem\fR is
 116 application-specific. The command returns the value of \fIitem\fR as
 117 defined in the application.  Normally this is interpreted to be a
 118 string with terminating null.  If \fB\-binary\fR is specified, the
 119 result is returned as a byte array.
 120 .TP
 121 \fBdde services \fIservice topic\fR
 122 .
 123 \fBdde services\fR returns a list of service-topic pairs that
 124 currently exist on the machine. If \fIservice\fR and \fItopic\fR are
 125 both empty strings ({}), then all service-topic pairs currently
 126 available on the system are returned. If \fIservice\fR is empty and
 127 \fItopic\fR is not, then all services with the specified topic are
 128 returned. If \fIservice\fR is non-empty and \fItopic\fR is, all topics
 129 for a given service are returned. If both are non-empty, if that
 130 service-topic pair currently exists, it is returned; otherwise, an
 131 empty string is returned.
 132 .TP
 133 \fBdde eval\fR ?\fB\-async\fR? \fItopic cmd \fR?\fIarg arg ...\fR?
 134 .
 135 \fBdde eval\fR evaluates a command and its arguments using the interpreter
 136 specified by \fItopic\fR. The DDE service must be the \fBTclEval\fR
 137 service.  The \fB\-async\fR option requests asynchronous invocation.  The
 138 command returns an error message if the script did not run, unless the
 139 \fB\-async\fR flag was used, in which case the command returns immediately
 140 with no error.  This command can be used to replace send on Windows.
 141 .SH "DDE AND TCL"
 142 .PP
 143 A Tcl interpreter always has a service name of \fBTclEval\fR.  Each
 144 different interpreter of all running Tcl applications must be
 145 given a unique
 146 name specified by \fBdde servername\fR. Each interp is available as a
 147 DDE topic only if the \fBdde servername\fR command was used to set the
 148 name of the topic for each interp. So a \fBdde services TclEval {}\fR
 149 command will return a list of service-topic pairs, where each of the
 150 currently running interps will be a topic.
 151 .PP
 152 When Tcl processes a \fBdde execute\fR command, the data for the
 153 execute is run as a script in the interp named by the topic of the
 154 \fBdde execute\fR command.
 155 .PP
 156 When Tcl processes a \fBdde request\fR command, it returns the value of the
 157 variable given in the dde command in the context of the interp named by the
 158 dde topic. Tcl reserves the variable \fB$TCLEVAL$EXECUTE$RESULT\fR for
 159 internal use, and \fBdde request\fR commands for that variable will give
 160 unpredictable results.
 161 .PP
 162 An external application which wishes to run a script in Tcl should have
 163 that script store its result in a variable, run the \fBdde execute\fR
 164 command, and then run \fBdde request\fR to get the value of the
 165 variable.
 166 .PP
 167 When using DDE, be careful to ensure that the event queue is flushed
 168 using either \fBupdate\fR or \fBvwait\fR.  This happens by default
 169 when using \fBwish\fR unless a blocking command is called (such as \fBexec\fR
 170 without adding the \fB&\fR to place the process in the background).
 171 If for any reason the event queue is not flushed, DDE commands may
 172 hang until the event queue is flushed.  This can create a deadlock
 173 situation.
 174 .SH EXAMPLE
 175 .PP
 176 This asks Internet Explorer (which must already be running) to go to a
 177 particularly important website:
 178 .PP
 179 .CS
 180 package require dde
 181 \fBdde execute\fR -async iexplore WWW_OpenURL http://www.tcl-lang.org/
 182 .CE
 183 .SH "SEE ALSO"
 184 tk(n), winfo(n), send(n)
 185 .SH KEYWORDS
 186 application, dde, name, remote execution
 187 '\"Local Variables:
 188 '\"mode: nroff
 189 '\"End: