errinstall Command

Purpose

Installs messages in the error logging message sets.

Syntax

errinstall [ -c ] [ -f ] [ -q ] [ -z FileName ] File

Description

The errinstall command is an installation aid that adds or replaces messages in the Error Description, Probable Cause, User Cause, Install Cause, Failure Cause, Recommended Action, and Detailed Data data id message sets of the error log message catalog.

The File parameter specifies an input file containing messages to be added or replaced. If you do not specify the File parameter or if you specify it as the - (minus sign), the errinstall command reads from standard input.

Note: Program products and in-house applications should use predefined messages from the error logging message sets. List the predefined messages using the errmsg -w command. To add new messages, third-party software vendors should contact IBM® Developer Solutions to register new messages. During the development of in-house applications, the errmsg command can be used to add new messages, but the new messages must not conflict with the messages added for other in-house applications.

Undo Feature

The errinstall command creates an undo file in the current directory named the File.undo file. (If the errinstall command is reading from standard input, the undo file information is written to standard output.) The File.undo file can be used as input to the errinstall command to undo the changes the errinstall command has just made. To undo changes, run the errinstall command with the -f flag and specify the File.undo file for the File parameter.

Input File (or Standard In) File Format

Two separate lines of information are required to add or replace a single message in the error log message catalog. You can include multiple additions or replacements in a single file. The first line is required to identify the message set to which the message is to be added or replaced. Use the following format:

SET MessageSetID

where the MessageSetID parameter is one of the following single characters:

Item Description
E Identifies Error Description
P Identifies Probable Cause
U Identifies User Cause
I Identifies Install Cause
F Identifies Failure Cause
R Identifies Recommended Action
D Identifies Detailed Data

The second line lists the message ID with the message to be added or replaced. At least one line is required, and multiple lines can be included, following a single line that identifies a message set. As described earlier, users should contact their service representative to obtain the message ID, unless it is required for an in-house application only (in which case, use the errmsg command to install the error message without a predetermined error message ID).

You must put a space between the message ID and the message text, and enclose the text of the message in double quotes as follows:

message ID "message text"

In addition to the two required lines of information, you can also include lines of comments. A comment line must have a $ (dollar sign) or an * (asterisk) operator in the first column. The asterisk is the preferred choice.

Note: Messages added to the Error Description, Probable Cause, and Detailed Data ID message sets must not exceed 40 characters in length. Messages added to the User Cause, Install Cause, Failure Cause, and Recommended Action message sets must not exceed 128 characters in length. If messages exceed these lengths, the errinstall command displays a warning message, but adds the messages to the codepoint catalogue. These messages will be truncated when displayed by the summary errpt command.

Flags

Item Description
-c Checks the input File parameter for syntax errors.
-f Replaces messages having duplicate IDs. When an attempt is made to add a message using a message ID that is already in use, the -f flag forces the errinstall command to replace the old message text with the new message text. If the -f flag is not specified, the old message text is not replaced and a warning message is written to standard error. The -f flag is also required to undo a message installation.
-q Suppresses the creation of an undo file.
-z FileName Uses the error logging message catalog specified by the FileName parameter.

Security

Access Control: Only the root user can run this command.

Attention RBAC users and Trusted AIX users: This command can perform privileged operations. Only privileged users can run privileged operations. For more information about authorizations and privileges, see Privileged Command Database in AIX® Version 7.1 Security. For a list of privileges and the authorizations associated with this command, see the lssecattr command or the getcmdattr subcommand.

Examples

  1. To install the error log messages for the licensed product lpp, enter:
    errinstall -f /tmp/lpp.desc
  2. To undo the changes made to the error log message catalog by the above example of the errinstall command, enter:
    errinstall -f /tmp/lpp.desc.undo
  3. To install an error message in the Probable Cause message set, enter:
    errinstall
     
    * Add a probable cause for widget failure:
    SET P
    E100 "widget adapter"
  4. To replace a message with a duplicate ID in the Probable Cause message set, enter:
    errinstall -f
     
    * Replace the message associated with ID E100 in the
    * Recommended Action message set
    SET R
    E100 "Replace disk drive"
  5. If you name your input file in_file and then want to use it to install new error messages, enter:
    errinstall in_file
  6. To overwrite existing error messages in message sets, use the previously defined ID numbers in your in_file, and specify the -f flag with the errinstall command as follows:
    errinstall -f in_file
  7. The following example illustrates sample contents of an input file to be installed.
    *
    * Add these error messages to the Detailed Data message set:
    *
    SET D
    8105 "Logical channel number"
    8106 "Timer reference stamp"
    *
    * Add these error messages to the Probable Cause message set:
    *
    SET P
    E861 "Bad memory card"
    E865 "Unexpected System Halt"
    E876 "Fiber Optic Cable"
    *
    * Add this message to the Recommended Action message set:
    *
    SET R
    E850 "Install updated driver code"

Files

Item Description
/usr/lib/nls/msg/$LANG/codepoint.cat Contains the error log message catalog. In the United States, the value of the $LANG environment variable is En_US.