NAME
       dde - Execute a Dynamic Data Exchange command

SYNOPSIS
       package require dde 1.2

       dde servername ?topic?

       dde execute ?-async? service topic ?data?

       dde poke service topic item data

       dde request ?-binary? service topic ?data?

       dde services service topic ?data?

       dde eval ?-async? service topic ?data?


DESCRIPTION
       This  command  allows  an application to send Dynamic Data
       Exchange (DDE) command when running under  Microsoft  Win-
       dows.  Dynamic Data Exchange is a mechanism where applica-
       tions can exchange raw data. Each DDE transaction needs  a
       service  name and a topic. Both the service name and topic
       are application defined; Tcl uses the service  name  TclE-
       val,  while  the topic name is the name of the interpreter
       given by dde servername. Other applications have their own
       service  names  and  topics. For instance, Microsoft Excel
       has the service name Excel.

       The eval and execute commands accept the option -async:



       DDE COMMANDS

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

       dde servername ?topic?
              dde  servername  registers the interpreter as a DDE
              server with the service name TclEval and the  topic
              name specified by topic.  If no topic is given, dde
              servername returns the name of the current topic or
              the  empty string if it is not registered as a ser-
              vice.

       dde execute ?-async? service topic data
              dde execute takes the data  and  sends  it  to  the
              server  indicated  by  service with the topic indi-
              cated by topic. Typically, service is the  name  of
              an  application,  and  topic  is a file to work on.
              The data field is given to the remote  application.
              Typically, the application treats the data field as
              a script, and the script is run in the application.
              The -async option requests asynchronous invocation.
              The command returns an error message if the  script
              did  not  run,  unless the -async flag was used, in
              which case the command returns immediately with  no
              error.

       dde poke service topic item data
              dde poke passes the data to the server indicated by
              service using the topic and item specified.   Typi-
              cally,  service  is  the  name  of  an application.
              topic is application specific but can be a  command
              to  the  server  or  the name of a file to work on.
              The item is also application specific and is  often
              not used, but it must always be non-null.  The data
              field is given to the remote application.

       dde request ?-binary? service topic item
              dde request is 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.  ser-
              vice is typically the name of an application, topic
              is typically the name of  the  file,  and  item  is
              application-specific. The command returns the value
              of item as defined in  the  application.   Normally
              this is interpreted to be a string with terminating
              null.  If  -binary  is  specified,  the  result  is
              returned as a byte array.

       dde services service topic
              dde  services returns a list of service-topic pairs
              that currently exist on the machine. If service and
              topic are both null strings ({}), then all service-
              topic pairs currently available on the  system  are
              returned. If service is null and topic is not, then
              all services with the specified topic are returned.
              If service is not null and topic 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.

       dde eval ?-async? topic cmd ?arg arg ...?
              dde eval evaluates  a  command  and  its  arguments
              using  the  interpreter specified by topic. The DDE
              service must be the TclEval  service.   The  -async
              option  requests asynchronous invocation.  The com-
              mand returns an error message if the script did not
              run, unless the -async flag was used, in which case
              the command  returns  immediately  with  no  error.
              This  command  can  be used to replace send on Win-
              dows.


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

       When Tcl processes a dde execute command, the data for the
       execute is run as a script in  the  interp  named  by  the
       topic of the dde execute command.

       When  Tcl  processes a dde request command, it returns the
       value of the variable given in the dde command in the con-
       text  of  the  interp named by the dde topic. Tcl reserves
       the variable $TCLEVAL$EXECUTE$RESULT for internal use, and
       dde  request  commands  for that variable will give unpre-
       dictable results.

       An external application which wishes to run  a  script  in
       Tcl  should  have  that script store its result in a vari-
       able, run the dde execute command, and the run dde request
       to get the value of the variable.

       When  using DDE, be careful to ensure that the event queue
       is flushed using either update or vwait.  This happens  by
       default  when  using  wish  unless  a  blocking command is
       called (such as exec without adding the  &  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 situa-
       tion.


SEE ALSO
       tk(n), winfo(n), send(n)


KEYWORDS
