#F mc.txt v1 #K text #O addfile #P 1.00 #T Wed Jan 05 14:37:09 1994 #A BryanT3 #C Unicode from Floyd\Diane #I 1 #D 20623 0a1,407 > This document describes how messages will be input, stored and formatted > by a Win32 application. > > 1. Message Input > > Messages are input as ASCII text in a text file. The format of this > file supports specifying multiple versions of the same message text, > one for each language supported. It also supports automatic assignment > of code numbers to each message, along with the generation of a C > language include file for use by the application for accessing the > messages using symbolic constants. The purpose of the message text > file is to define all of the messages needed by an application, in a > format that makes it easy to support multiple languages with the same > image file. > > Message text files are converted into binary resource files by the > MC program. These binary resource files are then input to the RC > compiler which will put them in the resource table for an > application or DLL. > > The format of the message text file (default extension is .mc). > Basic syntax is Keyword=Value, where spaces around the equal sign > are ignored, and the value is delimited by white space from the next > keyword=value pair. Case is ignored when comparing against keyword > names. The value portion can either be a numeric integer constant, > {NUMBER}, using C syntax; a symbol name, {NAME}, that follows the > rules for C identifier names; or a file name that follows the > rules for the FAT file system (8 characters or less, no periods). > > Comment lines are allowed in the message text file. The comment > syntax is the same as for WIN.INI, namely a semicolon begins a > comment which is terminated by the end of the line. Comments that > exist by themselves on a line are copied as is to the output .h > file, with the semicolon converted to the C end of line comment > syntax (//). > > The overall structure of a message text file consists of a header > section which contains zero or more of the following keywords: > > MessageIdTypedef={NAME} > SeverityNames=({NAME}={NUMBER}:{NAME}) > FacilityNames=({NAME}={NUMBER}:{NAME}) > LanguageNames=({NAME}={NUMBER}:{FILENAME}) > > These keywords have the following meaning: > > MessageIdTypedef - gives a symbolic name that is output as the > typedef name for each numeric MessageId value. The default > value for this is NULL, which means there will be no type > cast output when defining symbolic names for a MessageId. > > SeverityNames - defines the set of names that are allowed as the > value of the Severity keyword in the message definition. > The set is delimited by left and right parenthesis. > Associated with each severity name is a number that, when > shifted left by 30, gives the bit pattern to logically OR > with the Facility value and MessageId to come up with the > full 32-bit message code. The default value of this keyword > is: > > SeverityNames=(Success=0x0 > Informational=0x1 > Warning=0x2 > Error=0x3 > ) > > Severity values occupy the high two bits of a 32-bit message > code. Any severity value that does not fit in two bits is > an error. The severity codes can be given symbolic names > by following each value with :{NAME} > > FacilityNames - defines the set of names that are allowed as the > value of the Facility keyword in the message definition. > The set is delimited by left and right parenthesis. > Associated with each facility name is a number that, when > shift it left by 16 bits, gives the bit pattern to logically > OR with the Severity value and MessageId to come up with the > full 32-bit message code. The default value of this keyword > is: > > FacilityNames=(System=0x0FF > Application=0xFFF > ) > > > Facility codes occupy the low order 12 bits of the high > order 16-bits of a 32-bit message code. Any facility code > that does not fit in 12 bits is an error. This allows for > 4096 facility codes. The first 256 are reserved for > use by the system software. > > The facility codes can be given symbolic names by following > each value with :{NAME} > > LanguageNames - defines the set of names that are allowed as the > value of the Language keyword in the message definition. > The set is delimited by left and right parenthesis. > Associated with each language name is a number and a file > name that will be used to name the binary output file that > will contain all of the message text for that language. The > number corresponds to the Language Id tag to use in the > resource table. The number is separate from the file name > with a colon. The initial value of this keyword is: > > LanguageNames=(English=1:MSG00001) > > Any new names that an application defines in its .mc file > which don't override any of the builtin names will be added > to the list of valid languages. This allows an application > to support private languages with descriptive names. > > Following the header section are zero or more message definitions. > Each message definition begins with one or more of the following > keywords. > > MessageId={|{NUMBER}|+{NUMBER}} > Severity={SEVERITY_NAME} > Facility={FACILITY_NAME} > SymbolicName={NAME} > > The MessageId keyword is required to mark the beginning of the > message definition, although its value is optional. If no value is > specified, then the value used will be the last value used for the > facility, plus one. If the value is specified as +{NUMBER} then > the value used will be the last value used for the facility, plus > the number after the plus sign. Otherwise if a numeric value is > given, that will be value used. Any MessageId value that does not > fit in 16 bits is an error. > > Severity and Facility are optional keywords that can specify > additional bits to OR into the final 32-bit message code. If either > of these are not specified they default to the value last specified > for a message definition. The initial values of these prior to > processing the first message definition is: > > Severity=Success > Facility=Application > > The value associated with these keywords must match one of the names > given to the FacilityNames and SeverityNames keywords. The SymbolicName > keyword allows the ISV to associate a C symbolic constant name with the > final 32-bit message code that is a result of ORing together the > MessageId, Severity and Facility bits. The constant definition is > output to the generated .h file with the following format: > > // > // {MESSAGETEXT} > // > > #define CONSTANT_SYMBOL_NAME ((MessageIdTypedef) 0x12345678) > > where the comment before the definition is a copy of the message > text for the first language specified in the message definition. > The CONSTANT_SYMBOL_NAME is the value of the SymbolicName keyword. > The MessageIdTypedef is not output if it is NULL, the default value. > > After the message definition keywords, comes one or more message text > definitions. Each message text definition begins with the Language > keyword that identifies which binary output file this message text > is to be output to. Beginning on the very next line is the first > line of the message text. The message text is terminated by a line > containing a single period at the beginning of the line, immediately > followed by a new line. No spaces allowed around keyword. Within > the message text, blank lines and white space are preserved as part > of the message. > > Language={LANGUAGE_NAME} > {MESSAGETEXT} > . > > Within the message text, several escape sequences are supported for > dynamically formatting the message. The percent sign character (%) > begins all escape sequences. > > > %0 - This terminates a message text line without a trailing > newline. This can be used to build up long lines or to > terminate the message itself without a trailing newline, > which is useful for prompt messages. > > %n!printf format string! - This identifies an insert. The > value of n can be between 1 and 99. The printf format > string must be bracketed by exclamation marks. It is > optional and defaults to !s! if not specified. > > The printf format string can contain the * specifier for > either the precision or width components, and if so, they > will consume inserts %n+1 and %n+2 for their values at run > time. MC will print a warning message if an explicit > reference is made to these inserts elsewhere in the message > text. > > Inserts must reference a parameter passed to the FormatMessage API > call. It will return an error if a message refers to an insert that > was not passed to the FormatMessage API call. > > Any other character following a percent sign, other than a digit will > be formatted in the output message without the percent sign. Some > examples: > > %% - will output a single percent sign in the formatted message text. > > %n - will output a hard line break when it occurs at the end of a > a line. Useful when FormatMessage is supplying normal line > breaks so the message fits in a certain width. > > %r - will output a hard carriage return, without a trailing newline. > > %b - will output a space in the formatted message text. This > can be used to insure there are the appropriate number of > trailing spaces in a message text line. > > %t - will output a tab in the formatted message text. > > %. - will output a single period in the formatted message text. > This can be used to get a single period at the beginning of > a line without terminating the message text definition. > > %! - will output a single exclamation point in the formatted > message text. This can be used to get an exclamation point > immediately after an insert without it being mistaken for > the beginning of a printf format string. > > Unicode support is not understood yet. If the input file is ASCII > text, do we need an escape sequence to allow input of Unicode values? > Or do we just let them use DBCS in the text file, assuming they have > a text editor that can do this. > > 2. Message Compiler (MC) > > This program converts .mc message text files into binary files > suitable for inclusion into a .RC file by the resource compiler. > > Command line syntax: > > MC [-v] [-w] [-s] [-h DirSpec] [-r DirSpec] filename[.mc] ... > > where: > > -v - generates verbose output to stderr. > > -w - generates a warning message whenever an insert escape > sequence is seen that is a superset of the type supported > by OS/2 mkmsgf (i.e. anything other than %0 and %n). > Useful for converting old OS/2 message files to this > format. > > -s - Add an extra line to the beginning of each message that is > the symbolic name associated with the message id. > > -h DirSpec - specifies the target directory of the generated > .h file. The file name is the name of the .mc file with a > .h extension. > > -r DirSpec - specifies the target directory of the generated > .rc file. The file name is the name of the .mc file with a > .rc extension. > > filename.mc - specifes one or more input message files that > will be compiled into one or more binary resource > files, one for each language that the message > files contain message text for. > > The message compiler reads the .mc file and generates a .h file > containing all the symbolic name definitions. For each LanguageId > that was used to specify message text, it outputs a binary file > containing a message table resource. It also outputs a single .rc > file that contains the appropriate RC syntax to include each binary > file output as a resource with the appropriate name and type ids. > > 3. Message Win32 API Calls > > DWORD > APIENTRY > FormatMessage( > DWORD dwFlags, > LPVOID lpSource, > DWORD dwMessageId, > DWORD dwLanguageId, > LPSTR lpBuffer, > DWORD nSize, > va_list Arguments > ) > > Routine Description: > > This function formats a message string. Input to this function is a > message definition. It can come from a buffer passed into this > function. It can come from a message table resource in a module > already loaded. Or the caller can ask this function to search the > system message table resource(s) for the message. This function > finds the message definition based on the Message Id and the > Language Id and copies the message text to the output buffer, > processing any imbedded insert sequences if requested. > > Arguments: > > dwFlags - Specifies options to the formatting process along with how > to interpret the lpSource parameter. The low order 16bits of > this parameter are the maximum width of a line, in characters. > Possible values are: > > FORMAT_MESSAGE_ALLOCATE_BUFFER - the lpBuffer is a PVOID * and > nSize is the minimum size to allocate. This function will > then allocate a buffer large enought to hold the formatted > message and store the pointer to the buffer in the location > pointed to by lpBuffer. Caller should free the buffer > with LocalFree when they are done using it. > > FORMAT_MESSAGE_IGNORE_INSERTS - insert sequences in the message > definition will be ignored and passed through to the output > buffer as is. Useful for fetching a message for later > formatting. If this flag is set, the lpArguments parameter > is ignored. > > FORMAT_MESSAGE_FROM_STRING - lpSource is a pointer to a null > terminated message definition. It can contain insert > sequences just as the message text in the .mc file can. > > FORMAT_MESSAGE_FROM_HMODULE - lpSource is a module handle that > contains the message table resource(s) to search. If this > handle is NULL, then the current process's application > image file will be searched. > > FORMAT_MESSAGE_FROM_SYSTEM - If the requested message was not > found in lpSource or if lpSource was not examined (i.e. neither > of the preceeding two flags was specified), then this function > will search the system message table resource(s). > > FORMAT_MESSAGE_ARGUMENT_ARRAY - If set, specifies that the passed > Arguments parameter is NOT a va_list structure but instead is > just a pointer to an array of 32-bit values that represent > the arguments. > > FORMAT_MESSAGE_MAX_WIDTH_MASK - The low order 8 bits specify the > maximum width of each line formatted into the output buffer. > A maximum width of zero, means that no restrictions are > placed on the width, and only the line breaks in the message > definition will be placed in the output buffer. If a non-zero > value is specified, then line breaks in the message definition > text are ignored, and instead line breaks are calculated based > on the maximum width, with white space delimited strings never > being split across a line break. Hard coded line breaks in > the message definition text, that are identified by the %n > escape sequence, are always output to the output buffer. > > If the width specified is FORMAT_MESSAGE_MAX_WIDTH_MASK, then > line breaks in the message file are ignored and only hard coded > line breaks are kept and none are generated. > > lpSource - specifies where to retrieve the message definition from. > The type of this parameter depends upon the settings in the > dwFlags parameter. > > FORMAT_MESSAGE_FROM_HMODULE - lpSource is an hModule of the > module that contains the message table to search. > > FORMAT_MESSAGE_FROM_STRING - lpSource is an LPSTR that points > to unformatted message text. It will be scanned for > inserts and formatted accordingly. > > If neither of these options is specified, then this parameter is > ignored. > > dwMessageId - specifices the 32-bit message identifier that identifies > the message being requested. This parameter is ignored if the > FORMAT_MESSAGE_FROM_STRING flag is specified. > > dwLanguageId - specifices the 32-bit language identifier that > identifies the language of the message being requested. This > parameter is ignored if the FORMAT_MESSAGE_FROM_STRING flag is > specified. > > lpBuffer - specifies a pointer to a buffer where the formatted message > is to be written. A terminating null byte will also be written. > If the FORMAT_MESSAGE_ALLOCATE_BUFFER flag was specified, then > this parameter points to a 32-bit pointer value that is filled in > by this call with a pointer allocated via LocalAlloc to contain > the text of the message. > > nSize - specifies the maximum number of bytes that can be stored in > the output buffer. This parameter is ignore if the > FORMAT_MESSAGE_ALLOCATE_BUFFER flag is set. > > Arguments - specifies a pointer to variable number of arguments. > These arguments are used to satisfy insert requests in the > format string. Thus %1 in the format string specifies the > first argument in the variable number of arguments described > by the Arguments parameter; %3 would specify the third, etc. > > The interpretation of each 32-bit arguments value depends upon > the formatting information associated with the insert in the > message definition. The default is to treat each pointer as a > pointer to a null terminated string. > > By default the Arguments parameter is of type va_list, which is > a language and implementation specific data type for describing > a variable number of arguments. If you do not have a pointer of > type va_list, then specify the FORMAT_MESSAGE_ARGUMENT_ARRAY > flag and pass a pointer to an array of 32-bit values that are > are input to the message formatted as the insert values. > Return Value: > > DwORD - Returns the number of bytes actually stored in the output > buffer, excluding the terminating null character. Returns 0 if > an error occurred. Extended error status is available via the > GetLastError API. #D 20623 1632986 #F mc.txt v1 #K text #O in #P 1.00 #T Mon Jun 13 12:35:49 1994 #A BryanT3 #C Remove incorrect comment #I 2 #D 119 34,35c34 < file, with the semicolon converted to the C end of line comment < syntax (//). --- > file. #D 119 8593 #F mc.txt v2 #K text #O in #P 1.00 #T Wed Jun 15 16:39:38 1994 #A FLOYDRX86 #C 18122 - codepage option #I 3 #D 605 42c42 < LanguageNames=({NAME}={NUMBER}:{FILENAME}) --- > LanguageNames=({NAME}={NUMBER}:{FILENAME}[:{CODEPAGE}]) 110a111,121 > If the message file contains messages for languages that > must be represented in separate codepages, the optional > fourth (4th) parameter may be used to specify the codepage > that the messages for that Language's messages are in. > > LanguageNames=(Japanese=411:MSG00411:932) > > The default codepage used, if the codepage is not explicitly > specified, is the OEM Codepage of the system. > > #D 605 46648 #F mc.txt v3 #K text #O in #P 1.00 #T Thu Aug 11 13:26:51 1994 #A andyh #C add OutputBase and -e switch #I 4 #D 1108 42a43 > OutputBase={NUMBER} 120a122,131 > OutputBase - sets the output radix for the constants output to C > header file for messages. (It does not set the radix for the > SEVERITY and FACILITY constants. These default to HEX and can be > output in decimal using the -d switch.) If present, Outputbase > overwrites the -d switch for message constants in the header file. > Legal values are 10 and 16. > > The OutputBase keyword is legal both in the header section and in the > message definition section of the input file. The OutputBase can be > changed as often as desired. 246c257 < MC [-v] [-w] [-s] [-h DirSpec] [-r DirSpec] filename[.mc] ... --- > MC [-v] [-w] [-s] [-d] [-h DirSpec] [-e extension] [-r DirSpec] filename[.mc] ... 260a272,276 > -d - Output SEVERITY and FACILTY constants in decimal. Set the > initial output radix for messages to decimal. > > -e - Specify the extension for the header file. From 1 - 3 chars. > #D 1108 83748