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

5.3 Running DCOM$CNFG

DCOM$CNFG is a utility to help COM developers configure and manage COM for OpenVMS applications on OpenVMS. Use the DCOM$CNFG utility to query information and manipulate properties of COM for OpenVMS applications.

To use the DCOM$CNFG utility, choose option 1 from the DCOM$SETUP menu.

Note

Before running the DCOM$CNFG utility, you must:
  • Have OpenVMS Registry Read access to read application properties, and Write access to modify application properties.
  • Ensure that the ACME server is running on the current system. The ACME server must be running to view and change application security properties. For more information, see Table 4-1.
  • Acquire Windows NT security credentials before you can change an application identity. For more information, see Section 12.2.

The system displays the DCOM$CNFG Main menu.

Figure 5-2 DCOM$CNFG Main Menu



--------------------------------------------------------- 
                DCOM$CNFG Main 
 
   1 - Applications List 
   2 - System-wide Default Properties 
   3 - System-wide Default Security 
 
   (E to Exit) 
   (H for Help) 
 
   Enter <CTRL-Z> or 'E' to return to the previous menu at any time 
 
   Please enter your choice: 
--------------------------------------------------------- 

The options are as follows:

5.3.1 The DCOM$CNFG Application List Submenu

To display this submenu, from the DCOM$CNFG Main menu, choose option 1.

The system displays the Applications List submenu.

Figure 5-3 Applications List Submenu



--------------------------------------------------------- 
                Applications List 
 
   Index    Name 
    1      Inside COM, Chapter 11 Example 
    2      application 2
    3      application 3
    .      ... 
    .      ... 
    .      ... 
 
  (E to Exit to previous menu) 
  (H for Help) 
 
  Please enter Index number to select an Application: 
--------------------------------------------------------- 

Enter a number to select an application. You can then view or configure its properties.

This option displays the Application Properties submenu.

Note

The system stores the Application Properties (Location, Security, and Identity) (see Figure 5-4) in a special key in the OpenVMS Registry that is associated with each application. You cannot change the Application Properties until you create this special key using the DCOM$CNFG utility. The DCOM$CNFG utility creates this special key when it discovers a newly registered application. However, the DCOM$CNFG utility creates this key only when a user who has acquired Windows NT security credentials for an account that is a member of the Administrator group runs the DCOM$CNFG utility. For more information about acquiring Windows NT credentials, see Section 12.2).

Use the following procedure to manage the Application Properties:

  1. Register the application.
  2. Do either of the following:
    • Acquire Windows NT security credentials for an account that is a member of the Administrator group and then run DCOM$CNFG.
    • Have a system administrator with the appropriate credentials run DCOM$CNFG.
  3. Run DCOM$CNFG from your own account to manage the properties.

Figure 5-4 Application Properties Submenu



------------------------------------------------------------------ 
               Application Properties 
 
   General Properties of this DCOM Application 
 
   Application name:  Inside COM, Chapter 11 Example 
   Application id:    {0C092C2C-882C-11CF-A6BB-0080C7B2D682} 
   Application type:  local server 
   Local path:        DISK1:[SMITH.DISPATCH_SAMPLE1]CMPNT.EXE 
   Type Library:      {D3011EE1-B997-11CF-A6BB-0080C7B2D682} 
   version: 1.0  DISK1:[SMITH.DISPATCH_SAMPLE1]Server.tlb 
 
   1 - Location    Machine to run application 
   2 - Security    Security permissions for application 
   3 - Identity    User account to use to run application 
 
   (E to Exit to previous menu) 
   (H for Help) 
 
   Please enter Application Property you wish to change: 
------------------------------------------------------------------ 

If the system cannot find the type library file or if the type library is unaccessible, the system displays an error message next to the type library file name.

The options are as follows:

5.3.2 Registry Value Permissions Submenus

To display this submenu:

  1. From the DCOM$CNFG menu, choose option 1.
  2. From the Applications List submenu, choose any application.
  3. From the Application Properties submenu, choose option 2.
  4. From the Application Security submenu, choose option 2 or 4.

Figure 5-7 Registry Value Permissions Submenu



--------------------------------------------------------- 
                Registry Value Permissions 
 
   Application name: Inside COM, Chapter 11 Example 
   Registry Value: LaunchPermission 
   Owner: Administrator 
 
   Index    Name                           Type of Access 
     1      OPENVMS_DCOM\USER1                Deny 
     2      BUILTIN\Administrators            Allow 
     3      Everyone                          Allow 
     4      NT AUTHORITY\SYSTEM               Allow 
     5      OPENVMS_DCOM\USER2                Allow 
 
        (Index Number to Delete or Modify Access) 
        (A to Add to list) 
 
        (E to Exit to previous menu) 
        (H for Help) 
 
        Please enter your choice: 
--------------------------------------------------------- 

The options are as follows:

Figure 5-8 Edit Registry Value Permissions Submenu



--------------------------------------------------------- 
                Edit Registry Value Permissions 
 
        Application name: Inside COM, Chapter 11 Example 
        Registry Value: AccessPermission 
        Owner: Administrator 
 
        Name: OPENVMS_DCOM\USER1 
        Type of Access: Deny 
 
        1 - Delete entry from list 
        2 - Change Access 
 
        (E to Exit to previous menu) 
        (H for Help) 
 
        Please enter your choice: 
--------------------------------------------------------- 

The options are as follows:

5.3.3 Registry Key Permissions Submenus

To display this submenu:

  1. From the DCOM$CNFG menu, choose option 1.
  2. From the Applications List submenu, choose any application.
  3. From the Application Properties submenu, choose option 2.
  4. From the Application Security submenu, choose option 6.

Figure 5-10 Registry Key Permissions Submenu



--------------------------------------------------------- 
                Registry Key Permissions 
 
   Application name: Inside COM, Chapter 11 Example 
   Registry Key: Inside COM, Chapter 11 Example 
   Owner: Administrator 
 
   Index    Name                     Type of Access 
 
   1     BUILTIN\Administrators      Full Control 
   2     NT AUTHORITY\SYSTEM         Full Control 
   3     CREATOR OWNER               Full Control 
   4     Everyone                    Special Access 
   5     OPENVMS_DCOM\USER1          Read 
 
   (Index Number to Delete or Modify Access) 
   (A to Add to list) 
 
   (E to Exit to previous menu) 
   (H for Help) 
 
   Please enter your choice: 
--------------------------------------------------------- 

The options are as follows:

Figure 5-11 Edit Registry Key Permissions Submenu



--------------------------------------------------------- 
                Edit Registry Key Permissions 
 
   Application name: Inside COM, Chapter 11 Example 
   Registry Key: Inside COM, Chapter 11 Example 
   Owner: Administrator 
 
   Name: BUILTIN\Administrators 
   Type of Access: Full Control 
 
   1 - Delete entry from list 
   2 - Allow Full Control 
   3 - Allow Read Access 
   4 - Set/View Special Access 
 
   (E to Exit to previous menu) 
   (H for Help) 
 
   Please enter your choice: 
--------------------------------------------------------- 

The options are as follows:

Figure 5-12 Special Access Registry Key Permissions Submenu



--------------------------------------------------------- 
                Special Access Registry Key Permissions 
 
   Application name: Inside COM, Chapter 11 Example 
   Registry Key: Inside COM, Chapter 11 Example 
 
   Name: Everyone 
 
   Type of Access                          Current Value 
 
   0 - Query Value                           Yes 
   1 - Set Value                             Yes 
   2 - Create Subkey                         Yes 
   3 - Enumerate Subkeys                     Yes 
   4 - Notify                                Yes 
   5 - Create Link                           No 
   6 - Delete                                Yes 
   7 - Write DACL                            No 
   8 - Write Owner                           No 
   9 - Read Control                          Yes 
 
   (E to Exit to previous menu) 
   (H for Help) 
 
   Please enter your choice: 
--------------------------------------------------------- 

The options are as follows:

Figure 5-13 Add Registry Key Permissions Submenu



--------------------------------------------------------- 
                Add Registry Key Permissions 
 
   Application name: Inside COM, Chapter 11 Example 
   Registry Key: Inside COM, Chapter 11 Example 
   Owner: Administrator 
 
   1 - Add Specific User or Group 
   2 - Add Everyone 
   3 - Add NT AUTHORITY\System 
   4 - Add BUILTIN\Administrators 
 
   (E to Exit to previous menu) 
   (H for Help) 
 
   Please enter your choice: 
--------------------------------------------------------- 

The options are as follows:

5.3.4 Application Identity Submenu

To display this submenu:

  1. From the DCOM$CNFG menu, choose option 1.
  2. From the Applications List submenu, choose any application.
  3. From the Application Properties submenu, choose option 3.

The system displays the Application Identity submenu.

Figure 5-14 Application Identity Submenu



--------------------------------------------------------- 
                Application Identity 
 
   Which user account do you want to use to run this application? 
 
   Application name:  Inside COM, Chapter 11 Example 
   Current Identity:  NTLM Account OPENVMS_DCOM\USER2 
 
   1 - Launching User 
   2 - NTLM Account 
   3 - OpenVMS Username 
   4 - OpenVMS DCOM Guest Account 
 
   (E to Exit to previous menu) 
   (H for Help) 
 
   Please enter account you wish to use: 
--------------------------------------------------------- 

The options are as follows:

5.3.5 The DCOM$CNFG System-wide Default Properties Submenu

To display this submenu, from the DCOM$CNFG Main menu, choose option 2.

The system displays the System-wide Default Properties submenu.

Figure 5-15 System-wide Default Properties Submenu



--------------------------------------------------------- 
            System-wide Default Properties 
 
   1 - Enable Distributed COM on this computer (Yes/No) 
              Current value: Yes 
   2 - Default Authentication Level 
   3 - Default Impersonation Level 
 
 
   (E to Exit to previous menu) 
   (H for Help) 
 
   Please enter your choice: 
--------------------------------------------------------- 

The options are as follows:

5.3.6 System-wide Default Security Submenu

To display this submenu, from the DCOM$CNFG Main Menu, choose option 3.

The system displays the System-wide Default Security submenu.

Figure 5-18 System-wide Default Security Submenu



------------------------------------------------------------------ 
                System-wide Default Security 
 
        1 - Access Permissions Default 
        2 - Launch Permissions Default 
        3 - Configuration Permissions Default 
 
        (E to Exit to previous menu) 
        (H for Help) 
 
        Please enter your choice: 
------------------------------------------------------------------ 

The options are as follows:

When you first install the system, by default only Administrator and System accounts have application launch and access permissions. Compaq recommends that you do not change these default settings. Typically you modify an individual application's launch and access security to grant or deny permissions to Everyone, various Groups, or even specific users. Compaq recommends this technique over adjusting the machinewide default security settings that affect all applications.

5.4 Configuring Authentication across Windows NT Domains

You can run a COM application on a system in one domain and have the application authenticated by a system in a second domain.

To configuring authentication across Windows NT domains, you must do the following:

  1. Set up trust relationships between domains.
    For more information, see the "Setting Up External Authentication by a Trusted Domain" section in the Advanced Server for OpenVMS Server Administrator's Guide.
  2. Set up the HostMapDomains parameter on Advanced Server for OpenVMS domains.
    For more information, see the "Setting Up External Authentication by a Trusted Domain" section in the Advanced Server for OpenVMS Server Administrator's Guide.
  3. Set up account hostmap entries between the Windows NT user account and a local OpenVMS user account.
    For more information, see Section 12.3.2.

Example 5-4 provides an example of how you can set up a HostMapDomains file. In this example, there are two domains: DOM_JOE and DOM_JANE. Domain DOM_JANE is running Advanced Server for OpenVMS; Domain DOM_JOE is a Windows NT domain. The commands in Example 5-4 introduce DOM_JANE to DOM_JOE.

Example 5-4 Sample: Setting Up HostMapDomains

SYSJANE$ show sym regutl 
  REGUTL == "$SYS$SYSTEM:PWRK$REGUTL.EXE" 
SYSJANE$ regutl 
REGUTL> SET PARAM /CREATE VMSSERVER HOSTMAPDOMAINS DOM_JOE 
REGUTL> SHOW VALUE * HOSTMAPDOMAINS 
Key: SYSTEM\CurrentControlSet\Services\AdvancedServer\UserServiceParameters 
Value: HostmapDomains 
Type: String 
Current Data: DOM_JOE 

5.5 Registering In-Process Servers: DCOM$REGSVR32 Utility

All COM components (implemented as either an out-of-process server or as an in-process server) must be registered in the OpenVMS Registry before you can use them.

Out-of-process servers, which are implemented as executable programs (.EXE files), usually contain code to register and unregister the components contained within them. The advantage an out-of-process server has over an in-process server is that you can run the executable and automatically create the necessary registry keys.

In-process servers, which are usually implemented as dynamic link libraries (.DLL files) on Windows NT or as shareable images on OpenVMS, also contain code to register and unregister the components within them automatically. However, these in-process servers cannot be run the same way as an executable image because they do not contain a main entry point. As a result, you must manually register the components contained within a .DLL, or create a command procedure to perform the registration.

Microsoft provides the REGSVR32 utility that you can use to register the components contained within a DLL. REGSVR32 takes as a command line argument the following:

When registering a DLL's components, REGSVR32 searches the specified DLL for the DllRegisterServer symbol and, if found, calls it. When unregistering a DLL, REGSVR32 calls DllUnregisterServer. This means that all in-process components that you want to register automatically must include these two entry points in their export files.

To facilitate the registration of components contained within shareable images on OpenVMS systems, Compaq created the DCOM$REGSVR32 utility. The DCOM$REGSVR32 utility does the same things that the Microsoft REGSVR32 utility does. Any shareable images that contain components to be registered must also include the DllRegisterServer and DllUnregisterServer universal symbols in their symbol vectors. Both the DCOM$REGSVR32 and the REGSVR32 utilities use the same command line syntax.

During the COM for OpenVMS installation, the system places the DCOM$REGSVR32.EXE file in the SYS$SYSTEM directory.

Before you use the DCOM$REGSVR32 utility, you must define a symbol that allows the utility to accept foreign command lines. For example:


$ regsvr32 :== $DCOM$REGSVR32 

Alternatively, you can activate the DCOM$REGSVR32 utility as follows:


$ MCR DCOM$REGSVR32 

You can use either method to activate the utility, and register or unregister components contained in shareable images.

To display help for DCOM$REGSVR32, enter the following:


$ regsvr32 -? 

Table 5-1 summarizes the DCOM$REGSVR32 command line options.

Table 5-1 DCOM$REGSVR32 Command Line Options
Switch Use
-?, /? Display help file (this table).
shareable-image-name Register the specified shareable image name.
-u or /u image-name Unregister the specified shareable image name.

Note

The DCOM$REGSVR32 utility requires that the shareable image name contain a full directory specification.

Example 5-5 demonstrates how to register an in-process component (contained within a shareable image) using the DCOM$REGSVR32 utility.

Example 5-5 Registering a Component Using the DCOM$REGSVR32 Utility

$ regsvr32 USER$DISK:[SEYMOUR.DISPATCH_SAMPLE1]CMPNT$SHR.EXE 
Class factory:          Create self. 
DllRegisterServer:      Registering Server DLL 
Creating key CLSID\{0C092C2C-882C-11CF-A6BB-0080C7B2D682} 
Creating key CLSID\{0C092C2C-882C-11CF-A6BB-0080C7B2D682}\InProcServer32 
Creating key CLSID\{0C092C2C-882C-11CF-A6BB-0080C7B2D682}\ProgID 
Creating key CLSID\{0C092C2C-882C-11CF-A6BB-0080C7B2D682}\VersionIndependentProgID 
Creating key CLSID\{0C092C2C-882C-11CF-A6BB-0080C7B2D682}\TypeLib 
Creating key InsideCOM.Chap11 
Creating key InsideCOM.Chap11\CLSID 
Creating key InsideCOM.Chap11\CurVer 
 
Creating key InsideCOM.Chap11.1 
Creating key InsideCOM.Chap11.1\CLSID 
Class factory:          Destroy self. 

Example 5-6 demonstrates how to unregister an in-process component (contained within a shareable image) using the DCOM$REGSVR32 utility.

Example 5-6 Unregistering a Component Using the DCOM$REGSVR32 Utility

$ regsvr32 /u USER$DISK:[SEYMOUR.DISPATCH_SAMPLE1]CMPNT$SHR.EXE 
 
Class factory:          Create self. 
DllUnregisterServer:    Unregistering Server DLL 
Deleting key InProcServer32 
Deleting key ProgID 
Deleting key VersionIndependentProgID 
Deleting key TypeLib 
Deleting key LocalServer32 
Deleting key CLSID\{0C092C2C-882C-11CF-A6BB-0080C7B2D682} 
Deleting key CLSID 
Deleting key CurVer 
Deleting key InsideCOM.Chap11 
Deleting key CLSID 
Deleting key InsideCOM.Chap11.1 
Class factory:          Destroy self. 


Chapter 6
Developing a COM for OpenVMS Application

This chapter explains how to develop COM applications for OpenVMS.

Note

You can find the sample COM applications shown in this chapter in the following directories on the COM for OpenVMS kit:


DCOM$EXAMPLES:[SAMPLE1] 
DCOM$EXAMPLES:[SIMPLE] 
DCOM$EXAMPLES:[DISPATCH_SAMPLE1] 

SAMPLE1 and DISPATCH_SAMPLE1 are taken from Dale Rogerson's book, Inside COM, published by Microsoft Press. This book is a good reference for developing COM applications.

The following sections describe how to create a COM for OpenVMS application.

Note

Building COM for OpenVMS applications places demands on the virtual memory requirements of a process. You should have a minimum page file quota of 100,000 pagelets before building a COM for OpenVMS application. This is a DEC C++ compiler requirement.

6.1 Step 1: Generate Unique Identifiers

Use the DCOM$GUIDGEN utility to generate 16-byte globally unique identifiers (GUIDs). The utility supports both OpenVMS and UNIX styles. For example:

The following table summarizes the GUID format options.
OpenVMS qualifier (value) UNIX switch Use
IDL -i Output GUID in an IDL interface template.
STRUCT -s Output GUID as an initialized C struct.
IMPLEMENT_OLECREATE -c Output GUID in IMPLEMENT_OLECREATE(...) format.
DEFINE_GUID -d Output GUID in DEFINE_GUID(...) format.
GUID_STRUCT -g Output GUID as an initialized static const GUID struct.
REGISTRY_GUID -r Output GUID in registry format.

Note

The last four options in the preceding table are the same as the four options in the Windows NT Guidgen utility.

The following table lists additional options supported by the DCOM$GUIDGEN utility.
OpenVMS qualifier UNIX switch Use
/OUTPUT= filename -o filename Redirect output to a specified file.
/COUNT= number -n number Number of GUIDs to generate.
not available -h, -? Display command option summary.

You can specify more than one format for the same GUID.

6.2 Step 2: Build an Application Using the MIDL Compiler

The following sections describe how to use the MIDL compiler to build an application.

6.2.1 Running the MIDL Compiler

The MIDL compiler consists of the following separate images:

To run MIDL, you must first define a DCL symbol. For example:


    $ midl :== $dcom$midl 
    $ midl -? 
    $ midl -Oicf -idcom$library: example.idl 

The midl -? command displays a list of valid command line arguments. For a list of these arguments, see Appendix A.

6.2.2 Running the MIDL Compiler with DCOM$RUNSHRLIB

The DCOM$MIDL.EXE utility gets its arguments from the DCL foreign command line buffer. DCL foreign commands can have a maximum of 255 characters.

Because of the number of arguments that DCOM$MIDL.EXE can accept, you might exceed this maximum number of characters if you specify a complex MIDL command (for example, a command that contains mixed-case arguments that require quotation marks).

As a workaround, you can use the SYS$SYSTEM:DCOM$RUNSHRLIB.EXE utility. Use the following procedure:

  1. Define the DCL command DCOM$RUNSHRLIB.
    A process that needs to use DCOM$RUNSHRLIB.EXE must first use the OpenVMS DCL Command Definition utility to define the DCL command DCOM$RUNSHRLIB. For example:


      $ SET COMMAND DCOM$LIBRARY:DCOM$RUNSHRLIB.CLD 
    

    DCOM$LIBRARY:DCOM$RUNSHRLIB.CLD defines the DCOM$RUNSHRLIB DCL command. The following table shows the command's parameters.
    Argument Value Required/Optional
    P1 Name of the shareable image library. This can be a logical name, the name of an image in SYS$SHARE:, or a full file specification. Required
    P2 Name of the routine to be called as a C or C++ main() routine with an argc/argv vector. Required
    P3 List of qualifiers in quotation marks. Optional

  2. Define the DCL symbol midl to use DCOM$RUNSHRLIB.EXE to parse the command line and call the DCOM$MIDL_MAIN function in the DCOM$MIDL_SHR shareable image library. For example:


      $ midl :== DCOM$RUNSHRLIB DCOM$MIDL_SHR DCOM$MIDL_MAIN 
    

    The new DCL command MIDL accepts multiple command line arguments inside a single quoted string. If the command becomes too long, you can specify multiple quoted strings, using a comma to separate the strings.
    For example, here is a complex MIDL command that fails:


      $ midl :== $dcom$midl 
      $ midl -Zp8 -Oicf -Os -oldnames -char unsigned - 
         -error allocation -error bounds_check -error stub_data - 
         -ms_ext -c_ext -out [.OBJ] - 
         -I[INC] -I[PROJECT_WIDE_INC] -I[COMMON_INC] -IDCOM$LIBRARY: - 
         -DRMS_DB "-DOpenVMS_Definitions" "-DPermanentProcess" - 
         -header [.obj]example.h -client none -server none example.idl 
      %DCL-W-TKNOVF, command element is too long - shorten 
    

    You can successfully specify this command using DCOM$RUNSHRLIB as follows:


      $ set command dcom$library:dcom$runshrlib.cld 
      $ midl :== DCOM$RUNSHRLIB DCOM$MIDL_SHR DCOM$MIDL_MAIN 
      $ midl "-Zp8 -Oicf -Os -oldnames -char unsigned",- 
         "-error allocation -error bounds_check -error stub_data",- 
         "-ms_ext -c_ext -out [.OBJ]",- 
         "-I[INC] -I[PROJECT_WIDE_INC] -I[COMMON_INC] -IDCOM$LIBRARY:",- 
         "-DRMS_DB -DOpenVMS_Definitions -DPermanentProcess",- 
         "-header [.obj]example.h -client none -server none example.idl" 
    

6.2.3 Required MIDL Switches

When running MIDL on OpenVMS, you must specify the -Oicf MIDL command line switch.

6.2.4 Required Include Directories

MIDL components typically import UNKNWN.IDL, which contains the component definitions for IUnknown and IClassFactory. UNKNWN.IDL and other COM-related IDL and header files are located in DCOM$LIBRARY. To build your component's IDL file, use the following switch:


-IDCOM$LIBRARY: 

6.2.5 Required Header File

The VMS_DCOM.H header file contains macro definitions that enable your COM for OpenVMS application to compile properly with Bristol's Wind/U® Win32 environment. You must include this header file in every source file and header file you create that relies on COM APIs or Win32 APIs. Because the files generated by MIDL rely on parts of the Win32 environment, Compaq has modified the MIDL compiler for OpenVMS to include VMS_DCOM.H in all output files.

6.3 Step 3: Compile the COM Application

The following sections describe how to compile COM for OpenVMS applications.

Note

When you develop COM applications that require Read access to the OpenVMS Registry, you must be sure that you have the REG$LOOKUP identifier. For applications that require Read and Write access to the OpenVMS Registry (either during compilation or at run time), you must have either the REG$UPDATE identifier or the SYSPRV privilege. For more information about OpenVMS Registry privileges, see Section 7.5.1.

6.3.1 Required Macro Definitions

The VMS_DCOM.H file defines several macros used by the Wind/U Win32 environment. An include statement that specifies this header file should be the first noncommented line in any source file (code or header files) that you write. However, this is not always guaranteed to be true for files generated by MIDL. Be sure to always include the following /DEFINE qualifier on all of your C and CXX commands:


 /DEFINE=(UNICODE=1,_WINDU_SOURCE=0X041000,_WIN32_DCOM) 

The UNICODE macro ensures that the wide character variants of Win32 APIs and data structures are enabled when you compile your code. (This macro is also defined in VMS_DCOM.H.) Omitting this macro can lead to compilation failures when building with the Wind/U Win32 environment.

The other two macro definitions are recognized by the Wind/U header files and are required to ensure the proper definition of structures and COM APIs.

6.3.2 Required Include Directories

COM for OpenVMS applications typically require header files that come from DCOM$LIBRARY.

Include the following qualifier on your C and CXX command lines:


 /INCLUDE=DCOM$LIBRARY 

If you already have an /INCLUDE qualifier on your command line, modify the command to include DCOM$LIBRARY.

6.3.3 Required Header File: VMS_DCOM.H

The VMS_DCOM.H header file defines several macros used by the Wind/U header files.

Include this header file as the first noncommented line in your source files (both header files and implementation files).

6.3.4 Required C++ Qualifiers

You must specify the following C++ qualifiers when you build COM for OpenVMS applications:

6.3.5 Required C Qualifiers

There are no qualifiers unique to DEC C that you must specify when you build COM for OpenVMS applications.

6.4 Step 4: Link the COM Application

To build a COM for OpenVMS application, you must build both client and component images. Because you can implement a component as either an in-process component or an out-of-process component, you must build either a shareable image or an executable image, or both. If you are creating a new interface, you must also build a proxy/stub shareable image. The proxy/stub shareable image provides an interface-specific object that packages parameters for that interface in preparation for a remote method call. A proxy runs in the sender's address space and communicates with a corresponding stub in the receiver's address space.

The following sections describe the steps you must follow to link the client, component, and proxy/stub images.

6.4.1 Linking the Client and the Out-of-Process Component

Although you do not need to specify any qualifiers to link the client or the component executable images, you must link both images with the following:

The specific link-time dependencies are as follows:

If you have one or more C++ modules, use the C++ linker (CXXLINK) instead of the standard OpenVMS linker so you can specify the location of your C++ repository (/CXX_REPOSITORY qualifier). For example:


$  CXXLINK/your-specific-linker-qualifiers list-of-object-modules, -
_$ DCOM$WIN32:WINDU.OPT/OPTIONS, DCOM$LIBRARY:DCOM.OPT/OPTIONS -
_$ application.OPT/OPTIONS /REPOSITORY=[.CXX_REPOSITORY]

Other ways of including the options file are as follows:

6.4.2 Linking the In-Process Component Shareable Image

The component in-process shareable image dependency list differs slightly from that of the client and component executables. The specific link-time dependencies are as follows:

6.4.2.1 Creating a Symbol Vector

Linking the in-process component shareable image requires that you create a symbol vector for the entry points that COM for OpenVMS expects to call within the shareable image. The Win32 run-time environment enforces a naming standard on the DllMain entry point, which must contain the following:

For example, a component shareable image with the name CMPNT$SHR would define the symbol vector using the following options file:


! 
! The list of symbols exported by CMPNT$SHR.EXE. 
! 
SYMBOL_VECTOR=(- 
        _WindU_DllMain_CMPNT$/DllMain  = PROCEDURE,- 
        DllGetClassObject               = PROCEDURE,- 
        DllCanUnloadNow                 = PROCEDURE,- 
        DllRegisterServer               = PROCEDURE,- 
        DllUnregisterServer             = PROCEDURE) 

A component shareable image with the name CMPNT_SHARE would define the symbol vector using the following options file:


! 
! The list of symbols exported by CMPNT_SHARE.EXE. 
! 
SYMBOL_VECTOR=(- 
        _WindU_DllMain_CMPNT_SHARE/DllMain  = PROCEDURE,- 
        DllGetClassObject               = PROCEDURE,- 
        DllCanUnloadNow                 = PROCEDURE,- 
        DllRegisterServer               = PROCEDURE,- 
        DllUnregisterServer             = PROCEDURE) 

6.4.3 Linking the Proxy/Stub Shareable Image

The proxy/stub shareable image dependency list differs slightly from that of the client and component executables. The specific link-time dependencies are as follows:

6.4.3.1 Creating a Symbol Vector

Linking the proxy/stub shareable image is more involved because you must create a symbol vector for the entry points that COM for OpenVMS expects to call within the shareable image. The Win32 run-time environment enforces a naming standard on the DllMain entry point, which must contain the following:

For example, a proxy/stub shareable image with the name PROXY$SHR would define the symbol vector using the following options file:


! 
! RPC Shareable Image 
! 
 SYS$LIBRARY:DCOM$RPCRT4_SHR.EXE/SHARE 
! 
! 
! The list of symbols exported by PROXY$SHR.EXE. 
! 
SYMBOL_VECTOR=(- 
        _Windu_DllMain_PROXY$/DllMain   = PROCEDURE,- 
        DllGetClassObject               = PROCEDURE,- 
        DllCanUnloadNow                 = PROCEDURE,- 
        GetProxyDllInfo                 = PROCEDURE,- 
        DllRegisterServer               = PROCEDURE,- 
        DllUnregisterServer             = PROCEDURE) 

A proxy/stub shareable image with the name PROXY_SHARE would define the symbol vector using the following options file:


! 
! RPC Shareable Image 
! 
 SYS$LIBRARY:DCOM$RPCRT4_SHR.EXE/SHARE 
! 
! 
! The list of symbols exported by PROXY_SHARE.EXE. 
! 
SYMBOL_VECTOR=(- 
        _Windu_DllMain_PROXY_SHARE/DllMain = PROCEDURE,- 
        DllGetClassObject                  = PROCEDURE,- 
        DllCanUnloadNow                    = PROCEDURE,- 
        GetProxyDllInfo                    = PROCEDURE,- 
        DllRegisterServer                  = PROCEDURE,- 
        DllUnregisterServer                = PROCEDURE) 


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_002.HTML