Rohan Douglas is an associate director of Giltnet Limited and has been an architect of a number of real-time analytic products for the global fixed interest markets including the product Tactician. Rohan can be reached at G.P.O. Box 2424, Sydney, N.S.W. 2001, Australia or by FAX (2)-262-5357 (Australia).
One of the more overlooked problems programmers face during the software development life cycle is error message management. For one thing, a list of error messages must usually be provided in the user manual, along with detailed descriptions. At one stage or another, many of us may have resorted to a combination of grep and our favorite text editor to produce such a list. For larger projects, however, this approach becomes unmanageable.
The purpose of this article is to present an approach which is simple to implement and use. It offers some significant advantages over more traditional approaches to the problem. In particular, this approach automates the error message documentation process, guaranteeing consistency between the product and documentation, and adds the ability to generate error messages in one of several written languages. For that matter, there's no reason this scheme couldn't be adapted for on-screen menus, prompts, and dialog boxes.
An Error Message Data Base
One traditional approach to the problem of error message management is to maintain a separate data base of error messages which are referenced within the source code by calling some function with an identifying index. This approach, however, presents several problems.
For readability, a description of each error must also be included in the source. The problems of maintaining two copies of the same information quickly become apparent. Cross-checking the source against the error message data base is a problem to be avoided.
Maintaining a distinct error message data base is also fairly cumbersome. In the worst case, having come across an error condition while editing source code, we have to exit the source editor to call up our error message data base editor. Other issues to consider involve multiple write access to this error message data base not necessary.
The Solution
A more natural approach is to retain the error messages within the source code. This avoids the problems listed above, but how do we generate a detailed listing of error messages along with descriptions? The solution takes the form of a source processor.
The source processor takes a completed source program and scans for error messages. By embedding a full description of each error message within the source code, we can automatically generate a list of error messages along with descriptions suitable for inclusion in a user manual.
If we extend this concept further, we can combine the facilities of the C preprocessor with the source processor, allowing us to automatically generate an external data base of error messages. This allows not only conversion to foreign languages but also such final touches as a spell-check for the production version of the product.
The source processor approach can encourage more readable code by documenting error messages thoroughly within the source code, automating the generation of error message descriptions, allowing fine-tuning of the error messages for the production version without touching the source code, and allowing multi-language error messages using the same program executable. Another advantage is that the source processor approach does not impede the flow of the development process. The source processor need only be run on the production version of the source.
I have used the source processor approach on a number of real-time financial systems, each around 300,000 lines of C, and it has proven both flexible and practical.
Implementation
The implementation essentially consists of two components. The first is a macro, error( ), which replaces the error message in the source with a call to an error-handling function _error( ). This error-handling function is passed the file name and line number which are used to look up an error data base file. The definition for the error macro is shown in Listing One, page 108, and the definition of the error-handling function is shown in Listing Two, page 108.
The implementation shown is fairly simple. More than likely you will want the error-handling function to pop up some window rather than use printf( ). The ability to pass additional information to the error function may also be required. These are fairly straightforward extensions.
The second component of the error handling system is the source processor. The function of the source processor is to scan through the source and extract error messages and accompanying descriptions. The file and line numbers of each error message are noted and two files are produced. The first is a listing of the error messages with descriptions suitable for inclusion in a user manual. The second is a data base of error messages indexed by their respective file and line numbers. Figure 1 shows a sample source file with an embedded error message and description. Figure 2 shows the resulting description for the user manual while Figure 3 shows the message data base. Figure 4 shows the results of the sample program.
Figure 1: Sample source file with embedded error message and description
#include <stdio.h>
#include "error.h"
main(int argc, char *argv[])
{
if (argc == 1)
error("Missing parameters");
/* No parameters have been passed
* to this test program. This error message
* will be displayed as an example if no
* parameters are passed to this test
* program.
*/
exit(0);
}
Figure 2: The user manual list resulting from Figure 1
Missing parameters:
No parameters have been passed
to this test program. This error
message will be displayed as an
example if no parameters are passed
to this test program.
Figure 3: The message data base resulting from Figure 1
test:8 Missing parameters
Figure 4: The results of the sample program
Missing parameters [test:8]
An AWK listing of the source processor is shown in Listing Three, page 108. Some assumptions have been made about the format of the embedded error message comments. This listing is intended as a starting point rather than a definitive implementation.
Conclusion
An error message source processor provides a flexible and effective mechanism for controlling error messages. Embedded error messages along with descriptions are extracted from the source code to create an external error message data base for a production version of the product and error message listing suitable for inclusion in a user manual. The benefits of retaining the error messages within the source code are maintained while the benefits of an external error message data base are obtained for the production version of the product.
_ERROR MESSAGE MANAGEMENT_ by Rohan Douglas
[LISTING ONE]<a name="0029_000d">
/* Include file for macros replacement of error function. */
#define error(m) _error(__FILE__, __LINE__)
extern void _error(char *, int);
<a name="0029_000e"><a name="0029_000e">
<a name="0029_000f">
[LISTING TWO]<a name="0029_000f">
/* Definition of error function. */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "error.h"
static int get_err_msg(char *, char *, char *);
void
_error(char *fname, int lno)
{
char *period; /* Pointer for file extension */
char lstr[6]; /* Temp string for file line */
char key[15]; /* Message key (file:line) */
char msg[75]; /* Error message from file */
/* Strip out file extension from file name */
if ((period = strchr(fname, '.')) != NULL)
*period = '\0';
/* Create file:linenumber key */
sprintf(key, "%s:%s", fname, itoa(lno, lstr,
10));
/* Look up error message from file */
if (!get_err_msg(fname, key, msg))
/* Not found in file, just print out
* file:lineno.
*/
printf("Error [%s]", key);
else
printf("%s [%s]", msg, key);
return;
} /* error() */
static int
get_err_msg(char *fname, char *key, char *msg)
{
FILE *fp; /* Error message file pointer */
char msg_key[14];/* Key for current line */
/* Open error file */
if (!(fp = fopen("error.dat", "r")))
return FALSE;
/* Scan file for message */
while (!feof(fp)) {
fscanf(fp, " %s ", msg_key);
fgets(msg, 75, fp);
if (!strcmpi(key, msg_key))
break;
}
fclose(fp);
/* Return false if message not found */
if (feof(fp))
return FALSE;
/* Remove CR from message string */
msg[strlen(msg)-1] = '\0';
return TRUE;
} /* get_err_msg() */
<a name="0029_0010"><a name="0029_0010">
<a name="0029_0011">[LISTING THREE]<a name="0029_0011">
BEGIN {
FS = "\"";
printf("") > "error.txt";
printf("") > "error.dat";
}
/ *error *\(/ {
printf("%s :\n", $2) >> "error.txt";
ind = substr(FILENAME, 0, index(FILENAME, ".")
- 1);
printf("%s:%d\t%s\n", ind, NR, $2) >>
"error.dat";
getline();
i = index($0, "/* ");
if (i) i++;
while (i) {
printf("\t%s\n", substr($0, i + 2)) >>
"error.txt";
getline();
if (index($0, "*/")) break;
i = index($0, "* ");
}
}
