|
HP OpenVMS Systems |
|
COM, Registry, and Events for
|
| Contents | Index |
This document is designed primarily for developers who want to use the OpenVMS infrastructure to develop applications that move easily between the OpenVMS and Windows 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 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.
This document, formerly titled OpenVMS Connectivity Developer Guide, contains all the information you need to develop COM for OpenVMS applications and use the OpenVMS Registry. The document is divided into the following sections:
For additional information about HP OpenVMS products and services, visit the following World Wide Web address:
http://www.hp.com/go/openvms |
HP welcomes your comments on this manual. Please send comments to either of the following addresses:
| Postal Mail |
Hewlett-Packard Company
OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698 |
For information about how to order additional documentation, visit the following World Wide Web address:
http://www.hp.com/go/openvms/doc/order |
The following conventions are used in this manual:
| Ctrl/ x | A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button. |
| PF1 x | A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button. |
| [Return] |
In examples, a key name enclosed in a box indicates that you press a
key on the keyboard. (In text, a key name is not enclosed in a box.)
In the HTML version of this document, this convention appears as brackets, rather than a box. |
| ... |
A horizontal ellipsis in examples indicates one of the following
possibilities:
|
|
.
. . |
A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed. |
| ( ) | In command format descriptions, parentheses indicate that you must enclose choices in parentheses if you specify more than one. |
| [ ] | In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement. |
| | | In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line. |
| { } | In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line. |
| bold type | Bold type represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason. |
| italic type | Italic type 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 TYPE | Uppercase type indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege. |
| Example | This typeface indicates code examples, command examples, and interactive screen displays. In text, this type also identifies URLs, UNIX commands and pathnames, PC-based commands and folders, and certain elements of the C programming language. |
| - | 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 release notes in this chapter apply to COM Version 1.4 for OpenVMS.
1.1 COM for OpenVMS Versions
This section describes the versions of COM for OpenVMS.
| Area | Unauthenticated COM (V1.0, V1.1-B, V1.2, V1.3, V1.4) | Authenticated COM (V1.1, V1.1-A, V1.1-B, V1.2, V1.3, V1.4) |
|---|---|---|
| Client requests | Authenticated on Windows; not authenticated on requests to OpenVMS. | Authenticated on Windows and OpenVMS. |
| Security | Servers can run with the client's identity on Windows and with a prespecified OpenVMS identity on OpenVMS. | Servers can run with the client's identity on Windows and on OpenVMS. |
| Security | Per-method security is allowed on Windows, but only processwide security is allowed on OpenVMS. | Per-method security is allowed on Windows and on OpenVMS. |
| Outbound COM requests | Authenticated on Windows only. | Authenticated on Windows and OpenVMS. |
| Registry access |
On Windows: controlled by Windows credentials.
On OpenVMS: relies on OpenVMS security controls such as privileges or rights identifiers. |
On Windows: controlled by Windows credentials.
On OpenVMS: controlled either by Windows credentials or by OpenVMS security controls. |
| Event logging | Windows only. | Windows and OpenVMS. |
If you are upgrading to Version 1.4 from an earlier version of COM for OpenVMS, follow the upgrade instructions in Section 4.3. In addition:
If you are upgrading from any version of COM later than (but not including) COM Version 1.1 for OpenVMS, you do not need to repopulate the OpenVMS Registry. |
If you are upgrading from Version 1.0 or Version 1.1 to Version 1.4, 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 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 YES to continue [default is NO]: YES
The COM for OpenVMS Registry has already been loaded. This
action will overwrite the current COM for OpenVMS values
and data.
Enter YES to continue [default is NO]: YES
|
Repopulating the OpenVMS Registry does not affect the registration of existing COM applications. |
In previous versions of COM for OpenVMS, DECwindows Motif was required
software. In COM Version 1.4 for OpenVMS and higher, this prerequisite
is removed.
1.2.3 C Compiler Requirement Removed
In previous versions of COM for OpenVMS, DEC C Version 5.6 or higher was required software for COM for OpenVMS application development. In COM Version 1.2 for OpenVMS and higher, this prerequisite is removed. (You can still build your applications using DEC C Version 6.0 or higher; however, the C compiler is not required software.)
You can now build all applications using the recommended HP C++ compiler Version 6.5 or higher, or the minimum requirement of Compaq C++ compiler Version 6.0. (You need Compaq C++ Version 6.2-016 or higher to build ATL applications.)
For more information about building applications using the MIDL
compiler, see Section 7.2.
1.2.4 Previously Registered Applications That Use Logical Names for the Local Server Path
If you previously registered any COM application using a logical name for the local server path, you must modify (reregister) the application using the actual name for the local server path.
For example, if you use the REGISTER_SIMPLE.COM command procedure to register the "Simple" application under COM Version 1.0 for OpenVMS, you must reregister the "Simple" application using the new REGISTER_SIMPLE.COM command procedure.
As of COM Version 1.1-A for OpenVMS, HP has updated the registration command files.
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:
$ REG$CP == "$REG$CP"
$ 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 about
Localserver32 and CLSID, see Section 7.5.
1.2.5 Changes to the Examples
In COM Version 1.1-A for OpenVMS, the names of the server images in the
Dispatch_Sample1 example changed. If you previously built and
registered this application and you want to build the new version, you
must reregister the server after it has been built.
1.3 Problems Fixed in This Release
The following notes describe problems that have been fixed in COM
Version 1.4 for OpenVMS.
1.3.1 New NTA$LOGON.EXE Fixes Data Corruption in Password File
HP testing has uncovered a problem that occurs while using the DCOM$SETUP menu option number 8 to update the DCOM$RPCSS user password in the COM for OpenVMS Service Control Manager password file. This problem can potentially cause the password file to be corrupted.
A new NTA$LOGON.EXE image corrects this problem. This image can be
obtained by picking up the latest DCE update kit.
1.3.2 Access Violation When Compiling Very Large IDL Files
In certain instances, an access violation would occur when compiling
very large IDL files. COM Version 1.4 provides a modification to the
MIDL compiler that prevents this problem.
1.3.3 Windows 2000 Interoperability Requires Windows 2000 SP4 and Latest DCERPC
As part of interoperability testing, HP has identified problems in the authentication layer that prevents authenticated COM requests between OpenVMS and Windows 2000 systems.
The solution to these problems is to install Windows 2000 SP4 on your
Windows system, and the latest DCE$LIB_SHR.EXE (available from your
support center) on your OpenVMS system.
1.3.4 ERROR_ACCESS_DENIED (C0000005 or 80070005)
COM for OpenVMS in authenticated mode reported intermittent ERROR_ACCESS_DENIED (C0000005 or 80070005) errors when running an OpenVMS client to a Windows 2000 server. These errors were seen only if the domain name was fewer than 12 characters. This problem has been fixed in this release.
Under heavy load testing, HP still encounters a few remaining
ERROR_ACCESS_DENIED errors, but the occurence is less than 1%. To avoid
this problem completely, use a domain name of 12-15 characters.
1.4 Known Problems in the Current Release
The following notes describe the known problems with COM Version 1.4
for OpenVMS. These problems currently do not have fixes.
1.4.1 Fatal Exception in DCOM$RPCSS While Launching Multiple Instances of COM Applications
During extensive testing by HP in unauthenticated mode, in certain instances the DCOM$RPCSS process may experience a fatal exception while trying to launch multiple instances of different COM applications. This results in all client processes reporting a 8007071C error.
To return to a working environment, shut down and restart DCOM$RPCSS. A possible workaround is to run your application as a persistent server.
HP is continuing to investigate this problem. If you encounter this
problem, please contact your HP support center.
1.4.2 COM Version 1.4 Fails with Microsoft MS04-012 (KB 828741) Patch
HP testing has discovered that after installing the Microsoft security patch MS04-012 (Knowledge Base article 828741), an OpenVMS client connection to a Windows server fails. The application will fail with an access denied error such as C0000005 or 80070005.
If you have already installed this security patch and are experiencing problems, a possible workaround is to temporarily uninstall the patch.
A solution to this problem is being jointly investigated by Microsoft
and HP, and an update will be provided as soon as it becomes available.
1.4.3 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.4.4 Errors Seen Between OpenVMS Systems Running COM Version 1.3 Under Heavy Load
Testing by HP has uncovered the errors E-OUTOFMEMORY (8007000E),
DCERPC-E-WHOAREYOUFAILED (EE1282FA) and CO_E_SERVER_EXEC_FAILURE
(80080005) between OpenVMS systems running heavy load tests with COM
Version 1.3 for OpenVMS. This problem was not seen when the tests were
run locally or between Windows and OpenVMS systems.
1.5 Limitations and Restrictions
The following sections contain general release note information.
1.5.1 Windows XP Not Supported
HP has not tested COM Version 1.4 with Windows XP. Therefore, Windows
XP is not supported in COM Version 1.4 for OpenVMS.
1.5.2 NetBEUI as Listed Protocol in DCOMCNFG
If you have NetBEUI listed as a default protocol in DCOMCNFG, you might
see various errors when running sample programs between OpenVMS and
Windows 2000. To correct these problems, remove NetBEUI from the list
of default protocols and reboot your Windows system.
1.5.3 COM Version 1.0 for OpenVMS and COM Version 1.4 for OpenVMS Not Supported in the Same Cluster
When you install and configure any version of COM for OpenVMS higher
than Version 1.0 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.5.4 Threading Model Supported by COM for OpenVMS
COM Version 1.4 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.5.5 Enhanced NTLM in Windows NT SP4 and Later Versions Not Supported
In Windows NT SP4, Microsoft introduced enhanced NTLM support. COM Version 1.4 for OpenVMS does not support enhanced NTLM.
If you want to use COM Version 1.4 for OpenVMS with SP4 or later, you must be sure that enhanced NTLM is disabled.
Ongoing testing by HP has show that, with SP4 or higher and enhanced
NTLM disabled, authentication requests fail if you use passwords that
are longer than 12 characters.
1.5.6 Specifying Activation Security in CoCreateInstanceEx
The pServerInfo parameter of the CoCreateInstanceEx API allows you to specify a user name and password that will be used for authentication on the remote server system. The user name 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 communicating with COM servers on
OpenVMS.
1.5.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 HP Advanced Server for OpenVMS having lost a connection between domain controllers. The Advanced Server 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 HP support center.
1.5.8 RPC Cannot Support Failure (800706E4) Error Message
If you attempt to use the single-threaded apartment (STA) model, some COM APIs may display the following return status code:
(800706E4) |
COM Version 1.4 for OpenVMS does not support the STA model. For more information, see Section 1.5.4.
For the latest OpenVMS Registry information, refer to the OpenVMS Release Notes for the current version of the operating system.
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.
The former Digital Equipment Corporation (now part of Hewlett-Packard Company) 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 2000, Windows NT, Windows
98, Windows 95, OpenVMS, and HP 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:
http://www.microsoft.com/com |
COM for OpenVMS is HP's implementation of Microsoft's Windows NT 4.0 Service Pack 5 (SP5) Component Object Model (COM) software on the OpenVMS Alpha operating system.
In support of COM for OpenVMS, HP 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.
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 system
The smaller box on the left side of Figure 3-1 represents the Windows 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 includes a utility to acquire Windows credentials if you are running COM for OpenVMS in authenticated mode. For more information about getting Windows 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 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 12.
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.4 for OpenVMS Kit
COM Version 1.4 for OpenVMS contains the following:
The following software is required:
| Software | Global pages | Global sections | Disk blocks |
|---|---|---|---|
| COM for OpenVMS | 11,000 | 27 | 34000 |
| RPC Runtime | 3,300 | 14 | N/A |
For Advanced Server requirements: See the HP Advanced Server for OpenVMS Server Installation and Configuration Guide.
For TCP/IP requirements: See the HP TCP/IP Services for OpenVMS Installation and Configuration document.
The following sections describe COM Version 1.4 for OpenVMS installation and upgrade options.
If you want to run COM Version 1.4 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. | Section 4.4 |
| Install COM for OpenVMS on an OpenVMS Cluster system for the first time. | Section 4.6 |
| Upgrade from earlier versions of COM for OpenVMS on an OpenVMS standalone system. | Section 4.5 |
| Upgrade from earlier versions of COM for OpenVMS on an OpenVMS Cluster system. | 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, HP 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, HP recommends that you disable any HP Advanced Server for OpenVMS, OpenVMS Registry, and layered product automatic startups so that 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, HP 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, HP 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 HP Advanced Server for OpenVMS on at least one Alpha node in the cluster. On the other nodes, you can either install HP 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, HP 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, HP recommends that you disable any HP 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, HP Advanced Server for OpenVMS (if running), and then the OpenVMS Registry on all nodes in the cluster. |
Use the following procedure:
You must install HP Advanced Server for OpenVMS on at least one Alpha node in the cluster. On the other nodes, you can either install HP 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 provides a command procedure that defines shortcut commands for many regular COM commands.
Add the following command to your login command procedure, or execute the command line after logging in:
$ @SYS$STARTUP:DCOM$DEFINE_COMMANDS.COM |
SYS$STARTUP:DCOM$DEFINE_COMMANDS.COM defines the following commands:
$ DCOMSTA*RT :== @SYS$STARTUP:DCOM$STARTUP.COM $ DCOMSTO*P :== @SYS$STARTUP:DCOM$SHUTDOWN.COM $ DCOMSTOPN*O :== @SYS$STARTUP:DCOM$SHUTDOWN.COM NOCONFIRM $ DCOMSE*TUP :== @SYS$STARTUP:DCOM$SETUP.COM $ DCOMC*NFG :== $SYS$SYSTEM:DCOM$CNFG.EXE $ DCOMT*OOL :== $SYS$SYSTEM:DCOM$TOOL.EXE $ NTLOG*ON :== $SYS$SYSTEM:NTA$LOGON.EXE $ DCOMOUT :== TYPE/PAGE SYS$MANAGER:DCOM$RPCSS.OUT $ DCOMEV*ENTS :== TYPE/PAGE SYS$MANAGER:DCOM$EVENTLOG.RPT $ DCOMVER :== $SYS$SYSTEM:DCOM$TOOL.EXE SHOW VERSION $ DCOMER*ROR :== $SYS$SYSTEM:DCOM$TOOL.EXE SHOW ERROR |
With COM Version 1.3 or higher for OpenVMS, you can view the currently installed version of COM. To do so, invoke the following command:
$ DCOM$TOOL == "$DCOM$TOOL" $ DCOM$TOOL SHOW VERSION |
For more ways to use to the DCOM$TOOL Utility, see Section 7.6.2.
4.10 Understanding the COM for OpenVMS Environment
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 Interrelationships Among Processes and Layers
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.10.1 |
| REGISTRY_SERVER | OpenVMS Registry server | Section 4.10.2 |
| PWRK xxx | HP Advanced Server for OpenVMS server (multiple processes) | Section 4.10.3 |
| ACME_SERVER | ACME server | Section 4.10.4 |
| DCE$DCED | RPC endpoint mapper | Section 4.10.5 |
The following sections list and describe the servers and the layers.
4.10.1 COM for OpenVMS Service Control Manager (SCM)
The COM for OpenVMS Service Control Manager enables COM for OpenVMS.
Process name: DCOM$RPCSS
Requires: OpenVMS Registry, OpenVMS (RPC and SSPI/NTLM layers)
Required by: COM applications
Configured by: DCOM$SETUP. See Section 6.2.
Started by: DCOM$SETUP, option 4. See Section 6.2.
Shutdown procedure: DCOM$SETUP, option 5. See
Section 6.2.
4.10.2 OpenVMS Registry Server
The OpenVMS Registry server manages the OpenVMS Registry database.
Process name: REGISTRY_SERVER
Requires: None.
Required by: COM for OpenVMS, HP Advanced Server for OpenVMS
Configured by: REG$CONFIG.
Started by: REG$STARTUP. See Section 13.2.1.
Shutdown procedure: SET SERVER REGISTRY_SERVER/EXIT.
For more information, see Section 13.3.
4.10.3 HP Advanced Server for OpenVMS Server
The HP Advanced Server for OpenVMS server enables OpenVMS to act as a Windows NTLM domain controller.
The ACME server requires the PWRK$MSV1_0_ACMESHR ACME agent image to talk with the local or remote PWRK$LMSRV process.
Requires: OpenVMS Registry
Required by: ACME server
Configured by: PWRK$CONFIG
Started by: PWRK$STARTUP
Shutdown procedure: PWRK$SHUTDOWN
For more information, see the HP PATHWORKS for OpenVMS (Advanced
Server) Server Migration Guide.
4.10.4 ACME Server
The ACME server controls the granting of credentials.
Process name: ACME_SERVER
Requires: HP Advanced Server for OpenVMS
Required by: OpenVMS (RPC and SSPI/NTLM layers) and OpenVMS Events
Started:
$ @SYS$STARTUP:NTA$STARTUP_NT_ACME |
Shutdown procedures (both are valid):
$ SET SERVER ACME /CANCEL /EXIT |
$ SET SERVER ACME /DISABLE /CANCEL $ SET SERVER ACME /ENABLE=(NAME=VMS) |
For more information, see Section 8.3.2.
4.10.5 RPC Endpoint Mapper
The RPC endpoint mapper controls authentication and security.
Process name: DCE$DCED
Requires: RPC image
Required by: COM for OpenVMS Service Control Manager, RPC image
Started by: OpenVMS
Shutdown procedure: Use the following command procedure:
$ @SYS$STARTUP:DCE$RPC_SHUTDOWN.COM |
For more information, see the Compaq DCE Installation and
Configuration Guide.
4.10.6 RPC and SSPI/NTLM Layers
The RPC and SSPI/NTLM layers provides remote procedure call and Windows-style authentication on OpenVMS.
Process name: n/a (part of OpenVMS operating system)
Requires: OpenVMS, ACME server
Required by: COM for OpenVMS
Started by: OpenVMS
Shutdown procedure: n/a
4.10.7 OpenVMS Events
The Events layer provides Windows-style event logging on OpenVMS.
Process name: n/a (part of OpenVMS operating system)
Requires: ACME server
Required by: COM for OpenVMS
Started by: OpenVMS
Shutdown procedure: n/a
For more information, see Chapter 15.
4.11 Installing COM for OpenVMS
The COM for OpenVMS installation kit contains a single POLYCENTER Software Installation utility file. The name of the kit is DEC-AXPVMS-DCOM-V0104--1.PCSI . You must install the COM for OpenVMS files on an OpenVMS Alpha system. Please check the prerequisites before installing the kit. See Section 4.2.
To install COM for OpenVMS, invoke the POLYCENTER Software Installation utility using the following command:
$ PRODUCT INSTALL DCOM /SOURCE=device:[directory] |
For device:[directory], specify the device name and directory location of the kit, respectively.
The COM for OpenVMS MIDL compiler no longer requires the DCOM-MIDL license. |
Example 4-1 shows a sample installation.
| Example 4-1 Sample COM for OpenVMS Installation |
|---|
$ product install dcom/source=disk:[directory]
The following product has been selected:
DEC AXPVMS DCOM V1.4 Layered Product
Do you want to continue? [YES]
Configuration phase starting ...
You will be asked to choose options, if any, for each selected product and for
any products that may be installed to satisfy software dependency requirements.
DEC AXPVMS DCOM V1.4
Copyright © 2004 Hewlett-Packard Development Company, L.P. All rights reserved.
Do you want the defaults for all options? [YES]
The following software is required to run COM for HP OpenVMS
- HP OpenVMS Alpha V7.3-1 or later
* Includes DCE RPC and OpenVMS Registry
(The most recent DCE$LIB_SHR.EXE available is
required for interoperating with Windows 2000.)
- HP TCP/IP Services V5.0 or later for HP OpenVMS (or equivalent product)
- HP Advanced Server V7.3 or later for HP OpenVMS
Do you want to continue? [YES]
Do you want to review the options? [NO]
Execution phase starting ...
The following product will be installed to destination:
DEC AXPVMS DCOM V1.4 DISK$FINALKES:[VMS$COMMON.]
Portion done:
0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%
The following product has been installed:
|
After you install the COM for OpenVMS kit, do the following:
Use the following command to start COM for OpenVMS:
$ @SYS$STARTUP:DCOM$STARTUP |
Alternately, you can run DCOM$SETUP and choose option 4. (See Section 6.2.)
The COM for OpenVMS Service Control Manager can be in one of the following states: initializing/running or not started. Depending on the COM for OpenVMS Service Control Manager state, you will see one of the following messages:
DCOM Service Control Manager daemon (DCOM$RPCSS) is active [pid=xxxxxxxx] |
DCOM Service Control Manager daemon (DCOM$STARTUP-**) is active [pid=xxxxxxxx] |
The OpenVMS Registry server is already started on this node.
*** DCOM system startup procedure ***
Starting DCOM Service Control Manager daemon ( "DCOM$STARTUP-**" ) . . .
After initialization, the daemon will use process name "DCOM$RPCSS" . . .
%RUN-S-PROC_ID, identification of created process is xxxxxxxx
*** DCOM startup successful ***
*** DCOM Startup Procedure Complete ***
|
HP recommends that you modify the SYS$MANAGER:SYLOGICALS.COM command file to control COM for OpenVMS startup.
OpenVMS includes a revised SYLOGICALS.TEMPLATE file that includes new startup commands for COM for OpenVMS and related components. Review the "Coordinated Startup" section of this template file and add the appropriate information to your existing startup files.
To have COM for OpenVMS start automatically when the system boots, copy the following line to your SYLOGICALS.COM file, uncomment the line, and make sure it is set to TRUE :
$ DEFINE DCOM$TO_BE_STARTED TRUE |
If you do not set COM for OpenVMS to start automatically when the
system boots, you can start COM for OpenVMS using the DCOM$SETUP
OpenVMS COM Tools menu, option 4 (see Section 6.2).
4.14 Shutting Down COM for OpenVMS (COM for OpenVMS Service Control Manager)
Use the following command to shut down COM for OpenVMS:
$ @SYS$STARTUP:DCOM$SHUTDOWN |
Alternately, you can run DCOM$SETUP and choose option 5. (See Section 6.2.)
The COM for OpenVMS Service Control Manager can be in one of the following states: stopped, running, or initializing. Depending on the COM for OpenVMS Service Control Manager state, you will see one of the following messages:
*** DCOM system shutdown procedure ***
There is no active DCOM$RPCSS daemon on this system.
*** DCOM Shutdown Procedure Complete ***
|
*** DCOM system shutdown procedure ***
*************************** Warning ********************************
*** Stopping the DCOM Service Control Manager daemon (DCOM$RPCSS)
*** Active DCOM applications will no longer be operational.
Do you want to proceed with this operation (YES/NO/?) [N]?
|
For information about suppressing this confirmation step, see Section 4.14.1. |
Terminating DCOM Service Control Manager daemon (DCOM$RPCSS) . . .
*** DCOM shutdown successful ***
*** DCOM Shutdown Procedure Complete ***
|
*** DCOM system shutdown procedure ***
*************************** Warning ********************************
*** Stopping the DCOM Service Control Manager daemon (DCOM$RPCSS)
*** Active DCOM applications will no longer be operational.
Do you want to proceed with this operation (YES/NO/?) [N]?
|
Terminating DCOM Service Control Manager daemon (DCOM$STARTUP-**) . . .
*** DCOM shutdown successful ***
*** DCOM Shutdown Procedure Complete ***
|
You can suppress the DCOM$SHUTDOWN command confirmation request by specifying the NOCONFIRM parameter. Use the following command:
$ @SYS$STARTUP:DCOM$SHUTDOWN NOCONFIRM |
The system displays the following shutdown messages without prompting you to confirm the shutdown:
*** DCOM system shutdown procedure ***
Terminating DCOM Service Control Manager daemon (DCOM$RPCSS) . . .
*** DCOM shutdown successful ***
*** DCOM Shutdown Procedure Complete ***
|
| Next | Contents | Index |