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 insure backward compatibility with earlier versions of the HDF library. They can be assigned to two types of HDF objects: data sets and dimensions. (See Table 3X.)
TABLE 3X Predefined Attribute List
3.11.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.11 on page 87 and the second employs routines specifically designed for each attribute. 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 array attributes, predefined dimension attributes should be read or written using the specialized attribute routines only.
TABLE 3Y Predefined Attribute Parameter List
C: status = SDsetdatastrs(sds_id, label, unit, format, coordsys); FORTRAN: status = sfsdtstr(sds_id, label, unit, format, coordsys)
SDsetdatastrs assigns a predefined attribute to an SDS. The arguments for SDsetdatastrs are described in Table 3Z. To avoid creating one or more attributes, pass NULL as the appropriate argument.
3.11.2.2 Reading String Attributes: SDgetdatastrs
The following function reads the label, unit, format and coordinate system string attributes of an SDS:
C: status = SDgetdatastrs(sds_id, label, unit, format, coordsys, len); FORTRAN: status = sfgdtstr(sds_id, label, unit, format, coordsys, len)
SDgetdatastrs reads the predefined attributes of an SDS array. The arguments label, unit, format and coordsys are string buffers. If a particular attribute does not exist, the first character of the returned string will be NULL. Each string buffer is assumed to be at least len characters long, including the space to hold the NULL termination character. To avoid reading a particular attribute, pass NULL in the corresponding argument.
TABLE 3Z SDsetdatastrs and SDgetdatastrs Parameter List
C: status = SDsetdimstrs(dim_id, label, unit, format); FORTRAN: status = sfsdmstr(dim_id, label, unit, format)
SDsetdimstrs assigns label, unit and format attributes to an SDS dimension. The dim_id argument is the dimension identifier returned by the call to SDgetdimid. It identifies the dimension to which the attribute will be assigned. The remaining arguments are described below. (See Table 3AA on page 90.)
3.11.3.2 Reading a Dimension String Attribute: SDgetdimstrs
C: status = SDgetdimstrs(dim_id, label, unit, format, len); FORTRAN: status = sfgdmstr(dim_id, label, unit, format, len)
SDgetdimstrs reads the attributes specified by the label, unit and format parameters to an SDS dimension. The arguments label, unit, and format are buffers to hold the label, unit and format strings as defined in their respective attributes. If a particular attribute does not exist, the first character of the returned string will be NULL. Each buffer is assumed to be at least len characters long including the space to hold the NULL termination character. To avoid reading a particular attribute, pass NULL as the appropriate argument.
TABLE 3AA SDsetdimstrs and SDgetdimstrs Parameter List
C: status = SDsetrange(sds_id, max, min); FORTRAN: status = sfsrange(sds_id, max, min)
The parameters of SDsetrange are described below. (See Table 3AB on page 91.)
3.11.4.2 Reading a Range Attribute: SDgetrange
SDgetrange reads the maximum and minimum valid values of an SDS array as specified by a SDsetrange call or its equivalent:
C: status = SDgetrange(sds_id, max, min); FORTRAN: status = sfgrange(sds_id, max, min)
The arguments max and min are buffers the maximum and minimum values will be read into. The arguments in the C version of SDgetrange are pointers rather than simple variables, whereas in the Fortran-77 version they are variables of the same data type as the data set. The parameters of SDgetrange are described in the following table.
TABLE 3AB SDsetrange and SDgetrange Parameter List
A fill value must be of the same data type as the array to which it's 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.
Fill values can also be defined for all SDSs within a file. This is determined by setting a fill mode, which can be done by calling the SDsetfillmode routine described below.
C: status = SDsetfillvalue(sds_id, fill_val); FORTRAN: status = sfsfill(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.
3.11.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:
C: status = SDgetfillvalue(sds_id, fill_val); FORTRAN: status = sfgfill(sds_id, fill_val)
The argument fill_val is the space allocated to store the fill value.
3.11.5.3 Setting the Fill Mode for all SDSs in the Specified File: SDsetfillmode
Writing fill values to an SDS can involve more I/O overhead than is necessary. This is because, whenever a fill value is set for an SDS, two write operations are generally needed - one to write the fill value and one to write the actual dataset data. It is "generally needed" because, whenever all of the data is written to the dataset in one write operation the additional write operation to add the fill values is not performed, as it isn't necessary. For datasets containing contiguous data, preventing the HDF library from performing these fill value write operations can result in a substantial performance increase.
C: status = SDsetfillmode(file_id, fill_mode); FORTRAN: status = sfsflmd(file_id, fill_mode)
The argument file_id is the identifier of the file the fill mode will be applied to. The fill_mode argument is the fill mode to be applied - it can be set to either SD_FILL or SD_NOFILL. 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, this 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 specific SDSs by subsequent calls to SDsetfillvalue.
TABLE 3AC SDsetfillvalue, SDgetfillvalue and SDsetfillmode Parameter List,
C: status = SDsetcal(sds_id, cal, cal_error, offset, off_err, num_type); FORTRAN: status = sfscal(sds_id, cal, cal_error, offset, off_err, num_type)
SDsetcal must be called to calibrate the data before the data is written.
3.11.6.2 Reading Calibrated Data: SDgetcal
SDgetcal reads calibration attributes for an SDS array as written by a SDsetcal call or its equivalent:
C: status = SDgetcal(sds_id, cal, cal_error, off, off_err, num_type); FORTRAN: status = sfgcal(sds_id, cal, cal_error, off, off_err, num_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 FALSE. SDgetcal takes six arguments; sds_id, cal, cal_error, offset, off_err and num_type. These parameters are described in the following table.
TABLE 3AD SDsetcal and SDgetcal Parameter List
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}