[Top] [Prev] [Next]

12.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.

12.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 12B - DFSDadddata and DFSDputdata Parameter List.

Routine Name

[Return Type]

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

[intn]

(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

[intn]

(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.

12.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 version



FORTRAN-77 version



12.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 12C - DFSDsetNT and DFSDwriteref Parameter List

Routine Name

[Return Type]

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

[intn]

(dssNT)
number_type
int32
integer
Number type tag.

DFSDwriteref

[intn]

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

ref_number
int16
integer
Reference number to be assigned to the data set created.

12.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 12.4 on page 363). 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 12.7.1 on page 373 and Section 12.7.3 on page 377.

12.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 12D - DFSDsetdims Parameter List

Routine Name

[Return Type]

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

[intn]

(dssdims)
rank
intn
integer
Number of dimensions in the array.

dim_sizes
int32*
integer (*)
Size of each dimension in the array.

12.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 12E - DFSDclear Parameter List

Routine Name

[Return Type]

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

[intn]

(dsclear)
None
None
None
Clears all DFSD interface settings.



[Top] [Prev] [Next]

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