[Top] [Prev] [Next]

3.4 Programming Model for the SD Interface

This section describes the routines used to initialize the SD interface, create a new SDS or access an existing one, terminate access to that SDS, and shut down the SD interface. Writing to existing scientific data sets will be described in Section 3.5 on page 28.

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 creating and accessing an SDS in an HDF file is as follows:

  1. Open a file and initialize the SD interface.
  2. Create a new data set or open an existing one using its index.
  3. Perform desired operations on this data set.
  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 = SDcreate(sd_id, sds_name, data_type, rank, dim_sizes);	
	OR	sds_id = SDselect(sd_id, sds_index);
		<Optional operations>
		status = SDendaccess(sds_id);
		status = SDend(sd_id);
FORTRAN:	sd_id = sfstart(filename, access_mode)
		sds_id = sfcreate(sd_id, sds_name, data_type, rank, dim_sizes)	
	OR	sds_id = sfselect(sd_id, sds_index)	
		<Optional operations>
		status = sfendacc(sds_id)
		status = sfend(sd_id)
To access several files at the same time, a program must obtain a separate SD file identifier (sd_id) for each file to be opened. Likewise, to access more than one SDS, a calling program must obtain a separate SDS identifier (sds_id) for each SDS. For example, to open two SDSs stored in two files a program would execute the following series of function calls.

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)

3.4.1 Establishing Access to Files and Data Sets: SDstart, SDcreate, 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 SD interface identifier, sd_id. Note that the SD interface identifier, sd_id, is not interchangeable with the file identifier, file_id, created by Hopen and used in other HDF APIs.

The argument filename is the name of an HDF or netCDF file.

The argument access_mode specifies the type of access required for operations on the file. All the valid values for access_mode are listed in Table 3B. If the file does not exist, specifying DFACC_READ or DFACC_WRITE will cause SDstart to return a FAIL (or -1) . Specifying DFACC_CREATE creates a new file with read and write access. If DFACC_CREATE is specified and the file already exists, the contents of this file will be replaced.

TABLE 3B - File Access Code Flags

File Access Flag
Flag Value
Description
DFACC_READ
1
Read only access

DFACC_WRITE
2
Read and write access

DFACC_CREATE
4
Create with read and write access

The SD interface identifiers can be obtained and discarded in any order and all SD interface identifiers must be individually discarded, by SDend, before the termination of the calling program.

Although it is possible to open a file more than once, it is recommended that the appropriate access mode be specified and SDstart called only once per file. Repeatedly calling SDstart on the same file and with different access modes may cause unexpected results.

SDstart returns an SD identifier or a value of FAIL (or -1). The parameters of SDstart are defined in Table 3C on page 27.

SDcreate defines a new SDS using the arguments sd_id, sds_name, data_type, rank, and dim_sizes and returns the data set identifier, sds_id.

The parameter sds_name is a character string containing the name to be assigned to the SDS. The SD interface will generate a default name, "Data Set", for the SDS, if one is not provided, i.e., when the parameter sds_name is set to NULL in C, or an empty string in FORTRAN-77. The maximum length of an SDS name is 64 characters and, if sds_name contains more than 64 characters, the name will be truncated before being assigned.

The parameter data_type is a defined name, prefaced by DFNT, and specifies the type of the data to be stored in the data set. The header file "hntdefs.h" contains the definitions of all valid data types, which are described in Chapter 2, HDF Fundamentals, and listed in Table 2F on page 14.

The parameter rank is a positive integer specifying the number of dimensions of the SDS array. The maximum rank of an SDS array is defined by MAX_VAR_DIMS (or 32), which is defined in the header file "netcdf.h".

Each element of the one-dimensional array dim_sizes specifies the length of the corresponding dimension of the SDS array. The size of dim_sizes must be the value of the parameter rank. To create a data set with an unlimited dimension, assign the value of SD_UNLIMITED (or 0) to dim_sizes[0] in C, and to dim_sizes(rank) in FORTRAN-77.

Once an SDS is created, you cannot change its name, data type, size, or shape. However, it is possible to modify the data set data or to create an empty data set and later add values. To add data or modify an existing data set, use SDselect to get the data set identifier instead of SDcreate.

Note that the SD interface retains no definitions about the size, contents, or rank of an SDS from one SDS to the next, or from one file to the next.

SDselect initiates access to an existing data set. The routine takes two arguments: sd_id and sds_index and returns the SDS identifier sds_id. The argument sd_id is the SD interface identifier returned by SDstart, and sds_index is the position of the data set in the file. The argument sds_index is zero-based, meaning that the index of first SDS in the file is 0.

Similar to SD interface identifiers, SDS identifiers can be obtained and discarded in any order as long as they are discarded properly. Each SDS identifier must be individually disposed of, by SDendaccess, before the disposal of the identifier of the interface in which the SDS is opened.

SDcreate and SDselect each returns an SDS identifier or a value of FAIL (or -1). The parameters of SDstart, SDcreate, and SDselect are further described in Table 3C.

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

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

SDend terminates access to the file and the SD interface and disposes of the file identifier sd_id. 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.

SDendaccess and SDend each returns either a value of SUCCEED (or 0) or FAIL (or -1). The parameters of SDendaccess and SDend are further described in Table 3C.

TABLE 3C - SDstart, SDcreate, SDselect, SDendaccess, and SDend Parameter Lists

Routine Name

[Return Type]

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

[int32]

(sfstart)
filename
char *
character*(*)
Name of the HDF or netCDF file

access_mode
int32
integer
Type of access

SDcreate

[int32]

(sfcreate)
sd_id
int32
integer
SD interface identifier

sds_name
char *
character*(*)
ASCII string containing the name of the data set

data_type
int32
integer
Data type of the data set

rank
int32
integer
Number of dimensions in the array

dim_sizes
int32[]
integer(*)
Array defining the size of each dimension

SDselect

[int32]

(sfselect)
sd_id
int32
integer
SD interface identifier

sds_index
int32
integer
Position of the data set within the file

SDendaccess

[intn]

(sfendacc)
sds_id
int32
integer
Data set identifier

SDend

[intn]

(sfend)
sd_id
int32
integer
SD interface identifier

EXAMPLE 1. Creating an HDF file and an Empty SDS.

This example illustrates the use of SDstart/sfstart, SDcreate/sfcreate, SDendaccess/sfendacc, and SDend/sfend to create the HDF file named SDS.hdf, and an empty data set with the name SDStemplate in the file.

Note that the Fortran program uses a transformed array to reflect the difference between C and Fortran internal data storages. When the actual data is written to the data set, SDS.hdf will contain the same data regardless of the language being used.

C version

FORTRAN-77 version



[Top] [Prev] [Next]

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