[Top] [Prev] [Next]

3.10 Predefined Attributes

Predefined attributes use reserved names and in some cases predefined data type names. Predefined attributes are categorized as follows:

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

HDF Data Object Type
Attribute Category
Attribute Name
Description
SDS Array
or
Dimension
Label long_name Name of the array

Unit units Units used for all dimensions and data

Format format Format for displaying dim scales and array values

SDS Array Only
Coordinate System cordsys Coordinate system used to interpret the SDS array

Range valid_range Maximum and minimum values within a selected data range

Fill Value __FillValue Value used to fill empty locations in an SDS array

Calibration scale_factor Value by which each array value is to be multiplied

scale_factor_err Error introduced by scaling SDS array data

add_offset Value to which each array value is to be added

add_offset_err Error introduced by offsetting the SDS array data

calibrated_nt Data type of the calibrated data

While the following netCDF naming conventions are not predefined in HDF, they are highly recommended to promote consistency of information-sharing among generic applications. Refer to the netCDF User's Guide for C for further information.

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 50; 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.

The predefined attribute parameters are described in Table 3U. Creating a predefined attribute with parameters different from these will produce unpredictable results when the attribute is read using the corresponding predefined-attribute routine.

TABLE 3U - Predefined Attribute Definitions

Category
Attribute Name
Data Type
Number of Values
Attribute Description
Label
long_name
DFNT_CHAR8
String length
Pointer to string

Unit
units
DFNT_CHAR8
String length
Pointer to string

Format
format
DFNT_CHAR8
String length
Pointer to string

Coordinate
System
cordsys
DFNT_CHAR8
String length
Pointer to string

Range
valid_range
<valid data type>
2
Pointer to array

Fill Value
_FillValue
<valid data type>
1
Pointer to fill value

Calibration
scale_factor
DFNT_FLOAT64
1
Pointer to scale

scale_factor_err
DFNT_FLOAT64
1
Pointer to scale error

add_offset
DFNT_FLOAT64
1
Pointer to offset

add_offset_err
DFNT_FLOAT64
1
Pointer to offset error

calibrated_nt
DFNT_INT32
1
Pointer to data type

In addition to SDreadattr, SDfindattr and SDattrinfo are also valid general attribute routines to use when reading a predefined attribute. SDattrinfo is always useful for determining the size of an attribute whose value contains a string.

3.10.2 SDS String Attributes

This section describes the predefined string attributes of the SDSs and the next section describes those of the dimensions. Predefined string attributes of an SDS include the label, unit, format, and coordinate system.

3.10.2.1 Writing String Attributes of an SDS: SDsetdatastrs

SDsetdatastrs assigns the predefined string attributes label, unit, format, and coordinate system to an SDS array. The syntax of this routine is as follows:

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 57.

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.

SDgetdatastrs returns a value of SUCCEED (or 0) or FAIL (or -1). Its parameters are further described in Table 3V.

TABLE 3V - SDsetdatastrs and SDgetdatastrs Parameter Lists
Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
SDsetdatastrs

[intn]

(sfsdtstr)
sds_id
int32
integer
Data set identifier

label
char *
character*(*)
Label for the data

unit
char *
character*(*)
Definition of the units

format
char *
character*(*)
Description of the data format

coord_syst em
char *
character*(*)
Description of the coordinate system

SDgetdatastrs

[intn]

(sfgdtstr)
sds_id
int32
integer
Data set identifier

label
char *
character*(*)
Buffer for the label

unit
char *
character*(*)
Buffer for the description of the units

format
char *
character*(*)
Buffer for the description of the data format

coord_syst em
char *
character*(*)
Buffer for the description of the coordinate system

len
intn
integer
Minimum length of the string buffers

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.

SDsetdimstrs returns a value of 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.

SDgetdimstrs returns a value of SUCCEED (or 0) or FAIL (or -1). Its parameters are further described in Table 3W.

TABLE 3W - SDsetdimstrs and SDgetdimstrs Parameter Lists

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
SDsetdimstrs

[intn]

(sfsdmstr)
dim_id
int32
integer
Dimension identifier

label
char *
character*(*)
Label describing the specified dimension

unit
char *
character*(*)
Units to be used with the specified dimension

format
char *
character*(*)
Format to use when displaying the scale values

SDgetdimstrs

[intn]

(sfgdmstr)
dim_id
int32
integer
Dimension identifier

label
char *
character*(*)
Buffer for the dimension label

unit
char *
character*(*)
Buffer for the dimension unit

format
char *
character*(*)
Buffer for the dimension format

len
intn
integer
Maximum length of the string attributes

3.10.4 Range Attributes

The attribute range contains user-defined maximum and minimum values in a selected range. Since the HDF library does not check or update the range attribute as data is added or removed from the file, the calling program may assign any values deemed appropriate. Also, because the maximum and minimum values are supposed to relate to the data set, it is assumed that they are of the same data type as the data.

3.10.4.1 Writing a Range Attribute: SDsetrange

SDsetrange sets the maximum and minimum range values for the data set identified by 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.

SDgetrange returns a value of SUCCEED (or 0) or FAIL (or -1). Its parameters are further described in Table 3X.

TABLE 3X - SDsetrange and SDgetrange Parameter Lists

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
SDsetrange

[intn]

(sfsrange)
sds_id
int32
integer
Data set identifier

max
VOIDP
<valid data type>
Maximum value to be stored

min
VOIDP
<valid data type>
Minimum value to be stored

SDgetrange

[intn]

(sfgrange)
sds_id
int32
integer
Data set identifier

max
VOIDP
<valid data type>
Buffer for the maximum value

min
VOIDP
<valid data type>
Buffer for the minimum value

3.10.5 Fill Values and Fill Mode

A fill value is the value used to fill the spaces between non-contiguous writes to SDS arrays; it can be set with SDsetfillvalue. If a fill value is set before writing data to an SDS, the entire array is initialized to the specified fill value. By default, any location not subsequently overwritten with SDS data will contain the fill value.

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.

3.10.5.1 Writing a Fill Value Attribute: SDsetfillvalue

SDsetfillvalue assigns a new value to the fill value attribute for an SDS array. The syntax of this routine is as follows:

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 61.

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.

There are two FORTRAN-77 versions of this routine: sfgfill and sfgcfill. The sfgfill routine reads numeric fill value data and sfgcfill reads character fill value data.

SDgetfillvalue returns a value of 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.

Note that whenever a file has been newly opened, or has been closed and then re-opened, the default SD_FILL fill mode will be in effect until it is changed by a call to SDsetfillmode.

SDsetfillmode returns the fill mode value before it is reset or a value of FAIL (or -1). The parameters of this routine are further described in Table 3Y.

TABLE 3Y - SDsetfillvalue, SDgetfillvalue, and SDsetfillmode Parameter Lists

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
SDsetfillvalue

[intn]

(sfsfill/
sfscfill)
sds_id
int32
integer
Data set identifier

fill_val
VOIDP
<valid numeric data type>/
character*(*)
Fill value to be set

SDgetfillvalue

[intn]

(sfgfill/
sfgcfill)
sds_id
int32
integer
Data set identifier

fill_val
VOIDP
<valid numeric data type>/
character*(*)
Buffer for the fill value

SDsetfillmode

[intn]

(sfsflmd)
sd_id
int32
integer
SD interface identifier

fill_mode
intn
integer
Fill mode to be set

3.10.6 Calibration Attributes

The calibration attributes are designed to store calibration information associated with data set data. When data is calibrated, the values in an array can be represented using a smaller data type than the original. For instance, an array containing data of type 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.

3.10.6.1 Setting Calibration Information: SDsetcal

SDsetcal stores the scale factor, offset, scale factor error, offset error, and the data type of the uncalibrated data set for the specified data set. The syntax of this routine is as follows:

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 cal 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

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
SDsetcal

[intn]

(sfscal)
sds_id
int32
integer
Data set identifier

cal
float64
real*8
Calibration factor

cal_error
float64
real*8
Calibration error

offset
float64
real*8
Uncalibrated offset

offset_err
float64
real*8
Uncalibrated offset error

data_type
int32
integer
Data type of uncalibrated data

SDgetcal
[intn]
(sfgcal)
sds_id
int32
integer
Data set identifier

cal
float64 *
real*8
Calibration factor

cal_error
float64 *
real*8
Calibration error

offset
float64 *
real*8
Uncalibrated offset

offset_err
float64 *
real*8
Uncalibrated offset error

data_type
int32 *
integer
Data type of uncalibrated data

EXAMPLE 16. Calibrating Data.

Suppose the values in the calibrated array 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}


[Top] [Prev] [Next]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 05/19/99, NCSA HDF Development Group.