At run time, you can encounter different types of errors or messages that are related to the use of the ESSL subroutines:
This section explains how to handle all these situations.
|The program exceptions you can encounter in ESSL are described in |the ANSI/IEEE Standard for Binary Floating-Point |Arithmetic, ANSI/IEEE Standard 754-1985.
This section gives an overview on how you can handle input-argument errors.
ESSL checks the validity of most input arguments. If it finds that any are invalid, it issues the appropriate error messages. Also, except for the three recoverable errors described below, it terminates your program. You should use standard programming techniques to diagnose and fix unrecoverable input-argument errors, as described in Chapter 7, Handling Problems.
You can determine the input-argument errors that can occur in a subroutine by looking under "Error Conditions" in the subroutine description in Part 2 of this book. Error messages for all input-argument errors are listed in Input-Argument Error Messages(2001-2099).
For three input-argument errors, 2015, 2030, and 2200 in Fortran, C, C++, and PL/I programs, you have the option to continue running and have an updated value of the input argument returned to your program for subsequent use. These are called recoverable errors. This recoverable error-handling capability gives you flexibility in determining the correct values for the arguments. You can:
If you chose to leave errors 2015, 2030 and 2200 unrecoverable, you do not need to make any coding changes to your program. The input-argument error message is issued upon termination, containing the updated values you could have specified for the program to run successfully. You then make the necessary corrections in your program and rerun it.
If you choose to make errors 2015, 2030 and 2200 recoverable, you call the ERRSET subroutine to set up the ESSL error exit routine, ENOTRM, and then call the ESSL subroutine. When one or more of these errors occurs, the input-argument error message is issued with the updated values. In addition, the updated values are returned to your program in the input arguments named in the error message, along with a nonzero return code and processing continues. Return code values associated with these recoverable errors are described under "Error Conditions" for each ESSL subroutine in Part 2.
For details on how to code the necessary statements in your program to make 2015, 2030 and 2200 recoverable, see the following sections:
This section gives an overview on how you can handle computational errors.
ESSL computational errors are errors occurring in the computational data, such as in your vectors and matrices. You can determine the computational errors that can occur in a subroutine by looking under "Error Conditions" in the subroutine description in Part 2 of this book. These errors cause your program to terminate abnormally unless you take preventive action. A message is also provided in your output, containing information about the error. Messages are listed in Computational Error Messages(2100-2199).
When a computational error occurs, you should assume that the results are unpredictable. The result of the computation is valid only if no errors have occurred. In this case, a zero return code is returned.
Figure 8 shows what happens when a computational error occurs.
Figure 8. How to Obtain Computational Error Information from an Error Message, but Terminate
|
In Fortran, C, C++, and PL/I programs, you have the capability to make certain computational errors recoverable and have information returned to your program about the errors. Recoverable computational errors are listed in Table 172. First, you call EINFO in the beginning of your program to initialize the ESSL error option table. You then call ERRSET to reset the number of allowable errors for the computational error codes in which you are interested. When a computational error occurs, a nonzero return code is returned for each computational error. Return code values associated with these errors are described under "Error Conditions" in each subroutine description. Based on the return code, your program can branch to an appropriate statement to call the ESSL error information-handler subroutine, EINFO, to obtain specific information about the data involved in the error. This information is returned in the EINFO output arguments, inf1 and, optionally, inf2. You can then check the information returned and continue processing, if you choose. The syntax for EINFO is described under EINFO--ESSL Error Information-Handler Subroutine. You also get a message in your output for each computational error encountered, containing information about the error. The EINFO subroutine provides the same information in the messages as it provides to your program.
For details on how to code the necessary statements in your program to obtain specific information on computational errors, see the following sections:
Figure 9 shows what happens if you make a computational error recoverable.
Figure 9. How to Obtain Computational Error Information in an Error Message and in Your Program
 |
This section gives an overview on how you can handle resource errors.
ESSL returns a resource error and terminates your program when an attempt to allocate work area fails. Some ESSL subroutines attempt to allocate work area for their internal use. Other ESSL subroutines attempt to dynamically allocate auxiliary storage when a user requests it through calling sequence arguments, such as aux and naux. For information on how you could reduce memory constraints on the system or increase the amount of memory available before rerunning the application program, see ESSL Resource Error Messages.
You can determine the resource errors that can occur in a subroutine by looking under "Error Conditions" in the subroutine description in Part 2 of this book. Error messages for all resource errors are listed in Resource Error Messages(2400-2499).
This section gives an overview on how you can handle attention messages.
ESSL returns an attention message to describe a condition that occurred, however, ESSL is able to continue processing. For information on how you could reduce memory constraints on the system or increase the amount of memory available, see ESSL Resource Error Messages.
For example, an attention message may be issued when enough work area was available to continue processing, but was not the amount initially requested. An attention message would be issued to indicate that performance may be degraded.
For a list of subroutines that may generate an attention message, see Table 31. For a list of attention messages, see Informational and Attention Error Messages(2600-2699).
This section explains all aspects of using the ESSL error option table.
The ESSL error option table contains information that tells ESSL what to do
every time it encounters an ESSL-generated error. Table 26 shows the default values established in the table when ESSL
is installed.
Table 26. ESSL Error Option Table Default Values
| Range of Error Messages (From-To) | Number of Allowable Errors (ALLOW) | Number of Messages Printed (PRINT) | Modifiable Table Entry (MODENT) |
|---|---|---|---|
| 2538-2000 | Unlimited | 255 | NO |
| 2538-2001 through 2538-2073 | Unlimited | 255 | YES |
| 2538-2074 | Unlimited | 5 | YES |
| 2538-2075 through 2538-2098 | Unlimited | 255 | YES |
| 2538-2099 | 1 | 255 | YES |
| 2538-2100 through 2538-2101 | 1 | 255 | YES |
| 2538-2102 | Unlimited | 255 | YES |
| 2538-2103 through 2538-2113 | 1 | 255 | YES |
| 2538-2114 | Unlimited | 255 | YES |
| 2538-2115 through 2538-2122 | 1 | 255 | YES |
| 2538-2123 through 2538-2124 | Unlimited | 255 | YES |
| 2538-2125 through 2538-2126 | 1 | 255 | YES |
| 2538-2127 | Unlimited | 255 | YES |
| 2538-2128 through 2538-2137 | 1 | 255 | YES |
| 2538-2138 through 2538-2143 | Unlimited | 255 | YES |
| 2538-2144 through 2538-2145 | 1 | 255 | YES |
| 2538-2146 through 2538-2149 | Unlimited | 255 | YES |
| 2538-2150 | 1 | 255 | YES |
| 2538-2151 | Unlimited | 255 | YES |
| 2538-2152 through 2538-2198 | 1 | 255 | YES |
| 2538-2199 | 1 | 255 | YES |
| 2538-2200 through 2538-2299 | Unlimited | 255 | YES |
| 2538-2400 through 2538-2499 | 1 | 255 | NO |
| 2538-2600 through 2538-2699 | Unlimited | 255 | NO |
| 2538-2700 through 2538-2799 | 1 | 255 | NO |
You can change any of the values in the ESSL error option table by calling the ERRSET subroutine in your program. This dynamically changes values at run time. You can also save and restore entries in the table by using the ERRSAV and ERRSTR subroutines, respectively. For a description of the ERRSET, ERRSAV, and ERRSTR subroutines see Chapter 17, Utilities.
Because you can change the information in the error option table, you can control what happens when any of the ESSL errors occur. There are a number of instances when you may want to do this:
You may simply want to adjust the number of times an error is allowed to occur before your program terminates. You can use any of the capabilities available in ERRSET.
You may want to make ESSL input-argument error 2015 or 2030 recoverable, so ESSL returns updated auxiliary storage sizes or transform lengths, respectively, to your program. For a more detailed discussion, see What Can You Do about ESSL Input-Argument Errors?. For how to use ERRSET to do this, see the section for your programming language in Chapter 4, Coding Your Program.
You may want to make ESSL input-argument error 2200 recoverable, so ESSL returns an updated size to your program. For a more detailed discussion, see What Can You Do about ESSL Input-Argument Errors?. For how to use ERRSET to do this, see the section for your programming language in Chapter 4, Coding Your Program.
You may want ESSL to return information about a computational error to your program. For a more detailed discussion, see What Can You Do about ESSL Computational Errors?. For how to do use ERRSET to do this, see the section for your programming language in Chapter 4, Coding Your Program.
If your program is part of a large application, you may want to dynamically save and restore entries in the error option table that have been altered by ERRSET. This ensures the integrity of the error option table when it is used by multiple programs within an application. For a more detailed discussion, see How Can You Control Error Handling in Large Applications by Saving and Restoring Entries in the Error Option Table? For how to use ERRSAV and ERRSTR, see the section for your programming language in Chapter 4, Coding Your Program.
When your program is part of a larger application, you should consider that one of the following can occur:
These situations can be avoided if every program that uses ERRSET, in the large application, also uses the ERRSAV and ERRSTR facilities. For a particular error number, ERRSAV saves an entry from the error option table in an area accessible to your program. ERRSTR then stores the entry back into the error option table from the storage area. You code an ERRSAV and ERRSTR for each input-argument error number and computational error number for which you do an ERRSET to reset the values in the error option table. Call ERRSAV at the beginning of your program after you call EINFO, and then call ERRSTR at the end of your program after all ESSL computations are completed. This saves the original contents of the error option table while your program is running with different values, and then restores it to its original contents when your program is done. For details on how to code these statements in your program, see Chapter 4, Coding Your Program.
When your application program or Fortran first creates a thread, ESSL initializes the error option table information to the default settings shown in Table 26. You can change the default settings for each thread you created by calling the appropriate error handling subroutines (ERRSET, ERRSAV, or ERRSTR) from each thread. An example of how to initialize the error option table and change the default settings on multiple threads is shown in Example of Handling Errors in a Multithreaded Application Program.
ESSL issues error messages as they occur in a threaded environment. Error messages issued from any of the existing threads are written to standard output in the order in which they occur.
When a terminating condition occurs on any of the existing threads (for example, the number of allowable errors was exceeded), ESSL terminates your application program. One set of summary information corresponding to the terminating thread is always printed. Summary information corresponding to other threads may also be printed.
Information about errors and how to handle them can be found in the following places: