OpenVMS Connectivity Developer Guide


Previous Contents Index


Chapter 10
COM for OpenVMS and DLL Surrogates

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:

10.1 Running Your Components in the Context of a DLL Surrogate

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.


Chapter 11
COM for OpenVMS and IEEE Floating Point

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:

11.2 Restrictions Using IEEE Floating-Point Values in COM for OpenVMS Applications

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:


Part 2
OpenVMS Registry

The following chapters describe the OpenVMS Registry database and its structure.


Chapter 12
Overview of OpenVMS Registry

12.1 What is the Registry?

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:

12.2 OpenVMS Registry Concepts and Definitions

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:

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:

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:

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:

12.2.2 Class

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:

12.4 Reading and Writing to the OpenVMS Registry

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

12.4.1 $REGISTRY System Services

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?
  2. Does the user have the OpenVMS SYSPRV privilege?
  3. Does the user have the REG$UPDATE , REG$LOOKUP , or REG$PERFORMANCE rights identifier?
  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:

12.5.1.1 Granting OpenVMS Registry Access Rights Using the AUTHORIZE Utility

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.

Caution

Granting OpenVMS Registry rights overrides Windows NT security access checks.

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.

12.5.2 Windows NT Security Model

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


Chapter 13
OpenVMS Registry System Management

13.1 Installing the OpenVMS Registry

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:

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:

Tip: Enter Q (Quit) at any time

You can enter Q at any prompt to return to the OpenVMS Registry Configuration utility menu.

If you quit while you are configuring logical names, the system updates only those values for which you have received a confirmation message.

13.2.1 Configuring OpenVMS Registry Values

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. 
    

13.3 Starting the OpenVMS Registry

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

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 SERVER REGISTRY_SERVER

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.

SET SERVER REGISTRY_SERVER

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

To increase the availability and reliability of the OpenVMS Registry, you can run multiple OpenVMS Registry servers in a cluster, up to one per node. No matter how many OpenVMS Registry servers you run, you have only one OpenVMS Registry database.

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:

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.

Caution

Be careful when you modify OpenVMS Registry database keys and values. If you damage the OpenVMS Registry database, you can affect all applications and users on the entire OpenVMS system or cluster.

13.8 OpenVMS Registry Quotas

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:

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.


Chapter 14
OpenVMS Registry Server Management

14.1 Managing the OpenVMS Registry Server from the Command Line

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 

Note

Before you can access the OpenVMS Registry database, the OpenVMS Registry server must be running either in the cluster or on the standalone system.

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.

Note

A user who has the SYSPRV privilege can can execute all the commands listed in Table 14-1. You must specify an OpenVMS Registry identifier only if the user does not have SYSPRV privilege.

If you grant a user the REG$UPDATE identifier, in addition to the commands listed in Table 14-1, the user can also execute the following commands:

LIST KEY
LIST VALUE
SEARCH KEY
SEARCH VALUE

If you do not grant a user the REG$LOOKUP identifier, the user cannot examine keys (LIST KEY, LIST VALUE, SEARCH KEY, SEARCH VALUE, or EXPORT KEYs or DATABASE) that are protected from world read access. However, the default for almost all keys created in a new database is world read access. The exceptions are keys that have ACLs that prohibit world read access. For example, a user who does not have the REG$LOOKUP identifier cannot execute the following command:


$ MC REG$CP LIST KEY HKEY_LOCAL_MACHINE\SECURITY 

14.2 Backing Up and Restoring the OpenVMS Registry Database

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

14.2.1 Creating a Snapshot of the OpenVMS Registry Database

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 
    

14.2.2 Restoring a Snapshot of the OpenVMS Registry Database

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

Caution

Any information that the system has written to the OpenVMS Registry database between the time of the last snapshot and this restore process will be lost.

14.3 OpenVMS Registry Server Management Utility Syntax

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

Note

In all the commands in this section, the key-name parameter is a string that specifies the full path of the key, beginning from one of following entry points:
HKEY_LOCAL_MACHINE
HKEY_USERS
HKEY_CLASSES_ROOT

You can also specify the strings REG$_HKEY_LOCAL_MACHINE , REG$_HKEY_USERS , and REG$_HKEY_CLASSES_ROOT .

For all server management commands, links are not followed. (For more information about links, see Section 12.2.1.3.)

To make key and values names case sensitive, enclose the keys and values in quotation marks (for example: "value" ).


CREATE DATABASE

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.


CREATE KEY

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:

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:

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


CREATE SNAPSHOT

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


CREATE VALUE

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:

/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:

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:

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


Previous Next Contents Index