FIGURE 3c - Dimension Records and Attributes Shared Between Related Data Sets
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). FAIL (or -1). The parameters of SDgetdimid are specified in Table 3O on page 44.
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.
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
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. 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.dim_id is unlimited.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.
TABLE 3P - SDsetdimval_comp and SDisdimval_bwcomp Parameter Lists
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.SUCCEED (or 0) or FAIL (or -1). The parameters of this routine are specified in Table 3Q on page 47.
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. 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.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.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.data_type will contain the data type of the scale values; otherwise, data_type will contain 0.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 46 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.
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
C 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.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
|
|
|
|
| |
|
|
| |||
|
|
|
Data set identifier
| |
C 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.
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