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

11.4 Writing DFSD Scientific Data Sets

The DFSD programming model for writing an SDS to an HDF file involves the following steps:

1. Define data set options. (optional)
2. Write all or part of the data set.
These steps are performed for every data set written to a file. However, it is not always necessary to define data set options for every write operation as setting an option places information about the data set in a structure in primary memory. This information is retained until explicitly altered by another set call.

11.4.1 Creating a DFSD Scientific Data Set: DFSDadddata and DFSDputdata

To define and write a single SDS, the calling program must contain of of the following routines:

C:		status = DFSDadddata(filename, rank, dim_sizes, data);
FORTRAN:	status = dsadata(filename, rank, dim_sizes, data)		

OR

C:		status = DFSDputdata(filename, rank, dim_sizes, data);
FORTRAN:	status = dspdata(filename, rank, dim_sizes, data)

DFSDadddata appends data to a file when given an existing file name and creates a new file when given a unique file name. DFSDputdata replaces the contents of a file when given an existing file name and creates a new file when given a unique file name. To avoid accidentally overwriting data in a file, the use of DFSDadddata is recommended.

DFSDadddata and DFSDputdata have four parameters: filename, rank, dim_sizes, and data. In both routines, the data set is written to the file specified by the filename parameter. The total number of dimensions in the array and the size of each dimension are passed in the rank and dim_sizes parameters. A pointer to the data or slab of data written to the named file is passed in the data parameter.

The parameters of DFSDadddata and DFSDputdata are further described in the following table.

TABLE 11B DFSDadddata and DFSDputdata Parameter List.
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

DFSDadddata

(dsadata)

filename

char *

character* (*)

Name of the file containing the data set.

rank

int32

integer

Number of dimensions in the array.

dim_sizes

int32 *

integer (*)

Size of each dimension in the data array.

data

VOIDP

<valid numeric data type>

Array containing the data.

DFSDputdata

(dsadata)

filename

char *

character* (*)

Name of file containing the data set.

rank

int32

integer

Number of dimensions in the array.

dim_sizes

int32 *

integer (*)

Size of each dimension in the data array.

data

VOIDP

<valid numeric data type>

Array containing the data.

11.4.2 Specifying the Data Type of a DFSD SDS: DFSDsetNT

The default data type for scientific data is DFNT_FLOAT32. To change the default setting, the calling program must contain calls to the following routines:

C:		status = DFSDsetNT(number_type);

 		status = DFSDadddata(filename, rank, dim_sizes, data);

FORTRAN: status = dssnt(number_type) status = dsadata(filename, rank, dim_sizes, data)

DFSDsetNT defines the data type for all subsequent DFSDadddata and DFSDputdata calls until it is changed by a subsequent call to DFSDsetNT or reset to the default by DFSDclear. DFSDsetNT's only parameter is the data type.

EXAMPLE 1. Creating and Writing to a DFSD Scientific Data Set

In the following code examples, DFSDadddata is used to write an array of 64-bit floating-point numbers to a file named "Example1.hdf". Although the DFSDsetNT function call is optional, it is included here to demonstrate how to override the float32 default.

C:

#include "hdf.h"

#define LENGTH 3
#define HEIGHT 2
#define WIDTH 5

main( )
{

	/* Create data array - store dimensions in array 'dims' */
	static float64 scien_data[LENGTH][HEIGHT][WIDTH] = 
  		{ 1., 2., 3., 4., 5.,
		6., 7., 8., 9.,10.,
		11.,12.,13.,14.,15.,
		16.,17.,18.,19.,20.,
		21.,22.,23.,24.,25.,
		26.,27.,28.,29.,30. };

	intn status;

	int32 dims[3] = {LENGTH, HEIGHT, WIDTH};

	/* Set number type to 64-bit float */
	status = DFSDsetNT(DFNT_FLOAT64);

	/* Write the data to file */
	status = DFSDadddata("Example1.hdf", 3, dims, scien_data);

}

FORTRAN:

	 PROGRAM WRITE SDS      

      integer  dsadata, dssnt, dims(3), status
      real*8   sci_data(5,2,3)

C     Create array called 'sci_data'; store dimensions in array 'dims'.
      data     sci_data/ 1., 2., 3., 4., 5.,
     $                   6., 7., 8., 9.,10.,
     $                   11.,12.,13.,14.,15.,
     $                   16.,17.,18.,19.,20.,
     $                   21.,22.,23.,24.,25.,
     $                   26.,27.,28.,29.,30./

      data dims /3,2,5/

C     Set number type to 64-bit float
      status = dssnt(6)

C     Write the data to file
      status = dsadata('Example1.hdf', 3, dims, sci_data)

      end

11.4.3 Overwriting Data for a Given Reference Number: DFSDwriteref

DFSDwriteref is a highly specialized function call that overwrites data referred to by the specified reference number.

If DFSDwriteref is called with a reference number that doesn't exist, an error return value of -1 will be returned.

The following series of function calls should appear in your program:

C:		status = DFSDwriteref(filename, ref_number);

 		status = DFSDadddata(filename, rank, dim_sizes, data);

FORTRAN: status = dswref(filename, ref_number) status = dsadata(filename, rank, dim_sizes, data)

If the filename passed to DFSDwriteref is different from the filename in the DFSDadddata or DFSDputdata routine calls, it will be ignored. The next scientific data set written, regardless of the filename, is assigned the reference number ref_number.

Care should be taken when using DFSDwriteref, as once the new data has been written the old data cannot be retrieved.

The parameters of DFSDwriteref are described in the following table.

TABLE 11C DFSDsetNT and DFSDwriteref Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

DFSDsetNT

(dssNT)

number_type

int32

integer

Number type tag.

DFSDwriteref

(dswref)

filename

char *

character* (*)

Name of the file containing the data.

ref_number

int16

integer

Reference number to be assigned to the data setcreated.

11.4.4 Writing Several Data Sets: DFSDsetdims and DFSDclear

The DFSD programming model for writing multiple data sets to an HDF file is identical to that for writing individual data sets. (Refer to Section 11.4 on page 281). To understand how multiple data sets are written to file, it is first necessary to take a closer look at each step of the programming model. First and most importantly, all DFSD routines that set a write option except DFSDsetNT and DFSDsetfillvalue add information to a special structure in primary memory. This information is used to determine how data is written to file for all subsequent write operations.

Information stored in primary memory is retained by the HDF library until explicitly changed by a call to DFSDsetdims or reset to NULL by calling DFSDclear. DFSDsetdims and DFSDclear are used to prevent assignments of attributes created for a group of data sets to data sets outside the group. For more information on assigning attributes see Section 11.7.1 on page 293 and Section 11.7.3 on page 299.

11.4.5 Preventing the Reassignment of DFSD Data Set Attributes: DFSDsetdims

Information stored in primary memory is retained by the HDF library until explicitly changed by a call to DFSDsetdims or reset to NULL by calling DFSDclear. DFSDsetdims and DFSDclear are used to prevent assignments of attributes created for a group of data sets to data sets outside the group.

The syntax of DFSDsetdims is the following:

C:		status = DFSDsetdims(rank, dim_sizes);

FORTRAN:	status = dssdims(rank, dim_sizes)

DFSDsetdims is not used here to define the rank and dimension sizes to be used in the next operation, but to alert the DFSD interface to stop the automatic assignment of attributes to the data sets to be written to file. DFSDsetdims has two parameters: rank and dim_sizes. The rank of an array is the total number of dimensions in the array and the dimension sizes are the length of each individual dimension.

As a rule of thumb, DFSDsetdims should be called if any DFSDset* routine (DFSDsetNT, for example) has been called. This insures that all attribute values that have been reset will be assigned in future data set operations.

The parameters of DFSDsetdims are further defined in the following table.

TABLE 11D DFSDsetdims Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

DFSDsetdims

(dssdims)

rank

intn

integer

Number of dimensions in the array.

dim_sizes

int32*

integer (*)

Size of each dimension in the array.

11.4.6 Resetting the Default DFSD Interface Settings: DFSDclear

The syntax for DFSDclear is as follows:

C:		status = DFSDclear( );

FORTRAN:	status = dsclear( )

The DFSDclear routine clears all interface settings defined by any of the DFSDset routines (DFSDsetNT, DFSDsetfillvalue, DFSDsetdims, DFSDsetdatastrs, DFSDsetdatalengths, DFSDsetrange, DFSDsetcal, DFSDsetdimscale and DFSDsetdimstrs). After the DFSDclear has been called, calls to any of the DFSDset routines will result in the corresponding value not being written. To write new values, call the appropriate DFSDset routine again.

TABLE 11E DFSDclear Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

DFSDclear

(dsclear)

None

None

None

Clears all DFSD interface settings.



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

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