ncsa.hdf.hdflib
Class HDFLibrary

java.lang.Object
  ncsa.hdf.hdflib.HDFLibrary

Direct Known Subclasses:

HDFDeprecated

public class HDFLibrary
extends java.lang.Object

This is the Java interface for the HDF 4.1 library.

This code is the called by Java programs to access the entry points of the HDF 4.1 library. Each routine wraps a single HDF entry point, generally with the arguments and return codes analogous to the C interface.

For details of the HDF libraries, see the HDF Documentation at: http://hdf.ncsa.uiuc.edu

These routines use the class HDFArray to handle arrays of arbitrary type and shape.

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.

C types to Java types

C	Java
int, intn, int32, uint32	int
short, uint16, int16	short
float, float32	float
double, float64	double
char, uchar, int8, uint8	byte
char * (i.e., string)	java.lang.String
void	void
void *, VOIDP, char * (meaning ``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 intn or whatever. (Functions that return a value or else FAIL are declared the equivalent to the C function.)

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:

       void HDFdummy( int32* a1, int32* a2)
  

For the Java interface, this would be declared:

       public static native void HDFdummy( int args[] );
  

where a1 is args[0] and a2 is args[1].

All the routines where this convention is used will have specific documentation of the details, given below.

Arrays

HDF needs to read and write multi-dimensional arrays of many types. The HDF API is self-describing, with the data for the array passed as a block of bytes, for instance,

      int SDreaddata(int sdsid, int32 *start, int32 * stride,
                       int32 *count, VOIDP data);
  

where ``VOIDP'' means that the data may be any valid numeric type, and is a contiguous block of bytes that is the data for a multi-dimensional array.

For Java, this is a problem, as the type of data must be declared. Furthermore, multidimensional arrays are definitely not layed out contiguously in memory. It would be infeasible to declare a separate routine for every combination of number type and dimensionality. For that reason, the HDFArray class is used to discover the type, shape, and size of the data array at run time, and to convert to and from contigous bytes. The upshot is that the data can be passed as an ``Object'', and the Java API will translate to and from the appropriate bytes. So the function above would be declared:

      int SDreaddata(int sdsid, int[] start, int[] stride,
                       int[] count, Object data);
  

and the parameter data can be any multi-dimensional array of numbers, such as float[][], or int[][][].

Compression and Chunk Information

The HDF library passes the parameters needed by compression and chunking through C structures (actually, unions). The Java interface passes these as instances of subclasses of class HDFCompInfo and HDFChunkInfo respectively.

See: ncsa.hdf.hdflib.HDFChunkInfo, and

ncsa.hdf.hdflib.HDFCompInfo.

Field Summary

static java.lang.String

HDFPATH_PROPERTY_KEY

Constructor Summary

HDFLibrary()

Method Summary

static int	ANannlen(int ann_id)
static int	ANannlist(int an_id, int anntype, int tag, int ref, int[] ann_list)
static short	ANatype2tag(int antag)
static int	ANcreate(int an_id, short tag, short ref, int type)
static int	ANcreatef(int an_id, int type)
static boolean	ANdestroy()
static boolean	ANend(int an_id)
static boolean	ANendaccess(int an_id)
static boolean	ANfileinfo(int an_id, int[] info)
static int	ANget_tagref(int an_id, int index, int type, short[] tagref)
static boolean	ANid2tagref(int an_id, short[] tagref)
static int	ANnumann(int an_id, int anntype, short tag, short ref)
static boolean	ANreadann(int ann_id, java.lang.String[] annbuf, int maxlen)
static int	ANselect(int an_id, int index, int anntype)
static int	ANstart(int fid)
static int	ANtag2atype(short anttype)
static int	ANtagref2id(int an_id, short tag, short ref)
static boolean	ANwriteann(int ann_id, java.lang.String label, int ann_length)
static boolean	DF24addimage(java.lang.String filename, byte[] image, int width, int height)
static boolean	DF24addimage(java.lang.String filename, java.lang.Object theImage, int width, int height)
static boolean	DF24getdims(java.lang.String fileName, int[] argv)
static boolean	DF24getimage(java.lang.String fileName, byte[] imagedata, int width, int height)
static boolean	DF24getimage(java.lang.String fileName, java.lang.Object theImagedata, int width, int height)
static short	DF24lastref()
static int	DF24nimages(java.lang.String fileName)
static boolean	DF24putimage(java.lang.String filename, byte[] image, int width, int height)
static boolean	DF24putimage(java.lang.String filename, java.lang.Object theImage, int width, int height)
static boolean	DF24readref(java.lang.String filename, int ref)
static boolean	DF24reqil(int il)
static boolean	DF24restart()
static boolean	DF24setcompress(int type, HDFCompInfo cinfo)
static boolean	DF24setdims(int width, int height)
static boolean	DF24setil(int il)
static int	DFKNTsize(int numbertype)
static boolean	DFPaddpal(java.lang.String filename, byte[] palette)
static boolean	DFPgetpal(java.lang.String filename, byte[] palette)
static short	DFPlastref()
static int	DFPnpals(java.lang.String filename)
static boolean	DFPputpal(java.lang.String filename, byte[] palette, boolean overwrite, java.lang.String filemode)
static boolean	DFPputpal(java.lang.String filename, byte[] palette, int overwrite, java.lang.String filemode)
static boolean	DFPreadref(java.lang.String filename, short ref)
static short	DFPrestart()
static boolean	DFPwriteref(java.lang.String filename, short ref)
static boolean	DFR8addimage(java.lang.String filename, byte[] image, int width, int height, short compress)
static boolean	DFR8addimage(java.lang.String filename, java.lang.Object theImage, int width, int height, short compress)
static boolean	DFR8getdims(java.lang.String fileName, int[] argv, boolean[] haspalette)
static boolean	DFR8getimage(java.lang.String fileName, byte[] imagedata, int width, int height, byte[] palette)
static boolean	DFR8getimage(java.lang.String fileName, java.lang.Object theImagedata, int width, int height, byte[] palette)
static boolean	DFR8getpalref(short[] palref)
static short	DFR8lastref()
static int	DFR8nimages(java.lang.String fileName)
static boolean	DFR8putimage(java.lang.String filename, byte[] image, int width, int height, short compress)
static boolean	DFR8putimage(java.lang.String filename, java.lang.Object theImage, int width, int height, short compress)
static boolean	DFR8readref(java.lang.String filename, int ref)
static boolean	DFR8restart()
static boolean	DFR8setcompress(int type, HDFCompInfo cinfo)
static boolean	DFR8setpalette(byte[] palette)
static boolean	DFR8writeref(java.lang.String filename, short ref)
static java.lang.String	getJHIVersion()
static boolean	GRattrinfo(int id, int index, java.lang.String[] name, int[] argv)
static int	GRcreate(int gr_id, java.lang.String name, int ncomp, int data_type, int interlace_mode, int[] dim_sizes)
static boolean	GRend(int grid)
static boolean	GRendaccess(int riid)
static boolean	GRfileinfo(int grid, int[] args)
static int	GRfindattr(int id, java.lang.String name)
static boolean	GRgetattr(int id, int index, byte[] data)
static boolean	GRgetattr(int id, int index, java.lang.Object theData)
static boolean	GRgetchunkinfo(int sdsid, HDFChunkInfo chunk_def, int[] flag)
static boolean	GRgetcompress(int ri_id, HDFCompInfo c_info)
static boolean	GRgetiminfo(int grid, java.lang.String[] gr_name, int[] args, int[] dim_sizes)
static int	GRgetlutid(int rrid, int index)
static boolean	GRgetlutinfo(int lutid, int[] args)
static int	GRgetnluts(int rrid)
static short	GRidtoref(int riid)
static short	GRluttoref(int pal_id)
static int	GRnametoindex(int grid, java.lang.String name)
static boolean	GRreadchunk(int sdsid, int[] origin, byte[] theData)
static boolean	GRreadchunk(int grid, int[] origin, java.lang.Object theData)
static boolean	GRreadimage(int grid, int[] start, int[] stride, int[] count, byte[] data)
static boolean	GRreadimage(int grid, int[] start, int[] stride, int[] count, java.lang.Object theData)
static boolean	GRreadlut(int lutid, byte[] data)
static boolean	GRreadlut(int lutid, java.lang.Object theData)
static int	GRreftoindex(int grid, short ref)
static boolean	GRreqimageil(int rrid, int interlace)
static boolean	GRreqlutil(int riid, int interlace)
static int	GRselect(int grid, int index)
static boolean	GRsetattr(int gr_id, java.lang.String attr_name, int data_type, int count, byte[] values)
static boolean	GRsetattr(int gr_id, java.lang.String attr_name, int data_type, int count, java.lang.Object theData)
static boolean	GRsetattr(int gr_id, java.lang.String attr_name, int data_type, int count, java.lang.String values)
static boolean	GRsetchunk(int sdsid, HDFChunkInfo chunk_def, int flags)
static int	GRsetchunkcache(int sdsid, int maxcache, int flags)
static boolean	GRsetcompress(int ri_id, int comp_type, HDFCompInfo c_info)
static boolean	GRsetexternalfile(int ri_id, java.lang.String filename, int offset)
static int	GRstart(int fid)
static boolean	GRwriteimage(int grid, int[] start, int[] stride, int[] edge, byte[] data)
static boolean	GRwriteimage(int grid, int[] start, int[] stride, int[] edge, java.lang.Object theData)
static boolean	GRwritelut(int pal_id, int ncomp, int data_type, int interlace, int num_entries, byte[] pal_data)
static boolean	GRwritelut(int pal_id, int ncomp, int data_type, int interlace, int num_entries, java.lang.Object theData)
static boolean	Hcache(int file_id, int cache_switch)
static int	HCget_config_info(int coder_type) New API for hdf-42r1
static boolean	Hclose(int fid)
static int	HDdont_atexit()
static boolean	HDFclose(int file_id)
static int	HDFopen(java.lang.String filename, int access, short n_dds)
static java.lang.String	HDgetNTdesc(int nt)
static java.lang.String	HEstring(int error_code)
static short	HEvalue(int level)
static boolean	Hgetfileversion(int file_id, int[] vers, java.lang.String[] string) Note: the version of an HDF file is not well defined, it is not recommended that programs rely on these numbers.
static boolean	Hgetlibversion(int[] vers, java.lang.String[] string)
static boolean	Hishdf(java.lang.String fileName)
static int	Hnumber(int fid)
static int	Hopen(java.lang.String filename)
static int	Hopen(java.lang.String filename, int access)
static boolean	Hsetaccesstype(int h_id, int access_type)
static boolean	Hsync(int file_id)
static boolean	HXsetcreatedir(java.lang.String dir)
static boolean	HXsetdir(java.lang.String dir)
static boolean	SDattrinfo(int id, int index, java.lang.String[] name, int[] argv)
static boolean	SDcheckempty(int sdsid, int[] emptySDS)
static int	SDcreate(int sd_id, java.lang.String name, int number_type, int rank, int[] dimsizes)
static boolean	SDdiminfo(int dimid, java.lang.String[] name, int[] argv)
static boolean	SDend(int sdid)
static boolean	SDendaccess(int sdsid)
static boolean	SDfileinfo(int sdid, int[] argv)
static int	SDfindattr(int id, java.lang.String name)
static boolean	SDgetcal(int sdsid, double[] argv, int[] NT)
static boolean	SDgetchunkinfo(int sdsid, HDFChunkInfo chunk_def, int[] clflags)
static boolean	SDgetcompress(int id, HDFCompInfo cinfo)
static boolean	SDgetdatastrs(int sdsid, java.lang.String[] strings, int len)
static int	SDgetdimid(int sdsid, int index)
static boolean	SDgetdimscale(int dimid, byte[] data)
static boolean	SDgetdimscale(int dimid, java.lang.Object theData)
static boolean	SDgetdimstrs(int dimid, java.lang.String[] args, int len)
static boolean	SDgetfillvalue(int sdsid, byte[] fillValue)
static boolean	SDgetfillvalue(int sdsid, java.lang.Object[] theFillValue)
static boolean	SDgetinfo(int sdsid, java.lang.String[] name, int[] dimsizes, int[] args)
static boolean	SDgetrange(int sdsid, byte[] max, byte[] min)
static boolean	SDgetrange(int sdsid, double[] maxmin)
static int	SDidtoref(int sdsid)
static boolean	SDiscoordvar(int sdsid)
static boolean	SDisdimval_bwcomp(int dimid)
static boolean	SDisrecord(int sdsid)
static int	SDnametoindex(int sdid, java.lang.String name)
static boolean	SDreadattr(int id, int index, byte[] data)
static boolean	SDreadattr(int id, int index, java.lang.Object theData)
static boolean	SDreadchunk(int sdsid, int[] origin, byte[] theData)
static boolean	SDreadchunk(int sdsid, int[] origin, java.lang.Object theData)
static boolean	SDreaddata_double(int sdsid, int[] start, int[] stride, int[] count, double[] theData)
static boolean	SDreaddata_float(int sdsid, int[] start, int[] stride, int[] count, float[] theData)
static boolean	SDreaddata_int(int sdsid, int[] start, int[] stride, int[] count, int[] theData)
static boolean	SDreaddata_long(int sdsid, int[] start, int[] stride, int[] count, long[] theData)
static boolean	SDreaddata_short(int sdsid, int[] start, int[] stride, int[] count, short[] theData)
static boolean	SDreaddata(int sdsid, int[] start, int[] stride, int[] count, byte[] data)
static boolean	SDreaddata(int sdsid, int[] start, int[] stride, int[] count, java.lang.Object theData)
static int	SDreftoindex(int sdid, int ref)
static int	SDselect(int sdid, int index)
static boolean	SDsetaccesstype(int id, int accesstype)
static boolean	SDsetattr(int s_id, java.lang.String attr_name, int num_type, int count, byte[] values)
static boolean	SDsetattr(int s_id, java.lang.String attr_name, int num_type, int count, java.lang.Object theValues)
static boolean	SDsetblocksize(int sdsid, int block_size)
static boolean	SDsetcal(int sds_id, double cal, double cal_err, double offset, double offset_err, int number_type)
static boolean	SDsetchunk(int sdsid, HDFChunkInfo chunk_def, int flags)
static int	SDsetchunkcache(int sdsid, int maxcache, int flags)
static boolean	SDsetcompress(int id, int type, HDFCompInfo cinfo)
static boolean	SDsetdatastrs(int sds_id, java.lang.String label, java.lang.String unit, java.lang.String format, java.lang.String coordsys)
static boolean	SDsetdimname(int dim_id, java.lang.String dim_name)
static boolean	SDsetdimscale(int dim_id, int count, int number_type, byte[] data)
static boolean	SDsetdimscale(int dim_id, int count, int number_type, java.lang.Object theData)
static boolean	SDsetdimstrs(int dim_id, java.lang.String label, java.lang.String unit, java.lang.String format)
static boolean	SDsetdimval_comp(int dimid, int comp_mode)
static boolean	SDsetexternalfile(int sds_id, java.lang.String filename, int offset)
static boolean	SDsetfillmode(int sdsid, boolean fill_enable)
static boolean	SDsetfillmode(int sdsid, int fillmode)
static boolean	SDsetfillvalue(int sds_id, byte[] fill_val)
static boolean	SDsetfillvalue(int sds_id, java.lang.Object the_fill_val)
static boolean	SDsetnbitdataset(int id, int start_bit, int bit_len, int sign_ext, int fill_one)
static boolean	SDsetrange(int sdsid, byte[] max, byte[] min)
static boolean	SDsetrange(int sdsid, java.lang.Object max, java.lang.Object min)
static int	SDstart(java.lang.String filename, int accessmode)
static boolean	SDwritechunk(int sdsid, int[] origin, byte[] data)
static boolean	SDwritechunk(int sdsid, int[] origin, java.lang.Object theData)
static boolean	SDwritedata(int sdsid, int[] start, int[] stride, int[] count, byte[] data)
static boolean	SDwritedata(int sdsid, int[] start, int[] stride, int[] count, java.lang.Object theData)
static int	Vaddtagref(int vgroup_id, int tag, int ref)
static int	Vattach(int fid, int vgroup_ref, java.lang.String access)
static boolean	Vattrinfo(int id, int index, java.lang.String[] name, int[] argv)
static int	Vdeletetagref(int vgroup_id, int tag, int ref)
static void	Vdetach(int vgroup_id)
static void	Vend(int file_id)
static int	VFfieldesize(int vdata_id, int field_index)
static int	VFfieldisize(int vdata_id, int field_index)
static java.lang.String	VFfieldname(int vdata_id, int field_index)
static int	VFfieldorder(int vdata_id, int field_index)
static int	VFfieldtype(int vdata_id, int field_index)
static int	Vfind(int file_id, java.lang.String vgroup_name)
static int	Vfindattr(int id, java.lang.String name)
static int	Vfindclass(int file_id, java.lang.String vgclassname)
static int	Vflocate(int key, java.lang.String vgclassname)
static int	VFnfields(int vkey)
static boolean	Vgetattr(int id, int index, byte[] data)
static boolean	Vgetattr(int id, int index, java.lang.Object theData)
static void	Vgetclass(int vgroup_id, java.lang.String[] hdfclassname)
static int	Vgetid(int file_id, int vgroup_ref)
static void	Vgetname(int vgroup_id, java.lang.String[] hdfname)
static int	Vgetnext(int key, int ref)
static boolean	Vgettagref(int vgroup_id, int index, int[] tagref)
static int	Vgettagrefs(int vgroup_id, int[] tags, int[] refs, int arraysize)
static int	Vgetversion(int id)
static int	VHmakegroup(int file_id, int[] tag_array, int[] ref_array, int n_objects, java.lang.String vgroup_name, java.lang.String vgroup_class)
static int	VHstoredata(int file_id, java.lang.String fieldname, byte[] buf, int n_records, int data_type, java.lang.String vdata_name, java.lang.String vdata_class)
static int	VHstoredata(int file_id, java.lang.String fieldname, java.lang.Object thebuf, int n_records, int data_type, java.lang.String vdata_name, java.lang.String vdata_class)
static int	VHstoredatam(int file_id, java.lang.String fieldname, byte[] buf, int n_records, int data_type, java.lang.String vdata_name, java.lang.String vdata_class, int order)
static int	VHstoredatam(int file_id, java.lang.String fieldname, java.lang.Object buf, int n_records, int data_type, java.lang.String vdata_name, java.lang.String vdata_class, int order)
static boolean	Vinqtagref(int vgroup_id, int tag, int ref)
static boolean	Vinquire(int vgroup_id, int[] n_entries, java.lang.String[] vgroup_name)
static int	Vinsert(int vgroup_id, int v_id)
static boolean	Visvg(int vgroup_id, int vgroup_ref)
static boolean	Visvs(int vgroup_id, int vdata_ref)
static int	Vlone(int fid, int[] ref_array, int buffersize)
static int	Vnattrs(int id)
static int	Vnrefs(int key, int ref)
static int	Vntagrefs(int vgroup_id)
static int	VQueryref(int vkey)
static int	VQuerytag(int vkey)
static boolean	VSappendable(int vkey, int block_size)
static int	VSattach(int fid, int vdata_ref, java.lang.String access)
static boolean	VSattrinfo(int id, int index, int attr_index, java.lang.String[] name, int[] argv)
static void	VSdetach(int vdata_id)
static int	VSelts(int vdata_id)
static boolean	Vsetattr(int id, java.lang.String attr_name, int data_type, int count, byte[] data)
static boolean	Vsetattr(int id, java.lang.String attr_name, int data_type, int count, java.lang.Object theData)
static boolean	Vsetattr(int id, java.lang.String attr_name, int data_type, int count, java.lang.String values)
static boolean	Vsetclass(int vgroup_id, java.lang.String vgclassname)
static boolean	Vsetname(int vgroup_id, java.lang.String vgname)
static boolean	VSfdefine(int vdata_id, java.lang.String fieldname, int numbertype, int order)
static boolean	VSfexist(int vdata_id, java.lang.String fields)
static int	VSfind(int file_id, java.lang.String vdataname)
static int	VSfindattr(int id, int index, java.lang.String name)
static int	VSfindclass(int file_id, java.lang.String vgclass)
static int	VSfindex(int id, java.lang.String name, int[] findex)
static int	VSfnattrs(int id, int fnattrs)
static boolean	VSgetattr(int id, int index, int attr_index, byte[] data)
static boolean	VSgetattr(int id, int index, int attr_index, java.lang.Object theData)
static void	VSgetclass(int vdata_id, java.lang.String[] hdfclassname)
static int	VSgetfields(int vdata_id, java.lang.String[] fieldname)
static int	VSgetid(int file_id, int vdata_ref)
static int	VSgetinterlace(int vdata_id)
static void	VSgetname(int vdata_id, java.lang.String[] hdfname)
static int	VSgetversion(int vkey)
static boolean	VSinquire(int vdata_id, int[] iargs)
static boolean	VSinquire(int vdata_id, int[] iargs, java.lang.String[] sargs)
static boolean	VSisattr(int id)
static int	VSlone(int fid, int[] ref_array, int buffersize)
static int	VSnattrs(int id)
static boolean	VSQuerycount(int vdata_id, int[] n_records)
static boolean	VSQueryfields(int vdata_id, java.lang.String[] fields)
static boolean	VSQueryinterlace(int vdata_id, int[] interlace)
static boolean	VSQueryname(int vdata_id, java.lang.String[] vdata_name)
static int	VSQueryref(int vdata_id)
static int	VSQuerytag(int vdata_id)
static boolean	VSQueryvsize(int vdata_id, int[] vdata_size)
static int	VSread(int vdata_id, byte[] databuf, int nrecord, int interlace)
static int	VSread(int vdata_id, java.lang.Object theData, int nrecord, int interlace)
static int	VSseek(int vdata_id, int record)
static boolean	VSsetattr(int id, int index, java.lang.String attr_name, int data_type, int count, byte[] values)
static boolean	VSsetattr(int id, int index, java.lang.String attr_name, int data_type, int count, java.lang.Object theData)
static boolean	VSsetattr(int id, int index, java.lang.String attr_name, int data_type, int count, java.lang.String values)
static int	VSsetblocksize(int vdata_id, int blocksize)
static void	VSsetclass(int vdata_id, java.lang.String vdata_class)
static boolean	VSsetexternalfile(int vkey, java.lang.String filename, int offset)
static boolean	VSsetfields(int vdata_id, java.lang.String fields)
static boolean	VSsetinterlace(int vdata_id,