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 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\Priority"

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. For more information, see Section 12.4.1.
• From Windows NT, through the Windows NT Registry APIs, or using RegEdt32 (the Windows NT Registry Editor). This allows Windows NT 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.4.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.5 OpenVMS Registry Security

The OpenVMS Registry implements both the OpenVMS and Windows NT 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.5.1 OpenVMS Security Model

When a user requests access to the OpenVMS Registry, the OpenVMS system checks the user's Windows NT credentials and allows access as follows:

1. Does the user have Windows NT credentials?
   • If the user has Windows NT credentials because the user has connected to OpenVMS from a Windows NT system, OpenVMS allows the user access to the OpenVMS Registry based on the user's supplied credentials.
   • If the user has Windows NT credentials because the user is a COM Version 1.1-B for OpenVMS client, OpenVMS allows the user access to the OpenVMS Registry based on the user's supplied credentials.
   • If the user has Windows NT credentials because the user has logged on to OpenVMS through single signon, OpenVMS allows the user access to the OpenVMS Registry based on the user's supplied credentials.
     If the user is not allowed access to the OpenVMS Registry based on the user's supplied credentials, skip to Step 2.
   • If the user does not have Windows NT 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 NT credentials, OpenVMS grants the OpenVMS user Windows NT 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 user processes.

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 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 NT users can access the OpenVMS Registry only through the Compaq Advanced Server for OpenVMS. OpenVMS grants Windows NT users access to the OpenVMS Registry based on the user's Windows NT credentials.

12.6 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.6.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.6.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.6.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 server recalculates the file quota every 30 seconds.

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

12.6.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.6.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.6.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.6.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.6.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.6.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.6.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 Version 7.2-1 system installation.

Before you can use the OpenVMS Registry, you must configure the OpenVMS Registry server and populate the OpenVMS Registry database. For more information about configuring the OpenVMS Registry server, see Section 13.2. For more information about populating the OpenVMS Registry database, see Section 6.2.

The first time you start the OpenVMS Registry server using the startup process described in Section 13.3, 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. For more information, see Chapter 4.
• If you want to access the OpenVMS Registry using the Windows NT application RegEdt32 , you must first install, configure, and start Compaq Advanced Server for OpenVMS. For more information, see the Compaq 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 in OpenVMS Version 7.2-1.

13.2 Configuring the OpenVMS Registry: the REG$CONFIG Configuration Utility

The OpenVMS Registry Configuration utility (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 start the OpenVMS Registry Configuration utility:

$ @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 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.2.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.

• 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/CLUSTER/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
   Add the REG$TO_BE_STARTED logical to the LNM$CLUSTER logical name table. This table is the parent table for all clusterwide logical name tables.	CLUSTER
   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.

   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/CLUSTER/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
   Add the SYS$REGISTRY logical to the LNM$CLUSTER logical name table. This table is the parent table for all clusterwide logical name tables.	CLUSTER
   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.

   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.

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 described in Section 13.2 to control how the OpenVMS Registry starts.

13.3.1 Starting the OpenVMS Registry Manually

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

Compaq 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.4 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.5 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 SYSLCK privilege as well as 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 SYSLCK privilege as well as 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.6 OpenVMS Registry Failover in a Cluster

When you run more than one OpenVMS Registry server in a cluster, only one OpenVMS Registry server process is active and writing to the OpenVMS Registry database. The other OpenVMS Registry server processes are standing by.

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

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

$ mcr reg$cp REG> CREATE VALUE HKEY_LOCAL_MACHINE\SYSTEM\REGISTRY\PRIORITY - _REG> /NAME=NODENAME1/DATA=15/TYPE=DWORD REG> CREATE VALUE HKEY_LOCAL_MACHINE\SYSTEM\REGISTRY\PRIORITY - _REG> /NAME=NODENAME2/DATA=10/TYPE=DWORD REG> CREATE VALUE HKEY_LOCAL_MACHINE\SYSTEM\REGISTRY\PRIORITY - _REG> /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

$ mcr reg$cp REG> MODIFY VALUE HKEY_LOCAL_MACHINE\SYSTEM\REGISTRY\PRIORITY - _REG> /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.7 Connecting to the OpenVMS Registry from a Windows NT System

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

• On the OpenVMS system:
  • Install the Compaq Advanced Server for OpenVMS.
  • Configure the Compaq Advanced Server for OpenVMS.
• On the Windows NT system:
  • Install and configure any required hardware.
  • Install and configure the Windows NT 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 NT system. For example, if you are logged on to the Windows NT 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 NT user profile ( username and Group membership). Connect to the OpenVMS Registry through Compaq 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.9 OpenVMS Registry Security

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

• From a Windows NT system (through a connection through Compaq 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.5.1. For a description of how to grant the necessary system privileges and right identifiers, see Section 12.5.1.1.

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

13.10 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.11 Using the OpenVMS Registry in an OpenVMS Alpha Mixed-Version Cluster

The OpenVMS Registry Server can run in an OpenVMS Alpha mixed-version cluster. That is, the OpenVMS Registry can run in a cluster that includes OpenVMS versions other than OpenVMS Version 7.2-1; but the OpenVMS Registry server must be running on the node that is running OpenVMS Version 7.2-1.

13.12 Internationalization and Unicode Support

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

The OpenVMS Registry includes a server management utility that allows you to update and display 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 backing up and restoring the OpenVMS Registry database, see Section 14.2 and the CREATE SNAPSHOT, EXPORT, and IMPORT commands in the command reference section of this chapter.

To start the OpenVMS Registry server management utility, enter one of the following commands:

$ RUN SYS$SYSTEM:REG$CP

or

$ MCR REG$CP

Table 14-1 lists and describes OpenVMS Registry server management utility commands.

Table 14-1 OpenVMS Registry Server Management Utility Commands

Command	Identifier	Action
CREATE DATABASE	SYSPRV	Creates a new OpenVMS Registry database file.
CREATE KEY	REG$UPDATE	Creates one or more keys in the OpenVMS Registry database.
CREATE SNAPSHOT	SYSPRV	Makes an immediate backup of the OpenVMS Registry database files.
CREATE VALUE	REG$UPDATE	Specifies the data component for a key.
DELETE KEY	REG$UPDATE	Removes one or more keys from the OpenVMS Registry database.
DELETE VALUE	REG$UPDATE	Removes one or more values from a specified key.
EXPORT	REG$LOOKUP	Exports the OpenVMS Registry to a text format.
IMPORT	REG$UPDATE	Imports a text-formatted version of a registry database to the OpenVMS Registry format.
LIST KEY	REG$LOOKUP	Displays all subkey information for a specified key.
LIST VALUE	REG$LOOKUP	Displays all values of a specified key.
MODIFY KEY	REG$UPDATE	Modifies the information of a specified key.
MODIFY VALUE	REG$UPDATE	Modifies the information of a specified value.
MODIFY TREE	REG$UPDATE	Modifies the information of a specified key and its subkeys.
SEARCH KEY	REG$LOOKUP	Displays the path name of all keys that match a specified key.
SEARCH VALUE	REG$LOOKUP	Displays the path name of all keys that match a specified value name.
SHOW COUNTERS	REG$PERFORMANCE	Displays counter information.
SHOW FILE	REG$PERFORMANCE	Displays OpenVMS Registry database file statistics.
SHOW INTERNAL	REG$PERFORMANCE	Displays internal values (used by shared libraries).
START MONITOR	REG$PERFORMANCE	Enables monitoring functions.
STOP MONITOR	REG$PERFORMANCE	Disables monitoring functions.
ZERO COUNTERS	REG$PERFORMANCE	Resets monitoring counters.

The REG$CP server management utility includes two commands that allow you to back up and restore an OpenVMS Registry database.

• The EXPORT command allows you to back up the OpenVMS Registry keys and values on demand in OpenVMS or Windows NT format.
  You can use this command to export part or all of an OpenVMS Registry database. The corresponding IMPORT command allows you to restore or import OpenVMS Registry or Windows NT Registry keys and values.
  For more information, see the EXPORT and IMPORT commands in the command reference section of this chapter.
• The CREATE SNAPSHOT command allows you to back up the OpenVMS Registry database files automatically on a specified schedule.
  By default, the REGISTRY_SERVER process creates a snapshot of the OpenVMS Registry database every 24 hours. You can change this interval by modifying the Snapshot Interval setting in the OpenVMS Registry server operations. (For more information about these operations, see Section 12.6.)
  The following example shows how to modify the interval between automatic snapshots of the OpenVMS Registry database from the default of once every 24 hours to once every hour.

  $ MCR REG$CP REG> MODIFY VALUE HKEY_LOCAL_MACHINE\SYSTEM\REGISTRY - _REG> /NAME="Snapshot Interval"/DATA=3600/TYPE=DWORD

  
  For more information, see the CREATE SNAPSHOT command in this chapter.

Use the following procedure to create a snapshot of the OpenVMS Registry database:

1. Verify that the REGISTRY_SERVER process is running in the cluster.
2. From an account with the SYSPRV privilege, enter the following commands:

   $ MCR REG$CP REG> CREATE SNAPSHOT

   
   The resulting snapshot consists of the following two files, located in the specified directory:

   REGISTRY$LOCAL_MACHINE.RSS REGISTRY$USERS.RSS

Use the following procedure to restore a snapshot of the OpenVMS Registry database:

1. Shut down the REGISTRY_SERVER process on all nodes in the cluster. (For information about shutting down the OpenVMS Registry, see Section 13.4.)
2. Verify that the OpenVMS Registry snapshot files are in the SYS$REGISTRY directory.
   If the OpenVMS Registry snapshot files are not in the SYS$REGISTRY directory, copy the OpenVMS Registry snapshot files to the SYS$REGISTRY directory.
3. Rename the OpenVMS Registry snapshot files as follows:

   $ RENAME REGISTRY$LOCAL_MACHINE.RSS REGISTRY$LOCAL_MACHINE.REG $ RENAME REGISTRY$USERS.RSS REGISTRY$USERS.REG

4. Restart the REGISTRY_SERVER process. (For information about starting the OpenVMS Registry manually, see Section 13.3.1.)

The following command section describes each OpenVMS Registry command in alphabetical order.

Creates the basic OpenVMS Registry database files in the location specified by the SYS$REGISTRY logical. The command creates an empty database and loads the predefined keys.

If you enter this command and the database files already exist, the utility does not overwrite the existing files. The system displays a warning that the files already exist. If you want to create a new OpenVMS Registry database, you must first delete all previous versions of the database files. If you delete the OpenVMS Registry database files, you will lose all keys, subkeys, and values stored in the OpenVMS Registry.

This command requires the SYSPRV privilege.

The following table lists and describes the OpenVMS Registry database files.

File	Description
REGISTRY$ROOT.DAT	Root of the database
REGISTRY$USERS.REG	HKEY_USERS tree
REGISTRY$LOCAL_MACHINE.REG	HKEY_LOCAL_MACHINE tree
REGISTRY$MASTER.RLG	The master commit log file
REGISTRY$REPLY.RLG	Log file that tracks modification requests to the OpenVMS Registry database

Format

CREATE DATABASE

Parameters

None

Qualifiers

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

Examples

REG> CREATE DATABASE

Regenerates the basic OpenVMS Registry database files if the database files are lost or deleted.

Creates one or more keys in the OpenVMS Registry database.

This command requires the SYSPRV privilege or the REG$UPDATE rights identifier.

Format

CREATE KEY key-name [,...]

Parameters

key-name[,...]

Specifies the name of the key to create. You can create multiple keys by separating the keys with commas

Qualifiers

/CACHE_ACTION=value

Specifies the cache attribute for the new key. The value can be WRITEBEHIND (default) or WRITETHRU (write to disk immediately).

/CLASS_NAME=string

Specifies the class name of the key.

/LINK=(TYPE=value, NAME=key-name)

Defines the key as a link to another key. The link value must be one of the following:

• SYMBOLICLINK
• NONE

To remove a link, enter the following:

/LINK=(TYPE=NONE,NAME="")

/SECPOLICY=policy

Defines the security policy for the key. Currently the only valid policy is NT_40 .

/VOLATILE=level
/NONVOLATILE (default)

Specifies whether or not the new key is volatile. If you are running the OpenVMS Registry on a standalone OpenVMS system, volatile keys are lost when the system reboots. If you are running the OpenVMS Registry in an OpenVMS cluster, volatile keys are lost when all nodes in the cluster are rebooted.

The values for level are as follows:

• NONE (same as /NONVOLATILE)
• CLUSTER

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

/WRITEBEHIND
/NOWRITEBEHIND (default)

Specifies that the key information must be written to disk immediately. /NOWRITEBEHIND specifies a write-through operation.

Examples

REG> CREATE KEY/CACHE_ACTION=WRITEBEHIND HKEY_USERS\GUEST, HKEY_USERS\SYSTEM

Creates the GUEST and SYSTEM keys under the HKEY_USERS entry point. The keys are created with the write-behind attribute.

Creates a snapshot of the OpenVMS Registry database. That is, the system writes all cached OpenVMS Registry keys or values and makes a copy of the OpenVMS Registry database files.

This command requires the SYSPRV privilege.

Format

CREATE SNAPSHOT

Parameters

None

Qualifiers

/DESTINATION=file-spec

Controls where the system will write the snapshot files. By default, the system creates the snapshot in the location specified by the SYS$REGISTRY logical.

If you specify the /DESTINATION qualifier but do not provide a valid directory, the system creates the snapshot files in the directory in which you started the OpenVMS Registry server.

/VERSIONS=number

Specifies how many previous versions of the snapshot files to keep.

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

Examples

REG> CREATE SNAPSHOT/DESTINATION=SYS$REGISTRY/VERSION=3

Creates a snapshot of the OpenVMS Registry database in the SYS$REGISTRY directory. If more than three versions of the OpenVMS Registry database snapshot files exist, the system deletes the oldest version (the same as purge/keep=3 command).

Specifies the data component for the specified key. If the value does not exist, the command creates the value.

This command requires the SYSPRV privilege or the REG$UPDATE rights identifier.

Format

CREATE VALUE key-name

Parameters

key-name

Specifies the name of the key for which you will set the value.

Qualifiers

/DATA=value

The value can be one of the following:

• String (for example, /DATA=COSMOS )
• An array of strings separated by a comma and enclosed in parentheses (for example, /DATA=(COSMOS,Noidea)
• A longword in octal (%O), decimal, or hexadecimal (%X) format (for example, /DATA=%X1A0FCB or /DATA=1234 )

/FLAGS=flag

Specifies the data flags value. This is an application-dependent 64-bit flag specified as a decimal number or as a hexadecimal number preceded by 0x or %X.

/LINK=(TYPE=value, NAME=key-name)

Defines the key as a link to another key. The link value must be one of the following:

• SYMBOLICLINK
• NONE

To remove a link, enter the following:

/LINK=(TYPE=NONE,NAME="")

/TYPE_CODE=type

Specifies the type of the new value. The type value must be one of the following:

• SZ: a null-terminated Unicode string
• EXPAND_SZ: a string of Unicode characters
• MULTI_SZ: a concatenated array of SZ strings
• DWORD: a 32-bit number

/NAME=string

Specifies the name of the new value.

/WAIT=seconds
/NOWAIT

Specifies the number of seconds that the OpenVMS Registry should wait for the command to complete. By default, the OpenVMS Registry waits 90 seconds for the command to complete.

/WRITEBEHIND
/NOWRITEBEHIND (default)

Specifies that the value must be written to disk immediately. /NOWRITEBEHIND specifies a write-through operation.

Examples

REG> CREATE VALUE/DATA=COSMOS/TYPE=SZ/NAME=COMPUTERNAME HKEY_LOCAL_MACHINE\NODE

Creates the COMPUTERNAME value for the key HKEY_LOCAL_MACHINE\NODE and sets its type to SZ and its data value to COSMOS .