Zebra has been programmed to be as helpful as reasonably possible in the task of detecting and diagnosing errors. Depending on the kind of the error, three different approaches are used : for the convenience of the user we have made it a general rule that he does not have to test on the success of a request to Zebra, the return from the CALL to Zebra implies successful completion. For example : if the user calls MZLIFT he can be sure that the bank has been created if he receives control on the next Fortran statement; if MZLIFT is in trouble, either because the parameters supplied by the user are faulty, or because there is no free memory left, Zebra will not return to the calling routine, but take an escape road, by calling ZFATAL in the first case to stop the program with diagnostics, or by calling ZTELL in the second case to allow the user to re-gain control at the top-level to handle the problem.
The exceptions to this general rule are again dictated by the convenience of usage, since there are cases where it is necessary to be able to handle errors in-line to the code as a matter of routine. This is realized with the first approach:
This approach is used in all instances where "errors" are part of the normal processing. The obvious example is the routine FZIN which must allow the user to handle read errors in particular, exceptions in general.
The status-return code
is always in the word \IQUEST(1) of /QUEST/IQUEST(100).
This word is zero if the request has been completed successfully;
a non-zero value indicates an exception.
The value is positive for a normal exception (such as end-of-file),
the value is negative for errors (such as read errors);
the particular value indicates which exception has occurred.
The significance of the status-return code is part of the
specifications of the routine.
For an error status, other words in /QUEST/ carry more information to identify the problem, the exact details are found in the present paper under the name of the routine in question.
This approach is used in the instances where Zebra cannot
satisfy a request, without the program being really at fault.
The obvious example is a request for memory, such as with MZLIFT,
which cannot be satisfied even after garbage collection.
The exit to ZTELL allows the user at the high level to take
control away from the failing low level of his program.
The first parameter to ZTELL is an integer identifying the
cause of the problem; this ID is 99 for 'no memory'.
On page 
a list of
the Zebra routines which call ZTELL is given,
together with their identifiers;
further details are found under the name of the calling routine.
This approach is used to catch programming mistakes, such as faulty parameters in a Zebra call. Also, some Zebra routine may detect that the user has overwritten some system information in a bank, thereby destroying the sequential chaining from one bank in memory to the physically next bank ('bank chaining clobbered').
Any error of this kind is trapped as soon as it is detected, information to localize the problem is loaded into /QUEST/ and control is transferred to ZFATAL. ZFATAL will print the name of the routine which has called it (if ZFATAL is reached by in an internal transfer within Zebra) and the diagnostic information, whose significance is found in the present paper under the name of the routine which catches the error.
The routine which detects the problem is not necessarily the routine actually called by the user. For example : the user may call MZLIFT which in turn may need to call the garbage collector; one of its routines may discover that the memory is invalid, and it will transfer control to ZFATAL. ZFATAL will print its name, which the user may never have heard of. In order to be able to tell the user which routine he actually called, Zebra keeps an internal trace-back stack which is printed by ZFATAL. If the Fortran trace-back is available on a particular machine, this will also be printed as it contains information very useful to localize the problem.
This chapter gives the details on error information under the name of the routine in question, sorted alphabetically.