COM, Registry, and Events for
HP OpenVMS Developer's Guide


Previous Contents Index


Chapter 10
COM for OpenVMS and DLL Surrogates

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

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

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


Chapter 11
COM for OpenVMS and IEEE Floating Point

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

11.1 Running Sample Programs with IEEE Floating Point Values

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

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.

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

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


Chapter 12
Overview of OpenVMS Registry

12.1 What is the Registry?

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

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

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

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

12.1.1 Suggested Reading

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

12.2 OpenVMS Registry Concepts and Definitions

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

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

12.2.1 Keys, Subkeys, and Values

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

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

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

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

12.3 OpenVMS Registry Structure

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

The OpenVMS Registry includes the following predefined standard keys:

12.4 OpenVMS Registry Restrictions and Limitations

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

12.4.1 Registry Data Transfer Size Restriction Eased

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

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

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

12.5 Reading and Writing to the OpenVMS Registry

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

12.5.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.5.2 REG$CP Server Management Utility

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

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

12.6 OpenVMS Registry Security

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

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

The following sections describe the two models.

12.6.1 OpenVMS Security Model

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

  1. Does the user have Windows credentials?
    If the user has Windows credentials, OpenVMS allows the user access to the OpenVMS Registry based on the user's supplied credentials. The user can acquire Windows credentials through the following methods:
    If the user is not allowed access to the OpenVMS Registry based on the user's supplied credentials, or if the user does not have Windows credentials, continue to the next step.
  2. Does the user have the OpenVMS SYSPRV privilege?
  3. Does the user have the REG$UPDATE , REG$LOOKUP , or REG$PERFORMANCE rights identifier?
  4. If the user has no Windows credentials, OpenVMS grants the OpenVMS user Windows Everyone group access. In this case, the OpenVMS user's access to OpenVMS Registry keys depends on what permissions the key owner defined for Everyone when the key owner created the key or subkey. Based on these permissions, the OpenVMS user will be able to do one of the following:

12.6.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 users.

Caution

Granting OpenVMS Registry rights overrides Windows 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 identifiers on your system. Running the REG$CP server management utility creates these rights by default. You must run REG$CP from a privileged account. For more information about running REG$CP , see Chapter 14.

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



$ SET RIGHTS_LIST/ENABLE/SYSTEM REG$LOOKUP 

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

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


$ SET DEF SYS$SYSTEM 

$ RUN AUTHORIZE 

UAF> GRANT/IDENTIFIER REG$LOOKUP SMITH (1)

UAF> GRANT/IDENTIFIER/ATTRIBUTES=DYNAMIC REG$UPDATE SMITH (2)

UAF> REVOKE/IDENTIFIER REG$UPDATE SMITH (3)

UAF> GRANT/IDENTIFIER REG$PERFORMANCE SYSTEM (4)

 

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

12.6.2 Windows Security Model

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

12.7 Controlling the OpenVMS Registry Server Operations

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

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

12.7.1 Defining Maximum Reply Age/Age Checker Interval Settings

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

By default, the server checks for old completed requests every five seconds. By default, the server discards completed requests that are older than five seconds.
Setting Name Default value Minimum value Maximum value
Maximum Reply Age 5 1 60
Age Checker Interval 5 1 60

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

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

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

By default, the log file is applied every five seconds. By default, the OpenVMS Registry log file is created using a size of 32 blocks (16 KB).
Setting Name Default value Minimum value Maximum value
Database Log Cleaner Interval 5 1 30
Initial Log File Size 32 16 256

12.7.3 Defining Default File Quota/File Quota Interval Settings

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

Note

The File Quota Interval setting is used by Registry servers prior to OpenVMS V7.3-1 only.

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

By default, the Default File Quota setting is 10 MB. By default, the File Quota Interval setting is 30 seconds.
Setting Name Default value Minimum value Maximum value
Default File Quota 0x10000000 0x7d00 0x3fffffff
File Quota Interval 30 10 60

12.7.4 Defining the Scan Interval Setting

Note

The Scan Interval setting is used by Registry servers prior to OpenVMS Version 7.3-1 only.

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

By default, a server checks for changes in priority every 120 seconds.
Setting Name Default value Minimum value Maximum value
Scan Interval 120 60 300

12.7.5 Defining the Log Registry Value Error Setting

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

By default, the OpenVMS Registry server does not log out-of-range errors.
Setting Name Default value Minimum value Maximum value
Log Registry Value Error 0 0 1

12.7.6 Defining the Operator Communications Interval Setting

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

By default, the OpenVMS Registry server writes a message to the operator console if the error persists longer than 60 seconds.
Setting Name Default value Minimum value Maximum value
Operator Communication Interval 60 30 120

12.7.7 Defining the Process Time Limit Setting

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

By default, 180 seconds are allowed per request before the OpenVMS Registry logs a message.
Setting Name Default value Minimum value Maximum value
Process Time Limit 180 60 600

12.7.8 Defining the Reply Log Cleaner Interval Setting

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

By default, the OpenVMS Registry server discards replies every five seconds.
Setting Name Default value Minimum value Maximum value
Reply Log Cleaner Interval 5 5 60

12.7.9 Defining Snapshot Interval/Snapshot Location/Snapshot Versions Settings

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

By default, the OpenVMS Registry database is copied to backup once per day. By default, the OpenVMS Registry database is copied to the location determined by the definition of the SYS$REGISTRY logical name. By default, the OpenVMS Registry keeps five previous versions of the OpenVMS Registry database.
Setting Name Default value Minimum value Maximum value
Snapshot Interval 86400 3600 604800
Snapshot Location SYS$REGISTRY --- ---
Snapshot Versions 5 1 10

12.7.10 Defining the Write Retry Interval Setting

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

By default, the OpenVMS Registry server attempts to retry failed writes to the OpenVMS Registry database every five seconds.
Setting Name Default value Minimum value Maximum value
Writer Retry Interval 5 1 30


Chapter 13
OpenVMS Registry System Management

13.1 Installing the OpenVMS Registry

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

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

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

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

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

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

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



  $ @SYS$MANAGER:REG$CONFIG 

The system displays the following menu:



--------------------------------------------------------- 

 

        OpenVMS Registry Configuration Utility 

        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

        1 - Configure OpenVMS Registry logical names and directory paths 

 

        2 - Display OpenVMS Registry logical names and directory paths 

 

        3 - Check the state of the OpenVMS Registry server 

 

        4 - Start the OpenVMS Registry server on this node 

 

        5 - Convert to latest database version and/or reclaim database 

 

        H - Help about this utility 

 

       [E] - Exit 

 

Please enter your choice : 

--------------------------------------------------------- 

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

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.1.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/Q) : 
    
    

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

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


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

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


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

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


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

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

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


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

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


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

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

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


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

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


    
                 - SYS$REGISTRY directory - 
    
     
    
      [directory status]
    
     
    
    

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


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

    If you enter Y the system confirms the directory creation.


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

13.1.2 Registry Database Conversion and Compaction

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

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

Who Should Convert

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

Who Should Not Convert

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

13.1.2.1 Converting an Existing Database

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

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

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

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

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

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

13.1.2.2 Determining the Registry Database Version

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

Note

In all of the following cases, the database version is a longword (DWORD). The lower word is the major version, and the upper word is the minor version. Normally the minor version is zero.

13.1.2.3 Reclaiming the Database

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

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

13.1.2.4 Manual Conversion and Reclamation

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

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


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

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

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


    
    $ SET SERVER REGISTRY/CLUSTER/EXIT 
    
    

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


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

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


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

    Note

    The new database will default to a Version 2 database. To reclaim without converting to Version 2, enter the following command:


    
    $ REG$CP == "$REG$CP" 
    
    $ REG$CP CREATE DATABASE/VERSION=1 
    
    

  8. Import the original database using the following command:


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

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

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

13.2 Starting the OpenVMS Registry

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

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

13.2.1 Starting the OpenVMS Registry Manually

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

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



$ @SYS$STARTUP:REG$STARTUP.COM 

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



$ SET SERVER REGISTRY_SERVER/START 

13.3 Shutting Down the OpenVMS Registry

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

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



$ SET SERVER REGISTRY_SERVER/EXIT 

13.4 OpenVMS Registry Server Commands

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


SHOW 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 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 SYSPRV privilege.

/CLUSTER

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

/NODE=(node,...)

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

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

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

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

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

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

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

/[NO]LOG

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

13.5 OpenVMS Registry Failover in a Cluster

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.

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

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

13.5.1 Changing the Priority of OpenVMS Registry Server Processes

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

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

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

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

Example 13-1 Setting Priority Values


$ REG$CP == "$REG$CP" 

$ CREATE VALUE HKEY_LOCAL_MACHINE\SYSTEM\REGISTRY\PRIORITY - 

_$ /NAME=NODENAME1/DATA=15/TYPE=DWORD 

$ REG$CP CREATE VALUE HKEY_LOCAL_MACHINE\SYSTEM\REGISTRY\PRIORITY - 

_$ /NAME=NODENAME2/DATA=10/TYPE=DWORD 

$ REG$CP CREATE VALUE HKEY_LOCAL_MACHINE\SYSTEM\REGISTRY\PRIORITY - 

_$ /NAME=NODENAME3/DATA=5/TYPE=DWORD 

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

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

Example 13-2 Changing Priority Values


$ REG$CP == "$REG$CP" 

$ REG$CP MODIFY VALUE HKEY_LOCAL_MACHINE\SYSTEM\REGISTRY\PRIORITY - 

_$ /NAME=NODENAME3/DATA=20/TYPE=DWORD 

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

13.6 Connecting to the OpenVMS Registry from a Windows System

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

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

Caution

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

13.7 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.8 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.6.1. For a description of how to grant the necessary system privileges and right identifiers, see Section 12.6.1.1.

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

13.9 Backing Up and Restoring the OpenVMS Registry Database

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

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

13.10 Internationalization and Unicode Support

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


Previous Next Contents Index