H5Pset_copy_object.htm

H5Pget_mcdt_search_cb.htm

H5Pset_mcdt_search_cb.htm

H5Padd_merge_committed_dtype_path.htm

H5Pfree_merge_committed_dtype_paths.htm

H5O_mcdt_search_cb_t.htm

H5Ocopy.htm

H5Pset_copy_object.htm

Last modified: 14 March 2012

Name: H5Pset_copy_object

Signature:

herr_t H5Pset_copy_object( hid_t ocpypl_id, unsigned copy_options )

Purpose:

Sets properties to be used when an object is copied.

Description:

H5Pset_copy_object sets properties in the object copy property list ocpypl_id. When an existing object is copied, that property list will determine how the new copy is created.

The following flags are available for use in an object copy property list:

`H5O_COPY_SHALLOW_HIERARCHY_FLAG`	Copy only immediate members of a group. Default behavior, without flag: Recursively copy all objects in and below the group.
`H5O_COPY_EXPAND_SOFT_LINK_FLAG`	Expand soft links into new objects. Default behavior, without flag: Copy soft links as they are.
`H5O_COPY_EXPAND_EXT_LINK_FLAG`	Expand external link into new objects. Default behavior, without flag: Copy external links as they are.
`H5O_COPY_EXPAND_REFERENCE_FLAG`	Copy objects that are pointed to by references. Default behavior, without flag: Update only the values of object references.
`H5O_COPY_WITHOUT_ATTR_FLAG`	Copy object without copying attributes. Default behavior, without flag: Copy object with all its attributes.
`H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG`	Use a matching committed datatype in the destination file when copying a committed datatype, a dataset with a committed datatype, or an object with an attribute of committed datatype. Default behavior without flag: A committed datatype in the source will be copied to the destination as a committed datatype. If a dataset in the source uses a committed datatype or an object in the source has an attribute of a committed datatype, that committed datatype will be written to the destination as an anonymous committed datatype. See the “See Also” section immediately below for functions related to the use of this flag.

Parameters:

hid_t `ocpypl_id`	IN: Object copy property list identifier
unsigned `copy_options`	IN: Copy option(s) to be set

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

See Also:

`H5Ocopy` The following functions and callback function can be used to tune copy behavior when the flag `H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG` is used:
`H5Padd_merge_committed_dtype_path` `H5Pfree_merge_committed_dtype_paths`		`H5Pset_mcdt_search_cb` `H5Pget_mcdt_search_cb` `H5O_mcdt_search_cb_t`

Fortran90 Interface: h5pset_copy_object_f

SUBROUTINE h5pset_copy_object_f(ocpypl_id, copy_options, hdferr)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: ocpypl_id 
                              ! Object copy property list identifier
  INTEGER, INTENT(IN) :: copy_options 
                              ! Copy option(s) to be set, valid options are:
                              !   H5O_COPY_SHALLOW_HIERARCHY_F
                              !   H5O_COPY_EXPAND_SOFT_LINK_F 
                              !   H5O_COPY_EXPAND_EXT_LINK_F
                              !   H5O_COPY_EXPAND_REFERENCE_F
                              !   H5O_COPY_WITHOUT_ATTR_FLAG_F
                              !   H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG_F

  INTEGER, INTENT(OUT) :: hdferr      
                              ! Error code
                              ! 0 on success and -1 on failure
END SUBROUTINE h5pset_copy_object_f

History:

Release	C
1.8.0	Function introduced in this release.
1..	`H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG` added in this release.

H5Pget_mcdt_search_cb.htm

Last modified: 14 March 2012

Name: H5Pget_mcdt_search_cb

Signature:

herr_t H5Pget_mcdt_search_cb( hid_t ocpypl_id, H5O_mcdt_search_cb_t *func, void **op_data )

Purpose:

Retrieves the callback function from the specified object copy property list.

Description:

H5Pget_mcdt_search_cb retrieves the user-defined callback function and the user data that are set via H5Pset_mcdt_search_cb in the object copy property list ocpypl_id.

The callback function will be returned in the parameter func and the user data will be returned in the parameter op_data.

Parameters:

hid_t `ocpypl_id`		IN: Object copy property list identifier
H5O_mcdt_search_cb_t *`func`		OUT: User-defined callback function
void **`op_data`		OUT: User-defined input data for the callback function

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Failure Modes:

H5Pget_mcdt_search_cb will fail if the object copy property list is invalid.

See Also:

H5Ocopy
H5Pset_copy_object

H5Pset_mcdt_search_cb
H5O_mcdt_search_cb_t

History:

Release	Change
..*	C function introduced in this release.

H5Pset_mcdt_search_cb.htm

Last modified: 14 March 2012

Name: H5Pset_mcdt_search_cb

Signature:

herr_t H5Pset_mcdt_search_cb( hid_t ocpypl_id, H5O_mcdt_search_cb_t func, void *op_data )

Purpose:

Sets the callback function that H5Ocopy will invoke before searching the entire destination file for a matching committed datatype.

Motivation:

H5Pset_mcdt_search_cb provides the means to define a callback function. An application can then use that callback to take an additiional action before the default search of all committed datayptes in the destination file or to take an action that replaces that default search. This mechanism is intended to improve performance when the global search might take a long time.

Description:

H5Pset_mcdt_search_cb allows an application to set a callback function, func, that will be invoked before searching the destination file for a matching committed datatype. The default, global search process is described in H5Padd_merge_committed_dtype_path.

The callback function must conform to the H5O_mcdt_search_cb_t prototype and will return an instruction for one of the following actions:

Continue the search for a matching committed datatype in the destination file.
Discontinue the search for a matching committed datatype. H5Ocopy will then apply the default behavior of creating an anonymous committed datatype.
Abort the copy operation and exit H5Ocopy.

Warning:

If the callback function return value causes H5Ocopy to abort, the destination file may be left in an inconsistent or corrupted state.

Parameters:

hid_t `ocpypl_id`		IN: Object copy property list identifier
H5O_mcdt_search_cb_t `func`		IN: User-defined callback function
void *`op_data`		IN: User-defined input data for the callback function

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Failure Modes:

H5Pset_mcdt_search_cb will fail if the object copy property list is invalid.

Example Usage:

This example defines a callback function in the object copy property list.

/* The user-defined callback function */
static H5O_mcdt_search_ret_t
mcdt_search_cb(void *_udata)
{
    H5O_mcdt_search_ret_t action = *((H5O_mcdt_search_ret_t *)_udata);

    return(action);
}

int main(void) {
    hid_t ocpypl_id = H5Pcreate(H5P_OBJECT_COPY);

    /* Enable the merging committed datatype feature. */
    H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG);

    /* Add a path to search for a matching committed datatype. */
    H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");

    /* 
     * Set the callback function to discontinue the global search
     * if H5Ocopy cannot find a matching committed datatype from the 
     * above suggested path.
     */
    action = H5O_MCDT_SEARCH_STOP;
    H5Pset_mcdt_search_cb(ocpypl_id, mcdt_search_cb, &action);
    H5Ocopy(...ocpypl_id...);
    ...
    ...
}

See Also:

H5Ocopy
H5Pset_copy_object

H5Padd_merge_committed_dtype_path
H5Pget_mcdt_search_cb
H5O_mcdt_search_cb_t

History:

Release	Change
..*	C function introduced in this release.

H5Padd_merge_committed_dtype_path.htm

Last modified: 14 March 2012

Name: H5Padd_merge_committed_dtype_path

Signature:

herr_t H5Padd_merge_committed_dtype_path( hid_t ocpypl_id, char *path )

Purpose:

Adds a path to the list of paths that will be be searched in the destination file for a matching committed datatype.

Motivation:

H5Padd_merge_committed_dtype_path provides a means to override the default behavior of H5Ocopy when H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG is set in an object copy property list.

H5Padd_merge_committed_dtype_path is the mechanism for suggesting search paths where H5Ocopy will look for a matching committed datatype. This can be substantially faster than the default approach of searching the entire destination file for a match.

Description:

H5Padd_merge_committed_dtype_path adds a path, path, which points to a committed datatype, to the current list of suggested paths stored in the object copy property list ocpypl_id. The search as described in the next paragraph is effective only if the H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG is enabled in the object copy property list via H5Pset_copy_object.

When copying a committed datatype, a dataset with a committed datatype, or an object with an attribute of a committed datatype, the default behavior of H5Ocopy is to search for a matching committed datatype:

First search the list of suggested paths in the object copy property list.
Then, if no match has been found, search all the committed datatypes in the destination file.

The default Step 2 in this search process can changed by setting a callback function (see H5Pset_mcdt_search_cb).

Two datatypes are determined equal if their descriptions are identical, in a manner similar to H5Tequal. If either committed datatype has one or more attributes, then all attributes must be present in both committed datatypes and they must be identical. Two attributes are considered identical if their datatype description, dataspace, and raw data values are the same. However, if an attribute uses a committed datatype, that committed datatype’s attributes will not be compared.

If a match is found, H5Ocopy will perform the following in the destination file:

For a committed datatype, the library will create a hard link to the found datatype.
For a dataset that uses a committed datatype, the library will modify the copied dataset to use the found committed datatype as its datatype.
For an object with an attribute of a committed datatype, the library will modify the copied object’s attribute to use the found committed datatype as its datatype.

If no match is found, H5Ocopy will perform the following in the destination file:

For a committed datatype, the library will copy it as it would any other object, creating a named committed datatype at the destination. That is, the library will create a committed datatype that is accessible in the file by a unique path.
For a dataset that uses a committed datatype, the library will copy the datatype as an anonymous committed datatype and use that as the dataset’s datatype.
For an object with an attribute of a committed datatype, the library will copy the datatype as an anonymous committed datatype and use that as the attribute’s datatype.

Parameters:

hid_t `ocpypl_id`		IN: Object copy property list identifier.
char *`path`		IN: The path to be added.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Failure Modes:

H5Padd_merge_committed_dtype_path will fail if the object copy property list is invalid.

It will also fail if there is insufficient memory when duplicating path.

Example Usage:

This example adds two paths to the object copy property list. H5Ocopy will search the two suggested paths for a match before searching all the committed datatypes in the destination file.


int main(void) {
    hid_t ocpypl_id = H5Pcreate(H5P_OBJECT_COPY);

    /* Enable the merging committed datatype feature */
    H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG);

    /* Add a path to a committed datatype */
    H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");

    /* Add a path to a dataset with committed datatype */
    H5Padd_merge_committed_dtype_path(ocpypl_id, "/group2/committed_dset");
    
    /* Does the copy */
    H5Ocopy(...ocpypl_id...);
    ...
    ...
}

See Also:

H5Ocopy
H5Pset_copy_object

H5Pset_mcdt_search_cb
H5Pfree_merge_committed_dtype_paths

History:

Release	Change
..*	C function introduced in this release.

H5Pfree_merge_committed_dtype_paths.htm

Last modified: 14 March 2012

Name: H5Pfree_merge_committed_dtype_paths

Signature:

herr_t H5Pfree_merge_committed_dtype_paths( hid_t ocpypl_id )

Purpose:

Clears the list of paths stored in the object copy property list ocpypl_id. These are the suggested paths previously set with H5Padd_merge_committed_dtype_path.

Description:

H5Pfree_merge_committed_dtype_paths clears the suggested paths stored in the object copy property list ocpypl_id.

Parameters:

hid_t ocpypl_id IN: Object copy property list identifier.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Failure Modes:

H5Pfree_merge_committed_dtype_paths will fail if the object copy property list is invalid.

Example Usage:

This example adds a suggested path to the object copy property list, does the copy, clears the list, and then adds a new suggested path to the list for another copy.

int main(void) {
    hid_t ocpypl_id = H5Pcreate(H5P_OBJECT_COPY);

    /* Enable the merging committed datatype feature. */
    H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG);

    /* Add a path to search for a matching committed datatype. */
    H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");

    /* Do the copy. */
    H5Ocopy(...ocpypl_id...);
    ...
    ...
    /* Free the previous suggested path. */
    H5Pfree_merge_committed_dtype_paths(ocpypl_id);

    /* Add a path to search for a matching committed datatype. */
    H5Padd_merge_committed_dtype_path(ocpypl_id, "/group2/committed_dtypeB");

    /* Do the copy. */
    H5Ocopy(...ocpypl_id...);
    ...
    ...
}

See Also:

H5Ocopy
H5Pset_copy_object

H5Pset_mcdt_search_cb
H5Padd_merge_committed_dtype_path

History:

Release	Change
..*	C function introduced in this release.

H5O_mcdt_search_cb_t.htm

Current plan: Place this entry in H5O/ and publish it on the H5O RM page. Links to it will be to the entry within the H5O page rather than to the free-standing entry. It could be published adjacent to H5Pset_mcdt_search_cb, but that breaks standard practice and would probably be more confusing.

Last modified: 14 March 2012

Name: H5O_mcdt_search_cb_t

Signature:

typedef H5O_mcdt_search_ret_t ( *H5O_mcdt_search_cb_t )( void *op_data )

Purpose:

Provides the mechanism by which a user application may set an action for H5Ocopy to take after checking all suggested paths for a matching committed datatype but before starting the global search of the destination file.

Description:

H5O_mcdt_search_cb_t is the callback function that H5Ocopy will invoke if the callback is set and when the merge committed datatype feature is enabled in the object copy property list (see H5Pset_copy_object).

After searching the list of suggested committed datatype paths, H5Ocopy will invoke this callback before searching all committed datatypes in the destination file. This allows a user application to add a customized step to the search process. The callback function is set with H5Pset_mcdt_search_cb and the search process is described in H5Padd_merge_committed_dtype_path.

Valid return values from this callback function are as follows (defined in the enumerated datatype H5O_mcdt_search_ret_t in H5Opublic.h):

H5O_MCDT_SEARCH_ERROR Aborts H5Ocopy.
H5O_MCDT_SEARCH_CONT Continues the global search of all committed datatypes in the destination file.
H5O_MCDT_SEARCH_STOP Stops the search, but continues copying.

Warning:

If the callback’s return value is H5O_MCDT_SEARCH_ERROR, H5Ocopy will abort and the destination file may be left in an inconsistent or corrupted state.

Parameters:

void *op_data IN/OUT: Pointer to user-defined input data. This is a pass-through of the data that was passed to H5Pset_mcdt_search_cb.

Returns:

Returns one of the H5O_MCDT_SEARCH_* values described above.

Failure Modes:

H5O_mcdt_search_cb_t failure modes are dependent on the implementation of the callback function.

Example Usage:

This example defines a callback function in the object copy property list to discontinue the global search if a matching committed datatype cannot be found among the suggested paths.

/* The user-defined callback function */
static H5O_mcdt_search_ret_t
mcdt_search_cb(void *_udata)
{
    H5O_mcdt_search_ret_t action = *((H5O_mcdt_search_ret_t *)_udata);

    return(action);
}

int main(void) {
    hid_t ocpypl_id = H5Pcreate(H5P_OBJECT_COPY);

    /* Enable the merging committed datatype feature. */
    H5Pset_copy_object(ocpypl_id, H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG);

    /* Add the path to search for a matching committed datatype. */
    H5Padd_merge_committed_dtype_path(ocpypl_id, "/group/committed_dtypeA");

    /*
     * Set the callback function to discontinue the global search
     * if H5Ocopy cannot find a matching committed datatype from the
     * above suggested path.
     */
    action = H5O_MCDT_SEARCH_STOP;
    H5Pset_mcdt_search_cb(ocpypl_id, mcdt_search_cb, &action);

    /* Do the copy. */
    H5Ocopy(...ocpypl_id...);
    ...
    ...
}

See Also:

H5Ocopy
H5Pset_copy_object

H5Pset_mcdt_search_cb
H5Pget_mcdt_search_cb

History:

Release	Change
..*	C function type introduced in this release.

H5Ocopy.htm

Last modified: 14 March 2012

Name: H5Ocopy

Signature:

herr_t H5Ocopy( hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name, hid_t ocpypl_id, hid_t lcpl_id )

Purpose:

Copies an object in an HDF5 file.

Description:

H5Ocopy copies the group, dataset or committed datatype specified by src_name from the file or group specified by src_loc_id to the destination location dst_loc_id.

The destination location, as specified in dst_loc_id, may be a group in the current file or a location in a different file. If dst_loc_id is a file identifier, the copy will be placed in that file’s root group.

The new copy will be created with the name dst_name. dst_name must not pre-exist in the destination location; if dst_name already exists at the location dst_loc_id, H5Ocopy will fail.

The new copy of the object is created with the creation property lists specified by ocpypl_id and lcpl_id.

H5Ocopy will always try to make a copy of the object specified in src_name.

If the object specified by src_name is a group containing a soft or external link, the default is that the new copy will contain a soft or external link with the same value as the original. See H5Pset_copy_object for optional settings.
If the path specified in src_name is or contains a soft link or an external link, H5Ocopy will copy the target object. Use H5Lcopy if the intent is to create a new soft or external link with the same value as the original link.

Several flags are available to govern the behavior of H5Ocopy:

A flag controlling the creation of intermediate groups that may not yet exist is set in the link creation property list lcpl_id with H5Pset_create_intermediate_group.
Copying of committed datatypes can be tuned through the use of H5Pset_copy_object, H5Padd_merge_committed_dtype_path, H5Pset_mcdt_search_cb, and related functions.
Flags controlling other aspects of object copying are set in the object copy property list ocpypl_id with H5Pset_copy_object.

Parameters:

hid_t src_loc_id IN: Object identifier indicating the location of the source object to be copied

const char *src_name IN: Name of the source object to be copied

hid_t dst_loc_id IN: Location identifier specifying the destination

const char *dst_name IN: Name to be assigned to the new copy

hid_t ocpypl_id IN: Object copy property list

hid_t lcpl_id IN: Link creation property list for the new hard link

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

See Also:

H5Pset_copy_object
H5Pset_create_intermediate_group

H5Padd_merge_committed_dtype_path
H5Pset_mcdt_search_cb

Fortran90 Interface:

None.

History:

Release C

1.8.0 Function introduced in this release.

`H5O_MCDT_SEARCH_ERROR`		Aborts `H5Ocopy`.
`H5O_MCDT_SEARCH_CONT`		Continues the global search of all committed datatypes in the destination file.
`H5O_MCDT_SEARCH_STOP`		Stops the search, but continues copying.

hid_t `src_loc_id`	IN: Object identifier indicating the location of the source object to be copied
const char *`src_name`	IN: Name of the source object to be copied
hid_t `dst_loc_id`	IN: Location identifier specifying the destination
const char *`dst_name`	IN: Name to be assigned to the new copy
hid_t `ocpypl_id`	IN: Object copy property list
hid_t `lcpl_id`	IN: Link creation property list for the new hard link