OpenVMS Connectivity Developer Guide


Previous Contents Index


Appendix B
Troubleshooting

B.1 RPC Troubleshooting

When you perform a significant number of simultaneous NTLM authentications, the following errors are likely to occur. Several factors affect the number of simultaneous NTLM authentications, however, you are most likely to see these errors when the network is congested or when the RPC application server does not respond to requests in a timely manner. The errors are returned as standard RPC application return values.

Table B-1 provides a description of the suspected cause and possible workarounds.

Table B-1 RPC Errors
Error Cause/Corrective Actions
RPC_S_CONNECTION_REJECTED This error is seen by the client application as an exception when using either DECnet Phase IV or DECnet Phase V as a transport and when the server is heavily loaded servicing other DECnet clients.

The system returns this error when the client RPC run time binds to a newly created socket and the socket call returns error 61 (connection refused).

Possible solutions:

  1. Raise DECnet resource quotas.
  2. Enhance the client RPC program to catch the exception and either retry the RPC or choose a different server.
RPC_S_CONNECTION_TIMED_OUT This error is seen by the client application as an exception when using TCP or DECnet as a transport and when the server is heavily loaded.

The system returns this error when the client RPC run time binds to a newly created socket and the server takes too long to either accept or reject the connection.

Possible solutions:

  1. Configure TCP or DECnet to wait longer before sockets time out.
  2. Enhance the RPC client application to call rpc_mgmt_set_com_timeout() and instruct the RPC run time to retry when it gets this socket error.
  3. Recode the client RPC program to catch the exception and either retry the RPC or choose a different server.
RPC_S_ASSOC_SHUTDOWN This error is seen by the client application as an exception when using TCP or DECnet as a transport and when the client is heavily loaded (usually when the client is also an RPC server).

After an RPC server receives an RPC_BIND packet from a client and the server sends back an RPC_BIND_ACK packet to the client, the server expects to receive a REQUEST packet within 12 seconds. If the client does not send the REQUEST packet within 12 seconds, the RPC server deletes the association and sends a SHUTDOWN packet to the client. The client RPC run time raises an exception to the RPC application.

This scenario is likely to occur when the client RPC application is also acting as an RPC server and that RPC server is already heavily loaded.

Possible solutions:

  1. Implement the client RPC program to catch the exception and either retry the RPC or choose a different server.
RPC_S_COMM_FAILURE

This error is seen by the client application as an exception when using DG (UDP) as a transport and when the RPC server is heavily loaded.

The RPC client sends a REQUEST packet to the server. If the client does not get a WORKING packet response from the server within 30 seconds, the client sends a PING packet to the server to see if the server is still active and working on the client's request. If the RPC server is under heavy load, the server may not return the WORKING packet to the client before the client times out.

Possible solutions:

  1. RPC client application can call rpc_mgmt_set_com_timeout() to instruct the RPC run time to wait longer than 30 seconds before timing out.
  2. Implement the client RPC program to catch the exception and either retry the RPC or choose a different server.

B.2 Troubleshooting the ACME server

Use the following procedure to troubleshoot problems with the ACME server:

  1. Verify that the ACME_SERVER process is running (use the SHOW SERVER ACME command) and verify there is a connection between the MSV1_0 ACME agent and the Compaq Advanced Server for OpenVMS process.
  2. If no connection exists, verify that the PWRK$ACME_SERVER logical name contains the SCS node names of systems in the cluster that are running the Compaq Advanced Server for OpenVMS process.
  3. If the PWRK$ACME_SERVER logical name is defined correctly, verify that the Compaq Advanced Server for OpenVMS process is running on the systems specified (look for the PWRK$LMSRV process).
  4. If authentications are failing, check the following:

B.3 Troubleshooting the DCOM$RPCSS Process

The DCOM$RPCSS process must be running to run any COM for OpenVMS applications on your OpenVMS system. The DCOM$STARTUP.COM command file is automatically starts this process. If you have problems running COM for OpenVMS applications, check that this process is running. Use the following command:


  $ SHOW SYSTEM 

If the process is initializing, the process name is DCOM$STARTUP-**. If the process is in its normal running state, the process name is be DCOM$RPCSS.

Check the SYS$MANAGER:DCOM$RPCSS.OUT log file for error messages from the DCOM$RPCSS process. The messages can include the following:

B.4 Troubleshooting the Advanced Server for OpenVMS

The Advanced Server for OpenVMS must be running to authenticate users with NT credentials.

A troubleshooter may wish to enable the audit policy to capture failures for logonoff and system events. For example, on systems running Advanced Server for OpenVMS, issue the command:


    $ ADMINISTER SET AUDIT POLICY/AUDIT/FAILURE=(LOGONOFF,SYSTEM) 

To monitor events, issue the commands:


    $ ADMINISTER SHOW EVENT /FULL /TYPE=SYSTEM 
    $ ADMINISTER SHOW EVENT /FULL /TYPE=SECURITY 

For more information, the Advanced Server for OpenVMS Server Administrator's Guide provides a chapter on Monitoring Events and Troubleshooting.

Additionally, the system manager may want to check the system operator log, SYSMANAGER:OPERATOR.LOG, to verify that no network errors have occurred.

B.5 Troubleshooting COM for OpenVMS Application Failures

This section describes problems you may encounter when running a COM application.

B.5.1 Access Denied Failures

For information on access denied failures, see Section 5.4.6.


Appendix C
Cookbook Examples: Building a Sample Application on OpenVMS

Note

SAMPLE1 and DISPATCH_SAMPLE1 are taken from Dale Rogerson's book, Inside COM, published by Microsoft Press.

C.1 COM Example (Sample1)

This example implements a COM client and server in which the component provides two interfaces: IX and IY . The client also queries the component for a third interface, IZ , an interface that the component does not provide.

This example demonstrates connectivity between two OpenVMS systems, between two Windows NT systems, or between an OpenVMS system and a Windows NT system.

Note

Before you build the application on OpenVMS, you must run NTA$LOGON and acquire Windows NT credentials. For more information, see Section 8.2.

C.1.1 OpenVMS Instructions

The following sections describe how to build the application on an OpenVMS system.

C.1.1.1 Building the Application on OpenVMS

Copy files from the DCOM examples directory to your local directory. For example:


   $ set default mydisk:[mydirectory] 
   $ copy dcom$examples:[sample1]*.* [] 

To build the application, run the following command procedure:


   $ @build_sample1 

If you have MMS, you can use the included description file as follows:


   $  MMS/DESCRIPTION=BUILD_SAMPLE1.MMS 

The BUILD file builds and registers both the in-process and out-of-process servers.

C.1.1.2 Registering the Application on OpenVMS

The build procedure automatically registers both DISPCMPNT$SHR.EXE and DISPCMPNT.EXE . To register the components manually, use the following procedure:

C.1.1.3 Running the Application on OpenVMS as an Out-of-Process Server

To run the sample where the component is an out-of-process server, run DISPCMPNT.EXE . When the system displays the Server: Waiting message from the component, run the client in a separate window or terminal session.

The client displays the following:


  To which server do you want to connect? 
   1) In-Process Server 
   2) Out-of-Process Server 
   : 

Enter 2 to select the out-of-process server.

C.1.1.4 Running the Application on OpenVMS and Specifying a Remote Server

Run DISPCMPNT.EXE on the system you designate as the remote machine (or server system). The remote system can also be a Windows NT system. When you receive the Server: Waiting message from the component, run the client on the system you designate as the local machine (or client system). For example:


   $ client :== $path-nameCLIENT.EXE 
   $ client remote-system-name
   2 
   $ 

The client displays the following:


  To which server do you want to connect? 
   1) In-Process Server 
   2) Out-of-Process Server 
   : 

Enter 2 to select remote server execution, out-of-process server.

C.1.1.5 Running the Application on OpenVMS as an In-Process Server

To run the sample where the component is an in-process server, run only the client. For example:


   For InProc: 
   $ client 
   1 
   $ 

The client displays the following:


  To which server do you want to connect? 
   1) In-Process Server 
   2) Out-of-Process Server 
   : 

Enter 1 to select the in-process server.

C.1.2 Windows NT Instructions

The following sections describe how to build the application on a Windows NT system.

Note

In order to build Visual C++ applications from a DOS window, you must first set up a number of environment variables. If you did not select the option to have these variables set up automatically when you installed Visual C++, you will need to set them up each time you create a DOS window. To set up these variables, execute the file


C:\Program Files\Microsoft Visual Studio\VC98\BIN\VCVARS32.BAT 

C.1.2.1 Building the Application on Windows NT

Copy the README-SAMPLE1.TXT file and the following files from the COM examples directory to your Windows NT system:


   CLIENT.CXX 
   CMPT.CXX 
   CMPT.DEF 
   MAKE-ONE. 
   MAKEFILE.BAT 
   PROXY.DEF 
   REGISTRY.CXX 
   REGISTRY.H 
   SERVER.IDL   

Build the sample using the MAKEFILE.BAT file. For example:


   > MAKEFILE 

The Makefile builds and registers both the in-process and out-of-process servers.

C.1.2.2 Registering the Application on Windows NT

The build procedure make-one automatically registers DISPCMPNT.DLL , PROXY.DLL , and CMPNT.EXE as follows:


   regsvr32 -s Dispcmpnt.dll 
   regsvr32 -s Proxy.dll 
   Dispcmpnt /RegServer 

To unregister the application, enter the following:


   regsvr32 -u Dispcmpnt.dll 
   regsvr32 -u Proxy.dll 
   Dispcmpnt /UnRegServer 

C.1.2.3 Running the Application on Windows NT

Run CLIENT . Follow the same procedure as described for OpenVMS for running the application as an in-process server ( Section C.1.1.5) and out-of-process server Section C.2.1.3).

Use the name of a remote machine (UNC or DNS) as an argument to instantiate the object on the remote machine. For example:


   >Client hostname        ! point the client at the remote system  
   2                       ! means outproc invocation       
   >                                                        

C.2 Automation Example (Dispatch_Sample1)

This example implements the Automation component server as a dual interface. There are two separate clients: Dclient , which connects to the dual interface through the dispinterface, and Client , which is a COM client implementation that connects through the IUnknown interface (using a v-table).

This example demonstrates connectivity between two OpenVMS systems, between two Windows NT systems, or between an OpenVMS system and a Windows NT system.

C.2.1 OpenVMS Instructions

The following sections describe how to build the application on an OpenVMS system.

C.2.1.1 Building the Application on OpenVMS

Copy files from the DCOM examples directory to your local directory. For example:


   $ set default mydisk:[mydirectory] 
   $ copy dcom$examples:[dispatch_sample1]*.* [] 

To build the application, run the following command procedure:


   $ @build_dispatch_sample1 

If you have MMS, you can use the included description file as follows:


   $  MMS/DESCRIPTION=BUILD_DISPATCH_SAMPLE1.MMS 

The BUILD file builds and registers both the in-process and out-of-process servers.

C.2.1.2 Registering the Application on OpenVMS

The build procedure automatically registers both DISPCMPNT$SHR.EXE and DISPCMPNT.EXE . To register the components manually, use the following procedure:

C.2.1.3 Running the Application on OpenVMS as an Out-of-process Server

To run the sample where the component is an out-of-process server, run DISPCMPNT.EXE .

When the system displays the Server: Waiting message from the component, run the client in a separate window or terminal session.

The client displays the following:


  To which server do you want to connect? 
   1) In-Process Server 
   2) Out-of-Process Server 
   : 

Enter 2 to select the out-of-process server.

C.2.1.4 Running the Application on OpenVMS and Specifying a Remote Server

Run DISPCMPNT.EXE on the system you designate as the remote machine (or server system). The remote system can also be a Windows NT system. When you receive the Server: Waiting message from the component, run the client on the system you designate as the local machine (or client system). For example:

To use the COM client, enter the following:


   $ client :== $path-nameCLIENT.EXE 
   $ client remote-system-name
  To which server do you want to connect? 
   1) In-Process Server 
   2) Out-of-Process Server 
   : 

Enter 2 to select remote server execution, out-of-process server.

C.2.1.5 Running the Application on OpenVMS as an In-Process Server

To run the sample where the component is an in-process server, run only the client. For example:

The client displays the following:


  To which server do you want to connect? 
   1) In-Process Server 
   2) Out-of-Process Server 
   : 

Enter 1 to select the in-process server.

C.2.2 Windows NT Instructions

The following sections describe how to build the application on a Windows NT system.

Note

In order to build Visual C++ applications from a DOS window, you must first set up a number of environment variables. If you did not select the option to have these variables set up automatically when you installed Visual C++, you will need to set them up each time you create a DOS window. To set up these variables, execute the file


C:\Program Files\Microsoft Visual Studio\VC98\BIN\VCVARS32.BAT 

C.2.2.1 Building the Application on Windows NT

Copy the README-DISPATCH-SAMPLE1.TXT file and the following files from the COM examples directory to your Windows NT system:


   CLIENT.CXX 
   DCLIENT.CXX 
   DISPCMPNT.CXX 
   DISPCMPNT.DEF 
   DISPCMPNT.IDL 
   MAKE-ONE. 
   MAKEFILE.BAT 
   REGISTRY.CXX 
   REGISTRY.H 

Build the sample using the MAKEFILE.BAT file. For example:


   C:> MAKEFILE 

The Makefile builds and registers both the in-process and out-of-process servers.

C.2.2.2 Registering the Application on Windows NT

The build procedure make-one automatically registers DISPCMPNT.DLL , PROXY.DLL , and DISPCMPNT.EXE as follows:


   regsvr32 -s Dispcmpnt.dll 
   Dispcmpnt /RegServer 

To unregister the application, enter the following:


   regsvr32 -u Dispcmpnt.dll 
   Dispcmpnt /UnRegServer 

C.2.2.3 Running the Application on Windows NT

Run DCLIENT or CLIENT . Follow the same procedure as described for OpenVMS for running the application as an in-process server ( Section C.2.1.5) and an out-of-process server ( Section C.2.1.3).

Use the name of a remote machine (UNC or DNS) as an argument to instantiate the object on the remote machine.

C.3 Cross-Domain Security Example (CLIENTAUTH)

This example shows how you can authenticate a remote client that is not in the server's domain or in a domain that has a trust with the server's domain. The client must pass to this application the credentials (user name, domain and password) of an account on the server's domain that is allowed access and launch permissions. In fact, the client need not be in any domain and can be anywhere on the network. This is demonstrated in Section C.3.1.3.

C.3.1 OpenVMS Instructions

The following sections describe how to build the application on an OpenVMS system.

Note

Not all functionality is present in the underlying Windows NT infrastructure on OpenVMS. Therefore, you cannot run the client on OpenVMS. This example works when you run the client on Windows NT and the server on OpenVMS.

Copy files from the DCOM examples directory to your local directory:


   $ set default mydisk:[mydirectory] 
   $ copy dcom$examples:[clientauth]*.* [] 

To build the application, run the command procedure:


   $ @build_clientauth 

The BUILD file builds and registers both the in-process and out-of-process servers.

C.3.1.1 Registering the Application on OpenVMS

PROXY$SHR.EXE , CLIENTAUTH$SHR.EXE , and CLIENTAUTH.EXE are registered automatically by the build procedure. To register the application manually, use the following procedure:

C.3.1.2 Running the Application on OpenVMS as an Out-of-Process Server

To run the example when the component is an out-of-process server, run CLIENTAUTH.EXE . When you receive the server waiting message from the component, run the client (in a separate window or terminal session).

C.3.1.3 Running the Application on OpenVMS and Specifying a Remote Server

Run CLIENTAUTH.EXE on the system you designate as the remote machine, or server system. The remote system can also be a Windows NT system. When you receive the server waiting message from the component, run the client on the system you designate as the local machine, or client system.


   $ client :== $<path-name>CLIENT.EXE 
   $ client <remote-system-name> 
   2 
   $ Please enter account to use on remote machine: 
   $ Username: 
   $ Domain: 
   $ Password: 

The client asks whether you want to start an in-process server or an out-of-process server. For remote server execution, specify out-of-process server. You then are prompted to enter the user name, domain, and password of an account on the remote server. Make sure this account has been granted access and launch permissions to the component (see Section 6.3.2).

C.3.1.4 Running the Application on OpenVMS as an In-Process Server

To run the sample when the component is an in-process server, run only the client:


   For InProc: 
   $ client 
   1 
   $ 

The client asks whether you want to start an in-process server or an out-of-process server. Specify in-process server.

C.3.2 Windows NT Instructions

The following sections describe how to build the application on a Windows NT system.

Note

In order to build Visual C++ applications from a DOS window, you must first set up a number of environment variables. If you did not select the option to have these variables set up automatically when you installed Visual C++, you will need to set them up each time you create a DOS window. To set up these variables, execute the following file:


C:\Program Files\Microsoft Visual Studio\VC98\BIN\VCVARS32.BAT 

C.3.2.1 Building the Application on Windows NT

Copy the file README-CLIENTAUTH.TXT and the following files from the DCOM examples directory to your Windows NT system:


   CLIENT.CXX 
   CLIENTAUTH.CXX 
   CLIENTAUTH.DEF 
   CLIENTAUTH.IDL 
   GUIDS.CXX 
   MAKE-ONE. 
   MAKEFILE.BAT 
   PROXY.DEF 
   REGISTRY.CXX 
   REGISTRY.H 

Build the sample using the MAKEFILE.BAT file:


   > MAKEFILE 

The Makefile builds and registers both the in-process and out-of-process servers.

C.3.2.2 Registering the Application on Windows NT

CLIENTAUTH.DLL , PROXY.DLL , and CLIENTAUTH.EXE are registered automatically by the build procedure <make-one>:


   regsvr32 -s clientauth.dll 
   regsvr32 -s Proxy.dll 
   clientauth /RegServer 

To unregister the application:


   regsvr32 -u clientauth.dll 
   regsvr32 -u Proxy.dll 
   clientauth /UnRegServer 

C.3.2.3 Running the Application on Windows NT

Run CLIENT. Follow the same procedure as described for running the application on an in-process server and out-of-process server (see Section C.3.1.2 and Section C.3.1.4).

Do not use command line arguments to instantiate the object on the current machine. Instead, use the name of a remote machine (UNC or DNS) as an argument to instantiate the object on the remote machine.


  (i.e) >Client hostname        ! point the client at the remote system 
        2                       ! means outproc invocation       
        >                                                        
        >Username: 
        >Domain: 
        >Password: 


Appendix D
Upgrading to COM Version 1.2 for OpenVMS from COM Version 1.0 for OpenVMS

D.1 Upgrading from Earlier Versions of COM for OpenVMS

The following sections describe tasks you must complete when upgrading from a previous version of COM for OpenVMS.

D.1.1 Rebuild Existing COM for OpenVMS Applications

If your COM for OpenVMS applications include references to any of the following APIs, you must recompile the modules that include the references and relink the application:

LoadLibraryA
LoadLibraryW
LoadLibraryExW
LoadLibraryExA
GetModuleFileNameA
GetModuleFileNameW
GetModuleHandleW
GetProcAddress
FreeLibrary

Some sample COM applications that shipped with COM Version 1.0 for OpenVMS include references to these APIs in the modules REGISTRY and CMPNT. If you built any samples, or if you built your own COM applications based on these samples, you should recompile and relink those applications.

D.1.2 Configuring the Windows NT Systems

For COM Version 1.0 for OpenVMS (unauthenticated COM) the COM for OpenVMS documentation instructed you to change specific values in your Windows NT registry to allow unauthenticated COM for OpenVMS to interoperate with Windows NT. COM Version 1.2 for OpenVMS, COM Version 1.1-B for OpenVMS, and COM Version 1.1-A for OpenVMS support authentication. As a result, you must set or reset the Windows NT Registry values we asked you to change for COM Version 1.0 for OpenVMS back to their default authenticated settings. To set the Windows NT Registry values, use the following procedure:

  1. Start the Windows NT Registry editor.
  2. Select the following registry key:


    HKEY_LOCAL_MACHINE\Software\Microsoft\Ole 
    

  3. Delete the following value names and value data:
    Value name Recommended COM V1.0 setting Default (Authenticated) Value data (COM V1.2 setting) Registry type
    ActivationSecurity N Remove REG_SZ
    PersonalClasses N Remove REG_SZ
  4. Verify the Default Authentication Level and Default Impersonation Level and change if necessary. Use the following procedure:

    Note

    You must have Windows NT Administrator privileges to view and update these settings.
    1. From the Start menu, choose Run...
    2. In the Run dialog box, enter dcomcnfg .
      The system displays the Distributed COM Configuration Properties sheet.
    3. Click the Default Properties tab.
      • The Default Authentication Level list box should display Connect. If it does not, click the list box arrow and select Connect from the list.
      • The Default Impersonation Level list box should display Identity. If it does not, click the list box arrow and select Identity from the list.
  5. You must reboot the Windows NT system for these changes to take effect.

D.1.3 Configuring the OpenVMS System

On OpenVMS systems, you must set or reset the specific OpenVMS Registry values. You can use the Windows NT Registry editor to edit the OpenVMS Registry, or you can use the REG$CP utility. To set the OpenVMS Registry values, use the following procedure:

  1. Select the following OpenVMS Registry key:


    HKEY_LOCAL_MACHINE\Software\Microsoft\Ole 
    

  2. Delete the ActivationSecurity , PersonalClasses , LegacyAuthenticationLevel , and LegacyImpersonationLevel keys. Use the following commands to delete the keys:


    $ MCR REG$CP 
    REG> LIST VALUE HKEY_LOCAL_MACHINE\Software\Microsoft\Ole 
    REG> DELETE VALUE HKEY_LOCAL_MACHINE\Software\Microsoft\
         Ole ActivationSecurity 
    REG> DELETE VALUE HKEY_LOCAL_MACHINE\Software\Microsoft\
         Ole PersonalClasses 
    REG> DELETE VALUE HKEY_LOCAL_MACHINE\Software\Microsoft\
         Ole LegacyAuthenticationLevel 
    REG> DELETE VALUE HKEY_LOCAL_MACHINE\Software\Microsoft\
         Ole LegacyImpersonationLevel 
    REG> LIST VALUE HKEY_LOCAL_MACHINE\Software\Microsoft\Ole 
    REG> EXIT 
    

D.2 Previously Configured Applications on Windows NT

If you configured an application to run with COM Version 1.0 for OpenVMS (unauthenticated COM for OpenVMS ) on Windows NT, you might want to reconfigure the Windows NT settings to take advantage of COM Version 1.2 for OpenVMS (authenticated COM for OpenVMS ).

Under COM Version 1.0 for OpenVMS after you registered a component, the COM for OpenVMS documentation instructed you to check the security properties on that component to ensure that an unauthenticated user can activate the image. Use the following procedure:

  1. From the Windows NT Start menu, choose Run...
  2. In the Run dialog box, enter dcomcnfg .
    The system displays the Distributed COM Configuration Properties sheet.
  3. Select the object by name from the Applications list, then click the Properties... button.
    The system displays the property sheet for the selected object.
  4. From the property sheet, click the Security tab.
    Under COM Version 1.0 for OpenVMS after you set security properties, you had to set the identity of the account to run the application.
    For COM Version 1.2 for OpenVMS, you can set the identity of the account to option 1 or 2.
    Click the Identity tab to display the user account selection. Select The interactive user option.

D.2.1 You Must Repopulate the OpenVMS Registry for COM Version 1.2 for OpenVMS

For COM Version 1.2 for OpenVMS, you must repopulate the OpenVMS Registry to include security settings. Use the DCOM$SETUP command procedure to display the OpenVMS COM Tools menu, and choose option 3.

D.2.2 Changing Application Security Settings in the OpenVMS Registry

COM Version 1.0 for OpenVMS, which shipped with OpenVMS 7.2, did not support NTLM security. As a result, the OpenVMS account through which you (or the system) registered the COM Version 1.0 for OpenVMS COM application was the owner for any OpenVMS Registry keys created as part of the application registration. For example, using COM Version 1.0 for OpenVMS, if you logged into the SYSTEM account and registered the SAMPLE1 application, all SAMPLE1's OpenVMS Registry keys are owned by SYSTEM.

COM Version 1.2 for OpenVMS supports NTLM security. The system now uses the network account to control access to the OpenVMS Registry keys. As a result of this change, previous security settings might prevent a nonprivileged user from accessing an application's registry keys. This means that a nonprivileged user working on an existing application might not be able to unregister or reregister an application.

To prevent this registration lockout, you must change the permission of the application. You can change the permission from either the Windows NT system or the OpenVMS system. Use either of the following procedures:

D.2.2.1 COM Application Registry Keys

A COM application can have several registry keys associated with it. You must be sure to change all keys associated with the application. An application usually registers the following keys:

HKEY_CLASSES_ROOT\CLSID\{guid} and subkeys
HKEY_CLASSES_ROOT\APPID\{guid}
HKEY_CLASSES_ROOT\APPID\filename
HKEY_CLASSES_ROOT\TYPELIB\{typelib guid}
HKEY_CLASSES_ROOT\INTERFACES\{interface guid(s)} and subkeys
HKEY_CLASSES_ROOT\name and subkeys
HKEY_CLASSES_ROOT\version independent name and subkeys

Note

HKEY_CLASSES_ROOT is an alias for HKEY_LOCAL_MACHINE\SOFTWARE\Classes . If you connect to the OpenVMS Registry from Windows NT using Regedt32 and you want to edit the HKEY_CLASSES_ROOT key, edit the HKEY_LOCAL_MACHINE\SOFTWARE\Classes key.


Appendix E
Running COM Version 1.2 for OpenVMS in an Unauthenticated Mode

COM Version 1.2 for OpenVMS includes an option that allows you to run the software in an unauthenticated environment in which NTLM support is not utilized. If you enable this option, only OpenVMS security semantics are used to control COM applications' access to resources. This is essentially the same behavior as in COM Version 1.0 for OpenVMS.

For a list of security differences between an unauthenticated implementation and an authenticated implementation of COM for OpenVMS, see Table 1-1.

Note

When you run COM for OpenVMS in unauthenticated mode, detached processes started by DCOM$RPCSS to run COM servers run in the context of the OpenVMS DCOM$GUEST account. These detached processes have the security attributes of the DCOM$GUEST account.

The following sections describe tasks you must complete in order to run COM for OpenVMS in an unauthenticated environment.

E.1 Installing COM V1.2 for OpenVMS to Run in Unauthenticated Mode

If you are installing COM for OpenVMS for the first time, or if you are upgrading from an earlier version, perform the following steps:

The ACME Server process is started automatically by RPC, but it is not required if you are in unauthenticated mode. To cause the ACME Server process to not start when the system reboots, edit the SYLOGICALS.COM file as follows:


$  DEFINE ACME$TO_BE_STARTED FALSE              ! ACME Server  

E.2 Configuring COM V1.2 for OpenVMS to Run in Unauthenticated Mode

The following section describes how to configure COM Version 1.2 for OpenVMS to run in an unauthenticated environment.

Note

Before you begin configuring COM for OpenVMS for unauthenticated mode, make a note of your current Windows NT system default values and application settings. This makes returning to authenticated mode easier. (For information about how to convert from unauthenticated mode to authenticated mode, see Section E.5.)

E.2.1 Define the DCOM$UNAUTHENTICATED Logical Systemwide

Define DCOM$UNAUTHENTICATED to be Y or YES systemwide. If this logical is undefined or defined as any other value, COM V1.2 for OpenVMS will run in the usual authenticated mode utilizing NTLM security.

To cause COM for OpenVMS to start automatically in unauthenticated mode when the system boots, edit the SYLOGICALS.COM file and add the following line:


$ DEFINE/SYSTEM DCOM$UNAUTHENTICATED YES 

E.2.2 Populate the OpenVMS Registry

Use option 3 in the DCOM$SETUP utility to populate the OpenVMS Registry. (See Section 6.2 for more information.)

Note

If you are upgrading from COM Version 1.1-A for OpenVMS or higher, you do not need to populate the OpenVMS Registry.

E.2.3 Create the DCOM$GUEST Account

Create the OpenVMS DCOM$GUEST account using option 7 in the DCOM$SETUP utility. (See Section 6.2 for more information.)

E.2.4 Create the DCOM$RPCSS Account

Create the OpenVMS DCOM$RPCSS account using option 8 in the DCOM$SETUP utility. (See Section 6.2 for more information.)

E.3 Configuring Windows NT to Interoperate with Unauthenticated COM

For COM objects to interoperate correctly between unauthenticated COM V1.2 for OpenVMS systems and Windows NT, perform the steps described in the following sections. This will configure the COM objects to run without security enabled on the Windows NT system.

E.3.1 Setting the Windows NT Systemwide Authentication Level

On Windows NT systems, set the systemwide authentication level using this procedure:

  1. Run DCOMCNFG on the Windows NT system.
  2. Select the Default Properties tab.
  3. Set the Default Authentication Level to None.

E.3.2 Setting Windows NT Application Security Properties

After a COM application has been registered, check the security properties for that application to ensure that an unauthenticated user can activate the image.

To do this, perform the following steps:

  1. Run DCOMCNFG on the Windows NT system.
  2. Select the application by name.
  3. Click the Properties button.
  4. Click the Security tab.

Set the access permissions (registry value AccessPermission) so that user Everyone is allowed access (Allow access).

Set the launch permissions (registry value LaunchPermission) so that user Everyone is allowed access (Allow access).

Set the configuration permissions so that user Everyone is allowed at least Read access to the Registry values.

E.3.3 Setting the Windows NT Application Security Identity

After you set security permissions, you must set the identity of the account to run the application. To do this, click the Identity tab, and select The interactive user.

E.4 Expected Failures from CLIENTAUTH Sample Program

While you are running COM Version 1.2 for OpenVMS in unauthenticated mode, the Cross-Domain Security example (CLIENTAUTH) does not work because it requires NTLM authentication to be enabled.

E.5 Converting from Unauthenticated Mode to Authenticated Mode

If you performed the steps in this appendix to run COM Version 1.2 for OpenVMS in unauthenticated mode and you want to return to authenticated mode, perform the following steps.

  1. Log in to the SYSTEM account.
  2. Stop the COM server. Use option 5 in the DCOM$SETUP utility. (See Section 6.2 for more information.)
  3. Edit SYLOGICALS.COM with the following changes:
  4. Enter the following command:


      $ DEFINE/SYSTEM DCOM$UNAUTHENTICATED NO 
    

  5. Install, configure, and start Compaq Advanced Server for OpenVMS, if it is not already present.
  6. Repopulate the OpenVMS Registry.
    To do this, use option 3 in the DCOM$SETUP utility. (See Section 6.2 for more information.)
  7. Add the DCOM$RPCSS account to include the Compaq Advanced Server for OpenVMS account and hostmap. Use option 8 in the DCOM$SETUP utility. (See Section 6.2 for more information.)
  8. Reset your Windows NT system default values and application settings to the values that were set before you followed the procedure in Section E.3.
  9. Start the COM server. Use option 4 in the DCOM$SETUP utility. (See Section 6.2 for more information.)
  10. Update or add network accounts. (See Section 5.1 for more information.)


Appendix F
Lists of Differences, APIs, and Interfaces

This appendix contains a list of implementation differences between COM for OpenVMS and Microsoft COM as well as a list of APIs and interfaces provided in this release of COM for OpenVMS.

F.1 Differences between COM for OpenVMS and Microsoft COM

The following sections list important implementation differences between COM for OpenVMS and Microsoft's COM.

F.1.1 Service Control Manager (SCM)

OpenVMS does not provide an equivalent to the Windows NT Service Control Manager. As a result, applications that depend on Server services (such as stop, start, pause, and resume) rely on the OpenVMS features that provide similar functionality (if the features are available).

For example, you would use the OpenVMS site-specific startup and shutdown command procedures to implement automatic starting of services at system startup and automatic shutdown of services at system shutdown. Service APIs such as RegisterServiceCtrlHandler , ChangeServiceConfig , and so on, are not provided on OpenVMS.

F.1.2 Server Application Stack Size

In COM for OpenVMS, server application functions run in the context of server threads. As a result, server functions have a limited stack space of 48 KB. If you require additional space for local variables or structures, you should allocate dynamic memory for local variables or structures.

F.1.3 Use of the "char" Datatype

OpenVMS and Windows NT translate the IDL base data type "char" differently.

OpenVMS translates the data type as MIDL_CHAR, which is defined to be CHAR, and further defined to be "char." The OpenVMS compiler by default takes this to be equivalent to "unsigned char;" in most cases they can be used interchangeably. The two are not the same---C++ treats them as different data types you specify them in class member definitions.

Windows NT translates the data type directly as "unsigned char." This causes conflicts with Visual C++, which treats the "char" datatype as equivalent to "signed char." As in OpenVMS, "char" is not the same as "signed char" in class member definitions.

There are two workarounds to this mismatch:

F.1.4 MIDL Compiler Version

The MIDL compiler supplied with COM for OpenVMS is based on Microsoft's MIDL compiler V3.00.44.

F.1.4.1 The OpenVMS MIDL Compiler

The OpenVMS MIDL compiler is identical to the Microsoft Interface Definition Language (MIDL) compiler V3.00.44 except for the following:

  1. The Microsoft MIDL implementation supports several optimization levels. The OpenVMS MIDL implementation supports only -Oicf . Do not use any other optimization level.
  2. The /cpp_cmd and /cpp_opt switches are not fully functional in the OpenVMS MIDL implementation.
  3. On a Windows NT system, Microsoft MIDL commands, switches, and qualifiers are case sensitive. The OpenVMS MIDL compiler is not case sensitive; all commands, switches, and qualifiers passed to the OpenVMS MIDL compiler are lowercase. As a result, the Microsoft MIDL switches /I and /i are equivalent on OpenVMS.
  4. MIDL-generated files are platform specific.
    You must run MIDL on both platforms. The MIDL output files generated on one platform (OpenVMS or Windows NT) cannot be copied and used on the other platform.
  5. MIDL -w switch
    The Microsoft MIDL compiler allows you to specify either -w or -warn to limit the level of warnings generated by the compiler. The OpenVMS MIDL compiler supports only the -w switch.

F.1.5 Using DCOM$CNFG to Change Application Configuration Permission

Use the Application Security Submenu options 5 and 6 to change the OpenVMS Registry key permissions of some keys associated with an application. Option 5 and 6 affect the security settings of the following keys:

HKEY_CLASSES_ROOT\APPID\{guid}
HKEY_CLASSES_ROOT\CLSID\{guid} and subkeys

On Windows NT systems, the security settings of the subkeys under HKEY_CLASSES_ROOT\CLSID\{guid} are changed only if the existing security settings match the original settings of HKEY_CLASSES_ROOT\APPID\{guid} .

On OpenVMS systems, the settings of the subkeys are changed even if the existing settings do not match the original settings of HKEY_CLASSES_ROOT\APPID\{guid} .

Options 5 and 6 do not change the settings of all keys associated with an application. For example, options 5 and 6 do not affect the following keys:

HKEY_CLASSES_ROOT\APPID\filename
HKEY_CLASSES_ROOT\TYPELIB\{typelib guid}
HKEY_CLASSES_ROOT\INTERFACES\{interface guid(s)} and subkeys.
HKEY_CLASSES_ROOT\name and subkeys
HKEY_CLASSES_ROOT\version independent name and subkeys

To change the security settings of these keys, use the following procedure:

  1. From a Windows NT system, start RegEdt32.
  2. From the Registry menu, choose Select Computer and connect to the OpenVMS system that contains the OpenVMS Registry.
  3. Select the key associated with the application you want to change.
  4. From the Security menu, choose Permissions... and grant the user Full Control.
  5. Repeat the last two steps for each registry key associated with the application (see the list of keys described earlier in this section).

Note

HKEY_CLASSES_ROOT is an alias for HKEY_LOCAL_MACHINE\SOFTWARE\Classes . If you connect to the OpenVMS Registry from Windows NT using Regedt32 and you want to edit the HKEY_CLASSES_ROOT key, edit the HKEY_LOCAL_MACHINE\SOFTWARE\Classes key.

F.2 APIs

APIs that require security support are not supported in COM Version 1.0 for OpenVMS.

The APIs supported in this release are as follows:


BindMoniker 
BstrFromVector 
CLSIDFromProgID 
CLSIDFromString 
CoAddRefServerProcess 
CoCopyProxy 
CoCreateErrorInfo 
CoCreateFreeThreadedMarshaler 
CoCreateGuid 
CoCreateInstance 
CoCreateInstanceEx 
CoDisconnectObject 
CoDosDateTimeToFileTime 
CoFileTimeNow 
CoFileTimeToDosDateTime 
CoFreeAllLibraries 
CoFreeLibrary 
CoFreeUnusedLibraries 
CoGetCallContext 
CoGetClassObject 
CoGetCurrentProcess 
CoGetErrorInfo 
CoGetInstanceFromFile 
CoGetInstanceFromIStorage 
CoGetInterfaceAndReleaseStream 
CoGetMalloc 
CoGetMarshalSizeMax 
CoGetPSClsid 
CoGetStandardMarshal 
CoGetTreatAsClass 
CoImpersonateClient 
CoInitialize 
CoInitializeEx 
CoInitializeSecurity 
CoIsHandlerConnected 
CoLoadLibrary 
CoLockObjectExternal 
CoMarshalInterface 
CoQueryAuthenticationServices 
CoQueryClientBlanket 
CoQueryProxyBlanket 
CoRegisterChannelHook 
CoRegisterClassObject 
CoRegisterMallocSpy 
CoRegisterMessageFilter 
CoRegisterPSClsid 
CoReleaseMarshalData 
CoReleaseServerProcess 
CoResumeClassObjects 
CoRevertToSelf 
CoRevokeClassObject 
CoRevokeMallocSpy 
CoSetErrorInfo 
CoSetProxyBlanket 
CoSuspendClassObjects 
CoTaskMemAlloc 
CoTaskMemFree 
CoTaskMemRealloc 
CoTreatAsClass 
CoUninitialize 
CoUnmarshalInterface 
CreateAntiMoniker 
CreateBindCtx 
CreateClassMoniker 
CreateDataAdviseHolder 
CreateDispTypeInfo 
CreateErrorInfo 
CreateGenericComposite 
CreateILockBytesOnHGlobal 
CreateItemMoniker 
CreatePointerMoniker 
CreateStdDispatch 
CreateStreamOnHGlobal 
CreateTypeLib 
DispGetIDsOfNames 
DispGetParam 
DispInvoke 
DllCanUnloadNow 
DllGetClassObject 
DllGetClassObject 
DllMain 
DllRegisterServer 
DllUnregisterServer 
DosDateTimeToVariantTime 
FreePropVariantArray 
GetActiveObject 
GetAltMonthNames 
GetClassFile 
GetConvertStg 
GetErrorInfo 
GetHGlobalFromILockBytes 
GetHGlobalFromStream 
GetRunningObjectTable 
IIDFromString 
IsEqualCLSID 
IsEqualGUID 
IsEqualIID 
IsValidIid 
IsValidInterface 
IsValidPtrIn 
IsValidPtrOut 
LHashValOfName 
LHashValOfNameSys 
LoadRegTypeLib 
LoadTypeLibEx 
MkParseDisplayName 
MonikerCommonPrefixWith 
MonikerRelativePathTo 
ProgIDFromCLSID 
PropStgNameToFmtId 
PropVariantClear 
PropVariantCopy 
QueryPathOfRegTypeLib 
ReadClassStg 
ReadClassStm 
ReadFmtUserTypeStg 
RegisterActiveObject 
RegisterTypeLib 
ReleaseStgMedium 
RevokeActiveObject 
SafeArrayAccessData 
SafeArrayAllocData 
SafeArrayAllocDescriptor 
SafeArrayCopy 
SafeArrayCopyData 
SafeArrayCreate 
SafeArrayCreateVector 
SafeArrayDestroy 
SafeArrayDestroyData 
SafeArrayDestroyDescriptor 
SafeArrayGetDim 
SafeArrayGetElement 
SafeArrayGetElemsize 
SafeArrayGetLBound 
SafeArrayGetUBound 
SafeArrayLock 
SafeArrayPtrOfIndex 
SafeArrayPutElement 
SafeArrayRedim 
SafeArrayUnaccessData 
SafeArrayUnlock 
SetConvertStg 
SetErrorInfo 
StgCreateDocfile 
StgCreateDocfileOnILockBytes 
StgCreatePropSetStg 
StgCreatePropStg 
StgIsStorageFile 
StgIsStorageILockBytes 
StgOpenPropStg 
StgOpenStorage 
StgOpenStorageOnILockBytes 
StgSetTimes 
StringFromCLSID 
StringFromGUID2 
StringFromIID 
SysAllocString 
SysAllocStringByteLen 
SysAllocStringLen 
SysFreeString 
SysReAllocString 
SysReAllocStringLen 
SysStringByteLen 
SysStringLen 
SystemTimeToVariantTime 
UnRegisterTypeLib 
VarDateFromUdate 
VarNumFromParseNum 
VarParseNumFromStr 
VarUdateFromDate 
VariantChangeType 
VariantChangeTypeEx 
VariantClear 
VariantCopy 
VariantCopyInd 
VariantInit 
VariantTimeToDosDateTime 
VariantTimeToSystemTime 
VectorFromBstr 
WriteClassStg 
WriteClassStm 
WriteFmtUserTypeStg 

F.3 Interfaces

The interfaces supported in this release are as follows:


IAdviseSink 
IBindCtx 
IClassActivator 
IClassFactory 
IConnectionPoint 
IConnectionPointContainer 
ICreateErrorInfo 
ICreateTypeInfo 
ICreateTypeLib 
IDataAdviseHolder 
IDataObject 
IDispatch 
IEnumCallBack 
IEnumConnectionPoints 
IEnumConnections 
IEnumFORMATETC 
IEnumMoniker 
IEnumOLEVerb 
IEnumSTATDATA 
IEnumSTATPROPSETSTG 
IEnumSTATSTG 
IEnumString 
IEnumUnknown 
IEnumVariant 
IErrorInfo 
IExternalConnection 
ILockBytes 
IMalloc 
IMallocSpy 
IMarshal 
IMessageFilter 
IMoniker 
IMultiQI 
IParseDisplayName 
IPersist 
IPersistFile 
IPersistStorage 
IPersistStream 
IPropertySetStorage 
IPropertyStorage 
IRootStorage 
IRunnableObject 
IRunningObjectTable 
IStdMarshalInfo 
IStorage 
IStream 
ISupportErrorInfo 
ITypeComp 
ITypeInfo 
ITypeInfo2 
ITypeLib 
ITypeLib2 
IUnknown 


Previous Next Contents Index