Document revision date: 19 July 1999

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.

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:

• 1 - Applications List
  Lists all applications registered on this machine. For more information about this option, see Section 5.3.1.
• 2 - System-wide Default Properties
  Allows you to set systemwide machine properties. For more information about this option, see Section 5.3.5.
• 3 - System-wide Default Security
  Allows you to set systemwide security parameters. For more information about this option, see Section 5.3.6.

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.

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:

• 1 - Location: Machine to run application
  This option allows you to set or change the machine on which the COM application will run.
  The system displays the Application Location submenu.

  Figure 5-5 Application Location Submenu

  ---

  --------------------------------------------------------- Application Location The following settings allow DCOM to locate the correct computer for this application. If more than one machine is selected then DCOM uses the first available one. Client applications may override these selections. Application name: Inside COM, Chapter 11 Example 1 - Run application on this computer (Yes/No) Current value: Yes 2 - Run application on another computer Current value: Currently Disabled (E to Exit to previous menu) (H for Help) Please enter your choice: ---------------------------------------------------------

  
  The options are as follows:

  • 1 - Run application on this computer
    Indicates whether the application will be run on the local computer. Select the option to change the current value.
  • 2 - Run application on another computer
    Indicates that the application will be run on the specified computer. Select the option and enter one of the following:
    • A valid system name to change the current value.
    • A hyphen (-) to disable the value. This sets the field to "Currently Disabled."
• 2 - Security: Security permissions for application
  This option allows you to set the following security properties:
  • Access permission: allow or deny access to users or groups to access this application.
  • Launch permission: allow or deny access to users or groups to run this application.
  • Configuration permission: identify users or groups who have read, write, or special access to the OpenVMS Registry area that contains information about the application.
  
  The system uses the systemwide default security values unless you specify a different setting.
  The system displays the Application Security submenu.

  Figure 5-6 Application Security Submenu

  ---

  --------------------------------------------------------- Application Security Application name: Inside COM, Chapter 11 Example Current Access permissions: Custom Current Launch permissions: Custom Current Configuration permissions: Default 1 - Use Default Access permission 2 - Edit Custom Access permission 3 - Use Default Launch permission 4 - Edit Custom Launch permission 5 - Use Default Configuration permission 6 - Edit Custom Configuration permission (E to Exit to previous menu) (H for Help) Please enter your choice: ---------------------------------------------------------

  
  The options are as follows:

  • 1 - Use Default Access permission
    Sets the system to the default access permission values.
  • 2 - Edit Custom Access permission
    Displays the Registry Value Permissions submenu. This submenu allows you to view, add, modify, and delete access permission values for this application. For this set of submenus, see Section 5.3.2.
    The ACL Editor starts with the systemwide default values unless you previously set other values.
  • 3 - Use Default Launch permission
    Use the systemwide default launch permission values.
  • 4 - Edit Custom Launch permission
    Displays the Registry Value Permissions submenu. This submenu allows you to view, add, modify, and delete launch permission values for this application. For this set of submenus, see Section 5.3.2.
    The ACL Editor starts with the systemwide default values unless you previously set other values.
  • 5 - Use Default Configuration permission
    Use the systemwide configuration permission values.
  • 6 - Edit Custom Configuration permission
    The system displays the Registry Key Permissions submenu. This submenu allows you to view, add, modify, delete, and configure special access security permissions for this application. For this set of submenus, see Section 5.3.3.

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:

• Index Number...
  To change or delete an access type, enter the corresponding index number. The system displays Edit Registry Value Permissions submenu. See Figure 5-8.
• A to Add to List
  This option displays the Add Registry Value Permissions submenu. This submenu allows you to add a new entry to the OpenVMS Registry value's Access Control List. See Figure 5-9.

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:

• 1 - Delete entry from list
  Delete the entry from the Access Control List. If you delete all entries, you will deny access and launch permissions to everyone for the selected value.
• 2 - Change Access
  Toggle the access type from Allow to Deny or Deny to Allow.

  Figure 5-9 Add Registry Value Permissions Submenu

  ---

  --------------------------------------------------------- Add Registry Value Permissions Application name: Inside COM, Chapter 11 Example Registry Value: LaunchPermission Owner: ROLLO 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:

  • 1 - Add Specific User or Group
    Prompts for a user/group name and type of access. Specify the user name as domain\username or username if the account exists on the primary domain.
  • 2 - Add Everyone
    Allow or Deny Everyone Access/Launch permission to the application.
  • 3 - Add NT AUTHORITY\System
    Allow or Deny System Access/Launch permission to the application.
  • 4 - Add BUILTIN\Administrators
    Allow or Deny Administrator Access/Launch permission to the application.
  
  When a user is part of two or more groups, Deny access takes precedence over Allow access.
• 3 - Identity: User account to use to run application
  This option allows you to run the application server using the security context of the specified user account.
  The system displays the Application Identity submenu. See Section 5.3.4.

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:

• Index Number...
  To change or delete an access type, enter the corresponding index number. The system displays Edit Registry Key Permissions submenu. See Figure 5-11.
• A to Add to List
  This option displays the Add Registry Key Permissions submenu. This submenu allows you to add a new entry to the OpenVMS Registry key's Access Control List. See Figure 5-13.

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:

• 1 - Delete entry from list
  Delete the entry from the security permissions list. If you delete all entries, noone can access the key and only the owner can change the permissions.
• 2 - Allow Full Control
  Allow the user to access, to edit, and to take ownership of the key.
• 3 - Allow Read Access
  Allow the user to read the key but not to save any changes to it.
• 4 - Set/View Special Access
  Displays the Special Access Registry Key Permissions submenu. This submenu allows you to set customized permissions for the selected user or groups. See Figure 5-12.

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:

• 0 - Query Value
  Allow the user to read a value from the key.
• 1 - Set Value
  Allow the user to set one or more values for the key.
• 2 - Create Subkey
  Allow the user to create subkeys on the key.
• 3 - Enumerate Subkeys
  Allow the user to identify the subkeys of the key.
• 4 - Notify
  Allow the user to audit notification events from the key.
• 5 - Create Link
  Allow the user to create a symbolic link in the key.
• 6 - Delete
  Allow the user to delete the key.
• 7 - Write DACL
  Allow the user access to the key to write a discretionary ACL to the key.
• 8 - Write Owner
  Allow the user access to the key to take ownership of the key.
• 9 - Read Control
  Allow the user access to the security information on the key.

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:

• 1 - Add Specific User or Group
  Prompts for a user/group name and type of access. Specify the user name as domain\username or username if the account exists on the primary domain.
• 2 - Add Everyone
  Allow Everyone Full Control or Read Access to the application.
• 3 - Add NT AUTHORITY\System
  Allow System Full Control or Read Access to the application.
• 4 - Add BUILTIN\Administrators
  Allow Administrator Full Control or Read Access to the application.

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:

• 1 - Launching User
  Specifies that the application will run using the security context of the user who started the application. This is the default if NTLM security is available.
• 2 - NTLM Account
  Specifies that the application will run using the security context of the specified NTLM account. If you specify a valid User/Group name, the system prompts you for a password. The system checks that the password matches the password you used to log on (through NTA$LOGON). If the passwords do not match, you can either continue and write this new password to the OpenVMS Registry or reenter a password that matches your logon password.

  Note If you enter a new password, the system does not synchronize the new password with any other password. You must synchronize the passwords manually. You must have the IMPERSONATE privilege for the password to be validated. You must have system write access (SYSPRV or REG$UPDATE) to the OpenVMS Registry to write the password to the database.

• 3 - OpenVMS Username
  Specifies that the application will run using the security context of the specified OpenVMS account. This option is active only when you are using unauthenticated COM for OpenVMS.
• 4 - OpenVMS DCOM Guest Account
  Specifies that the application will run using the security context of the OpenVMS DCOM Guest account. This option is active only when you are using unauthenticated COM for OpenVMS. If you are using unauthenticated COM for OpenVMS, this option is the default.

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:

• 1 - Enable Distributed COM on this computer (Yes/No)
  Enables or disables COM on this computer.
• 2 - Default Authentication Level
  Sets packet-level security on communications between applications. This systemwide default applies to all applications installed on this computer.

  Figure 5-16 Default Authentication Level Submenu

  ---

  ------------------------------------------------------------------ Default Authentication Level The Authentication Level specifies security at the packet level. Current value: Connect 1 - Default 2 - None 3 - Connect 4 - Call 5 - Packet 6 - Packet Integrity (E to Exit to previous menu) (H for Help) Please enter your choice: ------------------------------------------------------------------

  
  Enter a number to select the desired Authentication level. When installed, the system default for the Default Authentication Level is Connect.

• 3 - Default Impersonation Level
  Specifies whether applications can determine who is calling them, and whether the application can perform operations using the client's identity.

  Figure 5-17 Default Impersonation Level Submenu

  ---

  ------------------------------------------------------------------ Default Impersonation Level The Impersonation Level specifies whether applications can determine who is calling them, and whether the application can perform operations using the client's identity. Current value: Identify 1 - Anonymous 2 - Identify 3 - Impersonate (E to Exit to previous menu) (H for Help) Please enter your choice: ------------------------------------------------------------------

  
  Enter a number to select the desired Impersonation level. When installed, the system default for the Default Impersonation Level is Identify.

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:

• 1 - Access Permissions Default:
  Displays the Registry Value Permissions submenu. This submenu allow you to view, add, modify, and delete Access permission values for the systemwide default for all applications.
• 2 - Launch Permissions Default:
  Displays the Registry Value Permissions submenu. This submenu allows you to view, add, modify, and delete Launch Permission Values for the systemwide default for all applications. You must restart the COM for OpenVMS Service Control Manager for the new setting to take effect.
• 3 - Configuration Permissions Default
  Not implemented in this release.

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:

• DLL name
• Switches to register or unregister the components

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.

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.

This chapter explains how to develop COM applications for OpenVMS.

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

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

• OpenVMS style
  Enter the following commands:

  $ SET COMMAND DCOM$LIBRARY:DCOM$GUIDGEN.CLD $ DCOM$GUIDGEN [/FORMAT=value] [/COUNT=value] [/OUTPUT=value]

• UNIX style
  Enter the following command:

  $ mcr dcom$guidgen [-cdghirs?] [-on]

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.

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:

• SYS$SYSTEM:DCOM$MIDL.EXE
  The executable image that takes its arguments (parameters) from the DCL command line.
• SYS$SHARE:DCOM$MIDL_SHR.EXE
  A shareable image library that does the actual work for DCOM$MIDL.EXE.

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"

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.

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:

• /EXCEPTIONS=CLEANUP
  Specify the /EXCEPTIONS=CLEANUP qualifier on C++ commands to enable C++ exceptions.
• /STANDARD=CFRONT
  The C++ compiler supports many different compilation standards. Compaq recommends that you use /STANDARD=CFRONT.
  /STANDARD=CFRONT informs the compiler that it should follow the language conventions defined in the AT&T® cfront implementation. This switch works well with the Wind/U header files because those header files are used by several UNIX platforms in addition to the OpenVMS platform.

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 Wind/U shareable images (to satisfy Win32 dependencies)
• The DCOM OLE32 shareable image (to satisfy references to COM APIs)

The specific link-time dependencies are as follows:

• DCOM$WIN32:WINDU.OPT
• DCOM$LIBRARY:DCOM.OPT

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:

• Include the list of object modules in an options file instead of on the command line.
• Use DCOM$LIBRARY:DCOM.OPT.

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:

• DCOM$WIN32:WINDU.OPT
• DCOM$LIBRARY:DCOM.OPT

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:

• _Windu_ prefix
• Actual entry point name
• A suffix that includes the image name or a portion of the image name, depending on the format of the image name.
  If the image name ends in $SHR (for example, CMPNT$SHR), the suffix is the image name up to and including the dollar sign ($).
  If the image name ends in anything other than $SHR (for example, CMPNT_SHARE), the suffix is the full image name.

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:

• DCOM$WIN32:WINDU.OPT
• SYS$LIBRARY:DCOM$RPCRT4_SHR.EXE

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:

• _Windu_ prefix
• Actual entry point name
• A suffix that includes the image name or a portion of the image name, depending on the format of the image name.
  If the image name ends in $SHR (for example, PROXY$SHR), the suffix is the image name up to and including the dollar sign ($).
  If the image name ends in anything other than $SHR (for example, PROXY_SHARE), the suffix is the full image name.

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)

	privacy and legal statement
6539PRO_002.HTML