[Top] [Prev] [Next]

3.7 Obtaining Information about SD Data Sets

The routines covered in this section provide methods for obtaining information about all scientific data sets in a file, for identifying the data sets that meet certain criteria, and for obtaining information about specific data sets.

SDfileinfo obtains the numbers of data sets and file attributes, set by SD interface routines, in a file. SDgetinfo provides information about an individual SDS. To retrieve information about all data sets in a file, a calling program can use SDfileinfo to determine the number of data sets, followed by repeated calls to SDgetinfo to obtain the information about a particular data set.

SDnametoindex or SDreftoindex can be used to obtain the index of an SDS in a file knowing its name or reference number, respectively. Refer to Section 3.2.1 on page 19 for a description of the data set index and reference number. SDidtoref is used when the reference number of an SDS is required by another routine and the SDS identifier is available.

These routines are described individually in the following subsections.

3.7.1 Obtaining Information about the Contents of a File: SDfileinfo

SDfileinfo determines the number of scientific data sets and the number of file attributes contained in a file. This information is often useful in index validation or sequential searches. The syntax of SDfileinfo is as follows:

C:		status = SDfileinfo(sd_id, &n_datasets, &n_file_attrs);
FORTRAN:	status = sffinfo(sd_id, n_datasets, n_file_attrs)
SDfileinfo stores the numbers of scientific data sets and file attributes in the parameters n_datasets and n_file_attrs, respectively. Note that the value returned by n_datasets will include the number of SDS arrays and the number of dimension scales. Refer to Section 3.8.4 on page 46 and Section 3.8.4.4 on page 48 for the description of dimension scales and its association with SDS arrays as well as how to distinguish between SDS arrays and dimension scales. The file attributes are those that are created by SDsetattr for an SD interface identifier instead of an SDS identifier. Refer to Section 3.9.1 on page 51 for the discussion of SDsetattr.

SDfileinfo returns a value of SUCCEED (or 0) or FAIL (or -1). The parameters of SDfileinfo are specified in Table 3L on page 41.

3.7.2 Obtaining Information about a Specific SDS: SDgetinfo

SDgetinfo provides basic information about an SDS array. Often information about an SDS array is needed before reading and working with the array. For instance, the rank, dimension sizes, and/or data type of an array are needed to allocate the proper amount of memory to work with the array. SDgetinfo takes an SDS identifier as input, and retrieves the name, rank, dimension sizes, data type, and number of attributes for the corresponding SDS. The syntax of this routine is as follows:

C:			status = SDgetinfo(sds_id, sds_name, &rank, dim_sizes, &data_type, &n_attrs);
FORTRAN:	status = sfginfo(sds_id, sds_name, rank, dim_sizes, data_type, n_attrs)
SDgetinfo stores the name, rank, dimension sizes, data type, and number of attributes of the specified data set into the parameters sds_name, rank, dim_sizes, data_type, and n_attrs, respectively. The parameter sds_name is a character string. Note that the name of the SDS is limited to 64 characters.

If the data set is created with an unlimited dimension, then in the C interface, the first element of the dim_sizes array (corresponding to the slowest-changing dimension) contains the number of records in the unlimited dimension; in the FORTRAN-77 interface, the last element of the array dim_sizes (corresponding to the slowest-changing dimension) contains this information.

The parameter data_type contains any type that HDF supports for the scientific data. Refer to Table 2F on page 14, for the list of supported data types and their corresponding defined values. The parameter n_attrs only reflects the number of attributes assigned to the data set specified by sds_id; file attributes are not included. Use SDfileinfo to get the number of file attributes.

SDgetinfo returns a value of SUCCEED (or 0) or FAIL (or -1). The parameters of SDgetinfo are specified in Table 3L.

3.7.3 Determining whether an SDS is empty: SDcheckempty

SDcheckempty takes an SDS identifier, sds_id, as input, and returns a single parameter indicating whether the SDS is empty. The syntax of this routine is as follows:

C:			status = SDgcheckempty(sds_id, emptySDS);
FORTRAN:	status = sfchempty(sds_id, emptySDS)
The output parameter, emptySDS, indicates whether the SDS is empty or non-empty.

SDcheckempty returns a value of SUCCEED (or 0) or FAIL (or -1). The parameters of SDcheckempty are specified in Table 3L.

TABLE 3L - SDfileinfo and SDgetinfo Parameter Lists

Routine Name

[Return Type]

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

[intn]

(sffinfo)
sd_id
int32
integer
SD interface identifier

n_datasets
int32 *
integer
Number of data sets in the file

n_file_attrs
int32 *
integer
Number of global attributes in the file

SDgetinfo

[intn]

(sfginfo)
sds_id
int32
integer
Data set identifier

sds_name
char*
character*(*)
Name of the data set

rank
int32 *
integer
Number of dimensions in the data set

dim_sizes
int32 []
integer (*)
Size of each dimension in the data set

data_type
int32 *
integer
Data type of the data in the data set

n_attrs
int32 *
integer
Number of attributes in the data set

SDcheckempty

[int32]

(sfchempty)
sds_id
int32
integer
SDS identifier

emptySDS
intn *
integer
SDS status indicator (empty, not empty)

EXAMPLE 10. Getting Information about a File and an SDSs.

This example illustrates the use of the routine SDfileinfo/sffinfo to obtain the number of data sets in the file SDS.hdf and the routine SDgetinfo/sfginfo to retrieve the name, rank, dimension sizes, data type and number of attributes of the selected data set.

C version

FORTRAN-77 version

3.7.4 Locating an SDS by Name: SDnametoindex

SDnametoindex determines and returns the index of a data set in a file given the data set's name. The syntax of this routine is as follows:

C:		sds_index = SDnametoindex(sd_id, sds_name);
FORTRAN:	sds_index = sfn2index(sd_id, sds_name)
The parameter sds_name is a character string with the maximum length of 64 characters. If more than one data set has the name specified by sds_name, SDnametoindex will return the index of the first data set. The index can then be used by SDselect to obtain an SDS identifier for the specified data set.

The SDnametoindex routine is case-sensitive to the name specified by sds_name and does not accept wildcards as part of that name. The name must exactly match the name of the SDS being searched for.

SDnametoindex returns the index of a data set or FAIL (or -1). The parameters of SDnametoindex are specified in Table 3M.

3.7.5 Locating an SDS by Reference Number: SDreftoindex

SDreftoindex determines and returns the index of a data set in a file given the data set's reference number. The syntax of this routine is as follows:

C:		sds_index = SDreftoindex(sd_id, ref);
FORTRAN:	sds_index = sfref2index(sd_id, ref)
The reference number can be obtained using SDidtoref if the SDS identifier is available. Remember that reference numbers do not necessarily adhere to any ordering scheme.

SDreftoindex returns either the index of an SDS or FAIL (or -1). The parameters of this routine are specified in Table 3M.

3.7.6 Obtaining the Reference Number Assigned to the Specified SDS: SDidtoref

SDidtoref returns the reference number of the data set identified by the parameter sds_id if the data set is found, or FAIL (or -1) otherwise. The syntax of this routine is as follows:

C:		sds_ref = SDidtoref(sds_id);
FORTRAN:	sds_ref = sfid2ref(sds_id)
This reference number is often used by Vaddtagref to add the data set to a vgroup. Refer to Chapter 5, Vgroups (V API), for more information.

The parameter of SDidtoref is specified in Table 3M.

TABLE 3M - SDnametoindex, SDreftoindex, and SDidtoref Parameter Lists

Routine Name

[Return Type]

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

[int32]

(sfn2index)
sd_id
int32
integer
SD interface identifier

sds_name
char *
character*(*)
Name of the data set

SDreftoindex

[int32]

(sfref2index)
sd_id
int32
integer
SD interface identifier

ref
int32
integer
Reference number of the specified data set

SDidtoref

[int32]

(sfid2ref)
sds_id
int32
integer
Data set identifier

EXAMPLE 11. Locating an SDS by Its Name.

This example uses the routine SDnametoindex/sfn2index to locate the SDS with the specified name and then reads the data from it.

C version

FORTRAN-77 version

3.7.7 Creating SDS Arrays Containing Non-standard Length Data: SDsetnbitdataset

Starting with version 4.0r1, HDF provides the routine SDsetnbitdataset, allowing the HDF user to specify that a particular SDS array contains data of a non-standard length.

SDsetnbitdataset specifies that the data set identified by the parameter sds_id will contain data of a non-standard length defined by the parameters start_bit and bit_len. Additional information about the non-standard bit length decoding are specified in the parameters sign_ext and fill_one. The syntax of SDsetnbitdataset is as follows:

C:		status = SDsetnbitdataset(sds_id, start_bit, bit_len, sign_ext, fill_one);
FORTRAN:	status = sfsnbit(sds_id, start_bit, bit_len, sign_ext, fill_one)
Any length between 1 and 32 bits can be specified. After SDsetnbitdataset has been called for an SDS array, any read or write operations will convert between the new data length of the SDS array and the data length of the read or write buffer.

Bit lengths of all data types are counted from the right of the bit field starting with 0. In a bit field containing the values 01111011, bits 2 and 7 are set to 0 and all the other bits are set to 1.

The parameter start_bit specifies the left-most position of the variable-length bit field to be written. For example, in the bit field described in the preceding paragraph a parameter start_bit set to 4 would correspond to the fourth bit value of 1 from the right.

The parameter bit_len specifies the number of bits of the variable-length bit field to be written. This number includes the starting bit and the count proceeds toward the right end of the bit field - toward the lower-bit numbers. For example, starting at bit 5 and writing 4 bits of the bit field described in the preceding paragraph would result in the bit field 1110 being written to the data set. This would correspond to a start_bit value of 5 and a bit_len value of 4.

The parameter sign_ext specifies whether to use the left-most bit of the variable-length bit field to sign-extend to the left-most bit of the data set data. For example, if 9-bit signed integer data is extracted from bits 17-25 and the bit in position 25 is 1, then when the data is read back from disk, bits 26-31 will be set to 1. Otherwise bit 25 will be 0 and bits 26-31 will be set to 0. The sign_ext parameter can be set to TRUE (or 1) or FALSE (or 0); specify TRUE to sign-extend.

The parameter fill_one specifies whether to fill the "background" bits with the value 1 or 0. This parameter is also set to either TRUE (or 1) or FALSE (or 0).

The "background" bits of a non-standard length data set are the bits that fall outside of the non-standard length bit field stored on disk. For example, if five bits of an unsigned 16-bit integer data set located in bits 5 to 9 are written to disk with the parameter fill_one set to TRUE (or 1), then when the data is reread into memory bits 0 to 4 and 10 to 15 would be set to 1. If the same 5-bit data was written with a fill_one value of FALSE (or 0), then bits 0 to 4 and 10 to 15 would be set to 0.

The operation on fill_one is performed before the operation on sign_ext. For example, using the sign_ext example above, bits 0 to 16 and 26 to 31 will first be set to the background bit value, and then bits 26 to 31 will be set to 1 or 0 based on the value of the 25th bit.

SDsetnbitdataset returns a value of SUCCEED (or 0) or FAIL (or -1). The parameters for SDsetnbitdataset are specified in Table 3N.

TABLE 3N - SDsetnbitdataset Parameter List

Routine Name

[Return Type]

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

[intn]

(sfsnbit)
sds_id
int32
integer
Data set identifier

start_bit
intn
integer
Leftmost bit of the field to be written

bit_len
intn
integer
Length of the bit field to be written

sign_ext
intn
integer
Sign-extend specifier

fill_one
intn
integer
Background bit specifier



[Top] [Prev] [Next]

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