[Top] [Prev] [Next]

12.5 Reading DFSD Scientific Data Sets

The DFSD programming model for reading an SDS is also a two-step operation:

  1. Obtain information about the data set if necessary.
  2. Read all or part of the data set.

These steps are performed for every data set read. In some cases, calls to determine the data set definition may be reduced or avoided completely. For example, if the data set dimensions are known, the call that returns the data set dimensions may be eliminated.

12.5.1 Reading a DFSD SDS: DFSDgetdata

If the dimensions of the data set are known, DFSDgetdata is the only function call required to read an SDS. If the file is being opened for the first time, DFSDgetdata returns the first data set in the file. Any subsequent calls will return successive data sets in the file - data sets are read in the same order they were written. Normally, DFSDgetdims is called before DFSDgetdata so that space allocations for the array can be checked if necessary and the dimensions verified. If this information is already known, DFSDgetdims may be omitted.

To read an SDS of known dimension and number type, the calling program should include the following routine:

C:		status = DFSDgetdata(filename, rank, dim_sizes, data);
FORTRAN:	status = dsgdata(filename, rank, dim_sizes, data)
DFSDgetdata has four parameters: filename, rank, dim_sizes, and data. DFSDgetdata returns a data set specified by the parameter filename. The total number of dimensions is specified in rank and the size of each dimension is specified in dim_sizes. DFSDgetdata returns the array in data.

The parameters of DFSDgetdata are further defined in the following table.

TABLE 12F - DFSDgetdata Parameter List

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
DFSDgetdata

[intn]

(dsgdata)
filename
char
character*(*)
Name of the file containing the data.

rank
int32
integer
Number of dimensions.

dim_sizes
int32 *
integer (*)
Buffer for the dimension sizes.

data
VOIDP
<valid numeric data type>
Buffer for the stored scientific data.

12.5.2 Specifying the Dimensions and Data Type of an SDS: DFSDgetdims and DFSDgetNT

When DFSDgetdims is first called, it returns dimension information of the first data set. Subsequent calls will return this information for successive data sets. If you need to determine the dimensions or the data type of an array before reading it, call DFSDgetdims and DFSDgetNT. DFSDgetNT gets the data type (or, in HDF parlance, number type) of the data retrieved in the next read operation.

To determine the dimensions and data type of an array before attempting to read it, the calling program must include the following:

C:		status = DFSDgetdims(filename, rank, dimsizes, max_rank);
		status = DFSDgetNT(number_type);
		status = DFSDgetdata(filename, rank, dimsizes, data);
FORTRAN:	status = dsgnt(filename, rank, dimsizes, max_rank)
		status = dsgdims(number_type)
		status = dsgdata(filename, rank, dimsizes, data)
DFSDgetdims has four parameters: filename, rank, dim_sizes, and maxrank. The number of dimensions is returned in rank, the size of each dimension in the array dim_sizes, and the size of the array containing the dimensions sizes in max_rank. DFSDgetNT has only one parameter: number_type. As there is no way to specify the file or data set through the use of DFSDgetNT, it is only valid if it is called after DFSDgetdims.

The parameters of DFSDgetdims and DFSDgetNT are further defined in the following table.

TABLE 12G - DFSDgetNT and DFSDgetdims Parameter List

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
DFSDgetdims

[intn]

(dsgdims)
filename
char *
character*(*)
Name of file containing the data.

rank
intn *
integer
Number of dimensions.

dim_sizes
int32 *
integer
Buffer for the dimension sizes.

max_rank
intn
integer
Size of the dimension size buffer.

DFSDgetNT

[intn]

(dsgnt)
number_type
int32 *
integer
Data type of the data to be read.

EXAMPLE 2. Reading from a DFSD Scientific Data Set

The following examples search the file named "Example1.hdf" for the dimensions and data type of a DFSD array. Although use of DFSDgetdims and DFSDgetNT is optional, they are included here as a demonstration of how to verify the array dimensions and number type before reading any data. If the dimensions and type are known, only a call to DFSDgetdata is required.

C version



FORTRAN-77 version



12.5.3 Determining the Number of DFSD Data Sets: DFSDndatasets and DFSDrestart

DFSDgetdims and DFSDgetdata sequentially access DFSD data sets. By repeatedly calling either function, a program can step through an entire file by reading one data set at a time. However, before attempting to sequentially access all of the data sets in a file the total number of data sets in the file should be determined. To do so, the calling program must call the following routine:

C:		num_of_datasets = DFSDndatasets(filename);
FORTRAN:	num_of_datasets = dsnum(filename)
Once the total number of data sets is known, a calling program can at any time, reset the current data set to the first data set in the file by calling the following routine:

C:		status = DFSDrestart( );
FORTRAN:	status = dsfirst( )
Use of DFSDndatasets and DFSDrestart is optional, it is usually more convenient than cycling through the entire file one SDS at a time.

12.5.4 Obtaining Reference Numbers of DFSD Data Sets: DFSDreadref and DFSDlastref

As the HDF library handles the assignment and tracking of reference numbers, reference numbers must be explicitly returned. Obtaining the reference number is an operation best performed immediately after data set creation.

The DFSD interface uses the function DFSDreadref to initiate access to individual scientific data sets. DFSDreadref specifies the reference number of the next SDS to be read.

To access a specific SDS, the calling program must contain the following routines:

C:		status = DFSDreadref(filename, ref);
		status = DFSDgetdata(filename, rank, dim_sizes, data);
FORTRAN:	status = dsrref(filename, ref)
		status = dsgdata(filename, rank, dim_sizes, data)
DFSDreadref has two parameters: filename and ref. DFSDreadref specifies the reference number of the object to be next operated on in the HDF file filename as ref. Determining the correct reference number is the most difficult part of this operation. As a result, DFSDreadref is often used in conjunction with DFSDlastref, which determines the reference number of the last data set accessed.

To syntax of DFSDadddata and DFSDlastref is:

C:		status = DFSDadddata(filename, rank, dim_sizes, data);
		ref_num = DFSDlastref( );
FORTRAN:	status = dsadata(filename, rank, dim_sizes, data)
		ref_num = dslref( )
DFSDputdata can also be used with DFSDlastref to obtain similar results. In any case, DFSDlastref can be used before any operation that requires identifying a scientific data set by reference number, as in the assignment of annotations and inserting data sets into vgroups. For more information about annotations and vgroups refer to Chapter 10, Annotations (AN API), and Chapter 5, Vgroups (V API).

TABLE 12H - DFSDreadref Parameter List

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
DFSDreadref

[intn]

(dsrref)
filename
char *
character*(*)
Name of the file containing the data set.

ref_number
uint16
integer
Reference number of the next data set to be read.



[Top] [Prev] [Next]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 07/21/98, NCSA HDF Development Group.