[Top] [Prev] [Next]

3.8 SDS Dimension and Dimension Scale Operations

The concept of dimensions is introduced in Section 3.2.1 on page 19. This section describes SD interface routines which store and retrieve information on dimensions and dimension scales. When a dimension scale is set for a dimension, the library stores the dimension and its associated information as an SDS array. In the following discussion, we will refer to that array (recall NetCDF) as a coordinate variable or dimension record. The section concludes with consideration of related data sets and sharable dimensions.

3.8.1 Selecting a Dimension: SDgetdimid

SDS dimensions are uniquely identified by dimension identifiers, which are assigned when a dimension is created. These dimension identifiers are used within a program to refer to a particular dimension, its scale, and its attributes. Before working with a dimension, a program must first obtain a dimension identifier by calling the SDgetdimid routine as follows:

C:		dim_id = SDgetdimid(sds_id, dim_index);
FORTRAN:	dim_id = sfdimid(sds_id, dim_index)
SDgetdimid takes two arguments, sds_id and dim_index, and returns a dimension identifier, dim_id. The argument dim_index is an integer from 0 to the number of dimensions minus 1. The number of dimensions in a data set is specified at the time the data set is created. Specifying a dimension index equal to or larger than the number of dimensions in the data set causes SDgetdimid to return a value of FAIL (or -1).

Unlike file and data set identifiers, dimension identifiers do not require explicit disposal. SDgetdimid returns a dimension identifier or FAIL (or -1). The parameters of SDgetdimid are specified in Table 3O on page 45.

3.8.2 Naming a Dimension: SDsetdimname

SDsetdimname assigns a name to a dimension. If two dimensions have the same name, they will be represented in the file by only one SDS. Therefore changes to one dimension will be reflected in the other. Naming dimensions is optional but encouraged. Dimensions that are not explicitly named by the user will have names generated by the HDF library. Use SDdiminfo to read existing dimension names. The syntax of SDsetdimname is as follows:

C:		status = SDsetdimname(dim_id, dim_name);
FORTRAN:	status = sfsdmname(dim_id, dim_name)
The argument dim_id in SDsetdimname is the dimension identifier returned by SDgetdimid. The parameter dim_name is a string of alphanumeric characters representing the name for the selected dimension. An attempt to rename a dimension using SDsetdimname will cause the old name to be deleted and a new one to be assigned.

Note that when naming dimensions the name of a particular dimension must be set before attributes are assigned; once the attributes have been set, the name must not be changed. In other words, SDsetdimname must only be called before any calls to SDsetdimscale (described in Section 3.8.4.1 on page 46), SDsetattr (described in Section 3.9.1 on page 51) or SDsetdimstrs (described in Section 3.10.2.1 on page 56).

SDsetdimname returns a value of SUCCEED (or 0) or FAIL (or -1). The parameters of SDsetdimname are described in Table 3O.

TABLE 3O - SDgetdimid and SDsetdimname Parameter Lists

Routine Name

[Return Type]

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

[int32]

(sfdimid)
sds_id
int32
integer
Data set identifier

dim_index
intn
integer
Dimension index

SDsetdimname

[intn]

(sfsdmname)
dim_id
int32
integer
Dimension identifier

dim_name
char *
character*(*)
Dimension name

3.8.3 Old and New Dimension Implementations

Up to and including HDF version 4.0 beta1, dimensions were vgroup objects (described in Chapter 5, Vgroups (V API), containing a single field vdata (described in Chapter 4, Vdatas (VS API), with a class name of DimVal0.0. The vdata had the same number of records as the size of the dimension, which consisted of the values 0, 1, 2, . . . n - 1, where n is the size of the dimension. These values were not strictly necessary. Consider the case of applications that create large one dimensional data sets: the disk space taken by these unnecessary values nearly doubles the size of the HDF file. To avoid these situations, a new representation of dimensions was implemented for HDF version 4.0 beta 2 and later versions.

Dimensions are still vgroups in the new representation, but the vdata has only one record with a value of <dimension size> and the class name of the vdata has been changed to DimVal0.1 to distinguish it from the old version.

Between HDF versions 4.0 beta1 and 4.1, the old and new dimension representations were written by default for each dimension created, and both representations were recognized by routines that operate on dimensions. From HDF version 4.1 forward, SD interface routines recognize only the new representation. Two compatibility mode routines, SDsetdimval_comp and SDisdimval_bwcomp, are provided to allow HDF programs to distinguish between the two dimension representations, or compatibility modes.

3.8.3.1 Setting the Future Compatibility Mode of a Dimension: SDsetdimval_comp

SDsetdimval_comp sets the compatibility mode for the dimension identified by the parameter dim_id. This operation determines whether the dimension will have the old and new representations or the new representation only. The syntax of SDsetdimval_comp is as follows:

C:		status = SDsetdimval_comp(dim_id, comp_mode);
FORTRAN:	status = sfsdmvc(dim_id, comp_mode)
The parameter comp_mode specifies the compatibility mode. It can be set to either SD_DIMVAL_BW_COMP (or 1), which specifies compatible mode and that the old and new dimension representations will be written to the file, or SD_DIMVAL_BW_INCOMP (or 0), which specifies incompatible mode and that only the new dimension representation will be written to file. As of HDF version 4.1r1, the default mode is backward-incompatible. Subsequent calls to SDsetdimval_comp will override the settings established in previous calls to the routine.

Unlimited dimensions are always backward compatible. Therefore SDsetdimval_comp takes no action when the dimension identified by dim_id is unlimited.

SDsetdimval_comp returns a value of SUCCEED (or 0) or FAIL (or -1). The parameters of SDsetdimval_comp are specified in Table 3P on page 46.

3.8.3.2 Determining the Current Compatibility Mode of a Dimension: SDisdimval_bwcomp

SDisdimval_bwcomp determines whether the specified dimension has the old and new representations or the new representation only. The syntax of SDisdimval_bwcomp is as follows:

C:		comp_mode = SDisdimval_bwcomp(dim_id);
FORTRAN:	comp_mode = sfisdmvc(dim_id)
SDisdimval_bwcomp returns one of the three values: SD_DIMVAL_BW_COMP (or 1), SD_DIMVAL_BW_INCOMP (or 0), and FAIL (or -1). The interpretation of SD_DIMVAL_BW_COMP and SD_DIMVAL_BW_INCOMP are as that in the routine SDsetdimval_comp.

The parameters of SDisdimval_bwcomp are specified in Table 3P.

TABLE 3P - SDsetdimval_comp and SDisdimval_bwcomp Parameter Lists

Routine Name

[Return Type]

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

[intn]

(sfsdmvc)
dim_id
int32
integer
Dimension identifier

comp_mode
intn
integer
Compatibility mode

SDisdimval_bwcomp

[intn]

(sfisdmvc)
dim_id
int32
integer
Dimension identifier

3.8.4 Dimension Scales

A dimension scale can be thought of as a series of numbers demarcating intervals along a dimension. One scale is assigned per dimension. Users of netCDF can think of them as analogous to coordinate variables. In the SDS data model, each dimension scale is a one-dimensional array with name and size equal to its assigned dimension name and size.

For example, if a dimension of length 6 named "depth" is assigned a dimension scale, its scale is a one-dimensional array of length 6 and is also assigned the name "depth". The name of the dimension will also appear as the name of the dimension scale.

Recall that when dimension scale is assigned to a dimension, the dimension is implemented as an SDS array with data being the data scale. Although dimension scales are conceptually different from SDS arrays, they are implemented as SDS arrays by the SDS interface and are treated similarly by the routines in the interface. For example, when the SDfileinfo routine returns the number of data sets in a file, it includes dimension scales in that number. The SDiscoordvar routine (described in Section 3.8.4.4 on page 48) distinguishes SDS data sets from dimension scales.

3.8.4.1 Writing Dimension Scales: SDsetdimscale

SDsetdimscale stores scale information for the dimension identified by the parameter dim_id. The syntax of this routine is as follows:

C:		status = SDsetdimscale(dim_id, n_values, data_type, data);
FORTRAN:	status = sfsdscale(dim_id, n_values, data_type, data)
The argument n_values specifies the number of scale values along the specified dimension. For a fixed size dimension, n_values must be equal to the size of the dimension. The parameter data_type specifies the data type for the scale values and data is an array containing the scale values.

SDsetdimscale returns a value of SUCCEED (or 0) or FAIL (or -1). The parameters of this routine are specified in Table 3Q on page 48.

3.8.4.2 Obtaining Dimension Scale and Other Dimension Information: SDdiminfo

Before working with an existing dimension scale, it is often necessary to determine its characteristics. For instance, to allocate the proper amount of memory for a scale requires knowledge of its size and data type. SDdiminfo provides this basic information, as well as the name and the number of attributes for a specified dimension.

The syntax of this routine is as follows:

C:		status = SDdiminfo(dim_id, dim_name, &dim_size, &data_type, &n_attrs);
FORTRAN:	status = sfgdinfo(dim_id, dim_name, dim_size, data_type, n_attrs)
SDdiminfo retrieves and stores the dimension's name, size, data type, and number of attributes into the parameters dim_name, dim_size, data_type, and n_attrs, respectively.

The parameter dim_name will contain the dimension name set by SDsetdimname or the default dimension name, fakeDim[x], if SDsetdimname has not been called, where [x] denotes the dimension index. If the name is not desired, the parameter dim_name can be set to NULL in C or an empty string in FORTRAN-77.

An output value of 0 for the parameter dim_size indicates that the dimension specified by the parameter dim_id is unlimited. Use SDgetinfo to get the number of elements of the unlimited dimension.

If scale information is available for the specified dimension, i.e., SDsetdimscale has been called, the parameter data_type will contain the data type of the scale values; otherwise, data_type will contain 0.

SDdiminfo returns a value of SUCCEED (or 0) or FAIL (or -1). The parameters of this routine are specified in Table 3Q.

3.8.4.3 Reading Dimension Scales: SDgetdimscale

SDgetdimscale retrieves the scale values of a dimension. These values have previously been stored by SDsetdimscale. The syntax of this routine is as follows:

C:		status = SDgetdimscale(dim_id, data);
FORTRAN:	status = sfgdscale(dim_id, data)
SDgetdimscale reads all the scale values and stores them in the buffer data which is assumed to be sufficiently allocated to hold all the values. SDdiminfo should be used to determine whether the scale has been set for the dimension and to obtain the data type and the number of scale values for space allocation before calling SDgetdimscale. Refer to Section 3.8.4.2 on page 47 for a discussion of SDdiminfo.

Note that it is not possible to read a subset of the scale values. SDgetdimscale returns all of the scale values stored with the given dimension.

SDgetdimscale returns a value of SUCCEED (or 0) or FAIL (or -1). The parameters of this routine are specified in Table 3Q.

TABLE 3Q - SDsetdimscale, SDdiminfo, and SDgetdimscale Parameter Lists

Routine Name

[Return Type]

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

[intn]

(sfsdscale)
dim_id
int32
integer
Dimension identifier

n_values
int32
integer
Number of scale values

data_type
int32
integer
Data type to be set for the scale values

data
VOIDP
<valid data type>(*)
Buffer containing the scale values to be set

SDdiminfo

[intn]

(sfgdinfo)
dim_id
int32
integer
Dimension identifier

dim_name
char *
character*(*)
Buffer for the dimension name

n_values
int32 *
integer
Buffer for the dimension size

data_type
int32 *
integer
Buffer for the scale data type

n_attrs
int32 *
integer
Buffer for the attribute count

SDgetdimscale

[intn]

(sfgdscale)
dim_id
int32
integer
Dimension identifier

data
VOIDP
<valid data type>(*)
Buffer for the scale values

EXAMPLE 12. Setting and Retrieving Dimension Information.

This example illustrates the use of the routines SDgetdimid/sfdimid, SDsetdimname/sfsdmname, SDsetdimscale/sfsdscale, SDdiminfo/sfgdinfo, and SDgetdimscale/sfgdscale to set and retrieve the dimensions names and dimension scales of the SDS created in Example 2 and modified in Examples 4 and 7.

C version

FORTRAN-77 version

3.8.4.4 Distinguishing SDS Arrays from Dimension Scales: SDiscoordvar

The HDF library stores SDS dimensions as data sets. HDF therefore provides the routine SDiscoordvar to determine whether a particular data set contains the data of an SDS or an SDS dimension with dimension scale or attribute assigned to it. The syntax of SDiscoordvar this routine is as follows:

C:		status = SDiscoordvar(sds_id);
FORTRAN:	status = sfiscvar(sds_id)
If the data set, identified by the parameter sds_id, contains the dimension data, a subsequent call to SDgetinfo will fill the specified arguments with information about a dimension, rather than a data set.

SDiscoordvar returns TRUE (or 1) if the specified data set represents a dimension scale and FALSE (or 0), otherwise. This routine is further defined in Table 3R.

TABLE 3R - SDiscoordvar Parameter List

Routine Name

[Return Type]

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

[intn]

(sfiscvar)
sds_id
int32
integer
Data set identifier

EXAMPLE 13. Distinguishing a Dimension Scale from a Data Set in a File.

This example illustrates the use of the routine SDiscoordvar/sfiscvar to determine whether the selected SDS array is a data set or a dimension stored as an SDS array (coordinate variable) (see discussion in Section 3.8.4) and displays the name of the data set or dimension.

C version

FORTRAN-77 version

3.8.5 Related Data Sets

SD data sets with one or more dimensions with the same name and size are considered to be related. Examples of related data sets are cross-sections from the same simulation, frames in an animation, or images collected from the same apparatus. HDF attempts to preserve this relationship by unifying their dimension scales and attributes. To understand how related data sets are handled, it is necessary to understand what dimension records are and how they are created.

In the SD interface, dimension records are only created for dimensions of a unique name and size. To illustrate this, consider a case where there are three scientific data sets, each representing a unique variable, in an HDF file. (See Figure 3c.) The first two data sets have two dimensions each and the third data set has three dimensions. There are a total of five dimensions in the file and the name mapping between the data sets and the dimensions are shown in the figure. Note that if, for example, the creation of a second dimension named "Altitude" is attempted and the size of the dimension is different from the existing dimension named "Altitude", an error condition will be generated.

As expected, assigning a dimension attribute to dimension 1 of either data set will create the required dimension scale and assign the appropriate attribute. However, because related data sets share dimension records, they also share dimension attributes. Therefore, it is impossible to assign an attribute to a dimension without assigning the same attribute to all dimensions of identical name and size, either within one data set or related data sets.

FIGURE 3c - Dimension Records and Attributes Shared Between Related Data Sets



[Top] [Prev] [Next]

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