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

3.6 Reading Data from an SDS Array: SDreaddata

Selecting an SD data set and reading one or more slabs from it involves the following steps:

1. Select an SDS.
2. Read a slab or series of slabs.
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, edge, data);

FORTRAN:	sds_id = sfselect(sd_id, sds_index)
		status = sfrdata(sds_id, start, stride, edge, data)

SDreaddata reads an entire array, slabs of an array or it can be used to read a subset of the array. For more information on reading attributes or scales see Section 3.10.3 on page 84 and Section 3.9.4.3 on page 75.

The sds_id argument is the SDS id returned by SDcreate or SDselect. As with SDwritedata, the arguments start, stride, and edge respectively describe the n-dimensional coordinate of the slab the SD interface will begin the read operation, number of locations the current SDS location will be moved forward after each read, and the length of each dimension of the subset to be read. If the SDS array is smaller than the data argument array, the amount of data read will be truncated to the size of the SDS array. For additional information on the start, stride and edge parameters refer to Section 3.5.2 on page 28.

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

The parameters of SDreaddata are further described in the following table. Note that, because there are two Fortran-77 versions of SDreaddata, there are correspondingly two entries in the "Data Type" field of the data parameter.

TABLE 3I SDreaddata Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

SDreaddata

(sfrdata/

sfrcdata)

sds_id

int32

integer

Data set identifier.

start

int32 []

integer (*)

Array containing the position 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.

edge

int32 []

integer (*)

Array containing the number of data elements that will be read along each dimension.

data

VOIDP

<valid numeric data type>

Buffer the data will be read into.

EXAMPLE 8. Reading an Entire SDS

When SDreaddata is used to read an entire n-dimensional SDS array, the coordinates for the start position must begin at 0 for each dimension (start={0,0, ... 0}), the interval between each read must equal 1 for each dimension (stride=NULL or stride={1,1, ... 1}), and the size of each dimension must equal the size of the array itself (edge={dim_size_1, dim_size_2, ... dim_size_n}). The data buffer must have enough preallocated space to hold the data.

C:

#include "hdf.h"
#include "mfhdf.h"

#define X_LENGTH 4
#define Y_LENGTH 5
#define Z_LENGTH 6

main( )
{
	int32 sd_id, sds_id, status;
	int32 start[3], edges[3];
	int16 array_data[Z_LENGTH][Y_LENGTH][X_LENGTH];

	/* Open the file and initiate the SD interface. */
	sd_id = SDstart("Example4.hdf", DFACC_RDONLY);

	/* Select the first (and in this case, only) data set in the file. */
	sds_id = SDselect(sd_id, 0);

	/* Define the location, pattern, and size of the data to read. */
	start[0] = start[1] = start[2] = 0;
	edges[0] = Z_LENGTH;
	edges[1] = Y_LENGTH;
	edges[2] = X_LENGTH;

	/* Read the array. */
	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 gr_id, gr_index, ri_id, file_id, status
      integer*4 start(2), edges(2), stride(2) 
      integer mgstart, mgn2ndx, mgrdimg, mgendac, mgselct
      integer mgend, hopen, hclose

C     DFACC_RDONLY is defined in hdf.h.
      integer*4 DFACC_RDONLY
      integer*4 X_LENGTH, Y_LENGTH
      parameter (DFACC_RDONLY = 1, X_LENGTH = 10, Y_LENGTH = 20)
      integer*2 image_data(2, X_LENGTH, Y_LENGTH)

C     Open the file. 
      file_id = hopen('Example5.hdf', DFACC_RDONLY, 0)

C     Initialize the GR interface. 
      gr_id = mgstart(file_id)

C     Search for the index of a non-existent image. 
      gr_index = mgn2ndx(gr_id, 'Invalid_Data_Set_Name')

C     Error condition: gr_index contains the value -1. 
C     Search for the index of the image named 'Image_array_5'. 
      gr_index = mgn2ndx(gr_id, 'Image_array_5')

C     Select the image corresponding to the returned index.
      ri_id = mgselct(gr_id, gr_index)

C     Read the image data into the image_data array. 
      start(1) = 0
      start(2) = 0
      edges(1) = X_LENGTH
      edges(2) = Y_LENGTH
      stride(1) = 1
      stride(2) = 1
      status = mgrdimg(ri_id, start, stride, edges, image_data)

C     Terminate access to the array. 
      status = mgendac(ri_id)

C     Terminate access to the GR interface and the file.
      status = mgend(gr_id)

C     Close the file.
      status = hclose(file_id)

      end

EXAMPLE 9. Reading a Subset of an SDS Array

The start and edges arguments of the SDreaddata function can be used to read a subset of the entire data set, as shown in the following examples.

C:

#include "hdf.h"
#include "mfhdf.h"

#define X_LENGTH 5
#define Y_LENGTH 16

main( ) 
{

	int32 sd_id, sds_id;
	int32 start[2], edges[2];
	int16 all_data[Y_LENGTH][X_LENGTH], subset_data[7][3], status;

	/* Open the file for read-only access. */
	sd_id = SDstart("Example3.hdf", DFACC_RDONLY);

	/* Select the first data set. */
	sds_id = SDselect(sd_id, 0);

	/* First, read the entire data set. */
	start[0] = start[1] = 0;
	edges[0] = Y_LENGTH;
	edges[1] = X_LENGTH;
	status = SDreaddata(sds_id, start, NULL, edges, (VOIDP)all_data);

	/* Read a subset of the data set. */
	start[0] = 1;
	start[1] = 1;
	edges[0] = 7;
	edges[1] = 3;
	status = SDreaddata(sds_id, start, NULL, edges, (VOIDP)subset_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 READ SUBSET

      integer*4 sd_id, sds_id
      integer start(2), edges(2), stride(2), status
      integer sfstart, sfselect, sfrdata, sfendacc, sfend

C     DFACC_RDONLY is defined in hdf.h.
      integer*4 DFACC_RDONLY
      integer*4 X_LENGTH, Y_LENGTH
      parameter (DFACC_RDONLY = 1, X_LENGTH = 5, Y_LENGTH = 16)
      integer*2 all_data(X_LENGTH, Y_LENGTH)
      integer*2 subset_data(3, 7)

C     Open the file. 
      sd_id = sfstart('Example3.hdf', DFACC_RDONLY)

C     Select the first data set. 
      sds_id = sfselect(sd_id, 0)

C     Read the entire data set. 
      start(1) = 0
      start(2) = 0
      edges(1) = 5
      edges(2) = 16
      stride(1) = 1
      stride(2) = 1
      status = sfrdata(sds_id, start, stride, edges, all_data)

C     Read a subset from the middle of the data set. 
      start(1) = 1
      start(2) = 1
      edges(1) = 3
      edges(2) = 7
      status = sfrdata(sds_id, start, stride, edges, subset_data)

C     Terminate access to the array. 
      status = sfendacc(sds_id)

C     Terminate access to the SD interface and close the file. 
      status = sfend(sd_id)

      end


EXAMPLE 10. Sampling SDS Data

These examples demonstrate how samples of data set elements can be read by using the stride argument of the SDreaddata function. Here we read every tenth row and every other column.

C:

#include "hdf.h"
#include "mfhdf.h"

#define X_LENGTH 10
#define Y_LENGTH 20

main( ) 
{

	int32 sd_id, sds_id, rank, start[2], edges[2], stride[2], dims[2];
	int16 all_data[Y_LENGTH][X_LENGTH], sample_data[5][5];
	intn i, j;
	int16 status;

	/* Open the file. */
	sd_id = SDstart("Example10.hdf", DFACC_CREATE);

	/* Define the rank and dimensions of the array to be created. */
	rank = 2;
	dims[0] = Y_LENGTH;
	dims[1] = X_LENGTH;

	/* Create the array. */
	sds_id = SDcreate(sd_id, "Ex_array_10", DFNT_INT16, rank, dims);

	/* Compute and store the data values. */
	for (j = 0; j < Y_LENGTH; j++) {
		for (i = 0; i < X_LENGTH; i++) 
			all_data[j][i] = i + j * 10;
	}

	/* Define the start and edge parameters. */
	start[0] = start[1] = 0;
	edges[0] = Y_LENGTH;
	edges[1] = X_LENGTH;

	/* Write the buffered data in all_data to the data set. */
	status = SDwritedata(sds_id, start, NULL, edges, (VOIDP)all_data);

	/* Close the SD interface and the file, then re-open both and \
	select the first and only data set in the file. */

	status = SDendaccess(sds_id);
	status = SDend(sd_id);

	sd_id = SDstart("Example10.hdf", DFACC_RDONLY);
	sds_id = SDselect(sd_id, 0);

	/* Read the data into the sample_data array, skipping every fourth \
	row and every other column. */
	start[0] = start[1] = 0;
	edges[0] = 5;
	edges[1] = 5;
	stride[0] = 4;
	stride[1] = 2;

	status = SDreaddata(sds_id, start, stride, edges, (VOIDP)sample_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 READ STRIDES

      integer*4 sd_id, sds_id, rank
      integer*4 start(2), edges(2), stride(2), dims(2)
      integer i, j, status
      integer sfstart, sfcreate, sfwdata, sfrdata, sfendacc
      integer sfselect, sfend

C     DFACC_CREATE and DFNT_INT16 are defined in hdf.h.
      integer*4 DFACC_CREATE, DFACC_RDONLY, DFNT_INT16
      integer*4 X_LENGTH, Y_LENGTH
      parameter (DFACC_CREATE = 4, DFACC_RDONLY = 1, DFNT_INT16 = 22,
     +            X_LENGTH = 10, Y_LENGTH = 20)
      integer*2 all_data(X_LENGTH, Y_LENGTH), sample_data(5, 5)

C     Create the file. 
      sd_id = sfstart('Example10.hdf', DFACC_CREATE)

C     Define the rank and dimensions of the array to be created. 
      rank = 2
      dims(1) = X_LENGTH
      dims(2) = Y_LENGTH

C     Create the array. 
      sds_id = sfcreate(sd_id, 'Ex_array_10', DFNT_INT16, rank, dims)

C     Compute and store the data values. 
      do 20 j = 1, Y_LENGTH
         do 10 i = 1, X_LENGTH
            all_data(i, j) = i + j * 10
10         continue
20    continue

C     Set up the start and edge parameters to write the buffered
C     data to the entire array data set. 
      start(1) = 0
      start(2) = 0
      edges(1) = X_LENGTH
      edges(2) = Y_LENGTH
      stride(1) = 1
      stride(2) = 1

C     Write the buffered data in wrt_data to the data set. 
      status = sfwdata(sds_id, start, stride, edges, all_data)

C     Close the SD interface and the file, then re-open both and 
C     select the first and only data set in the file. 
      status = sfendacc(sds_id)
      status = sfend(sd_id)
      sd_id = sfstart('Example10.hdf', DFACC_RDONLY)
      sds_id = sfselect(sd_id, 0)

C     Read the data into the sample_data array, skipping every fourth 
C     row and every other column. 
      edges(1) = 5
      edges(2) = 5
      stride(1) = 2
      stride(2) = 4
      status = sfrdata(sds_id, start, stride, edges, sample_data)

C     Terminate access to the array. 
      status = sfendacc(sds_id)

C     Terminate access to the SD interface and close the file. 
      status = sfend(sd_id)

      end

3.6.1 Reading Data from an External File

SDS data is read from an external file in the same way that it is read from a primary file. Whether the SDS data is or is not stored in an external file is transparent to the user.



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

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