Integrating with External Systems Release 3.5 of Forte™ 4GL Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 U.S.A. 1-800-786-7638 Part No. 806-6672-01 October 2000, Revision A Copyright 2000 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, California 94303, U.S.A. All rights reserved. Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in this product. In particular, and without limitation, these intellectual property rights include U.S. Patent 5,457,797 and may include one or more additional patents or pending patent applications in the U.S. or other countries. This product is distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. Third-party software, including font technology, is copyrighted and licensed from Sun suppliers. c-tree Plus is licensed from, and is a trademark of, FairCom Corporation. Xprinter and HyperHelp Viewer are licensed from Bristol Technology, Inc. Regents of the University of California. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc. UNIX is a registered trademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd. Sun, Sun Microsystems, the Sun Logo, Forte, and Forte Fusion are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Federal Acquisitions: Commercial Software — Government Users Subject to Standard License Terms and Conditions. DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. Contents Preface Organization of This Manual . 14 Conventions. 16 Command Syntax Conventions . 16 TOOL Code Conventions . 16 The Forte Documentation Set . 17 Forte 4GL . 17 Forte Express. 17 Forte WebEnterprise and WebEnterprise Designer . 17 Forte Example Programs. 18 Viewing and Searching PDF Files . 19 I Integration with Microsoft Windows Applications 1 Overview About OLE, ActiveX, and DDE . 24 About OLE . 24 Object Linking and Embedding . 24 Using Windows Applications . 24 Defining Service Objects as OLE Servers . 24 ActiveX Controls. 25 Terminology used in this Part . 25 2 Using OLE to Access Windows Applications About Using OLE to Access Windows Applications . 28 Using Object Linking and Embedding . 29 Defining an OLE Field in the Window Workshop . 29 Creating an OLE Field. 30 OLEField Properties Dialog . 30 Linking to an OLE Object . 31 Embedding a Read-Only OLE Object. 32 Embedding an Editable OLE Object . 32 4 Defining an OLE Field in TOOL . 34 OLE Menu Groups . 35 Using OLE Automation . 36 Generating TOOL Projects That Access OLE Methods. 37 Step 1. Generate TOOL Classes for the OLE Application. 37 Running the Olegen Utility . 37 Importing the Generated Project Definition .pex File . 38 Step 2. Write the Forte Application Using OLE Methods . 39 Dealing with Variant Objects . 40 Step 3. Partition the TOOL Application and Make a Distribution . 42 Step 4. Install the Client Application . 42 Invoking Methods on OLE Interfaces Using CDispatch. 43 Step 1. Decide Which OLE Methods to Invoke. 43 Step 2. Include the OLE Library as a Supplier Plan. 44 Step 3. Instantiate an Object of the CDispatch Class. 44 Step 4. Set the ObjectReference Attribute. 44 Step 5. Set the Parameters You Need . 44 Step 6. Use InvokeMethod or InvokeMethodWithResult to Invoke the OLE Method . 45 Step 7. Check the Results of the Method . 46 Step 8. Handle Any Exceptions . 46 Step 9. Partition the Client Application . 46 Step 10. Install the Forte Application . 46 3 Making a Forte Service Object an OLE Server About Making a Forte Service Object an OLE Server . 48 Examples . 49 Step 1. Define a Service Object in a Forte Application . 50 Providing an OLE Interface for a Service Object. 50 Providing Methods to Get and Set Attributes . 50 Adding Wrapper Methods to a Service Object . 51 Defining an OLE Interface in a New Service Object . 51 Raising Exceptions in the TOOL Code . 52 Defining the ProgID for the Service Object . 53 Step 2. Partition the Application Containing the Service Objects . 54 Step 3. Mark a Service Object as an OLE Server . 55 Step 4. Make the Distribution . 56 Making the Distribution with Auto-Compile and Auto-Install . 56 Making the Distribution without Auto-Compiling . 58 Step 5. Compile and Link to Produce a Shared Library and Type Libraries. 59 fcompile command. 59 Steps for Compiling and Linking . 60 Step 6. Install the Executable . 61 Step 7. Start the Forte Partition . 61 Registering the Partition . 62 Troubleshooting the OLE Server . 62 Integrating with External Systems 5 Customizing Registry Entries for a Forte OLE Server . 63 Deleting Obsolete Entries from the Windows Registry. 63 Modifying How a Partition Is Autostarted . 65 Using DCOM with Forte OLE Servers. 66 Changing Security Settings . 67 Registering the Forte OLE Server on Client Machines . 70 Writing OLE Clients That Access a Forte Service Object. 71 Determining the ProgID for the Service Object . 71 Handling Forte Exceptions . 72 4 Using ActiveX Controls in TOOL Applications About Using ActiveX Controls in TOOL Applications. 74 Overview. 74 Support for ActiveX Controls. 74 Including ActiveX Controls in TOOL Applications . 75 Using ActiveX Controls as Widgets . 75 Using ActiveX Controls to Display Information . 75 Examples. 75 Producing TOOL Classes For an ActiveX Control . 76 Step 1. Install the ActiveX Control on Your System. 76 Step 2. Run the Olegen utility . 77 Step 3. Import the Generated Project Definition .pex File . 78 Developing a Forte Application that Uses ActiveX Controls . 79 Before You Start. 79 Restrictions . 80 Overview. 80 Step 1. Specify the Supplier Plans. 81 Step 2. Define an ActiveXField Widget . 81 In the Window Workshop—Static Definition. 81 In TOOL Code—Dynamic Definition . 83 Step 3. Invoke Methods and Access Properties of the Control. 84 Step 4. Handle Events Posted by the ActiveX Control . 85 Partitioning the TOOL Application . 87 Making the Distribution and Installing the Application . 88 Install ActiveX Controls Where Client Partitions are Installed . 88 Troubleshooting . ..