The HDF Group

HDF User’s Guide

Version 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 List
Category
Routine Name
Description
C
FORTRAN-77
Error Reporting
HEprint
heprnt
heprntf
Prints the errors on the error stack to a specified file.
HEstring
hestringf
Returns the error message associated with an error code.
HEvalue
None
Returns the nth most recent error reported.

13.3 Error Reporting in HDF

Most HDF error reporting routines return 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.

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:

  1. A description of the error.
  2. The routine in which the error was detected.
  3. The source file in which the error was detected.
  4. The line number in which the error was detected.

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) or heprnt(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 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
Error Code
Code Definition
DFE_NONE
No error.
DFE_FNF
File not found.
DFE_DENIED
Access to file denied.
DFE_ALROPEN
File already open.
DFE_TOOMANY
Too many AID's or files open.
DFE_BADNAME
Bad file name on open.
DFE_BADACC
Bad file access mode.
DFE_BADOPEN
Miscellaneous open error.
DFE_NOTOPEN
File can't be closed because it hasn't been opened.
DFE_CANTCLOSE
fclose error
DFE_READERROR
Read error.
DFE_WRITEERROR
Write error.
DFE_SEEKERROR
Seek error.
DFE_RDONLY
File is read only.
DFE_BADSEEK
Attempt to seek past end of element.
DFE_PUTELEM
Hputelement error.
DFE_GETELEM
Hgetelement error.
DFE_CANTLINK
Cannot initialize link information.
DFE_CANTSYNC
Cannot synchronize memory with file.
DFE_BADGROUP
Error from DFdiread in opening a group.
DFE_GROUPSETUP
Error from DFdisetup in opening a group.
DFE_PUTGROUP
Error on putting a tag/reference number pair into a group.
DFE_GROUPWRITE
Error when writing group contents.
DFE_DFNULL
Data file reference is a null pointer.
DFE_ILLTYPE
Data file contains an illegal type: internal error.
DFE_BADDDLIST
The DD list is non-existent: internal error.
DFE_NOTDFFILE
The current file is not an HDF file and it is not zero length.
DFE_SEEDTWICE
The DD list already seeded: internal error.
DFE_NOSUCHTAG
No such tag in the file: search failed.
DFE_NOFREEDD
There are no free DDs left: internal error.
DFE_BADTAG
Illegal WILDCARD tag.
DFE_BADREF
Illegal WILDCARD reference number.
DFE_NOMATCH
No DDs (or no more DDs) that match the specified tag/reference number pair.
DFE_NOTINSET
Warning: Set contained unknown tag. Ignored.
DFE_BADOFFSET
Illegal offset specified.
DFE_CORRUPT
File is corrupted.
DFE_NOREF
No more reference numbers are available.
DFE_DUPDD
The new tag/reference number pair has been allocated.
DFE_CANTMOD
Old element doesn't exist. Cannot modify.
DFE_DIFFFILES
Attempt to merge objects in different files.
DFE_BADAID
An invalid AID was received.
DFE_OPENAID
Active AIDs still exist.
DFE_CANTFLUSH
Cannot flush DD back to file.
DFE_CANTUPDATE
Cannot update the DD block.
DFE_CANTHASH
Cannot add a DD to the hash table.
DFE_CANTDELDD
Cannot delete a DD in the file.
DFE_CANTDELHASH
Cannot delete a DD from the hash table.
DFE_CANTACCESS
Cannot access specified tag/reference number pair.
DFE_CANTENDACCESS
Cannot end access to data element.
DFE_TABLEFULL
Access table is full.
DFE_NOTINTABLE
Cannot find element in table.
DFE_UNSUPPORTED
Feature not currently supported.
DFE_NOSPACE
malloc failed.
DFE_BADCALL
Routine calls were in the wrong order.
DFE_BADPTR
NULL pointer argument was specified.
DFE_BADLEN
Invalid length was specified.
DFE_NOTENOUGH
Not enough space for the data.
DFE_NOVALS
Values were not available.
DFE_ARGS
Invalid arguments passed to the routine.
DFE_INTERNAL
Serious internal error.
DFE_NORESET
Too late to modify this value.
DFE_GENAPP
Generic application level error.
DFE_UNINIT
Interface was not initialized correctly.
DFE_CANTINIT
Cannot initialize the interface the operation requires.
DFE_CANTSHUTDOWN
Cannot shut down the interface the operation requires.
DFE_BADDIM
Negative number of dimensions, or zero dimensions, was specified.
DFE_BADFP
File contained an illegal floating point number.
DFE_BADDATATYPE
Unknown or unavailable data type was specified.
DFE_BADMCTYPE
Unknown or unavailable machine type was specified.
DFE_BADNUMTYPE
Unknown or unavailable number type was specified.
DFE_BADORDER
Unknown or illegal array order was specified.
DFE_RANGE
Improper range for attempted access.
DFE_BADCONV
Invalid data type conversion was specified.
DFE_BADTYPE
Incompatible types were specified.
DFE_BADSCHEME
Unknown compression scheme was specified.
DFE_BADMODEL
Invalid compression model was specified.
DFE_BADCODER
Invalid compression encoder was specified.
DFE_MODEL
Error in the modeling layer of the compression operation.
DFE_CODER
Error in the encoding layer of the compression operation.
DFE_CINIT
Error in encoding initialization.
DFE_CDECODE
Error in decoding compressed data.
DFE_CENCODE
Error in encoding compressed data.
DFE_CTERM
Error in encoding termination.
DFE_CSEEK
Error seeking in an encoded data set.
DFE_MINIT
Error in modeling initialization.
DFE_COMPINFO
Invalid compression header.
DFE_CANTCOMP
Cannot compress an object.
DFE_CANTDECOMP
Cannot decompress an object.
DFE_NOENCODER
Encoder not available.
DFE_NOSZLIB
SZIP library not available.
DFE_COMPVERSION
Version error from zlib
Note: when Z_VERSION_ERROR (-6) returned from zlib.
DFE_READCOMP
Error in reading compressed data.
Note: when one of the following error codes returned from zlib:
Z_ERRNO (-1)
Z_STREAM_ERROR (-2)
Z_DATA_ERROR (-3)
Z_MEM_ERROR (-4)
Z_BUF_ERROR (-5)
DFE_NODIM
A dimension record was not associated with the image.
DFE_BADRIG
Error processing a RIG.
DFE_RINOTFOUND
Cannot find raster image.
DFE_BADATTR
Invalid attribute.
DFE_BADTABLE
The nsdg table has incorrect information.
DFE_BADSDG
Error in processing an SDG.
DFE_BADNDG
Error in processing an NDG.
DFE_VGSIZE
Too many elements in the vgroup.
DFE_VTAB
Element not in vtab[].
DFE_CANTADDELEM
Cannot add the tag/reference number pair to the vgroup.
DFE_BADVGNAME
Cannot set the vgroup name.
DFE_BADVGCLASS
Cannot set the vgroup class.
DFE_BADFIELDS
Invalid fields string passed to vset routine.
DFE_NOVS
Cannot find the vset in the file.
DFE_SYMSIZE
Too many symbols in the users table.
DFE_BADATTACH
Cannot write to a previously attached vdata.
DFE_BADVSNAME
Cannot set the vdata name.
DFE_BADVSCLASS
Cannot set the vdata class.
DFE_VSWRITE
Error writing to the vdata.
DFE_VSREAD
Error reading from the vdata.
DFE_BADVH
Error in the vdata header.
DFE_VSCANTCREATE
Cannot create the vdata.
DFE_VGCANTCREATE
Cannot create the vgroup.
DFE_CANTATTACH
Cannot attach to a vdata or vset.
DFE_CANTDETACH
Cannot detach a vdata or vset with write access.
DFE_BITREAD
A bit read error occurred.
DFE_BITWRITE
A bit write error occurred.
DFE_BITSEEK
A bit seek error occurred.
DFE_TBBTINS
Failed to insert the element into tree.
DFE_BVNEW
Failed to create a bit vector.
DFE_BVSET
Failed when setting a bit in a bit vector.
DFE_BVGET
Failed when getting a bit in a bit vector.
DFE_BVFIND
Failed when finding a bit in a bit vector.


HDF4.2r4 - February 2009
Copyright
The HDF Group
www.hdfgroup.org
The HDF Group