HP MLIB User's Guide Vol. 1 7th Ed.

28 HP MLIB User’s Guide
Error handling
Error handling
VECLIB subprograms are divided into two classes according to the way they
detect and report usage errors:
• Low-level subprograms
• High-level subprograms
Low-level subprograms
Low-level subprograms are only minimally capable of detecting or handling
errors. These subprograms attempt to do what is reasonable when a usage
error occurs, but they do not warn you that something is wrong. For example,
SDOT, which computes the dot product of two dense real vectors of length N,
gives the mathematically proper result, zero, when N ≤ 0. This is considered
mathematically correct because, by definition, an empty sum is zero. Because
SDOT conforms to the published BLAS argument list and usage, however,
SDOT does not notify you that you may have made a mistake. Issuing a
warning would add severe usage conflicts with codes that already use the
BLAS.
Because these low-level subprograms do what is reasonable, you can simplify a
program and perhaps speed it up by using VECLIB subprograms without
checking for special cases. For example, relying on SDOT having a zero result
for N ≤ 0 may eliminate an IF statement that would take the same branch
almost every time through a loop.
High-level subprograms
High-level subprograms detect and report errors. These subprograms usually
do more work than the low-level subprograms, so the relative expense of
checking and reporting errors may be small. Some possible errors are:
• Argument value errors, such as negative matrix order
• Computational errors, such as a singular matrix
• Computational problems, such as ill-conditioning
When a high-level subprogram detects an error, it responds with a success/error
code, usually with the output argument ier.
The convention used for ier is:
• ier = 0: Successful exit
• ier < 0: Invalid value of an argument—computation not completed