Please, help us to better serve our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5 1.14.5
API Reference
Loading...
Searching...
No Matches
HDF5 Dimension Scales APIs (H5DS)

Detailed Description

Creating and manipulating HDF5 datasets that are associated with the dimension of another HDF5 dataset (H5DS)

Note
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
This module contains Fortran interfaces for H5DS.
Definition H5DSff.F90:35

Functions

H5_HLDLL herr_t H5DSwith_new_ref (hid_t obj_id, hbool_t *with_new_ref)
 Determines if new references are used with dimension scales.
 
H5_HLDLL herr_t H5DSattach_scale (hid_t did, hid_t dsid, unsigned int idx)
 Attach dimension scale dsid to dimension idx of dataset did.
 
H5_HLDLL herr_t H5DSdetach_scale (hid_t did, hid_t dsid, unsigned int idx)
 Detach dimension scale dsid from the dimension idx of dataset did.
 
H5_HLDLL herr_t H5DSset_scale (hid_t dsid, const char *dimname)
 Convert dataset dsid to a dimension scale, with optional name, dimname.
 
H5_HLDLL int H5DSget_num_scales (hid_t did, unsigned int idx)
 Determines how many Dimension Scales are attached to dimension idx of did.
 
H5_HLDLL herr_t H5DSset_label (hid_t did, unsigned int idx, const char *label)
 Set label for the dimension idx of did to the value label.
 
H5_HLDLL ssize_t H5DSget_label (hid_t did, unsigned int idx, char *label, size_t size)
 Read the label for dimension idx of did into buffer label.
 
H5_HLDLL ssize_t H5DSget_scale_name (hid_t did, char *name, size_t size)
 Retrieves name of scale did into buffer name.
 
H5_HLDLL htri_t H5DSis_scale (hid_t did)
 Determines whether did is a Dimension Scale.
 
H5_HLDLL herr_t H5DSiterate_scales (hid_t did, unsigned int dim, int *idx, H5DS_iterate_t visitor, void *visitor_data)
 Iterates the operation visitor through the scales attached to dimension dim.
 
H5_HLDLL htri_t H5DSis_attached (hid_t did, hid_t dsid, unsigned int idx)
 Report if dimension scale dsid is currently attached to dimension idx of dataset did.
 

Function Documentation

◆ H5DSattach_scale()

H5_HLDLL herr_t H5DSattach_scale ( hid_t  did,
hid_t  dsid,
unsigned int  idx 
)

Attach dimension scale dsid to dimension idx of dataset did.


Parameters
[in]didThe dataset
[in]dsidThe scale to be attached
[in]idxThe dimension of did that dsid is associated with
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

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 of HDF5 Dimension Scale Specification.

Fails if:

  • Bad arguments
  • If dsid is not a Dimension Scale
  • If did is a Dimension Scale (A Dimension Scale cannot have scales.)
Note
The Dimension Scale dsid can be attached to the same dimension more than once, which has no effect.

◆ H5DSdetach_scale()

H5_HLDLL herr_t H5DSdetach_scale ( hid_t  did,
hid_t  dsid,
unsigned int  idx 
)

Detach dimension scale dsid from the dimension idx of dataset did.


Parameters
[in]didThe dataset
[in]dsidThe scale to be detached
[in]idxThe dimension of did to detach
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

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 of HDF5 Dimension Scale Specification.

Fails if:

  • Bad arguments
  • The dataset did or dsid do not exist
  • The dsid is not a Dimension Scale
  • dsid is not attached to did
Note
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.

◆ H5DSget_label()

H5_HLDLL ssize_t H5DSget_label ( hid_t  did,
unsigned int  idx,
char *  label,
size_t  size 
)

Read the label for dimension idx of did into buffer label.


Parameters
[in]didThe dataset
[in]idxThe dimension
[out]labelThe label
[in]sizeThe length of the label buffer
Returns
Upon success, size of label or zero if no label found. Negative if fail.

Returns the value of the DIMENSION_LABELS 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:

  • Bad arguments

◆ H5DSget_num_scales()

H5_HLDLL int H5DSget_num_scales ( hid_t  did,
unsigned int  idx 
)

Determines how many Dimension Scales are attached to dimension idx of did.


Parameters
[in]didThe dataset to query
[in]idxThe dimension of did to query
Returns
Returns the number of Dimension Scales associated with did, if successful, otherwise returns a negative value.

H5DSget_num_scales() determines how many Dimension Scales are attached to dimension idx of dataset did.

◆ H5DSget_scale_name()

H5_HLDLL ssize_t H5DSget_scale_name ( hid_t  did,
char *  name,
size_t  size 
)

Retrieves name of scale did into buffer name.


Parameters
[in]didDimension scale identifier
[out]nameBuffer to contain the returned name
[in]sizeSize in bytes, of the name buffer
Returns
Upon success, the length of the scale name or zero if no name found. Negative if fail.

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

◆ H5DSis_attached()

H5_HLDLL htri_t H5DSis_attached ( hid_t  did,
hid_t  dsid,
unsigned int  idx 
)

Report if dimension scale dsid is currently attached to dimension idx of dataset did.


Parameters
[in]didThe dataset
[in]dsidThe scale to be attached
[in]idxThe dimension of did that dsid is associated with
Returns
Returns zero (false), a positive (true) or a negative (failure) value.

Report if dimension scale dsid is currently attached to dimension idx of dataset did.

Fails if:

  • Bad arguments
  • If dsid is not a Dimension Scale
  • The dsid is not a Dimension Scale
  • If did is a Dimension Scale (A Dimension Scale cannot have scales.)

◆ H5DSis_scale()

H5_HLDLL htri_t H5DSis_scale ( hid_t  did)

Determines whether did is a Dimension Scale.


Parameters
[in]didThe dataset to query
Returns
Returns zero (false), a positive (true) or a negative (failure) value.

H5DSis_scale() determines if did is a Dimension Scale, i.e., has class="DIMENSION_SCALE").

◆ H5DSiterate_scales()

H5_HLDLL herr_t H5DSiterate_scales ( hid_t  did,
unsigned int  dim,
int *  idx,
H5DS_iterate_t  visitor,
void *  visitor_data 
)

Iterates the operation visitor through the scales attached to dimension dim.


Parameters
[in]didThe dataset
[in]dimThe dimension of dataset did
[in,out]idxInput the index to start iterating, output the next index to visit. If NULL, start at the first position.
[in]visitorThe visitor function
[in]visitor_dataArbitrary data to pass to the visitor function
Returns
Returns the return value of the last operator if it was non-zero, or zero if all scales were processed.

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 dset, unsigned dim, hid_t scale, void *visitor_data);
herr_t(* H5DS_iterate_t)(hid_t dset, unsigned dim, hid_t scale, void *visitor_data)
Prototype for H5DSiterate_scales() operator.
Definition H5DSpublic.h:26
int64_t hid_t
Definition H5Ipublic.h:60
int herr_t
Definition H5public.h:239

The operation receives the Dimension Scale dataset identifier, scale, and the pointer to the operator data passed in to H5DSiterate_scales(), visitor_data.

The return values from an operator are:

  • Zero causes the iterator to continue, returning zero when all group members have been processed.
  • Positive causes the iterator to immediately return that positive value, indicating short-circuit success. The iterator can be restarted at the next group member.
  • Negative causes the iterator to immediately return that value, indicating failure. The iterator can be restarted at the next group member.

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.

◆ H5DSset_label()

H5_HLDLL herr_t H5DSset_label ( hid_t  did,
unsigned int  idx,
const char *  label 
)

Set label for the dimension idx of did to the value label.


Parameters
[in]didThe dataset
[in]idxThe dimension
[in]labelThe label
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

Sets the DIMENSION_LABELS for dimension idx of dataset did. If the dimension had a label, the new value replaces the old.

Fails if:

  • Bad arguments

◆ H5DSset_scale()

H5_HLDLL herr_t H5DSset_scale ( hid_t  dsid,
const char *  dimname 
)

Convert dataset dsid to a dimension scale, with optional name, dimname.


Parameters
[in]dsidThe dataset to be made a Dimemsion Scale
[in]dimnameThe dimension name (optional), NULL if the dimension has no name.
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

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:

  • Bad arguments
  • If dsid is already a scale
  • If dsid is a dataset which already has dimension scales

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

Todo:
what is [9] after Palette interface?

◆ H5DSwith_new_ref()

H5_HLDLL herr_t H5DSwith_new_ref ( hid_t  obj_id,
hbool_t with_new_ref 
)

Determines if new references are used with dimension scales.


Parameters
[in]obj_idObject identifier
[out]with_new_refNew references are used or not
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5DSwith_new_ref() takes any object identifier and checks if new references are used for dimension scales. Currently, new references are used when non-native VOL connector is used or when H5_DIMENSION_SCALES_WITH_NEW_REF is set up via configure option.