TECHNICAL BULLETIN #175 - Rev 1.00 (9/05/96) ============================================================================== TITLE : Using DDE with Procomm Plus PRODUCT : Procomm Plus 4.x, 3.x ============================================================================== DDE BASICS DDE is a means by which two Windows programs can communicate with each other. Procomm Plus' ability to use DDE to communicate with other applications increases its power and versatility. For example, a Microsoft Excel macro can create a DDE link to Procomm Plus, dial a number, retrieve information, and integrate it into a spreadsheet without intervention. This allows Microsoft Excel to take advantage of Procomm Plus' features. Conversely, Procomm Plus can use DDE to control other programs via Aspect without user intervention. To make use of DDE, one program, known as the client, initiates a DDE session with another program, known as the server. This is accomplished by sending the server application a DDE initiate message. After the session is established, the client application sends DDE commands to the server application. Any of the following commands can be used after the DDE session has begun: Advise Unadvise Request Poke Execute Each of these commands will be discussed in detail later in this document. The client can send as many commands as desired to the server during a single DDE conversation. When the client is finished communicating with the server application, the client is required to close the link. This is accomplished by sending a DDE terminate message to the server application. Note that the client always sends the commands to the server, not vice versa. The server can send responses to queries by the client but it cannot tell the client to perform one of the operations listed above. If the server application wants to send commands to the client application, a separate DDE link will need to be established. For example, if Procomm Plus initiates a DDE link with Microsoft Excel, Procomm plus becomes the client while Microsoft Excel becomes the server. Procomm plus can tell Microsoft Excel to do a variety of things, from maximizing the spreadsheet to entering data in a spreadsheet's cells. However, Microsoft Excel cannot tell Procomm plus to dial a phone number. In order to do this, a second DDE link would have to be created where Microsoft Excel is the client and Procomm plus is the server. Each DDE link is given a different identification number, known as the DDE channel number, so multiple DDE links between two applications can exist simultaneously. Procomm plus can act as either a client or a server. PROCOMM PLUS ACTING AS A DDE SERVER 1. The first thing an application must do to communicate with Procomm plus is to initiate a DDE link using the DDE initiate command. DDE INITIATE This command begins a DDE conversation between two applications. The client must specify the name of the server as well the topic of the conversation. The name 'PW4' should be used when communicating with Procomm plus (PW3 should be used with version 3.0) via DDE. Optionally, "PW4xxxx" can be used for the name of the server, where "xxxx" is the handle to the instance of Procomm plus. This is useful if there are two or more versions of Procomm plus running and you want to use a specific instance as the DDE server. There are two available topics: System - Opens a standard DDE link with Procomm plus [script name] - This opens a standard DDE link with Procomm plus and executes the specified script. Aspect example: ddeinit l0 "PW4" "System" ;Create a DDE link with PW4 or ddeinit l0 "PW4" "HOST.WAX" ;Create a DDE link with PW4 and launch ;the Host script. The l0 variable is a predefined Aspect long variable that holds the DDE channel number. This variable can be changed to any user-defined long variable. 2. After a DDE link has been established with Procomm plus as the server, any of the following commands can be sent. Note that the syntax of the client application's DDE command will vary from application to application. For more information on how to program a non-Procomm plus client to perform DDE, refer to that application's user guide. DDE EXECUTE The DDE execute command tells the server to perform the specified action. When Procomm plus acts as the server, the following commands are available: * ASPECTCMD string - Executes an Aspect command. * Capture ON/OFF - Toggles data capture ON/OFF. * DIAL dialclass [GROUP] name [DIALINGBOX OFF] - Dials specified entry/entries optionally allowing the Dialing Status box to be hidden. Dialclass can be Data, Fax, Voice, Telnet, FTP, WWW, News, or Mail. * Dialload filespec - Loads the specified Connection Directory. * Execute filespec- Executes a specific script file. * Getfile string filespec [FILEXFERBOXOFF] - Begins a file transfer with the specified protocol. The filespec only needs to be included if the transfer protocol requires it. The File transfer box can optionally be hidden. * Halt - Halts the currently executing script and all parent scripts. * Hangup - Hangs up the active data line. * Pwexit - Exits PW * Sendfile string filespec [FILEXFERBOXOFF] - Begins a file upload using the specified protocol. Most protocols require the filespec. The file transfer box can be optionally hidden. * Transmit string - Sends the specified string out the port (with caret translation). Aspect examples: ddeexecute l0 "ASPECTCMD usermsg '"Hello'"" ;Note how quotes are used. ddeexecute l0 "capture ON" ddeexecute l0 "DIAL WWW QUARTERDECK" ;Dialing entry name is case ;sensitive!!! ddeexecute l0 "transmit '"ATDT 4017^M'"" ddeexecute l0 "PWEXIT" DDE ADVISE/UNADVISE When PROCOMM PLUS is the server, a DDE advise command can be used to create a 'hot link' which monitors the value of a predefined Aspect variable. These variables consist of integers (i0-i9), strings (s0-s9), floats (f0-f9), and longs (l0-l9). Aspect example: ddeadvise l0 "i0" iNewValue iAdviseId If two instances of Procomm plus are used, one acting as the server and the other acting as a client, two things occur when the value of i0 changes. First, a DDE message is sent to the client telling it that the value has changed. The new value of i0 is then copied into the integer variable iNewValue. Second, the $DDEADVISE variable is changed to the iAdviseId, which is the identification number for this ddeadvise link. For example, use a Client application to create a ddeadvise link to monitor the i0 variable in Procomm plus. Next, run the following script: proc Main for i0=1 upto 1000 endfor endproc The DDE client should see the value of i0 increment by one until it reaches 1000 as it receives DDE advise messages from Procomm plus. When the client no longer wants to monitor the value of the i0 variable, it sends a ddeunadvise message to the server. This tells the server not to send anymore DDE messages when the value of i0 changes. Aspect example: ddeunadvise l0 "i0" DDE POKE A DDE client can poke a value into a predefined Aspect variable. This allows the DDE client to send information to the server upon which it can act. Note that the client cannot poke a value into a user defined variable. Aspect example: ddepoke l0 "s0" "String to store in server's s0 variable" As an example, initiate a DDE link using Procomm plus as the server and then run the following script: proc Main i0=-1 i1=-1 while 1 if i1!=i0 usermsg "i1=%I" i1 i1=i0 endif endwhile endproc Now, use the client application to poke a value other than -1 into i1. A user message will be displayed stating that the value of i1 has changed. DDE REQUEST This command requests the value of the specified variable in the server application. When Procomm plus is the server, any of the predefined Aspect variables can be requested. In addition to these, the following topics can be requested: * Topics - Returns the two topics that are supported (System or a script filename) * SysItems - Returns the items that can be requested. * Status - Returns a block of information listing the status of certain PW operations. The information is in the following format: DIAL DIR {directory name}, {script file | NO SCRIPT}, OFFLINE | ONLINE, CAPTURE ON | OFF, PRINTER ON | PRINTER OFF, {TERMINAL | {FILE XFER} | DIALING}, FAX IDLE | FAX BUSY * Formats - Returns the DDE data formats supported by PW. PW3 only supports the 'Text' format. * Help - Returns information concerning the types of operations PW will support as a DDE server. If two instances of PW are being used as the client and the server, the string length limitation of Aspect will truncate the text at 256 characters. Aspect examples: dderequest l0 "s0" szVarValue dderequest l0 "Status" szStatus 3. When the client is finished with the DDE link, it should terminate the link with the server application. DDE TERMINATE This command terminates the DDE link. After the client issues a DDE terminate command to a Procomm plus server, the client application will no longer be able to send messages to Procomm plus until a new DDE initiate command is sent. Aspect example: ddeterminate l0 where l0 is the long variable containing the DDE channel number. PROCOMM PLUS ACTING AS A DDE CLIENT When Procomm plus is acting as a DDE client, Aspect is used to send commands to the DDE server. The following commands are available in Aspect when using Procomm plus as a DDE client: ddeadvise long string gdatavar [integer] ddeexecute long string ddeinit longvar string string [integer] ddepoke long string data dderequest long string datavar ddeterminate long ddeunadvise long string In addition, the system variable $DDEADVISE is available. The steps for creating a DDE link when Procomm plus is the client are the same as when Procomm plus is acting as the server: 1. Initiate the DDE link. 2. Send desired DDE commands. 3. Terminate the DDE link. The actual DDE commands you send to the server will, of course, depend on the syntax required by the server application. The following script is a sample included in the Aspect Help file that creates a DDE link with Microsoft Excel and uses each of the above DDE commands: string szText ; Text read from DDE link to Microsoft Excel proc main long LinkVar, SystemVar ; Variables containing DDE Id's. ; Set up DDE links to Microsoft Excel's system and a spreadsheet. Microsoft Excel ; must be running in order for this script to work properly. if ddeinit SystemVar "excel" "system" ddeexecute SystemVar "[FULL(TRUE)]" ; Maximize the spreadsheet. if ddeinit LinkVar "excel" "sheet1" ; Set up link to spreadsheet. ;Poke the string into spreadsheet cell at Row 1 Column 1 ddepoke LinkVar "R1C1" "Procomm plus DDE example!" pause 2 dderequest LinkVar "R1C1" szText ; Request value stored in R1C1. usermsg szText ; Display text in User Message. ddeadvise LinkVar "R1C1" szText ; Make hot link to row 1, ; col 1 of the spreadsheet. while 1 ; Loop forever. if $DDEADVISE ; See if row 1 and col 1 ; changed. if stricmp szText "exit'r'n" ;If R1C1 contains the value 'exit' exitwhile ; Exit the while loop. else usermsg szText ; Display cell contents. endif endif endwhile ddeunadvise LinkVar "R1C1" ; Break hot link to spreadsheet. ddeterminate LinkVar ; Break DDE link to spreadsheet. ddeterminate SystemVar ; Break DDE link to Microsoft Excel. else errormsg "Couldn't establish DDE link to spreadsheet!" endif else errormsg "Couldn't establish DDE link to Microsoft Excel!" endif endproc Note that in this example, two DDE links are established, one with the 'system' topic and the other with the topic 'sheet1.' In order to maximize the spreadsheet, the client must begin a DDE conversation with the 'system' topic. However, when the client wants to communicate with the spreadsheet itself, it uses the 'sheet1' topic. In order to differentiate between the two DDE links, the program refers to either LinkVar or SystemVar. These are two local long variables which contain the DDE channel numbers for the spreadsheet link and the system link, respectively. For information concerning available commands of DDE servers other than Procomm plus, please refer to that application's User Guide or contact that company's Technical Support department. For more information on the syntax of Aspect's DDE commands, please refer to the Procomm plus Aspect Help file. ============================================================================== To ensure that you have the latest version of this document, compare its revision number to that of the same document on any of our support sites. This technical bulletin may be copied and distributed freely as long as it is distributed in its entirety and it is not distributed for profit. Copyright (c) 1996 Quarterdeck All rights reserved. ==============================================================================