SDfileinfo obtains the number of SDSs and file attributes in a file, and SDgetinfo provides information about individual SDSs. To cycle through the data sets in a file, a calling program must use SDfileinfo to determine the number of data sets, followed by repeated calls to SDgetinfo to view them. The parameters of these two routines are described below. (See Table 3J on page 53.)
At times you might need to search through a file for an SDS for a given name or reference number. The SDnametoindex routine determines the index of an SDS from its name, and SDreftoindex determines the index of an SDS from its reference number. The parameters of these two routines are described below. (See Table 3K on page 56.)
3.7.1 Obtaining Information About the SDSs in a File: SDfileinfo
It is often useful to determine the number of scientific data sets and global SDS attributes contained in a file before executing a series of read or write operations. The SDfileinfo routine is designed for this purpose. To determine the contents of a file, the calling program must contain the following calls:
C: sd_id = SDstart(filename, access_mode); status = SDfileinfo(sd_id, n_datasets, n_file_attr); status = SDend(sd_id); FORTRAN: sd_id = sfstart(filename, access_mode) status = sffinfo(sd_id, n_datasets, n_file_attr) status = sfend(sd_id)
SDfileinfo uses n_datasets to return the number of scientific data sets in the file, and n_file_attr to return the number of file attributes in the file.
3.7.2 Obtaining Information About a Specific SDS: SDgetinfo
Some information may be needed before reading and working with SDS arrays. For instance, if the rank, dimension sizes and/or data type of an array are unknown, it may be impossible to allocate the proper amount of memory to work with the array. The SDgetinfo routine provides basic information about SDS arrays.TABLE 3J SDfileinfo and SDgetinfo Parameter List
C:
#include "hdf.h" #include "mfhdf.h" #include <stdio.h> main( ) { int32 sd_id, sds_id, n_datasets, n_file_attrs, index, status; int32 dim_sizes[MAX_VAR_DIMS]; int32 rank, num_type, attributes; char name[MAX_NC_NAME]; /* Open the file and initiate the SD interface. */ sd_id = SDstart("Example4.hdf", DFACC_RDONLY); /* Determine the contents of the file. */ status = SDfileinfo(sd_id, &n_datasets, &n_file_attrs); /* Access and print the name of every data set in the file. */ for (index = 0; index < n_datasets; index++) { sds_id = SDselect(sd_id, index); status = SDgetinfo(sds_id, name, &rank, dim_sizes, \ &num_type, &attributes); printf("name = %s\n", name); status = SDendaccess(sds_id); } /* Terminate access to the SD interface and close the file. */ status = SDend(sd_id); }
PROGRAM PRINT NAMES integer*4 sd_id, sds_id integer*4 n_datasets, n_file_attrs, index integer status, attributes integer sfstart, sffinfo, sfselect, sfginfo integer sfendacc, sfend C DFACC_RDONLY is defined in hdf.h. MAX_NC_NAME and MAX_VAR_DIMS C are defined in netcdf.h. integer*4 DFACC_RDONLY, MAX_NC_NAME, MAX_VAR_DIMS parameter (DFACC_RDONLY = 1, MAX_NC_NAME = 256, + MAX_VAR_DIMS = 32) integer*4 dim_sizes(MAX_VAR_DIMS) character name *(MAX_NC_NAME) C Open the file and initiate the SD interface. sd_id = sfstart('Example4.hdf', DFACC_RDONLY) C Determine the contents of the file. status = sffinfo(sd_id, n_datasets, n_file_attrs) C Access and print the names of every data set in the file. do 10 index = 0, n_datasets - 1 sds_id = sfselect(sd_id, index) status = sfginfo(sds_id, name, rank, dim_sizes, num_type, + attributes) print *, "name = ", name status = sfendacc(sds_id) 10 continue C Terminate access to the SD interface and close the file. status = sfend(sd_id) end
3.7.3 Locating a SDS Data Set by Name: SDnametoindex
When an SDS is created, a unique number is assigned to it by the SD library so that it can be located in the file for future access. This number is referred to as the index of an SDS.
C: sds_index = SDnametoindex(sd_id, sds_name); sds_id = SDselect(sd_id, sds_index); FORTRAN: sds_index = sfn2index(sd_id, sds_name) sds_id = sfselect(sd_id, sds_index)
SDnametoindex returns the index specified by the sds_index parameter for the first data set in the file with the name sds_name. If two data sets have the same name, SDnametoindex returns the index of the first data set. The index sds_index can then be used by SDselect to obtain an SDS id for the specified data set.
3.7.4 Locating an SDS by Reference Number: SDreftoindex
In addition to an index and name, data sets are also assigned a tag and reference number. SDreftoindex determines the index of the SDS from its reference number. Selecting a data set by reference number involves the following steps:
C: sds_index = SDreftoindex(sd_id, ref); sds_id = SDselect(sd_id, sds_index); FORTRAN: sds_index = sfref2index(sd_id, ref) sds_id = sfselect(sd_id, sds_index)
SDreftoindex returns the index specified by the sds_index parameter for the SDS in the file with the reference number ref. The index sds_index can then be passed to SDselect to obtain an SDS id for the SDS.
TABLE 3K SDnametoindex and SDreftoindex Parameter List
C:
#include "hdf.h" #include "mfhdf.h" #define X_LENGTH 4 #define Y_LENGTH 5 #define Z_LENGTH 6 main( ) { int32 sd_id, sds_index, sds_id, status; int32 start[3], edges[3]; int16 array_data[Z_LENGTH][Y_LENGTH][X_LENGTH]; /* Open the file. */ sd_id = SDstart("Example4.hdf", DFACC_RDONLY); /* Search for the index of a non-existent array data set. */ sds_index = SDnametoindex(sd_id, "Invalid_Data_Set_Name"); /* Error condition: sds_index contains the value -1. */ /* Search for the index of a "Ex_array_4" array data set. */ sds_index = SDnametoindex(sd_id, "Ex_array_4"); /* Select the data set corresponding to the returned index. */ sds_id = SDselect(sd_id, sds_index); /* Read the data set data into the array_data array. */ start[0] = start[1] = start[2] = 0; edges[0] = Z_LENGTH; edges[1] = Y_LENGTH; edges[2] = X_LENGTH; status = SDreaddata(sds_id, start, NULL, edges, (VOIDP)array_data); /* Terminate access to the array */ status = SDendaccess(sds_id); /* Terminate access to the SD interface and close the file */ status = SDend(sd_id); }
PROGRAM SEARCH INDEX integer*4 sd_id, sds_index, sds_id, status integer*4 start(3), edges(3), stride(3) integer sfstart, sfn2index, sfrdata, sfendacc, sfselect C DFACC_RDONLY is defined in hdf.h. integer*4 DFACC_RDONLY integer*4 X_LENGTH, Y_LENGTH, Z_LENGTH parameter (DFACC_RDONLY = 1, X_LENGTH = 4, Y_LENGTH = 5, + Z_LENGTH = 6) integer*2 array_data(X_LENGTH, Y_LENGTH, Z_LENGTH) C Open the file. sd_id = sfstart('Example4.hdf', DFACC_RDONLY) C Search for the index of a non-existent array data set. sds_index = sfn2index(sd_id, 'Invalid_Data_Set_Name') C Error condition: sds_index contains the value -1. C Search for the index of a 'Ex_array_4' array data set. sds_index = sfn2index(sd_id, 'Ex_array_4') C Select the data set corresponding to the returned index. sds_id = sfselect(sd_id, sds_index) C Read the data set data into the rd_data array. start(1) = 0 start(2) = 0 start(3) = 0 edges(1) = X_LENGTH edges(2) = Y_LENGTH edges(3) = Z_LENGTH stride(1) = 1 stride(2) = 1 stride(3) = 1 status = sfrdata(sds_id, start, stride, edges, array_data) C Terminate access to the array status = sfendacc(sds_id) end
3.7.5 Creating SDS Arrays Containing Variable-Length Data: SDsetnbitdataset
Version 4.0r1 of HDF provided the SDsetnbitdataset routine, allowing the HDF user to specify that a particular SDS array contains data of a non-standard length. Any length between 1 and 32 bits can be specified. After SDsetnbitdataset has been called for the SDS array, any read or write operations will involve a conversion between the new data length of the SDS array and the data length of the read or write buffer.
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)
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.
TABLE 3L SDsetnbitdataset Parameter List