MC文件格式定义

MC文件的格式描述如下：

1.消息源文件语法
keyword=value
等号附近的空格符号是不计的,value被空格(包括回车)与下一个keyword=value界定。
value部分可能是
使用c/c++语法的数字常量;
也可以是一个被c/c++识别的符号名字;
也可以是一个小于等于8个字符的文件名称,不带句话。
2.消息源文件的注释
消息源文件中可以有注释行.在一行的最后一个分句是一个注释行的开始.
注释语句在生成的c/c++include中方法中转化为//开头的注释行。
3.头段
一个消息文本文件包含一个头，它在定义名字和语言识别.一个头包括0个或多个下面的声明
MessageIdTypedef = [type]
SeverityNames = (name=number[:name])
FacilityNames = (name=number[:name])
LanguageNames = (name=number:filename)
OutputBase = {number}
关健字的解释如下：

MessageIdTypedef = type
Gives a typedef name that is used in a type cast for each message code in the generated include file. Each message code appears in the include file with the format:
#define name ((type) 0xnnnnnnnn)

The default value for type is empty, and no type cast is generated. It is the programmer's responsibility to specify a typedef statement in the application source code to define the type. The type used in the typedef must be large enough to accommodate the entire 32-bit message code.

SeverityNames = (name=number[:name])
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 parentheses. Associated with each severity name is a number that, when shifted left by 30, gives the bit pattern to logical-OR with the Facility value and MessageId value to form 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 = (name=number[:name])
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 parentheses. Associated with each facility name is a number that, when shifted left by 16 bits, gives the bit pattern to logical-OR with the Severity value and MessageId value to form 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 codes are reserved for use by the system software. The facility codes can be given symbolic names by following each value with :name

LanguageNames = (name=number:filename)
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 parentheses. Associated with each language name are a number and a file name that are used to name the generated resource file that contains the messages for that language. The number corresponds to the language identifier to use in the resource table. The number is separated from the file name by a colon.
The initial value of LanguageNames is:

LanguageNames=(English=1:MSG00001)
 
Any new names in the source file which don't override the built-in names are added to the list of valid languages. This allows an application to support private languages with descriptive names. For example, use the following syntax in the .MC file to support messages in both English and Japanese:

LanguageNames=(English=0x409:MSG00409)
LanguageNames=(Japanese=0x411:MSG00411)

MessageId=0x1
Severity=Error
Facility=Runtime
SymbolicName=MSG_BAD_COMMAND
Language=English
You have chosen an incorrect command.

Language=Japanese
òsé|é+aRa}a?ahé??I?=é|éOé_é|é+.

OutputBase = {number}
Sets the output radix for the message constants output to the C/C++ include file. It does not set the radix for the Severity and Facility constants; these default to HEX, but can be output in decimal by using the -d switch. If present, OutputBase overrides the -d switch for message constants in the include file.
The legal values for number are 10 and 16.

You can use OutputBase in both the header section and the message definition section of the input file. You can change OutputBase as often as you like.

4.消息定义
Message Definitions
Following the header section is the body of the message compiler source file. The body consists of zero or more message definitions. Each message definition begins with one or more of the following statements.

MessageId = [number|+number]
Severity = severity_name
Facility = facility_name
SymbolicName = name
OutputBase = {number}

The MessageId statement marks the beginning of the message definition. A MessageID statement is required for each message, although the value is optional. If no value is specified, the value used is the previous value for the facility plus one. If the value is specified as +number then the value used is the previous value for the facility, plus the number after the plus sign. Otherwise, if a numeric value is given, that value is used. Any MessageId value that does not fit in 16 bits is an error.

The Severity and Facility statements are optional. These statements specify additional bits to OR into the final 32-bit message code. If not specified they default to the value last specified for a message definition. The initial values prior to processing the first message definition are:

Severity=Success
Facility=Application
 
The value associated with Severity and Facility must match one of the names given in the FacilityNames and SeverityNames statements in the header section.

The SymbolicName statement allows you to associate a C/C++ symbolic constant with the final 32-bit message code.

The constant definition in the generated include file has the format:

//
// message text
//

#define name ((type) 0xnnnnnnnn)

The comment before the definition is a copy of the message text for the first language specified in the message definition. The name is the value given in the SymbolicName statement. The type is the type name specified in the MessageIdTypedef statement. If no type was specified, the cast is not generated.

The following comment appears in each header file to explain the bit fields in the 32-bit message:

//  Values are 32 bit values laid out as follows:
//
//   3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1
//   1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
//  +---+-+-+-----------------------+-------------------------------+
//  |Sev|C|R|     Facility          |               Code            |
//  +---+-+-+-----------------------+-------------------------------+
//
 
The meanings of the fields in the message code are:

Sev
The severity code: Bits Meaning
00 Success
01 Informational
10 Warning
11 Error

C
The Customer code flag.
R
A reserved bit.
Facility
The facility code.
Code
The status code for the facility.
The OutputBase statement lets you set the output radix for the message constants output to the C/C++ include file. It does not set the radix for the Severity and Facility constants; these default to HEX, but can be output in decimal by using the -d switch. If present, OutputBase overrides the -d switch for message constants in the include file.

The legal values for number are 10 and 16

You can use OutputBase in both the header section and the message definition section of the input file. You can change OutputBase as often as you like.

 

5.语言特定消息文本定义(Lanuage-Specific Message Text Definitions)
After the message definition statements, you specify one or more message text definitions.

Syntax
Language=language_name
messagetext
.

Each message begins with a Language statement that identifies the binary output file for this message. The first line of the message text begins with the next line. 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 are allowed around the terminating period. Within the message, blank lines and white space are preserved as part of the message.

You can specify several escape sequences for formatting the message when the message text is used by the application or an event viewer. The percent sign character (%) begins all escape sequences.

%0
Terminates a message text line without a trailing newline. This can be used to build up long lines or to terminate the message without a trailing newline, which is useful for prompt messages.
%n[!printf-format-specifier!]
Identifies an insert. Each insert refers to a parameter used in a call to theFormatMessage function. FormatMessage returns an error if the message text specifies an insert that was not passed to FormatMessage.
The value of n can be between 1 and 99. The printf format specifier must be enclosed in exclamation marks. It is optional and defaults to !s! if not specified.

The printf format specifier can contain the * specifier for either the precision or width components. When specified, they consume inserts numbered n+1 and n+2 for their values at run time. MC prints a warning message if these inserts are specified elsewhere in the message text.

Any character following a percent sign other than a digit is formatted in the output message without the percent sign.

You can specify the following additional escape sequences:

%%
Generates a single percent sign in the formatted message text.
%\
Generates a hard line break when it occurs at the end of a line. Useful whenFormatMessage is supplying normal line breaks so the message fits in a certain width.
%r
Generates a hard carriage return, without a trailing newline character.
%b
Generates a space character in the formatted message text. This can be used to ensure there are the appropriate number of trailing spaces in a message text line.
%.
Generates a single period in the formatted message text. This can be used to get a period at the beginning of a line without terminating the message definition.
%!
Generates a single exclamation point in the formatted message text. This can be used to specify an exclamation point immediately after an insert.

6.MC使用(The MC command Line)
The message compiler has the following command-line syntax:

Syntax
MC [-v] [-w] [-s] [-d] [-h dir] [-e extension] [-r dir] filename[.mc]

Parameters
-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 the OS/2 MKMSGF utility. These are any escape sequences other than %0 and %n. This option is useful for converting MKMSGF message files to MC format.
-s
Adds an extra line to the beginning of each message that is the symbolic name associated with the message identifier.
-d
Outputs Severity and Facility constants in decimal. Sets the initial output radix for messages to decimal.
-h dirs
Specifies the target directory of the generated include file. The include-file name is the base name of the .MC file with a .H extension.
-e extension
Specifies the extension for the header file, which can be from one to three characters. The default is .H.
-r dir
Specifies the target directory of the generated Resource Compiler script (.RC file). The script file name is the base name of the .MC file with a .RC extension.
filename[.MC]
Specifies an input message file that is compiled into one or more binary resource files, one for each language specified in the message file.
The message compiler reads the message file and generates a C/C++ include file containing definitions for the symbolic names. For each LanguageId statement, the message compiler generates a binary file containing a message table resource. It also generates a single resource script file that contains the appropriate resource compiler statements to include each binary output file as a resource with the appropriate symbolic name and language type.