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.
TABLE 11F DFSDgetdata Parameter List
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.
TABLE 11G DFSDgetNT and DFSDgetdims Parameter List
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); }
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)
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.
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.
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