Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS Connectivity Developer Guide


Previous Contents Index

Part 5
Appendixes

This part contains reference information about COM for OpenVMS and the OpenVMS Registry.

The appendixes provide information about the MIDL compiler, troubleshooting tips, COM sample code, and APIs and interfaces.

This part also includes coupons for related COM books, a glossary, and a list of acronyms.


Appendix A
MIDL Compiler Options

A.1 Mode

Switch Use
/ms_ext Microsoft extensions to the IDL language (default)
/c_ext Allow Microsoft C extensions in the IDL file (default)
/osf OSF mode - disables /ms_ext and /c_ext options
/app_config Allow selected ACF attributes in the IDL file
/mktyplib203 MKTYPLIB Version 2.03 compatibility mode

A.2 Input

Switch Use
/acf filename Specify the attribute configuration file
/I directory-list Specify one or more directories for include path
/no_def_idir Ignore the current and the INCLUDE directories

A.3 Output File Generation

Switch Use
/client none Do not generate client files
/client stub Generate client stub file only
/out directory Specify destination directory for output files
/server none Generate no server files
/server stub Generate server stub file only
/syntax_check Check syntax only; do not generate output files
/Zs Check syntax only; do not generate output files
/old Generate old format type libraries
/new Generate new format type libraries

A.4 Output File Names

Switch Use
/cstub filename Specify client stub file name
/dlldata filename Specify dlldata file name
/h filename Specify header file name
/header filename Specify header file name
/iid filename Specify interface UUID file name
/proxy filename Specify proxy file name
/sstub filename Specify server stub file name
/tlb filename Specify type library file name

A.5 C Compiler and Preprocessor Options

Switch Use
/cpp_cmd cmd_line Specify name of C preprocessor
/cpp_opt options Specify additional C preprocessor options
/D name[=def] Pass #define name, optional value to C preprocessor
/no_cpp Turn off the C preprocessing option
/nocpp Turn off the C preprocessing option
/U name Remove any previous definition (undefine)

A.6 Environment

Switch Use
/char signed C compiler default char type is signed
/char unsigned C compiler default char type is unsigned
/char ascii7 Char values limited to 0-127
/dos Target environment is MS-DOS client
/env dos Target environment is MS-DOS client
/env mac Target environment is Apple Macintosh
/env powermac Target environment is Apple PowerMac
/env win16 Target environment is Microsoft Windows 16-bit (Win 3.x)
/env win32 Target environment is Microsoft Windows 32-bit (NT)
/mac Target environment is Apple Macintosh
/ms_union Use Midl 1.0 non-DCE wire layout for non-encapsulated unions
/oldnames Do not mangle version number into names
/powermac Target environment is Apple PowerMac
/rpcss Automatically activate rpc_sm_enable_allocate
/use_epv Generate server side application calls via entry-pt vector
/no_default_epv Do not generate a default entry-point vector
/prefix client str Add "str" prefix to client-side entry points
/prefix server str Add "str" prefix to server-side manager routines
/prefix switch str Add "str" prefix to switch routine prototypes
/prefix all str Add "str" prefix to all routines
/win16 Target environment is Microsoft Windows 16-bit (Win 3.x)
/win32 Target environment is Microsoft Windows 32-bit (NT)

A.7 Error and Warning Messages

Switch Use
/error none Turn off all error checking options
/error allocation Check for out of memory errors
/error bounds_check Check size vs transmission length specification
/error enum Check enum values to be in allowable range
/error ref Check ref pointers to be non-null
/error stub_data Emit additional check for server side stub data validity
/no_warn Suppress compiler warning messages

A.8 Optimization

Switch Use
/align {1|2|4|8} Designate packing level of structures
/pack {1|2|4|8} Designate packing level of structures
/Zp{1|2|4|8} Designate packing level of structures
/Oi Generate fully interpreted stubs
/Oic Generate fully interpreted stubs for standard interfaces and stubless proxies for object interfaces as of NT 3.51 release
/Oicf Generate fully interpreted stubs with extensions and stubless proxies for object interfaces as of NT 4.0 release
/Os Generate inline stubs
/hookole Generate HookOle debug info for local object interfaces

A.9 Miscellaneous

Switch Use
@response_file Accept input from a response file
/? Display a list of MIDL compiler switches
/confirm Display options without compiling MIDL source
/help Display a list of MIDL compiler switches
/nologo Suppress displaying of the banner lines
/o filename Redirects output from screen to a file
/W{0|1|2|3|4} Specify warning level 0-4 (default = 1)
/WX Report warnings at specified /W level as errors


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 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 Advanced Server for OpenVMS process.
  3. If the PWRK$ACME_SERVER logical name is defined correctly, verify that the 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:


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 sample 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 sample 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 12.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 CMPNT$SHR.EXE and CMPNT.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 CMPNT.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 CMPNT.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.

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 
 CMPNT.CXX 
 CMPNT.DEF 
 GUIDS.CXX 
 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 CMPNT.DLL, PROXY.DLL, and CMPNT.EXE as follows:


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

To unregister the application, enter the following:


   regsvr32 -u Cmpnt.dll 
   regsvr32 -u Proxy.dll 
   Cmpnt /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.1.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 sample 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 sample 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 CMPNT$SHR.EXE and CMPNT.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 CMPNT.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 CMPNT.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.

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 
 CMPNT.CXX 
 CMPNT.DEF 
 MAKE-ONE. 
 MAKEFILE.BAT 
 REGISTRY.CXX 
 REGISTRY.H 
 SERVER.IDL 

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 CMPNT.DLL, PROXY.DLL, and CMPNT.EXE as follows:


   regsvr32 -s Cmpnt.dll 
   Cmpnt /RegServer 

To unregister the application, enter the following:


   regsvr32 -u Cmpnt.dll 
   Cmpnt /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.


Appendix D
Upgrading to COM Version 1.1 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:

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.1 for OpenVMS now supports 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 Version 1.0 for OpenVMS setting Default (Authenticated) Value data (COM Version 1.1 for OpenVMS 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.1 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.1 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.1 for OpenVMS

For COM Version 1.1 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.1 for OpenVMS, which ships with OpenVMS 7.2-1, now support NTLM security. The system now uses the network account to control access to the OpenVMS Registry keys. As a result if 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:

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.


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
6539PRO_007.HTML