| List: | Internals | « Previous MessageNext Message » | |
| From: | paul | Date: | September 10 2005 6:32pm |
| Subject: | bk commit - mysqldoc@docsrva tree (paul:1.3525) | ||
| View as plain text | |||
Below is the list of changes that have just been committed into a local mysqldoc repository of paul. When paul does a push these changes will be propagated to the main repository and, within 24 hours after the push, to the public repository. For information on how to access the public repository see http://www.mysql.com/doc/I/n/Installing_source_tree.html ChangeSet 1.3525 05/09/10 11:32:05 paul@stripped +1 -0 internals.xml: Update the procedure for adding new error messages. internals/internals.xml 1.27 05/09/10 11:31:32 paul@stripped +325 -38 Update the procedure for adding new error messages. # This is a BitKeeper patch. What follows are the unified diffs for the # set of deltas contained in the patch. The rest of the patch, the part # that BitKeeper cares about, is below these diffs. # User: paul # Host: frost.snake.net # Root: /Volumes/frost2/MySQL/bk/mysqldoc --- 1.26/internals/internals.xml 2005-09-03 12:28:00 -05:00 +++ 1.27/internals/internals.xml 2005-09-10 11:31:32 -05:00 @@ -6548,9 +6548,7 @@ from root). </para> - <para> <!-- Question: Does this really capitalize? --> - </para> </listitem> <listitem> @@ -11850,9 +11848,7 @@ and an example. </para> -<!-- TODO: this should be reformatted - the types each should be preceded --> - -<!-- by @item, not a blank line. --> +<!-- TODO: this should be reformatted (use a table?) --> <itemizedlist> @@ -12673,7 +12669,7 @@ <title id="title-the-myi-file">The <filename>.MYI</filename> file</title> -<!-- TODO: change some of the @strong things to real headings. --> +<!-- TODO: change some of the bold things to real headings. --> <para> A <filename>.MYI</filename> file for a <literal>MyISAM</literal> @@ -15031,13 +15027,95 @@ <title id="title-error-message-adding">Adding New Error Messages to MySQL</title> <para> - To add new error messages, use the following procedure: + The procedure for adding error messages depends on which version + of MySQL you are using: + </para> + + <itemizedlist> + + <listitem> + <para> + Before MySQL 5.0.3, error messages are stored in + <filename>errmsg.txt</filename> files in the language + directories under <filename>sql/share</filename>. That is, + the files have names like + <filename>czech/errmsg.txt</filename>, + <filename>danish/errmsg.txt</filename>, and so forth, and + each one is language-specific. Each of these + language-specific files must contain a line for each error + message, so adding a new message involves adding a line to + the <filename>errmsg.txt</filename> file for every language. + The procedure involves adding the English message to the + <filename>english/errmsg.txt</filename> file and running a + script that adds the message to the other language-specific + files. Translators may translate the message in other + <filename>errmsg.txt</filename> files later. + </para> + </listitem> + + <listitem> + <para> + Beginning with MySQL 5.0.3, error messages are stored in a + single <filename>errmsg.txt</filename> file in the + <filename>sql/share</filename> directory, and it contains + the error messages for all languages. The messages are + grouped by error symbol. For each symbol, there must be an + English message, and messages can be present for other + languages as well. If there is no message for a given + language, the English version is used. + </para> + </listitem> + + </itemizedlist> + + <para> + For all versions, the <command>comp_err</command> program + compiles the text error message file or files into + language-specific <filename>errmsg.sys</filename> files that + each are located in the appropriate language directory under + <filename>sql/share</filename>. In MySQL 5.0.3 and up, + <command>comp_err</command> also generates a number of header + files in the <filename>include</filename> directory. The MySQL + build process runs <command>comp_err</command> automatically. + </para> + + <para> + <emphasis role="bold">Note</emphasis>: You should observe some + general considerations regarding error messages that apply no + matter your version of MySQL: </para> <itemizedlist> <listitem> <para> + The maximum error message length is + <literal>MYSQL_ERRMSG_SIZE</literal> = 512. Ensure by using + constructs such as <literal>"%s-.64s"</literal> that there + are no buffer overflows! + </para> + </listitem> + + <listitem> + <para> + You should <emphasis>never</emphasis> new add parameters + (such as %s) to existing error messages. Error messages are + always supposed to be backward compatible. If a parameter is + added, older servers will crash. + </para> + </listitem> + + </itemizedlist> + + <para> + For versions of MySQL older than 5.0.3, use the following + procedure to add new error messages: + </para> + + <orderedlist> + + <listitem> + <para> Open the file <filename>sql/share/english/errmsg.txt</filename> in an editor. @@ -15047,18 +15125,20 @@ <listitem> <para> Add new error messages at the end of this file. Each message - should be on a separate line, it should be quoted within - double quote ('<literal>"</literal>') characters and should - end with a '<literal>,</literal>' following the second + should be on a separate line, and it must be quoted within + double quote ('<literal>"</literal>') characters. By + convention, every message line except the last should end + with a comma ('<literal>,</literal>') following the second double quote. </para> </listitem> <listitem> <para> - For each new error message, add a define to the file - <filename>include/mysqld_error.h</filename> before the last - line (<literal>#define ER_ERROR_MESSAGES</literal>). + For each new error message, add a <literal>#define</literal> + line to the <filename>include/mysqld_error.h</filename> file + before the last line (<literal>#define + ER_ERROR_MESSAGES</literal>). </para> </listitem> @@ -15072,10 +15152,10 @@ <listitem> <para> Add the defined error symbols to - <filename>include/sql_state.h</filename>. It contains the - SQL states for the error messages. If the new errors don't - have SQL states, add a comment instead. Note that this file - must be kept sorted according to the value of the error + <filename>include/sql_state.h</filename>. This file contains + the SQL states for the error messages. If the new errors + don't have SQL states, add a comment instead. Note that this + file must be kept sorted according to the value of the error number. That is, although the <filename>sql_state.h</filename> file might not contain an entry for every symbol in @@ -15089,8 +15169,9 @@ <listitem> <para> Go to the <filename>sql</filename> directory in a terminal - window and type <literal>./add_errmsg #</literal>. This will - copy the last <literal>#</literal> error messages from + window and type <command>./add_errmsg + <replaceable>N</replaceable></command>. This will copy the + last <replaceable>N</replaceable> error messages from <filename>share/english.txt</filename> to all the other language files in <filename>share/</filename>. </para> @@ -15098,34 +15179,240 @@ <listitem> <para> - Translate the error message in the languages you know by - editing the files - <literal>share/XXXXXX/errmsg.txt</literal>. + Translate the error message for those languages that you + know by editing the files + <filename>share/<replaceable>language</replaceable>/errmsg.txt</filename>. </para> </listitem> <listitem> <para> - Make a full build <literal>(configure + make)</literal>. A - <literal>make all</literal> is insufficient to build - <filename>sql/share/*/errmsg.sys</filename>. + Make a full build (<command>configure</command> + + <command>make</command>). A <command>make all</command> is + insufficient to build the + <filename>sql/share/*/errmsg.sys</filename> files. </para> </listitem> - </itemizedlist> + </orderedlist> + + <para> + For MySQL 5.0.3 and up, the procedure for adding error messages + is less tedious. You need edit only a single message text file, + and it's not necessary to edit <filename>*.h</filename> header + files. Instead, <command>comp_err</command> generates the header + files for you based on the contents of the message text file. + </para> + + <para> + The <filename>errmsg.txt</filename> 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 an <filename>errmsg.txt</filename> file. + (The <literal>languages</literal> line is wrapped here; it must + be given all on one line.) + </para> + +<programlisting> +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" + ... +</programlisting> + + <para> + Indentation is significant. Unless otherwise specified, leading + whitespace should not be used. + </para> + + <para> + The <quote>grammar</quote> of the + <filename>errmsg.txt</filename> file looks like this: + </para> + +<programlisting> +languages <replaceable>langspec</replaceable> [, <replaceable>langspec</replaceable>] ... ; + +start-error-number <replaceable>number</replaceable> + +default-language <replaceable>langcode</replaceable> + +<replaceable>error-message-section</replaceable> +<replaceable>error-message-section</replaceable> +... +</programlisting> + + <para> + The <literal>languages</literal> line lists the languages for + which language-specific <filename>errmsg.sys</filename> files + should be generated. A language specification + <replaceable>langspec</replaceable> in the + <literal>languages</literal> line has this syntax: + </para> + +<programlisting> +<replaceable>langspec</replaceable>: <replaceable>langname</replaceable>=<replaceable>langcode</replaceable> <replaceable>langcharset</replaceable> +</programlisting> + + <para> + <replaceable>langname</replaceable> is the long language name, + <replaceable>langcode</replaceable> is the short language code, + and <replaceable>langcharset</replaceable> is the character set + to use for error messages in the language. + </para> + + <para> + The <literal>default-language</literal> 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.) + </para> + + <para> + The <literal>start-error-number</literal> line indicates the + number to be assigned to the first error message. Messages that + follow the first one are numbered consecutively from this value. + </para> + + <para> + Each <replaceable>error-message-section</replaceable> 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 <literal>ER_</literal> for an error or + <literal>WARN_</literal> 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 ('<literal>"</literal>') 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 + <literal>ER_BAD_FIELD_ERROR</literal> symbol: + </para> + +<programlisting> +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" +</programlisting> <para> - The maximum error message length is - <literal>MYSQL_ERRMSG_SIZE</literal> = 512. Ensure by using - constructs such as <literal>"%s-.64s"</literal> that there are - no buffer overflows! + In the preceding example, two SQLSTATE values are given + following the error symbol (<literal>42S22</literal>, + <literal>S0022</literal>). Internally (in + <filename>sql/sql_state.c</filename>), these are known as + <literal>odbc_state</literal> and <literal>jdbc_state</literal>. + Currently, only the first appears ever to be used. </para> <para> - <emphasis role="bold">Note</emphasis>: you should NEVER add - parameters (such as %s) to existing error messages. Error - messages are always backward compatible, and if a parameter is - added, older servers will crash. + A line beginning with a '<literal>#</literal>' character is + taken as a comment. Comments and blank lines are ignored. + </para> + + <para> + Use the following procedure to add new error messages: + </para> + + <orderedlist> + + <listitem> + <para> + 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: + </para> + + <para> + Before: + </para> + +<programlisting> +ER_UNKNOWN_COLLATION + eng "Unknown collation: '%-.64s'" + ger "Unbekannte Kollation: '%-.64s'" + por "Collation desconhecida: '%-.64s'" +</programlisting> + + <para> + After (with a new Spanish translation): + </para> + +<programlisting> +ER_UNKNOWN_COLLATION + eng "Unknown collation: '%-.64s'" + ger "Unbekannte Kollation: '%-.64s'" + por "Collation desconhecida: '%-.64s'" + spa "Collation desconocida: '%-.64s'" +</programlisting> + </listitem> + + <listitem> + <para> + To add an entirely new error message, go to the end of the + <filename>errmsg.txt</filename> 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. + </para> + </listitem> + + <listitem> + <para> + Make a full build (<command>configure</command> + + <command>make</command>). A <command>make all</command> is + insufficient to build the + <filename>sql/share/*/errmsg.sys</filename> files. + </para> + + <para> + <command>comp_err</command> will generate the + <filename>errmsg.sys</filename> files, as well as the header + files <filename>mysqld_error.h</filename>, + <filename>mysqld_ername.h</filename>, and + <filename>sql_state.h</filename> in the + <filename>include</filename> directory. + </para> + </listitem> + + </orderedlist> + + <para> + Be aware that if you make a mistake editing a message text file, + <command>comp_err</command> 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: <filename>errmsg.txt</filename> tends to + grow by gradual accretion, so if an error occurs when + <command>comp_err</command> processes it, the problem is likely + due to whatever change you just made. </para> </section> @@ -15197,8 +15484,8 @@ <para> Thus the <literal>handler::get_error_message</literal> is called and you can return the handler-specific error - message, which either is a static error message that you - retrive from an error/string array, or a a dynamic one that + message, which is either a static error message that you + retrieve from an error/string array, or a a dynamic one that you format when the error occurs. </para> </listitem> @@ -20910,7 +21197,7 @@ --------- -------------------- ------ ------------------- sync0sync.c Synchronization / 37,940 Mutex, the basic sync primitive sync0arr.c ... / array 26,455 Wait array used in primitives - sync0rw.c ... / read-write 22,846 read-write lock for thread sync + sync0rw.c ... / read-write 22,846 read-write lock for thread sync </programlisting> <para> @@ -21025,7 +21312,7 @@ <para> One user can have multiple sessions (the session being all the - things that happen betweeen a connect and disconnect). This is + things that happen between a connect and disconnect). This is where <literal>InnoDB</literal> used to track session IDs, and server/client messaging. It's another of those items which is usually MySQL's job, though. So now usr0sess.c merely closes.
| Thread | ||
|---|---|---|
| • bk commit - mysqldoc@docsrva tree (paul:1.3525) | paul | 10 Sep |
© 1995-2008 MySQL AB, 2008-2009 Sun Microsystems, Inc.
Page generated in 0.659 sec. using MySQL 5.1.14-beta-log