Document revision date: 15 July 2002

This chapter describes how to configure your OpenVMS system (and, optionally, your Windows NT system) to develop and deploy COM applications. It describes the following COM for OpenVMS utilities:

• The DCOM$SETUP utility, which helps a system manager configure the COM for OpenVMS system environment.
• The DCOM$CNFG utility, which helps an application developer configure and examine COM applications.
• The DCOM$REGSVR32 utility, which allows an application developer to register and unregister in-process server applications.

This chapter also includes information about configuring OpenVMS and Windows NT systems to interoperate.

DCOM$SETUP is a collection of tools to help a system manager configure the COM for OpenVMS system environment.

DCOM$SETUP Conventions and Requirements

• For Yes/No questions, you can enter any one of the following:
  • YES or NO
  • Y or N
  • [Return] (to accept the default value)
• Some DCOM$SETUP options require system manager privileges and OpenVMS Registry access.

To run DCOM$SETUP , enter @SYS$STARTUP:DCOM$SETUP at the OpenVMS system prompt.

The system displays the OpenVMS COM Tools menu.

Figure 6-1 DCOM$SETUP OpenVMS COM Tools Menu

--------------------------------------------------------- OpenVMS COM Tools 1) DCOMCNFG, COM Configuration Properties 2) GUIDGEN, Globally Unique Identifier Generator 3) Populate the Registry database for COM 4) Start the COM server 5) Stop the COM server 6) Register a COM application 7) Create the DCOM$GUEST account and directory 8) Configure the DCOM$RPCSS accounts H) Help E) Exit Please enter your choice: ---------------------------------------------------------

To choose an option, enter the option number. The options are as follows:

• 1) DCOMCNFG, COM Configuration Properties
  Use to query information and manipulate properties of COM for OpenVMS applications. For more information, see Section 6.3.
• 2) GUIDGEN, Globally Unique Identifier Generator
  Generate CLSIDs (class IDs) (or GUIDs [globally unique identifiers]) in various formats (for example, the OpenVMS Registry or Windows NT Registry format). The CLSID tags each application with a unique identifier.
  This version of DCOM$SETUP generates GUIDs in OpenVMS Registry and Windows NT Registry formats only. For a discussion of other formats, see Section 7.1.
• 3) Populate the Registry database for COM
  Set up the OpenVMS Registry database. COM for OpenVMS requires that specific keys and values be added to the OpenVMS Registry database. You must have both write access to the OpenVMS Registry and Windows NT Administrator privileges.
• 4) Start the COM server
  Start the COM for OpenVMS Server Control Manager server ( DCOM$RPCSS ). DCOM$SETUP calls the SYS$STARTUP:DCOM$STARTUP procedure to start the server. For more information, see Section 6.2.2.
• 5) Stop the COM server
  Shut down the COM for OpenVMS Service Control Manager server ( DCOM$RPCSS ). DCOM$SETUP calls the SYS$STARTUP:DCOM$SHUTDOWN procedure to stop the server. For more information, see Section 6.2.2.
• 6) Register a COM application
  Register a COM for OpenVMS server application. You can register the following types of servers:
  • In-process server
    When you register an in-process server, the system prompts you for the server's location.
  • Local server or out-of-process server
    When you register a local server or out-of-process server, the system prompts you for the following information:
    • Full path information (location of the server)
      This is a required value. Use the following syntax: device::[directory]file-name.ext
    • Application title
      This is an optional value. If you do not supply a title, the system uses a default title.
    • CLSID (GUID)
      This is a required value. If the server does not have a CLSID, the system generates one automatically. For more information about CLSIDs and LocalServer32, see Section 7.5.1.
    
    After you complete the registration process, the system generates the following files:
    1. A Windows NT Registry file ( server-name.REG_NT ) that you can use to register the application on a Windows NT system.
    2. An OpenVMS command procedure ( server-name.REG_VMS ) that you can use to register the server on an OpenVMS system.
    
    When you use these files on other systems, you must modify the path statement to point to the server's current location. For more information, see Section 6.2.3.
• 7) Create the DCOM$GUEST account and directory
  You must create the DCOM$GUEST account before you can use COM for OpenVMS without NTLM authentication.
• 8) Configure the DCOM$RPCSS accounts
  Configure and create the DCOM$RPCSS Compaq Advanced Server for OpenVMS user and SYSUAF accounts. The COM for OpenVMS Service Control Manager ( DCOM$RPCSS ) requires these accounts for authentication. For more information, see Section 6.2.1.
• H) Help
  Display help about each menu option.
• E) Exit
  Exit the menu.

To display these functions, choose option 8 from the OpenVMS COM Tools menu. The system displays the following:

--------------------------------------------------------- Configure the COM for OpenVMS Service Control Manager (DCOM$RPCSS) accounts 1) Create the DCOM$RPCSS account in both the SYSUAF database and the Advanced Server for OpenVMS SAM database. The password you specify for the new DCOM$RPCSS user is stored in a protected file. 2) Update the DCOM$RPCSS user password in the COM for OpenVMS Service Control Manager password file. E) Exit Please enter your choice: ---------------------------------------------------------

Enter one of the following:

• 1) Create the DCOM$RPCSS account . . .
  This option creates the DCOM$RPCSS account in both the SYSUAF database and the Compaq Advanced Server for OpenVMS SAM database.
  The password you specify for the DCOM$RPCSS user is stored in a protected file that the COM for OpenVMS Service Control Manager uses to log into the NTLM network and obtain a Windows NT identity.

  Note The system creates this account in the Compaq Advanced Server for OpenVMS database with a password that will not expire. To change this behavior (that is, modify the account so that the password expires according to the Compaq Advanced Server for OpenVMS User Policy), use the following procedure: Run the Compaq Advanced Server for OpenVMS ADMIN utility. Log into the Administrator account. Issue the following ADMIN command: ADMIN> MODIFY USER DCOM$RPCSS/FLAG=NODISPWDEXP To determine the maximum password age in the Compaq Advanced Server for OpenVMS User Policy, enter the following ADMIN command: ADMIN> SHOW ACCOUNT POLICY If you change the Compaq Advanced Server for OpenVMS password of the DCOM$RPCSS account, you must update the password in the COM for OpenVMS Service Control Manager password file. (See option 2 [Update the DCOM$RPCSS user password].)

  
  Use the following procedure:
  1. Enter 1 .
     The system displays the following:

     To create a new account, you must be logged on to an existing Advanced Server for OpenVMS account that is capable of adding new users. Enter Y[ES] to log on to this account:

     
     You must belong to the PATHWORKS administrator group to create this account.

  2. Enter Y .
     The system prompts you to log on. The password is not displayed as you enter it.

     Enter username: JOSEPHM Password: Confirm password:

     
     The system prompts you to enter a new password, and then asks you to confirm the password. The password is not displayed as you enter it.

     Enter the new DCOM$RPCSS password. Enter password: Confirm password:

     
     The system uses this password for both the SYSUAF account (DCOM$RPCSS) and the PATHWORKS user account (DCOM$RPCSS). The system stores this password in the COM for OpenVMS Service Control Manager password file.
     The system displays the following account creation information:

     %PWRK-S-USERADD, user "DCOM$RPCSS" added to domain "DCOM1_DOMAIN" Username: DCOM$RPCSS Owner: COM Account: UIC: [37776,1] ([DCOM$RPCSS]) CLI: DCL Tables: DCLTABLES Default: SYS$SYSDEVICE:[DCOM$RPCSS] LGICMD: Flags: ExtAuth Primary days: Mon Tue Wed Thu Fri Secondary days: Sat Sun No access restrictions Expiration: (none) Pwdminimum: 6 Login Fails: 0 Pwdlifetime: (none) Pwdchange: (pre-expired) Last Login: (none) (interactive), (none) (non-interactive) Maxjobs: 0 Fillm: 100 Bytlm: 64000 Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0 Maxdetach: 0 BIOlm: 150 JTquota: 4096 Prclm: 8 DIOlm: 150 WSdef: 1024 Prio: 4 ASTlm: 250 WSquo: 4000 Queprio: 4 TQElm: 10 WSextent: 8000 CPU: (none) Enqlm: 2000 Pgflquo: 130000 Authorized Privileges: NETMBX TMPMBX Default Privileges: NETMBX TMPMBX %PWRK-S-HOSTMAPADD, user "DCOM$RPCSS" mapped to host user "DCOM$RPCSS" Press RETURN to continue:

• 2) Update the DCOM$RPCSS user password . . .
  If you change the DCOM$RPCSS user password in the Compaq Advanced Server for OpenVMS SAM database, you must also update the password in the COM for OpenVMS Service Control Manager password file.
  Use the following procedure:
  1. Enter 2 .
     The system displays the following:

     Enter the new DCOM$RPCSS password. Enter password: Confirm password:

  2. Enter the new password and confirm the password.
• E) Exit
  Exit the menu.

COM for OpenVMS requires that the COM server process ( DCOM$RPCSS ) always be running. The DCOM$RPCSS process on OpenVMS provides the same functions for the COM run-time environment that the RPCSS process provides on Microsoft Windows NT, including the following:

• Build and maintain the list of server objects running on the system.
• Build and maintain a cache of known applications as defined in the registry. This cache improves COM performance.
• Start a server as a detached process whenever a client requests a connection to a server object that is not currently running.
• Communicate with the RPCSS process on remote Windows NT systems or the DCOM$RPCSS process on OpenVMS systems to locate or start remote server objects.

To start DCOM$RPCSS , either use DCOM$SETUP option 4 ("Start") (see Section 6.2) or call the COM for OpenVMS startup procedure directly from SYS$STARTUP:DCOM$STARTUP . See Section 4.11 for information on starting COM for OpenVMS.

To stop DCOM$RPCSS on your system, either use the DCOM$SETUP option 5 ("Stop") (see Section 6.2) or call the COM for OpenVMS shutdown procedure directly from SYS$STARTUP:DCOM$SHUTDOWN . See Section 4.12 for information on shutting down COM for OpenVMS.

6.2.3 Registering an Application

The following example shows how to register the COM for OpenVMS "Simple" application included on the COM for OpenVMS kit. You can use the resulting Windows NT file to register the server on a Windows NT system as long as the application is available on your Windows NT system.

To build the "Simple" application on a Windows NT system, see and execute the instructions in the README-SIMPLE.TXT file in DCOM$EXAMPLES:[SIMPLE] .

Use the following procedure:

1. From the DCOM$SETUP menu, enter 6 or REGISTER .
2. Answer the questions as follows:

   Note The "Simple" application already has a CLSID.

   Example 6-1 Sample" Simple" Application Registration on OpenVMS

   Enter server type (1. In-Proc 2. Out-Proc): 2 [Return] Enter Local Path (device:[directory]filename.ext): DKA0:[SMITH]SSERVER.EXE [Return] Enter Application Name (<RETURN> to assign default): COM Simple Server [Return] Does the server have a CLSid {GUID} (Yes/No) [N]: Y [Return] Enter the CLSid (i.e. {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}: {5e9ddec7-5767-11cf-beab-00aa006c3606} [Return] Verify Application Information: Application Name: COM SIMPLE SERVER Local Path: DKA0:[SMITH]SSERVER.EXE Application ID: {5E9DDEC7-5767-11CF-BEAB-00AA006C3606} Is the information correct (Yes/No) [Y]: [Return] Register application (Yes/No)? [Y]: [Return] SETUP-I-NEWFILES, The following files have been created: DKA0:[SMITH]SSERVER.REG_NT DKA0:[SMITH]SSERVER.REG_VMS SETUP-I-SRVIN, Server has been registered Press RETURN to continue: [Return]

To register the "Simple" application on a Windows NT system, use the following procedure:

1. Copy all the files in the DCOM$EXAMPLES:[SIMPLE] directory to your Windows NT system.
2. Rename SSERVER.REG_NT to SSERVER.REG .
3. Edit the file to point to the local server path.
   For example, replace DEVICE:\SSERVER with C:\SSERVER .
4. Run the Install.bat program to add the necessary keys to the Windows NT registry.

Example 6-2 shows the contents of SSERVER.REG_NT .

Example 6-2 Contents of SSERVER.REG_NT

REGEDIT HKEY_CLASSES_ROOT\CLSID\{5E9DDEC7-5767-11CF-BEAB-00AA006C3606}\ = DCOM server application SSERVER HKEY_CLASSES_ROOT\CLSID\{5E9DDEC7-5767-11CF-BEAB-00AA006C3606}\LaunchPermission = Y HKEY_CLASSES_ROOT\CLSID\{5E9DDEC7-5767-11CF-BEAB-00AA006C3606}\LocalServer32 = DEVICE:\SSERVER

To reregister the "Simple" application on an OpenVMS system, enter the following command at the system prompt:

$ @SSERVER.REG_VMS

Example 6-3 shows the contents of the SSERVER.REG_VMS command procedure:

Example 6-3 Contents of SSERVER.REG_VMS

$ Set noon $ regcp := $regcp $ crekey := $regcp create key $ creval := $regcp create value $ modval := $regcp modify value $ lisval := $regcp list value $ crekey HKEY_CLASSES_ROOT\CLSID\{5E9DDEC7-5767-11CF-BEAB-00AA006C3606} $ creval HKEY_CLASSES_ROOT\CLSID\{5E9DDEC7-5767-11CF-BEAB-00AA006C3606} - /data="DCOM server application SSERVER" /type=sz $ creval HKEY_CLASSES_ROOT\CLSID\{5E9DDEC7-5767-11CF-BEAB-00AA006C3606}/name="AppID" - /data="{5E9DDEC7-5767-11CF-BEAB-00AA006C3606}" /type=sz $ crekey HKEY_CLASSES_ROOT\CLSID\{5E9DDEC7-5767-11CF-BEAB-00AA006C3606}\LaunchPermission $ creval HKEY_CLASSES_ROOT\CLSID\{5E9DDEC7-5767-11CF-BEAB-00AA006C3606}\LaunchPermission - /data="Y" /type=sz $ crekey HKEY_CLASSES_ROOT\CLSID\{5E9DDEC7-5767-11CF-BEAB-00AA006C3606}\LocalServer32 $ creval HKEY_CLASSES_ROOT\CLSID\{5E9DDEC7-5767-11CF-BEAB-00AA006C3606}\LocalServer32 - /data="DKA0::[SMITH]SSERVER.EXE" /type=sz $

6.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.

The system displays the DCOM$CNFG Main menu.

Figure 6-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 6.3.1.
• 2 - System-wide Default Properties
  Allows you to set systemwide machine properties. For more information about this option, see Section 6.3.5.
• 3 - System-wide Default Security
  Allows you to set systemwide security parameters. For more information about this option, see Section 6.3.6.

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

The system displays the Applications List submenu.

Figure 6-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 6-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 6-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.
• 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 6.3.4.

	privacy and legal statement
6539PRO_005.HTML