H5DS: HDF5 Dimension Scales

HDF5 Dimension Scale API Reference

The C Interfaces:

H5DSset_scale H5DSattach_scale H5DSdetach_scale H5DSis_attached H5DSis_scale

H5DSiterate_scales H5DSset_label H5DSget_label H5DSget_scale_name H5DSget_num_scales

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:

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

Parameters:

hid_t dsid;	IN: the dataset to be made a Dimension Scale
char *dimname;	IN: the dimension name (optional), NULL if the dimension has no name.

Returns:

Zero if succeed, negative if fail.

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:

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

Parameters:

hid_t did;	IN: the dataset
hid_t dsid;	IN: the scale to be attached
unsigned int idx;	IN: the dimension of did that dsid is associated with.

Returns:

Zero if succeed, negative if fail.

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:

• Bad arguments
• The dataset did or dsid do not exist.
• The dsid is not a Dimension Scale
• dsid is not attached to did.

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:

hid_t did;	IN: the dataset
hid_t dsid;	IN: the scale to be detached
unsigned int idx;	IN: the dimension of did to detach

Returns:

Zero if succeed, negative if fail.

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:

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

Parameters:

hid_t did;	IN: the dataset
hid_t dsid;	IN: the scale to be attached
unsigned int idx;	IN: the dimension of did that dsid is associated with.

Returns:

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

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:

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

Parameters:

hid_t did;	IN: the dataset
unsigned dim;	IN: the dimension of dataset did
int *idx;	IN/OUT: input the index to start iterating, output the next index to visit. If NULL, start at the first position.
H5DS_iterate_t visitor;	IN: the visitor function
void *visitor_data;	IN: arbitrary 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.

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:

• Bad arguments

Parameters:

hid_t did;	IN: the dataset
unsigned int idx;	IN: the dimension
char *label;	IN: the label

Returns:

Zero if succeed, negative if fail.

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:

• Bad arguments

Parameters:

hid_t did;	IN: the dataset
unsigned int idx;	IN: the dimension
char *label;	OUT: the label
size_t size;	IN: the length of the label buffer.

Returns:

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

Name: H5DSget_scale_name

Signature:

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

Purpose:

Read the name of scale did into buffer name.

Description:

Read the value of the NAME attribute for scale did. Reads up to size characters into name. On return, size is the number of characters read into name.

Parameters:

int did;	IN: dimension scale identifier
char *name;	OUT: the name, or NULL if there is no name set.
size_t size;	IN: the maximum characters to copy into name.

Returns:

Upon success, size of name or zero if no name found.
Negative if fail.

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:

hid_t did;

IN: the data set to query

Returns:

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

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:

hid_t did;	IN: the data set to query
unsigned int idx;	IN: the dimension of did to query.

Returns:

Returns the number of Dimension Scales associated with did, if successful, otherwise returns a negative value.