home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1996 December / PCWKCD1296.iso / vjplusb / msdev / redist / racreg32.txt < prev    next >
Text File  |  1996-05-06  |  11KB  |  263 lines
  1. Windows NT 4.0 Distributed COM and Visual Basic
  2. May 10, 1996
  3.  
  4. By providing Remote Automation in Visual Basic 4.0 Enterprise
  5. Edition (VB4EE), the Visual Basic product team enabled a new
  6. class of distributed solution development with a clear migration
  7. to future, integrated technologies.  Those technologies are here
  8. now with Windows NT 4.0 and DCOM.
  9.  
  10. Microsoft is pleased to offer updated tools and information to
  11. help our VB4EE customers use the new distributed capabilities of
  12. DCOM in Windows NT 4.0.  In this readme.txt file you'll find
  13. descriptions of updated administrative tools, and the latest
  14. compatibility information available.
  15.  
  16. The information here is written to assume that you have
  17. installed Windows NT 4.0 Beta 1 (build 1234), or Beta 2 (build
  18. 1314), or later, and that the DCOM has been enabled properly.
  19.  
  20. Also, you must have a valid Visual Basic Enterprise Edition
  21. license.  The tools rely on a number of VB4EE support files,
  22. like ActiveX Controls and the VB runtime DLL.  These must be
  23. installed properly on the system.
  24.  
  25. What's here, what's not
  26.  
  27. We have included updated administrative tools that extend class
  28. configuration options to include DCOM.  This is a very simple
  29. approach, taking advantage of the complete compatibility that
  30. this new release of DCOM provides.
  31.  
  32. DCOM provides a robust suite of methods for instantiating COM
  33. objects, including ways to indicate the remote machine name in
  34. the call to create the object.  Future releases of Visual Basic
  35. will reflect this additional capability.
  36.  
  37. Once Windows NT 4.0 is available as a released product, more
  38. complete and powerful administrative tools will be available.
  39. Some tools will be provided in Windows NT 4.0 for administration
  40. of DCOM services.  Others will be in a future release of Visual
  41. Basic Enterprise Edition, allowing automated migration, etc.
  42.  
  43. Remote Automation
  44.  
  45. The Remote Automation technology that shipped in VB4EE was a
  46. specific subset of DCOM capabilities.  It consists of client,
  47. server, and administrative components.  It implemented remote
  48. connections to specific COM interfaces and features to
  49. facilitate remote instantiation and communication with OLE
  50. Automation servers.  OLE Automation is a set of OLE interfaces
  51. dealing with richer type information and script-based services
  52. for identifying a class' capabilities.
  53.  
  54. DCOM does not specify OLE Automation interfaces (or any other
  55. OLE interfaces).  It simply facilitates interfaces and also
  56. allows interface remoting.  Therefore, any components built with
  57. COM-compliant interfaces, e.g. OLE Automation components, or any
  58. component with a custom interface, can be remoted via DCOM.
  59.  
  60. The client and server components of Remote Automation are
  61. completely replaced by native DCOM capabilities.  When using
  62. DCOM, the files Remote Automation Proxy (autprx32.dll) and the
  63. Remote Automation Manager (autmgr32.exe) are no longer needed.
  64. The administrative components are addressed below.
  65.  
  66. New Tools
  67.  
  68. Two tools are included, racreg32.dll and racmgr32.exe.
  69. Racreg32.dll is described below, in "RacReg32 Interfaces."
  70. Racmgr32.exe has been updated to include a new choice for
  71. remoting classes.  There are option buttons on the Server
  72. Connection tab that indicate Distributed COM and Remote
  73. Automation.  Switching from Remote Automation to DCOM is as
  74. simple as selecting the Distributed COM option and pressing the
  75. Apply button.
  76.  
  77.     Complete these steps once:
  78.      - Enable DCOM using the dcomcnfg.exe tool in the beta
  79.      - Save the old copies of racreg32.dll and racmgr32.exe
  80.      - Register racreg32.dll on the client machine using
  81.        regsvr32.exe
  82.  
  83.     Complete these for each OLE automation server:
  84.      - Register your OLE components (your .dll and .exe files)
  85.      - Run racmgr32.exe on the client to set the remote machine
  86.        information for the class(es)
  87.  
  88. Error Reporting
  89.  
  90. With Remote Automation, a number of errors with the RPC
  91. transport and other components were reported as OLE errors, often
  92. incorrectly or out of context.  This was due to complex
  93. interactions with several different entities along the path of a
  94. remote object connection.
  95.  
  96. With DCOM, all the facilities involved have been unified, and
  97. errors are correctly reported.  When Visual Basic receives an
  98. error from COM, it accurately reflects the true error.  COM has
  99. been extended to report additional, remoting related errors that
  100. are correctly mapped to the corresponding description by the
  101. system.
  102.  
  103. RacReg32 Interfaces
  104.  
  105. Before proceding, note that this information is incremental
  106. only. Please familiarize yourself with the information on
  107. racreg32.dll that is included in the VB4EE documentation.
  108.  
  109. There is one new method in racreg32.dll.  This method allows
  110. configuration of a class to use DCOM.  New behavior on another
  111. method returns an indicator of whether a class is configured for
  112. DCOM if it is remoted.
  113.  
  114.     Public Function SetDCOMServerSettings _
  115.                (ByVal Remote As Boolean, _
  116.                 Optional ByVal ProgID As Variant, _
  117.                 Optional ByVal CLSID As Variant, _
  118.                 Optional ByVal ServerName As Variant) _
  119.                 As Integer
  120.  
  121.     Sets the DCOM registry values to meet OLE and
  122.     COM requirements, including configuration settings for
  123.     remote server access.
  124.  
  125.     The SetDCOMServerSettings method syntax has these parts:
  126.  
  127.     Part        Type        Description
  128.  
  129.     Remote        Boolean    True if the server is remote
  130.     ProgID        Variant The ProgID for the server
  131.     CLSID        Variant    The CLSID for the server
  132.     ServerName    Variant    The name of the server machine
  133.  
  134.     Return Values
  135.  
  136.     The method returns the following error codes:
  137.  
  138.     Value    Description
  139.  
  140.     0    No error.
  141.     1    Unknown run time error occurred.
  142.     2    No protocol was specified.
  143.     3    No server machine name was specified.
  144.     4    An error occurred reading from the registry.
  145.     5    An error occurred writing to the registry.
  146.     6    Both the ProgID and CLSID parameters were missing.
  147.     7    There is no local server (either in-process or
  148.         cross-process, 16-bit or 32-bit).
  149.     8    There was an error looking for the Proxy DLLs, check
  150.         that they were installed properly.
  151.  
  152.     Remarks
  153.  
  154.     The SetDCOMServerSettings method will take either a CLSID or
  155.     a ProgID and set the registry information to local or remote
  156.     depending on the value of the Remote parameter.  If a CLSID
  157.     and a ProgID are passed to the method, the CLSID will take
  158.     precedence.
  159.  
  160.     NOTE:  SetNetOLEServerSettings is a synonym for
  161.     SetDCOMServerSettings.  Older applications that may have coded
  162.     to the method SetNetOLEServerSettings will continue to work,
  163.     but SetDCOMServerSettings is the preferred method name.
  164.  
  165.  
  166.     ~~~~~~~~~~~~~~~~~~~~~
  167.     GetAutoServerSettings
  168.  
  169.     Returns information about the state of an OLE object's
  170.     registration.
  171.  
  172.     Syntax
  173.  
  174.     object.GetAutoServerSettings ([ProgID], [CLSID])
  175.  
  176.     The GetAutoServerSettings method returns a Variant that
  177.     contains an array of values about the given OLE class.  The
  178.     index values and descriptions shown in the following table.
  179.  
  180.     Value    Description
  181.  
  182.     1    True if the server is registered remotely.
  183.     2    Remote machine name.
  184.     3    RPC network protocol name.
  185.     4    RPC authentication level.
  186.     5    True if the server is registered for DCOM,
  187.         false if for Remote Automation ** NEW **
  188.  
  189.     If a value is missing or not available, the value will be an
  190.     empty string.  If there is an error during the method, then the
  191.     return value will be a Variant of type Empty.
  192.  
  193.  
  194. APPID and CLSID
  195.  
  196. Beta 2 of DCOM changed the implementation of certain DCOM-related
  197. registry keys.  Newly introduced is the APPID, a GUID used to
  198. abstract common registry-based information from the CLSID up to a
  199. higher level, based on the entire component's binary image.  The
  200. DCOM documentation contains complete information on this new
  201. key.
  202.  
  203. Until development tools implement APPID registration, these
  204. remote automation tools and the DCOM configuration utility use
  205. the CLSID value for the APPID.  Therefore, when configuring
  206. servers for remote connection, the registry will contain
  207. something like the following:
  208.  
  209.         HKEY_CLASSES_ROOT\APPID
  210.                 {guid}          <various DCOM settings>
  211.         HKEY_CLASSES_ROOT\CLSID
  212.                 {guid}          AppID={guid}
  213.  
  214. The AppID value in the CLSID key maps the CLSID back to the APPID,
  215. where the DCOM settings are stored.
  216.  
  217. Racreg32.dll is able to detect the build of Windows NT and perform
  218. the appropriate configuration for the build on which it is running.
  219. For example, on Beta 1 it puts the remoting information in the CLSID
  220. key, and on Beta 2 it uses the APPID key.
  221.  
  222. NOTE:  This APPID information applies only to Beta 2 (build 1314) of
  223. Windows NT 4.0.
  224.  
  225. Server User Interfaces
  226.  
  227. Some automation servers were written to intentionally include user
  228. interface components such as a form or message boxes.  While these
  229. can be helpful for reporting errors or diagnostic information, they
  230. block operation of the server while the form is displayed.
  231.  
  232. When servers are run under DCOM, they are hidden by default.  They
  233. are running as services on an effectively hidden desktop.  In order
  234. to see and interact with the servers, they must be running in the
  235. winstation of the interactive user.
  236.  
  237. To allow your servers to show up on the desktop, add a "RunAs" key
  238. to the server's APPID key, and put the string "Interactive User" in
  239. the default value for the key.  Note that the server will only run
  240. when a user is logged on to the Windows NT system.  If there is no
  241. interactive user, the server activation will fail.  The beta DCOM
  242. documentation contains complete information on this topic.
  243.  
  244. Client-side Only
  245.  
  246. It is important to note that while racreg32.dll dealt only with
  247. client-side configuration, racmgr32.exe had configuration options
  248. for client and server together in one application.  Only the
  249. client-side information is valid for DCOM.  Currently,
  250. other DCOM-specific tools must be used to manage server-side
  251. semantics such as allowing activation, etc.  The server-side
  252. settings in the tool apply only to Remote Automation and are benign in DCOM.
  253.  
  254. Careful with Server Versions
  255.  
  256. The new racreg32.dll has been implemented with interfaces
  257. compatible to the racreg32.dll that shipped with VB4EE.  This means
  258. that applications written to the old DLL will still work, and new
  259. applications can take advantage of the new interface (described
  260. above).  Please save the old racreg32.dll before installing the new
  261. on, or put the new one in a separate subdirectory.  If difficulty
  262. arises, re-register the old DLL using regsvr32.exe.
  263.