QM provides a number of ways to trap errors, some applicable to the command environment, some to QMBasic programs. This section summarises the features of QM error handling.
QM uses a simple system of error numbers to identify the cause of an error. The formal definition of these numbers is in a QMBasic include record named ERR.H in the SYSCOM file. The list can also be found in the Error Numbers section of this manual.
The @SYSTEM.RETURN.CODE Variable
Many commands leave status information in the @SYSTEM.RETURN.CODE variable. The value of this variable can be tested within a paragraph or a QMBasic program to determine whether the command was successful. In general, success is indicated by the value of this variable being zero. Because the query processor uses @SYSTEM.RETURN.CODE to return the number of records processed, error values are usually returned as the negative of the error number.
The REPORT.SRC command can be used to enable automatic display of the value of @SYSTEM.RETURN.CODE after every command. This is useful as a debugging aid during application development.
The @USER.RETURN.CODE Variable
User written programs cannot update @SYSTEM.RETURN.CODE. QM provides a similar variable, @USER.RETURN.CODE, for use in user written programs. This variable starts zero and is never updated by QM itself. It can be set from programs or by use of the SET command in a paragraph.
The QMBasic STATUS() Function
Many QMBasic program operations leave status information that can be accessed using the STATUS() function. Although often used for error numbers, the data returned by the STATUS() function may have other roles. For example, some operations that attempt to get locks return the user number of the user who owns the lock if the action cannot be completed. Use of the STATUS() fuunction is documented with the relevant QMBasic statements and functions.
The QMBasic OS.ERROR() Function
Where an error reported by QM is related to some underlying error reported by the operating system, the original operating system error code can often be obtained using the OS.ERROR() function. The QM errors for which this extended error information is available are documented with the relevant QMBasic statements and functions. They are also marked in the SYSCOM ERR.H record.
Operating system error numbers vary between platforms and are documented by the operating system vendor.
The QMBasic ON ERROR Clause
Many QMBasic statements that could fail due to external influence have an optional ON ERROR clause. This would be executed, for example, when attempting to write to a file for which the user does not have write access.
The default action of QM to this type of error if no ON ERROR clause is present is to abort the program with a suitable diagnostic message. The ON ERROR clause allows the program to catch this error and handle it internally instead of aborting.
Very few programs ever need to use the ON ERROR clause. It is only applicable in situations where the program can take some meaningful action to recover from the error. The default action of QM is usually appropriate and informative. A program that simply uses the ON ERROR clause to abort is likely to produce a less helpful diagnostic message than would have been displayed without this clause.