Windows NT 4.0 Distributed COM and Visual Basic May 10, 1996 By providing Remote Automation in Visual Basic 4.0 Enterprise Edition (VB4EE), the Visual Basic product team enabled a new class of distributed solution development with a clear migration to future, integrated technologies. Those technologies are here now with Windows NT 4.0 and DCOM. Microsoft is pleased to offer updated tools and information to help our VB4EE customers use the new distributed capabilities of DCOM in Windows NT 4.0. In this readme.txt file you'll find descriptions of updated administrative tools, and the latest compatibility information available. The information here is written to assume that you have installed Windows NT 4.0 Beta 1 (build 1234), or Beta 2 (build 1314), or later, and that the DCOM has been enabled properly. Also, you must have a valid Visual Basic Enterprise Edition license. The tools rely on a number of VB4EE support files, like ActiveX Controls and the VB runtime DLL. These must be installed properly on the system. What's here, what's not We have included updated administrative tools that extend class configuration options to include DCOM. This is a very simple approach, taking advantage of the complete compatibility that this new release of DCOM provides. DCOM provides a robust suite of methods for instantiating COM objects, including ways to indicate the remote machine name in the call to create the object. Future releases of Visual Basic will reflect this additional capability. Once Windows NT 4.0 is available as a released product, more complete and powerful administrative tools will be available. Some tools will be provided in Windows NT 4.0 for administration of DCOM services. Others will be in a future release of Visual Basic Enterprise Edition, allowing automated migration, etc. Remote Automation The Remote Automation technology that shipped in VB4EE was a specific subset of DCOM capabilities. It consists of client, server, and administrative components. It implemented remote connections to specific COM interfaces and features to facilitate remote instantiation and communication with OLE Automation servers. OLE Automation is a set of OLE interfaces dealing with richer type information and script-based services for identifying a class' capabilities. DCOM does not specify OLE Automation interfaces (or any other OLE interfaces). It simply facilitates interfaces and also allows interface remoting. Therefore, any components built with COM-compliant interfaces, e.g. OLE Automation components, or any component with a custom interface, can be remoted via DCOM. The client and server components of Remote Automation are completely replaced by native DCOM capabilities. When using DCOM, the files Remote Automation Proxy (autprx32.dll) and the Remote Automation Manager (autmgr32.exe) are no longer needed. The administrative components are addressed below. New Tools Two tools are included, racreg32.dll and racmgr32.exe. Racreg32.dll is described below, in "RacReg32 Interfaces." Racmgr32.exe has been updated to include a new choice for remoting classes. There are option buttons on the Server Connection tab that indicate Distributed COM and Remote Automation. Switching from Remote Automation to DCOM is as simple as selecting the Distributed COM option and pressing the Apply button. Complete these steps once: - Enable DCOM using the dcomcnfg.exe tool in the beta - Save the old copies of racreg32.dll and racmgr32.exe - Register racreg32.dll on the client machine using regsvr32.exe Complete these for each OLE automation server: - Register your OLE components (your .dll and .exe files) - Run racmgr32.exe on the client to set the remote machine information for the class(es) Error Reporting With Remote Automation, a number of errors with the RPC transport and other components were reported as OLE errors, often incorrectly or out of context. This was due to complex interactions with several different entities along the path of a remote object connection. With DCOM, all the facilities involved have been unified, and errors are correctly reported. When Visual Basic receives an error from COM, it accurately reflects the true error. COM has been extended to report additional, remoting related errors that are correctly mapped to the corresponding description by the system. RacReg32 Interfaces Before proceding, note that this information is incremental only. Please familiarize yourself with the information on racreg32.dll that is included in the VB4EE documentation. There is one new method in racreg32.dll. This method allows configuration of a class to use DCOM. New behavior on another method returns an indicator of whether a class is configured for DCOM if it is remoted. Public Function SetDCOMServerSettings _ (ByVal Remote As Boolean, _ Optional ByVal ProgID As Variant, _ Optional ByVal CLSID As Variant, _ Optional ByVal ServerName As Variant) _ As Integer Sets the DCOM registry values to meet OLE and COM requirements, including configuration settings for remote server access. The SetDCOMServerSettings method syntax has these parts: Part Type Description Remote Boolean True if the server is remote ProgID Variant The ProgID for the server CLSID Variant The CLSID for the server ServerName Variant The name of the server machine Return Values The method returns the following error codes: Value Description 0 No error. 1 Unknown run time error occurred. 2 No protocol was specified. 3 No server machine name was specified. 4 An error occurred reading from the registry. 5 An error occurred writing to the registry. 6 Both the ProgID and CLSID parameters were missing. 7 There is no local server (either in-process or cross-process, 16-bit or 32-bit). 8 There was an error looking for the Proxy DLLs, check that they were installed properly. Remarks The SetDCOMServerSettings method will take either a CLSID or a ProgID and set the registry information to local or remote depending on the value of the Remote parameter. If a CLSID and a ProgID are passed to the method, the CLSID will take precedence. NOTE: SetNetOLEServerSettings is a synonym for SetDCOMServerSettings. Older applications that may have coded to the method SetNetOLEServerSettings will continue to work, but SetDCOMServerSettings is the preferred method name. ~~~~~~~~~~~~~~~~~~~~~ GetAutoServerSettings Returns information about the state of an OLE object's registration. Syntax object.GetAutoServerSettings ([ProgID], [CLSID]) The GetAutoServerSettings method returns a Variant that contains an array of values about the given OLE class. The index values and descriptions shown in the following table. Value Description 1 True if the server is registered remotely. 2 Remote machine name. 3 RPC network protocol name. 4 RPC authentication level. 5 True if the server is registered for DCOM, false if for Remote Automation ** NEW ** If a value is missing or not available, the value will be an empty string. If there is an error during the method, then the return value will be a Variant of type Empty. APPID and CLSID Beta 2 of DCOM changed the implementation of certain DCOM-related registry keys. Newly introduced is the APPID, a GUID used to abstract common registry-based information from the CLSID up to a higher level, based on the entire component's binary image. The DCOM documentation contains complete information on this new key. Until development tools implement APPID registration, these remote automation tools and the DCOM configuration utility use the CLSID value for the APPID. Therefore, when configuring servers for remote connection, the registry will contain something like the following: HKEY_CLASSES_ROOT\APPID {guid} HKEY_CLASSES_ROOT\CLSID {guid} AppID={guid} The AppID value in the CLSID key maps the CLSID back to the APPID, where the DCOM settings are stored. Racreg32.dll is able to detect the build of Windows NT and perform the appropriate configuration for the build on which it is running. For example, on Beta 1 it puts the remoting information in the CLSID key, and on Beta 2 it uses the APPID key. NOTE: This APPID information applies only to Beta 2 (build 1314) of Windows NT 4.0. Server User Interfaces Some automation servers were written to intentionally include user interface components such as a form or message boxes. While these can be helpful for reporting errors or diagnostic information, they block operation of the server while the form is displayed. When servers are run under DCOM, they are hidden by default. They are running as services on an effectively hidden desktop. In order to see and interact with the servers, they must be running in the winstation of the interactive user. To allow your servers to show up on the desktop, add a "RunAs" key to the server's APPID key, and put the string "Interactive User" in the default value for the key. Note that the server will only run when a user is logged on to the Windows NT system. If there is no interactive user, the server activation will fail. The beta DCOM documentation contains complete information on this topic. Client-side Only It is important to note that while racreg32.dll dealt only with client-side configuration, racmgr32.exe had configuration options for client and server together in one application. Only the client-side information is valid for DCOM. Currently, other DCOM-specific tools must be used to manage server-side semantics such as allowing activation, etc. The server-side settings in the tool apply only to Remote Automation and are benign in DCOM. Careful with Server Versions The new racreg32.dll has been implemented with interfaces compatible to the racreg32.dll that shipped with VB4EE. This means that applications written to the old DLL will still work, and new applications can take advantage of the new interface (described above). Please save the old racreg32.dll before installing the new on, or put the new one in a separate subdirectory. If difficulty arises, re-register the old DLL using regsvr32.exe.