Predefined attributes are useful because they establish conventions that applications can depend on and because they are understood by the HDF library without users having to define them. Predefined attributes also ensure backward compatibility with earlier versions of the HDF library. They can be assigned only to data sets and dimensions. Table 3T lists the predefined attributes and the types of object each attribute can be assigned to.
TABLE 3T - Predefined Attributes List
missing_value value could be supplied. The missing_value attribute is different from the _FillValue attribute in that fill values are intended to indicate data that was expected but did not appear, whereas missing values are used to indicate data that were never expected.
3.10.1 Accessing Predefined Attributes
The SD interface provides two methods for accessing predefined attributes. The first method uses the general attribute routines for user-defined attributes described in Section 3.9 on page 49; the second employs routines specifically designed for each attribute and will be discussed in the following sections. Although the general attribute routines work well and are recommended in most cases, the specialized attribute routines are sometimes easier to use, especially when reading or writing related predefined attributes. This is true for two reasons. First, because predefined attributes are guaranteed unique names, the attribute index is unnecessary. Second, attributes with several components may be read as a group. For example, using the SD routine designed to read the predefined calibration attribute returns all five components with a single call, rather than five separate calls.
There is one exception: unlike predefined data set attributes, predefined dimension attributes should be read or written using the specialized attribute routines only.
TABLE 3U - Predefined Attribute Definitions
C: status = SDsetdatastrs(sds_id, label, unit, format, coord_system);
FORTRAN: status = sfsdtstr(sds_id, label, unit, format, coord_system)If you do not wish to set an attribute, set the corresponding parameter to
NULL in C and an empty string in FORTRAN-77. SDsetdatastrs returns a value of SUCCEED (or 0) or FAIL (or -1). Its arguments are further described in Table 3V on page 56.
3.10.2.2 Reading String Attributes of an SDS: SDgetdatastrs
SDgetdatastrs reads the predefined string attributes label, unit, format, and coordinate system from an SDS. These string attributes have previously been set by the routine SDsetdatastrs. The syntax of SDgetdatastrs is as follows:C: status = SDgetdatastrs(sds_id, label, unit, format, coord_system, len);
FORTRAN: status = sfgdtstr(sds_id, label, unit, format, coord_system, len)
SDgetdatastrs stores the predefined attributes into the parameters label, unit, format, and coord_system, which are character string buffers. If a particular attribute has not been set by SDsetdatastrs, the first character of the corresponding returned string will be NULL for C and 0 for FORTRAN-77. Each string buffer is assumed to be at least len characters long, including the space to hold the NULL termination character. If you do not wish to get a predefined attribute of this SDS, set the corresponding parameter to NULL in C and an empty string in FORTRAN-77. SUCCEED (or 0) or FAIL (or -1). Its parameters are further described in Table 3V.
TABLE 3V - SDsetdatastrs and SDgetdatastrs Parameter Lists
3.10.3 String Attributes of Dimensions
Predefined string attributes of a dimension include label, unit, and format. They adhere to the same definitions as those of the label, unit, and format strings for SDS attributes. 3.10.3.1 Writing a String Attribute of a Dimension: SDsetdimstrs
SDsetdimstrs assigns the predefined string attributes label, unit, and format to an SDS dimension and its scales. The syntax of this routine is as follows:C: status = SDsetdimstrs(dim_id, label, unit, format);
FORTRAN: status = sfsdmstr(dim_id, label, unit, format)
The argument dim_id is the dimension identifier, returned by SDgetdimid, and identifies the dimension to which the attributes will be assigned. If you do not wish to set an attribute, set the corresponding parameter to NULL in C and an empty string in FORTRAN-77.SUCCEED (or 0) or FAIL (or -1). Its parameters are further described in Table 3W.
3.10.3.2 Reading a String Attribute of a Dimension: SDgetdimstrs
SDgetdimstrs reads the predefined string attributes label, unit, and format from an SDS dimension. These string attributes have previously been set by the routine SDsetdimstrs. The syntax of SDgetdimstrs is as follows:C: status = SDgetdimstrs(dim_id, label, unit, format, len);
FORTRAN: status = sfgdmstr(dim_id, label, unit, format, len)
SDgetdimstrs stores the predefined attributes of the dimension into the arguments label, unit, and format, which are character string buffers. If a particular attribute has not been set by SDsetdimstrs, the first character of the corresponding returned string will be NULL for C and 0 for FORTRAN-77. Each string buffer is assumed to be at least len characters long, including the space to hold the NULL termination character. If you do not wish to get a predefined attribute of this dimension, set the corresponding parameter to NULL in C and an empty string in FORTRAN-77.SUCCEED (or 0) or FAIL (or -1). Its parameters are further described in Table 3W.
TABLE 3W - SDsetdimstrs and SDgetdimstrs Parameter Lists
sds_id to the values provided by the parameters max and min. The syntax of the routine is as follows:
C: status = SDsetrange(sds_id, max, min);
FORTRAN: status = sfsrange(sds_id, max, min)SDsetrange does not compute the maximum and minimum range values, it only stores the values as given. As a result, the maximum and minimum range values may not always reflect the actual maximum and minimum range values in the data set data. Recall that the type of max and min is assumed to be the same as that of the data set data.
SDsetrange returns a value of
SUCCEED (or 0) or FAIL (or -1). Its parameters are further described in Table 3X.
3.10.4.2 Reading a Range Attribute: SDgetrange
SDgetrange reads the maximum and minimum valid values of a data set. The syntax of this routine is as follows:C: status = SDgetrange(sds_id, &max, &min);
FORTRAN: status = sfgrange(sds_id, max, min)
The maximum and minimum range values are stored in the parameters max and min, respectively, and must have previously been set by SDsetrange. Recall that the type of max and min is assumed to be the same as that of the data set data.SUCCEED (or 0) or FAIL (or -1). Its parameters are further described in Table 3X.
TABLE 3X - SDsetrange and SDgetrange Parameter Lists
A fill value must be of the same data type as the array to which it is written. To avoid conversion errors, use data-specific fill values instead of special architecture-specific values, such as infinity and Not-a-Number or NaN.
A fill mode specifies whether the fill value is to be written to all the SDSs in the file; it can be set with SDsetfillmode.
Writing fill values to an SDS can involve more I/O overhead than is necessary, particularly in situations where the data set is to be contiguously filled with data before any read operation is made. In other words, writing fill values is only necessary when there is a possibility that the data set will be read before all gaps between writes are filled with data, i.e., before all elements in the array have been assigned values. Thus, for a file that has only data sets containing contiguous data, the fill mode should be set to
SD_NOFILL (or 256). Avoiding unnecessary filling can substantially increase the application performance.For a non-contiguous data set, the array elements that have no actual data values must be filled with a fill value before the data set is read. Thus, for a file that has a non-contiguous data set, the fill mode should be set to
SD_FILL (or 0) and a fill value will be written to the all data sets in the file.Note that, currently, SDsetfillmode specifies the fill mode of all data sets in the file. Thus, either all data sets are in
SD_FILL mode or all data sets are in SD_NOFILL mode. However, when a specific SDS needs to be written with a fill value while others in the file do not, the following procedure can be used: set the fill mode to SD_FILL, write data to the data set requiring fill values, then set the fill mode back to SD_NOFILL. This procedure will produce one data set with fill values while the remaining data sets have no fill values.
C: status = SDsetfillvalue(sds_id, fill_val);
FORTRAN: status = sfsfill(sds_id, fill_val)
OR status = sfscfill(sds_id, fill_val)The argument
fill_val is the new fill value. It is recommended that you set the fill value before writing data to an SDS array, as calling SDsetfillvalue after data is written to an SDS array only changes the fill value attribute - it does not update the existing fill values. There are two FORTRAN-77 versions of this routine: sfsfill and sfscfill. sfsfill writes numeric fill value data and sfscfill writes character fill value data.
SDsetfillvalue returns a value of
SUCCEED (or 0) or FAIL (or -1). Its parameters are further described in Table 3Y on page 60.
3.10.5.2 Reading a Fill Value Attribute: SDgetfillvalue
SDgetfillvalue reads in the fill value of an SDS array as specified by a SDsetfillvalue call or its equivalent. The syntax of this routine is as follows:C: status = SDgetfillvalue(sds_id, &fill_val);
FORTRAN: status = sfgfill(sds_id, fill_val)
OR status = sfgcfill(sds_id, fill_val)
The fill value is stored in the argument fill_val which is previously allocated based on the data type of the SDS data.SUCCEED (or 0) if a fill value is retrieved successfully, or FAIL (or -1) otherwise, including when the fill value has not been set. The parameters of SDgetfillvalue are further described in Table 3Y.
3.10.5.3 Setting the Fill Mode for all SDSs in the Specified File: SDsetfillmode
SDsetfillmode sets the fill mode for all data sets contained in the file identified by the parameter sd_id. The syntax of SDsetfillmode is as follows:C: old_fmode = SDsetfillmode(sd_id, fill_mode);
FORTRAN: old_fmode = sfsflmd(sd_id, fill_mode)
The argument fill_mode is the fill mode to be applied and can be set to either SD_FILL (or 0) or SD_NOFILL (or 256). SD_FILL specifies that fill values will be written to all SDSs in the specified file by default. If SDsetfillmode is never called before SDsetfillvalue, SD_FILL is the default fill mode. SD_NOFILL specifies that, by default, fill values will not be written to all SDSs in the specified file. This can be overridden for a specific SDS by calling SDsetfillmode then writing data to this data set before closing the file.SD_FILL fill mode will be in effect until it is changed by a call to SDsetfillmode.FAIL (or -1). The parameters of this routine are further described in Table 3Y.
TABLE 3Y - SDsetfillvalue, SDgetfillvalue, and SDsetfillmode Parameter Lists
float could be stored as an array containing data of type 8- or 16-bit integer. Note that neither function performs any operation on the data set.
C: status = SDsetcal(sds_id, cal, cal_error, offset, off_err, data_type);
FORTRAN: status = sfscal(sds_id, cal, cal_error, offset, off_err, data_type)SDsetcal has six arguments;
sds_id, cal, cal_error, offset, off_err, and data_type. The argument cal represents a single value that when multiplied against every value in the calibrated data array reproduces the original data array (assuming an offset of 0). The argument offset represents a single value that when subtracted from every value in the calibrated array reproduces the original data (assuming a offset of 1). The values of the calibrated data array relate to the values of the original data array according to the following equation:
orig_value = cal * (cal_value - offset)In addition to
cal and offset, SDsetcal also includes the scale and offset errors. The argument cal_err contains the potential error of the calibrated data due to scaling; offset_err contains the potential error for the calibrated data due to the offset. SDsetcal returns a value of
SUCCEED (or 0) or FAIL (or -1). Its parameters are further described in Table 3Z.
3.10.6.2 Reading Calibrated Data: SDgetcal
SDgetcal reads calibration attributes for an SDS array as previously written by SDsetcal. The syntax of this routine is as follows:C: status = SDgetcal(sds_id, &cal, &cal_error, &offset, &offset_err, &data_type);
FORTRAN: status = sfgcal(sds_id, cal, cal_error, offset, offset_err, data_type)
Because the HDF library does not actually apply calibration information to the data, SDgetcal can be called anytime before or after the data is read. If a calibration record does not exist, SDgetcal returns FAIL. SDgetcal takes six arguments: sds_id, cal, cal_error, offset, offset_err, and data_type. Refer to Section 3.10.6.1 for the description of these arguments.
SDgetcal returns a value of SUCCEED (or 0) or FAIL (or -1). The parameters of SDgetcal are described in Table 3Z.
TABLE 3Z - SDsetcal and SDgetcal Parameter Lists
cal_val are the following integers:
cal_val[6] = {2, 4, 5, 11, 26, 81}
By applying the calibration equation orig = cal * (cal_val - offset) with cal = 0.50 and offset = -2000.0, the calibrated array cal_val[] returns to its original floating-point form:
original_val[6] = {1001.0, 1002.0, 1002.5, 1005.5, 1013.0, 1040.5}