[Top] [Prev] [Next]

3.6 Reading Data from an SDS Array: SDreaddata

Data of an SDS array can be read as an entire array, a subset of the array, or a set of samples of the array. SDS data is read from an external file in the same way that it is read from a primary file; whether the SDS array is stored in an external file is transparent to the user. Reading data from an SDS array involves the following steps:

  1. Select the data set.
  2. Define the portion of the data to be read.
  3. Read data portion as defined.

To read data from an SDS array, the calling program must contain the following function calls:

C:		sds_id = SDselect(sd_id, sds_index);
		status = SDreaddata(sds_id, start, stride, edges, data);
FORTRAN:	sds_id = sfselect(sd_id, sds_index)
		status = sfrdata(sds_id, start, stride, edges, data)					
	OR	status = sfrcdata(sds_id, start, stride, edges, data)
Note that step 2 is not illustrated in the function call syntax; it is carried out by assigning values to the parameters start, stride, and edges before the routine SDreaddata is called in step 3.

SDreaddata reads the data according to the definition specified by the parameters start, stride, and edges and stores the data into the buffer provided, data. The argument sds_id is the SDS identifier returned by SDcreate or SDselect. As with SDwritedata, the arguments start, stride, and edges describe the starting location, the number of elements to skip after each read, and the number of elements to be read, respectively, for each dimension. For additional information on the parameters start, stride, and edges, refer to Section 3.5.1 on page 28.

There are two FORTRAN-77 versions of this routine: sfrdata reads numeric data and sfrcdata reads character data.

SDreaddata returns a value of SUCCEED (or 0), including the situation when the data set does not contain data, or FAIL (or -1). The parameters of SDreaddata are further described in Table 3K.

TABLE 3K - SDreaddata Parameter List

Routine Name

[Return Type]

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

[intn]

(sfrdata/
sfrcdata)
sds_id
int32
integer
Data set identifier

start
int32[]
integer(*)
Array containing the position at which the read will start for each dimension

stride
int32[]
integer(*)
Array containing the number of data locations the current location is to be moved forward before the next read

edges
int32[]
integer(*)
Array containing the number of data elements to be read along each dimension

data
VOIDP
<valid numeric data type>(*)/
character*(*)
Buffer the data will be read into

EXAMPLE 8. Reading from an SDS.

This example uses the routine SDreaddata/sfrdata to read the data that has been written in Example 2, modified in Example 4, and moved to the external file in the Example 7. Note that the original file SDS.hdf that contains the SDS metadata and the external file ExternalSDS that contains the SDS raw data should reside in the same directory. The fact that raw data is in the external file is transparent to the user's program.

C version

FORTRAN-77 version

EXAMPLE 9. Reading Subsets of an SDS.

This example shows how parameters start, stride, and edges of the routine SDreadata/sfrdata can be used to read three subsets of an SDS array.

C:

For the first subset, the program reads every 3rd element of the 2nd column starting at the 4th row of the data set created in Example 2 and modified in Examples 4 and 7.
For the second subset the program reads the first 4 elements of the 10th row.
For the third subset, the program reads from the same data set every 6th element of each column and 4th element of each row starting at 1st column, 3d row.
FORTRAN-77:

Fortran program reads transposed data to reflect the difference in C and Fortran internal storage.
C version

FORTRAN-77 version



[Top] [Prev] [Next]

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