1mNAME0m
       dde - Execute a Dynamic Data Exchange command

1mSYNOPSIS0m
       1mpackage require dde 1.20m

       1mdde eval 22m?1m-async22m? 4mservice24m 4mcmd24m ?4marg24m 4m...24m?

       1mdde execute 22m?1m-async22m? 4mservice24m 4mtopic24m 4mdata0m

       1mdde poke 4m22mservice24m 4mtopic24m 4mitem24m 4mdata0m

       1mdde request 22m?1m-binary22m? 4mservice24m 4mtopic24m 4mdata0m

       1mdde servername 22m?4mtopic24m?

       1mdde services 4m22mservice24m 4mtopic0m


1mDESCRIPTION0m
       This  command allows an application to send Dynamic Data Exchange (DDE)
       command when running under Microsoft Windows. Dynamic Data Exchange  is
       a mechanism where applications can exchange raw data. Each DDE transac-
       tion needs a 4mservice24m 4mname24m and a 4mtopic24m. Both the 4mservice24m 4mname24m and  4mtopic0m
       are  application  defined; Tcl uses the service name 1mTclEval22m, while the
       topic name is the name of the  interpreter  given  by  1mdde  servername22m.
       Other  applications  have  their  own  4mservice24m  4mname24ms  and  4mtopic24ms. For
       instance, Microsoft Excel has the service name 1mExcel22m.

       The 1meval 22mand 1mexecute 22mcommands accept the option 1m-async22m:


1mDDE COMMANDS0m
       The following commands are a subset of the full Dynamic  Data  Exchange
       set of commands.

       1mdde servername 22m?4mtopic24m?
              1mdde  servername  22mregisters  the interpreter as a DDE server with
              the service name 1mTclEval 22mand the topic name specified by  4mtopic24m.
              If  no  4mtopic24m  is  given, 1mdde servername 22mreturns the name of the
              current topic or the empty string if it is not registered  as  a
              service.

       1mdde execute 22m?1m-async22m? 4mservice24m 4mtopic24m 4mdata0m
              1mdde  execute 22mtakes the 4mdata24m and sends it to the server indicated
              by 4mservice24m with the topic indicated by 4mtopic24m. Typically, 4mservice0m
              is  the  name of an application, and 4mtopic24m is a file to work on.
              The 4mdata24m field is given to the remote  application.   Typically,
              the  application  treats  the  4mdata24m  field  as a script, and the
              script is run in the application.  The  1m-async  22moption  requests
              asynchronous  invocation.   The command returns an error message
              if the script did not run, unless the 1m-async 22mflag was  used,  in
              which case the command returns immediately with no error.

       1mdde poke 4m22mservice24m 4mtopic24m 4mitem24m 4mdata0m
              1mdde  poke  22mpasses  the  4mdata24m  to the server indicated by 4mservice0m
              using the 4mtopic24m and 4mitem24m specified.  Typically, 4mservice24m  is  the
              name  of  an application.  4mtopic24m is application specific but can
              be a command to the server or the name of a  file  to  work  on.
              The 4mitem24m is also application specific and is often not used, but
              it must always be non-null.  The 4mdata24m  field  is  given  to  the
              remote application.

       1mdde request 22m?1m-binary22m? 4mservice24m 4mtopic24m 4mitem0m
              1mdde request 22mis typically used to get the value of something; the
              value of a cell in Microsoft Excel or the text of a selection in
              Microsoft Word. 4mservice24m is typically the name of an application,
              4mtopic24m is typically the name of the file, and  4mitem24m  is  applica-
              tion-specific.  The command returns the value of 4mitem24m as defined
              in the application.  Normally this is interpreted to be a string
              with  terminating  null.  If 1m-binary 22mis specified, the result is
              returned as a byte array.

       1mdde services 4m22mservice24m 4mtopic0m
              1mdde services 22mreturns a list of  service-topic  pairs  that  cur-
              rently  exist on the machine. If 4mservice24m and 4mtopic24m are both null
              strings ({}), then all service-topic pairs  currently  available
              on the system are returned. If 4mservice24m is null and 4mtopic24m is not,
              then all services with the specified topic are returned. If 4mser-0m
              4mvice24m  is  not  null and 4mtopic24m is, all topics for a given service
              are returned. If both are not null, if that  service-topic  pair
              currently exists, it is returned; otherwise, null is returned.

       1mdde eval 22m?1m-async22m? 4mtopic24m 4mcmd24m ?4marg24m 4marg24m 4m...24m?
              1mdde  eval 22mevaluates a command and its arguments using the inter-
              preter specified by 4mtopic24m. The DDE service must be  the  1mTclEval0m
              service.   The  1m-async  22moption requests asynchronous invocation.
              The command returns an error message if the script did not  run,
              unless  the  1m-async  22mflag  was  used,  in which case the command
              returns immediately with no error.  This command can be used  to
              replace 1msend 22mon Windows.


1mDDE AND TCL0m
       A Tcl interpreter always has a service name of 1mTclEval22m.  Each different
       interpreter of all running Tcl applications must be given a unique name
       specified  by  1mdde  servername22m. Each interp is available as a DDE topic
       only if the 1mdde servername 22mcommand was used to  set  the  name  of  the
       topic for each interp. So a 1mdde services TclEval {} 22mcommand will return
       a list of service-topic pairs, where  each  of  the  currently  running
       interps will be a topic.

       When  Tcl  processes a 1mdde execute 22mcommand, the data for the execute is
       run as a script in the interp named by the topic  of  the  1mdde  execute0m
       command.

       When  Tcl  processes a 1mdde request 22mcommand, it returns the value of the
       variable given in the dde command in the context of the interp named by
       the  dde  topic.  Tcl reserves the variable 1m$TCLEVAL$EXECUTE$RESULT 22mfor
       internal use, and 1mdde request 22mcommands  for  that  variable  will  give
       unpredictable results.

       An external application which wishes to run a script in Tcl should have
       that script store its result in a variable, run the  1mdde  execute  22mcom-
       mand, and the run 1mdde request 22mto get the value of the variable.

       When  using  DDE,  be careful to ensure that the event queue is flushed
       using either 1mupdate 22mor 1mvwait22m.  This happens by default when using  1mwish0m
       unless  a blocking command is called (such as 1mexec 22mwithout adding the 1m&0m
       to place the process in the background).  If for any reason  the  event
       queue  is  not  flushed, DDE commands may hang until the event queue is
       flushed.  This can create a deadlock situation.


1mEXAMPLE0m
       This asks Internet Explorer (which must already be running) to go to  a
       particularly important website:
              package require dde
              1mdde execute 22miexplore WWW_OpenURL http://www.tcl.tk/


1mSEE ALSO0m
       tk(n), winfo(n), send(n)


1mKEYWORDS0m
