Overview

Universal Agent component error messages are translated - by the Universal Message Translator (UMET) utility - into return (exit) codes based on a user-defined translation table.

Every command ends with a return code that indicates the success or failure of the command execution. Typically, a return code of 0 indicates success; all other codes indicate failure.

However, a small number of commands do not set their return code under failure conditions; instead, they issue error messages. Based on the user-defined translation table, Universal Message Translator translates these error messages into return codes.

Usage

Universal Message Translator requires two input files:

Message Input file (user-specified or standard input) containing the error messages that are to be translated into a return codes.
Translation Table file containing the user-defined translation table that controls the error message-to-return code translation process.

To perform a translation, Universal Message Translator:

Reads the messages in the input file.
Matches each line against the translation table entries.
Exits with an return code from the best match in the translation table.

If no match is found, Universal Message Translator ends with return code 0.

Universal Message Translator performs operations specified by the configuration options. This section describes each option and their syntax.

Translation Table

The translation table specifies:

Text to search for.
Return code associated with the text.
Precedence when multiple matches are found.

Translation Table Format

The translation table consists of one or more lines.

Each line is either:

Comment line (# in column one)
Blank line (ignored)
Translation table entry

Translation table entries consist of two fields separated by spaces or tabs. An entry cannot be continued onto multiple lines.

Translation Table Fields

Field

Description

Message Mask

Selects which messages to match in the input file. The mask must be enclosed in double ( " ) quotation marks.

Mask characters include the asterisks ( * ) and the question mark ( ? ). The asterisk matches 0 or more characters and the question mark matches one character.

If an asterisk, question mark, or quotation mark is required in the message text, it must be preceded with a back slash ( \ ). If a back slash is required in the message text, it must be preceded by another back slash.

Exit Code

Specifies an integer value that UMET exits with if this entry is the resulting match.

The exit code is in the range of -99999 to 99999.

Matching Algorithm

The input file is read line by line. For each line, the line is compared to each entry in the translation table. All the matching entries are saved.

After the entire input file is read, the matched entries from the translation table are sorted in ascending order by their line number in the translation table. The first entry in this sorted list is the resulting translation table entry. The exit code from the resulting translation table entry is used as the return code of UMET. If no matching entry is found, UMET exits with 0.

IBM i

The resulting return code from the translation process is converted into an IBM i escape message.

The escape message ID and message severity depend on the return code value as identified in the following table.

Return Code	Message ID	Message Severity
1 - 10	UNV0344	10
11 - 20	UNV0345	20
21 - 30	UNV0346	30
31 and higher	UNV0347	40

Additional Information

The following pages provide additional detailed information for Message Translation:

Message Translation - Examples