[ Previous | Next | Table of Contents | Index | Library Home |
Legal |
Search ]
Commands Reference, Volume 2
Updates the Error Record Template
Repository.
errupdate [ -c] [ -f] [ -h]
[ -n] [ -p] [ -q]
[ -yFileName] [
File ]
The errupdate command
adds or deletes entries in the Error Record Template Repository, or modifies
the log, report, or alert characteristics of existing entries. The
errupdate command reads from the specified File
parameter. If the File parameter is not specified, the
errupdate command reads from standard input and writes to standard
output.
Each entry to be added, deleted,
or modified must be preceded by an operator. The valid operators
are:
| +
| Adds an entry (add operator).
|
| -
| Deletes an entry (delete operator).
|
| =
| Modifies the log, report, or alert characteristics of an entry.
|
Entries in the input file must be
separated by a blank line.
Comments in the input file can be
placed between templates and are indicated by an * (asterisk) in
the first column.
If XPG/4 messages are used in error templates, a message catalog must be
specified. This can be done with a line of the form:
<*!catalog-name>
For example
*!mycat.cat
The catalog specified applies to XPG/4 messages found in subsequent
templates, until another "*!" catalog specifier is encountered. Also,
the "*!" specifier may be overridden on an individual template basis with the
"catname" keyword.
Unless a full pathname to the catalog is specified, the normal rules for
retrieving a message catalog are followed. For example, in the above
example, mycat.cat is assumed to be in
/usr/lib/nls/msg/%L.
Entries to be added must be
defined in a specific format. The general form of the error record
template is:
Error Record Template
+ LABEL:
Comment=
Class=
Log=
Report=
Alert=
Err_Type=
Err_Desc=
Prob_Causes=
User_Causes=
User_Actions=
Inst_Causes=
Inst_Actions=
Fail_Causes=
Fail_Actions=
Detail_Data= <data_len>, <data_id>,
<data_encoding>
Additionally, a catalog name for XPG/4 messages can be specified
with:
catname = <catalog>
Any template which contains XPG4 messages, the catname keyword, more than
eight detail data items will be referred to as an XPG4 template. An
XPG4 template is not alertable, and uses a slightly different calculation for
the error id.
The error record template fields
are described as follows:
| Alert
| Indicates that the error log entry can be processed by products that
conform to the SNA Generic Alert Architecture. The Alert
field can be set to True or False. If this field is omitted from the
template, its value will default to False. If the Alert
field is set to True, the errupdate command does not add the
template unless the contents of the Err_Desc ,
Inst_Actions , Fail_Cause, Fail_Actions , and
Detail_Data data_id fields are values recognized by the SNA Generic
Alert Architecture (in publication GA27-3136). If any of the values
used are not recognized by the SNA Generic Alert Architecture or the template
is an XPG4 template, and the Alert field is set to True, the
-p flag must be specified to add or update the template.
|
| Class
| Describes whether the error occurred in hardware or software, is an
operator message, or is undetermined. One of the following class
descriptors must be specified:
- H
- Indicates the error is a hardware failure.
- O
- Indicates the error is an operator message.
- S
- Indicates the error is a software failure.
- U
- Indicates the error is undetermined.
|
| Comment
| Specifies a comment to be included with the #define statement
that was created for the Error ID message set. The comment must not
exceed 40 characters and must be enclosed in double quotation marks.
Comments longer than 40 characters are automatically truncated.
The errupdate command encloses the comment in the C language
comment delimiters, /* (slash, asterisk) and */ (asterisk, slash).
|
| Detail_Data
| Describes detailed data, such as detecting module names, sense data, or
return codes, that are logged with the error when the error occurs. If
no detailed data is logged with the error, this field can be left blank or it
can display a message from the Detailed Data ID message set by specifying a
data_len value of zero. The following three values are
required for each Detail_Data field and must be separated by
commas:
- data_len
- Number of bytes of data to be associated with the data_id
value. The data_len value is interpreted as a decimal
value. To specify environment dependent size, use "W". "W" will
be treated as 8 bytes if error is logged from a 64-bit environment, otherwise
4 bytes.
Note: During detail data length calculation, each "W" is
treated as 8 bytes long, and it is not case sensitive.
- data_id
- Identifies a text message from the Detailed Data ID message set
"D" to be printed in the error report in front of the detailed
data. The value is interpreted as an unsigned hexadecimal up to 4
digits in length.
- data_encoding
- Describes how detailed data is to be printed in an error report.
Valid values are:
- ALPHA
- The detailed data is a printable ASCII character string.
- DEC
- The detailed data is the binary representation of an integer value, and
the decimal equivalent is to be printed.
- LDEC
- The detailed data is the binary representation of a 64-bit value, and the
decimal equivalent is to be printed.
- HEX
- The detailed data is to be printed in hexadecimal.
Up to 16 Detail_Data
entries may be specified per template. The amount of data logged with
an error must not exceed the maximum error record length defined in the
/usr/include/sys/err_rec.h file. Error data that cannot be
contained in an error log entry should be saved elsewhere. Detailed
data in the error log entry should contain information that can be used to
correlate the error data and the error log entry.
|
| Err_Desc
| Describes the error that has occurred. An Error Description
message identifier must be specified in this field. This value
identifies a text message from the Error Description message set "E"
to be displayed for an occurrence of the error. The value is
interpreted as an unsigned hexadecimal up to 4 digits in length. The
field may also specify an XPG/4 style message. This is discussed
later.
|
| Err_Type
| Describes the severity of the error that has occurred. One of the
following values must be specified:
- PERF
- Condition where the performance of the device or component has degraded to
below an acceptable level (performance).
- PERM
- Condition that cannot be recovered from (permanent).
- PEND
- Condition signifying that the loss of availability of a device or
component is imminent (impending).
- TEMP
- Condition that was recovered from after a number of unsuccessful attempts
(temporary).
- UNKN
- Condition where it is not possible to determine the severity of the error
(unknown).
- INFO
- Condition for informational error log entry.
|
| Fail_Actions
| Describes recommended actions for correcting an error that resulted from
a failure cause. A list of up to 4 Recommended Action message
identifiers separated by commas can be specified. This value identifies
a text message from the Recommended Action message set "R" to be
displayed for an occurrence of the error. The value is interpreted as
an unsigned hexadecimal up to four digits in length. This field must be
blank if the Fail_Causes field is blank.
The order in which the
recommended actions are listed should be determined by the expense of the
action and the probability that the action will correct the error.
Always list the actions that have little or no cost (or little or no impact)
on the system first. List the actions for which the probability of
correcting the error is equal or nearly equal next, with the least expensive
actions first. List the remaining actions in order of decreasing
probability. The field may also specify an XPG/4 style message.
This is discussed later.
|
| Fail_Causes
| Describes failure causes for the error that has occurred. A
failure cause is defined as a condition that resulted from the failure of a
resource. This field can list up to four Failure Cause message
identifiers separated by commas. This value identifies a text message
from the Failure Cause messages set "F" to be displayed for an
occurrence of the error. The value is interpreted as an unsigned
hexadecimal up to 4 digits in length. List the failure causes in order
of decreasing probability. This field can be left blank if it does not
apply to the error that has occurred. If this field is blank, either
the User_Causes or the Inst_Causes field must not be
blank. The field may also specify an XPG/4 style message. This
is discussed later.
|
| Inst_Actions
| Describes recommended actions for correcting an install caused
error. This field can list of up to 4 Recommended Action message
identifiers separated by commas. This value identifies a text message
from the Recommended Action message set "R" to be displayed for an
occurrence of the error. The value is interpreted as an unsigned
hexadecimal up to four digits in length. This field must be blank if
the Inst_Causes field was left blank. The order in which
the recommended actions are listed is determined by the expense of the action
and the probability that the action will correct the error. The actions
that have little or no cost or little or no impact on the system should always
be listed first. Actions for which the probability of correcting the
error are equal or nearly equal should be listed next, with the least
expensive actions first. The remaining actions should be listed in
order of decreasing probability. The field may also specify an XPG/4
style message. This is discussed later.
|
| Inst_Causes
| Describes install causes for the error that has occurred. An
install cause is defined to be a condition that resulted from the initial
installation or setup of a resource. A list of up to 4 Install Cause
message identifiers separated by commas can be specified. This value
identifies a text message from the Install Cause message set "I" to be
displayed for an occurrence of the error. The value is interpreted as
an unsigned hexadecimal up to four digits in length. Install causes
should be listed in order of decreasing probability. This field can be
left blank if it is not applicable to the error that has occurred. If
this field is left blank, the User_Causes or the
Fail_Causes field must be non-blank. The field may also specify
an XPG/4 style message. This is discussed later.
|
| LABEL
| Specifies a unique label of up to 19 characters that must be provided for
each error logging template. A string containing " #define
#ERRID_label Error_ID ", where the Error_ID value is the
unique ID assigned to the Error Record Template is written to standard output
if the -h flag was specified at the command line.
|
| Log
| Specifies whether an error log entry should be created for this error
when it occurs. The log field can be set to True or False. If
this field is omitted from the template, its value will default to
True. When this field is set to False, the Report and
Alert fields are ignored.
|
| Prob_Causes
| Describes 1 or more probable causes for the error that has
occurred. A list of up to 4 Probable Cause message identifiers
separated by commas can be specified. This value identifies a text
message from the Probable Cause message set "P" to be displayed for an
occurrence of the error. The value is interpreted as an unsigned
hexadecimal up to 4 digits in length. Probable causes should be listed
in order of decreasing probability. At least one probable cause is
required. The field may also specify an XPG/4 style message.
This is discussed later.
|
| Report
| Specifies whether logged occurrences of this error should be reported
when an error report is printed. The Report field can be
set to True or False. If this field is omitted from the template, its
value will default to True.
|
| User_Actions
| Describes recommended actions for correcting a user-caused error.
A list of up to 4 Recommended Action message identifiers separated by commas
can be specified. This value identifies a text message from the
Recommended Action message set "R" to be displayed for an occurrence
of the error. The value is interpreted as an unsigned hexadecimal up to
4 digits in length. This field must be left blank if the
User_Causes field was left blank. The order in which the
recommended actions are listed is determined by the expense of the error and
the probability that the action will correct the error. The actions
that have little or no cost, or little or no impact on the system should
always be listed first. Actions for which the probability of correcting
the error are equal or nearly equal should be listed next, with the least
expensive actions first. The remaining actions should be listed in
order of decreasing probability. The field may also specify an XPG/4
style message. This is discussed later.
|
| User_Causes
| Describes user causes for the error that has occurred. A user
cause is defined as a condition that can be corrected without contacting a
service organization. A list of up to four User Cause message
identifiers separated by commas can be specified. This value identifies
a text message from the User Cause message set "U" to be displayed for
an occurrence of the error. The value is interpreted as an unsigned
hexadecimal up to four digits in length. User causes should be listed
in order of decreasing probability. This field can be left blank if it
is not applicable to the error that has occurred. If this field is left
blank, the Inst_Causes or the Fail_Causes field must
be non-blank. The field may also specify an XPG/4 style message.
This is discussed later.
|
The catname is used to specify a message catalog to be used for retrieving
XPG/4 messages for the current template. This will override a catalog
specified with a previous "*!" catalog specifier. Any template
containing XPG/4 messages must have a catalog specified either with catname or
"*!". The catalog name must be enclosed in quotes. Unless a full
pathname to the catalog is specified, the normal rules for retrieving a
message catalog are followed.
For example, if
catname = "mycat.cat"
is specified, mycat.cat is assumed to be in
/usr/lib/nls/msg/%L.
The Error Description, Probable Cause, User Cause, Install Cause, Failure
Cause, Recommended Actions, and Detailed Data ID messages must be either an
error message identifier maintained in the error log message catalog, or an
XPG/4 message.
An error message identifier consists of up to 4 hexadecimal digits, without
any leading "0x". For example, 1234 or ABCD. The errmsg
-w command can be used to print these messages along with their
identifiers. The errmsg command can
be used to add new messages.
An XPG/4 message is specified using the form
{<set>, <number>, <"default text">}
The set, number, and default text are all required. Symbolic message
references are not supported. Also, templates which contain XPG/4
messages are not alertable.
A message catalog must be specified for XPG/4 messages. This is done
with either the "*!" catalog specifier, or the catname keyword.
Error logging does not support all the features of normal error
messaging. Strings used in error log templates must conform to some
restrictions.
- Variable substitution is not supported. For example, the strings
may not be used as format specifiers to print values. The strings may
only contain the formatting characters "\t" and "\n".
- The default text strings may not be longer than 1 kb, 1024 bytes.
- It must be noted that the error description is printed in a 40 character
area on the non-detailed reports. No string formatting is done for
these reports, and only the first 40 characters will be printed.
- The strings should not contain a trailing new line. This is
supplied by errpt.
The Error Description, Probable
Cause, User Cause, Install Cause, Failure Cause, Recommended Actions, and
Detailed Data ID messages are maintained in the error log message
catalog. The errmsg -w command can be used to print the messages
along with their identifiers. The errmsg command can be used to add new
messages.
For each entry added, the
errupdate command assigns a unique Error ID that is written to the header file
specified by File.h (where the File parameter is
the name of the errupdate command input file). If the errupdate command
is reading from standard input, the #define statement is written
to standard output. The values supplied for the Class ,
Err_Desc , Err_Type , Fail_Actions ,
Fail_Causes , Inst_Actions ,
Inst_Causes , Prob_Causes , User_Actions ,
User_Causes fields, and the Detail_Data .
data_id value, are used to calculate the unique Error ID for that
error. For XPG4 templates, the Label is also included in the
calculation.
The contents of the
Log , Report , and Alert fields are not
included in the calculation of the unique Error ID; therefore, the log,
report, and alert characteristics of a particular error can be modified at any
time in the error entry definition stored in the Error Record Template
Repository using the errupdate command. Also note that the
data_len and data_encode portions of the detail data field are not
used.
The errupdate command
also creates an undo file in the current directory named
File.undo. If the errupdate command
is reading from standard input, the undo file is written to
errids.undo file. The undo file contains
inputs to the errupdate command to undo changes the
errupdate command has made.
The errpt -t
command can be used to view the contents of the Error Record Template
Repository. The templates are processed and printed as they would
appear in an actual error report.
Attention: If you change the error templates be aware that
these templates may be changed by a subsequent update. You should keep
a record of all changes made and re-apply the changes when your system is
updated. This is usually only necessary after a major system update
such as moving to a new level of the operating system. Also, such a
record allows you to change your templates if you re-install. The
easiest way to keep such a record is to always make your template
modifications from one errupdate source file.
| -c
| Checks the input file for syntax errors.
|
| -f
| Forces all templates to be updated, including any templates with error
ids identical to ones in the input templates
|
| -h
| Creates a #define statement for each Error ID assigned to an
error template. If a file name was supplied on the command line, the
header file name will be that supplied file name appended with
.h. Otherwise, the #define statements
are written to standard output.
|
| -n
| Suppresses the addition of the error record template to the Error Record
Template Repository.
|
| -p
| Adds or updates a template with the Alert field set to True
that contains Error Description, Probable Cause, User Cause, User Action,
Install Cause, Install Action, Failure Cause, Fail Action, or Detailed Data
data id values that are not recognized by the SNA Generic Alert Architecture
(in publication GA27-3136). The errupdate command will not
let you add a template with these characteristics unless you specify this
flag.
|
| -q
| Suppresses the creation of an undo file.
|
| -y FileName
| Uses the error record template file specified by the FileName
parameter.
|
Access Control: Only the
root user can run this command.
- To add an entry, define the
entry in the input file in the following manner:
+ CDROM_ERR22:
Comment= "Temporary CDROM read error"
Class= H
Log= True
Report= True
Alert= False
Err_Type= TEMP
Err_Desc= E801
Prob_Causes= 5004
Fail_Causes= E800, 6312
Fail_Actions= 1601, 0000
Detail_Data= 120, 11, HEX
Detail_Data= 4, 8058, DEC
Detail_Data= 4, 8059, DEC
To enter the data,
errupdate <input file>
- To modify the log, report,
and alert characteristics of entry 99999999 , specify the modify
operator = (equal sign) followed by the unique Error ID, and the new
characteristics for the entry to be modified:
errupdate
=99999999:
Report = False
Log = True
- To delete entry
99999999 from the Error Record Template Repository, specify the delete
operator - (minus sign) followed by the unique Error ID of the entry to be
deleted:
errupdate
-99999999:
- To override the XPG/4 message catalog specified for this input stream with
"*!", use the "catname" keyword.
*!mycat.cat
* mycat.cat is used for all XPG/4 messages from now
on.
* except for this one:
+ CDROM_ERR23:
Comment= "Temporary CDROM read error"
catname= "othercat.cat"
Class= H
Log= True
Report= True
Alert= False
Err_Type= TEMP
Err_Desc= {1, 1, "CD ROM is broken"}
Prob_Causes= {2, 1, "cause 1"},\
{2, 2, "Cause 2"}
Fail_Causes= E800, 6312
Fail_Actions= 1601, 0000
Detail_Data= 120, 11, HEX
Detail_Data= 4, 8058, DEC
Detail_Data= 4, 8059, DEC
The catalog othercat.cat will be used for the CDROM_ERR23 template
only.
Note: A template may contain both XPG/4 messages and the
traditional error ids or codepoints.
| /usr/include/sys/errids.h
| Contains the header file that contains Error IDs.
|
| /usr/include/sys/err_rec.h
| Contains the header file that contains structures for logging
errors.
|
The errclear command, errdead command, errinstall command, errlogger command, errmsg command, errpt command, errstop command.
The errdemon daemon.
The errsave kernel service.
The errlog subroutine.
Error Logging
Overview in AIX 5L Version 5.1 General Programming
Concepts: Writing and Debugging Programs
[ Previous | Next | Table of Contents | Index |
Library Home |
Legal |
Search ]