[Top] [Prev] [Next] [Bottom]

3.7 Obtaining Information About SD Data Sets

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

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.

SDgetinfo takes an SDS id as input, and returns the name, rank, dimensions, data type, and number of attributes for the corresponding SDS. The attribute count will only reflect the number of attributes assigned to the SDS array; file attributes are not included.

TABLE 3J SDfileinfo and SDgetinfo Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

SDfileinfo

(sffinfo)

file_id

int32

integer

File identifier.

n_datasets

int32 *

integer

Number of data sets in the file.

n_file_attr

int32 *

integer

Number of global attributes in the file.

SDgetinfo

(sfginfo)

sds_id

int32

integer

Data set identifier

sds_name

char*

character* (*)

Space to put the name of the data set.

rank

int32 *

integer

Space to put the number of dimensions in the array.

dim_sizes

int32 []

integer (*)

Space to put the size of each dimension in the array.

data_type

int32 *

integer

Space to put the data type for the data in the array.

nattrs

int32 *

integer

Space to put the number of attributes in the data set.

EXAMPLE 11. Printing Data Set Names

The SDgetinfo function can be called within a loop to retrieve the names of all data sets in an HDF file, as shown in the following examples.

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);

}

FORTRAN:

	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.

If the index of an SDS in an HDF file is known, SDselect can be used immediately. If not, it is necessary to determine the index by some other means. SDnametoindex determines the index of an SDS from its name. Selecting a data set by name involves the following steps:

1. Convert the SDS name into a valid index number.
2. Select the SDS by obtaining its identifier from its index number.
To access a SDS via its name, the calling program must contain the following function calls:

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.

The SDnametoindex routine is case-sensitive and does not accept wildcards.

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:

1. Convert the reference number for the SDS into a valid index number.
2. Select the SDS by obtaining its identifier from its index number.
To select a data set by reference number, the calling program must execute the following calls:

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.

Because the HDF library assigns reference numbers in unpredictable ways, reference numbers should be used to identify SDSs only when no other means are available. Reference numbers do not necessarily adhere to any ordering scheme.

TABLE 3K SDnametoindex and SDreftoindex Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

SDnametoindex

(sfn2index)

sd_id

int32

integer

SD interface identifier.

sds_name

char *

character* (*)

Name of the data set to index.

SDreftoindex

(sfref2index)

sd_id

int32

integer

SD interface identifier.

ref

int32

integer

IN: Reference number for the specified data set.

EXAMPLE 12. Searching for the Index of an SDS

In these examples, an invalid data set name is specified which results in SDnametoindex returning a value of -1. A valid data set name is then provided and the returned index is used to read the contents of the corresponding data set.

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);

}

FORTRAN:

	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.

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)

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 start_bit parameter specifies the leftmost position of the variable-length bit field to be written. For example, in the bit field described in the preceding paragraph a start_bit parameter value of 1 would denote the fourth bit value of 1 from the right.

The bit_len parameter 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 sign_ext parameter specifies whether to use the leftmost bit of the variable-length bit field to sign-extend to the leftmost 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 is set to either TRUE or FALSE - specify TRUE to sign-extend.

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

The "background" bits of a variable-length data set are the bits that fall outside of the variable-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 fill_one parameter 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.

This bit operation is performed before the sign-extend bit-filling. 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 SUCCEED (or 0) upon successful completion and FAIL (or -1) otherwise.

TABLE 3L SDsetnbitdataset Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

SDsetnbitdataset

(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] [Bottom]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF Development Group.