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 a Previous Version of COM to COM Version 1.1-B for OpenVMS
1.2.1	You Must Repopulate the OpenVMS Registry for COM Version 1.1-B for OpenVMS
1.2.2	Previously Registered Applications That Use Logical Names for the Local Server Path
1.2.3	Changes to the Examples
1.3	Problems Fixed in the Current Release
1.3.1	Memory Leak in COM for OpenVMS Servers
1.3.2	DCOM$RPCSS Process Resource Exhaustion
1.3.3	Passing an Interface Pointer through IDispatch
1.4	Known Problems (with Fixes) in the Current Release
1.4.1	Trusted-Domain Authentication Feature Requires ECO
1.4.1.1	NET3004 Messages Broadcast to Administrator on Windows NT Server System
1.4.1.2	Password Synchronization Errors (NET5716, NET5722, NET5723)
1.4.1.3	Hostmap Problem
1.4.2	DCERPC-E-UNKNOWNREJECT Failure (EE128302)
1.4.3	DCERPC-E-WHOAREYOUFAILED Failure (EE1282FA)
1.4.4	NTARPC-E-PROTOCOL_ERROR Failure (800706C0)
1.4.5	Cached IID Value Not Equal to Registry Value Failure
1.4.6	IGNORE_EXTAUTH Support
1.5	Known Problems (without Fixes) in the Current Release
1.5.1	Kernel Threads and Upcalls Not Supported
1.6	Limitations and Restrictions
1.6.1	DCOM$RPCSS Stalls on Restart
1.6.2	MIDL Limitations and Restrictions
1.6.2.1	MIDL -w Switch
1.6.2.2	MIDL Compiler Treats wchar_t Literals as char
1.6.2.3	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 2000 Limitations
1.6.4.2	COM Version 1.0 for OpenVMS and COM Version 1.1-B for OpenVMS Not Supported in the Same Cluster
1.6.4.3	Remote Activation of an In-Process Server
1.6.4.4	Threading Model Supported by COM for OpenVMS
1.6.4.5	SP4 with Enhanced NTLM Enabled is Not Supported
1.6.4.6	Specifying Activation Security in CoCreateInstanceEx
1.6.4.7	RPC Communication Failures Caused by Advanced Server
1.6.4.8	Specific Error Messages
1.6.4.8.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.1-B 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	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	Required MIDL Switches
7.2.4	Required Include Directories
7.2.5	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.3.5	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
Command 1	NTA$VMSGetMessage
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
Part 2
Part 2	OpenVMS Registry
Chapter 10
10	Overview of OpenVMS Registry
10.1	What is the Registry?
10.1.1	Suggested Reading
10.2	OpenVMS Registry Concepts and Definitions
10.2.1	Keys, Subkeys, and Values
10.2.1.1	Key and Value Volatility
10.2.1.2	Key Write-through and Write-behind
10.2.1.3	Linking a Key to Other Keys and Values
10.2.1.4	Rules for Creating OpenVMS Registry Keys and Value Names
10.2.2	Class
10.2.3	Hive
10.3	OpenVMS Registry Structure
10.4	Reading and Writing to the OpenVMS Registry
10.4.1	$REGISTRY System Services
10.4.2	REG$CP Server Management Utility
10.5	OpenVMS Registry Security
10.5.1	OpenVMS Security Model
10.5.1.1	Granting OpenVMS Registry Access Rights Using the AUTHORIZE Utility
10.5.2	Windows NT Security Model
10.6	Controlling the OpenVMS Registry Server Operations
10.6.1	Defining Maximum Reply Age/Age Checker Interval Settings
10.6.2	Defining the Database Log Cleaner Interval/Initial Log File Size Settings
10.6.3	Defining Default File Quota/File Quota Interval Settings
10.6.4	Defining the Scan Interval Setting
10.6.5	Defining the Log Registry Value Error Setting
10.6.6	Defining the Operator Communications Interval Setting
10.6.7	Defining the Process Time Limit Setting
10.6.8	Defining the Reply Log Cleaner Interval Setting
10.6.9	Defining Snapshot Interval/Snapshot Location/Snapshot Versions Settings
10.6.10	Defining the Write Retry Interval Setting
Chapter 11
11	OpenVMS Registry System Management
11.1	Installing the OpenVMS Registry
11.2	Configuring the OpenVMS Registry: the REG$CONFIG Configuration Utility
11.2.1	Configuring OpenVMS Registry Values
11.3	Starting the OpenVMS Registry
11.3.1	Starting the OpenVMS Registry Manually
11.4	Shutting Down the OpenVMS Registry
11.5	OpenVMS Registry Server Commands
Command 2	SHOW SERVER REGISTRY_SERVER
Command 3	SET SERVER REGISTRY_SERVER
11.6	OpenVMS Registry Failover in a Cluster
11.6.1	Changing the Priority of OpenVMS Registry Server Processes
11.7	Connecting to the OpenVMS Registry from a Windows NT System
11.8	OpenVMS Registry Quotas
11.9	OpenVMS Registry Security
11.10	Backing Up and Restoring the OpenVMS Registry Database
11.11	Using the OpenVMS Registry in an OpenVMS Alpha Mixed-Version Cluster
11.12	Internationalization and Unicode Support
Chapter 12
12	OpenVMS Registry Server Management
12.1	Managing the OpenVMS Registry Server from the Command Line
12.2	Backing Up and Restoring the OpenVMS Registry Database
12.2.1	Creating a Snapshot of the OpenVMS Registry Database
12.2.2	Restoring a Snapshot of the OpenVMS Registry Database
12.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 13
13	OpenVMS Registry System Services
Command 23	$REGISTRY and $REGISTRYW
Part 3
Part 3	OpenVMS Events
Chapter 14
14	OpenVMS Events
14.1	What are Events?
14.1.1	Suggested Reading
14.2	Overview of OpenVMS Events
14.2.1	Viewing OpenVMS Events Using Windows NT Event Viewer
14.2.2	Viewing OpenVMS Events Using Advanced Server for OpenVMS Event Viewer
14.2.3	Event Logging on OpenVMS Only
Command 24	NTA$EVENTW
14.3	Writing Your Own Events
14.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.1-B 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.1-B for OpenVMS
D.2.2	Changing Application Security Settings in the OpenVMS Registry
D.2.2.1	COM Application Registry Keys
Appendix E
Appendix E	Running COM Version 1.1-B for OpenVMS in an Unauthenticated Mode
E.1	Installing COM V1.1-B for OpenVMS to Run in Unauthenticated Mode
E.2	Configuring COM V1.1-B for OpenVMS to Run in Unauthenticated Mode
E.2.1	Define the DCOM$UNAUTHENTICATED Logical Systemwide
E.2.2	Populate the OpenVMS Registry
E.2.3	Create the DCOM$GUEST Account
E.2.4	Create the DCOM$RPCSS Account
E.3	Configuring Windows NT to Interoperate with Unauthenticated COM
E.3.1	Setting the Windows NT Systemwide Authentication Level
E.3.2	Setting Windows NT Application Security Properties
E.3.3	Setting the Windows NT Application Security Identity
E.4	Expected Failures from CLIENTAUTH Sample Program
E.5	Converting from Unauthenticated Mode to Authenticated Mode