Document revision date: 19 July 1999

Contains COM for OpenVMS, OpenVMS Registry, and OpenVMS Events information

Order Number: AA-RF02B-TE

This document contains information about 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 is an updated manual.

Software Version: OpenVMS Alpha Version 7.2-1
Microsoft Windows NT 4.0 SP3

Compaq Computer Corporation
Houston, Texas

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

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

© Digital Equipment Corporation 1999. All rights reserved.

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.

Compaq, the Compaq logo, and the DIGITAL logo are registered in the U.S. Patent and Trademark Office.

Alpha, AlphaServer, AlphaStation, DEC, DIGITAL, OpenVMS, POLYCENTER, Tru64, VAX, VMS, are trademarks of Compaq Computer Corporation.

COMPAQ, the Compaq logo, and the DIGITAL logo are registered in the U. S. Patent and Trademark Office.

The following are third-party trademarks:

• ActiveX, Microsoft, MS, MS-DOS, Win32, Windows, and Windows NT are registered trademarks, and NT, Windows 95, and Windows 98 are trademarks of Microsoft Corporation.
• Adobe, Display POSTSCRIPT, and POSTSCRIPT are registered trademarks of Adobe Systems Incorporated.
• Apple, Mac, Macintosh, and Power Macintosh are registered trademarks of Apple Computer, Inc.
• AT&T is a registered trademark of the American Telephone and Telegraph Company.
• Motif, OSF/1, UNIX and the "X" device are registered trademarks, and IT DialTone, X/Open, and The Open Group are trademarks, of The Open Group in the U.S. and other countries.
• Unicode is a registered trademark of Unicode, Inc.
• Wind/U is a registered trademark of Bristol Technology, Inc.

Other product names mentioned herein may be the trademarks of their respective companies.

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

ZK6539

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

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

6-JUL-1999 09:52:00.42

Contents

Index

Intended Audience

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

• COM for OpenVMS developers: those who are encapsulating existing OpenVMS applications or data, as well as those who are creating new COM applications for OpenVMS systems.
• OpenVMS Registry developers: those who want to use the OpenVMS Registry to store information about their OpenVMS systems alone, or who want to use the OpenVMS Registry as a shared repository for both OpenVMS and Windows NT registry information.

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

• Release notes
  COM for OpenVMS, OpenVMS Registry, and OpenVMS Events release notes.
• Part I
  COM for OpenVMS information, including installing, configuring, and running COM for OpenVMS; how to develop a COM for OpenVMS application.
• Part II
  OpenVMS Registry information, including OpenVMS Registry overview and concepts, OpenVMS Registry server startup and system management, OpenVMS Registry system services, and OpenVMS Registry server management.
• Part III
  OpenVMS Events information.
• Part IV
  Information about authenticating users and applications between OpenVMS and Windows NT systems.
• Part V
  Reference information, including MIDL compiler information, COM for OpenVMS cookbook examples, COM APIs supported by COM for OpenVMS, how to upgrade from previous versions of COM for OpenVMS, lists of installed files, coupons for related COM books, a glossary, and a list of acronyms.
• Index

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 E, Lists of Differences, APIs, and Interfaces.

Win32 API calls that are not listed in Appendix E 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 E, you must purchase those interfaces from an independent software vendor such as Bristol Technologies (www.bristol.com).

Related Documents

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

www.compaq.com/openvms

Reader's Comments

Compaq welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet	openvmsdoc@compaq.com
Fax	603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail	OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following World-Wide Web address find out how to order additional documentation:

www.compaq.com/openvms

To reach the OpenVMS documentation website, click the Documentation link.

If you need help deciding which documentation best meets your needs, call 800-ATCOMPAQ.

Conventions

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

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

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

The following conventions are also used in this manual:

Ctrl/ x	A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 x	A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
[Return]	In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) In the HTML version of this document, this convention appears as brackets, rather than a box.
...	A horizontal ellipsis in examples indicates one of the following possibilities: Additional optional arguments in a statement have been omitted. The preceding item or items can be repeated one or more times. Additional parameters, values, or other information can be entered.
. . .	A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( )	In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you choose more than one.
[ ]	In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
[|]	In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.
{ }	In command format descriptions, braces indicate required elements; you must choose one of the options listed.
text style	This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason. In the HTML version of this document, this convention appears as italic text.
italic text	Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).
UPPERCASE TEXT	Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
Monospace type	Monospace type indicates code examples and interactive screen displays. In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
-	A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers	All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

The information in the following sections applies to this release.

1.1.1 Upgrading from COM Version 1.0 for OpenVMS to COM Version 1.1 for OpenVMS

If you are upgrading from COM Version 1.0 for OpenVMS to COM Version 1.1 for OpenVMS, please follow the upgrade instructions in Appendix D and Section 4.3.

1.1.2 DCOM$RPCSS Process Resource Exhaustion

The COM for OpenVMS run-time environment requires that the DCOM$RPCSS process is always running.

During testing, Compaq discovered that, after DCOM$RPCSS creates and deletes a large number of COM for OpenVMS application servers, DCOM$RPCSS can run out of resources. If this happens, DCOM$RPCSS automatically attempts to restart itself. If DCOM$RPCSS is not running on your system, or if it appears to be hung, stop and then restart DCOM$RPCSS using the following commands:

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

You can examine the file SYS$MANAGER:DCOM$RPCSS.OUT for error and information messages. You should also check for stale application server processes and stop the processes if necessary.

1.1.3 Floating Point Restriction When Passed by Value Through the IDispatch Interface

Compaq has discovered problems when passing multiple floating point parameters (single or double precision) by value to the IDispatch interface.

Component methods that have multiple floating point parameters will terminate with unexpected behavior if you access them through the IDispatch interface. This error does not occur if you pass the floating point parameters by reference. This limitation will be fixed in a future release.

1.1.4 DECwindows Motif® Required to Run COM for OpenVMS

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

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

1.1.6 MIDL compiler treats wchar_t literals as char

In this release of COM for OpenVMS when using DEC C Version 5.7 or earlier, wide character literal strings in IDL files are incorrectly handled as "char" types. (If you are using DEC C Version 6.0 or above, you can disregard this release note.)

For example, suppose an IDL file contains the following string literal:

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

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

#define PROGRAM_ID ( L"Sample.Component" )

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

#define PROGRAM_ID ( "Sample.Component" )

The following workarounds are available:

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

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

   Caution Do not use this workaround if the IDL source file or any IDL source file imported by the main IDL source file contains any conditional assembly switches (for example, #ifdef" . . . "#endif").

2. Define all character string constants as "char" type instead of "wchar_t" type.
   Using this workaround causes the MIDL compiler on Microsoft Windows NT and on OpenVMS to create character string constants that are not wide characters. If the software requires a wide character string literal, the software can convert the ANSI string to a wide character string before the value is used.
3. Replace the wide character string constants with macro definitions inside the IDL source file.
   For example, instead of defining the string literal as:

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

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

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

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

   #define PROGRAM_ID L"Sample.Component"

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

1.1.8 COM for OpenVMS Security: COM Version 1.0 for OpenVMS and COM Version 1.1 for OpenVMS

The following table summarizes the differences between the COM Version 1.0 for OpenVMS and COM Version 1.1 for OpenVMS releases.

Table 1-1 Summary of Security Differences

Area	COM Version 1.0 for OpenVMS	COM Version 1.1 for OpenVMS
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 run with a pre-specified 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 process-wide 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.1.9 DCOM$CNFG Utility and Disabling Applications: Possible Unintended Side Effects

The COM for OpenVMS DCOM$CNFG utility includes several options that allow a developer to modify application properties (for example, changing the location of the computer on which an application can run). If you select one of these options, you are modifying an OpenVMS Registry entry.

Because the OpenVMS Registry supports a single database in a cluster, modifying one of these options affects all nodes in the cluster that are running COM for OpenVMS.

For example, if you use the System-wide Default Properties submenu option 1 to disable COM for OpenVMS, you effectively disable COM for OpenVMS on the entire cluster. In the same way, if you use the Application Location submenu option 1 to prevent an application from running on this computer, you effectively prevent the application from running on any computer in the cluster.

1.1.10 Threading Model Supported by COM for OpenVMS

COM Version 1.1 for OpenVMS supports only the multithreaded apartment (MTA, also known as free threads) model for application servers. The multithreaded apartment 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.1.11 Change to COM for OpenVMS Service Control Manager Startup and Shutdown

In previous versions of COM for OpenVMS, you could not always tell whether the detached DCOM$RPCSS process was actually running (that is, completed its initialization) or was still initializing.

Compaq has changed the DCOM$RPCSS.EXE image to display different process names, depending on its state. When the DCOM$RPCSS.EXE image is initializing, the process name is "DCOM$STARTUP-**." When the DCOM$RPCSS.EXE image is running, the process name changes to "DCOM$RPCSS." If the process fails and has to restart, the process name changes back to "DCOM$STARTUP-**."

Both DCOM$STARTUP.COM and DCOM$SHUTDOWN.COM have been changed to look for either process name.

For more information about starting COM for OpenVMS, see Section 4.12. For more information about shutting down COM for OpenVMS, see Section 4.13.

1.1.12 CoQueryProxyBlanket() and CoQueryClientBlanket() Do Not Return Valid Principal Name Strings

The CoQueryProxyBlanket() and CoQueryClientBlanket() APIs do not return valid principal name strings. You cannot use these APIs to acquire the principal name.

1.1.13 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 used 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 has updated the registration command files for COM Version 1.1 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]IMAGENAME.EXE

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

1.1.14 SAFEARRAY Limitation

Because the COM for OpenVMS MIDL compiler is based on Microsoft's MIDL compiler V3.00.44, COM for OpenVMS supports the use of SAFEARRAYs only inside a LIBRARY block in an .IDL file. Microsoft's MIDL compiler V3.00.44 has the same limitation.

1.1.15 COM Version 1.0 for OpenVMS and COM Version 1.1 for OpenVMS Not Supported in the Same Cluster

When you install and configure COM Version 1.1 for OpenVMS 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.1.16 You Must Repopulate the OpenVMS Registry for COM Version 1.1 for OpenVMS

For COM Version 1.1 for OpenVMS, 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.1 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

1.1.17 SP4 with Enhanced NTLM Enabled is Not Supported

COM Version 1.1 for OpenVMS supports NT SP4 with the following limitation: COM Version 1.1 for OpenVMS does not support SP4 with enhanced NTLM enabled.

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

Although SP4 and COM for OpenVMS appear to interoperate with SP4 enhanced NTLM disabled, SP4 has not been fully tested with COM for OpenVMS and is not officially supported.

Compaq ongoing SP4 testing has identified the following limitation with SP4 and enhanced NTLM disabled: authentication requests fail if you use passwords that are longer than 12 characters.

1.1.18 Trusted-Domain Authentication Support Patch Kit

This release of COM for OpenVMS does not support trusted domain authentication. Compaq will provide a patch kit to deliver this capability.

Please see the COM for OpenVMS website for information on the kit status. The COM for OpenVMS website is located at:

http://www.openvms.digital.com/openvms/products/dcom/

1.1.19 IGNORE_EXTAUTH Support Patch Kit

This release of COM for OpenVMS does not support the IGNORE_EXTUATH flag in the SECURITY_POLICY system parameter. Compaq will provide a patch to deliver this capability.

Please see the COM for OpenVMS website for information on the patch status. The COM for OpenVMS website is located at:

http://www.openvms.digital.com/openvms/products/dcom/

1.1.20 DCOM$RPCSS Stalls on Restart

If a system running DCOM$RPCSS in a cluster crashes and restarts, the DCOM$RPCSS process may hang during startup. In this condition, the process name remains DCOM$STARTUP-** and the SYS$STARTUP:DCOM$RPCSS.OUT file contains the following error message:

%PPL-W-SYSERROR, system service error -SYSTEM-W-VALNOTVALID, value block is not valid

To recover from this condition, stop the stalled process and restart COM for OpenVMS by entering the following command:

$ @SYS$STARTUP:DCOM$STARTUP

1.1.21 Using COM for OpenVMS between Two OpenVMS Systems

To run COM applications between two OpenVMS systems, both OpenVMS systems must be in the same domain. If the OpenVMS systems are not in the same domain, the authentication on the method calls fails. This restriction does not apply when running applications between OpenVMS and Windows NT systems.

Compaq will provide a patch kit to remove this restriction.

Please see the COM for OpenVMS website for information on the kit status. The COM for OpenVMS website is located at:

http://www.openvms.digital.com/openvms/products/dcom/

1.1.22 Specific Error Messages

The following sections list and describe specific COM for OpenVMS error messages.

1.1.22.1 RPC Cannot Support Failure (800706E4)

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

(800706E4)

This model is not supported in COM Version 1.1 for OpenVMS. For more information, see Section 1.1.10.

1.1.22.2 RPC Server Unavailable Failure (800706BA)

Under certain conditions when you are running a client application on Windows NT and a server application on OpenVMS, you might see the following error:

RPC server unavailable (800706BA)

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

1.1.22.3 RPC WHO_ARE_YOU Failure (EE1282FA)

Under certain conditions when communicating between a client and a server, you might see the following error:

rpc_s_who_are_you_failed (EE1282FA)

If you see this message, retry the operation.

Compaq is working on a patch to resolve this problem.

1.1.22.4 RPC PROTOCOL Failure (800706C0)

Under certain conditions when communicating between a client and a server, you might see the following error:

rpc_s_protocol_error (800706C0)

If you see this message, retry the operation.

Compaq is working on a patch to resolve this problem.

The information in the following sections applies to this release.

2.1.1 No Key Change Notifications When a Key's Attributes are Modified

When you specify the REG$M_CHANGEATTRIBUTES value for the REG$_NOTIFYFILTER item code, the system should notify you of any changes to that OpenVMS Registry key. However, when you modify the attributes of a OpenVMS Registry key, the system fails to notify the processes that have requested notifications.

To correct this problem, specify a different value for the REG$_NOTIFYFILTER item code: use either REG$M_CHANGENAME or REG$M_CHANGELASTSET.

2.1.2 Database Searches Limited

The REG$CP server management utility SEARCH command and calls to the $REGISTRY system service using the REG$FC_SEARCH_TREE_DATA, REG$FC_SEARCH_TREE_KEY, or REG$FC_SEARCH_TREE_VALUE function codes may result in more data being returned to the client than the communications buffers on the client node can handle. These functions are limited to paths that are no more that 16 levels deep and return data of no more than 4 KB.

To avoid this problem, limit the search depth by specifying an exact path---that is, avoid searching the entire database when the database is large.

This restriction will be lifted in a future release.

2.1.3 Key Access Policy

When a user requests access to an OpenVMS Registry key or value, the OpenVMS Registry validates the specified key path by checking the first key and the last key of the key path.

2.1.4 OpenVMS Registry Maximum Data Size Restrictions

The maximum size of any single block of data that can be sent to the OpenVMS Registry server for storage in the OpenVMS Registry database is limited to no more than 7880 bytes. If you exceed this limit, the system displays the following error:

REG-F_NORESPONSE, registry server failed to respond within allotted time period

This limit is imposed by the communication protocol between the OpenVMS Registry server and the OpenVMS Registry client which limits the transfer to 8 K bytes.

This restriction will be lifted in a future release.

2.1.5 REG$_EXQUOTA Errors

If you set the OpenVMS Registry File Quota to be less than the current size of the OpenVMS Registry database, the system displays the following error for all OpenVMS Registry operations:

REG-E-EXQUOTA, registry file quota or page file quota exceeded

As a workaround, you can raise the File Quota temporarily above the current size of the OpenVMS Registry database file, then perform delete operations to bring the OpenVMS Registry database file size within the desired File Quota limit. (For information about changing these quotas, see Section 7.6.3.)

To determine the approximate number of bytes applied towards the two OpenVMS Registry File Quotas, multiply the size of the SYS$REGISTRY:REGISTRY$LOCAL_MACHINE.REG and SYS$REGISTRY:REGISTRY$USERS.REG files by 512. The result of this calculation gives you the approximate number of bytes applied towards quota for each file. For information about how to set OpenVMS Registry file quotas, see Section 2.1.6.

This restriction will be lifted in a future release.

2.1.6 OpenVMS Registry Maximum Database Size Restrictions

The maximum amount of data that can be stored in the OpenVMS Registry database is limited to approximately 1.7 MB. If you exceed this limit, the system displays the following error:

REG-F-DBACCESS, cannot access registry database object

This is a fatal error and prevents further access to the OpenVMS Registry database.

To prevent the REG-F-DBACCESS error, Compaq recommends that you establish quotas to limit the database size so that the OpenVMS Registry can never reach 1.7 MB.

You can establish quotas using either of the following procedures:

• Modify the Default File Quota value.
  Use the following command to set the Default File Quota value:

  $ mcr reg$cp modify value/name="Default File Quota"/type=dword - _$ /data=%D1700000 "hkey_local_machine\system\registry\File Quotas"

• Create or modify the File Quota value on individual OpenVMS Registry database files.
  Use the following command to set individual File Quota values:

  Note If you have previously set File Quota values, use the MODIFY command in place of the CREATE command in the following examples.

  $ mcr reg$cp create value/name=REGISTRY$LOCAL_MACHINE/type=dword - _$ /data=%D1700000 "hkey_local_machine\system\registry\File Quotas" $ mcr reg$cp create value/name=REGISTRY$USERS/type=dword - _$ /data=%D1700000 "hkey_local_machine\system\registry\File Quotas"

You must specify a value for the /DATA qualifier that is between 32,000 and 2,000,000 (0x7D00 and 0x1E8480 hexadecimal).

If you set a value below 32,000, the system will ignore the value and instead use the Default File Quota value of 10,000,000. This Default File Quota value is too high.

If you set a value above 2,000,000, the system generates a REG-F-DBACCESS error when the OpenVMS Registry database size exceeds that value.

This restriction will be lifted in a future release.

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.

Digital Equipment Corporation (now Compaq Computer Corporation) 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 NT, Windows 95^tm, Windows 98, OpenVMS, and Compaq Tru64^tm 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:

• Third-party books on COM:
  • Inside COM/Microsoft's Component Object Model, Dale Rogerson, Microsoft Press, Redmond, WA, 1997. ISBN: 1-57231-349-8.
    The examples in this document are taken from Dale Rogerson's book and are used with the publisher's permission.
  • Essential COM, Don Box, Addison Wesley Longman, Reading, MA, 1998. ISBN: 0-201-63446-5.
    (See Appendix G for a special offer on this book.)
  • Effective COM, Don Box, Keith Brown, Tim Ewald, and Chris Sells, Addison Wesley Longman, Reading, MA, 1998. ISBN: 0-201-37968-6.
    (See Appendix G for a special offer on this book.)
  • DCOM Explained, Rosemary Rock-Evans, Digital Press, Woburn, MA, 1998. ISBN: 1-55558-216-8.
    Provides a good introduction to DCOM and COM, and discusses COM implementations on various platforms.
    (See Appendix G for a special offer on this book.)
  • Understanding ActiveX and OLE, David Chappell, Microsoft Press, Redmond, WA, 1996. ISBN: 1-57231-216-5.
• Websites:
  • The Component Object Model Specification, available from the Microsoft COM website:

    www.microsoft.com/com

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

In support of COM for OpenVMS, Compaq 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 NT.

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 NT system
  The smaller box on the left side of Figure 3-1 represents the Windows NT 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. Advanced Server for OpenVMS
   The Advanced Server for OpenVMS provides authentication of Windows NT users to OpenVMS and provides a connection to the OpenVMS Registry and events viewer for Windows NT users.
3. Windows NT identity/Win32 APIs
   The OpenVMS Security, MSV1_0 ACME agent, Advanced Server for OpenVMS, OpenVMS Registry, event logger, and Win32 APIs (COM APIs) all contribute to the creation of a Windows NT identity within the OpenVMS system.
4. OpenVMS Registry
   The OpenVMS Registry, like the registry on Windows NT 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 NT systems, the event logger on OpenVMS records informational, warning, and error messages about COM events. For detailed information about the OpenVMS Events, see Chapter 11.
6. Windows NT COM stack
   On the Windows NT 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 NT 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 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 12.
8. Connection through RPC layer
   The COM connection between the Windows NT 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 3.4.

OpenVMS now includes a function to get Windows NT credentials. For more information about getting Windows NT credentials through NTA$LOGON, see Section 4.8 and Chapter 12.

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 E.

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

3.3 Using COM for OpenVMS

You can use COM for OpenVMS to do the following:

• Develop new COM for OpenVMS COM applications
• Encapsulate existing applications for use with COM for OpenVMS

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

3.3.1 Developing New Applications

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

• You want to share data between an OpenVMS server and Windows NT clients in a two-tier client/server computing model.
• You want to share data and to place business logic in the middle tier of a three-tier computing environment.
  For example, you might have a Windows NT system as the client so you can take advantage of its graphical user interface. You could write business logic as a collection of COM objects on a middle-tier server; while the third-tier large-capacity, high-availability OpenVMS server provides database access.
• You want to share data between one or more OpenVMS systems or between OpenVMS and other non-Windows systems using COM.

The advantages of using COM for OpenVMS include:

• COM for OpenVMS provides a good programming model for programmers with C++ and object-oriented programming skills.
• COM for OpenVMS provides multivendor interoperability. COM is a standard with implementations available on a number of platforms today, and ports for additional platforms are in development.
• The COM for OpenVMS run-time provides automated data marshaling and unmarshaling.
• COM provides OLE Automation services to support communications with Microsoft Visual Basic® applications. Visual Basic is a very popular programming environment for client/server computing.
• COM provides version support for components so you can upgrade applications over time without breaking existing environments.

See Chapter 6 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.

• User interface
  If you choose to encapsulate the user interface, the UI could be supported on some other platform (for example, from a graphical user interface [GUI] on a Windows NT system).
  Encapsulating and moving the UI to the user's desktop can mean that the rest of the application remains on OpenVMS. Batch processing programs are well suited to user interface encapsulation. Applications that do screen management (for example, SMG or FMS) could have their older character-cell interface encapsulated using COM for OpenVMS, providing users access through newer Windows NT style dialog boxes.
• Database
  If you choose to encapsulate a database using COM for OpenVMS, the database could be accessed from parts of a distributed application running on other platforms. The advantage of this approach is that the programmer can keep the database on OpenVMS (a stable, 24x365 system), while the user interface and data access routines are on remote (and perhaps less reliable) systems.
• Database manipulation routines
  If you choose to encapsulate the database manipulation routines, the routines could be accessed from any other COM component in a heterogeneous computing environment.

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.

3.4 The OpenVMS MIDL Compiler

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

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

	privacy and legal statement
6539PRO.HTML