This appendix discusses:

• What is the PV-WAVE HDF interface?

• Where to find example programs and NCSA documentation in the PV-WAVE distribution.

• Using PV-WAVE HDF functions.

• The PV-WAVE HDF Base functions.

What is the PV-WAVE HDF Interface?

PV-WAVE provides an extensive interface to the NCSA (National Center for Supercomputer Applications) HDF (Hierarchical Data Format) C library, which is in the public domain. PV-WAVE's interface to the HDF library is fully supported by Visual Numerics; however, Visual Numerics is not responsible for questions or problems specifically related to the HDF library. Please direct such problems or questions directly to NSCA.

The PV-WAVE HDF interface is divided into two sets of functions: convenience routines and base functions.

The convenience routines are a set of PV-WAVE routines developed for general situations where you need to access HDF functionality from PV-WAVE. The convenience routines are described in this reference. For a list of these routines, see Chapter 1, Functional Summary of Routines.

The extensive set of base functions provides direct access within PV-WAVE to the HDF library, which is dynamically linked to PV-WAVE and invoked at runtime. The calling sequence for each base function is listed in this appendix.

Example Programs Are Available

To help you get the most out of the PV-WAVE HDF base functions, a collection of example programs is available in:

(UNIX)$VNI_DIR/hdf-4_00/test

(OpenVMS)VNI_DIR:[HDF-4_00.TEST]

(Windows)$VNI_DIR\hdf-4_00\test

To run these test programs, either add the test directory path to the PV-WAVE system variable !Path, or simply start your PV-WAVE session directly from the test directory.

In addition, the convenience routines themselves provide good examples of how the base functions can be used in other applications. The convenience routines are located in:

(UNIX)$VNI_DIR/hdf-4_00/lib

(OpenVMS)VNI_DIR:[HDF-4_00.LIB]

(Windows)$VNI_DIR\hdf-4_00\lib

An extensive collection of NCSA documentation on HDF and NetCDF is located in the subdirectories of:

(UNIX)$VNI_DIR/hdf-4_00/doc

(OpenVMS)VNI_DIR:[HDF-4_00.DOC]

(Windows)$VNI_DIR\hdf-4_00\doc

These documents are stored as compressed PostScript files that you can print on any PostScript laser printer. Simply uncompress the files before printing them.

The NCSA documents that are included with PV-WAVE are:

• HDF User's Guide, Version 4.0r2, July 1996, University of Illinois at Urbana-Champaign.

• HDF Reference Manual, Version 4.0r2, July 1996, University of Illinois at Urbana-Champaign.

• NetCDF User's Guide, Version 2.3, April 1993, University Corporation for Atmospheric Research.

For more information on these documents, refer to the README files in:

(UNIX)$VNI_DIR/hdf-4_00/doc

(OpenVMS)VNI_DIR:[HDF-4_00.DOC]

(Windows)$VNI_DIR\hdf-4_00\doc

NCSA documentation is directly available from:

NCSA Documentation Orders

152 Computing Applications Building

605 East Springfield Avenue

Champaign, IL 61820

(217) 244-0072

or from FTP site ftp.ncsa.uiuc.edu

NetCDF documentation is available from the FTP site unidata.ucar.edu in the directory pub/netcdf.

Using the PV-WAVE HDF Functions

Before you can use any of the PV-WAVE HDF base or convenience routines, you must initialize the HDF module. To to this, type:

WAVE @hdf_startup
% Compiled module: HDF_INIT.
      PV-WAVE:HDF 4.00 Module Initialized

After the module is initialized, you can use any of the PV-WAVE HDF routines.

HDF_STARTUP calls a function HDF_INIT which initializes the variables in the hdf_common common block. These variables match the flags that are defined by the header files to the HDF and NetCDF C libraries. For example, the NetCDF flag NC_WRITE is set to the value 1 in the file when the PV-WAVE HDF module is initialized.

These variables are used to define:

• Default palette and string sizes

• Flags for Raster 8 encoding schemes

• Flags for Raster 24 bit interlace schemes

• Flags for SDS number types

• Flags for HOPEN file opening status

• Tag values, as found in the header file

  (UNIX)$VNI_DIR/hdf-4_00/src/hdf

  (OpenVMS)VNI_DIR:[HDF-4_00.SRC.HDF]

  (Windows)$VNI_DIR\hdf-4_00\hdf

The HDF Calling Interfaces manual refers to these common variables in HDF calls. These variables are used frequently in many of the calls to PV-WAVE HDF convenience routines and base routines.

Input data to the PV-WAVE HDF base functions is usually converted to the required data type. This alters the input parameters if they are not the correct data type.

An error message

XXX must be declared in the calling procedure.

indicates that the data type and space required for the supplied variable is used within, but not allocated by, the service HDF routine. By defining the PV-WAVE variable with a dummy value of the proper data type, the PV-WAVE HDF wrapper will automatically convert the fetched value to the desired data type.

If you know the name of the routine you want to call, but do not know the calling sequence, use the Usage or Help keywords. For example, the following command displays the parameters for the NCCREATE function:

tmp = NCCREATE(/Usage)
% NCCREATE: usage: status = NCCREATE (path, cmode,     Help=help, 
Usage=usage)

These keywords are not part of HDF or NetCDF, but are provided for convenience to PV-WAVE HDF users.

When using an SDS "GET" routine, be sure that the data types with which you fetch the annotated data are the same as your main dataset. Otherwise, you will get unexpected results.

Arrays in PV-WAVE are aligned similar to FORTRAN (i.e., column-major order or first subscript varying fastest), therefore, datasets and images should be aligned as discussed in the HDF documentation for FORTRAN. For data read or written by C, this will result in the data being transposed from the PV-WAVE representation. For example, a 24-bit raster image array in PV-WAVE is defined as "3 X width X height" for pixel interlacing, however, in C, the same image array would be defined as "height X width X 3".

Annotation routines which read or write descriptions (i.e., DFANADDFDS, DFANGETDESC, HDFPUTANN, etc.) operate on byte arrays rather than strings and may require further processing.

NCSA has replaced the slice routines for reading and writing hyperslabs of scientific data with equivalent slab routines. The slab routines are supported in PV-WAVE HDF; however, the slice routines are not.

The PV-WAVE HDF convenience routines are written to check input data for errors before continuing execution. The PV-WAVE HDF base routines assume that the input data is valid, and performs minimal tests on the input data. Because of this, the possibility for failure is present. If you are using PV-WAVE HDF base routines and are experiencing core dumps, double check your input data for correct size and data type.

PV-WAVE HDF Base Function Interface

The PV-WAVE HDF base functions let you access all of the functions described in the NSCA HDF Reference Manual from within PV-WAVE.

These functions are located in the library:

(UNIX)$VNI_DIR/hdf-4_00/lib

(OpenVMS)VNI_DIR:[HDF-4_00.LIB]

(Windows)$VNI_DIR\hdf-4_00\lib

For detailed information on these routines, refer to the HDF Reference Manual.

For complete descriptions of these functions, see the HDF Reference Manual.

status = DF24ADDIMAGE (filename, image, xdim, ydim, Help=help, Usage=usage)

status = DF24GETDIMS (filename, pxdim, pydim, pil, Help=help, Usage=usage)

status = DF24GETIMAGE (filename, image, xdim, ydim, Help=help, Usage=usage)

ref = DF24LASTREF (Help=help, Usage=usage)

nimages= DF24NIMAGES (filename, Help=help, Usage=usage)

status = DF24PUTIMAGE (filename, image, xdim, ydim, Help=help, Usage=usage)

status = DF24READREF (filename, ref, Help=help, Usage=usage)

status = DF24REQIL (il, Help=help, Usage=usage)

status = DF24RESTART (Help=help, Usage=usage)

status = DF24SETCOMPRESS (type, cinfo, Help=help, Usage=usage)

status = DF24SETDIMS (xdim, ydim, Help=help, Usage=usage)

status = DF24SETIL (il, Help=help, Usage=usage)

For complete descriptions of these functions, see the HDF Reference Manual.

status = DFANADDFDS (file_id, desc, desclen, Help=help, Usage=usage)

status = DFANADDFID (file_id, id, Help=help, Usage=usage)

status = DFANGETDESC (filename, tag, ref, desc, maxlen, Help=help, Usage=usage)

desclen = DFANGETDESCLEN (filename, tag, ref, Help=help, Usage=usage)

desclen = DFANGETFDS (file_id, desc, maxlen, isfirst, Help=help, Usage=usage)

fidlen = DFANGETFDSLEN (file_id, isfirst, Help=help, Usage=usage)

fidlen = DFANGETFID (file_id, id, maxlen, isfirst, Help=help, Usage=usage)

fidlen = DFANGETFIDLEN (file_id, isfirst, Help=help, Usage=usage)

status = DFANGETLABEL (filename, tag, ref, label, maxlen, Help=help, Usage=usage)

lablen = DFANGETLABLEN (filename, tag, ref, Help=help, Usage=usage)

numrefs = DFANLABLIST (filename, tag, reflist, labellist, listsize, maxlen, startpos, Help=help, Usage=usage)

ref = DFANLASTREF (Help=help, Usage=usage)

status = DFANPUTDESC (filename, tag, ref, desc, desclen, Help=help, Usage=usage)

status = DFANPUTLABEL (filename, tag, ref, label, Help=help, Usage=usage)

For complete descriptions of these functions, see the HDF Reference Manual.

status = DFPADDPAL (filename, palette, Help=help, Usage=usage)

status = DFPGETPAL (filename, palette, Help=help, Usage=usage)

ref = DFPLASTREF (Help=help, Usage=usage)

npals = DFPNPALS (filename, Help=help, Usage=usage)

status = DFPPUTPAL (filename, palette, overwrite, filemode, Help=help, Usage=usage)

status = DFPREADREF (filename, ref, Help=help, Usage=usage)

status = DFPRESTART (Help=help, Usage=usage)

status = DFPWRITEREF (filename, ref, Help=help, Usage=usage)

For complete descriptions of these functions, see the HDF Reference Manual.

status = DFR8ADDIMAGE (filename, image, xdim, ydim, compress, Help=help, Usage=usage)

status = DFR8GETDIMS (filename, pxdim, pydim, pispal, Help=help, Usage=usage)

status = DFR8GETIMAGE (filename, image, xdim, ydim, pal, Help=help, Usage=usage)

ref = DFR8LASTREF (Help=help, Usage=usage)

nimages = DFR8NIMAGES (filename, Help=help, Usage=usage)

status = DFR8PUTIMAGE (filename, image, xdim, ydim, compress, Help=help, Usage=usage)

status = DFR8READREF (filename, ref, Help=help, Usage=usage)

status = DFR8RESTART (Help=help, Usage=usage)

status = DFR8SETCOMPRESS (type, cinfo, Help=help, Usage=usage)

status = DFR8SETPALETTE (pal, Help=help, Usage=usage)

status = DFR8WRITEREF (filename, ref, Help=help, Usage=usage)

For complete descriptions of these functions, see the HDF Reference Manual.

status = DFSDADDDATA (filename, rank, dimsizes, data, Help=help, Usage=usage)

status = DFSDCLEAR (Help=help, Usage=usage)

status = DFSDENDSLAB (Help=help, Usage=usage)

status = DFSDGETCAL (pcal, pcal_err, pioff, pioff_err, cal_nt, Help=help, Usage=usage)

status = DFSDGETDATA (filename, rank, dimsizes, data, Help=help, Usage=usage)

status = DFSDGETDATALEN (llabel, lunit, lformat, lcoordsys, Help=help, Usage=usage)

status = DFSDGETDATASTRS (label, unit, format, coordsys, Help=help, Usage=usage)

status = DFSDGETDIMLEN (dim, llabel, lunit, lformat, Help=help, Usage=usage)

status = DFSDGETDIMS (filename, prank, sizes, maxrank, Help=help, Usage=usage)

status = DFSDGETDIMSCALE (dim, maxsize, scale, Help=help, Usage=usage)

status = DFSDGETDIMSTRS (dim, label, unit, format, Help=help, Usage=usage)

status = DFSDGETFILLVALUE (fill_value, Help=help, Usage=usage)

status = DFSDGETNT (pnumbertype, Help=help, Usage=usage)

status = DFSDGETRANGE (pmax, pmin, Help=help, Usage=usage)

ref = DFSDLASTREF (Help=help, Usage=usage)

ndatasets = DFSDNDATASETS (filename, Help=help, Usage=usage)

status = DFSDPRE32SDG (filename, ref, ispre32, Help=help, Usage=usage)

status = DFSDPUTDATA (filename, rank, dimsizes, data, Help=help, Usage=usage)

status = DFSDREADREF (filename, ref, Help=help, Usage=usage)

status = DFSDREADSLAB (filename, start, slab_size, stride, buffer, buffer_size, Help=help, Usage=usage)

status = DFSDRESTART (Help=help, Usage=usage)

status = DFSDSETCAL (cal, cal_err, ioff, ioff_err, cal_nt, Help=help, Usage=usage)

status = DFSDSETDATASTRS (label, unit, format, coordsys, Help=help, Usage=usage)

status = DFSDSETDIMS (rank, dimsizes, Help=help, Usage=usage)

status = DFSDSETDIMSCALE (dim, dimsize, scale, Help=help, Usage=usage)

status = DFSDSETDIMSTRS (dim, label, unit, format, Help=help, Usage=usage)

status = DFSDSETFILLVALUE (fill_value, Help=help, Usage=usage)

status = DFSDSETLENGTHS (maxlen_label, maxlen_unit, maxlen_format, maxlen_coordsys, Help=help, Usage=usage)

status = DFSDSETNT (numbertype, Help=help, Usage=usage)

status = DFSDSETRANGE (maxi, mini, Help=help, Usage=usage)

status = DFSDSTARTSLAB (filename, Help=help, Usage=usage)

status = DFSDWRITEREF (filename, ref, Help=help, Usage=usage)

status = DFSDWRITESLAB (start, stride, count, data, Help=help, Usage=usage)

For complete descriptions of these functions, see the HDF Reference Manual.

status = HCLOSE (file_id, Help=help, Usage=usage)

status = HGETFILEVERSION (file_id, majorv, minorv, release, string, Help=help, Usage=usage)

status = HGETLIBVERSION (majorv, minorv, release, string, Help=help, Usage=usage)

status = HISHDF (filename, Help=help, Usage=usage)

fileid = HOPEN (path, access, ndds, Help=help, Usage=usage)

status = HXSETCREATEDIR (dirname, Help=help, Usage=usage)

status = HXSETDIR (dirname, Help=help, Usage=usage)

For complete descriptions of these functions, see the HDF Reference Manual.

status = NCABORT (cdfid, Help=help, Usage=usage)

status = NCATTCOPY (incdf, invar, name, outcdf, outvar, Help=help, Usage=usage)

status = NCATTDEL (cdfid, varid, name, Help=help, Usage=usage)

status = NCATTGET (cdfid, varid, name, value, Help=help, Usage=usage)

status = NCATTINQ (cdfid, varid, name, datatype, len, Help=help, Usage=usage)

status = NCATTNAME (cdfid, varid, attnum, name, Help=help, Usage=usage)

status = NCATTPUT (cdfid, varid, name, datatype, len, value, Help=help, Usage=usage)

status = NCATTRENAME (cdfid, varid, name, newname, Help=help, Usage=usage)

status = NCCLOSE (cdfid, Help=help, Usage=usage)

status = NCCREATE (path, cmode, Help=help, Usage=usage)

status = NCDIMDEF (cdfid, name, length, Help=help, Usage=usage)

status = NCDIMID (cdfid, name, Help=help, Usage=usage)

status = NCDIMINQ (cdfid, dimid, name, length, Help=help, Usage=usage)

status = NCDIMRENAME (cdfid, dimid, name, Help=help, Usage=usage)

status = NCENDEF (cdfid, Help=help, Usage=usage)

status = NCINQUIRE (cdfid, ndims, nvars, natts, recdim, Help=help, Usage=usage)

status = NCOPEN (path, mode, Help=help, Usage=usage)

status = NCREDEF (cdfid, Help=help, Usage=usage)

status = NCSETFILL (cdfid, fillmode, Help=help, Usage=usage)

status = NCSYNC (cdfid, Help=help, Usage=usage)

status = NCTYPELEN (datatype, Help=help, Usage=usage)

status = NCVARDEF (cdfid, name, datatype, ndims, dim, Help=help, Usage=usage)

status = NCVARGET (cdfid, varid, start, count, value, Help=help, Usage=usage)

status = NCVARGET1 (cdfid, varid, coords, value, Help=help, Usage=usage)

status = NCVARGETG (cdfid, varid, start, count, stride, imap, values, Help=help, Usage=usage)

status = NCVARGETS (cdfid, varid, start, count, stride, values, Help=help, Usage=usage)

status = NCVARID (cdfid, name, Help=help, Usage=usage)

status = NCVARINQ (cdfid, varid, name, datatype, ndims, dim, natts, Help=help, Usage=usage)

status = NCVARPUT (cdfid, varid, start, count, value, Help=help, Usage=usage)

status = NCVARPUT1 (cdfid, varid, coords, value, Help=help, Usage=usage)

status = NCVARPUTG (cdfid, varid, start, count, stride, imap, values, Help=help, Usage=usage)

status = NCVARPUTS (cdfid, varid, start, count, stride, values, Help=help, Usage=usage)

status = NCVARRENAME (cdfid, varid, name, Help=help, Usage=usage)

For complete descriptions of these functions, see the HDF Reference Manual.

size = DFKNTSIZE (data_type, Help=help, Usage=usage)

status = SDATTRINFO (id, index, name, nt, count, Help=help, Usage=usage)

status = SDCREATE (fid, name, nt, rank, dimsizes, Help=help, Usage=usage)

status = SDDIMINFO (id, name, l_size, nt, nattr, Help=help, Usage=usage)

status = SDEND (id, Help=help, Usage=usage)

status = SDENDACCESS (id, Help=help, Usage=usage)

status = SDFILEINFO (fid, datasets, attrs, Help=help, Usage=usage)

status = SDFINDATTR (id, attrname, Help=help, Usage=usage)

status = SDGETCAL (sdsid, cal, cale, ioff, ioffe, nt, Help=help, Usage=usage)

status = SDGETDATASTRS (sdsid, l, u, f, c, len, Help=help, Usage=usage)

status = SDGETDIMID (sdsid, number, Help=help, Usage=usage)

status = SDGETDIMSCALE (id, data, Help=help, Usage=usage)

status = SDGETDIMSTRS (id, l, u, f, len, Help=help, Usage=usage)

status = SDGETFILLVALUE (sdsid, val, Help=help, Usage=usage)

status = SDGETINFO (sdsid, name, rank, dimsizes, nt, nattr, Help=help, Usage=usage)

status = SDGETRANGE (sdsid, pmax, pmin, Help=help, Usage=usage)

status = SDIDTOREF (id, Help=help, Usage=usage)

status = SDISCOORDVAR (id, Help=help, Usage=usage)

status = SDNAMETOINDEX (fid, name, Help=help, Usage=usage)

status = SDREADATTR (id, index, buf, Help=help, Usage=usage)

status = SDREADDATA (sdsid, start, stride, l_end, data, Help=help, Usage=usage)

status = SDSELECT (fid, index, Help=help, Usage=usage)

status = SDSETATTR (id, name, nt, count, data, Help=help, Usage=usage)

status = SDSETCAL (sdsid, cal, cale, ioff, ioffe, nt, Help=help, Usage=usage)

status = SDSETDATASTRS (sdsid, l, u, f, c, Help=help, Usage=usage)

status = SDSETDIMNAME (id, name, Help=help, Usage=usage)

status = SDSETDIMSCALE (id, count, nt, data, Help=help, Usage=usage)

status = SDSETDIMSTRS (id, l, u, f, Help=help, Usage=usage)

status = SDSETEXTERNALFILE (id, filename, offset, Help=help, Usage=usage)

status = SDSETFILLVALUE (sdsid, val, Help=help, Usage=usage)

status = SDSETRANGE (sdsid, pmax, pmin, Help=help, Usage=usage)

status = SDSTART (name, HDFmode, Help=help, Usage=usage)

status = SDWRITEDATA (sdsid, start, stride, l_end, data, Help=help, Usage=usage)

For complete descriptions of these routines, see the HDF Reference Manual.

status = VADDTAGREF (vg, tag, ref, Help=help, Usage=usage)

status = VATTACH (f, vgid, accesstype, Help=help, Usage=usage)

VDETACH, vg, Help=help, Usage=usage

VEND, f, Help=help, Usage=usage

VGETCLASS, vkey, vgclass, Help=help, Usage=usage

status = VGETID (f, vgid, Help=help, Usage=usage)

VGETNAME, vkey, vgname, Help=help, Usage=usage

status = VGETNEXT (vg, id, Help=help, Usage=usage)

status = VGETTAGREF (vg, which, tag, ref, Help=help, Usage=usage)

status = VGETTAGREFS (vg, tagarray, refarray, n, Help=help, Usage=usage)

status = VINQTAGREF (vg, tag, ref, Help=help, Usage=usage)

status = VINQUIRE (vg, nentries, vgname, Help=help, Usage=usage)

status = VINSERT (vgroup_id, v_id, Help=help, Usage=usage)

status = VISVG (vg, id, Help=help, Usage=usage)

status = VISVS (vg, id, Help=help, Usage=usage)

status = VLONE (f, idarray, asize, Help=help, Usage=usage)

status = VNTAGREFS (vg, Help=help, Usage=usage)

status = VSETCLASS(vkey, vgclass, Help=help, Usage=usage)

status = VSETNAME(vkey, vgname, Help=help, Usage=usage)

VSTART, f, Help=help, Usage=usage

For complete descriptions of these routines, see the HDF Reference Manual.

status = VSATTACH (f, vsid, accesstype, Help=help, Usage=usage)

VSDETACH, vs, Help=help, Usage=usage

status = VSELTS (vs, Help=help, Usage=usage)

status = VSFDEFINE (vs, field, localtype, order, Help=help, Usage=usage)

status = VSFEXIST (vs, fields, Help=help, Usage=usage)

status = VSFIND (f, vsname, Help=help, Usage=usage)

VSGETCLASS, vs, vsclass, Help=help, Usage=usage

status = VSGETFIELDS (vs, fields, Help=help, Usage=usage)

status = VSGETID (f, vsid, Help=help, Usage=usage)

status = VSGETINTERLACE (vs, Help=help, Usage=usage)

VSGETNAME, vs, vsname, Help=help, Usage=usage

status = VSINQUIRE (vs, nelt, interlace, fields, eltsize, vsname, Help=help, Usage=usage)

status = VSLONE (f, idarray, asize, Help=help, Usage=usage)

status = VSREAD (vs, buf, nelt, interlace, Help=help, Usage=usage)

status = VSSEEK (vs, eltpos, Help=help, Usage=usage)

VSSETCLASS, vs, vsclass, Help=help, Usage=usage

status = VSSETFIELDS (vs, fields, Help=help, Usage=usage)

status = VSSETINTERLACE (vs, interlace, Help=help, Usage=usage)

VSSETNAME, vs, vsname, Help=help, Usage=usage

status = VSSIZEOF (vs, fields, Help=help, Usage=usage)

status = VSWRITE (vs, buf, nelt, interlace, Help=help, Usage=usage)

For complete descriptions of these functions, see the HDF Reference Manual.

status = VFFIELDESIZE (vkey, index, Help=help, Usage=usage)

status = VFFIELDISIZE (vkey, index, Help=help, Usage=usage)

status = VFFIELDNAME (vkey, index, Help=help, Usage=usage)

status = VFFIELDORDER (vkey, index, Help=help, Usage=usage)

status = VFFIELDTYPE (vkey, index, Help=help, Usage=usage)

status = VFNFIELDS (vkey, Help=help, Usage=usage)

For complete descriptions of these functions, see the HDF Reference Manual.

status = VSQUERYCOUNT (vs, count, Helpzzzhelp, Usagezzzusage)

status = VSQUERYFIELDS (vs, flds, Help=help, Usage=usage)

status = VSQUERYINTERLACE (vs, intr, Help=help, Usage=usage)

status = VSQUERYNAME (vs, name, Help=help, Usage=usage)

status = VSQUERYREF (vkey, Help=help, Usage=usage)

status = VSQUERYTAG (vkey, Help=help, Usage=usage)

status = VSQUERYVSIZE (vs, size, Help=help, Usage=usage)

For complete descriptions of these functions, see the HDF Reference Manual.

status = VHMAKEGROUP (f, tagarray, refarray, n, vgname, vgclass, Help=help, Usage=usage)

status = VHSTOREDATA (f, field, buf, n, datatype, vsname, vsclass, Help=help, Usage=usage)

status = VHSTOREDATAM (f, field, buf, n, datatype, vsname, vsclass, order, Help=help, Usage=usage)