Reporting errors from within GRASP code is simple: every legal GRASP error report consists of exactly one call to GR_start_error(), zero or more calls to GR_report_error(), and exactly one call to GR_end_error(). Failing to call the functions in exactly this order will cause an assert to fail and the program to abort; this allows the code in the handler routines to safely assume that they will be called in the correct order.
GR_start_error() takes four arguments specifying the name of the function in which the error occured, the RCS ID of the GRASP file which contains the function's source, the name of that file, and the line number on which the error report began. In practice providing this data is easy. Every GRASP file should declare a static string 'rcsid' containing the ID, and ANSI C defines the macros __FILE__ and __LINE__ which expand to the file name and line number, respectively. Within a given file only the function name parameter will change from call to call.
The arguments to GR_report_error() are exactly the same as those to printf(): a familiar printf-style format string followed by a variable number of arguments. There is no file pointer a' la fprintf() because the errors may not be printed to a file or the screen but handled in some completely different way determined by the calling program. Repeated calls are a convenient way to build up the complete message just as with printing to the screen with printf(). Finally, a call to GR_end_error() ends the report. It requires no arguments.
The GRASP source code provides many examples of the use of these functions, and they are documented by example in Section . Because of the stereotyped calling sequence and arguments involved, an efficient technique for GRASP library programmers is to paste in the calls from another location in the source file or from a handy template kept in a scratch file so that only the function name and actual message needs editing for each case.