diff options
| author | Frank Baker <fbaker@hdfgroup.org> | 2003-10-07 22:17:58 (GMT) |
|---|---|---|
| committer | Frank Baker <fbaker@hdfgroup.org> | 2003-10-07 22:17:58 (GMT) |
| commit | c1afffec458a21b98072930d06ece03e7ba1954c (patch) | |
| tree | 2d063db22e94604a343a5aa43cacc78f00f441c6 | |
| parent | 0eaf192df8e7df34cb2d45085bb3252816eb8e2d (diff) | |
| download | hdf5-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
| -rw-r--r-- | doc/html/RM_H5P.html | 8261 |
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> || <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> </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> </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>|| <i>Available only in the parallel HDF5 library.</i> + || <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"> </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> + </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"> </td><td> + <code>H5D_ALLOC_TIME_DEFAULT</code> + </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> + </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"> </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> - </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> </td><td> - <code>H5D_FILL_TIME_IFSET</code> - </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>. - (Default) - </td></tr><tr valign="top"><td> </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> </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"> </td><td> - <code>H5D_ALLOC_TIME_DEFAULT</code> - </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> - </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"> </td><td> - <code>H5D_ALLOC_TIME_DEFAULT</code> - </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> - </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> </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 </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 </code> - </td><td> - <hr> - Compresses exactly as in hardware. - </td></tr> - <tr valign=top align=left><td> - <code>H5_SZIP_ALLOW_K13_OPTION_MASK </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> - 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> </td><td> - <code>H5Z_ENABLE_EDC</code> (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 <code> NULL</code> + for system <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 + <code> NULL</code>. + <dt><em>H5MM_free_t</em> <code>free</code> + <dd>OUT: User's free routine, or <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 + <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"> </td><td> + <code>H5D_ALLOC_TIME_DEFAULT</code> + </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> + </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> </td><td> + <code>H5Z_ENABLE_EDC</code> (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> - <em>typedef void</em> *(*<code>H5MM_allocate_t</code>)(<em>size_t</em> <code>size</code>, - <em>void</em> *<code>alloc_info</code>) ; - - <br> - <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 <code> NULL</code> - for system <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 - <code> NULL</code>. - <dt><em>H5MM_free_t</em> <code>free</code> - <dd>IN: User's free routine, or <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 - <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 <code> NULL</code> - for system <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 - <code> NULL</code>. - <dt><em>H5MM_free_t</em> <code>free</code> - <dd>OUT: User's free routine, or <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 - <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> </td><td> - <code>H5FD_MEM_DEFAULT</code> - </td><td> - Need description.... - </td></tr> - <tr valign=top align=left><td> </td><td> - <code>H5FD_MEM_SUPER</code> - </td><td> - Super block ... need description.... - </td></tr> - <tr valign=top align=left><td> </td><td> - <code>H5FD_MEM_BTREE</code> - </td><td> - Btree ... need description.... - </td></tr> - <tr valign=top align=left><td> </td><td> - <code>H5FD_MEM_DRAW</code> - </td><td> - Need description.... - </td></tr> - <tr valign=top align=left><td> </td><td> - <code>H5FD_MEM_GHEAP</code> - </td><td> - Global heap ... need description.... - </td></tr> - <tr valign=top align=left><td> </td><td> - <code>H5FD_MEM_LHEAP</code> - </td><td> - Local Heap ... need description.... - </td></tr> - <tr valign=top align=left><td> </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> </td><td> + <code>H5D_FILL_TIME_IFSET</code> + </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>. + (Default) + </td></tr><tr valign="top"><td> </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> </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> </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 </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> </td><td> + <code>H5FD_MEM_DEFAULT</code> + </td><td> + Need description.... + </td></tr> + <tr valign=top align=left><td> </td><td> + <code>H5FD_MEM_SUPER</code> + </td><td> + Super block ... need description.... + </td></tr> + <tr valign=top align=left><td> </td><td> + <code>H5FD_MEM_BTREE</code> + </td><td> + Btree ... need description.... + </td></tr> + <tr valign=top align=left><td> </td><td> + <code>H5FD_MEM_DRAW</code> + </td><td> + Need description.... + </td></tr> + <tr valign=top align=left><td> </td><td> + <code>H5FD_MEM_GHEAP</code> + </td><td> + Global heap ... need description.... + </td></tr> + <tr valign=top align=left><td> </td><td> + <code>H5FD_MEM_LHEAP</code> + </td><td> + Local Heap ... need description.... + </td></tr> + <tr valign=top align=left><td> </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 </code> + </td><td> + <hr> + Compresses exactly as in hardware. + </td></tr> + <tr valign=top align=left><td> + <code>H5_SZIP_ALLOW_K13_OPTION_MASK </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> + 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> + <em>typedef void</em> *(*<code>H5MM_allocate_t</code>)(<em>size_t</em> <code>size</code>, + <em>void</em> *<code>alloc_info</code>) ; + + <br> + <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 <code> NULL</code> + for system <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 + <code> NULL</code>. + <dt><em>H5MM_free_t</em> <code>free</code> + <dd>IN: User's free routine, or <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 + <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> |