FAIL (or -1) if the operation is successful and SUCCEED (or 0) otherwise. Each time a FAIL code is returned one or more error codes are pushed onto the error code stack. The following pseudo-code will demonstrate the two methods commonly used to access and print the contents of this stack.
if (<general HDF function() >= FAIL) {
<HDF error reporting API routines>
}
OR
status = <general HDF function( );
if (status == FAIL) {
<HDF error reporting API routines>
}A list of error codes is included at the end of this chapter.
The syntax for HEprint is as follows:
C: HEprint(stream, level);
FORTRAN: status = heprnt(level)
The stream parameter is a UNIX file handle indicating the output stream the error information will be written to. The level parameter specifies the amount of error information to report. In FORTRAN-77, HEprint always writes to the standard error stream, or stderr, therefore the only parameter is level.level parameter value of 1 will write the first error that occurred, or the first error pushed onto the stack. Specifying a level parameter of value 0 will write all errors on the stack to the specified file. For example, the following C code will write all errors on the stack to the file named "errors". f = fopen("errors", "w");
HEprint(f, 0);
As an example of the output of HEprint, suppose an attempt is made to open an nonexistent file with Hopen. Calling HEprint(stdout, 0) or heprnt(0) will produce the following output: HDF error: <error opening file>
Detected in Hopen() [hfile.c line 305]
13.3.2 Returning the Code of the Nth Most Recent Error: HEvalue
HEvalue returns the error code for the nth most recent error and is only available as a C routine. The error_stack_offset parameter specifies the number of errors to regress from the top of the error stack.C: status = HEvalue(error_stack_offset);
13.3.3 Returning the Description of an Error Code: HEstring
HEstring returns the error description associated with the error code specified by the error_code parameter as a character string. As with HEvalue, HEstring is only available in the C HDF library.C: error_string = HEstring(error_code);
EXAMPLE 1. Writing Errors to a Console Window
The following C code fragment will copy errors from the stack to a console window. C:
#include "hdf.h"
main( )
{
int32 i, e;
const char *str;
...
i = 0;
while ((e = HEvalue(i)) != DFE_NONE) {
str = HEstring(e);
<device-specific code to print the string to a console>
i++
...
}
TABLE 13B - HDF Error Codes