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.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.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.SUCCEED (or 0) or FAIL (or -1). The parameters of SDcheckempty are specified in Table 3L.
TABLE 3L - SDfileinfo and SDgetinfo Parameter Lists
C 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. 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.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.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
C 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. 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.01111011, bits 2 and 7 are set to 0 and all the other bits are set to 1.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.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.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.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).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. 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.SUCCEED (or 0) or FAIL (or -1). The parameters for SDsetnbitdataset are specified in Table 3N.
TABLE 3N - SDsetnbitdataset Parameter List