HDF User’s Guide
Version 4.2r4[Top] [Prev][Next]
|
|
HDF User’s GuideVersion 4.2r4 |
[Top] [Prev][Next] |
Chapter 13 -- Error Reporting
13.1 Chapter Overview
This chapter describes the main error reporting routines designed for general HDF use and the types of errors handled by the error reporting API and the general structure of the API.
13.2 The HDF Error Reporting API
The HDF error reporting API consists of routines that query error stack information, the names of which are prefaced by "HE". They are described briefly in Table 13A. Some are primarily for use by HDF developers while others are available to HDF users. In this chapter, three error reporting functions are covered: HEprint, HEvalue and HEstring. Note that only one C error reporting routine has a FORTRAN-77 counterpart: heprnt/heprntf (heprntf is the newer function, supported on all platforms; heprnt is the original function, supported on non-Microsoft Windows platforms).
TABLE 13A Error Reporting Routine List13.3 Error Reporting in HDF
Most HDF error reporting routines return
FAIL(or-1) if the operation is successful andSUCCEED(or0) otherwise. Each time aFAILcode 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.A list of error codes is included at the end of this chapter.
13.3.1 Writing Errors to a File: HEprint
HEprint writes the errors on the stack to the specified file. There are four sections of an HEprint error report:
The syntax for HEprint is as follows:
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, heprnt (supported on non-Microsoft Windows platforms) always writes to the standard error stream, or stderr; therefore the only parameter is level. To facilitate Microsoft Windows support, a newer function heprntf (supported on all platforms) requires two parameters, filename to identify the file to which the error information is to be written and level.
Errors are written in sequential order starting from the bottom of the stack. Consequently, specifying a 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".
As an example of the output of HEprint, suppose an attempt is made to open an nonexistent file with Hopen. Calling
HEprint(stdout, 0)orheprnt(0)will produce the following output: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 level parameter specifies the number of errors to regress from the top of the error stack, i.e.,
HEvalue(1)will return the error code at the top of the stack. Refer to Table 13B on page 409 for a complete list of HDF4 error codes.The syntax for HEvalue is as follows:
13.3.3 Returning the Description of an Error Code: HEstring/hestringf
HEstring returns the error description associated with the error code specified by the error_code parameter as a character string.
The syntax for HEstring is as follows:
13.3.4 Clearing the error stack: HEclear
HEclear clears all information on reported errors from the error stack and is only available as a C routine. The syntax for HEclear is as follows:
Note that every HDF4 API calls HEclear to clear the error stack.
EXAMPLE 1. Writing Errors to a Console WindowThe 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
|
HDF4.2r4 - February 2009 Copyright |
The HDF Group www.hdfgroup.org 
|