explain command

The explain command displays online error message explanations.

Synopsis

explain {msgID} [...]

explain -l [{pattern}...]

explain [-d] {msgID} [...]

Description

The explain command displays on-line error message explanations. The {msgID} is one of the two forms of identification that comes with each message. The primary form is {CLASS}nnn , where {CLASS} is the class of messages, such as CGEN or TSM, and nnn is the index of the message within the class of messages. The second form, available with most messages is the mnemonic form (for example, CGEN_NOMSGQ or CGEN_MSGRCV).

If the explanation of the message fits in 24 lines and only a single explanation has been requested, it is printed without interruption. If the explanation is longer than 24 lines or more than one explanation is requested, the output is paged via the use of a paging program. Use the -d option to disable paging. The default paging program is /bin/pg.

If the -l option is used, explain looks up all messages whose {msgID} matches the pattern. For example, explain -l A V lists the names of explanations available that begin with either A or V, while explain -l VROP lists all explanation names available that begin with VROP. In other words, the {pattern} is anchored at the beginning of the {msgID} and assumes a match of anything after the pattern selected.

The explain command is also affected by certain environment variables. These environment variables, described in the following table, are intended for advanced users only.

The edExplain command allows you to add or change explanations. An explanation comes in two parts, a file containing the explanation itself, and a set of synonyms or translations that allow the explain command to find the file under more than one tag. To create a new explanation, you must provide both. When modifying an existing explanation, all you need to do is edit the file that contains the explanation.

The explanation file itself is an almost-clear text file of what you want the user to see when they ask for the explanation. There are two features of the file that are not plain clear text. All lines beginning with the pound sign (#) are treated as internal comments and are not output. Also lines of the form explain {msgID} have special meaning. They cause the inclusion of the explanation text specified by the {msgID}. This allows you to have common explanations and reference from more than one explanation.

The recommended format for an explanation procedure is:

# Comment and SCCS keywords

<< {msgID} [{msgID}...] >>
{text of message}
...

When creating a new explanation procedure, you are asked to edit the synonyms list place it in the appropriate translateLst file. There are instructions at the top of the file. Each non-comment line is a list of synonyms, with the right-most word on the line being the name of the file in which the text is located. For example:

ADM001 ADM_SYSERR
ALERT003 AL_INVALID_THRESHOLD AL_INVALID_T

The descriptions for ADM001 and ADM_SYSERR are found in a file named ADM_SYSERR. The descriptions for ALERT003 and AL_INVALID_THRESHOLD are found in a file named AL_INVALID_T. The second example has a truncated file name, because file names are limited to 14 characters in most Solaris systems, and if you want to use source code control, the file name must not be longer than 12 characters. The recommended way to store an explanation is under a file name related to the mnemonic {msgID} rather than the {CLASS}nnn name, since the later is meaningless. A file name of the form {CLASS}nnn does not provide a sophisticated user with much information about the contents of the file, while the mnemonic form does. If the mnemonic is longer than 12 characters, create a shorter name related to the mnemonic that is unique within 12 characters.

There are some environment variables that affect the behavior of edExplain:

Files

• /vs/data/explain is the directory in which explanation directories are located
• /vs/data/explain/translateLst is the file containing the synonym list of {msgID} s

See also

• edExplain command

© 2006 Avaya Inc. All Rights Reserved.