[Top] [Prev] [Next] [Bottom]

11.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.

11.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 11F DFSDgetdata Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

DFSDgetdata

(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 dat.

11.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 11G DFSDgetNT and DFSDgetdims Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

DFSDgetdims

(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

(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:

#include "hdf.h"

#define LENGTH 3
#define HEIGHT 2
#define WIDTH 5

main( )
{

	float64 scien_data[LENGTH][HEIGHT][WIDTH];
	int32 number_type;
	intn rank, status;
	int32 dims[3];

	/* Get the dimensions and number type of the array */
	status = DFSDgetdims("Example1.hdf", &rank, dims, 3);
	status = DFSDgetNT(&number_type);

	/* Read the array if the dimensions are correct */
	if (dims[0] <= LENGTH && dims[1] <= HEIGHT && dims[2] <= WIDTH)
    		status = DFSDgetdata("Example1.hdf", rank, dims, scien_data);

}

FORTRAN:

	 PROGRAM READ SDS      

      integer  dsgdata, dsgdims, dsgnt, dims(3), status
      integer rank, num_type
      real*8   sci_data(5, 2, 3)

C     Get the dimensions and number type of the array.
      status = dsgdims('Example1.hdf', rank, dims, 3)
      status = dsgnt(num_type)

C     Read the array if the dimensions are correct.
      if ((dims(1) .eq. 3) .and. (dims(2) .eq. 2) .and. 
     +    (dims(3) .eq. 5)) then 
            status = dsgdata('Example1.hdf', rank, dims, sci_data)
      endif

      end

11.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.

11.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, titled Annotations (DFAN API), and Chapter 5, titled Vgroups (V API).

TABLE 11H DFSDreadref Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

DFSDreadref

(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] [Bottom]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF Development Group.