Appendix A. Error Handling

This appendix describes error handling in the Interpreter and the SAI. Software for error handling is described here rather than in Appendix D. This appendix is intended to be useful to developers and researchers. NC programmers, machine operators, and SAI installers are not likely to find it useful. A complete list of error messages the Interpreter can generate (not including SAI driver error messages) is in the file rs274ngc_errors.cc, for those who are interested.

The Interpreter detects and flags most kinds of illegal input. Unreadable input, missing words, extra words, out-of-bounds numbers, and illegal combinations of words, for example, are all detected. The Interpreter does not check for axis overtravel or excessively high feeds or speeds, however. The Interpreter also does not detect situations where a legal command does something unfortunate, such as machining a fixture.

The Interpreter always saves the text of the last line to be interpreted. If there is an error, the Interpreter also saves the names of the functions in the function call stack. The driver, which has been given the error code, may then ask the Interpreter for (1) the text of the error, (2) the text of the line, and/or (3) some or all of the names of the functions in the stack. In the SAI, if an error occurs, the driver always asks for and prints the error text and line text. If the user has asked for it (see Section 5.1.1), the SAI also prints the names on the function call stack.

Control flow for error handling, synchronization of the Interpreter with the driver, and exiting are handled together by having each function that tells the Interpreter to do something return a status value meaning one of six things:

2. The Interpreter just executed a line that makes it necessary for the Interpreter to ask for information. No error has occurred, and it is not time to exit. If there is a queue of things that canonical machining function calls said to do, empty the queue (by executing everything in it), so that the state of the world will be up-to-date when the Interpreter asks for information. The driver should not ask the Interpreter to read again until the queue is empty. The symbolic value for this is RS274NGC_EXECUTE_FINISH. The main instance of this situation is in probing. After interpreting a line with a probe command, the Interpreter is going to ask for the results of probing the next time the driver tells it to read, but needs to be sure the probing has been carried out before asking for results.

3. The Interpreter just read a line starting with the block_delete character and there were no errors in reading the line. The symbolic value for this is also RS274NGC_EXECUTE_FINISH. This use of that value is easily distinguished from its use in item 2 (immediately above) because this use occurs during reading while the previous use occurs during execution.

4. Interpretation of a file has begun, and the Interpreter has read a line with nothing on it but a percent sign, "%", possibly surrounded by white space. If the first non-blank line of the file was the same sort of line, this means interpretation of the file should stop, and the value RS274NGC_ENDFILE is returned. If the first line was not such a line, an error has occurred.

If an error occurs, control is passed back up through the function call hierarchy to some driver function. If a subordinate Interpreter function called by a superior Interpreter function returns an error code, the superior stops where it is and passes the error code up to the function that called it. When the error code reaches the driver, it may be reported (and is, in the SAI).

Since returned values are usually used as just described to handle the possibility of errors, an alternative method of passing calculated values is required. In general, if Interpreter function A needs a value for variable V calculated by Interpreter function B, this is handled by passing a pointer to V from A to B, and B calculates and sets V. A few Interpreter functions in which no errors can be detected return calculated values rather than error codes.

The Interpreter software for handling errors uses four compiler macros: CHK, CHP, ERM, and ERP. Macros make the source more compact and easier to understand. Macros are used rather than functions because a "return" statement needs to be included.

The CHK macro checks if a given condition is true and returns a given error code if so.

The CHP macro calls another Interpreter function. If the called function returns an error code, CHP returns that code; otherwise, CHP does not cause a return.

ERP returns an error code generated in some other Interpreter function and passed to it.

The rs274ngc_error.cc and rs274ngc_return.hh files are generated automatically from the source code file rs274ngc.cc. This is done by a combination of lex programs and shell scripts. The basic approach is for the programmer (the authors of this report) to use symbolic values (NCE_G_CODE_OUT_OF_RANGE, for example) while writing rs274ngc.cc. Each symbolic value is the text of an error message set in all upper case letters, with spaces replaced by underscores, and the prefix "NCE_" added.

In writing the source code, a new error message is used (as a symbolic value) whenever none of the old ones is adequate to describe a particular error.

The lex programs and shell script read the source code file, pull out the error symbols (keeping track of which message comes from which function(s)), remove duplicates, alphabetize the list, assign an integer value to each symbol in the list, and write the list in the rs274ngc_return.hh file. A typical line of the file is #define NCE_G_CODE_OUT_OF_RANGE 82, for example.

The lex programs and shell script also convert each symbol back to text by removing the prefix, changing all letters except the first to lower case, and putting spaces back in where there are underscores. The text strings are written as a C array in the rs274ngc_error.cc file. That file also includes the index numbers as comments and the names of the functions which can give the messages. A typical line of the file is, for example:
/* 82 */ "G code out of range", // read_g

Error messages in the rs274ngc_error.cc file beginning with the word "Bug" should never appear but are provided as a check on the internal workings of the Interpreter. The appearance of one of these means there is a bug in the source code for the Interpreter. If one of these error messages ever appears, please contact kramer@cme.nist.gov by E-mail; include the message and describe the circumstances in which it appeared.

The following error messages may be printed by the SAI. Each message describes an error in the SAI that is not an Interpreter error. In the list below, each message is followed by the names of the driver function(s) that can print it. The messages originate in the source code for the SAI driver. A word in bold italics stands for a number or word that will differ according the exact nature of the error. The error messages are not kept in an array.