Document revision date: 19 July 1999

Applications that depend on internal interfaces are bound to a particular version of the operating system when the application is linked. Version-dependent images reference both of the following version numbers:

• The major version number of the operating system
• A set of component version numbers (version numbers of loadable executive images)
  Images can be linked against SYS.STB in one of two ways:
  • Images linked against SYS.STB with the Linker utility qualifier /SELECTIVE_SEARCH include component version numbers only for those symbols that were referenced at link time. (This is the recommended method.)
  • Images linked against SYS.STB without the /SELECTIVE_SEARCH qualifier include references to all component versions.

When you attempt to run an image, the system checks to determine if the image requires a certain version of the operating system or of system components. If the version of the running system does not match the version requirements of the image, the image fails.

The system also checks version numbers when you attempt to install an image using the Install utility (INSTALL) or connect a device driver using the System Generation utility (SYSGEN).

When you upgrade your system to a new version of the operating system, an image might fail because the new version no longer matches the image's version requirements. However, an image might continue to be compatible with the new operating system version, even if it fails the version check.

To continue running a compatible image, you can register the image using the Image Registry facility. You do not need to register images that are linked as part of the installation because they match the current operating system version. However, linking an image during installation does not ensure that system version dependencies do not exist. For information about changes in the current operating system version that might require you to recompile an image or change source code, see the release notes.

To register an image in the image registry, run the command procedure SYS$UPDATE:REGISTER_PRIVILEGED_IMAGE.COM. Enter a command in the following format:

$ @SYS$UPDATE:REGISTER_PRIVILEGED_IMAGE keyword filename

where:

keyword	Specifies one or more of the keywords described in Table 5-3, separated by commas.
filename	Specifies the name and location of the image you want to register. The filename parameter accepts wildcard characters.

Table 5-3 REGISTER_PRIVILEGED_IMAGE.COM Keywords

Keyword	Action
ANALYZE	Displays version-dependent image names and their subsystem dependencies.
REGISTER	Registers images on the local system.
DEREGISTER	Deletes images from the registry on the local system.
SHOW	Lists the registry content. To display the complete registry content, specify a wildcard (*) for the file name.
CONFIRM	Confirms that each specified image be added to or deleted from the registry (used only with REGISTER and DEREGISTER).
TRACE	Lists each image file for verification purposes (used only with REGISTER and DEREGISTER).
HELP	Describes the supported keywords and provides examples.

If the image does not have a version dependency, the following message is displayed:

REGISTER-I-SUMMARY n images examined, n have dependencies

In this message, n is the number of images examined and the number of images that have dependencies.

Example

The following example adds the V6USRAPP image to the registry:

$ @SYS$UPDATE:REGISTER_PRIVILEGED_IMAGE REGISTER SYS$LIBRARY:V6USRAPP %REGISTER-I-ADDED added V6USRAPP to registry

5.6 Customizing the Help Message Database

The Help Message utility (MSGHLP) allows users to quickly access online descriptions of system messages from the DCL prompt. Users with write access to Compaq-supplied .MSGHLP$DATA files can customize the Help Message database in more radical ways than general users can. The following sections describe how to perform the following customization tasks:

Task	For More Information
Accessing $STATUS values for uninstalled messages	Section 5.6.1
Creating system-level Help Message database search paths	Section 5.6.2
Deleting Compaq-supplied messages	Section 5.6.3
Adding comments to Compaq-supplied messages	Section 5.6.4
Changing text in Compaq-supplied messages	Section 5.6.5
Adding messages to Compaq-supplied database files	Section 5.6.6

Before performing these tasks, you should be familiar with the Help Message utility. For a complete description of Help Message features, basic tasks, and the HELP/MESSAGE command and qualifiers, refer to the OpenVMS System Messages: Companion Guide for Help Message Users. Also refer to that manual for a description of the files that you must manipulate to customize the Help Message database.

Any messages that are not installed as part of the OpenVMS operating system cannot be equated with a value stored in $STATUS until they are recognized by the system. When the Help Message utility attempts to translate the value stored in $STATUS or a value specified with the /STATUS qualifier, the search can fail if the value does not equate to an installed message or a message that was linked into the Help Message utility when it was created by Compaq. You can make your system recognize such uninstalled messages. These messages include user-supplied messages, third-party messages, and messages from layered products and certain other OpenVMS facilities.

How to Perform This Task

1. Use the Help Message qualifier /SECTION_FILE=* to include all the OpenVMS supplied message section files that have not already been linked into the main Help Message program, MSGHLP$MAIN.EXE:

   $ HELP/MESSAGE/SECTION_FILE=*

   
   This command generates a user-modifiable object library, SYS$LIBRARY:MSGHLP$MESSAGE_SECTIONS.OLB. Each module in this library contains a pointer to a message section .EXE file. You can use the /SECTION_FILE qualifier to insert additional modules into this library. (See the following steps.)

   Note This HELP/MESSAGE command produces results similar to, but entirely separate from those effected by the SET MESSAGE filespec command. The Help Message utility does not interact with the Message utility. If you want both utilities to translate the same set of message sections, you must separately code each utility to do so. It is perfectly acceptable to have each utility point to different message section files.

   
   When you use the /SECTION_FILE qualifier to create the object library or add modules to it, the MSGHLP$MESSAGE_SECTIONS.EXE file is also automatically created from all the modules in the object library and is placed in your default directory. When you finish modifying the object library, you must copy the final .EXE file to SYS$COMMON:[SYSLIB] (logical name SYS$LIBRARY).
   Thereafter, if Help Message cannot translate a status code and the SYS$LIBRARY:MSGHLP$MESSAGE_SECTION.EXE image exists, Help Message activates it and searches all message section files to which it points. The impact on Help Message search time depends upon the number of files searched.
2. Use the following command as many times as you want to add pointer modules for any other specific message section files to SYS$LIBRARY:MSGHLP$MESSAGE_SECTIONS.OLB and MSGHLP$MESSAGE_SECTIONS.EXE:

   HELP/MESSAGE/SECTION_FILE=disk:[directory]file-name.EXE

   
   The default file specification is SYS$MESSAGE:.EXE.

3. Review the contents of the resulting SYS$LIBRARY:MSGHLP$MESSAGE_SECTIONS.OLB file:

   $ LIBRARY/LIST MSGHLP$MESSAGE_SECTIONS.OLB

   
   The names of the modules in the .OLB file are derived from strings specified in the /SECTION_FILE qualifier.
   Help Message can search a maximum of 42 message section files. Files are searched in this order:

   • The last file activated by a SET MESSAGE command (if any).
   • The message section files that Help Message is linked with before it is shipped:
     • SYSMSG.EXE
     • SYSMGTMSG.EXE
     • CLIUTLMSG.EXE
     • PRGMSG.EXE
   • Any message section files explicitly linked with MSGHLP$MAIN.EXE or with any shareable image that MSGHLP$MAIN.EXE references.
   • Any nonduplicate message section files linked with SYS$LIBRARY:MSGHLP$MESSAGE_SECTIONS.EXE.
     Message section files are searched in the order in which they are listed in the .OLB file. (Order is alphabetical.) If the total count of message section files exceeds 42, message section files listed near the end of the .OLB file might not be searched.
4. If you want, remove any references to message section files in the .OLB file to control which 42 message section files are included in the Help Message search. You might delete a file that you rarely use earlier in the alphabet to ensure that a file later in the alphabet is among the 42 files searched. For example, to delete the NCP (Network Control Program) messages from the .OLB file, use this command:

   $ LIBRARY/DELETE=NETWRKMSG SYS$LIBRARY:MSGHLP$MESSAGE_SECTIONS.OLB

   
   If you delete a module from the .OLB file, you must execute the HELP/MESSAGE command with the /SECTION_FILE qualifier to generate an updated .EXE file. The qualifier argument can specify either a new file or a file that is already listed in the .OLB file.

5. When your .OLB file reflects the message section files you want Help Message to search, copy the final .EXE file from your account to SYS$LIBRARY:.

Example

The following example demonstrates this sequence of events:

1. Link all OpenVMS supplied message section files.
2. Review the resulting .OLB file.
3. Delete the VVIEFMSG module from the .OLB file.
4. Add the file USERS:[TOOLS]NEW_MSGS.EXE to the list in the .OLB file.
5. Review the revised contents of the .OLB file.
6. Copy the final .EXE file from the local account to SYS$LIBRARY:.

Note that the output from the LIBRARY/LIST commands is omitted from the example.

$ HELP/MESSAGE/SECTION_FILE=* $ LIBRARY/LIST SYS$LIBRARY:MSGHLP$MESSAGE_SECTIONS.OLB $ LIBRARY/DELETE=VVIEFMSG SYS$LIBRARY:MSGHLP$MESSAGE_SECTIONS.OLB $ HELP/MESSAGE/SECTION_FILE=USERS:[TOOLS]NEW_MSGS.EXE $ LIBRARY/LIST SYS$LIBRARY:MSGHLP$MESSAGE_SECTIONS.OLB $ COPY MSGHLP$MESSAGE_SECTIONS.EXE SYS$LIBRARY:MSGHLP$MESSAGE_SECTIONS.EXE

5.6.2 Creating System-Level Database Search Paths

Help Message database files need not reside on the system disk. You can create system logical names to define one or more Help Message search paths to access multiple .MSGHLP$DATA files in different locations.

When Help Message is installed, the OpenVMS messages database file is installed by default at SYS$COMMON:[SYSHLP]MSGHLP$LIBRARY.MSGHLP$DATA. However, this file can optionally be installed on or moved to another disk. The alternate location must be pointed to by logical name MSGHLP$LIBRARY. Use this command to define the logical name:

DEFINE/SYSTEM MSGHLP$LIBRARY disk:[directory]MSGHLP$LIBRARY

By default, Help Message attempts to look up messages in the default location unless the logical name MSGHLP$LIBRARY is defined. If you do not use the default database location, include the logical name definition command in SYS$MANAGER:SYLOGICALS.COM so that the database is defined each time the system is booted.

You and other system users can create additional .MSGHLP$DATA files, as described in the OpenVMS System Messages: Companion Guide for Help Message Users. None of the .MSGHLP$DATA files need reside on the system disk. You can add new files to a systemwide default database search path defined by MSGHLP$LIBRARY, or you can create specialized search paths to include different configurations of .MSGHLP$DATA files.

A search path definition can include individual file names or can point to one or more directories. If you specify a directory with no file name, Help Message searches all .MSGHLP$DATA files currently found in that directory. Pointing to a directory instead of individual files can minimize your bookkeeping when .MSGHLP$DATA files are added or removed.

To use system resources more efficiently, you can create different search paths for different user groups, depending on which .MSGHLP$DATA files they need to access. You can also set up different directories for different types of messages or for different user groups. For example, you could use three unique logical names to define three different search paths tailored to different user groups:

DEFINE/SYSTEM logical-name-1 file-a,file-b,file-c

DEFINE/SYSTEM logical-name-2 file-a,directory-z

DEFINE/SYSTEM logical-name-3 file-x,file-a,directory-y

Users can select an alternate to the system default database by specifying the /LIBRARY qualifier in the HELP/MESSAGE command. Individual users can also create their own logical name search paths at the process level.

Example

The following example defines a Help Message search path that accesses .MSGHLP$DATA database files in three locations: the Compaq-supplied OpenVMS messages at USERS:[TOOLS], the user-supplied file USERS:[NEW_PROJ]OUR_MESSAGES.MSGHLP$DATA, and all .MSGHLP$DATA files in directory TEST:[TRY_ME].

$ DEFINE/SYSTEM MSGHLP$LIBRARY USERS:[TOOLS]MSGHLP$LIBRARY,- _$ USERS:[NEW_PROJ]OUR_MESSAGES.MSGHLP$DATA,TEST:[TRY_ME]

5.6.3 Deleting Compaq-Supplied Messages from the Database

You can delete Compaq-supplied messages from the database to conserve system resources or improve response time.

How to Perform This Task

1. Use the /EXTRACT qualifier to create a .MSGHLP file containing the messages you want to delete from the database. (Refer to the OpenVMS System Messages: Companion Guide for Help Message Users for a full description of how to select the contents of the .MSGHLP file.) Some examples follow.
   Use the following syntax to extract all the messages for a specified facility:

   HELP/MESSAGE/FACILITY=facility-name/EXTRACT=filename.MSGHLP

   
   Use this syntax to extract one or more messages specified by the search string:

   HELP/MESSAGE/EXTRACT=filename.MSGHLP search-string

2. Check the contents of the resulting .MSGHLP file to be sure that it contains only the data that you want to delete from the database. Edit out any messages that you do not want to delete from the database.
3. Use /DELETE to delete the contents of the .MSGHLP file from the database. Include /LIBRARY if the MSGHLP$LIBRARY.MSGHLP$DATA file is not the default database or if it is not the first file in the search path defined by logical name MSGHLP$LIBRARY.

   HELP/MESSAGE/DELETE=filename.MSGHLP

   HELP/MESSAGE/DELETE=filename.MSGHLP/LIBRARY=disk:[directory]filename.MSGHLP$DATA

   
   Save the .MSGHLP file if you might ever want to add the deleted messages back into the database prior to the next upgrade. You can store the file on tape to conserve disk space. If you delete and then reinsert messages, these messages are treated like user-supplied messages and are displayed with change bars.
   Any Compaq-supplied messages that you delete are currently reinserted into the database at the next upgrade. You can delete the messages again using a saved .MSGHLP file or you can create a new .MSGHLP file. Note that if you keep a .MSGHLP file for future deletion purposes only, you need save only the lines prefixed by 1 and 2.

4. To save disk space, you can compress the .MSGHLP$DATA file to close up any free space created by the deletions. Use the following command sequence to compress the file:

   CONVERT disk:[directory]filename.MSGHLP$DATA disk:[directory]filename.MSGHLP$DATA

   PURGE disk:[directory]filename.MSGHLP$DATA

Example

The following example extracts and then deletes all messages for the DDTM (DECdtm services) facility from the default database. The last two commands compress the Compaq-supplied database file to conserve disk space after the deletions.

$ HELP/MESSAGE/FACILITY=DDTM/EXTRACT=DDTM.MSGHLP $ HELP/MESSAGE/DELETE=DDTM.MSGHLP $ CONVERT SYS$COMMON:[SYSHLP]MSGHLP$LIBRARY.MSGHLP$DATA - _$ SYS$COMMON:[SYSHLP]MSGHLP$LIBRARY.MSGHLP$DATA $ PURGE SYS$COMMON:[SYSHLP]MSGHLP$LIBRARY.MSGHLP$DATA

	privacy and legal statement
6017PRO_015.HTML