Predefined string attributes are defined as follows:
C: status = DFSDsetlengths(label_len, unit_len, format_len, coords_len); status = DFSDsetdatastrs(label, unit, format, coordsys);status = DFSDadddata(filename, rank, dimsizes, data);
FORTRAN: status = dsslens(label_len, unit_len, format_len, coords_len) status = dssdast(label, unit, format, coordsys)
status = dsadata(filename, rank, dimsizes, data)
DFSDsetlengths has four arguments: label_len, unit_len, format_len, and coords_len. Each parameter reflects the maximum length for the string that will hold the label, unit, format, and coordinate system. Use of DFSDsetlengths is optional and usually not necessary.
TABLE 11L DFSDsetlengths and DFSDsetdatastrs Parameter List
To assign a value attribute to a data set, the following routines must be called:
C: status = DFSDsetfillvalue(fill_val); status = DFSDsetcal(scale, scale_err, offset, offset_err,num_type);
status = DFSDsetrange(max, min);
status = DFSDadddata(filename, rank, dimsizes, data);
FORTRAN: status = dssfill(fill_val) status = dsscal(scale, scale_err, offset, offset_err, num_type)
status = dssrang(max, min)
status = dsadata(filename, rank, dimsizes, data)
DFSDsetrange sets a new range attribute for the current DFSD SDS. DFSDsetrange has two arguments: max and min. The HDF library will not check or update the range attributes as new data are added to the file, therefore max and min will always reflect the values supplied by the last DFSDsetrange call. The parameters for DFSDsetrange is defined in Table 11K below.
DFSDsetfillvalue specifies a new value to the default fill value attribute for an SDS array. It's only argument is fill_val, which specifies the new fill value. The fill value must be of the same number type as the array it's written to. To avoid conversion errors, use data-specific fill values instead of special architecture-specific values, such as infinity or Not-a-Number (or NaN). Setting the fill value after data is written to the SDS will not update the fill values already written to the data set - it will only change the attribute.
The DFSDsetcal routine creates a calibration record for a specified array and by doing so adds five attributes to the current data set. As the HDF library does not specifically apply calibration information to the data, SDsetcal can be called anytime before or after the data is written. DFSDsetcal has five arguments; scale, scale_error, offset, off_err, and num_type. The arguments scale and offset are defined as they are for the multifile SD API routines.
TABLE 11M DFSDsetfillvalue, DFSDsetrange and DFSDsetcal Parameter List
C:
#include "hdf.h" /* * Write an array of floating point values representing * pressure in a 3x2x5 array. */ main( ) { float32 data[3][2][5]; int32 dimsizes[3]; float32 max, min; intn status, rank; int i, j, k; /* Set the rank and dimension sizes. */ rank = 3; dimsizes[0] = 3; dimsizes[1] = 2; dimsizes[2] = 5; /* Set the dimensions, to define the beginning of a data set. */ status = DFSDsetdims(rank, dimsizes); /* Set the maximum string length to 50. */ status = DFSDsetlengths(50, 50, 50, 50); /* Define the attribute strings and values. */ status = DFSDsetdatastrs("Pressure Data", "Millibars", "F5.5", "None"); max = 1500.0; min = 0.0; status = DFSDsetrange(&max, &min); /* Set the rank to 3. */ rank = 3; /* Calculate the data values. */ for (i = 0; i < 3; i++) for (j = 0; j < 2; j++) for (k = 0; k < 5; k++) data[i][j][k] = i*100.0 + j*10.0 + k; /* Write the data set and its attributes to file. */ status = DFSDadddata("Example3.hdf", rank, dimsizes, data); } FORTRAN:PROGRAM SET ATTRIBS real*8 data(5, 2, 3), max, min, i, j, k integer*4 dimsizes(3) integer status, rank integer dsslens, dssdast, dssrang, dsadata integer dssdims character*13 label /"Pressure Data"/ character*9 unit /"Millibars"/ character*4 format /"F5.5"/ character*4 coordsys /"None"/ C Set the dimensions, to define the beginning of a data set. rank = 3 dimsizes(1) = 5 dimsizes(2) = 2 dimsizes(3) = 3 status = dssdims(rank, dimsizes) C Set the maximum string lengths to 50. status = dsslens(50, 50, 50, 50) C Define the attribute strings and values. status = dssdast(label, unit, format, coordsys) max = 1500.0 min = 0.0 status = dssrang(max, min) C Fill the data array with values. do 30 k = 1, 3 do 20 j = 1, 2 do 10 i = 1, 5 data(i, j, k) = i*100.0 + j*10.0 + k 10 continue 20 continue 30 continue C Write the data set and its attributes to file. status = dsadata("Example3.hdf", rank, dimsizes, data) end
11.7.2 Reading DFSD Data Set Attributes
The DFSD interface provides two function calls for reading predefined data set attribute strings. 11.7.2.1 Reading Data Set Attributes: DFSDgetdatalen and DFSDgetdatastrs
DFSDgetdatalen returns the length of each string in the attribute. It is useful for determining the length of an attribute before reading it. DFSDgetdatastrs reads the label, unit, format, and coordinate system strings.
C: status = DFSDgetdatalen(label_len, unit_len, format_len, coords_len); status = DFSDgetdatastrs(label, unit, format, coordsys);status = DFSDgetrange(max, min);
status = DFSDgetdata(filename, rank, dimsizes, data);
FORTRAN: status = dsgdghaln(label_len, unit_len, format_len, coords_len) status = dsgdast(label, unit, format, coordsys)
status = dsgrang(max, min)
status = dsgdata(filename, rank, dimsizes, data)
The parameters of DFSDgetdatalen and DFSDgetdatastrs are described in the following table.
TABLE 11N DFSDgetdatalen and DFSDgetdatastrs Parameter List
C:
#include "hdf.h" main( ) { intn rank, maxrank, status; int32 dimsizes[3]; char datalabel[50], dataunit[50], datafmt[50], coordsys[50]; float64 data[3][2][5]; maxrank = 3; status = DFSDgetdims("Example3.hdf", &rank, dimsizes, maxrank); status = DFSDgetdatastrs(datalabel, dataunit, datafmt, coordsys); status = DFSDgetdata("Example3.hdf", rank, dimsizes, data); }
PROGRAM READ SD INFO integer dsgdata, dsgdast, dsgdims integer*4 dimsizes(3) integer status, rank, maxrank character*50 datalabel, dataunit, datafmt character*10 coordsys real*8 data(5, 2, 3) maxrank = 3 status = dsgdims('Example3.hdf', rank, dimsizes, maxrank) status = dsgdast(datalabel, dataunit, datafmt, coordsys) status = dsgdata('Example3.hdf', rank, dimsizes, data) end
11.7.2.2 Reading the Value Attributes of a DFSD Data Set: DFSDgetfillvalue and DFSDgetcal
There are three routines in the DFSD interface that retrieve the fill value, range and calibration information of a data set array: DFSDgetfillvalue, DFSDgetrange and DFSDgetcal.
C: status = DFSDgetfillvalue(sds_id, fill_val); status = DFSDgetrange(max, min);status = DFSDgetcal(cal, cal_err, offset, offset_err, num_type);
FORTRAN: status = dsgfill(fill_value) status = dsgrang(max, min)
status = dsadata(cal, cal_err, offset, offset_err, num_type)
DFSDgetfillvalue has two arguments; sds_id and fill_val. The sds_id is the data set identifier and fill_val is the space allocated to store the fill value.
TABLE 11O DFSDgetfillvalue, DFSDgetcal and DFSDgetrange Parameter List
Predefined dimension string attributes are limited to one per dimension and contain the following:
To assign a predefined attribute to a dimension, the following routines should be called:
C: status = DFSDsetlengths(label_len, unit_len, format_len, coords_len); status = DFSDsetdimstrs(label, unit, format);status = DFSDadddata(filename, rank, dimsizes, data);
FORTRAN: status = dsslens(label_len, unit_len, format_len, coords_len) status = dssdist(label, unit, format)
status = dsadata(filename, rank, dimsizes, data)
DFSDsetlengths has four arguments: label_len, unit_len, format_len, and coords_len. Each parameter specifies the maximum length of the string that defines the label, unit, format, and coordinate system. As mentioned earlier in this chapter, attribute lengths seldom need to be reset..
TABLE 11P DFSDsetlengths and DFSDsetdimstrs Parameter List
C: status = DFSDsetdimscale(dim, dimsize, scale); status = DFSDadddata(filename, rank, dimsizes, data);
FORTRAN: status = dssdisc(dim, dimsize, scale) status = dsadata(filename, rank, dimsizes, data)
DFSDsetdimscale has three arguments; dim, dimsize, and scale. These arguments identify the dimension, specify its size, and assign a value to each of its grid points. The parameter dim = 1 for the first dimension, and dim = 2 for the second dimension. The dimsize argument must contain a value equal to the dimension it describes in order for the scale to be applied correctly.
TABLE 11Q DFSDsetdimscale Parameter List
Reading data set attributes involves the following steps:
C: status = DFSDgetdimlen(label_len, unit_len, format_len, coords_len); status = DFSDgetdimstrs(label, unit, format);status = DFSDgetdimscale(dim, dim_size, scale);
status = DFSDgetdata(filename, rank, dimsizes, data);
FORTRAN: status = dsgdiln(label_len, unit_len, format_len, coords_len) status = dsgdist(label, unit, format)
status = dsgdisc(dim, dim_size, scale)
status = dsgdata(filename, rank, dimsizes, data)
The parameters for DFSDgetdimlen, DFSDgetdimstrs and DFSDgetdimscale are described in the following table.
TABLE 11R DFSDgetdimlen, DFSDgetdimstrs and DFSDgetdimscale Parameter List