Document revision date: 15 July 2002
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

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

Order Number: AA-RSCWA-TE

June 2002

This document, formerly titled OpenVMS Connectivity Developer Guide, 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 NT authentication and interoperation.

Revision/Update Information: This manual supersedes the OpenVMS Connectivity Developer Guide, Version 1.1-B.

Software Version: COM Version 1.2 for OpenVMS

Operating System: OpenVMS Alpha Version 7.2-1 or higher
Microsoft Windows NT 4.0 SP5 or higher




Compaq Computer Corporation
Houston, Texas

© 2002 Compaq Information Technologies Group, L.P.

COMPAQ, the Compaq logo, Alpha, OpenVMS, Tru64, VAX, VMS, and the DIGITAL logo are trademarks of Compaq Information Technologies Group, L.P., in the U.S. and/or other countries.

Microsoft, MS-DOS, Visual C++, Windows, and Windows NT are trademarks of Microsoft Corporation in the U.S. and/or 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.

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

All other product names mentioned herein may be trademarks of their respective companies.

Confidential computer software. Valid license from Compaq 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.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

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

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 NT 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 NT 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:

Win32 API Calls Shown in Example Code

Win32 API calls shown in example code throughout this document and included on the COM for OpenVMS kit are provided for documentation purposes only.

COM for OpenVMS includes only those Win32 APIs that the COM for OpenVMS software requires. These COM APIs are listed in Appendix F, Lists of Differences, APIs, and Interfaces.

Win32 API calls that are not listed in Appendix F but that appear in examples in this document and in code samples on the COM for OpenVMS kit are provided by software vendors other than Compaq. If you want to use any Win32 APIs on OpenVMS other than those listed in Appendix F, you must purchase those interfaces from an independent software vendor such as Bristol Technologies ( www.bristol.com ).

Related Documents

For additional information about Compaq OpenVMS products and services, access the Compaq website at the following location: 


http://www.openvms.compaq.com/

Reader's Comments

Compaq welcomes your comments on this manual. Please send comments to either of the following addresses:
Internet openvmsdoc@compaq.com
Mail Compaq Computer Corporation
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How to Order Additional Documentation

Visit the following World Wide Web address for information about how to order additional documentation: 


http://www.openvms.compaq.com/

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 text This typeface represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.
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 text 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
COM for OpenVMS Release Notes

The release notes in this chapter apply to COM Version 1.2 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) Authenticated COM (V1.1, V1.1-A, V1.1-B, V1.2)
Client requests Authenticated on Windows NT; not authenticated on requests to OpenVMS. Authenticated on Windows NT and OpenVMS.
Security Servers can run with the client's identity on Windows NT and with a prespecified OpenVMS identity on OpenVMS. Servers can run with the client's identity on Windows NT and on OpenVMS.
Security Per-method security is allowed on Windows NT, but only processwide security is allowed on OpenVMS. Per-method security is allowed on Windows NT and on OpenVMS.
Outbound COM requests Authenticated on Windows NT only. Authenticated on Windows NT and OpenVMS.
Registry access On Windows NT: controlled by NT credentials.

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

On Windows NT: controlled by NT credentials.

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

Event logging Windows NT only. Windows NT and OpenVMS.

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

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

1.2.1 PCSI Warning When Upgrading from Version 1.2 Field Test 1 to Field Test 2

If you have previously installed COM Version 1.2 Field Test 1 (released June 2001) and are upgrading to COM Version 1.2 Field Test 2 (released February 2002), during the installation you will see a warning from the PCSI Utility. The warning is as follows: 


%PCSI-W-VERLOW, you have selected a lower version of an installed product 
-PCSI-W-VERINS, the installation of product DEC AXPVMS DCOM H1.2 
-PCSI-W-VERREM, will remove current product DEC AXPVMS DCOM V1.2 
Do you want to continue? [YES]

Press Return or enter YES to continue the installation.

This warning occurs because the Version 1.2 Field Test 2 kit is named H1.2, which PCSI considers a lower version than the Version 1.2 Field Test 1 kit, named Version 1.2.

Note
COM for OpenVMS Field Test 1 and the final customer release of COM for OpenVMS Version 1.2 are both referred to as Version 1.2.

1.2.2 Upgrading from Versions Prior to COM Version 1.1-A for OpenVMS Requires You to Repopulate the OpenVMS Registry

Note
If you are upgrading from COM Version 1.1-A for OpenVMS or COM Version 1.1-B for OpenVMS, you do not need to repopulate the OpenVMS Registry.

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 Version 1.2 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 Y[ES] to continue: YES 
 
         The COM for OpenVMS Registry has already been loaded. This 
         action will overwrite the current COM for OpenVMS values 
         and data. 
 
Enter Y[ES] to continue: YES

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

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. As of COM Version 1.2 for OpenVMS, this prerequisite has been 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 DEC C++ Version 6.0 or higher. (You need Compaq C++ Version 6.2-016 or higher to build ATL applications.)

See Section 7.2 for more information on building applications using the MIDL compiler.

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.

Compaq updated the registration command files as of COM Version 1.1-A for OpenVMS.

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: 


  $ MCR 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 on 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 Windows 2000 Interoperability with COM Version 1.2

This section describes issues or problems you might encounter when running Windows 2000 with COM Version 1.2.

1.3.1 NTARPC-E-CALL_FAILED_DNE (800706BF) Using IStream

When running in an authenticated mode, a Windows 2000 client that is passing a buffer greater than 512 bytes and is using the IStream interface might return the following error: 


800706BF error, NTARPC-E-CALL_FAILED_DNE - The remote procedure call failed 
and did not execute

As a temporary workaround, use the IUnknown interface or reduce the size of the buffer.

Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
6539PRO.HTML