Error Handling

The DARs routines trap user input argument errors and cases where return character arguments are too short for the data being returned. The way in which such errors are handled varies according to the routine and is detailed in the 'Subroutine Specifications'. Many other potential errors are detected by the routines in the course of execution. All error conditions are communicated to the calling program through a return status code argument (always named ID3ERR in the subroutine specifications). A zero status code signifies successful execution; a positive value indicates an error condition.

Each subroutine specification lists the status codes applicable to it and a full list is provided in Error Codes and Messages.

Whenever an error condition is returned, the DARs set an internal error flag. This prevents entry into the next DARs routine (unless it is D3FIN, D3EMSG, D3ERST or D3UMON). The purpose of this action is to make the error obvious to the programmer (or to the user) and to prevent subsequent return of useless data. When such a failure occurs, helpful information concerning the source of the error is output to the screen. The programmer can obtain even more information by setting the monitor flag at an appropriate point.

In some circumstances, the programmer deliberately creates an error condition. This is a convenient way to terminate a loop. Routine D3ERST is provided to allow the programmer to reset the internal error flag in such a situation. Thus, the internal error flag is a device to trap errors not expected by the programmer.

The following extract from D3QMEM in the auxiliary routine library illustrates use of these principles. The status code returned by a routine can be converted into a message by a call to D3EMSG.

It is good practice if the programmer provides his own error trapping as illustrated above, particularly in a released applications program. The user can then be given an appropriate message, rather than receiving a message from the DARs error handling system.