#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


