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

3.4 Programming Model for the SD Interface

To support multifile access, the SD interface relies on the calling program to initiate and terminate access to files and data sets. The SD programming model for accessing an SDS in an HDF file is as follows:

1. Open a file and initialize the SD interface.
2. Open an existing SDS by obtaining an SDS id from an SDS index OR create a new SDS by obtaining an SDS id from the SDS name, rank and dimensions.
3. Perform desired operations on the SDS.
4. Terminate access to the data set.
5. Terminate access to the SD interface and close the file.
To access a single SDS in an HDF file, the calling program must contain the following calls:

C:		sd_id = SDstart(filename, access_mode);
		sds_id = SDselect(sd_id, sds_index);
		<Optional operations>
		status = SDendaccess(sds_id);
		status = SDend(sd_id);

FORTRAN:	sd_id = sfstart(filename_1, access_mode)
		sds_id = sfselect(sd_id, sds_index)
		<Optional operations>
		status = sfendaccess(sds_id)
		status = sfend(sd_id)

To access several files at the same time, a calling program must obtain a separate file id for each file to be opened. Likewise, to access more than one SDS a calling program must obtain a separate SDS id for each SDS. For example, to open two SDSs stored in two files a program would execute a series of function calls similar to the following:

C:		sd_id_1 = SDstart(filename_1, access_mode);
		sds_id_1 = SDselect(sd_id_1, sds_index_1);
		sd_id_2 = SDstart(filename_2, access_mode);
		sds_id_2 = SDselect(sd_id_2, sds_index_2);
		<Optional operations>
		status = SDendaccess(sds_id_1);
		status = SDend(sd_id_1);
		status = SDendaccess(sds_id_2);
		status = SDend(sd_id_2);

FORTRAN:	sd_id_1 = sfstart(filename_1, access_mode)
		sds_id_1 = sfselect(sd_id_1, sds_index_1)
		sd_id_2 = sfstart(filename_2, access_mode)
		sds_id_2 = sfselect(sd_id_2, sds_index_2)
		<Optional operations>
		status = sfendacc(sds_id_1)
		status = sfend(sd_id_1)
		status = sfendacc(sds_id_2)
		status = sfend(sd_id_2)

As with file identifiers, SD ids can be obtained and discarded in any order and all SD ids must be individually discarded before termination of the calling program.

3.4.1 Establishing Access to Files and Data Sets: SDstart and SDselect

In the SD interface, SDstart is used to open files rather than Hopen. SDstart takes two arguments; filename and access_mode, and returns the file id sd_id. The argument filename is the name of an HDF or netCDF file as it is stored on disk. All other functions in the SD interface accept only sd_id for file operations. The argument access_mode specifies the type of access required for operations on the file. The access mode tags passed in the access_mode parameter have names prefaced by "DFACC".

Although it is possible to open a file more than once, it is better to select the most appropriate access mode and call SDstart only once. Repeatedly calling SDstart may cause unexpected results and is not recommended.

If access_mode is set to DFACC_RDONLY, the specified file will not be created if it doesn't exist.

SDselect takes two arguments: sd_id and sds_index and returns the data set id sds_id. The argument sd_id is the file identifier returned by SDstart, and sds_index is the position of the data set relative to the beginning of the file. The argument sds_index is zero-based, meaning that the index of first SDS in the file is 0.

The parameters of SDstart and SDselect are further defined below. (See Table 3B.)

3.4.2 Terminating Access to Files and Data Sets: SDendaccess and SDend

SDendaccess disposes of the open data set id sds_id and terminates access to the data set. The calling program must make one SDendaccess call for every SDselect call made during its execution. Failing to call SDendaccess for each call to SDselect or SDcreate may result in a loss of data.

SDend disposes of the file id file_id and terminates access to the file and the SD interface. The calling program must make one SDend call for every SDstart call made during its execution. Failing to call SDend for each SDstart may result in a loss of data.

The parameters of SDendaccess and SDend are further defined in the following table.

TABLE 3B SDstart, SDselect, SDend and SDendaccess Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

SDstart

(sfstart)

filename

char *

character* (*)

Name of the HDF or netCDF file.

access_mode

int32

integer

Type of access.

SDselect

(sfselect)

file_id

int32

integer

HDF file identifier.

sds_index

int32

integer

Position of the data set within the file.

SDend

(sfend)

file_id

int32

integer

HDF file identifier.

SDendaccess

(sfendacc)

sds_id

int32

integer

Data set identifier.

EXAMPLE 1. Accessing and Closing an SDS

The following examples are a code template on how to access the first data set in an HDF file, then detach from the data set and the file. The file name "Dummy_HDF_File.hdf" represents a preexisting HDF file - replace it with the name of your target file.

This example assumes that the "Dummy_HDF_File.hdf" file contains one SDS.

C:

#include "mfhdf.h"

main( ) 
{
	int32 sd_id, sds_id, sds_index, status;
	int32 rank, num_type, attributes;

	/* Open the HDF file. DFACC_CREATE is defined in hdf.h. */
	sd_id = SDstart("Dummy_HDF_File.hdf", DFACC_CREATE);

	/* Get the identifier of the first data set. */
	sds_index = 0;
	sds_id = SDselect(sd_id, sds_index);

	/* Dispose of the data set identifier to terminate access. */
	status = SDendaccess(sds_id);

	/* Dispose of the file identifier to close the file. */
	status = SDend(sd_id);

}

FORTRAN:

	PROGRAM SDSDATA ACCESS

      integer*4 sds_id, sd_id, sds_index, status
      integer sfstart, sfselect, sfendacc, sfend

C     DFACC_CREATE is defined in hdf.h.
      parameter (DFACC_CREATE = 4)

C     Open the HDF file.
      sd_id = sfstart('Dummy_HDF_File.hdf', DFACC_CREATE)

C     Get the identifier of the first data set.
      sds_index = 0
      sds_id = sfselect(sd_id, sds_index)

C     Dispose of the data set identifier to terminate access.
      status = sfendacc(sds_id)

C     Dispose of the file identifier to close the file.
      status = sfend(sd_id)

      end



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

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