Reference Guide > PV-WAVE HDF Interface > Using the PV‑WAVE HDF4 Functions
  

Using the PV‑WAVE HDF4 Functions
Initializing the HDF4 Module
Before you can use any of the PV‑WAVE HDF4 base or convenience routines, you must initialize the HDF4 module. To to this, type:
WAVE> @hdf_startup
   PV-WAVE:HDF Module Initialized
After the module is initialized, you can use any of the PV‑WAVE HDF4 routines.
 
note
Include a call to HDF_STARTUP in your PV‑WAVE system startup file, or your personal PV‑WAVE startup file.
HDF_STARTUP Initializes Common Block Variables
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 HDF4 and NetCDF C libraries. For example, the NetCDF flag NC_WRITE is set to the value 1 in the file when the PV‑WAVE HDF4 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 defined in the HDF libraries
The HDF Calling Interfaces manual refers to these common variables in HDF4 calls. These variables are used frequently in many of the calls to PV‑WAVE HDF4 convenience routines and base routines.
 
note
hdf_common must be included in all PV‑WAVE procedures and functions that use PV‑WAVE HDF4 routines.
Input Data Is Converted to Required Data Type
Input data to the PV‑WAVE HDF4 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 HDF4 routine. By defining the PV‑WAVE variable with a dummy value of the proper data type, the PV‑WAVE HDF4 wrapper will automatically convert the fetched value to the desired data type.
Using the Usage and Help Keywords
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 HDF4 or NetCDF, but are provided for convenience to PV‑WAVE HDF4 users.
Ensure Correct Data Types with SDS GET Routines
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.
Use FORTRAN Array Alignment
Arrays in PV‑WAVE are aligned similar to FORTRAN (for example, column-major order or first subscript varying fastest), therefore, datasets and images should be aligned as discussed in the HDF4 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 × width × height” for pixel interlacing; however, in C, the same image array would be defined as “height × width × 3”.
Annotation Routines May Require Further Processing
Annotation routines which read or write descriptions (for example, DFANADDFDS, DFANGETDESC, HDFPUTANN, and so on) operate on byte arrays rather than strings and may require further processing.
Slab Routines Replace Slice Routines
The HDF Group 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 HDF4; however, the slice routines are not.
Base Functions Assume Valid Input
The PV‑WAVE HDF4 convenience routines are written to check input data for errors before continuing execution. The PV‑WAVE HDF4 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 HDF4 base routines and are experiencing core dumps, double check your input data for correct size and data type.

Version 2017.0
Copyright © 2017, Rogue Wave Software, Inc. All Rights Reserved.