C++ Producer Guide

March 1998

3.3. Error catalogue

This section describes the error catalogue which lies at the heart of the C++ producer's error reporting routines. The full error catalogue syntax is given as an annex. A typical entry in the catalogue is as follows:

	class_union_deriv ( CLASS_TYPE: ct )
	{
	    USAGE:              serious
	    PROPERTIES:         ansi
	    KEY (ISO)           "9.5"
	    KEY (STANDARD)      "The union '"ct"' can't have base classes"
	}

This defines an error, class_union_deriv, which takes a single parameter ct of type CLASS_TYPE. The severity of this error is serious; that is to say, a constraint error. The error property ansi indicates that the error arises from the ISO C++ standard, the associated ISO key indicating section 9.5. Finally the text to be printed for this error, including a reference to ct, is given. Looking up section 9.5 in the ISO C++ standard reveals the corresponding constraint in paragraph 1:

A union shall not have base classes.

Each constraint within the ISO C++ standard has a corresponding error in this way. The errors are named in a systematic fashion using the section names used in the draft standard. For example, section 9.5 is called class.union, so all the constraint errors arising from this section have names of the form class_union_*. These error names can be used in the low level directives such as:

	#pragma TenDRA++ error "class_union_deriv" allow

to modify the error severity. The effect of reducing the severity of a constraint error in this way is undefined.

In addition to the obvious error severity levels, serious, warning and none, the error catalogue specifies a list of optional severity levels along with their default values. For example, the entry:

	link_incompat = serious

sets up an option named link_incompat which is a constraint error by default. Errors with this severity, such as:

	dcl_stc_external ( LONG_ID: id, PTR_LOC: loc )
	{
	    USAGE:              link_incompat
	    PROPERTIES:         ansi
	    KEY (ISO)           "7.1.1"
	    KEY (STANDARD)      "'"id"' previously declared with external
				 linkage (at "loc")"
	}

are therefore constraint errors. The severity associated with link_incompat can be modified either directly, using the directive:

	#pragma TenDRA++ option "link_incompat" allow

or indirectly using the directive:

	#pragma TenDRA incompatible linkage allow

the effect being to modify the severity of the associated error messages.

The error catalogue is processed by a simple tool, make_err, which generates C code which is compiled into the C++ producer. Each error in the catalogue is assigned a number (there are currently 873 errors in the catalogue) which gives an index into an automatically generated table of error information. It is this error number, together with a list of error arguments, which forms the associated ERROR object. make_err generates a macro for each error in the catalogue which takes arguments of the appropriate types (which may be statically checked) and creates an ERROR object. For example, for the entry above this macro takes the form:

	ERROR ERR_class_union_deriv ( CLASS_TYPE ) ;

These macros hide the error catalogue numbers from the rest of the C++ producer.

It is also possible to join a number of simple ERROR objects to form a single composite ERROR. The severity of the composite error is the maximum of the severities of the component errors. To this purpose a dummy error severity level whatever is introduced which is less severe than any other level. This is intended for use with error messages which are only ever used to add information to existing errors, and which inherit their severity level from the main error.

The text of a simple error message can be found in the table of error information. The text contains certain escape sequences indicating where the error arguments are to be printed. For example, %1 indicates the second argument. The error argument sorts - what is referred to as the error signature - is also stored in the table of error information as an array of characters, each corresponding to an ERR_KEY_type macro. The producer defines printing routines for each of the types given by these values, and calls the appropriate routine to print the argument.

There are several command-line options which can be used to modify the form in which the error message is printed. The default format is as follows:

	"file.C", line 42: Error:
	    [ISO 9.5]: The union 'U' can't have base classes.

The ISO section number can be suppressed using -m-s. The -mc option causes the source code line giving rise to the error to be printed as part of the message, with !!!! marking the position of the error within the line. The -me option causes the error name, class_union_deriv, to be printed as part of the message. The -ml option causes the full file location, including the list of #include directives used in reaching the file, to be printed. The -mt option causes typedef names to be used when printing types, rather than expanding to the type definition.