OpenVMS Connectivity Developer Guide

Contents

Preface
Preface	Preface
Chapter 1
1	COM for OpenVMS Release Notes
1.1	COM for OpenVMS Versions
1.2	Upgrading from Earlier Versions of COM for OpenVMS to Version 1.2
1.2.1	PCSI Warning When Upgrading from Version 1.2 Field Test 1 to Field Test 2
1.2.2	Upgrading from Versions Prior to COM Version 1.1-A for OpenVMS Requires You to Repopulate the OpenVMS Registry
1.2.3	C Compiler Requirement Removed
1.2.4	Previously Registered Applications That Use Logical Names for the Local Server Path
1.2.5	Changes to the Examples
1.3	Windows 2000 Interoperability with COM Version 1.2
1.3.1	NTARPC-E-CALL_FAILED_DNE (800706BF) Using IStream
1.3.2	'Invoke call failed' or NTARPC-E-BAD_STUB_DATA Using Automation
1.3.3	ERROR_ACCESS_DENIED (C0000005 or 80070005)
1.3.4	NetBEUI as Listed Protocol in DCOMCNFG
1.3.5	Windows 2000 Clients Inactive for an Extended Period of Time - Reports 'Automation error'
1.3.6	OpenVMS Client Hangs When Trying to Invoke a Server if Machine Name Cannot Be Resolved
1.4	Problems Fixed in the Current Release
1.4.1	Windows 2000 Interoperation Requires Compaq DCE Version 3.0 for OpenVMS
1.4.2	Memory Leak Seen in DCE/RPC Process When Running Between Windows Client and OpenVMS Server in Unauthenticated Mode
1.4.3	Excessive Messages in DCOM$RPCSS.OUT
1.4.4	Marshaling an Interface with More Than 32 Methods
1.4.5	Trusted-Domain Authentication Feature Requires ECO
1.4.6	DCERPC-E-UNKNOWNREJECT Failure (EE128302)
1.4.7	DCERPC-E-WHOAREYOUFAILED Failure (EE1282FA)
1.4.8	NTARPC-E-PROTOCOL_ERROR Failure (800706C0)
1.4.9	Cached IID Value Not Equal to Registry Value Failure
1.4.10	IGNORE_EXTAUTH Support
1.5	Known Problems (without Fixes) in the Current Release
1.5.1	Kernel Threads and Upcalls Not Supported
1.5.2	Errors Seen Between OpenVMS Systems Running COM Version 1.2 Under Heavy Load
1.6	Limitations and Restrictions
1.6.1	DCOM$RPCSS May Stall on Cluster Restart (PPL-W-SYSERROR)
1.6.2	MIDL Limitations and Restrictions
1.6.2.1	MIDL -w Switch
1.6.2.2	SAFEARRAY Limitation
1.6.3	DCOM$CNFG Limitations and Restrictions
1.6.3.1	DCOM$CNFG Utility and Disabling Applications: Possible Unintended Side Effects
1.6.4	Other Limitations and Restrictions
1.6.4.1	Windows XP Not Supported
1.6.4.2	COM Version 1.0 for OpenVMS and COM Version 1.2 for OpenVMS Not Supported in the Same Cluster
1.6.4.3	Threading Model Supported by COM for OpenVMS
1.6.4.4	Enhanced NTLM in Windows NT SP4 and Later Versions Not Supported
1.6.4.5	Specifying Activation Security in CoCreateInstanceEx
1.6.4.6	RPC Communication Failures Caused by Advanced Server
1.6.4.7	Specific Error Messages
1.6.4.7.1	RPC Cannot Support Failure (800706E4)
Chapter 2
2	OpenVMS Registry Release Notes
2.1	Release Notes
2.1.1	No Key Change Notifications When a Key's Attributes are Modified
2.1.2	Database Searches Limited
2.1.3	Key Access Policy
2.1.4	OpenVMS Registry Maximum Data Size Restrictions
2.1.5	REG$_EXQUOTA Errors
2.1.6	OpenVMS Registry Maximum Database Size Restrictions
Part 1
Part 1	COM for OpenVMS
Chapter 3
3	Overview of COM for OpenVMS
3.1	What is COM?
3.1.1	Suggested Reading
3.2	Overview of COM for OpenVMS
3.2.1	How COM for OpenVMS Uses the OpenVMS Registry
3.3	Using COM for OpenVMS
3.3.1	Developing New Applications
3.3.2	Encapsulating Existing Applications
Chapter 4
4	Installing the COM for OpenVMS Kit
4.1	Contents of the COM Version 1.2 for OpenVMS Kit
4.2	Prerequisites
4.2.1	DECwindows Motif Required to Run COM for OpenVMS
4.3	Supported COM for OpenVMS Installations
4.4	Installing COM for OpenVMS on an OpenVMS Standalone System
4.5	Upgrading COM for OpenVMS on an OpenVMS Standalone System
4.6	Installing COM for OpenVMS on an OpenVMS Cluster
4.7	Upgrading COM for OpenVMS in an OpenVMS Cluster
4.8	Understanding the COM for OpenVMS Environment
4.8.1	COM for OpenVMS Service Control Manager (SCM)
4.8.2	OpenVMS Registry Server
4.8.3	Compaq Advanced Server for OpenVMS Server
4.8.4	ACME Server
4.8.5	RPC Endpoint Mapper
4.8.6	RPC and SSPI/NTLM Layers
4.8.7	OpenVMS Events
4.9	Installing COM for OpenVMS
4.10	COM for OpenVMS Postinstallation Procedures
4.11	Starting COM for OpenVMS (COM for OpenVMS Service Control Manager)
4.11.1	Starting COM for OpenVMS Automatically after a Reboot
4.12	Shutting Down COM for OpenVMS (COM for OpenVMS Service Control Manager)
4.12.1	Suppressing the DCOM$SHUTDOWN Confirmation Request
Chapter 5
5	COM for OpenVMS Security
5.1	System Configuration
5.1.1	LOGINOUT.EXE Use of External Authentication
5.1.2	DCE Integrated Login Restriction
5.2	Cross-Domain Configuration
5.3	Acquiring Windows NT Credentials
5.4	Application Security
5.4.1	Launch Security
5.4.2	Activation Security
5.4.3	Server Process Identity
5.4.4	Domain Issues
5.4.5	Disabling Authentication
5.4.6	Access Denied Problems (80070005)
5.5	Server Run-Time Environment
Chapter 6
6	COM for OpenVMS Utilities for Application Development and Deployment
6.1	DCOM$SETUP Utility
6.2	Running DCOM$SETUP
6.2.1	Creating and Configuring DCOM$RPCSS Accounts
6.2.2	Starting and Stopping the COM Server (DCOM$RPCSS Process)
6.2.3	Registering an Application
6.3	Running DCOM$CNFG
6.3.1	The DCOM$CNFG Application List Submenu
6.3.2	Registry Value Permissions Submenus
6.3.3	Registry Key Permissions Submenus
6.3.4	Application Identity Submenu
6.3.5	The DCOM$CNFG System-wide Default Properties Submenu
6.3.6	System-wide Default Security Submenu
6.4	Registering In-Process Servers: DCOM$REGSVR32 Utility
Chapter 7
7	Developing a COM for OpenVMS Application
7.1	Step 1: Generate Unique Identifiers
7.2	Step 2: Build an Application Using the MIDL Compiler
7.2.1	Running the MIDL Compiler
7.2.2	Running the MIDL Compiler with DCOM$RUNSHRLIB
7.2.3	Modifying Your Applications To Use the C++ Only MIDL Compiler
7.2.4	Required MIDL Switches
7.2.5	Required Include Directories
7.2.6	Required Header File
7.3	Step 3: Compile the COM Application
7.3.1	Required Macro Definitions
7.3.2	Required Include Directories
7.3.3	Required Header File: VMS_DCOM.H
7.3.4	Required C++ Qualifiers
7.4	Step 4: Link the COM Application
7.4.1	Linking the Client and the Out-of-Process Component
7.4.2	Linking the In-Process Component Shareable Image
7.4.2.1	Creating a Symbol Vector
7.4.3	Linking the Proxy/Stub Shareable Image
7.4.3.1	Creating a Symbol Vector
7.5	Required OpenVMS Registry Entries
7.5.1	HKEY_CLASSES_ROOT\CLSID
7.5.1.1	Component CLSIDs
7.5.1.2	Proxy/Stub CLSIDs
7.5.2	HKEY_CLASSES_ROOT\Interface
7.6	Converting OpenVMS and Windows Error Codes to Text
7.6.1	NTA$VMSGetMessage
Command 1	NTA$VMSGetMessage
7.6.2	DCOM$TOOL SHOW ERROR
7.6.2.1	DCOM$TOOL Optional Qualifiers
Chapter 8
8	Authentication
8.1	What is Authentication?
8.2	Acquiring Windows NT Credentials Using NTA$LOGON
8.2.1	NTA$LOGON Optional Qualifiers
8.2.2	Examples of Using NTA$LOGON to Acquire Windows NT Credentials
8.3	The Authentication and Credential Management (ACM) Authority
8.3.1	Windows NT Authentication on OpenVMS
8.3.2	Managing the ACME_SERVER Process (ACME Server Commands)
8.3.3	Configuring the MSV1_0 ACME Agent
Chapter 9
9	Active Template Library
9.1	COM for OpenVMS and ATL
9.2	Developing a COM for OpenVMS Application Using ATL
9.2.1	Step 1: Create the ATL Component in Microsoft Visual Studio
9.2.2	Step 2: Modify Generated Files for ATL Applications on OpenVMS
9.2.2.1	Remove _ATL_MIN_CRT
9.2.2.2	Include ATLMAIN.CXX
9.2.2.3	Modify Registration Procedure
9.2.3	Step 3: Build an Application Using the MIDL Compiler
9.2.4	Step 4: Compile the ATL COM Application
9.2.4.1	Required Header File: ATLBASE.H
9.2.4.2	Required Macro Definitions
9.2.4.3	Required Include Directories
9.2.4.4	Required C++ Qualifiers
9.2.5	Step 5: Link the ATL COM Application
9.2.5.1	Linking the Client and the Out of Process Component
9.2.5.2	Linking the In Process Component Shareable Image
9.2.5.3	Creating a Symbol Vector
9.3	ATL Samples
9.3.1	Out of Process COM Sample (TESTATL_OUTPROC)
9.3.1.1	Creating the Application on Windows NT
9.3.1.2	Building, Registering, and Running the Application on OpenVMS
9.3.2	In-Process COM Sample (TESTATL_INPROC)
9.3.2.1	Creating the Application on Windows NT
9.3.2.2	Building, Registering, and Running the Application on OpenVMS
9.4	Suggested Reading
Chapter 10
10	COM for OpenVMS and DLL Surrogates
10.1	Running Your Components in the Context of a DLL Surrogate
10.2	Developing a Surrogate Application
Chapter 11
11	COM for OpenVMS and IEEE Floating Point
11.1	Running Sample Programs with IEEE Floating Point Values
11.2	Restrictions Using IEEE Floating-Point Values in COM for OpenVMS Applications
Part 2
Part 2	OpenVMS Registry
Chapter 12
12	Overview of OpenVMS Registry
12.1	What is the Registry?
12.1.1	Suggested Reading
12.2	OpenVMS Registry Concepts and Definitions
12.2.1	Keys, Subkeys, and Values
12.2.1.1	Key and Value Volatility
12.2.1.2	Key Write-through and Write-behind
12.2.1.3	Linking a Key to Other Keys and Values
12.2.1.4	Rules for Creating OpenVMS Registry Keys and Value Names
12.2.2	Class
12.2.3	Hive
12.3	OpenVMS Registry Structure
12.4	Reading and Writing to the OpenVMS Registry
12.4.1	$REGISTRY System Services
12.4.2	REG$CP Server Management Utility
12.5	OpenVMS Registry Security
12.5.1	OpenVMS Security Model
12.5.1.1	Granting OpenVMS Registry Access Rights Using the AUTHORIZE Utility
12.5.2	Windows NT Security Model
12.6	Controlling the OpenVMS Registry Server Operations
12.6.1	Defining Maximum Reply Age/Age Checker Interval Settings
12.6.2	Defining the Database Log Cleaner Interval/Initial Log File Size Settings
12.6.3	Defining Default File Quota/File Quota Interval Settings
12.6.4	Defining the Scan Interval Setting
12.6.5	Defining the Log Registry Value Error Setting
12.6.6	Defining the Operator Communications Interval Setting
12.6.7	Defining the Process Time Limit Setting
12.6.8	Defining the Reply Log Cleaner Interval Setting
12.6.9	Defining Snapshot Interval/Snapshot Location/Snapshot Versions Settings
12.6.10	Defining the Write Retry Interval Setting
Chapter 13
13	OpenVMS Registry System Management
13.1	Installing the OpenVMS Registry
13.2	Configuring the OpenVMS Registry: the REG$CONFIG Configuration Utility
13.2.1	Configuring OpenVMS Registry Values
13.3	Starting the OpenVMS Registry
13.3.1	Starting the OpenVMS Registry Manually
13.4	Shutting Down the OpenVMS Registry
13.5	OpenVMS Registry Server Commands
Command 2	SHOW SERVER REGISTRY_SERVER
Command 3	SET SERVER REGISTRY_SERVER
13.6	OpenVMS Registry Failover in a Cluster
13.6.1	Changing the Priority of OpenVMS Registry Server Processes
13.7	Connecting to the OpenVMS Registry from a Windows NT System
13.8	OpenVMS Registry Quotas
13.9	OpenVMS Registry Security
13.10	Backing Up and Restoring the OpenVMS Registry Database
13.11	Using the OpenVMS Registry in an OpenVMS Alpha Mixed-Version Cluster
13.12	Internationalization and Unicode Support
Chapter 14
14	OpenVMS Registry Server Management
14.1	Managing the OpenVMS Registry Server from the Command Line
14.2	Backing Up and Restoring the OpenVMS Registry Database
14.2.1	Creating a Snapshot of the OpenVMS Registry Database
14.2.2	Restoring a Snapshot of the OpenVMS Registry Database
14.3	OpenVMS Registry Server Management Utility Syntax
Command 4	CREATE DATABASE
Command 5	CREATE KEY
Command 6	CREATE SNAPSHOT
Command 7	CREATE VALUE
Command 8	DELETE KEY
Command 9	DELETE VALUE
Command 10	EXPORT
Command 11	IMPORT
Command 12	LIST KEY
Command 13	LIST VALUE
Command 14	MODIFY KEY
Command 15	MODIFY VALUE
Command 16	MODIFY TREE
Command 17	SEARCH KEY
Command 18	SEARCH VALUE
Command 19	SHOW
Command 20	START MONITORING
Command 21	STOP
Command 22	ZERO COUNTERS
Chapter 15
15	OpenVMS Registry System Services
Part 3
Part 3	OpenVMS Events
Chapter 16
16	OpenVMS Events
16.1	What are Events?
16.1.1	Suggested Reading
16.2	Overview of OpenVMS Events
16.2.1	Viewing OpenVMS Events Using Windows NT Event Viewer
16.2.2	Viewing OpenVMS Events Using Compaq Advanced Server for OpenVMS Event Viewer
16.2.3	Event Logging on OpenVMS Only
Command 23	NTA$EVENTW
16.3	Writing Your Own Events
16.4	Troubleshooting OpenVMS Events
Part 4
Part 4	Appendixes
Appendix A
Appendix A	MIDL Compiler Options
A.1	Mode
A.2	Input
A.3	Output File Generation
A.4	Output File Names
A.5	C Compiler and Preprocessor Options
A.6	Environment
A.7	Error and Warning Messages
A.8	Optimization
A.9	Miscellaneous
Appendix B
Appendix B	Troubleshooting
B.1	RPC Troubleshooting
B.2	Troubleshooting the ACME server
B.3	Troubleshooting the DCOM$RPCSS Process
B.4	Troubleshooting the Advanced Server for OpenVMS
B.5	Troubleshooting COM for OpenVMS Application Failures
B.5.1	Access Denied Failures
Appendix C
Appendix C	Cookbook Examples: Building a Sample Application on OpenVMS
C.1	COM Example (Sample1)
C.1.1	OpenVMS Instructions
C.1.1.1	Building the Application on OpenVMS
C.1.1.2	Registering the Application on OpenVMS
C.1.1.3	Running the Application on OpenVMS as an Out-of-Process Server
C.1.1.4	Running the Application on OpenVMS and Specifying a Remote Server
C.1.1.5	Running the Application on OpenVMS as an In-Process Server
C.1.2	Windows NT Instructions
C.1.2.1	Building the Application on Windows NT
C.1.2.2	Registering the Application on Windows NT
C.1.2.3	Running the Application on Windows NT
C.2	Automation Example (Dispatch_Sample1)
C.2.1	OpenVMS Instructions
C.2.1.1	Building the Application on OpenVMS
C.2.1.2	Registering the Application on OpenVMS
C.2.1.3	Running the Application on OpenVMS as an Out-of-process Server
C.2.1.4	Running the Application on OpenVMS and Specifying a Remote Server
C.2.1.5	Running the Application on OpenVMS as an In-Process Server
C.2.2	Windows NT Instructions
C.2.2.1	Building the Application on Windows NT
C.2.2.2	Registering the Application on Windows NT
C.2.2.3	Running the Application on Windows NT
C.3	Cross-Domain Security Example (CLIENTAUTH)
C.3.1	OpenVMS Instructions
C.3.1.1	Registering the Application on OpenVMS
C.3.1.2	Running the Application on OpenVMS as an Out-of-Process Server
C.3.1.3	Running the Application on OpenVMS and Specifying a Remote Server
C.3.1.4	Running the Application on OpenVMS as an In-Process Server
C.3.2	Windows NT Instructions
C.3.2.1	Building the Application on Windows NT
C.3.2.2	Registering the Application on Windows NT
C.3.2.3	Running the Application on Windows NT
Appendix D
Appendix D	Upgrading to COM Version 1.2 for OpenVMS from COM Version 1.0 for OpenVMS
D.1	Upgrading from Earlier Versions of COM for OpenVMS
D.1.1	Rebuild Existing COM for OpenVMS Applications
D.1.2	Configuring the Windows NT Systems
D.1.3	Configuring the OpenVMS System
D.2	Previously Configured Applications on Windows NT
D.2.1	You Must Repopulate the OpenVMS Registry for COM Version 1.2 for OpenVMS
D.2.2	Changing Application Security Settings in the OpenVMS Registry
D.2.2.1	COM Application Registry Keys