This file was created for the HDF4.2r0. release to store the documents that were in the release_notes directory of the main HDF4 source tree since the 4.0.alpha release. See also HISTORY.txt file for more information. File contains the following *.txt files: Fortran_APIs.txt JPEG.txt Pablo.txt comp_SDS.txt compile.txt compression.txt dimval.txt external_path.txt hdp.txt install_winNT.txt macintosh.txt mf_anno.txt mf_ris.txt new_functions.txt page_buf.txt sd_chunk_examples.txt vattr.txt windows.txt To search for a particular document use "filename.txt=" string, for example to seach for the beginning of the new_functions.txt file, use "new_functions.txt=" string ================================Fortran_APIs.txt============================ Problem: ======== In HDF4.0r1 and previous versions of HDF several Fortran routines declared a formal parameter as character*(*) or integer while the actual parameter was a character or a numeric type. This caused problems on some systems, such as VMS and T3D. With HDF 4.0r2 and later releases, these routines have either been replaced by 2 routines, one for character type parameters and another for numeric type parameters; or, a new routine has been added for char type parameters and the old routine is used for numeric type parameters only. Those routines that were replaced by two routines should be phased out in the future. However, in order to not break currently working applications they are still supported. New applications should use the new routines. Routines and parameters affected: ================================ 1. Write vdata Old: vsfwrit(vsid, databuf, n_rec, interlace) character*(*) databuf HDF4.0r2: Write to a vdata from a character buffer: vsfwrtc(vsid, cbuf, n_rec, interlace) character*(*) cbuf Write to a vdata from an integer buffer (for numeric values): vsfwrt(vsid, buf, n_rec, interlace) integer buf 2. Read vdata Old: vsfread(vsid, buf, n_recs, interlace) character*(*) buf HDF4.0r2: Read records into a character buffer: vsfrdc(vsid, cbuf, n_recs, interlace) character*(*) cbuf Read records into an integer buffer (for numeric values): vsfrd(vsid, buf, n_recs, interlace) integer buf 3. High level function for creating a single field single component vdata Old: vhfsd(f, field, buf, n, dtype, vsname, vsclass) integer buf HDF4.0r2: Store a simple character dataset in a vdata: vhfscd(f,field,cbuf,n,dtype,vsname,vsclass) character*(*) cbuf Store a simple numeric dataset in a vdata vhfsd(f, field, buf, n, dtype, vsname, vsclass) integer buf 4. High level function for creating a single field multi- component vdata Old: vhfsdm (f,field,buf,n,dtype,vsname,vsclass,order) integer buf HDF4.0r2: Store an aggregate char dataset in a vadata: vhfscdm (f,field,cbuf,n,dtype,vsname,vsclass,order) character*(*) cbuf Store a simple numeric dataset in a vdata vhfsdm(f,field,buf,n,dtype,vsname,vsclass,order) integer buf 5. Write GR image Old: mgwrimg(riid, start,stride,count,data) data HDF4.0r2: Write character type image data mgwcimg(riid, start, stride, count, cdata) character*(*) cdata Write numeric type image data mgwrimg(riid, start,stride,count,data) data 6. Read GR image Old: mgrdimg(riid,start,stride,count,data) integer data HDF4.0r2: Read character type image data mgrcimg(riid,start,stride,count,cdata) character*(*) cdata Read numeric type image data mgrdimg(riid,start,stride,count,data) data 7. Write LUT Old: mgwrlut(lutid,ncomp,data_type,interlace,nentries,data) data HDF4.0r2: Write character type palette: mgwclut(lutid,ncomp,data_type,interlace,nentries,cdata) character*(*) cdata Write numeric type palette: mgwrlut(lutid,ncomp,data_type,interlace,nentries,data) data 8. Read LUT Old: mgrdlut(lutid, data) data HDF4.0r2: Read char type palette: mgrclut(lutid,cdata) character*(*) cdata Read numeric type palette: mgrdlut(lutid, data) data 9. Set GR attribute Old: mgsattr(riid, name, nt, count, data) character*(*) data HDF4.0r2: Add char type attribute to a raster image mgscatt(riid, name, nt, count, cdata) character*(*) cdata Add a numeric attribute to a raster image mgsnatt(riid, name, nt, count, data) integer data 10. Get GR attribute Old: mggattr(riid, index, data) data HDF4.0r2: Get a char type attribute: mggcatt(riid, index, cdata) character*(*) cdata Get a numeric type attribute: mggnatt(riid, index, data) integer data 11. Write SDS data Old: sfwdata(sdsid,start,stride,end,values) values HDF4.0r2 Write char type SDS data sfwcdata(sdsid,start,stride,end,cvalues) character*(*) cvalues Write numeric type SDS data sfwdata(sdsid,start,stride,end,values) values 12. Read SDS data Old: sfrdata(sdsid,start,stride,end,values) values HDF4.0r2 Read char type SDS data sfrcdata(sdsid,start,stride,end,cvalues) character*(*) cvalues Read numeric type SDS data sfrdata(sdsid,start,stride,end,values) values 13. Add an attribute to an object in SD interface Old: sfsattr(id, name, nt, count, data) character*(*) data HDF4.0r2 Add a char type attribute to an object sfscatt(id, name, nt, count, cdata) character*(*) cdata Add a numeric type attribute to an object sfsnatt(id, name,nt, count,data) integer data 14. Get contents of an attribute Old: sfrattr(id, index, buf) buf HDF4.0r2: Get a char type attribute sfrcatt(id, index, cbuf) character*(*) cbuf Get a numeric type attribute sfrnatt(id, index, buf) buf 15. Set fill value Old: sfsfill(id, val) val HDF4.0r2 Set a char type fill value sfscfill(id, cval) character cval Set a numeric type fill value sfsfill(id, val) val 16. Get fill value Old: sfgfill(id, val) val HDF4.0r2 Get char type fill value sfgcfill(id, cval) character cval Get numeric type fill value sfgfill(id, val) val ============================================================================ ================================JPEG.txt==================================== Independant JPEG Group library Version 4.1b of the HDF-netCDF library uses v6a of the Independent JPEG Group (IJG) JPEG file access library. For most users of the HDF library, this will be completely transparent. For users who are integrating the HDF library into an existing application which uses the IJG's JPEG library, linking with the HDF library is now much simpler and should be completely painless. The JPEG library will need to be linked with user's applications when raster images are being used (whether they are compressed with JPEG or not). cc -o myprog.c -I \ Note: order of the libraries is important, the mfhdf library must be first and be followed by the hdf library. ============================================================================ ================================Pablo.txt=================================== Pablo Instrumentation of HDF =========================== This version of the distribution has support to create an instrumented version of the HDF library(libdf-inst.a). This library along with the Pablo performance data capture libraries can be used to gather data about I/O behavior and procedure execution times. More detailed documentation on how to use the instrumented version of the HDF library with Pablo can be found in the Pablo directory '$(toplevel)/hdf/pablo'. See the provided '$(toplevel)/hdf/pablo/README.Pablo' and the Postscript file '$(toplevel)/hdf/pablo/Pablo.ps'. At this time only an instrumented version of the core HDF library libdf.a can be created. Future versions will have support for the SDxx interface found in libmfhdf.a. Current interfaces supported are ANxx, GRxx, DFSDxx, DFANxx, DFPxx, DFR8xx, DF24xx, Hxx, Vxx, and VSxx. To enable the creation of an instrumented library the following section in the makefile fragment($(toplevel)/config/mh-) must be uncommented and set. # ------------ Macros for Pablo Instrumentation -------------------- # Uncomment the following lines to create a Pablo Instrumentation # version of the HDF core library called 'libdf-inst.a' # See the documentation in the directory 'hdf/pablo' for further # information about Pablo and what platforms it is supported on # before enabling. # You need to set 'PABLO_INCLUDE' to the Pablo distribution # include directory to get the files 'IOTrace.h' and 'IOTrace_SD.h'. #PABLO_FLAGS = -DHAVE_PABLO #PABLO_INCLUDE = -I/hdf2/Pablo/Instrument.HP/include After setting these values you must re-run the top-level 'configure' script. Make sure that your start from a clean re-build(i.e. 'make clean') after re-running the toplevel 'configure' script and then run 'make'. Details on running configure can be found in the section 'General Configuration/Installation - Unix' found in the top-level installation file '$(toplevel)/INSTALL'. ============================================================================ ================================comp_SDS.txt================================ Limitations of compressed SDS datasets Due to certain limitations in the way compressed datasets are stored, data which has been compressed is not completely writable in ways that uncompressed datasets are. The "rules" for writing to a compressed dataset are as follows: (1) Write an entire dataset that is to be compressed. I.e. build the dataset entirely in memory, then write it out with a single call. (2) Append to a compressed dataset. I.e. write to a compressed dataset that has already been written out by adding to the unlimited dimension for that dataset. (3) For users of HDF 4.1, write to any subset of a compressed dataset that is also chunked. Generally speaking, these mean that it is impossible to overwrite existing compressed data which is not stored in "chunked" form. This is due to compression algorithms not being suitable for "local" modifications in a compressed datastream. Please send questions about compression to the general HDF support e-mail address: help@hdfgroup.org Compression for HDF SDS The SDsetcompress and SDsetnbitdataset functions are used as higher-level routines to access the HCcreate function (HCcreate is described in the reference manual). SDsetnbitdataset allows for the storage of 1-32 bit integer values (instead of being restricted to 8, 16 or 32-bit sizes) in a scientific dataset. SDsetcompress can be used to compress a scientific dataset through the SD interface instead of dropping down to the lower-level H interface. N-bit SDS using SDsetnbitdataset: The interface to SDsetnbitdataset is described below: intn SDsetnbitdataset(sds_id,start_bit,bit_len,sign_ext,fill_one); int32 sds_id - The id of a scientific dataset returned from SDcreate or SDselect. intn start_bit - This value determines the bit position of the highest end of the n-bit data to write out. Bits in all number-types are counted from the right starting with 0. For example, in the following bit data, "01111011", bits 2 and 7 are set to 0 and all the other bits are set to one. intn bit_len - The number of bits in the n-bit data to write, including the starting bit, counting towards the right (i.e. lower bit numbers). For example, starting at bit 5 and writing 4 bits from the following bit data, "01111011", would write out the bit data, "1110", to the dataset on disk. intn sign_ext - Whether to use the top bit of the n-bit data to sign-extend to the highest bit in the memory representation of the data. For example, if 9-bit signed integer data is being extracted from bits 17-25 (nt=DFNT_INT32, start_bit=25, bit_len=9, see below for full information about start_bit & bit_len parameters) and the bit in position 25 is a 1, then when the data is read back in from the disk, bits 26-31 will be set to a 1, otherwise bit 25 will be a zero and bits 26-31 will be set to 0. This bit-filling takes higher precedence (i.e. is performed after) the fill_one (see below) bit-filling. intn fill_one - Whether to fill the "background" bits with 1's or 0's. The "background" bits of a n-bit dataset are those bits in the in-memory representation which fall outside of the actual n-bit field stored on disk. For example, if 5 bits of an unsigned 16-bit integer (in-memory) dataset located in bits 5-9 are written to disk with the fill_one parameter set to TRUE (or 1), then when the data is read back into memory at a future time, bits 0-4 and 10-15 would be set to 1. If the same 5-bit data was written with a fill_one value of FALSE (or 0), then bits 0-4 and 10-15 would be set to 0. This setting has a lower precedence (i.e. is performed first) than the sign_ext setting. For example, using the sign_ext example above, bits 0-16 and 26-31 will first be set to either 1 or 0 based on the fill_one parameter, and then bits 26-31 will be set to 1 or 0 based on bit-25's value. RETURNS - SUCCEED (0) or FAIL (-1) for success/failure. The corresponding FORTRAN function name is sfsnbit which takes the same parameters in the same order. For example, to store an unsigned 12-bit integer (which is represented unpacked in memory as an unsigned 16-bit integer), with no sign extension or bit filling and which starts at bit 14 (counting from the right with bit zero being the lowest) the following setup & call would be appropriate: intn sign_ext = FALSE; intn fill_one = FALSE; intn start_bit= 14; intn bit_len = 12; SDsetnbitdataset(sds_id,start_bit,bit_len,sign_ext,fill_one); Further reads and writes to this dataset would transparently convert the 16-bit unsigned integers from memory into 12-bit unsigned integers stored on disk. More details about this function can be found in the HDF library reference manual. Compressed SDS data using SDsetcompress: The SDsetcompress function call contains a subset of the parameters to the HCcreate function call described in compression.txt and performs the same types of compression. The interface to SDsetcompress is described below: intn SDsetcompress(sds_id,comp_type,c_info); int32 sds_id - The id of a scientific dataset returned from SDcreate or SDselect. int32 comp_type - The type of compression to encode the dataset with. The values are the same as for HCcreate: COMP_CODE_NONE - for no compression COMP_CODE_RLE - for RLE encoding COMP_CODE_SKPHUFF - for adaptive Huffman COMP_CODE_DEFLATE - for gzip 'deflation' comp_info *c_info - Information needed for the encoding type chosen. For COMP_CODE_NONE and COMP_CODE_RLE, this is unused and can be set to NULL. For COMP_CODE_SKPHUFF, the structure skphuff in this union needs information about the size of the data elements in bytes (see example below). For COMP_CODE_DEFLATE, the structure deflate in this union need information about "effort" to try to compress with (see example below). For more information about the types of compression see the compression.txt document in this directory. RETURNS - SUCCEED (0) or FAIL (-1) for success/failure. Similarly to the HCcreate function, SDsetcompress can be used to create compressed dataset or to compress existing ones. For example, to compress unsigned 16-bit integer data using the adaptive Huffman algorithm, the following setup and call would be used: comp_info c_info; c_info.skphuff.skp_size=sizeof(uint16); SDsetcompress(sds_id,COMP_CODE_SKPHUFF,&c_info); Further reads and writes to this dataset would transparently convert the 16-bit unsigned integers from memory into a compressed representation on disk. For example, to compress a dataset using the gzip deflation algorithm, with the maximum effort to compress the data, the following setup and call would be used: comp_info c_info; c_info.deflate.level=9; SDsetcompress(sds_id,COMP_CODE_DEFLATE,&c_info); Currently, SDsetcompress is limited to creating new datasets or appending new slices/slabs onto existing datasets. Overwriting existing data in a dataset will be supported at some point in the future. More details about this function can be found in the HDF library reference manual. ============================================================================ ================================compile.txt================================= COMPILING A PROGRAM Following are instructions for compiling an application program on the platforms supported by HDF, using the binaries that we provide. For Unix, the information on options to specify comes from the configuration files (mh-*) in the HDF source code (under ../HDF4.1r5/config). In general, you compile your program as shown below. If your platform is not specified in the section, "INSTRUCTIONS FOR SPECIFIC PLATFORMS", then use these instructions. If you are unable to compile your program on Unix, please check the configuration file for your platform for the correct options. C: cc -o .c -I\ -L -lmfhdf -ldf -ljpeg -lz or cc -o .c -I \ \ FORTRAN: f77 -o .f \ -L -lmfhdf -ldf -ljpeg -lz or f77 -o .f \ \ NOTE: The order of the libraries is important: libmfhdf.a first, followed by libdf.a, then libjpeg.a and libz.a. The libjpeg.a library is optional. INSTRUCTIONS FOR SPECIFIC PLATFORMS =================================== Cray: ---- C: cc -O -s -o .c \ -I \ -L -lmfhdf -ldf -ljpeg -lz FORTRAN: f90 -O 1 -o .f \ -L -lmfhdf -ldf -ljpeg -lz Dec Alpha/Digital Unix: ---------------------- C: cc -Olimit 2048 -std1 -o .c \ -I\ -L -lmfhdf -ldf -ljpeg -lz FORTRAN: f77 -o .f \ -L -lmfhdf -ldf -ljpeg -lz Dec Alpha/OpenVMS AXP: --------------------- To compile your programs, prog.c and prog1.for, with the HDF library, mfhdf.olb, df.olb, and libz.olb are required. The libjpeg.olb library is optional. cc/opt/nodebug/define=(HDF,VMS)/nolist/include= prog.c fort prog1.for link/nodebug/notraceback/exec=prog.exe prog.obj, prog1.obj, - mfhdf/lib - df/lib, libjpeg/lib, - libz/lib, sys$library:vaxcrtl/lib NOTE: The order of the libraries is important: mfhdf.olb first, followed by df.olb then libjpeg.olb and libz.olb. Exemplar: -------- C: cc -ext -nv -no .c \ -I \ -L -lmfhdf -ldf -ljpeg -lz FORTRAN: fc -sfc -72 -o .f \ -L -lmfhdf -ldf -ljpeg -lz NOTE: These instructions are for Convex/HP Exemplar machines running versions of the OS ealier than 10.x. For machines running version 10.x of HP-UX, follow the instructions for HP-UX 10.2. FreeBSD: ------- C: cc -ansi -Wall -pedantic -o .c \ -I \ -L -lmfhdf -ldf -ljpeg -lz FORTRAN: f77 -O -o .f \ -L -lmfhdf -ldf -ljpeg -lz HP-UX: ----- C: cc -Ae -s -o .c \ -I \ -L -lmfhdf -ldf -ljpeg -lz FORTRAN: f77 -s -o .f \ -L -lmfhdf -ldf -ljpeg -lz IRIX 6.x: -------- C: cc -ansi -n32 -mips3 -O -s -o .c \ -I\ -L -lmfhdf -ldf -ljpeg -lz FORTRAN: f90 -n32 -mips3 -O -s -o .f \ -L -lmfhdf -ldf -ljpeg -lz IRIX64 with 64-bit mode: ------------------------ C: cc -ansi -64 -mips4 -O -s -o .c \ -I\ -L -lmfhdf -ldf -ljpeg -lz FORTRAN: f77 -64 -mips4 -O -s -o .f \ -L -lmfhdf -ldf -ljpeg -lz IRIX64 with n32-bit mode: ------------------------- C: cc -ansi -n32 -mips4 -O -s -o .c \ -I \ -L -lmfhdf -ldf -ljpeg -lz FORTRAN: f77 -n32 -mips4 -O -s -o .f \ -L -lmfhdf -ldf -ljpeg -lz Linux: ----- C: gcc -ansi -D_BSD_SOURCE -o .c \ -I \ -L -lmfhdf -ldf -ljpeg -lz FORTRAN: g77 -o .f \ -L -lmfhdf -ldf -ljpeg -lz Solaris: ------- The -lnsl is necessary in order to include the xdr library. C: cc -Xc -xO2 -o .c \ -I\ -L -lmfhdf -ldf -ljpeg -lz \ -L/usr/lib -lnsl FORTRAN: f77 -O -o .f \ -L -lmfhdf -ldf -ljpeg -lz \ -L/usr/lib -lnsl Solaris_x86 (C only): -------------------- The -lnsl is necessary in order to include the xdr library. gcc -ansi -O -o .c \ -I \ -L -lmfhdf -ldf -ljpeg -lz \ -L/usr/lib -lnsl SP: --- C: xlc -qlanglvl=ansi -O -o .c \ -I \ -L -lmfhdf -ldf -ljpeg -lz FORTRAN: f77 -O -o .f \ -L -lmfhdf -ldf -ljpeg -lz T3E: --- C: cc -X m -s -o .c \ -I\ -L -lmfhdf -ldf -ljpeg -lz FORTRAN: f90 -X m -Wl"-Dpermok=yes" -Wl"-s" -o .f \ -L -lmfhdf -ldf -ljpeg -lz Windows NT/98/2000: ------------------ Using Microsoft Visual C++ version 6.x: Under Tools->Options, select the folder, Directories: Under "Show directories for", select "Include files". Add the following directories: C:\INCLUDE Under "Show directories for", select "Library files": Add the following directories: C:\LIB Under Project->Settings, select folder, Link: Add the following libraries to the beginning of the list of Object/Library Modules: hd415.lib hm415.lib (single-threaded release version) hd415d.lib hm415d.lib (single-threaded debug version) hd415m.lib hm415m.lib (multi-threaded release version) hd415md.lib hm415md.lib (multi-threaded debug version) ============================================================================ ================================compression.txt============================= Compression Algorithms and interface The low-level compression interface allows any data object to be compressed using a variety of algorithms. This is completely transparent to users once the data has been compressed initially - further data written to an object or read from it are compressed or decompressed internally to the library, without user intervention. (For information on compressing SDS datasets, see the ../release_notes/comp_SDS.txt file.) Currently only three compression algorithms are supported: Run-Length Encoding (RLE), adaptive Huffman, and an LZ-77 dictionary coder (the gzip 'deflation' algorithm). Plans for future algorithms include an Lempel/Ziv-78 dictionary coding, an arithmetic coder and a faster Huffman algorithm. The public interface for this routine is contained in the user-level function call, HCcreate. The interface to HCcreate is described below: int32 HCcreate(id,tag,ref,model_type,m_info,coder_type,c_info); int32 id; IN: the file id to create the data in (from Hopen) uint16 tag,ref; IN: the tag/ref pair of the data object which is to be compressed comp_model_t model_type; IN: the type of modeling to use, currently only COMP_MODEL_STDIO is supported, which indicates data is transferred in the same way as C I/O functions operate. model_info *m_info; IN: Information needed for the modeling type chosen Nothing needed for COMP_MODEL_STDIO, so NULL can be used. comp_coder_t coder_type; IN: the type of encoding to use from the following: COMP_CODE_NONE - for no compression COMP_CODE_RLE - for RLE encoding COMP_CODE_SKPHUFF - for adaptive Huffman COMP_CODE_DEFLATE - for gzip 'deflation' comp_info *c_info; IN: Information needed for the encoding type chosen For COMP_CODE_NONE and COMP_CODE_RLE, this is unused and can be set to NULL. For COMP_CODE_SKPHUFF, the structure skphuff in this union needs information about the size of the data elements in bytes (see examples below). For COMP_CODE_DEFLATE, the structure deflate in this union needs information about the "effort" to encode data with. Higher values of 'level' member indicate more compression effort. Values may range from 0 (minimal compression, fastest time) to 9 (maximum compression, slowest time). RETURNS Return an AID to the newly created compressed element, FAIL on error. HCcreate will compress an existing data object with the specified compression method, or it can create a new data object which will contain compressed data when it is written to. In either case, Hendaccess must be called to release the AID allocated by HCcreate. In the first two examples below the datasets already exist, in the final example the dataset is created by the HCcreate call. There is currently no FORTRAN equivalent for this function. More details about this function can be found in the HDF reference manual. The following example shows how to compress a scientific dataset data object (which is composed of multi-dimensional 32-bit integer data) using the adaptive Huffman encoding: { int32 aid; comp_info c_info; c_info.skphuff.skp_size=sizeof(int32); aid=HCcreate(file_id, DFTAG_SD, ref, COMP_MODEL_STDIO, NULL, COMP_CODE_SKPHUFF,&c_info); . . . . Hendaccess(aid); } The following example shows show to compress a raster image data object using the RLE algorithm: { int32 aid; aid=HCcreate(file_id, DFTAG_RI, ref, COMP_MODEL_STDIO, NULL, COMP_CODE_RLE,NULL); . . . . Hendaccess(aid); } The following example shows how to create a new data object whose data will compressed as it is written: { int32 aid; aid=HCcreate(file_id, DFTAG_RI, ref, COMP_MODEL_STDIO, NULL, COMP_CODE_RLE,NULL); . . Hwrite(aid,len,data); . . Hendaccess(aid); } ============================================================================ ================================dimval.txt================================== New Version of Dimension Values =============================== HDF4.0b1 and previous releases use a vgroup to represent a dimension. The vgroup has a single field vdata with class "DimVal0.0". The vdata has number of records, each record has a fake value from 0, 1, 2 ... , ( - 1 ). The fake values are not really required and take a lot of space. For applications that create large one dimensional array datasets the disk space taken by these fake values almost double the size of the HDF file. In order to omit the fake values, a new version of dimension vdata has been proposed. The new version uses the same structure as the old version. The only differences are that the vdata has only 1 record with value and that the vdata's class is "DimVal0.1" to distinguish it from the old version. However, existing tools and utilities which were compiled with the old version can't recognize the new dimensions of hdf files created using HDF4.0b2 or later version. This could cause problems for HDF users. To solve this problem, we are planning to implement a transitional policy: 1. Starting from HDF4.0b2 both versions of the dimension will be created by default. The old tools recognize the "DimVal0.0" dimension. 2. A new function SDsetdimval_comp (sfsdmvc) is added which can be called for a specific dimension to suppress the creation of the "DimVal0.0" vdata for that dimension. Users who store big 1D arrays should use this function to create "DimVal0.1" only. See the man page for sdsetdimval_comp.3. 3. A new function SDisdimval_bwcomp (sfisdmvc) is added which can be called to get the current compatibility mode of a dimension. See the man page for sdisdimval_bwcomp.3. 4. HDF4.0b2 and later version of HDF libraries can recognize both old and new versions of dimensions. This means old HDF files can always be read by new HDF libraries. 5. HDF4.1 will create only "DimVal0.1" by default and function SDsetdimval_comp should be called if "DimVal0.0" is also desired. The transition time period is ended. 6. Existing tools and utilities should be re-compiled with HDF4.0b2 or later releases during that transition time period. 7. A new utility will be written to remove redundant "DimVal0.0" from the files created during the transition time period. 8. A new utility will be written to convert "DimVal0.1" to "DimVal0.0" for special cases. Please send bug reports, comments and suggestions to help@hdfgroup.org. ============================================================================ ================================external_path.txt=========================== User Settable File Location for External Elements Users sometimes encounter situations (e.g., disk space shortage, different filesystem names) that the external file containing the data of the external element has to reside in a directory different from the one it was created. The user may set up symbolic pointers to forward the file locations but this does not work if the external filename is an absolute path type containing directory components that do not exist in the local system. A new feature is added such that an application can provide a list of directories for the HDF library to search for the external file. This is set by the function call HXsetdir or via the environment variable $HDFEXTDIR. See the man page HXsetdir(3) for details. A similar feature is also added to direct the HDF library to create the external file of a _new_ external element in the given directory. An example for the need of this feature is that an application wants to create multiple external element files with certain naming conventions (e.g., Data950101, Data950102) while all these files share a common parent directory (project123/DataVault). Different users will have a different choice of the common parent directory. This can be set by the function call HXsetcreatedir or the environment variable $HDFEXTCREATEDIR. See the man page for HXsetcreatedir (1) for detail. ============================================================================ ================================hdp.txt===================================== hdp -- HDF dumper NAME hdp - HDF dumper SYNOPSIS hdp [hdp options] hdp command [command options] DESCRIPTION hdp is a command line utility designed for quick display of contents and data of HDF3.3 objects. It can list the contents of hdf files at various levels with different details. It can also dump the data of one or more specific objects in the file. HDP OPTIONS Currently, there is only one option. -H Display usage information about the specified command. If no command is specified, -H lists all available commands. HDP COMMANDS hdp currently has two types of commands: list and dump. Other types of commands such as those for editing may be added in the future. hdp list lists contents of files in hdp dumpsds displays data of NDGs and SDGs in the listed files. hdp dumpvd displays data of vdatas in the listed files. hdp dumpvg displays data of objects in vgroups in the listed files. hdp dumprig displays data of RIGs in the listed files. hdp dumpgr displays data of general RIGs in the listed files. HDP COMMAND OPTIONS (Note: options preceeded by an * have not yet been implemented.) hdp list [format options] [content ops] [filter ops] [order ops] -------------------------------------------------------------------------- Format options decide how the info of objects will be presented on the screen. -s (short format) under each tag #, all ref's of that tag are listed in one or more lines, same as the output of hdfls. (default) -l (long format) one object per line. Each line contains tag-name, tag/ref and the index of this tag in the file.(e.g., the ith NDG in the file). -d debug format, one object per line. Each line contains tag_name, tag/ref, index, offset, and length, same as the output of hdfls -d. no tagname tag ref index/tag offset length -- ------- --- --- --------- ------ ------ 1 DFTAG_NT 106 2 1 2 DFTAG_SD 701 3 1 ... Content options allow contents be displayed. -n display the name or label of the object, if there is any. -n puts you in -l format automatically. -c display the class of the object, if there is any. -l format. -a display description of the object, if there is any. -l format. Filter options select certain type of objects to display, default is all. -g display groups only. Objects which do not belong to any group will not be displayed. Nested groups will be displayed in tree format. -t display objects with specified tag number . e.g. 720 for NDG. -t display objects with specified tag name. Order options sort the output list in different orders. -ot by tag # (default) -of by the order in file DDlist. -og by group -on by name(label) hdp dumpsds [filter ops] [contents ops] [output ops] -------------------------------------------------------------------- Filter options specify which SDS to dump. -i dump SDS's with indices specified in ; indices correspond to the order of the SDS in the file -r dump SDS's with reference numbers specified in -n dump SDS's with names specified in -a dump all SDS's in the file. (default) Options -i, -r, and -n can be used inclusively to specify different SDS's. Content options -v display everything including all annotations (default) -h header only, no annotation for elements or data -d data only, no tag/ref These options are exclusive. Output options -o specify as output file name -b binary output -x ascii text output (default) Options -b and -x are exclusive, but each can be used with option -o. Format options -c print space characters as they are, not \digit -g do not print data of file (global) attributes -l do not print data of local attributes -s do not add carriage return to a long line - dump as a stream Options in this category can be used inclusively. Note: Any combination of an option from each of the categories can be used as long as the criteria of that category are met. hdp dumpvd [filter ops] [contents ops] [output ops] -------------------------------------------------------------------- Filter options specify which vdata to dump. -i dump vdatas with indices in ; indices correspond to the order of the vdatas in the files -r dump vdatas with reference numbers specified in -n dump vdatas with names specified in -c dump vdatas with classes specified in -a dump all vdatas in the file. (default) Content options -v display everything including all annotations (default) -h header only, no annotation for elements or data -d data only, no tag/ref -f dump data of specified fields Output options -o specify fn as output file name * -b binary file -t text ascii file (default) hdp dumpvg [filter ops] [contents ops] [output ops] -------------------------------------------------------------------- Filter options specify which vgroups to dump. -i dump vgroups with indices specified in ; indices correspond to the order of the vgroups specified in the files -r dump vgroups with reference numbers specified in -n dump vgroups with names specified in -c dump vgroups with classes specified in -a dump all vgroups in the file. (default) Content options -v display everything including all annotations (default) -h header only, no annotation for elements or data -d data only Output options -o specify fn as output file name * -b binary file -t text ascii file (default) Note: Unless the "-d" option is specified, a graphical representation of the file will be given after the data has been displayed. hdp dumprig [filter ops] [contents ops] [output ops] -------------------------------------------------------------------- Filter options specify which RIG to dump. -i dump RIGs with indices specified in ; indices correspond to the order of the RIGs specified in the files -r dump RIGs with reference numbers specified in -a dump all RIGs in the file. (default) -m 8|24 dump the RIGs of 8-bit or 24-bit. By default all RIGs in the file will be dumped Content options -v display everything including all annotations (default) -h header only, no annotation for elements or data -d data only Output options -o specify fn as output file name -b binary file -t text ascii file (default) hdp dumpgr [filter ops] [contents ops] [output ops] -------------------------------------------------------------------- Filter options specify which general RIGs to dump. -i dump general RIG's with indices specified in ; indices correspond to the order of the RIG in the file -r dump general RIG's with reference numbers specified in -n dump general RIG's with names specified in -a dump all general RIG's in the file. (default) Content options -v display everything including all annotations (default) -h header only, no annotation for elements or data -d data only, no tag/ref Output options -o specify fn as output file name -b binary file -t ascii text file (default) Note: any combination of an option from each of the three categories can be used; but no more than one option from one category is allowed. ============================================================================ ================================install_winNT.txt=========================== Install HDF4.1 Release 2 on Windows NT and Windows 95, and Alpha NT. Since Windows NT, Windows '95 (Chicago) and Windows 3.1 (with the Win 32s extensions) all are designed to run the same 32-bit code, our decision is to support only 32-bit libraries and code on the MS-Windows platform. We are not planning on supporting any 16-bit versions in the foreseeable future. The instructions which follow assume that you will be using one of the 'zip' files that we provide, either the binary code release (hdf41r2.zip) or the source code release (hdf41r2s.zip). In building HDF from source code you may select between two build environment options depending on your application and environment needs. Each option has it's own zip file: Option I, (select Win32nof.zip) Test and Utility configuration : HDF library, tests, and utilities, no fortran, available for Win32 Intel platform only. Option II, (select Win32full.zip) Full configuration : HDF library, tests, and utilities, with fortran This version has been built and tested using DEC Visual Fortran on both the Win32 Intel platform and the Win32 Alpha platform. Building from Binary Code Release (hdf41r2.zip) =============================================== To install the HDF, JPEG, zlib and mfhdf libraries and utilities, it is assumed that you have done the following: 1. Create a directory structure to unpack the library. For example: c:\ (any drive) MyHDFstuff\ (any folder name) 2. Copy the binary archive (HDF41r2.zip) to that directory and unpack it by running WinZip on HDF41r2.zip (the binary archive). This should create a directory called 'HDF41r2' which contains the following files and directories. c:\MyHDFstuff\HDF41r2\lib ( Debug and Release versions of HDF libraries ) c:\MyHDFstuff\HDF41r2\include ( HDF include files ) c:\MyHDFstuff\HDF41r2\bin ( HDF utilities files ) c:\MyHDFstuff\HDF41r2\release_notes ( release notes ) c:\MyHDFstuff\HDF41r2\install_NT_95 ( this file) 3. If you are building an application that uses the HDF library the following locations will need to be specified for locating header files and linking in the HDF libraries: C:\MyHDFstuff\HDF41r2\lib C:\MyHDFstuff\HDF41r2\include Building from Source Code Release (hdf41r2s.zip) =============================================== STEP I: Preconditions To build the HDF, JPEG, zlib and mfhdf libraries and utilities, it is assumed that you have done the following: 1. Installed MicroSoft Developer Studio, and Visual C++ 5.0. Visual Fortran 5.0 is needed if you are going to build the full HDF Library with Fortran support. 2. Set up a directory structure to unpack the library. For example: c:\ (any drive) MyHDFstuff\ (any folder name) 3. Copy the source distribution archive to that directory and unpack it using the appropriate archiver options to create a directory hierarchy. Run WinZip on HDF41r2s.zip (the entire source tree). This should create a directory called 'HDF41r2' which contains several files and directories. ( Note for those using the Win32 Alpha platform: If you do not have a Winzip utility for your Alpha system you can download the needed executables from: http://www.cdrom.com/pub/infozip ) STEP II: Select Installation type and Build. You may select one of 2 ways to build the HDF library and utilities, depending on your environment and application needs. Option I, (select Win32nof.zip) Test and Utility configuration : HDF library, tests, and utilities, no fortran Option II, (select Win32full.zip) Full configuration : HDF library, tests, and utilities, with fortran STEP III: Follow Instructions for Option I, or II INSTRUCTIONS FOR OPTION I, TEST AND UTILITY INSTALLATION, NO FORTRAN (Win32 Intel platform only) *** Builds hdf library, hdf utilities, *** test programs and batch files. No fortran code. 1. You will use Win32nof.zip Unpack dev\win32nof.zip in directory dev\ Run WinZip on c:\myHDFstuff\HDF41r2\Win32nof.zip This archive contains a Developer Studio project "dev" and two batch files. 40 project files (*.dsp files) will be created when Win32nof.zip is expanded. 2. Invoke Microsoft Visial C++ 5.0, go to "File" and select "Open Workspace" option. Then open c:\myHDFstuff\HDF41r2\dev.dsw workspace. 3. Select "Build", then Select "Set Active Configuration". Select "dev -- Win32Debug" as active configuration. Select "Build" and "Build dev.exe" to build the Debug version of the HDF41r2 tree. 4. Select "Build", then Select "Set Active Configuration". Select "dev -- Win32Release" as active configuration. Select "Build" and "Build dev.exe" to build the Release version of the HDF41r2 tree. 5. In command prompt window run the test batch file win32noftst.bat in directory HDF41r2\. 6. If all tests passed, run the installation batch file win32ins.bat in directory HDF41r2\. Commands in this file will create subdirectories bin\, include\ and lib\ in HDF41r2\. The bin dirctory will contain the HDF utilities, the include directory will contain header files, and the lib directory will contain: jpeg.lib - JPEG Library jpegd.lib - JPEG Library with DEBUG option libsrc.lib - multi-file SDS Inteface routines libsrcd.lib - multi-file SDS Inteface routines with DEBUG option src.lib - multi-file Vdata Interface Vgroup Interface AN Interface GR Interface routines srcd.lib - multi-file Vdata Interface Vgroup Interface AN Interface GR Interface routines with DEBUG option xdr.lib - XDR Library xdrd.lib - XDR Library with DEBUG option zlib.lib - GNU Zip Library zlibd.lib - GNU Zip Library with DEBUG option INSTRUCTIONS FOR OPTION II, FULL INSTALLATION WITH FORTRAN *** Builds the hdf library, hdf utility programs, test programs, *** and batch files. Includes fortran source code to be *** compiled with Digital Visual Fortran on either a Win32 Intel *** machine or a Win32 Alpha machine. 1. Unpack HDF41r2\Win32full.zip in directory HDF41r2\. 2. Invoke Microsoft Visial C++ 5.0, go to "File" and select "Open Workspace" option. Then open c:\myHDFstuff\HDF41r2\dev.dsw workspace. 3. Select "Build", then Select "Set Active Configuration". Select as the active configuration "dev -- Win32Debug" if you have a Win32 Intel processor OR select "dev-Win32AlphaDbg" if you have a Win32 Alpha processor. Select "Build" and "Build dev.exe" to build the Debug version of the HDF41r2 tree. You will see that Digital Visual Fortran compiler is invoked by Visual C++ Development environment in compiling the fortran code. 4. Select "Build", then Select "Set Active Configuration". Select as the active configuration"dev -- Win32Release" if you have a Win32 Intel processor OR select "dev-Win32AlphaRel" if you have a Win32 Alpha processor. Select "Build" and "Build dev.exe" to build the Release version of the HDF41r2 tree. 5. In command prompt window run the test batch file which resides in the HDF41r2 directory. Run win32tst.bat if you have a Win32 Intel platform OR run win32ALPHAtst.bat if you have the Win32 Alpha platform. 6. If all tests passed, run the installation batch file which resides in the HDF41r2 directory Run win32ins.bat if you have a Win32 Intel platform OR run win32ALPHAins.bat if you have a Win32 Alpha platform. Commands in these files will create subdirectories bin\, include\ and lib\ in HDF41r2\. The bin dirctory will contain the HDF utilities, include directory will contain header files, and the lib directory will contain: jpeg.lib - JPEG Library jpegd.lib - JPEG Library with DEBUG option libsrc.lib - multi-file SDS Inteface routines libsrcd.lib - multi-file SDS Inteface routines with DEBUG option src.lib - multi-file Vdata Interface Vgroup Interface AN Interface GR Interface routines srcd.lib - multi-file Vdata Interface Vgroup Interface AN Interface xdrd.lib - XDR Library with DEBUG option zlib.lib - GNU Zip Library zlibd.lib - GNU Zip Library with DEBUG option STEP IV: BUILDING AN APPLICATION USING THE HDF LIBRARY - SOME HELPFUL POINTERS ===================================================================== If you are building an application that uses the HDF library the following locations will need to be specified for locating header files and linking in the HDF libraries: \lib \include where may be C:\myHDFstuff\dev or C:\MyHDFstuff\HDF41r2\ Please refer to the \release_notes\compile.txt file for more information on compiling an application with the HDF libraries. MORE HELPFUL POINTERS ===================== (as described in terms of installing the nofortran configuration) Here are some notes that may be of help if you are not familiar with using the Visual C++ Development Environment. Project name and location issues: The files in Win32nof.zip must end up in the HDF41r2\ directory installed by HDF41r2s.zip If you must install dev.dsw and dev.dsp in another directory, relative to HDF41r2\ , you will be asked to locate the above 5 sub-project files, when you open the project dev.dsw. If you want to rename dev (the entire project), you will need to modify two files dev.dsw and dev.dsp as text (contrary to the explicit warnings in the files). You can also modify dev.dsw and dev.dsp as text, to allow these 2 files to be installed in another directory. Settings... details: If you create your own project, the necessary settings can be read from the dev.dsp file(as text), or from the Project Settings in the Developer Studio project settings dialog. Project Settings C/C++ Category PreProcessor Code Generation Use run-time Library These are all set to use Single-Threaded. or Single-Threaded debug. ============================================================================ ================================macintosh.txt=============================== Fortner Software LLC ("Fortner") created the reference implementation for Macintosh of the HDF 4.1r3 library, providing C-language bindings to all 4.1r3 features. The Macintosh reference implementation of the HDF 4.1r3 library was implemented and tested on a PowerMac Model 7600/120 running MacOS 8.5.1 using Metrowerks CodeWarrior Pro1. The library has also been run on a PowerMac G3. Fortner cannot be certain that the libraries will run on other versions of Macintoshes (or clones) or MacOS versions, or when built using other development tools. (In particular, this Macintosh implementation has not addressed use with non-PowerPC versions of Macintosh [i.e., 680x0-based Macintoshes]). Migrating the Macintosh reference implementation to other development and/or run-time environments is the responsibility of the library user. First-time HDF users are encouraged to read the FAQ in this release for more information about HDF. Users can also look at the home page for HDF at: https://www.hdfgroup.org/ Please send questions, comments, and recommendations regarding the Macintosh version of the HDF library to: help@hdfgroup.org ============================================================================ ================================mf_anno.txt================================= Annotation access through the Multi-file Annotation Interface(ANxxx) ==================================================================== These routines are for accessing file labels, file descriptions, data labels and data descriptions(i.e. all are annotations). General access requires the routines Hopen() and ANstart() to be called first and the last call to be ANend() and Hclose() which ends annotation handling on the file and closes the file. Basic annotation manipulation involes dealing with handles(ann_id's) foreach annotation and annotation interface handle(an_id). NOTES: Note that the annotation types are enumerated. TYPE here refers to file/data label/description types They are AN_FILE_LABEL, AN_FILE_DESC, AN_DATA_LABEL, AN_DATA_DESC The tag/ref refers to data tag/ref. AN_DATA_LABEL = 0, /* Data label */ AN_DATA_DESC = 1, /* Data description */ AN_FILE_LABEL = 2, /* File label */ AN_FILE_DESC = 3 /* File description */ In C-code you need to declare the annotation type using the enumerated type defintion. e.g. C-code fragment to write a File label #include "hdf.h" ... .. char fname[10] = {"ann.hdf"}; char *file_lab[1] = {"File label #1: This is a file label"}; int32 file_id; /* file id */ int32 an_id; /* annotation interface id */ int32 ann_id; /* annotation id */ ann_type myanntype; /* annotation type */ /* Start Annotation inteface and create file */ file_id = Hopen(fname, DFACC_CREATE,0); an_id = ANstart(file_id); /* Set annotation type to file label */ myanntype = AN_FILE_LABEL; /* Create id for file label */ ann_id = ANcreatef(an_id, myanntype); /* Write file label */ ANwriteann(ann_id, file_lab[0], HDstrlen(file_lab[0])); /* end access to file label */ ANendaccess(ann_id); /* end access to file and close it*/ ANend(an_id); Hclose(file_id); .... ... NOTE: You could also call ANcreatef() like this ANcreatef(an_handle, AN_FILE_LABEL); without using the intermediate variable. ROUTINES NEEDED: ================ Hopen - Opening the file, returns a file handle Hclose - Close the file. NEW ROUTINES: =============== ANstart - open file for annotation handling, returns annotation interface id ANfileinfo - get number of file/data annotations in file. Indices returned are used in ANselect() calls. ANend - end access to annotation handling on file ANcreate - create a new data annotation and return an id(ann_id) ANcreatef - create a new file annotation and return an id(ann_id) ANselect - returns an annotation id(ann_id) from index for a particular annotation TYPE. This id is then used for calls like ANwriteann(), ANreadann(), ANannlen(),..etc ANnumann: - return number of annotations that match TYPE/tag/ref ANannlist: - return list of id's(ann_id's) that match TYPE/tag/ref ANannlen: - get length of annotation given id(ann_id) ANreadann: - read annotation given id(ann_id) ANwriteann: - write annotation given id(ann_id) ANendaccess - end access to annotation using id(ann_id) Routines: ---------- C: /* ------------------------------- ANstart -------------------------------- NAME ANstart -- open file for annotation handling USAGE int32 ANstart(file_id) int32 file_id; IN: file id RETURNS An annotation interface ID or FAIL DESCRIPTION Start annotation handling on the file and return an interface id. Fortran: afstart(file_id) /*------------------------------- ANfileinfo ---------------------------- NAME ANfileinfo PURPOSE Report high-level information about the ANxxx interface for a given file. USAGE intn ANfileinfo(an_id, n_file_label, n_file_desc, n_data_label, n_data_desc) int32 an_id; IN: annotation interface ID int32 *n_file_label; OUT: the # of file labels int32 *n_file_desc; OUT: the # of file descriptions int32 *n_data_label; OUT: the # of data labels int32 *n_data_desc; OUT: the # of data descriptions RETURNS SUCCEED/FAIL DESCRIPTION Reports general information about the number of file and data annotations in the file. This routine is generally used to find the range of acceptable indices for ANselect calls. Fortran: affileinfo(an_id, num_flabel, num_fdesc, num_dlabel, num_ddesc) /* -------------------------------- ANend --------------------------------- NAME ANend -- close annotation handling on a file USAGE int32 ANend(an_id) int32 an_id; IN: annotation interface ID for the file RETURNS SUCCEED / FAIL DESCRIPTION Closes annotation handling on the gvien annotation interface id. Fortran: afend(an_id) /* ------------------------------ ANcreate ---------------------------- NAME ANcreate - create a new data annotation and return an id USAGE int32 ANcreate(an_id, tag, ref, type ) int32 an_id; IN: annotation interface ID uint16 tag; IN: tag of item to be assigned annotation uint16 ref; IN: reference number of itme to be assigned ann ann_type type: IN: AN_DATA_LABEL for data labels, AN_DATA_DESC for data descriptions, RETURNS An ID to an annotation which can either be a label or description DESCRIPTION Creates a data annotation, returns an 'ann_id' to work with the new annotation which can either be a label or description. Fortran: afcreate(an_id, tag, ref, type) /* ------------------------------ ANcreatef ---------------------------- NAME ANcreatef - create a new file annotation and return an id USAGE int32 ANcreatef(an_id, type ) int32 an_id; IN: annotation interface ID ann_type type: IN: AN_FILE_LABEL for file labels, AN_FILE_DESC for file descritpions. RETURNS An ID to an annotation which can either be a file label or description DESCRIPTION Creates a file annotation, returns an 'ann_id' to work with the new file annotation which can either be a label or description. Fortran: afcreatef(an_id, type) /* ------------------------------- ANselect ------------------------------- NAME ANselect -- get an annotation ID from index of 'type' USAGE int32 ANselect(an_id, index, type) int32 an_id; IN: annotation interface ID int32 index; IN: index of annottion to get ID for ann_type type: IN: AN_DATA_LABEL for data labels, AN_DATA_DESC for data descriptions, AN_FILE_LABEL for file labels, AN_FILE_DESC for file descritpions. RETURNS An ID to an annotation type which can either be a label or description DESCRIPTION The position index is ZERO based Fortran: afselect(an_id, index, type) /*------------------------------- ANnumann --------------------------------- NAME ANnumann -- find number of annotation of 'type' that match the given element tag/ref USAGE intn ANnumann(an_id, type, elem_tag, elem_ref) int32 an_id; IN: annotation interface ID int type: IN: AN_DATA_LABEL for data labels, AN_DATA_DESC for data descriptions, AN_FILE_LABEL for file labels, AN_FILE_DESC for file descritpions. uint16 elem_tag,: IN: tag of item of which this is annotation uint16 elem_ref; IN: ref of item of which this is annotation RETURNS number of annotation found if successful and FAIL (-1) otherwise DESCRIPTION Find number of annotation of 'type' for the given element tag/ref pair. Here an element is either a file label/desc or data label/desc. Fortran: afnumann(an_id, type, tag, ref) /*-------------------------------------------------------------------------- NAME ANannlist -- generate list of annotation ids of 'type' that match the given element tag/ref USAGE intn ANannlist(an_id, type, elm_tag, elem_ref, ann_list[]) int32 an_id; IN: annotation interface ID ann_type type: IN: AN_DATA_LABEL for data labels, AN_DATA_DESC for data descriptions, AN_FILE_LABEL for file labels, AN_FILE_DESC for file descritpions. uint16 elem_tag,: IN: tag of element of which this is annotation uint16 elem_ref; IN: ref of element of which this is annotation int32 ann_list[]; OUT: array of ann_id's that match criteria. RETURNS number of annotations ids found if successful and FAIL (-1) otherwise DESCRIPTION Find and generate list of annotation ids of 'type' for the given element tag/ref pair Fortran: afannlist(an_id,type, tag, ref, alist[]) /*-------------------------------------------------------------------------- NAME ANannlen -- get length of annotation givne annotation id USAGE int32 ANannlen(ann_id) int32 ann_id; IN: annotation id RETURNS length of annotation if successful and FAIL (-1) otherwise DESCRIPTION Get the length of the annotation specified. Fortran: afannlen(ann_id) /*-------------------------------------------------------------------------- NAME ANwriteann -- write annotation given ann_id USAGE intn ANwriteann(ann_id, ann, ann_len) char *ann_id; IN: annotation id char *ann; IN: annotation to write int32 ann_len; IN: length of annotation RETURNS SUCCEED (0) if successful and FAIL (-1) otherwise DESCRIPTION Checks for pre-existence of given annotation, replacing old one if it exists. Writes out annotation. Fortran: afwriteann(ann_id, ann, annlen) /*-------------------------------------------------------------------------- NAME ANreadann -- read annotation given ann_id USAGE intn ANreadann(ann_id, ann, maxlen) int32 ann_id; IN: annotation id (handle) char *ann; OUT: space to return annotation in int32 maxlen; IN: size of space to return annotation in RETURNS SUCCEED (0) if successful and FAIL (-1) otherwise DESCRIPTION Gets tag and ref of annotation. Finds DD for that annotation. Reads the annotation, taking care of NULL terminator, if necessary. Fortran: afreadann(ann_id, ann, maxlen) /* ----------------------------------------------------------------------- NAME ANendaccess -- end access to an annotation given it's id USAGE intn ANendaccess(ann_id) int32 an_id; IN: annotation id RETURNS SUCCEED or FAIL DESCRIPTION Terminates access to an annotation. Fortran: afendaccess(ann_id) ============================================================================ ================================mf_ris.txt================================== The multi-file RIS interface ============================= Contents: Introduction How to access files and images in the new interface "Name = value" attributes in the new interface Dealing with annotations in the new interface Work not yet completed, bugs, limitations A listing or routines Descriptions of GR routines File level interface Dataset Manipulation ID/Ref/Index Functions Interlace Request Functions LUT/Palette I/O Functions Special Element Functions Attribute Functions Introduction ============ The new Generic Raster (GR) interface provides a set of functions for manipulating raster images of all kinds. This new interface is meant to replace the older RIS8 and RIS24 interfaces, although these older interfaces will continue to be supported. Generic raster images are composed of "pixels" which can have multiple components, including but not limited to 8-bit unsigned integers. Each image can have multiple palettes associated with it and other 'attributes' in the same "name=value" style as the SD*() routines have. The new GR interface was motivated by a number of needs: o The need for multi-file, multi-object access to raster images, allowing users to keep open more than one file at a time, and to "attach" more than one raster image at a time. o A need to further integrate the netCDF data-model with the HDF data-models. o A need for a more general framework for attributes within the RIS data-model (allowing 'name = value' style metadata). o A need to be able to access subsamples and subsets of images. IMPORTANT: The added functionality represented by this new interface has necessitated a change in how raster images are physically represented on disk. As a result programs using the old single-file RIS interfaces will only be able to read the data out of files produced by the new interface. The metadata / attributes will not be accessible. The following chart represents what can be done with the various interfaces available in HDF 4.0b1: old RIS-API new GR-API old RIS CRW CRW HDF files new RIS r CRW HDF files 'R' means read, 'W' means write and 'C' means create. Entries with dashes '-' represent functionality which has not yet been implemented. 'r' stands for the ability to only read the data, not the metadata. Work not yet completed, bugs, limitations =========================================== Misc. stuff left to do: Deal with special elements for images. GRrename for images. GRsetflags to suppress writing fill data and to suppress fillvalue attr. Features not supported: Full support for multiple palettes with each RI. Support for named palettes with each RI. Support for palettes with non-standard formats. Deletion of attributes or images (would require changing the way index numbers are handled) Other limitations: Currently the following design limitations are still in place: 1 - Cannot have pixels or palette entries which contain mixed variable types, i.e. all the pixel/palette components must be of the same number type. 2 - Currently all the components must be of valid HDF number types, fractional bytes (i.e. 6-bit components) or 'plain' multiple byte values are not handled, although they can be packed into the next larger sized number type in order to hold them. How to access files and images in the new interface ====================================================== Here are the steps involved in accessing images in the new interface: 1. Open or create the file using Hopen. This provides you with a file ID to be used in step 2. 2. Activate the GR interface for the file with the file ID obtained from step 1, using GRstart. This provides you with a GR interface ID (GR ID). 3. Optionally obtain information about the raster images in the file and global GR attributes using GRfileinfo. Use the GR ID from step 2 to refer to the image file. 4. Optionally find the index of a raster image, by name using GRnametoindex, or by reference number using GRreftoindex. 5. Select for access an image with a given index, using GRselect for each image. Each call to GRselect returns a raster image ID (RI ID) for subsequent accesses involving the corresponding image. 5. Access the image by its RI ID, using routines such as GRgetiminfo (to get information about the image) and GRreadimage (to read all or part of an image). 6. Terminate access to a given image using GRendaccess. 7. Terminate access to the GR interface for the file, using GRend. 8. Close the file using Hclose. Notice that in the GR interface, images are identified in several ways. Before an image is accessible ("attached"), it is identified by index, name, and reference number. The index describes the relative position of the image in the file. The name is a character string associated with the image, and the reference number is a unique integer. An image's name is assigned by the program when it is created, and the reference number is assigned by the HDF library when it is created. After an image is attached , it is identified by an raster image identifier, or RI ID. The following code fragment illustrates the steps involved in accessing the image in a file and printing information about them. /* Open the file and initialize the GR interface */ hdf_file_id=Hopen(TESTFILE,DFACC_RDWR,0); grid=GRstart(hdf_file_id); /* Obtain information about the images in the file */ GRfileinfo(grid,&n_datasets,&n_attrs); /* Attach to each image and print information about it */ for(i=0; i) must be uncommented and set. # ------------ Macros for Shared Memory File Buffer Pool(fmpool) ------ # Uncomment the following lines to enable shared memory file buffer pool # version of the HDF core library libdf.a. Please read the # documentation before enabling this feature. #FMPOOL_FLAGS = -DHAVE_FMPOOL After setting these values you must re-run the toplevel 'configure' script. Make sure that your start from a clean re-build(i.e. 'make clean') after re-running the toplevel 'configure' script and then run 'make'. Details on running configure can be found in the section 'General Configuration/Installation - Unix' in the installation file '$(toplevel)/INSTALL'. The file caching version of libdf.a is automatically tested when the regular HDF and netCDF tests are run. The page caching version has been tested only on a few UNIX platforms and is NOT available for the Macintosh ,IBM-PC(Windows NT/95) or VMS. ****************************** Beta Version ********************************* ============================================================================ ================================sd_chunk_examples.txt======================= /************************************************************************** File: sd_chunk_examples.c Examples for writing/reading SDS with Chunking and Chunking w/ Compression. - Sample C-code using SDS chunking routines. - No real error checking is done and the value of 'status' should be checked for proper values. 5 Examples are shown, 1 for 2-D array, 3 for 3-D arrays and 1 for 2-D array with compression.. Example 1. 2-D 9x4 SDS of uint16 with 3x2 chunks Write data using SDwritechunk(). Read data using SDreaddata(). Example 2. 3-D 2x3x4 SDS of uint16 with 2x3x2 chunks Write data using SDwritedata(). Read data using SDreaddata(). Example 3. 3-D 2x3x4 SDS of uint16 with 1x1x4 chunks Write data using SDwritechunk(). Read data using SDreaddata(). Example 4. 3-D 2x3x4 SDS of uint16 with 1x1x4 chunks Write data using SDwritedata(). Read data using SDreadchunk(). Example 5. 2-D 9x4 SDS of uint16 with 3x2 chunks with GZIP compression. Write data using SDwritechunk(). Read data using SDreaddata(). Author - GeorgeV Date - 11/25/96 ********************************************************************/ #include "mfhdf.h" /* arrays holding dim info for datasets */ static int32 d_dims[3] = {2, 3, 4}; /* data dimensions */ static int32 edge_dims[3] = {0, 0, 0}; /* edge dims */ static int32 start_dims[3] = {0, 0, 0}; /* starting dims */ /* data arrays layed out in memory */ /* used in Example 1 and 5 */ static uint16 u16_2data[9][4] = { {11, 21, 31, 41}, {12, 22, 32, 42}, {13, 23, 33, 43}, {14, 24, 34, 44}, {15, 25, 35, 45}, {16, 26, 36, 46}, {17, 27, 37, 47}, {18, 28, 38, 48}, {19, 29, 39, 49}, }; /* uint16 3x2 chunk arrays used in example 1 and 5*/ static uint16 chunk1_2u16[6] = {11, 21, 12, 22, 13, 23}; static uint16 chunk2_2u16[6] = {31, 41, 32, 42, 33, 43}; static uint16 chunk3_2u16[6] = {14, 24, 15, 25, 16, 26}; static uint16 chunk4_2u16[6] = {34, 44, 35, 45, 36, 46}; static uint16 chunk5_2u16[6] = {17, 27, 18, 28, 19, 29}; static uint16 chunk6_2u16[6] = {37, 47, 38, 48, 39, 49}; /* uint16 1x1x4 chunk arrays used in example 3 */ static uint16 chunk1_3u16[4] = { 0, 1, 2, 3}; static uint16 chunk2_3u16[4] = { 10, 11, 12, 13}; static uint16 chunk3_3u16[4] = { 20, 21, 22, 23}; static uint16 chunk4_3u16[4] = { 100, 101, 102, 103}; static uint16 chunk5_3u16[4] = { 110, 111, 112, 113}; static uint16 chunk6_3u16[4] = { 120, 121, 122, 123}; /* Used in Examples 2 and 4 */ static uint16 u16_3data[2][3][4] = { { { 0, 1, 2, 3}, { 10, 11, 12, 13}, { 20, 21, 22, 23}}, { { 100, 101, 102, 103}, { 110, 111, 112, 113}, { 120, 121, 122, 123}}}; /* * Main routine */ int main(int argc, char *argv[]) { int32 f1; /* file handle */ int32 sdsid; /* SDS handle */ uint16 inbuf_3u16[2][3][4]; /* Data array read for Example 2 and 3*/ uint16 inbuf_2u16[5][2]; /* Data array read for Example 1 */ uint16 ru16_3data[4]; /* whole chunk input buffer */ uint16 fill_u16 = 0; /* fill value */ HDF_CHUNK_DEF chunk_def; /* Chunk defintion set */ HDF_CHUNK_DEF rchunk_def; /* Chunk defintion read */ int32 cflags; /* chunk flags */ comp_info cinfo; /* compression info */ intn status; ncopts = NC_VERBOSE; /* create file */ f1 = SDstart("chunk.hdf", DFACC_CREATE); /* Example 1. 2-D 9x4 SDS of uint16 with 3x2 chunks Write data using SDwritechunk(). Read data using SDreaddata(). */ /* create a 9x4 SDS of uint16 in file 1 */ d_dims[0] = 9; d_dims[1] = 4; sdsid = SDcreate(f1, "DataSetChunked_1", DFNT_UINT16, 2, d_dims); /* set fill value */ fill_u16 = 0; status = SDsetfillvalue(sdsid, (VOIDP) &fill_u16); /* Create chunked SDS chunk is 3x2 which will create 6 chunks */ chunk_def.chunk_lengths[0] = 3; chunk_def.chunk_lengths[1] = 2; status = SDsetchunk(sdsid, chunk_def, HDF_CHUNK); /* Set Chunk cache to hold 3 chunks */ status = SDsetchunkcache(sdsid, 3, 0); /* Write data use SDwritechunk */ /* Write chunk 1 */ start_dims[0] = 0; start_dims[1] = 0; status = SDwritechunk(sdsid, start_dims, (VOIDP) chunk1_2u16); /* Write chunk 4 */ start_dims[0] = 1; start_dims[1] = 1; status = SDwritechunk(sdsid, start_dims, (VOIDP) chunk4_2u16); /* Write chunk 2 */ start_dims[0] = 0; start_dims[1] = 1; status = SDwritechunk(sdsid, start_dims, (VOIDP) chunk2_2u16); /* Write chunk 5 */ start_dims[0] = 2; start_dims[1] = 0; status = SDwritechunk(sdsid, start_dims, (VOIDP) chunk5_2u16); /* Write chunk 3 */ start_dims[0] = 1; start_dims[1] = 0; status = SDwritechunk(sdsid, start_dims, (VOIDP) chunk3_2u16); /* Write chunk 6 */ start_dims[0] = 2; start_dims[1] = 1; status = SDwritechunk(sdsid, start_dims, (VOIDP) chunk6_2u16); /* read a portion of data back in using SDreaddata i.e 5x2 subset of the whole array */ start_dims[0] = 2; start_dims[1] = 1; edge_dims[0] = 5; edge_dims[1] = 2; status = SDreaddata(sdsid, start_dims, NULL, edge_dims, (VOIDP) inbuf_2u16); /* This 5x2 array should look somethink like this {{23, 24, 25, 26, 27}, {33, 34, 35, 36, 37}} */ /* Get chunk information */ status = SDgetchunkinfo(sdsid, &rchunk_def, &cflags); /* Close down this SDS*/ status = SDendaccess(sdsid); /* Example 2. 3-D 2x3x4 SDS of uint16 with 2x3x2 chunks Write data using SDwritedata(). Read data using SDreaddata(). */ /* create a new 2x3x4 SDS of uint16 in file 1 */ d_dims[0] = 2; d_dims[1] = 3; d_dims[2] = 4; sdsid = SDcreate(f1, "DataSetChunked_2", DFNT_UINT16, 3, d_dims); /* set fill value */ fill_u16 = 0; status = SDsetfillvalue(sdsid, (VOIDP) &fill_u16); /* Create chunked SDS chunk is 2x3x2 which will create 2 chunks */ chunk_def.chunk_lengths[0] = 2; chunk_def.chunk_lengths[1] = 2; chunk_def.chunk_lengths[2] = 3; status = SDsetchunk(sdsid, chunk_def, HDF_CHUNK); /* Set Chunk cache to hold 2 chunks*/ status = SDsetchunkcache(sdsid, 2, 0); /* Write data using SDwritedata*/ start_dims[0] = 0; start_dims[1] = 0; start_dims[2] = 0; edge_dims[0] = 2; edge_dims[1] = 3; edge_dims[2] = 4; status = SDwritedata(sdsid, start_dims, NULL, edge_dims, (VOIDP) u16_3data); /* read data back in using SDreaddata*/ start_dims[0] = 0; start_dims[1] = 0; start_dims[2] = 0; edge_dims[0] = 2; edge_dims[1] = 3; edge_dims[2] = 4; status = SDreaddata(sdsid, start_dims, NULL, edge_dims, (VOIDP) inbuf_3u16); /* Verify the data in inbuf_3u16 against u16_3data[] */ /* Get chunk information */ status = SDgetchunkinfo(sdsid, &rchunk_def, &cflags); /* Close down this SDS*/ status = SDendaccess(sdsid); /* Example 3. 3-D 2x3x4 SDS of uint16 with 1x1x4 chunks Write data using SDwritechunk(). Read data using SDreaddata(). */ /* Now create a new 2x3x4 SDS of uint16 in file 'chunk.hdf' */ d_dims[0] = 2; d_dims[1] = 3; d_dims[2] = 4; sdsid = SDcreate(f1, "DataSetChunked_3", DFNT_UINT16, 3, d_dims); /* set fill value */ fill_u16 = 0; status = SDsetfillvalue(sdsid, (VOIDP) &fill_u16); /* Create chunked SDS chunk is 1x1x4 which will create 6 chunks */ chunk_def.chunk_lengths[0] = 1; chunk_def.chunk_lengths[1] = 1; chunk_def.chunk_lengths[2] = 4; status = SDsetchunk(sdsid, chunk_def, HDF_CHUNK); /* Set Chunk cache to hold 4 chunks*/ status = SDsetchunkcache(sdsid, 4, 0); /* Write data use SDwritechunk */ /* Write chunk 1 */ start_dims[0] = 0; start_dims[1] = 0; start_dims[2] = 0; status = SDwritechunk(sdsid, start_dims, (VOIDP) chunk1_3u16); /* Write chunk 4 */ start_dims[0] = 1; start_dims[1] = 0; start_dims[2] = 0; status = SDwritechunk(sdsid, start_dims, (VOIDP) chunk4_3u16); /* Write chunk 2 */ start_dims[0] = 0; start_dims[1] = 1; start_dims[2] = 0; status = SDwritechunk(sdsid, start_dims, (VOIDP) chunk2_3u16); /* Write chunk 5 */ start_dims[0] = 1; start_dims[1] = 1; start_dims[2] = 0; status = SDwritechunk(sdsid, start_dims, (VOIDP) chunk5_3u16); /* Write chunk 3 */ start_dims[0] = 0; start_dims[1] = 2; start_dims[2] = 0; status = SDwritechunk(sdsid, start_dims, (VOIDP) chunk3_3u16); /* Write chunk 6 */ start_dims[0] = 1; start_dims[1] = 2; start_dims[2] = 0; status = SDwritechunk(sdsid, start_dims, (VOIDP) chunk6_3u16); /* read data back in using SDreaddata*/ start_dims[0] = 0; start_dims[1] = 0; start_dims[2] = 0; edge_dims[0] = 2; edge_dims[1] = 3; edge_dims[2] = 4; status = SDreaddata(sdsid, start_dims, NULL, edge_dims, (VOIDP) inbuf_3u16); /* Verify the data in inbuf_3u16 against u16_3data[] */ /* Close down this SDS*/ status = SDendaccess(sdsid); /* Example 4. 3-D 2x3x4 SDS of uint16 with 1x1x4 chunks Write data using SDwritedata(). Read data using SDreadchunk(). */ /* Now create a new 2x3x4 SDS of uint16 in file 'chunk.hdf' */ d_dims[0] = 2; d_dims[1] = 3; d_dims[2] = 4; sdsid = SDcreate(f1, "DataSetChunked_4", DFNT_UINT16, 3, d_dims); /* set fill value */ fill_u16 = 0; status = SDsetfillvalue(sdsid, (VOIDP) &fill_u16); /* Create chunked SDS chunk is 1x1x4 which will create 6 chunks */ chunk_def.chunk_lengths[0] = 1; chunk_def.chunk_lengths[1] = 1; chunk_def.chunk_lengths[2] = 4; status = SDsetchunk(sdsid, chunk_def, HDF_CHUNK); /* Set Chunk cache to hold 4 chunks */ status = SDsetchunkcache(sdsid, 4, 0); /* Write data using SDwritedata*/ start_dims[0] = 0; start_dims[1] = 0; start_dims[2] = 0; edge_dims[0] = 2; edge_dims[1] = 3; edge_dims[2] = 4; status = SDwritedata(sdsid, start_dims, NULL, edge_dims, (VOIDP) u16_3data); /* read data back in using SDreadchunk and verify against the chunk arrays chunk1_3u16[] ... chunk6_3u16[] */ /* read chunk 1 */ start_dims[0] = 0; start_dims[1] = 0; start_dims[2] = 0; status = SDreadchunk(sdsid, start_dims, (VOIDP) ru16_3data); /* read chunk 2 */ start_dims[0] = 0; start_dims[1] = 1; start_dims[2] = 0; status = SDreadchunk(sdsid, start_dims, (VOIDP) ru16_3data); /* read chunk 3 */ start_dims[0] = 0; start_dims[1] = 2; start_dims[2] = 0; status = SDreadchunk(sdsid, start_dims, (VOIDP) ru16_3data); /* read chunk 4 */ start_dims[0] = 1; start_dims[1] = 0; start_dims[2] = 0; status = SDreadchunk(sdsid, start_dims, (VOIDP) ru16_3data); /* read chunk 5 */ start_dims[0] = 1; start_dims[1] = 1; start_dims[2] = 0; status = SDreadchunk(sdsid, start_dims, (VOIDP) ru16_3data); /* read chunk 6 */ start_dims[0] = 1; start_dims[1] = 2; start_dims[2] = 0; status = SDreadchunk(sdsid, start_dims, (VOIDP) ru16_3data); /* Close down this SDS*/ status = SDendaccess(sdsid); /* Example 5. 2-D 9x4 SDS of uint16 with 3x2 chunks with GZIP compression Write data using SDwritechunk(). Read data using SDreaddata(). */ /* create a 9x4 SDS of uint16 in file 1 */ d_dims[0] = 9; d_dims[1] = 4; sdsid = SDcreate(f1, "DataSetChunked_1", DFNT_UINT16, 2, d_dims); /* set fill value */ fill_u16 = 0; status = SDsetfillvalue(sdsid, (VOIDP) &fill_u16); /* Create chunked SDS chunk is 3x2 which will create 6 chunks Compression set will be GZIP. Note that 'chunk_def' is a union. See the man page 'sd_chunk.3' for more info on the union. */ chunk_def.comp.chunk_lengths[0] = 3; chunk_def.comp.chunk_lengths[1] = 2; chunk_def.comp.comp_type = COMP_CODE_DEFLATE; /* GZIP */ chunk_def.comp.cinfo.deflate.level = 6; /* Level */ /* set Chunking with Compression */ status = SDsetchunk(sdsid, chunk_def, HDF_CHUNK | HDF_COMP); /* Set Chunk cache to hold 3 chunks */ status = SDsetchunkcache(sdsid, 3, 0); /* Write data use SDwritechunk NOTE: This is the recommended way when using Compression */ /* Write chunk 1 */ start_dims[0] = 0; start_dims[1] = 0; status = SDwritechunk(sdsid, start_dims, (VOIDP) chunk1_2u16); /* Write chunk 4 */ start_dims[0] = 1; start_dims[1] = 1; status = SDwritechunk(sdsid, start_dims, (VOIDP) chunk4_2u16); /* Write chunk 2 */ start_dims[0] = 0; start_dims[1] = 1; status = SDwritechunk(sdsid, start_dims, (VOIDP) chunk2_2u16); /* Write chunk 5 */ start_dims[0] = 2; start_dims[1] = 0; status = SDwritechunk(sdsid, start_dims, (VOIDP) chunk5_2u16); /* Write chunk 3 */ start_dims[0] = 1; start_dims[1] = 0; status = SDwritechunk(sdsid, start_dims, (VOIDP) chunk3_2u16); /* Write chunk 6 */ start_dims[0] = 2; start_dims[1] = 1; status = SDwritechunk(sdsid, start_dims, (VOIDP) chunk6_2u16); /* read a portion of data back in using SDreaddata i.e 5x2 subset of the whole array */ start_dims[0] = 2; start_dims[1] = 1; edge_dims[0] = 5; edge_dims[1] = 2; status = SDreaddata(sdsid, start_dims, NULL, edge_dims, (VOIDP) inbuf_2u16); /* This 5x2 array should look somethink like this {{23, 24, 25, 26, 27}, {33, 34, 35, 36, 37}} */ /* Get chunk information */ status = SDgetchunkinfo(sdsid, &rchunk_def, &cflags); /* Close down this SDS*/ status = SDendaccess(sdsid); /* Close down SDS interface */ status = SDend(f1); } ============================================================================ ================================vattr.txt=================================== Vgroup and vdata attributes 9/8/96 Vdata/vgroup version -------------------- Previously (up to HDF4.0r2), the vdata and vgroup version was 3, VSET_VERSION. With attributes added, the version number has been changed to 4, VSET_NEW_VERSION. For backward compatibility, a vdata or a vgroup will still have version number 3 if it has no attribute(s) assigned. Attribute --------- An attribute has a name, data type, a number of values and the values. All values of an attribute should be of the same data type. For example, 10 characters, or 2 32-bit integers. Any number of attributes can be assigned to a vgroup, a vdata (entire vdata) or any field of a vdata. An attribute name should be unique in its scope. For example, a field attribute name should be unique among all attributes of that field. Attributes in HDF files ----------------------- Attributes will be stored in vdatas. The vdata's name is the attribute name specified by the user. Its class is "Attr0.0", _HDF_ATTRIBUTE. All attributes of a vgroup or a vdata will be included in the vgroup represented by DFTAG_VG, or the vdata header, DFTAG_VH. Vdata/Vgroup attribute routines (see man pages for more info) ---------------------------------------------------------- intn VSfindex(int32 vsid, char *fieldname, int32 *fldindex) find out the index of a field given the field name. intn VSsetattr(int32 vsid, int32 findex, char *attrname, int32 datatype, int32 count, VOIDP values) set attr for a field of a vdata or for the vdata. if the attr already exists the new values will replace the current ones, provided the datatype and order have not been changed. intn VSnattrs(int32 vsid) total number of attr for a vdata and its fields int32 VSfnattrs(int32 vsid, int32 findex) number of attrs for a vdata or a field of it intn VSfindattr(int32 vsid, int32 findex, char *attrname) get index of an attribute with a given name intn VSattrinfo(int32 vsid, int32 findex, intn attrindex, char *name, int32 *datatype, int32 *count, int32 *size); get info about an attribute intn VSgetattr(int32 vsid, int32 findex, intn attrindex, VOIDP values) get values of an attribute intn VSisattr(int32 vsid) test if a vdata is an attribute of other object intn Vsetattr(int32 vgid, char *attrname, int32 datatype, int32 count, VOIDP values) set attr for a vgroup intn Vnattrs(int32 vgid) number of attrs for a vgroup intn Vfindattr(int32 vgid, char *attrname) get index of an attribute with a given name intn Vattrinfo(int32 vgid, intn attrindex, char *name, int32 *datatype, int32 *count, int32 *size) get info about an attribute intn Vgetattr(int32 vgid, intn attrindex, VOIDP values) get values of an attribute int32 Vgetversion(int32 vgid) get vset version of a vgroup ( int32 VSgetversion(int32 vsid) already exists.) Changes in the vdata header in HDF files : ------------------------------------------ 1. If attributes or other new features are assigned: o version number will be VSET_NEW_VERSION (4, defined in vg.h) o the new DFTAG_VH looks like: interlace number_records hdf_rec_size n_fields 2 bytes 4 2 2 datatype_field_n offset_field_n order_field_n fldnmlen_n 2*n_fields 2*n_fields 2*n_fields 2*n_fields fldnm_n namelen name classlen class extag exref version 2 2 2 2 2 more flags < nattrs field_index attr0_tag/ref 2 4 4 4 2/2 field_index attr1_tag/ref ...> version more extra_byte 4 2/2 If no attributes or other new features were assigned, version number is still VSET_VERSION and the old vdata header will be written out. 2. In the old implementation the 'version' and 'more' fields follow the 'exref' field. In order to not break existing applications the new implementation keeps these two fields and adds a duplication of 'version' and 'more' at the end, along with an extra byte which was not documented in the old documentation. 3. The field "flags" of uint32: bit 0 -- has attr bit 1 -- 15 -- unused. o Fields follow the 'flags' are: total_number_of_attrs this vdata has (4 bytes) vs_attr_list (#_attrs * 8 bytes (4+2+2)) (field_index, attr_vdata_tag, attr_vdata_ref) the flags and attribute fields are added after the first 'more' fields. Changes in the vgroup data in HDF files --------------------------------------- 1. If has attribute(s): o add a flag field, uint16, bit 0 -- has attr bit 1-15 -- unused. o version number will be changed to 4 o fields following the flag are: number_of_attrs vg_attr_list the above fields are added preceding the version field o vg_attr_list consists of a list of attribute_tag/ref pairs If no attribute: No changes in vgroup data and version number is still 3 ============================================================================ ================================windows.txt================================= Fortner Software LLC ("Fortner") created the reference implementation for Windows of the HDF 4.1r3 library, providing C-language bindings to all 4.1r3 features. The Windows reference implementation of the 4.1r3 library was implemented and tested on a Pentium PC running Windows95 4.00.950 using Microsoft Developers Studio 97 Visual C++ Version 5.00. The library has also been run on Pentium PC running WindowsNT version 4.0. Fortner cannot be certain that the libraries will run on other versions of Windows or when built using other development tools. (In particular, this Windows implementation has not addressed use with Windows 3.x, or non-PC versions of WindowsNT). Migrating the Windows reference implementation to other development and/or run-time environments is the responsibility of the library user. First-time HDF users are encouraged to read the FAQ in this release for more information about HDF. Users can also look at the home page for HDF at: https://www.hdfgroup.org/ Please send questions, comments, and recommendations regarding the Windows version of the HDF library to: help@hdfgroup.org ============================================================================