12.7.1.1 Assigning String Attributes to an SDS: DFSDsetlengths and DFSDsetdatastrs
The DFSD interface provides two function calls for creating data set string attributes: DFSDsetlengths and DFSDsetdatastrs. DFSDsetlengths overrides the default string length and DFSDsetdatastrs writes the string. DFSDsetlengths and DFSDsetdatastrs are optional and may be called individually, or in any order as long as they precede calls to DFSDadddata or DFSDputdata.
To assign a predefined attribute to an HDF file, the program must contain the following routine calls:
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. label, unit, format, and coordsys. To avoid the assignment of a string, pass NULL as the appropriate argument.TABLE 12L - 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 K 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.scale and offset, DFSDsetcal also includes both a scale and offset error. The argument scale_err contains the potential error of the calibrated data due to scaling and offset_err contains the potential error for the calibrated data due to the offset. The num_type parameter specifies the number type of the uncalibrated data. TABLE 12M - DFSDsetfillvalue, DFSDsetrange and DFSDsetcal Parameter List
C version
12.7.2 Reading DFSD Data Set Attributes
The DFSD interface provides two function calls for reading predefined data set attribute strings. 12.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.
To assign a predefined attribute to an HDF file, the following routines should be called:
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 12N - DFSDgetdatalen and DFSDgetdatastrs Parameter List
data, datalabel, dataunit, datafmt and coordsys pointer variables. It assumes the dimension sizes and rank are correct and data strings are less than 10 characters long, with one additional character for the null termination.C version
12.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. max parameter is the maximum value of the defined range and the value of the min parameter is the minimum value. These values must be of the same number type as the values stored in the data array. In C, the max and min parameters are indirect pointers specifying the range values, while in FORTRAN-77 they are variables set to the range values.cal, offset, offset_err and cal_err parameters are defined as they are in the multifile SD API. This calibration record exists for information only.TABLE 12O - DFSDgetfillvalue, DFSDgetcal and DFSDgetrange Parameter List
12.7.3.1 Writing the String Attributes of a Dimension: DFSDsetlengths and DFSDsetdimstrs
The DFSD interface provides two routines for creating dimension string attributes: DFSDsetlengths and DFSDsetdimstrs. DFSDsetlengths overwrites the default string length and DFSDsetdimstrs is defines the string text. DFSDsetdatalengths and DFSDsetdimstrs are optional and must precede calls to DFSDadddata or DFSDputdata.
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.dim, label, unit, and format. The parameter dim = 1 for the first dimension, dim = 2 for the second dimension, etc. To avoid assigning a string to the coordinate length, pass NULL in the appropriate parameter. DFSDsetdimstrs writes null-terminated strings to a file.TABLE 12P - 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. The parameters of DFSDsetdiscale are further described in the following table.
Reading data set attributes involves the following steps:
To assign a predefined attribute to an HDF file, the following routines must be called:
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 12R - DFSDgetdimlen, DFSDgetdimstrs and DFSDgetdimscale Parameter List