NAME
       dde - Execute a Dynamic Data Exchange command

SYNOPSIS
       package require dde 1.1

       dde servername ?topic?

       dde ?-async? command 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 only option to the dde command is:

       -async Requests asynchronous invocation.   This  is  valid
              only  for the execute subcommand. Normally, the dde
              execute subcommand waits  until  the  command  com-
              pletes,  returning appropriate error messages. When
              the -async option  is  used,  the  command  returns
              immediately, and no error information is available.

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 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  command returns an error if the script did not
              run. If the  -async  flag  was  used,  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 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.

       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 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.  This command
              can be used to replace send on Windows.

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
       application, dde, name, remote execution
