[Top] [Prev] [Next] [Bottom]

3.11 Predefined Attributes

Predefined attributes are attributes that use reserved labels and in some cases Predefined data types. 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 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
Object Type

Attribute

Reserved Label

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

The following naming conventions taken from the netCDF User's Guide are meant to promote consistency of information-sharing among generic applications. These naming conventions are not specifically required by the HDF library, but are highly recommended.

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.

The predefined attribute parameters are described in Table 3Y. 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 3Y Predefined Attribute Parameter List
Category

attr_name

(Attribute type)

num_type

(Data type)

count

(Number of Values)

value

(Attribute value)

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

2

Pointer to array.

Fill Value

_FillValue

<valid 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.11.2 SDS String Attributes

Predefined string attributes for an SDS array include the label, unit, format and coordinate system of an SDS.

3.11.2.1 Writing String Attributes: SDsetdatastrs

The following function assigns label, unit, format and coordinate system string attributes to an SDS array:

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.

Keep in mind that the value returned by label is the value of the attribute named "long_name" and that the value returned by coordsys is the value of the attribute named "cordsys". The reasons for this are explained in User's Guide Appendix F.

The parameters of SDgetdatastrs are described in Table 3Z.

TABLE 3Z SDsetdatastrs and SDgetdatastrs Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

SDsetdatastrs

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

coordsys

char *

character* (*)

Description of the coordinate system.

SDgetdatastrs

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

coordsys

char *

character* (*)

Buffer for the description of the coordinate system.

len

integer

intn

Maximum length of the attributes.

3.11.3 Dimension String Attributes

Dimension string attributes include a label, unit and format string which describe a dimension. They adhere to the same definitions as those of the label, unit and format strings for SDS attributes.

3.11.3.1 Writing a Dimension String Attribute: SDsetdimstrs

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.

The parameters of SDgetdimstrs are described in Table 3AA.

TABLE 3AA SDsetdimstrs and SDgetdimstrs Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

SDsetdimstrs

(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

(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.11.4 Range Attributes

The attribute range contains user-defined maximum and minimum values in a selected range. As 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.11.4.1 Writing a Range Attribute: SDsetrange

SDsetrange assigns the range attribute to an SDS:

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
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

SDsetrange

(sfsrange)

sds_id

int32

integer

Data set identifier.

max

VOIDP

<valid numeric data type>

Maximum value of the range.

min

VOIDP

<valid numeric data type>

Minimum value of the range.

SDgetrange

(sfgrange)

sds_id

int32

integer

Data set identifier.

max

VOIDP

<valid numeric data type>

Buffer for the maximum value.

min

VOIDP

<valid numeric data type>

Buffer for the minimum value.

3.11.5 Fill Values

A fill value is the value used to fill the spaces between non-contiguous writes to SDS arrays. 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 by SDS data will contain the fill value.

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.

3.11.5.1 Writing a Fill Value Attribute: SDsetfillvalue

SDsetfillvalue assigns a new value to the fill value attribute for an SDS array:

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.

There are two Fortran-77 versions of this routine: sfsfill and sfscfill. The sfsfill routine writes numeric fill value data and sfscfill writes character fill value data.

The parameters of SDsetfillvalue are described below. (See Table 3AC on page 93.) Note that, because there are two Fortran-77 versions of SDsetfillvalue, there are correspondingly two entries in the "Data Type" field of the fill_val parameter.

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.

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.

The parameters of SDgetfillvalue are described in the following table. Note that, because there are two Fortran-77 versions of SDgetfillvalue, there are correspondingly two entries in the "Data Type" field of the fill_val parameter.

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.

However, it can be tedious to unset the fill value for all SDSs in a file, particularly when the file contains a large number of them. This can be done with one call to SDsetfillmode, which must occur before calls to SDsetfillvalue.

The syntax of SDsetfillmode is as follows:

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.

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.

The parameters of SDsetfillmode are described in the table below.

TABLE 3AC SDsetfillvalue, SDgetfillvalue and SDsetfillmode Parameter List,
Function Call

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

SDsetfillvalue

(sfsfill/

sfscfill)

sds_id

int32

integer

Data set identifier.

fill_val

VOIDP

<valid numeric data type>

Pointer to the fill value to be set.

SDgetfillvalue

(sfgfill/

sfgcfill)

sds_id

int32

integer

Data set identifier

fill_val

VOIDP

<valid numeric data type>

Buffer for the fill value.

SDsetfillmode

(sfsflmd)

file_id

int32

integer

File identifier.

fill_mode

intn

integer

Fill mode to be set.

3.11.6 Calibration Attributes

The calibration attribute stores scale and offset values to describe calibrated data in SDS arrays. When data are calibrated using a scale and an offset, 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. Both the scale_factor and add_offset attributes should be of the type float64.

3.11.6.1 Writing Calibrated Data: SDsetcal

SDsetcal adds the scale factor, offset, scale factor error, offset error and the data type of the uncalibrated data to the specified data set:

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.

SDsetcal has six arguments; sds_id, cal, cal_error, offset, off_err and num_type. The argument cal represents a single value that when multiplied against every value in the calibrated array reproduces the original data (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 scale of 1). The cal and offset values relate to the original data according to the following equation:

original_data = cal * (calibrated_data - offset)

In addition to cal and offset, SDsetcal also includes both a scale and offset error. The argument cal_err contains the potential error of the calibrated data due to scaling; off_err contains the potential error for the calibrated data due to the offset.

The parameters of SDsetcal are described below. (See Table 3AD on page 94.)

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
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

SDsetcal

(sfscal)

sds_id

int32

integer

Data set identifier.

cal

float64

real*8

Calibration factor.

cal_error

float64

real*8

Calibration error.

off

float64

real*8

Uncalibrated offset.

off_err

float64

real*8

Uncalibrated offset error.

num_type

int32

integer

Data type of uncalibrated data.

SDgetcal

(sfgcal)

sds_id

int32

integer

Data set identifier.

cal

float64 *

real*8

Pointer to the calibration factor.

cal_error

float64 *

real*8

Pointer to the calibration error.

off

float64 *

real*8

Pointer to the uncalibrated offset.

off_err

float64 *

real*8

Pointer to the uncalibrated offset error.

num_type

int32 *

integer

Pointer to the data type of uncalibrated data.

EXAMPLE 21. 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] [Bottom]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF Development Group.