Development Environment

MATLAB HDF Function Calling Conventions

Each HDF API includes many individual routines to read data from files, write data to files, and perform other related functions. For example, the HDF SD API includes separate C routines to open (SDopen), close (SDend), and read data (SDreaddata).

MATLAB, instead of supporting a corresponding function for each individual HDF API routine, supports a single function for each HDF API. You use this single function to access all the individual routines in the HDF API, specifying the name of the individual HDF routine as the first argument.

For example, to call the HDF SD API routine to terminate access to an HDF file in a C program, you use

• status = SDend(sd_id);
  

To call this routine from MATLAB, use the MATLAB function associated with the API. By convention, the name of the MATLAB function associated with an HDF API includes the API acronym in the function name. For example, the MATLAB function used to access routines in the HDF SD API is called hdfsd.

As the first argument to this function, specify the name of the API routine, minus the acronym, and pass the remaining arguments expected by the routine in the order they are required. Thus, to call the SDend routine from MATLAB, use this syntax:

• status = hdfsd('end',sd_id);
  

Note    For some HDF API routines, particularly those that use output arguments to return data, the MATLAB calling sequence is different. (See Handling HDF Routines with Output Arguments for more information.) Refer to the MATLAB online Function Reference to make sure you have the correct syntax.

Handling HDF Routines with Output Arguments

When calling HDF API routines that use output arguments to return data, you must specify all output arguments as return values. For example, in C syntax, the SDfileinfo routine returns data about an HDF file in two output arguments, ndatasets and nglobal_atts:

• status = SDfileinfo(sd_id, ndatasets, nglobal_atts);
  

To call this routine from MATLAB, change the output arguments into return values:

• [ndatasets, nglobal_atts, status] = hdfsd('fileinfo',sd_id);
  

Specify the return values in the same order as they appear as output arguments. The function status return value is always specified last.

Handling HDF Library Symbolic Constants

The C versions of the HDF APIs use symbolic constants, defined in header files, to specify modes and data types. For example, the SDstart routine uses a symbolic constant to specify the mode in which to open an HDF file:

• sd_id = SDstart("my_file.hdf",DFACC_RDONLY);
  

When calling this routine from MATLAB, specify these constants as text strings:

• sd_id = hdfsd('start','my_file.hdf','DFACC_RDONLY')
  

In MATLAB, you can specify the entire constant or leave off the prefix. For example, in this call to SDstart, you can use any of these variations as the constant text string: 'DFACC_RDONLY', 'dfacc_rdonly', or 'rdonly'. Note that you can use any combination of uppercase and lowercase characters.

Using the HDF Command-Line Interface

Exporting MATLAB Data in an HDF File