HDF5 documents and links 
Introduction to HDF5 
HDF5 User’s Guide 
Other High-level API documents
In the HDF5 Reference Manual  
H5DS   H5IM   H5LT   H5PT   H5TB   Optimized 
H5   H5A   H5D   H5E   H5F   H5G   H5I   H5L  
H5O   H5P   H5PL   H5R   H5S   H5T   H5Z  
Tools   Datatypes   Fortran  

H5DS: HDF5 Dimension Scales

HDF5 Dimension Scale API Reference

Programming Hints:

To use any of these functions or subroutines, you must first include the relevant include file (C) or module (Fortran) in your application.

The following line includes the HDF5 Dimension Scale package, H5DS, in C applications:
         #include "hdf5_hl.h"

This line includes the H5DS module in Fortran applications:
         use h5ds

The C Interfaces:
 

The FORTRAN90 Interfaces:
 


Name: H5DSset_scale
Signature:
herr_t H5DSset_scale(hid_t dsid, char *dimname)
Purpose:
Convert dataset dsid to a dimension scale, with optional name, dimname.
Description:
The dataset dsid is converted to a Dimension Scale dataset, as defined above. Creates the CLASS attribute, set to the value "DIMENSION_SCALE" and an empty REFERENCE_LIST attribute, as described in “HDF5 Dimension Scale Specification” (PDF, see section 4.2).

If dimname is specified, then an attribute called NAME is created, with the value dimname.

Fails if:

If the dataset was created with the Table, Image, or Palette interface [9], it is not recommended to convert to a Dimension Scale. (These Datasets will have a CLASS Table, Image, or Palette.)

Parameters:
Returns:
Zero if succeed, negative if fail.

 

Fortran90 Interface: H5DSset_scale_f
Convert dataset dsid to a Dimension Scale, with optional dimension name dimname.
SUBROUTINE H5DSset_scale_f(dsid, errcode, dimname)
    IMPLICIT NONE
    INTEGER(hid_t),   INTENT(in) :: dsid               ! The dataset to be made 
                                                       ! a Dimension Scale
    INTEGER :: errcode                                 ! Error code
    CHARACTER(LEN=*), INTENT(in), OPTIONAL :: dimname  ! The dimension name
END SUBROUTINE H5DSset_scale_f   

 


Name: H5DSattach_scale
Signature:
herr_t H5DSattach_scale(hid_t did, hid_t dsid, unsigned int idx)
Purpose:
Attach dimension scale dsid to dimension idx of dataset did.
Description:
Define Dimension Scale dsid to be associated with dimension idx of Dataset did.

Entries are created in the DIMENSION_LIST and REFERENCE_LIST attributes, as defined in section 4.2.

Fails if:

Note: The Dimension Scale dsid can be attached to the same dimension more than once, which has no effect.

Parameters:
Returns:
Zero if succeed, negative if fail.

 

Fortran90 Interface: H5DSattach_scale_f
Attach Dimension Scale dsid to dimension idx of dataset did.
SUBROUTINE H5DSattach_scale_f(did, dsid, idx, errcode)
    IMPLICIT NONE
    INTEGER(hid_t), INTENT(in) :: did     ! The dataset
    INTEGER(hid_t), INTENT(in) :: dsid    ! The scale to be attached 
    INTEGER       , INTENT(in) :: idx     ! The dimension of did that 
                                          ! dsid is associated with.
    INTEGER                    :: errcode ! Error code
END SUBROUTINE H5DSattach_scale_f   

 


Name: H5DSdetach_scale
Signature:
herr_t H5DSdetach_scale(hid_t did, hid_t dsid, unsigned int idx)
Purpose:
Detach dimension scale dsid from the dimension idx of Dataset did.
Description:
If possible, deletes association of Dimension Scale dsid with dimension idx of Dataset did. This deletes the entries in the DIMENSION_LIST and REFERENCE_LIST attributes, as defined in section 4.2.

Fails if:

Note that a scale may be associated with more than dimension of the same dataset. If so, the detach operation only deletes one of the associations, for did.

Parameters:
Returns:
Zero if succeed, negative if fail.

 

Fortran90 Interface: H5DSdetach_scale_f
Detach Dimension Scale dsid from the dimension idx of dataset did.
SUBROUTINE H5DSdetach_scale_f(did, dsid, idx, errcode)
    IMPLICIT NONE

    INTEGER(hid_t), INTENT(in) :: did     ! The dataset
    INTEGER(hid_t), INTENT(in) :: dsid    ! The scale to be detached 
    INTEGER       , INTENT(in) :: idx     ! The dimension of did to detach
    INTEGER                    :: errcode ! Error code
END SUBROUTINE H5DSdetach_scale_f

 


Name: H5DSis_attached
Signature:
htri_t H5DSis_attached(hid_t did, hid_t dsid, unsigned int idx)
Purpose:
Report if dimension scale dsid is currently attached to dimension idx of dataset did.
Description:
Report if dimension scale dsid is currently attached to dimension idx of dataset did.

Fails if:

Parameters:
Returns:
When successful, returns a positive value for TRUE or 0 (zero) for FALSE. Otherwise returns a negative value.

 

Fortran90 Interface: H5DSdetach_scale_f
Detach Dimension Scale dsid to dimension idx of dataset did.
SUBROUTINE H5DSdetach_scale_f(did, dsid, idx, errcode)
    IMPLICIT NONE
    INTEGER(hid_t), INTENT(in) :: did     ! The dataset
    INTEGER(hid_t), INTENT(in) :: dsid    ! The scale to be detached 
    INTEGER       , INTENT(in) :: idx     ! The dimension of did to detach
    INTEGER                    :: errcode ! Error code
END SUBROUTINE H5DSdetach_scale_f   

 


Name: H5DSiterate_scales
Signature:
herr_t H5DSiterate_scales(hid_t did, unsigned dim, int *idx, H5DS_iterate_t visitor, void *visitor_data)
Purpose:
Iterates the operation visitor through the scales attached to dimension dim.
Description:
H5DSiterate_scales iterates over the scales attached to dimension dim of dataset did. For each scale in the list, the visitor_data and some additional information, specified below, are passed to the visitor function. The iteration begins with the idx object in the group and the next element to be processed by the operator is returned in idx. If idx is NULL, then the iterator starts at the first group member; since no stopping point is returned in this case, the iterator cannot be restarted if one of the calls to its operator returns non-zero.

The prototype for H5DS_iterate_t is:
typedef herr_t (*H5DS_iterate_t)(hid_t did, unsigned dim, hid_t dsid, void *visitor_data);

The operation receives the Dimension Scale dataset identifier, dsid, and the pointer to the operator data passed in to H5DDiterate_scales, visitor_data.

The return values from an operator are:

H5DSiterate_scales assumes that the scales of the dimension identified by dim remain unchanged through the iteration. If the membership changes during the iteration, the function's behavior is undefined.

Parameters:
Returns:
Returns the return value of the last operator if it was non-zero, or zero if all scales were processed.

Name: H5DSset_label
Signature:
herr_t H5DSset_label(hid_t did, unsigned int idx, const char *label)
Purpose:
Set label for the dimension idx of did to the value label.
Description:
Sets the DIMENSION_LABEL_LIST for dimension idx of dataset did. If the dimension had a label, the new value replaces the old.

Fails if:

Parameters:
Returns:
Zero if succeed, negative if fail.

 

Fortran90 Interface: H5DSset_label_f
Set label for the dimension idx of did to the value label.
SUBROUTINE H5DSset_label_f(did, idx, label, errcode)
    IMPLICIT NONE
    INTEGER(hid_t),   INTENT(in) :: did    ! The dataset
    INTEGER       ,   INTENT(in) :: idx    ! The dimension
    CHARACTER(LEN=*), INTENT(in) :: label  ! The label
    INTEGER :: errcode                     ! Error code
END SUBROUTINE H5DSset_label_f   

 


Name: H5DSget_label
Signature:
ssize_t H5DSget_label(hid_t did, unsigned int idx, char *label, size_t size)
Purpose:
Read the label for dimension idx of did into buffer label.
Description:
Returns the value of the DIMENSION_LABEL_LIST for dimension idx of dataset did, if set. Up to size characters of the name are copied into the buffer label. If the label is longer than size, it will be truncated to fit. The parameter size is set to the size of the returned label.

If did has no label, the return value of label is NULL.

Fails if:

Parameters:
Returns:
Upon success, size of label or zero if no label found.
Negative if fail.

 

Fortran90 Interface: H5DSget_label_f
Read the label for dimension idx of did into buffer label.
SUBROUTINE H5DSget_label_f(did, idx, label, size, errcode)
    IMPLICIT NONE
    INTEGER(hid_t),   INTENT(in) :: did     ! The dataget
    INTEGER       ,   INTENT(in) :: idx     ! The dimension
    CHARACTER(LEN=*), INTENT(in) :: label   ! The label
    INTEGER(size_t) , INTENT(inout) :: size ! The length of the label buffer
    INTEGER :: errcode                      ! Error code
END SUBROUTINE H5DSget_label_f   

 


Name: H5DSget_scale_name
Signature:
ssize_t H5DSget_scale_name(hid_t did, char *name, size_t size)
Purpose:
Retrieves name of scale did into buffer name.
Description:
H5DSget_scale_name retrieves the name attribute for scale did.

Up to size characters of the scale name are returned in name; additional characters, if any, are not returned to the user application.

If the length of the name, which determines the required value of size, is unknown, a preliminary H5DSget_scale_name call can be made by setting name to NULL. The return value of this call will be the size of the scale name; that value plus one (1) can then be assigned to size for a second H5DSget_scale_name call, which will retrieve the actual name. (The value passed in with the parameter size must be one greater than size in bytes of the actual name in order to accommodate the null terminator; if size is set to the exact size of the name, the last byte passed back will contain the null terminator and the last character will be missing from the name passed back to the calling application.)

Parameters:
Returns:
Upon success, the length of the scale name or zero if no name found.
Negative if fail.

 

Fortran90 Interface: H5DSget_scale_name_f
Read the name of scale did into buffer name.
SUBROUTINE H5DSget_scale_name_f(did, name, size, errcode)
    IMPLICIT NONE
    INTEGER(hid_t),   INTENT(in) :: did     ! The dataget
    CHARACTER(LEN=*), INTENT(out) :: name   ! The name
    INTEGER(size_t) , INTENT(inout) :: size ! The length of the name buffer
    INTEGER :: errcode                      ! Error code
END SUBROUTINE H5DSget_scale_name_f   

 


Name: H5DSis_scale
Signature:
htri_t H5DSis_scale(hid_t did)
Purpose:
Determines whether dset is a Dimension Scale.
Description:
H5DSis_scale determines if did is a Dimension Scale, i.e., has CLASS="DIMENSION_SCALE").
Parameters:
Returns:
When successful, returns a positive value for TRUE or 0 (zero) for FALSE. Otherwise returns a negative value.

 

Fortran90 Interface: H5DSis_scale_f
Determines whether dset is a Dimension Scale.
SUBROUTINE H5DSis_scale_f(did, is_scale, errcode)
    IMPLICIT NONE
    INTEGER(hid_t), INTENT(in)  :: did         ! The data set to query
    LOGICAL       , INTENT(out) :: is_scale    ! Logical:  
                                               ! .TRUE. if did is a Dimension Scale
    INTEGER                     :: errcode     ! Error code
END SUBROUTINE H5DSis_scale_f 

 


Name: H5DSget_num_scales
Signature:
int H5DSget_num_scales(hid_t did, unsigned int idx)
Purpose:
Determines how many Dimension Scales are attached to dimension idx of did.
Description:
H5DSget_num_scales determines how many Dimension Scales are attached to dimension did of dataset dset.
Parameters:
Returns:
Returns the number of Dimension Scales associated with did, if successful, otherwise returns a negative value.

 

Fortran90 Interface: H5DSget_num_scales_f
Determines how many Dimension Scales are attached to dimension idx of did.
SUBROUTINE H5DSget_num_scales_f(did, idx, num_scales, errcode)
    IMPLICIT NONE
    INTEGER(hid_t), INTENT(in)  :: did         ! The dataset
    INTEGER       , INTENT(in)  :: idx         ! The dimension of did to query
    INTEGER       , INTENT(out) :: num_scales  ! The number of Dimension Scales 
                                               ! associated with did
    INTEGER                     :: errcode     ! Error code
END SUBROUTINE H5DSget_num_scales_f   

 


HDF5 documents and links 
Introduction to HDF5 
HDF5 User’s Guide 
Other High-level API documents
In the HDF5 Reference Manual  
H5DS   H5IM   H5LT   H5PT   H5TB   Optimized 
H5   H5A   H5D   H5E   H5F   H5G   H5I   H5L  
H5O   H5P   H5PL   H5R   H5S   H5T   H5Z  
Tools   Datatypes   Fortran  

The HDF Group Help Desk:
Describes HDF5 Release 1.8.20, November 2017.
  Copyright by The HDF Group
and the Board of Trustees of the University of Illinois