WL#13423: Split errmgs-utf8.txt into one file for messages to clients and another for messages to the error log
Affects: Server-8.0 — Status: Complete
The file errmsg-utf8.txt contains error messages: a) messages from the server to clients (error code < 10,000) b) messages for the error log Within both of those two major groups, there exist various sub-ranges (e.g. one per major server version, so that when a message has to be backported, it can be added at the end of that version's range where we have some unused indices without which inserting that message would renumber all that follow it). Additionally, ranges can be reserved for special use. Finally, each error-code can have multiple translations of the same message. This complexity makes it non-obvious where to add new messages, how to backport messages, and so on. A FAQ has recently been added to the message file to cover the most common and the most difficult cases, and to highlight the fact that there is something to know in the first place where this may not be obvious to the casual users (that is to say, engineers not primarily concerned with the workings of the error subsystems). Splitting the message file in two for the major groups a) and b) as per above and using obvious nomenclature for the new file should further aid in this goal, and let us simplify the included instructions.
NFR-1 Splitting errmsg-utf8.txt The error messages will be migrated to two new files, one file for the messages intended for the error log, and another for the messages intended for sending to clients. This is a one time process the results of which will be committed to the repository. NFR-1.1 File names The file name errmsg-utf8.txt shall not be used for either new input file, nor shall it be used for any intermediate files. This will make it harder for engineers to add messages to the wrong files just because its name looks familiar. It will also highlight the fact that a change has happened and investigation is in order. NFR-1.1.1 File location The new files shall located in the same source directory as errmsg-utf8.txt previously was in order to make them findable. NFR-1.1.2 Mesages from the server to clients Message from the server to the client shall be collected in the new file, messages_to_clients.txt. This somewhat elaborate name was chosen over shorter alternatives such as "client_messages.txt" to clearly distinguish these messages from those built into the client-library (libmysql/C-API). NFR-1.1.3 Messages from the server to the error log Messages written by the server to the error log shall be collected in the new file, messages_to_error_log.txt. NFR-1.1.4 Developer information and FAQ The list of Frequently Asked Questions about error messages (and their answers) will be moved from errmsg-utf8.txt to errmsg_readme.txt. The similarity in name is intentional so that an engineer trying to tab-complete the old name is greeted with an explanation detailing what has changed, and how the process now works. NFR-1.1.5 Other files The output files (as read by the C++ compilers) shall remain as before in name and equivalent in contents. NFR-1.2 Utilities: comp_err The utility, comp_err, that at build time creates the errmsg.sys files the server reads at run time must be updated. NFR-1.2.1 Command-line options comp_err must accept the messages previously in errmsg-utf8.txt from multiple files, and support command-line options to specify these files. --in_file_toclient specifies the file containing messages the MySQL server sends to its clients. --in_file_errlog specifies the file containing the messages intended for the error log. NFR-1.2.2 Processing order Regardless of the order of the command-line options, the server-to-client messages are processed before server-to-errorlog messages. NFR-1.2.3 Sanity check of input 220.127.116.11 The languages directive must be used exactly once, at the top of the server-to-client messages. Using the language directive multiple times will abort translation. 18.104.22.168 The default-language directive should be used exactly once, at the top of the server-to-client messages. Its value must be "eng" until such a time that any other language achieves full coverage (that is, has a message in that language for each error symbol). 22.214.171.124 A message may not contain a short language code (such as "eng") that was not previously assigned in the languages directive. This is intended to aid in identifying potential typos, or cases of different engineers using different abbreviations for the same language). 126.96.36.199 The utility defaults to an offset of 1,000 for the server-to-clients messages, and an offset of 10,000 for the server-to-errorlog messages. Setting the default values explicitly at the top of the respective files is accepted, but not required. Setting values other (that is, greater) than the defaults is accepted. 188.8.131.52 Using the start-error-number directive to set the offset to its current value will abort translation, except where in 184.108.40.206, as this use is assumed to be unintentional. 220.127.116.11 Using the start-error-number directive to set an offset smaller than the current one will abort translation. NFR-1.3 Update the build process for the new layout The build process must be updated so that comp_err is called with the new options and new files from CMakeLists.txt.
I-1 Semantics NO CHANGE I-2 Instrumentation NO CHANGE I-3 Error and Warnings NO CHANGE [ERR01] messages will be migrated to two new files, but the messages themselves, their format, or their numbers will be unaffected. No change should be observable on a production server. I-4 Install/Upgrade NO CHANGE I-5 Commercial plugins NO CHANGE. I-6 Replication NO CHANGE I-7 XProtocols NO CHANGE I-8 Protocols NO CHANGE I-9 Security NO CHANGE I-10 Log Files NO CHANGE The messages will be migrated to two new files, but the messages themselves, their format, or their numbers will be unaffected. [LOGxx] files on production servers should show no observable differences. I-11 MySQL clients NO CHANGE I-12 Auth plugins NO CHANGE I-13 Globalization NO CHANGE I-14 Configuration NO CHANGE I-15 File formats NO CHANGE I-16 Plugins/APIs NO CHANGE I-17 Other programs YES - however, these programs are not classed as [MISCxx] tools. The error messages will be migrated to two new files, one file for the messages intended for the error log, and another for the messages intended for sending to clients. This must be reflected in the build utilities, comp_err. The Docs Team should also take note and adjust their tools as needed. NO CHANGE I-18 Storage engines NO CHANGE I-19 Data types NO CHANGE
Copyright (c) 2000, 2020, Oracle Corporation and/or its affiliates. All rights reserved.