|
HP OpenVMS Systems Documentation |
|
OpenVMS Connectivity Developer GuideContains COM for OpenVMS, OpenVMS Registry, and OpenVMS Events information
July 2000
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:
COM Version 1.1-B for OpenVMS
July 2000 © 2000 Compaq Computer Corporation COMPAQ, VAX, VMS, the Compaq logo, and the DIGITAL logo Registered in U.S. Patent and Trademark Office. OpenVMS is a trademark of Compaq Information Technologies Group, L.P. ActiveX, Microsoft, MS, MS-DOS, Visual Studio, Win32, Windows, and Windows NT are registered trademarks, and NT, Windows 95, and Windows 98 are trademarks of Microsoft Corporation. Motif, OSF/1, and UNIX are trademarks of The Open Group. Wind/U is a registered trademark of Bristol Technology, Inc. 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. All other product names mentioned herein may be the trademarks or registered trademarks of their respective companies.
This product includes software licensed from Microsoft Corporation.
This product includes software licensed from Bristol Technology, Inc.
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 subject to change without notice. The Compaq OpenVMS documentation set is available on CD-ROM.
ZK6539
26-OCT-2000 12:55:37.51
PrefaceIntended AudienceThis 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:
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 StructureThis 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:
Win32 API Calls Shown in Example CodeWin32® 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 DocumentsFor additional information on the Open Systems Software Group (OSSG) products and services, access the Compaq OpenVMS World-Wide Web site with the following address:
Reader's CommentsCompaq welcomes your comments on this manual. Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:
How To Order Additional DocumentationUse the following World-Wide Web address find out how to order additional documentation:
To reach the OpenVMS documentation website, click the Documentation link. If you need help deciding which documentation best meets your needs, call 800-ATCOMPAQ. ConventionsIn 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:
Chapter 1
|
| Area | Unauthenticated COM (V1.0, V1.1-B) | Authenticated COM (V1.1, V1.1-A, V1.1-B) |
|---|---|---|
| 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. |
If you are upgrading from an earlier version of COM for OpenVMS to Version 1.1-B, follow the upgrade instructions in Section 4.3. In addition:
If you are upgrading from COM Version 1.1-A for OpenVMS, you do not need to repopulate the OpenVMS Registry. |
For COM Version 1.1-B 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-B 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
|
Repopulating the OpenVMS registry does not affect the registration of existing COM applications. |
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 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.3 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 the Current Release
The following notes describe previously documented problems that have
been fixed in COM Version 1.1-B for OpenVMS.
1.3.1 Memory Leak in COM for OpenVMS Servers
In previous versions of COM for OpenVMS, the MIDL compiler generated server proxy code that caused memory to be allocated and not released for certain types of method calls. This resulted in memory leaks in server applications. Testing by Compaq has shown that this problem occurs if the parameter list for any method call includes user defined structures as input parameters, and either FLOAT or DOUBLE datatypes. If you think your COM for OpenVMS server may have this problem, recompile your .IDL file using the new MIDL compiler, recompile the generated files, and relink your application.
If you discovered this problem, you may have compensated for it by
deallocating the structures directly, even though COM programming rules
state that you do not have to deallocate input parameters. If so, you
should remove your workaround and rebuild the application as directed
in the preceding paragraph.
1.3.2 DCOM$RPCSS Process Resource Exhaustion
The COM for OpenVMS run-time environment requires that the DCOM$RPCSS process is always running.
In previous versions of COM for OpenVMS, 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.
This limitation has been corrected.
1.3.3 Passing an Interface Pointer through IDispatch
In previous versions of COM for OpenVMS, passing an interface
pointer as a parameter through the IDispatch interface produced an
access violation error. This problem has been corrected.
1.4 Known Problems (with Fixes) in the Current Release
The following notes describe the known problems associated with COM
Version 1.1-B for OpenVMS. These problems can be corrected by
obtaining ECOs or updates from the Compaq Support Centers.
1.4.1 Trusted-Domain Authentication Feature Requires ECO
Compaq has discovered a number of problems associated with COM
applications running between systems in different domains with trusts
established between the domains. Some of these problems can be
corrected by installing the Advanced Server for OpenVMS V7.2-A-ECO1
kit. Please contact your Compaq Support Center and ask for this kit.
Other problems that may still occur are listed in the following
sections. If you experience these problems, please contact your Compaq
Support Center for additional information.
1.4.1.1 NET3004 Messages Broadcast to Administrator on Windows NT Server System
When COM applications are run between systems in trusted domains, one
or both of the systems may report NET3004 errors and broadcast these
errors to Windows NT systems logged into the Administrator account. The
Administrator will see a popup message box containing the NET3004
error. You can eliminate these broadcasts by stopping the Alerter
Service on the Domain Controller that is generating the messages.
1.4.1.2 Password Synchronization Errors (NET5716, NET5722, NET5723)
Under certain conditions, a Windows NT workstation can lose the ability
to authenticate with an Advanced Server domain controller. If this
happens you will need to remove the workstation from the domain, then
re-add it back to the domain.
1.4.1.3 Hostmap Problem
Under certain conditions, the hostmap entries in a trusted domain can
become invalid. See Section 5.4.6 for a way to resolve this problem.
1.4.2 DCERPC-E-UNKNOWNREJECT Failure (EE128302)
OpenVMS COM clients sometimes report this error when communicating with
NT COM components. This is due to a problem in the RPC Runtime. A fix
for this problem is available from the Compaq Support Centers. Contact
your Support Center and ask for the update to DCE$LIB_SHR.EXE.
1.4.3 DCERPC-E-WHOAREYOUFAILED Failure (EE1282FA)
OpenVMS COM clients sometimes report this error when communicating with
NT COM components. This is due to a problem in the RPC Runtime. A fix
for this problem is available from the Compaq Support Centers. Contact
your Support Center and ask for the update to DCE$LIB_SHR.EXE.
1.4.4 NTARPC-E-PROTOCOL_ERROR Failure (800706C0)
OpenVMS COM clients sometimes report this error when communicating with
NT COM components. This is due to a problem in the RPC Runtime. A fix
for this problem is available from the Compaq Support Centers. Contact
your Support Center and ask for the update to DCE$LIB_SHR.EXE.
1.4.5 Cached IID Value Not Equal to Registry Value Failure
Compaq's testing has shown that OpenVMS processes that run more than
2000 iterations of a COM for OpenVMS application may receive
this error. The error is caused by a bug in the Registry client that
returns a failure status after a process has made over 16,000 OpenKey
requests. A fix for this problem is available from the Compaq Support
Centers. Contact your Support Center and ask for the update to
SYS$NTA.EXE
.
1.4.6 IGNORE_EXTAUTH Support
Support for the IGNORE_EXTAUTH flag in the SECURITY_POLICY SYSGEN
parameter is now available in a patch kit from the Compaq Support
Centers. Contact your Support Center and ask for the update to
VMS$VMS_ACMESHR.EXE.
1.5 Known Problems (without Fixes) in the Current Release
The following notes describe the known problems associated with COM
Version 1.1-B for OpenVMS. These problems currently do not have
fixes.
1.5.1 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.6 Limitations and Restrictions
The following sections contain general release note information.
1.6.1 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 COM for OpenVMS on each node in the cluster using the following command:
$ @SYS$STARTUP:DCOM$SHUTDOWN |
Then restart COM for OpenVMS on each node in the cluster using the following command:
$ @SYS$STARTUP:DCOM$STARTUP |
The following release notes pertain to MIDL.
1.6.2.1 MIDL -w Switch
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.6.2.2 MIDL Compiler Treats wchar_t Literals as char
When using DEC C Version 5.7 or earlier, COM for OpenVMS incorrectly handles wide character literal strings in IDL files. These strings are mishandled 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 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:
$ midl -Oicf -nocpp -idcom$library: server.idl
|
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" ). |
const wchar_t * PROGRAM_ID = L"Sample.Component";
|
cpp_quote("#define PROGRAM_ID L\"Sample.Component\"")
|
#define PROGRAM_ID L"Sample.Component"
|
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.6.3 DCOM$CNFG Limitations and Restrictions
The following release note pertains to
DCOM$CNFG
when run in a cluster.
1.6.3.1 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.6.4 Other Limitations and Restrictions
The following release notes pertain to COM for OpenVMS.
1.6.4.1 Windows 2000 Limitations
Windows 2000 is not supported in COM Version 1.1-B for OpenVMS.
Preliminary results from Compaq's ongoing testing of interoperability
between COM for OpenVMS and Windows 2000 indicate that a
Windows 2000 client can successfully communicate with a COM for
OpenVMS server application. However, authentication problems occur
between a COM for OpenVMS client and a Windows 2000 server.
Full support for Windows 2000 will be available in a future release.
1.6.4.2 COM Version 1.0 for OpenVMS and COM Version 1.1-B for OpenVMS Not Supported in the Same Cluster
When you install and configure COM Version 1.1-B 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.6.4.3 Remote Activation of an In-Process Server
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.6.4.4 Threading Model Supported by COM for OpenVMS
COM Version 1.1-B 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.6.4.5 SP4 with Enhanced NTLM Enabled is Not Supported
COM Version 1.1-B for OpenVMS supports Windows NT SP4 with the following limitation: COM Version 1.1-B for OpenVMS does not support SP4 with enhanced NTLM enabled.
If you want to use COM Version 1.1-B 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's 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.6.4.6 Specifying Activation Security in CoCreateInstanceEx
The pServerInfo parameter of the CoCreateInstanceEx API allows you to specify a username and password that will be used for authentication on the remote server system. The username 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 NT communicating with COM servers
on OpenVMS.
1.6.4.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 Advanced Server for OpenVMS having lost a connection between domain controllers. The Advanced Server for OpenVMS 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 Compaq Support Center.
1.6.4.8 Specific Error Messages
The following sections list and describe specific COM for
OpenVMS error messages.
1.6.4.8.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-B for OpenVMS. For more information, see Section 1.6.4.4.
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 |
You will not see this error message on a single delete operation that brings the size of the OpenVMS Registry database file within quota limits. |
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 10.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:
$ mcr reg$cp modify value/name="Default File Quota"/type=dword - _$ /data=%D1700000 "hkey_local_machine\system\registry\File Quotas" |
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.
A fix for this problem is available from the Compaq Support Centers. Contact your Support Center and ask for the update to REGISTRY$SERVER.EXE.
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
95tm, Windows 98, OpenVMS, and Compaq 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:
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:
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 now includes a function to get Windows NT credentials. For more information about getting Windows NT 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 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 10.
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.
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.1-B for OpenVMS Kit
COM Version 1.1-B for OpenVMS contains the following:
The following software is required:
| Software | Global pages | Global sections | Disk blocks |
|---|---|---|---|
| COM for OpenVMS | 11,000 | 27 | 57000 |
| RPC Runtime | 3,300 | 14 | N/A |
For Advanced Server requirements: See the Advanced Server for OpenVMS Server Installation and Configuration Guide.
For TCP/IP requirements: See the DIGITAL TCP/IP Services for OpenVMS: Installation and Configuration document.
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.
If you are installing DECwindows Motif to meet the COM for OpenVMS requirements only, you do not need the DW-MOTIF license. |
The following sections describe COM Version 1.1-B for OpenVMS installation and upgrade options.
If you want to run COM Version 1.1-B 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. | See Section 4.4. |
| Install COM for OpenVMS on an OpenVMS Cluster system for the first time. | See Section 4.6. |
| Upgrade from earlier versions of COM for OpenVMS on an OpenVMS standalone system. | See Section 4.5. |
| Upgrade from earlier versions of COM for OpenVMS on an OpenVMS Cluster system. | See Section 4.7. |
Use the following procedure:
$ DEFINE/SYSTEM SYS$REGISTRY directory-specification |
You do not need DCE to run COM for OpenVMS, but if your environment uses DCE, Compaq recommends that you start DCE now. |
$ @SYS$STARTUP:NTA$STARTUP_NT_ACME |
$ @SYS$STARTUP:DCE$RPC_STARTUP.COM |
$ DEFINE DCOM$TO_BE_STARTED TRUE |
Before you start, Compaq recommends that you disable any Advanced Server for OpenVMS, OpenVMS Registry, 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:
If COM for OpenVMS is currently running, shut down COM for OpenVMS first, Advanced Server for OpenVMS (if running), and then the OpenVMS Registry. |
Use the following procedure:
You do not need DCE to run COM for OpenVMS, but if your environment uses DCE, Compaq recommends that you start DCE now. |
$ @SYS$STARTUP:NTA$STARTUP_NT_ACME |
$ @SYS$STARTUP:DCE$RPC_STARTUP.COM |
$ DEFINE DCOM$TO_BE_STARTED TRUE |
This cluster installation procedure assumes you are installing COM for OpenVMS on a single system disk. |
Use the following procedure:
You must install Advanced Server for OpenVMS on at least one Alpha node in the cluster. On the other nodes, you can either install Advanced Server for OpenVMS or select External Authentication images (only) . |
$ DEFINE/SYSTEM REG$TO_BE_STARTED FALSE |
You do not need DCE to run COM for OpenVMS, but if your environment uses DCE, Compaq recommends that you start DCE now. |
$ @SYS$STARTUP:NTA$STARTUP_NT_ACME |
$ @SYS$STARTUP:DCE$RPC_STARTUP.COM |
$ DEFINE DCOM$TO_BE_STARTED TRUE |
This cluster upgrade procedure assumes you are installing COM for OpenVMS on a single system disk. |
Before you start, Compaq recommends that you disable any 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:
If COM for OpenVMS is currently running, shut down COM for OpenVMS first, Advanced Server for OpenVMS (if running), and then the OpenVMS Registry on all nodes in the cluster. |
Use the following procedure:
You must install Advanced Server for OpenVMS on at least one Alpha node in the cluster. On the other nodes, you can either install Advanced Server for OpenVMS or select External Authentication images (only) . |
$ DEFINE/SYSTEM SYS$REGISTRY cluster-visible-directory-specification |
$ DEFINE/SYSTEM REG$TO_BE_STARTED FALSE |
$ @SYS$STARTUP:NTA$STARTUP_NT_ACME |
$ @SYS$STARTUP:DCE$RPC_STARTUP.COM |
$ DEFINE DCOM$TO_BE_STARTED TRUE |
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 Processes/Layers Relationships
Table 4-1 lists the process names and maps each name to its corresponding server.
| Process name | Server name | For more information |
|---|---|---|
| DCOM$RPCSS | COM for OpenVMS Service Control Manager (SCM) | Section 4.8.1 |
| REGISTRY_SERVER | OpenVMS Registry server | Section 4.8.2 |
| PWRK xxx | Advanced Server for OpenVMS server (multiple processes) | Section 4.8.3 |
| ACME_SERVER | ACME server | Section 4.8.4 |
| DCE$RPCD | RPC endpoint mapper | Section 4.8.5 |
The following sections list and describe the servers and the layers.
| Next | Contents | Index |