FormatMessage API call is very powerful, and particularly useful for issuing all kinds of messages. This is not intended to be a full tutorial on using
FormatMessage, but simply an example of one of the most effective uses of the the call. There is nothing more offensive than being presented with a message like the one below:
This is incomprehensible. The file cannot be opened. Why? For that matter, what file? The name the user types in is only part of the filename context; the rest relies on the current directory, which may not be what the user thinks it is. Errors like this generate unnecessary support calls to tech support departments, and consume a lot of time of the technical support people trying to determine what has gone wrong. A much
better example of an error message is the next one. It tells what the application-level error is, what file was being considered, and the description of the error code.
In this case, I had created a read-only file junk.txt to induce the error on a
To make this work, I use the
FormatMessage call. I then convert the value to a
CString. If no error message is found, I handle the error by formatting the message with a particular string, which is stored in the
Unknown error 0x%08x (%d)
You will have to add this
STRINGTABLE entry to your application. The string number doesn't matter. At the call site, you can do something like
if(!f.Open(dlg.GetPathName(), CFile::modeWrite | CFile::modeCreate))
DWORD err = ::GetLastError();
CString errmsg = ErrorString(err);
s.Format(fmt, dlg.GetPathName(), errmsg);
The message formatting string is stored as a resource in the
STRINGTABLE. This allows for internationalization.
File Open failed\n%s\n%s
One of the peculiar features of
FormatMessage, which makes absolutely no sense at all, is that it appends a newline sequence to the message. This is rarely, if ever, of value, and as far as I can tell, having worked in three other major operating systems that supported a
FormatMessage equivalent, this seems to arise from some fundamental misunderstanding of the problem. In every single one of these systems, dating back to 1968, I have had to eliminate the newline sequence from the error string before it was usable! So I delete this newline sequence from the result of
FormatMessage so the message can be placed in a
CListBox, or other such place and make sense. (The peculiar attitude seems to be that the designer of the error message should control this, when in fact it should either not be appended at all, or be an option flag that defaults to "off" in the call to retrieve the message).
Just for your information, if you want to get the error text while debugging, place in the watch window of the debugger the request
This is a screen snapshot of the watch window taken after the
CStdioFile::Open call failed. As you can see, the error message is nicely explained to you, the programmer. When the error is something that needs to be displayed to the user, you can use my
ErrorString function to get a nice
CString. Note that even if you think the message code is of no use to the user, display it anyway
. For example, a message of the form is actually very useful. Here is a simulated display of an
AfxMessageBox. Your tech support people will be greatly aided.
<TD width=375 bgColor=#0000ff>
<FONT face=Arial size=2>Your Application Name Here</FONT>
<TD width=375 bgColor=#c0c0c0>Unable to complete operation. Internal error.
Unexpected error code from network support.
( An attempt was made to establish a session to a network server, but there are already too many sessions established to that server).
Perhaps you did not expect this error and don't really know what to do when it occurs, but your tech support people could waste hours trying to track down a problem that is not really in your program, but an artifact of an overloaded server.
Here is the code of the function in its entirety: The download consists of a compilable
.cpp file and the accompanying
CString ErrorString(DWORD err)
NULL) == 0)
t.Format(fmt, err, LOWORD(err));
Error = t;
LPTSTR p = _tcschr(s, _T('\r'));
if(p != NULL)
*p = _T('\0');
Error = s;