Introduction
This package is the low-level Java interface for the CISD HDF5 library. It is derived from the
the low-level Java interface of the HDF Group's HDF-Java library.
 
It should be considered an internal interface and is likely to change in future versions.
 
 This code is called by Java programs to access the entry points of the HDF5 library. Each
 routine wraps a single HDF5 entry point, generally with the arguments and return codes analogous
 to the C interface.
 
 For details of the HDF5 library, see the HDF5 Documentation at: http://hdf.ncsa.uiuc.edu/HDF5/
 
 
 Mapping of arguments for Java
 
 In general, arguments to the HDF Java API are straightforward translations from the 'C' API
 described in the HDF Reference Manual.
 
 
 
 HDF-5 C types to Java types 
 
 | HDF-5 | Java | 
 
 | H5T_NATIVE_INT | int, Integer | 
 
 | H5T_NATIVE_SHORT | short, Short | 
 
 | H5T_NATIVE_FLOAT | float, Float | 
 
 | H5T_NATIVE_DOUBLE | double, Double | 
 
 | H5T_NATIVE_CHAR | byte, Byte | 
 
 | H5T_C_S1 | java.lang.String | 
 
 | void * (i.e., pointer to `Any')
 | Special -- see HDFArray | 
 
 
 
 
 General Rules for Passing Arguments and Results 
 
 In general, arguments passed IN to Java are the analogous basic types, as above. The
 exception is for arrays, which are discussed below.
 
 The return value of Java methods is also the analogous type, as above. A major exception
 to that rule is that all HDF functions that return SUCCEED/FAIL are declared boolean in
 the Java version, rather than int as in the C. Functions that return a value or else FAIL
 are declared the equivalent to the C function. However, in most cases the Java method will raise
 an exception instead of returning an error code. See Errors and Exceptions
 below.
 
 Java does not support pass by reference of arguments, so arguments that are returned through
 OUT parameters must be wrapped in an object or array. The Java API for HDF consistently
 wraps arguments in arrays.
 
 For instance, a function that returns two integers is declared:
 
 
 
       h_err_t HDF5dummy( int *a1, int *a2)
 
 
 For the Java interface, this would be declared:
 
 
 
 public static native int HDF5dummy(int args[]);
 
 
 where a1 is args[0] and a2 is args[1], and would be invoked:
 
 
 
 H5.HDF5dummy(a);
 
 
 All the routines where this convention is used will have specific documentation of the details,
 given below.
 
  HDF-5 Constants
 
 The HDF-5 API defines a set of constants and enumerated values. Most of these values are
 available to Java programs via the class HDF55Constants. For example, the parameters 
 for the h5open() call include two numeric values, HDF5Constants.H5F_ACC_RDWR and 
 HDF5Constants.H5P_DEFAULT. As would be expected, these numbers correspond to the 
 C constants H5F_ACC_RDWR and H5P_DEFAULT.
 
 The HDF-5 API defines a set of values that describe number types and sizes, such as
 "H5T_NATIVE_INT" and "hsize_t". These values are determined at run time by the HDF-5 C library.
 To support these parameters, the Java class HDF55Constants looks up the values when 
 initiated. The values can be accessed as public variables of the Java class, such as:
 
 
 int data_type = HDF55Constants.JH5T_NATIVE_INT;
 
 
 The Java application uses both types of constants the same way, the only difference is that the
 HDF55Constants may have different values on different platforms.
 
  Error handling and Exceptions
 
 The HDF5 error API (H5E) manages the behavior of the error stack in the HDF-5 library. This API
 is omitted from the JHI5. Errors are converted into Java exceptions. This is totally different
 from the C interface, but is very natural for Java programming.
 
 The exceptions of the JHI5 are organized as sub-classes of the class HDF5Exception. 
 There are two subclasses of HDF5Exception, HDF5LibraryException
 and HDF5JavaException. The sub-classes of the former represent errors from the HDF-5 
 C library, while sub-classes of the latter represent errors in the JHI5 wrapper and support code.
 
 The super-class HDF5LibraryException implements the method
 'printStackTrace()', which prints out the HDF-5 error stack, as described in the
 HDF-5 C API H5Eprint(). This may be used by Java exception handlers to print out
 the HDF-5 error stack.