[Top] [Prev] [Next]

12.6 Slabs in the DFSD Interface

To review, a slab is an n-dimensional array whose dimensions are smaller than those of the SDS array into which it is written or from which it is read.

12.6.1 Accessing Slabs: DFSDstartslab and DFSDendslab

There are two routines required for every DFSD slab operation - DFSDstartslab and DFSDendslab. DFSDstartslab is used to initialize the slab interface and to initiate access to new or existing data sets. DFSDendslab is used to terminate access to open data sets. DFSDstartslab must be called before any read or write slab operation and DFSDendslab must be called after the slab operation is completed. Both routines are required when reading and writing slabs.

Given a new filename, DFSDstartslab will create a new HDF file with the specified name. Given an existing filename, it will open the named file and append the new data set to the end of the file. Its only parameter is filename. DFSDendslab has no parameters and need only be called once per file. DFSDendslab will write any attributes defined immediately before the data set is created.

For more information on assigning attributes, see Section 12.7.3 on page 377.

TABLE 12I - DFSDstartslab Parameter List

Routine Name

[Return Type]

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

[intn]

(dssslab)
filename
char *
character*(*)
Name of the file containing the data set.

12.6.2 Writing Slabs: DFSDwriteslab

In the DFSD interface, writing an entire data set array and writing slabs follow the same programming model. The difference between the two is that calls to three routines is needed to write slabs, while a call to one routine is needed to write whole data sets.

More specifically, the DFSD programming model for writing slabs to an SDS is as follows:

  1. Set the appropriate options to define the new SDS or select an existing SDS.
  2. Write the data set using three specialized slab routines.

In addition to writing slabs to both new and existing data sets, DFSDwriteslab can also perform the following sequential write operations:

Although not specifically defined as a slab routine, in practice, the DFSDsetfillvalue routine is used to initialize array elements between non-contiguous slab write operations. Setting a fill value places the same value in every array location before the first slab is written. Any hole created by non-contiguous writes can then be recognized by identifying the known fill value. The fill value must have the same number type as the values in the data set. For more information on fill values refer to Section 12.7.1.2 on page 374.

To write a slab to a new data set, the calling program must include the following routine calls:

C:		status = DFSDsetdims(rank, dimsizes);
		status = DFSDsetNT(num_type);
		status = DFSDstartslab(filename);
		status = DFSDwriteslab(start, stride, count, data);
		status = DFSDendslab( );
FORTRAN:	status = dssnt(num_type)
		status = dssdims(rank, dim_sizes)
		status = dssslab(filename)
		status = dswslab(start, stride, edge, data)
		status = dseslab( )
When writing slabs to an existing data set, it is impossible to change the number type, array boundaries, fill value, or calibration information. Consequently DFSDsetNT, DFSDsetdims, DFSDsetcal, and DFSDsetfillvalue will generate errors if called for an existing data set.

To write a slab to an existing data set, your program should include the following calls:

C:		status = DFSDwriteref(filename, ref);
		status = DFSDstartslab(filename);
		status = DFSDwriteslab(start, stride, count, data);
		status = DFSDendslab( );
FORTRAN:	status = dswref(filename, ref)
		status = dssslab(filename)
		status = dswslab(start, stride, edge, data)
		status = dseslab( )
Because DFSDwriteslab offers no overwrite protection, the calling program is responsible for eliminating overlap when arranging slabs within the newly defined data set.

DFSDwriteslab has four arguments: start, stride, edge, and data. The arguments start, stride, and edge are defined as they are in the corresponding SD routines.

The DFSD SDS model does not support strides. Pass the start array as the stride parameter as a place holder. Whatever is passed as the stride parameter will be ignored by the DFSD interface.

Although DFSDendslab need only be called once per file, it is required to write data to the file. It will also write any attributes defined immediately before the data set is created.

TABLE 12J - DFSDwriteslab Parameter List

Routine Name

[Return Type]

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

[intn]

(sdwslab)
start
int32 *
integer (*)
Array containing the starting coordinate the write.

stride
int32 *
integer (*)
Ignored parameter.

count
int32 *
integer (*)
Array defining the boundaries of the slab.

data
VOIDP
<valid numeric data type>
Buffer for the data to be written.

12.6.3 Reading Slabs: DFSDreadslab

The programming model for reading one or more slabs involves the following steps:

  1. Select an existing SDS.
  2. Read the data set using three specialized slab routines.

In addition to reading single slabs of data, DFSDreadslab can perform the following sequential access operations:

To read a slab, the calling program must include the following routine calls:

C:		status = DFSDreadref(filename, ref);
		status = DFSDstartslab(filename);
		status = DFSDreadslab(start, stride, edge, data);
		status = DFSDendslab( );
FORTRAN:	status = dsrref(filename, ref)
		status = dssslab(filename)
		status = dsrslab(start, stride, edge, data)
		status = dseslab( )
In addition to DFSDreadref, DFSDgetdims may also be used to position the read pointer to the appropriate data set. When DFSDreadslab is used to read slabs, the coordinates of the start array must begin at 0 for each dimension (start={0,0, ... 0}) and the size of each dimension must equal the size of the array itself (edge={dim_size_1, dim_size_2, dim_size_n}). As with DFSDwriteslab, whatever is passed in as the stride parameter is ignored. Finally, the data buffer must allocate enough space to hold the data: excess data is truncated.

All parameters of the DFSDreadslab routine assume FORTRAN-77-style one-based arrays - the starting coordinates of the slab must be given as an offset from the origin of the data set where the origin is defined as (dim 1 = 1, dim 2 = 1, . . . dim n-1 = 1, dim n = 1). The first element of the slab will be the coordinates specified by the contents of the start array. DFSDreadslab will extract elements in increasing order until the until the dimensional offset specified by the contents of the edge array are encountered.

TABLE 12K - DFSDreadslab Parameter List

Routine Name

[Return Type]

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

[intn]

(dswslab)
filename
char *
character*(*)
Name of the HDF file.

start
int32 *
integer (*)
Array containing the coordinates for start of the slab.

slab_size
int32
integer (*)
Array of rank containing the size of each dimension of the slab.

stride
int32 *
integer (*)
Place holder array.

buffer
VOIDP
<valid numeric data type>
Array the will used to store the extracted slab.

buffer_size
int32 *
integer (*)
Array containing the dimensions of the buffer parameter.



[Top] [Prev] [Next]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 07/21/98, NCSA HDF Development Group.