Message Text Files

Messages are defined in a message text file. The message compiler assigns numbers to each message, and generates a C/C++ include file which the application can use to access a message using a symbolic constant.

The general syntax for statements in a message text file is as follows:

keyword=value

Spaces around the equal sign are ignored, and the value is delimited by white space (including line breaks) from the next keyword/value pair. Case is ignored when comparing against keyword names. The value portion can be a numeric integer constant using C/C++ syntax, a symbol name that follows the rules for C/C++ identifiers, or a file name with 8 characters or fewer, with no periods.

For an example message file, see Sample Message Text File.

Comments

Comment lines are allowed in the message text file. A semicolon (;) begins a comment that ends at the end of the line. Follow the semicolon with a C/C++ single-line comment indicator (//) so that the header file generated by the message compiler will compile in your application.

;// This is a single-line comment.

For a block comment, begin each line with a semicolon, then place a C/C++ open block comment indicator (/*) after the semicolon on the first line and the close block comment indicator (*/) after the semicolon on the last line.

;/* This is a block comment.
;   It spans multiple lines.
;*/

Header Section

The message text file contains a header that defines names and language identifiers for use by the message definitions in the body of the file. The header contains zero or more of the following statements.

Statement syntax	Description
MessageIdTypedef=type	Type to be used in the message definition as follows: #define name ((type)0xnnnnnnnn) The type must be large enough to accommodate the entire message code, such as a DWORD. The type can also be a type defined in the application source code. The default value for type is empty, so no type cast is used. This statement can be specified in the header and as often as necessary in the message definition section.
SeverityNames=(name=number[:name])	Set of names that are allowed for the severity in a message definition. Associated with each severity name is a number that, when shifted left by 30 bits, gives the bit pattern to logical-OR with the facility and message ID values to form the message code. Any severity value that does not fit in 2 bits is an error. The severity codes can be given symbolic names as well.The default value is defined as follows: SeverityNames=( Success=0x0 Informational=0x1 Warning=0x2 Error=0x3)
FacilityNames=(name=number[:name])	Set of names that are allowed for the facility values in a message definition. 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 and message ID values to form the message code. Any facility value that does not fit in 12 bits is an error. This allows for 4096 facility codes; the first 256 codes are reserved for system use. The facility codes can be given symbolic names as well.The default value is defined as follows: FacilityNames=( System=0x0FF Application=0xFFF)
LanguageNames=(name=number:filename)	Set of names that are allowed for the language values in a message definition. The number is used as the language identifier in the resource table. The specified file contains the messages for that language. It is typically a .bin file generated by the message compiler. An example value is: LanguageNames=(English=0x409:MSG00409) For a list of language identifiers, see https://go.microsoft.com/fwlink/p/?linkid=190280.
OutputBase=number	Output radix for the message constants that the message compiler writes to the header file. If present, this value overrides the -d switch. This number can be either 10 (decimal) or 16 (hexadecimal).

Message Definitions

A message text file contains zero or more message definitions following the header section. The following table describes the message-definition statements. The MessageId statement marks the beginning of the message definition. The Severity and Facility statements are optional.

Statement syntax	Description
MessageId=[number|+number]	Identifier for the message. This statement is required, 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 with a plus sign, the value used is the previous value for the facility, plus the number after the plus sign. Any value specified must fit in 16 bits.For more details on how the message value is formed from the severity, facility, and message ID, see the diagram in Winerror.h. This header file defines error codes for the system.
Severity=name	One of the values specified by SeverityNames in the header. This statement is optional. If no value is specified, the value used is the value last specified for a message definition. The default for the first message definition is Severity=Success
Facility=name	One of the values specified by FacilityNames in the header. This statement is optional. If no value is specified, the value used is the value last specified for a message definition. The default for the first message definition is Facility=Application
SymbolicName=name	Associates a C/C++ symbolic constant with the message code. It is used in the message definition as follows: #define name ((type)0xnnnnnnnn)
OutputBase={number}	Output radix for the message constants the message compiler writes to the header file. If present, this value overrides the -d switch. This number can be either 10 (decimal) or 16 (hexadecimal).
Language=name	One of the values specified by LanguageNames in the header. This statement is optional. If no value is specified, the value used is the value last specified for a message definition. The default for the first message definition is as follows: Language=English
message text	Text for the message. It is included in the message binary file. It is also included in the header file in the comment block that directly precedes the message definition.
.	Message text is terminated by a new line containing a single period at the beginning of the line.

If the message definition includes message text for more than one language, each language requires its own Language statement, message text, and terminating new line with a period. For example:

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

Language=Japanese
<Japanese message string goes here>
.

You can specify the following escape sequences for formatting message text for use by the event viewer or your application. The percent sign character (%) begins all escape sequences. Any other character following a percent sign is displayed without the percent sign.

%n[!format_specifier!]

Describes an insert. Each insert is an entry in the Arguments array in the FormatMessage function. The value of n can be a number between 1 and 99. The format specifier is optional. If no value is specified, the default is !s!. For information about the format specifier, see wsprintf.

The format specifier can use * for either the precision or the width. When specified, they consume inserts numbered n+1 and n+2.

%0

Terminates a message text line without a trailing newline character. This can be used to build a long line or terminate a prompt message without a trailing newline character.

%.

Generates a single period. This can be used to display a period at the beginning of a line, which would otherwise terminate the message text.

%!

Generates a single exclamation point. This can be used to specify an exclamation point immediately after an insert.

%%

Generates a single percent sign.

%n

Generates a hard line break when it occurs at the end of a line. This can be used with FormatMessage to ensure that the message fits a certain width.

%b

Generates a space character. This can be used to ensure an appropriate number of trailing spaces on a line.

%r

Generates a hard carriage return without a trailing newline character.