# Chapter 5. Creating and Loading Message Definitions

This chapter describes the following:

- Message Definitions

- Getting Message Definitions into the Log Central Database

- Using Other Message Definition Commands

## Message Definitions

Applications generate messages in many different formats. Log Central stores messages in its database in one format. It also stores message definitions. Message definitions provide static information about messages that may be generated by various applications. Such information might include recommendations for how to respond to specific errors. Message definitions can be viewed within the Log Central Console with the Message Details window of the Message Browser. For more information about the Message Browser, refer to Chapter 9, "Using the Log Central Console."

Message definitions provide information about probable causes or suggest corrective actions in response to received messages. Two fields in the Log Central message format-Description and Recommendation-are provided for this purpose. You can access this information from the Log Central Console by invoking the Message Browser Message Details window, as described in Chapter 9, "Using the Log Central Console," or by exporting message definitions to a file, as described in this chapter in "Exporting Message Definitions." This information is stored in the message type definitions in the Log Central database.

Message definitions are provided out-of-the-box for BEA TUXEDO applications, Oracle Host Log, and NT eventlog messages. Utilities, which are described in this chapter, are provided to add message definitions for other resources you wish to manage. The Message Definition Editor of the Log Central Console can also be used to update these fields. This facility allows users to update probable cause or recommended action fields in light of their experience.

## Getting Message Definitions into the Log Central Database

To get message definitions into the Log Central database, you perform the following two steps:

1. Create a Message Definition File

2. Load the Message Definition File

You can also modify or create message definitions one at a time through the GUI. How to do this is described in Chapter 9, "Using the Log Central Console."

### Create a Message Definition File

To create a message definition file, perform one of the following two actions:

- Construct your own file, following the structure and rules of the template (`install_dir``/etc/msgdef.template`) supplied with Log Central.

- Copy the template and then edit it to your specifications.

The remainder of this section provides details.

#### Description of Message Definition File

A message definition file contains one or more message definitions, each of which consists of up to 10 fields. Two of those fields, `SUBSYSTEM` and `SEVERITY`, must appear in the first message definition, and can optionally appear in succeeding definitions. If they are not specified in any definition after the first, their values are inherited from the last definition in which they were specified. Severity is an important attribute of a message. The severity of a message is a rating used to represent the importance or impact of an event. For example, a message that indicates high usage of a print spooler reports a less severe event than a message telling you that an application server has crashed. The Log Central Central Collector assigns a severity to messages as it saves the message in the Log Central database or to generate SNMP traps. When the Log Central Console displays messages in its Message Browser, the messages are typically colored depending on their severity. If you want the same subsystem and severity to apply to all message definitions, you can specify these values only in the first definition. Typically, though, you would assign a different severity to each message definition, and thus would repeat this field for each message definition. Alternatively, you could group message definitions by severity, so as to preclude having to repeat the same severity for each definition in a group.

The subsystem and message ID are used to correlate incoming messages in the Log Central database with their corresponding message definitions. Thus, when a message with a particular subsystem and message ID arrives, you can display its corresponding message definition.

Two of the fields, `MESSAGE_ID` and `SUMMARY`, must appear in every message definition. The message ID uniquely identifies a message definition, while the message summary gives it contextual identity.

Other fields are optional. If a particular field appears in one message definition, but not in succeeding definitions, the value of that field is inherited by message definitions that follow. Each message definition is enclosed within a pair of braces (`{}`).

The message definitions are stored in an ASCII text file. You can either construct your own file, following the structure and rules of the template supplied with Log Central, or copy the template and then edit it to your specifications. The template is found in `install_dir``/etc/msgdef.template`. If you use the template, you must edit all constructs following equals signs because the constructs specified in the template file are just descriptive placeholders.

#### Fields of a Message Definition File

The fields of a message definition are shown in the following table in the order in which they appear in the message definition file.

Field Name | Format | Description
--- | --- | ---
`SUBSYSTEM` | String field, single line, maximum of 8 characters. | Subsystem name (for example, TUXEDO, syslog), which must appear in the first message definition.
`MESSAGE_ID` | Integer, appearing on a single line, in the range 1-99999. | The message ID, which must appear in every message definition, which must be unique within a subsystem.
`SUMMARY` | String field, single line, maximum of 40 characters. | Summary of the `DESCRIPTION` field, which must appear in every message definition.
`SEVERITY` | One of the following strings: `Informational`, `Warning`, `Minor`, `Major`, `Critical` | The severity level of the message.
`DESCRIPTION` | String field, on one or more lines. The total maximum of this field plus the `RECOMMENDATION` field must not exceed 2 Gb. | The text to be associated with the message.
`RECOMMENDATION` | String field, on one or more lines. The total maximum of this field plus the `DESCRIPTION` field must not exceed 2 Gb. | A recommendation of what to do when encountering this message.
`EXECUTE_ON_UPLOAD` | String field, single line, maximum of 40 characters. | The path to a script or executable file to invoke when the Central Collector loads the specified message into the Log Central database.
`TRAP_ID` | Integer, appearing on a single line, in the range 1-99999. | The specific SNMP trap ID to issue upon encountering this message.
`TRAP_ENABLED` | A string, one of `Yes` or `No`. | A flag indicating whether the SNMP trap is to be enabled. Default is `No`.
`AUTO_ACKNOWLEDGE` | A string, one of `Yes` or `No`. | A flag indicating whether the message is to be automatically acknowledged. Default is `No`.

### Example

A sample message definition might look like the one following this paragraph. This definition includes all of the possible fields. Its subsystem is `TUXEDO`, its `MESSAGE_ID=1206`, its severity is `Critical`. The summary, description, and recommendation are as shown. When the Central Collector loads a message of ID 1206 and subsystem TUXEDO, the file `sendalert.exe` is executed. This could, for example, send an alert to the system administrator. Whenever a message matching this `MESSAGE_ID` and subsystem appears, Log Central issues an SNMP `TRAP_ID=47`. The message is also automatically marked as acknowledged.

>     {
>     SUBSYSTEM         = TUXEDO
>     MESSAGE_ID        = 1206
>     SUMMARY           = Memory allocation failed for compression
>     SEVERITY          = Critical
>     DESCRIPTION       = An attempt dynamically to allocate memory from the\
>     operating system failed while compressing a message.
>     RECOMMENDATION    = Make sure the operating system parameters are set\
>     correctly for the amount of memory on the machine and the amount of memory that\
>     can be used by a process. Reduce the memory usage on the machine or increase\
>     the amount of physical memory on the machine.
>     EXECUTE_ON_UPLOAD = C:\bin\sendalert.exe
>     TRAP_ID           = 47
>     TRAP_ENABLED      = Yes
>     AUTO_ACKNOWLEDGE  = Yes
>     }

### Load the Message Definition File

Once you have constructed your own message definition file, you load it into the Log Central database by entering the following command at the command-line prompt:

>     msgdef_import [-f filename] [-inifile inifilename]

where:

`filename`
  Specifies the complete file name from which the message definitions are to be imported into the Log Central database. The contents of this file must follow a specified format. If no file name is given, text is accepted from the standard input of the terminal.

`inifilename`
  Specifies the complete file name of the initialization file. If no name is given, the name `msg_processor.ini` is used. The initialization file is described in detail in Appendix F, "Initialization File."

## Using Other Message Definition Commands

There are also command-line utilities that enable you to export message definitions from the Log Central database to an ASCII text file and delete selected message definitions.

### Exporting Message Definitions

You can export message definitions from the database to an ASCII text file with the `msgdef_export` command at the command-line prompt. The exported data is written to a file in the format described in "Create a Message Definition File." To export message definitions, use the following command at the command-line prompt:

>     msgdef_export [-f filename] [-s subsystem_name
>     [-s subsystem_name...]] [-inifile inifilename]

>     msgdef_import [-f filename] [-inifile inifilename]

where:

`filename`
  Specifies the complete file name to which the message definitions are to be exported. If no file name is given, the message definitions are displayed on the standard output of the terminal.

`subsystem_name`
  Specifies the subsystem name for which message definitions will be exported. If no subsystem is given, the message definitions for all subsystems are exported. You can supply a list of subsystem names.

`inifilename`
  Specifies the complete file name of the initialization file. If no name is given, the name `msg_processor.ini` is used. The initialization file is described in detail in Appendix F, "Initialization File."

### Deleting Message Definitions

You can delete the message definitions specified in the message definition file from the Log Central database with the `msgdef_delete` and `subsystem_delete` commands at the command-line prompt. If you want to delete a group of message definitions you loaded previously, you could use the same message definition file you used with the `msgdef_import` command. If you want to delete a group of message definitions that belong to a specific subsystem, use the `subsystem_delete` command.

#### How to Delete a List of Message Definitions

You can delete a list of message definitions by using the following command:

>     msgdef_delete [-f filename] [-inifile inifilename]

where:

`filename`
  Specifies the complete file name that contains a list of message definitions to be deleted. The contents of this file must follow a specified format, as described in "Create a Message Definition File." Only the subsystem name and message ID are used for the deletion operation. If no file name is given, text is accepted from the standard input of the terminal.

`inifilename`
  Specifies the complete file name of the initialization file. If no name is given, the name `msg_processor.ini` is used. The initialization file is described in detail in Appendix F, "Initialization File."

You might use this command to delete the message definitions you just loaded with `msgdef_import`.

#### How to Delete Message Definitions Associated with a Subsystem

You can delete all the message definitions associated with a particular subsystem, as well as the subsystem name entry. To do so, use the following command:

>     subsystem_delete -s subsystemname [subsystem_name]

where:

`filename`
  Specifies the complete file name to which the message definitions are to be exported. If no file name is given, the message definitions are displayed on the standard output of the terminal.

`subsystem_name`
  Specifies the subsystem name for which to delete all message definitions. You can supply a list of subsystem names. Only the subsystem name and message ID are used for the deletion operation.