2. Agenda
• What Is DDE ?
• BIS Support for DDE
• Using DDE with:
- Excel
- Word
- Visual Basic
• DDE at Expanets
• Questions and Answers
3. What is DDE?
Definition
• Dynamic Data Exchange
• An early Windows™ API that allows
one DDE enhanced application to
share data with or drive another DDE
enhanced application
• Still supported but not being enhanced
• Replaced by OLE and other API’s
4. What is DDE?
Elements
• Conversation
- Windows assigns a handle
- Can have more than one open
• Application
- Name of main form (see manual)
• Topic
- Document, worksheet or form
• Item
- Bookmark, cell or field
5. What is DDE?
What can DDE do?
• Read data
• Write data
• Link data items between
applications
• Execute commands
or macros
6. BIS Support for DDE
Support
• Outbound DDE only
Requirements
• BIS Hosts:
- 2200, UNIX, NT, PC
• Workstations:
- DW, PCE, MPC, GI
• Session:
- foreground
7. BIS Support for DDE
@DDE: a function with
many command options
• (i) initiate a conversation
• (r) read data
• (p) poke data
• (e) execute command(s)
• (a) set an advise
• (u) clear an advise
@CLS close a conversation
8. BIS Support for DDE
Initiate:
@DDE,”applctn”,,I,[topic],TEXT,,lbl <HDL>I6 .
Read, Poke, Advise, Unadvise:
@DDE,””,<HDL>,R,item,TEXT .
@DDE,”value(s)”,<HDL>,P,item,TEXT .
@DDE,c,d,r,l,file,<HDL>,P,item,TEXT[,T] .
@DDE,””,<HDL>,A,item,TEXT .
@DDE,””,<HDL>,U,item,TEXT .
Execute:
@DDE,”command_string”,<HDL>,E,,TEXT .
10. Using DDE with Excel
Execute:
• Command set in Excel 4.0 Function
Reference and/or XLMACR8.HLP file
• Open/save/close
• Calculation on/off
@DDE,"[OPEN('"’STDWBS.XLS'"')]",<XL>,E,,TEXT . Excel
@DDE,"[CALCULATION(3)]",<XL>,E,,TEXT,,LIN1 . off
@CLS,<XL> DDE,"EXCEL",,I,SHEET1,TEXT <WS>I6 . sheet
...
@DDE,"[CALCULATE.NOW]",<WS>,E,,TEXT . do now
@DDE,"[CALCULATION(1)]",<WS>,E,,TEXT . on
@DDE,"[SAVE.AS('"’NEWWBS.XLS'"')]",<WS>,E,,TEXT .
@CLS,<WS> . sheet
11. Using DDE with Excel
Poke:
• Single cell
• Range of cells
• Large amounts of data
@DDE,”3.14159",<WS>,P,R4C6,TEXT . single cell
@DDE,”Able|Baker|Charlie",<WS>,P,R3C1:R3C3,TEXT .
1,280 character limit range of cells
@DDE,-0,2,DDETEMP,<WS>,P,R1C1:R3C3,TEXT,T .
64,000 character limit range of cells
@PCW,-2,2,0199 <PTH><FIL>'.txt' . large data
@PC,B <XDIR>'EXCEL.EXE '<PTH><FIL>'.txt' .
12. Using DDE with Excel
Format:
• Column width
• Font and alignment
• Number format
@DDE,"[Select('"'R3C1:R3C2'"')]",<XL>,e,,TEXT . the *=== row
@DDE,"[Column.Width(,,,3)]",<XL>,e,,TEXT . set column width
@.
@DDE,"[Select('"'R1C1:R2C2'"')]",<XL>,e,,TEXT . the headers
@DDE,"[Format.Font('"'Arial'"',10,True)]",<XL>,e,,TEXT . Bold
@DDE,"[Alignment(3)]",<XL>,e,,TEXT . center
@.
@DDE,"[Select('"'R3C2:R14C2'"')]",<XL>,e,,TEXT . the numbers
@DDE,"[Format.Number('"'$#,##0.00'"')]",<XL>,e,,TEXT . dollar
13. Using DDE with Excel
Read:
• Single cell
• Range of cells
• Medium amounts of data
@DDE,”",<WS>,R,R4C6,TEXT . single cell
@CHG INPUT$ <CELLVALUE>H12 .
@DDE,”",<WS>,P,R3C1:R3C3,TEXT . range of cells
@CHG INPUT$ <CELL1>H10,<CELL2>I6,<CELL3>F8.2 .
6,000 character limit
@DDE,””,<WS>,R,R1C1:R2C3,TEXT .
@RDL,-0,2 1-80 <TABBED_DATA1>S . medium data
@RDL,-0,3 1-80 <TABBED_DATA2>S .
6,000 character limit
14. Using DDE with Excel
Execute a Macro:
• Build with “Record a Macro” or
Visual Basic for Applications
• Store in current or external worksheet
• Execute from BIS
@DDE,"[RUN('"’MACRO1'"')]",<XL>,E,,TEXT .
@DDE,"[RUN('"’OTHER.XLS!MACRO2'"')]",<XL>,E,,TEXT .
17. Using DDE with Word
Getting a Clean Start:
• Find out if any documents are open
• Close previously opened documents
• Open your own document
@DDE,"",<WD>,R,Topics,TEXT . what files are open?
@CHG INPUT$ <SYS>H6,<OPEN1>H18,<OPEN2>H18 .
@IF <OPEN2> NE '’ .
DDE,"[FileCloseAll]",<WD>,E,,TEXT . close them
@DDE,"[FileOpen .NAME='"'<INPDOC>'"']",<WD>,E,,TEXT .
18. Using DDE with Word
Execute:
• Edit using the document’s conversation
• Command set in the WordBasic manual
and/or WRDBASIC.HLP file
@DDE,"[StartOfDocument]",<DOC>,e,,text .
@DDE,"[EditFind .Find='"'!target!'"']",<DOC>,e,,text
@DDE,”[Font ‘”’Courier New’”’],<DOC>,e,,text .
@DDE,”[FontSize 10],<DOC>,e,,text .
@DDE,”[LineDown 3],<DOC>,e,,text .
@DDE,”[SelectCurSentence],<DOC>,e,,text .
@DDE,”[EditCut],<DOC>,e,,text .
@DDE,"[EndOfDocument]",<DOC>,e,,text .
@DDE,”[EditPaste],<DOC>,e,,text .
20. Using DDE with Word
Headers and Footers:
• Separate from body of text
• Enter, edit and exit
@DDE,"[ViewHeader]",<DOC>,e,,text .
@DDE,”[ShowNextHeaderFooter]",<DOC>,e,,text .
@DDE,”[EditFind .Find = ‘”’!cust!’”’]", <DOC>,e,,text
@DDE,”[Insert ‘”’<cust>’”’]",<DOC>,e,,text .
@DDE,"[ViewHeader]",<DOC>,e,,text .
21. Using DDE with Word
Poke and Format Tables:
• Create a bookmark
• Poke in table data
• Reformat table
@DDE,"[EditFind .Find='"'!freq!'"']",<DOC>,e,,text .
@DDE,"[EditBookMark .Name = '"'CmdFreq'"', .
.Add]",<DC>,e,,text .
@DDE,-3,6,ddetemp,<DOC>,p,CmdFreq,text,t .
@.
@RSR,ECAB$,H,26 0010 . formatting commands
@LDV <LN8>I2=2 . get command
@RDL,-8,<LN8>,LIN3 1-132 <MAC>S LDV,P <MAC> .
@DDE,"[<MAC>]",<DOC>,e,,TEXT . execute command
27. Using DDE with Visual Basic
BIS Side:
@DDE,"<ARCHIVE>",<MZ>,p,txtArchive,text . SET ARCHIVE
@DDE,"<PCME>",<MZ>,p,txtDirectory,text . SET DIRECTORY
@DDE,"Y",<MZ>,p,txtDeleteAfter,text . SET DELETE AFTER
@.
@PCW,<c>,<d>,<r>,2 <PCME><FILE> . EXPORT RID
@DDE,"<FILE>",<MZ>,p,txtFileMask,text . SET FILE NAME
@DDE,"A",<MZ>,p,txtStatus,text . FORCE THE ADD
@.
@DDE,"",<MZ>,r,txtStatus,text . CHECK STATUS
@CHG INPUT$ <STAT>H1 IF <STAT> NE C,(LIN-1) ; .
@.
@DDE,"E",<MZ>,p,txtStatus,text . END MAPZIP.EXE
@CLS,<MZ> .
29. DDE at Expanets
BITS (Business Info Tracking Sys)
• VSS-RADS shell for managing ESS
• Uses DDE for proposals, contracts, memos
VSS-MAPPORT
• VSS-RADS shell for portation proposals
• Highly automated
“Inventory Report and Portation Proposal”
30. DDE at Expanets
Inventory
Rids
VSS-MAPPORT Process
Load & Size Gen
Analyze Project Report
portation rid wbs.xls invtrpt.doc
31. Questions and Answers
?
• What is DDE?
• BIS support for DDE
• Using DDE with:
- Excel
- Word
- Visual Basic
• DDE at Expanets
32. For more information contact:
Jerry Merrill
Director of Migration Services
Expanets
15941 No 77th Street
Scottsdale, AZ 85260
e-mail: jerry.merrill@expanets.com
web: www.expanets-az.com
Editor's Notes
Jerry Merrill is the Director of Migration Services and a senior systems integrator at Expanets (formerly Vector Technologies). He has been working with Unisys e-@ction Business Information Server (formerly called MAPPER) since it was first marketed on 1100’s in 1980. Since then he has worked with Business Information Server on 2200’s, MAPPER-5’s, PC’s, OS/2, NT’s, UNIX, Sun Solaris, IBM RS/6000, CTOS, A-Series, and OPUS. Mr. Merrill joined Expanets in 1996 after spending 18 years with Unisys, where he rose to the level of the Western Region 4GL Marketing Manager. He is the designer and developer of the methodology, tools and services used in VSS-MAP2000 and VSS-MAPPORT. He has written a dozen articles for Unisphere Magazine and is a frequent presenter at Unite conferences. Today he will present and demonstrate some real world uses of DDE between BIS and Excel, Word and Visual Basic applications. After this presentation, you should have all the information you need to begin building DDE interfaces of your own.
First we need to look at exactly what DDE is and what it can do. Then we can review the DDE interface capabilities provided by BIS. We will then examine the most common uses of DDE when interfacing with Excel, Word and Visual Basic applications. For each of these applications, sample code will be presented and a demo in run debug mode will be provided. Before we close we’ll overview some DDE enhanced applications that are used at Expanets on a regular basis. And finally we will give you a chance to ask questions.
DDE (Dynamic Data Exchange) is a Microsoft Windows API (application programming interface) that was first used by Word and Excel. It was developed so that charts inside Word documents could be linked to Excel spreadsheets, and whenever the values in Excel changed, the chart inside Word would change. Microsoft also documented DDE so that third parties could develop interfaces to Microsoft products. DDE sits at the operating system level and is available to any program or application that wants to use it. In the mid-1990’s “newer”/”better” interfaces such as OLE (object linking and embedding) came to the forefront. To my knowledge, DDE has received no enhancements since then.
DDE interfaces employ the following elements: Conversation The active DDE connection between two applications is called a conversation . A destination (client) application will initiate a conversation with a source (server) application and if successful, DDE will return a Windows handle (i6) to the destination (client) application to be used in all further interchange between the two applications. Application When you initiate a DDE conversation you must specify a DDE application name . Applications have such names as Excel (for Excel), Winword (for Word), WPwin9_Macros (for WordPerfect) and Faxmng32 (for WinFax Pro). You can only find these DDE application names by searching through the application’s manuals and/or help files. Topic When you initiate a DDE conversation you usually have to specify a topic . The default topic for most applications is “System”. For Excel, topics would be the names of spreadsheets, for Word and WordPerfect, the names of documents, for VB, the names of forms. These are all objects that you can edit or manage with DDE Execute commands. Item When you read data from or poke data into a document or form, you have to specify the name of a target item . For a spreadsheet the item would be a cell, or range for cells, for a word processor it would be a bookmark or a field, for a VB application it would be a “control”.
With DDE you can read from and write data to the source (server) application. You can establish a link between applications so that when data is changed on the source (server) the destination (client) will be notified. Of course you also need the capability to sever links when they are no longer needed. You can execute any command and/or macro on the source (server) application that it chooses to expose and document. The source (server) application dictates the format of these commands. While you may be able to find Excel and Word documentation on outbound DDE commands, their inbound DDE commands are difficult find. And the inbound commands are the ones that BIS developers need to know.
BIS only supports outbound DDE. That is, it can initiate conversations but it cannot receive them. DW (Designer Workbench) 3R1 and BIS for UNIX, NT and PC release 5R1 were the first releases to support outbound DDE. It was not till BIS for 2200 release 39R1 that it became available on the mainframe. Since then DW has been replaced by PCE (PowerClient Edition), and then MPC (MAPPER Presentation Client) and now Graphical Interface for BIS . BIS has to talk to a program on the workstation (mpcapi32.exe) to pass the DDE commands to the DDE interface. Because of this, DDE conversations can only take place as foreground sessions on workstations (or NT consoles).
Rather than creating an individual function for each DDE operation, Unisys chose to create one function with a flexible syntax and six command options. The one letter command option for each DDE function is shown above. Instead of a DDEterminate function, which is usually found in other applications, Unisys chose to reuse the @CLS command (followed by the handle of the conversation) to close a DDE conversation.
Here is how the syntax for @DDE shakes out: On the Initiate, if the topic is left blank, “System” is assumed. The Initiate usually includes a label to go to if the connection fails. The most common reason for failure to connect is that the source (server) application is not running. That can be remedied by executing an @PC command and retrying the Initiate. Note that the handle loaded on the Initiate is used in all subsequent DDE statements. The Read, Poke, Advise, and Unadvise command options must all include an item . If you are Poking a rid or result, you must include the name of a temporary DDE transfer file to hold the data during the transfer. You can also include a “T” option to remove the first tab character on each data line being transferred. If you specify the “T” option but there is no tab character or if there are no lines to transfer, the statement will error. The command_string submitted with the Execute command option must follow the format required by the source (server) application. Excel and Word require that the commands be enclosed between “[“ and “]”. Other applications do not. When double quotes (“) are required by the command_string, they must be enclosed in single quotes, e.g. FileOpen .Name=‘”’c:\\myfile.txt’”’ Note: under @DDE in the BIS help file is a list of error codes that will be returned in STAT1$ when there is a problem executing a DDE statement. Now let’s take a look at how we can use BIS to drive Excel, Word and VB applications using the DDE function.
The DDE application name for Excel is “excel”. The default topic is “system”. We can use our conversation with “system” to open, save and close workbooks. To edit/process a sheet we would start a conversation with that sheet. Note: several conversations can be open at the same time. Each connected to a different object and each with its own unique Windows handle. If our connection is with “system” then we have two items available: “sysitems” and “topics”. They will both return “EXCEL” and a list of open books and sheets. If we opened a conversation with a worksheet, the items would be cells, ranges of cells or named cells. Note that the rows and columns used to specify the cell(s) are in what Microsoft calls R1C1 style. You can change Excel to display R1C1 values by selecting Tools > Options… > General > R1C1 Reference Style. Our sample code shows how we would initiate a conversation with Excel. If is not running we would start it. We would then open a workbook, close the conversation to Excel and open a conversation to a sheet.
The commands that you need to use inbound DDE with Excel are documented in the Excel Function Reference for Excel 4.0 and/or the XLMACR8.HLP help file. Note: the current version of the XLMACR8.HLP file that you will probably find with your Excel is only a shell of about 20 KB. The full XLMACR8.HLP file is about 719 KB. Expanets will provide you with a copy of the full XLMACR8.HLP file on a Supplemental CD that we will distribute at the end of this presentation. The sample code included here demonstrates how to open and close workbooks, how to turn calculation off and on, and how to close conversations with “system” or a sheet. Note: that all command_strings are delimited with “[“ and “]”. This is a Microsoft convention.
The most common operation that people want to do with Excel is to poke BIS data into worksheet cells. To do that we use the “P” command option and specify a cell or range of cells in the item field. If we want to poke data into a single cell we can place one value in the value field and a cell reference in the item field. If we want to poke several values in cells that adjacent horizontally, we can place the values, separated by tab characters, in the value field and specify a cell range in the item field. If we want to poke several rows of data (or several rows and several columns) we have to use the “c,d,r,file” format for the value field and a cell range in the item field. The “T” option, that removes the first tab character on the line, is usually used. This method is limited to 64,000 characters, which is usually enough. For larger data transfers you would have to write the rid or result out as a flat file and import it into Excel.
Once you have poked some BIS data into your Excel worksheet, you will probably want to do some formatting. Here we show you how to set column width, how to change the font, and how to format some numbers. You can use other commands from the XLMACR8.HLP file to further manipulate the data.
A less frequently used operation is to read Excel cell(s) into BIS variables or results. For this we would use the “R” command option and specify a cell or range of cells in the item field. If we want to read a single cell, we execute a read with a single cell reference in the item field and pickup the value with a CHG INPUT$ statement and one variable. If we want to read a horizontal range of cells, we can execute a read with a cell range in the item field and pickup the value with a CHG INPUT$ statement and one variable for each cell. If we want to read a two dimensional range of cells, we have to execute a read with a two dimensional cell range in the item field to create a result. We can then read through the result one line at a time and parse the input. Note: Excel will return the data in tab separated, variable length (packed) strings. If you need to read more that 6,000 characters, then you will have to either execute multiple reads or export the sheet from Excel and use @PCR to load it into BIS.
If you need to do a lot of formatting and/or some graphing after you load the BIS data, instead of issuing dozens of Excel commands, you may want to execute a pre-recorded Excel macro and have it do all the work. Again, you would use the “E” command option. The command_string to execute the macro is shown here.
The Excel worksheet(s), Excel macro(s) BIS data and BIS code presented in this demo are included on our Supplemental CD.
The application name for Word is “winword”. The default topic is “system”. We can use our conversation with “system” to open, save and close documents. To edit/process a document we would start a conversation with that document. If our connection is with “system” then we have three items available: “sysitems”, “topics”, and “formats”. A read of: sysitems returns: SYSITEMS TOPICS FORMATS topics returns: System Document1 E:\\msoffice\\Templates\\Normal.dot Note: the template will always be the last entry on the “topics” list. It there are no documents open the first entry will be “System” and the second entry will be the template. If we have opened a conversation with a document, the items would be bookmarks. Our sample code initiates a conversation with Word. If Word is not running, we start it. We open a skeleton file (<SKEL>) and save it under a <NEW> name and request it be put on the Most Recently Used (MRU) list. Then we open a conversation with the <NEW> document.
Here is where we can take advantage of the “topics” item : Before we open a new document we want to be sure that all other documents are closed. However, if we issue a “FileCloseAll” and there are no documents open, a VBA error window will appear. So what we do is look at the first three entries returned from a (R)ead of “topics” and if the third entry is non-blank then we do a “FileCloseAll”.
Here are examples of some of the command_strings that you could use with Word. Full documentation is available in the WRDBASIC.HLP file which we have included on the Supplemental CD.
If you wanted to use BIS data to generate a lot of form letters you could use Word’s MailMerge capabilities. But if you only need to generate a few documents per day, poking individual data items uses a lot less overhead. If you have a pre-existing bookmark in a document you can poke to it directly. But what we have found is that it is very easy to loose the bookmarks. This is because they are not stored in the document itself, but separately, much like a template is. So what we prefer to do at Expanets is to use “EditReplace” for single fields. For tables we like to create a bookmark: [ EditBookMark .Name='&quot;'Terms'&quot;', .Add] and poke a result into it. If we have a lot of fields to “EditReplace”, then instead of hard-coding them, we will read them out of a table. The table also lets us include and loop on the number of occurrences (OC) for each replacement.
To customize a document you will often want to put the client and/or project name in the headers. To toggle in and out of Word headers use [ViewHeader]. To move from one section of headers to the next use [ShowNextHeaderFooter].
Poking and formatting tables is the most challenging task of all. Here we create a bookmark named “CmdFreq” then poke the contents of result -3 into it, beginning with line 6 and dropping the first tab character. After the poke, all the data will be left justified with extra positioning for each tab character. What we need to do next is format the poked data to match the document’s headers. Because some of the reformatting commands are up to 132 characters wide, we usually store the reformatting commands in a separate drawer and use a subroutine to access them. Here we load them into result -8 and process them one at a time. What do the reformatting commands look like?
Here is our subroutine. Pretend that the “ ¬” just continues the line off the right side of the slide. First we “GoTo” the bookmark to make sure it is selected. They we do a convert text to table and specify the number of columns among other things. Then we put a single line border around it, set the indent, and begin setting the column width for each of the columns. When the columns are set, we move to the table headers (StartOfColumn, StartOfRow) and make sure that it has a single line border. How do we get the values to use for the indent and each of the columns?
We manually go into Word, select the first cell in the table headers, and select “Table > Cell Height and Width…”. From the Row tab we can read the “Indent from left”. From the Column tab we can read the first “Width of column1” then press “Next Column” to read off the others. In this example, the target string is “!impact!”, the indent is “0.83”, and the first column is “0.75” wide. When we finish formatting, the columns will line up perfectly with the table headers in the document.
The Word document(s), BIS data and BIS code presented in this demo are included on our Supplemental CD.
When you develop your own VB applications you get to choose the DDE application name and the names of the topics . The DDE application name will be the name of the executable (.EXE). For inbound DDE, the forms we want to access must be compiled with a LinkMode of 1 (source (or server)) and assigned a LinkTopic (which is usually the form name). Although VB supports other DDE properties and methods, these are the only two that we need to work with BIS. The only type of control that BIS can access is the “Text” property of a TextBox control. So the item will be the name of the TextBox. In our example code we open up a connection to a little MAPZIP utility.
Here is a snapshot of the VB form with the “txtStatus” textbox highlighted. Also shown is a third party component that allows us to ZIP and UNZIP files that we transfer to and from BIS. The code that we are looking at is section of the “txtStatus_Change” subroutine. When BIS pokes a directive to this TextBox, the VB application responds. When the VB application completes a task, it will set the status to (C)omplete, BIS will read it and continue. Note: we don’t do anything when BIS pokes values into the Archive File Name, the Input File Directory, the Input File Mask or the Delete After fields. We have only one field that we use to control/drive the processing and to record the processing status. In other projects we have used two fields: one for BIS to poke into and VB to examine and a second for VB to poke into and BIS to examine.
Here is the BIS code. First we set the name of the archive file, the temporary directory we use during the data transfer, and whether we want to delete the downloaded file after it has been added to the archive. We then download a rid, pass the file name to the ZIP control, and force the adding of the file to the archive by poking an “A” into the “txtStatus” TextBox. Then we loop on a read and check the value of the “txtStatus” TextBox until the zipping task is complete. Finally we tell the VB program to end and we close our conversation with it.
Sorry, this utility will not be provided on our Supplemental CD.
Expanets has developed DDE interfaces for several clients and uses it even more extensively internally. My boss uses a Business Information Tracking System we named BITS. It was developed using VSS-RADS technology and includes DDE interfaces for generating proposals, contracts, schedule-A’s, reporting info memos to associates, etc. As the Director of Migration Services I use another VSS-RADS application for analyzing portation inventories and generating portation proposals. It uses all of the techniques that we have presented today.
Here is how it works. We send out a diskette with the inventory routines, written in BIS code, on it. The client runs the inventory, downloads the results and returns the diskette to Expanets. I have a routine that loads the results into BIS, lets me review and clean up the data, and then stores a number of calculations and subtotals. The next routine pokes selected items into a Work Breakdown Structure in an Excel spreadsheet. The spreadsheet calculates the project length, estimated Expanets hours and expected client hours. I then plug in how many people to assign to the project, and the spreadsheet recalculates the project length, labor cost and an estimate of the expenses. The next routine reads the project length, labor cost and estimate of expenses, etc. from the spreadsheet and pokes them into a skeleton proposal in a Word document. It also takes the summaries and totals that were stored in BIS and pokes them into the proposal. It pokes and reformats two tables in the Run Modifications section. And finally it saves the document under a new directory created for the client. I am then free to review and touch up the final document.
We have presented the specifications necessary to build DDE interfaces between BIS and Excel, Word or Visual Basic. We have presented sample code that covers the most common operations for each of these applications. We have demonstrated the DDE code for interfaces to each of these applications. The demo documents, data and runs will be included on a Supplemental CD that you can pick up in the back. The CD also includes the Excel and Word help files that you will need for developing your own DDE interfaces. Now it is your chance to ask those all-important, host stumping, questions…