Document revision date: 19 July 1999

Help Message (MSGHLP) is a versatile utility that allows you to quickly access online descriptions of system messages from the DCL prompt on a character-cell terminal (including DECterm windows).

Help Message displays descriptions of messages produced by the OpenVMS operating system. In addition, the Help Message database can optionally include other source files, such as user-supplied messages documentation.

The HELP/MESSAGE command and qualifiers are described in the following sections, including an overview of the facility's features and examples of a few simple operations. Detailed information about customizing the Help Message database follows the qualifier descriptions. System managers can refer to the OpenVMS System Manager's Manual for more information about customizing the Help Message database.

2.1 Features of Help Message

Basic Help Message features are as follows:

• By default, Help Message provides information on the status of the last executed DCL command. To obtain message information after a DCL command results in an error, enter the following:

  $ HELP/MESSAGE

  
  You can abbreviate the command according to standard conventions or define a key to evoke the basic HELP/MESSAGE command.

• Help Message preserves the value of $STATUS, so you can incorporate the HELP/MESSAGE command into a command procedure to obtain additional information about errors. For example, you could include a command similar to the following:

  $ IF .NOT. $STATUS THEN HELP/MESSAGE

• The default HELP/MESSAGE command operates on the value currently stored in $STATUS. You can also access a message description by explicitly specifying a status value in either decimal or hexadecimal. For example:

  $ HELP/MESSAGE/STATUS=12 $ HELP/MESSAGE/STATUS=%XC

• You can also access message descriptions by specifying the message identifier or other words from the message text in any order. For example, the following commands both access ACCVIO messages:

  $ HELP/MESSAGE ACCVIO $ HELP/MESSAGE VIRTUAL ACCESS

• By default, HELP/MESSAGE matches all words beginning with the specified search string. You can refine a search to match exact words only.
  In the following example, the first command outputs all messages containing words beginning with the ACC string, while the second command selects only those messages that contain ACC as a whole word. You can use Ctrl/Z to quit out of any undesired long list of messages---or to terminate any other Help Message operation.

  $ HELP/MESSAGE/BRIEF ACC $ HELP/MESSAGE/BRIEF/WORD_MATCH=WHOLE_WORD ACC

• To refine your search even further, you can specify that only messages produced by a certain facility be displayed. For example, the following command displays only the ACCVIO message produced by the SYSTEM facility:

  $ HELP/MESSAGE/FACILITY=SYSTEM ACCVIO

• You can also select all messages produced by one or more specified facilities. To list the names of all facilities in the database, enter the following:

  $ HELP/MESSAGE/FACILITY=?

  
  You can specify any facility name from the resulting list as a value for the /FACILITY qualifier. Specify /BRIEF to output a list of the messages only, without descriptions. Adding /SORT alphabetizes the output. For example, the following command alphabetically lists all the messages for the DTS facility:

  $ HELP/MESSAGE/BRIEF/SORT/FACILITY=DTS

  
  For more information about specifying facility names using the /FACILITY qualifier, see Section 2.3.

• By selecting the messages you want and directing them to a file, you can create and print your own customized message documentation.
  For example, the following command selects all messages issued by the Backup utility and those messages documented as "Shared by several facilities," alphabetizes them, and outputs them to a printable file called MESSAGES.TXT:

  $ HELP/MESSAGE/FACILITY=(BACKUP,SHARED)/SORT/OUTPUT=MESSAGES.TXT

• You can define a logical name in your login file to override a system-defined search path for the Help Message database and create a customized database that includes your own message descriptions (see Section 2.5.2).
• You can add your own messages documentation to the Help Message database (see Section 2.6.1).
• You can delete messages from the database (see Section 2.6.2).
• Users with write access to Digital-supplied MSGHLP$DATA files (usually the system manager) can further customize the Help Message database (for example, add a comment to a Digital-supplied message description).
• You can exit out of any Help Message display by pressing Ctrl/Z.

Following the HELP/MESSAGE command and qualifier descriptions, detailed information is provided for the following tasks:

• Customizing the Help Message database (see Section 2.5)
  Describes the files you can manipulate and explains how to use search paths to set up one or more Help Message databases.
• Modifying the Help Message database (see Section 2.6)
  Describes how to add, delete, or change information in the database.

If you experience performance problems with Help Message or have requirements that you cannot satisfy using the procedures described in this chapter, consult your system manager.

2.2 HELP/MESSAGE Command and Qualifiers

The HELP/MESSAGE command and qualifiers are described in the following section.

Displays descriptions of system messages.

Format

HELP/MESSAGE [/qualifier [...]] [search-string]

Parameter

search-string

Specifies a message identifier or one or more words from a message's text. By default, HELP/MESSAGE displays a description of the message produced by the last executed command (that is, the message corresponding to the value currently stored in the CLI symbol $STATUS). (Some exceptions are discussed in Section 2.4.)

The Help Message utility (MSGHLP) operates on the search string using the following conventions:

• Words containing fewer than three alphanumeric characters are ignored.
• Words can be specified in any order.
  You can minimize search time by specifying the most unusual word first.
• Nonalphanumeric characters are ignored in the search. Exceptions are the percent sign (%) and hyphen (-) when they prefix a message. Therefore, you can paste a full message into the search string, provided you include these special characters and delete any variables (such as file names) that were inserted into the message.
  If Help Message fails to find a pasted message in the database, submit the command again and omit the leading special character, facility, and severity. Some common messages are documented as "shared" messages rather than facility-specific messages.
• Help Message matches all words that begin with the characters specified in the search string. Use /WORD_MATCH=WHOLE_WORD to specify that only whole words be matched.

Qualifiers

/BRIEF

Outputs the message text only.

/DELETE=filename.MSGHLP

Deletes all messages contained in the specified .MSGHLP file from whichever of the following files is found first:

• A .MSGHLP$DATA file specified with the /LIBRARY qualifier
• The first .MSGHLP$DATA file in a search path specified by the /LIBRARY qualifier
• The first .MSGHLP$DATA file in the default search path (defined by logical name MSGHLP$LIBRARY)
• SYS$HELP:MSGHLP$LIBRARY.MSGHLP$DATA (the default .MSGHLP$DATA file)

You must have write access to Digital-supplied .MSGHLP$DATA files to delete messages from the Digital-supplied database.

Note If you create a .MSGHLP file by specifying a search string, check the output .MSGHLP file to be sure the search did not pick up any unexpected messages that you do not want to delete from the database. Edit any such messages out of the .MSGHLP file before you perform the delete operation.

/EXTRACT=filename.MSGHLP

Extracts messages from the database and generates a .MSGHLP file that can be edited, if desired, and used as input for /INSERT and /DELETE operations. /EXTRACT retrieves data from a .MSGHLP$DATA file or logical search path specified by /LIBRARY or, by default, from files in the search path defined by logical name MSGHLP$LIBRARY. When /EXTRACT is not specified, Help Message produces output in standard text format by default (see /OUTPUT).

/FACILITY=?

/FACILITY=(facility-name [,...])

/FACILITY=ALL

Specifies which facilities in the database are to be searched for a match.

Enter /FACILITY=? to output a list of all facilities in the default database or in a database specified by /LIBRARY.

To narrow your search, specify one or more facility names with /FACILITY. (Multiple facilities must be enclosed in parentheses and be separated by commas.) Help Message then outputs only matching messages produced by the specified facility or facilities.

Specify /FACILITY=ALL to output messages for all facilities in the database. /FACILITY=ALL is the default unless another facility is implied; for example, specifying /STATUS or defaulting to the value of the CLI symbol $STATUS automatically identifies a specific facility. Similarly, cutting and pasting a message that includes a facility name invalidates use of the /FACILITY qualifier.

/FULL (default)

Outputs the complete message description, including message text, facility name, explanation, user action, and user-supplied comment, if any.

/INSERT=filename.MSGHLP
/INSERT=TT:

Updates the first of the following files to be found with new or changed information from the specified .MSGHLP file, or, if TT: is specified, with the data entered immediately at the terminal:

• A .MSGHLP$DATA file specified with the /LIBRARY qualifier
• The first .MSGHLP$DATA file in a search path specified by the /LIBRARY qualifier

• The first .MSGHLP$DATA file in the default search path (defined by logical name MSGHLP$LIBRARY)
• SYS$HELP:MSGHLP$LIBRARY.MSGHLP$DATA (the default .MSGHLP$DATA file)

You must have write access for the Digital-supplied .MSGHLP$DATA files to insert data into these files. User-supplied data is identified by change bars in Help Message output.

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

/LIBRARY=disk:[directory]

/LIBRARY=logical-name

Defines the messages database for the current command to be a particular .MSGHLP$DATA file, all the .MSGHLP$DATA files in a specified directory, or all the files in a search path defined by a logical name.

For most operations, the default database is either SYS$HELP:MSGHLP$LIBRARY.MSGHLP$DATA or a search path of .MSGHLP$DATA files defined by logical name MSGHLP$LIBRARY.

For /DELETE and /INSERT operations, the default database is either SYS$HELP:MSGHLP$LIBRARY.MSGHLP$DATA or the first file in a search path defined by logical name MSGHLP$LIBRARY.

/OUTPUT=filespec

Writes output to the specified file. By default, Help Message writes output to SYS$OUTPUT, which is normally the terminal.

/PAGE (default for screen display)
/NOPAGE

Displays terminal output one screen at a time. The page length is automatically set to 1 line less than the value specified by SET TERMINAL/PAGE. (Use of /PAGE is incompatible with /OUTPUT=filespec.)

/SECTION_FILE=*
/SECTION_FILE=file-spec

Identifies the specified message section file to the system so that Help Message can interpret the $STATUS values for the messages in that file. The default file specification is SYS$MESSAGE:.EXE. Specifying /SECTION_FILE=* automatically includes all OpenVMS-supplied message section files. For more information, see Section 2.4.

Note The results of using this qualifier are entirely independent from those created by the SET MESSAGE command. The Help Message utility and Message utility do not interact. You must separately code each utility to obtain the results you want.

/SORT
/NOSORT (default)

Sorts output in alphabetical order. If a sort fails, retry the operation using the /WORK_FILES qualifier.

/STATUS=status-code

/STATUS='symbol'

/STATUS='$STATUS' (default)

Outputs the message corresponding to the specified status code. You can specify the status code with a decimal or hexadecimal number or a symbol enclosed in apostrophes. You can omit leading zeros, but you must prefix any hexadecimal number with "%X".

If a HELP/MESSAGE command does not include a search string, Help Message by default outputs the message corresponding to the CLI symbol $STATUS; that is, Help Message displays information on how the last executed command completed.

You cannot specify a search string or /FACILITY with /STATUS. /FACILITY is also illegal if you omit the search string and default to /STATUS='$STATUS'.

/WORD_MATCH=INITIAL_SUBSTRING (default)
/WORD_MATCH=WHOLE_WORD

/WORD_MATCH=INITIAL_SUBSTRING matches all words that begin with a word specified in the search string. The search string can contain multiple words to be matched. Only messages that match every word in the search string (in any order) are output.

/WORD_MATCH=WHOLE_WORD matches whole words only and refines your search to the exact words specified. For example, an exact search on ACC screens out dozens of other messages containing words that begin with the letters ACC.

/WORK_FILES=nn

/WORK_FILES=0 (default if qualifier is omitted)

/WORK_FILES=2 (default if qualifier is entered with no value)

Specifies that work files are to be used if the /SORT qualifier is specified. You can specify a value from 0 to 10 for nn. This qualifier is necessary only for large sort operations. The qualifier has no effect if /SORT is not specified.

2.3 Tips for Using the /FACILITY Qualifier

In addition to the facility names listed in response to /FACILITY=?, Digital has included a few internal nicknames to simplify access to certain facilities. "DCL" is such a nickname. For example, when accessing MSGHLP$LIBRARY.MSGHLP$DATA, the nickname "DCL" maps to the official facility name, "CLI, Command Language Interpreter (DCL)". DCL does not appear in the list of facility names, but if you enter /FACILITY=DCL in a command, Help Message outputs CLI messages.

Help Message searches for facility names from the beginning of the facility name's string only---not on each word of the string as with the message text. Therefore, you must enter enough characters to narrow your search to the desired field.

For example, a search on /FACILITY=RMS selects messages for two facilities:

• RMS, OpenVMS Record Management Services
• RMSREC, RMS Recovery Utility

To find the RMS messages only, you must enter enough literal characters to make the search string unique; for example, /FACILITY="RMS,". The double quotes are required in order to include the comma (and any following words) in the search string. Since the double quotes direct Help Message to search for a literal string, you must specify the precise capitalization used for the facility name in the database.

2.4 Accessing $STATUS Values for Uninstalled Messages

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. Such messages include user-supplied messages, third-party messages, and messages from layered products and certain other OpenVMS facilities. Your system manager may already have linked all the messages you need at the system level. If not, you can make these links in your own account. (System managers who want information about linking message section files at the system level should refer to the OpenVMS System Manager's Manual.)

Before linking such messages, determine whether you must frequently access them using the value in $STATUS or a value specified using the /STATUS qualifier. If not, the simplest alternative is to use the HELP/MESSAGE command and specify the message identifier or message text in the search string.

If you prefer the convenience of having Help Message interpret a $STATUS value, there are two ways that you can make the system recognize uninstalled messages:

• The simplest method is to use the SET MESSAGE command to link an unknown messages .EXE file. For example:

  $ SET MESSAGE TOOLS:[MYPROJ]MYNEWMSG.EXE

  
  This command includes the messages pointed to by file MYNEWMSG.EXE as part of the system until you enter another SET MESSAGE command specifying a different file.

• For a more permanent solution, execute the following command for every message section file that you would like to include in the list of files that Help Message automatically searches for $STATUS values:

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

  
  By default, /SECTION_FILE tries to generate or update object library SYS$LIBRARY:MSGHLP$MESSAGE_SECTIONS.OLB. Unless you have write access to system files, you must first define the logical name MSGHLP$MESSAGE_SECTIONS to point to your own account.
  For example, to make the messages pointed to by file TOOLS:[MYPROJ]MYNEWMSG.EXE known in your own account, use this command sequence:

  $ DEFINE MSGHLP$MESSAGE_SECTIONS SYS$LOGIN:MSGHLP$MESSAGE_SECTIONS $ HELP/MESSAGE/SECTION_FILE=TOOLS:[MYPROJ]MYNEWMSG.EXE

  
  Unlike the SET MESSAGE command, the /SECTION_FILE qualifier permanently links the specified message section file unless you later delete it.
  The default device and directory for the file specification is SYS$MESSAGE, where all OpenVMS-supplied message section files are stored, and the default file type is .EXE. Therefore, the following command automatically includes all OpenVMS-supplied message section files:

  $ HELP/MESSAGE/SECTION_FILE=*

  
  Your system manager may already have included the OpenVMS message section files at the system level. You will need to add these only if you define the logical name MSGHLP$MESSAGE_SECTIONS to point to somewhere other than SYS$LIBRARY:MSGHLP$MESSAGE_SECTIONS.

Help Message can search a maximum of 42 message section files. Files are searched in this order:

1. The last file activated by a SET MESSAGE command (if any).
2. The message section files that Help Message is linked with before it is shipped:
   • SYSMSG.EXE
   • SYSMGTMSG.EXE
   • CLIUTLMSG.EXE
   • PRGMSG.EXE
3. Any message section files explicitly linked against MSGHLP$MAIN.EXE or any of the shareable images that it references.
4. Any non-duplicate message section files linked with a MSGHLP$MESSAGE_SECTIONS.EXE file, if such a file exists.
   The MSGHLP$MESSAGE_SECTIONS.EXE file is automatically generated from the MSGHLP$MESSAGE_SECTIONS.OLB file each time the HELP/MESSAGE command is executed with the /SECTION_FILE qualifier. Each execution of the /SECTION_FILE qualifier adds a module to the .OLB file; each module represents a message section file.
   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.
   To display the contents of your .OLB file, use this command:

   $ LIBRARY/LIST MSGHLP$MESSAGE_SECTIONS.OLB

   
   The names of the modules in this .OLB file are derived from strings specified in the /SECTION_FILE qualifier.
   You can remove references to message section files in the .OLB file in order to control which 42 message section files Help Message will search. For example, to delete the NCP (Network Control Program) messages from your private .OLB file, use this command:

   $ LIBRARY/DELETE=NETWRKMSG 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 in order 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.

You can create one or more customized Help Message databases by changing information in the database files (see Section 2.6) and by selecting which files to include in a database. No matter how you customize your database, you will typically manipulate two kinds of files:

• .MSGHLP$DATA files
  One or more .MSGHLP$DATA files form the Help Message database that is accessed by the HELP/MESSAGE command (see Section 2.2). If you have write access to the .MSGHLP$DATA files, you can customize the database by inserting or deleting data contained in .MSGHLP files. (.MSGHLP files are described later in this section.)
  The system manager can define a system logical name to set up a system-wide Help Message database that includes all or selected .MSGHLP$DATA files in a search path. You can also set a logical name in your login file to include or exclude specific .MSGHLP$DATA files in your personalized Help Message database (see Section 2.5.2).
• .MSGHLP files
  A .MSGHLP file is used as input to change the content of a .MSGHLP$DATA file. The contents of a .MSGHLP file are applied to a .MSGHLP$DATA file either as data to be inserted or as data to be deleted from the .MSGHLP$DATA file. Various options are described in subsections to Section 2.6.

By setting up different search paths for multiple .MSGHLP$DATA files at the system or process level, you can create a variety of Help Message databases. The Help Message qualifier /LIBRARY allows you to access or change a specific .MSGHLP$DATA file or search path. For more information, see Section 2.5.2.

2.5.1 Creating a .MSGHLP File

• Use the /EXTRACT qualifier with the HELP/MESSAGE command.
  Use this method when you want to modify or delete information in the database.
  Users with write access to Digital-supplied .MSGHLP$DATA files can use a .MSGHLP file created in this fashion to add a comment to a Digital-supplied message or to delete Digital-supplied information from the database. See the OpenVMS System Manager's Manual for details.
• Write the file from scratch.
  Use this technique when you have new messages to add to the database. (See the .MSGHLP file format in the example that follows.)

The following example uses the /EXTRACT qualifier to extract hypothetical message NOSNO from the default database and create a file named NOSNO.MSGHLP to contain the message description:

$ HELP/MESSAGE/EXTRACT=NOSNO.MSGHLP NOSNO

The .MSGHLP file format uses a unique numerical prefix to designate the message, facility, explanation, and user action sections of the message description:

1NOSNO, can't ski; no snow 2XCSKI, XCSKI Program 3Your attempt to ski failed because there is no snow. 4Wait until there is snow and attempt the operation again.

When creating a .MSGHLP file, limit your text to 60 characters per line so that the Help Message output does not exceed the terminal display area. Also avoid using a long facility name that wraps to a second line.

Other sections in this chapter explain how you can use the contents of a .MSGHLP file, edited or unedited, to add data to or delete data from a .MSGHLP$DATA file.

2.5.2 Defining a Search Path in Your Login File

The Help Message database comprises one or more .MSGHLP$DATA files that can be accessed individually by the .MSGHLP$DATA file name or collectively by a search path that includes one or more .MSGHLP$DATA files. The search path can specify individual .MSGHLP$DATA files or it can specify one or more directory names. Help Message will search all .MSGHLP$DATA files in a named directory.

Your system manager sets up a default Help Message database on the system or accepts the installation default. When you instruct Help Message to display messages or to output messages to a file, Help Message defaults to the main OpenVMS messages file (SYS$HELP:MSGHLP$LIBRARY.MSGHLP$DATA) unless a search path is defined by logical name MSGHLP$LIBRARY at the system or user level.

You can create your own .MSGHLP$DATA files to add to the database (see Section 2.6.1). None of the .MSGHLP$DATA files need be installed on the system disk. Once you have created the .MSGHLP$DATA files, you can create a logical name in your login file (SYS$LOGIN:LOGIN.COM) to define a search path that names the .MSGHLP$DATA files you want to include in your customized database.

For example, the following command in your login file defines your Help Message default search path to include the main OpenVMS messages file and another file called MYMESSAGES.MSGHLP$DATA:

$ DEFINE MSGHLP$LIBRARY SYS$COMMON:[SYSHLP]MSGHLP$LIBRARY.MSGHLP$DATA,- _$ TOOLS:[MYPROJ]MYMESSAGES.MSGHLP$DATA

You can set up multiple logical names to create customized search paths that restrict the Help Message database to minimize search time or that add personal .MSGHLP$DATA files to the database. For example, the following logical name omits the main OpenVMS messages file and names two other .MSGHLP$DATA files instead:

$ DEFINE MSGHLP_ABCDEF TOOLS:[MYPROJ]ABC.MSGHLP$DATA,TOOLS:[MYPROJ]DEF.MSGHLP$DATA

If you want Help Message to search all .MSGHLP$DATA files in a directory, you can define a logical name that points to the directory, but does not name specific files. You can then add or delete files without changing the logical definition. For example, the following command defines logical name MSGHLP_MYPROJ to include all .MSGHLP$DATA files in directory TOOLS:[MYPROJ]:

$ DEFINE MSGHLP_MYPROJ TOOLS:[MYPROJ]

You can use the /LIBRARY qualifier with the HELP/MESSAGE command to specify a logical name or a .MSGHLP$DATA file. For example, the following command specifies that Help Message search only the file DEF.MSGHLP$DATA for hypothetical message TROUBLE:

$ HELP/MESSAGE/LIBRARY=TOOLS:[MYPROJ]DEF.MSGHLP$DATA TROUBLE

The following command specifies that Help Message search all the files defined by logical name MSGHLP_ABCDEF (defined in an earlier coding example), which includes both ABC.MSGHLP$DATA and DEF.MSGHLP$DATA:

$ HELP/MESSAGE/LIBRARY=MSGHLP_ABCDEF TROUBLE

If you have defined no search paths in your account, the following command directs Help Message to search the default database defined at the system level:

$ HELP/MESSAGE TROUBLE

Typically Help Message searches all .MSGHLP$DATA files in a search path. However, on /INSERT and /DELETE operations, Help Message operates on only one .MSGHLP$DATA file: either a file specified with the /LIBRARY qualifier, a default .MSGHLP$DATA file, or the first .MSGHLP$DATA file in a default or specified search path.

Unless you have write access to the Digital-supplied .MSGHLP$DATA files, it makes sense to put the .MSGHLP$DATA file that you are most likely to update first in a search string. For example, if you have the first of the following two commands in your login file, the second command would by default update file MYMESSAGES.MSGHLP$DATA:

$ DEFINE MSGHLP$LIBRARY TOOLS:[MYPROJ]MYMESSAGES.MSGHLP$DATA,- _$ SYS$COMMON:[SYSHLP]MSGHLP$LIBRARY.MSGHLP$DATA $ HELP/MESSAGE/INSERT=NEW_MESSAGES.MSGHLP

An alternative is to use the /LIBRARY qualifier to override the default .MSGHLP$DATA file and specify the file that you want to update. For example:

$ DEFINE MSGHLP$LIBRARY SYS$COMMON:[SYSHLP]MSGHLP$LIBRARY.MSGHLP$DATA,- _$ TOOLS:[MYPROJ]MYMESSAGES.MSGHLP$DATA $ HELP/MESSAGE/INSERT=NEW_MESSAGES.MSGHLP- _$ /LIBRARY=TOOLS:[MYPROJ]MYMESSAGES.MSGHLP$DATA

2.6 Modifying the Help Message Database

You can modify the database by adding or deleting information. When you add information to the database, user-supplied documentation displays with a change bar in the left margin to distinguish it from Digital-supplied data.

Only users with write access to Digital-supplied .MSGHLP$DATA files can delete Digital-supplied data or update these files (see the OpenVMS System Manager's Manual for details). However, any user can create a private .MSGHLP$DATA file and include it in the Help Message database (see Section 2.5.2).

The following sections explain how to make these modifications:

• Add messages to the database (see Section 2.6.1).
• Delete user-supplied messages from the database (see Section 2.6.2).
• Change user-supplied information in the database (see Section 2.6.3).
• Change Digital-supplied messages documentation (see Section 2.6.4).

You can add new messages to the database by creating a .MSGHLP$DATA file and adding it to a Help Message database search path. The .MSGHLP$DATA file that you create remains intact throughout system upgrades.

Follow these steps to add new messages to the Help Message database:

1. Create a .MSGHLP file with all your message descriptions in it. (The formatted data in the .MSGHLP file is used as input to create the .MSGHLP$DATA file.) (See Section 2.5.1 for an example of the .MSGHLP file format.)
2. Use the .MSGHLP file to create a .MSGHLP$DATA file. Use the /LIBRARY qualifier to specify the name of the .MSGHLP$DATA file that you want to create:

   $ HELP/MESSAGE/INSERT=MYMESSAGES.MSGHLP- _$ /LIBRARY=TOOLS:[MYPROJ]MYMESSAGES.MSGHLP$DATA

3. Add the new .MSGHLP$DATA file to a Help Message database search path, as described in Section 2.5.2.

You can delete any message, provided you have write access to the .MSGHLP$DATA file that contains the message. User-supplied data displays with change bars in the left margin to distinguish it from Digital-supplied data. Digital-supplied messages can be deleted only by users with write access to Digital-supplied .MSGHLP$DATA files, usually the system manager. (See the OpenVMS System Manager's Manual for details.)

Use a .MSGHLP file to delete messages, as follows:

1. Extract the message that you want to delete into a .MSGHLP file. The following example extracts hypothetical message PROBLEM from the default database:

   $ HELP/MESSAGE/EXTRACT=PROBLEM.MSGHLP PROBLEM

2. Check the contents of PROBLEM.MSGHLP to see if the Help Message search picked up any other messages that you were not expecting. If necessary, edit the file to include only the messages that you want to delete from the database.
3. Use the /DELETE qualifier to delete the messages in PROBLEM.MSGHLP from the .MSGHLP$DATA file:

   $ HELP/MESSAGE/DELETE=PROBLEM.MSGHLP

   
   Remember that a delete operation acts on only the first .MSGHLP$DATA file in a search path. If necessary, you can use the /LIBRARY qualifier to specify a particular .MSGHLP$DATA file. See Section 2.5.2 for more information about default databases and search paths.
   If you keep the PROBLEM.MSGHLP file, you can later use this file with the /INSERT qualifier to put the deleted messages back into the database, possibly in a different .MSGHLP$DATA file.

4. When you delete messages from the database, free space is created in the library. The following command sequence compresses file MYMESSAGES.MSGHLP$DATA to use as little disk space as possible:

   $ CONVERT TOOLS:[MYPROJ]MYMESSAGES.MSGHLP$DATA - _$ TOOLS:[MYPROJ]MYMESSAGES.MSGHLP$DATA $ PURGE TOOLS:[MYPROJ]MYMESSAGES.MSGHLP$DATA

You can change any user-supplied data, provided you have write access to the .MSGHLP$DATA file. User-supplied data displays with change bars in the left margin to distinguish it from Digital-supplied data.

Digital-supplied documentation can be modified only by users with write access to Digital-supplied .MSGHLP$DATA files, usually the system manager. (See the OpenVMS System Manager's Manual for details.) Other users can make a copy of a Digital-supplied message and edit that to fit their needs (see Section 2.6.4).

The procedure for updating an existing message is slightly different depending on which field you want to change. Both procedures are described in the following sections.

Changing the Explanation or User Action Fields

Follow these steps to change the explanation or user action fields:

1. Extract the message that you want to edit into a .MSGHLP file. The following example extracts hypothetical message FIXIT from MYMESSAGES.MSGHLP$DATA:

   $ HELP/MESSAGE/EXTRACT=FIXIT.MSGHLP- _$ /LIBRARY=TOOLS:[MYPROJ]MYMESSAGES.MSGHLP$DATA FIXIT

2. Edit the explanation or user action fields in FIXIT.MSGHLP.
3. Update MYMESSAGES.MSGHLP$DATA using the edited FIXIT.MSGHLP file as input. For example:

   $ HELP/MESSAGE/INSERT=FIXIT.MSGHLP- _$ /LIBRARY=TOOLS:[MYPROJ]MYMESSAGES.MSGHLP$DATA

Changing the Message Text or Facility Fields

Help Message updates an existing message entry by comparing the message text and facility name fields for an identical match before changing any data in the explanation or user action fields. Therefore, if you want to change the message text of an existing message, you must delete the current message before you insert the revised message. Otherwise, both the old and the new message will appear in the database.

1. Extract the message that you want to edit into a .MSGHLP file. The following example extracts hypothetical message PROBLEM from the default database:

   $ HELP/MESSAGE/EXTRACT=PROBLEM.MSGHLP PROBLEM

2. Check the contents of PROBLEM.MSGHLP to see if the Help Message search picked up any other messages that you were not expecting. If necessary, edit the file to include only the messages that you want to delete from the database.
3. Use the /DELETE qualifier to delete the messages in PROBLEM.MSGHLP from the .MSGHLP$DATA file:

   $ HELP/MESSAGE/DELETE=PROBLEM.MSGHLP

   
   See Section 2.6.2 for full details about deleting messages from the database.

4. Edit the message text or facility name in the .MSGHLP file.
5. Update the database using the edited .MSGHLP file as input. For example:

   $ HELP/MESSAGE/INSERT=PROBLEM.MSGHLP

   
   This command updates the default .MSGHLP$DATA file. Section 2.5.2 describes how the default database for an insert operation can differ from the default database for an output operation.

If you have write access to Digital-supplied .MSGHLP$DATA files, refer to the OpenVMS System Manager's Manual for information about modifying or deleting Digital-supplied messages documentation.

If you do not have write access to Digital-supplied .MSGHLP$DATA files, there are two ways you can add comments to or modify a Digital-supplied message:

• Ask a user with write access to the files, usually the system manager, to add your comment to the database. This is the best solution if your comment would be helpful to other users on the system.
  Please report to Digital any errors in a message text string so that we can correct the problem in future databases.
• Create a copy of the Digital message in your own .MSGHLP$DATA file and edit the description to suit your needs. Follow these steps:
  1. Extract the Digital-supplied message that you want to edit. The following example extracts the message BAD_NEWS from a default database that includes this hypothetical Digital-supplied message:

     $ HELP/MESSAGE/EXTRACT=BAD_NEWS.MSGHLP BAD_NEWS

  2. Edit any fields in BAD_NEWS.MSGHLP to say whatever you want.
  3. Update your own .MSGHLP$DATA file using the edited BAD_NEWS.MSGHLP file as input. For example:

     $ HELP/MESSAGE/INSERT=BAD_NEWS.MSGHLP/LIBRARY=TOOLS:[MYPROJ]- _$ MYMESSAGES.MSGHLP$DATA

If your .MSGHLP$DATA file is included in a search path of the main database, a Help Message search will output both the Digital-supplied message and your version of the message. Your version is distinguished by change bars in the left margin.

	privacy and legal statement
6023PRO_002.HTML