[SD Interface][Top]
SDattrinfo/sfgainfo
intn SDattrinfo(int32 obj_id, int32 attr_index, char *attr_name, int32 *data_type, int32 *count)
|
obj_id
|
IN:
|
Identifier of the object to which the attribute is attached to
|
|
attr_index
|
IN:
|
Index of the attribute
|
|
attr_name
|
OUT:
|
Name of the attribute
|
|
data_type
|
OUT:
|
Data type of the attribute values
|
|
count
|
OUT:
|
Total number of values in the attribute
|
|
Purpose
|
Retrieves information about an attribute.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDattrinfo retrieves the name, data type, and number of values of the attribute specified by its index, attr_index, and stores them in the parameters attr_name, data_type, and count, respectively. This routine should be used before reading the values of an attribute with SDreadattr.
|
|
|
The parameter obj_id can be either an SD interface identifier (sd_id), returned by SDstart, a data set identifier (sds_id), returned by SDselect, or a dimension identifier (dim_id), returned by SDgetdimid.
|
|
|
Valid values of the parameter attr_index range from 0 to the number of attributes attached to the object - 1.
|
|
|
Valid values of the parameter data_type can be found in Table 1A of Section I of this manual.
|
|
FORTRAN
|
integer function sfgainfo(obj_id, attr_index, attr_name, data_type, count)
|
|
|
character*(*) attr_name
|
|
|
integer obj_id, attr_index, data_type, count
|
[SD Interface][Top]
SDcheckempty/sfchempty
int32 SDcheckempty( int32 sds_id, intn *emptySDS )
|
sds_id
|
IN:
|
SDS identifier
|
|
emptySDS
|
OUT:
|
Boolean value indicating whether the SDS is empty
|
|
Purpose
|
Determines whether a scientific dataset (an SDS) is empty.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDcheckempty sets the parameter emptySDS to TRUE if the dataset identified by sds_id has not been written with data, and to FALSE , otherwise.
|
|
|
The Fortran routine, sfchempty, returns 1 in emptySDS if the dataset is empty and 0 otherwise.
|
|
FORTRAN
|
integer function sfchempty(sds_id, emptySDS)
|
|
|
integer sds_id, emptySDS
|
[SD Interface][Top]
SDcreate/sfcreate
int32 SDcreate(int32 sd_id, char *name, int32 data_type, int32 rank, int32 dimsizes[])
|
sd_id
|
IN:
|
SD interface identifier returned by SDstart
|
|
name
|
IN:
|
Name of the data set
|
|
data_type
|
IN:
|
Data type for the values in the data set
|
|
rank
|
IN:
|
Number of the data set dimensions
|
|
dimsizes
|
IN:
|
Array containing the size of each dimension
|
|
Purpose
|
Creates a new data set.
|
|
Return value
|
Returns the data set identifier (sds_id) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDcreate creates a data set with the name specified by the parameter name, the values of the data type specified by parameter data_type, the number of dimensions specified by the parameter rank, and the dimension sizes specified by the array dimsizes.
|
|
|
Once a data set has been created, it is not possible to change its name, data type, or rank. However, it is possible to create a data set and close the file before writing any data values to it. The values can be added or modified at a future time. To add data or modify an existing data set, use SDselect to get the data set identifier instead of SDcreate.
|
|
|
If the parameter name is NULL in C or an empty string in Fortran, the default name "Data Set" will be generated. The length of the name specified by the name parameter is no longer limited to 64 characters starting in HDF 4.2r2. Note that when an older version of the library reads a data set, which was created by a library of version 4.2r2 or later and has the name that is longer than 64 characters, the retrieved name will contain some garbage after 64 characters.
|
|
|
The calling program must ensure that the length of the dimsizes array is the value of the rank parameter, which is between 0 and MAX_VAR_DIMS (or 32 ). Note that, in order for HDF4 and NetCDF models to work together, HDF allows SDS to have rank 0. However, there is no intention for data to be written to this type of SDS, but only to store attribute as part of the data description. Consequently, setting compression and setting chunk are disallowed.
|
|
|
To create a data set with an unlimited dimension, assign the value of SD_UNLIMITED (or 0 ) to dimsizes[0] in C and to dimsizes(rank) in Fortran.
|
|
|
The data_type parameter can contain any data type supported by the HDF library. These data types are listed in Table 1A in Section I of this manual.
|
|
|
See the notes regarding the potential performance impact of unlimited dimension data sets in Section 14.4.3, "Unlimited Dimension Data Sets (SDSs and Vdatas) and Performance." the HDF User's Guide.
|
|
Note
|
Regarding an important difference between the SD and GR interfaces: The SD and GR interfaces differ in the correspondence between the dimension order in parameter arrays such as start, stride, edge, and dimsizes and the dimension order in the data array. See the SDreaddata and GRreadimage reference manual pages for discussions of the SD and GR approaches, respectively.
|
|
|
When writing applications or tools to manipulate both images and two-dimensional SDs, this crucial difference between the interfaces must be taken into account. While the underlying data is stored in row-major order in both cases, the API parameters are not expressed in the same way. Consider the example of an SD data set and GR image that are stored as identically-shaped arrays of X columns by Y rows and accessed via the SDreaddata and GRreadimage functions, respectively. Both functions take the parameters start, stride, and edge.
o For SDreaddata, those parameters are expressed in (y,x) or [row,column] order. For example, start[0] is the starting point in the Y dimension and start[1] is the starting point in the X dimension. The same ordering holds true for all SD data set manipulation functions.
o For GRreadimage, those parameters are expressed in (x,y) or [column,row] order. For example, start[0] is the starting point in the X dimension and start[1] is the starting point in the Y dimension. The same ordering holds true for all GR functions manipulating image data.
|
|
FORTRAN
|
integer function sfcreate(sd_id, name, data_type, rank, dimsizes)
|
|
|
character*(*) name
|
|
|
integer sd_id, data_type, rank, dimsizes(*)
|
[SD Interface][Top]
SDdiminfo/sfgdinfo
intn SDdiminfo(int32 dim_id, char *name, int32 *size, int32 *data_type, int32 *num_attrs)
|
dim_id
|
IN:
|
Dimension identifier returned by SDgetdimid
|
|
name
|
OUT:
|
Name of the dimension
|
|
size
|
OUT:
|
Size of the dimension
|
|
data_type
|
OUT:
|
Data type of the dimension scale
|
|
num_attrs
|
OUT:
|
Number of attributes assigned to the dimension
|
|
Purpose
|
Retrieves information about a dimension.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDdiminfo retrieves the name, size, data type, and number of values of the dimension specified by the parameter dim_id, and stores them in the parameters name, size, data_type, and num_attrs, respectively.
|
|
|
If the output value of the parameter size is set to 0 , then the dimension specified by the dim_id parameter is unlimited. To get the number of records of an unlimited dimension, use SDgetinfo.
|
|
|
If scale information has been stored for this dimension via SDsetdimscale, the data_type parameter will contain the data type. Valid data types can be found in Table 1A of Section I of this manual. If no scale information has been stored for this dimension, the value returned in the data_type parameter will be 0 .
|
|
|
If the user has not named the dimension via SDsetdimname, a default dimension name of "fakeDim[x] " will be generated by the library, where [x] denotes the dimension index. If the name is not desired, the parameter name can be set to NULL in C and an empty string in Fortran.
|
|
FORTRAN
|
integer function sfgdinfo(dim_id, name, size, data_type, num_attrs)
|
|
|
character*(*) name
|
|
|
integer dim_id, size, data_type, num_attrs
|
[SD Interface][Top]
SDend/sfend
intn SDend(int32 sd_id)
|
sd_id
|
IN:
|
SD interface identifier returned by SDstart
|
|
Purpose
|
Terminates access to an SD interface.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDend closes the file and frees memory allocated by the library when SD interface activities are completed. If the calling program exits without invoking this routine, recent changes made to the in-core file data are likely not to be flushed to the file. Note that each SDstart must have a matching SDend.
|
|
FORTRAN
|
integer function sfend(sd_id)
|
|
|
integer sd_id
|
[SD Interface][Top]
SDendaccess/sfendacc
intn SDendaccess(int32 sds_id)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
Purpose
|
Terminates access to a data set.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDendaccess frees the memory taken up by the HDF library's data structures devoted to the data set identified by the parameter sds_id.
|
|
|
Failing to call this routine after all operations on the specified data set are complete may result in loss of data. This routine must be called once for each call to SDcreate or SDselect.
|
|
FORTRAN
|
integer function sfendacc(sds_id)
|
|
|
integer sds_id
|
[SD Interface][Top]
SDfileinfo/sffinfo
intn SDfileinfo(int32 sd_id, int32 *num_datasets, int32 *num_global_attrs)
|
sd_id
|
IN:
|
SD interface identifier returned by SDstart
|
|
num_datasets
|
OUT:
|
Number of data sets in the file
|
|
num_global_attrs
|
OUT:
|
Number of global attributes in the file
|
|
Purpose
|
Retrieves the number of data sets and the number of global attributes in a file.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDfileinfo returns the number of data sets in the parameter num_datasets and the number of global attributes in the parameter num_global_attrs. The term "global attributes" refers to attributes that are assigned to the file. The global attributes are created by SDsetattr using an SD interface identifier (sd_id) rather than a data set identifier (sds_id).
|
|
|
The value returned by the parameter num_datasets includes the number of coordinate variable data sets. To determine if the data set is a coordinate variable, use SDiscoordvar.
|
|
FORTRAN
|
integer function sffinfo(sd_id, num_datasets, num_global_attrs)
|
|
|
integer sd_id, num_datasets, num_global_attrs
|
[SD Interface][Top]
SDfindattr/sffattr
int32 SDfindattr(int32 obj_id, char *attr_name)
|
obj_id
|
IN:
|
Identifier of the object to which the attribute is attached
|
|
attr_name
|
IN:
|
Name of the attribute
|
|
Purpose
|
Finds the index of an attribute given its name.
|
|
Return value
|
Returns the index if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDfindattr retrieves the index of the object's attribute with the name specified by the parameter attr_name.
|
|
|
The attribute is attached to the object specified by the parameter obj_id. The parameter obj_id can be either an SD interface identifier (sd_id), returned by SDstart, a data set identifier (sds_id), returned by SDselect, or a dimension identifier (dim_id), returned by SDgetdimid.
|
|
|
Wildcard characters are not allowed in the parameter attr_name. SDfindattr searches for the name specified in the parameter attr_name in a case-sensitive manner.
|
|
FORTRAN
|
integer function sffattr(obj_id, attr_name)
|
|
|
integer obj_id
|
|
|
character*(*) attr_name
|
[SD Interface][Top]
SDgetcal/sfgcal
intn SDgetcal(int32 sds_id, float64 *cal, float64 *cal_err, float64 *offset, float64 *offset_err, int32 *data_type)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
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 information associated with a data set.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDgetcal reads the calibration record attached to the data set identified by the parameter sds_id. A calibration record is comprised of four 64-bit floating point values followed by a 32-bit integer. The information is listed in the following table:
|
cal
|
calibration factor
|
cal_err
|
calibration error
|
offset
|
uncalibrated offset
|
offset_err
|
uncalibrated offset error
|
data_type
|
data type of the uncalibrated data
|
|
|
The relationship between a calibrated value cal_value and the original value orig_value is defined as orig_value = cal * (cal_value - 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.
|
|
FORTRAN
|
integer function sfgcal(sds_id, cal, cal_err, offset, offset_err, data_type)
|
|
|
integer sds_id, data_type
|
|
|
real*8 cal, cal_err, offset, offset_err
|
[SD Interface][Top]
SDgetchunkinfo/sfgichnk
intn SDgetchunkinfo(int32 sds_id, HDF_CHUNK_DEF *cdef, int32 *flag)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
C only:
|
|
|
|
cdef
|
OUT:
|
Pointer to the chunk definition
|
|
flag
|
OUT:
|
Compression flag
|
|
Fortran only:
|
|
|
|
dim_length
|
OUT:
|
Array of chunk dimensions
|
|
flag
|
OUT:
|
Compression flag
|
|
Purpose
|
Retrieves chunking information for a data set.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDgetchunkinfo retrieves chunking information about the data set identified by the parameter sds_id into the parameters cdef and flag in C, and to the parameters dim_length and flag in Fortran.
|
|
|
Currently, only information about chunk dimensions is retrieved into the corresponding cdef structure element for each type of compression in C, and in the dim_length array in Fortran. No information on compression parameters is available in the comp structure of the HDF_CHUNK_DEF union. Refer to the page on SDsetchunk in this manual for specific information on the HDF_CHUNK_DEF union.
|
|
|
If the data set is empty, SDgetchunkinfo will fail. Thus, application must first verify that the data set has been written with data, before calling SDgetchunkinfo. SDcheckempty determines whether the data set is empty.
|
|
|
The value returned in the flag parameter indicates the data set type (i.e., if the data set is not chunked, chunked, and chunked and compressed).
|
|
|
If the chunk length for each dimension is not needed, NULL can be passed in as the value of the cdef parameter in C.
|
|
|
The following table shows the type of the data set, possible values of the flag parameter, and the corresponding cdef structure element filled with the chunk's dimensions.
|
Type of Data Set
|
Values of flag in C
|
Values of flag in Fortran
|
cdef Structure Element Filled with the Chunk's Dimensions
|
Not chunked
|
HDF_NONE
|
-1
|
None
|
Chunked
|
HDF_CHUNK
|
0
|
cdef.chunk_lengths[]
|
Chunked and compressed with either the run-length encoding (RLE), Skipping Huffman, GZIP, or Szip compression algorithms
|
HDF_CHUNK | HDF_COMP
|
1
|
cdef.comp.chunk_lengths[]
|
Chunked and compressed with NBIT compression
|
HDF_CHUNK | HDF_NBIT
|
2
|
cdef.nbit.chunk_lengths[]
|
|
FORTRAN
|
integer function sfgichnk(sds_id, dim_length, flag)
|
|
|
integer sds_id, dim_length(*), flag
|
[SD Interface][Top]
SDgetcompinfo/sfgcompress
intn SDgetcompinfo(int32 sds_id, comp_coder_t *comp_type, comp_info *c_info)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
comp_type
|
OUT:
|
Type of compression
|
|
c_info
|
OUT:
|
Pointer to compression information structure
|
|
Purpose
|
Retrieves data set compression type and compression information.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDgetcompinfo retrieves the compression type and compression information for a data set, when the data is either compressed, chunked or chunked and compressed. SDgetcompinfo replaces SDgetcompress because this function has flaws, causing failure for some chunked and chunked/compressed data.
|
|
|
The compression method is returned in the parameter comp_type. Valid values of comp_type are as follows:
|
|
|
COMP_CODE_NONE for no compression
COMP_CODE_RLE for RLE run-length encoding
COMP_CODE_NBIT for NBIT compression
COMP_CODE_SKPHUFF for Skipping Huffman compression
COMP_CODE_DEFLATE for GZIP compression
COMP_CODE_SZIP for Szip compression
|
|
|
Additional compression method parameters are returned in the c_info struct in C and the array parameter comp_prm in Fortran. Note that c_info and comp_prm come into place only with compression modes that require additional parameters (i.e., other than comp_type); they are ignored in other cases.
|
|
|
The c_info struct is of type comp_info , contains algorithm-specific information for the library compression routines, and is described in the SDsetcompress entry in this reference manual and in the hcomp.h header file.
|
|
|
The comp_prm parameter is an array returning one or more parameters, as required by the compression method in use. Each compression parameter is returned as an element of the array, as follows:
o With Skipping Huffman compression, comp_prm is a 1-element array and comp_prm(1) contains the skip value, skphuff_skp_size .
o In the case of GZIP compression, comp_prm is also a 1-element array and comp_prm(1) contains the deflation value, deflate_value .
o In the case of NBIT compression, comp_prm is a 4-element array with sign_ext in comp_prm(1), fill_one in comp_prm(2), start_bit in comp_prm(3), and bit_len in comp_prm(4). The fields sign_ext , fill_one , start_bit , and bit_len are discussed in the SDsetnbitdataset/sfsnbit entry of this reference manual.
o In the case of Szip compression, comp_prm is a 5-element array with option_mask in comp_prm(1), pixels_per_block in comp_prm(2), pixels_per_scanline in comp_prm(3), bits_per_pixel in comp_prm(4), and pixels in comp_prm (5).
|
|
|
In the general case, any available compression type can be configured in any mode:
COMP_DECODER_ENABLED Decode data only
COMP_ENCODER_ENABLED Encode data only
COMP_DECODER_ENABLED |COMP_ENCODER_ENABLED Decode and encode data
As of this writing (HDF4 Release 2.1, February 2005), only the Szip compression library is actually used with the HDF libraries in more than one configuration (see immediately below). As a third-party product, it is distributed in both decode-only and encode/decode configurations. All other compression methods are currently distributed or used in an encode/decode configuration if they are available at all. See also HCget_config_info.
|
|
|
SDgetcompinfo will succeed for an Szip-compressed dataset whether the available Szip library is configured either for encoding/decoding or for decoding-only.
If the Szip configuration is decode-only, i.e., an HCget_config_info call on the dataset will return only COMP_DECODER_ENABLED in compression_config_info. Note that in such a case the file must be opened in read-only mode, i.e. with SDstart( filename, DFACC_RDONLY ) .
If the Szip configuration is encode/decode, i.e., an HCget_config_info call on the dataset will return COMP_ENCODER_ENABLED|COMP_DECODER_ENABLED in compression_config_info. In this case, the file and dataset can be opened in read/write mode.
|
|
Note
|
Regarding uncompressed data or an empty data set:
SDgetcompinfo will succeed and the parameter comp_type will have the value COMP_CODE_NONE if either of the following conditions exists:
o The data set is not compressed.
o No data has been written to the SDS.
|
|
Note
|
Regarding Szip usage and licensing:
See http://www.hdfgroup.org/doc_resource/SZIP/ for information regarding the use of Szip in HDF products and Szip licensing.
|
|
FORTRAN
|
integer function sfgcompress(sds_id, comp_type, comp_prm)
|
|
|
integer sds_id, comp_type, comp_prm(*)
|
|
|
|
[SD Interface][Top]
SDgetdatasize/
intn SDgetdatasize(int32 sds_id, int32 *comp_size, int32 *orig_size)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
comp_size
|
OUT:
|
Size of compressed data
|
|
orig_size
|
OUT:
|
Size of original data
|
|
Purpose
|
Retrieves the sizes of original and compressed data.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDgetdatastrs retrieves the original and compressed data sizes, in bytes, of the data set specified by the parameter sds_id. NULL can be passed in for undesired parameter.
|
|
|
The values of comp_size and orig_size will be returned as described below:
|
Type of data
|
comp_size
|
orig_size
|
no data
|
0
|
0
|
compressed
|
size of compressed data
|
size of original data
|
chunked/compressed
|
size of compressed data in all chunks
|
size of original data in all chunks
|
uncompressed
|
size of original data
|
size of original data
|
unlimited dimension
|
size of original data
|
size of original data
|
|
FORTRAN
|
Currently unavailable
|
|
|
|
|
|
|
[SD Interface][Top]
SDgetdatastrs/sfgdtstr
intn SDgetdatastrs(int32 sds_id, char *label, char *unit, char *format, char *coordsys, intn length)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
label
|
OUT:
|
Label (predefined attribute)
|
|
unit
|
OUT:
|
Unit (predefined attribute)
|
|
format
|
OUT:
|
Format (predefined attribute)
|
|
coordsys
|
OUT:
|
Coordinate system (predefined attribute)
|
|
length
|
IN:
|
Maximum length of the above predefined attributes
|
|
Purpose
|
Retrieves the predefined attributes of a data set.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDgetdatastrs retrieves the predefined attributes for the data set specified by the parameter sds_id. The predefined attributes are label, unit, format, and coordinate system. They are then stored in the parameters label, unit, format, and coordsys, respectively. Refer to Section 3.10 of the HDF User's Guide for more information on predefined attributes.
|
|
|
If a particular data string is not stored, the first character of the corresponding SDgetdatastrs parameter is '\0 ' in C. In FORTRAN, the parameter contains an empty string. Each string buffer must include the space to hold the null termination character. In C, if a user does not want a string back, NULL can be passed in for that string. Data strings are set by the SDsetdatastrs routine.
|
|
FORTRAN
|
integer function sfgdtstr(sds_id, label, unit, format, coordsys, length)
|
|
|
integer sds_id, length
|
|
|
character*(*) label, unit, format, coordsys
|
[SD Interface][Top]
SDgetdimid/sfdimid
int32 SDgetdimid(int32 sds_id, intn dim_index)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
dim_index
|
IN:
|
Index of the dimension
|
|
Purpose
|
Returns the identifier of a dimension given its index.
|
|
Return value
|
Returns the dimension identifier (dim_id) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDgetdimid returns the identifier of the dimension specified by its index, the parameter dim_index.
|
|
|
The dimension index is a nonnegative integer and is less than the total number of data set dimensions returned by SDgetinfo.
|
|
FORTRAN
|
integer function sfdimid(sds_id, dim_index)
|
|
|
integer sds_id, dim_index
|
[SD Interface][Top]
SDgetdimscale/sfgdscale
intn SDgetdimscale(int32 dim_id, VOIDP scale_buf)
|
dim_id
|
IN:
|
Dimension identifier returned by SDgetdimid
|
|
scale_buf
|
OUT:
|
Buffer for the scale values
|
|
Purpose
|
Retrieves the scale values for a dimension.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDgetdimscale retrieves the scale values of the dimension identified by the parameter dim_id and stores the values in the buffer scale_buf.
|
|
|
SDdiminfo should be used to determine whether a scale has been set for the dimension, i.e., that the dimension scale data type is a valid HDF data type (not 0). Also use SDdiminfo to obtain the number of scale values for space allocation before calling SDgetdimscale.
|
|
|
It is not possible to read a subset of the scale values. SDgetdimscale returns all of the scale values stored with the given dimension.
|
|
|
The fact that SDgetdimscale returns SUCCEED should not be interpreted to mean that scale values have been defined for the data set. This function should always be used with SDdiminfo, which is used first to determine whether a scale has been set, the number of scale values, their data type, etc. If SDdiminfo indicates that no scale values have been set, the values returned by SDgetdimscale in data should be ignored.
|
|
FORTRAN
|
integer function sfgdscale(dim_id, scale_buf)
|
|
|
integer dim_id
|
|
|
<valid numeric data type> scale_buf(*)
|
[SD Interface][Top]
SDgetdimstrs/sfgdmstr
intn SDgetdimstrs(int32 dim_id, char *label, char *unit, char *format, intn length)
|
dim_id
|
IN:
|
Dimension identifier returned by SDgetdimid
|
|
label
|
OUT:
|
Label (predefined attribute)
|
|
unit
|
OUT:
|
Unit (predefined attribute)
|
|
format
|
OUT:
|
Format (predefined attribute)
|
|
length
|
IN:
|
Maximum length of the above predefined attributes
|
|
Purpose
|
Retrieves the predefined attributes of a dimension.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDgetdimstrs retrieves the predefined attributes associated with the dimension identified by the parameter dim_id. The predefined attributes are label, unit, and format. These predefined attributes are stored in the parameters label, unit, and format, respectively. Refer to Section 3.10 of the HDF User's Guide for more information on predefined attributes.
|
|
|
If a particular data string was not stored, the first character of the corresponding SDgetdimstrs parameter is '\0 '. Each string buffer must include space for the null termination character. If a user does not want a string returned, the corresponding parameter can be set to NULL in C and an empty string in Fortran. The predefined attributes are set by SDsetdimstrs.
|
|
FORTRAN
|
integer function sfgdmstr(dim_id, label, unit, format, length)
|
|
|
integer dim_id, length
|
|
|
character*(*) label, unit, format
|
[SD Interface][Top]
SDgetfilename/sfgetfname
intn SDgetfilename(int32 file_id, char *filename)
|
file_id
|
IN:
|
A file identifier
|
|
filename
|
OUT:
|
Name of the file
|
|
Purpose
|
Given a file identifier, retrieves the name of the file.
|
|
Return value
|
Returns the length of the file name, without '\0 ', on success, and FAIL , otherwise.
|
|
FORTRAN
|
integer function sfgetfname(file_id, filename)
|
|
|
character*(*) filename
|
|
|
integer file_id
|
[SD Interface][Top]
SDgetfillvalue/sfgfill/sfgcfill
intn SDgetfillvalue(int32 sds_id, VOIDP fill_value)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
fill_value
|
OUT:
|
Buffer for the returned fill value
|
|
Purpose
|
Reads the fill value of a data set, if the value has been set.
|
|
Return value
|
Returns SUCCEED (or 0 ) if a fill value is retrieved and FAIL (or -1 ) otherwise, including when the fill value is not set.
|
|
Description
|
SDgetfillvalue reads the fill value which has been set for the data set specified by the parameter sds_id. It is assumed that the data type of the fill value is the same as that of the data set.
|
|
|
Note that there are two FORTRAN-77 versions of this routine: sfgfill and sfgcfill. The sfgfill routine reads numeric fill value data and sfgcfill reads character fill value data.
|
|
FORTRAN
|
integer function sfgfill(sds_id, fill_value)
|
|
|
integer sds_id
|
|
|
<valid numeric data type> fill_value
|
|
|
|
|
|
integer function sfgcfill(sds_id, fill_value)
|
|
|
integer sds_id
|
|
|
character*(*) fill_value
|
[SD Interface][Top]
SDgetinfo/sfginfo
intn SDgetinfo(int32 sds_id, char *sds_name, int32 *rank, int32 dimsizes[], int32 *data_type, int32 *num_attrs)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate and SDselect
|
|
sds_name
|
OUT:
|
Name of the data set
|
|
rank
|
OUT:
|
Number of dimensions in the data set
|
|
dimsizes
|
OUT:
|
Array containing the size of each dimension in the data set
|
|
data_type
|
OUT:
|
Data type for the data stored in the data set
|
|
num_attrs
|
OUT:
|
Number of attributes for the data set
|
|
Purpose
|
Retrieves the name, rank, dimension sizes, data type and number of attributes for a data set.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDgetinfo retrieves the name, number of dimensions, sizes of dimensions, data type, and number of attributes of the data set identified by sds_id, and stores them in the parameters sds_name, rank, dimsizes, data_type, and num_attrs, respectively.
|
|
|
The buffer sds_name can have at most 64 characters. If the name of the data set is not desired, then the parameter sds_name can be set to NULL in C and an empty string in Fortran.
|
|
|
The maximum value of the rank parameter is MAX_VAR_DIMS (or 32 ).
|
|
|
If the data set is created with an unlimited dimension, then in the C interface, the first element of the dimsizes array (corresponding to the slowest-changing dimension) contains the number of records in the unlimited dimension; in the FORTRAN-77 interface, the last element of the dimsizes array (corresponding to the slowest-changing dimension) contains this information. Use SDisrecord to determine if the data set has an unlimited dimension.
|
|
FORTRAN
|
integer function sfginfo(sds_id, sds_name, rank, dimsizes, data_type, num_attrs)
|
|
|
character*(*) sds_name
|
|
|
integer sds_id, rank, dimsizes(*)
|
|
|
integer data_type, num_attrs
|
[SD Interface][Top]
SDgetnamelen/sfgetnamelen
intn SDgetnamelen(int32 obj_id, uint16 name_len)
|
obj_id
|
IN:
|
Identifier of the object
|
|
name_len
|
OUT:
|
Length of the object's name
|
|
Purpose
|
Retrieves the length of the name of a file, a dataset, or a dimension.
|
|
Return value
|
Returns the length of the object's name on success, and FAIL (-1 ) otherwise.
|
|
Description
|
Given an identifier of a file, a dataset, or a dimension, SDgetnamelen retrieves the length of its name into name_len. The length does not include the character '\0 '.
|
|
FORTRAN
|
integer function sfgetnamelen(obj_id, length)
|
|
|
integer obj_id, length
|
[SD Interface][Top]
SDgetnumvars_byname/sfgnvars_byname
intn SDgetnumvars_byname(int32 sd_id, char *sds_name, int32 *n_vars)
|
sd_id
|
IN:
|
SD interface identifier returned by SDstart
|
|
sds_name
|
IN:
|
Name of the data set
|
|
n_vars
|
OUT:
|
Number of variables named sds_name
|
|
Purpose
|
Get the number of data sets having the same name.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDgetnumvars_byname retrieves the number of variables with the name specified by the parameter sds_name. The variables may include both data sets or coordinate variables. The routine does not accept wildcards in the specified data set name. It also searches on that name in a case-sensitive manner.
|
|
FORTRAN
|
integer function sfgnvars_byname(sd_id, sds_name, n_vars)
|
|
|
integer sd_id, n_vars
|
|
|
character*(*) sds_name
|
[SD Interface][Top]
SDgetrange/sfgrange
intn SDgetrange(int32 sds_id, VOIDP max, VOIDP min)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
max
|
OUT:
|
Maximum value of the range
|
|
min
|
OUT:
|
Minimum value of the range
|
|
Purpose
|
Retrieves the maximum and minimum values of the range.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDgetrange retrieves the maximum value of the range into the parameter max and the minimum value into the parameter min. The maximum and minimum values must be previously set via a call to SDsetrange.
|
|
|
It is assumed that the data type for the maximum and minimum range values are the same as that of the data.
|
|
FORTRAN
|
integer function sfgrange(sds_id, max, min)
|
|
|
integer sds_id
|
|
|
<valid numeric data type> max, min
|
[SD Interface][Top]
SDget_maxopenfiles/sfgmaxopenf
intn SDget_maxopenfiles(intn *curr_max, intn *sys_limit)
|
cu
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
curr_max
|
OUT:
|
Current number of open files
|
|
sys_limit
|
OUT:
|
Maximum number of open files
|
|
Purpose
|
Retrieves current and maximum number of open files.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDget_maxopenfiles retrieves the current number of open files allowed in HDF, curr_max, and the maxinum number of open files allowed on the system, sys_limit. If either of the values is not desired, then NULL can be passed in.
|
|
FORTRAN
|
integer function sfgmaxopenf(cur_max, sys_limit)
|
|
|
integer cur_max, sys_limit
|
[SD Interface][Top]
SDget_numopenfiles/sfgnumopenf
intn SDget_numopenfiles()
|
Purpose
|
Returns the number of files currently being opened.
|
|
Return value
|
Returns the number of files currently being opened.
|
|
FORTRAN
|
integer function sfgnumopenf(cur_num)
|
|
|
integer cur_num
|
[SD Interface][Top]
SDidtoref/sfid2ref
int32 SDidtoref(int32 sds_id)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
Purpose
|
Returns the reference number assigned to a data set.
|
|
Return value
|
Returns the data set reference number if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDidtoref returns the reference number of the data set specified by the parameter sds_id. The reference number is assigned by the HDF library when the data set is created. The specified reference number can be used to add the data set to a vgroup as well as a means of using the HDF annotations interface to annotate the data set.
|
|
FORTRAN
|
integer function sfid2ref(sds_id)
|
|
|
integer sds_id
|
[SD Interface][Top]
SDidtype/sfidtype
hdf_idtype_t SDidtype(int32 obj_id)
|
obj_id
|
IN:
|
Identifier of the object
|
|
Purpose
|
Given an id, return the type of object the id represents.
|
|
Return value
|
Returns a value of type hdf_idtype_t .
|
|
Description
|
SDidtype returns a value of type hdf_idtype_t, which can be one of the following:
o NOT_SDAPI_ID (or -1 ) not an SD API id
o SD_ID (or 0 ) SD id
o SDS_ID (or 1 ) SDS id
o DIM_ID (or 2 ) Dimension id
SDidtype returns NOT_SDAPI_ID for either
+ when obj_id is not a valid HDF id, or
+ when obj_id is a valid HDF id, but not one of the id types in
the SD interface, which are SD id, SDS id, and dimension id.
|
|
FORTRAN
|
integer function sfidtype(obj_id, obj_type)
|
|
|
integer obj_id, obj_type
|
[SD Interface][Top]
SDiscoordvar/sfiscvar
intn SDiscoordvar(int32 sds_id)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
Purpose
|
Determines if a data set is a coordinate variable.
|
|
Return value
|
Returns TRUE (or 1 ) if the data set is a coordinate variable, and FALSE (or 0 ) otherwise.
|
|
Description
|
SDiscoordvar determines if the data set specified by the parameter sds_id is a coordinate variable.
|
|
|
Coordinate variables are created to store metadata associated with dimensions. To ensure compatibility with netCDF, coordinate variables are implemented as data sets.
|
|
|
Note that if there are more than one variable (either multiple data sets or data sets and dimensions) with the same name in the file, SDiscoordvar might return the incorrect item. This was a bug in the HDF4 library prior to 4.2r2. For details, please refer to the note " Regarding naming a dimension the same as an SDS' name" in the SDsetdimname page.
|
|
|
When the uniqueness of the name is unknown, SDgetnumvars_byname can be used to get the number of data sets (or variables, which includes both data sets and coordinate variables) with the same name. SDnametoindices can then be used to get a list of structures containing the indices and the types of all the variables of that same name. However, note that the type of the variable will be UNKNOWN when the data was created by libraries of pre-4.2r2.
|
|
FORTRAN
|
integer function sfiscvar(sds_id)
|
|
|
integer sds_id
|
[SD Interface][Top]
SDisdimval_bwcomp/sfisdmvc
intn SDisdimval_bwcomp(int32 dim_id)
|
dim_id
|
IN:
|
Dimension identifier returned by SDgetdimid
|
|
Purpose
|
Determines whether a dimension has the old and new representations or the new representation only.
|
|
|
Refer to Chapter 3, "Scientific Data Sets (SD API)" of the HDF User's Guide, for information on old and new dimension representations.
|
|
Return value
|
Returns SD_DIMVAL_BW_COMP (or 1) if backward compatible, SD_DIMVAL_BW_INCOMP (or 0) if incompatible, FAIL (or -1) if error.
|
|
Description
|
SDisdimval_bwcomp will flag the dimension specified by the parameter dim_id as backward-compatible if a vdata with a class name of "DimVal0.0" does not exist in the vgroup for that dimension. If the vdata does exist, the specified dimension will be identified by SDisdimval_bcomp as backward-incompatible.
|
|
|
The compatibility mode can be changed by calls to SDsetdimval_comp at any time between the calls to SDstart and SDend.
|
|
FORTRAN
|
integer function sfisdmvc(dim_id)
|
|
|
integer dim_id
|
[SD Interface][Top]
SDisrecord/sfisrcrd
int32 SDisrecord(int32 sds_id)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
Purpose
|
Determines whether a data set is appendable.
|
|
Return value
|
Returns TRUE (or 1 ) if the data set is appendable, and FALSE (or 0 ) otherwise.
|
|
Description
|
SDisrecord will determine if the data set specified by the parameter sds_id is appendable, which means that the slowest-changing dimension was declared unlimited when the data set was created.
|
|
FORTRAN
|
integer sfisrcrd(sd_id)
|
|
|
integer sd_id
|
[SD Interface][Top]
SDnametoindex/sfn2index
int32 SDnametoindex(int32 sd_id, char *sds_name)
|
sd_id
|
IN:
|
SD interface identifier returned by SDstart
|
|
sds_name
|
IN:
|
Name of the data set
|
|
Purpose
|
Determines the index of a data set given its name.
|
|
Return value
|
Returns the index of the data set (sds_index) if the data set is found and FAIL (or -1 ) otherwise.
|
|
Description
|
SDnametoindex returns the index of the data set with the name specified by the parameter sds_name. The routine does not accept wildcards in the specified data set name. It also searches on that name in a case-sensitive manner. If there are more than one data set with the same name, the routine will return the index of the first one.
|
|
|
Note that if there are more than one data set with the same name in the file, writing to a data set returned by this function without verifying that it is the desired data set could cause data corruption. For details, please refer to the note " Regarding naming a dimension the same as an SDS' name" in the SDsetdimname page.
|
|
|
SDgetnumvars_byname can be used to get the number of data sets (or variables, which includes both data sets and coordinate variables) with the same name. SDnametoindices can be used to get a list of structures containing the indices and the types of all the variables of that same name.
|
|
FORTRAN
|
integer function sfn2index(sd_id, sds_name)
|
|
|
integer sd_id
|
|
|
character*(*) sds_name
|
[SD Interface][Top]
SDnametoindices/sfn2indices
intn SDnametoindices(int32 sd_id, char *sds_name, hdf_varlist_t* var_list)
|
sd_id
|
IN:
|
SD interface identifier returned by SDstart
|
|
sds_name
|
IN:
|
Name of the data set
|
|
var_list
|
OUT:
|
List of all variables of same name
|
|
Purpose
|
Retrieves indices of all variables with the same name.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDnametoindices retrieves a list of structures hdf_varlist_t , containing the indices and the types of all variables of the same name sds_name.
The structure hdf_varlist_t is defined as:
typedef struct varlist
{
int32 var_index; /* index of a variable */
vartype_t var_type; /* type of a variable */
} hdf_varlist_t;
The type of a variable vartype_t is defined as:
IS_SDSVAR=0 : variable is an actual SDS
IS_CRDVAR=1 : variable is a coordinate variable
UNKNOWN=2 : variable is created before HDF4.2r2, unknown type
The routine does not accept wildcards in the specified data set name. It also searches on that name in a case-sensitive manner.
|
|
|
Note that if there are more than one data set with the same name in the file, writing to a data set returned by this function without verifying that it is the desired data set could cause data corruption. For details, please refer to the note " Regarding naming a dimension the same as an SDS' name" in the SDsetdimname page.
|
|
|
SDgetnumvars_byname can be used to get the number of data sets (or variables, which includes both data sets and coordinate variables) with the same name. SDnametoindices can then be used to get a list of structures containing the indices and the types of all the variables of that same name.
|
|
FORTRAN
|
integer function sfn2indices(sd_id, sds_name, var_list, type_list, n_vars)
|
|
|
integer sd_id
|
|
|
character*(*) sds_name
|
|
|
integer var_list(*), type_list(*)
|
|
|
integer n_vars
|
[SD Interface][Top]
SDreadattr/sfrnatt/sfrcatt
intn SDreadattr(int32 obj_id, int32 attr_index, VOIDP attr_buf)
|
obj_id
|
IN:
|
Identifier of the object the attribute is attached to
|
|
attr_index
|
IN:
|
Index of the attribute to be read
|
|
attr_buf
|
OUT:
|
Buffer for the attribute values
|
|
Purpose
|
Reads the values of an attribute.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDreadattr reads the values of the attribute specified by the parameter attr_index and stores the values in the buffer attr_buf. It is assumed that the user has called SDattrinfo to retrieve the number of attribute values and allocate sufficient space for the buffer. Note that the routine does not read a subset of attribute values.
|
|
|
The value of obj_id can be either an SD interface identifier (sd_id), returned by SDstart, a data set identifier (sds_id), returned by SDselect, or a dimension identifier (dim_id), returned by SDgetdimid.
|
|
|
The value of attr_index is a positive integer and is less than the total number of attributes. The index value can be obtained using the routines SDnametoindex and SDreftoindex. The total number of attributes for the object can be obtained using the routines SDgetinfo, SDattrinfo, SDdiminfo and SDfileinfo.
|
|
|
Note that this routine returns an array of characters, not a standard null-terminated string. If an application is running in an environment where a null-terminated string is expected, the application must add the null character before saving the string or using it further.
Note that this routine has two FORTRAN-77 versions: sfrnatt and sfrcatt. The sfrnatt routine reads numeric attribute data and sfrcatt reads character attribute data.
|
|
FORTRAN
|
integer function sfrnatt(obj_id, attr_index, attr_buffer)
|
|
|
integer obj_id, attr_index
|
|
|
<valid numeric data> attr_buffer(*)
|
|
|
|
|
|
integer function sfrcatt(obj_id, attr_index, attr_buffer)
|
|
|
integer obj_id, attr_index
|
|
|
character*(*) attr_buffer
|
[SD Interface][Top]
SDreadchunk/sfrchnk/sfrcchnk
intn SDreadchunk(int32 sds_id, int32 *origin, VOIDP datap)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
origin
|
IN:
|
Origin of the chunk to be read
|
|
datap
|
OUT:
|
Buffer for the chunk to be read
|
|
Purpose
|
Reads a data chunk from a chunked data set.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDreadchunk reads the entire chunk of data from the chunked data set identified by the parameter sds_id, and stores the data in the buffer datap. Reading starts at the location specified by the parameter origin. SDreadchunk is used when an entire chunk of data is to be read. SDreaddata is used when the read operation is to be done regardless of the chunking scheme used in the data set.
|
|
|
The parameter origin specifies the coordinates of the chunk according to the chunk position in the chunked array. Refer to the Chapter 3, "Scientific Data Sets (SD API)" of the HDF User's Guide, for a description of the organization of chunks in a data set.
|
|
|
SDreadchunk will return FAIL (or -1 ) when an attempt is made to read from a non-chunked data set.
|
|
|
Note that there are two FORTRAN-77 versions of this routine; one for numeric data (sfrchnk) and one for character data (sfrcchnk).
|
|
FORTRAN
|
integer sfrchnk(sds_id, origin, datap)
|
|
|
integer sds_id, origin(*)
|
|
|
<valid numeric data type> datap(*)
|
|
|
|
|
|
integer sfrcchnk(sds_id, origin, datap)
|
|
|
integer sds_id, origin(*)
|
|
|
character*(*) datap(*)
|
[SD Interface][Top]
SDreaddata/sfrdata/sfrcdata
intn SDreaddata(int32 sds_id, int32 start[], int32 stride[], int32 edge[], VOIDP buffer)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
start
|
IN:
|
Array specifying the starting location from where data is read
|
|
stride
|
IN:
|
Array specifying the interval between the values that will be read along each dimension
|
|
edge
|
IN:
|
Array specifying the number of values to be read along each dimension
|
|
buffer
|
OUT:
|
Buffer to store the data read
|
|
Purpose
|
Reads a subsample of data from a data set or coordinate variable.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful or if the data set or coordinate variable contains no data and FAIL (or -1 ) otherwise.
|
|
Description
|
SDreaddata reads the specified subsample of data from the data set or coordinate variable identified by the parameter sds_id. The read data is stored in the buffer buffer. The subsample is defined by the parameters start, stride and edge.
|
|
|
The array start specifies the starting position from where the subsample will be read. Valid values of each element in the array start are from 0 to the size of the corresponding dimension of the data set - 1. The dimension sizes are returned by SDgetinfo.
|
|
|
The array edge specifies the number of values to read along each data set dimension.
|
|
|
The array stride specifies the reading pattern along each dimension. For example, if one of the elements of the array stride is 1, then every element along the corresponding dimension of the data set will be read. If one of the elements of the array stride is 2, then every other element along the corresponding dimension of the data set will be read, and so on. Specifying stride value of NULL in the C interface or setting all values of the array stride to 1 in either interface specifies the contiguous reading of data. If all values in the array stride are set to 0 or any value causes striding beyond the end of the associate dimension, SDreaddata returns FAIL (or -1 ). No matter what stride value is provided, data is always placed contiguously in the buffer.
|
|
|
When reading data from a "chunked" data set using SDreaddata, consideration should be given to the issues presented in the section on chunking in Chapter 3, "Scientific Data Sets (SD API)" and Chapter 14, "HDF Performance Issues" in the HDF User's Guide.
|
|
|
Note that 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.
|
|
Note
|
Regarding an important difference between the SD and GR interfaces: The SD and GR interfaces differ in the correspondence between the dimension order in parameter arrays such as start, stride, edge, and dimsizes and the dimension order in the data array. See the SDreaddata and GRreadimage reference manual pages for discussions of the SD and GR approaches, respectively.
|
|
|
When writing applications or tools to manipulate both images and two-dimensional SDs, this crucial difference between the interfaces must be taken into account. While the underlying data is stored in row-major order in both cases, the API parameters are not expressed in the same way. Consider the example of an SD data set and GR image that are stored as identically-shaped arrays of X columns by Y rows and accessed via the SDreaddata and GRreadimage functions, respectively. Both functions take the parameters start, stride, and edge.
o For SDreaddata, those parameters are expressed in (y,x) or [row,column] order. For example, start[0] is the starting point in the Y dimension and start[1] is the starting point in the X dimension. The same ordering holds true for all SD data set manipulation functions.
o For GRreadimage, those parameters are expressed in (x,y) or [column,row] order. For example, start[0] is the starting point in the X dimension and start[1] is the starting point in the Y dimension. The same ordering holds true for all GR functions manipulating image data.
|
|
|
It is sometimes necessary to determine whether and how a dataset is compressed and whether the software necessary to read that data is available. The compression method used on the dataset can be determined with SDgetcompinfo and the availability and configuration of the compression software with HCget_config_info. Further information is available in the respective entries in this reference manual.
|
|
Note
|
Regarding Szip-compressed data: SDreaddata can succeed for an Szip-compressed dataset whether the available Szip library is configured either for encoding/decoding or for decoding-only.
If the available Szip configuration is decode-only, HCget_config_info will return only COMP_DECODER_ENABLED in compression_config_info; the returned flags will not include COMP_ENCODER_ENABLED . In such a case, the file must have been opened in read-only mode, i.e. with SDstart(filename, DFACC_RDONLY ).
If the Szip avaialble configuration is encode/decode, HCget_config_info will return COMP_ENCODER_ENABLED |COMP_DECODER_ENABLED . In such a case, the file and dataset can be opened in read/write mode.
See the HCget_config_info and SDgetcompinfo entries in this reference manual for further information.
|
|
Note
|
Regarding Szip usage and licensing:
See http://www.hdfgroup.org/doc_resource/SZIP/ for information regarding the use of Szip in HDF products and Szip licensing.
|
|
FORTRAN
|
integer function sfrdata(sds_id, start, stride, edge, buffer)
|
|
|
integer sds_id, start(*), stride(*), edge(*)
|
|
|
<valid numeric data type> buffer(*)
|
|
|
|
|
|
integer function sfrcdata(sds_id, start, stride, edge, buffer)
|
|
|
integer sds_id, start(*), stride(*), edge(*)
|
|
|
character*(*) buffer
|
[SD Interface][Top]
SDreftoindex/sfref2index
int32 SDreftoindex(int32 sd_id, int32 sds_ref)
|
sd_id
|
IN:
|
SD interface identifier returned by SDstart
|
|
sds_ref
|
IN:
|
Reference number of the data set
|
|
Purpose
|
Returns the index of a data set given the reference number.
|
|
Return value
|
Returns the index of the data set (sds_index) if the data set is found and FAIL (or -1 ) otherwise.
|
|
Description
|
SDreftoindex returns the index of a data set identified by its reference number, sds_ref.
|
|
|
The value of sds_index returned by SDreftoindex can be passed to SDselect to obtain a data set identifier (sds_id).
|
|
FORTRAN
|
integer function sfref2index(sd_id, sds_ref)
|
|
|
integer sd_id, sds_ref
|
[SD Interface][Top]
SDreset_maxopenfiles/sfrmaxopenf
intn SDreset_maxopenfiles(intn req_max)
|
req_max
|
IN:
|
Requested maximum number of opened files allowed
|
|
Purpose
|
Resets the maximum number of files can be opened at the same time.
|
|
Return value
|
Returns the current maximum number of opened files allowed if successful and FAIL (or -1) otherwise.
|
|
Description
|
Prior to release 4.2r2, the maximum number of files that can be opened at the same time was limited to 32. In HDF 4.2r2 and later versions, if this limit is reached, the library will increase it to the system limit minus 3 to account for stdin, stdout, and stderr.
This function can be called anytime to change the maximum number of open files allowed in HDF to req_max. If req_max is 0 , SDreset_maxopenfiles will simply return the current maximum number of open files allowed. If req_max exceeds system limit, SDreset_maxopenfiles will reset the maximum number of open files to the system limit, and return that value.
Furthermore, if the system maximum limit is reached, the library will push the error code DFE_TOOMANY onto the error stack. User applications can detect this after an SDstart fails.
|
|
FORTRAN
|
integer function sfrmaxopenf(req_max)
|
|
|
integer req_max
|
[SD Interface][Top]
SDselect/sfselect
int32 SDselect(int32 sd_id, int32 sds_index)
|
sd_id
|
IN:
|
SD interface identifier returned by SDstart
|
|
sds_index
|
IN:
|
Index of the data set
|
|
Purpose
|
Obtains the data set identifier (sds_id) of a data set.
|
|
Return value
|
Returns the data set identifier (sds_id) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDselect obtains the data set identifier (sds_id) of the data set specified by its index, sds_index.
|
|
|
The integration with netCDF has required that a dimension (or coordinate variable) is stored as a data set in the file. Therefore, the value of sds_index may correspond to the coordinate variable instead of the actual data set. Users should use the routine SDiscoordvar to determine whether the given data set is a coordinate variable.
|
|
|
The value of sds_index is greater than or equal to 0 and less than the number of data sets in the file. The total number of data sets in a file may be obtained from a call to SDfileinfo. The SDnametoindex routine can be used to find the index of a data set if its name is known.
|
|
FORTRAN
|
integer function sfselect(sd_id, sds_index)
|
|
|
integer sd_id, sds_index
|
[SD Interface][Top]
SDsetattr/sfsnatt/sfscatt
intn SDsetattr(int32 obj_id, char *attr_name, int32 data_type, int32 count, VOIDP values)
|
obj_id
|
IN:
|
Identifier of the object the attribute is to be attached to
|
|
attr_name
|
IN:
|
Name of the attribute
|
|
data_type
|
IN:
|
Data type of the values in the attribute
|
|
count
|
IN:
|
Total number of values to be stored in the attribute
|
|
values
|
IN:
|
Data values to be stored in the attribute
|
|
Purpose
|
Attaches an attribute to an object.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDsetattr attaches the attribute to the object specified by the obj_id parameter. The attribute is defined by its name, attr_name, data type, data_type, number of attribute values, count, and the attribute values, values. SDsetattr provides a generic way for users to define metadata. It implements the label = value data abstraction.
|
|
|
The value of obj_id can be an SD interface identifier (sd_id), returned by SDstart, a data set identifier (sds_id), returned by SDcreate or SDselect, or a dimension identifier (dim_id), returned by SDgetdimid.
|
|
|
If an SD interface identifier (sd_id) is specified as the obj_id parameter, a global attribute is created which applies to all objects in the file. If a data set identifier (sds_id) is specified as the obj_id parameter, an attribute is attached to the specified data set. If a dimension identifier (dim_id) is specified as the obj_id parameter, an attribute is attached to the specified dimension.
|
|
|
The attr_name argument can be any ASCII string.
|
|
|
The data_type parameter can contain any data type supported by the HDF library. These data types are listed in Table 1A in Section I of this manual.
|
|
|
Attribute values are passed in the parameter values. The number of attribute values is defined by the count parameter. If more than one value is stored, all values must have the same data type. If an attribute with the given name, data type and number of values exists, it will be overwritten.
|
|
|
Note that there are two FORTRAN-77 versions of this routine; sfsnatt and sfscatt. The sfsnatt routine writes numeric attribute data and sfscatt writes character attribute data.
|
|
FORTRAN
|
integer function sfsnatt(obj_id, attr_name, data_type, count, values)
|
|
|
integer obj_id, data_type, count
|
|
|
character*(*) attr_name
|
|
|
<valid numeric data type> values(*)
|
|
|
|
|
|
integer function sfscatt(obj_id, attr_name, data_type, count, values)
|
|
|
integer obj_id, data_type, count
|
|
|
character*(*) attr_name, values
|
[SD Interface][Top]
SDsetblocksize/sfsblsz
intn SDsetblocksize(int32 sd_id, int32 block_size)
|
sd_id
|
IN:
|
SD interface identifier returned by SDstart
|
|
block_size
|
IN:
|
Size of the block in bytes
|
|
Purpose
|
Sets the block size used for storing data sets with unlimited dimensions.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDsetblocksize sets the block size defined in the parameter block_size for all data sets in the file. SDsetblocksize is used when creating new data sets only; it has no effect on pre-existing data sets.
|
|
|
SDsetblocksize must be used after calls to SDcreate or SDselect and before the call to SDwritedata.
|
|
|
The block_size parameter should be set to a multiple of the desired buffer size.
|
|
FORTRAN
|
integer sfsblsz(sd_id, block_size)
|
|
|
integer sd_id, block_size
|
[SD Interface][Top]
SDsetcal/sfscal
intn SDsetcal(int32 sds_id, float64 cal, float64 cal_err, float64 offset, float64 offset_err, int32 data_type)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
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.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDsetcal stores the calibration record associated with a data set. A calibration record contains the following information:
|
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 cal_value stored in a data set and the original value is defined as: orig_value = cal * (cal_value - 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.
|
|
|
The calibration information is automatically cleared after a call to SDreaddata or SDwritedata. Therefore, SDsetcal must be called once for each data set that is to be read or written.
|
|
FORTRAN
|
integer function sfscal(sds_id, cal, cal_err, offset, offset_err, data_type)
|
|
|
integer sds_id, data_type
|
|
|
real*8 cal, cal_err, offset, offset_err
|
[SD Interface][Top]
SDsetchunk/sfschnk
intn SDsetchunk(int32 sds_id, HDF_CHUNK_DEF cdef, int32 flag)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
C only:
|
|
|
|
cdef
|
IN:
|
Pointer to the chunk definition
|
|
flag
|
IN:
|
Compression flag
|
|
Fortran only:
|
|
|
|
dim_length
|
IN:
|
Chunk dimensions array
|
|
comp_type
|
IN:
|
Type of compression
|
|
comp_prm
|
IN:
|
Compression parameters array
|
|
Purpose
|
Sets the chunk size and the compression method, if any, of a data set.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDsetchunk makes the data set specified by the parameter sds_id a chunked data set according to the chunking and compression information provided in the parameters cdef and flag in C, and in the parameters comp_type and comp_prm in Fortran. Note that chunking and unlimited dimension are not supported together; SDsetchunk will fail if the dataset has an unlimited dimension.
|
|
|
C only:
|
|
|
The parameter flag specifies the type of the data set, i.e., if the data set is chunked or chunked and compressed with either RLE, Skipping Huffman, GZIP, Szip, or NBIT compression methods. Valid values of flag are as follows:
HDF_CHUNK for a chunked data set with no compression
HDF_CHUNK | HDF_COMP for a chunked data set compressed with RLE, Skipping Huffman, GZIP, or Szip compression methods
HDF_CHUNK | HDF_NBIT for a chunked and NBIT-compressed data set
|
|
|
Chunking and compression information are passed in the parameter cdef. The parameter cdef has a type of HDF_CHUNK_DEF , defined in the HDF library as follows:
|
|
|
typedef union hdf_chunk_def_u
{
int32 chunk_lengths[2]; /* chunk lengths along each dim */
struct
{
int32 chunk_lengths[2];
int32 comp_type; /* compression type */
struct comp_info cinfo;
} comp;
struct
{
int32 chunk_lengths[2];
intn start_bit;
intn bit_len;
intn sign_ext;
intn fill_one;
} nbit;
} HDF_CHUNK_DEF
|
|
|
There are three pieces of chunking and compression information which should be specified: chunking dimensions, compression type, and, if needed, compression parameters.
|
|
|
If the data set is chunked, i.e., flag value is HDF_CHUNK , then chunk_lengths[] elements of cdef union (cdef.chunk_lengths[] ) have to be initialized to the chunk dimensions.
|
|
|
If the data set is chunked and compressed using RLE, Skipping Huffman, Szip, or GZIP methods (i.e., flag value is set up to HDF_CHUNK | HDF_COMP ), then the elements chunk_lengths[] of the structure comp in the union cdef (cdef.comp.chunk_lengths[] ) have to be initialized to the chunk dimensions.
|
|
|
If the data set is chunked and NBIT compression is applied (i.e., flag values is set up to HDF_CHUNK | HDF_NBIT ), then the elements chunk_lengths[] of the structure nbit in the union cdef (cdef.nbit.chunk_lengths[] ) have to be initialized to the chunk dimensions.
|
|
|
Compression types are passed in the field comp_type of the structure cinfo , which is an element of the structure comp in the union cdef (cdef.comp.cinfo.comp_type ). Refer to the SDsetcompress page in this manual for the definition of structure comp_info . Valid compression methods are:
COMP_CODE_NONE for no compression
COMP_CODE_RLE for RLE run-length encoding
COMP_CODE_SKPHUFF for Skipping Huffman compression
COMP_CODE_DEFLATE for GZIP compression
COMP_CODE_SZIP for Szip compression
|
|
|
For Skipping Huffman and GZIP compression, parameters are passed in corresponding fields of the structure cinfo .
o Specify skipping size for Skipping Huffman compression in the field cdef.comp.cinfo.skphuff.skp_size , which must be an integer of value 1 or greater.
o Specify the deflate level for GZIP compression in the field cdef.comp.cinfo.deflate_level . Valid deflate level values are integers between 0 and 9 inclusive.
o Specify the options mask and the number of pixels per block for Szip compression in the fields c_info.szip.options_mask and c_info.szip.pixels_per_block , respectively.
Refer to the SDsetcompress entry in this reference manual for details on these parameters.
|
|
|
NBIT compression parameters are specified in the fields start_bit , bit_len , sign_ext , and fill_one in the structure nbit of the union cdef.
|
|
|
Fortran only:
|
|
|
The dim_length array specifies the chunk dimensions.
|
|
|
The comp_type parameter specifies the compression type. Valid compression types and their values are defined in the hdf.inc file, and are listed below:
|
|
|
COMP_CODE_NONE (or 0 ) for no compression
COMP_CODE_RLE (or 1 ) for RLE compression algorithm
COMP_CODE_NBIT (or 2 ) for NBIT compression algorithm
COMP_CODE_SKPHUFF (or 3 ) for Skipping Huffman compression
COMP_CODE_DEFLATE (or 4 ) for GZIP compression algorithm
COMP_CODE_SZIP (or 5 ) for Szip compression algorithm
|
|
|
The comp_prm(1) parameter specifies the skipping size for the Skipping Huffman compression method and the deflate level for the GZIP compression method. The skipping size value must be 1 or greater; the deflate level must be an integer value between 0 and 9 inclusive.
|
|
|
For NBIT compression, the four elements of the array comp_prm correspond to the four NBIT compression parameters listed in the structure nbit . The value of comp_prm(1) should be set to the value of start_bit , the value of comp_prm(2) should be set to the value of bit_len , the value of comp_prm(3) should be set to the value of sign_ext , and the value of comp_prm(4) should be set to the value of fill_one . See the HDF_CHUNK_DEF union description and the description of SDsetnbitdataset function for NBIT compression parameters definitions.
|
|
|
For Szip compression, the first two elements of the array comp_prm correspond to the first two Szip compression parameters listed in the structure szip . The value of comp_prm(1) should be set to the value of option_mask and the value of comp_prm(2) should be set to the value of pixels_per_block .
|
|
FORTRAN
|
integer sfschnk(sds_id, dim_length, comp_type, comp_prm)
|
|
|
integer sds_id, dim_length, comp_type, comp_prm(*)
|
[SD Interface][Top]
SDsetchunkcache/sfscchnk
intn SDsetchunkcache(int32 sds_id, int32 maxcache, int32 flag)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
maxcache
|
IN:
|
Maximum number of chunks in the cache
|
|
flag
|
IN:
|
Flag determining the behavior of the routine
|
|
Purpose
|
Sets the size of the chunk cache.
|
|
Return value
|
Returns the maximum number of chunks that can be cached (the value of the parameter maxcache) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDsetchunkcache sets the size of the chunk cache to the value of the parameter maxcache.
|
|
|
Currently the only allowed value of the parameter flag is 0 , which designates default operation.
|
|
|
By default, when a generic data set is promoted to be a chunked data set, the parameter maxcache is set to the number of chunks along the fastest changing dimension and a cache for the chunks is created.
|
|
|
If the chunk cache is full and the value of the parameter maxcache is greater then the current maxcache value, then the chunk cache is reset to the new value of maxcache. Otherwise the chunk cache remains at the current value of maxcache. If the chunk cache is not full, then the chunk cache is set to the new value of maxcache only if the new maxcache value is greater than the current number of chunks in the cache.
|
|
|
Do not set the value of maxcache to be less than the number of chunks along the fastest-changing dimension of the biggest slab to be written or read via SDreaddata or SDwritedata. Doing this will cause internal thrashing. See the section on chunking in Chapter 14, "HDF Performance Issues" in the HDF User's Guide, for more information on this.
|
|
FORTRAN
|
integer sfscchnk(sds_id, maxcache, flag)
|
|
|
integer sds_id, maxcache, flag
|
[SD Interface][Top]
SDsetcompress/sfscompress
intn SDsetcompress(int32 sds_id, int32 comp_type, comp_info *c_info)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
comp_type
|
IN:
|
Compression method
|
|
C only:
|
|
|
|
c_info
|
IN:
|
Pointer to the comp_info union
|
|
Fortran only:
|
|
|
|
comp_prm
|
IN:
|
Compression parameters array
|
|
Purpose
|
Compresses the data set with the specified compression method.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDsetcompress compresses the data set identified by the parameter sds_id according to the compression method specified by the parameter comp_type and the compression information specified by the parameter c_info in C and comp_prm in Fortran. SDsetcompress prepares compression information to be used uring the next call to SDwritedata.
|
|
|
SDsetcompress is a simplified interface to the HCcreate routine and should be used instead of HCcreate, unless the user is familiar with working with the lower-level routines.
|
|
|
The parameter comp_type is the compression type definition and is set to one of the following:
COMP_CODE_NONE for no compression
COMP_CODE_RLE for run-length encoding (RLE)
COMP_CODE_SKPHUFF for Skipping Huffman
COMP_CODE_DEFLATE for GZIP compression
COMP_CODE_SZIP for Szip compression
|
|
|
The parameter c_info is a pointer to a union structure of type comp_info . This union structure is defined as follows:
|
|
|
typedef union tag_comp_info
{
struct
{
/* Not used by SDsetcompress */
} jpeg;
struct
{
/* Not used by SDsetcompress */
} nbit;
struct
{ /* struct to contain info about how to compress size of the
elements when skipping */
intn skp_size;
} skphuff;
struct
{ /* struct to contain info about how to compress or decompress
gzip encoded dataset how hard to work when compressing data*/
intn level;
} deflate;
struct
{ /* struct to contain info about how to compress or decompress
szip encoded dataset*/
int32 options_mask; /* IN */
int32 pixels_per_block; /* IN */
int32 pixels_per_scanline; /* OUT */
int32 bits_per_pixel; /* OUT */
int32 pixels; /* OUT */
} szip;
} comp_info;
|
|
|
The skipping size for the Skipping Huffman algorithm must be 1 or greater and is specified in the field c_info.skphuff.skp_size in C and in the parameter comp_prm(1) in Fortran.
|
|
|
The deflate level for the GZIP algorithm is specified in the c_info.deflate.level field in C and in the parameter comp_prm(1) in Fortran. Valid values are integers between 0 and 9 inclusive.
|
|
|
The Szip options mask and the number of pixels per block in a chunked and Szip-compressed dataset are specified in c_info.szip.options_mask and c_info.szip.pixels_per_block , respectively.
|
|
|
The options mask can contain either of the following values:
SZ_EC_OPTION_MASK - Specifies entropy coding method
SZ_NN_OPTION_MASK - Specifies nearest neighbor coding method
|
|
|
The following guidelines may be helpful in selecting the encoding method:
o The entropy coding method, the EC option specified by SZ_EC_OPTION_MASK , is best suited for data that has been processed. The EC method works best for small numbers.
o The nearest neighbor coding method, the NN option specified by SZ_NN_OPTION_MASK , preprocesses the data then applies the EC method as above.
Other factors may affect results, but the above criteria provide a good starting point for optimizing data compression.
|
|
|
The Szip values of the number of pixels per scanline, the number of bits in a pixel, and the number of pixels in an image, are computed by the HDF4 library and provided to the user in c_info.szip.pixels_per_scanline , c_info.szip.bits_per_pixel , and c_info.szip.pixels , respectively.
|
|
|
SDsetcompress will succeed in setting Szip compression for a dataset only if the Szip library is available and configured for encoding, i.e., HCget_config_info must return the flag COMP_DECODER_ENABLED|COMP_ENCODER_ENABLED in compression_config_info.
|
|
Note
|
Regarding Szip usage and licensing:
See http://www.hdfgroup.org/doc_resource/SZIP/ for information regarding the use of Szip in HDF products and Szip licensing.
|
|
FORTRAN
|
integer sfscompress(sds_id, comp_type, comp_prm)
|
|
|
integer sds_id, comp_type, comp_prm(*)
|
[SD Interface][Top]
SDsetdatastrs/sfsdtstr
intn SDsetdatastrs(int32 sds_id, char *label, char *unit, char *format, char *coordsys)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
label
|
IN:
|
Label (predefined attribute)
|
|
unit
|
IN:
|
Unit (predefined attribute)
|
|
format
|
IN:
|
Format (predefined attribute)
|
|
coordsys
|
IN:
|
Coordinate system (predefined attribute)
|
|
Purpose
|
Sets the predefined attributes for a data set.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDsetdatastrs sets the predefined attributes of the data set, identified by sds_id, to the values specified in the parameters label, unit, format and coordsys. The predefined attributes are label, unit, format, and coordinate system. If the user does not want a string returned, the corresponding parameter can be set to NULL in C and an empty string in Fortran.
|
|
|
For more information about predefined attributes, refer to Section 3.10, "Predefined Attributes." of the HDF User's Guide.
|
|
FORTRAN
|
integer function sfsdtstr(sds_id, label, unit, format, coordsys)
|
|
|
integer sds_id
|
|
|
character*(*) label, unit, format, coordsys
|
[SD Interface][Top]
SDsetdimname/sfsdmname
intn SDsetdimname(int32 dim_id, char *dim_name)
|
dim_id
|
IN:
|
Dimension identifier returned by SDgetdimid
|
|
dim_name
|
IN:
|
Name of the dimension
|
|
Purpose
|
Assigns a name to a dimension.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDsetdimname sets the name of the dimension identified by the parameter dim_id to the value specified in the parameter dim_name. Dimensions that are not explicitly named by the user will have the default name of "fakeDim[x] " specified by the HDF library, where [x ] denotes the dimension index.
|
|
|
If another dimension exists with the same name it is assumed that they refer to the same dimension object and changes to one will be reflected in the other. If the dimension with the same name has a different size, an error condition will result.
|
|
|
The length of the parameter dim_name can be at most H4_MAX_NC_NAME (256 ) characters.
|
|
|
Naming dimensions is optional but encouraged.
|
|
Note
|
Regarding naming a dimension the same as an SDS' name
HDF4 allows a dimension and a one-dimensional SDS to be given the same name. Prior to HDF4.2r2, however, the library did not always adequately track object types; when a dimension and a one-dimensional SDS shared a name, writing to the SDS or the dimension could cause data corruption to the other. The corrupted data was unrecoverable.
|
|
|
This problem was fixed in Release 4.2r2 and such data corruption will not occur in files created with a 4.2r2 or later library. Note, however, that the fix is effective only in new files; a dimension and a one-dimensional SDS of the same name that were created with a pre-4.2r2 HDF4 Library remain vulnerable to data corruption if an application is unaware of the potential conflict. To safely handle pre-4.2r2 files, the library now provides two functions, SDgetnumvars_byname and SDnametoindices. SDgetnumvars_byname can be used to determine whether a name is unique. If the function reports one ('1') variable by that name, the name is unique and no further precaution needs to be taken. If the name is not unique, i.e., the number of variables by that name is greater than one, SDnametoindices must then be used to retrieve the index and the type of each variable with that name. The desired variable can then can be safely selected via its index. These functions are described in detail in this manual and the HDF User's Guide.
|
|
|
A similar problem is possible when a multi-dimensional SDS and a dimension are created with the same name by a pre-4.2r2 library. The HDF Group has not seen such a failure, however, and it is thought to be very unlikely. Note that the fix introduced in Release 4.2r2 also prevents data corruption from happening for this situation even though the data was created with libraries prior to 4.2r2, assuming no corruption had yet occurred.
|
|
FORTRAN
|
integer function sfsdmname(dim_id, dim_name)
|
|
|
integer dim_id
|
|
|
character*(*) dim_name
|
[SD Interface][Top]
SDsetdimscale/sfsdscale
intn SDsetdimscale(int32 dim_id, int32 count, int32 data_type, VOIDP data)
|
dim_id
|
IN:
|
Dimension identifier returned by SDgetdimid
|
|
count
|
IN:
|
Total number of values along the dimension
|
|
data_type
|
IN:
|
Data type of the values along the dimension
|
|
data
|
IN:
|
Value of each increment along the dimension
|
|
Purpose
|
Stores the values of a dimension.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDsetdimscale stores scale information for the dimension identified by the parameter dim_id. Note that it is possible to store dimension scale values without naming the dimension.
|
|
|
For fixed-size arrays, the value of count must be equal to the the dimension size or the routine will fail.
|
|
|
Note that, due to the existence of the parameter data_type, the dimension scales need not have the same data type as the data set.
|
|
|
Note that if SDsetdimscale is called and SDsetdimname is subsequently called for the same dimension, SDsetdimscale must be called again to reassociate the scale with the new name.
|
|
|
Note that if this dimension has the same name as another data set, SDsetdimscale might overwrite the data set. This was a bug in the HDF4 library prior to 4.2r2. For details, please refer to the note " Regarding naming a dimension the same as an SDS' name" in the SDsetdimname page.
|
|
|
When the uniqueness of the name is unknown, SDgetnumvars_byname can be used to get the number of data sets (or variables, which includes both data sets and coordinate variables) with the same name. SDnametoindices can then be used to get a list of structures containing the indices and the types of all the variables of that same name.
|
|
FORTRAN
|
integer function sfsdscale(dim_id, count, data_type, data)
|
|
|
integer dim_id, count, data_type
|
|
|
<valid data type> data(*)
|
[SD Interface][Top]
SDsetdimstrs/sfsdmstr
intn SDsetdimstrs(int32 dim_id, char *label, char *unit, char *format)
|
dim_id
|
IN:
|
Dimension identifier returned by SDgetdimid
|
|
label
|
IN:
|
Label (predefined attribute)
|
|
unit
|
IN:
|
Unit (predefined attribute)
|
|
format
|
IN:
|
Format (predefined attribute)
|
|
Purpose
|
Sets the predefined attribute of a dimension.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDsetdimstrs sets the predefined attribute (label, unit, and format) for a dimension and its scale to the values specified in the parameters label, unit and format. If a parameter is set to NULL in C and an empty string in Fortran, then the attribute corresponding to that parameter will not be written. For more information about predefined attributes, refer to Section 3.10, "Predefined Attributes." of the HDF User's Guide.
|
|
FORTRAN
|
integer function sfsdmstr(dim_id, label, unit, format)
|
|
|
integer dim_id
|
|
|
character*(*) label, unit, format
|
[SD Interface][Top]
SDsetdimval_comp/sfsdmvc
intn SDsetdimval_comp(int32 dim_id, intn comp_mode)
|
dim_id
|
IN:
|
Dimension identifier returned by SDgetdimid
|
|
comp_mode
|
IN:
|
Compatibility mode to be set
|
|
Purpose
|
Determines whether a dimension will have the old and new representations or the new representation only.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDsetdimval_comp sets the compatibility mode specified by the comp_mode parameter for the dimension identified by the dim_id parameter. The two possible compatibility modes are: "backward-compatible" mode, which implies that the old and new dimension representations are written to the file, and "backward-incompatible" mode, which implies that only the new dimension representation is written to the file.
|
|
|
Unlimited dimensions are always backward-compatible, therefore SDsetdimval_comp takes no action on unlimited dimensions.
|
|
|
As of HDF version 4.1r1, the default mode is backward-incompatible. Subsequent calls to SDsetdimval_comp will override the settings established in previous calls to the routine.
|
|
|
The comp_mode parameter can be set to SD_DIMVAL_BW_COMP (or 1 ), which specifies backward-compatible mode, or SD_DIMVAL_BW_INCOMP (or 0 ), which specifies backward-incompatible mode.
|
|
FORTRAN
|
integer function sfsdmvc(dim_id, comp_mode)
|
|
|
integer dim_id, comp_mode
|
[SD Interface][Top]
SDsetexternalfile/sfsextf
intn SDsetexternalfile(int32 sds_id, char *filename, int32 offset)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
filename
|
IN:
|
Name of the external file
|
|
offset
|
IN:
|
Number of bytes from the beginning of the external file to where the data will be written
|
|
Purpose
|
Stores data in an external file.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDsetexternalfile allows users to move the actual data values (i.e., not metadata) of a data set, sds_id, into the external data file named by the parameter filename, and started at the offset specified by the parameter offset. The metadata remains in the original file. Note that this routine works only with HDF post-version 3.2 files.
|
|
|
Data can only be moved once for any given data set, and it is the user's responsibility to make sure the external data file is kept with the "original" file.
|
|
|
If the data set already exists, its data will be moved to the external file. Space occupied by the data in the primary file will not be released. To release the space in the primary file use the hdfpack command-line utility. If the data set does not exist, its data will be written to the external file during the consequent calls to SDwritedata.
|
|
|
See the reference manual entries for HXsetcreatedir and HXsetdir for more information on the options available for accessing external files.
|
|
FORTRAN
|
integer function sfsextf(sds_id, file_name, offset)
|
|
|
integer sds_id, offset
|
|
|
character*(*) file_name
|
[SD Interface][Top]
SDsetfillmode/sfsflmd
intn SDsetfillmode(int32 sd_id, intn fill_mode)
|
sd_id
|
IN:
|
SD interface identifier returned by SDstart
|
|
fill_mode
|
IN:
|
Fill mode
|
|
Purpose
|
Sets the current fill mode of a file.
|
|
Return value
|
Returns the fill mode value before it was reset if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDsetfillmode applies the fill mode specified by the parameter fill_mode to all data sets contained in the file identified by the parameter sd_id.
|
|
|
Possible values of fill_mode are SD_FILL (or 0 ) and SD_NOFILL (or 256 ). SD_FILL is the default mode, and indicates that fill values will be written when the data set is created. SD_NOFILL indicates that fill values will not be written.
|
|
|
When a data set without unlimited dimensions is created, by default the first SDwritedata call will fill the entire data set with the default or user-defined fill value (set by SDsetfillvalue). In data sets with an unlimited dimension , if a new write operation takes place along the unlimited dimension beyond the last location of the previous write operation, the array locations between these written areas will be initialized to the user-defined fill value, or the default fill value if a user-defined fill value has not been specified.
|
|
|
If it is certain that all data set values will be written before any read operation takes place, there is no need to write the fill values. Simply call SDsetfillmode with fill_mode value set to SD_NOFILL , which will eliminate all fill value write operations to the data set. For large data sets, this can improve the speed by almost 50%.
|
|
FORTRAN
|
integer function sfsflmd(sd_id, fill_mode)
|
|
|
integer sd_id, fill_mode
|
[SD Interface][Top]
SDsetfillvalue/sfsfill/sfscfill
intn SDsetfillvalue(int32 sds_id, VOIDP fill_value)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
fill_value
|
IN:
|
Fill value
|
|
Purpose
|
Sets the fill value for a data set.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDsetfillvalue sets the fill value specified by the fill_value parameter for the data set identified by the sds_id parameter.
|
|
|
The fill value is assumed to have the same data type as the data set.
|
|
|
It is recommended to call SDsetfillvalue before writing data.
|
|
FORTRAN
|
integer function sfsfill(sds_id, fill_value)
|
|
|
integer sds_id
|
|
|
<valid numeric data type> fill_value
|
|
|
|
|
|
integer function sfscfill(sds_id, fill_value)
|
|
|
integer sds_id
|
|
|
character*(*) fill_value
|
[SD Interface][Top]
SDsetnbitdataset/sfsnbit
intn SDsetnbitdataset(int32 sds_id, intn start_bit, intn bit_len, intn sign_ext, intn fill_one)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
start_bit
|
IN:
|
Leftmost bit of the field to be written
|
|
bit_len
|
IN:
|
Length of the bit field to be written
|
|
sign_ext
|
IN:
|
Sign extend specifier
|
|
fill_one
|
IN:
|
Background bit specifier
|
|
Purpose
|
Specifies a non-standard bit length for the data set values.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDsetnbitdataset allows the HDF user to specify that the data set identified by the parameter sds_id contains data of a non-standard length defined by the parameters start_bit and bit_len. Additional information about the non-standard bit length decoding are specified in the parameters sign_ext and fill_one.
|
|
|
Any length between 1 and 32 bits can be specified. After SDsetnbitdataset has been called for the data set array, any read or write operations will involve a conversion between the new data length of the data set array and the data length of the read or write buffer.
|
|
|
Bit lengths of all data types are counted from the right of the bit field starting with 0. In a bit field containing the values 01111011 , bits 2 and 7 are set to 0 and all the other bits are set to 1 .
|
|
|
The start_bit parameter specifies the leftmost position of the variable-length bit field to be written. For example, in the bit field described in the preceding paragraph a start_bit parameter set to 4 would correspond to the fourth bit value of 1 from the right.
|
|
|
The bit_len parameter specifies the number of bits of the variable-length bit field to be written. This number includes the starting bit and the count proceeds toward the right end of the bit field - toward the lower-bit numbers. For example, starting at bit 5 and writing 4 bits of the bit field described in the preceding paragraph would result in the bit field 1110 being written to the data set. This would correspond to a start_bit value of 5 and a bit_len value of 4 .
|
|
|
The sign_ext parameter specifies whether to use the leftmost bit of the variable-length bit field to sign-extend to the leftmost bit of the data set data. For example, if 9-bit signed integer data is extracted from bits 17-25 and the bit in position 25 is 1 , then when the data is read back from disk, bits 26-31 will be set to 1 . Otherwise bit 25 will be 0 and bits 26-31 will be set to 0 . The sign_ext parameter can be set to TRUE (or 1 ) or FALSE (or 0 ) - specify TRUE to sign-extend.
|
|
|
The fill_one specifies whether to fill the "background" bits with the value 1 or 0 . This parameter can also be set to TRUE or FALSE .
|
|
|
The "background" bits of a variable-length data set are the bits that fall outside of the variable-length bit field stored on disk. For example, if five bits of an unsigned 16-bit integer data set located in bits 5 to 9 are written to disk with the fill_one parameter set to TRUE (or 1 ), then when the data is reread into memory bits 0 to 4 and 10 to 15 would be set to 1 . If the same 5-bit data was written with a fill_one value of FALSE (or 0 ), then bits 0 to 4 and 10 to 15 would be set to 0 .
|
|
|
This bit operation is performed before the sign-extend bit-filling. For example, using the sign_ext example above, bits 0 to 16 and 26 to 31 will first be set to the "background" bit value, and then bits 26 to 31 will be set to 1 or 0 based on the value of the 25th bit.
|
|
FORTRAN
|
integer function sfsnbit(sds_id, start_bit, bit_len, sign_ext, fill_one)
|
|
|
integer sds_id, start_bit, bit_len, sign_ext, fill_one
|
[SD Interface][Top]
SDsetrange/sfsrange
intn SDsetrange(int32 sds_id, VOIDP max, VOIDP min)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
max
|
IN:
|
Maximum value of the range
|
|
min
|
IN:
|
Minimum value of the range
|
|
Purpose
|
Sets the maximum and minimum range values for a data set.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDsetrange sets the maximum and minimum range values of the data set identified by the parameter sds_id with the values of the parameters max and min. The term "range" is used here to describe the range of numeric values stored in a data set.
|
|
|
It is assumed that the data type for the maximum and minimum range values are the same as the data type of the data.
|
|
|
This routine does not compute the maximum and minimum range values, it only stores the values as given. As a result, the maximum and minimum range values may not always reflect the actual maximum and minimum range values in the data set data.
|
|
FORTRAN
|
integer function sfsrange(sds_id, max, min)
|
|
|
integer sds_id
|
|
|
<valid numeric data type> max, min
|
[SD Interface][Top]
SDstart/sfstart
int32 SDstart(char *filename, int32 access_mode)
|
filename
|
IN:
|
Name of the HDF file
|
|
access_mode
|
IN:
|
The file access mode in effect during the current session
|
|
Purpose
|
Opens an HDF file and initializes an SD interface.
|
|
Return value
|
Returns an SD interface identifier if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDstart opens the file with the name specified by the parameter filename, with the access mode specified by the parameter access_mode, and returns an SD interface identifier (sd_id). This routine must be called for each file before any other SD calls can be made on that file.
|
|
|
The type of identifier returned by SDstart is currently not the same as the identifier returned by Hopen. As a result, the SD interface identifiers (sd_id) returned by this routine are not understood by other HDF interfaces.
|
|
|
To mix SD API calls and other HDF API calls, use SDstart and Hopen on the same file. SDstart must precede all SD calls, and Hopen must precede all other HDF function calls. To terminate access to the file, use SDend to dispose of the SD interface identifier, sd_id, and Hclose to dispose of the file identifier, file_id.
|
|
|
The file identified by the parameter filename can be any one of the following: an XDR-based netCDF file, "old-style" DFSD file or a "new-style" SD file.
|
|
|
The value of the parameter access_mode can be one of the following:
|
|
|
DFACC_READ - Open existing file for read-only access. If the file does not exist, specifying this mode will cause SDstart to return FAIL (or -1 ).
DFACC_WRITE - Open existing file for read and write access. If the file does not exist, specifying this mode will cause SDstart to return FAIL (or -1 ).
DFACC_CREATE - Create a new file with read and write access. If the file has already existed, its contents will be replaced.
|
|
Note
|
Starting from HDF 4.2r2, the maximum number of open files is no longer limited to 32. It can be up to what the system allowed.
|
|
Note
|
It has been reported that opening/closing file in loops is very slow; thus, it is not recommended to perform such operations too many times, particularly, when data is being added to the file between opening/closing.
|
|
FORTRAN
|
integer function sfstart(filename, access_mode)
|
|
|
character*(*) filename
|
|
|
integer access_mode
|
[SD Interface][Top]
SDwritechunk/sfwchnk/sfwcchnk
intn SDwritechunk(int32 sds_id, int32 *origin, VOIDP datap)
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
origin
|
IN:
|
Origin of the chunk to be written
|
|
datap
|
IN:
|
Buffer for the chunk data to be written
|
|
Purpose
|
Writes a data chunk to a chunked data set.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDwritechunk writes the entire chunk of data stored in the buffer datap to the chunked data set identified by the parameter sds_id. Writing starts at the location specified by the parameter origin. SDwritechunk is used when an entire chunk of data is to be written. SDwritedata is used when the write operation is to be done regardless of the chunking scheme used in the data set.
|
|
|
SDwritechunk will return FAIL (or -1 ) when an attempt is made to use it to write to a non-chunked data set.
|
|
|
The parameter origin specifies the coordinates of the chunk according to the chunk position in the overall chunk array. Refer to Chapter 3, "Scientific Data Sets (SD API)" in the HDF User's Guide, for a description of the organization of chunks in a data set.
|
|
|
Note that there are two FORTRAN-77 versions of this routine; one for numeric data (sfwchnk) and one for character data (sfwcchnk).
|
|
Note
|
Regarding Szip-compressed data: SDwritechunk can succeed only when the available Szip library is configured for encoding/decoding, i.e., when HCget_config_info returns COMP_ENCODER_ENABLED |COMP_DECODER_ENABLED in compression_config_info.
See the SDgetcompinfo and HCget_config_info entries in this reference manual for further discussion of compression methods and configuration.
|
|
Note
|
Regarding Szip usage and licensing:
See http://www.hdfgroup.org/doc_resource/SZIP/ for information regarding the use of Szip in HDF products and Szip licensing.
|
|
FORTRAN
|
integer sfwchnk(sds_id, origin, datap)
|
|
|
integer sds_id, origin
|
|
|
<valid numeric data type> datap(*)
|
|
|
|
|
|
integer sfwcchnk(sds_id, origin, datap)
|
|
|
integer sds_id, origin
|
|
|
character*(*) datap(*)
|
[SD Interface][Top]
SDwritedata/sfwdata/sfwcdata
intn SDwritedata(int32 sds_id, int32 start[], int32 stride[], int32 edge[], VOIDP buffer )
|
sds_id
|
IN:
|
Data set identifier returned by SDcreate or SDselect
|
|
start
|
IN:
|
Array specifying the starting location of the data to be written
|
|
stride
|
IN:
|
Array specifying the number of values to skip along each dimension
|
|
edge
|
IN:
|
Array specifying the number of values to be written along each dimension
|
|
buffer
|
IN:
|
Buffer for the values to be written
|
|
Purpose
|
Writes a subsample of data to a data set or to a coordinate variable.
|
|
Return value
|
Returns SUCCEED (or 0 ) if successful and FAIL (or -1 ) otherwise.
|
|
Description
|
SDwritedata writes the specified subsample of data to the data set or coordinate variable identified by the parameter sds_id. The data is written from the buffer buffer. The subsample is defined by the parameters start, stride and edge.
|
|
|
The array start specifies the starting position from where the subsample will be written. Valid values of each element in the array start are from 0 to the size of the corresponding dimension of the data set - 1. The dimension sizes are returned by SDgetinfo.
|
|
|
The array edge specifies the number of values to write along each data set dimension.
|
|
|
The array stride specifies the writing pattern along each dimension. For example, if one of the elements of the array stride is 1, then every element along the corresponding dimension of the data set will be written. If one of the elements of the array stride is 2, then every other element along the corresponding dimension of the data set will be written, and so on. Specifying stride value of NULL in the C interface or setting all values of the array stride to 1 in either interface specifies the contiguous writing of data. If all values in the array stride are set to 0, SDwritedata returns FAIL (or -1 ).
|
|
|
When writing data to a chunked data set using SDwritedata, consideration should be given to be issues presented in the section on chunking in Chapter 3, "Scientific Data Sets (SD API)" and Chapter 14, "HDF Performance Issues" in the HDF User's Guide.
|
|
|
Note that there are two FORTRAN-77 versions of this routine; sfwdata and sfwcdata. The sfwdata routine writes numeric data and sfwcdata writes character scientific data.
|
|
Note
|
Regarding an important difference between the SD and GR interfaces: The SD and GR interfaces differ in the correspondence between the dimension order in parameter arrays such as start, stride, edge, and dimsizes and the dimension order in the data array. See the SDreaddata and GRreadimage reference manual pages for discussions of the SD and GR approaches, respectively.
|
|
|
When writing applications or tools to manipulate both images and two-dimensional SDs, this crucial difference between the interfaces must be taken into account. While the underlying data is stored in row-major order in both cases, the API parameters are not expressed in the same way. Consider the example of an SD data set and GR image that are stored as identically-shaped arrays of X columns by Y rows and accessed via the SDreaddata and GRreadimage functions, respectively. Both functions take the parameters start, stride, and edge.
o For SDreaddata, those parameters are expressed in (y,x) or [row,column] order. For example, start[0] is the starting point in the Y dimension and start[1] is the starting point in the X dimension. The same ordering holds true for all SD data set manipulation functions.
o For GRreadimage, those parameters are expressed in (x,y) or [column,row] order. For example, start[0] is the starting point in the X dimension and start[1] is the starting point in the Y dimension. The same ordering holds true for all GR functions manipulating image data.
|
|
Note
|
Regarding compressed data sets:
If a data set is compressed, it may be necessary to determine whether the compression method is available on the current system and configured so that data can be encoded before being written. The compression method can be determined through the use of SDgetcompinfo and the configuration of that method on the current system through HCget_config_info.
|
|
Note
|
Regarding Szip-compressed data:
SDwritedata can succeed only when the available Szip library is configured for encoding/decoding, i.e., when HCget_config_info returns COMP_ENCODER_ENABLED|COMP_DECODER_ENABLED in compression_config_info.
|
|
Note
|
Regarding Szip usage and licensing:
See http://www.hdfgroup.org/doc_resource/SZIP/ for information regarding the use of Szip in HDF products and Szip licensing.
|
|
FORTRAN
|
integer function sfwdata(sds_id, start, stride, edge, buffer)
|
|
|
integer sds_id
|
|
|
integer start(*), stride(*), edge(*)
|
|
|
<valid numeric data type> buffer(*)
|
|
|
|
|
|
integer function sfwcdata(sds_id, start, stride, edge, buffer)
|
|
|
integer sds_id
|
|
|
integer start(*), stride(*), edge(*)
|
|
|
character*(*) buffer(*)
|