MySQL Internals Manual  /  ...  /  Adding Error Messages to MySQL 5.0.3 or Higher

27.1.2 Adding Error Messages to MySQL 5.0.3 or Higher

The file you edit to add a new error message depends on your version of MySQL:

  • MySQL 5.0.3 up to 5.5: Edit errmsg.txt

  • MySQL 5.5 and up: Edit errmsg-utf8.txt

In either case, comp_err generates the header files automatically during the MySQL build process.

The errmsg.txt (or errmsg-utf8.txt) file begins with some lines that define general characteristics of error messages, followed by sections for particular messages. The following example shows a partial listing of the file. (The languages line is wrapped here; it must be given all on one line.)

languages czech=cze latin2, danish=dan latin1, dutch=nla latin1,
english=eng latin1, estonian=est latin7, french=fre latin1, german=ger
latin1, greek=greek greek, hungarian=hun latin2, italian=ita latin1,
japanese=jpn ujis, japanese-sjis=jps sjis, korean=kor euckr,
norwegian-ny=norwegian-ny latin1, norwegian=nor latin1, polish=pol
latin2, portuguese=por latin1, romanian=rum latin2, russian=rus
koi8r, serbian=serbian cp1250, slovak=slo latin2, spanish=spa latin1,
swedish=swe latin1, ukrainian=ukr koi8u;

default-language eng

start-error-number 1000

ER_HASHCHK
        eng "hashchk"
ER_NISAMCHK
        eng "isamchk"
ER_NO
        cze "NE"
        dan "NEJ"
        nla "NEE"
        eng "NO"
        est "EI"
        ...

A line beginning with a '#' character is taken as a comment. Comments and blank lines are ignored.

Indentation is significant. Unless otherwise specified, leading whitespace should not be used.

The grammar of the errmsg.txt file looks like this:

languages langspec [, langspec] ... ;

start-error-number number

default-language langcode

error-message-section
error-message-section
...

The languages line lists the languages for which language-specific errmsg.sys files should be generated. A language specification langspec in the languages line has this syntax:

langspec: langname=langcodelangcharset

langname is the long language name, langcode is the short language code, and langcharset is the character set to use for error messages in the language. langcharset is irrelevant as of MySQL 5.5 because all errmsg.sys files are written using utf8.

The default-language line specifies the short language code for the default language. (If there is no translation into a given language for a given error message, the message from the default language will be used.)

The start-error-number line indicates the number to be assigned to the first error message. Messages that follow the first one are numbered consecutively from this value.

Note

Beginning with MySQL 5.7.6, the file can contain multiple start-error-number lines, with each one resetting the numbering. This enables the file to contain multiple ranges of error numbers. For example, this capability is used to cause 5.7-specific error numbers to begin at 3000.

Each error-message-section begins with a line that lists an error (or warning) symbol, optionally followed by one or two SQLSTATE values. The error symbol must begin with ER_ for an error or WARN_ for a warning. Lines following the error symbol line provide language-specific error messages that correspond to the error symbol. Each message line consists of a tab, a short language code, a space, and the text of the error message within double quote ('"') characters. Presumably, there must be a message in the default language. There may be message translations for other languages. Order of message lines within a section does not matter. If no translation is given for a given language, the default language message will be used. The following example defines several language translations for the ER_BAD_FIELD_ERROR symbol:

ER_BAD_FIELD_ERROR 42S22 S0022
        dan "Ukendt kolonne '%-.64s' i tabel %s"
        nla "Onbekende kolom '%-.64s' in %s"
        eng "Unknown column '%-.64s' in '%-.64s'"
        est "Tundmatu tulp '%-.64s' '%-.64s'-s"
        fre "Champ '%-.64s' inconnu dans %s"
        ger "Unbekanntes Tabellenfeld '%-.64s' in %-.64s"

In the preceding example, two SQLSTATE values are given following the error symbol (42S22, S0022). Internally (in sql/sql_state.c), these are known as odbc_state and jdbc_state. Currently, only the first appears ever to be used.

In errmsg-utf8.txt, the entire file is written in utf8. As long as your editor can handle utf8, there should be no problem editing the file.

In errmsg.txt, message strings for a given language must be written in the character set indicated for that language in the languages line. For example, the language information for Japanese in that line is japanese=jpn ujis, so messages with a language code of jpn must be written in the ujis character set. You might need to be careful about the editor you use for editing the errmsg.txt file. For example, there is a report that using Emacs will mangle the file, whereas vi will not.

Within a message string, C-style escape sequences are allowed:

\\  \
\"  "
\n  newline
\N  N, where N is an octal number
\X  X, for any other X

In MySQL 5.5 and up, error messages can contain positional constructs for arguments. This is convenient when arguments are most naturally specified in different orders in different languages. Positional arguments enable and error-message writer to avoid awkward language or unnecessarily long messages that result from having the arguments in the same order in all languages.

  • To specify a positional argument, include a single digit 0 to 9 and a dollar sign in the formatting specifier for each argument in the error message: "%1$.32s %2$.64s" includes the first argument, then the second, in that order. "%2$.64s %1$.32s" includes the second argument, then the first.

  • If any argument is positional, all must be positional. This is illegal: "%1$.32s %.64s"

  • Duplicates are allowed. This is legal even though it includes the first argument twice: "%1$.32s %2$.64s %1$.32s"

  • Gaps in positional number are not allowed. This is illegal because $2 is missing: "%1$.32s %3$.64s"

Use the following procedure to add new error messages:

  1. To add a new language translation for an existing error message, find the section for the appropriate error symbol. Then add a new message line to the section. For example:

Before:

ER_UNKNOWN_COLLATION  
        eng "Unknown collation: '%-.64s'"
        ger "Unbekannte Kollation: '%-.64s'"
        por "Collation desconhecida: '%-.64s'"

After (with a new Spanish translation):

ER_UNKNOWN_COLLATION  
        eng "Unknown collation: '%-.64s'"
        ger "Unbekannte Kollation: '%-.64s'"
        por "Collation desconhecida: '%-.64s'"
        spa "Collation desconocida: '%-.64s'"
  1. To add an entirely new error message, go to the end of the errmsg.txt file. Add a new error symbol line, followed by a message line for the default language, and message lines for any translations that you can supply.

  2. Make a full build (configure + make). A make all is insufficient to build the sql/share/*/errmsg.sys files.

comp_err will generate the errmsg.sys files, as well as the header files mysqld_error.h, mysqld_ername.h, and sql_state.h in the include directory.

Be aware that if you make a mistake editing a message text file, comp_err prints a cryptic error message and gives you no other feedback. For example, it does not print the input line number where it found a problem. It's up to you to figure this out and correct the file. Perhaps that is not a serious difficulty: errmsg.txt (or errmsg-utf8.txt) tends to grow by gradual accretion, so if an error occurs when comp_err processes it, the problem is likely due to whatever change you just made.


User Comments
User comments in this section are, as the name implies, provided by MySQL users. The MySQL documentation team is not responsible for, nor do they endorse, any of the information provided here.
Sign Up Login You must be logged in to post a comment.