COM, Registry, and Events for HP OpenVMS Developer's Guide

COM, Registry, and Events for
HP OpenVMS Developer's Guide


July 2004

This document contains information about the Component Object Module (COM) for OpenVMS, the OpenVMS Registry, and OpenVMS Events logging. It also includes information about OpenVMS and Windows authentication and interoperation.

Revision/Update Information: This manual supersedes the COM, Registry, and Events for OpenVMS Developer's Guide, Version 1.3.

Software Version: COM Version 1.4 for OpenVMS

Operating System: OpenVMS Alpha Version 7.3-1 or higher
Microsoft Windows NT 4.0 SP5 or higher, or Microsoft Windows 2000 SP4 or higher



Hewlett-Packard Company
Palo Alto, California


© Copyright 2004 Hewlett-Packard Development Company, L.P.

Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.

Microsoft, MS-DOS, Visual C++, Windows, and Windows NT are trademarks of Microsoft Corporation in the U.S. and/or other countries.

Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

Motif, OSF/1, and UNIX are trademarks of The Open Group in the U.S. and/or other countries.

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.

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

Printed in the U.S.

ZK6539

Contents Index


Preface

Intended Audience

This document is designed primarily for developers who want to use the OpenVMS infrastructure to develop applications that move easily between the OpenVMS and Windows environments. These developers include the following:

This document is not intended as an introduction to COM or the Registry. It assumes that readers are already familiar with object-oriented (OO) concepts and COM development techniques, as well as how the Registry works on a Windows system. The document does provide pointers to online information about COM and the Registry, and recommends other books about COM, OO development, and the Registry.

Document Structure

This document, formerly titled OpenVMS Connectivity Developer Guide, contains all the information you need to develop COM for OpenVMS applications and use the OpenVMS Registry. The document is divided into the following sections:

Related Documents

For additional information about HP OpenVMS products and services, visit the following World Wide Web address:


http://www.hp.com/go/openvms 

Reader's Comments

HP welcomes your comments on this manual. Please send comments to either of the following addresses:
Internet openvmsdoc@hp.com
Postal Mail Hewlett-Packard Company
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How to Order Additional Documentation

For information about how to order additional documentation, visit the following World Wide Web address:


http://www.hp.com/go/openvms/doc/order 

Conventions

The following conventions are 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 choices in parentheses if you specify more than one.
[ ] In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.
| In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line.
{ } In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line.
bold type Bold type represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.
italic type Italic type 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 TYPE Uppercase type indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
Example This typeface indicates code examples, command examples, and interactive screen displays. In text, this type also identifies URLs, UNIX commands and pathnames, PC-based commands and folders, and certain elements of the C programming language.
- 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
COM for OpenVMS Release Notes

The release notes in this chapter apply to COM Version 1.4 for OpenVMS.

1.1 COM for OpenVMS Versions

This section describes the versions of COM for OpenVMS.

Table 1-1 Summary of Security Differences
Area Unauthenticated COM (V1.0, V1.1-B, V1.2, V1.3, V1.4) Authenticated COM (V1.1, V1.1-A, V1.1-B, V1.2, V1.3, V1.4)
Client requests Authenticated on Windows; not authenticated on requests to OpenVMS. Authenticated on Windows and OpenVMS.
Security Servers can run with the client's identity on Windows and with a prespecified OpenVMS identity on OpenVMS. Servers can run with the client's identity on Windows and on OpenVMS.
Security Per-method security is allowed on Windows, but only processwide security is allowed on OpenVMS. Per-method security is allowed on Windows and on OpenVMS.
Outbound COM requests Authenticated on Windows only. Authenticated on Windows and OpenVMS.
Registry access On Windows: controlled by Windows credentials.

On OpenVMS: relies on OpenVMS security controls such as privileges or rights identifiers.

On Windows: controlled by Windows credentials.

On OpenVMS: controlled either by Windows credentials or by OpenVMS security controls.

Event logging Windows only. Windows and OpenVMS.

1.2 Upgrading from Earlier Versions of COM for OpenVMS to Version 1.4

If you are upgrading to Version 1.4 from an earlier version of COM for OpenVMS, follow the upgrade instructions in Section 4.3. In addition:

1.2.1 Upgrading from COM Version 1.0 or 1.1 for OpenVMS Requires You to Repopulate the OpenVMS Registry

Note

If you are upgrading from any version of COM later than (but not including) COM Version 1.1 for OpenVMS, you do not need to repopulate the OpenVMS Registry.

If you are upgrading from Version 1.0 or Version 1.1 to Version 1.4, you must repopulate the OpenVMS Registry to include security settings. Use the DCOM$SETUP command to display the OpenVMS COM Tools menu, and choose option 3.

When you populate the OpenVMS Registry for COM for OpenVMS, the system prompts you to confirm the repopulation. You must answer YES each time. For example:


        [ Starting to Populate the COM for OpenVMS Registry ] 
 
         Populating the Registry for OpenVMS may take up to 15 minutes 
         depending on your system. 
 
Enter YES to continue [default is NO]: YES 
 
         The COM for OpenVMS Registry has already been loaded. This 
         action will overwrite the current COM for OpenVMS values 
         and data. 
 
Enter YES to continue [default is NO]: YES 

Note

Repopulating the OpenVMS Registry does not affect the registration of existing COM applications.

1.2.2 DECwindows Motif Requirement Removed

In previous versions of COM for OpenVMS, DECwindows Motif was required software. In COM Version 1.4 for OpenVMS and higher, this prerequisite is removed.

1.2.3 C Compiler Requirement Removed

In previous versions of COM for OpenVMS, DEC C Version 5.6 or higher was required software for COM for OpenVMS application development. In COM Version 1.2 for OpenVMS and higher, this prerequisite is removed. (You can still build your applications using DEC C Version 6.0 or higher; however, the C compiler is not required software.)

You can now build all applications using the recommended HP C++ compiler Version 6.5 or higher, or the minimum requirement of Compaq C++ compiler Version 6.0. (You need Compaq C++ Version 6.2-016 or higher to build ATL applications.)

For more information about building applications using the MIDL compiler, see Section 7.2.

1.2.4 Previously Registered Applications That Use Logical Names for the Local Server Path

If you previously registered any COM application using a logical name for the local server path, you must modify (reregister) the application using the actual name for the local server path.

For example, if you use the REGISTER_SIMPLE.COM command procedure to register the "Simple" application under COM Version 1.0 for OpenVMS, you must reregister the "Simple" application using the new REGISTER_SIMPLE.COM command procedure.

As of COM Version 1.1-A for OpenVMS, HP has updated the registration command files.

The system stores the COM application local server path in the OpenVMS Registry as a value data as follows:


  "HKEY_CLASSES_ROOT\CLSID\{GUID}\LOCALSERVER32" 

Use the following REG$CP command to modify the local server path:


$ REG$CP == "$REG$CP" 
$ REG$CP CREATE VALUE HKEY_CLASSES_ROOT\CLSID\{GUID}\Localserver32 - 
_$ /TYPE=SZ/DATA=device:[directory]image-name.EXE 

A GUID is the COM application CLSID. For more information about Localserver32 and CLSID, see Section 7.5.

1.2.5 Changes to the Examples

In COM Version 1.1-A for OpenVMS, the names of the server images in the Dispatch_Sample1 example changed. If you previously built and registered this application and you want to build the new version, you must reregister the server after it has been built.

1.3 Problems Fixed in This Release

The following notes describe problems that have been fixed in COM Version 1.4 for OpenVMS.

1.3.1 New NTA$LOGON.EXE Fixes Data Corruption in Password File

HP testing has uncovered a problem that occurs while using the DCOM$SETUP menu option number 8 to update the DCOM$RPCSS user password in the COM for OpenVMS Service Control Manager password file. This problem can potentially cause the password file to be corrupted.

A new NTA$LOGON.EXE image corrects this problem. This image can be obtained by picking up the latest DCE update kit.

1.3.2 Access Violation When Compiling Very Large IDL Files

In certain instances, an access violation would occur when compiling very large IDL files. COM Version 1.4 provides a modification to the MIDL compiler that prevents this problem.

1.3.3 Windows 2000 Interoperability Requires Windows 2000 SP4 and Latest DCERPC

As part of interoperability testing, HP has identified problems in the authentication layer that prevents authenticated COM requests between OpenVMS and Windows 2000 systems.

The solution to these problems is to install Windows 2000 SP4 on your Windows system, and the latest DCE$LIB_SHR.EXE (available from your support center) on your OpenVMS system.

1.3.4 ERROR_ACCESS_DENIED (C0000005 or 80070005)

COM for OpenVMS in authenticated mode reported intermittent ERROR_ACCESS_DENIED (C0000005 or 80070005) errors when running an OpenVMS client to a Windows 2000 server. These errors were seen only if the domain name was fewer than 12 characters. This problem has been fixed in this release.

Under heavy load testing, HP still encounters a few remaining ERROR_ACCESS_DENIED errors, but the occurence is less than 1%. To avoid this problem completely, use a domain name of 12-15 characters.

1.4 Known Problems in the Current Release

The following notes describe the known problems with COM Version 1.4 for OpenVMS. These problems currently do not have fixes.

1.4.1 Fatal Exception in DCOM$RPCSS While Launching Multiple Instances of COM Applications

During extensive testing by HP in unauthenticated mode, in certain instances the DCOM$RPCSS process may experience a fatal exception while trying to launch multiple instances of different COM applications. This results in all client processes reporting a 8007071C error.

To return to a working environment, shut down and restart DCOM$RPCSS. A possible workaround is to run your application as a persistent server.

HP is continuing to investigate this problem. If you encounter this problem, please contact your HP support center.

1.4.2 COM Version 1.4 Fails with Microsoft MS04-012 (KB 828741) Patch

HP testing has discovered that after installing the Microsoft security patch MS04-012 (Knowledge Base article 828741), an OpenVMS client connection to a Windows server fails. The application will fail with an access denied error such as C0000005 or 80070005.

If you have already installed this security patch and are experiencing problems, a possible workaround is to temporarily uninstall the patch.

A solution to this problem is being jointly investigated by Microsoft and HP, and an update will be provided as soon as it becomes available.

1.4.3 Kernel Threads and Upcalls Not Supported

COM for OpenVMS applications cannot be built with kernel threads or upcalls enabled. This support will be available in a future release.

1.4.4 Errors Seen Between OpenVMS Systems Running COM Version 1.3 Under Heavy Load

Testing by HP has uncovered the errors E-OUTOFMEMORY (8007000E), DCERPC-E-WHOAREYOUFAILED (EE1282FA) and CO_E_SERVER_EXEC_FAILURE (80080005) between OpenVMS systems running heavy load tests with COM Version 1.3 for OpenVMS. This problem was not seen when the tests were run locally or between Windows and OpenVMS systems.

1.5 Limitations and Restrictions

The following sections contain general release note information.

1.5.1 Windows XP Not Supported

HP has not tested COM Version 1.4 with Windows XP. Therefore, Windows XP is not supported in COM Version 1.4 for OpenVMS.

1.5.2 NetBEUI as Listed Protocol in DCOMCNFG

If you have NetBEUI listed as a default protocol in DCOMCNFG, you might see various errors when running sample programs between OpenVMS and Windows 2000. To correct these problems, remove NetBEUI from the list of default protocols and reboot your Windows system.

1.5.3 COM Version 1.0 for OpenVMS and COM Version 1.4 for OpenVMS Not Supported in the Same Cluster

When you install and configure any version of COM for OpenVMS higher than Version 1.0 on any node in a cluster, you make clusterwide modifications to the OpenVMS Registry that prevent COM Version 1.0 for OpenVMS from running on any other node in the same cluster.

1.5.4 Threading Model Supported by COM for OpenVMS

COM Version 1.4 for OpenVMS supports only the multithreaded apartment (MTA, also known as free threads) model for application servers. The MTA model allows a component to have more than one thread. However, you must ensure that your code is thread safe.

The threading model initialization call is as follows:


CoInitializeEx( 
   NULL, 
   COINIT_MULTITHREADED 
   ) 

Because CoInitialize() implies the single-threaded apartment (STA) model, you cannot use it in place of CoInitializeEx() in a server application.

1.5.5 Enhanced NTLM in Windows NT SP4 and Later Versions Not Supported

In Windows NT SP4, Microsoft introduced enhanced NTLM support. COM Version 1.4 for OpenVMS does not support enhanced NTLM.

If you want to use COM Version 1.4 for OpenVMS with SP4 or later, you must be sure that enhanced NTLM is disabled.

Ongoing testing by HP has show that, with SP4 or higher and enhanced NTLM disabled, authentication requests fail if you use passwords that are longer than 12 characters.

1.5.6 Specifying Activation Security in CoCreateInstanceEx

The pServerInfo parameter of the CoCreateInstanceEx API allows you to specify a user name and password that will be used for authentication on the remote server system. The user name and password are part of the COAUTHIDENTITY structure inside the COAUTHINFO structure, which is inside the COSERVERINFO structure that is passed as the pServerInfo parameter to CoCreateInstanceEx .

The current NTLM security implementation on OpenVMS does not support this feature for COM client applications on OpenVMS. This feature is supported for COM clients on Windows communicating with COM servers on OpenVMS.

1.5.7 RPC Communication Failures Caused by Advanced Server

In a cross-domain environment, under some load situations, COM applications may report errors that are a side effect of the HP Advanced Server for OpenVMS having lost a connection between domain controllers. The Advanced Server reports this error as follows:


NET5719:    No domain controller for the domain 'xxxxx' is available. 

A series of these events over a limited time interval may lead to COM applications reporting RPC communications failures (%x8007071c). In this situation, a stop and start of DCOM$RPCSS may be required to clear the error.

See Section 5.4.6 for more information. If the NET5719 events persist, contact your HP support center.

1.5.8 RPC Cannot Support Failure (800706E4) Error Message

If you attempt to use the single-threaded apartment (STA) model, some COM APIs may display the following return status code:


  (800706E4) 

COM Version 1.4 for OpenVMS does not support the STA model. For more information, see Section 1.5.4.


Chapter 2
OpenVMS Registry Release Notes

For the latest OpenVMS Registry information, refer to the OpenVMS Release Notes for the current version of the operating system.


Part 1
COM for OpenVMS

The following chapters provide an overview of COM for OpenVMS, provide instructions for installing and configuring COM for OpenVMS and related software, and describe and explain how to create COM applications using COM for OpenVMS.


Chapter 3
Overview of COM for OpenVMS

3.1 What is COM?

Component Object Model (COM) is a technology from Microsoft that lets developers 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.

The former Digital Equipment Corporation (now part of Hewlett-Packard Company) 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 supports distributed 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 2000, Windows NT, Windows 98, Windows 95, OpenVMS, and HP Tru64tm UNIX, as well as other UNIX platforms.

3.1.1 Suggested Reading

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

3.2 Overview of COM for OpenVMS

COM for OpenVMS is HP's implementation of Microsoft's Windows NT 4.0 Service Pack 5 (SP5) Component Object Model (COM) software on the OpenVMS Alpha operating system.

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

Figure 3-1 shows the OpenVMS infrastructure.

Figure 3-1 OpenVMS Infrastructure and COM for OpenVMS


In Figure 3-1 the key pieces of the OpenVMS infrastructure are as follows:

Windows system
The smaller box on the left side of Figure 3-1 represents the Windows system.
OpenVMS Cluster/OpenVMS identity
The large box on the right side of Figure 3-1 represents the OpenVMS system. Within and around this box you can see several other boxes labeled with numbers. The following list describes these numbered items:
  1. OpenVMS security
    This is the standard OpenVMS security (login, authentication, ACLs, and so on) available with all OpenVMS systems.
  2. HP Advanced Server for OpenVMS
    The HP Advanced Server for OpenVMS provides authentication of Windows users to OpenVMS and provides a connection to the OpenVMS Registry and events viewer for Windows users.
  3. Windows identity/Win32 APIs
    The OpenVMS Security, MSV1_0 ACME agent, HP Advanced Server for OpenVMS, OpenVMS Registry, event logger, and Win32 APIs (COM APIs) all contribute to the creation of a Windows identity within the OpenVMS system.
  4. OpenVMS Registry
    The OpenVMS Registry, like the registry on Windows systems, allows you to store system, software, and hardware configuration information on OpenVMS. COM for OpenVMS uses the OpenVMS Registry to store information about COM applications. For detailed information about the OpenVMS Registry, see Part 2 of this document.
  5. Event logger
    Like the event logger on Windows systems, the event logger on OpenVMS records informational, warning, and error messages about COM events. For detailed information about the OpenVMS Events, see Chapter 15.
  6. Windows COM stack
    On the Windows system, COM requests and responses pass through the COM, RPC, SSPI (security), and Domain layers.
  7. OpenVMS COM stack
    The OpenVMS system mirrors the Windows COM stack, with some additions. On the OpenVMS system, COM requests and responses pass through the COM, RPC, SSPI (security), MSV1_0 ACME agent, and HP Advanced Server for OpenVMS layers. The MSV1_0 ACME agent (shown as ACME in Figure 3-1) is an extension to the Authentication and Credential and Management (ACM) authority. Authentication is explained in detail in Chapter 8.
  8. Connection through RPC layer
    The COM connection between the Windows system and OpenVMS is always through the RPC layer.

For developers, the COM for OpenVMS developer's kit provides a Microsoft Interface Definition Language (MIDL) compiler and C-style header files for application development. For more information about the OpenVMS MIDL compiler, see Section F.1.4.1.

OpenVMS includes a utility to acquire Windows credentials if you are running COM for OpenVMS in authenticated mode. For more information about getting Windows credentials through NTA$LOGON, see Section 5.1 and Chapter 8.

COM for OpenVMS also provides a free run-time environment on OpenVMS Alpha for the deployment of COM 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:


   www.microsoft.com/com 

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

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

3.2.1 How COM for OpenVMS Uses the OpenVMS Registry

COM for OpenVMS requires the OpenVMS Registry. Like its registry database counterpart on Windows systems, the OpenVMS Registry stores information about COM applications---specifically those COM applications running on OpenVMS. These COM for OpenVMS applications use the OpenVMS Registry to store CLSIDs (class IDs), startup information, security settings, and so on in the OpenVMS Registry database. COM for OpenVMS uses the Win32 APIs implemented on OpenVMS to read and write this information to the OpenVMS Registry.

COM for OpenVMS requires access to the OpenVMS Registry database. If COM for OpenVMS cannot access the OpenVMS Registry, COM for OpenVMS will not start. For more information about the OpenVMS Registry, see Chapter 12.

3.3 Using COM for OpenVMS

You can use COM for OpenVMS to do the following:

The following sections discuss new application development and encapsulation in more detail.

An example of a COM application to encapsulate an existing OpenVMS application is included with this release. The example can be found in DCOM$EXAMPLES:[WRAPPER]. A README file describes the example and how to build it.

3.3.1 Developing New Applications

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

The advantages of using COM for OpenVMS include:

See Chapter 7 and Appendix C for examples of developing COM for OpenVMS applications.

3.3.2 Encapsulating 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" or jacket around these applications to allow them either 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. Encapsulating 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. Encapsulation also allows developers to reuse code, saving time and resources.

Disadvantages to encapsulation 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 encapsulated 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 encapsulate: the user interface (UI), the database, and the data manipulation routines.

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


Chapter 4
Installing the COM for OpenVMS Kit

This chapter provides a list of the contents of the COM for OpenVMS kit, a list of prerequisite software, and preinstallation requirements. It also describes how to install COM for OpenVMS and includes postinstallation instructions.

4.1 Contents of the COM Version 1.4 for OpenVMS Kit

COM Version 1.4 for OpenVMS contains the following:

4.2 Prerequisites

The following software is required:

4.3 Supported COM for OpenVMS Installations

The following sections describe COM Version 1.4 for OpenVMS installation and upgrade options.

Note

If you want to run COM Version 1.4 for OpenVMS in unauthenticated mode, see Section E.1.
If you want to do this Read this section
Install COM for OpenVMS on an OpenVMS standalone system for the first time. Section 4.4
Install COM for OpenVMS on an OpenVMS Cluster system for the first time. Section 4.6
Upgrade from earlier versions of COM for OpenVMS on an OpenVMS standalone system. Section 4.5
Upgrade from earlier versions of COM for OpenVMS on an OpenVMS Cluster system. Section 4.7

4.4 Installing COM for OpenVMS on an OpenVMS Standalone System

Use the following procedure:

  1. Install OpenVMS Version 7.3-1 or higher. For this procedure, see the OpenVMS Alpha Version 7.x Upgrade and Installation Manual.
  2. Install TCP/IP Services. For this procedure, see the HP TCP/IP Services for OpenVMS Installation and Configuration manual or your TCP/IP supplier's documentation.
  3. Boot the installed system from the system disk.
  4. Install COM Version 1.4 for OpenVMS. For this procedure, see Section 4.11.
  5. Install HP Advanced Server for OpenVMS. For this procedure, see the HP Advanced Server for OpenVMS Server Installation and Configuration Guide.
  6. Configure TCP/IP Services (set up for startup and reboot); then start TCP/IP. You must configure the PWIP driver for HP Advanced Server for OpenVMS to use TCP/IP Services. For information about configuring TCP/IP, see the HP TCP/IP Services for OpenVMS Installation and Configuration manual or your TCP/IP supplier's documentation.
  7. Configure the OpenVMS Registry as follows:
  8. Start OpenVMS Registry by running the REG$STARTUP.COM file.
  9. If you want to run DCE, start DCE now.

    Note

    You do not need DCE to run COM for OpenVMS, but if your environment uses DCE, HP recommends that you start DCE now.

    For this procedure, see the Compaq DCE Installation and Configuration Guide.
    For more information about OpenVMS external authentication, see Section 5.1.
  10. Configure HP Advanced Server for OpenVMS. You may need to reboot, depending on your system configuration. For this procedure, see the HP Advanced Server for OpenVMS Server Installation and Configuration Guide.
  11. Start HP Advanced Server for OpenVMS (set up for startup on reboot). For this procedure, see the HP Advanced Server for OpenVMS Server Installation and Configuration Guide.
  12. Start the ACME server. Use the following command:


      $ @SYS$STARTUP:NTA$STARTUP_NT_ACME 
    

  13. Start RPC. Use the following command:


      $ @SYS$STARTUP:DCE$RPC_STARTUP.COM 
    

  14. Configure COM for OpenVMS. For this procedure, see Section 4.12 and Section 6.2.
  15. Edit the SYS$MANAGER:SYLOGICALS.COM file and add the following line:


      $ DEFINE DCOM$TO_BE_STARTED TRUE 
    

  16. Start COM for OpenVMS. For this procedure, see Section 4.13.

4.5 Upgrading COM for OpenVMS on an OpenVMS Standalone System

Note

Before you start, HP recommends that you disable any HP Advanced Server for OpenVMS, OpenVMS Registry, and layered product automatic startups so that these products do not start until you have upgraded COM for OpenVMS and its associated components.

Use the following procedure:

  1. Edit the SYLOGICALS.COM file to stop the following products from starting:
    • OpenVMS Registry (comment the line DEFINE/SYSTEM REG$TO_BE_STARTED TRUE )
    • COM for OpenVMS (comment the line DEFINE DCOM$TO_BE_STARTED TRUE )
  2. Edit the SYS$STARTUP:SYSTARTUP_VMS.COM file to stop the following products from starting:
    • HP Advanced Server for OpenVMS (comment the line @SYS$STARTUP:PWRK$STARTUP.COM ).

If COM for OpenVMS is currently running, shut down COM for OpenVMS first, HP Advanced Server for OpenVMS (if running), and then the OpenVMS Registry.

Use the following procedure:

  1. Upgrade to OpenVMS Version 7.3-1 or higher. For this procedure, see the OpenVMS Alpha Version 7.x Upgrade and Installation Manual.
  2. If you need to upgrade TCP/IP, upgrade TCP/IP now. For this procedure, see the HP TCP/IP Services for OpenVMS Installation and Configuration manual or your TCP/IP supplier's documentation.
  3. Boot the upgraded system from the system disk.
  4. Upgrade COM for OpenVMS. For this procedure, see Section 4.11.
  5. Install or upgrade HP Advanced Server for OpenVMS. For this procedure, see the HP Advanced Server for OpenVMS Server Installation and Configuration Guide.
  6. Start TCP/IP unless you have enabled TCP/IP to start on a reboot. For this procedure, see the HP TCP/IP Services for OpenVMS Installation and Configuration manual or your TCP/IP supplier's documentation.
  7. Start the OpenVMS Registry unless you have enabled the OpenVMS Registry to start on a reboot.
  8. If you want to run DCE, start DCE now.

    Note

    You do not need DCE to run COM for OpenVMS, but if your environment uses DCE, HP recommends that you start DCE now.

    For this procedure, see the Compaq DCE Installation and Configuration Guide.
    For more information about OpenVMS external authentication, see Section 5.1.
  9. Configure HP Advanced Server for OpenVMS. You may need to reboot, depending on your system configuration. For this procedure, see the HP Advanced Server for OpenVMS Server Installation and Configuration Guide.
  10. Start HP Advanced Server for OpenVMS (set up for startup on reboot). For this procedure, see the HP Advanced Server for OpenVMS Server Installation and Configuration Guide.
  11. Start the ACME server. Use the following command:


      $ @SYS$STARTUP:NTA$STARTUP_NT_ACME 
    

  12. Start RPC. Use the following command:


      $ @SYS$STARTUP:DCE$RPC_STARTUP.COM 
    

  13. See Appendix D for detailed information about upgrading from COM Version 1.0 for OpenVMS to COM Version 1.4 for OpenVMS.
  14. Configure COM for OpenVMS. For this procedure, see Section 4.12 and Section 6.2.
  15. Edit the SYLOGICALS.COM file and add the following line:


      $ DEFINE DCOM$TO_BE_STARTED TRUE 
    

  16. Start COM for OpenVMS. For this procedure, see Section 4.13.

4.6 Installing COM for OpenVMS on an OpenVMS Cluster

Note

This cluster installation procedure assumes you are installing COM for OpenVMS on a single system disk.

Use the following procedure:

  1. Install OpenVMS Version 7.3-1 or higher on all system disks as required. For this procedure, see the OpenVMS Alpha Version 7.x Upgrade and Installation Manual.
  2. Install TCP/IP. For this procedure, see the HP TCP/IP Services for OpenVMS Installation and Configuration manual or your TCP/IP supplier's documentation.
  3. Boot the installed system from the system disk.
  4. Install COM Version 1.4 for OpenVMS. For this procedure, see Section 4.11.
  5. Install HP Advanced Server for OpenVMS on this node in the cluster. For this procedure, see the HP Advanced Server for OpenVMS Server Installation and Configuration Guide.

    Note

    You must install HP Advanced Server for OpenVMS on at least one Alpha node in the cluster. On the other nodes, you can either install HP Advanced Server for OpenVMS or select External Authentication images (only) .
  6. Configure TCP/IP (set up for startup on reboot on each node) and start TCP/IP. You must configure the PWIP driver for HP Advanced Server for OpenVMS to use TCP/IP. For information about configuring TCP/IP, see the HP TCP/IP Services for OpenVMS Installation and Configuration manual or your TCP/IP supplier's documentation.
  7. Configure the OpenVMS Registry:
  8. Configure DCE.

    Note

    You do not need DCE to run COM for OpenVMS, but if your environment uses DCE, HP recommends that you start DCE now.

    For this procedure, see the Compaq DCE Installation and Configuration Guide.
  9. If you want to run DCE, start DCE now. You must configure DCE on each node on which you want to run DCE.
    For more information about OpenVMS external authentication, see Section 5.1.
  10. Configure and start HP Advanced Server for OpenVMS. For this procedure, see the HP Advanced Server for OpenVMS Server Installation and Configuration Guide.
    If this node is running HP Advanced Server for OpenVMS, set up HP Advanced Server for OpenVMS for startup on reboot (edit the SYS$MANAGER:SYSTARTUP_VMS.COM file as necessary).
    If this node is not running HP Advanced Server for OpenVMS, edit the SYLOGICALS.COM file and define the PWRK$ACME_SERVER logical. For this procedure, see the HP Advanced Server for OpenVMS Server Installation and Configuration Guide. For more information about the PWRK$ACME_SERVER logical, see Table 8-2.
  11. Start the ACME server. Use the following command:


      $ @SYS$STARTUP:NTA$STARTUP_NT_ACME 
    

  12. Start RPC. Use the following command:


      $ @SYS$STARTUP:DCE$RPC_STARTUP.COM 
    

  13. Configure COM for OpenVMS. For this procedure, see Section 4.12 and Section 6.2.
  14. Edit the SYLOGICALS.COM file and add the following line:


      $ DEFINE DCOM$TO_BE_STARTED TRUE 
    

  15. Start COM for OpenVMS. For this procedure, see Section 4.13.

4.7 Upgrading COM for OpenVMS in an OpenVMS Cluster

Note

This cluster upgrade procedure assumes you are installing COM for OpenVMS on a single system disk.

Note

Before you start, HP recommends that you disable any HP Advanced Server for OpenVMS and layered products automatic startups so these products do not start until you have upgraded COM for OpenVMS and its associated components.

Use the following procedure:

  1. Edit the SYLOGICALS.COM file to stop the following products from starting:
    • OpenVMS Registry (comment the line DEFINE/SYSTEM REG$TO_BE_STARTED TRUE )
    • COM for OpenVMS (comment the line DEFINE DCOM$TO_BE_STARTED TRUE )
  2. Edit the SYS$STARTUP:SYSTARTUP_VMS.COM file to stop the following products from starting:
    • HP Advanced Server for OpenVMS (comment the line @SYS$STARTUP:PWRK$STARTUP.COM )

If COM for OpenVMS is currently running, shut down COM for OpenVMS first, HP Advanced Server for OpenVMS (if running), and then the OpenVMS Registry on all nodes in the cluster.

Use the following procedure:

  1. Upgrade to OpenVMS Version 7.3-1 or higher on all required system disks. For this procedure, see the OpenVMS Alpha Version 7.x Upgrade and Installation Manual.
  2. Upgrade TCP/IP. For this procedure, see the HP TCP/IP Services for OpenVMS Installation and Configuration manual or your TCP/IP supplier's documentation.
  3. Boot the upgraded system from the system disk.
  4. Upgrade to COM Version 1.4 for OpenVMS. For this procedure, see Section 4.11.
  5. Upgrade HP Advanced Server for OpenVMS on this node in the cluster. For this procedure, see the HP Advanced Server for OpenVMS Server Installation and Configuration Guide.

    Note

    You must install HP Advanced Server for OpenVMS on at least one Alpha node in the cluster. On the other nodes, you can either install HP Advanced Server for OpenVMS or select External Authentication images (only) .
  6. Configure TCP/IP (set up for startup on reboot on each node). You must configure the PWIP driver for HP Advanced Server for OpenVMS to use TCP/IP. For information about configuring TCP/IP, see the HP TCP/IP Services for OpenVMS Installation and Configuration manual or your TCP/IP supplier's documentation.
  7. Configure the OpenVMS Registry as follows:
  8. Configure and start HP Advanced Server for OpenVMS. For this procedure, see the HP Advanced Server for OpenVMS Server Installation and Configuration Guide.
    If this node is running HP Advanced Server for OpenVMS, set up HP Advanced Server for OpenVMS for startup on reboot (edit the SYS$STARTUP file as necessary).
    If this node is not running HP Advanced Server for OpenVMS, edit the SYLOGICALS.COM file and define the PWRK$ACME_SERVER logical. For this procedure, see the HP Advanced Server for OpenVMS Server Installation and Configuration Guide. For more information about the PWRK$ACME_SERVER logical, see Table 8-2.
  9. Start the ACME server. Use the following command:


      $ @SYS$STARTUP:NTA$STARTUP_NT_ACME 
    

  10. Start RPC. Use the following command:


      $ @SYS$STARTUP:DCE$RPC_STARTUP.COM 
    

  11. See Appendix D for detailed information about upgrading from COM Version 1.0 for OpenVMS to COM Version 1.4 for OpenVMS.
  12. Configure COM for OpenVMS. For this procedure, see Section 4.12 and Section 6.2.
  13. Edit the SYLOGICALS.COM file and add the following line:


      $ DEFINE DCOM$TO_BE_STARTED TRUE 
    

  14. Start COM for OpenVMS on a particular node. For this procedure, see Section 4.13.

4.8 Defining Shortcut Commands for COM for OpenVMS

COM for OpenVMS provides a command procedure that defines shortcut commands for many regular COM commands.

Add the following command to your login command procedure, or execute the command line after logging in:


$  @SYS$STARTUP:DCOM$DEFINE_COMMANDS.COM 

SYS$STARTUP:DCOM$DEFINE_COMMANDS.COM defines the following commands:


$ DCOMSTA*RT    :== @SYS$STARTUP:DCOM$STARTUP.COM               
$ DCOMSTO*P     :== @SYS$STARTUP:DCOM$SHUTDOWN.COM              
$ DCOMSTOPN*O   :== @SYS$STARTUP:DCOM$SHUTDOWN.COM NOCONFIRM    
$ DCOMSE*TUP    :== @SYS$STARTUP:DCOM$SETUP.COM                 
$ DCOMC*NFG     :== $SYS$SYSTEM:DCOM$CNFG.EXE                   
$ DCOMT*OOL     :== $SYS$SYSTEM:DCOM$TOOL.EXE                   
$ NTLOG*ON      :== $SYS$SYSTEM:NTA$LOGON.EXE 
$ DCOMOUT       :== TYPE/PAGE SYS$MANAGER:DCOM$RPCSS.OUT 
$ DCOMEV*ENTS   :== TYPE/PAGE SYS$MANAGER:DCOM$EVENTLOG.RPT 
$ DCOMVER       :== $SYS$SYSTEM:DCOM$TOOL.EXE SHOW VERSION      
$ DCOMER*ROR    :== $SYS$SYSTEM:DCOM$TOOL.EXE SHOW ERROR        

4.9 Checking the COM for OpenVMS Version

With COM Version 1.3 or higher for OpenVMS, you can view the currently installed version of COM. To do so, invoke the following command:


$ DCOM$TOOL == "$DCOM$TOOL" 
$ DCOM$TOOL SHOW VERSION 

For more ways to use to the DCOM$TOOL Utility, see Section 7.6.2.

4.10 Understanding the COM for OpenVMS Environment

COM for OpenVMS relies on a number of interrelated servers (processes) and operating system images. In most cases, the servers start automatically when you restart the system. (Automatic startup requires that you have installed and configured each component and have made appropriate changes to the SYLOGICALS.COM file.) For more information about starting and configuring the servers, see Section 4.3.

Figure 4-1 shows the relationships and dependencies of the processes and operating system layers.

Figure 4-1 Interrelationships Among Processes and Layers


Table 4-1 lists the process names and maps each name to its corresponding server.

Table 4-1 Process Name to Server Name Mapping
Process name Server name For more information
DCOM$RPCSS COM for OpenVMS Service Control Manager (SCM) Section 4.10.1
REGISTRY_SERVER OpenVMS Registry server Section 4.10.2
PWRK xxx HP Advanced Server for OpenVMS server (multiple processes) Section 4.10.3
ACME_SERVER ACME server Section 4.10.4
DCE$DCED RPC endpoint mapper Section 4.10.5

The following sections list and describe the servers and the layers.

4.10.1 COM for OpenVMS Service Control Manager (SCM)

The COM for OpenVMS Service Control Manager enables COM for OpenVMS.

Process name: DCOM$RPCSS

Requires: OpenVMS Registry, OpenVMS (RPC and SSPI/NTLM layers)

Required by: COM applications

Configured by: DCOM$SETUP. See Section 6.2.

Started by: DCOM$SETUP, option 4. See Section 6.2.

Shutdown procedure: DCOM$SETUP, option 5. See Section 6.2.

4.10.2 OpenVMS Registry Server

The OpenVMS Registry server manages the OpenVMS Registry database.

Process name: REGISTRY_SERVER

Requires: None.

Required by: COM for OpenVMS, HP Advanced Server for OpenVMS

Configured by: REG$CONFIG.

Started by: REG$STARTUP. See Section 13.2.1.

Shutdown procedure: SET SERVER REGISTRY_SERVER/EXIT. For more information, see Section 13.3.

4.10.3 HP Advanced Server for OpenVMS Server

The HP Advanced Server for OpenVMS server enables OpenVMS to act as a Windows NTLM domain controller.

The ACME server requires the PWRK$MSV1_0_ACMESHR ACME agent image to talk with the local or remote PWRK$LMSRV process.

Requires: OpenVMS Registry

Required by: ACME server

Configured by: PWRK$CONFIG

Started by: PWRK$STARTUP

Shutdown procedure: PWRK$SHUTDOWN

For more information, see the HP PATHWORKS for OpenVMS (Advanced Server) Server Migration Guide.

4.10.4 ACME Server

The ACME server controls the granting of credentials.

Process name: ACME_SERVER

Requires: HP Advanced Server for OpenVMS

Required by: OpenVMS (RPC and SSPI/NTLM layers) and OpenVMS Events

Started:

Shutdown procedures (both are valid):


$ SET SERVER ACME /CANCEL /EXIT


$ SET SERVER ACME /DISABLE /CANCEL
$ SET SERVER ACME /ENABLE=(NAME=VMS)

For more information, see Section 8.3.2.

4.10.5 RPC Endpoint Mapper

The RPC endpoint mapper controls authentication and security.

Process name: DCE$DCED

Requires: RPC image

Required by: COM for OpenVMS Service Control Manager, RPC image

Started by: OpenVMS

Shutdown procedure: Use the following command procedure:


  $ @SYS$STARTUP:DCE$RPC_SHUTDOWN.COM 

For more information, see the Compaq DCE Installation and Configuration Guide.

4.10.6 RPC and SSPI/NTLM Layers

The RPC and SSPI/NTLM layers provides remote procedure call and Windows-style authentication on OpenVMS.

Process name: n/a (part of OpenVMS operating system)

Requires: OpenVMS, ACME server

Required by: COM for OpenVMS

Started by: OpenVMS

Shutdown procedure: n/a

4.10.7 OpenVMS Events

The Events layer provides Windows-style event logging on OpenVMS.

Process name: n/a (part of OpenVMS operating system)

Requires: ACME server

Required by: COM for OpenVMS

Started by: OpenVMS

Shutdown procedure: n/a

For more information, see Chapter 15.

4.11 Installing COM for OpenVMS

The COM for OpenVMS installation kit contains a single POLYCENTER Software Installation utility file. The name of the kit is DEC-AXPVMS-DCOM-V0104--1.PCSI . You must install the COM for OpenVMS files on an OpenVMS Alpha system. Please check the prerequisites before installing the kit. See Section 4.2.

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


 $ PRODUCT INSTALL DCOM /SOURCE=device:[directory] 

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

MIDL compiler license no longer required

The COM for OpenVMS MIDL compiler no longer requires the DCOM-MIDL license.

Example 4-1 shows a sample installation.

Example 4-1 Sample COM for OpenVMS Installation

$ product install dcom/source=disk:[directory] 
 
The following product has been selected: 
    DEC AXPVMS DCOM V1.4                   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 V1.4 
 
 Copyright © 2004 Hewlett-Packard Development Company, L.P. All rights reserved. 
 
Do you want the defaults for all options? [YES] 
 
    The following software is required to run COM for HP OpenVMS 
 
      - HP OpenVMS Alpha V7.3-1 or later 
        * Includes DCE RPC and OpenVMS Registry 
          (The most recent DCE$LIB_SHR.EXE available is 
           required for interoperating with Windows 2000.) 
      - HP TCP/IP Services V5.0 or later for HP OpenVMS (or equivalent product) 
      - HP Advanced Server V7.3 or later for HP OpenVMS 
 
    Do you want to continue? [YES] 
 
Do you want to review the options? [NO] 
 
Execution phase starting ... 
 
The following product will be installed to destination: 
    DEC AXPVMS DCOM V1.4                   DISK$FINALKES:[VMS$COMMON.] 
 
Portion done: 
0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100% 
 
The following product has been installed: 

4.12 COM for OpenVMS Postinstallation Procedures

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

  1. Verify that the OpenVMS Registry is running. (See Chapter 13.)
  2. Verify that the HP Advanced Server for OpenVMS is running. (See Section 4.10.3 for the HP Advanced Server for OpenVMS process names.)
  3. Verify that the ACME server is running. (See Section 4.10.4 for the name of this process.)
  4. Verify that the RPC daemon is running. (See Section 4.10.5 for the name of the process.)
  5. Populate the OpenVMS Registry with the required COM for OpenVMS keys and values using the DCOM$SETUP utility, option 3. (See Section 6.2.) You must do this only once in an OpenVMS Cluster.
  6. Configure the DCOM$RPCSS account using the DCOM$SETUP utility, option 8. (See Section 6.2.1.) You must do this only once in an OpenVMS Cluster.
  7. Start COM for OpenVMS using the DCOM$SETUP utility, option 4. (See Section 6.2.) You must do this on every node in an OpenVMS Cluster.
  8. If you want COM for OpenVMS to start automatically when the system reboots, modify the DEFINE DCOM$TO_BE_STARTED line in the SYLOGICALS.COM file. (See Section 4.13.1.) You must do this on every node in an OpenVMS Cluster.
  9. Configure COM for OpenVMS security. See Chapter 5.

4.13 Starting COM for OpenVMS (COM for OpenVMS Service Control Manager)

Use the following command to start COM for OpenVMS:


  $ @SYS$STARTUP:DCOM$STARTUP 

Alternately, you can run DCOM$SETUP and choose option 4. (See Section 6.2.)

The COM for OpenVMS Service Control Manager can be in one of the following states: initializing/running or not started. Depending on the COM for OpenVMS Service Control Manager state, you will see one of the following messages:

4.13.1 Starting COM for OpenVMS Automatically after a Reboot

HP recommends that you modify the SYS$MANAGER:SYLOGICALS.COM command file to control COM for OpenVMS startup.

OpenVMS includes a revised SYLOGICALS.TEMPLATE file that includes new startup commands for COM for OpenVMS and related components. Review the "Coordinated Startup" section of this template file and add the appropriate information to your existing startup files.

To have COM for OpenVMS start automatically when the system boots, copy the following line to your SYLOGICALS.COM file, uncomment the line, and make sure it is set to TRUE :


$ DEFINE DCOM$TO_BE_STARTED TRUE 

If you do not set COM for OpenVMS to start automatically when the system boots, you can start COM for OpenVMS using the DCOM$SETUP OpenVMS COM Tools menu, option 4 (see Section 6.2).

4.14 Shutting Down COM for OpenVMS (COM for OpenVMS Service Control Manager)

Use the following command to shut down COM for OpenVMS:


  $ @SYS$STARTUP:DCOM$SHUTDOWN 

Alternately, you can run DCOM$SETUP and choose option 5. (See Section 6.2.)

The COM for OpenVMS Service Control Manager can be in one of the following states: stopped, running, or initializing. Depending on the COM for OpenVMS Service Control Manager state, you will see one of the following messages:

4.14.1 Suppressing the DCOM$SHUTDOWN Confirmation Request

You can suppress the DCOM$SHUTDOWN command confirmation request by specifying the NOCONFIRM parameter. Use the following command:


   $ @SYS$STARTUP:DCOM$SHUTDOWN NOCONFIRM 

The system displays the following shutdown messages without prompting you to confirm the shutdown:


        ***  DCOM system shutdown procedure  *** 
 
   Terminating DCOM Service Control Manager daemon (DCOM$RPCSS) . . . 
 
        ***  DCOM shutdown successful  *** 
 
     ***  DCOM Shutdown Procedure Complete  *** 


Next Contents Index