<HTML><HEAD><TITLE>Tcl Built-In Commands - dde manual page</TITLE></HEAD><BODY>
<DL>
<DD><A HREF="dde.htm#M2" NAME="L166">NAME</A>
<DL><DD>dde - Execute a Dynamic Data Exchange command</DL>
<DD><A HREF="dde.htm#M3" NAME="L167">SYNOPSIS</A>
<DL>
<DD><B>package require dde 1.1</B>
<DD><B>dde </B><I>servername </I>?<I>topic</I>?
<DD><B>dde ?-async?</B> <I>command service topic </I>?<I>data</I>?
</DL>
<DD><A HREF="dde.htm#M4" NAME="L168">DESCRIPTION</A>
<DL>
<DD><A HREF="dde.htm#M5" NAME="L169"><B>-async</B></A>
</DL>
<DD><A HREF="dde.htm#M6" NAME="L170">DDE COMMANDS</A>
<DL>
<DD><A HREF="dde.htm#M7" NAME="L171"><B>dde servername </B>?<I>topic</I>?</A>
<DD><A HREF="dde.htm#M8" NAME="L172"><B>dde execute </B><I>service topic data</I></A>
<DD><A HREF="dde.htm#M9" NAME="L173"><B>dde poke </B><I>service topic item data</I></A>
<DD><A HREF="dde.htm#M10" NAME="L174"><B>dde request </B><I>service topic item</I></A>
<DD><A HREF="dde.htm#M11" NAME="L175"><B>dde services </B><I>service topic</I></A>
<DD><A HREF="dde.htm#M12" NAME="L176"><B>dde eval </B><I>topic cmd </I>?<I>arg arg ...</I>?</A>
</DL>
<DD><A HREF="dde.htm#M13" NAME="L177">DDE AND TCL</A>
<DD><A HREF="dde.htm#M14" NAME="L178">SEE ALSO</A>
<DD><A HREF="dde.htm#M15" NAME="L179">KEYWORDS</A>
</DL><HR>
<H3><A NAME="M2">NAME</A></H3>
dde - Execute a Dynamic Data Exchange command
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>package require dde 1.1</B><BR>
<B>dde </B><I>servername </I>?<I>topic</I>?<BR>
<B>dde ?-async?</B> <I>command service topic </I>?<I>data</I>?<BR>
<H3><A NAME="M4">DESCRIPTION</A></H3>
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
transaction needs a <I>service name</I> and a <I>topic</I>. Both the
<I>service name</I> and <I>topic</I> are application defined; Tcl uses
the service name <B>TclEval</B>, while the topic name is the name of the
interpreter given by <B>dde servername</B>. Other applications have their
own <I>service names</I> and <I>topics</I>. For instance, Microsoft Excel
has the service name <B>Excel</B>.
<P>
The only option to the <B>dde</B> command is:
<P>
<DL>
<P><DT><A NAME="M5"><B>-async</B></A><DD>
Requests asynchronous invocation. This is valid only for the
<B>execute</B> subcommand. Normally, the <B>dde execute</B> subcommand
waits until the command completes, returning appropriate error
messages. When the <B>-async</B> option is used, the command returns
immediately, and no error information is available.
<P></DL>
<H3><A NAME="M6">DDE COMMANDS</A></H3>
The following commands are a subset of the full Dynamic Data Exchange
set of commands.
<P>
<DL>
<P><DT><A NAME="M7"><B>dde servername </B>?<I>topic</I>?</A><DD>
<B>dde servername</B> registers the interpreter as a DDE server with
the service name <B>TclEval</B> and the topic name specified by <I>topic</I>.
If no <I>topic</I> is given, <B>dde servername</B> returns the name
of the current topic or the empty string if it is not registered as a service.
<P><DT><A NAME="M8"><B>dde execute </B><I>service topic data</I></A><DD>
<B>dde execute</B> takes the <I>data</I> and sends it to the server
indicated by <I>service</I> with the topic indicated by
<I>topic</I>. Typically, <I>service</I> is the name of an application,
and <I>topic</I> is a file to work on. The <I>data</I> field is given
to the remote application. Typically, the application treats the
<I>data</I> 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 <B>-async</B> flag was used, the command
returns immediately with no error.
<P><DT><A NAME="M9"><B>dde poke </B><I>service topic item data</I></A><DD>
<B>dde poke</B> passes the <I>data</I> to the server indicated by
<I>service</I> using the <I>topic</I> and <I>item</I> specified. Typically,
<I>service</I> is the name of an application. <I>topic</I> is application
specific but can be a command to the server or the name of a file to work
on. The <I>item</I> is also application specific and is often not used, but
it must always be non-null. The <I>data</I> field is given to the remote
application.
<P><DT><A NAME="M10"><B>dde request </B><I>service topic item</I></A><DD>
<B>dde request</B> 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. <I>service</I> is typically the name of an application,
<I>topic</I> is typically the name of the file, and <I>item</I> is
application-specific. The command returns the value of <I>item</I> as
defined in the application.
<P><DT><A NAME="M11"><B>dde services </B><I>service topic</I></A><DD>
<B>dde services</B> returns a list of service-topic pairs that
currently exist on the machine. If <I>service</I> and <I>topic</I> are
both null strings ({}), then all service-topic pairs currently
available on the system are returned. If <I>service</I> is null and
<I>topic</I> is not, then all services with the specified topic are
returned. If <I>service</I> is not null and <I>topic</I> 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.
<P><DT><A NAME="M12"><B>dde eval </B><I>topic cmd </I>?<I>arg arg ...</I>?</A><DD>
<B>dde eval</B> evaluates a command and its arguments using the
interpreter specified by <I>topic</I>. The DDE service must be the
<B>TclEval</B> service. This command can be used to replace send on
Windows.
<P></DL>
<H3><A NAME="M13">DDE AND TCL</A></H3>
A Tcl interpreter always has a service name of <B>TclEval</B>. Each
different interpreter of all running Tcl applications must be
given a unique
name specified by <B>dde servername</B>. Each interp is available as a
DDE topic only if the <B>dde servername</B> command was used to set the
name of the topic for each interp. So a <B>dde services TclEval {}</B>
command will return a list of service-topic pairs, where each of the
currently running interps will be a topic.
<P>
When Tcl processes a <B>dde execute</B> command, the data for the
execute is run as a script in the interp named by the topic of the
<B>dde execute</B> command.
<P>
When Tcl processes a <B>dde request</B> command, 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 <B>$TCLEVAL$EXECUTE$RESULT</B> for
internal use, and <B>dde request</B> commands for that variable will give
unpredictable results.
<P>
An external application which wishes to run a script in Tcl should have
that script store its result in a variable, run the <B>dde execute</B>
command, and the run <B>dde request</B> to get the value of the
variable.
<P>
When using DDE, be careful to ensure that the event queue is flushed
using either <B><A HREF="../TkCmd/update.htm">update</A></B> or <B><A HREF="../TkCmd/vwait.htm">vwait</A></B>. This happens by default
when using <B><A HREF="../UserCmd/wish.htm">wish</A></B> unless a blocking command is called (such as <B><A HREF="../TkCmd/exec.htm">exec</A></B>
without adding the <B>&</B> 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.
<H3><A NAME="M14">SEE ALSO</A></H3>
<B><A HREF="../TclCmd/tk.htm">tk</A></B>, <B><A HREF="../TclCmd/winfo.htm">winfo</A></B>, <B><A HREF="../TclCmd/send.htm">send</A></B>
<H3><A NAME="M15">KEYWORDS</A></H3>
<A href="../Keywords/A.htm#application">application</A>, <A href="../Keywords/D.htm#dde">dde</A>, <A href="../Keywords/N.htm#name">name</A>, <A href="../Keywords/R.htm#remote execution">remote execution</A>
<HR><PRE>
<A HREF="../copyright.htm">Copyright</A> © 1997 Sun Microsystems, Inc.
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
</BODY></HTML>