| '\" |
| '\" Copyright (c) 1997 Sun Microsystems, Inc. |
| '\" Copyright (c) 2001 ActiveState Corporation. |
| '\" |
| '\" See the file "license.terms" for information on usage and redistribution |
| '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
| '\" |
| '\" RCS: @(#) $Id: dde.n,v 1.8 2002/06/27 22:29:08 dgp Exp $ |
| '\" |
| '\" The definitions below are for supplemental macros used in Tcl/Tk |
| '\" manual entries. |
| '\" |
| '\" .AP type name in/out ?indent? |
| '\" Start paragraph describing an argument to a library procedure. |
| '\" type is type of argument (int, etc.), in/out is either "in", "out", |
| '\" or "in/out" to describe whether procedure reads or modifies arg, |
| '\" and indent is equivalent to second arg of .IP (shouldn't ever be |
| '\" needed; use .AS below instead) |
| '\" |
| '\" .AS ?type? ?name? |
| '\" Give maximum sizes of arguments for setting tab stops. Type and |
| '\" name are examples of largest possible arguments that will be passed |
| '\" to .AP later. If args are omitted, default tab stops are used. |
| '\" |
| '\" .BS |
| '\" Start box enclosure. From here until next .BE, everything will be |
| '\" enclosed in one large box. |
| '\" |
| '\" .BE |
| '\" End of box enclosure. |
| '\" |
| '\" .CS |
| '\" Begin code excerpt. |
| '\" |
| '\" .CE |
| '\" End code excerpt. |
| '\" |
| '\" .VS ?version? ?br? |
| '\" Begin vertical sidebar, for use in marking newly-changed parts |
| '\" of man pages. The first argument is ignored and used for recording |
| '\" the version when the .VS was added, so that the sidebars can be |
| '\" found and removed when they reach a certain age. If another argument |
| '\" is present, then a line break is forced before starting the sidebar. |
| '\" |
| '\" .VE |
| '\" End of vertical sidebar. |
| '\" |
| '\" .DS |
| '\" Begin an indented unfilled display. |
| '\" |
| '\" .DE |
| '\" End of indented unfilled display. |
| '\" |
| '\" .SO |
| '\" Start of list of standard options for a Tk widget. The |
| '\" options follow on successive lines, in four columns separated |
| '\" by tabs. |
| '\" |
| '\" .SE |
| '\" End of list of standard options for a Tk widget. |
| '\" |
| '\" .OP cmdName dbName dbClass |
| '\" Start of description of a specific option. cmdName gives the |
| '\" option's name as specified in the class command, dbName gives |
| '\" the option's name in the option database, and dbClass gives |
| '\" the option's class in the option database. |
| '\" |
| '\" .UL arg1 arg2 |
| '\" Print arg1 underlined, then print arg2 normally. |
| '\" |
| '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ |
| '\" |
| '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
| .if t .wh -1.3i ^B |
| .nr ^l \n(.l |
| .ad b |
| '\" # Start an argument description |
| .de AP |
| .ie !"\\$4"" .TP \\$4 |
| .el \{\ |
| . ie !"\\$2"" .TP \\n()Cu |
| . el .TP 15 |
| .\} |
| .ta \\n()Au \\n()Bu |
| .ie !"\\$3"" \{\ |
| \&\\$1 \\fI\\$2\\fP (\\$3) |
| .\".b |
| .\} |
| .el \{\ |
| .br |
| .ie !"\\$2"" \{\ |
| \&\\$1 \\fI\\$2\\fP |
| .\} |
| .el \{\ |
| \&\\fI\\$1\\fP |
| .\} |
| .\} |
| .. |
| '\" # define tabbing values for .AP |
| .de AS |
| .nr )A 10n |
| .if !"\\$1"" .nr )A \\w'\\$1'u+3n |
| .nr )B \\n()Au+15n |
| .\" |
| .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
| .nr )C \\n()Bu+\\w'(in/out)'u+2n |
| .. |
| .AS Tcl_Interp Tcl_CreateInterp in/out |
| '\" # BS - start boxed text |
| '\" # ^y = starting y location |
| '\" # ^b = 1 |
| .de BS |
| .br |
| .mk ^y |
| .nr ^b 1u |
| .if n .nf |
| .if n .ti 0 |
| .if n \l'\\n(.lu\(ul' |
| .if n .fi |
| .. |
| '\" # BE - end boxed text (draw box now) |
| .de BE |
| .nf |
| .ti 0 |
| .mk ^t |
| .ie n \l'\\n(^lu\(ul' |
| .el \{\ |
| .\" Draw four-sided box normally, but don't draw top of |
| .\" box if the box started on an earlier page. |
| .ie !\\n(^b-1 \{\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .el \}\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .\} |
| .fi |
| .br |
| .nr ^b 0 |
| .. |
| '\" # VS - start vertical sidebar |
| '\" # ^Y = starting y location |
| '\" # ^v = 1 (for troff; for nroff this doesn't matter) |
| .de VS |
| .if !"\\$2"" .br |
| .mk ^Y |
| .ie n 'mc \s12\(br\s0 |
| .el .nr ^v 1u |
| .. |
| '\" # VE - end of vertical sidebar |
| .de VE |
| .ie n 'mc |
| .el \{\ |
| .ev 2 |
| .nf |
| .ti 0 |
| .mk ^t |
| \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
| .sp -1 |
| .fi |
| .ev |
| .\} |
| .nr ^v 0 |
| .. |
| '\" # Special macro to handle page bottom: finish off current |
| '\" # box/sidebar if in box/sidebar mode, then invoked standard |
| '\" # page bottom macro. |
| .de ^B |
| .ev 2 |
| 'ti 0 |
| 'nf |
| .mk ^t |
| .if \\n(^b \{\ |
| .\" Draw three-sided box if this is the box's first page, |
| .\" draw two sides but no top otherwise. |
| .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 |
| .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| .\} |
| .if \\n(^v \{\ |
| .nr ^x \\n(^tu+1v-\\n(^Yu |
| \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
| .\} |
| .bp |
| 'fi |
| .ev |
| .if \\n(^b \{\ |
| .mk ^y |
| .nr ^b 2 |
| .\} |
| .if \\n(^v \{\ |
| .mk ^Y |
| .\} |
| .. |
| '\" # DS - begin display |
| .de DS |
| .RS |
| .nf |
| .sp |
| .. |
| '\" # DE - end display |
| .de DE |
| .fi |
| .RE |
| .sp |
| .. |
| '\" # SO - start of list of standard options |
| .de SO |
| .SH "STANDARD OPTIONS" |
| .LP |
| .nf |
| .ta 5.5c 11c |
| .ft B |
| .. |
| '\" # SE - end of list of standard options |
| .de SE |
| .fi |
| .ft R |
| .LP |
| See the \\fBoptions\\fR manual entry for details on the standard options. |
| .. |
| '\" # OP - start of full description for a single option |
| .de OP |
| .LP |
| .nf |
| .ta 4c |
| Command-Line Name: \\fB\\$1\\fR |
| Database Name: \\fB\\$2\\fR |
| Database Class: \\fB\\$3\\fR |
| .fi |
| .IP |
| .. |
| '\" # CS - begin code excerpt |
| .de CS |
| .RS |
| .nf |
| .ta .25i .5i .75i 1i |
| .. |
| '\" # CE - end code excerpt |
| .de CE |
| .fi |
| .RE |
| .. |
| .de UL |
| \\$1\l'|0\(ul'\\$2 |
| .. |
| .TH dde n 1.2 dde "Tcl Bundled Packages" |
| .BS |
| '\" Note: do not modify the .SH NAME line immediately below! |
| .SH NAME |
| dde \- Execute a Dynamic Data Exchange command |
| .SH SYNOPSIS |
| .sp |
| \fBpackage require dde 1.2\fR |
| .sp |
| \fBdde \fIservername\fR ?\fItopic\fR? |
| .sp |
| \fBdde \fIexecute\fR ?\fI\-async\fR? \fIservice topic \fR?\fIdata\fR? |
| .sp |
| \fBdde \fIpoke\fR \fIservice topic item data\fR |
| .sp |
| \fBdde \fIrequest\fR ?\fI\-binary\fR? \fIservice topic \fR?\fIdata\fR? |
| .sp |
| \fBdde \fIservices\fR \fIservice topic \fR?\fIdata\fR? |
| .sp |
| \fBdde \fIeval\fR ?\fI\-async\fR? \fIservice topic \fR?\fIdata\fR? |
| .BE |
| |
| .SH DESCRIPTION |
| .PP |
| 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 \fIservice name\fR and a \fItopic\fR. Both the |
| \fIservice name\fR and \fItopic\fR are application defined; Tcl uses |
| the service name \fBTclEval\fR, while the topic name is the name of the |
| interpreter given by \fBdde servername\fR. Other applications have their |
| own \fIservice names\fR and \fItopics\fR. For instance, Microsoft Excel |
| has the service name \fBExcel\fR. |
| .PP |
| The \fBeval\fR and \fBexecute\fR commands accept the option \fB\-async\fR: |
| .TP |
| |
| .SH "DDE COMMANDS" |
| .PP |
| The following commands are a subset of the full Dynamic Data Exchange |
| set of commands. |
| .TP |
| \fBdde servername \fR?\fItopic\fR? |
| \fBdde servername\fR registers the interpreter as a DDE server with |
| the service name \fBTclEval\fR and the topic name specified by \fItopic\fR. |
| If no \fItopic\fR is given, \fBdde servername\fR returns the name |
| of the current topic or the empty string if it is not registered as a service. |
| .TP |
| \fBdde execute\fR ?\fI\-async\fR? \fIservice topic data\fR |
| \fBdde execute\fR takes the \fIdata\fR and sends it to the server indicated |
| by \fIservice\fR with the topic indicated by \fItopic\fR. Typically, |
| \fIservice\fR is the name of an application, and \fItopic\fR is a file to |
| work on. The \fIdata\fR field is given to the remote application. |
| Typically, the application treats the \fIdata\fR field as a script, and the |
| script is run in the application. The \fI\-async\fR option requests |
| asynchronous invocation. The command returns an error message if the |
| script did not run, unless the \fB\-async\fR flag was used, in which case |
| the command returns immediately with no error. |
| .TP |
| \fBdde poke \fIservice topic item data\fR |
| \fBdde poke\fR passes the \fIdata\fR to the server indicated by |
| \fIservice\fR using the \fItopic\fR and \fIitem\fR specified. Typically, |
| \fIservice\fR is the name of an application. \fItopic\fR is application |
| specific but can be a command to the server or the name of a file to work |
| on. The \fIitem\fR is also application specific and is often not used, but |
| it must always be non-null. The \fIdata\fR field is given to the remote |
| application. |
| .TP |
| \fBdde request\fR ?\fI\-binary\fR? \fIservice topic item\fR |
| \fBdde request\fR 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. \fIservice\fR is typically the name of an application, |
| \fItopic\fR is typically the name of the file, and \fIitem\fR is |
| application-specific. The command returns the value of \fIitem\fR as |
| defined in the application. Normally this is interpreted to be a |
| string with terminating null. If \fI\-binary\fR is specified, the |
| result is returned as a byte array. |
| .TP |
| \fBdde services \fIservice topic\fR |
| \fBdde services\fR returns a list of service-topic pairs that |
| currently exist on the machine. If \fIservice\fR and \fItopic\fR are |
| both null strings ({}), then all service-topic pairs currently |
| available on the system are returned. If \fIservice\fR is null and |
| \fItopic\fR is not, then all services with the specified topic are |
| returned. If \fIservice\fR is not null and \fItopic\fR 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. |
| .TP |
| \fBdde eval\fR ?\fI\-async\fR? \fItopic cmd \fR?\fIarg arg ...\fR? |
| \fBdde eval\fR evaluates a command and its arguments using the interpreter |
| specified by \fItopic\fR. The DDE service must be the \fBTclEval\fR |
| service. The \fI\-async\fR option requests asynchronous invocation. The |
| command returns an error message if the script did not run, unless the |
| \fB\-async\fR flag was used, in which case the command returns immediately |
| with no error. This command can be used to replace send on Windows. |
| |
| .SH "DDE AND TCL" |
| A Tcl interpreter always has a service name of \fBTclEval\fR. Each |
| different interpreter of all running Tcl applications must be |
| given a unique |
| name specified by \fBdde servername\fR. Each interp is available as a |
| DDE topic only if the \fBdde servername\fR command was used to set the |
| name of the topic for each interp. So a \fBdde services TclEval {}\fR |
| command will return a list of service-topic pairs, where each of the |
| currently running interps will be a topic. |
| .PP |
| When Tcl processes a \fBdde execute\fR command, the data for the |
| execute is run as a script in the interp named by the topic of the |
| \fBdde execute\fR command. |
| .PP |
| When Tcl processes a \fBdde request\fR 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 \fB$TCLEVAL$EXECUTE$RESULT\fR for |
| internal use, and \fBdde request\fR commands for that variable will give |
| unpredictable results. |
| .PP |
| An external application which wishes to run a script in Tcl should have |
| that script store its result in a variable, run the \fBdde execute\fR |
| command, and the run \fBdde request\fR to get the value of the |
| variable. |
| .PP |
| When using DDE, be careful to ensure that the event queue is flushed |
| using either \fBupdate\fR or \fBvwait\fR. This happens by default |
| when using \fBwish\fR unless a blocking command is called (such as \fBexec\fR |
| without adding the \fB&\fR 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. |
| |
| .SH "SEE ALSO" |
| tk(n), winfo(n), send(n) |
| |
| .SH KEYWORDS |
| application, dde, name, remote execution |