[Top] [Prev]

12.7 Predefined Attributes and the DFSD Interface

Although they often contain important information, attributes are optional to the data set array and the dimension record. Although both types of attributes use similar names, they are read and written using different sets of routines. All attributes are predefined by the DFSD library.

12.7.1 Writing Data Set Attributes

Data set attributes are described in Chapter 3, Scientific Data Sets (SD API). There is a limit of one string attribute per data set.

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.

Predefined string attributes are defined as follows:

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.

DFSDsetdatastrs writes null-terminated strings to an HDF file. It has the same four arguments: 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

Routine Name

[Return Type]

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

[intn]

(dsslens)
label_len
intn
integer
Maximum length for any label string.

unit_len
intn
integer
Maximum length for any unit string.

format_len
intn
integer
Maximum length for any format string.

coords_len
intn
integer
Maximum length for any coordinate system string.

DFSDsetdatastrs

[intn]

(dssdast)
label
char *
character*(*)
Label describing the data.

unit
char *
character*(*)
Unit to be applied to the data.

format
char *
character*(*)
Format to be applied in displaying the data.

coordsys
char*
character*(*)
Coordinate system of the data set.

12.7.1.2 Assigning Value Attributes to a DFSD SDS: DFSDsetfillvalue, DFSDsetrange, and DFSDsetcal

The DFSD interface provides the following routines for defining value attributes. All three function calls are optional and may be called in any order provided they precede a call to DFSDadddata or DFSDputdata.

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 parameters for DFSDsetfillvalue are further defined in Table K below.

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.

In addition to the 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.

The parameters of DFSDsetcal are defined in the following table.

TABLE 12M - DFSDsetfillvalue, DFSDsetrange and DFSDsetcal Parameter List

Routine Name

[Return Type]

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

[intn]

(dssfill)
label
char *
character*(*)
Label describing the data.

unit
char *
character*(*)
Unit to be applied to the data.

format
char *
character*(*)
Format to be applied in displaying the data.

coordsys
char *
character*(*)
Coordinate system of the data set.

DFSDsetrange
[intn]
(dssrang)
max
VOIDP
<valid numeric data type>
Highest value in the selected range of data.

min
VOIDP
<valid numeric data type>
Lowest value in the selected range of data.

DFSDsetcal
[intn]
(dsscal)
cal
float64
real*8
Calibration scale.

cal_error
float64
real*8
Calibration scale error.

off
float64
real*8
Uncalibrated offset.

off_err
float64
real*8
Uncalibrated offset error.

num_type
int32
integer
Number type of uncalibrated data.

EXAMPLE 3. Assigning Predefined String Attributes to a File

The following examples demonstrate the steps necessary to assign predefined string attributes to the data set and stores the data set in the file "Example1.hdf". They create a string attribute using DFSDsetdatastrs and a value attribute using DFSDsetrange. It also demonstrates the use of DFSDsetlengths in altering the maximum string length from 255 characters to 50. It then writes the SDS array by calling DFSDadddata.

C version



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

Attribute data is not read by DFSDgetdatastrs until the appropriate routine is called to read the array and its dimension record. If DFSDgetdatastrs and DFSDgetrange are not called, the array and its dimension record can be read without reading its associated data set attributes. It is also possible to read string and value attributes individually. As attribute data is not actually read by DFSDgetdatastrs or DFSDgetrange, these calls must be made before calling DFSDgetdata.

Reading the attributes of a data set involves the following steps:

  1. Determine the length of each attribute string.
  2. Read the attribute strings.
  3. Read the maximum and minimum values.
  4. Read the remainder of the data set.

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

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C

FORTRAN-77

DFSDgetdatalen

[intn]

(dsgdaln)
label_len
intn *
integer
Length of any label string.

unit_len
intn *
integer
Length of any unit string.

format_len
intn *
integer
Length of any format string.

coords_len
intn *
integer
Length of any coordinate system string.

DFSDgetdatastrs

[intn]

(dsgdast)
label
char *
character*(*)
Label describing the data.

unit
char *
character*(*)
Unit applied to the data.

format
char *
character*(*)
Format applied to the data.

coordsys
char *
character*(*)
Coordinate system of the data set.

EXAMPLE 4. Reading a Data Set and its Attribute Record

These examples read the pressure data set and the dimension attribute record stored in the "Example1.hdf" file into the arrays pointed to by the 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



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

The syntax of these routines are as follows:

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.

The maximum range of values in the data set isn't automatically stored with the data set data; it is explicitly stored through a call to DFSDgetrange. The defined range of values can be less than the actual range of values stored in the data set. The value of the 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.

DFSDgetcal reads the calibration record of the current data set, if one exists. Each of the parameters of DFSDgetcal correspond to the five elements of the calibration record; - four 64-bit floating-point integers followed by a 32-bit integer. The 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.

The parameters for DFSDgetfillvalue, DFSDgetcal, and DFSDgetrange are defined in the following table.

TABLE 12O - DFSDgetfillvalue, DFSDgetcal and DFSDgetrange Parameter List

Routine Name

[Return Type]

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

[intn]

(dsgfill)
sds_id
int32
integer
Data set identifier.

fill_val
VOIDP
<valid numeric data type>
Buffer for the fill value.

DFSDgetcal

[int32]

(dsgcal)
cal
float64 *
real*8
Calibration factor.

cal_err
float64 *
real*8
Calibration error.

offset
float64 *
real*8
Uncalibrated offset.

offset_err
float64 *
real*8
Uncalibrated offset error.

num_type
int32 *
integer
Type of the uncalibrated data.

DFSDgetrange

[intn]

(dsgrang)
max
VOIDP
<valid numeric data type>
Highest value of the selected range.

min
VOIDP
<valid numeric data type>
Lowest value of the selected range.

12.7.3 Writing the Dimension Attributes of a DFSD SDS

Dimension attributes are described in Chapter 3, Scientific Data Sets (SD API).

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.

Predefined dimension string attributes are limited to one per dimension and contain the following:

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.

DFSDsetdimstrs also has four arguments; 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.

The parameters for DFSDsetlengths and DFSDsetdimstrs are further defined in the following table.

TABLE 12P - DFSDsetlengths and DFSDsetdimstrs Parameter List

Routine Name

[Return Type]

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

[intn]

(dsslen)
label_len
intn
integer
Maximum length of any label string.

unit_len
intn
integer
Maximum length of any unit string.

format_len
intn
integer
Maximum length of any format string.

coords_len
intn
integer
Maximum length of any coordinate system string.

DFSDsetdimstrs

[intn]

(dssdist)
dim
intn
integer
Dimension of the attribute strings.specified by the remaining three parameters

label
char *
character*(*)
Label describing the data.

unit
char *
character*(*)
Unit to be applied to the data.

format
char *
character*(*)
Format to be applied in displaying the data.

12.7.3.2 Writing a Dimension Scale of a DFSD SDS: DFSDsetdimscale

The syntax of the two routines needed to write a dimension scale is the following:

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.

TABLE 12Q - DFSDsetdimscale Parameter List

Routine Name

[Return Type]

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

[intn]

(dssdisc)
dim
intn
integer
Dimension of the current scale.

dim_size
int32
integer
Size of the current scale.

scale
VOIDP
<valid numeric data type>
Values of the current scale.

12.7.4 Reading the Dimension Attributes of a DFSD SDS

The DFSD interface provides three routines for reading dimension attributes: DFSDgetdimlen, DFSDgetdimstrs and DFSDgetdimscale. DFSDgetdimlen returns the string length for each string in the attribute record. It is a useful routine to call before reading an attribute. DFSDgetdimstrs and DFSDgetdimscale are used as instructions for reading the dimension attributes. DFSDgetdimstrs reads the dimension strings and DFSDgetdimscale reads the dimension scale. By avoiding calls to DFSDgetdimstrs and DFSDgetdimscale, it is possible to read an array and its dimension record without reading the data set attributes associated with it. It is also possible to omit one function call in order to read one attribute without the other. DFSDgetdimstrs and DFSDgetdimscale must be called before DFSDgetdata.

Reading data set attributes involves the following steps:

  1. Determine the length of each attribute string.
  2. Read the attribute strings.
  3. Read the scale values.
  4. Read the remainder of the data set.

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

Routine Name

[Return Type]

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

[intn]

(dsgdiln)
dim
intn
integer
Dimension of the string attributes describe.

label_len
intn *
integer
Length of the label attribute string.

unit_len
intn *
integer
Length of the unit attribute string.

format_len
intn *
integer
Length of the format attribute string.

DFSDgetdimstrs

[intn]

(dsgdist)
dim
intn
integer
Dimension the string attributes describe.

label
char *
character*(*)
Label of the dimension.

unit
char *
character*(*)
Unit to be applied to this dimension.

format
char *
character*(*)
Format to be applied when displaying the scale.

DFSDgetdimscale

[intn]

(dsgdisc)
dim
intn
integer
Dimension the current scale is attached to

dim_size
int32
integer
Size of the current scale.

scale
VOIDP
<valid numeric data type>
Values of the current scale.



[Top] [Prev]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 07/21/98, NCSA HDF Development Group.