home *** CD-ROM | disk | FTP | other *** search
/ C Programming Starter Kit 2.0 / SamsPublishing-CProgrammingStarterKit-v2.0-Win31.iso / bc45 / autocalc.pak / README.TXT < prev    next >
Text File  |  1997-07-23  |  10KB  |  204 lines
  1. Overview 
  2. ======== 
  3. The AUTOCALC project is an example illustrating OLE 2 automation
  4. servers and controllers. The list below describes the targets
  5. produced by the example:
  6.  
  7.   ACALIPS.DLL  :  DLL version of OLE 2 automation server.
  8.   AUTOCALC.EXE :  EXE version of OLE 2 automation server.
  9.   CALLCALC.EXE :  Automation controller which exercises the
  10.                   DLL and EXE automation servers.
  11.  
  12. The following sections describe how to build, register and run
  13. the samples created AUTOCALC using either the Integrated
  14. Development Environment (IDE) or the command line tools of
  15. Borland C++. The section 'Additional Information' provides some
  16. interesting insights on the features illustrated by the samples.
  17.  
  18.  
  19. Building the Samples from the IDE
  20. ================================= 
  21. To build the targets described above, open the AUTOCALC.IDE
  22. project and select the 'Build All' option from the Project menu.
  23. NOTE: It is important to select 'Build All' as the DLL and EXE
  24. servers are built from the same sources but require different
  25. compiler configurations.
  26.  
  27.  
  28. Registering the Servers from the IDE
  29. ====================================
  30. The DLL and EXE servers must be registered with OLE before
  31. running the controller. After building the targets, register the
  32. automation servers using the steps described below:
  33.  
  34. i.  Right-mouse click on the ACALIPS.DLL node within the Project window.
  35.     (This activates the local menu).
  36.  
  37. ii. Select the 'Special|Register OLE Server' menu option.
  38.     (This registers the DLL Server with OLE).
  39.  
  40. Repeat the above steps with the AUTOCALC.EXE node to register the
  41. EXE server with OLE.
  42.  
  43.  
  44. Running the Controller from the IDE
  45. ===================================
  46. To exercise the DLL and EXE servers, activate the CALLCALC.EXE
  47. node and select the Run option from the Debug menu. CALLCALC
  48. looks for a command line argument string consisting of numbers
  49. between 1 and 6. The following table describes how each number
  50. is interpreted by the controller:
  51.  
  52.     Number in CmdLine         Action performed by Controller
  53.     ---------------------------------------------------------------
  54.       1                       Binds to EXE Server via CLSID
  55.       2                       Binds to EXE Server via progid
  56.       3                       Binds to DLL Server via CLSID
  57.       4                       Binds to DLL Server via progid
  58.       5                       Binds to EXE Server via CLSID in debug mode
  59.       6                       Binds to EXE Server via progid in debug mode
  60.  
  61.  
  62. If no command line string is specified, CALLCALC.EXE defaults to
  63. "1234" - the EXE and DLL Servers are activated via both CLSID
  64. and progids in non-debug mode. You can specify an argument
  65. string by selecting Environment|Debugger|Run_Arguments from the
  66. Options menu. For example, the string "135" exercises the
  67. servers by binding via CLSIDs only.
  68.  
  69.  
  70. Using the command line tools 
  71. ============================ 
  72. A MAKEFILE is provided for building the samples of this project.
  73. Since OLE applications need to perform several tasks, (such as
  74. registering with the system or generating TypeLibrary files)
  75. which require Windows, you must run the MAKEFILE at a DOS prompt
  76. from Windows and make sure that the Borland C++ WINRUN utility
  77. is properly configured. (See UTILS.TXT for more information
  78. about WINRUN).
  79.  
  80.  
  81. Building the Samples from the command line
  82. ==========================================
  83. To build the targets described above, simply execute the MAKE
  84. command from the EXAMPLES\OCF\AUTOCALC directory. NOTE: The
  85. MAKE utility will execute the AUTOCALC.EXE program to generate a
  86. TypeLibrary file which is then used to build CALLCALC.EXE.
  87.  
  88.  
  89. Registering the Servers from the command line
  90. =============================================
  91. The MAKE utility will automatically invoke the REGISTER.EXE
  92. utility to register the DLL version of the automation server.
  93. The MAKE utility also executes the AUTOCALC.EXE application (to
  94. generate a TypeLibrary file) which allows the EXE server to be
  95. registered.
  96.  
  97.  
  98. Running the Controller from the command line
  99. ============================================
  100. To exercise the DLL and EXE servers, run CALLCALC.EXE utility
  101. using the following command:
  102.  
  103.         wr  callcalc.exe
  104.  
  105. CALLCALC looks for a command line argument string consisting of
  106. numbers between 1 and 6. The following table describes how each
  107. number is interpreted by the controller:
  108.  
  109.     Number in CmdLine         Action performed by Controller
  110.     ---------------------------------------------------------------
  111.       1                       Binds to EXE Server via CLSID
  112.       2                       Binds to EXE Server via progid
  113.       3                       Binds to DLL Server via CLSID
  114.       4                       Binds to DLL Server via progid
  115.       5                       Binds to EXE Server via CLSID in debug mode
  116.       6                       Binds to EXE Server via progid in debug mode
  117.  
  118.  
  119. If no command line string is specified, CALLCALC.EXE defaults to
  120. "1234":  the EXE and DLL Servers are activated via both CLSID
  121. and progids in non-debug mode. The following command exercices
  122. the servers by binding via CLSIDs only.
  123.  
  124.         wr  callcalc.exe 135
  125.  
  126. Note that the Accumulator field of the CALLCALC dialog box is updated by an
  127. automation callback from the calculator using a report object passed to the
  128. callculator by the controller. Try manually entering numbers in the calculator.
  129.  
  130.  
  131. Additional Build Information
  132. ======================
  133. This sample illustrates building both a DLL and EXE server from
  134. one set of sources. The file WINMAIN.CPP takes advantage of
  135. compiler macros to provide separate OLE registration values and
  136. program entry point (LibMain vs. WinMain) for the DLL and EXE
  137. versions. NOTE: Since the DLL and EXE server use the same set of
  138. .CPP files, make sure that you use the Build_All option when
  139. rebuilding either servers after modifying the sources.
  140.  
  141. This sample also illustrates the performance advantage of DLL
  142. servers: the passes which bind to the DLL server are noticeably
  143. faster than the ones which bind to the EXE version.
  144.  
  145.  
  146. Automated Classes - examples of various types of automated classes
  147. =================
  148.  
  149. class TCalc        application object, contains TCalcWindow as a member object
  150. class TCalcWindow  calculator dialog box with window property accessors
  151. class TCalcButton  simple encapsulation of a dialog button
  152. class TButtonList  collection of calculator buttons, exposed for automation
  153. class TCalcArray   collection of simple integers, not related to calc function
  154.  
  155.  
  156. Automation Features Demonstrated
  157. ================================
  158.  
  159. Returning C++ objects - TCalcWindow as a property of TCalc
  160. C++ objects as arguments - LookAtWindow method with TCalcWindow argument
  161. External object as property - TUpdate object binding to external IDispatch*
  162. Callback via external object - Calling method on TUpdate proxy object
  163. Exposing collection of intrisic types - interger array exposed as collection
  164. Exposing collection of objects - TButtonList collection of TCalcButton objects
  165. Enumeration of C++ enumeration - translation of C++ operators to text strings
  166. Help strings, help context IDs, and help files for automation
  167. Localization of names and help - resourced translations for German language
  168. Registration of error code translator - function to convert codes to strings
  169.  
  170.  
  171. Running AUTOCALC from a VBA application
  172. =======================================
  173.  
  174. BASIC scripts are supplied which bring up and control the calculator.
  175. Note that the script first trys to connect to a running instance of AUTOCALC,
  176. then, if that fails, will create a new instance of AUTOCALC.
  177. The progid, "OCCalc.Application", may be changed to "OCCalc.DLLServer".
  178. The steps to run the AUTOCALC.BAS script from Microsoft Excel are as follows:
  179.   Invoke EXCEL.EXE
  180.   Menu: Insert..Macro..Module
  181.   Menu: Insert..File..(select All Files(*.*), select directory) AUTOCALC.BAS
  182.   At this point script will run with F5 or the VB run icon (green triangle).
  183.   To enable browsing the registered type library for AUTOCALC do as below:
  184.   Menu: Tools..References..check: Automated Calculator 1.0 Application
  185.   The F2 key brings up the Object Browser, select Library: OCCalc.Application
  186. To enable Excel to use German scripts, German type libraries must be setup:
  187.   VBADE.OLB must be present, normally in the WINDOWS\SYSTEM directory
  188.   XLDE50.OLB must be present, normally in the same directory with Excel
  189.   In order to use the object browser, the German typelib must be registered:
  190.   Run AUTOCALC with the command line: -Language=9 -Typelib=ACALCGER
  191.   Create a new workbook with File New or by invoking Excel
  192.   Menu: Insert..Macro..Module (or use the icon with a bunch of linked boxes)
  193.   Menu: Tools..References..Browse..navigate to and select XLDE50.OLB
  194.   Ignore the following following error message and exit the dialogs with OK:
  195.     "Object library's language setting incompatible with current project"
  196.   Menu: Tools..References..Browse..navigate to and select VBADE.OLB
  197.   The German type libraries are now registered in the system registry.
  198. To run the German language script, ACALCGER.BAS, perform the steps below:
  199.   Menu: Tools..Options..Module General..Language/Country..German/Germany
  200.   Menu: Insert..File..(select All Files(*.*), select directory) ACALCGER.BAS
  201.   Menu: Tools..References..check: Automatisierte Taschenrechner-Anwendung 1.0
  202.   Bring up the Object Browser, select Library: OCCalc.Application
  203.   
  204.