COM 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 run remotely 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 for OpenVMS kit.

COM for OpenVMS 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 Registry is a single, systemwide, hierarchical database of configuration information about hardware and software (both the operating system and applications). The Windows Registry replaced Windows 3.x .ini files, providing a single place for storing application and configuration information.

To allow OpenVMS and Windows to interoperate, HP has provided a registry on OpenVMS. Like the Windows 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 Registry. Windows 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 Registry and related topics:

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

The OpenVMS Registry, like the Windows 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 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 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 systems, a hive is stored in a single file in the %SystemRoot%\system32\config directory, along with an associated LOG file. Windows 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 applications to interface with the OpenVMS Registry database, the OpenVMS Registry database includes a subset of the Windows Registry predefined keys and subkeys.

The OpenVMS Registry includes the following predefined standard keys:

• HKEY_CLASSES_ROOT
  On Windows 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 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 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 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 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 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
    • Hewlett-Packard Company
    • Microsoft
  • System
    On Windows systems, this key contains information about devices and services.
    On OpenVMS systems, this key has the following predefined subkeys:
    • CurrentControlSet
      On Windows systems, this key contains information about Control, Enum, and Hardware Profiles and Services.
      On OpenVMS systems, this key is reserved for use by HP Advanced Server for OpenVMS.
    • Registry
      This subkey does not exist on Windows 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:

        $ REG$CP == "$REG$CP" $ REG$CP CREATE VALUE/NAME=REGISTRY$LOCAL_MACHINE/TYPE=DWORD/ - _$ 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:

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

This section contains the current restrictions and limitations in the OpenVMS Registry.

12.4.1 Registry Data Transfer Size Restriction Eased

Versions of OpenVMS prior to Version 7.3 placed restrictions on the size of a data transfer between the $REGISTRY system service and the OpenVMS Registry server. The data transfer restrictions, in turn, placed restrictions on the maximum size of a single block of data that can be stored or retrieved from the Registry database. They also limited the depth of a REG$CP Search command, and placed limits on the number of Advanced Server domain groups of which a user can be a member. These restrictions were eased in OpenVMS Version 7.3, but have not been eliminated entirely.

Previously the restrictions were approximately 8K bytes transmit (service to server) and approximately 4K bytes receive. The current restriction depends on the setting of the system parameter MAXBUF. The range for MAXBUF is 4K to 64K, with a default of 8K.

MAXBUF is the maximum allowable size for any single buffered I/O packet. You should be aware that by changing MAXBUF you also affect other areas of the system that perform buffered I/O.

12.5 Reading and Writing to the OpenVMS Registry

You can read and write to the OpenVMS Registry in the following ways:

• Using COM for OpenVMS, through the COM APIs available on OpenVMS. This allows application programmers to enter, modify, and delete OpenVMS Registry keys and values.
• Through the $REGISTRY and $REGISTRYW system services and the OpenVMS Registry server management utility commands. This allows application programmers to enter, modify, and delete OpenVMS Registry keys and values.
• From Windows, through the Windows Registry APIs, or using RegEdt32 (the Windows Registry Editor). This allows Windows users to view and edit OpenVMS Registry keys and values.

The OpenVMS Registry includes two OpenVMS system services that provide an interface to the OpenVMS Registry server. The OpenVMS Registry system services allow you to query, update, and create keys, subkeys, and values in the OpenVMS Registry database.

For more information about the $REGISTRY and $REGISTRYW system services, see the OpenVMS System Services Reference Manual.

12.5.2 REG$CP Server Management Utility

The REG$CP server management utility allows you to display and update OpenVMS Registry information from the OpenVMS DCL prompt. The utility also allows you to back up and restore the entire OpenVMS Registry database to or from a file, as long as you have the required system privileges.

For more information about the REG$CP server management utility, see Chapter 14.

12.6 OpenVMS Registry Security

The OpenVMS Registry implements both the OpenVMS and Windows security models.

To access to the OpenVMS Registry database, the calling process must have the proper OpenVMS Registry rights identifier for the operation you want to perform (for example, REG$LOOKUP for read operations, REG$UPDATE for write operations, or REG$PERFORMANCE for statistics operations) or the calling process must have the SYSPRV privilege.

The following sections describe the two models.

12.6.1 OpenVMS Security Model

When a user requests access to the OpenVMS Registry, the OpenVMS system checks the following:

1. Does the user have Windows credentials?
   If the user has Windows credentials, OpenVMS allows the user access to the OpenVMS Registry based on the user's supplied credentials. The user can acquire Windows credentials through the following methods:
   • Connecting to the OpenVMS Registry from a Windows system
   • Running a COM for OpenVMS client
   • Running an OpenVMS SYS$ACM client that acquires NT credentials
   
   If the user is not allowed access to the OpenVMS Registry based on the user's supplied credentials, or if the user does not have Windows credentials, continue to the next step.
2. Does the user have the OpenVMS SYSPRV privilege?
   • If the user has the SYSPRV privilege, OpenVMS allows the user full access to the OpenVMS Registry.
   • If the user does not have the SYSPRV privilege, continue to the next step.
3. Does the user have the REG$UPDATE , REG$LOOKUP , or REG$PERFORMANCE rights identifier?
   • If the user has the REG$UPDATE , REG$LOOKUP , or REG$PERFORMANCE rights identifier, OpenVMS allows the user access to the OpenVMS Registry using the supplied rights identifier. The user can access the OpenVMS Registry database as follows:
     • REG$UPDATE : Allows full access to the OpenVMS Registry except for maintenance requests.
     • REG$LOOKUP : Allows read-only access to the OpenVMS Registry.
     • REG$PERFORMANCE : Allows access to performance data collected by the OpenVMS Registry server.
   • If the user does not have the REG$UPDATE , REG$LOOKUP , or REG$PERFORMANCE rights identifier, continue to the next step.
4. If the user has no Windows credentials, OpenVMS grants the OpenVMS user Windows Everyone group access. In this case, the OpenVMS user's access to OpenVMS Registry keys depends on what permissions the key owner defined for Everyone when the key owner created the key or subkey. Based on these permissions, the OpenVMS user will be able to do one of the following:
   • Read the key and its subkeys.
   • Not see the key and its subkeys.

You can use the OpenVMS Authorize utility (AUTHORIZE) to add the SYSPRV privilege and REG$UPDATE , REG$LOOKUP , and REG$PERFORMANCE identifiers to users.

Because rights identifiers are specific to an application, you cannot use the AUTHORIZE command to create the rights identifiers. Use the REG$CP server management utility to create these rights identifiers on your system. Running the REG$CP server management utility creates these rights by default. You must run REG$CP from a privileged account. For more information about running REG$CP , see Chapter 14.

The following example shows how to use the SET RIGHTS_LIST command to allow all users to view keys and data in the OpenVMS Registry database. This command adds the REG$LOOKUP identifier to the system rights list.

$ SET RIGHTS_LIST/ENABLE/SYSTEM REG$LOOKUP

Example 12-1 shows how to use AUTHORIZE to grant and remove OpenVMS Registry rights to a specific user.

Example 12-1 Using AUTHORIZE to Grant Rights to a User

$ SET DEF SYS$SYSTEM $ RUN AUTHORIZE UAF> GRANT/IDENTIFIER REG$LOOKUP SMITH (1) UAF> GRANT/IDENTIFIER/ATTRIBUTES=DYNAMIC REG$UPDATE SMITH (2) UAF> REVOKE/IDENTIFIER REG$UPDATE SMITH (3) UAF> GRANT/IDENTIFIER REG$PERFORMANCE SYSTEM (4)

1. This AUTHORIZE command grants the REG$LOOKUP identifier to user Smith , allowing Smith to view keys and data in the OpenVMS Registry database.
2. This AUTHORIZE command grants the REG$UPDATE identifier to user Smith , allowing Smith to modify keys and data in the OpenVMS Registry database. The dynamic attribute allows Smith to remove or restore the REG$UPDATE identifier from the process rights list by using the SET RIGHT/ENABLE or the SET RIGHT/DISABLE command.
3. This AUTHORIZE command removes the REG$UPDATE identifier from user Smith .
4. This AUTHORIZE command grants the REG$PERFORMANCE identifier to the system manager account, allowing the system manager to enable and disable the monitoring of OpenVMS Registry performance data.

Windows users can access the OpenVMS Registry only through the HP Advanced Server for OpenVMS. OpenVMS grants Windows users access to the OpenVMS Registry based on the user's Windows credentials.

12.7 Controlling the OpenVMS Registry Server Operations

OpenVMS Registry server operations include control of file quotas, server priority, error recovery actions, frequency of database backup, and OpenVMS Registry server tuning.

The following sections describe OpenVMS Registry server operations, and provide minimum, maximum, and default values for each setting. For information about how to change these settings, see Chapter 14.

12.7.1 Defining Maximum Reply Age/Age Checker Interval Settings

The OpenVMS Registry server handles duplicate requests by tracking work in progress and returning a REG$_DUPLREQUEST error. The OpenVMS Registry server also holds completed requests in case a duplicate request is received for work that is already completed. In this case, the OpenVMS Registry server reconstructs the reply. After a specified time, the requests are discarded. The Maximum Reply Age setting determines how long these requests are retained. The Age Checker Interval setting determines how often the OpenVMS Registry server checks for requests that exceed this age.

By default, the server checks for old completed requests every five seconds. By default, the server discards completed requests that are older than five seconds.

Setting Name	Default value	Minimum value	Maximum value
Maximum Reply Age	5	1	60
Age Checker Interval	5	1	60

12.7.2 Defining the Database Log Cleaner Interval/Initial Log File Size Settings

The OpenVMS Registry uses a a two-phase commit process to write modifications to the OpenVMS Registry database. The OpenVMS Registry first writes the modifications to a log file and then applies the log file to the OpenVMS Registry database. The Database Log Cleaner Interval setting determines how often the OpenVMS Registry applies the log file to the OpenVMS Registry database. After the OpenVMS Registry applies the log file, the OpenVMS Registry creates a new log file based on the size you specify in the Initial Log File Size setting.

The Database Log Cleaner Interval setting should be short enough so that writes to the database do not require that the log file be extended. Also, the log file size should be small to keep the amount of time spent applying the log relatively short, because this operation blocks writes to the database.

By default, the log file is applied every five seconds. By default, the OpenVMS Registry log file is created using a size of 32 blocks (16 KB).

Setting Name	Default value	Minimum value	Maximum value
Database Log Cleaner Interval	5	1	30
Initial Log File Size	32	16	256

12.7.3 Defining Default File Quota/File Quota Interval Settings

The OpenVMS Registry server limits the size of OpenVMS Registry database files by applying file quotas. You can assign file quotas to the individual files that make up the OpenVMS Registry database. If you do not assign a file quota, the OpenVMS Registry uses the Default File Quota setting.

The OpenVMS Registry server periodically recalculates the size of the OpenVMS Registry database files to see whether quota is exceeded. The File Quota Interval setting determines how often the OpenVMS Registry performs this calculation.

By default, the Default File Quota setting is 10 MB. By default, the File Quota Interval setting is 30 seconds.

Setting Name	Default value	Minimum value	Maximum value
Default File Quota	0x10000000	0x7d00	0x3fffffff
File Quota Interval	30	10	60

12.7.4 Defining the Scan Interval Setting

In an OpenVMS Cluster, you can run OpenVMS Registry servers on more than one node; however, only one OpenVMS Registry server is active at a time. A OpenVMS Registry server's priority relative to the other OpenVMS Registry servers in the cluster determines which OpenVMS Registry server is active. If the cluster configuration changes, the system manager can adjust the priority of one or more OpenVMS Registry servers. After the system manager changes the priority, the OpenVMS Registry servers in the cluster determine which server now has the highest priority and automatically change their states as necessary. The Scan Interval setting determines how often a OpenVMS Registry server checks for changes in its priority.

By default, a server checks for changes in priority every 120 seconds.

Setting Name	Default value	Minimum value	Maximum value
Scan Interval	120	60	300

12.7.5 Defining the Log Registry Value Error Setting

The OpenVMS Registry server logs an error if one of the OpenVMS Registry server parameter values is out of the acceptable range. If the OpenVMS Registry detects an out-of-range error, the OpenVMS Registry server uses the default value for that parameter. The Log Registry Value Error setting is a Boolean value that determines whether the error should be logged.

By default, the OpenVMS Registry server does not log out-of-range errors.

Setting Name	Default value	Minimum value	Maximum value
Log Registry Value Error	0	0	1

12.7.6 Defining the Operator Communications Interval Setting

If an I/O error occurs, the OpenVMS Registry server can display a message to the operator console using OPCOM. The Operator Communications Interval setting determines how long the OpenVMS Registry server waits after the I/O error to determine if the error is going to persist. If the error does persist, OpenVMS Registry writes a message to the operator console.

By default, the OpenVMS Registry server writes a message to the operator console if the error persists longer than 60 seconds.

Setting Name	Default value	Minimum value	Maximum value
Operator Communication Interval	60	30	120

12.7.7 Defining the Process Time Limit Setting

The OpenVMS Registry server writes a message to the server log file if it takes too long to process a request. The Process Time Limit setting determines when a request has taken too long.

By default, 180 seconds are allowed per request before the OpenVMS Registry logs a message.

Setting Name	Default value	Minimum value	Maximum value
Process Time Limit	180	60	600

12.7.8 Defining the Reply Log Cleaner Interval Setting

The OpenVMS Registry server maintains a log of recent replies that it uses to reconstruct work in progress in the case of failover. After a specified time, the server discards these replies. The Reply Log Cleaner Interval setting determines how often the OpenVMS Registry discards these replies.

By default, the OpenVMS Registry server discards replies every five seconds.

Setting Name	Default value	Minimum value	Maximum value
Reply Log Cleaner Interval	5	5	60

12.7.9 Defining Snapshot Interval/Snapshot Location/Snapshot Versions Settings

The OpenVMS Registry server maintains backup copies of the OpenVMS Registry database. The Snapshot Interval setting determines how often the OpenVMS Registry server creates a backup copy. The Snapshot Location setting determines where the OpenVMS Registry stores the copy. The Snapshot Versions setting determines how many previous copies the OpenVMS Registry keeps.

By default, the OpenVMS Registry database is copied to backup once per day. By default, the OpenVMS Registry database is copied to the location determined by the definition of the SYS$REGISTRY logical name. By default, the OpenVMS Registry keeps five previous versions of the OpenVMS Registry database.

Setting Name	Default value	Minimum value	Maximum value
Snapshot Interval	86400	3600	604800
Snapshot Location	SYS$REGISTRY	---	---
Snapshot Versions	5	1	10

12.7.10 Defining the Write Retry Interval Setting

If the OpenVMS Registry finds an error when writing to the OpenVMS Registry database, the OpenVMS Registry server retries the write at an interval specified by the Write Retry Interval setting.

By default, the OpenVMS Registry server attempts to retry failed writes to the OpenVMS Registry database every five seconds.

Setting Name	Default value	Minimum value	Maximum value
Writer Retry Interval	5	1	30

The OpenVMS Registry server is installed as part of the OpenVMS system installation.

Before you can use the OpenVMS Registry, you must configure the OpenVMS Registry server.

The first time you start the OpenVMS Registry server using the startup process described in Section 13.2, the OpenVMS system creates the OpenVMS Registry database.

You can access the OpenVMS Registry in several ways. Depending on how you want to access the OpenVMS Registry, you must install the following products:

• If you want to access the OpenVMS Registry using the COM APIs, you must install COM for OpenVMS and populate the OpenVMS Registry database. For more information about installing COM for OpenVMS, see Chapter 4. For more information about populating the OpenVMS Registry database, see Section 6.2.
• If you want to access the OpenVMS Registry using the Windows application RegEdt32 , you must first install, configure, and start HP Advanced Server for OpenVMS. For more information, see the HP Advanced Server for OpenVMS documentation.

You can also access the OpenVMS Registry using the OpenVMS Registry server management utility or the OpenVMS Registry system services, which are installed as part of the OpenVMS Registry.

The OpenVMS Registry configuration procedure (REG$CONFIG) provides information about the OpenVMS Registry server status and the OpenVMS Registry database location, and allows you to change OpenVMS Registry logical names and paths.

Enter the following command to invoke the OpenVMS Registry configuration procedure:

$ @SYS$MANAGER:REG$CONFIG

The system displays the following menu:

--------------------------------------------------------- OpenVMS Registry Configuration Utility ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1 - Configure OpenVMS Registry logical names and directory paths 2 - Display OpenVMS Registry logical names and directory paths 3 - Check the state of the OpenVMS Registry server 4 - Start the OpenVMS Registry server on this node 5 - Convert to latest database version and/or reclaim database H - Help about this utility [E] - Exit Please enter your choice : ---------------------------------------------------------

To select an option, enter the option number. The options are as follows:

• 1 - Configure OpenVMS Registry logical names and directory paths
  Allows you to configure the OpenVMS Registry server startup value and specify the location of the OpenVMS Registry database.
  For this procedure, see Section 13.1.1.
• 2 - Display OpenVMS Registry logical names and directory paths
  Displays the current values of the OpenVMS Registry server logical (startup value) for this node and the OpenVMS Registry database location.
• 3 - Check the state of the OpenVMS Registry server
  Displays the current state of the OpenVMS Registry server. The system displays one of the following:

  The OpenVMS Registry server is started in the cluster. The OpenVMS Registry server is started on this node. The OpenVMS Registry server is not started.

• 4 - Start the OpenVMS Registry server on this node
  Starts the OpenVMS Registry server on the current node. The system displays the following message:

  The OpenVMS Registry server has successfully started.

• 5 - Convert to latest database version and/or reclaim database
  This option can be used to convert an existing database to the latest version. The latest version is determined by the currently running server.
  This option can also be used to compact the database. Over time, the database can become fragmented in much the same way that a disk can become fragmented. Compacting the database makes it more efficient and requires less disk space.
• H - Help about this utility
  Displays online help for OpenVMS Registry Configuration utility options.
• [E] - Exit
  Exits the OpenVMS Registry Configuration utility.

The system displays the following questions:

1. The system prompts you to enter standalone or cluster information. The system displays the following message:

   Is this system now a node in a cluster or will this system become part of a cluster? (Y/N/Q):

2. The system displays the current information about the REG$TO_BE_STARTED logical, then prompts you to change the value.

   - REG$TO_BE_STARTED - [current value of REG$TO_BE_STARTED] NOTE: Setting this logical to TRUE starts the OpenVMS Registry server automatically when the system boots. Setting this logical to FALSE prevents the OpenVMS Registry server from starting when the system boots and prevents other products from starting the OpenVMS Registry server. If the OpenVMS Registry Server is not started at boot time, but other products that require an OpenVMS Registry server are able to start the OpenVMS Registry server, you do not need to assign a value to this logical. Do you want to change this value? (Y/N/Q) [Y]:

   
   If you choose Y , the system prompts you for the new value.

   Enter the new value (TRUE/FALSE/NOVAL/Q):

   
   Enter one of the following:

   Action	Value
   Start the OpenVMS Registry server on reboot. Allow other products to start the server.	TRUE
   Do not start the OpenVMS Registry server on reboot. Do not allow other products to start the server.	FALSE
   Do not start the OpenVMS Registry server on reboot. Allow other products to start the server. (Deassigns the logical name.)	NOVAL
   Quit this procedure and return to the OpenVMS Registry Configuration utility menu.	Q

   In which logical name table do you want the logical defined? (SYSTEM/SYSCLUSTER/Q) :

   
   Enter one of the following:

   Action	Value
   Add the REG$TO_BE_STARTED logical to the LNM$SYSTEM logical name table. This table contains names that are shared by all processes in the system.	SYSTEM
   Add the REG$TO_BE_STARTED logical to the LNM$SYSCLUSTER logical name table. This table contains names that are shared by all processes in an OpenVMS Cluster.	SYSCLUSTER
   Quit this procedure and return to the OpenVMS Registry Configuration utility menu.	Q

   
   After you enter the new or updated value, the system confirms the change and displays the line you must add to your SYLOGICALS.COM file, if you have selected the SYSTEM table, or to the end of the SYSTARTUP_VMS.COM file, if you have selected the SYSCLUSTER table.

   The logical REG$TO_BE_STARTED has been temporarily defined. Before you reboot the system you must edit your SYLOGICALS.COM to include the line: DEFINE/TABLE=table-name REG$TO_BE_STARTED value Press [Enter] to continue.

3. The system displays the current information about the SYS$REGISTRY logical, then prompts you to change the value.

   - SYS$REGISTRY logical - current value of SYS$REGISTRY Note: When the OpenVMS Registry server is started, the system creates an OpenVMS Registry database at this location. If an OpenVMS Registry database already exists on your system, you must redefine the SYS$REGISTRY logical to point to the existing OpenVMS Registry database location. Do you wish to change this value? (Y/N/Q) [Y]:

   
   If you choose Y , the system prompts you for the new value.

   Enter the new value for SYS$REGISTRY ("yourvalue"/NOVAL/Q):

   
   Enter one of the following:

   Action	Value
   Define a new or changed location for the OpenVMS Registry database.	A valid directory specification, such as DKA0: [SYS$REGISTRY].
   Deassign the logical name.	NOVAL
   Quit this procedure and return to the OpenVMS Registry Configuration utility menu.	Q

4. The system displays your updated value and prompts you to confirm the value.

   You have entered: value Is this correct? (Y/N/Q) [Y]:

5. The system prompts you to enter a logical table name in which to store the new or updated logical.

   In which logical name table do you want the logical defined? (SYSTEM/SYSCLUSTER/Q):

   
   Enter one of the following:

   Action	Value
   Add the SYS$REGISTRY logical to the LNM$SYSTEM logical name table. This table contains names that are shared by all processes in the system.	SYSTEM
   Add the SYS$REGISTRY logical to the LNM$SYSCLUSTER logical name table. This table contains names that are shared by all processes in an OpenVMS Cluster.	SYSCLUSTER
   Quit this procedure and return to the OpenVMS Registry Configuration utility menu.	Q

   
   After you enter the new or updated value, the system confirms the change and displays the line you must add to your SYLOGICALS.COM file, if you have selected the SYSTEM table, or to the end of the SYSTARTUP_VMS.COM file, if you have selected the SYSCLUSTER table.

   The logical SYS$REGISTRY has been temporarily defined. Before you reboot the system you must edit your SYLOGICALS.COM file to include the line: DEFINE/TABLE=table-name SYS$REGISTRY dir-spec Press [Enter] to continue.

6. The system displays information about the location of the OpenVMS Registry database.

   - SYS$REGISTRY directory - [directory status]

   
   If the directory does not exist, the system prompts you to create the directory.

   !!Caution!! When the OpenVMS Registry server starts, the system creates an OpenVMS Registry database at this location. If you already have an OpenVMS Registry database on your system, you must redefine the SYS$REGISTRY logical to point to that location. Do you wish to create the directory? (Y/N/Q) [Y]:

   
   If you enter Y the system confirms the directory creation.

   The SYS$REGISTRY directory has now been created. Press [Enter] to return to the menu.

Beginning with OpenVMS Version 7.3-1, the OpenVMS Registry supports two database formats, Version 1 and Version 2. The Version 2 database format includes an index access that improves on the access performance provided in the Version 1 database format.

The Registry server supports both database formats. To take advantage of the indexing feature, you must convert a Version 1 database to the Version 2 format.

Who Should Convert

Converting the Registry database is optional. Large databases are more likely to benefit from converting to Version 2. The more subkeys or values on a key, the more likely it is that there will be a performance improvement from using the Version 2 database. For databases where there are only one or two subkeys or values on most keys, converting to Version 2 will yield minimal performance improvement.

Who Should Not Convert

Do not convert the Registry database to Version 2 if you plan to run Registry servers on nodes in a mixed-version cluster. Registry servers on nodes running versions of OpenVMS prior to Version 7.3-1 cannot access a Version 2 database. Operating in this manner is not supported.

13.1.2.1 Converting an Existing Database

To convert an existing database to Version 2, invoke REG$CONFIG and select step 5, "Convert to latest database version and/or reclaim database," and follow the instructions. Be sure to invoke REG$CONFIG on a node that normally runs the Registry server. You cannot run REG$CONFIG on a node that explicitly disables the Registry server, that is, a node on which the REG$TO_BE_STARTED logical is FALSE.

The command procedure saves a copy of the current database in a separate directory, both in binary and EXPORT command (ASCII text) format.

The procedure requires an interruption in Registry services, so execute it at a time when this will cause minimal disruption. Prior to shutting down the Registry server, you must also shut down all layered products that use the Registry: COM for OpenVMS, Advanced Server for OpenVMS, and any other third-party applications.

Be sure to shut down these applications on all nodes in the cluster.

The command procedure informs you when to shut down these services and pauses while you perform this task. You should shut down in this order:

1. Shut down any third-party applications that use Registry.
2. Shut down COM for OpenVMS using SYS$STARTUP:DCOM$SHUTDOWN.COM.
3. Shut down Advanced Server for OpenVMS using SYS$STARTUP:PWRK$SHUTDOWN.COM.
4. Shut down the Registry server on all nodes in the cluster.

There are several ways to determine the version of a given Registry database.

• For a database currently in use, enter the command:

  $ REG$CP == "$REG$CP" $ REG$CP LIST VALUE HKEY_LOCAL_MACHINE\SYSTEM\REGISTRY

  
  The value Database Version contains the version of the database currently loaded. Database versions prior to Version 2 do not have a Database Version value.

• For an exported database, look for the following statement in the exported database file:

  Database Version"=dword:00000002"

  
  Exported databases prior to Version 2 do not contain this statement.

• The files SYS$MANAGER:REGISTRY$SERVER.LOG and .ERR identify the version of the database opened by the Registry server when it starts up.
• For a given set of registry files, dump the REGISTRY$ROOT.DAT file. The second longword indicates the database version.

You can also use Step 5 in REG$CONFIG to reclaim the database, which reclaims wasted space that can occur over time as the database becomes fragmented. Follow the same instructions as for converting the database. You can repeat this procedure as often as you like.

REG$CONFIG does not allow you to reclaim a Version 1 database. However, you can manually reclaim a Version 1 database by performing the steps in the following section.

13.1.2.4 Manual Conversion and Reclamation

Conversion and reclamation of a database use the Registry Import/Export feature. The current Registry database is exported, a new database is created, then the original database is imported. You can perform these steps manually as follows:

1. Shut down all applications in the cluster that use Registry (described in Section 13.1.2.1), including COM for OpenVMS and Advanced Server.
2. Enter the following command:

   $ REG$CP == "$REG$CP" $ REG$CP EXPORT DATABASE/OUTPUT=(filespec)

   
   If you do not specify a value for /OUTPUT, it defaults to REGISTRY.TXT in your current default directory. The output format defaults to /FORMAT=VMS. Do not specify /FORMAT=NT in this step.

3. Shut down the Registry server on all nodes in the cluster using the following command:

   $ SET SERVER REGISTRY/CLUSTER/EXIT

4. Preserve the current database by copying all of the files in SYS$REGISTRY to a separate directory.
5. Delete all the files in SYS$REGISTRY with the exception of REGISTRY$CONFIGDONE.DAT.
6. Start the Registry server on one node in the cluster using the following command:

   $ SET SERVER REGISTRY/START [/NODE=node]

7. Create a new Registry database using the following command:

   $ REG$CP == "$REG$CP" $ REG$CP CREATE DATABASE

   Note The new database will default to a Version 2 database. To reclaim without converting to Version 2, enter the following command: $ REG$CP == "$REG$CP" $ REG$CP CREATE DATABASE/VERSION=1

8. Import the original database using the following command:

   $ REG$CP == "$REG$CP" $ REG$CP IMPORT/INPUT=(filespec-from-step-2)

   
   If you do not specify a value for /INPUT, it defaults to REGISTRY.TXT in your current default directory.

9. Start the Registry server on any remaining nodes on which you want it to run (see Step 6).
10. Restart any applications that were stopped in Step 1.

You can control how the OpenVMS Registry will start as follows:

• Start the OpenVMS Registry automatically when the system reboots.
• Have products that require the OpenVMS Registry to be running start the OpenVMS Registry.
• Start the OpenVMS Registry manually.
• Prevent the OpenVMS Registry from starting.

Use the OpenVMS Registry Configuration utility to control how the OpenVMS Registry starts.

13.2.1 Starting the OpenVMS Registry Manually

Under some conditions, you might want to start the OpenVMS Registry server manually.

HP recommends that you use the SYS$STARTUP:REG$STARTUP.COM command procedure. The following command procedure ensures that the server process quotas are set to the required minimum values:

$ @SYS$STARTUP:REG$STARTUP.COM

Alternately, you can use the following command to start the OpenVMS Registry manually:

$ SET SERVER REGISTRY_SERVER/START

13.3 Shutting Down the OpenVMS Registry

The OpenVMS Registry server is shut down automatically as part of a system shutdown.

If you want to shut down the OpenVMS Registry manually, use the following command:

$ SET SERVER REGISTRY_SERVER/EXIT

13.4 OpenVMS Registry Server Commands

The OpenVMS Registry server commands allow you to display (SHOW) and change (SET) the state of the OpenVMS Registry server. The following sections list and describe the OpenVMS Registry server commands.

Show the current status of the OpenVMS Registry on a specified node.

This command requires the SYSPRV privilege.

Format

SHOW SERVER REGISTRY_SERVER

[/MASTER | /CLUSTER | /NODE=(node ,...)]

[/PAGE]

Qualifiers

/MASTER

Displays the node and process ID (PID) of the current OpenVMS Registry master server in the cluster. This command does not communicate with the OpenVMS Registry servers in the cluster. Requires the SYSPRV privilege.

/CLUSTER

Returns the show output from each OpenVMS Registry server in the cluster, listing the OpenVMS Registry master server information first.

/NODE=(node,...)]

Returns OpenVMS Registry server information about the servers on the specified nodes, listed in the order in which you enter the node names. The node names you specify must be in the current cluster.

/PAGE

Displays the returned show output in a scrollable page display.

Change the state of the OpenVMS Registry.

This command requires the SYSPRV privilege.

Format

SET SERVER REGISTRY_SERVER

[/MASTER | /CLUSTER | /NODE=(node ,...)]

[/START | /RESTART | /EXIT | /ABORT ]

[/[NO]LOG ]

Qualifiers

/MASTER

Issues the specified command to the OpenVMS Registry master server only. Requires the SYSPRV privilege.

/CLUSTER

Issues the SET command to each OpenVMS Registry server in the cluster, setting the OpenVMS Registry master server last.

/NODE=(node,...)

Issues the SET command to the OpenVMS Registry servers on the specified nodes, in the order in which you enter the node names. The node names must be in the current cluster.

/START[=(node,...)]

Starts the OpenVMS Registry server on the specified node or nodes in the cluster.

/EXIT[=(node,...)]

Stops the OpenVMS Registry server on the specified node or nodes in the cluster.

/ABORT[=(node,...)]

Aborts the OpenVMS Registry server on the specified node or nodes in the cluster.

/[NO]LOG

Creates a new OpenVMS Registry log file in SYS$REGISTRY. NOLOG is the default.

13.5 OpenVMS Registry Failover in a Cluster

There can be more than one Registry server in a cluster, but only one server functions as the master server. The other servers function as backup servers in case the master server or the node it is running on fails.

By default, the first OpenVMS Registry server process that is active in the cluster remains active until either the process no longer exists or the priority among OpenVMS Registry server processes changes.

13.5.1 Changing the Priority of OpenVMS Registry Server Processes

You can change the priority of OpenVMS Registry server processes by creating and modifying the priority value of each node in the cluster that will run the OpenVMS Registry server process: the higher the value, the higher the priority.

The Registry servers use a priority scheme to determine which server is the master. This scheme is provided so that a system manager can weigh one server against another, depending on the system capabilities. For example, the system manager may want the server master to normally run on the fastest system. This priority is determined by a Registry value and should not be confused with process priority.

Setting the priority of a Registry server is not required. If the server priorities have not been set, all servers run at the same priority. In this case, the server that starts executing first is the master server.

Example 13-1 shows priority values being assigned so that NODENAME1 will be the active OpenVMS Registry server process in the cluster.

Example 13-1 Setting Priority Values

$ REG$CP == "$REG$CP" $ CREATE VALUE HKEY_LOCAL_MACHINE\SYSTEM\REGISTRY\PRIORITY - _$ /NAME=NODENAME1/DATA=15/TYPE=DWORD $ REG$CP CREATE VALUE HKEY_LOCAL_MACHINE\SYSTEM\REGISTRY\PRIORITY - _$ /NAME=NODENAME2/DATA=10/TYPE=DWORD $ REG$CP CREATE VALUE HKEY_LOCAL_MACHINE\SYSTEM\REGISTRY\PRIORITY - _$ /NAME=NODENAME3/DATA=5/TYPE=DWORD

In Example 13-1, if NODENAME1 shuts down, control of the OpenVMS Registry database passes to the server process on NODENAME2 .

Example 13-2 shows the system manager increasing the priority value of NODENAME3 to 20.

Example 13-2 Changing Priority Values

$ REG$CP == "$REG$CP" $ REG$CP MODIFY VALUE HKEY_LOCAL_MACHINE\SYSTEM\REGISTRY\PRIORITY - _$ /NAME=NODENAME3/DATA=20/TYPE=DWORD

In Example 13-2, the OpenVMS Registry server process on NODENAME1 goes into standby mode and the OpenVMS Registry server process on NODENAME3 becomes active.

13.6 Connecting to the OpenVMS Registry from a Windows System

To connect to the OpenVMS Registry from a Windows system, you must do the following:

• On the OpenVMS system:
  • Install the HP Advanced Server for OpenVMS.
  • Configure the HP Advanced Server for OpenVMS.
• On the Windows system:
  • Install and configure any required hardware.
  • Install and configure the Windows Server or Workstation software.

When you access the OpenVMS Registry database from a Windows system, you will have all the privileges granted on your Windows system. For example, if you are logged on to the Windows system as an Administrator, you will be able to read and write to all keys and values in the OpenVMS Registry. Access to OpenVMS Registry keys is based on your Windows user profile ( username and Group membership). Connect to the OpenVMS Registry through HP Advanced Server for OpenVMS; use the Windows Regedt32 application to view and change keys, values, and security settings.

A quota mechanism limits the size of the OpenVMS Registry database. The system assigns a quota to the root key datafile for every OpenVMS Registry file. By default, these root keys are the USERS key ( REGISTRY$USERS.REG ) and the LOCAL_MACHINE key ( REGISTRY$LOCAL_MACHINE.REG ).

The quota limits the size of the information contained within the file but does not include the size of information stored in other files, even if the files are part of the subtree.

The default quota and file-specific quotas are stored in the OpenVMS Registry under the HKEY_LOCAL_MACHINE\SYSTEM\Registry key. For more information about these keys, see Section 12.3.

13.8 OpenVMS Registry Security

A user can access (read and modify) the OpenVMS Registry directly in the following ways:

• From a Windows system (through a connection through HP Advanced Server for OpenVMS)
• Using the OpenVMS Registry system services ($REGISTRY[W])
• Using the OpenVMS Registry server management utility ( REG$CP )

For a discussion of what system privileges and right identifiers each user needs, see Section 12.6.1. For a description of how to grant the necessary system privileges and right identifiers, see Section 12.6.1.1.

You can change a key's security attributes only from a Windows system---you cannot change a key's security attributes from an OpenVMS system. OpenVMS does not create or manage Windows security attributes.

13.9 Backing Up and Restoring the OpenVMS Registry Database

The OpenVMS Registry includes a server management utility that allows you to back up and restore the entire OpenVMS Registry database to or from a file from the OpenVMS DCL prompt as long as you have the required system privileges.

For more information about backing up and restoring the OpenVMS Registry database, see Section 14.2 and the REG$CP server management utility CREATE SNAPSHOT command and the EXPORT command.

13.10 Internationalization and Unicode Support

To integrate with Windows, the OpenVMS Registry is Unicode compliant. For more information about Unicode, see the OpenVMS Guide to Extended File Specifications.