2 '\" Copyright (c
) 1997 Sun Microsystems
, Inc
.
4 '\" See the file
"license.terms" for information on usage
and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 '\" RCS: @(#) $Id: dde.n,v 1.1 2003/12/20 03:31:54 bbbush Exp $
9 '\" The definitions below are for supplemental macros used in Tcl/Tk
12 '\" .AP
type name
in/out ?indent?
13 '\" Start paragraph describing an argument to a library procedure.
14 '\" type is
type of
argument (int, etc
.), in/out is either
"in", "out",
15 '\" or "in/out" to describe whether procedure reads or modifies arg,
16 '\" and indent is equivalent to second arg of
.IP (shouldn
't ever be
17 '\" needed
; use
.AS below instead
)
20 '\" Give maximum sizes of arguments for setting tab stops. Type and
21 '\" name are examples of largest possible arguments that will be passed
22 '\" to .AP later. If args are omitted, default tab stops are used.
25 '\" Start box enclosure
. From here until next
.BE
, everything will be
26 '\" enclosed in one large box.
29 '\" End of box enclosure
.
32 '\" Begin code excerpt.
37 '\" .VS ?version? ?br?
38 '\" Begin vertical sidebar, for use in marking newly-changed parts
39 '\" of man pages
. The first argument is ignored
and used
for recording
40 '\" the version when the .VS was added, so that the sidebars can be
41 '\" found
and removed
when they reach a certain age
. If another argument
42 '\" is present, then a line break is forced before starting the sidebar.
45 '\" End of vertical sidebar
.
48 '\" Begin an indented unfilled display.
51 '\" End of indented unfilled display
.
54 '\" Start of list of standard options for a Tk widget. The
55 '\" options follow on successive lines
, in four columns separated
59 '\" End of
list of standard options
for a Tk widget
.
61 '\" .OP cmdName dbName dbClass
62 '\" Start of description of a specific option. cmdName gives the
63 '\" option
's name as specified in the class command, dbName gives
64 '\" the option
's name in the option database, and dbClass gives
65 '\" the option
's class in the option database.
68 '\" Print arg1 underlined
, then print arg2 normally
.
70 '\" RCS
: @
(#) $Id: dde.n,v 1.1 2003/12/20 03:31:54 bbbush Exp $
72 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
76 '\" # Start an argument description
80 . ie !"\\$2"" .TP \\n()Cu
85 \&\\$1 \\fI\\$2\\fP (\\$3)
98 '\" # define tabbing values for .AP
101 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
104 .if !"\\$2
"" .nr
)B
\\w
'\\$2'u
+\\n()Au
+3n
105 .nr
)C
\\n()Bu
+\\w
'(in/out)'u
+2n
107 .AS Tcl_Interp Tcl_CreateInterp
in/out
108 '\" # BS - start boxed text
109 '\" # ^y = starting y location
117 .if n \l'\\n(.lu\
(ul
'
120 '\" # BE - end boxed text (draw box now)
125 .ie n \l
'\\n(^lu\(ul'
127 .\" Draw four
-sided box normally
, but don
't draw top of
128 .\" box if the box started on an earlier page.
130 \h'-1.5n
'\L'|\\n(^yu
-1v
'\l'\\n(^lu
+3n\
(ul
'\L'\\n(^tu
+1v
-\\n(^yu
'\l'|0u-1.5n\
(ul
'
133 \h'-1.5n
'\L'|\\n(^yu
-1v
'\h'\\n(^lu
+3n
'\L'\\n(^tu
+1v
-\\n(^yu
'\l'|0u-1.5n\
(ul
'
140 '\" # VS - start vertical sidebar
141 '\" # ^Y = starting y location
142 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
146 .ie n 'mc \s12\(br\s0
149 '\" # VE - end of vertical sidebar
157 \h
'|\\n(^lu+3n'\L
'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h
'-|\\n(^lu+3n'
164 '\" # Special macro to handle page bottom: finish off current
165 '\" # box/sidebar if in box/sidebar mode, then invoked standard
166 '\" # page bottom macro.
173 .\" Draw three-sided box if this is the box's first page
,
174 .\" draw two sides but no top otherwise
.
175 .ie
!\\n(^b
-1 \h
'-1.5n'\L
'|\\n(^yu-1v'\l
'\\n(^lu+3n\(ul'\L
'\\n(^tu+1v-\\n(^yu'\h
'|0u'\c
176 .el \h
'-1.5n'\L
'|\\n(^yu-1v'\h
'\\n(^lu+3n'\L
'\\n(^tu+1v-\\n(^yu'\h
'|0u'\c
179 .nr ^x
\\n(^tu
+1v
-\\n(^Yu
180 \kx\h
'-\\nxu'\h
'|\\n(^lu+3n'\ky\L
'-\\n(^xu'\v'\\n(^xu'\h
'|0u'\c
193 '\" # DS - begin display
199 '\" # DE - end display
205 '\" # SO - start of list of standard options
207 .SH
"STANDARD OPTIONS"
213 '\" # SE - end of list of standard options
218 See the \\fBoptions\\fR manual entry for details on the standard options.
220 '\" # OP - start of full description for a single option
225 Command
-Line Name
: \\fB
\\$1
\\fR
226 Database Name
: \\fB
\\$2
\\fR
227 Database Class
: \\fB
\\$3
\\fR
231 '\" # CS - begin code excerpt
237 '\" # CE - end code excerpt
245 .TH dde n
8.1 Tcl
"Tcl Built-In Commands"
247 '\" Note: do not modify the .SH NAME line immediately below!
249 dde \- Execute a Dynamic Data Exchange command
252 \fBpackage require dde 1.1\fR
254 \fBdde \fIservername \fR?\fItopic\fR?
256 \fBdde ?\-async?\fR \fIcommand service topic \fR?\fIdata\fR?
261 This command allows an application to send Dynamic Data Exchange (DDE)
262 command when running under Microsoft Windows. Dynamic Data Exchange is
263 a mechanism where applications can exchange raw data. Each DDE
264 transaction needs a \fIservice name\fR and a \fItopic\fR. Both the
265 \fIservice name\fR and \fItopic\fR are application defined; Tcl uses
266 the service name \fBTclEval\fR, while the topic name is the name of the
267 interpreter given by \fBdde servername\fR. Other applications have their
268 own \fIservice names\fR and \fItopics\fR. For instance, Microsoft Excel
269 has the service name \fBExcel\fR.
271 The only option to the \fBdde\fR command is:
274 Requests asynchronous invocation. This is valid only for the
275 \fBexecute\fR subcommand. Normally, the \fBdde execute\fR subcommand
276 waits until the command completes, returning appropriate error
277 messages. When the \fB\-async\fR option is used, the command returns
278 immediately, and no error information is available.
281 The following commands are a subset of the full Dynamic Data Exchange
284 \fBdde servername \fR?\fItopic\fR?
285 \fBdde servername\fR registers the interpreter as a DDE server with
286 the service name \fBTclEval\fR and the topic name specified by \fItopic\fR.
287 If no \fItopic\fR is given, \fBdde servername\fR returns the name
288 of the current topic or the empty string if it is not registered as a service.
290 \fBdde execute \fIservice topic data\fR
291 \fBdde execute\fR takes the \fIdata\fR and sends it to the server
292 indicated by \fIservice\fR with the topic indicated by
293 \fItopic\fR. Typically, \fIservice\fR is the name of an application,
294 and \fItopic\fR is a file to work on. The \fIdata\fR field is given
295 to the remote application. Typically, the application treats the
296 \fIdata\fR field as a script, and the script is run in the
297 application. The command returns an error if the script did not
298 run. If the \fB\-async\fR flag was used, the command
299 returns immediately with no error.
301 \fBdde poke \fIservice topic item data\fR
302 \fBdde poke\fR passes the \fIdata\fR to the server indicated by
303 \fIservice\fR using the \fItopic\fR and \fIitem\fR specified. Typically,
304 \fIservice\fR is the name of an application. \fItopic\fR is application
305 specific but can be a command to the server or the name of a file to work
306 on. The \fIitem\fR is also application specific and is often not used, but
307 it must always be non-null. The \fIdata\fR field is given to the remote
310 \fBdde request \fIservice topic item\fR
311 \fBdde request\fR is typically used to get the value of something; the
312 value of a cell in Microsoft Excel or the text of a selection in
313 Microsoft Word. \fIservice\fR is typically the name of an application,
314 \fItopic\fR is typically the name of the file, and \fIitem\fR is
315 application-specific. The command returns the value of \fIitem\fR as
316 defined in the application.
318 \fBdde services \fIservice topic\fR
319 \fBdde services\fR returns a list of service-topic pairs that
320 currently exist on the machine. If \fIservice\fR and \fItopic\fR are
321 both null strings ({}), then all service-topic pairs currently
322 available on the system are returned. If \fIservice\fR is null and
323 \fItopic\fR is not, then all services with the specified topic are
324 returned. If \fIservice\fR is not null and \fItopic\fR is, all topics
325 for a given service are returned. If both are not null, if that
326 service-topic pair currently exists, it is returned; otherwise, null
329 \fBdde eval \fItopic cmd \fR?\fIarg arg ...\fR?
330 \fBdde eval\fR evaluates a command and its arguments using the
331 interpreter specified by \fItopic\fR. The DDE service must be the
332 \fBTclEval\fR service. This command can be used to replace send on
335 A Tcl interpreter always has a service name of \fBTclEval\fR. Each
336 different interpreter of all running Tcl applications must be
338 name specified by \fBdde servername\fR. Each interp is available as a
339 DDE topic only if the \fBdde servername\fR command was used to set the
340 name of the topic for each interp. So a \fBdde services TclEval {}\fR
341 command will return a list of service-topic pairs, where each of the
342 currently running interps will be a topic.
344 When Tcl processes a \fBdde execute\fR command, the data for the
345 execute is run as a script in the interp named by the topic of the
346 \fBdde execute\fR command.
348 When Tcl processes a \fBdde request\fR command, it returns the value of the
349 variable given in the dde command in the context of the interp named by the
350 dde topic. Tcl reserves the variable \fB$TCLEVAL$EXECUTE$RESULT\fR for
351 internal use, and \fBdde request\fR commands for that variable will give
352 unpredictable results.
354 An external application which wishes to run a script in Tcl should have
355 that script store its result in a variable, run the \fBdde execute\fR
356 command, and the run \fBdde request\fR to get the value of the
359 When using DDE, be careful to ensure that the event queue is flushed
360 using either \fBupdate\fR or \fBvwait\fR. This happens by default
361 when using \fBwish\fR unless a blocking command is called (such as \fBexec\fR
362 without adding the \fB&\fR to place the process in the background).
363 If for any reason the event queue is not flushed, DDE commands may
364 hang until the event queue is flushed. This can create a deadlock
368 tk(n), winfo(n), send(n)
371 application, dde, name, remote execution