summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorFrank Baker <fbaker@hdfgroup.org>2003-10-07 22:17:58 (GMT)
committerFrank Baker <fbaker@hdfgroup.org>2003-10-07 22:17:58 (GMT)
commitc1afffec458a21b98072930d06ece03e7ba1954c (patch)
tree2d063db22e94604a343a5aa43cacc78f00f441c6 /doc
parent0eaf192df8e7df34cb2d45085bb3252816eb8e2d (diff)
downloadhdf5-c1afffec458a21b98072930d06ece03e7ba1954c.zip
hdf5-c1afffec458a21b98072930d06ece03e7ba1954c.tar.gz
hdf5-c1afffec458a21b98072930d06ece03e7ba1954c.tar.bz2
[svn-r7571]
Purpose: Alphabetic sort of RM function entries Additional and modified HTML coding to accomodate HTMLdoc and automated PDF generation Minor copy edits Platforms tested: Safari, IE 5
Diffstat (limited to 'doc')
-rw-r--r--doc/html/RM_H5P.html8261
1 files changed, 4185 insertions, 4076 deletions
diff --git a/doc/html/RM_H5P.html b/doc/html/RM_H5P.html
index 4fccf35..67406fa 100644
--- a/doc/html/RM_H5P.html
+++ b/doc/html/RM_H5P.html
@@ -25,6 +25,7 @@ HDF5/H5P API Specification
<!-- #EndLibraryItem --></head>
<body bgcolor="#FFFFFF">
+<!-- HEADER RIGHT " " -->
<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr>
@@ -60,8 +61,7 @@ And in this document, the
</td></tr>
</table>
</center>
-<hr>
-<!-- #EndLibraryItem --><center>
+<hr><!-- #EndLibraryItem --><center>
<h1>H5P: Property List Interface</h1>
</center>
<h2>Property List API Functions</h2>
@@ -154,7 +154,7 @@ which require many different parameters to be easily manipulated.
<li><a href="#Property-GetFaplStream">H5Pget_fapl_stream</a>
<!--<li><a href="#Property-SetDriver">H5Pset_driver</a> -->
<li><a href="#Property-GetDriver">H5Pget_driver</a>
- <li><a href="#Property-GetDriverInfo">H5Pget_driver_info</a>
+<!--<li><a href="#Property-GetDriverInfo">H5Pget_driver_info</a> -->
<li><a href="#Property-SetMetaBlockSize">H5Pset_meta_block_size</a>
<li><a href="#Property-GetMetaBlockSize">H5Pget_meta_block_size</a>
<li><a href="#Property-SetSieveBufSize">H5Pset_sieve_buf_size</a>
@@ -271,6 +271,7 @@ See further notes in the description of each function.
<table border="0">
<tr>
<td valign="top">
+ <ul>
<li><a href="#Property-AllFiltersAvail">H5Pall_filters_avail</a>
<li><a href="#Property-Close">H5Pclose</a>
<li><a href="#Property-CloseClass">H5Pclose_class</a>
@@ -294,7 +295,7 @@ See further notes in the description of each function.
<li><a href="#Property-GetClassName">H5Pget_class_name</a>
<li><a href="#Property-GetClassParent">H5Pget_class_parent</a>
<li><a href="#Property-GetDriver">H5Pget_driver</a>
- <li><a href="#Property-GetDriverInfo">H5Pget_driver_info</a>
+ <!--<li><a href="#Property-GetDriverInfo">H5Pget_driver_info</a> -->
<li><a href="#Property-GetDxplMpio">H5Pget_dxpl_mpio</a>&nbsp;&nbsp;&nbsp;||
<li><a href="#Property-GetDxplMulti">H5Pget_dxpl_multi</a>
<li><a href="#Property-GetEdcCheck">H5Pget_edc_check</a>
@@ -311,11 +312,13 @@ See further notes in the description of each function.
<li><a href="#Property-GetFaplStream">H5Pget_fapl_stream</a>
<li><a href="#Property-GetFcloseDegree">H5Pget_fclose_degree</a>
<li><a href="#Property-GetFillTime">H5Pget_fill_time</a>
+ </ul>
</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td>
- <td valign="top">
+ <td valign="top">
+ <ul>
<li><a href="#Property-GetFillValue">H5Pget_fill_value</a>
<li><a href="#Property-GetFilter">H5Pget_filter</a>
<li><a href="#Property-GetFilterById">H5Pget_filter_by_id</a>
@@ -355,11 +358,13 @@ See further notes in the description of each function.
<li><a href="#Property-SetDxplMulti">H5Pset_dxpl_multi</a>
<li><a href="#Property-SetEdcCheck">H5Pset_edc_check</a>
<li><a href="#Property-SetExternal">H5Pset_external</a>
+ </ul>
</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td valign="top">
+ <ul>
<li><a href="#Property-SetFamilyOffset">H5Pset_family_offset</a>
<li><a href="#Property-SetFaplCore">H5Pset_fapl_core</a>
<li><a href="#Property-SetFaplFamily">H5Pset_fapl_family</a>
@@ -395,26 +400,27 @@ See further notes in the description of each function.
<li><a href="#Property-SetUserblock">H5Pset_userblock</a>
<li><a href="#Property-SetVLMemManager">H5Pset_vlen_mem_manager</a>
<li><a href="#Property-Unregister">H5Punregister</a>
+ </ul>
<br><br>
- <i>||&nbsp;&nbsp;<i>Available only in the parallel HDF5 library.</i>
+ ||&nbsp;&nbsp;<i>Available only in the parallel HDF5 library.</i>
</td>
</tr>
</table>
-<p>
+<br>
<strong>The FORTRAN90 Interfaces:</strong>
<br>
<font size=-1>
<i>In general, each FORTRAN90 subroutine performs exactly the same task
-as the corresponding C function. The links below go to the C function
+as the corresponding C function. The links below (electronic versions only) go to the C function
descriptions, which serve as general descriptions for both. A button,
under <strong>Non-C API(s)</strong> at the end of the C function description,
opens an external browser window displaying the FORTRAN90-specific
information. You will probably want to adjust the size and location of
this external window so that both browser windows are visible and to
facilitate moving easily between them.</i>
-</font>
+</font><br>
<table border=0>
<tr><td valign=top>
@@ -589,66 +595,39 @@ facilitate moving easily between them.</i>
</td></tr>
</table>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pall_filters_avail" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-Create">H5Pcreate</a>
+ <dt><strong>Name:</strong> <a name="Property-AllFiltersAvail">H5Pall_filters_avail</a>
<dt><strong>Signature:</strong>
- <dd><em>hid_t </em><code>H5Pcreate</code>(<em>H5P_class_t</em> <code>type</code>
- )
+ <dd><em>htri_t</em> <code>H5Pall_filters_avail</code>(<em>hid_t</em> <code>dcpl_id</code>)
<dt><strong>Purpose:</strong>
- <dd>Creates a new property as an instance of a property list class.
+ <dd>Verifies that all required filters are available.
<dt><strong>Description:</strong>
- <dd><code>H5Pcreate</code> creates a new property as an instance of some
- property list class. The new property list is initialized
- with default values for the specified class. The classes are:
- <dl>
- <dt><code>H5P_FILE_CREATE</code>
- <dd>Properties for file creation.
- See <a href="Files.html">Files</a>
- in the <cite>HDF User's Guide</cite>
- for details about the file creation properties.
- <dt><code>H5P_FILE_ACCESS</code>
- <dd>Properties for file access.
- See <a href="Files.html">Files</a>
- in the <cite>HDF User's Guide</cite>
- for details about the file creation properties.
- <dt><code>H5P_DATASET_CREATE</code>
- <dd>Properties for dataset creation.
- See <a href="Datasets.html">Datasets</a>
- in the <cite>HDF User's Guide</cite>
- for details about dataset creation properties.
- <dt><code>H5P_DATASET_XFER</code>
- <dd>Properties for raw data transfer.
- See <a href="Datasets.html">Datasets</a>
- in the <cite>HDF User's Guide</cite>
- for details about raw data transfer properties.
- <dt><code>H5P_MOUNT</code>
- <dd>Properties for file mounting.
- With this parameter, <code>H5Pcreate</code>
- creates and returns a new mount property list
- initialized with default values.
- </dl>
- <p>
- This property list must eventually be closed with
- <code>H5Pclose</code>;
- otherwise, errors are likely to occur.
+ <dd><code>H5Pall_filters_avail</code> verifies that all of the filters
+ set in the dataset creation property list <code>dcpl_id</code> are
+ currently available.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>H5P_class_t</em> <code>type</code>
- <dd>IN: The type of property list to create.
+ <dt><em>hid_t</em> <code>dcpl_id</code>
+ <dd>IN: Dataset creation property list identifier.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a property list identifier (<code>plist</code>) if successful;
- otherwise Fail (-1).
- <dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pcreate_f"
+ <dd>Returns <code>TRUE</code> if all filters are available
+ and <code>FALSE</code> if one or more is not currently available.<br>
+ Returns <code>FAIL</code>, a negative value, on error.
+<!--<dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pall_filters_avail_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
+--> <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pclose" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-Close">H5Pclose</a>
@@ -679,38 +658,93 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pclose_class" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetClass">H5Pget_class</a>
+ <dt><strong>Name:</strong> <a name="Property-CloseClass">H5Pclose_class</a>
+
<dt><strong>Signature:</strong>
- <dd><em>H5P_class_t </em><code>H5Pget_class</code>(<em>hid_t</em> <code>plist</code>
- )
+ <dd><em>herr_t</em> <code>H5Pclose_class</code>(
+ <em>hid_t</em> <code>class</code>
+ )
+
<dt><strong>Purpose:</strong>
- <dd>Returns the property list class for a property list.
+ <dd>Closes an existing property list class.
+
<dt><strong>Description:</strong>
- <dd><code>H5Pget_class</code> returns the property list class for the
- property list identified by the <code>plist</code> parameter.
- Valid property list classes are defined in the description of
- <code>H5Pcreate</code>.
+ <dd>Removes a property list class from the library.
+
+ <p>
+ Existing property lists of this class will continue to exist,
+ but new ones are not able to be created.
+
<dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier of property list to query.
- </dl>
+ <ul><table>
+ <tr>
+ <td><em>hid_t</em> <code>class</code></td>
+ <td>IN: Property list class to close</td></tr>
+ </table></ul>
+
<dt><strong>Returns:</strong>
- <dd>Returns a property list class if successful.
- Otherwise returns H5P_NO_CLASS (-1).
- <dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_class_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
+ <dd>Success: a non-negative value
+ <dd>Failure: a negative value
+
+ <dt><strong>Non-C APIs:</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pclose_class_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pclose_list" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-CloseList">H5Pclose_list</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Pclose_list</code>(
+ <em>hid_t</em> <code>plist</code>
+ )
+
+ <dt><strong>Purpose:</strong>
+ <dd>Closes a property list.
+
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pclose_list</code> closes a property list.
+
+ <p>
+ If a <code>close</code> callback exists for the property list class,
+ it is called before the property list is destroyed.
+ If <code>close</code> callbacks exist for any individual properties
+ in the property list, they are called after the class
+ <code>close</code> callback.
+
+ <dt><strong>Parameters:</strong>
+ <ul><table>
+ <tr>
+ <td><em>hid_t</em> <code>plist</code><td>
+ <td>IN: Property list to close</td></tr>
+ </table></ul>
+
+ <dt><strong>Returns:</strong>
+ <dd>Success: a non-negative value
+ <dd>Failure: a negative value
+
+ <dt><strong>Non-C APIs:</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pclose_list_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pcopy" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-Copy">H5Pcopy</a>
@@ -741,7 +775,138 @@ facilitate moving easily between them.</i>
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pcopy_prop" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-CopyProp">H5Pcopy_prop</a>
+
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Pcopy_prop</code>(
+ <em>hid_t</em> <code>dst_id</code>,
+ <em>hid_t</em> <code>src_id</code>,
+ <em>const char *</em><code>name</code>
+ )
+
+ <dt><strong>Purpose:</strong>
+ <dd>Copies a property from one list or class to another.
+
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pcopy_prop</code> copies a property from one property
+ list or class to another.
+
+ <p>
+ If a property is copied from one class to another, all the property
+ information will be first deleted from the destination class and
+ then the property information will be copied from the source class
+ into the destination class.
+
+ <p>
+ If a property is copied from one list to another, the property
+ will be first deleted from the destination list (generating a call
+ to the <code>close</code> callback for the property, if one exists)
+ and then the property is copied from the source list to the
+ destination list (generating a call to the <code>copy</code>
+ callback for the property, if one exists).
+
+ <p>
+ If the property does not exist in the class or list, this call is
+ equivalent to calling <code>H5Pregister</code> or <code>H5Pinsert</code>
+ (for a class or list, as appropriate) and the <code>create</code>
+ callback will be called in the case of the property being
+ copied into a list (if such a callback exists for the property).
+
+ <dt><strong>Parameters:</strong>
+ <ul><table>
+ <tr>
+ <td><em>hid_t</em> <code>dst_id</code></td>
+ <td>IN: Identifier of the destination property list or
+ class</td></tr>
+ <tr>
+ <td><em>hid_t</em> <code>src_id</code></td>
+ <td>IN: Identifier of the source property list or class</td></tr>
+ <tr>
+ <td><em>const char *</em><code>name</code></td>
+ <td>IN: Name of the property to copy</td></tr>
+ </table></ul>
+
+ <dt><strong>Returns:</strong>
+ <dd>Success: a non-negative value
+ <dd>Failure: a negative value
+
+ <dt><strong>Non-C APIs:</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pcopy_prop_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pcreate" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-Create">H5Pcreate</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>hid_t </em><code>H5Pcreate</code>(<em>H5P_class_t</em> <code>type</code>
+ )
+ <dt><strong>Purpose:</strong>
+ <dd>Creates a new property as an instance of a property list class.
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pcreate</code> creates a new property as an instance of some
+ property list class. The new property list is initialized
+ with default values for the specified class. The classes are:
+ <dl>
+ <dt><code>H5P_FILE_CREATE</code>
+ <dd>Properties for file creation.
+ See <a href="Files.html">Files</a>
+ in the <cite>HDF User's Guide</cite>
+ for details about the file creation properties.
+ <dt><code>H5P_FILE_ACCESS</code>
+ <dd>Properties for file access.
+ See <a href="Files.html">Files</a>
+ in the <cite>HDF User's Guide</cite>
+ for details about the file creation properties.
+ <dt><code>H5P_DATASET_CREATE</code>
+ <dd>Properties for dataset creation.
+ See <a href="Datasets.html">Datasets</a>
+ in the <cite>HDF User's Guide</cite>
+ for details about dataset creation properties.
+ <dt><code>H5P_DATASET_XFER</code>
+ <dd>Properties for raw data transfer.
+ See <a href="Datasets.html">Datasets</a>
+ in the <cite>HDF User's Guide</cite>
+ for details about raw data transfer properties.
+ <dt><code>H5P_MOUNT</code>
+ <dd>Properties for file mounting.
+ With this parameter, <code>H5Pcreate</code>
+ creates and returns a new mount property list
+ initialized with default values.
+ </dl>
+ <p>
+ This property list must eventually be closed with
+ <code>H5Pclose</code>;
+ otherwise, errors are likely to occur.
+ <dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>H5P_class_t</em> <code>type</code>
+ <dd>IN: The type of property list to create.
+ </dl>
+ <dt><strong>Returns:</strong>
+ <dd>Returns a property list identifier (<code>plist</code>) if successful;
+ otherwise Fail (-1).
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pcreate_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pcreate_class" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-CreateClass">H5Pcreate_class</a>
@@ -876,7 +1041,8 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pcreate_list" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-CreateList">H5Pcreate_list</a>
@@ -919,618 +1085,46 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pequal" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-Register">H5Pregister</a>
-
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pregister</code>(
- <em>hid_t</em> <code>class</code>,
- <em>const char *</em> <code>name</code>,
- <em>size_t</em> <code>size</code>,
- <em>void *</em> <code>default</code>,
- <em>H5P_prp_create_func_t</em> <code>create</code>,
- <em>H5P_prp_set_func_t</em> <code>set</code>,
- <em>H5P_prp_get_func_t</em> <code>get</code>,
- <em>H5P_prp_delete_func_t</em> <code>delete</code>,
- <em>H5P_prp_copy_func_t</em> <code>copy</code>,
- <em>H5P_prp_close_func_t</em> <code>close</code>
- )
-
- <dt><strong>Purpose:</strong>
- <dd>Registers a permanent property with a property list class.
-
- <dt><strong>Description:</strong>
- <dd><code>H5Pregister</code> registers a new property with a
- property list class.
- The property will exist in all property list objects of
- <code>class</code> created after this routine finishes. The name
- of the property must not already exist, or this routine will fail.
- The default property value must be provided and all new property
- lists created with this property will have the property value set
- to the default value. Any of the callback routines may be set to
- NULL if they are not needed.
-
- <P>
- Zero-sized properties are allowed and do not store any data in the
- property list. These may be used as flags to indicate the presence
- or absence of a particular piece of information. The default pointer
- for a zero-sized property may be set to NULL.
- The property <code>create</code> and <code>close</code> callbacks
- are called for zero-sized properties, but the <code>set</code> and
- <code>get</code> callbacks are never called.
- </P>
-
- The <code>create</code> routine is called when a new property list
- with this property is being created.
- The <code>H5P_prp_create_func_t</code> callback function is defined
- as follows:
- <ul><em>typedef herr_t</em> (*<code>H5P_prp_create_func_t</code>)(
- <em>const char *</em><code>name</code>,
- <em>size_t </em><code>size</code>,
- <em>void *</em><code>initial_value</code>);
- </ul>
- The parameters to this callback function are defined as follows:
- <ul><table>
- <tr>
- <td><em>const char *</em><code>name</code></td>
- <td>IN: The name of the property being modified</td></tr>
- <tr>
- <td><em>size_t</em> <code>size</code></td>
- <td>IN: The size of the property in bytes</td></tr>
- <tr>
- <td><em>void *</em><code>initial_value</code></td>
- <td>IN/OUT: The default value for the property being created,
- which will be passed to <code>H5Pregister</code></td></tr>
- </table></ul>
- The <code>create</code> routine may modify the value to be set and
- those changes will be stored as the initial value of the property.
- If the <code>create</code> routine returns a negative value,
- the new property value is not copied into the property and the
- create routine returns an error value.
- </P>
-
- The <code>set</code> routine is called before a new value is copied
- into the property.
- The <code>H5P_prp_set_func_t</code> callback function is defined
- as follows:
- <ul><em>typedef herr_t</em> (*H5P_prp_set_func_t)(
- <em>hid_t </em><code>prop_id</code>,
- <em>const char *</em><code>name</code>,
- <em>size_t </em><code>size</code>,
- <em>void *</em><code>new_value</code>);
- </ul>
- The parameters to this callback function are defined as follows:
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>prop_id</code></td>
- <td>IN: The identifier of the property list being modified</td></tr>
- <tr>
- <td><em>const char *</em><code>name</code></td>
- <td>IN: The name of the property being modified</td></tr>
- <tr>
- <td><em>size_t </em><code>size</code></td>
- <td>IN: The size of the property in bytes</td></tr>
- <tr>
- <td><em>void **</em><code>new_value</code></td>
- <td>IN/OUT: Pointer to new value pointer for the property being
- modified</td></tr>
- </table></ul>
- The <code>set</code> routine may modify the value pointer to be set
- and those changes will be used when setting the property's value.
- If the <code>set</code> routine returns a negative value, the new
- property value is not copied into the property and the
- <code>set</code> routine returns an error value.
- The <code>set</code> routine will not be called for the initial
- value, only the <code>create</code> routine will be called.
- <p>
- <strong>Note:</strong>
- The <code>set</code> callback function may be useful
- to range check the value being set for the property
- or may perform some tranformation or translation of the
- value set. The <code>get</code> callback would then
- reverse the transformation or translation.
- A single <code>get</code> or <code>set</code> callback
- could handle multiple properties by
- performing different actions based on the
- property name or other properties in the property list.
-
- <p>
- The <code>get</code> routine is called when a value is retrieved
- from a property value.
- The <code>H5P_prp_get_func_t</code> callback function is defined
- as follows:
- <ul><em>typedef herr_t</em> (*<code>H5P_prp_get_func_t</code>)(
- <em>hid_t </em><code>prop_id</code>,
- <em>const char *</em><code>name</code>,
- <em>size_t </em><code>size</code>,
- <em>void *</em><code>value</code>);
- </ul>
- The parameters to the callback function are defined as follows:
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>prop_id</code></td>
- <td>IN: The identifier of the property list being queried</td></tr>
- <tr>
- <td><em>const char *</em> <code>name</code></td>
- <td>IN: The name of the property being queried</td></tr>
- <tr>
- <td><em>size_t </em> <code>size</code></td>
- <td>IN: The size of the property in bytes</td></tr>
- <tr>
- <td><em>void *</em> <code>value</code></td>
- <td>IN/OUT: The value of the property being returned</td></tr>
- </table></ul>
- The <code>get</code> routine may modify the value to be returned from
- the query and those changes will be returned to the calling routine.
- If the <code>set</code> routine returns a negative value, the query
- routine returns an error value.
- </P>
-
- The <code>delete</code> routine is called when a property is being
- deleted from a property list.
- The <code>H5P_prp_delete_func_t</code> callback function is defined
- as follows:
- <ul><em>typedef herr_t</em> (*<code>H5P_prp_delete_func_t</code>)(
- <em>hid_t </em><code>prop_id</code>,
- <em>const char *</em><code>name</code>,
- <em>size_t </em><code>size</code>,
- <em>void *</em><code>value</code>);
- </ul>
- The parameters to the callback function are defined as follows:
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>prop_id</code></td>
- <td>IN: The identifier of the property list the property is being
- deleted from</td></tr>
- <tr>
- <td><em>const char *</em> <code>name</code></td>
- <td>IN: The name of the property in the list</td></tr>
- <tr>
- <td><em>size_t </em> <code>size</code></td>
- <td>IN: The size of the property in bytes</td></tr>
- <tr>
- <td><em>void *</em> <code>value</code></td>
- <td>IN: The value for the property being deleted</td></tr>
- </table></ul>
- The <code>delete</code> routine may modify the value passed in,
- but the value is not used by the library when the <code>delete</code>
- routine returns. If the <code>delete</code> routine returns
- a negative value, the property list delete routine returns
- an error value but the property is still deleted.
- </P>
-
- The <code>copy</code> routine is called when a new property list with
- this property is being created through a copy operation.
- The <code>H5P_prp_copy_func_t</code> callback function is defined
- as follows:
- <ul><em>typedef herr_t</em> (*<code>H5P_prp_copy_func_t</code>)(
- <em>const char *</em><code>name</code>,
- <em>size_t </em><code>size</code>,
- <em>void *</em><code>value</code>);
- </ul>
- The parameters to the callback function are defined as follows:
- <ul><table>
- <tr>
- <td><em>const char *</em><code>name</code></td>
- <td>IN: The name of the property being copied</td></tr>
- <tr>
- <td><em>size_t </em><code>size</code></td>
- <td>IN: The size of the property in bytes</td></tr>
- <tr>
- <td><em>void *</em><code>value</code></td>
- <td>IN/OUT: The value for the property being copied</td></tr>
- </table></ul>
- The <code>copy</code> routine may modify the value to be set and
- those changes will be stored as the new value of the property.
- If the <code>copy</code> routine returns a negative value,
- the new property value is not copied into the property and
- the copy routine returns an error value.
- </P>
-
- The <code>close</code> routine is called when a property list with
- this property is being closed.
- The <code>H5P_prp_close_func_t</code> callback function is defined
- as follows:
- <ul><em>typedef herr_t</em> (*<code>H5P_prp_close_func_t</code>)(
- <em>hid_t </em><code>prop_id</code>,
- <em>const char *</em><code>name</code>,
- <em>size_t </em><code>size</code>,
- <em>void *</em><code>value</code>);
- </ul>
- The parameters to the callback function are defined as follows:
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>prop_id</code></td>
- <td>IN: The identifier of the property list being
- closed</td></tr>
- <tr>
- <td><em>const char *</em><code>name</code></td>
- <td>IN: The name of the property in the list</td></tr>
- <tr>
- <td><em>size_t</em> <code>size</code></td>
- <td>IN: The size of the property in bytes</td></tr>
- <tr>
- <td><em>void *</em><code>value</code></td>
- <td>IN: The value for the property being closed</td></tr>
- </table></ul>
- The <code>close</code> routine may modify the value passed in,
- but the value is not used by the library when the
- <code>close</code> routine returns.
- If the <code>close</code> routine returns a negative value,
- the property list close routine returns an error value but
- the property list is still closed.
-
-<dt><strong>Parameters:</strong>
- <ul><dl>
- <dt><code>hid_t</code> <em>class</em>
- <dd>IN: Property list class to register permanent property
- within
- <dt><code>const char *</code> <em>name</em>
- <dd>IN: Name of property to register
- <dt><code>size_t</code> <em>size</em>
- <dd>IN: Size of property in bytes
- <dt><code>void *</code> <em>default</em>
- <dd>IN: Default value for property in newly created property
- lists
- <dt><code>H5P_prp_create_func_t</code> <em>create</em>
- <dd>IN: Callback routine called when a property list is being
- created and the property value will be initialized
- <dt><code>H5P_prp_set_func_t</code> <em>set</em>
- <dd>IN: Callback routine called before a new value is copied
- into the property's value
- <dt><code>H5P_prp_get_func_t</code> <em>get</em>
- <dd>IN: Callback routine called when a property value is
- retrieved from the property
- <dt><code>H5P_prp_delete_func_t</code> <em>delete</em>
- <dd>IN: Callback routine called when a property is deleted from
- a property list
- <dt><code>H5P_prp_copy_func_t</code> <em>copy</em>
- <dd>IN: Callback routine called when a property is copied from
- a property list
- <dt><code>H5P_prp_close_func_t</code> <em>close</em>
- <dd>IN: Callback routine called when a property list is being
- closed and the property value will be disposed of
- </dl></ul>
-
-<dt><strong>Returns:</strong>
- <dd>Success: a non-negative value
- <dd>Failure: a negative value
-
- <dt><strong>Non-C APIs:</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pregister_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-Insert">H5Pinsert</a>
+<dt><strong>Name:</strong> <a name="Property-Equal">H5Pequal</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pinsert</code>(
- <em>hid_t</em> <code>plid</code>,
- <em>const char *</em><code>name</code>,
- <em>size_t</em> <code>size</code>,
- <em>void *</em><code>value</code>,
- <em>H5P_prp_set_func_t</em> <code>set</code>,
- <em>H5P_prp_get_func_t</em> <code>get</code>,
- <em>H5P_prp_delete_func_t</em> <code>delete</code>,
- <em>H5P_prp_copy_func_t</em> <code>copy</code>,
- <em>H5P_prp_close_func_t</em> <code>close</code>
- )
+ <dd><em>htri_t</em> <code>H5Pequal</code>(
+ <em></em>hid_t</em> <em>id1</em>,
+ <em>hid_t</em> <em>id2</em>
+ )
<dt><strong>Purpose:</strong>
- <dd>Registers a temporary property with a property list.
+ <dd>Compares two property lists or classes for equality.
<dt><strong>Description:</strong>
- <dd><code>H5Pinsert</code> create a new property in a property list.
- The property will exist only in this property list and copies made
- from it.
-
- <p>
- The initial property value must be provided in
- <code>value</code> and the property value will be set accordingly.
-
- <p>
- The name of the property must not already exist in this list,
- or this routine will fail.
+ <dd><code>H5Pequal</code> compares two property lists or classes
+ to determine whether they are equal to one another.
<p>
- The <code>set</code> and <code>get</code> callback routines may
- be set to NULL if they are not needed.
-
- <p>
- Zero-sized properties are allowed and do not store any data in the
- property list. The default value of a zero-size property may be set
- to NULL. They may be used to indicate the presence or absence of a
- particular piece of information.
- </p>
-
- The <code>set</code> routine is called before a new value is copied
- into the property.
- The <code>H5P_prp_set_func_t</code> calback function is defined
- as follows:
- <ul><em>typedef herr_t</em> (*<code>H5P_prp_set_func_t</code>)(
- <em>hid_t</em> <code>prop_id</code>,
- <em>const char *</em><code>name</code>,
- <em>size_t </em><code>size</code>,
- <em>void *</em><code>new_value</code>);
- </ul>
- The parameters to the callback function are defined as follows:
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>prop_id</code></td>
- <td>IN: The identifier of the property list being modified</td></tr>
- <tr>
- <td><em>const char *</em><code>name</code></td>
- <td>IN: The name of the property being modified</td></tr>
- <tr>
- <td><em>size_t </em> <code>size</code></td>
- <td>IN: The size of the property in bytes</td></tr>
- <tr>
- <td><em>void **</em><code>new_value</code></td>
- <td>IN: Pointer to new value pointer for the property being
- modified</td></tr>
- </table></ul>
- The <code>set</code> routine may modify the value pointer to be set
- and those changes will be used when setting the property's value.
- If the <code>set</code> routine returns a negative value, the new
- property value is not copied into the property and the set routine
- returns an error value.
- The <code>set</code> routine will be called for the initial value.
- <p>
- <strong>Note:</strong>
- The <code>set</code> callback function may be useful
- to range check the value being set for the property
- or may perform some tranformation or translation of the
- value set. The <code>get</code> callback would then
- reverse the transformation or translation.
- A single <code>get</code> or <code>set</code> callback
- could handle multiple properties by
- performing different actions based on the
- property name or other properties in the property list.
-
- <p>
- The <code>get</code> routine is called when a value is retrieved
- from a property value.
- The <code>H5P_prp_get_func_t</code> callback functioin is defined
- as follows:
- <ul><em>typedef herr_t</em> (*<code>H5P_prp_get_func_t</code>)(
- <em>hid_t</em> <code>prop_id</code>,
- <em>const char *</em><code>name</code>,
- <em>size_t </em><code>size</code>,
- <em>void *</em><code>value</code>);
- </ul>
- where the parameters to the callback function are:
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>prop_id</code></td>
- <td>IN: The identifier of the property list being queried</td></tr>
- <tr>
- <td><em>const char *</em><emcodename</code></td>
- <td>IN: The name of the property being queried</td></tr>
- <tr>
- <td><em>size_t </em> <code>size</code></td>
- <td>IN: The size of the property in bytes</td></tr>
- <tr>
- <td><em>void *</em><code>value</code></td>
- <td>IN: The value of the property being returned</td></tr>
- </table></ul>
- The <code>get</code> routine may modify the value to be returned from
- the query and those changes will be preserved.
- If the <code>get</code> routine returns a negative value, the query
- routine returns an error value.
- </p>
-
- The <code>delete</code> routine is called when a property is being
- deleted from a property list.
- The <code>H5P_prp_delete_func_t</code> callback function is defined
- as follows:
- <ul><code>typedef herr_t</code> (*<code>H5P_prp_delete_func_t</code>)(
- <em>hid_t </em><code>prop_id</code>,
- <em>const char *</em><code>name</code>,
- <em>size_t </em><code>size</code>,
- <em>void *</em><code>value</code>);
- </ul>
- where the parameters to the callback function are:
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>prop_id</code></td>
- <td>IN: The identifier of the property list the property is
- being deleted from</td></tr>
- <tr>
- <td><em>const char *</em> <code>name</code></td>
- <td>IN: The name of the property in the list</td></tr>
- <tr>
- <td><em>size_t </em> <code>size</code></td>
- <td>IN: The size of the property in bytes</td></tr>
- <tr>
- <td><em>void *</em> <code>value</code></td>
- <td>IN: The value for the property being deleted</td></tr>
- </table></ul>
- The <code>delete</code> routine may modify the value passed in,
- but the value is not used by the library when the <code>delete</code>
- routine returns. If the <code>delete</code> routine returns a
- negative value, the property list delete routine returns an
- error value but the property is still deleted.
- </P>
-
- The <code>copy</code> routine is called when a new property list
- with this property is being created through a copy operation.
- The <code>H5P_prp_copy_func_t</code> collback function is defined
- as follows:
- <ul><em>typedef herr_t</em> (*<code>H5P_prp_copy_func_t</code>)(
- <em>const char *</em><code>name</code>,
- <em>size_t </em><code>size</code>,
- <em>void *</em><code>value</code>);
- </ul>
- where the parameters to the callback function are:
- <ul><table>
- <tr>
- <td><em>const char *</em><code>name</code></td>
- <td>IN: The name of the property being copied</td></tr>
- <tr>
- <td><em>size_t </em> <code>size</code></td>
- <td>IN: The size of the property in bytes</td></tr>
- <tr>
- <td><em>void *</em> <code>value</code></td>
- <td>IN/OUT: The value for the property being copied</td></tr>
- </table></ul>
- The <code>copy</code> routine may modify the value to be set and
- those changes will be stored as the new value of the property.
- If the <code>copy</code> routine returns a negative value, the
- new property value is not copied into the property and the
- copy routine returns an error value.
-
- <P>The <code>close</code> routine is called when a property list
- with this property is being closed.
- The <code>H5P_prp_close_func_t</code> callback function is defined
- as follows:
- <ul><em>typedef herr_t</em> (*<code>H5P_prp_close_func_t</code>)(
- <em>hid_t</em> <code>prop_id</code>,
- <em>const char *</em><code>name</code>,
- <em>size_t </em><code>size</code>,
- <em>void *</em><code>value</code>);
- </ul>
- The parameters to the callback function are defined as follows:
- <ul><table>
- <tr>
- <td><code>hid_t</em> <code>prop_id</em></td>
- <td>IN: The ID of the property list being closed</td></tr>
- <tr>
- <td><code>const char *</code><em>name</em></td>
- <td>IN: The name of the property in the list</td></tr>
- <tr>
- <td><code>size_t </code> <em>size</em></td>
- <td>IN: The size of the property in bytes</td></tr>
- <tr>
- <td><code>void *</code><em>value</em></td>
- <td>IN: The value for the property being closed</td></tr>
- </table></ul>
- The <code>close</code> routine may modify the value passed in, the value
- is not used by the library when the <code>close</code> routine returns.
- If the <code>close</code> routine returns a negative value, the
- property list close routine returns an error value but the property list
- is still closed.
-
- <p>
- <strong>Note:</strong>
- There is no <code>create</code> callback routine for temporary property
- list objects; the initial value is assumed to have any necessary setup
- already performed on it.
+ Either both <code>id1</code> and <code>id2</code> must be
+ property lists or both must be classes; comparing a list to a
+ class is an error.
<dt><strong>Parameters:</strong>
<ul><table>
<tr>
- <td><code>hid_t</code> <code>plid</em></td>
- <td>IN: Property list identifier to create temporary property
- within</td></tr>
- <tr>
- <td><em>const char *</em><code>name</code></td>
- <td>IN: Name of property to create</td></tr>
- <tr>
- <td><em>size_t</em> <code>size</code></td>
- <td>IN: Size of property in bytes</td></tr>
- <tr>
- <td><em>void *</em><code>value</code></td>
- <td>IN: Initial value for the property</td></tr>
- <tr>
- <td><em>H5P_prp_set_func_t</em> <code>set</code></td>
- <td>IN: Callback routine called before a new value is copied into
- the property's value</td></tr>
- <tr>
- <td><em>H5P_prp_get_func_t</em> <code>get</code></td>
- <td>IN: Callback routine called when a property value is retrieved
- from the property</td></tr>
- <tr>
- <td><em>H5P_prp_delete_func_t</em> <code>delete</code></td>
- <td>IN: Callback routine called when a property is deleted from
- a property list</td></tr>
- <tr>
- <td><em>H5P_prp_copy_func_t</em> <code>copy</code></td>
- <td>IN: Callback routine called when a property is copied from
- an existing property list</td></tr>
+ <td><em>hid_t</em> <code>id1</code></td>
+ <td>IN: First property object to be compared</td></tr>
<tr>
- <td><em>H5P_prp_close_func_t</em> <code>close</code></td>
- <td>IN: Callback routine called when a property list is being closed
- and the property value will be disposed of</td></tr>
+ <td><em>hid_t</em> <code>id2</code></td>
+ <td>IN: Second property object to be compared</td></tr>
</table></ul>
<dt><strong>Returns:</strong>
- <dd>Success: a non-negative value
- <dd>Failure: a negative value
-
- <dt><strong>Non-C APIs:</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pinsert_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-Set">H5Pset</a>
-
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset</code>(
- <em>hid_t</em> <code>plid</code>,
- <em>const char *</em><code>name</code>,
- <em>void *</em><code>value</code>)
- )
-
- <dt><strong>Purpose:</strong>
- <dd>Sets a property list value.
-
- <dt><strong>Description:</strong>
- <dd><code>H5Pset</code> sets a new value for a property in a
- property list. If there is a <code>set</code> callback
- routine registered for this property, the <code>value</code> will be
- passed to that routine and any changes to the <code>value</code>
- will be used when setting the property value.
- The information pointed to by the <code>value</code> pointer
- (possibly modified by the <code>set</code> callback) is copied into
- the property list value and may be changed by the application making
- the <code>H5Pset</code> call without affecting the property value.
-
- <P>
- The property name must exist or this routine will fail.
-
- <P>
- If the <code>set</code> callback routine returns an error, the
- property value will not be modified.
-
- <P>
- This routine may not be called for zero-sized properties
- and will return an error in that case.
-
- <dt><strong>Parameters:</strong>
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>plid</code>;
- <td>IN: Property list identifier to modify</td></tr>
- <tr>
- <td><em>const char *</em><code>name</code>;
- <td>IN: Name of property to modify</td></tr>
- <tr>
- <td><em>void *</em><code>value</code>;
- <td>IN: Pointer to value to set the property to</td></tr>
- </table></ul>
-
- <dt><strong>Returns:</strong>
- <dd>Success: a non-negative value
+ <dd>Success: TRUE (positive) if equal; FALSE (zero) if unequal
<dd>Failure: a negative value
<dt><strong>Non-C APIs:</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pequal_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -1538,7 +1132,8 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pexist" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-Exist">H5Pexist</a>
@@ -1581,218 +1176,64 @@ facilitate moving easily between them.</i>
-->
</dl>
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-GetSize">H5Pget_size</a>
-
- <dt><strong>Signature:</strong>
- <dd><em>int</em> <code>H5Pget_size</code>(
- <em>hid_t</em> <code>id</code>,
- <em>const char *</em><code>name</code>,
- <em>size_t *</em><code>size</code>
- )
-
- <dt><strong>Purpose:</strong>
- <dd>Queries the size of a property value in bytes.
-
- <dt><strong>Description:</strong>
- <dd><code>H5Pget_size</code> retrieves the size of a
- property's value in bytes. This function operates on both
- poperty lists and property classes
-
- <p>
- Zero-sized properties are allowed and return <code>0</code>.
-
-
- <dt><strong>Parameters:</strong>
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>id</code></td>
- <td>IN: Identifier of property object to query</td></tr>
- <tr>
- <td><em>const char *</em><code>name</code></td>
- <td>IN: Name of property to query</td></tr>
- <tr>
- <td><em>size_t *</em><code>size</code></td>
- <td>OUT: Size of property in bytes</td></tr>
- </table></ul>
-
- <dt><strong>Returns:</strong>
- <dd>Success: a non-negative value
- <dd>Failure: a negative value
-
- <dt><strong>Non-C APIs:</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_size_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-GetNProps">H5Pget_nprops</a>
-
- <dt><strong>Signature:</strong>
- <dd><em>int</em> <code>H5Pget_nprops</code>(
- <em>hid_t</em> <code>id</code>,
- <em>size_t *</em><code>nprops</code>
- )
-
- <dt><strong>Purpose:</strong>
- <dd>Queries number of properties in property list or class.
-
- <dt><strong>Description:</strong>
- <dd><code>H5Pget_nprops</code> retrieves the number of properties in a
- property list or class.
- If a property class identifier is given, the number of registered
- properties in the class is returned in <code>nprops</code>.
- If a property list identifier is given, the current number of
- properties in the list is returned in <code>nprops</code>.
-
- <dt><strong>Parameters:</strong>
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>id</code></td>
- <td>IN: Identifier of property object to query</td></tr>
- <tr>
- <td><em>size_t *</em><code>nprops</code></td>
- <td>OUT: Number of properties in object</td></tr>
- </table></ul>
-
- <dt><strong>Returns:</strong>
- <dd>Success: a non-negative value
- <dd>Failure: a negative value
-
- <dt><strong>Non-C APIs:</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_nprops_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pfill_value_defined" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetClassName">H5Pget_class_name</a>
-
- <dt><strong>Purpose:</strong>
- <dd>Retrieves the name of a class.
-
- <dt><strong>Signature:</strong>
- <dd><em>char *</em> <code>H5Pget_class_name</code>(
- <em>hid_t</em> <code>pcid</code>
- )
-
- <dt><strong>Description:</strong>
- <dd><code>H5Pget_class_name</code> retrieves the name of a
- generic property list class. The pointer to the name
- must be freed by the user after each successful call.
-
- <dt><strong>Parameters:</strong>
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>pcid</code></td>
- <td>IN: Identifier of the property class to query</td></tr>
- </table></ul>
-
- <dt><strong>Returns:</strong>
- <dd>Success: a pointer to an allocated string containing the class name
- <dd>Failure: NULL
-
- <dt><strong>Non-C APIs:</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_class_name_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-GetClassParent">H5Pget_class_parent</a>
-
- <dt><strong>Signature:</strong>
- <dd><em>hid_t</em> <code>H5Pget_class_parent</code>(
- <em>hid_t</em> <code>pcid</code>
- )
-
- <dt><strong>Purpose:</strong>
- <dd>Retrieves the parent class of a property class.
-
- <dt><strong>Description:</strong>
- <dd><code>H5Pget_class_parent</code> retrieves an identifier for the
- parent class of a property class.
-
- <dt><strong>Parameters:</strong>
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>pcid</code></td>
- <td>IN: Identifier of the property class to query</td></tr>
- </table></ul>
-
- <dt><strong>Returns:</strong>
- <dd>Success: a valid parent class object identifier
- <dd>Failure: a negative value
-
- <dt><strong>Non-C APIs:</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_class_parent_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-IsAClass">H5Pisa_class</a>
-
+ <dt><strong>Name:</strong> <a name="Property-FillValueDefined">H5Pfill_value_defined</a>
<dt><strong>Signature:</strong>
- <dd><em>htri_t</em> <code>H5Pisa_class</code>(
- <em>hid_t</em> <code>plist</code>,
- <em>hid_t</em> <code>pclass</code>
- )
-
+ <dd><em>herr_t </em><code>H5Pfill_value_defined</code>(<em>hid_t</em> <code>plist_id</code>,
+ <em>H5D_fill_value_t *</em><code>status</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Determines whether a property list is a member of a class.
-
+ <dd>Determines whether fill value is defined.
<dt><strong>Description:</strong>
- <dd><code>H5Pisa_class</code> checks to determine whether a property list
- is a member of the specified class.
-
+ <dd><code>H5Pfill_value_defined</code> determines whether a fill value
+ is defined in the dataset creation property list <code>plist_id</code>.
+ <p>
+ Valid values returnrd in <code>status</code> are as follows:
+ <table border=0 width="80%">
+ <tr valign="top"><td rowspan="3">&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ <code>H5D_FILL_VALUE_UNDEFINED</code>
+ </td><td>
+ Fill value is undefined.
+ </td></tr><tr valign="top"><td>
+ <code>H5D_FILL_VALUE_DEFAULT</code>
+ </td><td>
+ Fill value is the library default.
+ </td></tr><tr valign="top"><td>
+ <code>H5D_FILL_VALUE_USER_DEFINED</code>&nbsp;&nbsp;
+ </td><td>
+ Fill value is defined by the application.
+ </td></tr></table>
+ <dt><strong>Note:</strong>
+ <dd><code>H5Pfill_value_defined</code> is designed for use in
+ concert with the dataset fill value properties functions
+ <code>H5Pget_fill_value</code> and <code>H5Pget_fill_time</code>.
+ <p>
+ See <a href="RM_H5D.html#Dataset-Create">H5Dcreate</a> for
+ further cross-references.
<dt><strong>Parameters:</strong>
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>plist</code></td>
- <td>IN: Identifier of the property list</td></tr>
- <tr>
- <td><code>hid_t</code> <em>pclass</em></td>
- <td>IN: Identifier of the property class</td></tr>
- </table></ul>
-
+ <dl>
+ <dt><em>hid_t</em> <code>plist_id</code>
+ <dd>IN: Dataset creation property list identifier.
+ <dt><em>H5D_fill_value_t *</em><code>status</code>
+ <dd>OUT: Status of fill value in property list.
+ </dl>
<dt><strong>Returns:</strong>
- <dd>Success: TRUE (positive) if equal; FALSE (zero) if unequal
- <dd>Failure: a negative value
-
- <dt><strong>Non-C APIs:</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pisa_class_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pfill_value_defined_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-Get">H5Pget</a>
@@ -1854,454 +1295,103 @@ facilitate moving easily between them.</i>
-->
</dl>
-
-<hr>
-<dl>
-<dt><strong>Name:</strong> <a name="Property-Equal">H5Pequal</a>
-
- <dt><strong>Signature:</strong>
- <dd><em>htri_t</em> <code>H5Pequal</code>(
- <em></em>hid_t</em> <em>id1</em>,
- <em>hid_t</em> <em>id2</em>
- )
-
- <dt><strong>Purpose:</strong>
- <dd>Compares two property lists or classes for equality.
-
- <dt><strong>Description:</strong>
- <dd><code>H5Pequal</code> compares two property lists or classes
- to determine whether they are equal to one another.
-
- <p>
- Either both <code>id1</code> and <code>id2</code> must be
- property lists or both must be classes; comparing a list to a
- class is an error.
-
- <dt><strong>Parameters:</strong>
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>id1</code></td>
- <td>IN: First property object to be compared</td></tr>
- <tr>
- <td><em>hid_t</em> <code>id2</code></td>
- <td>IN: Second property object to be compared</td></tr>
- </table></ul>
-
- <dt><strong>Returns:</strong>
- <dd>Success: TRUE (positive) if equal; FALSE (zero) if unequal
- <dd>Failure: a negative value
-
- <dt><strong>Non-C APIs:</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pequal_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-Iterate">H5Piterate</a>
-
- <dt><strong>Purpose:</strong>
- <dd>Iterates over properties in a property class or list.
-
- <dt><strong>Signature:</strong>
- <dd><em>int</em> <code>H5Piterate</code>(
- <em>hid_t</em> <code>id</code>,
- <em>int *</em> <code>idx</code>,
- <em>H5P_iterate_t</em> <code>iter_func</code>,
- <em>void *</em> <code>iter_data</code>
- )
-
- <dt><strong>Description:</strong>
- <P><code>H5Piterate</code> iterates over the properties in the
- property object specified in <code>id</code>, which may be either a
- property list or a property class, performing a specified
- operation on each property in turn.
-
- <p>
- For each property in the object, <code>iter_func</code> and
- the additional information specified below are passed to the
- <code>H5P_iterate_t</code> operator function.
-
- <b><i>(NOTE: <code>iter_func</code> was changed to
- <code>H5P_iterate_t</code> in the preceding sentence.
- Is this correct?)</i></b>
-
- <p>
- The iteration begins with the <code>idx</code>-th property in
- the object; the next element to be processed by the operator
- is returned in <code>idx</code>.
- If <code>idx</code> is NULL, the iterator starts at the first
- property; 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.
- </p>
-
- The prototype for the <code>H5P_iterate_t</code> operator is
- as follows:
- <ul> <dl>
- <dt><em>typedef herr_t</em> (*<code>H5P_iterate_t</code>)(
- <em>hid_t</em> <code>id</code>,
- <em>const char *</em><code>>name</code>,
- <em>void *</em><code>iter_data</code>
- )
- </dl> </ul>
- The operation receives the property list or class identifier for
- the object being iterated over, <code>id</code>,
- the name of the current property within the object, <code>name</code>,
- and the pointer to the operator data passed in to
- <code>H5Piterate</code>, <code>iter_data</code>.
- </p>
-
- The valid return values from an operator are as follows:
- <ul><table>
- <tr>
- <td valign=top>Zero</td>
- <td>Causes the iterator to continue, returning zero when all
- properties have been processed</td></tr>
- <tr>
- <td valign=top>Positive</td>
- <td>Causes the iterator to immediately return that positive
- value, indicating short-circuit success. The iterator can
- be restarted at the index of the next property</td></tr>
- <tr>
- <td valign=top>Negative</td>
- <td>Causes the iterator to immediately return that value,
- indicating failure. The iterator can be restarted at the
- index of the next property</td></tr>
- </table></ul>
-
- <P>
- <code>H5Piterate</code> assumes that the properties in the object
- identified by <code>id</code> remain unchanged through the iteration.
- If the membership changes during the iteration, the function's behavior
- is undefined.
-
- <dt><strong>Parameters:</strong>
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>id</code></td>
- <td>IN: Identifier of property object to iterate over</td></tr>
- <tr>
- <td><em>int *</em> <code>idx</code></td>
- <td>IN/OUT: Index of the property to begin with</td></tr>
- <tr>
- <td><em>H5P_iterate_t</em> <code>iter_func</code></td>
- <td>IN: Function pointer to function to be called with each
- property iterated over</td></tr>
- <tr>
- <td><em>void *</em> <code>iter_data</code></td>
- <td>IN/OUT: Pointer to iteration data from user</td></tr>
- </table></ul>
-
-<dt><strong>Returns:</strong>
- <dd>Success: the return value of the last call to
- <code>iter_func</code> if it was non-zero;
- zero if all properties have been processed
- <dd>Failure: a negative value
- </table></ul>
-
- <!--
- <dt><strong>Non-C APIs:</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pXXX_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- -->
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-CopyProp">H5Pcopy_prop</a>
-
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pcopy_prop</code>(
- <em>hid_t</em> <code>dst_id</code>,
- <em>hid_t</em> <code>src_id</code>,
- <em>const char *</em><code>name</code>
- )
-
- <dt><strong>Purpose:</strong>
- <dd>Copies a property from one list or class to another.
-
- <dt><strong>Description:</strong>
- <dd><code>H5Pcopy_prop</code> copies a property from one property
- list or class to another.
-
- <p>
- If a property is copied from one class to another, all the property
- information will be first deleted from the destination class and
- then the property information will be copied from the source class
- into the destination class.
-
- <p>
- If a property is copied from one list to another, the property
- will be first deleted from the destination list (generating a call
- to the <code>close</code> callback for the property, if one exists)
- and then the property is copied from the source list to the
- destination list (generating a call to the <code>copy</code>
- callback for the property, if one exists).
-
- <p>
- If the property does not exist in the class or list, this call is
- equivalent to calling <code>H5Pregister</code> or <code>H5Pinsert</code>
- (for a class or list, as appropriate) and the <code>create</code>
- callback will be called in the case of the property being
- copied into a list (if such a callback exists for the property).
-
- <dt><strong>Parameters:</strong>
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>dst_id</code></td>
- <td>IN: Identifier of the destination property list or
- class</td></tr>
- <tr>
- <td><em>hid_t</em> <code>src_id</code></td>
- <td>IN: Identifier of the source property list or class</td></tr>
- <tr>
- <td><em>const char *</em><code>name</code></td>
- <td>IN: Name of the property to copy</td></tr>
- </table></ul>
-
- <dt><strong>Returns:</strong>
- <dd>Success: a non-negative value
- <dd>Failure: a negative value
-
- <dt><strong>Non-C APIs:</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pcopy_prop_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-Remove">H5Premove</a>
-
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Premove</code>(<code>plid, name</code>)
- <em>hid_t</em> <code>plid</code>;
- <em>const char *</em><code>name</code>
- )
-
- <dt><strong>Purpose:</strong>
- <dd>Removes a property from a property list.
-
- <dt><strong>Description:</strong>
- <dd><code>H5Premove</code> removes a property from a property list.
-
- <p>
- Both properties which were in existence when the property list
- was created (i.e. properties registered with <code>H5Pregister</code>)
- and properties added to the list after it was created (i.e. added
- with <code>H5Pinsert</code>) may be removed from a property list.
- Properties do not need to be removed from a property list before the
- list itself is closed; they will be released automatically when
- <code>H5Pclose</code> is called.
-
- <p>
- If a <code>close</code> callback exists for the removed property,
- it will be called before the property is released.
-
- <dt><strong>Parameters:</strong>
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>plid</code></td>
- <td>IN: Identifier of the property list to modify</td></tr>
- <tr>
- <td><em>const char *</em><code>name</code></td>
- <td>IN: Name of property to remove</td></tr>
- </table></ul>
-
- <dt><strong>Returns:</strong>
- <dd>Success: a non-negative value
- <dd>Failure: a negative value
-
- <dt><strong>Non-C APIs:</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5premove_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-Unregister">H5Punregister</a>
-
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Punregister</code>(
- <em>H5P_class_t</em> <code>class</code>,
- <em>const char *</em><code>name</code>
- )
-
- <dt><strong>Purpose:</strong>
- <dd>Removes a property from a property list class.
-
- <dt><strong>Description:</strong>
- <dd><code>H5Punregister</code> removes a property from a
- property list class.
-
- <p>
- Future property lists created of that class will not contain
- this property;
- existing property lists containing this property are not affected.
-
- <dt><strong>Parameters:</strong>
- <ul><table>
- <tr>
- <td><em>H5P_class_t</em> <code>class</code></td>
- <td>IN: Property list class from which to remove
- permanent property</td></tr>
- <tr>
- <td><em>const char *</em><code>name</code></td>
- <td>IN: Name of property to remove</td></tr>
- </table></ul>
-
- <dt><strong>Returns:</strong>
- <dd>Success: a non-negative value
- <dd>Failure: a negative value
-
- <dt><strong>Non-C APIs:</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5punregister_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-CloseList">H5Pclose_list</a>
-
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pclose_list</code>(
- <em>hid_t</em> <code>plist</code>
- )
-
- <dt><strong>Purpose:</strong>
- <dd>Closes a property list.
-
- <dt><strong>Description:</strong>
- <dd><code>H5Pclose_list</code> closes a property list.
-
- <p>
- If a <code>close</code> callback exists for the property list class,
- it is called before the property list is destroyed.
- If <code>close</code> callbacks exist for any individual properties
- in the property list, they are called after the class
- <code>close</code> callback.
-
- <dt><strong>Parameters:</strong>
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>plist</code><td>
- <td>IN: Property list to close</td></tr>
- </table></ul>
-
- <dt><strong>Returns:</strong>
- <dd>Success: a non-negative value
- <dd>Failure: a negative value
-
- <dt><strong>Non-C APIs:</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pclose_list_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_alignment" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-CloseClass">H5Pclose_class</a>
-
+ <dt><strong>Name:</strong> <a name="Property-GetAlignment">H5Pget_alignment</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pclose_class</code>(
- <em>hid_t</em> <code>class</code>
- )
-
+ <dd><em>herr_t</em> <code>H5Pget_alignment</code>(<em>hid_t</em> <code>plist</code>,
+ <em>hsize_t</em> <code>*threshold</code>,
+ <em>hsize_t</em> <code>*alignment</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Closes an existing property list class.
-
+ <dd>Retrieves the current settings for alignment properties from a
+ file access property list.
<dt><strong>Description:</strong>
- <dd>Removes a property list class from the library.
-
- <p>
- Existing property lists of this class will continue to exist,
- but new ones are not able to be created.
-
+ <dd><code>H5Pget_alignment</code> retrieves the current settings for
+ alignment properties from a file access property list.
+ The <code>threshold</code> and/or <code>alignment</code> pointers
+ may be null pointers (NULL).
<dt><strong>Parameters:</strong>
- <ul><table>
- <tr>
- <td><em>hid_t</em> <code>class</code></td>
- <td>IN: Property list class to close</td></tr>
- </table></ul>
-
+ <dl>
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Identifier of a file access property list.
+ <dt><em>hsize_t</em> <code>*threshold</code>
+ <dd>OUT: Pointer to location of return threshold value.
+ <dt><em>hsize_t</em> <code>*alignment</code>
+ <dd>OUT: Pointer to location of return alignment value.
+ </dl>
<dt><strong>Returns:</strong>
- <dd>Success: a non-negative value
- <dd>Failure: a negative value
-
- <dt><strong>Non-C APIs:</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pclose_class_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_alignment_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_alloc_time" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetVersion">H5Pget_version</a>
+ <dt><strong>Name:</strong> <a name="Property-GetAllocTime">H5Pget_alloc_time</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pget_version</code>(<em>hid_t</em> <code>plist</code>,
- <em>int *</em> <code>super</code>,
- <em>int *</em> <code>freelist</code>,
- <em>int *</em> <code>stab</code>,
- <em>int *</em> <code>shhdr</code>
+ <dd><em>herr_t </em><code>H5Pget_alloc_time</code>(<em>hid_t</em> <code>plist_id</code>,
+ <em>H5D_alloc_time_t *</em><code>alloc_time</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves the version information of various objects for
- a file creation property list.
+ <dd>Retrieves the timing for storage space allocation.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_version</code> retrieves the version information of various objects
- for a file creation property list. Any pointer parameters which are
- passed as NULL are not queried.
+ <dd><code>H5Pget_alloc_time</code> retrieves the timing for allocating
+ storage space for a dataset's raw data.
+ This property is set in the dataset creation property list
+ <code>plist_id</code>.
+ <p>
+ The timing setting is returned in <code>fill_time</code> as one of the
+ following values:
+ <table border=0 >
+ <tr valign="top"><td rowspan="4">&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ <code>H5D_ALLOC_TIME_DEFAULT</code>&nbsp;&nbsp;
+ </td><td>
+ Uses the default allocation time, based on the dataset storage method.<br>
+ See the <code>fill_time</code> description in
+ <a href="#Property-SetAllocTime">H5Pset_alloc_time</a> for
+ default allocation times for various storage methods.
+ </td></tr><tr valign="top"><td>
+ <code>H5D_ALLOC_TIME_EARLY</code>
+ </td><td>
+ All space is allocated when the dataset is created.
+ </td></tr><tr valign="top"><td>
+ <code>H5D_ALLOC_TIME_INCR</code>&nbsp;&nbsp;
+ </td><td>
+ Space is allocated incrementally as data is written to the dataset.
+ </td></tr><tr valign="top"><td>
+ <code>H5D_ALLOC_TIME_LATE</code>
+ </td><td>
+ All space is allocated when data is first written to the dataset.
+ </td></tr></table>
+ <dt><strong>Note:</strong>
+ <dd><code>H5Pget_alloc_time</code> is designed to work in concert
+ with the dataset fill value and fill value write time properties,
+ set with the functions
+ <code>H5Pget_fill_value</code> and <code>H5Pget_fill_time</code>.
+ <p>
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier of the file creation property list.
- <dt><em>int *</em> <code>super</code>
- <dd>OUT: Pointer to location to return super block version number.
- <dt><em>int *</em> <code>freelist</code>
- <dd>OUT: Pointer to location to return global freelist version number.
- <dt><em>int *</em> <code>stab</code>
- <dd>OUT: Pointer to location to return symbol table version number.
- <dt><em>int *</em> <code>shhdr</code>
- <dd>OUT: Pointer to location to return shared object header version number.
+ <dt><em>hid_t</em> <code>plist_id</code>
+ <dd>IN: Dataset creation property list identifier.
+ <dt><em>H5D_alloc_time_t *</em><code>alloc_time</code>
+ <dd>IN: When to allocate dataset storage space.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_version_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_alloc_time_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2309,33 +1399,42 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_btree_ratios" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetUserblock">H5Pset_userblock</a>
+ <dt><strong>Name:</strong> <a name="Property-GetBTreeRatios">H5Pget_btree_ratios</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pset_userblock</code>(<em>hid_t</em> <code>plist</code>,
- <em>hsize_t</em> <code>size</code>
- )
+ <dd><em>herr_t</em> <code>H5Pget_btree_ratios</code>(<em>hid_t</em> <code>plist</code>,
+ <em>double</em> *<code>left</code>,
+ <em>double</em> *<code>middle</code>,
+ <em>double</em> *<code>right</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Sets user block size.
+ <dd>Gets B-tree split ratios for a dataset transfer property list.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_userblock</code> sets the user block size of a
- file creation property list.
- The default user block size is 0; it may be set to any
- power of 2 equal to 512 or greater (512, 1024, 2048, etc.).
+ <dd><code>H5Pget_btree_ratios</code> returns the B-tree split ratios
+ for a dataset transfer property list.
+ <p>
+ The B-tree split ratios are returned through the non-<code>NULL</code>
+ arguments <code>left</code>, <code>middle</code>, and <code>right</code>,
+ as set by the <a href="#Property-SetBTreeRatios">H5Pset_btree_ratios</a> function.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier of property list to modify.
- <dt><em>hsize_t</em> <code>size</code>
- <dd>IN: Size of the user-block in bytes.
+ <dd>IN: The dataset transfer property list identifier.
+ <dt><em>double</em> <code>left</code>
+ <dd>OUT: The B-tree split ratio for left-most nodes.
+ <dt><em>double</em> <code>right</code>
+ <dd>OUT: The B-tree split ratio for right-most nodes and lone nodes.
+ <dt><em>double</em> <code>middle</code>
+ <dd>OUT: The B-tree split ratio for all other nodes.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_userblock_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_btree_ratios_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2343,31 +1442,37 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_buffer" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetUserblock">H5Pget_userblock</a>
+ <dt><strong>Name:</strong> <a name="Property-GetBuffer">H5Pget_buffer</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pget_userblock</code>(<em>hid_t</em> <code>plist</code>,
- <em>hsize_t *</em> <code>size</code>
+ <dd><em>hsize_t</em> <code>H5Pget_buffer</code>(<em>hid_t</em> <code>plist</code>,
+ <em>void</em> <code>**tconv</code>,
+ <em>void</em> <code>**bkg</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves the size of a user block.
+ <dd>Reads buffer settings.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_userblock</code> retrieves the size of a user block
- in a file creation property list.
+ <dd><code>H5Pget_buffer</code> reads values previously set
+ with H5Pset_buffer.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier for property list to query.
- <dt><em>hsize_t *</em> <code>size</code>
- <dd>OUT: Pointer to location to return user-block size.
+ <dd>IN: Identifier for the dataset transfer property list.
+ <dt><em>void</em> <code>**tconv</code>
+ <dd>OUT: Address of the pointer to application-allocated
+ type conversion buffer.
+ <dt><em>void</em> <code>**bkg</code>
+ <dd>OUT: Address of the pointer to application-allocated
+ background buffer.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns buffer size, in bytes, if successful;
+ otherwise 0 on failure.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_userblock_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_buffer_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2375,40 +1480,46 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_cache" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetSizes">H5Pset_sizes</a>
+ <dt><strong>Name:</strong> <a name="Property-GetCache">H5Pget_cache</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pset_sizes</code>(<em>hid_t</em> <code>plist</code>,
- <em>size_t</em> <code>sizeof_addr</code>,
- <em>size_t</em> <code>sizeof_size</code>
- )
+ <dd><em>herr_t</em> <code>H5Pget_cache</code>(<em>hid_t</em> <code>plist_id</code>,
+ <em>int</em> <code>*mdc_nelmts</code>,
+ <em>int</em> <code>*rdcc_nelmts</code>,
+ <em>size_t</em> <code>*rdcc_nbytes</code>,
+ <em>double</em> <code>*rdcc_w0</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Sets the byte size of the offsets and lengths used to address objects
- in an HDF5 file.
+ <dd>Queries the meta data cache and raw data chunk cache parameters.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_sizes</code> sets the byte size of the offsets and lengths used to
- address objects in an HDF5 file. This function is only valid for
- file creation property lists. Passing in a value of 0 for one of the
- sizeof parameters retains the current value. The default value
- for both values is same as <code>sizeof(hsize_t)</code> in the library
- (normally 8 bytes). Valid values currently are 2, 4,
- 8 and 16.
+ <dd><code>H5Pget_cache</code> retrieves the maximum possible
+ number of elements in the meta
+ data cache and raw data chunk cache, the maximum possible number of
+ bytes in the raw data chunk cache, and the preemption policy value.
+ <p>
+ Any (or all) arguments may be null pointers, in which case the
+ corresponding datum is not returned.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier of property list to modify.
- <dt><em>size_t</em> <code>sizeof_addr</code>
- <dd>IN: Size of an object offset in bytes.
- <dt><em>size_t</em> <code>sizeof_size</code>
- <dd>IN: Size of an object length in bytes.
+ <dt><em>hid_t</em> <code>plist_id</code>
+ <dd>IN: Identifier of the file access property list.
+ <dt><em>int</em> <code>*mdc_nelmts</code>
+ <dd>IN/OUT: Number of elements (objects) in the meta data cache.
+ <dt><em>int</em> <code>*rdcc_nelmts</code>
+ <dd>IN/OUT: Number of elements (objects) in the raw data chunk cache.
+ <dt><em>size_t</em> <code>*rdcc_nbytes</code>
+ <dd>IN/OUT: Total size of the raw data chunk cache, in bytes.
+ <dt><em>double</em> <code>*rdcc_w0</code>
+ <dd>IN/OUT: Preemption policy.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_sizes_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_cache_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2416,35 +1527,39 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_chunk" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetSizes">H5Pget_sizes</a>
+ <dt><strong>Name:</strong> <a name="Property-GetChunk">H5Pget_chunk</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pget_sizes</code>(<em>hid_t</em> <code>plist</code>,
- <em>size_t *</em> <code>sizeof_addr</code>,
- <em>size_t *</em> <code>sizeof_size</code>
+ <dd><em>int </em><code>H5Pget_chunk</code>(<em>hid_t</em> <code>plist</code>,
+ <em>int</em> <code>max_ndims</code>,
+ <em>hsize_t *</em> <code>dims</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves the size of the offsets and lengths used in an HDF5 file.
+ <dd>Retrieves the size of chunks for the raw data of a chunked layout dataset.
+
<dt><strong>Description:</strong>
- <dd><code>H5Pget_sizes</code> retrieves the size of the offsets
- and lengths used in an HDF5 file.
- This function is only valid for file creation property lists.
+ <dd><code>H5Pget_chunk</code> retrieves the size of chunks for the
+ raw data of a chunked layout dataset.
+ This function is only valid for dataset creation property lists.
+ At most, <code>max_ndims</code> elements of <code>dims</code>
+ will be initialized.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>plist</code>
<dd>IN: Identifier of property list to query.
- <dt><em>size_t *</em> <code>size</code>
- <dd>OUT: Pointer to location to return offset size in bytes.
- <dt><em>size_t *</em> <code>size</code>
- <dd>OUT: Pointer to location to return length size in bytes.
+ <dt><em>int</em> <code>max_ndims</code>
+ <dd>IN: Size of the <code>dims</code> array.
+ <dt><em>hsize_t *</em> <code>dims</code>
+ <dd>OUT: Array to store the chunk dimensions.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
+ <dd>Returns chunk dimensionality successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_sizes_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_chunk_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2452,49 +1567,31 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_class" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetSymK">H5Pset_sym_k</a>
+ <dt><strong>Name:</strong> <a name="Property-GetClass">H5Pget_class</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pset_sym_k</code>(<em>hid_t</em> <code>plist</code>,
- <em>int</em> <code>ik</code>,
- <em>int</em> <code>lk</code>
+ <dd><em>H5P_class_t </em><code>H5Pget_class</code>(<em>hid_t</em> <code>plist</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets the size of parameters used to control the symbol table nodes.
+ <dd>Returns the property list class for a property list.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_sym_k</code> sets the size of parameters used to
- control the symbol table nodes. This function is only valid
- for file creation property lists. Passing in a value of 0 for
- one of the parameters retains the current value.
- <p>
- <code>ik</code> is one half the rank of a tree that stores a symbol
- table for a group. Internal nodes of the symbol table are on
- average 75% full. That is, the average rank of the tree is
- 1.5 times the value of <code>ik</code>.
- <p>
- <code>lk</code> is one half of the number of symbols that can
- be stored in a symbol table node. A symbol table node is the
- leaf of a symbol table tree which is used to store a group.
- When symbols are inserted randomly into a group, the group's
- symbol table nodes are 75% full on average. That is, they
- contain 1.5 times the number of symbols specified by
- <code>lk</code>.
+ <dd><code>H5Pget_class</code> returns the property list class for the
+ property list identified by the <code>plist</code> parameter.
+ Valid property list classes are defined in the description of
+ <code>H5Pcreate</code>.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier for property list to query.
- <dt><em>int</em> <code>ik</code>
- <dd>IN: Symbol table tree rank.
- <dt><em>int</em> <code>lk</code>
- <dd>IN: Symbol table node size.
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Identifier of property list to query.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns a property list class if successful.
+ Otherwise returns H5P_NO_CLASS (-1).
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_sym_k_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_class_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2502,40 +1599,128 @@ facilitate moving easily between them.</i>
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_class_name" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-GetClassName">H5Pget_class_name</a>
+
+ <dt><strong>Purpose:</strong>
+ <dd>Retrieves the name of a class.
+
+ <dt><strong>Signature:</strong>
+ <dd><em>char *</em> <code>H5Pget_class_name</code>(
+ <em>hid_t</em> <code>pcid</code>
+ )
+
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pget_class_name</code> retrieves the name of a
+ generic property list class. The pointer to the name
+ must be freed by the user after each successful call.
+ <dt><strong>Parameters:</strong>
+ <ul><table>
+ <tr>
+ <td><em>hid_t</em> <code>pcid</code></td>
+ <td>IN: Identifier of the property class to query</td></tr>
+ </table></ul>
+
+ <dt><strong>Returns:</strong>
+ <dd>Success: a pointer to an allocated string containing the class name
+ <dd>Failure: NULL
+
+ <dt><strong>Non-C APIs:</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_class_name_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_class_parent" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetSymK">H5Pget_sym_k</a>
+ <dt><strong>Name:</strong> <a name="Property-GetClassParent">H5Pget_class_parent</a>
+
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pget_sym_k</code>(<em>hid_t</em> <code>plist</code>,
- <em>int *</em> <code>ik</code>,
- <em>int *</em> <code>lk</code>
- )
+ <dd><em>hid_t</em> <code>H5Pget_class_parent</code>(
+ <em>hid_t</em> <code>pcid</code>
+ )
+
<dt><strong>Purpose:</strong>
- <dd>Retrieves the size of the symbol table B-tree 1/2 rank
- and the symbol table leaf node 1/2 size.
+ <dd>Retrieves the parent class of a property class.
+
<dt><strong>Description:</strong>
- <dd><code>H5Pget_sym_k</code> retrieves the size of the
- symbol table B-tree 1/2 rank and the symbol table leaf
- node 1/2 size. This function is only valid for file creation
- property lists. If a parameter valued is set to NULL, that
- parameter is not retrieved. See the description for
- <a href="#Property-SetSymK">H5Pset_sym_k</a> for more
- information.
+ <dd><code>H5Pget_class_parent</code> retrieves an identifier for the
+ parent class of a property class.
+
+ <dt><strong>Parameters:</strong>
+ <ul><table>
+ <tr>
+ <td><em>hid_t</em> <code>pcid</code></td>
+ <td>IN: Identifier of the property class to query</td></tr>
+ </table></ul>
+
+ <dt><strong>Returns:</strong>
+ <dd>Success: a valid parent class object identifier
+ <dd>Failure: a negative value
+
+ <dt><strong>Non-C APIs:</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_class_parent_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_driver" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-GetDriver">H5Pget_driver</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>hid_t</em> <code>H5Pget_driver</code>(
+ <em>hid_t</em> <code>plist_id</code>
+ )
+ <dt><strong>Purpose:</strong>
+ <dd>Returns low-lever driver identifier.
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pget_driver</code> returns the identifier of the
+ low-level file driver associated with the file access property list
+ or data transfer property list <code>plist_id</code>.
+ <p>
+ Valid driver identifiers with the standard HDF5 library distribution
+ include the following:
+ <pre>
+ H5FD_CORE
+ H5FD_DPSS
+ H5FD_FAMILY
+ H5FD_GASS
+ H5FD_LOG
+ H5FD_MPIO
+ H5FD_MULTI
+ H5FD_SEC2
+ H5FD_STDIO
+ H5FD_STREAM </pre>
+ If a user defines and registers custom drivers or
+ if additional drivers are defined in an HDF5 distribution,
+ this list will be longer.
+ <p>
+ The returned driver identifier is only valid as long as the
+ file driver remains registered.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Property list to query.
- <dt><em>int *</em> <code>ik</code>
- <dd>OUT: Pointer to location to return the symbol table's B-tree 1/2 rank.
- <dt><em>int *</em> <code>size</code>
- <dd>OUT: Pointer to location to return the symbol table's leaf node 1/2 size.
+ <dt><em>hid_t</em> <code>plist_id</code>
+ <dd>IN: File access or data transfer property list identifier.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns a valid low-level driver identifier if successful.
+ Otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_sym_k_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_driver_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2543,74 +1728,85 @@ facilitate moving easily between them.</i>
-->
</dl>
+<!-- ********** MOVED TO TechNotes/VFLfunc.html **********
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetIstoreK">H5Pset_istore_k</a>
+ <dt><strong>Name:</strong> <a name="Property-GetDriverInfo">H5Pget_driver_info</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pset_istore_k</code>(<em>hid_t</em> <code>plist</code>,
- <em>int</em> <code>ik</code>
- )
+ <dd><em>void *</em><code>H5Pget_driver_info</code>(
+ <em>hid_t</em> <code>plist_id</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Sets the size of the parameter used to control the
- B-trees for indexing chunked datasets.
+ <dd>Returns a pointer to file driver information.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_istore_k</code> sets the size of the parameter
- used to control the B-trees for indexing chunked datasets.
- This function is only valid for file creation property lists.
- <p>
- <code>ik</code> is one half the rank of a tree that stores
- chunked raw data. On average, such a tree will be 75% full,
- or have an average rank of 1.5 times the value of
- <code>ik</code>.
+ <dd><code>H5Pget_driver_info</code> returns a pointer to
+ file driver-specific information for the low-level driver
+ associated with the file access or data transfer property list
+ <code>plist_id</code>.
+
+ <p>
+ <font color=red><b><i>Need more on "a pointer" or on what
+ is "pointed to." Might this be the <code>driver_info</code>
+ struct definition in <code>H5Pset_driver</code>?</i></b></font>
+
+ <p>
+ If no driver-specific properties have been registered,
+ <code>H5Pget_driver_info</code> returns <code>NULL</code>.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier of property list to query.
- <dt><em>int</em> <code>ik</code>
- <dd>IN: 1/2 rank of chunked storage B-tree.
+ <dt><em>hid_t</em> <code>plist_id</code>
+ <dd>IN: File access or data transfer property list identifier.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns a pointer to the struct containing
+ low-level driver information.
+ Otherwise returns <code>NULL</code>.
+ <p>
+ <code>NULL</code> is also returned if no driver-specific properties
+ have been registered.
+ No error is pushed on the stack in this case.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_istore_k_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
- -->
</dl>
+-->
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_dxpl_mpio" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetIstoreK">H5Pget_istore_k</a>
+ <dt><strong>Name:</strong> <a name="Property-GetDxplMpio">H5Pget_dxpl_mpio</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pget_istore_k</code>(<em>hid_t</em> <code>plist</code>,
- <em>int *</em> <code>ik</code>
- )
+ <dd><em>herr_t</em> <code>H5Pget_dxpl_mpio</code>(
+ <em>hid_t</em> <code>dxpl_id</code>,
+ <em>H5FD_mpio_xfer_t *</em><code>xfer_mode</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Queries the 1/2 rank of an indexed storage B-tree.
+ <dd>Returns the data transfer mode.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_istore_k</code> queries the 1/2 rank of
- an indexed storage B-tree.
- The argument <code>ik</code> may be the null pointer (NULL).
- This function is only valid for file creation property lists.
- <p>
- See <a href="#Property-SetIstoreK">H5Pset_istore_k</a> for details.
+ <dd><code>H5Pget_dxpl_mpio</code> queries the data transfer mode
+ currently set in the data transfer property list <code>dxpl_id</code>.
+ <p>
+ Upon return, <code>xfer_mode</code> contains the data transfer mode,
+ if it is non-null.
+ <p>
+ <code>H5Pget_dxpl_mpio</code> is not a collective function.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier of property list to query.
- <dt><em>int *</em> <code>ik</code>
- <dd>OUT: Pointer to location to return the chunked storage B-tree 1/2 rank.
+ <dt><em>hid_t</em> <code>dxpl_id</code>
+ <dd>IN: Data transfer property list identifier.
+ <dt><em>H5FD_mpio_xfer_t *</em><code>xfer_mode</code>
+ <dd>OUT: Data transfer mode.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful.
+ Otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_istore_k_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_dxpl_mpio_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2618,90 +1814,68 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_dxpl_multi" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetLayout">H5Pset_layout</a>
+ <dt><strong>Name:</strong> <a name="Property-GetDxplMulti">H5Pget_dxpl_multi</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pset_layout</code>(<em>hid_t</em> <code>plist</code>,
- <em>H5D_layout_t</em> <code>layout</code>
- )
+ <dd><em>herr_t</em> <code>H5Pget_dxpl_multi</code>(
+ <em>hid_t</em> <code>dxpl_id</code>,
+ <em>const hid_t *</em><code>memb_dxpl</code>
+ )
+<br>
+<br>
<dt><strong>Purpose:</strong>
- <dd>Sets the type of storage used to store the raw data for a dataset.
+ <dd>Returns multi-file data transfer property list information.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_layout</code> sets the type of storage used to store the
- raw data for a dataset.
- This function is only valid for dataset creation property lists.
- <p>
- Valid values for <code>layout</code> are:
- <ul><dl>
- <dt>H5D_COMPACT
- <dd>Store raw data in the dataset object header in file.
- This should only be used for very small amounts of raw
- data.
- The current limit is approximately 64K (HDF5 Release 1.6).
- <dt>H5D_CONTIGUOUS
- <dd>Store raw data separately from the object header in one
- large chunk in the file.
- <dt>H5D_CHUNKED
- <dd>Store raw data separately from the object header as
- chunks of data in separate locations in the file.
- </dl></ul>
+ <dd><code>H5Pget_dxpl_multi</code> returns the data transfer property list
+ information for the multi-file driver.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier of property list to query.
- <dt><em>H5D_layout_t</em> <code>layout</code>
- <dd>IN: Type of storage layout for raw data.
+ <dt><em>hid_t</em> <code>dxpl_id</code>,
+ <dd>IN: Data transfer property list identifier.
+ <dt><em>const hid_t *</em><code>memb_dxpl</code>
+ <dd>OUT: Array of data access property lists.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful.
+ Otherwise returns a negative value.
+ <!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_layout_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ -->
<!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_edc_check" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetLayout">H5Pget_layout</a>
+ <dt><strong>Name:</strong> <a name="Property-GetEdcCheck">H5Pget_edc_check</a>
<dt><strong>Signature:</strong>
- <dd><em>H5D_layout_t</em> <code>H5Pget_layout</code>(<em>hid_t</em> <code>plist</code>)
+ <dd><em>H5Z_EDC_t</em> <code>H5Pget_edc_check</code>(<em>hid_t</em> <code>plist</code>)
<dt><strong>Purpose:</strong>
- <dd>Returns the layout of the raw data for a dataset.
+ <dd>Determines whether error-detection is enabled for dataset reads.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_layout</code> returns the layout of the raw data for
- a dataset. This function is only valid for dataset creation
- property lists.
-
+ <dd><code>H5Pget_edc_check</code> queries the dataset transfer property
+ list <code>plist</code> to determine whether error detection
+ is enabled for data read operations.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier for property list to query.
+ <dd>IN: Dataset transfer property list identifier.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns the layout type (a non-negative value)
- of a dataset creation property list if successful.
- Valid return values are:
- <ul> <dl>
- <dt>H5D_COMPACT
- <dd>Raw data is stored in the object header in the file.
- <dt>H5D_CONTIGUOUS
- <dd>Raw data is stored separately from the object header in
- one contiguous chunk in the file.
- <dt>H5D_CHUNKED
- <dd>Raw data is stored separately from the object header in
- chunks in separate locations in the file.
- </dl> </ul>
- <p>
- Otherwise, returns a negative value indicating faliure.
+ <dd>Returns <code>H5P_ENABLE_EDC</code> or <code>H5P_DISABLE_EDC</code>
+ if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_layout_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_edc_check_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2709,40 +1883,56 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_external" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetChunk">H5Pset_chunk</a>
+ <dt><strong>Name:</strong> <a name="Property-GetExternal">H5Pget_external</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pset_chunk</code>(<em>hid_t</em> <code>plist</code>,
- <em>int</em> <code>ndims</code>,
- <em>const hsize_t *</em> <code>dim</code>
- )
+ <dd><em>herr_t</em> <code>H5Pget_external</code>(<em>hid_t</em> <code>plist</code>,
+ <em>int</em> <code>idx</code>,
+ <em>size_t</em> <code>name_size</code>,
+ <em>char</em> <code>*name</code>,
+ <em>off_t</em> <code>*offset</code>,
+ <em>hsize_t</em> <code>*size</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Sets the size of the chunks used to store a chunked layout dataset.
+ <dd>Returns information about an external file.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_chunk</code> sets the size of the chunks used to
- store a chunked layout dataset. This function is only valid
- for dataset creation property lists.
- The <code>ndims</code> parameter currently must be the same size
- as the rank of the dataset. The values of the <code>dim</code>
- array define the size of the chunks to store the dataset's raw data.
- As a side-effect, the layout of the dataset is changed to
- <code>H5D_CHUNKED</code>, if it is not already.
+ <dd><code>H5Pget_external</code> returns information about an external
+ file. The external file is specified by its index, <code>idx</code>,
+ which is a number from zero to N-1, where N is the value
+ returned by <code>H5Pget_external_count</code>.
+ At most <code>name_size</code> characters are copied into the
+ <code>name</code> array. If the external file name is
+ longer than <code>name_size</code> with the null terminator, the
+ return value is not null terminated (similar to <code>strncpy()</code>).
+ <p>
+ If <code>name_size</code> is zero or <code>name</code> is the
+ null pointer, the external file name is not returned.
+ If <code>offset</code> or <code>size</code> are null pointers
+ then the corresponding information is not returned.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier for property list to query.
- <dt><em>int</em> <code>ndims</code>
- <dd>IN: The number of dimensions of each chunk.
- <dt><em>const hsize_t *</em> <code>dim</code>
- <dd>IN: An array containing the size of each chunk.
+ <dd>IN: Identifier of a dataset creation property list.
+ <dt><em>int</em> <code>idx</code>
+ <dd>IN: External file index.
+ <dt><em>size_t</em> <code>name_size</code>
+ <dd>IN: Maximum length of <code>name</code> array.
+ <dt><em>char</em> <code>*name</code>
+ <dd>OUT: Name of the external file.
+ <dt><em>off_t</em> <code>*offset</code>
+ <dd>OUT: Pointer to a location to return an offset value.
+ <dt><em>hsize_t</em> <code>*size</code>
+ <dd>OUT: Pointer to a location to return the size of the
+ external file data.
</dl>
-<dt><strong>Returns:</strong>
+ <dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_chunk_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_external_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2750,38 +1940,29 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_external_count" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetChunk">H5Pget_chunk</a>
+ <dt><strong>Name:</strong> <a name="Property-GetExternalCount">H5Pget_external_count</a>
<dt><strong>Signature:</strong>
- <dd><em>int </em><code>H5Pget_chunk</code>(<em>hid_t</em> <code>plist</code>,
- <em>int</em> <code>max_ndims</code>,
- <em>hsize_t *</em> <code>dims</code>
- )
+ <dd><em>int</em> <code>H5Pget_external_count</code>(<em>hid_t</em> <code>plist</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Retrieves the size of chunks for the raw data of a chunked layout dataset.
-
+ <dd>Returns the number of external files for a dataset.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_chunk</code> retrieves the size of chunks for the
- raw data of a chunked layout dataset.
- This function is only valid for dataset creation property lists.
- At most, <code>max_ndims</code> elements of <code>dims</code>
- will be initialized.
+ <dd><code>H5Pget_external_count</code> returns the number of external files
+ for the specified dataset.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier of property list to query.
- <dt><em>int</em> <code>max_ndims</code>
- <dd>IN: Size of the <code>dims</code> array.
- <dt><em>hsize_t *</em> <code>dims</code>
- <dd>OUT: Array to store the chunk dimensions.
+ <dd>IN: Identifier of a dataset creation property list.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns chunk dimensionality successful;
+ <dd>Returns the number of external files if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_chunk_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_external_count_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2789,91 +1970,87 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_family_offset" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetAlignment">H5Pset_alignment</a>
+ <dt><strong>Name:</strong> <a name="Property-GetFamilyOffset">H5Pget_family_offset</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_alignment</code>(<em>hid_t</em> <code>plist</code>,
- <em>hsize_t</em> <code>threshold</code>,
- <em>hsize_t</em> <code>alignment</code>
+ <dd><em>herr_t</em> <code>H5Pget_family_offset</code> (
+ <em>hid_t</em> <code>fapl_id</code>,
+ <em>hsize_t *</em><code>offset</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets alignment properties of a file access property list.
+ <dd>Retrieves a data offset from the file access property list.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_alignment</code> sets the alignment properties
- of a file access property list
- so that any file object greater than or equal in size to
- <code>threshold</code> bytes will be aligned on an address
- which is a multiple of <code>alignment</code>. The addresses
- are relative to the end of the user block; the alignment is
- calculated by subtracting the user block size from the
- absolute file address and then adjusting the address to be a
- multiple of <code>alignment</code>.
- <p>
- Default values for <code>threshold</code> and
- <code>alignment</code> are one, implying
- no alignment. Generally the default values will result in
- the best performance for single-process access to the file.
- For MPI-IO and other parallel systems, choose an alignment
- which is a multiple of the disk block size.
+ <dd><code>H5Pget_family_offset</code> retrieves the value of <code>offset</code>
+ from the file access property list <code>fapl_id</code>
+ so that the user application
+ can retrieve a file handle for low-level access to a particluar member
+ of a family of files. The file handle is retrieved with a separate call
+ to <a href="RM_H5F.html#File-GetVfdHandle"><code>H5Fget_vfd_handle</code></a>
+ (or, in special circumstances, to <code>H5FDget_vfd_handle</code>;
+ see <cite>Virtual File Layer</cite> and <cite>List of VFL Functions</cite>
+ in <a href="TechNotes.html"><cite>HDF5 Technical Notes</cite></a>).
+ <p>
+ The data offset returned in <code>offset</code> is the offset
+ of the data in the HDF5 file that is stored on disk in the selected
+ member file in a family of files.
+ <p>
+ Use of this function is only appropriate for an HDF5 file written as a
+ family of files with the <code>FAMILY</code> file driver.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier for a file access property list.
- <dt><em>hsize_t</em> <code>threshold</code>
- <dd>IN: Threshold value.
- Must be non-negative.
- Note that setting the threshold value to 0 (zero) has
- the effect of a special case, forcing everything
- to be aligned.
- <dt><em>hsize_t</em> <code>alignment</code>
- <dd>IN: Alignment value.
- Must be a positive value.
+ <dt><em>hid_t</em> <code>fapl_id</code>
+ <dd>IN: File access property list identifier.
+ <dt><em>hsize_t *</em><code>offset</code>
+ <dd>IN: Offset in bytes within the HDF5 file.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
+ <!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_alignment_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ -->
<!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_fapl_core" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetAlignment">H5Pget_alignment</a>
+ <dt><strong>Name:</strong> <a name="Property-GetFaplCore">H5Pget_fapl_core</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_alignment</code>(<em>hid_t</em> <code>plist</code>,
- <em>hsize_t</em> <code>*threshold</code>,
- <em>hsize_t</em> <code>*alignment</code>
+ <dd><em>herr_t</em> <code>H5Pget_fapl_core</code>(
+ <em>hid_t</em> <code>fapl_id</code>,
+ <em>size_t</em> *<code>increment</code>,
+ <em>hbool_t</em> *<code>backing_store</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves the current settings for alignment properties from a
- file access property list.
+ <dd>Queries core file driver properties.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_alignment</code> retrieves the current settings for
- alignment properties from a file access property list.
- The <code>threshold</code> and/or <code>alignment</code> pointers
- may be null pointers (NULL).
+ <dd><code>H5Pget_fapl_core</code> queries the <code>H5FD_CORE</code>
+ driver properties as set by <code>H5Pset_fapl_core</code>.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier of a file access property list.
- <dt><em>hsize_t</em> <code>*threshold</code>
- <dd>OUT: Pointer to location of return threshold value.
- <dt><em>hsize_t</em> <code>*alignment</code>
- <dd>OUT: Pointer to location of return alignment value.
+ <dt><em>hid_t</em> <code>fapl_id</code>
+ <dd>IN: File access property list identifier.
+ <dt><em>size_t</em> *<code>increment</code>
+ <dd>OUT: Size, in bytes, of memory increments.
+ <dt><em>hbool_t</em> *<code>backing_store</code>
+ <dd>OUT: Boolean flag indicating whether to write the file
+ contents to disk when the file is closed.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful.
+ Otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_alignment_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_fapl_core_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2881,51 +2058,38 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_fapl_family" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetExternal">H5Pset_external</a>
+ <dt><strong>Name:</strong> <a name="Property-GetFaplFamily">H5Pget_fapl_family</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_external</code>(<em>hid_t</em> <code>plist</code>,
- <em>const char</em> <code>*name</code>,
- <em>off_t</em> <code>offset</code>,
- <em>hsize_t</em> <code>size</code>
+ <dd><em>herr_t</em> <code>H5Pget_fapl_family</code> (
+ <em>hid_t</em> <code>fapl_id</code>,
+ <em>hsize_t *</em><code>memb_size</code>,
+ <em>hid_t *</em><code>memb_fapl_id</code>
)
<dt><strong>Purpose:</strong>
- <dd>Adds an external file to the list of external files.
+ <dd>Returns file access property list information.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_external</code> adds an external file to the
- list of external files.
- <p>
- If a dataset is split across multiple files then the files
- should be defined in order. The total size of the dataset is
- the sum of the <code>size</code> arguments for all the external files. If
- the total size is larger than the size of a dataset then the
- dataset can be extended (provided the data space also allows
- the extending).
- <p>
- The <code>size</code> argument specifies number of bytes reserved
- for data in the external file.
- If <code>size</code> is set to <code>H5F_UNLIMITED</code>, the
- external file can be of unlimited size and no more files can be added to
- the external files list.
+ <dd><code>H5Pget_fapl_family</code> returns file access property list
+ for use with the family driver.
+ This information is returned through the output parameters.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier of a dataset creation property list.
- <dt><em>const char</em> <code>*name</code>
- <dd>IN: Name of an external file.
- <dt><em>off_t</em> <code>offset</code>
- <dd>IN: Offset, in bytes, from the beginning of the file
- to the location in the file where the data starts.
- <dt><em>hsize_t</em> <code>size</code>
- <dd>IN: Number of bytes reserved in the file for the data.
+ <dt><em>hid_t</em> <code>fapl_id</code>
+ <dd>IN: File access property list identifier.
+ <dt><em> hsize_t *</em><code>memb_size</code>
+ <dd>OUT: Size in bytes of each file member.
+ <dt><em>hid_t *</em><code>memb_fapl_id</code>
+ <dd>OUT: Identifier of file access property list for each
+ family member.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_external_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_fapl_family_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -2933,84 +2097,89 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_fapl_gass" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetExternalCount">H5Pget_external_count</a>
+ <dt><strong>Name:</strong> <a name="Property-GetFaplGass">H5Pget_fapl_gass</a>
<dt><strong>Signature:</strong>
- <dd><em>int</em> <code>H5Pget_external_count</code>(<em>hid_t</em> <code>plist</code>
+ <dd><em>herr_t</em> <code>H5Pget_fapl_gass</code>(
+ <em>hid_t</em> <code>fapl_id</code>,
+ <em>GASS_Info *</em><code>info</code>
)
<dt><strong>Purpose:</strong>
- <dd>Returns the number of external files for a dataset.
+ <dd>Retrieves GASS information.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_external_count</code> returns the number of external files
- for the specified dataset.
+ <dd>If the file access property list <code>fapl_id</code> is set
+ for use of the <code>H5FD_GASS</code> driver,
+ <code>H5Pget_fapl_gass</code> returns the <em>GASS_Info</em>
+ object through the <code>info</code> pointer.
+ <p>
+ The <em>GASS_Info</em> information is copied, so it is valid
+ only until the file access property list is modified or closed.
+ <dt><strong>Note:</strong>
+ <dd><code>H5Pget_fapl_gass</code> is an experimental function.
+ It is designed for use only when accessing files via the
+ GASS facility of the Globus environment.
+ For further information, see
+ <a href="http://www.globus.org/">http//www.globus.org/</a>.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier of a dataset creation property list.
+ <dt><em>hid_t</em> <code>fapl_id</code>,
+ <dd>IN: File access property list identifier.
+ <dt><em>GASS_Info *</em><code>info</code>
+ <dd>OUT: Pointer to the GASS information structure.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns the number of external files if successful;
- otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful.
+ Otherwise returns a negative value.
+ <!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_external_count_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ -->
<!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_fapl_mpio" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetExternal">H5Pget_external</a>
+ <dt><strong>Name:</strong> <a name="Property-GetFaplMpio">H5Pget_fapl_mpio</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_external</code>(<em>hid_t</em> <code>plist</code>,
- <em>int</em> <code>idx</code>,
- <em>size_t</em> <code>name_size</code>,
- <em>char</em> <code>*name</code>,
- <em>off_t</em> <code>*offset</code>,
- <em>hsize_t</em> <code>*size</code>
+ <dd><em>herr_t</em> <code>H5Pget_fapl_mpio</code>(
+ <em>hid_t</em> <code>fapl_id</code>,
+ <em>MPI_Comm *</em><code>comm</code>,
+ <em>MPI_Info *</em><code>info</code>
)
<dt><strong>Purpose:</strong>
- <dd>Returns information about an external file.
+ <dd> Returns MPI communicator information.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_external</code> returns information about an external
- file. The external file is specified by its index, <code>idx</code>,
- which is a number from zero to N-1, where N is the value
- returned by <code>H5Pget_external_count</code>.
- At most <code>name_size</code> characters are copied into the
- <code>name</code> array. If the external file name is
- longer than <code>name_size</code> with the null terminator, the
- return value is not null terminated (similar to <code>strncpy()</code>).
+ <dd>If the file access property list is set to the <code>H5FD_MPIO</code>
+ driver, <code>H5Pget_fapl_mpio</code> returns the MPI communicator and
+ information through the <code>comm</code> and <code>info</code>
+ pointers, if those values are non-null.
<p>
- If <code>name_size</code> is zero or <code>name</code> is the
- null pointer, the external file name is not returned.
- If <code>offset</code> or <code>size</code> are null pointers
- then the corresponding information is not returned.
+ Neither <code>comm</code> nor <code>info</code> is copied,
+ so they are valid only until the file access property list
+ is either modified or closed.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier of a dataset creation property list.
- <dt><em>int</em> <code>idx</code>
- <dd>IN: External file index.
- <dt><em>size_t</em> <code>name_size</code>
- <dd>IN: Maximum length of <code>name</code> array.
- <dt><em>char</em> <code>*name</code>
- <dd>OUT: Name of the external file.
- <dt><em>off_t</em> <code>*offset</code>
- <dd>OUT: Pointer to a location to return an offset value.
- <dt><em>hsize_t</em> <code>*size</code>
- <dd>OUT: Pointer to a location to return the size of the
- external file data.
+ <dt><em>hid_t</em> <code>fapl_id</code>
+ <dd>IN: File access property list identifier.
+ <dt><em>MPI_Comm *</em><code>comm</code>
+ <dd>OUT: MPI-2 communicator.
+ <dt><em>MPI_Info *</em><code>info</code>
+ <dd>OUT: MPI-2 info object.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful.
+ Otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_external_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_fapl_mpio_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -3018,135 +2187,86 @@ facilitate moving easily between them.</i>
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_fapl_mpiposix" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetFillValue">H5Pset_fill_value</a>
+ <dt><strong>Name:</strong> <a name="Property-GetFaplMpiPosix">H5Pget_fapl_mpiposix</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_fill_value</code>(<em>hid_t</em> <code>plist_id</code>,
- <em>hid_t</em> <code>type_id</code>,
- <em>const void *</em><code>value</code>
+ <dd><em>herr_t</em> <code>H5Pget_fapl_mpiposix</code>(
+ <em>hid_t</em> <code>fapl_id</code>,
+ <em>MPI_Comm *</em><code>comm</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets the fill value for a dataset.
+ <dd> Returns MPI communicator information.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_fill_value</code> sets the fill value for
- a dataset in the dataset creation property list.
+ <dd>If the file access property list is set to the <code>H5FD_MPIO</code>
+ driver, <code>H5Pget_fapl_mpiposix</code> returns
+ the MPI communicator through the <code>comm</code>
+ pointer, if those values are non-null.
<p>
- <code>value</code> is interpreted as being of datatype
- <code>type_id</code>. This datatype may differ from that of
- the dataset, but the HDF5 library must be able to convert
- <code>value</code> to the dataset datatype when the dataset
- is created.
- <p>
- The default fill value is <code>0</code> (zero), which is
- interpreted according to the actual dataset datatype.
- <p>
- Setting <code>value</code> to <code>NULL</code> indicates
- that the fill value is to be undefined.
- <dt><strong>Notes:</strong>
- <dd> Applications sometimes write data only to portions of
- an allocated dataset. It is often useful in such cases
- to fill the unused space with a known
- <span class="termEmphasis">fill value</span>.
- This function allows the user application to set that fill value;
- the functions
- <a href="RM_H5D.html#Dataset-Fill">H5Dfill</a> and
- <a href="RM_H5P.html#Property-SetFillTime">H5Pset_fill_time</a>,
- respectively, provide the ability
- to apply the fill value on demand or
- to set up its automatic application.
- <p>
- A fill value should be defined so that it is appropriate for
- the application. While the HDF5 default fill value is
- <code>0</code> (zero), it is often appropriate to use another value.
- It might be useful, for example, to use a value that is
- known to be impossible for the application to legitimately generate.
- <p>
- <code>H5Pset_fill_value</code> is designed to work in
- concert with <code>H5Pset_alloc_time</code> and
- <code>H5Pset_fill_time</code>.
- <code>H5Pset_alloc_time</code> and <code>H5Pset_fill_time</code>
- govern the timing of dataset storage allocation and fill value
- write operations and can be important in tuning application
- performance.
- <p>
- See <a href="RM_H5D.html#Dataset-Create">H5Dcreate</a> for
- further cross-references.
+ <code>comm</code> is not copied, so it is valid only
+ until the file access property list is either modified or closed.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist_id</code>
- <dd>IN: Dataset creation property list identifier.
- <dt><em>hid_t</em> <code>type_id</code>,
- <dd>IN: Datatype of <code>value</code>.
- <dt><em>const void *</em><code>value</code>
- <dd>IN: Pointer to buffer containing value to use as fill value.
+ <dt><em>hid_t</em> <code>fapl_id</code>
+ <dd>IN: File access property list identifier.
+ <dt><em>MPI_Comm *</em><code>comm</code>
+ <dd>OUT: MPI-2 communicator.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful.
+ Otherwise returns a negative value.
+<!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_fill_value_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_fapl_mpiposix_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
+--> <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_fapl_multi" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetFillValue">H5Pget_fill_value</a>
+ <dt><strong>Name:</strong> <a name="Property-GetFaplMulti">H5Pget_fapl_multi</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_fill_value</code>(<em>hid_t</em> <code>plist_id</code>,
- <em>hid_t</em> <code>type_id</code>,
- <em>void *</em><code>value</code>
+ <dd><em>herr_t</em> <code>H5Pget_fapl_multi</code>(
+ <em>hid_t</em> <code>fapl_id</code>,
+ <em>const H5FD_mem_t *</em><code>memb_map</code>,
+ <em>const hid_t *</em><code>memb_fapl</code>,
+ <em>const char **</em><code>memb_name</code>,
+ <em>const haddr_t *</em><code>memb_addr</code>,
+ <em>hbool_t *</em><code>relax</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves a dataset fill value.
+ <dd>Returns information about the multi-file access property list.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_fill_value</code> returns the dataset
- fill value defined in the dataset creation property list
- <code>plist_id</code>.
- <p>
- The fill value is returned through the <code>value</code>
- pointer and will be converted to the datatype specified
- by <code>type_id</code>.
- This datatype may differ from the
- fill value datatype in the property list,
- but the HDF5 library must be able to convert between the
- two datatypes.
- <p>
- If the fill value is undefined,
- i.e., set to <code>NULL</code> in the property list,
- <code>H5Pget_fill_value</code> will return an error.
- <code>H5Pfill_value_defined</code> should be used to
- check for this condition before
- <code>H5Pget_fill_value</code> is called.
- <p>
- Memory must be allocated by the calling application.
- <dt><strong>Note:</strong>
- <dd><code>H5Pget_fill_value</code> is designed to coordinate
- with the dataset storage allocation time and
- fill value write time properties, which can be retrieved
- with the functions <code>H5Pget_alloc_time</code>
- and <code>H5Pget_fill_time</code>, respectively.
- <p>
+ <dd><code>H5Pget_fapl_multi</code> returns information about the
+ multi-file access property list.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist_id</code>
- <dd>IN: Dataset creation property list identifier.
- <dt><em>hid_t</em> <code>type_id</code>,
- <dd>IN: Datatype identifier for the value passed
- via <code>value</code>.
- <dt><em>void *</em><code>value</code>
- <dd>OUT: Pointer to buffer to contain the returned fill value.
+ <dt><em>hid_t</em> <code>fapl_id</code>
+ <dd>IN: File access property list identifier.
+ <dt><em>const H5FD_mem_t *</em><code>memb_map</code>
+ <dd>OUT: Maps memory usage types to other memory usage types.
+ <dt><em>const hid_t *</em><code>memb_fapl</code>
+ <dd>OUT: Property list for each memory usage type.
+ <dt><em>const char **</em><code>memb_name</code>
+ <dd>OUT: Name generator for names of member files.
+ <dt><em>const haddr_t *</em><code>memb_addr</code>
+ <dd>OUT:
+ <dt><em>hbool_t *</em><code>relax</code>
+ <dd>OUT: Allows read-only access to incomplete file sets
+ when <code>TRUE</code>.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful.
+ Otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_fill_value_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_fapl_multi_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -3154,126 +2274,131 @@ facilitate moving easily between them.</i>
-->
</dl>
-
-
-
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_fapl_srb" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-FillValueDefined">H5Pfill_value_defined</a>
+ <dt><strong>Name:</strong> <a name="Property-GetFaplSrb">H5Pget_fapl_srb</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pfill_value_defined</code>(<em>hid_t</em> <code>plist_id</code>,
- <em>H5D_fill_value_t *</em><code>status</code>
- )
+ <dd><em>herr_t</em> <code>H5Pget_fapl_srb</code>(
+ <em>hid_t</em> <code>fapl_id</code>,
+ <em>SRB_Info *</em><code>info</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Determines whether fill value is defined.
+ <dd>Retrieves SRB information.
<dt><strong>Description:</strong>
- <dd><code>H5Pfill_value_defined</code> determines whether a fill value
- is defined in the dataset creation property list <code>plist_id</code>.
+ <dd>If the file access property list <code>fapl_id</code> is set
+ for use of the <code>H5FD_SRB</code> driver,
+ <code>H5Pget_fapl_srb</code> returns the <em>SRB_Info</em>
+ object through the <code>info</code> pointer.
<p>
- Valid values returnrd in <code>status</code> are as follows:
- <table border=0 width="80%">
- <tr valign="top"><td rowspan="3">&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
- <code>H5D_FILL_VALUE_UNDEFINED</code>
- </td><td>
- Fill value is undefined.
- </td></tr><tr valign="top"><td>
- <code>H5D_FILL_VALUE_DEFAULT</code>
- </td><td>
- Fill value is the library default.
- </td></tr><tr valign="top"><td>
- <code>H5D_FILL_VALUE_USER_DEFINED</code>&nbsp;&nbsp;
- </td><td>
- Fill value is defined by the application.
- </td></tr></table>
+ The <em>SRB_Info</em> information is copied, so it is valid
+ only until the file access property list is modified or closed.
<dt><strong>Note:</strong>
- <dd><code>H5Pfill_value_defined</code> is designed for use in
- concert with the dataset fill value properties functions
- <code>H5Pget_fill_value</code> and <code>H5Pget_fill_time</code>.
- <p>
- See <a href="RM_H5D.html#Dataset-Create">H5Dcreate</a> for
- further cross-references.
+ <dd><code>H5Pset_fapl_gass</code> is an experimental function.
+ It is designed for use only when accessing files via the
+ Storage Resource Broker (SRB). For further information, see
+ <a href="http://www.npaci.edu/Research/DI/srb/">http//www.npaci.edu/Research/DI/srb/</a>.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist_id</code>
- <dd>IN: Dataset creation property list identifier.
- <dt><em>H5D_fill_value_t *</em><code>status</code>
- <dd>OUT: Status of fill value in property list.
+ <dt><em>hid_t</em> <code>fapl_id</code>
+ <dd>IN: File access property list identifier.
+ <dt><em>SRB_Info *</em><code>info</code>
+ <dd>OUT: Pointer to the SRB information structure.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful.
+ Otherwise returns a negative value.
+ <!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pfill_value_defined_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ -->
<!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_fapl_stream" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetFillTime">H5Pset_fill_time</a>
+ <dt><strong>Name:</strong> <a name="Property-GetFaplStream">H5Pget_fapl_stream</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pset_fill_time</code>(<em>hid_t</em> <code>plist_id</code>,
- <em>H5D_fill_time_t</em> <code>fill_time</code>
- )
+ <dd><em>herr_t</em> <code>H5Pget_fapl_stream</code>(
+ <em>hid_t</em> <code>fapl_id</code>,
+ <em>H5FD_stream_fapl_t *</em><code>fapl</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Sets the time when fill values are written to a dataset.
+ <dd>Returns the streaming I/O driver settings.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_fill_time</code> sets up the timing for writing fill values
- to a dataset.
- This property is set in the dataset creation property list <code>plist_id</code>.
+ <dd><code>H5Pget_fapl_stream</code> returns the file access properties
+ set for the use of the streaming I/O driver.
<p>
- Timing is specified in <code>fill_time</code> with one of the following values:
- <table border=0 >
- <tr valign="top"><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
- <code>H5D_FILL_TIME_IFSET</code>&nbsp;&nbsp;
- </td><td>
- Write fill values to the dataset when storage space is allocated
- only if there is a user-defined fill value, i.e., one set with
- <a href="#Property-SetFillValue">H5Pset_fill_value</a>.
- &nbsp;&nbsp;(Default)
- </td></tr><tr valign="top"><td>&nbsp;</td><td>
- <code>H5D_FILL_TIME_ALLOC</code>
- </td><td>
- Write fill values to the dataset when storage space is allocated.
- </td></tr><tr valign="top"><td>&nbsp;</td><td>
- <code>H5D_FILL_TIME_NEVER</code>
- </td><td>
- Never write fill values to the dataset.
- </td></tr></table>
- <dt><strong>Note:</strong>
- <dd><code>H5Pset_fill_time</code> is designed for coordination
- with the dataset fill value and
- dataset storage allocation time properties, set with the functions
- <code>H5Pset_fill_value</code> and <code>H5Pset_alloc_time</code>.
- <p>
- See <a href="RM_H5D.html#Dataset-Create">H5Dcreate</a> for
- further cross-references.
+ <code>H5Pset_fapl_stream</code> and <code>H5Pget_fapl_stream</code>
+ are not intended for use in a parallel environment.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist_id</code>
- <dd>IN: Dataset creation property list identifier.
- <dt><em>H5D_fill_time_t</em> <code>fill_time</code>
- <dd>IN: When to write fill values to a dataset.
+ <dt><em>hid_t</em> <code>fapl_id</code>
+ <dd>IN: File access property list identifier.
+ <dt><em>H5FD_stream_fapl_t *</em><code>fapl</code>
+ <dd>OUT: The streaming I/O file access property list.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful.
+ Otherwise returns a negative value.
+ <!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_fill_time_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ -->
<!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_fclose_degree" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-GetFcloseDegree">H5Pget_fclose_degree</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Pget_fclose_degree</code>(<em>hid_t</em> <code>fapl_id</code>,
+ <em>H5F_close_degree_t</em> <code>fc_degree</code>)
+ <dt><strong>Purpose:</strong>
+ <dd>Returns the file close degree.
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pget_fclose_degree</code> returns the current setting of the file
+ close degree property <code>fc_degree</code> in the file access property list
+ <code>fapl_id</code>. 
+ <p> The value of <code>fc_degree</code> determines how aggressively <code>H5Fclose</code>
+ deals with objects within a file that remain open when <code>H5Fclose</code>
+ is called to close that file.  <code>fc_degree</code> can have any one of
+ four valid values as described above in <a href="#Property-SetFcloseDegree"><code>H5Pset_fclose_degree</code></a>.
+ <dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>fapl_id</code>
+ <dd>IN: File access property list identifier.
+ <dt><em>H5F_close_degree_t</em> <code>fc_degree</code>
+ <dd>OUT: Pointer to a location to which to return the file close degree
+ property, the value of <code>fc_degree</code>.
+ </dl>
+ <dt><strong>Returns:</strong>
+ <dd>Returns a non-negative value if successful. Otherwise returns a negative
+ value.
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_fclose_degree_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_fill_time" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-GetFillTime">H5Pget_fill_time</a>
@@ -3331,336 +2456,61 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_fill_value" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetAllocTime">H5Pset_alloc_time</a>
+ <dt><strong>Name:</strong> <a name="Property-GetFillValue">H5Pget_fill_value</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pset_alloc_time</code>(<em>hid_t</em> <code>plist_id</code>,
- <em>H5D_alloc_time_t</em> <code>alloc_time</code>
- )
+ <dd><em>herr_t</em> <code>H5Pget_fill_value</code>(<em>hid_t</em> <code>plist_id</code>,
+ <em>hid_t</em> <code>type_id</code>,
+ <em>void *</em><code>value</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Sets the timing for storage space allocation.
+ <dd>Retrieves a dataset fill value.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_alloc_time</code> sets up the timing for the allocation of
- storage space for a dataset's raw data.
- This property is set in the dataset creation property list
- <code>plist_id</code>.
+ <dd><code>H5Pget_fill_value</code> returns the dataset
+ fill value defined in the dataset creation property list
+ <code>plist_id</code>.
<p>
- Timing is specified in <code>fill_time</code> with one of the
- following values:
- <table border=0 >
- <tr valign="top"><td rowspan="4">&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
- <code>H5D_ALLOC_TIME_DEFAULT</code>&nbsp;&nbsp;
- </td><td>
- Allocate dataset storage space at the default time.<br>
- (Defaults differ by storage method.)
- </td></tr><tr valign="top"><td>
- <code>H5D_ALLOC_TIME_EARLY</code>
- </td><td>
- Allocate all space when the dataset is created.<br>
- (Default for compact datasets.)
- </td></tr><tr valign="top"><td>
- <code>H5D_ALLOC_TIME_INCR</code>&nbsp;&nbsp;
- </td><td>
- Allocate space incrementally, as data is written to the dataset.<br>
- (Default for chunked storage datasets.)
- <li>Chunked datasets:
- Storage space allocation for each chunk is deferred until data
- is written to the chunk.
- <li>Contiguous datasets:
- Incremental storage space allocation for contiguous data
- is treated as late allocation.
- <li>Compact datasets:
- Incremental allocation is not allowed with compact datasets;
- </em><code>H5Pset_alloc_time</code> will return an error.
- </td></tr><tr valign="top"><td>
- <code>H5D_ALLOC_TIME_LATE</code>
- </td><td>
- Allocate all space when data is first written to the dataset.<br>
- (Default for contiguous datasets.)
- </td></tr></table>
- <dt><strong>Note:</strong>
- <dd><code>H5Pset_alloc_time</code> is designed to work in concert
- with the dataset fill value and fill value write time properties,
- set with the functions
- <code>H5Pset_fill_value</code> and <code>H5Pset_fill_time</code>.
- <p>
- <p>
- See <a href="RM_H5D.html#Dataset-Create">H5Dcreate</a> for
- further cross-references.
- <dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>plist_id</code>
- <dd>IN: Dataset creation property list identifier.
- <dt><em>H5D_alloc_time_t</em> <code>alloc_time</code>
- <dd>IN: When to allocate dataset storage space.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
- <dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_alloc_time_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-GetAllocTime">H5Pget_alloc_time</a>
- <dt><strong>Signature:</strong>
- <dd><em>herr_t </em><code>H5Pget_alloc_time</code>(<em>hid_t</em> <code>plist_id</code>,
- <em>H5D_alloc_time_t *</em><code>alloc_time</code>
- )
- <dt><strong>Purpose:</strong>
- <dd>Retrieves the timing for storage space allocation.
- <dt><strong>Description:</strong>
- <dd><code>H5Pget_alloc_time</code> retrieves the timing for allocating
- storage space for a dataset's raw data.
- This property is set in the dataset creation property list
- <code>plist_id</code>.
+ The fill value is returned through the <code>value</code>
+ pointer and will be converted to the datatype specified
+ by <code>type_id</code>.
+ This datatype may differ from the
+ fill value datatype in the property list,
+ but the HDF5 library must be able to convert between the
+ two datatypes.
<p>
- The timing setting is returned in <code>fill_time</code> as one of the
- following values:
- <table border=0 >
- <tr valign="top"><td rowspan="4">&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
- <code>H5D_ALLOC_TIME_DEFAULT</code>&nbsp;&nbsp;
- </td><td>
- Uses the default allocation time, based on the dataset storage method.<br>
- See the <code>fill_time</code> description in
- <a href="#Property-SetAllocTime">H5Pset_alloc_time</a> for
- default allocation times for various storage methods.
- </td></tr><tr valign="top"><td>
- <code>H5D_ALLOC_TIME_EARLY</code>
- </td><td>
- All space is allocated when the dataset is created.
- </td></tr><tr valign="top"><td>
- <code>H5D_ALLOC_TIME_INCR</code>&nbsp;&nbsp;
- </td><td>
- Space is allocated incrementally as data is written to the dataset.
- </td></tr><tr valign="top"><td>
- <code>H5D_ALLOC_TIME_LATE</code>
- </td><td>
- All space is allocated when data is first written to the dataset.
- </td></tr></table>
+ If the fill value is undefined,
+ i.e., set to <code>NULL</code> in the property list,
+ <code>H5Pget_fill_value</code> will return an error.
+ <code>H5Pfill_value_defined</code> should be used to
+ check for this condition before
+ <code>H5Pget_fill_value</code> is called.
+ <p>
+ Memory must be allocated by the calling application.
<dt><strong>Note:</strong>
- <dd><code>H5Pget_alloc_time</code> is designed to work in concert
- with the dataset fill value and fill value write time properties,
- set with the functions
- <code>H5Pget_fill_value</code> and <code>H5Pget_fill_time</code>.
+ <dd><code>H5Pget_fill_value</code> is designed to coordinate
+ with the dataset storage allocation time and
+ fill value write time properties, which can be retrieved
+ with the functions <code>H5Pget_alloc_time</code>
+ and <code>H5Pget_fill_time</code>, respectively.
<p>
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>plist_id</code>
<dd>IN: Dataset creation property list identifier.
- <dt><em>H5D_alloc_time_t *</em><code>alloc_time</code>
- <dd>IN: When to allocate dataset storage space.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
- <dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_alloc_time_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-
-
-
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-SetFilter">H5Pset_filter</a>
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_filter</code>(<em>hid_t</em> <code>plist</code>,
- <em>H5Z_filter_t</em> <code>filter</code>,
- <em>unsigned int</em> <code>flags</code>,
- <em>size_t</em> <code>cd_nelmts</code>,
- <em>const unsigned int</em> <code>cd_values[]</code>
- )
- <dt><strong>Purpose:</strong>
- <dd>Adds a filter to the filter pipeline.
- <dt><strong>Description:</strong>
- <dd><code>H5Pset_filter</code> adds the specified
- <code>filter</code> and corresponding properties to the
- end of an output filter pipeline.
- If <code>plist</code> is a dataset creation property list,
- the filter is added to the permanent filter pipeline;
- if <code>plist</code> is a dataset transfer property list,
- the filter is added to the transient filter pipeline.
- <p>
- The array <code>cd_values</code> contains
- <code>cd_nelmts</code> integers which are auxiliary data
- for the filter. The integer values will be stored in the
- dataset object header as part of the filter information.
- <p>
- The <code>flags</code> argument is a bit vector with
- the following fields specifying certain general properties
- of the filter:
- <center>
- <table align=center width="75%">
- <tr valign=top>
- <td valign=top><code>H5Z_FLAG_OPTIONAL</code>&nbsp;&nbsp;</td>
- <td valign=top>If this bit is set then the filter is
- optional. If the filter fails (see below) during an
- <code>H5Dwrite</code> operation then the filter is
- just excluded from the pipeline for the chunk for which
- it failed; the filter will not participate in the
- pipeline during an <code>H5Dread</code> of the chunk.
- This is commonly used for compression filters: if the
- filter result would be larger than the input, then
- the compression filter returns failure and the
- uncompressed data is stored in the file. If this bit is
- clear and a filter fails, then <code>H5Dwrite</code>
- or <code>H5Dread</code> also fails.
- <p>
- This flag should not be set for the Fletcher32 checksum
- filter as it will bypass the checksum filter without
- reporting checksum errors to an application.</td>
- </tr>
- </table>
- </center>
- <p>
- The <code>filter</code> parameter specifies the filter to be set.
- Valid values are as follows:
-
- <center>
- <table width=75%>
- <tr valign=top align=left><td>
- <code>H5Z_FILTER_DEFLATE</code>
- </td><td>
- Data compression filter, employing the gzip algorithm
- </td></tr>
- <tr valign=top align=left><td>
- <code>H5Z_FILTER_SHUFFLE</code>
- </td><td>
- Data shuffling filter
- </td></tr>
- <tr valign=top align=left><td>
- <code>H5Z_FILTER_FLETCHER32&nbsp;&nbsp;</code>
- </td><td>
- Error detection filter, employing the Fletcher32 checksum algorithm
- </td></tr>
- <tr valign=top align=left><td>
- <code>H5Z_FILTER_SZIP</code>
- </td><td>
- Data compression filter, employing the SZIP algorithm
- </td></tr>
- </table>
- </center>
- <p>
- Also see <a href="#Property-SetEdcCheck">H5Pset_edc_check</a> and
- <a href="Property-SetFilterCallback">H5Pset_filter_callback</a>.
-
- <dt><strong>Notes:</strong>
- <dd>This function currently supports only the permanent filter
- pipeline; <code>plist</code> must be a dataset creation
- property list.
- <p>
- If multiple filters are set for a property list, they will be
- applied to each chunk in the order in which they were set.
- <dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Property list identifier.
- <dt><em>H5Z_filter_t</em> <code>filter</code>
- <dd>IN: Filter to be added to the pipeline.
- <dt><em>unsigned int</em> <code>flags</code>
- <dd>IN: Bit vector specifying certain general properties
- of the filter.
- <dt><em>size_t</em> <code>cd_nelmts</code>
- <dd>IN: Number of elements in <code>cd_values</code>.
- <dt><em>const unsigned int</em> <code>cd_values[]</code>
- <dd>IN: Auxiliary data for the filter.
+ <dt><em>hid_t</em> <code>type_id</code>,
+ <dd>IN: Datatype identifier for the value passed
+ via <code>value</code>.
+ <dt><em>void *</em><code>value</code>
+ <dd>OUT: Pointer to buffer to contain the returned fill value.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_filter_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-AllFiltersAvail">H5Pall_filters_avail</a>
- <dt><strong>Signature:</strong>
- <dd><em>htri_t</em> <code>H5Pall_filters_avail</code>(<em>hid_t</em> <code>dcpl_id</code>)
- <dt><strong>Purpose:</strong>
- <dd>Verifies that all required filters are available.
- <dt><strong>Description:</strong>
- <dd><code>H5Pall_filters_avail</code> verifies that all of the filters
- set in the dataset creation property list <code>dcpl_id</code> are
- currently available.
- <dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>dcpl_id</code>
- <dd>IN: Dataset creation property list identifier.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns <code>TRUE</code> if all filters are available
- and <code>FALSE</code> if one or more is not currently available.<br>
- Returns <code>FAIL</code>, a negative value, on error.
-<!--<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pall_filters_avail_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
---> <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-GetNFilters">H5Pget_nfilters</a>
- <dt><strong>Signature:</strong>
- <dd><em>int</em> <code>H5Pget_nfilters</code>(<em>hid_t</em> <code>plist</code>)
- <dt><strong>Purpose:</strong>
- <dd>Returns the number of filters in the pipeline.
- <dt><strong>Description:</strong>
- <dd><code>H5Pget_nfilters</code> returns the number of filters
- defined in the filter pipeline associated with the property list
- <code>plist</code>.
- <p>
- In each pipeline, the filters are numbered from
- 0 through <em>N</em>-1, where <em>N</em> is the value returned
- by this function. During output to the file, the filters are
- applied in increasing order; during input from the file, they
- are applied in decreasing order.
- <p>
- <code>H5Pget_nfilters</code> returns the number of filters
- in the pipeline, including zero (<code>0</code>) if there
- are none.
- <dt><strong>Note:</strong>
- <dd>This function currently supports only the permanent filter
- pipeline; <code>plist_id</code> must be a dataset creation
- property list.
- <dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Property list identifier.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns the number of filters in the pipeline if successful;
- otherwise returns a negative value.
- <dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_nfilters_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_fill_value_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -3668,7 +2518,8 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_filter" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-GetFilter">H5Pget_filter</a>
@@ -3772,7 +2623,8 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_filter_by_id" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-GetFilterById">H5Pget_filter_by_id</a>
@@ -3849,53 +2701,38 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_gc_references" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-ModifyFilter">H5Pmodify_filter</a>
+ <dt><strong>Name:</strong> <a name="Property-GetGCReferences">H5Pget_gc_references</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pmodify_filter</code>(<em>hid_t</em> <code>plist</code>,
- <em>H5Z_filter_t</em> <code>filter</code>,
- <em>unsigned int</em> <code>flags</code>,
- <em>size_t</em> <code>cd_nelmts</code>,
- <em>const unsigned int</em> <code>cd_values[]</code>
+ <dd><em>herr_t</em> <code>H5Pget_gc_references</code>(<em>hid_t</em> <code>plist</code>,
+ <em>unsigned</em> *<code>gc_ref</code>
)
<dt><strong>Purpose:</strong>
- <dd>Modifies a filter in the filter pipeline.
+ <dd>Returns garbage collecting references setting.
<dt><strong>Description:</strong>
- <dd><code>H5Pmodify_filter</code> modifies the specified
- <code>filter</code> in the filter pipeline.
- <code>plist</code> must be a dataset creation property list
- and the modified filter will be in a permanent filter pipeline.
- <p>
- The <code>filter</code>, <code>flags</code>
- <code>cd_nelmts[]</code>, and <code>cd_values</code> parameters
- are used in the same manner and accept the same values as described
- in the discussion of <a href="#Property-SetFilter">H5Pset_filter</a>.
- <dt><strong>Note:</strong>
- <dd>This function currently supports only the permanent filter
- pipeline; <code>plist_id</code> must be a dataset creation
- property list.
+ <dd><code>H5Pget_gc_references</code> returns the current setting
+ for the garbage collection references property from
+ the specified file access property list.
+ The garbage collection references property is set
+ by <a href="#Property-SetGCReferences">H5Pset_gc_references</a>.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist_id</code>
- <dd>IN: Property list identifier.
- <dt><em>H5Z_filter_t</em> <code>filter</code>
- <dd>IN: Filter to be modified.
- <dt><em>unsigned int</em> <code>flags</code>
- <dd>IN: Bit vector specifying certain general properties
- of the filter.
- <dt><em>size_t</em> <code>cd_nelmts</code>
- <dd>IN: Number of elements in <code>cd_values</code>.
- <dt><em>const unsigned int</em> <code>cd_values[]</code>
- <dd>IN: Auxiliary data for the filter.
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: File access property list identifier.
+ <dt><em>unsigned</em> <code>gc_ref</code>
+ <dd>OUT: Flag returning the state of reference garbage collection.
+ A returned value of <code>1</code> indicates that
+ garbage collection is on while
+ <code>0</code> indicates that garbage collection is off.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
-
- dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pmodify_filter_f"
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_gc_references_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -3903,51 +2740,36 @@ facilitate moving easily between them.</i>
-->
</dl>
-
-
-
-
-
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_istore_k" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetShuffle">H5Pset_shuffle</a>
+ <dt><strong>Name:</strong> <a name="Property-GetIstoreK">H5Pget_istore_k</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_shuffle</code>(<em>hid_t</em> <code>plist_id</code>)
+ <dd><em>herr_t </em><code>H5Pget_istore_k</code>(<em>hid_t</em> <code>plist</code>,
+ <em>int *</em> <code>ik</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Sets up use of the shuffle filter.
+ <dd>Queries the 1/2 rank of an indexed storage B-tree.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_shuffle</code> sets the shuffle filter,
- <code>H5Z_FILTER_SHUFFLE</code>,
- in the dataset creation property list <code>plist_id</code>.  
- <p>
- The shuffle filter <span class=termEmphasis>de-interlaces</span>
- a block of data by reordering the bytes.
- All the bytes from one consistent byte position of
- each data element are placed together in one block;
- all bytes from a second consistent byte position of
- each data element are placed together a second block; etc.
- For example, given three data elements of a 4-byte datatype
- stored as <code>012301230123</code>,
- shuffling will re-order data as <code>000111222333</code>.
- This can be a valuable step in an effective compression
- algorithm because the bytes in each byte position are often
- closely related to each other and putting them together
- can increase the compression ratio.
- <p>
- This filter is designed to be used in combination with
- a compression filter.
+ <dd><code>H5Pget_istore_k</code> queries the 1/2 rank of
+ an indexed storage B-tree.
+ The argument <code>ik</code> may be the null pointer (NULL).
+ This function is only valid for file creation property lists.
+ <p>
+ See <a href="#Property-SetIstoreK">H5Pset_istore_k</a> for details.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist_id</code>
- <dd>IN: Dataset creation property list identifier.
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Identifier of property list to query.
+ <dt><em>int *</em> <code>ik</code>
+ <dd>OUT: Pointer to location to return the chunked storage B-tree 1/2 rank.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_shuffle_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_istore_k_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -3955,30 +2777,48 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_layout" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetFletcher32">H5Pset_fletcher32</a>
+ <dt><strong>Name:</strong> <a name="Property-GetLayout">H5Pget_layout</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_fletcher32</code>(<em>hid_t</em> <code>plist</code>)
+ <dd><em>H5D_layout_t</em> <code>H5Pget_layout</code>(<em>hid_t</em> <code>plist</code>)
<dt><strong>Purpose:</strong>
- <dd>Sets up use of the Fletcher32 checksum filter.
+ <dd>Returns the layout of the raw data for a dataset.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_fletcher32</code> sets the Fletcher32 checksum filter
- in the dataset creation property list <code>plist</code>.  
- <dt><strong>Note:</strong>
- <dd>The initial error detection implementation supports
- error detection for chunked datasets only.
+ <dd><code>H5Pget_layout</code> returns the layout of the raw data for
+ a dataset. This function is only valid for dataset creation
+ property lists.
+ <p>
+ Note that a compact storage layout may affect writing data to
+ the dataset with parallel applications. See note in
+ <a href="RM_H5D.html#Dataset-Write">H5Dwrite</a>
+ documentation for details.
+
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Dataset creation property list identifier.
+ <dd>IN: Identifier for property list to query.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns the layout type (a non-negative value)
+ of a dataset creation property list if successful.
+ Valid return values are:
+ <ul> <dl>
+ <dt>H5D_COMPACT
+ <dd>Raw data is stored in the object header in the file.
+ <dt>H5D_CONTIGUOUS
+ <dd>Raw data is stored separately from the object header in
+ one contiguous chunk in the file.
+ <dt>H5D_CHUNKED
+ <dd>Raw data is stored separately from the object header in
+ chunks in separate locations in the file.
+ </dl> </ul>
+ <p>
+ Otherwise, returns a negative value indicating faliure.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_fletcher32_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_layout_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -3986,291 +2826,137 @@ facilitate moving easily between them.</i>
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_meta_block_size" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetSzip">H5Pset_szip</a>
+ <dt><strong>Name:</strong> <a name="Property-GetMetaBlockSize">H5Pget_meta_block_size</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_szip</code>(<em>hid_t</em> <code>plist</code>,
- <em>unsigned int</em> <code>options_mask</code>,
- <em>unsigned int</em> <code>pixels_per_block</code>)
+ <dd><em>herr_t</em> <code>H5Pget_meta_block_size</code>(
+ <em>hid_t</em> <code>fapl_id</code>,
+ <em>hsize_t *</em><code>size</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Sets up use of the SZIP compression filter.
+ <dd>Returns the current metadata block size setting.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_szip</code> sets a filter for the dataset
- to SZIP compression, <code>H5Z_FILTER_SZIP</code>,
- a compression method designed for use with scientific data.
- <p>
- SZIP options are passed in an options mask, <code>options_mask</code>,
- as follows.
- <center>
- <table>
- <tr valign=top align=left><td>
- <hr>
- <b>Option</b>
- </td><td>
- <hr>
- <b>Description</b>
- <br>
- <font size=-1>(Paired options are mutually exclusive.)</font>
- </td></tr>
-
- <tr valign=top align=left><td>
- <hr>
- <code>H5_SZIP_CHIP_OPTION_MASK&nbsp;&nbsp;</code>
- </td><td>
- <hr>
- Compresses exactly as in hardware.
- </td></tr>
- <tr valign=top align=left><td>
- <code>H5_SZIP_ALLOW_K13_OPTION_MASK&nbsp;&nbsp;</code>
- </td><td>
- Allows k split = 13 compression mode. (Default)
- </td></tr>
-
- <tr valign=top align=left><td>
- <hr>
- <code>H5_SZIP_EC_OPTION_MASK</code>
- </td><td>
- <hr>
- Selects entropy coding method. (Default)
- </td></tr>
- <tr valign=top align=left><td>
- <code>H5_SZIP_NN_OPTION_MASK</code>
- </td><td>
- Selects nearest neighbor coding method.
- </td></tr>
-
-<!-- THESE OPTIONS ARE SET DIRECTLY BY THE LIBRARY AND
- ARE NOT AVAILABLE FOR USER CONTROL
-
- <tr valign=top align=left><td>
- <hr>
- <code>LSB_OPTION_MASK</code>
- </td><td>
- <hr>
- Data format is least significant byte first. (Default)
- </td></tr>
- <tr valign=top align=left><td>
- <code>MSB_OPTION_MASK</code>
- </td><td>
- Data format is most significant byte first.
- </td></tr>
-
- <tr valign=top align=left><td>
- <hr>
- <code>RAW_OPTION_MASK</code>
- </td><td>
- <hr>
- Do not output SZIP header.<br>
- Not a default setting, but should always be set in HDF5.
- </td></tr>
-
-END LIBRARY-SET OPTION TAGS -->
-
- <tr valign=top align=left><td>
- <hr>
- </td><td>
- <hr>
- </td></tr>
- </table>
- </center>
- Some typical usages are as follows:
- <ul>
- <li>One of the compression methods,
- <code>H5_SZIP_EC_OPTION_MASK</code> or
- <code>H5_SZIP_NN_OPTION_MASK</code>, is specified.
- <li>The <code>H5_SZIP_ALLOW_K13_OPTION_MASK</code> is used.
- </ul>
- <p>
- Options are combined to create the options mask by means of
- a logical <code>OR</code> operation. For example, the
- option mask can be set as follows:
- <br><br><code>&nbsp;&nbsp;&nbsp;&nbsp;
- options_mask = H5_SZIP_NN_OPTION_MASK | H5_SZIP_ALLOW_K13_OPTION_MASK;
- </code>
- <p>
- SZIP compresses data block by block, with a user-tunable block size.
- This block size is passed in the parameter
- <code>pixels_per_block</code> and must be even,
- with typical values being <code>8</code>, <code>10</code>,
- <code>16</code>, and <code>32</code>.
- The more pixel values vary, the smaller this number should be.
- For optimal performance, the number of pixels per scan line
- (i.e., the size of the fastest-changing dimension in the chunk)
- should be an even multiple of the number of pixels per block.
- <p>
- <dt><strong>Notes:</strong>
- <dd>SZIP works only with datasets with 1 through 24 bits/pixel,
- 32 pits/pixel, or 64 bits/pixel.
- <p>
- SZIP typically requires that the user application also supply
- the number of pixels in the object to be compressed,
- the number of bits per pixel, and the number of pixels per scan line.
- These values need not be independently supplied in the HDF5
- environment as they are derived from the datatype and dataspace,
- which are already known.
- <p>
- Also see
- <a href="http://hdf.ncsa.uiuc.edu/HDF5/doc_resource/SZIP/index.html"
- target="External">SZIP Compression in HDF5</a>
- for further discussion of SZIP compression in HDF5,
- for <em>important information regarding terms of use and
- the SZIP copyright notice</em>,
- and for a list of SZIP-related references.
-
+ <dd><code>H5Pget_meta_block_size</code> returns the current
+ minimum size, in bytes, of new metadata block allocations.
+ This setting is retrieved from the file access property list
+ <code>fapl_id</code>.
+ <p>
+ This value is set by
+ <a href="#Property-SetMetaBlockSize">H5Pset_meta_block_size</a>
+ and is retrieved from the file access property list
+ <code>fapl_id</code>.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Dataset creation or dataset transfer property list
- identifier.
- <dt><em>unsigned int</em> <code>options_mask</code>
- <dd>IN: A bit-mask conveying the desired SZIP options.
- <dt><em>unsigned int</em> <code>pixels_per_block</code>
- <dd>IN: The number of pixels or data elements in each data block.
+ <dt><em>hid_t</em> <code>fapl_id</code>
+ <dd>IN: File access property list identifier.
+ <dt><em>hsize_t *</em><code>size</code>
+ <dd>OUT: Minimum size, in bytes, of metadata block allocations.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful.
+ Otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_szip_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_meta_block_size_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
-
-<!--
- <p>
- <dt><strong>References:</strong>
- (This material will appear in a separate file in the final release documents.)
- <ul>
- <li>J. Venbrux, P.S. Yeh, G. Zweigle, J. Vesel,
- "A VLSI Chip Solution for Lossless Medical Imagery Compression,"
- <cite>SPIE conference on Medical Imaging 1994</cite>.
- Vol. 2164, pp. 561-572, February 13-14, 1994,
- Newport Beach, California.
-
- <li>J. Venbrux, J. Gambles, D. Wiseman, G. Zweigle, W.H. Miller, P.S. Yeh,
- "A VLSI Chip Set Development for Lossless Data Compression,"
- <cite>AIAA Computing in Aerospace 9 Conference</cite>.
- October 1993, San Diego, California.
-
- <li>J. Venbrux, G. Zweigle, J. Gambles, D.Wiseman, W. Miller, P. Yeh,
- "An Adaptive, Lossless Data Compression Algorithm and VLSI
- Implementations,"
- <cite>NASA Symposium on VLSI Design</cite>.
- Pp 1.2.1-1.2.16, November 1993.
-
- <li>J. Venbrux, P.S. Yeh, and M. N. Liu,
- "A VLSI Chip Set for High Speed Lossless Data Compression,"
- <cite>IEEE Transactions on Circuits and Systems for Video
- Technology</cite>.
- Pp. 381-391, December 1992.
-
- <li>CCSDS 120.0-G-1.
- <cite>Lossless Data Compression</cite>.
- Green Book. Issue 1, May 1997.
- This Report presents a summary of the key operational concepts and
- rationale underlying the requirements for the CCSDS Recommendation,
- Lossless Data Compression. Supporting performance information along
- with illustrations are also included. This Report also provides a
- broad tutorial overview of the CCSDS Lossless Data Compression
- algorithm and is aimed at helping first-time readers
- to understand the Recommendation.
- <br>
- Appears In: CCSDS Publications TGannett 02/04/2003 387K Services
- Check Out View
-
- <li>CCSDS 121.0-B-1.
- <cite>Lossless Data Compression</cite>.
- Blue Book. Issue 1, May 1997.
- This Recommendation defines a source-coding data-compression
- algorithm and specifies how data compressed using the algorithm
- are inserted into source packets for retrieval and decoding.
- <br>
- Appears In: CCSDS Publications
-
- </ul>
--->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_multi_type" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetEdcCheck">H5Pset_edc_check</a>
+ <dt><strong>Name:</strong> <a name="Property-GetMultiType">H5Pget_multi_type</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_edc_check</code>(<em>hid_t</em> <code>plist</code>,
- <em>H5Z_EDC_t</em> <code>check</code>)
+ <dd><em>herr_t</em> <code>H5Pset_multi_type</code> (
+ <em>hid_t</em> <code>fapl_id</code>,
+ <em>H5FD_mem_t *</em><code>type</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Sets whether to enable error-detection when reading a dataset.
+ <dd>Retrieves data type property for <code>MULTI</code> driver.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_edc_check</code> sets the dataset transfer property
- list <code>plist</code> to enable or disable error detection
- when reading data.
- <p>
- Whether error detection is enabled or disabled is specified
- in the <code>check</code> parameter.
- Valid values are as follows:
- <table border="0">
- <tr><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
- <code>H5Z_ENABLE_EDC</code> &nbsp; (default)
- <br>
- <code>H5Z_DISABLE_EDC</code>
- </td></tr>
- </table>
+ <dd><code>H5Pget_multi_type</code> retrieves the data type setting from the
+ file access or data transfer property list <code>fapl_id</code>.
+ This enables a user application to specifiy the type of data the
+ application wishes to access so that the application
+ can retrieve a file handle for low-level access to the particular member
+ of a set of <code>MULTI</code> files in which that type of data is stored.
+ The file handle is retrieved with a separate call
+ to <a href="RM_H5F.html#File-GetVfdHandle"><code>H5Fget_vfd_handle</code></a>
+ (or, in special circumstances, to <code>H5FDget_vfd_handle</code>;
+ see <cite>Virtual File Layer</cite> and <cite>List of VFL Functions</cite>
+ in <a href="TechNotes.html"><cite>HDF5 Technical Notes</cite></a>).
<p>
- The error detection algorithm used is the algorithm previously
- specified in the corresponding dataset creation property list.  
+ The type of data returned in <code>type</code> will be one of those
+ listed in the discussion of the <code>type</code> parameter in the the
+ description of the function
+ <a href="#Property-SetMultiType"><code>H5Pset_multi_type</code></a>.
<p>
- This function does not affect the use of error detection when
- writing data.  
- <dt><strong>Note:</strong>
- <dd>The initial error detection implementation, Fletcher32 checksum,
- supports error detection for chunked datasets only.
+ Use of this function is only appropriate for an HDF5 file written
+ as a set of files with the <code>MULTI</code> file driver.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Dataset transfer property list identifier.
- <dt><em>H5Z_EDC_t</em> <code>check</code>
- <dd>IN: Specifies whether error checking is enabled or disabled
- for dataset read operations.
+ <dt><em>hid_t</em> <code>fapl_id</code>
+ <dd>IN: File access property list or data transfer property list identifier.
+ <dt><em>H5FD_mem_t *</em><code>type</code>
+ <dd>OUT: Type of data.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
+ <!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_edc_check_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ -->
<!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_nfilters" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetEdcCheck">H5Pget_edc_check</a>
+ <dt><strong>Name:</strong> <a name="Property-GetNFilters">H5Pget_nfilters</a>
<dt><strong>Signature:</strong>
- <dd><em>H5Z_EDC_t</em> <code>H5Pget_edc_check</code>(<em>hid_t</em> <code>plist</code>)
+ <dd><em>int</em> <code>H5Pget_nfilters</code>(<em>hid_t</em> <code>plist</code>)
<dt><strong>Purpose:</strong>
- <dd>Determines whether error-detection is enabled for dataset reads.
+ <dd>Returns the number of filters in the pipeline.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_edc_check</code> queries the dataset transfer property
- list <code>plist</code> to determine whether error detection
- is enabled for data read operations.
+ <dd><code>H5Pget_nfilters</code> returns the number of filters
+ defined in the filter pipeline associated with the property list
+ <code>plist</code>.
+ <p>
+ In each pipeline, the filters are numbered from
+ 0 through <em>N</em>-1, where <em>N</em> is the value returned
+ by this function. During output to the file, the filters are
+ applied in increasing order; during input from the file, they
+ are applied in decreasing order.
+ <p>
+ <code>H5Pget_nfilters</code> returns the number of filters
+ in the pipeline, including zero (<code>0</code>) if there
+ are none.
+ <dt><strong>Note:</strong>
+ <dd>This function currently supports only the permanent filter
+ pipeline; <code>plist_id</code> must be a dataset creation
+ property list.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Dataset transfer property list identifier.
+ <dd>IN: Property list identifier.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns <code>H5P_ENABLE_EDC</code> or <code>H5P_DISABLE_EDC</code>
- if successful;
+ <dd>Returns the number of filters in the pipeline if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_edc_check_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_nfilters_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -4278,121 +2964,115 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_nprops" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-GetNProps">H5Pget_nprops</a>
+
+ <dt><strong>Signature:</strong>
+ <dd><em>int</em> <code>H5Pget_nprops</code>(
+ <em>hid_t</em> <code>id</code>,
+ <em>size_t *</em><code>nprops</code>
+ )
+
+ <dt><strong>Purpose:</strong>
+ <dd>Queries number of properties in property list or class.
+
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pget_nprops</code> retrieves the number of properties in a
+ property list or class.
+ If a property class identifier is given, the number of registered
+ properties in the class is returned in <code>nprops</code>.
+ If a property list identifier is given, the current number of
+ properties in the list is returned in <code>nprops</code>.
+
+ <dt><strong>Parameters:</strong>
+ <ul><table>
+ <tr>
+ <td><em>hid_t</em> <code>id</code></td>
+ <td>IN: Identifier of property object to query</td></tr>
+ <tr>
+ <td><em>size_t *</em><code>nprops</code></td>
+ <td>OUT: Number of properties in object</td></tr>
+ </table></ul>
+
+ <dt><strong>Returns:</strong>
+ <dd>Success: a non-negative value
+ <dd>Failure: a negative value
+
+ <dt><strong>Non-C APIs:</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_nprops_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_preserve" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetFilterCallback">H5Pset_filter_callback</a>
+ <dt><strong>Name:</strong> <a name="Property-GetPreserve">H5Pget_preserve</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_filter_callback</code>(<em>hid_t</em> <code>plist</code>,
- <em>H5Z_filter_func_t</em> <code>func</code>,
- <em>void *</em><code>op_data</code>)
+ <dd><em>int</em> <code>H5Pget_preserve</code>(<em>hid_t</em> <code>plist</code>)
<dt><strong>Purpose:</strong>
- <dd>Sets user-defined filter callback function.
+ <dd>Checks status of the dataset transfer property list.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_filter_callback</code> sets the user-defined
- filter callback function <code>func</code> in the
- dataset transfer property list <code>plist</code>.
- <p>
- The parameter <code>op_data</code> is a pointer to user-defined
- input data for the callback function and will be passed through
- to the callback function.
- <p>
- The callback function <code>func</code> defines the actions
- an application is to take when a filter fails.
- The function prototype is as follows:
- <dir>
- <code>typedef</code> <em>H5Z_cb_return_t</em> (<code>H5Z_filter_func_t</code>)
- (<em>H5Z_filter_t</em> <code>filter</code>,
- <em>void *</em><code>buf</code>,
- <em>size_t</em> <code>buf_size</code>,
- <em>void *</em><code>op_data</code>)
- </dir>
- <p>
- where <code>filter</code> indicates which filter has failed,
- <code>buf</code> and <code>buf_size</code> are used to pass in
- the failed data,
- and <code>op_data</code> is the required input data for this
- callback function.
- <p>
- Valid callback function return values are
- <code>H5Z_CB_FAIL</code> and <code>H5Z_CB_CONT</code>.  
+ <dd><code>H5Pget_preserve</code> checks the status of the
+ dataset transfer property list.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Dataset transfer property list identifier.
- <dt><em>H5Z_filter_func_t</em> <code>func</code>
- <dd>IN: User-defined filter callback function.
- <dt><em>void *</em><code>op_data</code>
- <dd>IN: User-defined input data for the callback function.
+ <dd>IN: Identifier for the dataset transfer property list.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
+ <dd>Returns TRUE or FALSE if successful;
otherwise returns a negative value.
-<!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_filter_callback_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_preserve_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- --> <!--
+ <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
-
-
-
-
-
-
-
-
-
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_sieve_buf_size" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetMetaBlockSize">H5Pset_meta_block_size</a>
+ <dt><strong>Name:</strong> <a name="Property-GetSieveBufSize">H5Pget_sieve_buf_size</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_meta_block_size</code>(
+ <dd><em>herr_t</em> <code>H5Pget_sieve_buf_size</code>(
<em>hid_t</em> <code>fapl_id</code>,
- <em>hsize_t</em> <code>size</code>
+ <em>hsize_t *</em><code>size</code>
)
+<br>
+<br>
<dt><strong>Purpose:</strong>
- <dd>Sets the minimum metadata block size.
+ <dd> Returns maximum data sieve buffer size.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_meta_block_size</code> sets the
- minimum size, in bytes, of metadata block allocations when
- <code>H5FD_FEAT_AGGREGATE_METADATA</code> is set by a VFL driver.
- <p>
- Each <i>raw</i> metadata block is initially allocated to be of the
- given size. Specific metadata objects (e.g., object headers,
- local heaps, B-trees) are then sub-allocated from this block.
- <p>
- The default setting is 2048 bytes, meaning that the library
- will attempt to aggregate metadata in at least 2K blocks in the file.
- Setting the value to <code>0</code> (zero) with this function
- will turn off metadata aggregation, even if the VFL driver attempts
- to use the metadata aggregation strategy.
+ <dd><code>H5Pget_sieve_buf_size</code> retrieves, <code>size</code>,
+ the current maximum size of the data sieve buffer.
<p>
- Metadata aggregation reduces the number of small data objects
- in the file that would otherwise be required for metadata.
- The aggregated block of metadata is usually written in a
- single write action and always in a contiguous block,
- potentially significantly improving library and application
- performance.
+ This value is set by
+ <a href="#Property-SetSieveBufSize">H5Pset_sieve_buf_size</a>
+ and is retrieved from the file access property list
+ <code>fapl_id</code>.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>fapl_id</code>
<dd>IN: File access property list identifier.
- <dt><em>hsize_t</em> <code>size</code>
- <dd>IN: Minimum size, in bytes, of metadata block allocations.
+ <dt><em>hsize_t *</em><code>size</code>
+ <dd>IN: Maximum size, in bytes, of data sieve buffer.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful.
Otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_meta_block_size_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_sieve_buf_size_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -4400,39 +3080,87 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_size" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-GetSize">H5Pget_size</a>
+
+ <dt><strong>Signature:</strong>
+ <dd><em>int</em> <code>H5Pget_size</code>(
+ <em>hid_t</em> <code>id</code>,
+ <em>const char *</em><code>name</code>,
+ <em>size_t *</em><code>size</code>
+ )
+
+ <dt><strong>Purpose:</strong>
+ <dd>Queries the size of a property value in bytes.
+
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pget_size</code> retrieves the size of a
+ property's value in bytes. This function operates on both
+ poperty lists and property classes
+
+ <p>
+ Zero-sized properties are allowed and return <code>0</code>.
+
+
+ <dt><strong>Parameters:</strong>
+ <ul><table>
+ <tr>
+ <td><em>hid_t</em> <code>id</code></td>
+ <td>IN: Identifier of property object to query</td></tr>
+ <tr>
+ <td><em>const char *</em><code>name</code></td>
+ <td>IN: Name of property to query</td></tr>
+ <tr>
+ <td><em>size_t *</em><code>size</code></td>
+ <td>OUT: Size of property in bytes</td></tr>
+ </table></ul>
+
+ <dt><strong>Returns:</strong>
+ <dd>Success: a non-negative value
+ <dd>Failure: a negative value
+
+ <dt><strong>Non-C APIs:</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_size_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_sizes" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetMetaBlockSize">H5Pget_meta_block_size</a>
+ <dt><strong>Name:</strong> <a name="Property-GetSizes">H5Pget_sizes</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_meta_block_size</code>(
- <em>hid_t</em> <code>fapl_id</code>,
- <em>hsize_t *</em><code>size</code>
- )
+ <dd><em>herr_t </em><code>H5Pget_sizes</code>(<em>hid_t</em> <code>plist</code>,
+ <em>size_t *</em> <code>sizeof_addr</code>,
+ <em>size_t *</em> <code>sizeof_size</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Returns the current metadata block size setting.
+ <dd>Retrieves the size of the offsets and lengths used in an HDF5 file.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_meta_block_size</code> returns the current
- minimum size, in bytes, of new metadata block allocations.
- This setting is retrieved from the file access property list
- <code>fapl_id</code>.
- <p>
- This value is set by
- <a href="#Property-SetMetaBlockSize">H5Pset_meta_block_size</a>
- and is retrieved from the file access property list
- <code>fapl_id</code>.
+ <dd><code>H5Pget_sizes</code> retrieves the size of the offsets
+ and lengths used in an HDF5 file.
+ This function is only valid for file creation property lists.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>fapl_id</code>
- <dd>IN: File access property list identifier.
- <dt><em>hsize_t *</em><code>size</code>
- <dd>OUT: Minimum size, in bytes, of metadata block allocations.
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Identifier of property list to query.
+ <dt><em>size_t *</em> <code>size</code>
+ <dd>OUT: Pointer to location to return offset size in bytes.
+ <dt><em>size_t *</em> <code>size</code>
+ <dd>OUT: Pointer to location to return length size in bytes.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful.
- Otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_meta_block_size_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_sizes_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -4440,43 +3168,35 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_small_data_block_size" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetSieveBufSize">H5Pset_sieve_buf_size</a>
+ <dt><strong>Name:</strong> <a name="Property-GetSmallData">H5Pget_small_data_block_size</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_sieve_buf_size</code>(
- <em>hid_t</em> <code>fapl_id</code>,
- <em>hsize_t</em> <code>size</code>
- )
+ <dd><em>herr_t</em> <code>H5Pget_small_data_block_size</code>(<em>hid_t</em> <code>fapl_id</code>,
+ <em>hsize_t *</em><code>size</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Sets the maximum size of the data sieve buffer.
+ <dd>Retrieves the current small data block size setting.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_sieve_buf_size</code> sets <code>size</code>,
- the maximum size in bytes of the data sieve buffer, which is
- used by file drivers that are capable of using data sieving.
- <p>
- The data sieve buffer is used when performing I/O on datasets
- in the file. Using a buffer which is large enough to hold
- several pieces of the dataset being read in for
- hyperslab selections boosts performance by quite a bit.
+ <dd><code>H5Pget_small_data_block_size</code> retrieves the
+ current setting for the size of the small data block.
<p>
- The default value is set to 64KB, indicating that file I/O for
- raw data reads and writes will occur in at least 64KB blocks.
- Setting the value to 0 with this API function will turn off the
- data sieving, even if the VFL driver attempts to use that strategy.
+ If the returned value is zero (<code>0</code>), the small data
+ block mechanism has been disabled for the file.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>fapl_id</code>
- <dd>IN: File access property list identifier.
- <dt><em>hsize_t</em> <code>size</code>
- <dd>IN: Maximum size, in bytes, of data sieve buffer.
+ <dd>IN: File access property list identifier .
+ <dt><em>hsize_t *</em><code>size</code>
+ <dd>OUT: Maximum size, in bytes, of the small data block.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful.
- Otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful;
+ otherwise a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_sieve_buf_size_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_small_data_block_size_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -4484,39 +3204,41 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_sym_k" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetSieveBufSize">H5Pget_sieve_buf_size</a>
+ <dt><strong>Name:</strong> <a name="Property-GetSymK">H5Pget_sym_k</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_sieve_buf_size</code>(
- <em>hid_t</em> <code>fapl_id</code>,
- <em>hsize_t *</em><code>size</code>
- )
-<br>
-<br>
+ <dd><em>herr_t </em><code>H5Pget_sym_k</code>(<em>hid_t</em> <code>plist</code>,
+ <em>int *</em> <code>ik</code>,
+ <em>int *</em> <code>lk</code>
+ )
<dt><strong>Purpose:</strong>
- <dd> Returns maximum data sieve buffer size.
+ <dd>Retrieves the size of the symbol table B-tree 1/2 rank
+ and the symbol table leaf node 1/2 size.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_sieve_buf_size</code> retrieves, <code>size</code>,
- the current maximum size of the data sieve buffer.
- <p>
- This value is set by
- <a href="#Property-SetSieveBufSize">H5Pset_sieve_buf_size</a>
- and is retrieved from the file access property list
- <code>fapl_id</code>.
+ <dd><code>H5Pget_sym_k</code> retrieves the size of the
+ symbol table B-tree 1/2 rank and the symbol table leaf
+ node 1/2 size. This function is only valid for file creation
+ property lists. If a parameter valued is set to NULL, that
+ parameter is not retrieved. See the description for
+ <a href="#Property-SetSymK">H5Pset_sym_k</a> for more
+ information.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>fapl_id</code>
- <dd>IN: File access property list identifier.
- <dt><em>hsize_t *</em><code>size</code>
- <dd>IN: Maximum size, in bytes, of data sieve buffer.
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Property list to query.
+ <dt><em>int *</em> <code>ik</code>
+ <dd>OUT: Pointer to location to return the symbol table's B-tree 1/2 rank.
+ <dt><em>int *</em> <code>size</code>
+ <dd>OUT: Pointer to location to return the symbol table's leaf node 1/2 size.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful.
- Otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_sieve_buf_size_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_sym_k_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -4524,46 +3246,32 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
-
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_userblock" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetGCReferences">H5Pset_gc_references</a>
+ <dt><strong>Name:</strong> <a name="Property-GetUserblock">H5Pget_userblock</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_gc_reference</code>(<em>hid_t</em> <code>plist</code>,
- <em>unsigned</em> <code>gc_ref</code>
- )
+ <dd><em>herr_t </em><code>H5Pget_userblock</code>(<em>hid_t</em> <code>plist</code>,
+ <em>hsize_t *</em> <code>size</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Sets garbage collecting references flag.
+ <dd>Retrieves the size of a user block.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_gc_references</code> sets the flag for
- garbage collecting references for the file.
- <p>
- Dataset region references and other reference types use space
- in an HDF5 file's global heap. If garbage collection is on
- and the user passes in an uninitialized value in a reference structure,
- the heap might get corrupted. When garbage collection is off, however,
- and the user re-uses a reference, the previous heap block will be
- orphaned and not returned to the free heap space.
- <p>
- When garbage collection is on, the user must initialize the
- reference structures to 0 or risk heap corruption.
- <p>
- The default value for garbage collecting references is off.
+ <dd><code>H5Pget_userblock</code> retrieves the size of a user block
+ in a file creation property list.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>plist</code>
- <dd>IN: File access property list identifier.
- <dt><em>unsigned</em> <code>gc_ref</code>
- <dd>IN: Flag setting reference garbage collection to
- on (<code>1</code>) or off (<code>0</code>).
+ <dd>IN: Identifier for property list to query.
+ <dt><em>hsize_t *</em> <code>size</code>
+ <dd>OUT: Pointer to location to return user-block size.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_gc_references_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_userblock_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -4571,36 +3279,43 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_version" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetGCReferences">H5Pget_gc_references</a>
+ <dt><strong>Name:</strong> <a name="Property-GetVersion">H5Pget_version</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_gc_references</code>(<em>hid_t</em> <code>plist</code>,
- <em>unsigned</em> *<code>gc_ref</code>
- )
+ <dd><em>herr_t </em><code>H5Pget_version</code>(<em>hid_t</em> <code>plist</code>,
+ <em>int *</em> <code>super</code>,
+ <em>int *</em> <code>freelist</code>,
+ <em>int *</em> <code>stab</code>,
+ <em>int *</em> <code>shhdr</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Returns garbage collecting references setting.
+ <dd>Retrieves the version information of various objects for
+ a file creation property list.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_gc_references</code> returns the current setting
- for the garbage collection references property from
- the specified file access property list.
- The garbage collection references property is set
- by <a href="#Property-SetGCReferences">H5Pset_gc_references</a>.
+ <dd><code>H5Pget_version</code> retrieves the version information of various objects
+ for a file creation property list. Any pointer parameters which are
+ passed as NULL are not queried.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>plist</code>
- <dd>IN: File access property list identifier.
- <dt><em>unsigned</em> <code>gc_ref</code>
- <dd>OUT: Flag returning the state of reference garbage collection.
- A returned value of <code>1</code> indicates that
- garbage collection is on while
- <code>0</code> indicates that garbage collection is off.
+ <dd>IN: Identifier of the file creation property list.
+ <dt><em>int *</em> <code>super</code>
+ <dd>OUT: Pointer to location to return super block version number.
+ <dt><em>int *</em> <code>freelist</code>
+ <dd>OUT: Pointer to location to return global freelist version number.
+ <dt><em>int *</em> <code>stab</code>
+ <dd>OUT: Pointer to location to return symbol table version number.
+ <dt><em>int *</em> <code>shhdr</code>
+ <dd>OUT: Pointer to location to return shared object header version number.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_gc_references_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pget_version_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -4608,105 +3323,535 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_vlen_mem_manager" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetCache">H5Pset_cache</a>
+ <dt><strong>Name:</strong> <a name="Property-GetVLMemManager">H5Pget_vlen_mem_manager</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_cache</code>(<em>hid_t</em> <code>plist_id</code>,
- <em>int</em> <code>mdc_nelmts</code>,
- <em>int</em> <code>rdcc_nelmts</code>,
- <em>size_t</em> <code>rdcc_nbytes</code>,
- <em>double</em> <code>rdcc_w0</code>
+ <dd><em>herr_t</em> <code>H5Pget_vlen_mem_manager</code>(<em>hid_t</em> <code>plist</code>,
+ <em>H5MM_allocate_t</em> *<code>alloc</code>,
+ <em>void</em> **<code>alloc_info</code>,
+ <em>H5MM_free_t</em> *<code>free</code>,
+ <em>void</em> **<code>free_info</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets the meta data cache and raw data chunk cache parameters.
+ <dd>Gets the memory manager for variable-length datatype allocation in
+ <code>H5Dread</code> and <code>H5Dvlen_reclaim</code>.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_cache</code> sets
- the number of elements (objects) in the meta data cache and
- the number of elements, the total number of bytes, and
- the preemption policy value in the raw data chunk cache.
- <p>
- The <em>plist_id</em> is a file access property list.
- The number of elements (objects) in the meta data cache
- and the raw data chunk cache are <em>mdc_nelmts</em> and
- <em>rdcc_nelmts</em>, respectively.
- The total size of the raw data chunk cache and the preemption policy
- are <em>rdcc_nbytes</em> and <em>rdcc_w0</em>.
- <p>
- Any (or all) of the <code>H5Pget_cache</code> pointer arguments
- may be null pointers.
- <p>
- The <em>rdcc_w0</em> value should be between 0 and 1 inclusive and
- indicates how much chunks that have been fully read are
- favored for preemption. A value of zero means fully read
- chunks are treated no differently than other chunks (the
- preemption is strictly LRU) while a value of one means fully
- read chunks are always preempted before other chunks.
+ <dd><code>H5Pget_vlen_mem_manager</code> is the companion function to
+ <code>H5Pset_vlen_mem_manager</code>, returning the parameters
+ set by that function.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist_id</code>
- <dd>IN: Identifier of the file access property list.
- <dt><em>int</em> <code>mdc_nelmts</code>
- <dd>IN: Number of elements (objects) in the meta data cache.
- <dt><em>int</em> <code>rdcc_nelmts</code>
- <dd>IN: Number of elements (objects) in the raw data chunk cache.
- <dt><em>size_t</em> <code>rdcc_nbytes</code>
- <dd>IN: Total size of the raw data chunk cache, in bytes.
- <dt><em>double</em> <code>rdcc_w0</code>
- <dd>IN: Preemption policy.
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Identifier for the dataset transfer property list.
+ <dt><em>H5MM_allocate_t</em> <code>alloc</code>
+ <dd>OUT: User's allocate routine, or &nbsp; <code> NULL</code>
+ for system &nbsp; <code> malloc</code>.
+ <dt><em>void</em> *<code>alloc_info</code>
+ <dd>OUT: Extra parameter for user's allocation routine.
+ <br>
+ Contents are ignored if preceding parameter is &nbsp;
+ <code> NULL</code>.
+ <dt><em>H5MM_free_t</em> <code>free</code>
+ <dd>OUT: User's free routine, or &nbsp; <code> NULL</code> for
+ system <code>free</code>.
+ <dt><em>void</em> *<code>free_info</code>
+ <dd>OUT: Extra parameter for user's free routine.
+ <br>
+ Contents are ignored if preceding parameter is &nbsp;
+ <code> NULL</code>.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
+ <!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_cache_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
+ --> <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pinsert" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-Insert">H5Pinsert</a>
+
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Pinsert</code>(
+ <em>hid_t</em> <code>plid</code>,
+ <em>const char *</em><code>name</code>,
+ <em>size_t</em> <code>size</code>,
+ <em>void *</em><code>value</code>,
+ <em>H5P_prp_set_func_t</em> <code>set</code>,
+ <em>H5P_prp_get_func_t</em> <code>get</code>,
+ <em>H5P_prp_delete_func_t</em> <code>delete</code>,
+ <em>H5P_prp_copy_func_t</em> <code>copy</code>,
+ <em>H5P_prp_close_func_t</em> <code>close</code>
+ )
+
+ <dt><strong>Purpose:</strong>
+ <dd>Registers a temporary property with a property list.
+
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pinsert</code> create a new property in a property list.
+ The property will exist only in this property list and copies made
+ from it.
+
+ <p>
+ The initial property value must be provided in
+ <code>value</code> and the property value will be set accordingly.
+
+ <p>
+ The name of the property must not already exist in this list,
+ or this routine will fail.
+
+ <p>
+ The <code>set</code> and <code>get</code> callback routines may
+ be set to NULL if they are not needed.
+
+ <p>
+ Zero-sized properties are allowed and do not store any data in the
+ property list. The default value of a zero-size property may be set
+ to NULL. They may be used to indicate the presence or absence of a
+ particular piece of information.
+ </p>
+ The <code>set</code> routine is called before a new value is copied
+ into the property.
+ The <code>H5P_prp_set_func_t</code> calback function is defined
+ as follows:
+ <ul><em>typedef herr_t</em> (*<code>H5P_prp_set_func_t</code>)(
+ <em>hid_t</em> <code>prop_id</code>,
+ <em>const char *</em><code>name</code>,
+ <em>size_t </em><code>size</code>,
+ <em>void *</em><code>new_value</code>);
+ </ul>
+ The parameters to the callback function are defined as follows:
+ <ul><table>
+ <tr>
+ <td><em>hid_t</em> <code>prop_id</code></td>
+ <td>IN: The identifier of the property list being modified</td></tr>
+ <tr>
+ <td><em>const char *</em><code>name</code></td>
+ <td>IN: The name of the property being modified</td></tr>
+ <tr>
+ <td><em>size_t </em> <code>size</code></td>
+ <td>IN: The size of the property in bytes</td></tr>
+ <tr>
+ <td><em>void **</em><code>new_value</code></td>
+ <td>IN: Pointer to new value pointer for the property being
+ modified</td></tr>
+ </table></ul>
+ The <code>set</code> routine may modify the value pointer to be set
+ and those changes will be used when setting the property's value.
+ If the <code>set</code> routine returns a negative value, the new
+ property value is not copied into the property and the set routine
+ returns an error value.
+ The <code>set</code> routine will be called for the initial value.
+ <p>
+ <strong>Note:</strong>
+ The <code>set</code> callback function may be useful
+ to range check the value being set for the property
+ or may perform some tranformation or translation of the
+ value set. The <code>get</code> callback would then
+ reverse the transformation or translation.
+ A single <code>get</code> or <code>set</code> callback
+ could handle multiple properties by
+ performing different actions based on the
+ property name or other properties in the property list.
+
+ <p>
+ The <code>get</code> routine is called when a value is retrieved
+ from a property value.
+ The <code>H5P_prp_get_func_t</code> callback functioin is defined
+ as follows:
+ <ul><em>typedef herr_t</em> (*<code>H5P_prp_get_func_t</code>)(
+ <em>hid_t</em> <code>prop_id</code>,
+ <em>const char *</em><code>name</code>,
+ <em>size_t </em><code>size</code>,
+ <em>void *</em><code>value</code>);
+ </ul>
+ where the parameters to the callback function are:
+ <ul><table>
+ <tr>
+ <td><em>hid_t</em> <code>prop_id</code></td>
+ <td>IN: The identifier of the property list being queried</td></tr>
+ <tr>
+ <td><em>const char *</em><code>name</code></td>
+ <td>IN: The name of the property being queried</td></tr>
+ <tr>
+ <td><em>size_t </em> <code>size</code></td>
+ <td>IN: The size of the property in bytes</td></tr>
+ <tr>
+ <td><em>void *</em><code>value</code></td>
+ <td>IN: The value of the property being returned</td></tr>
+ </table></ul>
+ The <code>get</code> routine may modify the value to be returned from
+ the query and those changes will be preserved.
+ If the <code>get</code> routine returns a negative value, the query
+ routine returns an error value.
+ </p>
+
+ The <code>delete</code> routine is called when a property is being
+ deleted from a property list.
+ The <code>H5P_prp_delete_func_t</code> callback function is defined
+ as follows:
+ <ul><code>typedef herr_t</code> (*<code>H5P_prp_delete_func_t</code>)(
+ <em>hid_t </em><code>prop_id</code>,
+ <em>const char *</em><code>name</code>,
+ <em>size_t </em><code>size</code>,
+ <em>void *</em><code>value</code>);
+ </ul>
+ where the parameters to the callback function are:
+ <ul><table>
+ <tr>
+ <td><em>hid_t</em> <code>prop_id</code></td>
+ <td>IN: The identifier of the property list the property is
+ being deleted from</td></tr>
+ <tr>
+ <td><em>const char *</em> <code>name</code></td>
+ <td>IN: The name of the property in the list</td></tr>
+ <tr>
+ <td><em>size_t </em> <code>size</code></td>
+ <td>IN: The size of the property in bytes</td></tr>
+ <tr>
+ <td><em>void *</em> <code>value</code></td>
+ <td>IN: The value for the property being deleted</td></tr>
+ </table></ul>
+ The <code>delete</code> routine may modify the value passed in,
+ but the value is not used by the library when the <code>delete</code>
+ routine returns. If the <code>delete</code> routine returns a
+ negative value, the property list delete routine returns an
+ error value but the property is still deleted.
+ </P>
+
+ The <code>copy</code> routine is called when a new property list
+ with this property is being created through a copy operation.
+ The <code>H5P_prp_copy_func_t</code> collback function is defined
+ as follows:
+ <ul><em>typedef herr_t</em> (*<code>H5P_prp_copy_func_t</code>)(
+ <em>const char *</em><code>name</code>,
+ <em>size_t </em><code>size</code>,
+ <em>void *</em><code>value</code>);
+ </ul>
+ where the parameters to the callback function are:
+ <ul><table>
+ <tr>
+ <td><em>const char *</em><code>name</code></td>
+ <td>IN: The name of the property being copied</td></tr>
+ <tr>
+ <td><em>size_t </em> <code>size</code></td>
+ <td>IN: The size of the property in bytes</td></tr>
+ <tr>
+ <td><em>void *</em> <code>value</code></td>
+ <td>IN/OUT: The value for the property being copied</td></tr>
+ </table></ul>
+ The <code>copy</code> routine may modify the value to be set and
+ those changes will be stored as the new value of the property.
+ If the <code>copy</code> routine returns a negative value, the
+ new property value is not copied into the property and the
+ copy routine returns an error value.
+
+ <P>The <code>close</code> routine is called when a property list
+ with this property is being closed.
+ The <code>H5P_prp_close_func_t</code> callback function is defined
+ as follows:
+ <ul><em>typedef herr_t</em> (*<code>H5P_prp_close_func_t</code>)(
+ <em>hid_t</em> <code>prop_id</code>,
+ <em>const char *</em><code>name</code>,
+ <em>size_t </em><code>size</code>,
+ <em>void *</em><code>value</code>);
+ </ul>
+ The parameters to the callback function are defined as follows:
+ <ul><table>
+ <tr>
+ <td><code>hid_t</em> <code>prop_id</em></td>
+ <td>IN: The ID of the property list being closed</td></tr>
+ <tr>
+ <td><code>const char *</code><em>name</em></td>
+ <td>IN: The name of the property in the list</td></tr>
+ <tr>
+ <td><code>size_t </code> <em>size</em></td>
+ <td>IN: The size of the property in bytes</td></tr>
+ <tr>
+ <td><code>void *</code><em>value</em></td>
+ <td>IN: The value for the property being closed</td></tr>
+ </table></ul>
+ The <code>close</code> routine may modify the value passed in, the value
+ is not used by the library when the <code>close</code> routine returns.
+ If the <code>close</code> routine returns a negative value, the
+ property list close routine returns an error value but the property list
+ is still closed.
+
+ <p>
+ <strong>Note:</strong>
+ There is no <code>create</code> callback routine for temporary property
+ list objects; the initial value is assumed to have any necessary setup
+ already performed on it.
+
+ <dt><strong>Parameters:</strong>
+ <ul><table>
+ <tr>
+ <td><code>hid_t</code> <code>plid</em></td>
+ <td>IN: Property list identifier to create temporary property
+ within</td></tr>
+ <tr>
+ <td><em>const char *</em><code>name</code></td>
+ <td>IN: Name of property to create</td></tr>
+ <tr>
+ <td><em>size_t</em> <code>size</code></td>
+ <td>IN: Size of property in bytes</td></tr>
+ <tr>
+ <td><em>void *</em><code>value</code></td>
+ <td>IN: Initial value for the property</td></tr>
+ <tr>
+ <td><em>H5P_prp_set_func_t</em> <code>set</code></td>
+ <td>IN: Callback routine called before a new value is copied into
+ the property's value</td></tr>
+ <tr>
+ <td><em>H5P_prp_get_func_t</em> <code>get</code></td>
+ <td>IN: Callback routine called when a property value is retrieved
+ from the property</td></tr>
+ <tr>
+ <td><em>H5P_prp_delete_func_t</em> <code>delete</code></td>
+ <td>IN: Callback routine called when a property is deleted from
+ a property list</td></tr>
+ <tr>
+ <td><em>H5P_prp_copy_func_t</em> <code>copy</code></td>
+ <td>IN: Callback routine called when a property is copied from
+ an existing property list</td></tr>
+ <tr>
+ <td><em>H5P_prp_close_func_t</em> <code>close</code></td>
+ <td>IN: Callback routine called when a property list is being closed
+ and the property value will be disposed of</td></tr>
+ </table></ul>
+
+ <dt><strong>Returns:</strong>
+ <dd>Success: a non-negative value
+ <dd>Failure: a negative value
+
+ <dt><strong>Non-C APIs:</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pinsert_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pisa_class" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetCache">H5Pget_cache</a>
+ <dt><strong>Name:</strong> <a name="Property-IsAClass">H5Pisa_class</a>
+
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_cache</code>(<em>hid_t</em> <code>plist_id</code>,
- <em>int</em> <code>*mdc_nelmts</code>,
- <em>int</em> <code>*rdcc_nelmts</code>,
- <em>size_t</em> <code>*rdcc_nbytes</code>,
- <em>double</em> <code>*rdcc_w0</code>
+ <dd><em>htri_t</em> <code>H5Pisa_class</code>(
+ <em>hid_t</em> <code>plist</code>,
+ <em>hid_t</em> <code>pclass</code>
+ )
+
+ <dt><strong>Purpose:</strong>
+ <dd>Determines whether a property list is a member of a class.
+
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pisa_class</code> checks to determine whether a property list
+ is a member of the specified class.
+
+ <dt><strong>Parameters:</strong>
+ <ul><table>
+ <tr>
+ <td><em>hid_t</em> <code>plist</code></td>
+ <td>IN: Identifier of the property list</td></tr>
+ <tr>
+ <td><code>hid_t</code> <em>pclass</em></td>
+ <td>IN: Identifier of the property class</td></tr>
+ </table></ul>
+
+ <dt><strong>Returns:</strong>
+ <dd>Success: TRUE (positive) if equal; FALSE (zero) if unequal
+ <dd>Failure: a negative value
+
+ <dt><strong>Non-C APIs:</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pisa_class_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Piterate" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-Iterate">H5Piterate</a>
+
+ <dt><strong>Purpose:</strong>
+ <dd>Iterates over properties in a property class or list.
+
+ <dt><strong>Signature:</strong>
+ <dd><em>int</em> <code>H5Piterate</code>(
+ <em>hid_t</em> <code>id</code>,
+ <em>int *</em> <code>idx</code>,
+ <em>H5P_iterate_t</em> <code>iter_func</code>,
+ <em>void *</em> <code>iter_data</code>
+ )
+
+ <dt><strong>Description:</strong>
+ <P><code>H5Piterate</code> iterates over the properties in the
+ property object specified in <code>id</code>, which may be either a
+ property list or a property class, performing a specified
+ operation on each property in turn.
+
+ <p>
+ For each property in the object, <code>iter_func</code> and
+ the additional information specified below are passed to the
+ <code>H5P_iterate_t</code> operator function.
+
+ <b><i>(NOTE: <code>iter_func</code> was changed to
+ <code>H5P_iterate_t</code> in the preceding sentence.
+ Is this correct?)</i></b>
+
+ <p>
+ The iteration begins with the <code>idx</code>-th property in
+ the object; the next element to be processed by the operator
+ is returned in <code>idx</code>.
+ If <code>idx</code> is NULL, the iterator starts at the first
+ property; 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.
+ </p>
+
+ The prototype for the <code>H5P_iterate_t</code> operator is
+ as follows:
+ <ul> <dl>
+ <dt><em>typedef herr_t</em> (*<code>H5P_iterate_t</code>)(
+ <em>hid_t</em> <code>id</code>,
+ <em>const char *</em><code>>name</code>,
+ <em>void *</em><code>iter_data</code>
+ )
+ </dl> </ul>
+ The operation receives the property list or class identifier for
+ the object being iterated over, <code>id</code>,
+ the name of the current property within the object, <code>name</code>,
+ and the pointer to the operator data passed in to
+ <code>H5Piterate</code>, <code>iter_data</code>.
+ </p>
+
+ The valid return values from an operator are as follows:
+ <ul><table>
+ <tr>
+ <td valign=top>Zero</td>
+ <td>Causes the iterator to continue, returning zero when all
+ properties have been processed</td></tr>
+ <tr>
+ <td valign=top>Positive</td>
+ <td>Causes the iterator to immediately return that positive
+ value, indicating short-circuit success. The iterator can
+ be restarted at the index of the next property</td></tr>
+ <tr>
+ <td valign=top>Negative</td>
+ <td>Causes the iterator to immediately return that value,
+ indicating failure. The iterator can be restarted at the
+ index of the next property</td></tr>
+ </table></ul>
+
+ <P>
+ <code>H5Piterate</code> assumes that the properties in the object
+ identified by <code>id</code> remain unchanged through the iteration.
+ If the membership changes during the iteration, the function's behavior
+ is undefined.
+
+ <dt><strong>Parameters:</strong>
+ <ul><table>
+ <tr>
+ <td><em>hid_t</em> <code>id</code></td>
+ <td>IN: Identifier of property object to iterate over</td></tr>
+ <tr>
+ <td><em>int *</em> <code>idx</code></td>
+ <td>IN/OUT: Index of the property to begin with</td></tr>
+ <tr>
+ <td><em>H5P_iterate_t</em> <code>iter_func</code></td>
+ <td>IN: Function pointer to function to be called with each
+ property iterated over</td></tr>
+ <tr>
+ <td><em>void *</em> <code>iter_data</code></td>
+ <td>IN/OUT: Pointer to iteration data from user</td></tr>
+ </table></ul>
+
+<dt><strong>Returns:</strong>
+ <dd>Success: the return value of the last call to
+ <code>iter_func</code> if it was non-zero;
+ zero if all properties have been processed
+ <dd>Failure: a negative value
+ </table></ul>
+
+ <!--
+ <dt><strong>Non-C APIs:</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pXXX_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ -->
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pmodify_filter" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-ModifyFilter">H5Pmodify_filter</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Pmodify_filter</code>(<em>hid_t</em> <code>plist</code>,
+ <em>H5Z_filter_t</em> <code>filter</code>,
+ <em>unsigned int</em> <code>flags</code>,
+ <em>size_t</em> <code>cd_nelmts</code>,
+ <em>const unsigned int</em> <code>cd_values[]</code>
)
<dt><strong>Purpose:</strong>
- <dd>Queries the meta data cache and raw data chunk cache parameters.
+ <dd>Modifies a filter in the filter pipeline.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_cache</code> retrieves the maximum possible
- number of elements in the meta
- data cache and raw data chunk cache, the maximum possible number of
- bytes in the raw data chunk cache, and the preemption policy value.
- <p>
- Any (or all) arguments may be null pointers, in which case the
- corresponding datum is not returned.
+ <dd><code>H5Pmodify_filter</code> modifies the specified
+ <code>filter</code> in the filter pipeline.
+ <code>plist</code> must be a dataset creation property list
+ and the modified filter will be in a permanent filter pipeline.
+ <p>
+ The <code>filter</code>, <code>flags</code>
+ <code>cd_nelmts[]</code>, and <code>cd_values</code> parameters
+ are used in the same manner and accept the same values as described
+ in the discussion of <a href="#Property-SetFilter">H5Pset_filter</a>.
+ <dt><strong>Note:</strong>
+ <dd>This function currently supports only the permanent filter
+ pipeline; <code>plist_id</code> must be a dataset creation
+ property list.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>plist_id</code>
- <dd>IN: Identifier of the file access property list.
- <dt><em>int</em> <code>*mdc_nelmts</code>
- <dd>IN/OUT: Number of elements (objects) in the meta data cache.
- <dt><em>int</em> <code>*rdcc_nelmts</code>
- <dd>IN/OUT: Number of elements (objects) in the raw data chunk cache.
- <dt><em>size_t</em> <code>*rdcc_nbytes</code>
- <dd>IN/OUT: Total size of the raw data chunk cache, in bytes.
- <dt><em>double</em> <code>*rdcc_w0</code>
- <dd>IN/OUT: Preemption policy.
+ <dd>IN: Property list identifier.
+ <dt><em>H5Z_filter_t</em> <code>filter</code>
+ <dd>IN: Filter to be modified.
+ <dt><em>unsigned int</em> <code>flags</code>
+ <dd>IN: Bit vector specifying certain general properties
+ of the filter.
+ <dt><em>size_t</em> <code>cd_nelmts</code>
+ <dd>IN: Number of elements in <code>cd_values</code>.
+ <dt><em>const unsigned int</em> <code>cd_values[]</code>
+ <dd>IN: Auxiliary data for the filter.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
- <dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_cache_f"
+
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pmodify_filter_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -4714,47 +3859,461 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pregister" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-Register">H5Pregister</a>
+
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Pregister</code>(
+ <em>hid_t</em> <code>class</code>,
+ <em>const char *</em> <code>name</code>,
+ <em>size_t</em> <code>size</code>,
+ <em>void *</em> <code>default</code>,
+ <em>H5P_prp_create_func_t</em> <code>create</code>,
+ <em>H5P_prp_set_func_t</em> <code>set</code>,
+ <em>H5P_prp_get_func_t</em> <code>get</code>,
+ <em>H5P_prp_delete_func_t</em> <code>delete</code>,
+ <em>H5P_prp_copy_func_t</em> <code>copy</code>,
+ <em>H5P_prp_close_func_t</em> <code>close</code>
+ )
+
+ <dt><strong>Purpose:</strong>
+ <dd>Registers a permanent property with a property list class.
+
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pregister</code> registers a new property with a
+ property list class.
+ The property will exist in all property list objects of
+ <code>class</code> created after this routine finishes. The name
+ of the property must not already exist, or this routine will fail.
+ The default property value must be provided and all new property
+ lists created with this property will have the property value set
+ to the default value. Any of the callback routines may be set to
+ NULL if they are not needed.
+
+ <P>
+ Zero-sized properties are allowed and do not store any data in the
+ property list. These may be used as flags to indicate the presence
+ or absence of a particular piece of information. The default pointer
+ for a zero-sized property may be set to NULL.
+ The property <code>create</code> and <code>close</code> callbacks
+ are called for zero-sized properties, but the <code>set</code> and
+ <code>get</code> callbacks are never called.
+ </P>
+
+ The <code>create</code> routine is called when a new property list
+ with this property is being created.
+ The <code>H5P_prp_create_func_t</code> callback function is defined
+ as follows:
+ <ul><em>typedef herr_t</em> (*<code>H5P_prp_create_func_t</code>)(
+ <em>const char *</em><code>name</code>,
+ <em>size_t </em><code>size</code>,
+ <em>void *</em><code>initial_value</code>);
+ </ul>
+ The parameters to this callback function are defined as follows:
+ <ul><table>
+ <tr>
+ <td><em>const char *</em><code>name</code></td>
+ <td>IN: The name of the property being modified</td></tr>
+ <tr>
+ <td><em>size_t</em> <code>size</code></td>
+ <td>IN: The size of the property in bytes</td></tr>
+ <tr>
+ <td><em>void *</em><code>initial_value</code></td>
+ <td>IN/OUT: The default value for the property being created,
+ which will be passed to <code>H5Pregister</code></td></tr>
+ </table></ul>
+ The <code>create</code> routine may modify the value to be set and
+ those changes will be stored as the initial value of the property.
+ If the <code>create</code> routine returns a negative value,
+ the new property value is not copied into the property and the
+ create routine returns an error value.
+ </P>
+
+ The <code>set</code> routine is called before a new value is copied
+ into the property.
+ The <code>H5P_prp_set_func_t</code> callback function is defined
+ as follows:
+ <ul><em>typedef herr_t</em> (*H5P_prp_set_func_t)(
+ <em>hid_t </em><code>prop_id</code>,
+ <em>const char *</em><code>name</code>,
+ <em>size_t </em><code>size</code>,
+ <em>void *</em><code>new_value</code>);
+ </ul>
+ The parameters to this callback function are defined as follows:
+ <ul><table>
+ <tr>
+ <td><em>hid_t</em> <code>prop_id</code></td>
+ <td>IN: The identifier of the property list being modified</td></tr>
+ <tr>
+ <td><em>const char *</em><code>name</code></td>
+ <td>IN: The name of the property being modified</td></tr>
+ <tr>
+ <td><em>size_t </em><code>size</code></td>
+ <td>IN: The size of the property in bytes</td></tr>
+ <tr>
+ <td><em>void **</em><code>new_value</code></td>
+ <td>IN/OUT: Pointer to new value pointer for the property being
+ modified</td></tr>
+ </table></ul>
+ The <code>set</code> routine may modify the value pointer to be set
+ and those changes will be used when setting the property's value.
+ If the <code>set</code> routine returns a negative value, the new
+ property value is not copied into the property and the
+ <code>set</code> routine returns an error value.
+ The <code>set</code> routine will not be called for the initial
+ value, only the <code>create</code> routine will be called.
+ <p>
+ <strong>Note:</strong>
+ The <code>set</code> callback function may be useful
+ to range check the value being set for the property
+ or may perform some tranformation or translation of the
+ value set. The <code>get</code> callback would then
+ reverse the transformation or translation.
+ A single <code>get</code> or <code>set</code> callback
+ could handle multiple properties by
+ performing different actions based on the
+ property name or other properties in the property list.
+
+ <p>
+ The <code>get</code> routine is called when a value is retrieved
+ from a property value.
+ The <code>H5P_prp_get_func_t</code> callback function is defined
+ as follows:
+ <ul><em>typedef herr_t</em> (*<code>H5P_prp_get_func_t</code>)(
+ <em>hid_t </em><code>prop_id</code>,
+ <em>const char *</em><code>name</code>,
+ <em>size_t </em><code>size</code>,
+ <em>void *</em><code>value</code>);
+ </ul>
+ The parameters to the callback function are defined as follows:
+ <ul><table>
+ <tr>
+ <td><em>hid_t</em> <code>prop_id</code></td>
+ <td>IN: The identifier of the property list being queried</td></tr>
+ <tr>
+ <td><em>const char *</em> <code>name</code></td>
+ <td>IN: The name of the property being queried</td></tr>
+ <tr>
+ <td><em>size_t </em> <code>size</code></td>
+ <td>IN: The size of the property in bytes</td></tr>
+ <tr>
+ <td><em>void *</em> <code>value</code></td>
+ <td>IN/OUT: The value of the property being returned</td></tr>
+ </table></ul>
+ The <code>get</code> routine may modify the value to be returned from
+ the query and those changes will be returned to the calling routine.
+ If the <code>set</code> routine returns a negative value, the query
+ routine returns an error value.
+ </P>
+
+ The <code>delete</code> routine is called when a property is being
+ deleted from a property list.
+ The <code>H5P_prp_delete_func_t</code> callback function is defined
+ as follows:
+ <ul><em>typedef herr_t</em> (*<code>H5P_prp_delete_func_t</code>)(
+ <em>hid_t </em><code>prop_id</code>,
+ <em>const char *</em><code>name</code>,
+ <em>size_t </em><code>size</code>,
+ <em>void *</em><code>value</code>);
+ </ul>
+ The parameters to the callback function are defined as follows:
+ <ul><table>
+ <tr>
+ <td><em>hid_t</em> <code>prop_id</code></td>
+ <td>IN: The identifier of the property list the property is being
+ deleted from</td></tr>
+ <tr>
+ <td><em>const char *</em> <code>name</code></td>
+ <td>IN: The name of the property in the list</td></tr>
+ <tr>
+ <td><em>size_t </em> <code>size</code></td>
+ <td>IN: The size of the property in bytes</td></tr>
+ <tr>
+ <td><em>void *</em> <code>value</code></td>
+ <td>IN: The value for the property being deleted</td></tr>
+ </table></ul>
+ The <code>delete</code> routine may modify the value passed in,
+ but the value is not used by the library when the <code>delete</code>
+ routine returns. If the <code>delete</code> routine returns
+ a negative value, the property list delete routine returns
+ an error value but the property is still deleted.
+ </P>
+
+ The <code>copy</code> routine is called when a new property list with
+ this property is being created through a copy operation.
+ The <code>H5P_prp_copy_func_t</code> callback function is defined
+ as follows:
+ <ul><em>typedef herr_t</em> (*<code>H5P_prp_copy_func_t</code>)(
+ <em>const char *</em><code>name</code>,
+ <em>size_t </em><code>size</code>,
+ <em>void *</em><code>value</code>);
+ </ul>
+ The parameters to the callback function are defined as follows:
+ <ul><table>
+ <tr>
+ <td><em>const char *</em><code>name</code></td>
+ <td>IN: The name of the property being copied</td></tr>
+ <tr>
+ <td><em>size_t </em><code>size</code></td>
+ <td>IN: The size of the property in bytes</td></tr>
+ <tr>
+ <td><em>void *</em><code>value</code></td>
+ <td>IN/OUT: The value for the property being copied</td></tr>
+ </table></ul>
+ The <code>copy</code> routine may modify the value to be set and
+ those changes will be stored as the new value of the property.
+ If the <code>copy</code> routine returns a negative value,
+ the new property value is not copied into the property and
+ the copy routine returns an error value.
+ </P>
+
+ The <code>close</code> routine is called when a property list with
+ this property is being closed.
+ The <code>H5P_prp_close_func_t</code> callback function is defined
+ as follows:
+ <ul><em>typedef herr_t</em> (*<code>H5P_prp_close_func_t</code>)(
+ <em>hid_t </em><code>prop_id</code>,
+ <em>const char *</em><code>name</code>,
+ <em>size_t </em><code>size</code>,
+ <em>void *</em><code>value</code>);
+ </ul>
+ The parameters to the callback function are defined as follows:
+ <ul><table>
+ <tr>
+ <td><em>hid_t</em> <code>prop_id</code></td>
+ <td>IN: The identifier of the property list being
+ closed</td></tr>
+ <tr>
+ <td><em>const char *</em><code>name</code></td>
+ <td>IN: The name of the property in the list</td></tr>
+ <tr>
+ <td><em>size_t</em> <code>size</code></td>
+ <td>IN: The size of the property in bytes</td></tr>
+ <tr>
+ <td><em>void *</em><code>value</code></td>
+ <td>IN: The value for the property being closed</td></tr>
+ </table></ul>
+ The <code>close</code> routine may modify the value passed in,
+ but the value is not used by the library when the
+ <code>close</code> routine returns.
+ If the <code>close</code> routine returns a negative value,
+ the property list close routine returns an error value but
+ the property list is still closed.
+
+<dt><strong>Parameters:</strong>
+ <ul><dl>
+ <dt><code>hid_t</code> <em>class</em>
+ <dd>IN: Property list class to register permanent property
+ within
+ <dt><code>const char *</code> <em>name</em>
+ <dd>IN: Name of property to register
+ <dt><code>size_t</code> <em>size</em>
+ <dd>IN: Size of property in bytes
+ <dt><code>void *</code> <em>default</em>
+ <dd>IN: Default value for property in newly created property
+ lists
+ <dt><code>H5P_prp_create_func_t</code> <em>create</em>
+ <dd>IN: Callback routine called when a property list is being
+ created and the property value will be initialized
+ <dt><code>H5P_prp_set_func_t</code> <em>set</em>
+ <dd>IN: Callback routine called before a new value is copied
+ into the property's value
+ <dt><code>H5P_prp_get_func_t</code> <em>get</em>
+ <dd>IN: Callback routine called when a property value is
+ retrieved from the property
+ <dt><code>H5P_prp_delete_func_t</code> <em>delete</em>
+ <dd>IN: Callback routine called when a property is deleted from
+ a property list
+ <dt><code>H5P_prp_copy_func_t</code> <em>copy</em>
+ <dd>IN: Callback routine called when a property is copied from
+ a property list
+ <dt><code>H5P_prp_close_func_t</code> <em>close</em>
+ <dd>IN: Callback routine called when a property list is being
+ closed and the property value will be disposed of
+ </dl></ul>
+
+<dt><strong>Returns:</strong>
+ <dd>Success: a non-negative value
+ <dd>Failure: a negative value
+
+ <dt><strong>Non-C APIs:</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pregister_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Premove" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-Remove">H5Premove</a>
+
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Premove</code>(<code>plid, name</code>)
+ <em>hid_t</em> <code>plid</code>;
+ <em>const char *</em><code>name</code>
+ )
+
+ <dt><strong>Purpose:</strong>
+ <dd>Removes a property from a property list.
+
+ <dt><strong>Description:</strong>
+ <dd><code>H5Premove</code> removes a property from a property list.
+
+ <p>
+ Both properties which were in existence when the property list
+ was created (i.e. properties registered with <code>H5Pregister</code>)
+ and properties added to the list after it was created (i.e. added
+ with <code>H5Pinsert</code>) may be removed from a property list.
+ Properties do not need to be removed from a property list before the
+ list itself is closed; they will be released automatically when
+ <code>H5Pclose</code> is called.
+
+ <p>
+ If a <code>close</code> callback exists for the removed property,
+ it will be called before the property is released.
+
+ <dt><strong>Parameters:</strong>
+ <ul><table>
+ <tr>
+ <td><em>hid_t</em> <code>plid</code></td>
+ <td>IN: Identifier of the property list to modify</td></tr>
+ <tr>
+ <td><em>const char *</em><code>name</code></td>
+ <td>IN: Name of property to remove</td></tr>
+ </table></ul>
+
+ <dt><strong>Returns:</strong>
+ <dd>Success: a non-negative value
+ <dd>Failure: a negative value
+
+ <dt><strong>Non-C APIs:</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5premove_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-Set">H5Pset</a>
+
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Pset</code>(
+ <em>hid_t</em> <code>plid</code>,
+ <em>const char *</em><code>name</code>,
+ <em>void *</em><code>value</code>)
+ )
+
+ <dt><strong>Purpose:</strong>
+ <dd>Sets a property list value.
+
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pset</code> sets a new value for a property in a
+ property list. If there is a <code>set</code> callback
+ routine registered for this property, the <code>value</code> will be
+ passed to that routine and any changes to the <code>value</code>
+ will be used when setting the property value.
+ The information pointed to by the <code>value</code> pointer
+ (possibly modified by the <code>set</code> callback) is copied into
+ the property list value and may be changed by the application making
+ the <code>H5Pset</code> call without affecting the property value.
+
+ <P>
+ The property name must exist or this routine will fail.
+
+ <P>
+ If the <code>set</code> callback routine returns an error, the
+ property value will not be modified.
+
+ <P>
+ This routine may not be called for zero-sized properties
+ and will return an error in that case.
+
+ <dt><strong>Parameters:</strong>
+ <ul><table>
+ <tr>
+ <td><em>hid_t</em> <code>plid</code>;
+ <td>IN: Property list identifier to modify</td></tr>
+ <tr>
+ <td><em>const char *</em><code>name</code>;
+ <td>IN: Name of property to modify</td></tr>
+ <tr>
+ <td><em>void *</em><code>value</code>;
+ <td>IN: Pointer to value to set the property to</td></tr>
+ </table></ul>
+
+ <dt><strong>Returns:</strong>
+ <dd>Success: a non-negative value
+ <dd>Failure: a negative value
+ <dt><strong>Non-C APIs:</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_alignment" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetHyperVectorSize">H5Pset_hyper_vector_size</a>
+ <dt><strong>Name:</strong> <a name="Property-SetAlignment">H5Pset_alignment</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_hyper_vector_size</code>(<em>hid_t</em> <code>dxpl_id</code>,
- <em>size_t</em> <code>vector_size</code>
+ <dd><em>herr_t</em> <code>H5Pset_alignment</code>(<em>hid_t</em> <code>plist</code>,
+ <em>hsize_t</em> <code>threshold</code>,
+ <em>hsize_t</em> <code>alignment</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets number of I/O vectors to be read/written in hyperslab I/O.
+ <dd>Sets alignment properties of a file access property list.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_hyper_vector_size</code> sets the number of
- I/O vectors to be accumulated in memory before being issued
- to the lower levels of the HDF5 library for reading or writing the
- actual data.
- <p>
- The <em>I/O vectors</em> are hyperslab offset and length pairs
- and are generated during hyperslab I/O.
- <p>
- The number of I/O vectors is passed in <code>vector_size</code>
- to be set in the dataset transfer property list <code>dxpl_id</code>.
- <code>vector_size</code> must be greater than <code>1</code> (one).
+ <dd><code>H5Pset_alignment</code> sets the alignment properties
+ of a file access property list
+ so that any file object greater than or equal in size to
+ <code>threshold</code> bytes will be aligned on an address
+ which is a multiple of <code>alignment</code>. The addresses
+ are relative to the end of the user block; the alignment is
+ calculated by subtracting the user block size from the
+ absolute file address and then adjusting the address to be a
+ multiple of <code>alignment</code>.
<p>
- <code>H5Pset_hyper_vector_size</code> is an I/O optimization function;
- increasing <code>vector_size</code> should provide better performance,
- but the library will use more memory during hyperslab I/O.
- The default value of <code>vector_size</code> is <code>1024</code>.
+ Default values for <code>threshold</code> and
+ <code>alignment</code> are one, implying
+ no alignment. Generally the default values will result in
+ the best performance for single-process access to the file.
+ For MPI-IO and other parallel systems, choose an alignment
+ which is a multiple of the disk block size.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>dxpl_id</code>
- <dd>IN: Dataset transfer property list identifier.
- <dt><em>size_t</em> <code>vector_size</code>
- <dd>IN: Number of I/O vectors to accumulate in memory for I/O operations.
- Must be greater than <code>1</code> (one).
- Default value: <code>1024</code>.
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Identifier for a file access property list.
+ <dt><em>hsize_t</em> <code>threshold</code>
+ <dd>IN: Threshold value.
+ Must be non-negative.
+ Note that setting the threshold value to 0 (zero) has
+ the effect of a special case, forcing everything
+ to be aligned.
+ <dt><em>hsize_t</em> <code>alignment</code>
+ <dd>IN: Alignment value.
+ Must be a positive value.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_hyper_vector_size_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_alignment_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -4762,41 +4321,77 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_alloc_time" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetHyperVectorSize">H5Pget_hyper_vector_size</a>
+ <dt><strong>Name:</strong> <a name="Property-SetAllocTime">H5Pset_alloc_time</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_hyper_vector_size</code>(<em>hid_t</em> <code>dxpl_id</code>,
- <em>size_t *</em><code>vector_size</code>
- )
+ <dd><em>herr_t </em><code>H5Pset_alloc_time</code>(<em>hid_t</em> <code>plist_id</code>,
+ <em>H5D_alloc_time_t</em> <code>alloc_time</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Retrieves number of I/O vectors to be read/written in hyperslab I/O.
+ <dd>Sets the timing for storage space allocation.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_hyper_vector_size</code> retrieves the number of
- I/O vectors to be accumulated in memory before being issued
- to the lower levels of the HDF5 library for reading or writing the
- actual data.
+ <dd><code>H5Pset_alloc_time</code> sets up the timing for the allocation of
+ storage space for a dataset's raw data.
+ This property is set in the dataset creation property list
+ <code>plist_id</code>.
<p>
- The number of I/O vectors set in the dataset transfer property list
- <code>dxpl_id</code> is returned in <code>vector_size</code>.
- Unless the default value is in use, <code>vector_size</code>
- was previously set with a call to
- <a href="#Property-SetHyperVectorSize">H5Pset_hyper_vector_size</a>.
+ Timing is specified in <code>fill_time</code> with one of the
+ following values:
+ <table border=0 >
+ <tr valign="top"><td rowspan="4">&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ <code>H5D_ALLOC_TIME_DEFAULT</code>&nbsp;&nbsp;
+ </td><td>
+ Allocate dataset storage space at the default time.<br>
+ (Defaults differ by storage method.)
+ </td></tr><tr valign="top"><td>
+ <code>H5D_ALLOC_TIME_EARLY</code>
+ </td><td>
+ Allocate all space when the dataset is created.<br>
+ (Default for compact datasets.)
+ </td></tr><tr valign="top"><td>
+ <code>H5D_ALLOC_TIME_INCR</code>&nbsp;&nbsp;
+ </td><td>
+ Allocate space incrementally, as data is written to the dataset.<br>
+ (Default for chunked storage datasets.)
+ <li>Chunked datasets:
+ Storage space allocation for each chunk is deferred until data
+ is written to the chunk.
+ <li>Contiguous datasets:
+ Incremental storage space allocation for contiguous data
+ is treated as late allocation.
+ <li>Compact datasets:
+ Incremental allocation is not allowed with compact datasets;
+ </em><code>H5Pset_alloc_time</code> will return an error.
+ </td></tr><tr valign="top"><td>
+ <code>H5D_ALLOC_TIME_LATE</code>
+ </td><td>
+ Allocate all space when data is first written to the dataset.<br>
+ (Default for contiguous datasets.)
+ </td></tr></table>
+ <dt><strong>Note:</strong>
+ <dd><code>H5Pset_alloc_time</code> is designed to work in concert
+ with the dataset fill value and fill value write time properties,
+ set with the functions
+ <code>H5Pset_fill_value</code> and <code>H5Pset_fill_time</code>.
+ <p>
+ <p>
+ See <a href="RM_H5D.html#Dataset-Create">H5Dcreate</a> for
+ further cross-references.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>dxpl_id</code>
- <dd>IN: Dataset transfer property list identifier.
- <dt><em>size_t *</em><code>vector_size</code>
- <dd>OUT: Number of I/O vectors to accumulate in memory for I/O operations.
+ <dt><em>hid_t</em> <code>plist_id</code>
+ <dd>IN: Dataset creation property list identifier.
+ <dt><em>H5D_alloc_time_t</em> <code>alloc_time</code>
+ <dd>IN: When to allocate dataset storage space.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
-
-
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_hyper_vector_size_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_alloc_time_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -4804,11 +4399,8 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
-
-
-
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_btree_ratios" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-SetBTreeRatios">H5Pset_btree_ratios</a>
@@ -4858,49 +4450,8 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-GetBTreeRatios">H5Pget_btree_ratios</a>
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_btree_ratios</code>(<em>hid_t</em> <code>plist</code>,
- <em>double</em> *<code>left</code>,
- <em>double</em> *<code>middle</code>,
- <em>double</em> *<code>right</code>
- )
- <dt><strong>Purpose:</strong>
- <dd>Gets B-tree split ratios for a dataset transfer property list.
- <dt><strong>Description:</strong>
- <dd><code>H5Pget_btree_ratios</code> returns the B-tree split ratios
- for a dataset transfer property list.
- <p>
- The B-tree split ratios are returned through the non-<code>NULL</code>
- arguments <code>left</code>, <code>middle</code>, and <code>right</code>,
- as set by the <a href="#Property-SetBTreeRatios">H5Pset_btree_ratios</a> function.
- <dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: The dataset transfer property list identifier.
- <dt><em>double</em> <code>left</code>
- <dd>OUT: The B-tree split ratio for left-most nodes.
- <dt><em>double</em> <code>right</code>
- <dd>OUT: The B-tree split ratio for right-most nodes and lone nodes.
- <dt><em>double</em> <code>middle</code>
- <dd>OUT: The B-tree split ratio for all other nodes.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
- <dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_btree_ratios_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_buffer" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-SetBuffer">H5Pset_buffer</a>
@@ -4959,94 +4510,60 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-GetBuffer">H5Pget_buffer</a>
- <dt><strong>Signature:</strong>
- <dd><em>hsize_t</em> <code>H5Pget_buffer</code>(<em>hid_t</em> <code>plist</code>,
- <em>void</em> <code>**tconv</code>,
- <em>void</em> <code>**bkg</code>
- )
- <dt><strong>Purpose:</strong>
- <dd>Reads buffer settings.
- <dt><strong>Description:</strong>
- <dd><code>H5Pget_buffer</code> reads values previously set
- with H5Pset_buffer.
- <dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier for the dataset transfer property list.
- <dt><em>void</em> <code>**tconv</code>
- <dd>OUT: Address of the pointer to application-allocated
- type conversion buffer.
- <dt><em>void</em> <code>**bkg</code>
- <dd>OUT: Address of the pointer to application-allocated
- background buffer.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns buffer size, in bytes, if successful;
- otherwise 0 on failure.
- <dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_buffer_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_cache" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetSmallData">H5Pset_small_data_block_size</a>
+ <dt><strong>Name:</strong> <a name="Property-SetCache">H5Pset_cache</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_small_data_block_size</code>(<em>hid_t</em> <code>fapl_id</code>,
- <em>hsize_t</em> <code>size</code>
- )
+ <dd><em>herr_t</em> <code>H5Pset_cache</code>(<em>hid_t</em> <code>plist_id</code>,
+ <em>int</em> <code>mdc_nelmts</code>,
+ <em>int</em> <code>rdcc_nelmts</code>,
+ <em>size_t</em> <code>rdcc_nbytes</code>,
+ <em>double</em> <code>rdcc_w0</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Sets the size of a contiguous block reserved for small data.
+ <dd>Sets the meta data cache and raw data chunk cache parameters.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_small_data_block_size</code> reserves blocks of
- <code>size</code> bytes for the contiguous storage of the raw data
- portion of <em>small</em> datasets.
- The HDF5 library then writes the raw data from small datasets
- to this reserved space, thus reducing unnecessary discontinuities
- within blocks of meta data and improving IO performance.
- <p>
- A small data block is actually allocated the first time a
- qualifying small dataset is written to the file.
- Space for the raw data portion of this small dataset is suballocated
- within the small data block.
- The raw data from each subsequent small dataset is also written to
- the small data block until it is filled; additional small data blocks
- are allocated as required.
+ <dd><code>H5Pset_cache</code> sets
+ the number of elements (objects) in the meta data cache and
+ the number of elements, the total number of bytes, and
+ the preemption policy value in the raw data chunk cache.
<p>
- The HDF5 library employs an algorithm that determines whether
- IO performance is likely to benefit from the use of this mechanism
- with each dataset as storage space is allocated in the file.
- A larger <code>size</code> will result in this mechanism being
- employed with larger datasets.
+ The <em>plist_id</em> is a file access property list.
+ The number of elements (objects) in the meta data cache
+ and the raw data chunk cache are <em>mdc_nelmts</em> and
+ <em>rdcc_nelmts</em>, respectively.
+ The total size of the raw data chunk cache and the preemption policy
+ are <em>rdcc_nbytes</em> and <em>rdcc_w0</em>.
<p>
- The small data block size is set as an allocation property in the
- file access property list identified by <code>fapl_id</code>.
+ Any (or all) of the <code>H5Pget_cache</code> pointer arguments
+ may be null pointers.
<p>
- Setting <code>size</code> to zero (<code>0</code>) disables the
- small data block mechanism.
+ The <em>rdcc_w0</em> value should be between 0 and 1 inclusive and
+ indicates how much chunks that have been fully read are
+ favored for preemption. A value of zero means fully read
+ chunks are treated no differently than other chunks (the
+ preemption is strictly LRU) while a value of one means fully
+ read chunks are always preempted before other chunks.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>fapl_id</code>
- <dd>IN: File access property list identifier .
- <dt><em>hsize_t</em> <code>size</code>
- <dd>IN: Maximum size, in bytes, of the small data block.
- <br>
- The default size is <code>2048</code>.
+ <dt><em>hid_t</em> <code>plist_id</code>
+ <dd>IN: Identifier of the file access property list.
+ <dt><em>int</em> <code>mdc_nelmts</code>
+ <dd>IN: Number of elements (objects) in the meta data cache.
+ <dt><em>int</em> <code>rdcc_nelmts</code>
+ <dd>IN: Number of elements (objects) in the raw data chunk cache.
+ <dt><em>size_t</em> <code>rdcc_nbytes</code>
+ <dd>IN: Total size of the raw data chunk cache, in bytes.
+ <dt><em>double</em> <code>rdcc_w0</code>
+ <dd>IN: Preemption policy.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
- otherwise a negative value.
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_small_data_block_size_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_cache_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -5054,34 +4571,41 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_chunk" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetSmallData">H5Pget_small_data_block_size</a>
+ <dt><strong>Name:</strong> <a name="Property-SetChunk">H5Pset_chunk</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_small_data_block_size</code>(<em>hid_t</em> <code>fapl_id</code>,
- <em>hsize_t *</em><code>size</code>
+ <dd><em>herr_t </em><code>H5Pset_chunk</code>(<em>hid_t</em> <code>plist</code>,
+ <em>int</em> <code>ndims</code>,
+ <em>const hsize_t *</em> <code>dim</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves the current small data block size setting.
+ <dd>Sets the size of the chunks used to store a chunked layout dataset.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_small_data_block_size</code> retrieves the
- current setting for the size of the small data block.
- <p>
- If the returned value is zero (<code>0</code>), the small data
- block mechanism has been disabled for the file.
+ <dd><code>H5Pset_chunk</code> sets the size of the chunks used to
+ store a chunked layout dataset. This function is only valid
+ for dataset creation property lists.
+ The <code>ndims</code> parameter currently must be the same size
+ as the rank of the dataset. The values of the <code>dim</code>
+ array define the size of the chunks to store the dataset's raw data.
+ As a side-effect, the layout of the dataset is changed to
+ <code>H5D_CHUNKED</code>, if it is not already.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>fapl_id</code>
- <dd>IN: File access property list identifier .
- <dt><em>hsize_t *</em><code>size</code>
- <dd>OUT: Maximum size, in bytes, of the small data block.
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Identifier for property list to query.
+ <dt><em>int</em> <code>ndims</code>
+ <dd>IN: The number of dimensions of each chunk.
+ <dt><em>const hsize_t *</em> <code>dim</code>
+ <dd>IN: An array containing the size of each chunk.
</dl>
- <dt><strong>Returns:</strong>
+<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
- otherwise a negative value.
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_small_data_block_size_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_chunk_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -5089,38 +4613,36 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_deflate" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetPreserve">H5Pset_preserve</a>
+ <dt><strong>Name:</strong> <a name="Property-SetDeflate">H5Pset_deflate</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_preserve</code>(<em>hid_t</em> <code>plist</code>,
- <em>hbool_t</em> <code>status</code>
- )
+ <dd><em>herr_t</em> <code>H5Pset_deflate</code>(<em>hid_t</em> <code>plist</code>,
+ <em>int</em> <code>level</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Sets the dataset transfer property list status to TRUE or FALSE.
+ <dd>Sets compression method and compression level.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_preserve</code> sets the
- dataset transfer property list status to TRUE or FALSE.
- <p>
- When reading or writing compound data types and the
- destination is partially initialized and the read/write is
- intended to initialize the other members, one must set this
- property to TRUE. Otherwise the I/O pipeline treats the
- destination datapoints as completely uninitialized.
+ <dd><code>H5Pset_deflate</code> sets the compression method for a
+ dataset creation property list to <code>H5D_COMPRESS_DEFLATE</code>
+ and the compression level to <code>level</code>, which should
+ be a value from zero to nine, inclusive.
+ Lower compression levels are faster but result in less compression.
+ This is the same algorithm as used by the GNU gzip program.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier for the dataset transfer property list.
- <dt><em>hbool_t</em> <code>status</code>
- <dd>IN: Status of for the dataset transfer property list
- (TRUE/FALSE).
+ <dd>IN: Identifier for the dataset creation property list.
+ <dt><em>int</em> <code>level</code>
+ <dd>IN: Compression level.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_preserve_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_deflate_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -5128,169 +4650,186 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
+<!-- ********** MOVED TO TechNotes/VFLfunc.html **********
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetPreserve">H5Pget_preserve</a>
+ <dt><strong>Name:</strong> <a name="Property-SetDriver">H5Pset_driver</a>
<dt><strong>Signature:</strong>
- <dd><em>int</em> <code>H5Pget_preserve</code>(<em>hid_t</em> <code>plist</code>)
+ <dd><em>herr_t</em> <code>H5Pset_driver</code>(
+ <em>hid_t</em> <code>plist_id</code>,
+ <em>hid_t</em> <code>driver_id</code>,
+ <em>const void *</em> <code>driver_info</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Checks status of the dataset transfer property list.
+ <dd>Sets the file driver.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_preserve</code> checks the status of the
- dataset transfer property list.
+ <dd><code>H5Pset_driver</code> sets the file driver,
+ <code>driver_id</code>, for a file access or data transfer
+ property list, <code>plist_id</code>, and supplies an
+ optional struct containing the driver-specific properties,
+ <code>driver_info</code>.
+ <p>
+ <font color=red><b><i>Need <code>driver_info</code> struct definition.</i></b></font>
+ <p>
+ The driver properties will be copied into the property list
+ and the reference count on the driver will be incremented,
+ allowing the caller to close the driver identifier but still use
+ the property list.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier for the dataset transfer property list.
+ <dt><em>hid_t</em> <code>plist_id</code>
+ <dd>IN: File access or data transfer property list identifier.
+ <dt><em>hid_t</em> <code>driver_id</code>
+ <dd>IN: Driver identifier.
+ <dt><em>const void *</em> <code>driver_info</code>
+ <dd>IN: Optional struct containing driver properties.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns TRUE or FALSE if successful;
- otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful.
+ Otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_preserve_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
- -->
</dl>
+-->
-<!--
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_dxpl_mpio" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetCompression">H5Pset_compression</a>
+ <dt><strong>Name:</strong> <a name="Property-SetDxplMpio">H5Pset_dxpl_mpio</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_compression</code>(<em>hid_t</em> <code>plist</code>,
- <em>H5Z_method_t</em> <code>method</code>,
- <em>unsigned int</em> <code>flags</code>,
- <em>size_t</em> <code>cd_size</code>,
- <em>const void</em> <code>*client_data</code>
+ <dd><em>herr_t</em> <code>H5Pset_dxpl_mpio</code>(
+ <em>hid_t</em> <code>dxpl_id</code>,
+ <em>H5FD_mpio_xfer_t</em> <code>xfer_mode</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets compression method.
+ <dd>Sets data transfer mode.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_compression</code> sets the compression method
- in a dataset creation property list. This is a catch-all
- function for defining compression methods
- and is intended to be called from a wrapper such as
- <code>H5Pset_deflate</code>. The dataset creation property
- list <em>plist</em> is adjusted to use the specified
- compression method. The <em>flags</em> is an 8-bit vector
- which is stored in the file as part of the compression message
- and passed to the compress and uncompress functions. The
- <em>client_data</em> is a byte array of length
- <em>cd_size</em> which is copied to the file and passed to the
- compress and uncompress methods.
- <p>
- The FLAGS, CD_SIZE, and CLIENT_DATA are copied to the
- property list and eventually to the file and passed to the
- compression functions.
+ <dd><code>H5Pset_dxpl_mpio</code> sets the data transfer property list
+ <code>dxpl_id</code> to use transfer mode <code>xfer_mode</code>.
+ The property list can then be used to control the I/O transfer mode
+ during data I/O operations.
<p>
- See <a href="Datasets.html"><cite>The Dataset Interface (H5D)</cite></a>
- in the <cite>HDF5 User's Guide</cite> for further information
- regarding data compression.
+ Valid transfer modes are as follows:
+ <dir>
+ <dl>
+ <dt><code>H5FD_MPIO_INDEPENDENT</code>
+ <dd>Use independent I/O access (default).
+ <dt><code>H5FD_MPIO_COLLECTIVE</code>
+ <dd>Use collective I/O access.
+ </dl>
+ </dir>
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier for the dataset creation property list.
- <dt><em>H5Z_method_t</em> <code>method</code>
- <dd>IN: Compression method, an integer from 16 to 225.
- <dt><em>unsigned int</em> <code>flags</code>
- <dd>IN: Compression flags.
- <dt><em>size_t</em> <code>cd_size</code>
- <dd>IN: Size of the byte array <code>client_data</code>.
- <dt><em>const void</em> <code>*client_data</code>
- <dd>IN: Client data byte array passed to the compression method.
+ <dt><em>hid_t</em> <code>dxpl_id</code>
+ <dd>IN: Data transfer property list identifier.
+ <dt><em>H5FD_mpio_xfer_t</em> <code>xfer_mode</code>
+ <dd>IN: Transfer mode.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful.
+ Otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_dxpl_mpio_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
+ -->
</dl>
--->
-
-
-<!--
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_dxpl_multi" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetCompression">H5Pget_compression</a>
+ <dt><strong>Name:</strong> <a name="Property-SetDxplMulti">H5Pset_dxpl_multi</a>
<dt><strong>Signature:</strong>
- <dd><em>H5Z_method_t</em> <code>H5Pget_compression</code>(<em>hid_t</em> <code>plist</code>,
- <em>unsigned int</em> <code>*flags</code>,
- <em>size_t</em> <code>*cd_size</code>,
- <em>void</em> <code>*client_data</code>
+ <dd><em>herr_t</em> <code>H5Pset_dxpl_multi</code>(
+ <em>hid_t</em> <code>dxpl_id</code>,
+ <em>const hid_t *</em><code>memb_dxpl</code>
)
<dt><strong>Purpose:</strong>
- <dd>Gets compression method.
+ <dd>Sets the data transfer property list for the multi-file driver.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_compression</code> gets the compression method
- information from a dataset creation property list.
- The <code>client_data</code> buffer is initially
- <code>cd_size</code> bytes. On return, <code>client_data</code>
- will be initialized with at most that many bytes, and
- <code>cd_size</code> will contain the actual size of the
- client data, which might be larger than its original value.
+ <dd><code>H5Pset_dxpl_multi</code> sets the data transfer property list
+ <code>dxpl_id</code> to use the multi-file driver for each
+ memory usage type <code>memb_dxpl[]</code>.
+ <p>
+ <code>H5Pset_dxpl_multi</code> can only be used after
+ the member map has been set with <code>H5Pset_fapl_multi</code>.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier for the dataset creation property list.
- <dt><em>unsigned int</em> <code>*flags</code>
- <dd>OUT: Compression flags.
- <dt><em>size_t</em> <code>*cd_size</code>
- <dd>IN/OUT: Size of the <code>client_data</code> array.
- <dt><em>void</em> <code>*client_data</code>
- <dd>OUT: Byte array for the client data.
+ <dt><em>hid_t</em> <code>dxpl_id</code>,
+ <dd>IN: Data transfer property list identifier.
+ <dt><em>const hid_t *</em><code>memb_dxpl</code>
+ <dd>IN: Array of data access property lists.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns compression method if successful;
- otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful.
+ Otherwise returns a negative value.
+ <!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ -->
+ <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
+ -->
</dl>
--->
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_edc_check" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetDeflate">H5Pset_deflate</a>
+ <dt><strong>Name:</strong> <a name="Property-SetEdcCheck">H5Pset_edc_check</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_deflate</code>(<em>hid_t</em> <code>plist</code>,
- <em>int</em> <code>level</code>
- )
+ <dd><em>herr_t</em> <code>H5Pset_edc_check</code>(<em>hid_t</em> <code>plist</code>,
+ <em>H5Z_EDC_t</em> <code>check</code>)
<dt><strong>Purpose:</strong>
- <dd>Sets compression method and compression level.
+ <dd>Sets whether to enable error-detection when reading a dataset.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_deflate</code> sets the compression method for a
- dataset creation property list to <code>H5D_COMPRESS_DEFLATE</code>
- and the compression level to <code>level</code>, which should
- be a value from zero to nine, inclusive.
- Lower compression levels are faster but result in less compression.
- This is the same algorithm as used by the GNU gzip program.
+ <dd><code>H5Pset_edc_check</code> sets the dataset transfer property
+ list <code>plist</code> to enable or disable error detection
+ when reading data.
+ <p>
+ Whether error detection is enabled or disabled is specified
+ in the <code>check</code> parameter.
+ Valid values are as follows:
+ <table border="0">
+ <tr><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ <code>H5Z_ENABLE_EDC</code> &nbsp; (default)
+ <br>
+ <code>H5Z_DISABLE_EDC</code>
+ </td></tr>
+ </table>
+ <p>
+ The error detection algorithm used is the algorithm previously
+ specified in the corresponding dataset creation property list.  
+ <p>
+ This function does not affect the use of error detection when
+ writing data.  
+ <dt><strong>Note:</strong>
+ <dd>The initial error detection implementation, Fletcher32 checksum,
+ supports error detection for chunked datasets only.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier for the dataset creation property list.
- <dt><em>int</em> <code>level</code>
- <dd>IN: Compression level.
+ <dd>IN: Dataset transfer property list identifier.
+ <dt><em>H5Z_EDC_t</em> <code>check</code>
+ <dd>IN: Specifies whether error checking is enabled or disabled
+ for dataset read operations.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_deflate_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_edc_check_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -5298,183 +4837,166 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
-
-<!--
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_external" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetDeflate">H5Pget_deflate</a>
+ <dt><strong>Name:</strong> <a name="Property-SetExternal">H5Pset_external</a>
<dt><strong>Signature:</strong>
- <dd><em>int</em> <code>H5Pget_deflate</code>(<em>hid_t</em> <code>plist</code>
+ <dd><em>herr_t</em> <code>H5Pset_external</code>(<em>hid_t</em> <code>plist</code>,
+ <em>const char</em> <code>*name</code>,
+ <em>off_t</em> <code>offset</code>,
+ <em>hsize_t</em> <code>size</code>
)
<dt><strong>Purpose:</strong>
- <dd>Returns the deflate compression level from a dataset creation
- property list.
+ <dd>Adds an external file to the list of external files.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_deflate</code> returns the deflate compression level
- from a dataset creation property list that uses that method.
+ <dd><code>H5Pset_external</code> adds an external file to the
+ list of external files.
+ <p>
+ If a dataset is split across multiple files then the files
+ should be defined in order. The total size of the dataset is
+ the sum of the <code>size</code> arguments for all the external files. If
+ the total size is larger than the size of a dataset then the
+ dataset can be extended (provided the data space also allows
+ the extending).
+ <p>
+ The <code>size</code> argument specifies number of bytes reserved
+ for data in the external file.
+ If <code>size</code> is set to <code>H5F_UNLIMITED</code>, the
+ external file can be of unlimited size and no more files can be added to
+ the external files list.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier for the dataset creation property list.
+ <dd>IN: Identifier of a dataset creation property list.
+ <dt><em>const char</em> <code>*name</code>
+ <dd>IN: Name of an external file.
+ <dt><em>off_t</em> <code>offset</code>
+ <dd>IN: Offset, in bytes, from the beginning of the file
+ to the location in the file where the data starts.
+ <dt><em>hsize_t</em> <code>size</code>
+ <dd>IN: Number of bytes reserved in the file for the data.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns compression level, a value between 0 and 9, if successful.
- Otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_external_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
+ -->
</dl>
--->
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_family_offset" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetVLMemManager">H5Pset_vlen_mem_manager</a>
+ <dt><strong>Name:</strong> <a name="Property-SetFamilyOffset">H5Pset_family_offset</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_vlen_mem_manager</code>(<em>hid_t</em> <code>plist</code>,
- <em>H5MM_allocate_t</em> <code>alloc</code>,
- <em>void</em> *<code>alloc_info</code>,
- <em>H5MM_free_t</em> <code>free</code>,
- <em>void</em> *<code>free_info</code>
+ <dd><em>herr_t</em> <code>H5Pset_family_offset</code> (
+ <em>hid_t</em> <code>fapl_id</code>,
+ <em>hsize_t</em> <code>offset</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets the memory manager for variable-length datatype allocation in
- <code>H5Dread</code> and <code>H5Dvlen_reclaim</code>.
+ <dd>Sets offset property for low-level access to a file in a family of files.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_vlen_mem_manager</code> sets the memory manager for
- variable-length datatype allocation in <code>H5Dread</code>
- and free in <code>H5Dvlen_reclaim</code>.
- <p>
- The <code>alloc</code> and <code>free</code> parameters
- identify the memory management routines to be used.
- If the user has defined custom memory management routines,
- <code>alloc</code> and/or <code>free</code> should be set to make
- those routine calls (i.e., the name of the routine is used as
- the value of the parameter);
- if the user prefers to use the system's <code> malloc</code>
- and/or <code>free</code>, the <code>alloc</code> and
- <code>free</code> parameters, respectively, should be set to
- <code> NULL</code>
- <p>
- The prototypes for these user-defined functions would appear as follows:
- <br>&nbsp;&nbsp;&nbsp;&nbsp;
- <em>typedef void</em> *(*<code>H5MM_allocate_t</code>)(<em>size_t</em> <code>size</code>,
- <em>void</em> *<code>alloc_info</code>) ;
-
- <br>&nbsp;&nbsp;&nbsp;&nbsp;
- <em>typedef void</em> (*<code>H5MM_free_t</code>)(<em>void</em> *<code>mem</code>,
- <em>void</em> *<code>free_info</code>) ;
- <br>
- The <code>alloc_info</code> and <code>free_info</code> parameters
- can be used to pass along any required information to
- the user's memory management routines.
- <p>
- In summary, if the user has defined custom memory management
- routines, the name(s) of the routines are passed in the
- <code>alloc</code> and <code>free</code> parameters and the
- custom routines' parameters are passed in the
- <code>alloc_info</code> and <code>free_info</code> parameters.
- If the user wishes to use the system <code> malloc</code> and
- <code>free</code> functions, the <code>alloc</code> and/or
- <code>free</code> parameters are set to <code> NULL</code>
- and the <code>alloc_info</code> and <code>free_info</code>
- parameters are ignored.
+ <dd><code>H5Pset_family_offset</code> sets the offset property in the
+ file access property list <code>fapl_id</code> so that the user application
+ can retrieve a file handle for low-level access to a particluar member
+ of a family of files. The file handle is retrieved with a separate call
+ to <a href="RM_H5F.html#File-GetVfdHandle"><code>H5Fget_vfd_handle</code></a>
+ (or, in special circumstances, to <code>H5FDget_vfd_handle</code>;
+ see <cite>Virtual File Layer</cite> and <cite>List of VFL Functions</cite>
+ in <a href="TechNotes.html"><cite>HDF5 Technical Notes</cite></a>).
+ <p>
+ The value of <code>offset</code> is an offset in bytes from the
+ beginning of the HDF5 file, identifying a user-determined location
+ within the HDF5 file. The file handle the user application is seeking
+ is for the specific member-file in the associated family of files
+ to which this offset is mapped.
+ <p>
+ Use of this function is only appropriate for an HDF5 file written as a
+ family of files with the <code>FAMILY</code> file driver.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier for the dataset transfer property list.
- <dt><em>H5MM_allocate_t</em> <code>alloc</code>
- <dd>IN: User's allocate routine, or &nbsp; <code> NULL</code>
- for system &nbsp; <code> malloc</code>.
- <dt><em>void</em> *<code>alloc_info</code>
- <dd>IN: Extra parameter for user's allocation routine.
- <br>
- Contents are ignored if preceding parameter is &nbsp;
- <code> NULL</code>.
- <dt><em>H5MM_free_t</em> <code>free</code>
- <dd>IN: User's free routine, or &nbsp; <code> NULL</code>
- for system <code>free</code>.
- <dt><em>void</em> *<code>free_info</code>
- <dd>IN: Extra parameter for user's free routine.
- <br>
- Contents are ignored if preceding parameter is &nbsp;
- <code> NULL</code>.
+ <dt><em>hid_t</em> <code>fapl_id</code>
+ <dd>IN: File access property list identifier.
+ <dt><em>hsize_t</em> <code>offset</code>
+ <dd>IN: Offset in bytes within the HDF5 file.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
- <!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_family_offset_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- --> <!--
+ <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_fapl_core" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetVLMemManager">H5Pget_vlen_mem_manager</a>
+ <dt><strong>Name:</strong> <a name="Property-SetFaplCore">H5Pset_fapl_core</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_vlen_mem_manager</code>(<em>hid_t</em> <code>plist</code>,
- <em>H5MM_allocate_t</em> *<code>alloc</code>,
- <em>void</em> **<code>alloc_info</code>,
- <em>H5MM_free_t</em> *<code>free</code>,
- <em>void</em> **<code>free_info</code>
+ <dd><em>herr_t</em> <code>H5Pset_fapl_core</code>(
+ <em>hid_t</em> <code>fapl_id</code>,
+ <em>size_t</em> <code>increment</code>,
+ <em>hbool_t</em> <code>backing_store</code>
)
<dt><strong>Purpose:</strong>
- <dd>Gets the memory manager for variable-length datatype allocation in
- <code>H5Dread</code> and <code>H5Dvlen_reclaim</code>.
+ <dd>Modifies the file access property list to use the
+ <code>H5FD_CORE</code> driver.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_vlen_mem_manager</code> is the companion function to
- <code>H5Pset_vlen_mem_manager</code>, returning the parameters
- set by that function.
+ <dd><code>H5Pset_fapl_core</code> modifies the file access property list
+ to use the <code>H5FD_CORE</code> driver.
+ <p>
+ The <code>H5FD_CORE</code> driver enables an application to work
+ with a file in memory, speeding reads and writes as no disk access
+ is made. File contents are stored only in memory until the file
+ is closed. The <code>backing_store</code> parameter determines
+ whether file contents are ever written to disk.
+ <p>
+ <code>increment</code> specifies the increment by which allocated
+ memory is to be increased each time more memory is required.
+ <p>
+ If <code>backing_store</code> is set to <code>1</code>
+ (<code>TRUE</code>), the file contents are flushed to a file
+ with the same name as this core file when the file is closed
+ or access to the file is terminated in memory.
+ <dt><strong>Note:</strong>
+ <dd>There is currently no means for reading a file from disk then
+ using the <code>H5FD_CORE</code> driver to manipulate the file.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist</code>
- <dd>IN: Identifier for the dataset transfer property list.
- <dt><em>H5MM_allocate_t</em> <code>alloc</code>
- <dd>OUT: User's allocate routine, or &nbsp; <code> NULL</code>
- for system &nbsp; <code> malloc</code>.
- <dt><em>void</em> *<code>alloc_info</code>
- <dd>OUT: Extra parameter for user's allocation routine.
- <br>
- Contents are ignored if preceding parameter is &nbsp;
- <code> NULL</code>.
- <dt><em>H5MM_free_t</em> <code>free</code>
- <dd>OUT: User's free routine, or &nbsp; <code> NULL</code> for
- system <code>free</code>.
- <dt><em>void</em> *<code>free_info</code>
- <dd>OUT: Extra parameter for user's free routine.
- <br>
- Contents are ignored if preceding parameter is &nbsp;
- <code> NULL</code>.
+ <dt><em>hid_t</em> <code>fapl_id</code>
+ <dd>IN: File access property list identifier.
+ <dt><em>size_t</em> <code>increment</code>
+ <dd>IN: Size, in bytes, of memory increments.
+ <dt><em>hbool_t</em> <code>backing_store</code>
+ <dd>IN: Boolean flag indicating whether to write the file
+ contents to disk when the file is closed.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
- <!--
+ <dd>Returns a non-negative value if successful.
+ Otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_fapl_core_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- --> <!--
+ <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
-<!-- -->
-<!-- The new *fapl* functions with R1.4 -->
-<!-- -->
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_fapl_family" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-SetFaplFamily">H5Pset_fapl_family</a>
@@ -5517,134 +5039,47 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-GetFaplFamily">H5Pget_fapl_family</a>
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_fapl_family</code> (
- <em>hid_t</em> <code>fapl_id</code>,
- <em>hsize_t *</em><code>memb_size</code>,
- <em>hid_t *</em><code>memb_fapl_id</code>
- )
- <dt><strong>Purpose:</strong>
- <dd>Returns file access property list information.
- <dt><strong>Description:</strong>
- <dd><code>H5Pget_fapl_family</code> returns file access property list
- for use with the family driver.
- This information is returned through the output parameters.
- <dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>fapl_id</code>
- <dd>IN: File access property list identifier.
- <dt><em> hsize_t *</em><code>memb_size</code>
- <dd>OUT: Size in bytes of each file member.
- <dt><em>hid_t *</em><code>memb_fapl_id</code>
- <dd>OUT: Identifier of file access property list for each
- family member.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
- <dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_fapl_family_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-
-
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-SetFamilyOffset">H5Pset_family_offset</a>
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_family_offset</code> (
- <em>hid_t</em> <code>fapl_id</code>,
- <em>hsize_t</em> <code>offset</code>
- )
- <dt><strong>Purpose:</strong>
- <dd>Sets offset property for low-level access to a file in a family of files.
- <dt><strong>Description:</strong>
- <dd><code>H5Pset_family_offset</code> sets the offset property in the
- file access property list <code>fapl_id</code> so that the user application
- can retrieve a file handle for low-level access to a particluar member
- of a family of files. The file handle is retrieved with a separate call
- to <a href="RM_H5F.html#File-GetVfdHandle"><code>H5Fget_vfd_handle</code></a>
- (or, in special circumstances, to <code>H5FDget_vfd_handle</code>;
- see <cite>Virtual File Layer</cite> and <cite>List of VFL Functions</cite>
- in <a href="TechNotes.html"><cite>HDF5 Technical Notes</cite></a>).
- <p>
- The value of <code>offset</code> is an offset in bytes from the
- beginning of the HDF5 file, identifying a user-determined location
- within the HDF5 file. The file handle the user application is seeking
- is for the specific member-file in the associated family of files
- to which this offset is mapped.
- <p>
- Use of this function is only appropriate for an HDF5 file written as a
- family of files with the <code>FAMILY</code> file driver.
- <dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>fapl_id</code>
- <dd>IN: File access property list identifier.
- <dt><em>hsize_t</em> <code>offset</code>
- <dd>IN: Offset in bytes within the HDF5 file.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
- <dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_family_offset_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_fapl_gass" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetFamilyOffset">H5Pget_family_offset</a>
+ <dt><strong>Name:</strong> <a name="Property-SetFaplGass">H5Pset_fapl_gass</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_family_offset</code> (
- <em>hid_t</em> <code>fapl_id</code>,
- <em>hsize_t *</em><code>offset</code>
+ <dd><em>herr_t</em> <code>H5Pset_fapl_gass</code>(
+ <em>hid_t</em> <code>fapl_id</code>,
+ <em>GASS_Info</em> <code>info</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves a data offset from the file access property list.
+ <dd>Stores user-supplied GASS information.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_family_offset</code> retrieves the value of <code>offset</code>
- from the file access property list <code>fapl_id</code>
- so that the user application
- can retrieve a file handle for low-level access to a particluar member
- of a family of files. The file handle is retrieved with a separate call
- to <a href="RM_H5F.html#File-GetVfdHandle"><code>H5Fget_vfd_handle</code></a>
- (or, in special circumstances, to <code>H5FDget_vfd_handle</code>;
- see <cite>Virtual File Layer</cite> and <cite>List of VFL Functions</cite>
- in <a href="TechNotes.html"><cite>HDF5 Technical Notes</cite></a>).
- <p>
- The data offset returned in <code>offset</code> is the offset
- of the data in the HDF5 file that is stored on disk in the selected
- member file in a family of files.
- <p>
- Use of this function is only appropriate for an HDF5 file written as a
- family of files with the <code>FAMILY</code> file driver.
+ <dd><code>H5Pset_fapl_gass</code> stores user-supplied GASS information,
+ the <em>GASS_Info</em> struct data as passed in <code>info</code>,
+ to the file access property list <code>fapl_id</code>.
+ <code>fapl_id</code> can then be used to create and/or open the file.
+ <p>
+ The <em>GASS_Info</em> object, <code>info</code>, is used for
+ file open operations when using GASS in the Globus environment.
+ <p>
+ Any modification to <code>info</code> after this function call
+ returns may have undetermined effect to the access property list.
+ Users must call <code>H5Pset_fapl_gass</code> again to setup
+ the property list.
+ <dt><strong>Note:</strong>
+ <dd><code>H5Pset_fapl_gass</code> is an experimental function.
+ It is designed for use only when accessing files via the
+ GASS facility of the Globus environment.
+ For further information, see
+ <a href="http://www.globus.org/">http//www.globus.org/</a>.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>fapl_id</code>
+ <dt><em>hid_t</em> <code>fapl_id</code>,
<dd>IN: File access property list identifier.
- <dt><em>hsize_t *</em><code>offset</code>
- <dd>IN: Offset in bytes within the HDF5 file.
+ <dt><em>GASS_Info</em> <code>info</code>
+ <dd>IN: Pointer to the GASS information structure.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful.
+ Otherwise returns a negative value.
<!--
<dt><strong>Non-C API(s):</strong>
<dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
@@ -5656,7 +5091,8 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_fapl_log" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-SetFaplLog">H5Pset_fapl_log</a>
@@ -5924,7 +5360,8 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_fapl_mpio" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-SetFaplMpio">H5Pset_fapl_mpio</a>
@@ -5983,50 +5420,8 @@ END LIBRARY-SET OPTION TAGS -->
</dl>
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-GetFaplMpio">H5Pget_fapl_mpio</a>
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_fapl_mpio</code>(
- <em>hid_t</em> <code>fapl_id</code>,
- <em>MPI_Comm *</em><code>comm</code>,
- <em>MPI_Info *</em><code>info</code>
- )
- <dt><strong>Purpose:</strong>
- <dd> Returns MPI communicator information.
- <dt><strong>Description:</strong>
- <dd>If the file access property list is set to the <code>H5FD_MPIO</code>
- driver, <code>H5Pget_fapl_mpio</code> returns the MPI communicator and
- information through the <code>comm</code> and <code>info</code>
- pointers, if those values are non-null.
- <p>
- Neither <code>comm</code> nor <code>info</code> is copied,
- so they are valid only until the file access property list
- is either modified or closed.
- <dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>fapl_id</code>
- <dd>IN: File access property list identifier.
- <dt><em>MPI_Comm *</em><code>comm</code>
- <dd>OUT: MPI-2 communicator.
- <dt><em>MPI_Info *</em><code>info</code>
- <dd>OUT: MPI-2 info object.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful.
- Otherwise returns a negative value.
- <dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_fapl_mpio_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pget_fapl_mpio" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-SetFaplMpiPosix">H5Pset_fapl_mpiposix</a>
@@ -6074,132 +5469,8 @@ END LIBRARY-SET OPTION TAGS -->
</dl>
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-GetFaplMpiPosix">H5Pget_fapl_mpiposix</a>
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_fapl_mpiposix</code>(
- <em>hid_t</em> <code>fapl_id</code>,
- <em>MPI_Comm *</em><code>comm</code>
- )
- <dt><strong>Purpose:</strong>
- <dd> Returns MPI communicator information.
- <dt><strong>Description:</strong>
- <dd>If the file access property list is set to the <code>H5FD_MPIO</code>
- driver, <code>H5Pget_fapl_mpiposix</code> returns
- the MPI communicator through the <code>comm</code>
- pointer, if those values are non-null.
- <p>
- <code>comm</code> is not copied, so it is valid only
- until the file access property list is either modified or closed.
- <dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>fapl_id</code>
- <dd>IN: File access property list identifier.
- <dt><em>MPI_Comm *</em><code>comm</code>
- <dd>OUT: MPI-2 communicator.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful.
- Otherwise returns a negative value.
-<!--
- <dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_fapl_mpiposix_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
---> <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-
-
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-SetDxplMpio">H5Pset_dxpl_mpio</a>
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_dxpl_mpio</code>(
- <em>hid_t</em> <code>dxpl_id</code>,
- <em>H5FD_mpio_xfer_t</em> <code>xfer_mode</code>
- )
- <dt><strong>Purpose:</strong>
- <dd>Sets data transfer mode.
- <dt><strong>Description:</strong>
- <dd><code>H5Pset_dxpl_mpio</code> sets the data transfer property list
- <code>dxpl_id</code> to use transfer mode <code>xfer_mode</code>.
- The property list can then be used to control the I/O transfer mode
- during data I/O operations.
- <p>
- Valid transfer modes are as follows:
- <dir>
- <dl>
- <dt><code>H5FD_MPIO_INDEPENDENT</code>
- <dd>Use independent I/O access (default).
- <dt><code>H5FD_MPIO_COLLECTIVE</code>
- <dd>Use collective I/O access.
- </dl>
- </dir>
- <dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>dxpl_id</code>
- <dd>IN: Data transfer property list identifier.
- <dt><em>H5FD_mpio_xfer_t</em> <code>xfer_mode</code>
- <dd>IN: Transfer mode.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful.
- Otherwise returns a negative value.
- <dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_dxpl_mpio_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-GetDxplMpio">H5Pget_dxpl_mpio</a>
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_dxpl_mpio</code>(
- <em>hid_t</em> <code>dxpl_id</code>,
- <em>H5FD_mpio_xfer_t *</em><code>xfer_mode</code>
- )
- <dt><strong>Purpose:</strong>
- <dd>Returns the data transfer mode.
- <dt><strong>Description:</strong>
- <dd><code>H5Pget_dxpl_mpio</code> queries the data transfer mode
- currently set in the data transfer property list <code>dxpl_id</code>.
- <p>
- Upon return, <code>xfer_mode</code> contains the data transfer mode,
- if it is non-null.
- <p>
- <code>H5Pget_dxpl_mpio</code> is not a collective function.
- <dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>dxpl_id</code>
- <dd>IN: Data transfer property list identifier.
- <dt><em>H5FD_mpio_xfer_t *</em><code>xfer_mode</code>
- <dd>OUT: Data transfer mode.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful.
- Otherwise returns a negative value.
- <dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_dxpl_mpio_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_fapl_multi" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-SetFaplMulti">H5Pset_fapl_multi</a>
@@ -6344,129 +5615,39 @@ END LIBRARY-SET OPTION TAGS -->
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_fapl_sec2" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetFaplMulti">H5Pget_fapl_multi</a>
+ <dt><strong>Name:</strong> <a name="Property-SetFaplSec2">H5Pset_fapl_sec2</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_fapl_multi</code>(
- <em>hid_t</em> <code>fapl_id</code>,
- <em>const H5FD_mem_t *</em><code>memb_map</code>,
- <em>const hid_t *</em><code>memb_fapl</code>,
- <em>const char **</em><code>memb_name</code>,
- <em>const haddr_t *</em><code>memb_addr</code>,
- <em>hbool_t *</em><code>relax</code>
+ <dd><em>herr_t</em> <code>H5Pset_fapl_sec2</code>(
+ <em>hid_t</em> <code>fapl_id</code>
)
<dt><strong>Purpose:</strong>
- <dd>Returns information about the multi-file access property list.
+ <dd>Sets the sec2 driver.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_fapl_multi</code> returns information about the
- multi-file access property list.
+ <dd><code>H5Pset_fapl_sec2</code> modifies the file access property list
+ to use the <code>H5FD_SEC2</code> driver.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>fapl_id</code>
<dd>IN: File access property list identifier.
- <dt><em>const H5FD_mem_t *</em><code>memb_map</code>
- <dd>OUT: Maps memory usage types to other memory usage types.
- <dt><em>const hid_t *</em><code>memb_fapl</code>
- <dd>OUT: Property list for each memory usage type.
- <dt><em>const char **</em><code>memb_name</code>
- <dd>OUT: Name generator for names of member files.
- <dt><em>const haddr_t *</em><code>memb_addr</code>
- <dd>OUT:
- <dt><em>hbool_t *</em><code>relax</code>
- <dd>OUT: Allows read-only access to incomplete file sets
- when <code>TRUE</code>.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful.
- Otherwise returns a negative value.
- <dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_fapl_multi_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-SetDxplMulti">H5Pset_dxpl_multi</a>
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_dxpl_multi</code>(
- <em>hid_t</em> <code>dxpl_id</code>,
- <em>const hid_t *</em><code>memb_dxpl</code>
- )
- <dt><strong>Purpose:</strong>
- <dd>Sets the data transfer property list for the multi-file driver.
- <dt><strong>Description:</strong>
- <dd><code>H5Pset_dxpl_multi</code> sets the data transfer property list
- <code>dxpl_id</code> to use the multi-file driver for each
- memory usage type <code>memb_dxpl[]</code>.
- <p>
- <code>H5Pset_dxpl_multi</code> can only be used after
- the member map has been set with <code>H5Pset_fapl_multi</code>.
- <dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>dxpl_id</code>,
- <dd>IN: Data transfer property list identifier.
- <dt><em>const hid_t *</em><code>memb_dxpl</code>
- <dd>IN: Array of data access property lists.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful.
- Otherwise returns a negative value.
- <!--
- <dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- -->
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-GetDxplMulti">H5Pget_dxpl_multi</a>
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_dxpl_multi</code>(
- <em>hid_t</em> <code>dxpl_id</code>,
- <em>const hid_t *</em><code>memb_dxpl</code>
- )
-<br>
-<br>
- <dt><strong>Purpose:</strong>
- <dd>Returns multi-file data transfer property list information.
- <dt><strong>Description:</strong>
- <dd><code>H5Pget_dxpl_multi</code> returns the data transfer property list
- information for the multi-file driver.
- <dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>dxpl_id</code>,
- <dd>IN: Data transfer property list identifier.
- <dt><em>const hid_t *</em><code>memb_dxpl</code>
- <dd>OUT: Array of data access property lists.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful.
Otherwise returns a negative value.
- <!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_fapl_sec2_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- -->
<!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_fapl_split" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-SetFaplSplit">H5Pset_fapl_split</a>
@@ -6560,175 +5741,55 @@ fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
-->
</dl>
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-SetMultiType">H5Pset_multi_type</a>
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_multi_type</code> (
- <em>hid_t</em> <code>fapl_id</code>,
- <em>H5FD_mem_t</em> <code>type</code>
- )
- <dt><strong>Purpose:</strong>
- <dd>Sets data type property for <code>MULTI</code> driver.
- <dt><strong>Description:</strong>
- <dd><code>H5Pset_multi_type</code> sets the data type property in the
- file access or data transfer property list <code>fapl_id</code>.
- This enables a user application to specifiy the type of data the
- appication wishes to access so that the application
- can retrieve a file handle for low-level access to the particular member
- of a set of <code>MULTI</code> files in which that type of data is stored.
- The file handle is retrieved with a separate call
- to <a href="RM_H5F.html#File-GetVfdHandle"><code>H5Fget_vfd_handle</code></a>
- (or, in special circumstances, to <code>H5FDget_vfd_handle</code>;
- see <cite>Virtual File Layer</cite> and <cite>List of VFL Functions</cite>
- in <a href="TechNotes.html"><cite>HDF5 Technical Notes</cite></a>).
- <p>
- The type of data specified in <code>type</code> may be one of the following:
- <table border=0>
- <tr valign=top align=left><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
- <code>H5FD_MEM_DEFAULT</code>&nbsp;&nbsp;
- </td><td>
- Need description....
- </td></tr>
- <tr valign=top align=left><td>&nbsp;</td><td>
- <code>H5FD_MEM_SUPER</code>
- </td><td>
- Super block ... need description....
- </td></tr>
- <tr valign=top align=left><td>&nbsp;</td><td>
- <code>H5FD_MEM_BTREE</code>
- </td><td>
- Btree ... need description....
- </td></tr>
- <tr valign=top align=left><td>&nbsp;</td><td>
- <code>H5FD_MEM_DRAW</code>
- </td><td>
- Need description....
- </td></tr>
- <tr valign=top align=left><td>&nbsp;</td><td>
- <code>H5FD_MEM_GHEAP</code>
- </td><td>
- Global heap ... need description....
- </td></tr>
- <tr valign=top align=left><td>&nbsp;</td><td>
- <code>H5FD_MEM_LHEAP</code>
- </td><td>
- Local Heap ... need description....
- </td></tr>
- <tr valign=top align=left><td>&nbsp;</td><td>
- <code>H5FD_MEM_OHDR</code>
- </td><td>
- Need description....
- </td></tr>
- </table>
- <p>
- Use of this function is only appropriate for an HDF5 file written
- as a set of files with the <code>MULTI</code> file driver.
- <dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>fapl_id</code>
- <dd>IN: File access property list or data transfer property list identifier.
- <dt><em>H5FD_mem_t</em> <code>type</code>
- <dd>OUT: Type of data.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
- <!--
- <dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- -->
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
-<hr>
-<dl>
- <dt><strong>Name:</strong> <a name="Property-GetMultiType">H5Pget_multi_type</a>
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_multi_type</code> (
- <em>hid_t</em> <code>fapl_id</code>,
- <em>H5FD_mem_t *</em><code>type</code>
- )
- <dt><strong>Purpose:</strong>
- <dd>Retrieves data type property for <code>MULTI</code> driver.
- <dt><strong>Description:</strong>
- <dd><code>H5Pget_multi_type</code> retrieves the data type setting from the
- file access or data transfer property list <code>fapl_id</code>.
- This enables a user application to specifiy the type of data the
- application wishes to access so that the application
- can retrieve a file handle for low-level access to the particular member
- of a set of <code>MULTI</code> files in which that type of data is stored.
- The file handle is retrieved with a separate call
- to <a href="RM_H5F.html#File-GetVfdHandle"><code>H5Fget_vfd_handle</code></a>
- (or, in special circumstances, to <code>H5FDget_vfd_handle</code>;
- see <cite>Virtual File Layer</cite> and <cite>List of VFL Functions</cite>
- in <a href="TechNotes.html"><cite>HDF5 Technical Notes</cite></a>).
- <p>
- The type of data returned in <code>type</code> will be one of those
- listed in the discussion of the <code>type</code> parameter in the the
- description of the function
- <a href="#Property-SetMultiType"><code>H5Pset_multi_type</code></a>.
- <p>
- Use of this function is only appropriate for an HDF5 file written
- as a set of files with the <code>MULTI</code> file driver.
- <dt><strong>Parameters:</strong>
- <dl>
- <dt><em>hid_t</em> <code>fapl_id</code>
- <dd>IN: File access property list or data transfer property list identifier.
- <dt><em>H5FD_mem_t *</em><code>type</code>
- <dd>OUT: Type of data.
- </dl>
- <dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful;
- otherwise returns a negative value.
- <!--
- <dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
- target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- -->
- <!--
- <img src="Graphics/Java.gif">
- <img src="Graphics/C++.gif">
- -->
-</dl>
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_fapl_srb" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetFaplSec2">H5Pset_fapl_sec2</a>
+ <dt><strong>Name:</strong> <a name="Property-SetFaplSrb">H5Pset_fapl_srb</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_fapl_sec2</code>(
- <em>hid_t</em> <code>fapl_id</code>
+ <dd><em>herr_t</em> <code>H5Pset_fapl_srb</code>(
+ <em>hid_t</em> <code>fapl_id</code>,
+ <em>SRB_Info</em> <code>info</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets the sec2 driver.
+ <dd>Saves SRB connection handler and sets SRB settings.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_fapl_sec2</code> modifies the file access property list
- to use the <code>H5FD_SEC2</code> driver.
+ <dd><code>H5Pset_fapl_srb</code> stores the SRB client-to-server
+ connection handler <code>SRB_CONN</code> after the connection
+ is established and other user-supplied SRB information.
+ <p>
+ The user-supplied SRB information is contained in the
+ <em>SRB_Info</em> struct pointed to by <code>info</code>
+ and is stored in the file access property list <code>fapl_id</code>.
+ This information can then be used to create or open a file.
+ <dt><strong>Note:</strong>
+ <dd><code>H5Pset_fapl_gass</code> is an experimental function.
+ It is designed for use only when accessing files via the
+ Storage Resource Broker (SRB). For further information, see
+ <a href="http://www.npaci.edu/Research/DI/srb/">http//www.npaci.edu/Research/DI/srb/</a>.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>fapl_id</code>
<dd>IN: File access property list identifier.
+ <dt><em>SRB_Info</em> <code>info</code>
+ <dd>IN: Pointer to the SRB information structure.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful.
Otherwise returns a negative value.
+ <!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_fapl_sec2_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ -->
<!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_fapl_stdio" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-SetFaplStdio">H5Pset_fapl_stdio</a>
@@ -6758,7 +5819,8 @@ fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_fapl_stream" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Property-SetFaplStream">H5Pset_fapl_stream</a>
@@ -6839,136 +5901,328 @@ fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_fclose_degree" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-SetFcloseDegree">H5Pset_fclose_degree</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Pset_fclose_degree</code>(<em>hid_t</em> <code>fapl_id</code>,
+ <em>H5F_close_degree_t</em> <code>fc_degree</code>)
+ <dt><strong>Purpose:</strong>
+ <dd>Sets the file close degree.
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pset_fclose_degree</code> sets the file close degree property <code>fc_degree</code>
+ in the file access property list <code>fapl_id</code>. 
+ <p> The value of <code>fc_degree</code> determines how aggressively <code>H5Fclose</code>
+ deals with objects within a file that remain open when <code>H5Fclose</code>
+ is called to close that file.  <code>fc_degree</code> can have any one of
+ four valid values:
+ <div align="center">
+ <table width="75%" border="1" cellpadding="3">
+ <tr>
+ <th valign="top">Degree name</th>
+ <th valign="top"><code>H5Fclose</code> behavior with no open object
+ in file</th>
+ <th valign="top"><code>H5Fclose</code> behavior with open object(s)
+ in file</th>
+ </tr>
+ <tr>
+ <td valign="top"><code>H5F_CLOSE_WEAK</code></td>
+ <td valign="top">Actual file is closed.</td>
+ <td valign="top">Access to file identifier is terminated; actual file
+ close is delayed until all objects in file are closed</td>
+ </tr>
+ <tr>
+ <td valign="top"><code>H5F_CLOSE_SEMI</code></td>
+ <td valign="top">Actual file is closed.</td>
+ <td valign="top">Function returns FAILURE</td>
+ </tr>
+ <tr>
+ <td valign="top"><code>H5F_CLOSE_STRONG</code></td>
+ <td valign="top">Actual file is closed.</td>
+ <td valign="top">All open objects ramaining in the file are closed then
+ file is closed</td>
+ </tr>
+ <tr>
+ <td valign="top"><code>H5F_CLOSE_DEFAULT</code></td>
+ <td colspan="2" valign="top">The VFL driver chooses the behavior.  Currently,
+ all VFL drivers set this value to <code>H5F_CLOSE_WEAK</code>, except
+ for the MPI-I/O driver, which sets it to <code>H5F_CLOSE_SEMI</code>.
+ </td>
+ </tr>
+ </table>
+ </div>
+ <dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>fapl_id</code>
+ <dd>IN: File access property list identifier.
+ <dt><em>H5F_close_degree_t</em> <code>fc_degree</code>
+ <dd>IN: Pointer to a location containing the file close degree property,
+ the value of <code>fc_degree</code>.
+ </dl>
+ <dt><strong>Returns:</strong>
+ <dd>Returns a non-negative value if successful. Otherwise returns a negative
+ value.
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_fclose_degree_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_fill_time" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetFaplStream">H5Pget_fapl_stream</a>
+ <dt><strong>Name:</strong> <a name="Property-SetFillTime">H5Pset_fill_time</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_fapl_stream</code>(
- <em>hid_t</em> <code>fapl_id</code>,
- <em>H5FD_stream_fapl_t *</em><code>fapl</code>
- )
+ <dd><em>herr_t </em><code>H5Pset_fill_time</code>(<em>hid_t</em> <code>plist_id</code>,
+ <em>H5D_fill_time_t</em> <code>fill_time</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Returns the streaming I/O driver settings.
+ <dd>Sets the time when fill values are written to a dataset.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_fapl_stream</code> returns the file access properties
- set for the use of the streaming I/O driver.
+ <dd><code>H5Pset_fill_time</code> sets up the timing for writing fill values
+ to a dataset.
+ This property is set in the dataset creation property list <code>plist_id</code>.
<p>
- <code>H5Pset_fapl_stream</code> and <code>H5Pget_fapl_stream</code>
- are not intended for use in a parallel environment.
+ Timing is specified in <code>fill_time</code> with one of the following values:
+ <table border=0 >
+ <tr valign="top"><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ <code>H5D_FILL_TIME_IFSET</code>&nbsp;&nbsp;
+ </td><td>
+ Write fill values to the dataset when storage space is allocated
+ only if there is a user-defined fill value, i.e., one set with
+ <a href="#Property-SetFillValue">H5Pset_fill_value</a>.
+ &nbsp;&nbsp;(Default)
+ </td></tr><tr valign="top"><td>&nbsp;</td><td>
+ <code>H5D_FILL_TIME_ALLOC</code>
+ </td><td>
+ Write fill values to the dataset when storage space is allocated.
+ </td></tr><tr valign="top"><td>&nbsp;</td><td>
+ <code>H5D_FILL_TIME_NEVER</code>
+ </td><td>
+ Never write fill values to the dataset.
+ </td></tr></table>
+ <dt><strong>Note:</strong>
+ <dd><code>H5Pset_fill_time</code> is designed for coordination
+ with the dataset fill value and
+ dataset storage allocation time properties, set with the functions
+ <code>H5Pset_fill_value</code> and <code>H5Pset_alloc_time</code>.
+ <p>
+ See <a href="RM_H5D.html#Dataset-Create">H5Dcreate</a> for
+ further cross-references.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>fapl_id</code>
- <dd>IN: File access property list identifier.
- <dt><em>H5FD_stream_fapl_t *</em><code>fapl</code>
- <dd>OUT: The streaming I/O file access property list.
+ <dt><em>hid_t</em> <code>plist_id</code>
+ <dd>IN: Dataset creation property list identifier.
+ <dt><em>H5D_fill_time_t</em> <code>fill_time</code>
+ <dd>IN: When to write fill values to a dataset.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful.
- Otherwise returns a negative value.
- <!--
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_fill_time_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- -->
<!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
-<!-- ********** MOVED TO TechNotes/VFLfunc.html **********
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_fill_value" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetDriver">H5Pset_driver</a>
+ <dt><strong>Name:</strong> <a name="Property-SetFillValue">H5Pset_fill_value</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_driver</code>(
- <em>hid_t</em> <code>plist_id</code>,
- <em>hid_t</em> <code>driver_id</code>,
- <em>const void *</em> <code>driver_info</code>
+ <dd><em>herr_t</em> <code>H5Pset_fill_value</code>(<em>hid_t</em> <code>plist_id</code>,
+ <em>hid_t</em> <code>type_id</code>,
+ <em>const void *</em><code>value</code>
)
<dt><strong>Purpose:</strong>
- <dd>Sets the file driver.
+ <dd>Sets the fill value for a dataset.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_driver</code> sets the file driver,
- <code>driver_id</code>, for a file access or data transfer
- property list, <code>plist_id</code>, and supplies an
- optional struct containing the driver-specific properties,
- <code>driver_info</code>.
- <p>
- <font color=red><b><i>Need <code>driver_info</code> struct definition.</i></b></font>
+ <dd><code>H5Pset_fill_value</code> sets the fill value for
+ a dataset in the dataset creation property list.
<p>
- The driver properties will be copied into the property list
- and the reference count on the driver will be incremented,
- allowing the caller to close the driver identifier but still use
- the property list.
+ <code>value</code> is interpreted as being of datatype
+ <code>type_id</code>. This datatype may differ from that of
+ the dataset, but the HDF5 library must be able to convert
+ <code>value</code> to the dataset datatype when the dataset
+ is created.
+ <p>
+ The default fill value is <code>0</code> (zero), which is
+ interpreted according to the actual dataset datatype.
+ <p>
+ Setting <code>value</code> to <code>NULL</code> indicates
+ that the fill value is to be undefined.
+ <dt><strong>Notes:</strong>
+ <dd> Applications sometimes write data only to portions of
+ an allocated dataset. It is often useful in such cases
+ to fill the unused space with a known
+ <span class="termEmphasis">fill value</span>.
+ This function allows the user application to set that fill value;
+ the functions
+ <a href="RM_H5D.html#Dataset-Fill">H5Dfill</a> and
+ <a href="RM_H5P.html#Property-SetFillTime">H5Pset_fill_time</a>,
+ respectively, provide the ability
+ to apply the fill value on demand or
+ to set up its automatic application.
+ <p>
+ A fill value should be defined so that it is appropriate for
+ the application. While the HDF5 default fill value is
+ <code>0</code> (zero), it is often appropriate to use another value.
+ It might be useful, for example, to use a value that is
+ known to be impossible for the application to legitimately generate.
+ <p>
+ <code>H5Pset_fill_value</code> is designed to work in
+ concert with <code>H5Pset_alloc_time</code> and
+ <code>H5Pset_fill_time</code>.
+ <code>H5Pset_alloc_time</code> and <code>H5Pset_fill_time</code>
+ govern the timing of dataset storage allocation and fill value
+ write operations and can be important in tuning application
+ performance.
+ <p>
+ See <a href="RM_H5D.html#Dataset-Create">H5Dcreate</a> for
+ further cross-references.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>plist_id</code>
- <dd>IN: File access or data transfer property list identifier.
- <dt><em>hid_t</em> <code>driver_id</code>
- <dd>IN: Driver identifier.
- <dt><em>const void *</em> <code>driver_info</code>
- <dd>IN: Optional struct containing driver properties.
+ <dd>IN: Dataset creation property list identifier.
+ <dt><em>hid_t</em> <code>type_id</code>,
+ <dd>IN: Datatype of <code>value</code>.
+ <dt><em>const void *</em><code>value</code>
+ <dd>IN: Pointer to buffer containing value to use as fill value.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful.
- Otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_fill_value_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
+ -->
</dl>
--->
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_filter" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetDriver">H5Pget_driver</a>
+ <dt><strong>Name:</strong> <a name="Property-SetFilter">H5Pset_filter</a>
<dt><strong>Signature:</strong>
- <dd><em>hid_t</em> <code>H5Pget_driver</code>(
- <em>hid_t</em> <code>plist_id</code>
+ <dd><em>herr_t</em> <code>H5Pset_filter</code>(<em>hid_t</em> <code>plist</code>,
+ <em>H5Z_filter_t</em> <code>filter</code>,
+ <em>unsigned int</em> <code>flags</code>,
+ <em>size_t</em> <code>cd_nelmts</code>,
+ <em>const unsigned int</em> <code>cd_values[]</code>
)
<dt><strong>Purpose:</strong>
- <dd>Returns low-lever driver identifier.
+ <dd>Adds a filter to the filter pipeline.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_driver</code> returns the identifier of the
- low-level file driver associated with the file access property list
- or data transfer property list <code>plist_id</code>.
+ <dd><code>H5Pset_filter</code> adds the specified
+ <code>filter</code> and corresponding properties to the
+ end of an output filter pipeline.
+ If <code>plist</code> is a dataset creation property list,
+ the filter is added to the permanent filter pipeline;
+ if <code>plist</code> is a dataset transfer property list,
+ the filter is added to the transient filter pipeline.
<p>
- Valid driver identifiers with the standard HDF5 library distribution
- include the following:
- <pre>
- H5FD_CORE
- H5FD_DPSS
- H5FD_FAMILY
- H5FD_GASS
- H5FD_LOG
- H5FD_MPIO
- H5FD_MULTI
- H5FD_SEC2
- H5FD_STDIO
- H5FD_STREAM </pre>
- If a user defines and registers custom drivers or
- if additional drivers are defined in an HDF5 distribution,
- this list will be longer.
+ The array <code>cd_values</code> contains
+ <code>cd_nelmts</code> integers which are auxiliary data
+ for the filter. The integer values will be stored in the
+ dataset object header as part of the filter information.
<p>
- The returned driver identifier is only valid as long as the
- file driver remains registered.
+ The <code>flags</code> argument is a bit vector with
+ the following fields specifying certain general properties
+ of the filter:
+ <center>
+ <table align=center width="75%">
+ <tr valign=top>
+ <td valign=top><code>H5Z_FLAG_OPTIONAL</code>&nbsp;&nbsp;</td>
+ <td valign=top>If this bit is set then the filter is
+ optional. If the filter fails (see below) during an
+ <code>H5Dwrite</code> operation then the filter is
+ just excluded from the pipeline for the chunk for which
+ it failed; the filter will not participate in the
+ pipeline during an <code>H5Dread</code> of the chunk.
+ This is commonly used for compression filters: if the
+ filter result would be larger than the input, then
+ the compression filter returns failure and the
+ uncompressed data is stored in the file. If this bit is
+ clear and a filter fails, then <code>H5Dwrite</code>
+ or <code>H5Dread</code> also fails.
+ <p>
+ This flag should not be set for the Fletcher32 checksum
+ filter as it will bypass the checksum filter without
+ reporting checksum errors to an application.</td>
+ </tr>
+ </table>
+ </center>
+ <p>
+ The <code>filter</code> parameter specifies the filter to be set.
+ Valid values are as follows:
+
+ <center>
+ <table width=75%>
+ <tr valign=top align=left><td>
+ <code>H5Z_FILTER_DEFLATE</code>
+ </td><td>
+ Data compression filter, employing the gzip algorithm
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>H5Z_FILTER_SHUFFLE</code>
+ </td><td>
+ Data shuffling filter
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>H5Z_FILTER_FLETCHER32&nbsp;&nbsp;</code>
+ </td><td>
+ Error detection filter, employing the Fletcher32 checksum algorithm
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>H5Z_FILTER_SZIP</code>
+ </td><td>
+ Data compression filter, employing the SZIP algorithm
+ </td></tr>
+ </table>
+ </center>
+ <p>
+ Also see <a href="#Property-SetEdcCheck">H5Pset_edc_check</a> and
+ <a href="Property-SetFilterCallback">H5Pset_filter_callback</a>.
+
+ <dt><strong>Notes:</strong>
+ <dd>This function currently supports only the permanent filter
+ pipeline; <code>plist</code> must be a dataset creation
+ property list.
+ <p>
+ If multiple filters are set for a property list, they will be
+ applied to each chunk in the order in which they were set.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist_id</code>
- <dd>IN: File access or data transfer property list identifier.
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Property list identifier.
+ <dt><em>H5Z_filter_t</em> <code>filter</code>
+ <dd>IN: Filter to be added to the pipeline.
+ <dt><em>unsigned int</em> <code>flags</code>
+ <dd>IN: Bit vector specifying certain general properties
+ of the filter.
+ <dt><em>size_t</em> <code>cd_nelmts</code>
+ <dd>IN: Number of elements in <code>cd_values</code>.
+ <dt><em>const unsigned int</em> <code>cd_values[]</code>
+ <dd>IN: Auxiliary data for the filter.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a valid low-level driver identifier if successful.
- Otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_driver_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_filter_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -6976,186 +6230,485 @@ fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_filter_callback" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-SetFilterCallback">H5Pset_filter_callback</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Pset_filter_callback</code>(<em>hid_t</em> <code>plist</code>,
+ <em>H5Z_filter_func_t</em> <code>func</code>,
+ <em>void *</em><code>op_data</code>)
+ <dt><strong>Purpose:</strong>
+ <dd>Sets user-defined filter callback function.
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pset_filter_callback</code> sets the user-defined
+ filter callback function <code>func</code> in the
+ dataset transfer property list <code>plist</code>.
+ <p>
+ The parameter <code>op_data</code> is a pointer to user-defined
+ input data for the callback function and will be passed through
+ to the callback function.
+ <p>
+ The callback function <code>func</code> defines the actions
+ an application is to take when a filter fails.
+ The function prototype is as follows:
+ <dir>
+ <code>typedef</code> <em>H5Z_cb_return_t</em> (<code>H5Z_filter_func_t</code>)
+ (<em>H5Z_filter_t</em> <code>filter</code>,
+ <em>void *</em><code>buf</code>,
+ <em>size_t</em> <code>buf_size</code>,
+ <em>void *</em><code>op_data</code>)
+ </dir>
+ <p>
+ where <code>filter</code> indicates which filter has failed,
+ <code>buf</code> and <code>buf_size</code> are used to pass in
+ the failed data,
+ and <code>op_data</code> is the required input data for this
+ callback function.
+ <p>
+ Valid callback function return values are
+ <code>H5Z_CB_FAIL</code> and <code>H5Z_CB_CONT</code>.  
+ <dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Dataset transfer property list identifier.
+ <dt><em>H5Z_filter_func_t</em> <code>func</code>
+ <dd>IN: User-defined filter callback function.
+ <dt><em>void *</em><code>op_data</code>
+ <dd>IN: User-defined input data for the callback function.
+ </dl>
+ <dt><strong>Returns:</strong>
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
+<!--
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_filter_callback_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ --> <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
-<!-- ********** MOVED TO TechNotes/VFLfunc.html **********
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_fletcher32" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-SetFletcher32">H5Pset_fletcher32</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Pset_fletcher32</code>(<em>hid_t</em> <code>plist</code>)
+ <dt><strong>Purpose:</strong>
+ <dd>Sets up use of the Fletcher32 checksum filter.
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pset_fletcher32</code> sets the Fletcher32 checksum filter
+ in the dataset creation property list <code>plist</code>.  
+ <dt><strong>Note:</strong>
+ <dd>The initial error detection implementation supports
+ error detection for chunked datasets only.
+ <dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Dataset creation property list identifier.
+ </dl>
+ <dt><strong>Returns:</strong>
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_fletcher32_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_gc_references" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetDriverInfo">H5Pget_driver_info</a>
+ <dt><strong>Name:</strong> <a name="Property-SetGCReferences">H5Pset_gc_references</a>
<dt><strong>Signature:</strong>
- <dd><em>void *</em><code>H5Pget_driver_info</code>(
- <em>hid_t</em> <code>plist_id</code>
+ <dd><em>herr_t</em> <code>H5Pset_gc_reference</code>(<em>hid_t</em> <code>plist</code>,
+ <em>unsigned</em> <code>gc_ref</code>
)
<dt><strong>Purpose:</strong>
- <dd>Returns a pointer to file driver information.
+ <dd>Sets garbage collecting references flag.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_driver_info</code> returns a pointer to
- file driver-specific information for the low-level driver
- associated with the file access or data transfer property list
- <code>plist_id</code>.
-
+ <dd><code>H5Pset_gc_references</code> sets the flag for
+ garbage collecting references for the file.
<p>
- <font color=red><b><i>Need more on "a pointer" or on what
- is "pointed to." Might this be the <code>driver_info</code>
- struct definition in <code>H5Pset_driver</code>?</i></b></font>
-
+ Dataset region references and other reference types use space
+ in an HDF5 file's global heap. If garbage collection is on
+ and the user passes in an uninitialized value in a reference structure,
+ the heap might get corrupted. When garbage collection is off, however,
+ and the user re-uses a reference, the previous heap block will be
+ orphaned and not returned to the free heap space.
<p>
- If no driver-specific properties have been registered,
- <code>H5Pget_driver_info</code> returns <code>NULL</code>.
+ When garbage collection is on, the user must initialize the
+ reference structures to 0 or risk heap corruption.
+ <p>
+ The default value for garbage collecting references is off.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>plist_id</code>
- <dd>IN: File access or data transfer property list identifier.
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: File access property list identifier.
+ <dt><em>unsigned</em> <code>gc_ref</code>
+ <dd>IN: Flag setting reference garbage collection to
+ on (<code>1</code>) or off (<code>0</code>).
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a pointer to the struct containing
- low-level driver information.
- Otherwise returns <code>NULL</code>.
- <p>
- <code>NULL</code> is also returned if no driver-specific properties
- have been registered.
- No error is pushed on the stack in this case.
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_gc_references_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
+ -->
</dl>
--->
-
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_hyper_cache" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetFaplGass">H5Pset_fapl_gass</a>
+ <dt><strong>Name:</strong> <a name="Property-SetHyperCache">H5Pset_hyper_cache</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_fapl_gass</code>(
- <em>hid_t</em> <code>fapl_id</code>,
- <em>GASS_Info</em> <code>info</code>
+ <dd><em>herr_t</em> <code>H5Pset_hyper_cache</code>(<em>hid_t</em> <code>plist</code>,
+ <em>unsigned</em> <code>cache</code>,
+ <em>unsigned</em> <code>limit</code>
)
<dt><strong>Purpose:</strong>
- <dd>Stores user-supplied GASS information.
+ <dd>Indicates whether to cache hyperslab blocks during I/O.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_fapl_gass</code> stores user-supplied GASS information,
- the <em>GASS_Info</em> struct data as passed in <code>info</code>,
- to the file access property list <code>fapl_id</code>.
- <code>fapl_id</code> can then be used to create and/or open the file.
+ <dd>[<strong>NOTE:</strong>
+ <span class="1_4_compat">
+ This function is deprecated in HDF5 Release 1.6
+ and will eventually be removed from the HDF5 distribution.
+ It is provided in this release only to enable backward compatibility
+ with HDF5 Releases 1.4.<i>x</i>
+ and is enabled only if the HDF5 library is configured
+ with the flag <code>H5_WANT_H5_V1_4_COMPAT</code>;
+ the function is not enabled in the binaries distributed by NCSA.
+ </span>]
<p>
- The <em>GASS_Info</em> object, <code>info</code>, is used for
- file open operations when using GASS in the Globus environment.
+ Given a dataset transfer property list, <code>H5Pset_hyper_cache</code>
+ indicates whether to cache hyperslab blocks during I/O,
+ a process which can significantly increase I/O speeds.
<p>
- Any modification to <code>info</code> after this function call
- returns may have undetermined effect to the access property list.
- Users must call <code>H5Pset_fapl_gass</code> again to setup
- the property list.
- <dt><strong>Note:</strong>
- <dd><code>H5Pset_fapl_gass</code> is an experimental function.
- It is designed for use only when accessing files via the
- GASS facility of the Globus environment.
- For further information, see
- <a href="http://www.globus.org/">http//www.globus.org/</a>.
+ When working with hyperslab selections, it is possible to
+ significantly speed up I/O operations by retrieving an
+ entire hyperslab from the file in one operation and
+ caching it in memory.
+ The <code>cache</code> parameter specifies whether to turn
+ caching on for hyperslab I/O operations.
+ If <code>cache</code> is set to <code>1</code>,
+ caching is turned on;
+ if set to <code>0</code>, caching is turned off.
+ <p>
+ The parameter <code>limit</code> sets the maximum size of the
+ hyperslab block to cache. If a block is smaller than that limit,
+ it may still not be cached if no memory is available.
+ Setting <code>limit</code> to <code>0</code> (zero) indicates
+ no limitation on the size of block to attempt to cache.
+ <p>
+ The default is to cache blocks with no limit on block size
+ for serial I/O and to not cache blocks for parallel I/O.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>fapl_id</code>,
- <dd>IN: File access property list identifier.
- <dt><em>GASS_Info</em> <code>info</code>
- <dd>IN: Pointer to the GASS information structure.
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Dataset transfer property list identifier.
+ <dt><em>unsigned</em> <code>cache</code>
+ <dd>IN: A flag indicating whether caching is to be
+ set to on (<code>1</code>) or off (<code>0</code>).
+ <dt><em>unsigned</em> <code>limit</code>
+ <dd>IN: Maximum size of the hyperslab block to cache.
+ <code>0</code> (zero) indicates no limit.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful.
- Otherwise returns a negative value.
- <!--
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_hyper_cache_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- -->
<!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_hyper_vector_size" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetFaplGass">H5Pget_fapl_gass</a>
+ <dt><strong>Name:</strong> <a name="Property-SetHyperVectorSize">H5Pset_hyper_vector_size</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_fapl_gass</code>(
- <em>hid_t</em> <code>fapl_id</code>,
- <em>GASS_Info *</em><code>info</code>
+ <dd><em>herr_t</em> <code>H5Pset_hyper_vector_size</code>(<em>hid_t</em> <code>dxpl_id</code>,
+ <em>size_t</em> <code>vector_size</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves GASS information.
+ <dd>Sets number of I/O vectors to be read/written in hyperslab I/O.
<dt><strong>Description:</strong>
- <dd>If the file access property list <code>fapl_id</code> is set
- for use of the <code>H5FD_GASS</code> driver,
- <code>H5Pget_fapl_gass</code> returns the <em>GASS_Info</em>
- object through the <code>info</code> pointer.
+ <dd><code>H5Pset_hyper_vector_size</code> sets the number of
+ I/O vectors to be accumulated in memory before being issued
+ to the lower levels of the HDF5 library for reading or writing the
+ actual data.
<p>
- The <em>GASS_Info</em> information is copied, so it is valid
- only until the file access property list is modified or closed.
- <dt><strong>Note:</strong>
- <dd><code>H5Pget_fapl_gass</code> is an experimental function.
- It is designed for use only when accessing files via the
- GASS facility of the Globus environment.
- For further information, see
- <a href="http://www.globus.org/">http//www.globus.org/</a>.
+ The <em>I/O vectors</em> are hyperslab offset and length pairs
+ and are generated during hyperslab I/O.
+ <p>
+ The number of I/O vectors is passed in <code>vector_size</code>
+ to be set in the dataset transfer property list <code>dxpl_id</code>.
+ <code>vector_size</code> must be greater than <code>1</code> (one).
+ <p>
+ <code>H5Pset_hyper_vector_size</code> is an I/O optimization function;
+ increasing <code>vector_size</code> should provide better performance,
+ but the library will use more memory during hyperslab I/O.
+ The default value of <code>vector_size</code> is <code>1024</code>.
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>fapl_id</code>,
- <dd>IN: File access property list identifier.
- <dt><em>GASS_Info *</em><code>info</code>
- <dd>OUT: Pointer to the GASS information structure.
+ <dt><em>hid_t</em> <code>dxpl_id</code>
+ <dd>IN: Dataset transfer property list identifier.
+ <dt><em>size_t</em> <code>vector_size</code>
+ <dd>IN: Number of I/O vectors to accumulate in memory for I/O operations.
+ Must be greater than <code>1</code> (one).
+ Default value: <code>1024</code>.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful.
- Otherwise returns a negative value.
- <!--
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_hyper_vector_size_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- -->
<!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_istore_k" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-SetIstoreK">H5Pset_istore_k</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t </em><code>H5Pset_istore_k</code>(<em>hid_t</em> <code>plist</code>,
+ <em>int</em> <code>ik</code>
+ )
+ <dt><strong>Purpose:</strong>
+ <dd>Sets the size of the parameter used to control the
+ B-trees for indexing chunked datasets.
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pset_istore_k</code> sets the size of the parameter
+ used to control the B-trees for indexing chunked datasets.
+ This function is only valid for file creation property lists.
+ <p>
+ <code>ik</code> is one half the rank of a tree that stores
+ chunked raw data. On average, such a tree will be 75% full,
+ or have an average rank of 1.5 times the value of
+ <code>ik</code>.
+ <dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Identifier of property list to query.
+ <dt><em>int</em> <code>ik</code>
+ <dd>IN: 1/2 rank of chunked storage B-tree.
+ </dl>
+ <dt><strong>Returns:</strong>
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_istore_k_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_layout" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetFaplSrb">H5Pset_fapl_srb</a>
+ <dt><strong>Name:</strong> <a name="Property-SetLayout">H5Pset_layout</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_fapl_srb</code>(
+ <dd><em>herr_t </em><code>H5Pset_layout</code>(<em>hid_t</em> <code>plist</code>,
+ <em>H5D_layout_t</em> <code>layout</code>
+ )
+ <dt><strong>Purpose:</strong>
+ <dd>Sets the type of storage used to store the raw data for a dataset.
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pset_layout</code> sets the type of storage used to store the
+ raw data for a dataset.
+ This function is only valid for dataset creation property lists.
+ <p>
+ Valid values for <code>layout</code> are:
+ <ul><dl>
+ <dt>H5D_COMPACT
+ <dd>Store raw data in the dataset object header in file.
+ This should only be used for very small amounts of raw
+ data.
+ The current limit is approximately 64K (HDF5 Release 1.6).
+ <dt>H5D_CONTIGUOUS
+ <dd>Store raw data separately from the object header in one
+ large chunk in the file.
+ <dt>H5D_CHUNKED
+ <dd>Store raw data separately from the object header as
+ chunks of data in separate locations in the file.
+ </dl></ul>
+ <p>
+ Note that a compact storage layout may affect writing data to
+ the dataset with parallel applications. See note in
+ <a href="RM_H5D.html#Dataset-Write">H5Dwrite</a>
+ documentation for details.
+ <dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Identifier of property list to query.
+ <dt><em>H5D_layout_t</em> <code>layout</code>
+ <dd>IN: Type of storage layout for raw data.
+ </dl>
+ <dt><strong>Returns:</strong>
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_layout_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_meta_block_size" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-SetMetaBlockSize">H5Pset_meta_block_size</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Pset_meta_block_size</code>(
<em>hid_t</em> <code>fapl_id</code>,
- <em>SRB_Info</em> <code>info</code>
+ <em>hsize_t</em> <code>size</code>
)
<dt><strong>Purpose:</strong>
- <dd>Saves SRB connection handler and sets SRB settings.
+ <dd>Sets the minimum metadata block size.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_fapl_srb</code> stores the SRB client-to-server
- connection handler <code>SRB_CONN</code> after the connection
- is established and other user-supplied SRB information.
+ <dd><code>H5Pset_meta_block_size</code> sets the
+ minimum size, in bytes, of metadata block allocations when
+ <code>H5FD_FEAT_AGGREGATE_METADATA</code> is set by a VFL driver.
<p>
- The user-supplied SRB information is contained in the
- <em>SRB_Info</em> struct pointed to by <code>info</code>
- and is stored in the file access property list <code>fapl_id</code>.
- This information can then be used to create or open a file.
- <dt><strong>Note:</strong>
- <dd><code>H5Pset_fapl_gass</code> is an experimental function.
- It is designed for use only when accessing files via the
- Storage Resource Broker (SRB). For further information, see
- <a href="http://www.npaci.edu/Research/DI/srb/">http//www.npaci.edu/Research/DI/srb/</a>.
+ Each <i>raw</i> metadata block is initially allocated to be of the
+ given size. Specific metadata objects (e.g., object headers,
+ local heaps, B-trees) are then sub-allocated from this block.
+ <p>
+ The default setting is 2048 bytes, meaning that the library
+ will attempt to aggregate metadata in at least 2K blocks in the file.
+ Setting the value to <code>0</code> (zero) with this function
+ will turn off metadata aggregation, even if the VFL driver attempts
+ to use the metadata aggregation strategy.
+ <p>
+ Metadata aggregation reduces the number of small data objects
+ in the file that would otherwise be required for metadata.
+ The aggregated block of metadata is usually written in a
+ single write action and always in a contiguous block,
+ potentially significantly improving library and application
+ performance.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>fapl_id</code>
<dd>IN: File access property list identifier.
- <dt><em>SRB_Info</em> <code>info</code>
- <dd>IN: Pointer to the SRB information structure.
+ <dt><em>hsize_t</em> <code>size</code>
+ <dd>IN: Minimum size, in bytes, of metadata block allocations.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful.
Otherwise returns a negative value.
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_meta_block_size_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_multi_type" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-SetMultiType">H5Pset_multi_type</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Pset_multi_type</code> (
+ <em>hid_t</em> <code>fapl_id</code>,
+ <em>H5FD_mem_t</em> <code>type</code>
+ )
+ <dt><strong>Purpose:</strong>
+ <dd>Sets data type property for <code>MULTI</code> driver.
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pset_multi_type</code> sets the data type property in the
+ file access or data transfer property list <code>fapl_id</code>.
+ This enables a user application to specifiy the type of data the
+ appication wishes to access so that the application
+ can retrieve a file handle for low-level access to the particular member
+ of a set of <code>MULTI</code> files in which that type of data is stored.
+ The file handle is retrieved with a separate call
+ to <a href="RM_H5F.html#File-GetVfdHandle"><code>H5Fget_vfd_handle</code></a>
+ (or, in special circumstances, to <code>H5FDget_vfd_handle</code>;
+ see <cite>Virtual File Layer</cite> and <cite>List of VFL Functions</cite>
+ in <a href="TechNotes.html"><cite>HDF5 Technical Notes</cite></a>).
+ <p>
+ The type of data specified in <code>type</code> may be one of the following:
+ <table border=0>
+ <tr valign=top align=left><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ <code>H5FD_MEM_DEFAULT</code>&nbsp;&nbsp;
+ </td><td>
+ Need description....
+ </td></tr>
+ <tr valign=top align=left><td>&nbsp;</td><td>
+ <code>H5FD_MEM_SUPER</code>
+ </td><td>
+ Super block ... need description....
+ </td></tr>
+ <tr valign=top align=left><td>&nbsp;</td><td>
+ <code>H5FD_MEM_BTREE</code>
+ </td><td>
+ Btree ... need description....
+ </td></tr>
+ <tr valign=top align=left><td>&nbsp;</td><td>
+ <code>H5FD_MEM_DRAW</code>
+ </td><td>
+ Need description....
+ </td></tr>
+ <tr valign=top align=left><td>&nbsp;</td><td>
+ <code>H5FD_MEM_GHEAP</code>
+ </td><td>
+ Global heap ... need description....
+ </td></tr>
+ <tr valign=top align=left><td>&nbsp;</td><td>
+ <code>H5FD_MEM_LHEAP</code>
+ </td><td>
+ Local Heap ... need description....
+ </td></tr>
+ <tr valign=top align=left><td>&nbsp;</td><td>
+ <code>H5FD_MEM_OHDR</code>
+ </td><td>
+ Need description....
+ </td></tr>
+ </table>
+ <p>
+ Use of this function is only appropriate for an HDF5 file written
+ as a set of files with the <code>MULTI</code> file driver.
+ <dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>fapl_id</code>
+ <dd>IN: File access property list or data transfer property list identifier.
+ <dt><em>H5FD_mem_t</em> <code>type</code>
+ <dd>OUT: Type of data.
+ </dl>
+ <dt><strong>Returns:</strong>
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
<!--
<dt><strong>Non-C API(s):</strong>
<dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
@@ -7167,101 +6720,232 @@ fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_preserve" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-SetPreserve">H5Pset_preserve</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Pset_preserve</code>(<em>hid_t</em> <code>plist</code>,
+ <em>hbool_t</em> <code>status</code>
+ )
+ <dt><strong>Purpose:</strong>
+ <dd>Sets the dataset transfer property list status to TRUE or FALSE.
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pset_preserve</code> sets the
+ dataset transfer property list status to TRUE or FALSE.
+ <p>
+ When reading or writing compound data types and the
+ destination is partially initialized and the read/write is
+ intended to initialize the other members, one must set this
+ property to TRUE. Otherwise the I/O pipeline treats the
+ destination datapoints as completely uninitialized.
+ <dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Identifier for the dataset transfer property list.
+ <dt><em>hbool_t</em> <code>status</code>
+ <dd>IN: Status of for the dataset transfer property list
+ (TRUE/FALSE).
+ </dl>
+ <dt><strong>Returns:</strong>
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_preserve_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_shuffle" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-SetShuffle">H5Pset_shuffle</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Pset_shuffle</code>(<em>hid_t</em> <code>plist_id</code>)
+ <dt><strong>Purpose:</strong>
+ <dd>Sets up use of the shuffle filter.
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pset_shuffle</code> sets the shuffle filter,
+ <code>H5Z_FILTER_SHUFFLE</code>,
+ in the dataset creation property list <code>plist_id</code>.  
+ <p>
+ The shuffle filter <span class=termEmphasis>de-interlaces</span>
+ a block of data by reordering the bytes.
+ All the bytes from one consistent byte position of
+ each data element are placed together in one block;
+ all bytes from a second consistent byte position of
+ each data element are placed together a second block; etc.
+ For example, given three data elements of a 4-byte datatype
+ stored as <code>012301230123</code>,
+ shuffling will re-order data as <code>000111222333</code>.
+ This can be a valuable step in an effective compression
+ algorithm because the bytes in each byte position are often
+ closely related to each other and putting them together
+ can increase the compression ratio.
+ <p>
+ This filter is designed to be used in combination with
+ a compression filter.
+ <dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>plist_id</code>
+ <dd>IN: Dataset creation property list identifier.
+ </dl>
+ <dt><strong>Returns:</strong>
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_shuffle_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
-
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_sieve_buf_size" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetFaplSrb">H5Pget_fapl_srb</a>
+ <dt><strong>Name:</strong> <a name="Property-SetSieveBufSize">H5Pset_sieve_buf_size</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_fapl_srb</code>(
+ <dd><em>herr_t</em> <code>H5Pset_sieve_buf_size</code>(
<em>hid_t</em> <code>fapl_id</code>,
- <em>SRB_Info *</em><code>info</code>
+ <em>hsize_t</em> <code>size</code>
)
<dt><strong>Purpose:</strong>
- <dd>Retrieves SRB information.
+ <dd>Sets the maximum size of the data sieve buffer.
<dt><strong>Description:</strong>
- <dd>If the file access property list <code>fapl_id</code> is set
- for use of the <code>H5FD_SRB</code> driver,
- <code>H5Pget_fapl_srb</code> returns the <em>SRB_Info</em>
- object through the <code>info</code> pointer.
+ <dd><code>H5Pset_sieve_buf_size</code> sets <code>size</code>,
+ the maximum size in bytes of the data sieve buffer, which is
+ used by file drivers that are capable of using data sieving.
<p>
- The <em>SRB_Info</em> information is copied, so it is valid
- only until the file access property list is modified or closed.
- <dt><strong>Note:</strong>
- <dd><code>H5Pset_fapl_gass</code> is an experimental function.
- It is designed for use only when accessing files via the
- Storage Resource Broker (SRB). For further information, see
- <a href="http://www.npaci.edu/Research/DI/srb/">http//www.npaci.edu/Research/DI/srb/</a>.
+ The data sieve buffer is used when performing I/O on datasets
+ in the file. Using a buffer which is large enough to hold
+ several pieces of the dataset being read in for
+ hyperslab selections boosts performance by quite a bit.
+ <p>
+ The default value is set to 64KB, indicating that file I/O for
+ raw data reads and writes will occur in at least 64KB blocks.
+ Setting the value to 0 with this API function will turn off the
+ data sieving, even if the VFL driver attempts to use that strategy.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>fapl_id</code>
<dd>IN: File access property list identifier.
- <dt><em>SRB_Info *</em><code>info</code>
- <dd>OUT: Pointer to the SRB information structure.
+ <dt><em>hsize_t</em> <code>size</code>
+ <dd>IN: Maximum size, in bytes, of data sieve buffer.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful.
Otherwise returns a negative value.
- <!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_sieve_buf_size_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- -->
<!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_sizes" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-SetSizes">H5Pset_sizes</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t </em><code>H5Pset_sizes</code>(<em>hid_t</em> <code>plist</code>,
+ <em>size_t</em> <code>sizeof_addr</code>,
+ <em>size_t</em> <code>sizeof_size</code>
+ )
+ <dt><strong>Purpose:</strong>
+ <dd>Sets the byte size of the offsets and lengths used to address objects
+ in an HDF5 file.
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pset_sizes</code> sets the byte size of the offsets and lengths used to
+ address objects in an HDF5 file. This function is only valid for
+ file creation property lists. Passing in a value of 0 for one of
+ the <code>sizeof_...</code> parameters retains the current value.
+ The default value for both values is the same as
+ <code>sizeof(hsize_t)</code> in the library (normally 8 bytes).
+ Valid values currently are 2, 4, 8 and 16.
+ <dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Identifier of property list to modify.
+ <dt><em>size_t</em> <code>sizeof_addr</code>
+ <dd>IN: Size of an object offset in bytes.
+ <dt><em>size_t</em> <code>sizeof_size</code>
+ <dd>IN: Size of an object length in bytes.
+ </dl>
+ <dt><strong>Returns:</strong>
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_sizes_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_small_data_block_size" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetFaplCore">H5Pset_fapl_core</a>
+ <dt><strong>Name:</strong> <a name="Property-SetSmallData">H5Pset_small_data_block_size</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_fapl_core</code>(
- <em>hid_t</em> <code>fapl_id</code>,
- <em>size_t</em> <code>increment</code>,
- <em>hbool_t</em> <code>backing_store</code>
- )
+ <dd><em>herr_t</em> <code>H5Pset_small_data_block_size</code>(<em>hid_t</em> <code>fapl_id</code>,
+ <em>hsize_t</em> <code>size</code>
+ )
<dt><strong>Purpose:</strong>
- <dd>Modifies the file access property list to use the
- <code>H5FD_CORE</code> driver.
+ <dd>Sets the size of a contiguous block reserved for small data.
<dt><strong>Description:</strong>
- <dd><code>H5Pset_fapl_core</code> modifies the file access property list
- to use the <code>H5FD_CORE</code> driver.
+ <dd><code>H5Pset_small_data_block_size</code> reserves blocks of
+ <code>size</code> bytes for the contiguous storage of the raw data
+ portion of <em>small</em> datasets.
+ The HDF5 library then writes the raw data from small datasets
+ to this reserved space, thus reducing unnecessary discontinuities
+ within blocks of meta data and improving IO performance.
<p>
- The <code>H5FD_CORE</code> driver enables an application to work
- with a file in memory, speeding reads and writes as no disk access
- is made. File contents are stored only in memory until the file
- is closed. The <code>backing_store</code> parameter determines
- whether file contents are ever written to disk.
+ A small data block is actually allocated the first time a
+ qualifying small dataset is written to the file.
+ Space for the raw data portion of this small dataset is suballocated
+ within the small data block.
+ The raw data from each subsequent small dataset is also written to
+ the small data block until it is filled; additional small data blocks
+ are allocated as required.
<p>
- <code>increment</code> specifies the increment by which allocated
- memory is to be increased each time more memory is required.
+ The HDF5 library employs an algorithm that determines whether
+ IO performance is likely to benefit from the use of this mechanism
+ with each dataset as storage space is allocated in the file.
+ A larger <code>size</code> will result in this mechanism being
+ employed with larger datasets.
<p>
- If <code>backing_store</code> is set to <code>1</code>
- (<code>TRUE</code>), the file contents are flushed to a file
- with the same name as this core file when the file is closed
- or access to the file is terminated in memory.
- <dt><strong>Note:</strong>
- <dd>There is currently no means for reading a file from disk then
- using the <code>H5FD_CORE</code> driver to manipulate the file.
+ The small data block size is set as an allocation property in the
+ file access property list identified by <code>fapl_id</code>.
+ <p>
+ Setting <code>size</code> to zero (<code>0</code>) disables the
+ small data block mechanism.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>fapl_id</code>
- <dd>IN: File access property list identifier.
- <dt><em>size_t</em> <code>increment</code>
- <dd>IN: Size, in bytes, of memory increments.
- <dt><em>hbool_t</em> <code>backing_store</code>
- <dd>IN: Boolean flag indicating whether to write the file
- contents to disk when the file is closed.
+ <dd>IN: File access property list identifier .
+ <dt><em>hsize_t</em> <code>size</code>
+ <dd>IN: Maximum size, in bytes, of the small data block.
+ <br>
+ The default size is <code>2048</code>.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful.
- Otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful;
+ otherwise a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_fapl_core_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_small_data_block_size_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
@@ -7269,152 +6953,576 @@ fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_sym_k" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-SetSymK">H5Pset_sym_k</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t </em><code>H5Pset_sym_k</code>(<em>hid_t</em> <code>plist</code>,
+ <em>int</em> <code>ik</code>,
+ <em>int</em> <code>lk</code>
+ )
+ <dt><strong>Purpose:</strong>
+ <dd>Sets the size of parameters used to control the symbol table nodes.
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pset_sym_k</code> sets the size of parameters used to
+ control the symbol table nodes. This function is only valid
+ for file creation property lists. Passing in a value of 0 for
+ one of the parameters retains the current value.
+ <p>
+ <code>ik</code> is one half the rank of a tree that stores a symbol
+ table for a group. Internal nodes of the symbol table are on
+ average 75% full. That is, the average rank of the tree is
+ 1.5 times the value of <code>ik</code>.
+ <p>
+ <code>lk</code> is one half of the number of symbols that can
+ be stored in a symbol table node. A symbol table node is the
+ leaf of a symbol table tree which is used to store a group.
+ When symbols are inserted randomly into a group, the group's
+ symbol table nodes are 75% full on average. That is, they
+ contain 1.5 times the number of symbols specified by
+ <code>lk</code>.
+ <dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Identifier for property list to query.
+ <dt><em>int</em> <code>ik</code>
+ <dd>IN: Symbol table tree rank.
+ <dt><em>int</em> <code>lk</code>
+ <dd>IN: Symbol table node size.
+ </dl>
+ <dt><strong>Returns:</strong>
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_sym_k_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_szip" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetFaplCore">H5Pget_fapl_core</a>
+ <dt><strong>Name:</strong> <a name="Property-SetSzip">H5Pset_szip</a>
<dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_fapl_core</code>(
- <em>hid_t</em> <code>fapl_id</code>,
- <em>size_t</em> *<code>increment</code>,
- <em>hbool_t</em> *<code>backing_store</code>
- )
+ <dd><em>herr_t</em> <code>H5Pset_szip</code>(<em>hid_t</em> <code>plist</code>,
+ <em>unsigned int</em> <code>options_mask</code>,
+ <em>unsigned int</em> <code>pixels_per_block</code>)
<dt><strong>Purpose:</strong>
- <dd>Queries core file driver properties.
+ <dd>Sets up use of the SZIP compression filter.
<dt><strong>Description:</strong>
- <dd><code>H5Pget_fapl_core</code> queries the <code>H5FD_CORE</code>
- driver properties as set by <code>H5Pset_fapl_core</code>.
+ <dd><code>H5Pset_szip</code> sets a filter for the dataset
+ to SZIP compression, <code>H5Z_FILTER_SZIP</code>,
+ a compression method designed for use with scientific data.
+ <p>
+ SZIP options are passed in an options mask, <code>options_mask</code>,
+ as follows.
+ <center>
+ <table>
+ <tr valign=top align=left><td>
+ <hr>
+ <b>Option</b>
+ </td><td>
+ <hr>
+ <b>Description</b>
+ <br>
+ <font size=-1>(Paired options are mutually exclusive.)</font>
+ </td></tr>
+
+ <tr valign=top align=left><td>
+ <hr>
+ <code>H5_SZIP_CHIP_OPTION_MASK&nbsp;&nbsp;</code>
+ </td><td>
+ <hr>
+ Compresses exactly as in hardware.
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>H5_SZIP_ALLOW_K13_OPTION_MASK&nbsp;&nbsp;</code>
+ </td><td>
+ Allows k split = 13 compression mode. (Default)
+ </td></tr>
+
+ <tr valign=top align=left><td>
+ <hr>
+ <code>H5_SZIP_EC_OPTION_MASK</code>
+ </td><td>
+ <hr>
+ Selects entropy coding method. (Default)
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>H5_SZIP_NN_OPTION_MASK</code>
+ </td><td>
+ Selects nearest neighbor coding method.
+ </td></tr>
+
+<!-- THESE OPTIONS ARE SET DIRECTLY BY THE LIBRARY AND
+ ARE NOT AVAILABLE FOR USER CONTROL
+
+ <tr valign=top align=left><td>
+ <hr>
+ <code>LSB_OPTION_MASK</code>
+ </td><td>
+ <hr>
+ Data format is least significant byte first. (Default)
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>MSB_OPTION_MASK</code>
+ </td><td>
+ Data format is most significant byte first.
+ </td></tr>
+
+ <tr valign=top align=left><td>
+ <hr>
+ <code>RAW_OPTION_MASK</code>
+ </td><td>
+ <hr>
+ Do not output SZIP header.<br>
+ Not a default setting, but should always be set in HDF5.
+ </td></tr>
+
+END LIBRARY-SET OPTION TAGS -->
+
+ <tr valign=top align=left><td>
+ <hr>
+ </td><td>
+ <hr>
+ </td></tr>
+ </table>
+ </center>
+ Some typical usages are as follows:
+ <ul>
+ <li>One of the compression methods,
+ <code>H5_SZIP_EC_OPTION_MASK</code> or
+ <code>H5_SZIP_NN_OPTION_MASK</code>, is specified.
+ <li>The <code>H5_SZIP_ALLOW_K13_OPTION_MASK</code> is used.
+ </ul>
+ <p>
+ Options are combined to create the options mask by means of
+ a logical <code>OR</code> operation. For example, the
+ option mask can be set as follows:
+ <br><br><code>&nbsp;&nbsp;&nbsp;&nbsp;
+ options_mask = H5_SZIP_NN_OPTION_MASK | H5_SZIP_ALLOW_K13_OPTION_MASK;
+ </code>
+ <p>
+ SZIP compresses data block by block, with a user-tunable block size.
+ This block size is passed in the parameter
+ <code>pixels_per_block</code> and must be even,
+ with typical values being <code>8</code>, <code>10</code>,
+ <code>16</code>, and <code>32</code>.
+ The more pixel values vary, the smaller this number should be.
+ For optimal performance, the number of pixels per scan line
+ (i.e., the size of the fastest-changing dimension in the chunk)
+ should be an even multiple of the number of pixels per block.
+ <p>
+ <dt><strong>Notes:</strong>
+ <dd>SZIP works only with datasets with 1 through 24 bits/pixel,
+ 32 pits/pixel, or 64 bits/pixel.
+ <p>
+ SZIP typically requires that the user application also supply
+ the number of pixels in the object to be compressed,
+ the number of bits per pixel, and the number of pixels per scan line.
+ These values need not be independently supplied in the HDF5
+ environment as they are derived from the datatype and dataspace,
+ which are already known.
+ <p>
+ Also see
+ <a href="http://hdf.ncsa.uiuc.edu/HDF5/doc_resource/SZIP/index.html"
+ target="External">SZIP Compression in HDF5</a>
+ for further discussion of SZIP compression in HDF5,
+ for <em>important information regarding terms of use and
+ the SZIP copyright notice</em>,
+ and for a list of SZIP-related references.
+
<dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>fapl_id</code>
- <dd>IN: File access property list identifier.
- <dt><em>size_t</em> *<code>increment</code>
- <dd>OUT: Size, in bytes, of memory increments.
- <dt><em>hbool_t</em> *<code>backing_store</code>
- <dd>OUT: Boolean flag indicating whether to write the file
- contents to disk when the file is closed.
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Dataset creation or dataset transfer property list
+ identifier.
+ <dt><em>unsigned int</em> <code>options_mask</code>
+ <dd>IN: A bit-mask conveying the desired SZIP options.
+ <dt><em>unsigned int</em> <code>pixels_per_block</code>
+ <dd>IN: The number of pixels or data elements in each data block.
</dl>
<dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful.
- Otherwise returns a negative value.
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_fapl_core_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_szip_f"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
<!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
+
+<!--
+ <p>
+ <dt><strong>References:</strong>
+ (This material will appear in a separate file in the final release documents.)
+ <ul>
+ <li>J. Venbrux, P.S. Yeh, G. Zweigle, J. Vesel,
+ "A VLSI Chip Solution for Lossless Medical Imagery Compression,"
+ <cite>SPIE conference on Medical Imaging 1994</cite>.
+ Vol. 2164, pp. 561-572, February 13-14, 1994,
+ Newport Beach, California.
+
+ <li>J. Venbrux, J. Gambles, D. Wiseman, G. Zweigle, W.H. Miller, P.S. Yeh,
+ "A VLSI Chip Set Development for Lossless Data Compression,"
+ <cite>AIAA Computing in Aerospace 9 Conference</cite>.
+ October 1993, San Diego, California.
+
+ <li>J. Venbrux, G. Zweigle, J. Gambles, D.Wiseman, W. Miller, P. Yeh,
+ "An Adaptive, Lossless Data Compression Algorithm and VLSI
+ Implementations,"
+ <cite>NASA Symposium on VLSI Design</cite>.
+ Pp 1.2.1-1.2.16, November 1993.
+
+ <li>J. Venbrux, P.S. Yeh, and M. N. Liu,
+ "A VLSI Chip Set for High Speed Lossless Data Compression,"
+ <cite>IEEE Transactions on Circuits and Systems for Video
+ Technology</cite>.
+ Pp. 381-391, December 1992.
+
+ <li>CCSDS 120.0-G-1.
+ <cite>Lossless Data Compression</cite>.
+ Green Book. Issue 1, May 1997.
+ This Report presents a summary of the key operational concepts and
+ rationale underlying the requirements for the CCSDS Recommendation,
+ Lossless Data Compression. Supporting performance information along
+ with illustrations are also included. This Report also provides a
+ broad tutorial overview of the CCSDS Lossless Data Compression
+ algorithm and is aimed at helping first-time readers
+ to understand the Recommendation.
+ <br>
+ Appears In: CCSDS Publications TGannett 02/04/2003 387K Services
+ Check Out View
+
+ <li>CCSDS 121.0-B-1.
+ <cite>Lossless Data Compression</cite>.
+ Blue Book. Issue 1, May 1997.
+ This Recommendation defines a source-coding data-compression
+ algorithm and specifies how data compressed using the algorithm
+ are inserted into source packets for retrieval and decoding.
+ <br>
+ Appears In: CCSDS Publications
+
+ </ul>
+-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_userblock" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-SetUserblock">H5Pset_userblock</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t </em><code>H5Pset_userblock</code>(<em>hid_t</em> <code>plist</code>,
+ <em>hsize_t</em> <code>size</code>
+ )
+ <dt><strong>Purpose:</strong>
+ <dd>Sets user block size.
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pset_userblock</code> sets the user block size of a
+ file creation property list.
+ The default user block size is 0; it may be set to any
+ power of 2 equal to 512 or greater (512, 1024, 2048, etc.).
+ <dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Identifier of property list to modify.
+ <dt><em>hsize_t</em> <code>size</code>
+ <dd>IN: Size of the user-block in bytes.
+ </dl>
+ <dt><strong>Returns:</strong>
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pset_userblock_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Pset_vlen_mem_manager" -->
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-SetFcloseDegree">H5Pset_fclose_degree</a>
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pset_fclose_degree</code>(<em>hid_t</em> <code>fapl_id</code>,
- <em>H5F_close_degree_t</em> <code>fc_degree</code>)
- <dt><strong>Purpose:</strong>
- <dd>Sets the file close degree.
- <dt><strong>Description:</strong>
- <dd><code>H5Pset_fclose_degree</code> sets the file close degree property <code>fc_degree</code>
- in the file access property list <code>fapl_id</code>. 
- <p> The value of <code>fc_degree</code> determines how aggressively <code>H5Fclose</code>
- deals with objects within a file that remain open when <code>H5Fclose</code>
- is called to close that file.  <code>fc_degree</code> can have any one of
- four valid values:
- <div align="center">
- <table width="75%" border="1" cellpadding="3">
- <tr>
- <th valign="top">Degree name</th>
- <th valign="top"><code>H5Fclose</code> behavior with no open object
- in file</th>
- <th valign="top"><code>H5Fclose</code> behavior with open object(s)
- in file</th>
- </tr>
- <tr>
- <td valign="top"><code>H5F_CLOSE_WEAK</code></td>
- <td valign="top">Actual file is closed.</td>
- <td valign="top">Access to file identifier is terminated; actual file
- close is delayed until all objects in file are closed</td>
- </tr>
- <tr>
- <td valign="top"><code>H5F_CLOSE_SEMI</code></td>
- <td valign="top">Actual file is closed.</td>
- <td valign="top">Function returns FAILURE</td>
- </tr>
- <tr>
- <td valign="top"><code>H5F_CLOSE_STRONG</code></td>
- <td valign="top">Actual file is closed.</td>
- <td valign="top">All open objects ramaining in the file are closed then
- file is closed</td>
- </tr>
- <tr>
- <td valign="top"><code>H5F_CLOSE_DEFAULT</code></td>
- <td colspan="2" valign="top">The VFL driver chooses the behavior.  Currently,
- all VFL drivers set this value to <code>H5F_CLOSE_WEAK</code>, except
- for the MPI-I/O driver, which sets it to <code>H5F_CLOSE_SEMI</code>.
- </td>
- </tr>
- </table>
- </div>
- <dt><strong>Parameters:</strong>
+ <dt><strong>Name:</strong> <a name="Property-SetVLMemManager">H5Pset_vlen_mem_manager</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Pset_vlen_mem_manager</code>(<em>hid_t</em> <code>plist</code>,
+ <em>H5MM_allocate_t</em> <code>alloc</code>,
+ <em>void</em> *<code>alloc_info</code>,
+ <em>H5MM_free_t</em> <code>free</code>,
+ <em>void</em> *<code>free_info</code>
+ )
+ <dt><strong>Purpose:</strong>
+ <dd>Sets the memory manager for variable-length datatype allocation in
+ <code>H5Dread</code> and <code>H5Dvlen_reclaim</code>.
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pset_vlen_mem_manager</code> sets the memory manager for
+ variable-length datatype allocation in <code>H5Dread</code>
+ and free in <code>H5Dvlen_reclaim</code>.
+ <p>
+ The <code>alloc</code> and <code>free</code> parameters
+ identify the memory management routines to be used.
+ If the user has defined custom memory management routines,
+ <code>alloc</code> and/or <code>free</code> should be set to make
+ those routine calls (i.e., the name of the routine is used as
+ the value of the parameter);
+ if the user prefers to use the system's <code> malloc</code>
+ and/or <code>free</code>, the <code>alloc</code> and
+ <code>free</code> parameters, respectively, should be set to
+ <code> NULL</code>
+ <p>
+ The prototypes for these user-defined functions would appear as follows:
+ <br>&nbsp;&nbsp;&nbsp;&nbsp;
+ <em>typedef void</em> *(*<code>H5MM_allocate_t</code>)(<em>size_t</em> <code>size</code>,
+ <em>void</em> *<code>alloc_info</code>) ;
+
+ <br>&nbsp;&nbsp;&nbsp;&nbsp;
+ <em>typedef void</em> (*<code>H5MM_free_t</code>)(<em>void</em> *<code>mem</code>,
+ <em>void</em> *<code>free_info</code>) ;
+ <br>
+ The <code>alloc_info</code> and <code>free_info</code> parameters
+ can be used to pass along any required information to
+ the user's memory management routines.
+ <p>
+ In summary, if the user has defined custom memory management
+ routines, the name(s) of the routines are passed in the
+ <code>alloc</code> and <code>free</code> parameters and the
+ custom routines' parameters are passed in the
+ <code>alloc_info</code> and <code>free_info</code> parameters.
+ If the user wishes to use the system <code> malloc</code> and
+ <code>free</code> functions, the <code>alloc</code> and/or
+ <code>free</code> parameters are set to <code> NULL</code>
+ and the <code>alloc_info</code> and <code>free_info</code>
+ parameters are ignored.
+ <dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>fapl_id</code>
- <dd>IN: File access property list identifier.
- <dt><em>H5F_close_degree_t</em> <code>fc_degree</code>
- <dd>IN: Pointer to a location containing the file close degree property,
- the value of <code>fc_degree</code>.
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Identifier for the dataset transfer property list.
+ <dt><em>H5MM_allocate_t</em> <code>alloc</code>
+ <dd>IN: User's allocate routine, or &nbsp; <code> NULL</code>
+ for system &nbsp; <code> malloc</code>.
+ <dt><em>void</em> *<code>alloc_info</code>
+ <dd>IN: Extra parameter for user's allocation routine.
+ <br>
+ Contents are ignored if preceding parameter is &nbsp;
+ <code> NULL</code>.
+ <dt><em>H5MM_free_t</em> <code>free</code>
+ <dd>IN: User's free routine, or &nbsp; <code> NULL</code>
+ for system <code>free</code>.
+ <dt><em>void</em> *<code>free_info</code>
+ <dd>IN: Extra parameter for user's free routine.
+ <br>
+ Contents are ignored if preceding parameter is &nbsp;
+ <code> NULL</code>.
</dl>
- <dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful. Otherwise returns a negative
- value.
+ <dt><strong>Returns:</strong>
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
+ <!--
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pset_fclose_degree_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
+ --> <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Punregister" -->
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-Unregister">H5Punregister</a>
+
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Punregister</code>(
+ <em>H5P_class_t</em> <code>class</code>,
+ <em>const char *</em><code>name</code>
+ )
+
+ <dt><strong>Purpose:</strong>
+ <dd>Removes a property from a property list class.
+
+ <dt><strong>Description:</strong>
+ <dd><code>H5Punregister</code> removes a property from a
+ property list class.
+
+ <p>
+ Future property lists created of that class will not contain
+ this property;
+ existing property lists containing this property are not affected.
+
+ <dt><strong>Parameters:</strong>
+ <ul><table>
+ <tr>
+ <td><em>H5P_class_t</em> <code>class</code></td>
+ <td>IN: Property list class from which to remove
+ permanent property</td></tr>
+ <tr>
+ <td><em>const char *</em><code>name</code></td>
+ <td>IN: Name of property to remove</td></tr>
+ </table></ul>
+
+ <dt><strong>Returns:</strong>
+ <dd>Success: a non-negative value
+ <dd>Failure: a negative value
+
+ <dt><strong>Non-C APIs:</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5punregister_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+
+<!--
<hr>
<dl>
- <dt><strong>Name:</strong> <a name="Property-GetFcloseDegree">H5Pget_fclose_degree</a>
- <dt><strong>Signature:</strong>
- <dd><em>herr_t</em> <code>H5Pget_fclose_degree</code>(<em>hid_t</em> <code>fapl_id</code>,
- <em>H5F_close_degree_t</em> <code>fc_degree</code>)
- <dt><strong>Purpose:</strong>
- <dd>Returns the file close degree.
- <dt><strong>Description:</strong>
- <dd><code>H5Pget_fclose_degree</code> returns the current setting of the file
- close degree property <code>fc_degree</code> in the file access property list
- <code>fapl_id</code>. 
- <p> The value of <code>fc_degree</code> determines how aggressively <code>H5Fclose</code>
- deals with objects within a file that remain open when <code>H5Fclose</code>
- is called to close that file.  <code>fc_degree</code> can have any one of
- four valid values as described above in <a href="#Property-SetFcloseDegree"><code>H5Pset_fclose_degree</code></a>.
- <dt><strong>Parameters:</strong>
+ <dt><strong>Name:</strong> <a name="Property-SetCompression">H5Pset_compression</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Pset_compression</code>(<em>hid_t</em> <code>plist</code>,
+ <em>H5Z_method_t</em> <code>method</code>,
+ <em>unsigned int</em> <code>flags</code>,
+ <em>size_t</em> <code>cd_size</code>,
+ <em>const void</em> <code>*client_data</code>
+ )
+ <dt><strong>Purpose:</strong>
+ <dd>Sets compression method.
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pset_compression</code> sets the compression method
+ in a dataset creation property list. This is a catch-all
+ function for defining compression methods
+ and is intended to be called from a wrapper such as
+ <code>H5Pset_deflate</code>. The dataset creation property
+ list <em>plist</em> is adjusted to use the specified
+ compression method. The <em>flags</em> is an 8-bit vector
+ which is stored in the file as part of the compression message
+ and passed to the compress and uncompress functions. The
+ <em>client_data</em> is a byte array of length
+ <em>cd_size</em> which is copied to the file and passed to the
+ compress and uncompress methods.
+ <p>
+ The FLAGS, CD_SIZE, and CLIENT_DATA are copied to the
+ property list and eventually to the file and passed to the
+ compression functions.
+ <p>
+ See <a href="Datasets.html"><cite>The Dataset Interface (H5D)</cite></a>
+ in the <cite>HDF5 User's Guide</cite> for further information
+ regarding data compression.
+ <dt><strong>Parameters:</strong>
<dl>
- <dt><em>hid_t</em> <code>fapl_id</code>
- <dd>IN: File access property list identifier.
- <dt><em>H5F_close_degree_t</em> <code>fc_degree</code>
- <dd>OUT: Pointer to a location to which to return the file close degree
- property, the value of <code>fc_degree</code>.
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Identifier for the dataset creation property list.
+ <dt><em>H5Z_method_t</em> <code>method</code>
+ <dd>IN: Compression method, an integer from 16 to 225.
+ <dt><em>unsigned int</em> <code>flags</code>
+ <dd>IN: Compression flags.
+ <dt><em>size_t</em> <code>cd_size</code>
+ <dd>IN: Size of the byte array <code>client_data</code>.
+ <dt><em>const void</em> <code>*client_data</code>
+ <dd>IN: Client data byte array passed to the compression method.
</dl>
- <dt><strong>Returns:</strong>
- <dd>Returns a non-negative value if successful. Otherwise returns a negative
- value.
+ <dt><strong>Returns:</strong>
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
<dt><strong>Non-C API(s):</strong>
- <dd><a href="fortran/h5p_FORTRAN.html#h5pget_fclose_degree_f"
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+</dl>
+
+-->
+
+
+<!--
+
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-GetCompression">H5Pget_compression</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>H5Z_method_t</em> <code>H5Pget_compression</code>(<em>hid_t</em> <code>plist</code>,
+ <em>unsigned int</em> <code>*flags</code>,
+ <em>size_t</em> <code>*cd_size</code>,
+ <em>void</em> <code>*client_data</code>
+ )
+ <dt><strong>Purpose:</strong>
+ <dd>Gets compression method.
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pget_compression</code> gets the compression method
+ information from a dataset creation property list.
+ The <code>client_data</code> buffer is initially
+ <code>cd_size</code> bytes. On return, <code>client_data</code>
+ will be initialized with at most that many bytes, and
+ <code>cd_size</code> will contain the actual size of the
+ client data, which might be larger than its original value.
+ <dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Identifier for the dataset creation property list.
+ <dt><em>unsigned int</em> <code>*flags</code>
+ <dd>OUT: Compression flags.
+ <dt><em>size_t</em> <code>*cd_size</code>
+ <dd>IN/OUT: Size of the <code>client_data</code> array.
+ <dt><em>void</em> <code>*client_data</code>
+ <dd>OUT: Byte array for the client data.
+ </dl>
+ <dt><strong>Returns:</strong>
+ <dd>Returns compression method if successful;
+ otherwise returns a negative value.
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+</dl>
+
+-->
+
+
+<!--
+
+<hr>
+<dl>
+ <dt><strong>Name:</strong> <a name="Property-GetDeflate">H5Pget_deflate</a>
+ <dt><strong>Signature:</strong>
+ <dd><em>int</em> <code>H5Pget_deflate</code>(<em>hid_t</em> <code>plist</code>
+ )
+ <dt><strong>Purpose:</strong>
+ <dd>Returns the deflate compression level from a dataset creation
+ property list.
+ <dt><strong>Description:</strong>
+ <dd><code>H5Pget_deflate</code> returns the deflate compression level
+ from a dataset creation property list that uses that method.
+ <dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>plist</code>
+ <dd>IN: Identifier for the dataset creation property list.
+ </dl>
+ <dt><strong>Returns:</strong>
+ <dd>Returns compression level, a value between 0 and 9, if successful.
+ Otherwise returns a negative value.
+ <dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx"
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
- <!--
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
- -->
</dl>
+-->
+
<!-- ***** TEMPLATE *****
@@ -7527,14 +7635,15 @@ And in this document, the
</td></tr>
</table>
</center>
-<hr>
-<!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address>
+<hr><!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address>
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
<br>
Describes HDF5 Release 1.6.0, July 2003
-</address><!-- #EndLibraryItem -->
-
-Last modified: 3 July 2003
+</address><!-- #EndLibraryItem --><SCRIPT LANGUAGE="JAVASCRIPT">
+<!--
+document.writeln("Last modified: 7 October 2003");
+-->
+</SCRIPT>
</body>
</html>