The HDF Group

HDF Reference Manual


[DFSD Interface][Top]


DFSDadddata/dsadata

intn DFSDadddata(char *filename, intn rank, int32 dimsizes[], VOIDP data)

filename
IN:
Name of the HDF file
rank
IN:
Number of dimensions in the data array to be written
dimsizes
IN:
Array containing the size of each dimension
data
IN:
Array containing the data to be stored

Purpose
Appends a scientific dataset in its entirety to an existing HDF file if the file exists. If not, a new file is created.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
In addition to appending a multidimensional array of data to an HDF file, DFSDadddata automatically stores any information pertinent to the dataset. It will not overwrite existing data in the file. The array data can be of any valid type. However, if no data type has been set by DFSDsetNT, it is assumed that the data is of type float32.
 
Calling DFSDadddata will write the scientific dataset and all associated information. That is, when DFSDadddata is called, any information set by a DFSDset* call is written to the file, along with the data array itself.

FORTRAN
integer function dsadata(filename, rank, dimsizes, data)
 
character*(*) filename
 
integer rank
 
integer dimsizes(*), data(*)

[DFSD Interface][Top]


DFSDclear/dsclear

intn DFSDclear( )

Purpose
Clears all values set by DFSDset* routines.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
After a call to DFSDclear, values set by any DFSDset* call will not be written unless they have been set again.

FORTRAN
integer function dsclear( )

[DFSD Interface][Top]


DFSDendslab/dseslab

intn DFSDendslab( )

Purpose
Terminates a sequence of slab calls started by DFSDstartslab by closing the file.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.

FORTRAN
integer function dseslab( )

[DFSD Interface][Top]


DFSDendslice/dseslc

intn DFSDendslice( )

Purpose
Terminates the write operation after storing a slice of data in a scientific dataset.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
DFSDendslice must be called after all the slices are written. It checks to ensure that the entire dataset has been written, and if it has not, returns an error code. DFSDendslice is obsolete in favor of DFSDendslab. DFSDendslab is the recommended function call to use when terminating hyperslab (previously known as data slices) operations. HDF will continue to support DFSDendslice only to maintain backward compatibility with earlier versions of the library.

FORTRAN
integer function dseslc( )

[DFSD Interface][Top]


DFSDgetcal/dsgcal

int32 DFSDgetcal(float64 *cal, float64 *cal_err, float64 *offset, float64 *offset_err, int32 *data_type)

cal
OUT:
Calibration factor
cal_err
OUT:
Calibration error
offset
OUT:
Uncalibrated offset
offset_err
OUT:
Uncalibrated offset error
data_type
OUT:
Data type of uncalibrated data

Purpose
Retrieves the calibration record, if there is one, attached to a scientific dataset.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
A calibration record contains four 64-bit floating point values followed by a 32-bit integer.
 
The relationship between a value iy stored in a dataset and the actual value y is defined as:
 
y = cal * (iy - offset)
 
The variable offset_err contains a potential error of offset, and cal_err contains a potential error of cal. Currently the calibration record is provided for information only. The SD interface performs no operations on the data based on the calibration tag.
 
As an example, suppose the values in the calibrated dataset iy[] are the following integers:
 
iy[6] = {2, 4, 5, 11, 26, 81}
 
By defining cal = 0.50 and offset = -200.0 and applying the calibration formula, the calibrated dataset iy[] returns to its original form as a floating point array:
 
y[6] = {1001.0, 1002.0, 1002.5, 1005.5, 1013.0,1040.5}

FORTRAN
integer function dsgcal(cal, cal_err, offset, offset_err, data_type)
 
real cal, cal_err, offset, offset_err
 
integer data_type

[DFSD Interface][Top]


DFSDgetdata/dsgdata

intn DFSDgetdata(char *filename, intn rank, int32 dimsizes[], VOIDP data)

filename
IN:
Name of the file
rank
IN:
Number of dimensions
dimsizes
IN:
Dimensions of the data buffer
data
OUT:
Buffer for the data

Purpose
Reads the next dataset in the file.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
If the values of rank or dimsizes aren't known, DFSDgetdims must be called to retrieve them and then use them to determine the buffer space needed for the array data. If the data type of the data in a scientific dataset isn't know, DFSDgetNT must be called to retrieve it. Subsequent calls to DFSDgetdata (or to DFSDgetdims and DFSDgetdata)will sequentially read scientific datasets from the file. For example, if DFSDgetdata is called three times in succession, the third call reads data from the third scientific dataset in the file.
 
If DFSDgetdims or DFSDgetdata is called and there are no more scientific datasets left in the file, an error code is returned and nothing is read. DFSDrestart can be used to override this convention.

FORTRAN
integer function dsgdata(filename, rank, dimsizes, data)
 
character*(*) filename
 
integer rank
 
integer dimsizes(*), data(*)

[DFSD Interface][Top]


DFSDgetdatalen/dsgdaln

intn DFSDgetdatalen(intn *label_len, intn *unit_len, intn *format_len, intn *coords_len)

label_len
OUT:
Maximum length of the label string
unit_len
OUT:
Maximum length of the unit string
format_len
OUT:
Maximum length of the format string
coords_len
OUT:
Maximum length of the coordinate system string

Purpose
Retrieves the lengths of the label, unit, format, and coordinate system strings.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
The space allocated for the label, unit, format, and coordinate system strings must be at least one byte larger than the actual length of the string to account for the null termination.

FORTRAN
integer function dsgdaln(label_len, unit_len, format_len, coords_len)
 
integer label_len, unit_len, format_len, coords_len

[DFSD Interface][Top]


DFSDgetdatastrs/dsgdast

intn DFSDgetdatastrs(char *label, char *unit, char *format, char *coordsys)

label
OUT:
Label describing the data
unit
OUT:
Unit to be used with the data
format
OUT:
Format to be used in displaying data
coordsys
OUT:
Coordinate system

Purpose
Retrieves information about the label, unit, and format attribute strings associated with the data.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
The parameter coordsys gives the coordinate system that is to be used for interpreting the dimension information.

FORTRAN
integer function dsgdast(label, unit, format, coordsys)
 
character*(*) label, unit, format, coordsys

[DFSD Interface][Top]


DFSDgetdimlen/dsgdiln

intn DFSDgetdimlen (intn dim, intn *label_len, intn *unit_len, intn *format_len)

dim
IN:
Dimension the label, unit, and format refer to
label_len
OUT:
Length of the label
unit_len
OUT:
Length of the unit
format_len
OUT:
Length of the format

Purpose
Retrieves the length of the label, unit, and format attribute strings associated with the specified dimension.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
The space allocated to hold the label, unit, and format strings must be at least one byte larger than the actual length of the string, to account for the null termination.

FORTRAN
integer function dsgdiln(dim, label_len, unit_len, format_len)
 
integer dim, label_len, unit_len, format_len

[DFSD Interface][Top]


DFSDgetdims/dsgdims

intn DFSDgetdims(char *filename, intn *rank, int32 dimsizes[], intn maxrank)

filename
IN:
Name of the HDF file
rank
OUT:
Number of dimensions
dimsizes
OUT:
Buffer for the returned dimensions
maxrank
IN:
Size of the storage buffer dimsizes

Purpose
Retrieves the number of dimensions (rank) of the dataset and the sizes of the dimensions (dimsizes) for the next scientific dataset in the file.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
The maxrank parameter tells DFSDgetdims the size of the array that is allocated for storing the dimsizes array. The value of rank must not exceed the value of maxrank.
 
The allocation of a buffer for the scientific dataset data should correspond to the values retrieved by DFSDgetdims. The first value in the array dimsizes should equal the first dimension of the array that is allocated to hold the dataset; the second value in dimsizes should equal the second dimension of the dataset, and so forth.

FORTRAN
integer function dsgdims(filename, rank, dimsizes, maxrank)
 
character*(*) filename
 
integer rank, maxrank
 
integer dimsizes(*)

[DFSD Interface][Top]


DFSDgetdimscale/dsgdisc

intn DFSDgetdimscale(intn dim, int32 size, VOIDP scale)

dim
IN:
Dimension this scale corresponds to
size
IN:
Size of the scale buffer
scale
OUT:
Array of values defining reference points along a specified dimension

Purpose
Gets the scale corresponding to the specified dimension.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
The DFSD interface requires the dimension scales to be of the same data type as the corresponding data. To store dimension scales of a different data type than the corresponding data, use the multifile SD interface.

FORTRAN
integer function dsgdisc(dim, size, scale)
 
integer dim, size
 
integer scale(*)

[DFSD Interface][Top]


DFSDgetdimstrs/dsgdist

intn DFSDgetdimstrs(intn dim, char *label, char *unit, char *format)

dim
IN:
Dimension this label, unit and format refer to
label
OUT:
Label that describes this dimension
unit
OUT:
Unit to be used with this dimension
format
OUT:
Format to be used in displaying scale for this dimension

Purpose
Retrieves the label, unit, and format attribute strings corresponding to the specified dimension.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
The space allocated for the label, unit, and format string must be at least one byte larger than the length of the string to accommodate the null termination. If the length is unknown when the program is written, declare the array size as 1+maxlen_label, maxlen_unit, or maxlen_format after they are set by DFSDsetlengths. The maximum default string length is 255.

FORTRAN
integer function dsgdist(dim, label, unit, format)
 
integer dim
 
character*(*) label, unit, format

[DFSD Interface][Top]


DFSDgetfillvalue/dsgfill

intn DFSDgetfillvalue(VOIDP fill_value)

fill_value
OUT:
Fill value

Purpose
Retrieves the fill value of a DFSD scientific dataset.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
The fill value is set by DFSDsetfillvalue and returned in the variable fill_value. Note that DFSDgetfillvalue does not take a file name as an argument. As a result, a DFSD call to initialize the file information structures is required before calling DFSDgetfillvalue. One such call is DFSDgetdims.

FORTRAN
integer function dsgfill(fill_value)
 
character*(*) fill_value

[DFSD Interface][Top]


DFSDgetNT/dsgnt

intn DFSDgetNT(int32 *data_type)

data_type
OUT:
Data type of data in the scientific dataset

Purpose
Retrieves the data type of the next dataset to be read.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
Note that DFSDgetNT does not take a file name as an argument. As a result, a DFSD call to initialize the file information structures is required before calling DFSDgetNT. One such call is DFSDgetdims.
 
Valid values for data_type are of the general form DFNT_. The following are valid symbolic names and their data types:

32-bit float
DFNT_FLOAT32
5
64-bit float
DFNT_FLOAT64
6
8-bit signed int
DFNT_INT8
20
8-bit unsigned int
DFNT_UINT8
21
16-bit signed int
DFNT_INT16
22
16-bit unsigned int
DFNT_UINT16
23
32-bit signed int
DFNT_INT32
24
32-bit unsigned int
DFNT_UINT32
25
8-bit character
DFNT_CHAR8
4

FORTRAN
integer function dsgnt(num_type)
 
integer num_type

[DFSD Interface][Top]


DFSDgetrange/dsgrang

intn DFSDgetrange(VOIDP max, VOIDP min)

max
OUT:
Maximum value stored with the scientific dataset
min
OUT:
Maximum value stored with the scientific dataset

Purpose
Retrieves the maximum and minimum values stored with the scientific dataset.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
The max and min values are set via a call to DFSDsetrange. They are not automatically stored when a dataset is written to a file. The data type of these values is the data type of the dataset array. One implication of this is that in the C version of DFSDgetrange the arguments are pointers, rather than simple variables, whereas in the FORTRAN-77 version they are simple variables of the same type as the data array.
 
Neither DFSDgetrange nor DFSDgetdata compare the max and min values stored with the dataset to the actual values in the dataset; they merely retrieve the data. As a result, the maximum and minimum values may not always reflect the actual maximum and minimum values in the dataset. In some cases the max and min values may actually lie outside the range of values in the dataset.

FORTRAN
integer function dsgrang(max, min)
 
character*(*) max, min

[DFSD Interface][Top]


DFSDgetslice/dsgslc

intn DFSDgetslice(char *filename, int32 winst[], int32 windims[], VOIDP data, int32 dims[])

filename
IN:
Name of HDF file
winst
IN:
Array containing the coordinates for the start of the slice
windim
IN:
Array containing the dimensions of the slice
data
OUT:
Array for returning slice
dims
OUT:
Dimensions of array data

Purpose
Reads part of a scientific dataset from a file.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
DFSDgetslice accesses the dataset last accessed by DFSDgetdims. If DFSDgetdims has not been called for the named file, DFSDgetslice gets a slice from the next dataset in the file. Array winst specifies the coordinates of the start of the slice. Array windims gives the size of the slice. The number of elements in winst and windims must be equal to the rank of the dataset. For example, if the file contains a three-dimensional dataset, winst may contain the values {2, 4, 3}, while windims contains the values {3, 1, 4} and the dims should be at least {3, 1, 4}, the same size as the slice. This will extract a 3 x 4, two-dimensional slice, containing the elements between (2, 4, 3) and (4, 4, 6) from the original dataset.
 
The data array is the array into which the slice is read. It must be at least as big as the desired slice. The dims array is the array containing the actual dimensions of the array data. The user assigns values to dims before calling DFSDgetslice.
 
All parameters assume FORTRAN-77-style one-based arrays.
 
DFSDgetslice is obsolete in favor of DFSDreadslab. DFSDreadslab is the recommended function call to use when reading hyperslabs (previously known as data slices). HDF will continue to support DFSDgetslice only to maintain backward compatibility with HDF applications built on earlier versions of the library.

FORTRAN
integer function dsgslc(filename, winst, windims, data, dims)
 
character*(*) filename, data
 
integer winst(*), windims(*), dims(*)

[DFSD Interface][Top]


DFSDlastref/dslref

intn DFSDlastref( )

Purpose
Retrieves the most recent reference number used in writing or reading a scientific dataset.
Return value
Returns the reference number for the last accessed scientific dataset if successful and FAIL (or -1) otherwise.
Description
DFSDlastref returns the value of the last reference number of a scientific dataset read from or written to the file.

FORTRAN
integer function dslref( )

[DFSD Interface][Top]


DFSDndatasets/dsnum

intn DFSDndatasets(char *filename)

filename
IN:
Name of the HDF file

Purpose
Returns the number of scientific datasets in the file.
Return value
Returns the number of datasets if successful and FAIL (or -1) otherwise.
Description
In HDF version 3.3, DFSDndatasets replaced DFSDnumber. In order to maintain backward compatibility with existing HDF applications, HDF will continue to support DFSDnumber. However, it is recommended that all new applications use DFSDndatasets instead of DFSDnumber.

FORTRAN
integer function dsnum(filename)
 
character*(*) filename

[DFSD Interface][Top]


DFSDpre32sdg/dsp32sd

intn DFSDpre32sdg(char *filename, uint16 ref, intn *ispre32)

filename
IN:
The name of the HDF file containing the scientific dataset
ref
IN:
Reference number of SDG
ispre32
OUT:
Pointer to results of the pre-HDF version 3.2 inquiry

Purpose
Tests if the scientific dataset with the specified reference number was created by an HDF library earlier than version 3.2.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
If the scientific dataset was created with a version of HDF prior to version 3.2, ispre32 will be set to 1, otherwise it will be set to 0. Based on this information, programmers can decide whether or not to transpose the corresponding array.

FORTRAN
integer function dsp32sd(filename, ref, ispre32)
 
character*(*) filename
 
integer ref, ispre32

[DFSD Interface][Top]


DFSDputdata/dspdata

intn DFSDputdata(char *filename, intn rank, int32 dimsizes[], VOIDP data)

filename
IN:
Name of the HDF file
rank
IN:
Number of dimensions of data array to be stored
dimsizes
IN:
Buffer for the dimension sizes
data
IN:
Buffer for the data to be stored

Purpose
Writes a scientific data and related information to an HDF file.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
DFSDputdata will write data to an existing file by destroying the contents of the original file. Use it with caution. If a new filename is used, DFSDputdata functions exactly like DFSDadddata.

FORTRAN
integer function dspdata(filename, rank, dimsizes, data)
 
character*(*) filename
 
<valid numeric data type> data
 
integer rank
 
integer dimsizes(*)

[DFSD Interface][Top]


DFSDputslice/dspslc

intn DFSDputslice(int32 windims[], VOIDP source, int32 dims[])

windims
IN:
Window dimensions specifying the size of the slice to be written
source
IN:
Buffer for the slice
dims
IN:
Dimensions of the source array

Purpose
Writes part of a scientific dataset to a file.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
DFSDputslice read a subset of an array in memory and stores it as part of the scientific dataset array last specified by DFSDsetdims. Slices must be stored contiguously.
 
Array windims ("window dimensions") specifies the size of the slice to be written. The windims array must contain as many elements as there are dimensions in the entire scientific dataset array. The source argument is an array in memory containing the slice and dims is an array containing the dimensions of the array source.
 
Notice that windims and dims need not be the same. The windims argument could refer to a sub-array of source, in which case only a portion of source is written to the scientific data array.
 
All parameters assume FORTRAN-77-style one-based arrays.
 
DFSDputslice is obsolete in favor of DFSDwriteslab. DFSDwriteslab is the recommended function call to use when writing hyperslabs (previously known as data slices). HDF will continue to support DFSDputslice only to maintain backward compatibility with earlier versions of the library.

[DFSD Interface][Top]


DFSDreadref/dsrref

intn DFSDreadref(char *filename, uint16 ref)

filename
IN:
Name of the HDF file
ref
IN:
Reference number for next DFSDgetdata call

Purpose
Specifies the reference number for the dataset to be read during the next read operation.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
This routine is commonly used in conjunction with DFANgetlablist, which returns a list of labels for a given tag together with their reference numbers. It provides a sort of random access to scientific datasets.
 
There is no guarantee that reference numbers appear in sequence in an HDF file, so it is not generally safe to assume that a reference number is an index number of a scientific dataset.

FORTRAN
integer function dsrref(filename, ref)
 
character*(*) filename
 
integer ref

[DFSD Interface][Top]


DFSDreadslab/dsrslab

intn DFSDreadslab(char *filename, int32 start[], int32 slab_size[], int32 stride[], VOIDP buffer, int32 buffer_size[])

filename
IN:
Name of the HDF file
start
IN:
Buffer of size rank containing the coordinates for the start of the slab
slab_size
IN:
Buffer of size rank containing the size of each dimension in the slab
stride
IN:
Subsampling (not yet implemented)
buffer
OUT:
\Buffer for the returned slab
buffer_size
OUT:
Dimensions of the buffer parameter

Purpose
Reads a slab of data from any scientific dataset.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
DFSDreadslab will access to the scientific dataset following the current one if DFSDgetdims or DFSDgetdata are not called earlier. The start array indices are one-based. The rank of start must be the same as the number of dimensions of the specified variable. The elements of slab_size must be no larger than the dimensions of the scientific dataset in order. The stride feature is not currently implemented. For now just pass the start array as the argument for stride where it will be ignored.
 
To extract a slab of lower dimension than that of the dataset, enter 1 in the slab_size array for each omitted dimension. For example, to extract a two-dimensional slab from a three-dimensional dataset, specify the beginning coordinates in three dimensions and enter a 1 for the missing dimension in the slab_size array. More specifically, to extract a 3 x 4 slab containing the elements (6, 7, 8) through (8, 7, 11) specify the beginning coordinates as {6, 7, 8} and the slab size as {3, 1, 4}.

FORTRAN
integer function dsrslab(filename, start, slab_size, stride, buffer, buffersize)
 
character*(*) filename, buffer
 
integer start(*), slab_size(*),
 
integer stride(*), buffer_size(*)

[DFSD Interface][Top]


DFSDrestart/dsfirst

intn DFSDrestart( )

Purpose
Causes the next read command to be read from the first scientific dataset in the file, rather than the scientific dataset following the one that was most recently read.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.

FORTRAN
integer function dsfirst( )

[DFSD Interface][Top]


DFSDsetcal/dsscal

intn DFSDsetcal(float64 cal, float64 cal_err, float64 offset, float64 offset_err, int32 data_type)

cal
IN:
Calibration factor
cal_err
IN:
Calibration error
offset
IN:
Uncalibrated offset
offset_err
IN:
Uncalibrated offset error
data_type
IN:
Data type of uncalibrated data

Purpose
Sets the calibration information associated with data
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
This routine sets the calibration record associated with a dataset. A calibration record contains four 64-bit floating point values followed by a 32-bit integer, to be interpreted as follows:
 
cal calibration factor
cal_err calibration error
offset uncalibrated offset
offset_err uncalibrated offset error
data_type data type of uncalibrated data

 
The relationship between a value iy stored in a dataset and the actual value y is defined as:
 
y = cal * (iy - offset)

 
The variable offset_err contains a potential error of offset, and cal_err contains a potential error of cal. Currently the calibration record is provided for information only. The SD interface performs no operations on the data based on the calibration tag.
 
DFSDsetcal works like other DFSDset* routines, with one exception: the calibration information is automatically cleared after a call to DFSDputdata or DFSDadddata. Hence, DFSDsetcal must be called again for each dataset that is to be written.
 
As an example, suppose the values in a dataset y[] are as follows:
 
y[6]={1001.0, 1002.0, 1002.5, 1005.5, 1013.0, 1040.5}

 
By defining cal = 0.50 and offset = -200.0 and applying the calibration formula, the calibrated dataset iy[] becomes as follows:
 
iy[6]={2, 4, 5, 11, 26, 81}

 
The array iy[] can then be stored as integers.

FORTRAN
integer function dsscal(cal, cal_err, offset, offset_err, data_type)
 
real*8 cal, cal_err, offset, offset_err
 
integer data_type

[DFSD Interface][Top]


DFSDsetdatastrs/dssdast

intn DFSDsetdatastrs(char *label, char *unit, char *format, char *coordsys)

label
IN:
Label describing the data
unit
IN:
Unit to be used with the data
format
IN:
Format to be used in displaying the data
coordsys
IN:
Coordinate system of the data

Purpose
Sets the label, unit, format, and coordinate system for the next dataset written to file.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.

FORTRAN
integer function dssdast(label, unit, format, coordsys)
 
character*(*) label, unit, format, coordsys

[DFSD Interface][Top]


DFSDsetdims/dssdims

intn DFSDsetdims (intn rank, int32 dimsizes[])

rank
IN:
Number of dimensions
dimsizes
IN:
Dimensions of the scientific dataset

Purpose
Sets the rank and dimension sizes for all subsequent scientific datasets written to the file.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
This routine must be called before calling either DFSDsetdimstrs or DFSDsetdimscale. DFSDsetdims need not be called if other set routines are not called and the correct dimensions are supplied in DFSDputdata or DFSDadddata.
 
If the rank or dimension sizes change, all previous set calls are cleared, except for the data type, which is set by calling DFSDsetNT.

FORTRAN
integer function dssdims(rank, dimsizes)
 
integer rank
 
integer dimsizes(*)

[DFSD Interface][Top]


DFSDsetdimscale/dssdisc

intn DFSDsetdimscale (intn dim, int32 dimsize, VOIDP scale)

dim
IN:
Dimension this scale corresponds to
dimsize
IN:
Size of the scale buffer
scale
IN:
Buffer for the scale values

Purpose
Defines the scale for a dimension.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
A scale is a one-dimensional array whose values describe reference points along one dimension of the dataset. For example, a two-dimensional dataset representing points on a map could have two scales, one representing points of latitude, and the other points of longitude.

FORTRAN
integer function dssdisc (dim, dimsize, scale)
 
integer dim
 
integer dimsize(*), scale(*)

[DFSD Interface][Top]


DFSDsetdimstrs/dssdist

intn DFSDsetdimstrs(intn dim, char *label, char *unit, char *format)

dim
IN:
Dimension this label, unit and format refer to
label
IN:
Label that describes this dimension
unit
IN:
Unit to be used with this dimension
format
IN:
Format to be used to display scale

Purpose
Sets the label, unit, and format strings corresponding to the specified dimension.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
In both FORTRAN-77 and C programs, dim = 1 for the first dimension, and dim = 2 for the second dimension. If the user is not interested in one or more strings, empty strings can be used as parameters for the DFSDsetdimstrs call. For example, DFSDsetdimstrs(1, "vertical", " ", " ") will set the label for the first dimension to "vertical" and set the unit and format to empty strings.

FORTRAN
integer function dssdist(dim, label, unit, format)
 
integer dim
 
character*(*) label, unit, format

[DFSD Interface][Top]


DFSDsetfillvalue/dssfill

intn DFSDsetfillvalue(VOIDP fill_value)

fill_value
IN:
Fill value

Purpose
Set the value used to fill in any unwritten location in a scientific dataset.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
It is assumed that the fill value has the same data type as the dataset. Once the fill value is set for a particular SDS, it cannot be changed.
 
If DFSDsetfillvalue is called before the first call to DFSDstartslab, DFSDstartslab will set the fill value tag attribute to the value specified in the DFSDsetfillvalue call, but will not actually write out the fill value when DFSDwriteslab is called. However, if DFSDsetfillvalue is called after the first call the DFSDstartslab, the fill value tag attribute will be set by DFSDsetfillvalue and the fill value will be written to the slab during the DFSDwriteslab call.

FORTRAN
integer function dssfill(fill_value)
 
character*(*) fill_value

[DFSD Interface][Top]


DFSDsetlengths/dsslens

intn DFSDsetlengths(intn label_len, intn unit_len, intn format_len, intn coords_len)

label_len
IN:
Maximum length of label strings
unit_len
IN:
Maximum length of unit strings
format_len
IN:
Maximum length of format strings
coords_len
IN:
Maximum length of coordinate system strings

Purpose
Sets the maximum lengths for the strings that will hold labels, units, formats, and the name of the coordinate system.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
The lengths set by this routine are used by the routines DFSDgetdimstrs and DFSDgetdatastrs to determine the maximum lengths of strings that they get from the file.
 
Normally, DFSDsetlengths is not needed. If it is not called, default maximum lengths of 255 are used for all strings.

FORTRAN
integer function dsslens(label_len, unit_len, format_len, coords_len)
 
integer label_len, unit_len, format_len, coords_len

[DFSD Interface][Top]


DFSDsetNT/dssnt

intn DFSDsetNT(int32 data_type)

data_type
IN:
Data type

Purpose
Sets the data type of the data to be written in the next write operation.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
DFSDsetNT must be called if a data type other than float32 is to be stored. DFSDsetNT and DFSDsetdims can be called in any order, but they should be called before any other DFSDset* functions and before DFSDputdata or DFSDadddata.
 
The following symbolic names can be used as the value of data_type:

32-bit float
DFNT_FLOAT32
5
64-bit float
DFNT_FLOAT64
6
8-bit signed int
DFNT_INT8
20
8-bit unsigned int
DFNT_UINT8
21
16-bit signed int
DFNT_INT16
22
16-bit unsigned int
DFNT_UINT16
23
32-bit signed int
DFNT_INT32
24
32-bit unsigned int
DFNT_UINT32
25
8-bit character
DFNT_CHAR8
4

FORTRAN
integer function dssnt(num_type)
 
integer num_type

[DFSD Interface][Top]


DFSDsetrange/dssrang

intn DFSDsetrange(VOIDP max, VOIDP min)

max
IN:
Highest value in the range
min
IN:
Lowest value in the range

Purpose
Stores the specified maximum and minimum data values.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
It is assumed that the data type of max and min is the same as the type of the data. One implication of this is that in the C version of DFSDsetrange the arguments are pointers, rather than simple variables, whereas in the FORTRAN-77 version they are simple variables of the same type as the data array.
 
This routine does not compute the maximum and minimum values; it merely stores the values it is given. As a result, the maximum and minimum values may not always reflect the actual maximum and minimum values in the data array.
 
When the maximum and minimum values are written to a file, the HDF element that holds these values is cleared, because it is assumed that subsequent datasets will have different values for max and min.

FORTRAN
integer function dssrang(max, min)
 
character*(*) max, min

[DFSD Interface][Top]


DFSDstartslab/dssslab

intn DFSDstartslab(char *filename)

filename
IN:
Name of the HDF file

Purpose
Prepares the DFSD interface to write a slab of data to a scientific dataset.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
DFSDsetdims must be called before calling DFSDstartslab. No call which involves a file open may be made after a DFSDstartslab call until DFSDendslab is called. This routine will write out the fill values if DFSDsetfillvalue is called before this routine.

FORTRAN
integer function dssslab(filename)
 
character*(*) filename

[DFSD Interface][Top]


DFSDstartslice/dssslc

intn DFSDstartslice(char *filename)

filename
IN:
Name of the HDF file

Purpose
Prepares the interface to write a data slice to the specified file.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
Before calling DFSDstartslice, DFSDsetdims must be called to specify the dimensions of the dataset to be written to the file. DFSDstartslice always appends a new dataset to an existing file.
 
Also, DFSDstartslice must be called before DFSDputslice or DFSDendslice.
 
DFSDstartslice is obsolete in favor of DFSDstartslab. DFSDstartslab is the recommended function call to use when beginning hyperslab operations. HDF will continue to support DFSDstartslice only to maintain backward compatibility earlier versions of the library.

FORTRAN
integer function dssslc(filename)
 
character*(*) filename

[DFSD Interface][Top]


DFSDwriteref/dswref

intn DFSDwriteref(char *filename, uint16 ref)

filename
IN:
Name of the HDF file
ref
IN:
Reference number for next add or put operation

Purpose
Specifies the reference number, ref, of the dataset to be overwritten next by DFSDputdata or DFSDadddata.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
DFSDwriteref verifies the refence number's existence before returning. If a non-existent reference number is specified, an error code will be returned.
 
As this routine alters data in a destructive manner, DFSDwriteref should be used with caution.

FORTRAN
integer function dswref(filename, ref)
 
character*(*) filename
 
integer ref

[DFSD Interface][Top]


DFSDwriteslab/dswslab

intn DFSDwriteslab(int32 start[], int32 stride[], int32 count[], VOIDP data)

start
IN:
Array containing the starting coordinates of the slab
stride
IN:
Array containing the dimensions for subsampling
count
IN:
Array containing the size of the slab
data
IN:
Array to hold the floating point data to be written

Purpose
Writes a slab of data to a scientific dataset.
Return value
Returns SUCCEED (or 0) if successful and FAIL (or -1) otherwise.
Description
The start indices are relative to 1. The rank of start must be the same as the number of dimensions of the specified variable. The elements of start must be no larger than the scientific dataset's dimensions in order. The stride feature is not currently implemented. For now just pass the start array as the argument for the stride parameter, where it will be ignored.
 
The rank of count must be the same as the number of dimensions of the specified variable. The elements of count must be no larger than the scientific dataset's dimensions in order. The order in which the data will be written into the specified hyperslab is with the last dimension varying fastest. The data should be of the appropriate type for the dataset. Note that neither the compiler nor HDF software can detect if the wrong type of data is used.

FORTRAN
integer function dswslab(start, stride, count, data)
 
integer start(*), stride(*), count(*)
 
character*(*) data


HDF4.2r4 - February 2009
Copyright
The HDF Group
www.hdfgroup.org
The HDF Group