distrib/share/tcl/help/tcl/control/dde

   1 NAME
   2        dde - Execute a Dynamic Data Exchange command
   3
   4 SYNOPSIS
   5        package require dde 1.2
   6
   7        dde eval ?-async? service cmd ?arg ...?
   8
   9        dde execute ?-async? service topic data
  10
  11        dde poke service topic item data
  12
  13        dde request ?-binary? service topic data
  14
  15        dde servername ?topic?
  16
  17        dde services service topic
  18
  19
  20 DESCRIPTION
  21        This  command allows an application to send Dynamic Data Exchange (DDE)
  22        command when running under Microsoft Windows. Dynamic Data Exchange  is
  23        a mechanism where applications can exchange raw data. Each DDE transac-
  24        tion needs a service name and a topic. Both the service name and  topic
  25        are  application  defined; Tcl uses the service name TclEval, while the
  26        topic name is the name of the  interpreter  given  by  dde  servername.
  27        Other  applications  have  their  own  service  names  and  topics. For
  28        instance, Microsoft Excel has the service name Excel.
  29
  30        The eval and execute commands accept the option -async:
  31
  32
  33 DDE COMMANDS
  34        The following commands are a subset of the full Dynamic  Data  Exchange
  35        set of commands.
  36
  37        dde servername ?topic?
  38               dde  servername  registers  the interpreter as a DDE server with
  39               the service name TclEval and the topic name specified by  topic.
  40               If  no  topic  is  given, dde servername returns the name of the
  41               current topic or the empty string if it is not registered  as  a
  42               service.
  43
  44        dde execute ?-async? service topic data
  45               dde  execute takes the data and sends it to the server indicated
  46               by service with the topic indicated by topic. Typically, service
  47               is  the  name of an application, and topic is a file to work on.
  48               The data field is given to the remote  application.   Typically,
  49               the  application  treats  the  data  field  as a script, and the
  50               script is run in the application.  The  -async  option  requests
  51               asynchronous  invocation.   The command returns an error message
  52               if the script did not run, unless the -async flag was  used,  in
  53               which case the command returns immediately with no error.
  54
  55        dde poke service topic item data
  56               dde  poke  passes  the  data  to the server indicated by service
  57               using the topic and item specified.  Typically, service  is  the
  58               name  of  an application.  topic is application specific but can
  59               be a command to the server or the name of a  file  to  work  on.
  60               The item is also application specific and is often not used, but
  61               it must always be non-null.  The data  field  is  given  to  the
  62               remote application.
  63
  64        dde request ?-binary? service topic item
  65               dde request is typically used to get the value of something; the
  66               value of a cell in Microsoft Excel or the text of a selection in
  67               Microsoft Word. service is typically the name of an application,
  68               topic is typically the name of the file, and  item  is  applica-
  69               tion-specific.  The command returns the value of item as defined
  70               in the application.  Normally this is interpreted to be a string
  71               with  terminating  null.  If -binary is specified, the result is
  72               returned as a byte array.
  73
  74        dde services service topic
  75               dde services returns a list of  service-topic  pairs  that  cur-
  76               rently  exist on the machine. If service and topic are both null
  77               strings ({}), then all service-topic pairs  currently  available
  78               on the system are returned. If service is null and topic is not,
  79               then all services with the specified topic are returned. If ser-
  80               vice  is  not  null and topic is, all topics for a given service
  81               are returned. If both are not null, if that  service-topic  pair
  82               currently exists, it is returned; otherwise, null is returned.
  83
  84        dde eval ?-async? topic cmd ?arg arg ...?
  85               dde  eval evaluates a command and its arguments using the inter-
  86               preter specified by topic. The DDE service must be  the  TclEval
  87               service.   The  -async  option requests asynchronous invocation.
  88               The command returns an error message if the script did not  run,
  89               unless  the  -async  flag  was  used,  in which case the command
  90               returns immediately with no error.  This command can be used  to
  91               replace send on Windows.
  92
  93
  94 DDE AND TCL
  95        A Tcl interpreter always has a service name of TclEval.  Each different
  96        interpreter of all running Tcl applications must be given a unique name
  97        specified  by  dde  servername. Each interp is available as a DDE topic
  98        only if the dde servername command was used to  set  the  name  of  the
  99        topic for each interp. So a dde services TclEval {} command will return
 100        a list of service-topic pairs, where  each  of  the  currently  running
 101        interps will be a topic.
 102
 103        When  Tcl  processes a dde execute command, the data for the execute is
 104        run as a script in the interp named by the topic  of  the  dde  execute
 105        command.
 106
 107        When  Tcl  processes a dde request command, it returns the value of the
 108        variable given in the dde command in the context of the interp named by
 109        the  dde  topic.  Tcl reserves the variable $TCLEVAL$EXECUTE$RESULT for
 110        internal use, and dde request commands  for  that  variable  will  give
 111        unpredictable results.
 112
 113        An external application which wishes to run a script in Tcl should have
 114        that script store its result in a variable, run the  dde  execute  com-
 115        mand, and the run dde request to get the value of the variable.
 116
 117        When  using  DDE,  be careful to ensure that the event queue is flushed
 118        using either update or vwait.  This happens by default when using  wish
 119        unless  a blocking command is called (such as exec without adding the &
 120        to place the process in the background).  If for any reason  the  event
 121        queue  is  not  flushed, DDE commands may hang until the event queue is
 122        flushed.  This can create a deadlock situation.
 123
 124
 125 EXAMPLE
 126        This asks Internet Explorer (which must already be running) to go to  a
 127        particularly important website:
 128               package require dde
 129               dde execute iexplore WWW_OpenURL http://www.tcl.tk/
 130
 131
 132 SEE ALSO
 133        tk(n), winfo(n), send(n)
 134
 135
 136 KEYWORDS