1dde(n)                       Tcl Bundled Packages                       dde(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       dde - Execute a Dynamic Data Exchange command
9

SYNOPSIS

11       package require dde 1.4
12
13       dde servername ?-force? ?-handler proc? ?--? ?topic?
14
15       dde execute ?-async? ?-binary? service topic data
16
17       dde poke ?-binary? service topic item data
18
19       dde request ?-binary? service topic item
20
21       dde services service topic
22
23       dde eval ?-async? topic cmd ?arg arg ...?
24______________________________________________________________________________
25
26

DESCRIPTION

28       This  command allows an application to send Dynamic Data Exchange (DDE)
29       command when running under Microsoft Windows. Dynamic Data Exchange  is
30       a mechanism where applications can exchange raw data. Each DDE transac‐
31       tion needs a service name and a topic. Both the service name and  topic
32       are  application  defined; Tcl uses the service name TclEval, while the
33       topic name is the name of the  interpreter  given  by  dde  servername.
34       Other  applications  have  their  own service names and topics. For in‐
35       stance, Microsoft Excel has the service name Excel.
36

DDE COMMANDS

38       The following commands are a subset of the full Dynamic  Data  Exchange
39       set of commands.
40
41       dde servername ?-force? ?-handler proc? ?--? ?topic?
42              dde  servername  registers  the interpreter as a DDE server with
43              the service name TclEval and the topic name specified by  topic.
44              If  no  topic  is  given, dde servername returns the name of the
45              current topic or the empty string if it is not registered  as  a
46              service.  If the given topic name is already in use, then a suf‐
47              fix of the form “ #2” or “ #3” is appended to the name  to  make
48              it  unique. The command's result will be the name actually used.
49              The -force option is used to force registration of precisely the
50              given topic name.
51
52              The  -handler  option  specifies  a  Tcl  procedure that will be
53              called to process calls to the dde server. If  the  package  has
54              been  loaded  into  a safe interpreter then a -handler procedure
55              must be defined. The procedure is called with all the  arguments
56              provided by the remote call.
57
58       dde execute ?-async? ?-binary? service topic data
59              dde  execute takes the data and sends it to the server indicated
60              by service with the topic indicated by topic. Typically, service
61              is  the  name of an application, and topic is a file to work on.
62              The data field is given to the remote  application.   Typically,
63              the  application  treats  the  data  field  as a script, and the
64              script is run in the application.  The  -async  option  requests
65              asynchronous  invocation.   The command returns an error message
66              if the script did not run, unless the -async flag was  used,  in
67              which case the command returns immediately with no error.  With‐ │
68              out the -binary option all data will be sent in unicode. For dde │
69              clients  which  don't implement the CF_UNICODE clipboard format, │
70              this will automatically be translated to  the  system  encoding. │
71              You can use the -binary option in combination with the result of │
72              encoding convertto to send data in any other encoding.
73
74       dde poke ?-binary? service topic item data
75              dde poke passes the data to the server indicated by service  us‐
76              ing  the  topic  and  item specified.  Typically, service is the
77              name of an application.  topic is application specific  but  can
78              be  a  command  to  the server or the name of a file to work on.
79              The item is also application specific and is often not used, but
80              it  must always be non-null.  The data field is given to the re‐
81              mote application.  Without the -binary option all data  will  be │
82              sent  in  unicode.  For  dde  clients  which don't implement the │
83              CF_UNICODE clipboard format, this will automatically  be  trans‐ │
84              lated  to the system encoding. You can use the -binary option in │
85              combination with the result of encoding convertto to  send  data │
86              in any other encoding.
87
88       dde request ?-binary? service topic item
89              dde request is typically used to get the value of something; the
90              value of a cell in Microsoft Excel or the text of a selection in
91              Microsoft Word. service is typically the name of an application,
92              topic is typically the name of the file, and  item  is  applica‐
93              tion-specific.  The command returns the value of item as defined
94              in the application.  Normally this is interpreted to be a string
95              with  terminating  null.  If -binary is specified, the result is
96              returned as a byte array.
97
98       dde services service topic
99              dde services returns a list of  service-topic  pairs  that  cur‐
100              rently exist on the machine. If service and topic are both empty
101              strings ({}), then all service-topic pairs  currently  available
102              on  the  system  are  returned. If service is empty and topic is
103              not, then all services with the specified topic are returned. If
104              service  is  non-empty and topic is, all topics for a given ser‐
105              vice are returned. If both are non-empty, if that  service-topic
106              pair  currently  exists,  it  is  returned;  otherwise, an empty
107              string is returned.
108
109       dde eval ?-async? topic cmd ?arg arg ...?
110              dde eval evaluates a command and its arguments using the  inter‐
111              preter  specified  by topic. The DDE service must be the TclEval
112              service.  The -async option  requests  asynchronous  invocation.
113              The  command returns an error message if the script did not run,
114              unless the -async flag was used, in which case the  command  re‐
115              turns  immediately  with  no error.  This command can be used to
116              replace send on Windows.
117

DDE AND TCL

119       A Tcl interpreter always has a service name of TclEval.  Each different
120       interpreter of all running Tcl applications must be given a unique name
121       specified by dde servername. Each interp is available as  a  DDE  topic
122       only  if  the  dde  servername  command was used to set the name of the
123       topic for each interp. So a dde services TclEval {} command will return
124       a  list of service-topic pairs, where each of the currently running in‐
125       terps will be a topic.
126
127       When Tcl processes a dde execute command, the data for the  execute  is
128       run  as  a  script  in the interp named by the topic of the dde execute
129       command.
130
131       When Tcl processes a dde request command, it returns the value  of  the
132       variable given in the dde command in the context of the interp named by
133       the dde topic. Tcl reserves the  variable  $TCLEVAL$EXECUTE$RESULT  for
134       internal  use, and dde request commands for that variable will give un‐
135       predictable results.
136
137       An external application which wishes to run a script in Tcl should have
138       that  script  store  its result in a variable, run the dde execute com‐
139       mand, and then run dde request to get the value of the variable.
140
141       When using DDE, be careful to ensure that the event  queue  is  flushed
142       using  either update or vwait.  This happens by default when using wish
143       unless a blocking command is called (such as exec without adding the  &
144       to  place  the process in the background).  If for any reason the event
145       queue is not flushed, DDE commands may hang until the  event  queue  is
146       flushed.  This can create a deadlock situation.
147

EXAMPLE

149       This  asks Internet Explorer (which must already be running) to go to a
150       particularly important website:
151
152              package require dde
153              dde execute -async iexplore WWW_OpenURL http://www.tcl-lang.org/
154

SEE ALSO

156       tk(n), winfo(n), send(n)
157

KEYWORDS

159       application, dde, name, remote execution
160
161
162
163dde                                   1.4                               dde(n)
Impressum