Updated: 26 May 1998

OpenVMS Connectivity Developer Guide

Contains DCOM for OpenVMS and OpenVMS Registry information

For FT2


          Digital Equipment Corporation 
 
             PROPRIETARY INFORMATION 
 
      Furnished for Field Test Purposes Only 
   
   The information contained herein is furnished 
   in confidence and is subject to the terms and 
   conditions of a License Agreement for field 
   testing DIGITAL software. 


May 1998

Revision/Update Information: This is a new manual.

Software Version: OpenVMS Alpha Version 7.1
OpenVMS Alpha Version 7.2 FT1 or FT2
Microsoft Windows NT 4.0




Digital Equipment Corporation Maynard, Massachusetts


May 1998

Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from DIGITAL or an authorized sublicensor.

DIGITAL conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

© Digital Equipment Corporation 1998. All rights reserved.

This product includes software licensed from Microsoft Corporation.
Copyright © Microsoft Corporation, 1991-1997. All rights reserved.

This product includes software licensed from Bristol Technology, Inc.
Copyright © Bristol Technology, Inc, 1990-1997. All rights reserved.

The following are trademarks of Digital Equipment Corporation: Alpha, DECdirect, DIGITAL, DIGITAL UNIX, OpenVMS, POLYCENTER, VAX, VAXcluster, VMS, and the DIGITAL logo.

The following are third-party trademarks:

All other trademarks and registered trademarks are the property of their respective holders.

Sample COM code that appears in this document is from Dale Rogerson's book, Inside COM (Microsoft Press, 1997), and is used with the publisher's permission.

ZK6539

The DIGITAL OpenVMS documentation set is available on CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2k.

26-MAY-1998 12:09:19.24

Contents Index


Preface

Intended Audience

This document is designed for DCOM for OpenVMS developers: those who are wrappering existing OpenVMS applications or data, as well as those who are creating new COM applications for OpenVMS systems.

This document is not intended as an introduction to COM. It assumes that readers are already familiar with object-oriented (OO) concepts and COM development techniques. The document does provide pointers to online information about COM and recommends other books about COM and OO development.

Document Structure

This document contains all the information you need to develop DCOM for OpenVMS applications. The document is divided into the following sections:

Related Documents

For additional information on the Open Systems Software Group (OSSG) products and services, access the DIGITAL OpenVMS World Wide Web site with the following address:


http://www.openvms.digital.com 

Reader's Comments

DIGITAL welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:
Internet openvmsdoc@zko.mts.dec.com
Fax 603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following World Wide Web address to order additional documentation:


        http://www.openvms.digital.com:81/ 

If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

Conventions

In this manual, any reference to OpenVMS is synonymous with DIGITAL OpenVMS.

VMScluster systems are now referred to as OpenVMS Cluster systems. Unless otherwise specified, references to OpenVMS Clusters or clusters in this document are synonymous with VMSclusters.

In this manual, every use of DECwindows and DECwindows Motif refers to DECwindows Motif for OpenVMS software.

The following conventions are also used in this manual:
Ctrl/ x A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 x A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
[Return] In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)

In the HTML version of this document, this convention appears as brackets, rather than a box.

... A horizontal ellipsis in examples indicates one of the following possibilities:
  • Additional optional arguments in a statement have been omitted.
  • The preceding item or items can be repeated one or more times.
  • Additional parameters, values, or other information can be entered.
.
.
.
A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( ) In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you choose more than one.
[ ] In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
[|] In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.
{ } In command format descriptions, braces indicate required elements; you must choose one of the options listed.
text style This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.

In the HTML version of this document, this convention appears as italic text.

italic text Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).
UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
Monospace type

Monospace type indicates code examples and interactive screen displays.

In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.

- A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.


Chapter 1
DCOM for OpenVMS FT2 Release Notes

1.1 Contents of the DCOM for OpenVMS Field Test 2 Kit

This release of DCOM for OpenVMS is a nonsecure implementation---that is, DCOM for OpenVMS makes no security checks to authenticate or validate client requests within a server. Do not use this field test release in an environment that requires secure COM. A future field test update will add security support.

The Field Test 2 Kit contains the following:

1.2 Prerequisites

The following software is required:

1.3 Release Notes

The following information applies to this release:

1.3.1 Upgrading from DCOM for OpenVMS FT1 to DCOM for OpenVMS FT2

If you have DCOM for OpenVMS FT1 installed and you want to upgrade to DCOM for OpenVMS FT2 using OpenVMS Version 7.2 FT2, you must do the following:

  1. Before installing the DCOM for OpenVMS FT2 kit, you must:
  2. Install DCOM for OpenVMS FT2 as described in Chapter 3. The system displays a message saying that DCOM for OpenVMS FT1 (G1.0) is being removed.
  3. Repopulate the OpenVMS Registry database using the DCOM$REGISTRY_KEYS.COM command file provided with DCOM for OpenVMS FT2. You can find this command file in the SYS4MANAGER directory.
    When you execute the DCOM$REGISTRY_KEYS.COM command file, the system prompts you to overwrite the current OpenVMS Registry values. Answer Yes to this question. The command file will not overwrite or invalidate any application data you have stored in the OpenVMS Registry. You will see a number of warning messages indicating that a value already exists; you can ignore these warning messages.

1.3.2 DCOM for OpenVMS and DECnet-Plus on OpenVMS Alpha

If you are running DCOM on an OpenVMS Alpha system with DECnet/Plus, you must grant the NET$DECLAREOBJECT rights identifier to those processes from which a DCOM for OpenVMS server application will be run.

For example, if the account SMITH will be used to run DCOM for OpenVMS server applications, you must issue the following AUTHORIZE command:


   UAF> GRANT/ID NET$DECLAREOBJECT SMITH 

1.3.3 OpenVMS Registry Consumption of Nonpaged Pool

During stress testing, DIGITAL discovered that a very large number of requests to the OpenVMS Registry server depleted the system's nonpaged pool memory, causing the system to hang.

This condition occurs only if you run many DCOM for OpenVMS clients and servers during a single OpenVMS Registry Server session.

To avoid this condition, DIGITAL recommends that you monitor nonpaged pool usage.

Use the following command to monitor nonpaged pool memory usage:


  $ SHOW MEMORY/POOL/FULL 

Check the Nonpaged Dynamic Memory values. If the Current Size value approaches the Maximum Size value, stop and then restart the OpenVMS Registry Server.

Use the following procedure to stop and restart the OpenVMS Registry Server:

  1. Display the status of the system. Use the following command:


      $ SHOW SYSTEM 
    

  2. Find the PID of the REGISTRY_SERVER process.
  3. Stop the REGISTRY_SERVER process. Use the following command:


      $ STOP/ID=pid-number
    

    where pid-number is the process identifier (PID) of the REGISTRY_SERVER process.

  4. Restart the OpenVMS Registry Server. Use the following command:


      $ @SYS$COMMON:[REGISTRYV71]REGISTRY$STARTUP.COM 
    

1.3.4 MIDL -w Switch

The MIDL compiler allows you to specify either -w or -warn to throttle the level of warnings generated by the compiler. The MIDL compiler for OpenVMS supports only the -w switch.

1.3.5 DCOM$RPCSS Process Resource Exhaustion

The DCOM for OpenVMS runtime environment requires that the DCOM$RPCSS process is always running.

During testing, after DCOM$RPCSS creates and deletes a large number of DCOM for OpenVMS server subprocesses, DCOM$RPCSS appears to run out of resources. When this happens, DCOM$RPCSS might terminate, hang, or otherwise cause unexpected results. If you see unexpected results when running your client or server applications, stop and then restart DCOM$RPCSS using the following commands:


  $ @SYS$STARTUP:DCOM$SHUTDOWN 
  $ @SYS$STARTUP:DCOM$STARTUP 

You can examine the file SYS$MANAGER:DCOM$RPCSS.OUT for error and information messages.

To avoid this particular problem, run server images in their own permanent process instead of having DCOM$RPCSS run them in a subprocess. In application development and testing and for production use, DIGITAL recommends that you run DCOM for OpenVMS servers as permanent multithreaded processes so that the servers are always available to clients. This technique avoids resource issues in DCOM$RPCSS and reduces the overhead associated with creating and deleting subprocesses.

1.3.6 DECwindows Motif Required to Run DCOM for OpenVMS

You must install DECwindows Motif for OpenVMS on any system running DCOM for OpenVMS. If you already have DECwindows Motif installed on your system, you do not need to do anything else. If you do not have DECwindows Motif installed on your system, you can find the installation kit for DECwindows Motif on the OpenVMS Version 7.1 CD-ROM in the [DWMOTIF_ALPHA124.KIT] directory.

Note

If you are installing DECwindows Motif to meet the DCOM for OpenVMS requirements only, you do not need the DW-MOTIF license.

1.3.7 Running DCOM for OpenVMS on OpenVMS Version 7.2 Systems

This release of DCOM for OpenVMS does not provide interoperability between OpenVMS Version 7.2 and Windows NT. DIGITAL will provide this support in a field test update.

This release supports the following interoperability:

1.3.8 System Requirements for Installing DCOM for OpenVMS

Before installing DCOM for OpenVMS, check that you have 9000 free global pages and 40000 free disk blocks. To install the OpenVMS Version 7.1 Registry, you will need an additional 12000 free disk blocks.

1.3.9 OpenVMS DCE Privacy Option

This release of DCOM for OpenVMS does not work on systems running OpenVMS DCE Privacy Option.

1.3.10 MIDL compiler treats wchar_t literals as char

In this release of DCOM for OpenVMS, wide character literal strings in IDL files are incorrectly handled as "char" types.

For example, suppose an IDL file contained the string literal:


    const wchar_t * PROGRAM_ID     = L"Sample.Component"; 

The MIDL compiler on Microsoft Windows NT would produce the following macro definition:


    #define PROGRAM_ID      ( L"Sample.Component" ) 

However, the MIDL compiler for DCOM for OpenVMS produces the following by default:


    #define PROGRAM_ID      ( "Sample.Component" ) 

The problem is caused by the DEC C Version 5.6 preprocessor and will be fixed in a future release of DEC C.

The following workarounds are available:

  1. Avoid using the DEC C preprocessor if possible.
    To run the MIDL compiler without the preprocessor, include the -nocpp or -no_cpp switch on the command line. For example:


        $ midl -Oicf -nocpp -idcom$library: server.idl 
    

    Caution

    Do not use this workaround if the IDL source file or any IDL source file imported by the main IDL source file contains any conditional assembly switches (for example, #ifdef" . . . "#endif").
  2. Define all character string constants as "char" type instead of "wchar_t" type.
    Using this workaround causes the MIDL compiler on Microsoft Windows NT and on OpenVMS to create character string constants that are not wide characters. If the software requires a wide character string literal, the software can convert the ANSI string to a wide character string before the value is used.
  3. Replace the wide character string constants with macro definitions inside the IDL source file.
    For example, instead of defining the string literal as:


        const wchar_t * PROGRAM_ID     = L"Sample.Component"; 
    

    Use a #define inside an IDL cpp_quote() directive as follows:


        cpp_quote("#define PROGRAM_ID L\"Sample.Component\"") 
    

    Even when you use the DEC C preprocessor, the output header file produced by the MIDL compiler for Microsoft Windows NT and OpenVMS will be as follows:


        #define PROGRAM_ID L"Sample.Component" 
    

1.3.11 RPC Server Unavailable Failure (800706BA)

Under certain conditions, you may see an "RPC server unavailable (800706BA)" error message when you are running a client application on Windows NT and a server application on OpenVMS.

To correct this error, stop and restart the server application (if you manually started the application); then restart the client application.

1.3.12 Remote Activation of an In-Process Server

If a server component is registered only as an in-process server, the component cannot be activated remotely on OpenVMS. If the system tries to activate an in-process server remotely, the remote client receives a "REGDB_E_CLASSNOTREG (80040154)" error. To activate a server component remotely, the component must be registered as an out-of-process server so the DCOM$RPCSS process can start the component on the client's behalf.


Part 1
DCOM for OpenVMS

This part contains information about DCOM for OpenVMS.

The following chapters provide an overview of DCOM for OpenVMS, instructions on installing and configuring DCOM for OpenVMS and related software, and describes and explains how to create COM applications using DCOM for OpenVMS.


Chapter 2
Overview of DCOM for OpenVMS

2.1 What is COM?

Component Object Model (COM) is a technology from Microsoft that lets you create distributed network objects. First introduced by Microsoft in its Windows 3.x product, COM was initially called Object Linking and Embedding (OLE). COM provides a widely available, powerful mechanism for customers to adopt and adapt to a new style multivendor distributed computing, while minimizing new software investment.

DIGITAL and Microsoft jointly developed the COM specification. First released as NetOLE (Network OLE) and then renamed DCOM (Distributed COM), the COM specification now includes network functionality. That is, COM now includes network objects.

COM is an object-based programming model designed to promote software interoperability. COM allows two or more applications (or components) to cooperate with one another easily, even if the objects are written by different vendors at different times and in different programming languages, or if they are running on different machines with different operating systems. To support its interoperability features, COM defines and implements mechanisms that allow applications to connect to each other as software objects.

COM implementations are available on Windows NT, Windows 95tm, Windows 98, OpenVMS, and DIGITAL UNIX, as well as other UNIX platforms.

2.1.1 Suggested Reading

The following resources can provide you with more information on COM and related topics:

2.2 Overview of DCOM for OpenVMS

DCOM for OpenVMS is Digital Equipment Corporation's implementation of Microsoft's Windows NT 4.0 Service Pack 2 (SP3) Component Object Model (COM) software on the OpenVMS Alpha operating system.

In support of DCOM for OpenVMS, DIGITAL ported Windows NT infrastructure to OpenVMS, including the registry, events logging [Not implemented in this FT] , NTLM security [Not implemented in this FT] , and Win32 APIs. DCOM for OpenVMS is layered on The Open Group's Distributed Computing Environment (DCE) RPC. DCOM for OpenVMS supports communication among objects on different computers on a local area network (LAN), a wide area network (WAN), or the Internet. DCOM for OpenVMS is important to the Affinity for OpenVMS program because it delivers a key piece of connectivity with Windows NT.

For developers, DCOM for OpenVMS provides a Microsoft Interface Definition Language (MIDL) compiler and C-style header files for application development. It also provides a run-time environment on OpenVMS Alpha for the deployment of DCOM for OpenVMS client and server applications.

You can find a complete description of Microsoft's COM, including protocol specifications and programming documentation, at the Microsoft COM website at the following location:


 http://www.microsoft.com/com 

The OpenVMS implementation is a subset of the full Microsoft implementation. For a complete list of the DCOM for OpenVMS APIs, supported interfaces, and implementation differences, see Appendix C.

While general interest in COM continues to grow, COM remains a sophisticated technology. It is not aimed at the naive user, but at skilled programmers, such as independent software vendors (ISVs) and large management information system (MIS) shops.

2.3 Using DCOM for OpenVMS

You can use DCOM for OpenVMS to do the following:

The following sections discuss developing new application and wrappering in more detail.

2.3.1 Developing New Applications

Your organization might use DCOM for OpenVMS to develop new applications under the following circumstances:

The advantages of using DCOM for OpenVMS include:

You might decide not to use COM if you require a distributed namespace or if you are concerned about failover or load balancing.

See Chapter 5 and Appendix B for examples of developing DCOM for OpenVMS applications.

2.3.2 Wrappering Existing Applications

If you have monolithic applications written in procedural languages (such as Fortran and COBOL) with character-cell interfaces, you can put a COM wrapper around these applications to allow them to run on new platforms, or to remain on OpenVMS and run in a client/server environment.

The risk associated with completely reengineering some older applications is high. Many applications are large, complex, poorly documented, and not well understood by their current maintainers. Wrappering a legacy application can be less risky than reengineering and can be the first step in a rewrite. Over time, pieces of the legacy application can be rewritten, while the older version of the application remains stable and available. Wrappering also allows developers to reuse code, saving time and resources.

Disadvantages to wrappering include more complex maintenance efforts and the inability to make changes to the underlying code. If the legacy application was unstable or hard to maintain, the wrappered application will not be any better, and might be made worse because of the wrapper.

There are several layers of a traditional procedural application that you can wrapper: the user interface (UI), the database, and the data manipulation routines.

Wrappering an OpenVMS application using DCOM for OpenVMS means that you write a DCOM for OpenVMS server that talks to the application being wrappered. The DCOM for OpenVMS server passes arguments to the application in the order and format that the application expects. The DCOM for OpenVMS server then intercepts the output from the application and directs it to the display device, user interface, or other routines.

2.4 What is the OpenVMS MIDL Compiler?

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

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

2.5 How DCOM for OpenVMS uses the OpenVMS Registry

DCOM for OpenVMS requires the OpenVMS Registry server. Like its registry database counterpart on Windows NT systems, the OpenVMS Registry stores information about COM applications---specifically those COM application running on OpenVMS. These DCOM for OpenVMS applications use the OpenVMS Registry to store CLSIDs (class IDs), startup information, security settings [Not implemented in this FT] , and so on in the OpenVMS Registry keys and values. DCOM for OpenVMS uses the Microsoft APIs implemented on OpenVMS to read and write this information to the OpenVMS Registry.

The OpenVMS Registry server should start during system startup. If OpenVMS Registry server is not running, DCOM for OpenVMS will not start. See Section 3.1.6 for startup instructions.

For more information about the OpenVMS Registry, see Chapter 6.


Chapter 3
Installing the DCOM for OpenVMS Kit

This chapter provides a preinstallation checklist (installing and configuring OpenVMS DCE, installing and configuring OpenVMS UCX, and installing and starting the OpenVMS Registry) and describes how to install DCOM for OpenVMS.

3.1 Preinstallation Checklist

Before you install DCOM for OpenVMS, you must do the following:

  1. Install OpenVMS UCX Version 4.1-12 ECO2 or higher. (See Section 3.1.1.)
  2. Configure OpenVMS UCX. (See Section 3.1.2.)
  3. Install the OpenVMS Registry. (See Section 3.1.3.)
  4. Reboot the system.
  5. Install OpenVMS DCE Version 1.4. (See Section 3.1.4.)
  6. Configure OpenVMS DCE. (See Section 3.1.5.)
  7. Start the OpenVMS Registry. (See Section 3.1.6.)

The following sections describe these procedures in more detail.

3.1.1 Installing OpenVMS UCX

DCOM for OpenVMS requires OpenVMS UCX V4.1-12 ECO2 or higher. You can find the OpenVMS UCX kits in the [TCPIP_ALPHA_041.KIT] directory of the OpenVMS Alpha Version 7.1 CD. You must install both the UCX V4.1 and the UCX ECO2 kits.

3.1.2 Configuring OpenVMS UCX

When you configure OpenVMS UCX, you must enable the Server PORTMAPPER component using SYS$MANAGER:UCX$CONFIG.

For OpenVMS DCE to work properly, you must disable the TCP parameter Delay ACK in UCX.

After you configure OpenVMS UCX, enter the following commands:


      $ UCX SET PROTOCOL TCP /NODELAY 
      $ UCX SET CONFIG PROTOCOL TCP /NODELAY 

3.1.3 Installing the OpenVMS Registry

DCOM for OpenVMS requires the OpenVMS Registry.

Note

DCOM for OpenVMS FT2 runs on an OpenVMS Version 7.1 system. You must install a version of the OpenVMS Registry designed for OpenVMS Version 7.1.

In OpenVMS Version 7.2, the OpenVMS Registry is integrated with the OpenVMS operating system.

The OpenVMS Version 7.1 Registry kit is distributed as a single file that you install using the POLYCENTERtm Software Installation utility on an OpenVMS Alpha Version 7.1 system. The name of the kit is DEC-AXPVMS-REGISTRYV71-V0100.PCSI.

To install the OpenVMS Registry, invoke the POLYCENTER Software Installation utility using the following command:


  $ PRODUCT INSTALL /SOURCE=ddcu:[dir] REGISTRYV71 

For ddcu:[dir], specify the device name and directory location of the kit.

Example 3-1 Sample OpenVMS Registry Installation

$ PRODUCT INSTALL /SOURCE=DKA0:[DCOMKIT] REGISTRYV71 
 
The following product has been selected: 
    DEC AXPVMS REGISTRYV71 V1.0            Layered Product [Installed] 
 
Do you want to continue? [YES] Y 
 
Configuration phase starting ... 
 
You will be asked to choose options, if any, for each selected product and for 
any products that may be installed to satisfy software dependency requirements. 
 
DEC AXPVMS REGISTRYV71 V1.0 [Installed] 
 
    Copyright © Digital Equipment Corporation 1998. All rights reserved. 
 
Do you want the defaults for all options? [YES] Y 
 
Do you want to review the options? [NO] N 
 
Execution phase starting ... 
 
The following product will be installed: 
    DEC AXPVMS REGISTRYV71 V1.0            Layered Product 
 
Portion done: 0%...50%...80%...90%...100% 
 
The following product has been installed: 
    DEC AXPVMS REGISTRYV71 V1.0            Layered Product 
 
DEC AXPVMS REGISTRYV71 V1.0 
 
    You must reboot this system following the installation of the Registry 
 
    Press RETURN to continue: 
$ 

After you complete the OpenVMS Registry installation, you must reboot the system before installing OpenVMS DCE.

3.1.4 Installing OpenVMS DCE (OpenVMS Version 7.1 systems only)

DCOM for OpenVMS requires OpenVMS DCE Version 1.4. DCOM for OpenVMS uses DCE RPC to handle communications between COM objects.

Required for OpenVMS Version 7.1 systems only

If you are running OpenVMS Version 7.1, you must install OpenVMS DCE.

If you are running OpenVMS Version 7.2 FT2, you do not have to install OpenVMS DCE.

If OpenVMS DCE Version 1.4 is already installed and configured on the system that will be running DCOM for OpenVMS applications, your current OpenVMS DCE configuration is sufficient. DCOM for OpenVMS requires no additional OpenVMS DCE changes.

If your OpenVMS system does not have OpenVMS DCE Version 1.4 installed and configured, you must install, configure, and start OpenVMS DCE.

You can find the installation kit for OpenVMS DCE Version 1.4 in the [DCE_ALPHA014.KIT] directory of the OpenVMS Version 7.1 CD-ROM. For information on installing OpenVMS DCE, read the OpenVMS DCE documentation. You do not need an OpenVMS DCE license to install and run OpenVMS DCE in a configuration sufficient to support DCOM for OpenVMS. DCOM for OpenVMS runs successfully on an RPC-only DCE configuration. A DCE cell with a security server and a CDS server is not required.

3.1.5 Configuring OpenVMS DCE (OpenVMS Version 7.1 systems only)

Required for OpenVMS Version 7.1 systems only

If you are running OpenVMS Version 7.1, you must configure OpenVMS DCE.

If you are running OpenVMS Version 7.2 FT2, you do not have to configure OpenVMS DCE.

To configure OpenVMS DCE to support DCOM for OpenVMS, select option 1, "Provide DCE RPC services only" from the configuration menu. This option provides the RPC endpoint mapper and DCE runtime on your system.

You must add commands to your system's site-specific startup procedure to start OpenVMS DCE and DCOM for OpenVMS each time the system is booted. You must start your TCP/IP services before you start DCE. You must start DCE before you start DCOM for OpenVMS. See Section 3.1.7 for a list of the startup command order.

3.1.6 Starting the OpenVMS Registry Server (OpenVMS Version 7.1 systems only)

Required for OpenVMS Version 7.1 systems only

If you are running OpenVMS Version 7.1, you must start the OpenVMS Registry.

If you are running OpenVMS Version 7.2 FT2, you do not have to start the OpenVMS Registry.

To start the OpenVMS Registry server, enter the following command:


  $ @SYS$COMMON:[REGISTRYV71]REGISTRY$STARTUP.COM 

Add this command to your system's site-specific startup command file so that the OpenVMS Registry server starts each time you boot the system. You must run this command before the command to start DCOM for OpenVMS.

A cluster environment requires only a single OpenVMS Registry server. Run this command file on the one node in the cluster that you designate as the OpenVMS Registry server node.

If you run this command on other nodes in the cluster, those nodes will act as backup OpenVMS Registry servers and will provide an extra level of redundancy for the OpenVMS Registry. For more information about running multiple version of the OpenVMS Registry in a cluster, see OpenVMS Registry Failover in a Cluster [Not implemented in this FT] .

3.1.7 Startup Order for Services

You must start the services in the the following order:

  1. The OpenVMS Registry server
  2. IP services
  3. DCE or RPC services
  4. DCOM for OpenVMS server

3.2 Installing DCOM for OpenVMS

The DCOM for OpenVMS installation kit contains a single POLYCENTER Software Installation file. The name of the kit is DEC-AXPVMS-DCOM-H0100--1.PCSI You must install the DCOM for OpenVMS files on an OpenVMS Alpha Version 7.1 system.

To install DCOM for OpenVMS, invoke the POLYCENTER Software Installation utility using the following command:


 $ PRODUCT INSTALL /SOURCE=ddcu:[dir] DCOM 

For ddcu:[dir], specify the device name and directory location of the kit.

MIDL compiler license

The DCOM for OpenVMS MIDL compiler requires a license. DIGITAL provides the DCOM-MIDL PAK separately from the DCOM for OpenVMS kit.

Example 3-2 Sample DCOM for OpenVMS Installation

$ PRODUCT INSTALL /SOURCE=DKA0:[DCOMKIT] DCOM 
 
The following product has been selected: 
    DEC AXPVMS DCOM H1.0                   Layered Product 
 
Do you want to continue? [YES] 
 
Configuration phase starting ... 
 
You will be asked to choose options, if any, for each selected product and for 
any products that may be installed to satisfy software dependency requirements. 
 
DEC AXPVMS DCOM H1.0 
 
    Copyright © Digital Equipment Corporation 1998. All rights reserved. 
 
Do you want the defaults for all options? [YES] 
 
    The following requirements must be met prior to installing OpenVMS DCOM 
 
      - You must be running OpenVMS Alpha V7.1 or later 
      - If you're running OpenVMS Alpha V7.1 you must install the REGISTRYV71 kit 
      - You must be running UCX V4.1-12 ECO2 or later 
      - You must be running OpenVMS DCE V1.4 or later (OpenVMS 7.1 only) 
      - In order to use the DCOM MIDL compiler you must install 
        the DCOM-MIDL License PAK 
 
    Do you want to continue? [YES] 
 
Do you want to review the options? [NO] 
 
Execution phase starting ... 
 
The following product will be installed: 
 
    DEC AXPVMS DCOM H1.0                   Layered Product 
 
Portion done: 0%...10%...20%...30%...40%...50%...60%...80%...90%...100% 
 
The following product has been installed: 
    DEC AXPVMS DCOM H1.0                   Layered Product 
 
DEC AXPVMS DCOM H1.0 
 
    Postinstallation tasks required for OpenVMS DCOM 
 
      - Execute the command  @SYS$MANAGER:DCOM$REGISTRY_KEYS  to populate 
        the registry 
 
      - If you're running OpenVMS DCE V1.4 you must perform these three steps 
        1. Execute the command  @SYS$STARTUP:DCE$SETUP STOP  to stop DCE 
        2. Execute the command  @SYS$UPDATE:DCOM$RENAME_DCE.COM  to activate 
           the new DCE V1.4 Runtime Library 
        3. Execute the command  @SYS$STARTUP:DCE$SETUP START  to restart DCE 
 
      - Execute the command  @SYS$STARTUP:DCOM$STARTUP  to start DCOM 
 
      - Add the command  @SYS$STARTUP:DCOM$STARTUP  to your site specific 
        startup command file after the command that starts DCE 
 
    Press RETURN to continue: 
$ 

3.2.1 DCOM for OpenVMS Postinstallation Procedures

After you install the DCOM for OpenVMS kit, do the following:

  1. Enter the @SYS$MANAGER:DCOM$REGISTRY_KEYS command to populate the OpenVMS Registry.
  2. For OpenVMS Version 7.1 systems only: If OpenVMS DCE is running, enter the @SYS$STARTUP:DCE$SETUP STOP command. This procedure stops OpenVMS DCE.
  3. For OpenVMS Version 7.1 systems only: Enter the @SYS$UPDATE:DCOM$RENAME_DCE.COM command to activate the new OpenVMS DCE runtime library.
    This command file saves the original OpenVMS DCE runtime library in a file named SYS$LIBRARY:DCE$LIB_SHR.EXE_ORIG and provides a new OpenVMS DCE runtime library in a file named SYS$LIBRARY:DCE$LIB_SHR.EXE.
  4. For OpenVMS Version 7.1 systems only: Enter the @SYS$STARTUP:DCE$SETUP START command to restart OpenVMS DCE.
  5. Add the command @SYS$STARTUP:DCOM$STARTUP to your site-specific startup command file after the command that starts OpenVMS DCE.
    This command file starts the DCOM for OpenVMS Service Control Manager (DCOM$RPCSS) every time you start the system.


Next Contents Index
 


  OVMS_DCOM_GUIDE_FT2.HTML