Document revision date: 15 July 2002

Although you do not need to specify any qualifiers to link the client or the component executable images, you must link both images. The specific link-time dependency is as follows:

• DCOM$LIBRARY:DCOM.OPT

If you have one or more C++ modules, use the C++ linker (CXXLINK) instead of the standard OpenVMS linker so you can specify the location of your C++ repository (/CXX_REPOSITORY qualifier). For example:

$ CXXLINK/your-specific-linker-qualifiers list-of-object-modules, - _$ DCOM$LIBRARY:DCOM.OPT/OPTIONS, application.OPT/OPTIONS - _$ /REPOSITORY=[.CXX_REPOSITORY]

You can also include the list of object modules in an options file instead of on the command line.

9.2.5.2 Linking the In Process Component Shareable Image

The in process component shareable image dependency list differs slightly from that of the client and component executables. The specific link-time dependencies are as follows:

• [directory-name]MYCOMPAPP$SHR.OPT
• DCOM$LIBRARY:DCOM.OPT

To create a symbol vector for the in process component shareable image, use the procedure described in Section 7.4.2.1.

To create a symbol vector for the proxy/stub shareable image, use the procedure described in Section 7.4.3.

9.3 ATL Samples

TESTATL is an out of process sample, and MATH101 is an in process sample.

You can find the sample ATL applications shown in this chapter in the following directories on the COM for OpenVMS kit:

DCOM$EXAMPLES:[TESTATL_OUTPROC] DCOM$EXAMPLES:[TESTATL_INPROC]

This sample implements a COM client and server in which the component provides one interface: ISum .

Given sources initially generated by the Microsoft Visual Studio ATL AppWizard and a few applied changes, the sample demonstrates the build, registration, and execution of the ATL application on OpenVMS.

The following sections describe how to create the application using the Microsoft ATL AppWizard on Windows NT and how to build the application on an OpenVMS system.

9.3.1.1 Creating the Application on Windows NT

To generate a skeleton project and simple objects using the Microsoft Visual Studio ATL AppWizard, follow these steps:

1. Generate the skeleton project:
   • Select the ATL COM AppWizard and name your skeleton project.
   • Choose Executable (EXE) as the server type.
2. Add objects:
   • Start the ATL Object Wizard.
   • From the Objects category, select Simple Object.
   • From the Attribute tab, choose the Both threading model.

A README file describes how to build, register, and run this COM for OpenVMS sample. The file is located in:

DCOM$EXAMPLES:[TESTATL_OUTPROC]README-TESTATL_OUTPROC.TXT

9.3.2 In-Process COM Sample (TESTATL_INPROC)

This sample implements a COM client and server in which the component provides three interfaces: ISum, IDiv, and IMul.

Given sources initially generated by the Microsoft Visual Studio ATL AppWizard, the sample demonstrates the build, registration, and execution of the shareable application on an OpenVMS system.

The following sections describe how to build the application.

9.3.2.1 Creating the Application on Windows NT

To generate a skeleton project and simple objects using the Microsoft Visual Studio ATL AppWizard, follow these steps:

• Generate the skeleton project:
  • Select the ATL COM AppWizard and name your skeleton project.
  • Choose Dynamic Link Library (DLL) as the server type.
• Add objects:
  • Start the ATL Object Wizard.
  • From the Objects category, select Simple Object.
  • From the Attribute tab, choose the Both threading model.

A README file describes how to build, register, and run this COM for OpenVMS sample. The file is located in:

DCOM$EXAMPLES:[TESTATL_INPROC]README-TESTATL_INPROC.TXT

9.4 Suggested Reading

The following resources provide more information about ATL:

• Third-party books about ATL:
  • Beginning ATL COM Programming, Grimes and Stockton, Templeman and Reilly, Wrox Press, Olton, Birmingham, UK, 1998. ISBN: 1-861000-11-1.
  • Professional ATL COM Programming, Dr Richard Grimes, Wrox Press, Olton, Birmingham, UK, 1998. ISBN: 1-861001-4-01.
• Websites:
  • The Component Object Model Specification, available from the Microsoft COM website:

    www.microsoft.com/com

COM Version 1.2 for OpenVMS makes it possible to create an in-process server that can be loaded into a surrogate process. The default surrogate provided, DCOM$DLLHOST.EXE, can be remoted and instructed to load any in-process component, providing it with a surrogate parent process and security context.

Running an in-process server in a surrogate process offers several possible benefits:

• Provides fault isolation and the ability to service multiple clients simultaneously.
• In a distributed environment, a DLL server implementation can service remote clients.
• Permits clients to take advantage of services the in-process server provides, while protecting themselves from untrusted components.
• The server is provided with the security context of the surrogate process.

To run your application using a Dllhost Surrogate, you need to set some values in your OpenVMS Registry.

Add the following values to the OpenVMS Registry:

[HKEY_CLASSES_ROOT\CLSID\{Guid}] "AppID"="{Guid}" [HKEY_CLASSES_ROOT\CLSID\{Guid}]\InProcServer32 "ThreadingModel"="Free" [HKEY_CLASSES_ROOT\APPID\{Guid}] "DllSurrogate"=""

The registry code in the DLL Surrogate sample (REG_SURROGATE.CXX) includes code that makes these changes.

In addition, if you plan to run multiple clients launched by different users within the same surrogate process, you need to change one of the application properties. Specifically, you must set a RunAs account (NTLM account) through DCOM$CNFG.

To set a RunAs account, perform the following steps:

1. Start the DCOM$CNFG utility (see Section 6.3).
2. Select option 1---Applications list.
3. Enter a number for the application you want to change.
4. Select option 3---Identity.
5. Modify the Application Identity (see Section 6.3.4).

By default, the Identity on an application is set as Launching User. This causes a separate surrogate process to be launched for each different user.

To run legacy applications within a surrogate, you do not need to modify any code. Add the preceding values to the OpenVMS Registry, and delete the following LocalServer32 key:

[HKEY_CLASSES_ROOT\CLSID\{Guid}]\LocalServer32

10.2 Developing a Surrogate Application

For more information about how to run your application within a surrogate and configure your Registry values, see the DLL Surrogate sample in the DCOM$EXAMPLES:[SURROGATE] directory in the COM Version 1.2 for OpenVMS kit.

COM Version 1.2 for OpenVMS fully supports IEEE floating-point values in COM for OpenVMS applications.

11.1 Running Sample Programs with IEEE Floating Point Values

You can run any sample program with IEEE floating-point values rather than VAX floating-point values. To do so, apply the following changes to your application:

• Add the following API below any included header files:

  VMS$UseIeeeFloatingPoint();

• Add the following switch to the compile statement for the sample to which you added the API:

  /FLOAT=IEEE_FLOAT

IEEE floating-point values can be used in COM for OpenVMS applications running between remote OpenVMS systems, running between Windows and OpenVMS, and running an out-of-process server on OpenVMS.

IEEE floating-point values cannot be used in the following circumstances:

• With an in-process server
• With another sample not compiled with the IEEE qualifier

The OpenVMS Registry $REGISTRY and $REGISTRYW system services are described in the OpenVMS System Services Reference Manual.

For the latest information about the OpenVMS Registry, refer to the OpenVMS Release Notes for the current version of the operating system.

The Windows NT Registry is a single, systemwide, hierarchical database of configuration information about hardware and software (both the operating system and applications). The Windows NT Registry replaced Windows 3.x .ini files, providing a single place for storing application and configuration information.

To allow OpenVMS and Windows NT to interoperate, Compaq has provided a registry on OpenVMS. Like the Windows NT Registry, the OpenVMS Registry is made up of two components: the OpenVMS Registry database and the OpenVMS Registry server. The OpenVMS Registry database is a systemwide or clusterwide hierarchical database of configuration information. This information is stored in a database structure of keys and associated values. The OpenVMS Registry server controls all OpenVMS Registry operations, such as creating and backing up the OpenVMS Registry database, and creating, displaying, modifying, or deleting keys and values.

The OpenVMS Registry includes interfaces (COM APIs and system services) to allow applications to control the OpenVMS Registry server and to read and write to the OpenVMS Registry database. The OpenVMS Registry also includes server management utilities to allow system managers to display and update OpenVMS Registry information from the OpenVMS DCL command line.

The OpenVMS Registry is compatible with the Windows NT Registry. Windows NT client applications such as RegEdt32 can connect to and edit the OpenVMS Registry.

12.1.1 Suggested Reading

The following resources can provide you with more information about Windows NT Registry and related topics:

• Third-party books about the Windows NT Registry:
  • Windows NT Server 4.0 Unleashed, Jason Garms, SAMS Publishing, Indianapolis, IN, 1998. ISBN: 0-672-30933-5.

The OpenVMS Registry, like the Windows NT Registry, is a hierarchical database with several branches.

The following sections list and explain OpenVMS Registry database elements and operation.

12.2.1 Keys, Subkeys, and Values

A key is one of the basic building blocks of the OpenVMS Registry database. A key contains information specific to the computer, system, or user; it is a header field in the OpenVMS Registry database. Keys can be arranged in a hierarchy (or tree).

There are two main (or root) keys in the OpenVMS Registry:

• HKEY_USERS contains information about each user.
• HKEY_LOCAL_MACHINE contains hardware, software, security, and general system configuration information.

The key HKEY_CLASSES_ROOT points to the CLASSES subkey in HKEY_LOCAL_MACHINE . These root keys are discussed in more detail in Section 12.3.

A subkey is a key that is a child to another key. A key can have zero or more subkeys. Subkeys allow you to group related keys together below another key in a hierarchy or tree.

A value entry (or value) is a named element of data; it is a record field in the registry database. A key has zero or more associated values. A value has a value name, a value type, a collection of flags, and associated data (defined by the value's type). OpenVMS Registry supports the following value types:

• Null-terminated string
• Null-terminated array of null terminated strings
• Null-terminated string containing environment variables (logical names or symbols)
• 32-bit data item
• 64-bit data item
• Raw binary

Figure 12-1 summarizes the relationship between keys, subkeys, and values.

Figure 12-1 Key, Subkey, and Value Relationships

Key1=Value1 Key2 | +-Subkey1=Value1 | +-Subkey2=Value1,Value2 : .

12.2.1.1 Key and Value Volatility

You can define OpenVMS Registry keys and values as either nonvolatile or volatile. Nonvolatile keys are saved to OpenVMS Registry files. Volatile keys are cached to a temporary file.

On Windows NT systems, volatile keys and values are removed when the system restarts.

On OpenVMS, volatile keys and values are automatically removed when all nodes in a cluster are rebooted. OpenVMS extends the lifetime of volatile keys to survive server failover but not a cluster reboot. (In a standalone system, volatile keys and values are lost when the system reboots.)

12.2.1.2 Key Write-through and Write-behind

When you create a key, you can specify when the OpenVMS Registry should write that key's changed information. The write options are as follows:

• Write-through: Write the changes to disk immediately.
• Write-behind: Cache the changes and write them later.

The Cache Action attribute allows you to specify a key's write characteristics. If you do not specify the cache action attribute when you create the key, the key inherits this attribute from its parent.

When you use the SYS$REGISTRY interface, you can use the the REG$M_NOW function code modifier for a request in progress to force an immediate write (write-through), regardless of the cache action attribute value.

12.2.1.3 Linking a Key to Other Keys and Values

OpenVMS Registry keys can link to other OpenVMS Registry keys, providing multiple paths to the same piece of data. In the same way, OpenVMS Registry values can link to other OpenVMS Registry values. These key and value links, or symbolic links, are similar to file links. Symbolic links are name references.

For example, you can link Key A to Key B . When you query Key A and its value, the system returns Key B 's value.

You can also chain symbolic links. That is, Key A can point to Key B and Key B can point to Key C ; as a result, Key A also points to Key C . You can specify a link through the $REGISTRY system service or through the OpenVMS Registry server management command-line interface.

12.2.1.4 Rules for Creating OpenVMS Registry Keys and Value Names

The following rules apply to key and value names:

• A key can have subkeys and values.
• A key name can be composed of any Unicode (4 bytes) character except the backslash (\) character and the null character. You must specify at least one character.
• A value name can be composed of any Unicode (4 bytes) character.
• A key string can be either a name (for example, disk ) or a path (for example, Hardware\cosmos\disk ).
• A value string can be a name only.
• When you define a key, if you specify a path but the system does not find one or more of the path subkeys, the system creates these subkeys automatically. The created keys inherit the attributes of their parent.
• The key and value names are case preserved in the OpenVMS Registry database. Name comparisons are case insensitive unless you specify the REG$M_CASESENSITIVE function code modifier with calls to the $REGISTRY system service.
• For pure binary data, the maximum size of a value is 1 MB (for Windows NT compatibility).

The Class attribute allows you to store additional descriptive information with each key. For example, specifying Class text string could allow you store permitted data types with a specified key.

12.2.3 Hive

A hive is a collection of related keys, subkeys, and values stored in the OpenVMS Registry.

On Windows NT systems, a hive is stored in a single file in the %SystemRoot%\system32\config directory, along with an associated LOG file. Windows NT allows users to save hives to specified files on disk so that these files can be loaded at a later time.

On OpenVMS systems, the entire OpenVMS Registry database consists of two hives: REGISTRY$LOCAL_MACHINE.REG and REGISTRY$USERS.REG . OpenVMS does not support loading and unloading hives.

12.3 OpenVMS Registry Structure

To allow Windows NT applications to interface with the OpenVMS Registry database, the OpenVMS Registry database includes a subset of the Windows NT Registry predefined keys and subkeys.

The OpenVMS Registry includes the following predefined standard keys:

• HKEY_CLASSES_ROOT
  On Windows NT systems, this key is reserved for the definition of classes of documents and the properties associated with these classes.
  On OpenVMS systems, this key by default does not have any subkey or value.
  This entry point maps to the HKEY_LOCAL_MACHINE\SOFTWARE\Classes subkey.
• HKEY_USERS
  On Windows NT systems, the entries under this entry point define the default user configuration for users on the local system and the user configuration for the current user.
  On OpenVMS systems, this key by default does not have any subkey or value.
• HKEY_LOCAL_MACHINE
  The entries under this entry point are reserved for system configuration information.
  On Windows NT systems, this area contains information about the bus type, system memory, and installed hardware and software.
  On OpenVMS systems, this key has the following predefined subkeys:
  • Hardware
    On Windows NT systems, the system constructs the volatile subkeys of this key from the information gathered at boot time.
    On OpenVMS systems, this key does not have any subkey or value by default.
  • Security
    On Windows NT systems, these keys contain all the security information for the local computer. The system owns the information in these keys and protects them accordingly.
    On OpenVMS systems, this key by default does not have any subkey or value.
  • Software
    On Windows NT systems, this key contains information about the software on the local system that is independent of per-user configurations.
    On OpenVMS systems, this key has the following predefined subkeys:
    • Classes
    • Compaq Computer Corporation
    • Microsoft
  • System
    On Windows NT systems, this key contains information about devices and services.
    On OpenVMS systems, this key has the following predefined subkeys:
    • CurrentControlSet
      On Windows NT systems, this key contains information about Control, Enum, and Hardware Profiles and Services.
      On OpenVMS systems, this key is reserved for use by Compaq Advanced Server for OpenVMS.
    • Registry
      This subkey does not exist on Windows NT systems. On OpenVMS systems, this key contains the OpenVMS Registry server configuration parameters in the form of subkeys and values. The predefined subkeys are as follows:
      • File Quotas
        This subkey is empty when you create the OpenVMS Registry database. A system manager can assign quota for each OpenVMS Registry database file by creating a value whose name is the name of the OpenVMS Registry file. If no value exists for a file, the OpenVMS Registry server uses the default value for the Default File Quota setting.
        For example, a system manager could use REG$CP to assign a 1 MB quota to the OpenVMS Registry REGISTRY$LOCAL_MACHINE.REG file by issuing the following command:

        $ MCR REG$CP REG> CREATE VALUE/NAME=REGISTRY$LOCAL_MACHINE/TYPE=DWORD/ - _REG> DATA=%D1000000 "hkey_local_machine\system\registry\File Quotas"

      • File Monitor
        This subkey is not used.
      • Priority
        This subkey is empty at OpenVMS Registry database creation. A system manager can change the priority of the OpenVMS Registry server on a specified node by creating a value whose name is the node name of the system in the cluster on which the OpenVMS Registry server resides.
        For example, a system manager could use the REG$CP server management utility to assign a priority of 100 to node COSMOS by issuing the following command:

        $ MCR REG$CP REG> CREATE VALUE/NAME=COSMOS/TYPE=DWORD/DATA=%D100 - _REG> "hkey_local_machine\system\registry - _REG> \Priority"

	privacy and legal statement
6539PRO_010.HTML