in PowerBuilder - sys-con.com's archive of magazines - SYS-CON ...

Word Excel OutlookOffice 97 VBAWRD8.HLP VBAXL8.HLP VBAOUTL.HLPOffice 2000 VBAWRD9.CHM VBAXL9.CHM VBAOUTL9.CHMOffice XP VBAWD10.CHM VBAXL10.CHM VBAOL10.CHMTABLE 1 | VBA Help Files for Microsoft Office ApplicationsFIGURE 1 | The VBA scripting utility available within Microsoft Officeproducts+++...n_cst_ole_word_97of_connect ()of_visible (boolean ab_status)of_open (string as_filename)...: integer: integer: integer...n_cst_word+ inv_word : n_cst_ole_word+ of_connect (): integer+ of_disconnect () : integer+ of_visible: integer(boolean ab_status)... ......inv_wordn_cst_ole_word# inv_word : oleobject# inv_const : n_cst_constants_word_ole+ of_connect (): integer+ of_disconnect (): integer+ of_visible (boolean ab_status) : integer... ......+++...n_cst_ole_word_2000of_connect (): integerof_visible (boolean ab_status) : integerof_open (string as_filename) : integer......n_cst_constants_word_oleis because it’s not installed by default but instead requires a custominstallation of Microsoft Office. The documentation is provided as a setof help files as indicated in Table 1.The VBA scripting utility that comes with those products also containsan object browser that can be used to determine which functionsare accessible on different objects and the syntax for using them (seeFigure 1). You access the VBA scripting utility from Tools->Macro->Visual Basic Editor within the application, and then the object browseris available from the toolbar, from the View menu item, or by hittingF2. From within the VBA Scripting utility you can bring up the documentationfor a particular method, property, or event by hitting F1after selecting it (assuming that the help files have been installed).The second issue raised above is the compatibility between versionsof the same target application. Fortunately, at least with theMicrosoft products, there is a fairly easy way to determine which versionof the target application is installed. (This will be demonstratedonce we get into the source code.) In addition, the OLE Automation+++...+++...wd100Wordswd10Percentwd10Sentences...: long: long: long...inv_constn_cst_ole_word_XPof_connect ()of_visible (boolean ab_status)of_open (string as_filename))...FIGURE 2 | Class diagram for OLE automation implementation objects= -4= -6= -2...: integer: integer: integer...syntax for these applications is highly backward-compatible. Whenobjects (or methods, properties, or events of an object) are depreciatedby Microsoft in a new version of the application, they usually markthose as “hidden.” Hidden objects (or methods, properties, or events)still work with the newer version, but they don’t appear in the objectmodel for that new version. Obviously, because each new version ofthe application adds additional features that were not present in earlierversions, the syntax developed using a newer version of the objectmodel will not always work for an older version.As mentioned previously, PowerBuilder uses late binding to interfacewith OLE Automation objects, so we are unable to use the constantsprovided in the Word type library. However, Microsoft does providean Excel spreadsheet on their MSDN site that contains all of theconstants and their values used within Office. (Those constants arealso defined in the Microsoft supplied help files and can be browsedusing the VBA scripting utility.) I downloaded that file and used thatinformation to create an autoinstantiating nonvisual user object thatcould be used for a similar purpose as the type library, at least withrespect to the constants (see Figure 2).The n_cst_constants_word_ole class contains the constants and isdefined as an instance variable on another class, n_cst_ole_word. Thatclass is basically a “virtual” class; it’s never actually called directly.Instead, descendants of it are created to handle each of the differentversions of Word we might actually interact with. The virtual classdetermines which methods we are going to make available, and thedescendants actually implement those methods as appropriate. Thevirtual class returns an error message if the method is called, so if themethod is not implemented on a descendant, it implies that particularversion of Word does not support the method. This allows us to addadditional methods to the virtual class as new versions of Word, andadd new functions and implement them in whichever descendantsactually support them without having to modify the classes representingearlier versions of Word. n_cst_word acts as a wrapper class so thatthe instantiation of the appropriate descendant of n_cst_ole_word andcalls to its methods are handled automatically.In the of_connect method of n_cst_word, the object determineswhich version of Word the user has installed and creates the appropriatedescendant of n_cst_ole_word (see Listing 1).Prior to version 8 of PowerBuilder, the standard method for handlingerrors in OLE Automation was to create a user object that inheritedfrom the OLEObject class and then code its Error and ExternalExceptionevents. Then that class, rather than the OLEObject class, wouldbe used for the ConnectToObject or ConnectToNewObject call. Oneproblem with that approach is that some OLE Automation propertiesand method returns are themselves OLEObjects, and would not allowthemselves to be cast into the descendant user object. Instead, a userobject based on OLEObject would have to be used, and then theSetAutomationPointer function of that object would be used to redirectprocessing to an instance of the custom class.That was all very complicated. It also tended to disassociate theerror-handling logic from the code that was making the call to theobject that caused the error, which made recovery from the errorsomewhat problematic.Fortunately version 8 of PowerBuilder introduced structured exceptionhandling, which greatly simplifies this for us. The object that weare using in this sample to interact with Word is the inv_word instancevariable in the n_cst_word class, and you can see from Figure 3 thatthe class we are using for it is OLEObject. We simply wrap our OLEAutomation calls in a try...catch...end try block and can deal with anyerrors that occur within that block.We’re going to review some of the code from the sample application(which can be downloaded from www.pbdj.sys-con.com), certainly notall of it, just certain code that illustrates some important concepts.The of_visible function determines whether or not Word will actuallybe visible to the end user. It’s fairly straightforward, simply settingthe visible property of the Word application (not a PowerBuilder objectvisible property).10 PBDJ volume12 issue11pbdj.sys-con.com