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.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 12F - 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. The parameters of DFSDgetdims and DFSDgetNT are further defined in the following table.
C 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. 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, Annotations (AN API), and Chapter 5, Vgroups (V API).
TABLE 12H - DFSDreadref Parameter List