diff options
| -rw-r--r-- | doc/html/RM_H5.html | 380 | ||||
| -rw-r--r-- | doc/html/RM_H5D.html | 769 | ||||
| -rw-r--r-- | doc/html/RM_H5E.html | 227 | ||||
| -rw-r--r-- | doc/html/RM_H5F.html | 362 | ||||
| -rw-r--r-- | doc/html/RM_H5G.html | 1007 | ||||
| -rw-r--r-- | doc/html/RM_H5I.html | 119 | ||||
| -rw-r--r-- | doc/html/RM_H5P.html | 8542 | ||||
| -rw-r--r-- | doc/html/RM_H5R.html | 97 | ||||
| -rw-r--r-- | doc/html/RM_H5S.html | 929 | ||||
| -rw-r--r-- | doc/html/RM_H5T.html | 2585 | ||||
| -rw-r--r-- | doc/html/RM_H5Z.html | 72 |
11 files changed, 7596 insertions, 7493 deletions
diff --git a/doc/html/RM_H5.html b/doc/html/RM_H5.html index 8a088fa..2c770e7 100644 --- a/doc/html/RM_H5.html +++ b/doc/html/RM_H5.html @@ -60,8 +60,7 @@ And in this document, the </td></tr> </table> </center> -<hr> -<!-- #EndLibraryItem --><center> +<hr><!-- #EndLibraryItem --><center> <h1>H5: General Library Functions</h1> </center> @@ -163,31 +162,97 @@ facilitate moving easily between them.</i> <!-- NEW PAGE --> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5open" --> +<!-- HEADER RIGHT "H5check_version" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Library-Open">H5open</a> +<dt><strong>Name:</strong> <a name="Library-VersCheck">H5check_version</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5open</code>(<em>void</em>) + <dd><em>herr_t</em> <code>H5check_version</code>(<em>unsigned</em> <code>majnum</code>, + <em>unsigned</em> <code>minnum</code>, + <em>unsigned</em> <code>relnum</code> + ) <dt><strong>Purpose:</strong> - <dd>Initializes the HDF5 library. + <dd>Verifies that library versions are consistent. <dt><strong>Description:</strong> - <dd><code>H5open</code> initialize the library. This function is - normally called automatically, but if you find that an - HDF5 library function is failing inexplicably, try calling - this function first. + <dd><code>H5check_version</code> verifies that the arguments provided + with the function call match the version numbers compiled into + the library. + <p> + <code>H5check_version</code> serves two slightly differing purposes. + <p> + First, the function is intended to be called by the user to verify + that the version of the header files compiled into an application + matches the version of the HDF5 library being used. + One may look at the <code>H5check</code> definition in the file + <code>H5public.h</code> as an example. + <p> + Due to the risks of data corruption or segmentation faults, + <code>H5check_version</code> causes the application to abort if the + version numbers do not match. + The abort is achieved by means of a call to the + standard C function <code>abort()</code>. + <p> + Note that <code>H5check_version</code> verifies only the + major and minor version numbers and the release number; + it does not verify the sub-release value as that should be + an empty string for any official release. + This means that any two incompatible library versions must + have different {major,minor,release} numbers. (Notice the + reverse is not necessarily true.) + <p> + Secondarily, <code>H5check_version</code> verifies that the + library version identifiers <code>H5_VERS_MAJOR</code>, + <code>H5_VERS_MINOR</code>, <code>H5_VERS_RELEASE</code>, + <code>H5_VERS_SUBRELEASE</code>, and <code>H5_VERS_INFO</code> + are consistent. + This is designed to catch source code inconsistencies, + but does not generate the fatal error as in the first stage + because this inconsistency does not cause errors in the data files. + If this check reveals inconsistencies, the library issues a warning + but the function does not fail. +<!-- + <p> +<strong><em>Alternate to preceding paragraph / More to the point?</em></strong> +<br> + If the function passes the above test and does not generate + an <code>abort()</code> call, the function's second purpose + comes into play. + <code>H5check_version</code> then procedes to verify + that the additional library version identifiers + <code>H5_VERS_SUBRELEASE</code>, and <code>H5_VERS_INFO</code> + are consistent. + This is designed to catch source code inconsistencies, + but does not generate the fatal error + that is generated under the first function. + <p> + The version and release numbers passed as + <code>H5check_version</code> parameters have the + following relationsips to each other: + <dir> + An official HDF5 release is labelled as + <br> + HDF5 Release <<code>majnum</code>><strong>.</strong><<code>minnum</code>><strong>.</strong><<code>relnum</code>> + </dir> + For example, in the version of the library known as HDF5 Release 1.4.2, + the 1 is the major version number, <code>majnum</code>; + the 1 is the minor version number, <code>minnum</code>; and + the 1 is the release number, <code>relnum</code>. +--> <dt><strong>Parameters:</strong> <dl> - <dt>None. + <dt><em>unsigned </em><code>majnum</code> + <dd>IN: The major version of the library. + <dt><em>unsigned </em><code>minnum</code> + <dd>IN: The minor version of the library. + <dt><em>unsigned </em><code>relnum</code> + <dd>IN: The release number of the library. </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. + Upon failure, this function causes the application to abort. <dt><strong>Non-C API(s):</strong> - <dd> -<a href="fortran/h5_FORTRAN.html#h5open_f" target="FortranWin"> -<img src="Graphics/FORTRAN.gif" border=0></a> - + <dd><a href="fortran/h5_FORTRAN.html#h5check_version_f" + target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> <img src="Graphics/C++.gif"> @@ -227,72 +292,39 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5set_free_list_limits" --> +<!-- HEADER RIGHT "H5H5dont_atexit" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Library-SetFreeListLimits">H5set_free_list_limits</a> +<dt><strong>Name:</strong> <a name="Library-DontAtExit">H5dont_atexit</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5set_free_list_limits</code>(<em>int</em> <code>reg_global_lim</code>, - <em>int</em> <code>reg_list_lim</code>, - <em>int</em> <code>arr_global_lim</code>, - <em>int</em> <code>arr_list_lim</code>, - <em>int</em> <code>blk_global_lim</code>, - <em>int</em> <code>blk_list_lim</code> - ) + <dd><em>herr_t</em> <code>H5dont_atexit</code>(<em>void</em>) <dt><strong>Purpose:</strong> - <dd>Sets free-list size limits. + <dd>Instructs library not to install <code>atexit</code> cleanup routine. <dt><strong>Description:</strong> - <dd><code>H5set_free_list_limits</code> sets size limits - on all types of free lists. - The HDF5 library uses free lists internally to manage memory. - There are three types of free lists: - <ul><li><span class=termDef>Regular</span> - free lists manage a single data structure. - <li><span class=termDef>Array</span> - free lists manage arrays of a data structure. - <li><span class=termDef>Block</span> - free lists manage blocks of bytes. - </ul> - <em>Alternate phrasing?</em>: - <ul><li><span class=termDef>Regular</span> - free lists manage data structures containing atomic data. - <li><span class=termDef>Array</span> - free lists manage data structures containing array data. - <li><span class=termDef>Block</span> - free lists manage blocks of bytes. - </ul> - <p> - These are global limits, but each limit applies only to - free lists of the specified type. - Therefore, if an application sets a 1Mb limit on each of - the global lists, up to 3Mb of total storage might be - allocated, 1Mb for each of the regular, array, and - block type lists. - <p> - Using a value of <code>-1</code> for a limit means that - no limit is set for the specified type of free list. + <dd><code>H5dont_atexit</code> indicates to the library that an + <code>atexit()</code> cleanup routine should not be installed. + The major purpose for this is in situations where the + library is dynamically linked into an application and is + un-linked from the application before <code>exit()</code> gets + called. In those situations, a routine installed with + <code>atexit()</code> would jump to a routine which was + no longer in memory, causing errors. + <p> + In order to be effective, this routine <em>must</em> be called + before any other HDF function calls, and must be called each + time the library is loaded/linked into the application + (the first time and after it's been un-loaded). <dt><strong>Parameters:</strong> <dl> - <dt><em>int</em> <code>reg_global_lim</code> - <dd>IN: The limit on all regular free list memory used - <dt><em>int</em> <code>reg_list_lim</code> - <dd>IN: The limit on memory used in each regular free list - <dt><em>int</em> <code>arr_global_lim</code> - <dd>IN: The limit on all array free list memory used - <dt><em>int</em> <code>arr_list_lim</code> - <dd>IN: The limit on memory used in each array free list - <dt><em>int</em> <code>blk_global_lim</code> - <dd>IN: The limit on all block free list memory used - <dt><em>int</em> <code>blk_list_lim</code> - <dd>IN: The limit on memory used in each block free list + <dt>None. </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/h5_FORTRAN.html#h5set_free_list_limits_f" + <dd><a href="fortran/h5_FORTRAN.html#h5dont_atexit_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> - <!-- + <!-- <img src="Graphics/Java.gif"> <img src="Graphics/C++.gif"> --> @@ -338,37 +370,35 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5H5dont_atexit" --> +<!-- HEADER RIGHT "H5get_libversion" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Library-DontAtExit">H5dont_atexit</a> +<dt><strong>Name:</strong> <a name="Library-Version">H5get_libversion</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5dont_atexit</code>(<em>void</em>) + <dd><em>herr_t</em> <code>H5get_libversion</code>(<em>unsigned *</em><code>majnum</code>, + <em>unsigned *</em><code>minnum</code>, + <em>unsigned *</em><code>relnum</code> + ) <dt><strong>Purpose:</strong> - <dd>Instructs library not to install <code>atexit</code> cleanup routine. + <dd>Returns the HDF library release number. <dt><strong>Description:</strong> - <dd><code>H5dont_atexit</code> indicates to the library that an - <code>atexit()</code> cleanup routine should not be installed. - The major purpose for this is in situations where the - library is dynamically linked into an application and is - un-linked from the application before <code>exit()</code> gets - called. In those situations, a routine installed with - <code>atexit()</code> would jump to a routine which was - no longer in memory, causing errors. - <p> - In order to be effective, this routine <em>must</em> be called - before any other HDF function calls, and must be called each - time the library is loaded/linked into the application - (the first time and after it's been un-loaded). + <dd><code>H5get_libversion</code> retrieves the major, minor, and release + numbers of the version of the HDF library which is linked to + the application. <dt><strong>Parameters:</strong> <dl> - <dt>None. + <dt><em>unsigned *</em><code>majnum</code> + <dd>OUT: The major version of the library. + <dt><em>unsigned *</em><code>minnum</code> + <dd>OUT: The minor version of the library. + <dt><em>unsigned *</em><code>relnum</code> + <dd>OUT: The release number of the library. </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/h5_FORTRAN.html#h5dont_atexit_f" + <dd><a href="fortran/h5_FORTRAN.html#h5get_libversion_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -377,36 +407,31 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5get_libversion" --> +<!-- HEADER RIGHT "H5open" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Library-Version">H5get_libversion</a> +<dt><strong>Name:</strong> <a name="Library-Open">H5open</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5get_libversion</code>(<em>unsigned *</em><code>majnum</code>, - <em>unsigned *</em><code>minnum</code>, - <em>unsigned *</em><code>relnum</code> - ) + <dd><em>herr_t</em> <code>H5open</code>(<em>void</em>) <dt><strong>Purpose:</strong> - <dd>Returns the HDF library release number. + <dd>Initializes the HDF5 library. <dt><strong>Description:</strong> - <dd><code>H5get_libversion</code> retrieves the major, minor, and release - numbers of the version of the HDF library which is linked to - the application. + <dd><code>H5open</code> initialize the library. This function is + normally called automatically, but if you find that an + HDF5 library function is failing inexplicably, try calling + this function first. <dt><strong>Parameters:</strong> <dl> - <dt><em>unsigned *</em><code>majnum</code> - <dd>OUT: The major version of the library. - <dt><em>unsigned *</em><code>minnum</code> - <dd>OUT: The minor version of the library. - <dt><em>unsigned *</em><code>relnum</code> - <dd>OUT: The release number of the library. + <dt>None. </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/h5_FORTRAN.html#h5get_libversion_f" - target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> + <dd> +<a href="fortran/h5_FORTRAN.html#h5open_f" target="FortranWin"> +<img src="Graphics/FORTRAN.gif" border=0></a> + <!-- <img src="Graphics/Java.gif"> <img src="Graphics/C++.gif"> @@ -414,98 +439,72 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5check_version" --> +<!-- HEADER RIGHT "H5set_free_list_limits" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Library-VersCheck">H5check_version</a> +<dt><strong>Name:</strong> <a name="Library-SetFreeListLimits">H5set_free_list_limits</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5check_version</code>(<em>unsigned</em> <code>majnum</code>, - <em>unsigned</em> <code>minnum</code>, - <em>unsigned</em> <code>relnum</code> - ) + <dd><em>herr_t</em> <code>H5set_free_list_limits</code>(<em>int</em> <code>reg_global_lim</code>, + <em>int</em> <code>reg_list_lim</code>, + <em>int</em> <code>arr_global_lim</code>, + <em>int</em> <code>arr_list_lim</code>, + <em>int</em> <code>blk_global_lim</code>, + <em>int</em> <code>blk_list_lim</code> + ) <dt><strong>Purpose:</strong> - <dd>Verifies that library versions are consistent. + <dd>Sets free-list size limits. <dt><strong>Description:</strong> - <dd><code>H5check_version</code> verifies that the arguments provided - with the function call match the version numbers compiled into - the library. - <p> - <code>H5check_version</code> serves two slightly differing purposes. - <p> - First, the function is intended to be called by the user to verify - that the version of the header files compiled into an application - matches the version of the HDF5 library being used. - One may look at the <code>H5check</code> definition in the file - <code>H5public.h</code> as an example. - <p> - Due to the risks of data corruption or segmentation faults, - <code>H5check_version</code> causes the application to abort if the - version numbers do not match. - The abort is achieved by means of a call to the - standard C function <code>abort()</code>. - <p> - Note that <code>H5check_version</code> verifies only the - major and minor version numbers and the release number; - it does not verify the sub-release value as that should be - an empty string for any official release. - This means that any two incompatible library versions must - have different {major,minor,release} numbers. (Notice the - reverse is not necessarily true.) - <p> - Secondarily, <code>H5check_version</code> verifies that the - library version identifiers <code>H5_VERS_MAJOR</code>, - <code>H5_VERS_MINOR</code>, <code>H5_VERS_RELEASE</code>, - <code>H5_VERS_SUBRELEASE</code>, and <code>H5_VERS_INFO</code> - are consistent. - This is designed to catch source code inconsistencies, - but does not generate the fatal error as in the first stage - because this inconsistency does not cause errors in the data files. - If this check reveals inconsistencies, the library issues a warning - but the function does not fail. -<!-- - <p> -<strong><em>Alternate to preceding paragraph / More to the point?</em></strong> -<br> - If the function passes the above test and does not generate - an <code>abort()</code> call, the function's second purpose - comes into play. - <code>H5check_version</code> then procedes to verify - that the additional library version identifiers - <code>H5_VERS_SUBRELEASE</code>, and <code>H5_VERS_INFO</code> - are consistent. - This is designed to catch source code inconsistencies, - but does not generate the fatal error - that is generated under the first function. - <p> - The version and release numbers passed as - <code>H5check_version</code> parameters have the - following relationsips to each other: - <dir> - An official HDF5 release is labelled as - <br> - HDF5 Release <<code>majnum</code>><strong>.</strong><<code>minnum</code>><strong>.</strong><<code>relnum</code>> - </dir> - For example, in the version of the library known as HDF5 Release 1.4.2, - the 1 is the major version number, <code>majnum</code>; - the 1 is the minor version number, <code>minnum</code>; and - the 1 is the release number, <code>relnum</code>. ---> + <dd><code>H5set_free_list_limits</code> sets size limits + on all types of free lists. + The HDF5 library uses free lists internally to manage memory. + There are three types of free lists: + <ul><li><span class=termDef>Regular</span> + free lists manage a single data structure. + <li><span class=termDef>Array</span> + free lists manage arrays of a data structure. + <li><span class=termDef>Block</span> + free lists manage blocks of bytes. + </ul> + <em>Alternate phrasing?</em>: + <ul><li><span class=termDef>Regular</span> + free lists manage data structures containing atomic data. + <li><span class=termDef>Array</span> + free lists manage data structures containing array data. + <li><span class=termDef>Block</span> + free lists manage blocks of bytes. + </ul> + <p> + These are global limits, but each limit applies only to + free lists of the specified type. + Therefore, if an application sets a 1Mb limit on each of + the global lists, up to 3Mb of total storage might be + allocated, 1Mb for each of the regular, array, and + block type lists. + <p> + Using a value of <code>-1</code> for a limit means that + no limit is set for the specified type of free list. <dt><strong>Parameters:</strong> <dl> - <dt><em>unsigned </em><code>majnum</code> - <dd>IN: The major version of the library. - <dt><em>unsigned </em><code>minnum</code> - <dd>IN: The minor version of the library. - <dt><em>unsigned </em><code>relnum</code> - <dd>IN: The release number of the library. + <dt><em>int</em> <code>reg_global_lim</code> + <dd>IN: The limit on all regular free list memory used + <dt><em>int</em> <code>reg_list_lim</code> + <dd>IN: The limit on memory used in each regular free list + <dt><em>int</em> <code>arr_global_lim</code> + <dd>IN: The limit on all array free list memory used + <dt><em>int</em> <code>arr_list_lim</code> + <dd>IN: The limit on memory used in each array free list + <dt><em>int</em> <code>blk_global_lim</code> + <dd>IN: The limit on all block free list memory used + <dt><em>int</em> <code>blk_list_lim</code> + <dd>IN: The limit on memory used in each block free list </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful. - Upon failure, this function causes the application to abort. + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5_FORTRAN.html#h5check_version_f" + <dd><a href="fortran/h5_FORTRAN.html#h5set_free_list_limits_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> - <!-- + <!-- <img src="Graphics/Java.gif"> <img src="Graphics/C++.gif"> --> @@ -545,14 +544,13 @@ 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 --><SCRIPT LANGUAGE="JAVASCRIPT"> <!-- -document.writeln("Last modified: 6 June 2003"); +document.writeln("Last modified: 3 October 2003"); --> </SCRIPT> diff --git a/doc/html/RM_H5D.html b/doc/html/RM_H5D.html index c219cb3..0d30cc7 100644 --- a/doc/html/RM_H5D.html +++ b/doc/html/RM_H5D.html @@ -61,8 +61,7 @@ And in this document, the </td></tr> </table> </center> -<hr> -<!-- #EndLibraryItem --><center> +<hr><!-- #EndLibraryItem --><center> <h1>H5D: Datasets Interface</h1> </center> @@ -200,6 +199,38 @@ facilitate moving easily between them.</i> <!-- NEW PAGE --> <!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Dclose" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataset-Close">H5Dclose</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Dclose</code>(<em>hid_t </em><code>dataset_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Closes the specified dataset. +<dt><strong>Description:</strong> + <dd><code>H5Dclose</code> ends access to a dataset specified by + <code>dataset_id</code> and releases resources used by it. + Further use of the dataset identifier is illegal in calls to + the dataset API. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>dataset_id</code> + <dd>IN: Identifier of the dataset to close access to. + </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/h5d_FORTRAN.html#h5dclose_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 "H5Dcreate" --> <hr> <dl> @@ -304,33 +335,46 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Dopen" --> +<!-- HEADER RIGHT "H5Dextend" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataset-Open">H5Dopen</a> +<dt><strong>Name:</strong> <a name="Dataset-Extend">H5Dextend</a> <dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Dopen</code>(<em>hid_t </em><code>loc_id</code>, - <em>const char *</em><code>name</code> + <dd><em>herr_t </em><code>H5Dextend</code>(<em>hid_t </em><code>dataset_id</code>, + <em>const hsize_t *</em> <code>size</code> ) <dt><strong>Purpose:</strong> - <dd>Opens an existing dataset. + <dd>Extends a dataset with unlimited dimension. <dt><strong>Description:</strong> - <dd><code>H5Dopen</code> opens an existing dataset for access in the file - or group specified in <code>loc_id</code>. <code>name</code> is - a dataset name and is used to identify the dataset in the file. + <dd><code>H5Dextend</code> verifies that the dataset is at least of size + <code>size</code>. + The dimensionality of <code>size</code> is the same as that of + the dataspace of the dataset being changed. + This function cannot be applied to a dataset with fixed dimensions. + <p> + Space on disk is immediately allocated for the new dataset extent + if the dataset's space allocation time is set to + <code>H5D_ALLOC_TIME_EARLY</code>. + Fill values will be written to the dataset if the dataset's fill time + is set to <code>H5D_FILL_TIME_IFSET</code> or + <code>H5D_FILL_TIME_ALLOC</code>. + (Also see + <a href="RM_H5P.html#Property-SetFillTime">H5Pset_fill_time</a> + and + <a href="RM_H5P.html#Property-SetAllocTime">H5Pset_alloc_time</a>.) + <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>loc_id</code> - <dd>IN: Identifier of the file or group - within which the dataset to be accessed will be found. - <dt><em>const char *</em> <code>name</code> - <dd>IN: The name of the dataset to access. + <dt><em>hid_t</em> <code>dataset_id</code> + <dd>IN: Identifier of the dataset. + <dt><em>const hsize_t *</em> <code>size</code> + <dd>IN: Array containing the new magnitude of each dimension. </dl> <dt><strong>Returns:</strong> - <dd>Returns a dataset identifier if successful; + <dd>Returns a non-negative value if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5d_FORTRAN.html#h5dopen_f" + <dd><a href="fortran/h5d_FORTRAN.html#h5dextend_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -339,30 +383,72 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Dget_space" --> +<!-- HEADER RIGHT "H5Dfill" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataset-GetSpace">H5Dget_space</a> +<dt><strong>Name:</strong> <a name="Dataset-Fill">H5Dfill</a> <dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Dget_space</code>(<em>hid_t </em><code>dataset_id</code> + <dd><em>herr_t </em><code>H5Dfill</code>( + <em>const void *</em><code>fill</code>, + <em>hid_t </em><code>fill_type_id</code>, + <em>void *</em><code>buf</code>, + <em>hid_t </em><code>buf_type_id</code>, + <em>hid_t </em><code>space_id</code> ) <dt><strong>Purpose:</strong> - <dd>Returns an identifier for a copy of the dataspace for a dataset. + <dd>Fills dataspace elements with a fill value in a memory buffer. <dt><strong>Description:</strong> - <dd><code>H5Dget_space</code> returns an identifier for a copy of the - dataspace for a dataset. - The dataspace identifier should be released with the - <code>H5Sclose</code> function. + <dd><code>H5Dfill</code> explicitly fills + the dataspace selection in memory, <code>space_id</code>, + with the fill value specified in <code>fill</code>. + If <code>fill</code> is <code>NULL</code>, + a fill value of <code>0</code> (zero) is used. + <p> + <code>fill_type_id</code> specifies the datatype + of the fill value.<br> + <code>buf</code> specifies the buffer in which + the dataspace elements will be written.<br> + <code>buf_type_id</code> specifies the datatype of + those data elements. + <p> + Note that if the fill value datatype differs + from the memory buffer datatype, the fill value + will be converted to the memory buffer datatype + before filling the selection. +<dt><strong>Note:</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>. + See <a href="RM_H5P.html#Property-SetFillValue">H5Pset_fill_value</a> + for further discussion. + Other related functions include + <a href="RM_H5P.html#Property-GetFillValue">H5Pget_fill_value</a>, + <a href="RM_H5P.html#Property-FillValueDefined">H5Pfill_value_defined</a>, + <a href="RM_H5P.html#Property-SetFillTime">H5Pset_fill_time</a>, + <a href="RM_H5P.html#Property-GetFillTime">H5Pget_fill_time</a>, + and + <a href="#Dataset-Create">H5Dcreate</a>. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>dataset_id</code> - <dd>IN: Identifier of the dataset to query. + <dt><em>const void *</em><code>fill</code> + <dd>IN: Pointer to the fill value to be used. + <dt><em>hid_t </em><code>fill_type_id</code> + <dd>IN: Fill value datatype identifier. + <dt><em>void *</em><code>buf</code> + <dd>IN/OUT: Pointer to the memory buffer containing the + selection to be filled. + <dt><em>hid_t </em><code>buf_type_id</code> + <dd>IN: Datatype of dataspace elements to be filled. + <dt><em>hid_t </em><code>space_id</code> + <dd>IN: Dataspace describing memory buffer and + containing the selection to be filled. </dl> <dt><strong>Returns:</strong> - <dd>Returns a dataspace identifier if successful; + <dd>Returns a non-negative value if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5d_FORTRAN.html#h5dget_space_f" + <dd><a href="fortran/h5d_FORTRAN.html#h5dfill_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -371,51 +457,31 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Dget_space_status" --> +<!-- HEADER RIGHT "H5Dget_create_plist" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataset-GetSpaceStatus">H5Dget_space_status</a> +<dt><strong>Name:</strong> <a name="Dataset-GetCreatePlist">H5Dget_create_plist</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Dget_space_status</code>(<em>hid_t </em><code>dset_id</code>, - <em>H5D_space_status_t *</em><code>status</code>) + <dd><em>hid_t </em><code>H5Dget_create_plist</code>(<em>hid_t </em><code>dataset_id</code> + ) <dt><strong>Purpose:</strong> - <dd>Determines whether space has been allocated for a dataset. + <dd>Returns an identifier for a copy of the + dataset creation property list for a dataset. <dt><strong>Description:</strong> - <dd><code>H5Dget_space_status</code> determines whether space has been - allocated for the dataset <code>dset_id</code>. - <p> - Space allocation status is returned in <code>status</code>, - which will have one of the following values: - <center> - <table border="0"> - <tr valign="top"><td rowspan="3"> </td><td> - H5D_SPACE_STATUS_NOT_ALLOCATED - </td><td> - Space has not been allocated for this dataset. - </td></tr><tr valign="top"><td> - H5D_SPACE_STATUS_ALLOCATED - </td><td> - Space has been allocated for this dataset. - </td></tr><tr valign="top"><td> - H5D_SPACE_STATUS_PART_ALLOCATED - </td><td> - Space has been partially allocated for this dataset. - (Used only for datasets with chunked storage.) - </td></tr> - </table> - </center> + <dd><code>H5Dget_create_plist</code> returns an identifier for a + copy of the dataset creation property list for a dataset. + The creation property list identifier should be released with + the <code>H5Pclose</code> function. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>dset_id</code> + <dt><em>hid_t</em> <code>dataset_id</code> <dd>IN: Identifier of the dataset to query. - <dt><em>H5D_space_status_t *</em><code>status</code> - <dd>OUT: Space allocation status. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; + <dd>Returns a dataset creation property list identifier if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5d_FORTRAN.html#h5dget_space_status_f" + <dd><a href="fortran/h5d_FORTRAN.html#h5dget_create_plist_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -424,67 +490,62 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Dget_type" --> +<!-- HEADER RIGHT "H5Dget_offset" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataset-GetType">H5Dget_type</a> +<dt><strong>Name:</strong> <a name="Dataset-GetOffset">H5Dget_offset</a> <dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Dget_type</code>(<em>hid_t </em><code>dataset_id</code> - ) + <dd><em>haddr_t </em><code>H5Dget_offset</code>(<em>hid_t </em><code>dset_id</code>) <dt><strong>Purpose:</strong> - <dd>Returns an identifier for a copy of the datatype for a dataset. + <dd>Returns dataset address in file. <dt><strong>Description:</strong> - <dd><code>H5Dget_type</code> returns an identifier for a copy of the - datatype for a dataset. - The datatype should be released with the <code>H5Tclose</code> function. - <p> - If a dataset has a named datatype, then an identifier to the - opened datatype is returned. - Otherwise, the returned datatype is read-only. - If atomization of the datatype fails, then the datatype is closed. + <dd><code>H5Dget_offset</code> returns the address in the file + of the dataset <code>dset_id</code>. + That address is expressed as the offset in bytes from + the beginning of the file. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>dataset_id</code> - <dd>IN: Identifier of the dataset to query. + <dt><em>hid_t </em><code>dset_id</code> + <dd>Dataset identifier. </dl> <dt><strong>Returns:</strong> - <dd>Returns a datatype identifier if successful; - otherwise returns a negative value. + <dd>Returns the offset in bytes; + otherwise returns <code>HADDR_UNDEF</code>, a negative value. +<!-- <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5d_FORTRAN.html#h5dget_type_f" + <dd><a href="fortran/h5d_FORTRAN.html#h5dget_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 "H5Dget_create_plist" --> +<!-- HEADER RIGHT "H5Dget_space" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataset-GetCreatePlist">H5Dget_create_plist</a> +<dt><strong>Name:</strong> <a name="Dataset-GetSpace">H5Dget_space</a> <dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Dget_create_plist</code>(<em>hid_t </em><code>dataset_id</code> + <dd><em>hid_t </em><code>H5Dget_space</code>(<em>hid_t </em><code>dataset_id</code> ) <dt><strong>Purpose:</strong> - <dd>Returns an identifier for a copy of the - dataset creation property list for a dataset. + <dd>Returns an identifier for a copy of the dataspace for a dataset. <dt><strong>Description:</strong> - <dd><code>H5Dget_create_plist</code> returns an identifier for a - copy of the dataset creation property list for a dataset. - The creation property list identifier should be released with - the <code>H5Pclose</code> function. + <dd><code>H5Dget_space</code> returns an identifier for a copy of the + dataspace for a dataset. + The dataspace identifier should be released with the + <code>H5Sclose</code> function. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>dataset_id</code> <dd>IN: Identifier of the dataset to query. </dl> <dt><strong>Returns:</strong> - <dd>Returns a dataset creation property list identifier if successful; + <dd>Returns a dataspace identifier if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5d_FORTRAN.html#h5dget_create_plist_f" + <dd><a href="fortran/h5d_FORTRAN.html#h5dget_space_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -493,32 +554,53 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Dget_offset" --> +<!-- HEADER RIGHT "H5Dget_space_status" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataset-GetOffset">H5Dget_offset</a> +<dt><strong>Name:</strong> <a name="Dataset-GetSpaceStatus">H5Dget_space_status</a> <dt><strong>Signature:</strong> - <dd><em>haddr_t </em><code>H5Dget_offset</code>(<em>hid_t </em><code>dset_id</code>) + <dd><em>herr_t</em> <code>H5Dget_space_status</code>(<em>hid_t </em><code>dset_id</code>, + <em>H5D_space_status_t *</em><code>status</code>) <dt><strong>Purpose:</strong> - <dd>Returns dataset address in file. + <dd>Determines whether space has been allocated for a dataset. <dt><strong>Description:</strong> - <dd><code>H5Dget_offset</code> returns the address in the file - of the dataset <code>dset_id</code>. - That address is expressed as the offset in bytes from - the beginning of the file. + <dd><code>H5Dget_space_status</code> determines whether space has been + allocated for the dataset <code>dset_id</code>. + <p> + Space allocation status is returned in <code>status</code>, + which will have one of the following values: + <center> + <table border="0"> + <tr valign="top"><td rowspan="3"> </td><td> + H5D_SPACE_STATUS_NOT_ALLOCATED + </td><td> + Space has not been allocated for this dataset. + </td></tr><tr valign="top"><td> + H5D_SPACE_STATUS_ALLOCATED + </td><td> + Space has been allocated for this dataset. + </td></tr><tr valign="top"><td> + H5D_SPACE_STATUS_PART_ALLOCATED + </td><td> + Space has been partially allocated for this dataset. + (Used only for datasets with chunked storage.) + </td></tr> + </table> + </center> <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t </em><code>dset_id</code> - <dd>Dataset identifier. + <dt><em>hid_t</em> <code>dset_id</code> + <dd>IN: Identifier of the dataset to query. + <dt><em>H5D_space_status_t *</em><code>status</code> + <dd>OUT: Space allocation status. </dl> <dt><strong>Returns:</strong> - <dd>Returns the offset in bytes; - otherwise returns <code>HADDR_UNDEF</code>, 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/h5d_FORTRAN.html#h5dget_offset_f" + <dd><a href="fortran/h5d_FORTRAN.html#h5dget_space_status_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> ---> <!-- + <!-- <img src="Graphics/Java.gif"> <img src="Graphics/C++.gif"> --> @@ -559,50 +641,35 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Dvlen_get_buf_size" --> +<!-- HEADER RIGHT "H5Dget_type" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataset-VLGetBuf">H5Dvlen_get_buf_size</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Dvlen_get_buf_size</code>(<em>hid_t </em><code>dataset_id</code>, - <em>hid_t</em> <code>type_id</code>, - <em>hid_t</em> <code>space_id</code>, - <em>hsize_t</em> *<code>size</code> +<dt><strong>Name:</strong> <a name="Dataset-GetType">H5Dget_type</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Dget_type</code>(<em>hid_t </em><code>dataset_id</code> ) <dt><strong>Purpose:</strong> - <dd>Determines the number of bytes required to store VL data. + <dd>Returns an identifier for a copy of the datatype for a dataset. <dt><strong>Description:</strong> - <dd><code>H5Dvlen_get_buf_size</code> determines the number of bytes - required to store the VL data from the dataset, using the - <code>space_id</code> for the selection in the dataset on - disk and the <code>type_id</code> for the memory representation - of the VL data in memory. + <dd><code>H5Dget_type</code> returns an identifier for a copy of the + datatype for a dataset. + The datatype should be released with the <code>H5Tclose</code> function. <p> - <code>*size</code> is returned with the number of bytes - required to store the VL data in memory. + If a dataset has a named datatype, then an identifier to the + opened datatype is returned. + Otherwise, the returned datatype is read-only. + If atomization of the datatype fails, then the datatype is closed. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>dataset_id</code> <dd>IN: Identifier of the dataset to query. - <dt><em>hid_t</em> <code>type_id</code> - <dd>IN: Datatype identifier. - <dt><em>hid_t</em> <code>space_id</code> - <dd>IN: Dataspace identifier. - <dt><em>hsize_t</em> *<code>size</code> - <dd>OUT: The size in bytes of the memory buffer required to store the VL data. </dl> <dt><strong>Returns:</strong> - <dd>Returns non-negative value if successful; + <dd>Returns a datatype identifier if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd>There is no direct FORTRAN couterpart for the C function - <code>H5Dvlen_get_buf_size</code>; - corresponding functionality is provided by the FORTRAN function - <a href="fortran/h5d_FORTRAN.html#h5dvlen_get_max_len_f" - target="FortranWin"><code>h5dvlen_get_max_len_f</code></a>. - <br> - <a href="fortran/h5d_FORTRAN.html#h5dvlen_get_max_len_f" - target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0 ></a> + <dd><a href="fortran/h5d_FORTRAN.html#h5dget_type_f" + target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> <img src="Graphics/C++.gif"> @@ -610,52 +677,56 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Dvlen_reclaim" --> +<!-- HEADER RIGHT "H5Diterate" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataset-VLReclaim">H5Dvlen_reclaim</a> +<dt><strong>Name:</strong> <a name="Dataset-Iterate">H5Diterate</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Dvlen_reclaim</code>(<em>hid_t </em><code>type_id</code>, - <em>hid_t</em> <code>space_id</code>, - <em>hid_t</em> <code>plist_id</code>, - <em>void</em> *<code>buf</code> + <dd><em>herr_t </em><code>H5Diterate</code>( + <em>void *</em><code>buf</code>, + <em>hid_t </em><code>type_id</code>, + <em>hid_t </em><code>space_id</code>, + <em>H5D_operator_t </em><code>operator</code>, + <em>void *</em><code>operator_data</code> ) <dt><strong>Purpose:</strong> - <dd>Reclaims VL datatype memory buffers. + <dd>Iterates over all selected elements in a dataspace. <dt><strong>Description:</strong> - <dd><code>H5Dvlen_reclaim</code> reclaims memory buffers created to - store VL datatypes. - <p> - The <code>type_id</code> must be the datatype stored in the buffer. - The <code>space_id</code> describes the selection for the memory buffer - to free the VL datatypes within. - The <code>plist_id</code> is the dataset transfer property list which - was used for the I/O transfer to create the buffer. - And <code>buf</code> is the pointer to the buffer to be reclaimed. - <p> - The VL structures (<code>hvl_t</code>) in the user's buffer are - modified to zero out the VL information after the memory has been reclaimed. + <dd><code>H5Diterate</code> iterates over all the elements selected + in a memory buffer. The callback function is called once for each + element selected in the dataspace. <p> - If nested VL datatypes were used to create the buffer, - this routine frees them <em>from the bottom up</em>, releasing all - the memory without creating memory leaks. + The selection in the dataspace is modified so that any elements + already iterated over are removed from the selection if the + iteration is interrupted (by the <code>H5D_operator_t</code> + function returning non-zero) before the iteration is complete; + the iteration may then be re-started by the user where it left off. + <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>IN: Identifier of the datatype. - <dt><em>hid_t</em> <code>space_id</code> - <dd>IN: Identifier of the dataspace. - <dt><em>hid_t</em> <code>plist_id</code> - <dd>IN: Identifier of the property list used to create the buffer. - <dt><em>void</em> *<code>buf</code> - <dd>IN: Pointer to the buffer to be reclaimed. + <dt><em>void *</em><code>buf</code> + <dd>IN/OUT: Pointer to the buffer in memory containing the + elements to iterate over. + <dt><em>hid_t </em><code>type_id</code> + <dd>IN: Datatype identifier for the elements stored in + <code>buf</code>. + <dt><em>hid_t </em><code>space_id</code> + <dd>IN: Dataspace identifier for <code>buf</code>. + Also contains the selection to iterate over. + <dt><em>H5D_operator_t </em><code>operator</code> + <dd>IN: Function pointer to the routine to be called + for each element in <code>buf</code> iterated over. + <dt><em>void *</em><code>operator_data</code> + <dd>IN/OUT: Pointer to any user-defined data associated + with the operation. </dl> <dt><strong>Returns:</strong> - <dd>Returns non-negative value if successful; - otherwise returns a negative value. + <dd>Returns the return value of the last operator if it was non-zero, + or zero if all elements have been processed. + Otherwise returns a negative value. <!-- <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5d_FORTRAN.html#h5dvlen_reclaim_f" + <dd><a href="fortran/h5d_FORTRAN.html#h5diterate_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> --> <!-- <img src="Graphics/Java.gif"> @@ -664,6 +735,41 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Dopen" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataset-Open">H5Dopen</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Dopen</code>(<em>hid_t </em><code>loc_id</code>, + <em>const char *</em><code>name</code> + ) +<dt><strong>Purpose:</strong> + <dd>Opens an existing dataset. +<dt><strong>Description:</strong> + <dd><code>H5Dopen</code> opens an existing dataset for access in the file + or group specified in <code>loc_id</code>. <code>name</code> is + a dataset name and is used to identify the dataset in the file. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: Identifier of the file or group + within which the dataset to be accessed will be found. + <dt><em>const char *</em> <code>name</code> + <dd>IN: The name of the dataset to access. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a dataset identifier if successful; + otherwise returns a negative value. +<dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5d_FORTRAN.html#h5dopen_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 "H5Dread" --> <hr> <dl> @@ -833,6 +939,110 @@ facilitate moving easily between them.</i> --> </dl> +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Dvlen_get_buf_size" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataset-VLGetBuf">H5Dvlen_get_buf_size</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Dvlen_get_buf_size</code>(<em>hid_t </em><code>dataset_id</code>, + <em>hid_t</em> <code>type_id</code>, + <em>hid_t</em> <code>space_id</code>, + <em>hsize_t</em> *<code>size</code> + ) +<dt><strong>Purpose:</strong> + <dd>Determines the number of bytes required to store VL data. +<dt><strong>Description:</strong> + <dd><code>H5Dvlen_get_buf_size</code> determines the number of bytes + required to store the VL data from the dataset, using the + <code>space_id</code> for the selection in the dataset on + disk and the <code>type_id</code> for the memory representation + of the VL data in memory. + <p> + <code>*size</code> is returned with the number of bytes + required to store the VL data in memory. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>dataset_id</code> + <dd>IN: Identifier of the dataset to query. + <dt><em>hid_t</em> <code>type_id</code> + <dd>IN: Datatype identifier. + <dt><em>hid_t</em> <code>space_id</code> + <dd>IN: Dataspace identifier. + <dt><em>hsize_t</em> *<code>size</code> + <dd>OUT: The size in bytes of the memory buffer required to store the VL data. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns non-negative value if successful; + otherwise returns a negative value. +<dt><strong>Non-C API(s):</strong> + <dd>There is no direct FORTRAN couterpart for the C function + <code>H5Dvlen_get_buf_size</code>; + corresponding functionality is provided by the FORTRAN function + <a href="fortran/h5d_FORTRAN.html#h5dvlen_get_max_len_f" + target="FortranWin"><code>h5dvlen_get_max_len_f</code></a>. + <br> + <a href="fortran/h5d_FORTRAN.html#h5dvlen_get_max_len_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 "H5Dvlen_reclaim" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataset-VLReclaim">H5Dvlen_reclaim</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Dvlen_reclaim</code>(<em>hid_t </em><code>type_id</code>, + <em>hid_t</em> <code>space_id</code>, + <em>hid_t</em> <code>plist_id</code>, + <em>void</em> *<code>buf</code> + ) +<dt><strong>Purpose:</strong> + <dd>Reclaims VL datatype memory buffers. +<dt><strong>Description:</strong> + <dd><code>H5Dvlen_reclaim</code> reclaims memory buffers created to + store VL datatypes. + <p> + The <code>type_id</code> must be the datatype stored in the buffer. + The <code>space_id</code> describes the selection for the memory buffer + to free the VL datatypes within. + The <code>plist_id</code> is the dataset transfer property list which + was used for the I/O transfer to create the buffer. + And <code>buf</code> is the pointer to the buffer to be reclaimed. + <p> + The VL structures (<code>hvl_t</code>) in the user's buffer are + modified to zero out the VL information after the memory has been reclaimed. + <p> + If nested VL datatypes were used to create the buffer, + this routine frees them <em>from the bottom up</em>, releasing all + the memory without creating memory leaks. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>IN: Identifier of the datatype. + <dt><em>hid_t</em> <code>space_id</code> + <dd>IN: Identifier of the dataspace. + <dt><em>hid_t</em> <code>plist_id</code> + <dd>IN: Identifier of the property list used to create the buffer. + <dt><em>void</em> *<code>buf</code> + <dd>IN: Pointer to the buffer to be reclaimed. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns non-negative value if successful; + otherwise returns a negative value. +<!-- +<dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5d_FORTRAN.html#h5dvlen_reclaim_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 "H5Dwrite" --> @@ -1016,219 +1226,6 @@ facilitate moving easily between them.</i> --> </dl> -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Dextend" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataset-Extend">H5Dextend</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Dextend</code>(<em>hid_t </em><code>dataset_id</code>, - <em>const hsize_t *</em> <code>size</code> - ) -<dt><strong>Purpose:</strong> - <dd>Extends a dataset with unlimited dimension. -<dt><strong>Description:</strong> - <dd><code>H5Dextend</code> verifies that the dataset is at least of size - <code>size</code>. - The dimensionality of <code>size</code> is the same as that of - the dataspace of the dataset being changed. - This function cannot be applied to a dataset with fixed dimensions. - <p> - Space on disk is immediately allocated for the new dataset extent - if the dataset's space allocation time is set to - <code>H5D_ALLOC_TIME_EARLY</code>. - Fill values will be written to the dataset if the dataset's fill time - is set to <code>H5D_FILL_TIME_IFSET</code> or - <code>H5D_FILL_TIME_ALLOC</code>. - (Also see - <a href="RM_H5P.html#Property-SetFillTime">H5Pset_fill_time</a> - and - <a href="RM_H5P.html#Property-SetAllocTime">H5Pset_alloc_time</a>.) - -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>dataset_id</code> - <dd>IN: Identifier of the dataset. - <dt><em>const hsize_t *</em> <code>size</code> - <dd>IN: Array containing the new magnitude of each dimension. - </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/h5d_FORTRAN.html#h5dextend_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 "H5Dclose" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataset-Close">H5Dclose</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Dclose</code>(<em>hid_t </em><code>dataset_id</code> - ) -<dt><strong>Purpose:</strong> - <dd>Closes the specified dataset. -<dt><strong>Description:</strong> - <dd><code>H5Dclose</code> ends access to a dataset specified by - <code>dataset_id</code> and releases resources used by it. - Further use of the dataset identifier is illegal in calls to - the dataset API. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>dataset_id</code> - <dd>IN: Identifier of the dataset to close access to. - </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/h5d_FORTRAN.html#h5dclose_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 "H5Diterate" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataset-Iterate">H5Diterate</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Diterate</code>( - <em>void *</em><code>buf</code>, - <em>hid_t </em><code>type_id</code>, - <em>hid_t </em><code>space_id</code>, - <em>H5D_operator_t </em><code>operator</code>, - <em>void *</em><code>operator_data</code> - ) -<dt><strong>Purpose:</strong> - <dd>Iterates over all selected elements in a dataspace. -<dt><strong>Description:</strong> - <dd><code>H5Diterate</code> iterates over all the elements selected - in a memory buffer. The callback function is called once for each - element selected in the dataspace. - <p> - The selection in the dataspace is modified so that any elements - already iterated over are removed from the selection if the - iteration is interrupted (by the <code>H5D_operator_t</code> - function returning non-zero) before the iteration is complete; - the iteration may then be re-started by the user where it left off. - -<dt><strong>Parameters:</strong> - <dl> - <dt><em>void *</em><code>buf</code> - <dd>IN/OUT: Pointer to the buffer in memory containing the - elements to iterate over. - <dt><em>hid_t </em><code>type_id</code> - <dd>IN: Datatype identifier for the elements stored in - <code>buf</code>. - <dt><em>hid_t </em><code>space_id</code> - <dd>IN: Dataspace identifier for <code>buf</code>. - Also contains the selection to iterate over. - <dt><em>H5D_operator_t </em><code>operator</code> - <dd>IN: Function pointer to the routine to be called - for each element in <code>buf</code> iterated over. - <dt><em>void *</em><code>operator_data</code> - <dd>IN/OUT: Pointer to any user-defined data associated - with the operation. - </dl> -<dt><strong>Returns:</strong> - <dd>Returns the return value of the last operator if it was non-zero, - or zero if all elements have been processed. - Otherwise returns a negative value. -<!-- -<dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5d_FORTRAN.html#h5diterate_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 "H5Dfill" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataset-Fill">H5Dfill</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Dfill</code>( - <em>const void *</em><code>fill</code>, - <em>hid_t </em><code>fill_type_id</code>, - <em>void *</em><code>buf</code>, - <em>hid_t </em><code>buf_type_id</code>, - <em>hid_t </em><code>space_id</code> - ) -<dt><strong>Purpose:</strong> - <dd>Fills dataspace elements with a fill value in a memory buffer. -<dt><strong>Description:</strong> - <dd><code>H5Dfill</code> explicitly fills - the dataspace selection in memory, <code>space_id</code>, - with the fill value specified in <code>fill</code>. - If <code>fill</code> is <code>NULL</code>, - a fill value of <code>0</code> (zero) is used. - <p> - <code>fill_type_id</code> specifies the datatype - of the fill value.<br> - <code>buf</code> specifies the buffer in which - the dataspace elements will be written.<br> - <code>buf_type_id</code> specifies the datatype of - those data elements. - <p> - Note that if the fill value datatype differs - from the memory buffer datatype, the fill value - will be converted to the memory buffer datatype - before filling the selection. -<dt><strong>Note:</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>. - See <a href="RM_H5P.html#Property-SetFillValue">H5Pset_fill_value</a> - for further discussion. - Other related functions include - <a href="RM_H5P.html#Property-GetFillValue">H5Pget_fill_value</a>, - <a href="RM_H5P.html#Property-FillValueDefined">H5Pfill_value_defined</a>, - <a href="RM_H5P.html#Property-SetFillTime">H5Pset_fill_time</a>, - <a href="RM_H5P.html#Property-GetFillTime">H5Pget_fill_time</a>, - and - <a href="#Dataset-Create">H5Dcreate</a>. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>const void *</em><code>fill</code> - <dd>IN: Pointer to the fill value to be used. - <dt><em>hid_t </em><code>fill_type_id</code> - <dd>IN: Fill value datatype identifier. - <dt><em>void *</em><code>buf</code> - <dd>IN/OUT: Pointer to the memory buffer containing the - selection to be filled. - <dt><em>hid_t </em><code>buf_type_id</code> - <dd>IN: Datatype of dataspace elements to be filled. - <dt><em>hid_t </em><code>space_id</code> - <dd>IN: Dataspace describing memory buffer and - containing the selection to be filled. - </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/h5d_FORTRAN.html#h5dfill_f" - target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> - <!-- - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - - <!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr> <center> <table border=0 width=98%> @@ -1262,17 +1259,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 --><SCRIPT LANGUAGE="JAVASCRIPT"> <!-- -document.writeln("Last modified: 25 June 2003"); +document.writeln("Last modified: 3 October 2003"); --> </SCRIPT> - </body> </html> diff --git a/doc/html/RM_H5E.html b/doc/html/RM_H5E.html index 64e9977..e5fa126 100644 --- a/doc/html/RM_H5E.html +++ b/doc/html/RM_H5E.html @@ -61,8 +61,7 @@ And in this document, the </td></tr> </table> </center> -<hr> -<!-- #EndLibraryItem --><center> +<hr><!-- #EndLibraryItem --><center> <h1>H5E: Error Interface</h1> </center> @@ -194,42 +193,31 @@ errors within the H5E package. <!-- NEW PAGE --> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Eset_auto" --> +<!-- HEADER RIGHT "H5Eclear" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Error-SetAuto">H5Eset_auto</a> +<dt><strong>Name:</strong> <a name="Error-Clear">H5Eclear</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Eset_auto</code>(<em>H5E_auto_t</em> <code>func</code>, - <em>void *</em><code>client_data</code> - ) + <dd><em>herr_t</em> <code>H5Eclear</code>(<code>void</code>) <dt><strong>Purpose:</strong> - <dd>Turns automatic error printing on or off. + <dd>Clears the error stack for the current thread. <dt><strong>Description:</strong> - <dd><code>H5Eset_auto</code> turns on or off automatic printing of - errors. When turned on (non-null <code>func</code> pointer), - any API function which returns an error indication will - first call <code>func</code>, passing it <code>client_data</code> - as an argument. + <dd><code>H5Eclear</code> clears the error stack for the current thread. <p> - When the library is first initialized the auto printing function - is set to <code>H5Eprint</code> (cast appropriately) and - <code>client_data</code> is the standard error stream pointer, - <code>stderr</code>. + The stack is also cleared whenever an API function is called, + with certain exceptions (for instance, <code>H5Eprint</code>). <p> - Automatic stack traversal is always in the - <code>H5E_WALK_DOWNWARD</code> direction. + <code>H5Eclear</code> can fail if there are problems initializing + the library. <dt><strong>Parameters:</strong> <dl> - <dt><em>H5E_auto_t</em> <code>func</code> - <dd>IN: Function to be called upon an error condition. - <dt><em>void *</em><code>client_data</code> - <dd>IN: Data passed to the error function. + <dt>None </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/h5e_FORTRAN.html#h5eset_auto_f" + <dd><a href="fortran/h5e_FORTRAN.html#h5eclear_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -277,31 +265,94 @@ errors within the H5E package. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Eclear" --> +<!-- HEADER RIGHT "H5Eget_major" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Error-Clear">H5Eclear</a> +<dt><strong>Name:</strong> <a name="Error-GetMajor">H5Eget_major</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Eclear</code>(<code>void</code>) + <dd><em>const char *</em> <code>H5Eget_major</code>(<em>H5E_major_t</em> <code>n</code>) <dt><strong>Purpose:</strong> - <dd>Clears the error stack for the current thread. + <dd>Returns a character string describing an error specified by a + major error number. <dt><strong>Description:</strong> - <dd><code>H5Eclear</code> clears the error stack for the current thread. - <p> - The stack is also cleared whenever an API function is called, - with certain exceptions (for instance, <code>H5Eprint</code>). + <dd>Given a major error number, <code>H5Eget_major</code> returns a + constant character string that describes the error. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5E_major_t</em> <code>n</code> + <dd>IN: Major error number. + </dl> +<dt><strong>Returns:</strong> + <dd> Returns a character string describing the error if successful. + Otherwise returns "Invalid major error number." +<dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5e_FORTRAN.html#h5eget_major_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 "H5Eget_minor" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Error-GetMinor">H5Eget_minor</a> +<dt><strong>Signature:</strong> + <dd><em>const char *</em> <code>H5Eget_minor</code>(<em>H5E_minor_t</em> <code>n</code>) +<dt><strong>Purpose:</strong> + <dd>Returns a character string describing an error specified by a + minor error number. +<dt><strong>Description:</strong> + <dd>Given a minor error number, <code>H5Eget_minor</code> returns a + constant character string that describes the error. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5E_minor_t</em> <code>n</code> + <dd>IN: Minor error number. + </dl> +<dt><strong>Returns:</strong> + <dd> Returns a character string describing the error if successful. + Otherwise returns "Invalid minor error number." +<dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5e_FORTRAN.html#h5eget_minor_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 "H5Eprint" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Error-Print">H5Eprint</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Eprint</code>(<em>FILE *</em> <code>stream</code>) +<dt><strong>Purpose:</strong> + <dd>Prints the error stack in a default manner. +<dt><strong>Description:</strong> + <dd><code>H5Eprint</code> prints the error stack on the specified + stream, <code>stream</code>. + Even if the error stack is empty, a one-line message will be printed: + <br> + <code>HDF5-DIAG: Error detected in thread 0.</code> <p> - <code>H5Eclear</code> can fail if there are problems initializing - the library. + <code>H5Eprint</code> is a convenience function for + <code>H5Ewalk</code> with a function that prints error messages. + Users are encouraged to write their own more specific error handlers. <dt><strong>Parameters:</strong> <dl> - <dt>None + <dt><em>FILE *</em> <code>stream</code> + <dd>IN: File pointer, or stderr if NULL. </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/h5e_FORTRAN.html#h5eclear_f" + <dd><a href="fortran/h5e_FORTRAN.html#h5eprint_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -368,34 +419,42 @@ errors within the H5E package. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Eprint" --> +<!-- HEADER RIGHT "H5Eset_auto" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Error-Print">H5Eprint</a> +<dt><strong>Name:</strong> <a name="Error-SetAuto">H5Eset_auto</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Eprint</code>(<em>FILE *</em> <code>stream</code>) + <dd><em>herr_t</em> <code>H5Eset_auto</code>(<em>H5E_auto_t</em> <code>func</code>, + <em>void *</em><code>client_data</code> + ) <dt><strong>Purpose:</strong> - <dd>Prints the error stack in a default manner. + <dd>Turns automatic error printing on or off. <dt><strong>Description:</strong> - <dd><code>H5Eprint</code> prints the error stack on the specified - stream, <code>stream</code>. - Even if the error stack is empty, a one-line message will be printed: - <br> - <code>HDF5-DIAG: Error detected in thread 0.</code> + <dd><code>H5Eset_auto</code> turns on or off automatic printing of + errors. When turned on (non-null <code>func</code> pointer), + any API function which returns an error indication will + first call <code>func</code>, passing it <code>client_data</code> + as an argument. <p> - <code>H5Eprint</code> is a convenience function for - <code>H5Ewalk</code> with a function that prints error messages. - Users are encouraged to write their own more specific error handlers. + When the library is first initialized the auto printing function + is set to <code>H5Eprint</code> (cast appropriately) and + <code>client_data</code> is the standard error stream pointer, + <code>stderr</code>. + <p> + Automatic stack traversal is always in the + <code>H5E_WALK_DOWNWARD</code> direction. <dt><strong>Parameters:</strong> <dl> - <dt><em>FILE *</em> <code>stream</code> - <dd>IN: File pointer, or stderr if NULL. + <dt><em>H5E_auto_t</em> <code>func</code> + <dd>IN: Function to be called upon an error condition. + <dt><em>void *</em><code>client_data</code> + <dd>IN: Data passed to the error 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/h5e_FORTRAN.html#h5eprint_f" + <dd><a href="fortran/h5e_FORTRAN.html#h5eset_auto_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -541,67 +600,6 @@ errors within the H5E package. --> </dl> -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Eget_major" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Error-GetMajor">H5Eget_major</a> -<dt><strong>Signature:</strong> - <dd><em>const char *</em> <code>H5Eget_major</code>(<em>H5E_major_t</em> <code>n</code>) -<dt><strong>Purpose:</strong> - <dd>Returns a character string describing an error specified by a - major error number. -<dt><strong>Description:</strong> - <dd>Given a major error number, <code>H5Eget_major</code> returns a - constant character string that describes the error. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>H5E_major_t</em> <code>n</code> - <dd>IN: Major error number. - </dl> -<dt><strong>Returns:</strong> - <dd> Returns a character string describing the error if successful. - Otherwise returns "Invalid major error number." -<dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5e_FORTRAN.html#h5eget_major_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 "H5Eget_minor" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Error-GetMinor">H5Eget_minor</a> -<dt><strong>Signature:</strong> - <dd><em>const char *</em> <code>H5Eget_minor</code>(<em>H5E_minor_t</em> <code>n</code>) -<dt><strong>Purpose:</strong> - <dd>Returns a character string describing an error specified by a - minor error number. -<dt><strong>Description:</strong> - <dd>Given a minor error number, <code>H5Eget_minor</code> returns a - constant character string that describes the error. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>H5E_minor_t</em> <code>n</code> - <dd>IN: Minor error number. - </dl> -<dt><strong>Returns:</strong> - <dd> Returns a character string describing the error if successful. - Otherwise returns "Invalid minor error number." -<dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5e_FORTRAN.html#h5eget_minor_f" - target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> - <!-- - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - - <!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr> <center> <table border=0 width=98%> @@ -635,14 +633,13 @@ 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 --><SCRIPT LANGUAGE="JAVASCRIPT"> <!-- -document.writeln("Last modified: 6 June 2003"); +document.writeln("Last modified: 3 October 2003"); --> </SCRIPT> diff --git a/doc/html/RM_H5F.html b/doc/html/RM_H5F.html index 04b0b97..c14c064 100644 --- a/doc/html/RM_H5F.html +++ b/doc/html/RM_H5F.html @@ -61,8 +61,7 @@ And in this document, the </td></tr> </table> </center> -<hr> -<!-- #EndLibraryItem --><center> +<hr><!-- #EndLibraryItem --><center> <h1>H5F: File Interface</h1> </center> @@ -183,98 +182,63 @@ facilitate moving easily between them.</i> <!-- NEW PAGE --> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Fopen" --> +<!-- HEADER RIGHT "H5Fclose" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="File-Open">H5Fopen</a> +<dt><strong>Name:</strong> <a name="File-Close">H5Fclose</a> <dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Fopen</code>(<em>const char *</em><code>name</code>, - <em>unsigned</em> <code>flags</code>, - <em>hid_t</em> <code>access_id</code> + <dd><em>herr_t </em><code>H5Fclose</code>(<em>hid_t</em> <code>file_id</code> ) <dt><strong>Purpose:</strong> - <dd>Opens an existing file. + <dd>Terminates access to an HDF5 file. <dt><strong>Description:</strong> - <dd><code>H5Fopen</code> opens an existing file and is the primary - function for accessing existing HDF5 files. - <p> - The parameter <code>access_id</code> is a file access property - list identifier or <code>H5P_DEFAULT</code> if the - default I/O access parameters are to be used - <p> - The <code>flags</code> argument determines whether writing - to an existing file will be allowed. - The file is opened with read and write permission if - <code>flags</code> is set to <code>H5F_ACC_RDWR</code>. - All flags may be combined with the bit-wise OR operator (`|') - to change the behavior of the file open call. - More complex behaviors of file access are controlled - through the file-access property list. + <dd><code>H5Fclose</code> terminates access to an HDF5 file + by flushing all data to storage and terminating access + to the file through <code>file_id</code>. <p> - The return value is a file identifier for the open file; - this file identifier should be closed by calling - <code>H5Fclose</code> when it is no longer needed. + If this is the last file identifier open for the file + and no other access identifier is open (e.g., a dataset + identifier, group identifier, or shared datatype identifier), + the file will be fully closed and access will end. <p> - - <b>Special case -- Multiple opens:</b> + <strong>Delayed close:</strong> <br> - A file can often be opened with a new <code>H5Fopen</code> - call without closing an already-open identifier established - in a previous <code>H5Fopen</code> or <code>H5Fcreate</code> - call. Each such <code>H5Fopen</code> call will return a - unique identifier and the file can be accessed through any - of these identifiers as long as the identifier remains valid. - In such multiply-opened cases, all the open calls should - use the same <code>flags</code> argument. - <p> - In some cases, such as files on a local Unix file system, - the HDF5 library can detect that a file is multiply opened and - will maintain coherent access among the file identifiers. + Note the following deviation from the above-described behavior. + If <code>H5Fclose</code> is called for a file but one or more + objects within the file remain open, those objects will remain + accessible until they are individually closed. + Thus, if the dataset <code>data_sample</code> is open when + <code>H5Fclose</code> is called for the file containing it, + <code>data_sample</code> will remain open and accessible + (including writable) until it is explicitely closed. + The file will be automatically closed once all objects in the + file have been closed. <p> - But in many other cases, such as parallel file systems or - networked file systems, it is not always possible to detect - multiple opens of the same physical file. - In such cases, HDF5 will treat the file identifiers - as though they are accessing different files and - will be unable to maintain coherent access. - Errors are likely to result in these cases. - While unlikely, the HDF5 library may not be able to detect, - and thus report, such errors. + Be warned, hoever, that there are circumstances where it is + not possible to delay closing a file. + For example, an MPI-IO file close is a collective call; all of + the processes that opened the file must close it collectively. + The file cannot be closed at some time in the future by each + process in an independent fashion. + Another example is that an application using an AFS token-based + file access privilage may destroy its AFS token after + <code>H5Fclose</code> has returned successfully. + This would make any future access to the file, or any object + within it, illegal. <p> - It is generally recommended that applications avoid - multiple opens of the same file. - + In such situations, applications must close all open objects + in a file before calling <code>H5Fclose</code>. + It is generally recommended to do so in all cases. <dt><strong>Parameters:</strong> <dl> - <dt><em>const char *</em><code>name</code> - <dd>IN: Name of the file to access. - <dt><em>unsigned</em> <code>flags</code> - <dd>IN: File access flags. Allowable values are: - <ul><dl> - <dt><code>H5F_ACC_RDWR</code> - <dd>Allow read and write access to file. - <dt><code>H5F_ACC_RDONLY</code> - <dd>Allow read-only access to file. - </dl> - <li><code>H5F_ACC_RDWR</code> and <code>H5F_ACC_RDONLY</code> - are mutually exclusive; use exactly one. - <li>An additional flag, <code>H5F_ACC_DEBUG</code>, prints - debug information. This flag is used only by HDF5 library - developers; it is neither tested nor supported - for use in applications. - </ul> - <dt><em>hid_t</em> <code>access_id</code> - <dd>IN: Identifier for the file access properties list. - If parallel file access is desired, this is a collective - call according to the communicator stored in the - <code>access_id</code>. - Use <code>H5P_DEFAULT</code> for default file access properties. + <dt><em>hid_t</em> <code>file_id</code> + <dd>IN: Identifier of a file to terminate access to. </dl> <dt><strong>Returns:</strong> - <dd>Returns a file identifier if successful; + <dd>Returns a non-negative value if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5f_FORTRAN.html#h5fopen_f" + <dd><a href="fortran/h5f_FORTRAN.html#h5fclose_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -448,37 +412,6 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Fis_hdf5" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="File-IsHDF5">H5Fis_hdf5</a> -<dt><strong>Signature:</strong> - <dd><em>htri_t </em><code>H5Fis_hdf5</code>(<em>const char *</em><code>name</code> - ) -<dt><strong>Purpose:</strong> - <dd>Determines whether a file is in the HDF5 format. -<dt><strong>Description:</strong> - <dd><code>H5Fis_hdf5</code> determines whether a file is in - the HDF5 format. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>const char *</em><code>name</code> - <dd>IN: File name to check format. - </dl> -<dt><strong>Returns:</strong> - <dd>When successful, returns a positive value, for <code>TRUE</code>, - or <code>0</code> (zero), for <code>FALSE</code>. - Otherwise returns a negative value. -<dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5f_FORTRAN.html#h5fis_hdf5_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 "H5Fget_access_plist" --> <hr> <dl> @@ -743,63 +676,29 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Fclose" --> +<!-- HEADER RIGHT "H5Fis_hdf5" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="File-Close">H5Fclose</a> +<dt><strong>Name:</strong> <a name="File-IsHDF5">H5Fis_hdf5</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Fclose</code>(<em>hid_t</em> <code>file_id</code> + <dd><em>htri_t </em><code>H5Fis_hdf5</code>(<em>const char *</em><code>name</code> ) <dt><strong>Purpose:</strong> - <dd>Terminates access to an HDF5 file. + <dd>Determines whether a file is in the HDF5 format. <dt><strong>Description:</strong> - <dd><code>H5Fclose</code> terminates access to an HDF5 file - by flushing all data to storage and terminating access - to the file through <code>file_id</code>. - <p> - If this is the last file identifier open for the file - and no other access identifier is open (e.g., a dataset - identifier, group identifier, or shared datatype identifier), - the file will be fully closed and access will end. - <p> - <strong>Delayed close:</strong> - <br> - Note the following deviation from the above-described behavior. - If <code>H5Fclose</code> is called for a file but one or more - objects within the file remain open, those objects will remain - accessible until they are individually closed. - Thus, if the dataset <code>data_sample</code> is open when - <code>H5Fclose</code> is called for the file containing it, - <code>data_sample</code> will remain open and accessible - (including writable) until it is explicitely closed. - The file will be automatically closed once all objects in the - file have been closed. - <p> - Be warned, hoever, that there are circumstances where it is - not possible to delay closing a file. - For example, an MPI-IO file close is a collective call; all of - the processes that opened the file must close it collectively. - The file cannot be closed at some time in the future by each - process in an independent fashion. - Another example is that an application using an AFS token-based - file access privilage may destroy its AFS token after - <code>H5Fclose</code> has returned successfully. - This would make any future access to the file, or any object - within it, illegal. - <p> - In such situations, applications must close all open objects - in a file before calling <code>H5Fclose</code>. - It is generally recommended to do so in all cases. + <dd><code>H5Fis_hdf5</code> determines whether a file is in + the HDF5 format. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>file_id</code> - <dd>IN: Identifier of a file to terminate access to. + <dt><em>const char *</em><code>name</code> + <dd>IN: File name to check format. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. + <dd>When successful, returns a positive value, for <code>TRUE</code>, + or <code>0</code> (zero), for <code>FALSE</code>. + Otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5f_FORTRAN.html#h5fclose_f" + <dd><a href="fortran/h5f_FORTRAN.html#h5fis_hdf5_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -855,44 +754,98 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Funmount" --> +<!-- HEADER RIGHT "H5Fopen" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="File-Unmount">H5Funmount</a> +<dt><strong>Name:</strong> <a name="File-Open">H5Fopen</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Funmount</code>(<em>hid_t</em> <code>loc_id</code>, - <em>const char *</em><code>name</code> + <dd><em>hid_t </em><code>H5Fopen</code>(<em>const char *</em><code>name</code>, + <em>unsigned</em> <code>flags</code>, + <em>hid_t</em> <code>access_id</code> ) <dt><strong>Purpose:</strong> - <dd>Unmounts a file. + <dd>Opens an existing file. <dt><strong>Description:</strong> - <dd>Given a mount point, <code>H5Funmount</code> - dissassociates the mount point's file - from the file mounted there. This function - does not close either file. - <p> - The mount point can be either the group in the - parent or the root group of the mounted file - (both groups have the same name). If the mount - point was opened before the mount then it is the - group in the parent; if it was opened after the - mount then it is the root group of the child. + <dd><code>H5Fopen</code> opens an existing file and is the primary + function for accessing existing HDF5 files. <p> - Note that <code>loc_id</code> is either a file or group identifier - and <code>name</code> is relative to <code>loc_id</code>. + The parameter <code>access_id</code> is a file access property + list identifier or <code>H5P_DEFAULT</code> if the + default I/O access parameters are to be used + <p> + The <code>flags</code> argument determines whether writing + to an existing file will be allowed. + The file is opened with read and write permission if + <code>flags</code> is set to <code>H5F_ACC_RDWR</code>. + All flags may be combined with the bit-wise OR operator (`|') + to change the behavior of the file open call. + More complex behaviors of file access are controlled + through the file-access property list. + <p> + The return value is a file identifier for the open file; + this file identifier should be closed by calling + <code>H5Fclose</code> when it is no longer needed. + <p> + + <b>Special case -- Multiple opens:</b> + <br> + A file can often be opened with a new <code>H5Fopen</code> + call without closing an already-open identifier established + in a previous <code>H5Fopen</code> or <code>H5Fcreate</code> + call. Each such <code>H5Fopen</code> call will return a + unique identifier and the file can be accessed through any + of these identifiers as long as the identifier remains valid. + In such multiply-opened cases, all the open calls should + use the same <code>flags</code> argument. + <p> + In some cases, such as files on a local Unix file system, + the HDF5 library can detect that a file is multiply opened and + will maintain coherent access among the file identifiers. + <p> + But in many other cases, such as parallel file systems or + networked file systems, it is not always possible to detect + multiple opens of the same physical file. + In such cases, HDF5 will treat the file identifiers + as though they are accessing different files and + will be unable to maintain coherent access. + Errors are likely to result in these cases. + While unlikely, the HDF5 library may not be able to detect, + and thus report, such errors. + <p> + It is generally recommended that applications avoid + multiple opens of the same file. + <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>loc_id</code> - <dd>IN: File or group identifier for the location at which - the specified file is to be unmounted. <dt><em>const char *</em><code>name</code> - <dd>IN: Name of the mount point. + <dd>IN: Name of the file to access. + <dt><em>unsigned</em> <code>flags</code> + <dd>IN: File access flags. Allowable values are: + <ul><dl> + <dt><code>H5F_ACC_RDWR</code> + <dd>Allow read and write access to file. + <dt><code>H5F_ACC_RDONLY</code> + <dd>Allow read-only access to file. + </dl> + <li><code>H5F_ACC_RDWR</code> and <code>H5F_ACC_RDONLY</code> + are mutually exclusive; use exactly one. + <li>An additional flag, <code>H5F_ACC_DEBUG</code>, prints + debug information. This flag is used only by HDF5 library + developers; it is neither tested nor supported + for use in applications. + </ul> + <dt><em>hid_t</em> <code>access_id</code> + <dd>IN: Identifier for the file access properties list. + If parallel file access is desired, this is a collective + call according to the communicator stored in the + <code>access_id</code>. + Use <code>H5P_DEFAULT</code> for default file access properties. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; + <dd>Returns a file identifier if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5f_FORTRAN.html#h5funmount_f" + <dd><a href="fortran/h5f_FORTRAN.html#h5fopen_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -945,6 +898,54 @@ facilitate moving easily between them.</i> --> </dl> +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Funmount" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="File-Unmount">H5Funmount</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Funmount</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code> + ) +<dt><strong>Purpose:</strong> + <dd>Unmounts a file. +<dt><strong>Description:</strong> + <dd>Given a mount point, <code>H5Funmount</code> + dissassociates the mount point's file + from the file mounted there. This function + does not close either file. + <p> + The mount point can be either the group in the + parent or the root group of the mounted file + (both groups have the same name). If the mount + point was opened before the mount then it is the + group in the parent; if it was opened after the + mount then it is the root group of the child. + <p> + Note that <code>loc_id</code> is either a file or group identifier + and <code>name</code> is relative to <code>loc_id</code>. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: File or group identifier for the location at which + the specified file is to be unmounted. + <dt><em>const char *</em><code>name</code> + <dd>IN: Name of the mount point. + </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/h5f_FORTRAN.html#h5funmount_f" + target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> + <!-- + <img src="Graphics/Java.gif"> + <img src="Graphics/C++.gif"> + --> +</dl> + + + <!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr> <center> @@ -979,14 +980,13 @@ 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 --><SCRIPT LANGUAGE="JAVASCRIPT"> <!-- -document.writeln("Last modified: 6 June 2003"); +document.writeln("Last modified: 3 October 2003"); --> </SCRIPT> diff --git a/doc/html/RM_H5G.html b/doc/html/RM_H5G.html index 88cfd61..88fa534 100644 --- a/doc/html/RM_H5G.html +++ b/doc/html/RM_H5G.html @@ -61,8 +61,7 @@ And in this document, the </td></tr> </table> </center> -<hr> -<!-- #EndLibraryItem --><center> +<hr><!-- #EndLibraryItem --><center> <h1>H5G: Group Interface</h1> </center> @@ -213,6 +212,41 @@ create or access function. <!-- NEW PAGE --> <!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Gclose" --> +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Close">H5Gclose</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Gclose</code>(<em>hid_t </em><code>group_id</code>) + <dt><strong>Purpose:</strong> + <dd>Closes the specified group. + <dt><strong>Description:</strong> + <dd><code>H5Gclose</code> releases resources used by a group which was + opened by <code>H5Gcreate</code> or <code>H5Gopen</code>. + After closing a group, the <code>group_id</code> cannot be used again. + <p> + Failure to release a group with this call will result in resource leaks. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>group_id</code> + <dd>IN: Group identifier to release. + </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/h5g_FORTRAN.html#h5gclose_f" target="FortWin" onClick="window.open("fortran/h5g_FORTRAN.html#h5gclose_f","FortWin&nquot;,"toolbar=0,location=0,directories=0,status=0,menubar=0,scrollbars=yes,resizable=1,width=500,height=250,titlebar=yes")"><img src="Graphics/FORTRAN.gif"></a> +--> + <dd><a href="fortran/h5g_FORTRAN.html#h5gclose_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 "H5Gcreate" --> <hr> <dl> @@ -273,203 +307,49 @@ create or access function. --> </dl> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Gopen" --> -<hr> -<dl> - <dt><strong>Name:</strong> <a name="Group-Open">H5Gopen</a> - <dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Gopen</code>(<em>hid_t</em> <code>loc_id</code>, - <em>const char *</em><code>name</code> - ) - <dt><strong>Purpose:</strong> - <dd>Opens an existing group for modification and returns a group - identifier for that group. - <dt><strong>Description:</strong> - <dd><code>H5Gopen</code> opens an existing group with the specified - name at the specified location, <code>loc_id</code>. - <p> - The location is identified by a file or group identifier - <p> - <code>H5Gopen</code> returns a group identifier for the group - that was opened. This group identifier should be released by - calling <code>H5Gclose</code> when it is no longer needed. - <dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>loc_id</code> - <dd>IN: File or group identifier within which group is to be open. - <dt><em>const char *</em> <code>name</code> - <dd>IN: Name of group to open. - </dl> - <dt><strong>Returns:</strong> - <dd>Returns a valid group identifier if successful; - otherwise returns a negative value. - <dt><strong>Non-C API(s):</strong> -<!-- - <dd><a href="fortran/h5g_FORTRAN.html#h5gopen_f" target="FortWin" onClick="window.open("fortran/h5g_FORTRAN.html#h5gopen_f","FortWin&nquot;,"toolbar=0,location=0,directories=0,status=0,menubar=0,scrollbars=yes,resizable=1,width=500,height=250,titlebar=yes")"><img src="Graphics/FORTRAN.gif"></a> ---> - <dd><a href="fortran/h5g_FORTRAN.html#h5gopen_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 "H5Gclose" --> -<hr> -<dl> - <dt><strong>Name:</strong> <a name="Group-Close">H5Gclose</a> - <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Gclose</code>(<em>hid_t </em><code>group_id</code>) - <dt><strong>Purpose:</strong> - <dd>Closes the specified group. - <dt><strong>Description:</strong> - <dd><code>H5Gclose</code> releases resources used by a group which was - opened by <code>H5Gcreate</code> or <code>H5Gopen</code>. - After closing a group, the <code>group_id</code> cannot be used again. - <p> - Failure to release a group with this call will result in resource leaks. - <dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>group_id</code> - <dd>IN: Group identifier to release. - </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/h5g_FORTRAN.html#h5gclose_f" target="FortWin" onClick="window.open("fortran/h5g_FORTRAN.html#h5gclose_f","FortWin&nquot;,"toolbar=0,location=0,directories=0,status=0,menubar=0,scrollbars=yes,resizable=1,width=500,height=250,titlebar=yes")"><img src="Graphics/FORTRAN.gif"></a> ---> - <dd><a href="fortran/h5g_FORTRAN.html#h5gclose_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 "H5Glink" --> +<!-- HEADER RIGHT "H5Gget_comment" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Group-Link">H5Glink</a> + <dt><strong>Name:</strong> <a name="Group-GetComment">H5Gget_comment</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Glink</code>(<em>hid_t</em> <code>loc_id</code>, - <em>H5G_link_t</em> <code>link_type</code>, - <em>const char *</em><code>current_name</code>, - <em>const char *</em><code>new_name</code> + <dd><em>herr_t</em> <code>H5Gget_comment</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code>, + <em>size_t</em> <code>bufsize</code>, + <em>char *</em><code>comment</code> ) <dt><strong>Purpose:</strong> - <dd>Creates a link of the specified type from <code>new_name</code> - to <code>current_name</code>. + <dd>Retrieves comment for specified object. <dt><strong>Description:</strong> - <dd><code>H5Glink</code> creates a new name for an object that has some current - name, possibly one of many names it currently has. + <dd><code>H5Gget_comment</code> retrieves the comment for the the + object <code>name</code>. The comment is returned in the buffer + <code>comment</code>. <p> - If <code>link_type</code> is <code>H5G_LINK_HARD</code>, then - <code>current_name</code> must specify the name of an - existing object and both - names are interpreted relative to <code>loc_id</code>, which is - either a file identifier or a group identifier. + At most <code>bufsize</code> characters, including a null + terminator, are copied. The result is not null terminated + if the comment is longer than the supplied buffer. <p> - If <code>link_type</code> is <code>H5G_LINK_SOFT</code>, then - <code>current_name</code> can be anything and is interpreted at - lookup time relative to the group which contains the final - component of <code>new_name</code>. For instance, if - <code>current_name</code> is <code>./foo</code>, - <code>new_name</code> is <code>./x/y/bar</code>, and a request - is made for <code>./x/y/bar</code>, then the actual object looked - up is <code>./x/y/./foo</code>. + If an object does not have a comment, the empty string + is returned. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>loc_id</code> - <dd>IN: File or group identifier. - <dt><em>H5G_link_t</em> <code>link_type</code> - <dd>IN: Link type. - Possible values are <code>H5G_LINK_HARD</code> and - <code>H5G_LINK_SOFT</code>. - <dt><em>const char *</em> <code>current_name</code> - <dd>IN: Name of the existing object if link is a hard link. - Can be anything for the soft link. - <dt><em>const char *</em> <code>new_name</code> - <dd>IN: New name for the 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/h5g_FORTRAN.html#h5glink_f" target="FortWin" onClick="window.open("fortran/h5g_FORTRAN.html#h5glink_f","FortWin&nquot;,"toolbar=0,location=0,directories=0,status=0,menubar=0,scrollbars=yes,resizable=1,width=500,height=250,titlebar=yes")"><img src="Graphics/FORTRAN.gif"></a> ---> - <dd><a href="fortran/h5g_FORTRAN.html#h5glink_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 "H5Glink2" --> -<hr> -<dl> - <dt><strong>Name:</strong> <a name="Group-Link2">H5Glink2</a> - <dt><strong>Signature:</strong> - - <dd><em>herr_t</em> <code>H5Glink2</code>( - <em>hid_t</em> <code>curr_loc_id</code>, <em>const char *</em><code>current_name</code>, - <em>H5G_link_t</em> <code>link_type</code>, - <em>hid_t</em> <code>new_loc_id</code>, <em>const char *</em><code>new_name</code> ) - <dt><strong>Purpose:</strong> - <dd>Creates a link of the specified type from <code>new_name</code> - to <code>current_name</code>. - <dt><strong>Description:</strong> - - <dd><code>H5Glink2</code> creates a new name for an object that has some current - name, possibly one of many names it currently has. - <p> - If <code>link_type</code> is <code>H5G_LINK_HARD</code>, then <code>current_name</code> - must specify the name of an existing object. - In this case, <code>current_name</code> and <code>new_name</code> are interpreted - relative to <code>curr_loc_id</code> and <code>new_loc_id</code>, respectively, - which are either file or group identifiers. - <p> - If <code>link_type</code> is <code>H5G_LINK_SOFT</code>, then - <code>current_name</code> can be anything and is interpreted at - lookup time relative to the group which contains the final - component of <code>new_name</code>. For instance, if - <code>current_name</code> is <code>./foo</code>, - <code>new_name</code> is <code>./x/y/bar</code>, and a request - is made for <code>./x/y/bar</code>, then the actual object looked - up is <code>./x/y/./foo</code>. - <dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>curr_loc_id</code> - <dd>IN: The file or group identifier for the original object. - <dt><em>const char *</em> <code>current_name</code> - <dd>IN: Name of the existing object if link is a hard link. - Can be anything for the soft link. - <dt><em>H5G_link_t</em> <code>link_type</code> - <dd>IN: Link type. - Possible values are <code>H5G_LINK_HARD</code> and - <code>H5G_LINK_SOFT</code>. - <dt><em>hid_t</em> <code>new_loc_id</code> - <dd>IN: The file or group identifier for the new link. - <dt><em>const char *</em> <code>new_name</code> - <dd>IN: New name for the object. + <dd>IN: Identifier of the file or group. + <dt><em>const char *</em><code>name</code> + <dd>IN: Name of the object whose comment is to be set or reset. + <dt><em>size_t</em> <code>bufsize</code> + <dd>IN: Anticipated size of the buffer required to hold + <code>comment</code>. + <dt><em>char *</em><code>comment</code> + <dd>OUT: The comment. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. + <dd>Returns the number of characters in the comment, + counting the null terminator, if successful; the value + returned may be larger than <code>bufsize</code>. + Otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> -<!-- - <dd><a href="fortran/h5g_FORTRAN.html#h5glink_f" target="FortWin" onClick="window.open("fortran/h5g_FORTRAN.html#h5glink_f","FortWin&nquot;,"toolbar=0,location=0,directories=0,status=0,menubar=0,scrollbars=yes,resizable=1,width=500,height=250,titlebar=yes")"><img src="Graphics/FORTRAN.gif"></a> ---> - <dd><a href="fortran/h5g_FORTRAN.html#h5glink2_f" + <dd><a href="fortran/h5g_FORTRAN.html#h5gget_comment_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -478,206 +358,54 @@ create or access function. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Gunlink" --> +<!-- HEADER RIGHT "H5Gget_linkval" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Group-Unlink">H5Gunlink</a> + <dt><strong>Name:</strong> <a name="Group-GetLinkval">H5Gget_linkval</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Gunlink</code>(<em>hid_t</em> <code>loc_id</code>, - <em>const char *</em><code>name</code> + <dd><em>herr_t</em> <code>H5Gget_linkval</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code>, + <em>size_t</em> <code>size</code>, + <em>char *</em><code>value</code> ) <dt><strong>Purpose:</strong> - <dd>Removes the link to an object from a group. + <dd>Returns the name of the object that the symbolic link points to. <dt><strong>Description:</strong> - <dd><code>H5Gunlink</code> removes the object specified by - <code>name</code> from the group graph and decrements the - link count for the object to which <code>name</code> points. - This action eliminates any association between <code>name</code> - and the object to which <code>name</code> pointed. - <p> - Object headers keep track of how many hard links refer to an object; - when the link count reaches zero, the object can be removed - from the file. Objects which are open are not removed until all - identifiers to the object are closed. - <p> - If the link count reaches zero, all file space associated with - the object will be released, i.e., identified in memory as freespace. - If the any object identifier is open for the object, the space - will not be released until after the object identifier is closed. + <dd><code>H5Gget_linkval</code> returns <code>size</code> + characters of the name of the object that the symbolic link <code>name</code> points to. <p> - Note that space identified as freespace is available for re-use - only as long as the file remains open; once a file has been - closed, the HDF5 library loses track of freespace. See - “<a href="Performance.html#Freespace">Freespace Management</a>” - in the <cite>HDF5 User's Guide</cite> for further details. - <dt><strong>Warning:</strong> - <dd>Exercise care in unlinking groups as it is possible to render data in - a file inaccessible with <code>H5Gunlink</code>. - See <a href="Groups.html#H5GUnlinkToCorrupt">The Group Interface</a> - in the <cite>HDF5 User's Guide</cite>. - <dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>loc_id</code> - <dd>IN: Identifier of the file or group containing the object. - <dt><em>const char *</em> <code>name</code> - <dd>IN: Name of the object to unlink. - </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/h5g_FORTRAN.html#h5gunlink_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 "H5Giterate" --> -<hr> -<dl> - <dt><strong>Name:</strong> <a name="Group-Iterate">H5Giterate</a> - <dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Giterate</code>(<em>hid_t</em> <code>loc_id</code>, - <em>const char</em> <code>*name</code>, - <em>int</em> <code>*idx</code>, - <em>H5G_iterate_t</em> <code>operator</code>, - <em>void</em> <code>*operator_data</code> - ) - <dt><strong>Purpose:</strong> - <dd>Iterates an operation over the entries of a group. - <dt><strong>Description:</strong> - <dd><code>H5Giterate</code> iterates over the members of - <code>name</code> in the file or group specified with - <code>loc_id</code>. - For each object in the group, the <code>operator_data</code> - and some additional information, specified below, are - passed to the <code>operator</code> function. - The iteration begins with the <code>idx</code> object in the - group and the next element to be processed by the operator is - returned in <code>idx</code>. If <code>idx</code> - is NULL, then the iterator starts at the first group member; - since no stopping point is returned in this case, the iterator - cannot be restarted if one of the calls to its operator returns - non-zero. + The parameter <code>loc_id</code> is a file or group identifier. <p> - The prototype for <code>H5G_iterate_t</code> is: - <ul><dl> - <dd><code>typedef</code> <em>herr_t </em>(*<code>H5G_iterate_t</code>)(<em>hid_t</em> <code>group_id</code>, - <em>const char *</em><code>member_name</code>, - <em>void *</em><code>operator_data</code>); - </dl></ul> - <dd>The operation receives the group identifier for the group being - iterated over, <code>group_id</code>, the name of the current - object within the group, <code>member_name</code>, and the - pointer to the operator data passed in to <code>H5Giterate</code>, - <code>operator_data</code>. + The parameter <code>name</code> must be a symbolic link pointing to + the desired object and must be defined relative to <code>loc_id</code>. <p> - The return values from an operator are: - <ul> - <li>Zero causes the iterator to continue, returning - zero when all group members have been processed. - <li>Positive causes the iterator to immediately return that positive - value, indicating short-circuit success. The iterator can be - restarted at the next group member. - <li>Negative causes the iterator to immediately return that value, - indicating failure. The iterator can be restarted at the next - group member. - </ul> + If <code>size</code> is smaller than the size of the returned object name, then + the name stored in the buffer <code>value</code> will not be null terminated. + <p> + This function fails if <code>name</code> is not a symbolic link. + The presence of a symbolic link can be tested by passing zero for + <code>size</code> and NULL for <code>value</code>. <p> - <code>H5Giterate</code> assumes that the membership of the group - identified by <code>name</code> remains unchanged through the - iteration. If the membership changes during the iteration, - the function's behavior is undefined. + This function should be used only after <code>H5Gget_objinfo</code> has been called + to verify that <code>name</code> is a symbolic link. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>loc_id</code> - <dd>IN: File or group identifier. - <dt><em>const char</em> <code>*name</code> - <dd>IN: Group over which the iteration is performed. - <dt><em>int</em> <code>*idx</code> - <dd>IN/OUT: Location at which to begin the iteration. - <dt><em>H5G_iterate_t</em> <code>operator</code> - <dd>IN: Operation to be performed on an object at each step of - the iteration. - <dt><em>void</em> <code>*operator_data</code> - <dd>IN/OUT: Data associated with the operation. + <dd>IN: Identifier of the file or group. + <dt><em>const char *</em><code>name</code> + <dd>IN: Symbolic link to the object whose name is to be returned. + <dt><em>size_t</em> <code>size</code> + <dd>IN: Maximum number of characters of <code>value</code> + to be returned. + <dt><em>char *</em><code>value</code> + <dd>OUT: A buffer to hold the name of the object being sought. </dl> <dt><strong>Returns:</strong> - <dd>Returns the return value of the last operator if it was non-zero, - or zero if all group members were processed. + <dd>Returns a non-negative value, with the link value in <code>value</code>, + if successful. Otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd>There is no direct FORTRAN couterpart for the C function - <code>H5Giterate</code>. - Instead, that functionality is provided by two FORTRAN functions: - <center> - <table width=80%> - <tr valign=top align=left> - <td> - <a href="fortran/h5g_FORTRAN.html#h5gn_members_f" - target="FortranWin"><code>h5gn_members_f</code></a>. - </td><td> </td><td> - <strong>Purpose:</strong> - Returns the number of group members. - </tr><tr valign=top align=left> - <td> - <a href="fortran/h5g_FORTRAN.html#h5gget_obj_info_idx_f" - target="FortranWin"><code>h5gget_obj_info_idx_f</code></a> - </td><td> </td><td> - <strong>Purpose:</strong> - Returns name and type of the group member identified by its index. - </td> - </table> - </center> - <dd><a href="fortran/h5g_FORTRAN.html#h5gn_members_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 "H5Gmove" --> -<hr> -<dl> - <dt><strong>Name:</strong> <a name="Group-Move">H5Gmove</a> - <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Gmove</code>(<em>hid_t</em> <code>loc_id</code>, - <em>const char</em> <code>*src_name</code>, - <em>const char</em> <code>*dst_name</code> - ) - <dt><strong>Purpose:</strong> - <dd>Renames an object within an HDF5 file. - <dt><strong>Description:</strong> - <dd><code>H5Gmove</code> renames an object within an HDF5 file. - The original name, <code>src_name</code>, is unlinked from the - group graph and the new name, <code>dst_name</code>, is inserted - as an atomic operation. Both names are interpreted relative - to <code>loc_id</code>, which is either a file or a group - identifier. - <dt><strong>Warning:</strong> - <dd>Exercise care in moving groups as it is possible to render data in - a file inaccessible with <code>H5Gmove</code>. - See <a href="Groups.html#H5GUnlinkToCorrupt">The Group Interface</a> - in the <cite>HDF5 User's Guide</cite>. - <dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>loc_id</code> - <dd>IN: File or group identifier. - <dt><em>const char</em> <code>*src_name</code> - <dd>IN: Object's original name. - <dt><em>const char</em> <code>*dst_name</code> - <dd>IN: Object's new name. - </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/h5g_FORTRAN.html#h5gmove_f" + <dd><a href="fortran/h5g_FORTRAN.html#h5gget_linkval_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -686,49 +414,30 @@ create or access function. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Gmove2" --> +<!-- HEADER RIGHT "H5Gget_num_objs" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Group-Move2">H5Gmove2</a> - <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Gmove2</code>( <em>hid_t</em> <code>src_loc_id</code>, - <em>const char</em> <code>*src_name</code>, <em>hid_t</em> <code>dst_loc_id</code>, - <em>const char</em> <code>*dst_name</code> ) - <dt><strong>Purpose:</strong> - <dd>Renames an object within an HDF5 file. - <dt><strong>Description:</strong> - <dd><code>H5Gmove2</code> renames an object within an HDF5 file. The original - name, <code>src_name</code>, is unlinked from the group graph and the new - name, <code>dst_name</code>, is inserted as an atomic operation. - <p> - </p><code>src_name</code> and <code>dst_name</code> are interpreted relative to - <code>src_name</code> and <code>dst_name</code>, respectively, - which are either file or group identifiers. - <dt><strong>Warning:</strong> - <dd>Exercise care in moving groups as it is possible to render data in a file - inaccessible with <code>H5Gmove</code>. See <a href="Groups.html#H5GUnlinkToCorrupt">The - Group Interface</a> in the <cite>HDF5 User's Guide</cite>. - <dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>src_loc_id</code> - <dd>IN: Original file or group identifier. - <dt><em>const char</em> <code>*src_name</code> - <dd>IN: Object's original name. - <dt><em>hid_t</em> <code>dst_loc_id</code> - <dd>IN: Destination file or group identifier. - <dt><em>const char</em> <code>*dst_name</code> - <dd>IN: Object's new name. - </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/h5g_FORTRAN.html#h5gmove2_f" - target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> - <!-- - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> +<dt><strong>Name:</strong> <a name="Group-GetNumObjs">H5Gget_num_objs</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Gget_num_objs</code>(<em>hid_t</em> <code>loc_id</code>, + <em>hsize_t* </em> <code>num_obj</code>) +<dt><strong>Purpose:</strong> + <dd>Returns number of objects in the group specified by its identifier +<dt><strong>Description:</strong> + <dd><code>H5Gget_num_objs</code> returns number of objects in a group. + Group is specified by its identifier <code>loc_id</code>. + If file identifier is passed in, then number of objects in the + root group is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: Identifier of the group or the file + <dt><em>hsize_t*</em> <code>num_obj</code> + <dd>OUT: Number of objects in the group. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns positive value if successful; + otherwise returns a negative value. </dl> <!-- NEW PAGE --> @@ -830,43 +539,6 @@ create or access function. --> </dl> - - - - - - - - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Gget_num_objs" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Group-GetNumObjs">H5Gget_num_objs</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Gget_num_objs</code>(<em>hid_t</em> <code>loc_id</code>, - <em>hsize_t* </em> <code>num_obj</code>) -<dt><strong>Purpose:</strong> - <dd>Returns number of objects in the group specified by its identifier -<dt><strong>Description:</strong> - <dd><code>H5Gget_num_objs</code> returns number of objects in a group. - Group is specified by its identifier <code>loc_id</code>. - If file identifier is passed in, then number of objects in the - root group is returned. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>loc_id</code> - <dd>IN: Identifier of the group or the file - <dt><em>hsize_t*</em> <code>num_obj</code> - <dd>OUT: Number of objects in the group. - </dl> -<dt><strong>Returns:</strong> - <dd>Returns positive value if successful; - otherwise returns a negative value. -</dl> - - - <!-- NEW PAGE --> <!-- HEADER RIGHT "H5Gget_objname_by_idx" --> <hr> @@ -1006,62 +678,105 @@ create or access function. Otherwise returns a negative value. </dl> - - - - - - - <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Gget_linkval" --> +<!-- HEADER RIGHT "H5Giterate" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Group-GetLinkval">H5Gget_linkval</a> + <dt><strong>Name:</strong> <a name="Group-Iterate">H5Giterate</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Gget_linkval</code>(<em>hid_t</em> <code>loc_id</code>, - <em>const char *</em><code>name</code>, - <em>size_t</em> <code>size</code>, - <em>char *</em><code>value</code> + <dd><em>int</em> <code>H5Giterate</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char</em> <code>*name</code>, + <em>int</em> <code>*idx</code>, + <em>H5G_iterate_t</em> <code>operator</code>, + <em>void</em> <code>*operator_data</code> ) <dt><strong>Purpose:</strong> - <dd>Returns the name of the object that the symbolic link points to. + <dd>Iterates an operation over the entries of a group. <dt><strong>Description:</strong> - <dd><code>H5Gget_linkval</code> returns <code>size</code> - characters of the name of the object that the symbolic link <code>name</code> points to. - <p> - The parameter <code>loc_id</code> is a file or group identifier. + <dd><code>H5Giterate</code> iterates over the members of + <code>name</code> in the file or group specified with + <code>loc_id</code>. + For each object in the group, the <code>operator_data</code> + and some additional information, specified below, are + passed to the <code>operator</code> function. + The iteration begins with the <code>idx</code> object in the + group and the next element to be processed by the operator is + returned in <code>idx</code>. If <code>idx</code> + is NULL, then the iterator starts at the first group member; + since no stopping point is returned in this case, the iterator + cannot be restarted if one of the calls to its operator returns + non-zero. <p> - The parameter <code>name</code> must be a symbolic link pointing to - the desired object and must be defined relative to <code>loc_id</code>. + The prototype for <code>H5G_iterate_t</code> is: + <ul><dl> + <dd><code>typedef</code> <em>herr_t </em>(*<code>H5G_iterate_t</code>)(<em>hid_t</em> <code>group_id</code>, + <em>const char *</em><code>member_name</code>, + <em>void *</em><code>operator_data</code>); + </dl></ul> + <dd>The operation receives the group identifier for the group being + iterated over, <code>group_id</code>, the name of the current + object within the group, <code>member_name</code>, and the + pointer to the operator data passed in to <code>H5Giterate</code>, + <code>operator_data</code>. <p> - If <code>size</code> is smaller than the size of the returned object name, then - the name stored in the buffer <code>value</code> will not be null terminated. - <p> - This function fails if <code>name</code> is not a symbolic link. - The presence of a symbolic link can be tested by passing zero for - <code>size</code> and NULL for <code>value</code>. + The return values from an operator are: + <ul> + <li>Zero causes the iterator to continue, returning + zero when all group members have been processed. + <li>Positive causes the iterator to immediately return that positive + value, indicating short-circuit success. The iterator can be + restarted at the next group member. + <li>Negative causes the iterator to immediately return that value, + indicating failure. The iterator can be restarted at the next + group member. + </ul> <p> - This function should be used only after <code>H5Gget_objinfo</code> has been called - to verify that <code>name</code> is a symbolic link. + <code>H5Giterate</code> assumes that the membership of the group + identified by <code>name</code> remains unchanged through the + iteration. If the membership changes during the iteration, + the function's behavior is undefined. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>loc_id</code> - <dd>IN: Identifier of the file or group. - <dt><em>const char *</em><code>name</code> - <dd>IN: Symbolic link to the object whose name is to be returned. - <dt><em>size_t</em> <code>size</code> - <dd>IN: Maximum number of characters of <code>value</code> - to be returned. - <dt><em>char *</em><code>value</code> - <dd>OUT: A buffer to hold the name of the object being sought. + <dd>IN: File or group identifier. + <dt><em>const char</em> <code>*name</code> + <dd>IN: Group over which the iteration is performed. + <dt><em>int</em> <code>*idx</code> + <dd>IN/OUT: Location at which to begin the iteration. + <dt><em>H5G_iterate_t</em> <code>operator</code> + <dd>IN: Operation to be performed on an object at each step of + the iteration. + <dt><em>void</em> <code>*operator_data</code> + <dd>IN/OUT: Data associated with the operation. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value, with the link value in <code>value</code>, - if successful. + <dd>Returns the return value of the last operator if it was non-zero, + or zero if all group members were processed. Otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5g_FORTRAN.html#h5gget_linkval_f" + <dd>There is no direct FORTRAN couterpart for the C function + <code>H5Giterate</code>. + Instead, that functionality is provided by two FORTRAN functions: + <center> + <table width=80%> + <tr valign=top align=left> + <td> + <a href="fortran/h5g_FORTRAN.html#h5gn_members_f" + target="FortranWin"><code>h5gn_members_f</code></a>. + </td><td> </td><td> + <strong>Purpose:</strong> + Returns the number of group members. + </tr><tr valign=top align=left> + <td> + <a href="fortran/h5g_FORTRAN.html#h5gget_obj_info_idx_f" + target="FortranWin"><code>h5gget_obj_info_idx_f</code></a> + </td><td> </td><td> + <strong>Purpose:</strong> + Returns name and type of the group member identified by its index. + </td> + </table> + </center> + <dd><a href="fortran/h5g_FORTRAN.html#h5gn_members_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1069,9 +784,264 @@ create or access function. --> </dl> +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Glink" --> +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Link">H5Glink</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Glink</code>(<em>hid_t</em> <code>loc_id</code>, + <em>H5G_link_t</em> <code>link_type</code>, + <em>const char *</em><code>current_name</code>, + <em>const char *</em><code>new_name</code> + ) + <dt><strong>Purpose:</strong> + <dd>Creates a link of the specified type from <code>new_name</code> + to <code>current_name</code>. + <dt><strong>Description:</strong> + <dd><code>H5Glink</code> creates a new name for an object that has some current + name, possibly one of many names it currently has. + <p> + If <code>link_type</code> is <code>H5G_LINK_HARD</code>, then + <code>current_name</code> must specify the name of an + existing object and both + names are interpreted relative to <code>loc_id</code>, which is + either a file identifier or a group identifier. + <p> + If <code>link_type</code> is <code>H5G_LINK_SOFT</code>, then + <code>current_name</code> can be anything and is interpreted at + lookup time relative to the group which contains the final + component of <code>new_name</code>. For instance, if + <code>current_name</code> is <code>./foo</code>, + <code>new_name</code> is <code>./x/y/bar</code>, and a request + is made for <code>./x/y/bar</code>, then the actual object looked + up is <code>./x/y/./foo</code>. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: File or group identifier. + <dt><em>H5G_link_t</em> <code>link_type</code> + <dd>IN: Link type. + Possible values are <code>H5G_LINK_HARD</code> and + <code>H5G_LINK_SOFT</code>. + <dt><em>const char *</em> <code>current_name</code> + <dd>IN: Name of the existing object if link is a hard link. + Can be anything for the soft link. + <dt><em>const char *</em> <code>new_name</code> + <dd>IN: New name for the 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/h5g_FORTRAN.html#h5glink_f" target="FortWin" onClick="window.open("fortran/h5g_FORTRAN.html#h5glink_f","FortWin&nquot;,"toolbar=0,location=0,directories=0,status=0,menubar=0,scrollbars=yes,resizable=1,width=500,height=250,titlebar=yes")"><img src="Graphics/FORTRAN.gif"></a> +--> + <dd><a href="fortran/h5g_FORTRAN.html#h5glink_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 "H5Glink2" --> +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Link2">H5Glink2</a> + <dt><strong>Signature:</strong> + + <dd><em>herr_t</em> <code>H5Glink2</code>( + <em>hid_t</em> <code>curr_loc_id</code>, <em>const char *</em><code>current_name</code>, + <em>H5G_link_t</em> <code>link_type</code>, + <em>hid_t</em> <code>new_loc_id</code>, <em>const char *</em><code>new_name</code> ) + <dt><strong>Purpose:</strong> + <dd>Creates a link of the specified type from <code>new_name</code> + to <code>current_name</code>. + <dt><strong>Description:</strong> + + <dd><code>H5Glink2</code> creates a new name for an object that has some current + name, possibly one of many names it currently has. + <p> + If <code>link_type</code> is <code>H5G_LINK_HARD</code>, then <code>current_name</code> + must specify the name of an existing object. + In this case, <code>current_name</code> and <code>new_name</code> are interpreted + relative to <code>curr_loc_id</code> and <code>new_loc_id</code>, respectively, + which are either file or group identifiers. + <p> + If <code>link_type</code> is <code>H5G_LINK_SOFT</code>, then + <code>current_name</code> can be anything and is interpreted at + lookup time relative to the group which contains the final + component of <code>new_name</code>. For instance, if + <code>current_name</code> is <code>./foo</code>, + <code>new_name</code> is <code>./x/y/bar</code>, and a request + is made for <code>./x/y/bar</code>, then the actual object looked + up is <code>./x/y/./foo</code>. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>curr_loc_id</code> + <dd>IN: The file or group identifier for the original object. + <dt><em>const char *</em> <code>current_name</code> + <dd>IN: Name of the existing object if link is a hard link. + Can be anything for the soft link. + <dt><em>H5G_link_t</em> <code>link_type</code> + <dd>IN: Link type. + Possible values are <code>H5G_LINK_HARD</code> and + <code>H5G_LINK_SOFT</code>. + <dt><em>hid_t</em> <code>new_loc_id</code> + <dd>IN: The file or group identifier for the new link. + <dt><em>const char *</em> <code>new_name</code> + <dd>IN: New name for the 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/h5g_FORTRAN.html#h5glink_f" target="FortWin" onClick="window.open("fortran/h5g_FORTRAN.html#h5glink_f","FortWin&nquot;,"toolbar=0,location=0,directories=0,status=0,menubar=0,scrollbars=yes,resizable=1,width=500,height=250,titlebar=yes")"><img src="Graphics/FORTRAN.gif"></a> +--> + <dd><a href="fortran/h5g_FORTRAN.html#h5glink2_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 "H5Gmove" --> +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Move">H5Gmove</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Gmove</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char</em> <code>*src_name</code>, + <em>const char</em> <code>*dst_name</code> + ) + <dt><strong>Purpose:</strong> + <dd>Renames an object within an HDF5 file. + <dt><strong>Description:</strong> + <dd><code>H5Gmove</code> renames an object within an HDF5 file. + The original name, <code>src_name</code>, is unlinked from the + group graph and the new name, <code>dst_name</code>, is inserted + as an atomic operation. Both names are interpreted relative + to <code>loc_id</code>, which is either a file or a group + identifier. + <dt><strong>Warning:</strong> + <dd>Exercise care in moving groups as it is possible to render data in + a file inaccessible with <code>H5Gmove</code>. + See <a href="Groups.html#H5GUnlinkToCorrupt">The Group Interface</a> + in the <cite>HDF5 User's Guide</cite>. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: File or group identifier. + <dt><em>const char</em> <code>*src_name</code> + <dd>IN: Object's original name. + <dt><em>const char</em> <code>*dst_name</code> + <dd>IN: Object's new name. + </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/h5g_FORTRAN.html#h5gmove_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 "H5Gmove2" --> +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Move2">H5Gmove2</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Gmove2</code>( <em>hid_t</em> <code>src_loc_id</code>, + <em>const char</em> <code>*src_name</code>, <em>hid_t</em> <code>dst_loc_id</code>, + <em>const char</em> <code>*dst_name</code> ) + <dt><strong>Purpose:</strong> + <dd>Renames an object within an HDF5 file. + <dt><strong>Description:</strong> + <dd><code>H5Gmove2</code> renames an object within an HDF5 file. The original + name, <code>src_name</code>, is unlinked from the group graph and the new + name, <code>dst_name</code>, is inserted as an atomic operation. + <p> + </p><code>src_name</code> and <code>dst_name</code> are interpreted relative to + <code>src_name</code> and <code>dst_name</code>, respectively, + which are either file or group identifiers. + <dt><strong>Warning:</strong> + <dd>Exercise care in moving groups as it is possible to render data in a file + inaccessible with <code>H5Gmove</code>. See <a href="Groups.html#H5GUnlinkToCorrupt">The + Group Interface</a> in the <cite>HDF5 User's Guide</cite>. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>src_loc_id</code> + <dd>IN: Original file or group identifier. + <dt><em>const char</em> <code>*src_name</code> + <dd>IN: Object's original name. + <dt><em>hid_t</em> <code>dst_loc_id</code> + <dd>IN: Destination file or group identifier. + <dt><em>const char</em> <code>*dst_name</code> + <dd>IN: Object's new name. + </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/h5g_FORTRAN.html#h5gmove2_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 "H5Gopen" --> +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Open">H5Gopen</a> + <dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Gopen</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code> + ) + <dt><strong>Purpose:</strong> + <dd>Opens an existing group for modification and returns a group + identifier for that group. + <dt><strong>Description:</strong> + <dd><code>H5Gopen</code> opens an existing group with the specified + name at the specified location, <code>loc_id</code>. + <p> + The location is identified by a file or group identifier + <p> + <code>H5Gopen</code> returns a group identifier for the group + that was opened. This group identifier should be released by + calling <code>H5Gclose</code> when it is no longer needed. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: File or group identifier within which group is to be open. + <dt><em>const char *</em> <code>name</code> + <dd>IN: Name of group to open. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a valid group identifier if successful; + otherwise returns a negative value. + <dt><strong>Non-C API(s):</strong> +<!-- + <dd><a href="fortran/h5g_FORTRAN.html#h5gopen_f" target="FortWin" onClick="window.open("fortran/h5g_FORTRAN.html#h5gopen_f","FortWin&nquot;,"toolbar=0,location=0,directories=0,status=0,menubar=0,scrollbars=yes,resizable=1,width=500,height=250,titlebar=yes")"><img src="Graphics/FORTRAN.gif"></a> +--> + <dd><a href="fortran/h5g_FORTRAN.html#h5gopen_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 "H5Gset_comment" --> @@ -1121,48 +1091,55 @@ create or access function. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Gget_comment" --> +<!-- HEADER RIGHT "H5Gunlink" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Group-GetComment">H5Gget_comment</a> + <dt><strong>Name:</strong> <a name="Group-Unlink">H5Gunlink</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Gget_comment</code>(<em>hid_t</em> <code>loc_id</code>, - <em>const char *</em><code>name</code>, - <em>size_t</em> <code>bufsize</code>, - <em>char *</em><code>comment</code> + <dd><em>herr_t </em><code>H5Gunlink</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves comment for specified object. + <dd>Removes the link to an object from a group. <dt><strong>Description:</strong> - <dd><code>H5Gget_comment</code> retrieves the comment for the the - object <code>name</code>. The comment is returned in the buffer - <code>comment</code>. + <dd><code>H5Gunlink</code> removes the object specified by + <code>name</code> from the group graph and decrements the + link count for the object to which <code>name</code> points. + This action eliminates any association between <code>name</code> + and the object to which <code>name</code> pointed. <p> - At most <code>bufsize</code> characters, including a null - terminator, are copied. The result is not null terminated - if the comment is longer than the supplied buffer. + Object headers keep track of how many hard links refer to an object; + when the link count reaches zero, the object can be removed + from the file. Objects which are open are not removed until all + identifiers to the object are closed. <p> - If an object does not have a comment, the empty string - is returned. + If the link count reaches zero, all file space associated with + the object will be released, i.e., identified in memory as freespace. + If the any object identifier is open for the object, the space + will not be released until after the object identifier is closed. + <p> + Note that space identified as freespace is available for re-use + only as long as the file remains open; once a file has been + closed, the HDF5 library loses track of freespace. See + “<a href="Performance.html#Freespace">Freespace Management</a>” + in the <cite>HDF5 User's Guide</cite> for further details. + <dt><strong>Warning:</strong> + <dd>Exercise care in unlinking groups as it is possible to render data in + a file inaccessible with <code>H5Gunlink</code>. + See <a href="Groups.html#H5GUnlinkToCorrupt">The Group Interface</a> + in the <cite>HDF5 User's Guide</cite>. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>loc_id</code> - <dd>IN: Identifier of the file or group. - <dt><em>const char *</em><code>name</code> - <dd>IN: Name of the object whose comment is to be set or reset. - <dt><em>size_t</em> <code>bufsize</code> - <dd>IN: Anticipated size of the buffer required to hold - <code>comment</code>. - <dt><em>char *</em><code>comment</code> - <dd>OUT: The comment. + <dd>IN: Identifier of the file or group containing the object. + <dt><em>const char *</em> <code>name</code> + <dd>IN: Name of the object to unlink. </dl> <dt><strong>Returns:</strong> - <dd>Returns the number of characters in the comment, - counting the null terminator, if successful; the value - returned may be larger than <code>bufsize</code>. - 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/h5g_FORTRAN.html#h5gget_comment_f" + <dd><a href="fortran/h5g_FORTRAN.html#h5gunlink_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1170,7 +1147,6 @@ create or access function. --> </dl> - <!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr> <center> <table border=0 width=98%> @@ -1204,14 +1180,13 @@ 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 --><SCRIPT LANGUAGE="JAVASCRIPT"> <!-- -document.writeln("Last modified: 6 June 2003"); +document.writeln("Last modified: 3 October 2003"); --> </SCRIPT> diff --git a/doc/html/RM_H5I.html b/doc/html/RM_H5I.html index 8f3dede..409de63 100644 --- a/doc/html/RM_H5I.html +++ b/doc/html/RM_H5I.html @@ -61,8 +61,7 @@ And in this document, the </td></tr> </table> </center> -<hr> -<!-- #EndLibraryItem --><center> +<hr><!-- #EndLibraryItem --><center> <h1>H5I: Identifier Interface</h1> </center> @@ -125,62 +124,6 @@ facilitate moving easily between them.</i> <!-- NEW PAGE --> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Iget_type" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Identify-GetType">H5Iget_type</a> -<dt><strong>Signature:</strong> - <dd><em>H5I_type_t</em> <code>H5Iget_type</code>(<em>hid_t</em> <code>obj_id</code>) -<dt><strong>Purpose:</strong> - <dd>Retrieves the type of an object. -<dt><strong>Description:</strong> - <dd><code>H5Iget_type</code> retrieves the type of the object - identified by <code>obj_id</code>. - <p> - Valid types returned by the function are - <table> - <tr><td width=200><code> H5I_FILE</code> - </td><td>File</td></tr> - <tr><td><code> H5I_GROUP</code> - </td><td>Group</td></tr> - <tr><td><code> H5I_DATATYPE</code> - </td><td>Datatype</td></tr> - <tr><td><code> H5I_DATASPACE</code> - </td><td>Dataspace</td></tr> - <tr><td><code> H5I_DATASET</code> - </td><td>Dataset</td></tr> - <tr><td><code> H5I_ATTR</code> - </td><td>Attribute</td></tr> - </table> - If no valid type can be determined or the identifier - submitted is invalid, the function returns - <table> - <tr><td width=200><code> H5I_BADID</code> - </td><td>Invalid identifier</td></tr> - </table> - <p> - This function is of particular value in determining the - type of object closing function (<code>H5Dclose</code>, - <code>H5Gclose</code>, etc.) to call after a call to - <code>H5Rdereference</code>. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>obj_id</code> - <dd>IN: Object identifier whose type is to be determined. - </dl> -<dt><strong>Returns:</strong> - <dd>Returns the object type if successful; - otherwise <code>H5I_BADID</code>. -<dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5i_FORTRAN.html#h5iget_type_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 "H5Iget_name" --> <hr> <dl> @@ -240,6 +183,61 @@ facilitate moving easily between them.</i> --> </dl> +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Iget_type" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Identify-GetType">H5Iget_type</a> +<dt><strong>Signature:</strong> + <dd><em>H5I_type_t</em> <code>H5Iget_type</code>(<em>hid_t</em> <code>obj_id</code>) +<dt><strong>Purpose:</strong> + <dd>Retrieves the type of an object. +<dt><strong>Description:</strong> + <dd><code>H5Iget_type</code> retrieves the type of the object + identified by <code>obj_id</code>. + <p> + Valid types returned by the function are + <table> + <tr><td width=200><code> H5I_FILE</code> + </td><td>File</td></tr> + <tr><td><code> H5I_GROUP</code> + </td><td>Group</td></tr> + <tr><td><code> H5I_DATATYPE</code> + </td><td>Datatype</td></tr> + <tr><td><code> H5I_DATASPACE</code> + </td><td>Dataspace</td></tr> + <tr><td><code> H5I_DATASET</code> + </td><td>Dataset</td></tr> + <tr><td><code> H5I_ATTR</code> + </td><td>Attribute</td></tr> + </table> + If no valid type can be determined or the identifier + submitted is invalid, the function returns + <table> + <tr><td width=200><code> H5I_BADID</code> + </td><td>Invalid identifier</td></tr> + </table> + <p> + This function is of particular value in determining the + type of object closing function (<code>H5Dclose</code>, + <code>H5Gclose</code>, etc.) to call after a call to + <code>H5Rdereference</code>. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>obj_id</code> + <dd>IN: Object identifier whose type is to be determined. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns the object type if successful; + otherwise <code>H5I_BADID</code>. +<dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5i_FORTRAN.html#h5iget_type_f" + target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> + <!-- + <img src="Graphics/Java.gif"> + <img src="Graphics/C++.gif"> + --> +</dl> <!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr> <center> @@ -274,14 +272,13 @@ 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 --><SCRIPT LANGUAGE="JAVASCRIPT"> <!-- -document.writeln("Last modified: 10 June 2003"); +document.writeln("Last modified: 3 October 2003"); --> </SCRIPT> diff --git a/doc/html/RM_H5P.html b/doc/html/RM_H5P.html index fb20a2b..fa725d5 100644 --- a/doc/html/RM_H5P.html +++ b/doc/html/RM_H5P.html @@ -61,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> @@ -155,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> @@ -298,7 +297,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> @@ -603,62 +602,31 @@ facilitate moving easily between them.</i> </table> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pcreate" --> +<!-- 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"> --> @@ -697,35 +665,88 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_class" --> +<!-- 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 --> @@ -761,6 +782,136 @@ 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> @@ -941,620 +1092,45 @@ facilitate moving easily between them.</i> </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 "H5Pinsert" --> +<!-- HEADER RIGHT "H5Pequal" --> <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><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. + 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> - -<!-- 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>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"> @@ -1607,219 +1183,59 @@ facilitate moving easily between them.</i> </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_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_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-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> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pisa_class" --> +<!-- HEADER RIGHT "H5Pfill_value_defined" --> <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 --> @@ -1886,461 +1302,37 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pequal" --> -<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> - -<!-- 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 "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 "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 "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> - -<!-- 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 "H5Pclose_class" --> -<hr> -<dl> - <dt><strong>Name:</strong> <a name="Property-CloseClass">H5Pclose_class</a> - - <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Pclose_class</code>( - <em>hid_t</em> <code>class</code> - ) - - <dt><strong>Purpose:</strong> - <dd>Closes an existing property list class. - - <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. - - <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> - - <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"> - --> -</dl> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_version" --> +<!-- HEADER RIGHT "H5Pget_alignment" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetVersion">H5Pget_version</a> + <dt><strong>Name:</strong> <a name="Property-GetAlignment">H5Pget_alignment</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_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>Retrieves the version information of various objects for - a file creation property list. + <dd>Retrieves the current settings for alignment properties from a + file access property list. <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_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> <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. + <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>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_alignment_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -2349,33 +1341,63 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_userblock" --> +<!-- HEADER RIGHT "H5Pget_alloc_time" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetUserblock">H5Pset_userblock</a> + <dt><strong>Name:</strong> <a name="Property-GetAllocTime">H5Pget_alloc_time</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_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>Sets user block size. + <dd>Retrieves the timing for storage space allocation. <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_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 property list to modify. - <dt><em>hsize_t</em> <code>size</code> - <dd>IN: Size of the user-block in bytes. + <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_userblock_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"> @@ -2384,31 +1406,41 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_userblock" --> +<!-- HEADER RIGHT "H5Pget_btree_ratios" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetUserblock">H5Pget_userblock</a> + <dt><strong>Name:</strong> <a name="Property-GetBTreeRatios">H5Pget_btree_ratios</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>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>Retrieves the size of a user block. + <dd>Gets B-tree split ratios for a dataset transfer property list. <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_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 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: 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_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"> @@ -2417,40 +1449,36 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_sizes" --> +<!-- HEADER RIGHT "H5Pget_buffer" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetSizes">H5Pset_sizes</a> + <dt><strong>Name:</strong> <a name="Property-GetBuffer">H5Pget_buffer</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>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>Sets the byte size of the offsets and lengths used to address objects - in an HDF5 file. + <dd>Reads buffer settings. <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_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 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. + <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#h5pset_sizes_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"> @@ -2459,35 +1487,45 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_sizes" --> +<!-- HEADER RIGHT "H5Pget_cache" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetSizes">H5Pget_sizes</a> + <dt><strong>Name:</strong> <a name="Property-GetCache">H5Pget_cache</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>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>Retrieves the size of the offsets and lengths used in an HDF5 file. + <dd>Queries the meta data cache and raw data chunk cache parameters. <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_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 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>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#h5pget_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"> @@ -2496,49 +1534,38 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_sym_k" --> +<!-- HEADER RIGHT "H5Pget_chunk" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetSymK">H5Pset_sym_k</a> + <dt><strong>Name:</strong> <a name="Property-GetChunk">H5Pget_chunk</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>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>Sets the size of parameters used to control the symbol table nodes. + <dd>Retrieves the size of chunks for the raw data of a chunked layout dataset. + <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_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 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. + <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. </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#h5pset_sym_k_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"> @@ -2547,40 +1574,30 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_sym_k" --> +<!-- HEADER RIGHT "H5Pget_class" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetSymK">H5Pget_sym_k</a> + <dt><strong>Name:</strong> <a name="Property-GetClass">H5Pget_class</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>H5P_class_t </em><code>H5Pget_class</code>(<em>hid_t</em> <code>plist</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>Returns the property list class for a property list. <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</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: 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</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#h5pget_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"> @@ -2589,124 +1606,127 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_istore_k" --> +<!-- HEADER RIGHT "H5Pget_class_name" --> <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>Name:</strong> <a name="Property-GetClassName">H5Pget_class_name</a> + <dt><strong>Purpose:</strong> - <dd>Sets the size of the parameter used to control the - B-trees for indexing chunked datasets. + <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>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_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> - <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> + <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>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"> - --> + <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_istore_k" --> +<!-- HEADER RIGHT "H5Pget_class_parent" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetIstoreK">H5Pget_istore_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_istore_k</code>(<em>hid_t</em> <code>plist</code>, - <em>int *</em> <code>ik</code> - ) + <dd><em>hid_t</em> <code>H5Pget_class_parent</code>( + <em>hid_t</em> <code>pcid</code> + ) + <dt><strong>Purpose:</strong> - <dd>Queries the 1/2 rank of an indexed storage B-tree. + <dd>Retrieves the parent class of a property class. + <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_class_parent</code> retrieves an identifier for the + parent class of a property class. + <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. - </dl> + <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>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" - target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> - <!-- - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> + <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 "H5Pset_layout" --> +<!-- HEADER RIGHT "H5Pget_driver" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetLayout">H5Pset_layout</a> + <dt><strong>Name:</strong> <a name="Property-GetDriver">H5Pget_driver</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>hid_t</em> <code>H5Pget_driver</code>( + <em>hid_t</em> <code>plist_id</code> + ) <dt><strong>Purpose:</strong> - <dd>Sets the type of storage used to store the raw data for a dataset. + <dd>Returns low-lever driver identifier. <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. + <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 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> + 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: 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>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#h5pset_layout_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"> @@ -2714,125 +1734,85 @@ facilitate moving easily between them.</i> --> </dl> -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_layout" --> +<!-- ********** MOVED TO TechNotes/VFLfunc.html ********** + <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetLayout">H5Pget_layout</a> + <dt><strong>Name:</strong> <a name="Property-GetDriverInfo">H5Pget_driver_info</a> <dt><strong>Signature:</strong> - <dd><em>H5D_layout_t</em> <code>H5Pget_layout</code>(<em>hid_t</em> <code>plist</code>) + <dd><em>void *</em><code>H5Pget_driver_info</code>( + <em>hid_t</em> <code>plist_id</code> + ) <dt><strong>Purpose:</strong> - <dd>Returns the layout of the raw data for a dataset. + <dd>Returns a pointer to file driver information. <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_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 for property list to query. + <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 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 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#h5pget_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 "H5Pset_chunk" --> -<hr> -<dl> - <dt><strong>Name:</strong> <a name="Property-SetChunk">H5Pset_chunk</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> - ) - <dt><strong>Purpose:</strong> - <dd>Sets the size of the chunks used to store a chunked layout dataset. - <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. - <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. - </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_chunk_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_chunk" --> +<!-- HEADER RIGHT "H5Pget_dxpl_mpio" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetChunk">H5Pget_chunk</a> + <dt><strong>Name:</strong> <a name="Property-GetDxplMpio">H5Pget_dxpl_mpio</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>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>Retrieves the size of chunks for the raw data of a chunked layout dataset. - + <dd>Returns the data transfer mode. <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_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>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. + <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 chunk dimensionality 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_chunk_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"> @@ -2841,54 +1821,37 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_alignment" --> +<!-- HEADER RIGHT "H5Pget_dxpl_multi" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetAlignment">H5Pset_alignment</a> + <dt><strong>Name:</strong> <a name="Property-GetDxplMulti">H5Pget_dxpl_multi</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_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 alignment properties of a file access property list. + <dd>Returns multi-file data transfer property list information. <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_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 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>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_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"> @@ -2896,37 +1859,29 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_alignment" --> +<!-- HEADER RIGHT "H5Pget_edc_check" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetAlignment">H5Pget_alignment</a> + <dt><strong>Name:</strong> <a name="Property-GetEdcCheck">H5Pget_edc_check</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>H5Z_EDC_t</em> <code>H5Pget_edc_check</code>(<em>hid_t</em> <code>plist</code>) <dt><strong>Purpose:</strong> - <dd>Retrieves the current settings for alignment properties from a - file access property list. + <dd>Determines whether error-detection is enabled for dataset reads. <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_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 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. + <dd>IN: Dataset transfer property list identifier. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; + <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_alignment_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"> @@ -2935,51 +1890,55 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_external" --> +<!-- HEADER RIGHT "H5Pget_external" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetExternal">H5Pset_external</a> + <dt><strong>Name:</strong> <a name="Property-GetExternal">H5Pget_external</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_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>Adds an external file to the list of external files. + <dd>Returns information about an external file. <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). + <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> - 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. + 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 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>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> <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_external_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -3018,56 +1977,49 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_external" --> +<!-- HEADER RIGHT "H5Pget_family_offset" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetExternal">H5Pget_external</a> + <dt><strong>Name:</strong> <a name="Property-GetFamilyOffset">H5Pget_family_offset</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_family_offset</code> ( + <em>hid_t</em> <code>fapl_id</code>, + <em>hsize_t *</em><code>offset</code> ) <dt><strong>Purpose:</strong> - <dd>Returns information about an external file. + <dd>Retrieves a data offset from the file access property list. <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>). - <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. + <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 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>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#h5pget_external_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"> @@ -3075,75 +2027,36 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_fill_value" --> +<!-- HEADER RIGHT "H5Pget_fapl_core" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetFillValue">H5Pset_fill_value</a> + <dt><strong>Name:</strong> <a name="Property-GetFaplCore">H5Pget_fapl_core</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_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>Sets the fill value for a dataset. + <dd>Queries core file driver properties. <dt><strong>Description:</strong> - <dd><code>H5Pset_fill_value</code> sets the fill value for - a dataset in the dataset creation property list. - <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. + <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_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>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#h5pset_fill_value_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"> @@ -3152,60 +2065,37 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_fill_value" --> +<!-- HEADER RIGHT "H5Pget_fapl_family" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetFillValue">H5Pget_fill_value</a> + <dt><strong>Name:</strong> <a name="Property-GetFaplFamily">H5Pget_fapl_family</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_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>Retrieves a dataset fill value. + <dd>Returns file access property list information. <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_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_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> 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_fill_value_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"> @@ -3214,55 +2104,46 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pfill_value_defined" --> +<!-- HEADER RIGHT "H5Pget_fapl_gass" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-FillValueDefined">H5Pfill_value_defined</a> + <dt><strong>Name:</strong> <a name="Property-GetFaplGass">H5Pget_fapl_gass</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_gass</code>( + <em>hid_t</em> <code>fapl_id</code>, + <em>GASS_Info *</em><code>info</code> + ) <dt><strong>Purpose:</strong> - <dd>Determines whether fill value is defined. + <dd>Retrieves GASS 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_GASS</code> driver, + <code>H5Pget_fapl_gass</code> returns the <em>GASS_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>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>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>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_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>GASS_Info *</em><code>info</code> + <dd>OUT: 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#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"> @@ -3270,59 +2151,41 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_fill_time" --> +<!-- HEADER RIGHT "H5Pget_fapl_mpio" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetFillTime">H5Pset_fill_time</a> + <dt><strong>Name:</strong> <a name="Property-GetFaplMpio">H5Pget_fapl_mpio</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_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>Sets the time when fill values are written to a dataset. + <dd> Returns MPI communicator information. <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>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> - 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. + 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_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>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#h5pset_fill_time_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"> @@ -3331,135 +2194,85 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_fill_time" --> +<!-- HEADER RIGHT "H5Pget_fapl_mpiposix" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetFillTime">H5Pget_fill_time</a> + <dt><strong>Name:</strong> <a name="Property-GetFaplMpiPosix">H5Pget_fapl_mpiposix</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Pget_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_mpiposix</code>( + <em>hid_t</em> <code>fapl_id</code>, + <em>MPI_Comm *</em><code>comm</code> + ) <dt><strong>Purpose:</strong> - <dd>Retrieves the time when fill value are written to a dataset. + <dd> Returns MPI communicator information. <dt><strong>Description:</strong> - <dd><code>H5Pget_fill_time</code> examines the dataset creation - property list <code>plist_id</code> to determine when fill values - are to be written to a dataset. + <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> - Valid values returned in <code>fill_time</code> are as follows: - <table border=0 > - <tr valign="top"><td> </td><td> - <code>H5D_FILL_TIME_IFSET</code> - </td><td> - Fill values are written 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> - Fill values are written to the dataset when storage space is allocated. - </td></tr><tr valign="top"><td> </td><td> - <code>H5D_FILL_TIME_NEVER</code> - </td><td> - Fill values are never written to the dataset. - </td></tr></table> - <dt><strong>Note:</strong> - <dd><code>H5Pget_fill_time</code> is designed to work in coordination - with the dataset fill value and - dataset storage allocation time properties, retrieved with the functions - <code>H5Pget_fill_value</code> and <code>H5Pget_alloc_time</code>. - <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>plist_id</code> - <dd>IN: Dataset creation property list identifier. - <dt><em>H5D_fill_time_t *</em><code>fill_time</code> - <dd>OUT: Setting for the timing of writing fill values to the dataset. + <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#h5pget_fill_time_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 "H5Pset_alloc_time" --> +<!-- HEADER RIGHT "H5Pget_fapl_multi" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetAllocTime">H5Pset_alloc_time</a> + <dt><strong>Name:</strong> <a name="Property-GetFaplMulti">H5Pget_fapl_multi</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_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>Sets the timing for storage space allocation. + <dd>Returns information about the multi-file access property list. <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>. - <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. + <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>H5D_alloc_time_t</em> <code>alloc_time</code> - <dd>IN: When to allocate dataset storage space. + <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#h5pset_alloc_time_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"> @@ -3468,64 +2281,45 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_alloc_time" --> +<!-- HEADER RIGHT "H5Pget_fapl_srb" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetAllocTime">H5Pget_alloc_time</a> + <dt><strong>Name:</strong> <a name="Property-GetFaplSrb">H5Pget_fapl_srb</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> - ) + <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>Retrieves the timing for storage space allocation. + <dd>Retrieves SRB information. <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>. + <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> - 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> + 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>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> + <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_alloc_time_t *</em><code>alloc_time</code> - <dd>IN: When to allocate dataset storage space. + <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#h5pget_alloc_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"> @@ -3533,118 +2327,38 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_filter" --> +<!-- HEADER RIGHT "H5Pget_fapl_stream" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetFilter">H5Pset_filter</a> + <dt><strong>Name:</strong> <a name="Property-GetFaplStream">H5Pget_fapl_stream</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> + <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>Adds a filter to the filter pipeline. + <dd>Returns the streaming I/O driver settings. <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. + <dd><code>H5Pget_fapl_stream</code> returns the file access properties + set for the use of the streaming I/O driver. <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. + <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</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>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_filter_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"> @@ -3652,73 +2366,157 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pall_filters_avail" --> +<!-- HEADER RIGHT "H5Pget_fclose_degree" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-AllFiltersAvail">H5Pall_filters_avail</a> + <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> <dt><strong>Signature:</strong> - <dd><em>htri_t</em> <code>H5Pall_filters_avail</code>(<em>hid_t</em> <code>dcpl_id</code>) + <dd><em>herr_t </em><code>H5Pget_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>Verifies that all required filters are available. + <dd>Retrieves the time when fill value are written to a dataset. <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. + <dd><code>H5Pget_fill_time</code> examines the dataset creation + property list <code>plist_id</code> to determine when fill values + are to be written to a dataset. + <p> + Valid values returned in <code>fill_time</code> are as follows: + <table border=0 > + <tr valign="top"><td> </td><td> + <code>H5D_FILL_TIME_IFSET</code> + </td><td> + Fill values are written 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> + Fill values are written to the dataset when storage space is allocated. + </td></tr><tr valign="top"><td> </td><td> + <code>H5D_FILL_TIME_NEVER</code> + </td><td> + Fill values are never written to the dataset. + </td></tr></table> + <dt><strong>Note:</strong> + <dd><code>H5Pget_fill_time</code> is designed to work in coordination + with the dataset fill value and + dataset storage allocation time properties, retrieved with the functions + <code>H5Pget_fill_value</code> and <code>H5Pget_alloc_time</code>. + <p> <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>dcpl_id</code> + <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>OUT: Setting for the timing of writing fill values to the dataset. </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" + <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_time_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" --> +<!-- HEADER RIGHT "H5Pget_fill_value" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetNFilters">H5Pget_nfilters</a> + <dt><strong>Name:</strong> <a name="Property-GetFillValue">H5Pget_fill_value</a> <dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Pget_nfilters</code>(<em>hid_t</em> <code>plist</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>Returns the number of filters in the pipeline. + <dd>Retrieves a dataset fill value. <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>. + <dd><code>H5Pget_fill_value</code> returns the dataset + fill value defined in the dataset creation property list + <code>plist_id</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. + 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> - <code>H5Pget_nfilters</code> returns the number of filters - in the pipeline, including zero (<code>0</code>) if there - are none. + 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>This function currently supports only the permanent filter - pipeline; <code>plist_id</code> must be a dataset creation - property list. + <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</code> - <dd>IN: Property list identifier. + <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. </dl> <dt><strong>Returns:</strong> - <dd>Returns the number of filters in the pipeline if successful; + <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_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"> @@ -3910,53 +2708,37 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pmodify_filter" --> +<!-- 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"> @@ -3965,45 +2747,48 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_shuffle" --> +<!-- HEADER RIGHT "H5Pget_hyper_cache" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetShuffle">H5Pset_shuffle</a> + <dt><strong>Name:</strong> <a name="Property-GetHyperCache">H5Pget_hyper_cache</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_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>Sets up use of the shuffle filter. + <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> + Returns information regarding the caching of hyperslab blocks during I/O. <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>Given a dataset transfer property list, <code>H5Pget_hyper_cache</code> + returns instructions regarding the caching of hyperslab blocks during I/O. + These parameters are set with the <code>H5Pset_hyper_cache</code> function. <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: Dataset transfer property list identifier. + <dt><em>unsigned</em> *<code>cache</code> + <dd>OUT: A flag indicating whether caching is + set to on (<code>1</code>) or off (<code>0</code>). + <dt><em>unsigned</em> *<code>limit</code> + <dd>OUT: 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. <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_hyper_cache_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -4012,30 +2797,41 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_fletcher32" --> +<!-- HEADER RIGHT "H5Pget_hyper_vector_size" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetFletcher32">H5Pset_fletcher32</a> + <dt><strong>Name:</strong> <a name="Property-GetHyperVectorSize">H5Pget_hyper_vector_size</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Pset_fletcher32</code>(<em>hid_t</em> <code>plist</code>) + <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> + ) <dt><strong>Purpose:</strong> - <dd>Sets up use of the Fletcher32 checksum filter. + <dd>Retrieves number of I/O vectors to be read/written in hyperslab I/O. <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>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. + <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>. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>plist</code> - <dd>IN: Dataset creation property list identifier. + <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. </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" + <dd><a href="fortran/h5p_FORTRAN.html#h5pget_hyper_vector_size_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -4044,262 +2840,79 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_szip" --> +<!-- HEADER RIGHT "H5Pget_istore_k" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetSzip">H5Pset_szip</a> + <dt><strong>Name:</strong> <a name="Property-GetIstoreK">H5Pget_istore_k</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_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 SZIP compression filter. + <dd>Queries the 1/2 rank of an indexed storage B-tree. <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_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</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. + <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_szip_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"> <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_edc_check" --> +<!-- HEADER RIGHT "H5Pget_layout" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetEdcCheck">H5Pset_edc_check</a> + <dt><strong>Name:</strong> <a name="Property-GetLayout">H5Pget_layout</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>H5D_layout_t</em> <code>H5Pget_layout</code>(<em>hid_t</em> <code>plist</code>) <dt><strong>Purpose:</strong> - <dd>Sets whether to enable error-detection when reading a dataset. + <dd>Returns the layout of the raw data for a dataset. <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> - <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. + <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. + <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. + <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_edc_check_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"> @@ -4308,29 +2921,39 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_edc_check" --> +<!-- HEADER RIGHT "H5Pget_meta_block_size" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetEdcCheck">H5Pget_edc_check</a> + <dt><strong>Name:</strong> <a name="Property-GetMetaBlockSize">H5Pget_meta_block_size</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>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>Determines whether error-detection is enabled for dataset reads. + <dd>Returns the current metadata block size setting. <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_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 transfer property list identifier. + <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 <code>H5P_ENABLE_EDC</code> or <code>H5P_DISABLE_EDC</code> - 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_edc_check_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"> @@ -4339,111 +2962,95 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_filter_callback" --> +<!-- HEADER RIGHT "H5Pget_multi_type" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetFilterCallback">H5Pset_filter_callback</a> + <dt><strong>Name:</strong> <a name="Property-GetMultiType">H5Pget_multi_type</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>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 user-defined filter callback function. + <dd>Retrieves data type property for <code>MULTI</code> driver. <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> + <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> - 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. + 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> - Valid callback function return values are - <code>H5Z_CB_FAIL</code> and <code>H5Z_CB_CONT</code>. + 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_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. + <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_filter_callback_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_meta_block_size" --> +<!-- HEADER RIGHT "H5Pget_nfilters" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetMetaBlockSize">H5Pset_meta_block_size</a> + <dt><strong>Name:</strong> <a name="Property-GetNFilters">H5Pget_nfilters</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>hsize_t</em> <code>size</code> - ) + <dd><em>int</em> <code>H5Pget_nfilters</code>(<em>hid_t</em> <code>plist</code>) <dt><strong>Purpose:</strong> - <dd>Sets the minimum metadata block size. + <dd>Returns the number of filters in the pipeline. <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. + <dd><code>H5Pget_nfilters</code> returns the number of filters + defined in the filter pipeline associated with the property list + <code>plist</code>. <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. + 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> - 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. + <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>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>hid_t</em> <code>plist</code> + <dd>IN: Property list identifier. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful. - Otherwise returns a negative value. + <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#h5pset_meta_block_size_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"> @@ -4452,84 +3059,73 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_meta_block_size" --> +<!-- HEADER RIGHT "H5Pget_nprops" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetMetaBlockSize">H5Pget_meta_block_size</a> + <dt><strong>Name:</strong> <a name="Property-GetNProps">H5Pget_nprops</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>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>Returns the current metadata block size setting. + <dd>Queries number of properties in property list or class. + <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_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> - <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. - </dl> + <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>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" - 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#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 "H5Pset_sieve_buf_size" --> +<!-- HEADER RIGHT "H5Pget_preserve" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetSieveBufSize">H5Pset_sieve_buf_size</a> + <dt><strong>Name:</strong> <a name="Property-GetPreserve">H5Pget_preserve</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>int</em> <code>H5Pget_preserve</code>(<em>hid_t</em> <code>plist</code>) <dt><strong>Purpose:</strong> - <dd>Sets the maximum size of the data sieve buffer. + <dd>Checks status of the dataset transfer property list. <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. - <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. + <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>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: Identifier for the dataset transfer property list. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful. - Otherwise returns a negative value. + <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_sieve_buf_size_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"> @@ -4579,44 +3175,86 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_gc_references" --> +<!-- HEADER RIGHT "H5Pget_size" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetGCReferences">H5Pset_gc_references</a> + <dt><strong>Name:</strong> <a name="Property-GetSize">H5Pget_size</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>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>Sets garbage collecting references flag. + <dd>Queries the size of a property value in bytes. + <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_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-GetSizes">H5Pget_sizes</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> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves the size of the offsets and lengths used in an HDF5 file. + <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. <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 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. <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_sizes_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -4625,37 +3263,34 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_gc_references" --> +<!-- HEADER RIGHT "H5Pget_small_data_block_size" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetGCReferences">H5Pget_gc_references</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>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_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>Returns garbage collecting references setting. + <dd>Retrieves the current small data block size setting. <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_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. <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. + <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. </dl> <dt><strong>Returns:</strong> <dd>Returns a non-negative value if successful; - otherwise returns a negative value. + otherwise 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_small_data_block_size_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -4664,59 +3299,40 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_cache" --> +<!-- HEADER RIGHT "H5Pget_sym_k" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetCache">H5Pset_cache</a> + <dt><strong>Name:</strong> <a name="Property-GetSymK">H5Pget_sym_k</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_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 meta data cache and raw data chunk cache parameters. + <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>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_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>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: 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. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5p_FORTRAN.html#h5pset_cache_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"> @@ -4725,45 +3341,31 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_cache" --> +<!-- HEADER RIGHT "H5Pget_userblock" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetCache">H5Pget_cache</a> + <dt><strong>Name:</strong> <a name="Property-GetUserblock">H5Pget_userblock</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>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>Queries the meta data cache and raw data chunk cache parameters. + <dd>Retrieves the size of a user block. <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>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_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. + <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. </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" + <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"> @@ -4772,67 +3374,42 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_hyper_cache" --> +<!-- HEADER RIGHT "H5Pget_version" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetHyperCache">H5Pset_hyper_cache</a> + <dt><strong>Name:</strong> <a name="Property-GetVersion">H5Pget_version</a> <dt><strong>Signature:</strong> - <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> - ) + <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>Indicates whether to cache hyperslab blocks during I/O. + <dd>Retrieves the version information of various objects for + a file creation property list. <dt><strong>Description:</strong> - <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> - 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> - 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. + <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: 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. + <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#h5pset_hyper_cache_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"> @@ -4841,48 +3418,534 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_hyper_cache" --> +<!-- HEADER RIGHT "H5Pget_vlen_mem_manager" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetHyperCache">H5Pget_hyper_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>H5Pget_hyper_cache</code>(<em>hid_t</em> <code>plist</code>, - <em>unsigned</em> *<code>cache</code>, - <em>unsigned</em> *<code>limit</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>[<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> - Returns information regarding the caching of hyperslab blocks during I/O. + <dd>Gets the memory manager for variable-length datatype allocation in + <code>H5Dread</code> and <code>H5Dvlen_reclaim</code>. <dt><strong>Description:</strong> - <dd>Given a dataset transfer property list, <code>H5Pget_hyper_cache</code> - returns instructions regarding the caching of hyperslab blocks during I/O. - These parameters are set with the <code>H5Pset_hyper_cache</code> function. + <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</code> - <dd>IN: Dataset transfer property list identifier. - <dt><em>unsigned</em> *<code>cache</code> - <dd>OUT: A flag indicating whether caching is - set to on (<code>1</code>) or off (<code>0</code>). - <dt><em>unsigned</em> *<code>limit</code> - <dd>OUT: Maximum size of the hyperslab block to cache. - <code>0</code> (zero) indicates no limit. + <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#h5pget_hyper_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-IsAClass">H5Pisa_class</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> + ) + + <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>Modifies a filter in the filter pipeline. + <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. + <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. + </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" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -4891,47 +3954,460 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_hyper_vector_size" --> +<!-- HEADER RIGHT "H5Pregister" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetHyperVectorSize">H5Pset_hyper_vector_size</a> + <dt><strong>Name:</strong> <a name="Property-Register">H5Pregister</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>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-SetAlignment">H5Pset_alignment</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> ) <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"> @@ -4940,41 +4416,76 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_hyper_vector_size" --> +<!-- 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"> @@ -5034,49 +4545,6 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_btree_ratios" --> -<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> @@ -5137,95 +4605,59 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_buffer" --> -<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_small_data_block_size" --> +<!-- 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"> @@ -5234,34 +4666,40 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_small_data_block_size" --> +<!-- 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"> @@ -5270,38 +4708,35 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_preserve" --> +<!-- 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"> @@ -5310,27 +4745,44 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_preserve" --> +<!-- HEADER RIGHT "H5Pset_dxpl_mpio" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetPreserve">H5Pget_preserve</a> + <dt><strong>Name:</strong> <a name="Property-SetDxplMpio">H5Pset_dxpl_mpio</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_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>Checks status of the dataset transfer property list. + <dd>Sets data transfer mode. <dt><strong>Description:</strong> - <dd><code>H5Pget_preserve</code> checks the status of the - dataset transfer property list. + <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>plist</code> - <dd>IN: Identifier for the dataset transfer property list. + <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 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#h5pset_dxpl_mpio_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -5338,142 +4790,146 @@ END LIBRARY-SET OPTION TAGS --> --> </dl> - -<!-- - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Pset_dxpl_multi" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetCompression">H5Pset_compression</a> + <dt><strong>Name:</strong> <a name="Property-SetDxplMulti">H5Pset_dxpl_multi</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_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 compression method. + <dd>Sets the data transfer property list for the multi-file driver. <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_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> - 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. + <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>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>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. + <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-GetCompression">H5Pget_compression</a> + <dt><strong>Name:</strong> <a name="Property-SetEdcCheck">H5Pset_edc_check</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_edc_check</code>(<em>hid_t</em> <code>plist</code>, + <em>H5Z_EDC_t</em> <code>check</code>) <dt><strong>Purpose:</strong> - <dd>Gets compression method. + <dd>Sets whether to enable error-detection when reading a dataset. <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_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>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. + <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 compression method if successful; + <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_edc_check_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_deflate" --> +<!-- HEADER RIGHT "H5Pset_external" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetDeflate">H5Pset_deflate</a> + <dt><strong>Name:</strong> <a name="Property-SetExternal">H5Pset_external</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_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>Sets compression method and compression level. + <dd>Adds an external file to the list of external files. <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_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. - <dt><em>int</em> <code>level</code> - <dd>IN: Compression level. + <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 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_external_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -5481,184 +4937,111 @@ END LIBRARY-SET OPTION TAGS --> --> </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> - ---> - <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_vlen_mem_manager" --> +<!-- 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 "H5Pget_vlen_mem_manager" --> +<!-- 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> @@ -5704,132 +5087,46 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_fapl_family" --> -<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> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_family_offset" --> -<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 "H5Pget_family_offset" --> +<!-- 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" @@ -6170,222 +5467,6 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_fapl_mpio" --> -<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">H5Pget_fapl_mpio</a> - <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Pset_fapl_mpiposix</code>( - <em>hid_t</em> <code>fapl_id</code>, - <em>MPI_Comm</em> <code>comm</code> - ) - <dt><strong>Purpose:</strong> - <dd>Stores MPI IO communicator information to a file access property list. - <dt><strong>Description:</strong> - <dd><code>H5Pset_fapl_mpiposix</code> stores the user-supplied - MPI IO parameter <code>comm</code>, for communicator, - in the file access property list <code>fapl_id</code>. - That property list can then be used to create and/or open the file. - <p> - <code>H5Pset_fapl_mpiposix</code> is available only in the - parallel HDF5 library and is not a collective function. - <p> - <code>comm</code> is the MPI communicator to be used for - file open as defined in <code>MPI_FILE_OPEN</code> of MPI-2. - This function does not create a duplicated communicator. - Modifications to <code>comm</code> after this function call - returns may have an undetermined effect on the access property list. - Users should not modify the communicator while it is defined - in a property list. - <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>IN: 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#h5pset_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_mpiposix" --> -<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> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_dxpl_mpio" --> -<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> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_dxpl_mpio" --> -<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> @@ -6532,124 +5613,30 @@ END LIBRARY-SET OPTION TAGS --> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_fapl_multi" --> +<!-- 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> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_dxpl_multi" --> -<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> - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_dxpl_multi" --> -<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"> @@ -6752,170 +5739,46 @@ fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl); </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" - 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_multi_type" --> -<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_sec2" --> +<!-- 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"> @@ -7036,137 +5899,584 @@ fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl); </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_fapl_stream" --> +<!-- HEADER RIGHT "H5Pset_fclose_degree" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetFaplStream">H5Pget_fapl_stream</a> + <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-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>Sets the time when fill values are written to a dataset. + <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>. + <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. + <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. + </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_fill_time_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_value" --> +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetFillValue">H5Pset_fill_value</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> ) <dt><strong>Purpose:</strong> - <dd>Returns the streaming I/O driver settings. + <dd>Sets the fill value for 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_value</code> sets the fill value for + a dataset in the dataset creation property list. <p> - <code>H5Pset_fapl_stream</code> and <code>H5Pget_fapl_stream</code> - are not intended for use in a parallel environment. + <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>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>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-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: -<!-- ********** MOVED TO TechNotes/VFLfunc.html ********** + <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. + </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> +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Pset_filter_callback" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetDriver">H5Pset_driver</a> + <dt><strong>Name:</strong> <a name="Property-SetFilterCallback">H5Pset_filter_callback</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_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> + +<!-- 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-SetGCReferences">H5Pset_gc_references</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> ) <dt><strong>Purpose:</strong> - <dd>Sets the file driver. + <dd>Sets garbage collecting references flag. <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>. + <dd><code>H5Pset_gc_references</code> sets the flag for + garbage collecting references for the file. <p> - <font color=red><b><i>Need <code>driver_info</code> struct definition.</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> - 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. + 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>driver_id</code> - <dd>IN: Driver identifier. - <dt><em>const void *</em> <code>driver_info</code> - <dd>IN: Optional struct containing driver properties. + <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 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_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-SetHyperCache">H5Pset_hyper_cache</a> + <dt><strong>Signature:</strong> + <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>Indicates whether to cache hyperslab blocks during I/O. + <dt><strong>Description:</strong> + <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> + 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> + 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>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. + <dt><strong>Non-C API(s):</strong> + <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 "H5Pget_driver" --> +<!-- HEADER RIGHT "H5Pset_hyper_vector_size" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetDriver">H5Pget_driver</a> + <dt><strong>Name:</strong> <a name="Property-SetHyperVectorSize">H5Pset_hyper_vector_size</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_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>Returns low-lever driver identifier. + <dd>Sets number of I/O vectors to be read/written in hyperslab I/O. <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_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> - 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 <em>I/O vectors</em> are hyperslab offset and length pairs + and are generated during hyperslab I/O. <p> - The returned driver identifier is only valid as long as the - file driver remains registered. + 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>plist_id</code> - <dd>IN: File access or data transfer property list identifier. + <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 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_hyper_vector_size_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -7174,451 +6484,1304 @@ fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl); --> </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> -<!-- ********** MOVED TO TechNotes/VFLfunc.html ********** +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Pset_layout" --> +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetLayout">H5Pset_layout</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> + ) + <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> + <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 "H5Punregister" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetDriverInfo">H5Pget_driver_info</a> + <dt><strong>Name:</strong> <a name="Property-Unregister">H5Punregister</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>H5Punregister</code>( + <em>H5P_class_t</em> <code>class</code>, + <em>const char *</em><code>name</code> + ) + <dt><strong>Purpose:</strong> - <dd>Returns a pointer to file driver information. + <dd>Removes a property from a property list class. + <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>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. - <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> + <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> + + + + + + + +<!-- 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_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 + 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. + <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_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_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: File access or data transfer property list identifier. + <dd>IN: Dataset creation property list identifier. </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_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_szip" --> +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetSzip">H5Pset_szip</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>) + <dt><strong>Purpose:</strong> + <dd>Sets up use of the SZIP compression filter. + <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. + + <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. + </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_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_fapl_gass" --> +<!-- HEADER RIGHT "H5Pset_meta_block_size" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetFaplGass">H5Pset_fapl_gass</a> + <dt><strong>Name:</strong> <a name="Property-SetMetaBlockSize">H5Pset_meta_block_size</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Pset_fapl_gass</code>( + <dd><em>herr_t</em> <code>H5Pset_meta_block_size</code>( <em>hid_t</em> <code>fapl_id</code>, - <em>GASS_Info</em> <code>info</code> + <em>hsize_t</em> <code>size</code> ) <dt><strong>Purpose:</strong> - <dd>Stores user-supplied GASS information. + <dd>Sets the minimum metadata block size. <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><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 <em>GASS_Info</em> object, <code>info</code>, is used for - file open operations when using GASS in the Globus environment. + 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> - 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>. + 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>, + <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>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#h5pxxx_f" + <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 "H5Pget_fapl_gass" --> +<!-- HEADER RIGHT "H5Pset_sieve_buf_size" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetFaplGass">H5Pget_fapl_gass</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_gass</code>( + <dd><em>herr_t</em> <code>H5Pset_sieve_buf_size</code>( <em>hid_t</em> <code>fapl_id</code>, - <em>GASS_Info *</em><code>info</code> + <em>hsize_t</em> <code>size</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves GASS 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_GASS</code> driver, - <code>H5Pget_fapl_gass</code> returns the <em>GASS_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>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 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>, + <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>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_fapl_srb" --> +<!-- HEADER RIGHT "H5Pset_small_data_block_size" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetFaplSrb">H5Pset_fapl_srb</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_srb</code>( - <em>hid_t</em> <code>fapl_id</code>, - <em>SRB_Info</em> <code>info</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>Saves SRB connection handler and sets SRB settings. + <dd>Sets the size of a contiguous block reserved for small data. <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_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 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>. + 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> + 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> + 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>SRB_Info</em> <code>info</code> - <dd>IN: Pointer to the SRB information structure. + <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#h5pxxx_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"> <img src="Graphics/C++.gif"> --> </dl> + + <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_fapl_srb" --> +<!-- HEADER RIGHT "H5Pset_preserve" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetFaplSrb">H5Pget_fapl_srb</a> + <dt><strong>Name:</strong> <a name="Property-SetPreserve">H5Pset_preserve</a> <dt><strong>Signature:</strong> - <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> - ) + <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>Retrieves SRB information. + <dd>Sets the dataset transfer property list status to TRUE or FALSE. <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_preserve</code> sets the + dataset transfer property list status to TRUE or FALSE. <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>. + 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>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>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. - <!-- + <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_preserve_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-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>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>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-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> + +--> + <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_fapl_core" --> +<!-- HEADER RIGHT "H5Pset_vlen_mem_manager" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetFaplCore">H5Pset_fapl_core</a> + <dt><strong>Name:</strong> <a name="Property-SetVLMemManager">H5Pset_vlen_mem_manager</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_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>Modifies the file access property list to use the - <code>H5FD_CORE</code> driver. + <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_fapl_core</code> modifies the file access property list - to use the <code>H5FD_CORE</code> driver. + <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>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. + 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> - <code>increment</code> specifies the increment by which allocated - memory is to be increased each time more memory is required. + 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> - 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. + 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>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. + <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. + <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_core_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> + + + +<!-- --> +<!-- The new *fapl* functions with R1.4 --> +<!-- --> + + + + + + + + + + + + + + + <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pget_fapl_core" --> +<!-- HEADER RIGHT "H5Pget_fapl_mpio" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-GetFaplCore">H5Pget_fapl_core</a> + <dt><strong>Name:</strong> <a name="Property-SetFaplMpiPosix">H5Pget_fapl_mpio</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Pget_fapl_core</code>( + <dd><em>herr_t</em> <code>H5Pset_fapl_mpiposix</code>( <em>hid_t</em> <code>fapl_id</code>, - <em>size_t</em> *<code>increment</code>, - <em>hbool_t</em> *<code>backing_store</code> + <em>MPI_Comm</em> <code>comm</code> ) <dt><strong>Purpose:</strong> - <dd>Queries core file driver properties. + <dd>Stores MPI IO communicator information to a file access property list. <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_fapl_mpiposix</code> stores the user-supplied + MPI IO parameter <code>comm</code>, for communicator, + in the file access property list <code>fapl_id</code>. + That property list can then be used to create and/or open the file. + <p> + <code>H5Pset_fapl_mpiposix</code> is available only in the + parallel HDF5 library and is not a collective function. + <p> + <code>comm</code> is the MPI communicator to be used for + file open as defined in <code>MPI_FILE_OPEN</code> of MPI-2. + This function does not create a duplicated communicator. + Modifications to <code>comm</code> after this function call + returns may have an undetermined effect on the access property list. + Users should not modify the communicator while it is defined + in a property list. <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>MPI_Comm</em> <code>comm</code> + <dd>IN: 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_core_f" + <dd><a href="fortran/h5p_FORTRAN.html#h5pset_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 "H5Pset_fclose_degree" --> +<!-- HEADER RIGHT "H5Pset_multi_type" --> <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-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 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>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>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_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" --> + + + + + + + + + + +<!-- ********** MOVED TO TechNotes/VFLfunc.html ********** + <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-SetDriver">H5Pset_driver</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> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the file driver. + <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> + <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>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_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 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_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> - <!-- <img src="Graphics/Java.gif"> <img src="Graphics/C++.gif"> - --> </dl> +--> + + + + + + + + + + + + + + + + + + + + + + + <!-- ***** TEMPLATE ***** @@ -7731,14 +7894,13 @@ 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 --><SCRIPT LANGUAGE="JAVASCRIPT"> <!-- -document.writeln("Last modified: 3 July 2003"); +document.writeln("Last modified: 3 October 2003"); --> </SCRIPT> diff --git a/doc/html/RM_H5R.html b/doc/html/RM_H5R.html index 138afbd..c1b95a8 100644 --- a/doc/html/RM_H5R.html +++ b/doc/html/RM_H5R.html @@ -61,8 +61,7 @@ And in this document, the </td></tr> </table> </center> -<hr> -<!-- #EndLibraryItem --><center> +<hr><!-- #EndLibraryItem --><center> <h1>H5R: Reference Interface</h1> </center> @@ -279,51 +278,6 @@ facilitate moving easily between them.</i> </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Rget_region" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Reference-GetRegion">H5Rget_region</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t</em> <code>H5Rget_region</code>(<em>hid_t</em> <code>dataset</code>, - <em>H5R_type_t</em> <code>ref_type</code>, - <em>void *</em><code>ref</code> - ) -<dt><strong>Purpose:</strong> - <dd>Retrieves a dataspace with the specified region selected. -<dt><strong>Description:</strong> - <dd>Given a reference to an object <code>ref</code>, - <code>H5Rget_region</code> creates a copy of the dataspace - of the dataset pointed to and defines a selection in the copy - which is the region pointed to. - <p> - The parameter <code>ref_type</code> specifies the reference type - of <code>ref</code>. - <code>ref_type</code> may contain the following value: - <ul> - <li><code>H5R_DATASET_REGION</code> (<code>1</code>) - </ul> -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>dataset</code>, - <dd>IN: Dataset containing reference object. - <dt><em>H5R_type_t</em> <code>ref_type</code>, - <dd>IN: The reference type of <code>ref</code>. - <dt><em>void *</em><code>ref</code> - <dd>IN: Reference to open. - </dl> -<dt><strong>Returns:</strong> - <dd>Returns a valid identifier if successful; - otherwise returns a negative value. -<dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5r_FORTRAN.html#h5rget_region_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 "H5Rget_obj_type" --> <hr> <dl> @@ -443,6 +397,50 @@ facilitate moving easily between them.</i> --> </dl> +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Rget_region" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Reference-GetRegion">H5Rget_region</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t</em> <code>H5Rget_region</code>(<em>hid_t</em> <code>dataset</code>, + <em>H5R_type_t</em> <code>ref_type</code>, + <em>void *</em><code>ref</code> + ) +<dt><strong>Purpose:</strong> + <dd>Retrieves a dataspace with the specified region selected. +<dt><strong>Description:</strong> + <dd>Given a reference to an object <code>ref</code>, + <code>H5Rget_region</code> creates a copy of the dataspace + of the dataset pointed to and defines a selection in the copy + which is the region pointed to. + <p> + The parameter <code>ref_type</code> specifies the reference type + of <code>ref</code>. + <code>ref_type</code> may contain the following value: + <ul> + <li><code>H5R_DATASET_REGION</code> (<code>1</code>) + </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>dataset</code>, + <dd>IN: Dataset containing reference object. + <dt><em>H5R_type_t</em> <code>ref_type</code>, + <dd>IN: The reference type of <code>ref</code>. + <dt><em>void *</em><code>ref</code> + <dd>IN: Reference to open. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a valid identifier if successful; + otherwise returns a negative value. +<dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5r_FORTRAN.html#h5rget_region_f" + target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> + <!-- + <img src="Graphics/Java.gif"> + <img src="Graphics/C++.gif"> + --> +</dl> <!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr> <center> @@ -477,14 +475,13 @@ 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 --><SCRIPT LANGUAGE="JAVASCRIPT"> <!-- -document.writeln("Last modified: 25 June 2003"); +document.writeln("Last modified: 3 October 2003"); --> </SCRIPT> diff --git a/doc/html/RM_H5S.html b/doc/html/RM_H5S.html index 679c9af..7bb5286 100644 --- a/doc/html/RM_H5S.html +++ b/doc/html/RM_H5S.html @@ -61,8 +61,7 @@ And in this document, the </td></tr> </table> </center> -<hr> -<!-- #EndLibraryItem --><center> +<hr><!-- #EndLibraryItem --><center> <h1>H5S: Dataspace Interface</h1> </center> @@ -244,6 +243,70 @@ of the <cite>HDF5 User's Guide.</cite>. <!-- NEW PAGE --> <!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Sclose" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataspace-Close">H5Sclose</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Sclose</code>(<em>hid_t </em><code>space_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Releases and terminates access to a dataspace. +<dt><strong>Description:</strong> + <dd><code>H5Sclose</code> releases a dataspace. + Further access through the dataspace identifier is illegal. + Failure to release a dataspace with this call will + result in resource leaks. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>space_id</code> + <dd>Identifier of dataspace to release. + </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/h5s_FORTRAN.html#h5sclose_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 "H5Scopy" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataspace-Copy">H5Scopy</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Scopy</code>(<em>hid_t </em><code>space_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Creates an exact copy of a dataspace. +<dt><strong>Description:</strong> + <dd><code>H5Scopy</code> creates a new dataspace which is an exact + copy of the dataspace identified by <code>space_id</code>. + The dataspace identifier returned from this function should be + released with <code>H5Sclose</code> or resource leaks will occur. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>space_id</code> + <dd>Identifier of dataspace to copy. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a dataspace identifier if successful; + otherwise returns a negative value. +<dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5s_FORTRAN.html#h5scopy_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 "H5Screate" --> <hr> <dl> @@ -331,30 +394,34 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Scopy" --> +<!-- HEADER RIGHT "H5Sextent_copy" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-Copy">H5Scopy</a> +<dt><strong>Name:</strong> <a name="Dataspace-ExtentCopy">H5Sextent_copy</a> <dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Scopy</code>(<em>hid_t </em><code>space_id</code> + <dd><em>herr_t</em> <code>H5Sextent_copy</code>(<em>hid_t</em> <code>dest_space_id</code>, + <em>hid_t</em> <code>source_space_id</code> ) <dt><strong>Purpose:</strong> - <dd>Creates an exact copy of a dataspace. + <dd>Copies the extent of a dataspace. <dt><strong>Description:</strong> - <dd><code>H5Scopy</code> creates a new dataspace which is an exact - copy of the dataspace identified by <code>space_id</code>. - The dataspace identifier returned from this function should be - released with <code>H5Sclose</code> or resource leaks will occur. + <dd><code>H5Sextent_copy</code> copies the extent from + <code>source_space_id</code> to <code>dest_space_id</code>. + This action may change the type of the dataspace. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>space_id</code> - <dd>Identifier of dataspace to copy. + <dt><em>hid_t</em> <code>dest_space_id</code> + <dd>IN: The identifier for the dataspace to which + the extent is copied. + <dt><em>hid_t</em> <code>source_space_id</code> + <dd>IN: The identifier for the dataspace from which + the extent is copied. </dl> <dt><strong>Returns:</strong> - <dd>Returns a dataspace identifier if successful; + <dd>Returns a non-negative value if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5scopy_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sextent_copy_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -363,113 +430,81 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Sselect_elements" --> +<!-- HEADER RIGHT "H5Sget_select_bounds" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SelectElements">H5Sselect_elements</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectBounds">H5Sget_select_bounds</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Sselect_elements</code>(<em>hid_t </em><code>space_id</code>, - <em>H5S_seloper_t</em> <code>op</code>, - <em>const size_t</em> <code>num_elements</code>, - <em>const hssize_t *</em><code>coord</code>[ ] + <dd><em>herr_t </em><code>H5Sget_select_bounds</code>(<em>hid_t </em><code>space_id</code>, + <em>hssize_t *</em><code>start</code>, + <em>hssize_t *</em><code>end</code> ) <dt><strong>Purpose:</strong> - <dd>Selects array elements to be included in the selection for a dataspace. + <dd>Gets the bounding box containing the current selection. <dt><strong>Description:</strong> - <dd><code>H5Sselect_elements</code> selects array elements to be - included in the selection for the <code>space_id</code> - dataspace. The number of elements selected must be set with - the <code>num_elements</code>. The <code>coord</code> array - is a two-dimensional array of size <em>dataspace rank</em> - by <code>num_elements</code> (ie. a list of coordinates in - the array). The order of the element coordinates in the - <code>coord</code> array also specifies the order in which - the array elements are iterated through when I/O is performed. - Duplicate coordinate locations are not checked for. + <dd><code>H5Sget_select_bounds</code> retrieves the coordinates of + the bounding box containing the current selection and places + them into user-supplied buffers. <p> - The selection operator <code>op</code> determines how the - new selection is to be combined with the previously existing - selection for the dataspace. - The following operators are supported: - <center> - <table width=90% border=0> - <tr><td valign=top> - <code>H5S_SELECT_SET</code> - </td><td valign=top> - Replaces the existing selection with the parameters from this call. - Overlapping blocks are not supported with this operator. -<!-- </td></tr><tr><td valign=top> - <code>H5S_SELECT_OR</code> - </td><td valign=top> ---> Adds the new selection to the existing selection. - </td></tr><tr><td valign=top> - <code>H5S_SELECT_APPEND</code> - </td><td valign=top> - Adds the new selection following the last element of the existing selection. - </td></tr><tr><td valign=top> - <code>H5S_SELECT_PREPEND </code> - </td><td valign=top> - Adds the new selection preceding the first element of the existing selection. - </td></tr> - </table> - </center> -<!-- When operator <code>H5S_SELECT_OR</code> - is used to combine a new selection with an existing selection, - the selection ordering is reset to C array ordering. ---> + The <code>start</code> and <code>end</code> buffers must be large + enough to hold the dataspace rank number of coordinates. + <p> + The bounding box exactly contains the selection. + I.e., if a 2-dimensional element selection is currently + defined as containing the points (4,5), (6,8), and (10,7), + then the bounding box will be (4, 5), (10, 8). + <p> + The bounding box calculation includes the current offset of the + selection within the dataspace extent. + <p> + Calling this function on a <code>none</code> selection will + return <code>FAIL</code>. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>Identifier of the dataspace. - <dt><em>H5S_seloper_t</em> <code>op</code> - <dd>operator specifying how the new selection is to be - combined with the existing selection for the dataspace. - <dt><em>const size_t</em> <code>num_elements</code> - <dd>Number of elements to be selected. - <dt><em>const hssize_t *</em><code>coord</code>[ ] - <dd>A 2-dimensional array specifying the coordinates of the - elements being selected. + <dd>IN: Identifier of dataspace to query. + <dt><em>hssize_t *</em><code>start</code> + <dd>OUT: Starting coordinates of the bounding box. + <dt><em>hssize_t *</em><code>end</code> + <dd>OUT: Ending coordinates of the bounding box, + i.e., the coordinates of the diagonally opposite corner. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; + <dd>Returns a non-negative value if successful; otherwise returns a negative value. +<!-- <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sselect_elements_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_bounds_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 "H5Sselect_all" --> +<!-- HEADER RIGHT "H5Sget_select_elem_npoints" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SelectAll">H5Sselect_all</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectElemNPoints">H5Sget_select_elem_npoints</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Sselect_all</code>(<em>hid_t</em> <code>space_id</code>) + <dd><em>hssize_t </em><code>H5Sget_select_elem_npoints</code>(<em>hid_t </em><code>space_id</code> + ) <dt><strong>Purpose:</strong> - <dd>Selects the entire dataspace. + <dd>Gets the number of element points in the current selection. <dt><strong>Description:</strong> - <dd><code>H5Sselect_all</code> selects the entire extent - of the dataspace <code>space_id</code>. - <p> - More specifically, <code>H5Sselect_all</code> selects - the special <tt>5S_SELECT_ALL</tt> region for the dataspace - <code>space_id</code>. <tt>H5S_SELECT_ALL</tt> selects the - entire dataspace for any dataspace it is applied to. + <dd><code>H5Sget_select_elem_npoints</code> returns + the number of element points in the current dataspace selection. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>IN: The identifier for the dataspace in which the - selection is being made. + <dd>IN: Identifier of dataspace to query. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. + <dd>Returns the number of element points in the current dataspace selection if successful. + Otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sselect_all_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_elem_npoints_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -478,28 +513,57 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Sselect_none" --> +<!-- HEADER RIGHT "H5Sget_select_elem_pointlist" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SelectNone">H5Sselect_none</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectElemPointList">H5Sget_select_elem_pointlist</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Sselect_none</code>(<em>hid_t</em> <code>space_id</code>) + <dd><em>herr_t </em><code>H5Sget_select_elem_pointlist</code>(<em>hid_t </em><code>space_id</code>, + <em>hsize_t </em><code>startpoint</code>, + <em>hsize_t </em><code>numpoints</code>, + <em>hsize_t *</em><code>buf</code> + ) <dt><strong>Purpose:</strong> - <dd>Resets the selection region to include no elements. + <dd>Gets the list of element points currently selected. <dt><strong>Description:</strong> - <dd><code>H5Sselect_none</code> resets the selection region - for the dataspace <code>space_id</code> to include no elements. + <dd><code>H5Sget_select_elem_pointlist</code> returns the list of + element points in the current dataspace selection. Starting with + the <code>startpoint</code>-th point in the list of points, + <code>numpoints</code> points are put into the user's buffer. + If the user's buffer fills up before <code>numpoints</code> + points are inserted, the buffer will contain only as many + points as fit. + <p> + The element point coordinates have the same dimensionality (rank) + as the dataspace they are located within. The list of element points + is formatted as follows: + <br> + <coordinate>, followed by + <br> + the next coordinate, + <br> + etc. + <br> + until all of the selected element points have been listed. + <p> + The points are returned in the order they will be iterated through + when the selection is read/written from/to disk. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>IN: The identifier for the dataspace in which the - selection is being reset. + <dd>IN: Dataspace identifier of selection to query. + <dt><em>hsize_t </em><code>startpoint</code> + <dd>IN: Element point to start with. + <dt><em>hsize_t </em><code>numpoints</code> + <dd>IN: Number of element points to get. + <dt><em>hsize_t *</em><code>buf</code> + <dd>OUT: List of element points selected. </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/h5s_FORTRAN.html#h5sselect_none_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_elem_pointlist_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -508,31 +572,58 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Sselect_valid" --> +<!-- HEADER RIGHT "H5Sget_select_hyper_blocklist" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SelectValid">H5Sselect_valid</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectHyperBlockList">H5Sget_select_hyper_blocklist</a> <dt><strong>Signature:</strong> - <dd><em>htri_t</em> <code>H5Sselect_valid</code>(<em>hid_t</em> <code>space_id</code>) + <dd><em>herr_t </em><code>H5Sget_select_hyper_blocklist</code>(<em>hid_t </em><code>space_id</code>, + <em>hsize_t </em><code>startblock</code>, + <em>hsize_t </em><code>numblocks</code>, + <em>hsize_t *</em><code>buf</code> + ) <dt><strong>Purpose:</strong> - <dd>Verifies that the selection is within the extent of the dataspace. + <dd>Gets the list of hyperslab blocks currently selected. <dt><strong>Description:</strong> - <dd><code>H5Sselect_valid</code> verifies that the selection - for the dataspace <code>space_id</code> is within the extent - of the dataspace if the current offset for the dataspace is used. + <dd><code>H5Sget_select_hyper_blocklist</code> returns a list of + the hyperslab blocks currently selected. Starting with the + <code>startblock</code>-th block in the list of blocks, + <code>numblocks</code> blocks are put into the user's buffer. + If the user's buffer fills up before <code>numblocks</code> + blocks are inserted, the buffer will contain only as many + blocks as fit. + <p> + The block coordinates have the same dimensionality (rank) + as the dataspace they are located within. The list of blocks + is formatted as follows: + <br> + <"start" coordinate>, immediately followed by + <br> + <"opposite" corner coordinate>, followed by + <br> + the next "start" and "opposite" coordinates, + <br> + etc. + <br> + until all of the selected blocks have been listed. + <p> + No guarantee is implied as the order in which blocks are listed. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>The identifier for the dataspace being queried. + <dd>IN: Dataspace identifier of selection to query. + <dt><em>hsize_t </em><code>startblock</code> + <dd>IN: Hyperslab block to start with. + <dt><em>hsize_t </em><code>numblocks</code> + <dd>IN: Number of hyperslab blocks to get. + <dt><em>hsize_t *</em><code>buf</code> + <dd>OUT: List of hyperslab blocks selected. </dl> <dt><strong>Returns:</strong> - <dd>Returns a positive value, for <code>TRUE</code>, - if the selection is contained within the extent - or <code>0</code> (zero), for <code>FALSE</code>, if it is not. - Returns a negative value on error conditions - such as the selection or extent not being defined. + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sselect_valid_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_hyper_blocklist_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -541,28 +632,29 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Sget_simple_extent_npoints" --> +<!-- HEADER RIGHT "H5Sget_select_hyper_nblocks" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-ExtentNpoints">H5Sget_simple_extent_npoints</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectHyperNBlocks">H5Sget_select_hyper_nblocks</a> <dt><strong>Signature:</strong> - <dd><em>hssize_t</em> <code>H5Sget_simple_extent_npoints</code>(<em>hid_t </em><code>space_id</code>) + <dd><em>hssize_t </em><code>H5Sget_select_hyper_nblocks</code>(<em>hid_t </em><code>space_id</code> + ) <dt><strong>Purpose:</strong> - <dd>Determines the number of elements in a dataspace. + <dd>Get number of hyperslab blocks. <dt><strong>Description:</strong> - <dd><code>H5Sget_simple_extent_npoints</code> determines the number of elements - in a dataspace. For example, a simple 3-dimensional dataspace - with dimensions 2, 3, and 4 would have 24 elements. + <dd><code>H5Sget_select_hyper_nblocks</code> returns the + number of hyperslab blocks in the current dataspace selection. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>ID of the dataspace object to query + <dd>IN: Identifier of dataspace to query. </dl> <dt><strong>Returns:</strong> - <dd>Returns the number of elements in the dataspace if successful; - otherwise returns 0. + <dd>Returns the number of hyperslab blocks in + the current dataspace selection if successful. + Otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sget_simple_extent_npoints_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_hyper_nblocks_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -600,27 +692,52 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Sget_simple_extent_ndims" --> +<!-- HEADER RIGHT "H5Sget_select_type" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-ExtentNdims">H5Sget_simple_extent_ndims</a> +<dt><strong>Name:</strong> <a name="Dataspace-GetSelectType">H5Sget_select_type</a> <dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Sget_simple_extent_ndims</code>(<em>hid_t</em> <code>space_id</code>) + <dd><em>H5S_sel_type</em> <code>H5Sget_select_type</code>(<em>hid_t</em> <code>space_id</code>) <dt><strong>Purpose:</strong> - <dd>Determines the dimensionality of a dataspace. + <dd>Determines the type of the dataspace selection. <dt><strong>Description:</strong> - <dd><code>H5Sget_simple_extent_ndims</code> determines the dimensionality (or rank) - of a dataspace. + <dd><code>H5Sget_select_type</code> retrieves the + type of selection currently defined for the dataspace + <code>space_id</code>. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>Identifier of the dataspace + <dd>Dataspace identifier. </dl> <dt><strong>Returns:</strong> - <dd>Returns the number of dimensions in the dataspace if successful; - otherwise returns a negative value. + <dd>Returns the dataspace selection type, a value of + the enumerated datatype <code>H5S_sel_type</code>, + if successful. + Valid return values are as follows: + <center> + <table width=90% border=0> + <tr><td valign=top> + <code>H5S_SEL_NONE</code> + </td><td valign=top> + No selection is defined. + </td></tr><tr><td valign=top> + <code>H5S_SEL_POINTS</code> + </td><td valign=top> + A sequence of points is selected. + </td></tr><tr><td valign=top> + <code>H5S_SEL_HYPERSLABS</code> + </td><td valign=top> + A hyperslab or compound hyperslab is selected. + </td></tr><tr><td valign=top> + <code>H5S_SEL_ALL</code> + </td><td valign=top> + The entire dataset is selected. + </td></tr> + </table> + </center> + Otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sget_simple_extent_ndims_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_type_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -673,32 +790,27 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Sget_simple_extent_type" --> +<!-- HEADER RIGHT "H5Sget_simple_extent_ndims" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-ExtentType">H5Sget_simple_extent_type</a> +<dt><strong>Name:</strong> <a name="Dataspace-ExtentNdims">H5Sget_simple_extent_ndims</a> <dt><strong>Signature:</strong> - <dd><em>H5S_class_t</em> <code>H5Sget_simple_extent_type</code>(<em>hid_t</em> <code>space_id</code>) + <dd><em>int</em> <code>H5Sget_simple_extent_ndims</code>(<em>hid_t</em> <code>space_id</code>) <dt><strong>Purpose:</strong> - <dd>Determine the current class of a dataspace. + <dd>Determines the dimensionality of a dataspace. <dt><strong>Description:</strong> - <dd><code>H5Sget_simple_extent_type</code> queries a dataspace to determine the - current class of a dataspace. - <p> - The function returns a class name, one of the following: - <code>H5S_SCALAR</code>, - <code>H5S_SIMPLE</code>, or - <code>H5S_NONE</code>. + <dd><code>H5Sget_simple_extent_ndims</code> determines the dimensionality (or rank) + of a dataspace. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>Dataspace identifier. + <dd>Identifier of the dataspace </dl> <dt><strong>Returns:</strong> - <dd>Returns a dataspace class name if successful; - otherwise H5S_NO_CLASS (-1). + <dd>Returns the number of dimensions in the dataspace if successful; + otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sget_simple_extent_type_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sget_simple_extent_ndims_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -707,50 +819,62 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Sset_extent_simple" --> +<!-- HEADER RIGHT "H5Sget_simple_extent_npoints" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SetExtentSimple">H5Sset_extent_simple</a> +<dt><strong>Name:</strong> <a name="Dataspace-ExtentNpoints">H5Sget_simple_extent_npoints</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Sset_extent_simple</code>(<em>hid_t</em> <code>space_id</code>, - <em>int</em> <code>rank</code>, - <em>const hsize_t *</em><code>current_size</code>, - <em>const hsize_t *</em><code>maximum_size</code> - ) + <dd><em>hssize_t</em> <code>H5Sget_simple_extent_npoints</code>(<em>hid_t </em><code>space_id</code>) <dt><strong>Purpose:</strong> - <dd>Sets or resets the size of an existing dataspace. + <dd>Determines the number of elements in a dataspace. <dt><strong>Description:</strong> - <dd><code>H5Sset_extent_simple</code> sets or resets the size of - an existing dataspace. - <p> - <code>rank</code> is the dimensionality, or number of - dimensions, of the dataspace. - <p> - <code>current_size</code> is an array of size <code>rank</code> - which contains the new size of each dimension in the dataspace. - <code>maximum_size</code> is an array of size <code>rank</code> - which contains the maximum size of each dimension in the - dataspace. + <dd><code>H5Sget_simple_extent_npoints</code> determines the number of elements + in a dataspace. For example, a simple 3-dimensional dataspace + with dimensions 2, 3, and 4 would have 24 elements. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>space_id</code> + <dd>ID of the dataspace object to query + </dl> +<dt><strong>Returns:</strong> + <dd>Returns the number of elements in the dataspace if successful; + otherwise returns 0. +<dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5s_FORTRAN.html#h5sget_simple_extent_npoints_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 "H5Sget_simple_extent_type" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataspace-ExtentType">H5Sget_simple_extent_type</a> +<dt><strong>Signature:</strong> + <dd><em>H5S_class_t</em> <code>H5Sget_simple_extent_type</code>(<em>hid_t</em> <code>space_id</code>) +<dt><strong>Purpose:</strong> + <dd>Determine the current class of a dataspace. +<dt><strong>Description:</strong> + <dd><code>H5Sget_simple_extent_type</code> queries a dataspace to determine the + current class of a dataspace. <p> - Any previous extent is removed from the dataspace, the dataspace - type is set to <code>H5S_SIMPLE</code>, and the extent is set as - specified. + The function returns a class name, one of the following: + <code>H5S_SCALAR</code>, + <code>H5S_SIMPLE</code>, or + <code>H5S_NONE</code>. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> <dd>Dataspace identifier. - <dt><em>int</em> <code>rank</code> - <dd>Rank, or dimensionality, of the dataspace. - <dt><em>const hsize_t *</em><code>current_size</code> - <dd>Array containing current size of dataspace. - <dt><em>const hsize_t *</em><code>maximum_size</code> - <dd>Array containing maximum size of dataspace. </dl> <dt><strong>Returns:</strong> - <dd>Returns a dataspace identifier if successful; - otherwise returns a negative value. + <dd>Returns a dataspace class name if successful; + otherwise H5S_NO_CLASS (-1). <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sset_extent_simple_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sget_simple_extent_type_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -830,69 +954,34 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> - -<!-- NOT YET IMPLEMENTED (R1.2 -- 9908) - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataspace-ExtentClass">H5Sextent_class</a> -<dt><strong>Signature:</strong> - <dd><em>H5S_class_t</em> <code>H5Sextent_class</code>(<em>hid_t</em> <code>space_id</code>) -<dt><strong>Purpose:</strong> - <dd>Determine the current class of a dataspace. -<dt><strong>Description:</strong> - <dd><code>H5Sextent_class</code> queries a dataspace to determine the - current class of a dataspace. - <p> - The function returns a class name, one of the following: - <code>H5S_SCALAR</code>, - <code>H5S_SIMPLE</code>. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>space_id</code> - <dd>Dataspace identifier. - </dl> -<dt><strong>Returns:</strong> - <dd>Returns a dataspace class name if successful; - otherwise H5S_NO_CLASS (-1). -<dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sextent_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 "H5Sextent_copy" --> +<!-- HEADER RIGHT "H5Sselect_all" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-ExtentCopy">H5Sextent_copy</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectAll">H5Sselect_all</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Sextent_copy</code>(<em>hid_t</em> <code>dest_space_id</code>, - <em>hid_t</em> <code>source_space_id</code> - ) + <dd><em>herr_t</em> <code>H5Sselect_all</code>(<em>hid_t</em> <code>space_id</code>) <dt><strong>Purpose:</strong> - <dd>Copies the extent of a dataspace. + <dd>Selects the entire dataspace. <dt><strong>Description:</strong> - <dd><code>H5Sextent_copy</code> copies the extent from - <code>source_space_id</code> to <code>dest_space_id</code>. - This action may change the type of the dataspace. + <dd><code>H5Sselect_all</code> selects the entire extent + of the dataspace <code>space_id</code>. + <p> + More specifically, <code>H5Sselect_all</code> selects + the special <tt>5S_SELECT_ALL</tt> region for the dataspace + <code>space_id</code>. <tt>H5S_SELECT_ALL</tt> selects the + entire dataspace for any dataspace it is applied to. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>dest_space_id</code> - <dd>IN: The identifier for the dataspace to which - the extent is copied. - <dt><em>hid_t</em> <code>source_space_id</code> - <dd>IN: The identifier for the dataspace from which - the extent is copied. + <dt><em>hid_t</em> <code>space_id</code> + <dd>IN: The identifier for the dataspace in which the + selection is being made. </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/h5s_FORTRAN.html#h5sextent_copy_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sselect_all_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -901,28 +990,78 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Sset_extent_none" --> +<!-- HEADER RIGHT "H5Sselect_elements" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SetExtentNone">H5Sset_extent_none</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectElements">H5Sselect_elements</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Sset_extent_none</code>(<em>hid_t</em> <code>space_id</code>) + <dd><em>herr_t</em> <code>H5Sselect_elements</code>(<em>hid_t </em><code>space_id</code>, + <em>H5S_seloper_t</em> <code>op</code>, + <em>const size_t</em> <code>num_elements</code>, + <em>const hssize_t *</em><code>coord</code>[ ] + ) <dt><strong>Purpose:</strong> - <dd>Removes the extent from a dataspace. + <dd>Selects array elements to be included in the selection for a dataspace. <dt><strong>Description:</strong> - <dd><code>H5Sset_extent_none</code> removes the extent from - a dataspace and sets the type to <tt>H5S_NO_CLASS</tt>. + <dd><code>H5Sselect_elements</code> selects array elements to be + included in the selection for the <code>space_id</code> + dataspace. The number of elements selected must be set with + the <code>num_elements</code>. The <code>coord</code> array + is a two-dimensional array of size <em>dataspace rank</em> + by <code>num_elements</code> (ie. a list of coordinates in + the array). The order of the element coordinates in the + <code>coord</code> array also specifies the order in which + the array elements are iterated through when I/O is performed. + Duplicate coordinate locations are not checked for. + <p> + The selection operator <code>op</code> determines how the + new selection is to be combined with the previously existing + selection for the dataspace. + The following operators are supported: + <center> + <table width=90% border=0> + <tr><td valign=top> + <code>H5S_SELECT_SET</code> + </td><td valign=top> + Replaces the existing selection with the parameters from this call. + Overlapping blocks are not supported with this operator. +<!-- </td></tr><tr><td valign=top> + <code>H5S_SELECT_OR</code> + </td><td valign=top> +--> Adds the new selection to the existing selection. + </td></tr><tr><td valign=top> + <code>H5S_SELECT_APPEND</code> + </td><td valign=top> + Adds the new selection following the last element of the existing selection. + </td></tr><tr><td valign=top> + <code>H5S_SELECT_PREPEND </code> + </td><td valign=top> + Adds the new selection preceding the first element of the existing selection. + </td></tr> + </table> + </center> +<!-- When operator <code>H5S_SELECT_OR</code> + is used to combine a new selection with an existing selection, + the selection ordering is reset to C array ordering. +--> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>The identifier for the dataspace from which - the extent is to be removed. + <dd>Identifier of the dataspace. + <dt><em>H5S_seloper_t</em> <code>op</code> + <dd>operator specifying how the new selection is to be + combined with the existing selection for the dataspace. + <dt><em>const size_t</em> <code>num_elements</code> + <dd>Number of elements to be selected. + <dt><em>const hssize_t *</em><code>coord</code>[ ] + <dd>A 2-dimensional array specifying the coordinates of the + elements being selected. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; + <dd>Returns a non-negative value if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sset_extent_none_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sselect_elements_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1068,29 +1207,28 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Sget_select_hyper_nblocks" --> +<!-- HEADER RIGHT "H5Sselect_none" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SelectHyperNBlocks">H5Sget_select_hyper_nblocks</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectNone">H5Sselect_none</a> <dt><strong>Signature:</strong> - <dd><em>hssize_t </em><code>H5Sget_select_hyper_nblocks</code>(<em>hid_t </em><code>space_id</code> - ) + <dd><em>herr_t</em> <code>H5Sselect_none</code>(<em>hid_t</em> <code>space_id</code>) <dt><strong>Purpose:</strong> - <dd>Get number of hyperslab blocks. + <dd>Resets the selection region to include no elements. <dt><strong>Description:</strong> - <dd><code>H5Sget_select_hyper_nblocks</code> returns the - number of hyperslab blocks in the current dataspace selection. + <dd><code>H5Sselect_none</code> resets the selection region + for the dataspace <code>space_id</code> to include no elements. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>IN: Identifier of dataspace to query. + <dd>IN: The identifier for the dataspace in which the + selection is being reset. </dl> <dt><strong>Returns:</strong> - <dd>Returns the number of hyperslab blocks in - the current dataspace selection 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/h5s_FORTRAN.html#h5sget_select_hyper_nblocks_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sselect_none_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1099,58 +1237,31 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Sget_select_hyper_blocklist" --> +<!-- HEADER RIGHT "H5Sselect_valid" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SelectHyperBlockList">H5Sget_select_hyper_blocklist</a> +<dt><strong>Name:</strong> <a name="Dataspace-SelectValid">H5Sselect_valid</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Sget_select_hyper_blocklist</code>(<em>hid_t </em><code>space_id</code>, - <em>hsize_t </em><code>startblock</code>, - <em>hsize_t </em><code>numblocks</code>, - <em>hsize_t *</em><code>buf</code> - ) + <dd><em>htri_t</em> <code>H5Sselect_valid</code>(<em>hid_t</em> <code>space_id</code>) <dt><strong>Purpose:</strong> - <dd>Gets the list of hyperslab blocks currently selected. + <dd>Verifies that the selection is within the extent of the dataspace. <dt><strong>Description:</strong> - <dd><code>H5Sget_select_hyper_blocklist</code> returns a list of - the hyperslab blocks currently selected. Starting with the - <code>startblock</code>-th block in the list of blocks, - <code>numblocks</code> blocks are put into the user's buffer. - If the user's buffer fills up before <code>numblocks</code> - blocks are inserted, the buffer will contain only as many - blocks as fit. - <p> - The block coordinates have the same dimensionality (rank) - as the dataspace they are located within. The list of blocks - is formatted as follows: - <br> - <"start" coordinate>, immediately followed by - <br> - <"opposite" corner coordinate>, followed by - <br> - the next "start" and "opposite" coordinates, - <br> - etc. - <br> - until all of the selected blocks have been listed. - <p> - No guarantee is implied as the order in which blocks are listed. + <dd><code>H5Sselect_valid</code> verifies that the selection + for the dataspace <code>space_id</code> is within the extent + of the dataspace if the current offset for the dataspace is used. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>IN: Dataspace identifier of selection to query. - <dt><em>hsize_t </em><code>startblock</code> - <dd>IN: Hyperslab block to start with. - <dt><em>hsize_t </em><code>numblocks</code> - <dd>IN: Number of hyperslab blocks to get. - <dt><em>hsize_t *</em><code>buf</code> - <dd>OUT: List of hyperslab blocks selected. + <dd>The identifier for the dataspace being queried. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. + <dd>Returns a positive value, for <code>TRUE</code>, + if the selection is contained within the extent + or <code>0</code> (zero), for <code>FALSE</code>, if it is not. + Returns a negative value on error conditions + such as the selection or extent not being defined. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_hyper_blocklist_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sselect_valid_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1159,28 +1270,28 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Sget_select_elem_npoints" --> +<!-- HEADER RIGHT "H5Sset_extent_none" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SelectElemNPoints">H5Sget_select_elem_npoints</a> +<dt><strong>Name:</strong> <a name="Dataspace-SetExtentNone">H5Sset_extent_none</a> <dt><strong>Signature:</strong> - <dd><em>hssize_t </em><code>H5Sget_select_elem_npoints</code>(<em>hid_t </em><code>space_id</code> - ) + <dd><em>herr_t</em> <code>H5Sset_extent_none</code>(<em>hid_t</em> <code>space_id</code>) <dt><strong>Purpose:</strong> - <dd>Gets the number of element points in the current selection. + <dd>Removes the extent from a dataspace. <dt><strong>Description:</strong> - <dd><code>H5Sget_select_elem_npoints</code> returns - the number of element points in the current dataspace selection. + <dd><code>H5Sset_extent_none</code> removes the extent from + a dataspace and sets the type to <tt>H5S_NO_CLASS</tt>. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>IN: Identifier of dataspace to query. + <dd>The identifier for the dataspace from which + the extent is to be removed. </dl> <dt><strong>Returns:</strong> - <dd>Returns the number of element points in the current dataspace selection 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/h5s_FORTRAN.html#h5sget_select_elem_npoints_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sset_extent_none_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1189,57 +1300,50 @@ of the <cite>HDF5 User's Guide.</cite>. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Sget_select_elem_pointlist" --> +<!-- HEADER RIGHT "H5Sset_extent_simple" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SelectElemPointList">H5Sget_select_elem_pointlist</a> +<dt><strong>Name:</strong> <a name="Dataspace-SetExtentSimple">H5Sset_extent_simple</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Sget_select_elem_pointlist</code>(<em>hid_t </em><code>space_id</code>, - <em>hsize_t </em><code>startpoint</code>, - <em>hsize_t </em><code>numpoints</code>, - <em>hsize_t *</em><code>buf</code> + <dd><em>herr_t</em> <code>H5Sset_extent_simple</code>(<em>hid_t</em> <code>space_id</code>, + <em>int</em> <code>rank</code>, + <em>const hsize_t *</em><code>current_size</code>, + <em>const hsize_t *</em><code>maximum_size</code> ) <dt><strong>Purpose:</strong> - <dd>Gets the list of element points currently selected. + <dd>Sets or resets the size of an existing dataspace. <dt><strong>Description:</strong> - <dd><code>H5Sget_select_elem_pointlist</code> returns the list of - element points in the current dataspace selection. Starting with - the <code>startpoint</code>-th point in the list of points, - <code>numpoints</code> points are put into the user's buffer. - If the user's buffer fills up before <code>numpoints</code> - points are inserted, the buffer will contain only as many - points as fit. + <dd><code>H5Sset_extent_simple</code> sets or resets the size of + an existing dataspace. <p> - The element point coordinates have the same dimensionality (rank) - as the dataspace they are located within. The list of element points - is formatted as follows: - <br> - <coordinate>, followed by - <br> - the next coordinate, - <br> - etc. - <br> - until all of the selected element points have been listed. + <code>rank</code> is the dimensionality, or number of + dimensions, of the dataspace. <p> - The points are returned in the order they will be iterated through - when the selection is read/written from/to disk. + <code>current_size</code> is an array of size <code>rank</code> + which contains the new size of each dimension in the dataspace. + <code>maximum_size</code> is an array of size <code>rank</code> + which contains the maximum size of each dimension in the + dataspace. + <p> + Any previous extent is removed from the dataspace, the dataspace + type is set to <code>H5S_SIMPLE</code>, and the extent is set as + specified. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>IN: Dataspace identifier of selection to query. - <dt><em>hsize_t </em><code>startpoint</code> - <dd>IN: Element point to start with. - <dt><em>hsize_t </em><code>numpoints</code> - <dd>IN: Number of element points to get. - <dt><em>hsize_t *</em><code>buf</code> - <dd>OUT: List of element points selected. + <dd>Dataspace identifier. + <dt><em>int</em> <code>rank</code> + <dd>Rank, or dimensionality, of the dataspace. + <dt><em>const hsize_t *</em><code>current_size</code> + <dd>Array containing current size of dataspace. + <dt><em>const hsize_t *</em><code>maximum_size</code> + <dd>Array containing maximum size of dataspace. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; + <dd>Returns a dataspace identifier if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_elem_pointlist_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sset_extent_simple_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1247,63 +1351,39 @@ of the <cite>HDF5 User's Guide.</cite>. --> </dl> -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Sget_select_bounds" --> + +<!-- NOT YET IMPLEMENTED (R1.2 -- 9908) + <hr> <dl> -<dt><strong>Name:</strong> <a name="Dataspace-SelectBounds">H5Sget_select_bounds</a> +<dt><strong>Name:</strong> <a name="Dataspace-ExtentClass">H5Sextent_class</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Sget_select_bounds</code>(<em>hid_t </em><code>space_id</code>, - <em>hssize_t *</em><code>start</code>, - <em>hssize_t *</em><code>end</code> - ) + <dd><em>H5S_class_t</em> <code>H5Sextent_class</code>(<em>hid_t</em> <code>space_id</code>) <dt><strong>Purpose:</strong> - <dd>Gets the bounding box containing the current selection. + <dd>Determine the current class of a dataspace. <dt><strong>Description:</strong> - <dd><code>H5Sget_select_bounds</code> retrieves the coordinates of - the bounding box containing the current selection and places - them into user-supplied buffers. - <p> - The <code>start</code> and <code>end</code> buffers must be large - enough to hold the dataspace rank number of coordinates. - <p> - The bounding box exactly contains the selection. - I.e., if a 2-dimensional element selection is currently - defined as containing the points (4,5), (6,8), and (10,7), - then the bounding box will be (4, 5), (10, 8). - <p> - The bounding box calculation includes the current offset of the - selection within the dataspace extent. + <dd><code>H5Sextent_class</code> queries a dataspace to determine the + current class of a dataspace. <p> - Calling this function on a <code>none</code> selection will - return <code>FAIL</code>. + The function returns a class name, one of the following: + <code>H5S_SCALAR</code>, + <code>H5S_SIMPLE</code>. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>space_id</code> - <dd>IN: Identifier of dataspace to query. - <dt><em>hssize_t *</em><code>start</code> - <dd>OUT: Starting coordinates of the bounding box. - <dt><em>hssize_t *</em><code>end</code> - <dd>OUT: Ending coordinates of the bounding box, - i.e., the coordinates of the diagonally opposite corner. + <dd>Dataspace identifier. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. -<!-- + <dd>Returns a dataspace class name if successful; + otherwise H5S_NO_CLASS (-1). <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_bounds_f" + <dd><a href="fortran/h5s_FORTRAN.html#h5sextent_class_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> ---> <!-- <img src="Graphics/Java.gif"> <img src="Graphics/C++.gif"> - --> </dl> - - - - +--> <!--<hr> @@ -1353,92 +1433,6 @@ of the <cite>HDF5 User's Guide.</cite>. <!--</dl> --> -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Sget_select_type" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataspace-GetSelectType">H5Sget_select_type</a> -<dt><strong>Signature:</strong> - <dd><em>H5S_sel_type</em> <code>H5Sget_select_type</code>(<em>hid_t</em> <code>space_id</code>) -<dt><strong>Purpose:</strong> - <dd>Determines the type of the dataspace selection. -<dt><strong>Description:</strong> - <dd><code>H5Sget_select_type</code> retrieves the - type of selection currently defined for the dataspace - <code>space_id</code>. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>space_id</code> - <dd>Dataspace identifier. - </dl> -<dt><strong>Returns:</strong> - <dd>Returns the dataspace selection type, a value of - the enumerated datatype <code>H5S_sel_type</code>, - if successful. - Valid return values are as follows: - <center> - <table width=90% border=0> - <tr><td valign=top> - <code>H5S_SEL_NONE</code> - </td><td valign=top> - No selection is defined. - </td></tr><tr><td valign=top> - <code>H5S_SEL_POINTS</code> - </td><td valign=top> - A sequence of points is selected. - </td></tr><tr><td valign=top> - <code>H5S_SEL_HYPERSLABS</code> - </td><td valign=top> - A hyperslab or compound hyperslab is selected. - </td></tr><tr><td valign=top> - <code>H5S_SEL_ALL</code> - </td><td valign=top> - The entire dataset is selected. - </td></tr> - </table> - </center> - Otherwise returns a negative value. -<dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5s_FORTRAN.html#h5sget_select_type_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 "H5Sclose" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Dataspace-Close">H5Sclose</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Sclose</code>(<em>hid_t </em><code>space_id</code> - ) -<dt><strong>Purpose:</strong> - <dd>Releases and terminates access to a dataspace. -<dt><strong>Description:</strong> - <dd><code>H5Sclose</code> releases a dataspace. - Further access through the dataspace identifier is illegal. - Failure to release a dataspace with this call will - result in resource leaks. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>space_id</code> - <dd>Identifier of dataspace to release. - </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/h5s_FORTRAN.html#h5sclose_f" - target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> - <!-- - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - <!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr> <center> @@ -1473,14 +1467,13 @@ 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 --><SCRIPT LANGUAGE="JAVASCRIPT"> <!-- -document.writeln("Last modified: 10 June 2003"); +document.writeln("Last modified: 3 October 2003"); --> </SCRIPT> diff --git a/doc/html/RM_H5T.html b/doc/html/RM_H5T.html index de24e6c..d5c8fdc 100644 --- a/doc/html/RM_H5T.html +++ b/doc/html/RM_H5T.html @@ -61,8 +61,7 @@ And in this document, the </td></tr> </table> </center> -<hr> -<!-- #EndLibraryItem --><center> +<hr><!-- #EndLibraryItem --><center> <h1>H5T: Datatype Interface</h1> </center> @@ -386,34 +385,87 @@ in the <cite>HDF5 User's Guide</cite> for further information, including a compl <!-- NEW PAGE --> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Topen" --> +<!-- HEADER RIGHT "H5Tarray_create" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-Open">H5Topen</a> +<dt><strong>Name:</strong> <a name="Datatype-ArrayCreate">H5Tarray_create</a> <dt><strong>Signature:</strong> - <dd><em>hid_t</em><code>H5Topen</code>(<em>hid_t</em> <code>loc_id</code>, - <em>const char *</em> <code>name</code> + <dd><em>hid_t</em> <code>H5Tarray_create</code>( + <em>hid_t</em> <code>base</code>, + <em>int</em> <code>rank</code>, + <em>const hsize_t</em> <code>dims[/*rank*/]</code>, + <em>const int</em> <code>perm[/*rank*/]</code> ) <dt><strong>Purpose:</strong> - <dd>Opens a named datatype. + <dd>Creates an array datatype object. <dt><strong>Description:</strong> - <dd><code>H5Topen</code> opens a named datatype at the location - specified by <code>loc_id</code> and returns an identifier - for the datatype. <code>loc_id</code> is either a file or - group identifier. The identifier should eventually be closed - by calling <code>H5Tclose</code> to release resources. + <dd><code>H5Tarray_create</code> creates a new array datatype object. + <p> + <code>base</code> is the datatype of every element of the array, + i.e., of the number at each position in the array. + <p> + <code>rank</code> is the number of dimensions and the + size of each dimension is specified in the array <code>dims</code>. + The value of <code>rank</code> is currently limited to + <code>H5S_MAX_RANK</code> and must be greater than <code>0</code> + (zero). + All dimension sizes specified in <code>dims</code> must be greater + than <code>0</code> (zero). + <p> + The array <code>perm</code> is designed to contain the dimension + permutation, i.e. C versus FORTRAN array order. + + <b><i>(The parameter </i><code>perm</code><i> is currently unused and is not yet implemented.)</i></b> + <p> <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>loc_id</code> - <dd>IN: A file or group identifier. - <dt><em>const char *</em> <code>name</code> - <dd>IN: A datatype name, defined within the file or group identified by <code>loc_id</code>. + <dt><em>hid_t</em> <code>base</code> + <dd>IN: Datatype identifier for the array base datatype. + <dt><em>int</em> <code>rank</code> + <dd>IN: Rank of the array. + <dt><em>const hsize_t</em> <code>dims[/*rank*/]</code> + <dd>IN: Size of each array dimension. + <dt><em>const int</em> <code>perm[/*rank*/]</code> + <dd>IN: Dimension permutation. + + <b><i>(Currently not implemented.)</i></b> </dl> <dt><strong>Returns:</strong> - <dd>Returns a named datatype identifier if successful; + <dd>Returns a non-negative value if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5topen_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tarray_create_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 "H5Tclose" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Close">H5Tclose</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tclose</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Releases a datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tclose</code> releases a datatype. Further access + through the datatype identifier is illegal. Failure to release + a datatype with this call will result in resource leaks. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to release. + </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/h5t_FORTRAN.html#h5tclose_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -497,48 +549,6 @@ in the <cite>HDF5 User's Guide</cite> for further information, including a compl </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tfind" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-Find">H5Tfind</a> -<dt><strong>Signature:</strong> - <dd><em>H5T_conv_t</em> <code>H5Tfind</code>(<em>hid_t</em> <code>src_id</code>, - <em>hid_t</em> <code>dst_id</code>, - <em>H5T_cdata_t **</em><code>pcdata</code> - ) -<dt><strong>Purpose:</strong> - <dd>Finds a conversion function. -<dt><strong>Description:</strong> - <dd><code>H5Tfind</code> finds a conversion function that can - handle a conversion from type <code>src_id</code> to type - <code>dst_id</code>. - The <code>pcdata</code> argument is a pointer to a pointer - to type conversion data which was created and initialized - by the soft type conversion function of this path when the - conversion function was installed on the path. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>src_id</code> - <dd>IN: Identifier for the source datatype. - <dt><em>hid_t</em> <code>dst_id</code> - <dd>IN: Identifier for the destination datatype. - <dt><em>H5T_cdata_t **</em><code>pcdata</code> - <dd>OUT: Pointer to type conversion data. - </dl> -<dt><strong>Returns:</strong> - <dd>Returns a pointer to a suitable conversion function if successful. - Otherwise returns NULL. -<!-- -<dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tfind_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 "H5Tconvert" --> <hr> <dl> @@ -601,204 +611,6 @@ in the <cite>HDF5 User's Guide</cite> for further information, including a compl </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tset_overflow" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-SetOverflow">H5Tset_overflow</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Tset_overflow</code>(<em>H5T_overflow_t</em> <code>func</code>) -<dt><strong>Purpose:</strong> - <dd>Sets the overflow handler to a specified function. -<dt><strong>Description:</strong> - <dd><code>H5Tset_overflow</code> sets the overflow handler - to be the function specified by <code>func</code>. - <code>func</code> will be called for all datatype conversions that - result in an overflow. - <p> - See the definition of <code>H5T_overflow_t</code> in - <code>H5Tpublic.h</code> for documentation - of arguments and return values. - The prototype for <code>H5T_overflow_t</code> is as follows:<br> - <code>herr_t (*H5T_overflow_t)(hid_t src_id, hid_t dst_id, - void *src_buf, void *dst_buf); - </code> - <p> - The NULL pointer may be passed to remove the overflow handler. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>H5T_overflow_t</em> <code>func</code> - <dd>Overflow 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/h5t_FORTRAN.html#h5tset_overflow_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 "H5Tget_overflow" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-GetOverflow">H5Tget_overflow</a> -<dt><strong>Signature:</strong> - - -H5Tget_overflow () - <dd><em>H5T_overflow_t</em> <code>H5Tget_overflow</code>(<code>void</code>) -<dt><strong>Purpose:</strong> - <dd>Returns a pointer to the current global overflow function. -<dt><strong>Description:</strong> - <dd><code>H5Tset_overflow</code> returns a pointer - to the current global overflow function. - This is an application-defined function that is called whenever a - datatype conversion causes an overflow. -<dt><strong>Parameters:</strong> - <dl> - <dt>None. - </dl> -<dt><strong>Returns:</strong> - <dd>Returns a pointer to an application-defined function if successful. - Otherwise returns NULL; this can happen if no overflow handling - function is registered. -<!-- -<dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_overflow_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 "H5Tcreate" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-Create">H5Tcreate</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Tcreate</code>(<em>H5T_class_t </em><code>class</code>, - <em>size_t</em><code>size</code> - ) -<dt><strong>Purpose:</strong> - <dd>Creates a new datatype. -<dt><strong>Description:</strong> - <dd><code>H5Tcreate</code> creates a new datatype of the specified - class with the specified number of bytes. - <p> - The following datatype classes are supported with this function: - <ul> - <li><code>H5T_COMPOUND</code> - <li><code>H5T_OPAQUE</code> - <li><code>H5T_ENUM</code> - </ul> - <p> - Use <code>H5Tcopy</code> to create integer or floating-point datatypes. - <p> - The datatype identifier returned from this function should be - released with <code>H5Tclose</code> or resource leaks will result. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>H5T_class_t</em> <code>class</code> - <dd>Class of datatype to create. - <dt><em>size_t</em> <code>size</code> - <dd>The number of bytes in the datatype to create. - </dl> -<dt><strong>Returns:</strong> - <dd>Returns datatype identifier if successful; - otherwise returns a negative value. -<dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tcreate_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 "H5Tvlen_create" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-VLCreate">H5Tvlen_create</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t </em><code>H5Tvlen_create</code>(<em>hid_t </em><code>base_type_id</code> - ) -<dt><strong>Purpose:</strong> - <dd>Creates a new variable-length datatype. -<dt><strong>Description:</strong> - <dd><code>H5Tvlen_create</code> creates a new variable-length (VL) datatype. - <p> - The base datatype will be the datatype that the sequence is composed of, - characters for character strings, vertex coordinates for polygon lists, etc. - The base type specified for the VL datatype can be of any HDF5 datatype, - including another VL datatype, a compound datatype or an atomic datatype. - <p> - When necessary, use <code>H5Tget_super</code> to determine the base type - of the VL datatype. - <p> - The datatype identifier returned from this function should be - released with <code>H5Tclose</code> or resource leaks will result. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>base_type_id</code> - <dd>Base type of datatype to create. - </dl> -<dt><strong>See Also:</strong> - <dd><a href="RM_H5D.html#Dataset-GetVLBuf">H5Dget_vlen_buf_size</a> - <dd><a href="RM_H5D.html#Dataset-VLReclaim">H5Dvlen_reclaim</a> -<dt><strong>Returns:</strong> - <dd>Returns datatype identifier if successful; - otherwise returns a negative value. -<dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tvlen_create_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 "H5Tis_variable_str" --> -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Datatype-IsVariableString">H5Tis_variable_str</a> -<dt><strong>Signature:</strong> - <dd><em>htri_t </em><code>H5Tis_variable_str</code>(<em>hid_t </em><code>dtype_id</code> - ) -<dt><strong>Purpose:</strong> - <dd>Determines whether datatype is a variable-length string. -<dt><strong>Description:</strong> - <dd><code>H5Tvlen_create</code> determines whether the datatype - identified in <code>dtype_id</code> is a variable-length string. - <p> - This function can be used to distinguish between - fixed and variable-length string datatypes. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>dtype_id</code> - <dd>Datatype identifier. - </dl> -<dt><strong>Returns:</strong> - <dd>Returns <code>TRUE</code> or <code>FALSE</code> if successful; - otherwise returns a negative value. -<dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tis_variable_str_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 "H5Tcopy" --> <hr> <dl> @@ -894,33 +706,43 @@ H5Tget_overflow () </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tequal" --> +<!-- HEADER RIGHT "H5Tcreate" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-Equal">H5Tequal</a> +<dt><strong>Name:</strong> <a name="Datatype-Create">H5Tcreate</a> <dt><strong>Signature:</strong> - <dd><em>htri_t </em><code>H5Tequal</code>(<em>hid_t </em><code>type_id1</code>, - <em>hid_t</em><code>type_id2</code> + <dd><em>hid_t </em><code>H5Tcreate</code>(<em>H5T_class_t </em><code>class</code>, + <em>size_t</em><code>size</code> ) <dt><strong>Purpose:</strong> - <dd>Determines whether two datatype identifiers refer to the same datatype. + <dd>Creates a new datatype. <dt><strong>Description:</strong> - <dd><code>H5Tequal</code> determines whether two datatype identifiers - refer to the same datatype. + <dd><code>H5Tcreate</code> creates a new datatype of the specified + class with the specified number of bytes. + <p> + The following datatype classes are supported with this function: + <ul> + <li><code>H5T_COMPOUND</code> + <li><code>H5T_OPAQUE</code> + <li><code>H5T_ENUM</code> + </ul> + <p> + Use <code>H5Tcopy</code> to create integer or floating-point datatypes. + <p> + The datatype identifier returned from this function should be + released with <code>H5Tclose</code> or resource leaks will result. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>type_id1</code> - <dd>Identifier of datatype to compare. - <dt><em>hid_t</em> <code>type_id2</code> - <dd>Identifier of datatype to compare. + <dt><em>H5T_class_t</em> <code>class</code> + <dd>Class of datatype to create. + <dt><em>size_t</em> <code>size</code> + <dd>The number of bytes in the datatype to create. </dl> <dt><strong>Returns:</strong> - <dd>When successful, returns a positive value, for <code>TRUE</code>, - if the datatype identifiers refer to the same datatype, - or <code>0</code> (zero), for <code>FALSE</code>. - Otherwise returns a negative value. + <dd>Returns datatype identifier if successful; + otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tequal_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tcreate_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -929,33 +751,40 @@ H5Tget_overflow () </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tlock" --> +<!-- HEADER RIGHT "H5Tdetect_class" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-Lock">H5Tlock</a> +<dt><strong>Name:</strong> <a name="Datatype-DetectClass">H5Tdetect_class</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tlock</code>(<em>hid_t </em><code>type_id</code> + <dd><em>htri_t </em><code>H5Tdetect_class</code>(<em>hid_t</em> <code>dtype_id</code>, + <em>H5T_class_t</em><code>dtype_class</code> ) <dt><strong>Purpose:</strong> - <dd>Locks a datatype. + <dd>Determines whether a datatype contains any datatypes of the + given datatype class. <dt><strong>Description:</strong> - <dd><code>H5Tlock</code> locks the datatype specified by the - <code>type_id</code> identifier, making it read-only and - non-destructible. This is normally done by the library for - predefined datatypes so the application does not - inadvertently change or delete a predefined type. - Once a datatype is locked it can never be unlocked. + <dd><code>H5Tdetect_class</code> determines whether the datatype + specified in <code>dtype_id</code> contains any datatypes of the + datatype class specified in <code>dtype_class</code>. + <p> + This function is useful primarily in recursively examining + all the fields and/or base types + of compound, array, and variable-length datatypes. + <p> + Valid class identifiers are as defined in + <a href="#Datatype-GetClass"><code>H5Tget_class</code></a>. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to lock. + <dt><em>hid_t</em> <code>dtype_id</code> + <dd>Datatype identifier. + <dt><em>H5T_class_t</em><code>dtype_class</code> + <dd>Datatype class. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; + <dd>Returns <code>TRUE</code> or <code>FALSE</code> if successful; otherwise returns a negative value. -<!-- -<dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tlock_f" +<!--<dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5t_FORTRAN.html#h5tdetect_class_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> --> <!-- <img src="Graphics/Java.gif"> @@ -964,41 +793,29 @@ H5Tget_overflow () </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_class" --> +<!-- HEADER RIGHT "H5Tenum_create" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetClass">H5Tget_class</a> +<dt><strong>Name:</strong> <a name="Datatype-EnumCreate">H5Tenum_create</a> <dt><strong>Signature:</strong> - <dd><em>H5T_class_t </em><code>H5Tget_class</code>(<em>hid_t </em><code>type_id</code> + <dd><em>hid_t</em> <code>H5Tenum_create</code>(<em>hid_t</em> <code>parent_id</code> ) <dt><strong>Purpose:</strong> - <dd>Returns the datatype class identifier. + <dd>Creates a new enumeration datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_class</code> returns the datatype class identifier. - <p> - Valid class identifiers, as defined in <code>H5Tpublic.h</code>, are: - <ul><li><code>H5T_INTEGER</code> - <li><code>H5T_FLOAT</code> - <li><code>H5T_TIME</code> - <li><code>H5T_STRING</code> - <li><code>H5T_BITFIELD</code> - <li><code>H5T_OPAQUE</code> - <li><code>H5T_COMPOUND</code> - <li><code>H5T_REFERENCE</code> - <li><code>H5T_ENUM</code> - <li><code>H5T_VLEN</code> - <li><code>H5T_ARRAY</code> - </ul> + <dd><code>H5Tenum_create</code> creates a new enumeration datatype + based on the specified base datatype, <code>parent_id</code>, + which must be an integer type. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to query. + <dt><em>hid_t</em> <code>parent_id</code> + <dd>IN: Datatype identifier for the base datatype. </dl> <dt><strong>Returns:</strong> - <dd>Returns datatype class identifier if successful; - otherwise <code>H5T_NO_CLASS</code> (-1). + <dd>Returns the datatype identifier for the new enumeration datatype if successful; + otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_class_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tenum_create_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1007,69 +824,94 @@ H5Tget_overflow () </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tdetect_class" --> +<!-- HEADER RIGHT "H5Tenum_insert" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-DetectClass">H5Tdetect_class</a> +<dt><strong>Name:</strong> <a name="Datatype-EnumInsert">H5Tenum_insert</a> <dt><strong>Signature:</strong> - <dd><em>htri_t </em><code>H5Tdetect_class</code>(<em>hid_t</em> <code>dtype_id</code>, - <em>H5T_class_t</em><code>dtype_class</code> + <dd><em>herr_t</em> <code>H5Tenum_insert</code>(<em>hid_t</em> <code>type</code>, + <em>const char</em> *<code>name</code>, + <em>void</em> *<code>value</code> ) <dt><strong>Purpose:</strong> - <dd>Determines whether a datatype contains any datatypes of the - given datatype class. + <dd>Inserts a new enumeration datatype member. <dt><strong>Description:</strong> - <dd><code>H5Tdetect_class</code> determines whether the datatype - specified in <code>dtype_id</code> contains any datatypes of the - datatype class specified in <code>dtype_class</code>. + <dd><code>H5Tenum_insert</code> inserts a + new enumeration datatype member into an enumeration datatype. <p> - This function is useful primarily in recursively examining - all the fields and/or base types - of compound, array, and variable-length datatypes. + <code>type</code> is the enumeration datatype, + <code>name</code> is the name of the new member, and + <code>value</code> points to the value of the new member. <p> - Valid class identifiers are as defined in - <a href="#Datatype-GetClass"><code>H5Tget_class</code></a>. + <code>name</code> and <code>value</code> must both + be unique within <code>type</code>. + <p> + <code>value</code> points to data which is of the + datatype defined when the enumeration datatype was created. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>dtype_id</code> - <dd>Datatype identifier. - <dt><em>H5T_class_t</em><code>dtype_class</code> - <dd>Datatype class. + <dt><em>hid_t</em> <code>type</code> + <dd>IN: Datatype identifier for the enumeration datatype. + <dt><em>const char</em> *<code>name</code> + <dd>IN: Name of the new member. + <dt><em>void</em> *<code>value</code> + <dd>IN: Pointer to the value of the new member. </dl> <dt><strong>Returns:</strong> - <dd>Returns <code>TRUE</code> or <code>FALSE</code> if successful; + <dd>Returns a non-negative value if successful; otherwise returns a negative value. -<!--<dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tdetect_class_f" +<dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5t_FORTRAN.html#h5tenum_insert_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 "H5Tget_size" --> +<!-- HEADER RIGHT "H5Tenum_nameof" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetSize">H5Tget_size</a> +<dt><strong>Name:</strong> <a name="Datatype-EnumNameOf">H5Tenum_nameof</a> <dt><strong>Signature:</strong> - <dd><em>size_t </em><code>H5Tget_size</code>(<em>hid_t </em><code>type_id</code> + <dd><em>herr_t</em> <code>H5Tenum_nameof</code>(<em>hid_t</em> <code>type</code> + <em>void</em> *<code>value</code>, + <em>char</em> *<code>name</code>, + <em>size_t</em> <code>size</code> ) <dt><strong>Purpose:</strong> - <dd>Returns the size of a datatype. + <dd>Returns the symbol name corresponding to a specified member of an enumeration datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_size</code> returns the size of a datatype in bytes. + <dd><code>H5Tenum_nameof</code> finds the symbol name that + corresponds to the specified <code>value</code> + of the enumeration datatype <code>type</code>. + <p> + At most <code>size</code> characters of the symbol + name are copied into the <code>name</code> buffer. + If the entire symbol name and null terminator + do not fit in the <code>name</code> buffer, then as + many characters as possible are copied + (not null terminated) and the function fails. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to query. + <dt><em>hid_t</em> <code>type</code> + <dd>IN: Enumeration datatype identifier. + <dt><em>void</em> *<code>value</code>, + <dd>IN: Value of the enumeration datatype. + <dt><em>char</em> *<code>name</code>, + <dd>OUT: Buffer for output of the symbol name. + <dt><em>size_t</em> <code>size</code> + <dd>IN: Anticipated size of the symbol name, in bytes (characters). </dl> <dt><strong>Returns:</strong> - <dd>Returns the size of the datatype in bytes if successful; - otherwise 0. + <dd>Returns a non-negative value if successful. + Otherwise returns a negative value + and, if <code>size</code> allows it, + the first character of <code>name</code> is + set to <code>NULL</code>. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_size_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tenum_nameof_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1078,41 +920,39 @@ H5Tget_overflow () </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tset_size" --> +<!-- HEADER RIGHT "H5Tenum_valueof" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-SetSize">H5Tset_size</a> +<dt><strong>Name:</strong> <a name="Datatype-EnumValueOf">H5Tenum_valueof</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_size</code>(<em>hid_t </em><code>type_id</code>, - <em>size_t</em><code>size</code> + <dd><em>herr_t</em> <code>H5Tenum_valueof</code>(<em>hid_t</em> <code>type</code> + <em>char</em> *<code>name</code>, + <em>void</em> *<code>value</code> ) <dt><strong>Purpose:</strong> - <dd>Sets the total size for an atomic datatype. + <dd>Returns the value corresponding to a specified member of an enumeration datatype. <dt><strong>Description:</strong> - <dd><code>H5Tset_size</code> sets the total size in bytes, - <code>size</code>, for a datatype. If the datatype is atomic and size - is decreased so that the significant bits of the datatype extend beyond - the edge of the new size, then the `offset' property is decreased - toward zero. If the `offset' becomes zero and the significant - bits of the datatype still hang over the edge of the new size, then - the number of significant bits is decreased. - The size set for a string should include space for the null-terminator - character, otherwise it will not be stored on (or retrieved from) disk. - Adjusting the size of an string automatically sets the precision - to 8*size. A compound datatype may increase in size, but may not - shrink. All datatypes must have a positive size. + <dd><code>H5Tenum_valueof</code> finds the value that + corresponds to the specified <code>name</code> + of the enumeration datatype <code>type</code>. + <p> + The <code>value</code> argument should be at least + as large as the value of <code>H5Tget_size(type)</code> + in order to hold the result. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to change size. - <dt><em>size_t</em> <code>size</code> - <dd>Size in bytes to modify datatype. + <dt><em>hid_t</em> <code>type</code> + <dd>IN: Enumeration datatype identifier. + <dt><em>const char</em> *<code>name</code>, + <dd>IN: Symbol name of the enumeration datatype. + <dt><em>void</em> *<code>value</code>, + <dd>OUT: Buffer for output of the value of the enumeration datatype. </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/h5t_FORTRAN.html#h5tset_size_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tenum_valueof_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1121,30 +961,33 @@ H5Tget_overflow () </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_super" --> +<!-- HEADER RIGHT "H5Tequal" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetSuper">H5Tget_super</a> +<dt><strong>Name:</strong> <a name="Datatype-Equal">H5Tequal</a> <dt><strong>Signature:</strong> - <dd><em>hid_t</em> <code>H5Tget_super</code>(<em>hid_t</em> <code>type</code> + <dd><em>htri_t </em><code>H5Tequal</code>(<em>hid_t </em><code>type_id1</code>, + <em>hid_t</em><code>type_id2</code> ) <dt><strong>Purpose:</strong> - <dd>Returns the base datatype from which a datatype is derived. + <dd>Determines whether two datatype identifiers refer to the same datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_super</code> returns the base datatype from which the - datatype <code>type</code> is derived. - <P> - In the case of an enumeration type, the return value is an integer type. + <dd><code>H5Tequal</code> determines whether two datatype identifiers + refer to the same datatype. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>type</code> - <dd>Datatype identifier for the derived datatype. + <dt><em>hid_t</em> <code>type_id1</code> + <dd>Identifier of datatype to compare. + <dt><em>hid_t</em> <code>type_id2</code> + <dd>Identifier of datatype to compare. </dl> <dt><strong>Returns:</strong> - <dd>Returns the datatype identifier for the base datatype if successful; - otherwise returns a negative value. + <dd>When successful, returns a positive value, for <code>TRUE</code>, + if the datatype identifiers refer to the same datatype, + or <code>0</code> (zero), for <code>FALSE</code>. + Otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_super_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tequal_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1153,87 +996,40 @@ H5Tget_overflow () </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_native_type" --> +<!-- HEADER RIGHT "H5Tfind" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetNativeType">H5Tget_native_type</a> +<dt><strong>Name:</strong> <a name="Datatype-Find">H5Tfind</a> <dt><strong>Signature:</strong> - <dd><em>hid_t</em> <code>H5Tget_native_type</code>(<em>hid_t</em> <code>type_id</code>, - <em>H5T_direction_t</em> <code>direction</code> + <dd><em>H5T_conv_t</em> <code>H5Tfind</code>(<em>hid_t</em> <code>src_id</code>, + <em>hid_t</em> <code>dst_id</code>, + <em>H5T_cdata_t **</em><code>pcdata</code> ) <dt><strong>Purpose:</strong> - <dd>Returns the native datatype of a specified datatype. + <dd>Finds a conversion function. <dt><strong>Description:</strong> - <dd><code>H5Tget_native_type</code> returns the equivalent native datatype - for the datatype specified in <code>type_id</code>. - <p> - <code>H5Tget_native_type</code> is a high-level function designed - primarily to facilitate use of the <code>H5Dread</code> function, - for which users otherwise must undertake a multi-step process to - determine the native datatype of a dataset prior to reading it - into memory. - It can be used not only to determine - the native datatype for atomic datatypes, - but also to determine the native datatypes of the individual components of - a compound datatype, an enumerated datatype, an array datatype, or - a variable-length datatype. - <p> - <code>H5Tget_native_type</code> selects the matching native datatype - from the following list: - <pre> H5T_NATIVE_CHAR - H5T_NATIVE_SHORT - H5T_NATIVE_INT - H5T_NATIVE_LONG - H5T_NATIVE_LLONG - - H5T_NATIVE_UCHAR - H5T_NATIVE_USHORT - H5T_NATIVE_UINT - H5T_NATIVE_ULONG - H5T_NATIVE_ULLONG - - H5T_NATIVE_FLOAT - H5T_NATIVE_DOUBLE - H5T_NATIVE_LDOUBLE</pre> - <p> - The <code>direction</code> parameter indicates the order - in which the library searches for a native datatype match. - Valid values for <code>direction</code> are as follows: - <table border=0> - <tr valign=top><td> </td><td> - <code>H5T_DIR_ASCEND</code></td><td> - Searches the above list in ascending size of the datatype,<br> - i.e., from top to bottom. (Default) - </td></tr> - <tr valign=top><td> </td><td> - <code>H5T_DIR_DESCEND</code> </td><td> - Searches the above list in descending size of the datatype,<br> - i.e., from bottom to top. - </td></tr> - </table> - <p> - <code>H5Tget_native_type</code> is designed primarily for - use with intenger and floating point datatypes. - Time, bifield, opaque, and reference datatypes are returned - as a copy of <code>type_id</code>. - <p> - The identifier returned by <code>H5Tget_native_type</code> - should eventually be closed by calling <code>H5Tclose</code> - to release resources. + <dd><code>H5Tfind</code> finds a conversion function that can + handle a conversion from type <code>src_id</code> to type + <code>dst_id</code>. + The <code>pcdata</code> argument is a pointer to a pointer + to type conversion data which was created and initialized + by the soft type conversion function of this path when the + conversion function was installed on the path. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>Datatype identifier for the dataset datatype. - <dt><em>H5T_direction_t</em> <code>direction</code> - <dd>Direction of search. + <dt><em>hid_t</em> <code>src_id</code> + <dd>IN: Identifier for the source datatype. + <dt><em>hid_t</em> <code>dst_id</code> + <dd>IN: Identifier for the destination datatype. + <dt><em>H5T_cdata_t **</em><code>pcdata</code> + <dd>OUT: Pointer to type conversion data. </dl> <dt><strong>Returns:</strong> - <dd>Returns the native datatype identifier for the - specified dataset datatype if successful; - otherwise returns a negative value. + <dd>Returns a pointer to a suitable conversion function if successful. + Otherwise returns NULL. <!-- <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_native_type_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tfind_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> --> <!-- <img src="Graphics/Java.gif"> @@ -1242,38 +1038,39 @@ H5Tget_overflow () </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_order" --> +<!-- HEADER RIGHT "H5Tget_array_dims" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetOrder">H5Tget_order</a> +<dt><strong>Name:</strong> <a name="Datatype-GetArrayDims">H5Tget_array_dims</a> <dt><strong>Signature:</strong> - <dd><em>H5T_order_t </em><code>H5Tget_order</code>(<em>hid_t </em><code>type_id</code> + <dd><em>int</em> <code>H5Tget_array_dims</code>( + <em>hid_t</em> <code>adtype_id</code>, + <em>hsize_t *</em><code>dims[]</code>, + <em>int *</em><code>perm[]</code> ) <dt><strong>Purpose:</strong> - <dd>Returns the byte order of an atomic datatype. + <dd>Retrieves sizes of array dimensions and dimension permutations. <dt><strong>Description:</strong> - <dd><code>H5Tget_order</code> returns the byte order of an - atomic datatype. + <dd><code>H5Tget_array_dims</code> returns the sizes of the dimensions + and the dimension permutations of the specified array datatype object. <p> - Possible return values are: - <ul><dl> - <dt><code>H5T_ORDER_LE</code> (<code>0</code>) - <dd>Little endian byte ordering (default). - <dt><code>H5T_ORDER_BE</code> (<code>1</code>) - <dd>Big endian byte ordering. - <dt><code>H5T_ORDER_VAX</code> (<code>2</code>) - <dd>VAX mixed byte ordering (not currently supported). - </dl></ul> + The sizes of the dimensions are returned in the array <code>dims</code>. + The dimension permutations, i.e., C versus FORTRAN array order, + are returned in the array <code>perm</code>. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to query. + <dt><em>hid_t</em> <code>adtype_id</code> + <dd>IN: Datatype identifier of array object. + <dt><em>hsize_t *</em><code>dims[]</code> + <dd>OUT: Sizes of array dimensions. + <dt><em>int *</em><code>perm[]</code> + <dd>OUT: Dimension permutations. </dl> <dt><strong>Returns:</strong> - <dd>Returns a byte order constant if successful; - otherwise <code>H5T_ORDER_ERROR</code> (-1). + <dd>Returns the non-negative number of dimensions of the array type if successful; + otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_order_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_array_dims_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1282,39 +1079,29 @@ H5Tget_overflow () </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tset_order" --> +<!-- HEADER RIGHT "H5Tget_array_ndims" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-SetOrder">H5Tset_order</a> +<dt><strong>Name:</strong> <a name="Datatype-GetArrayNdims">H5Tget_array_ndims</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_order</code>(<em>hid_t </em><code>type_id</code>, - <em>H5T_order_t</em><code>order</code> + <dd><em>int</em> <code>H5Tget_array_ndims</code>( + <em>hid_t</em> <code>adtype_id</code> ) <dt><strong>Purpose:</strong> - <dd>Sets the byte ordering of an atomic datatype. + <dd>Returns the rank of an array datatype. <dt><strong>Description:</strong> - <dd><code>H5Tset_order</code> sets the byte ordering of an atomic datatype. - Byte orderings currently supported are: - <ul> <dl> - <dt>H5T_ORDER_LE (<code>0</code>) - <dd> Little-endian byte ordering (default). - <dt>H5T_ORDER_BE (<code>1</code>) - <dd> Big-endian byte ordering. - <dt>H5T_ORDER_VAX (<code>2</code>) - <dd>VAX mixed byte ordering (not currently supported). - </dl> </ul> + <dd><code>H5Tget_array_ndims</code> returns the rank, + the number of dimensions, of an array datatype object. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to set. - <dt><em>H5T_order_t</em> <code>order</code> - <dd>Byte ordering constant. + <dt><em>hid_t</em> <code>adtype_id</code> + <dd>IN: Datatype identifier of array object. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; + <dd>Returns the rank of the array if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tset_order_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_array_ndims_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1323,29 +1110,41 @@ H5Tget_overflow () </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_precision" --> +<!-- HEADER RIGHT "H5Tget_class" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetPrecision">H5Tget_precision</a> +<dt><strong>Name:</strong> <a name="Datatype-GetClass">H5Tget_class</a> <dt><strong>Signature:</strong> - <dd><em>size_t </em><code>H5Tget_precision</code>(<em>hid_t </em><code>type_id</code> + <dd><em>H5T_class_t </em><code>H5Tget_class</code>(<em>hid_t </em><code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Returns the precision of an atomic datatype. + <dd>Returns the datatype class identifier. <dt><strong>Description:</strong> - <dd><code>H5Tget_precision</code> returns the precision of an atomic datatype. The - precision is the number of significant bits which, unless padding is - present, is 8 times larger than the value returned by H5Tget_size(). + <dd><code>H5Tget_class</code> returns the datatype class identifier. + <p> + Valid class identifiers, as defined in <code>H5Tpublic.h</code>, are: + <ul><li><code>H5T_INTEGER</code> + <li><code>H5T_FLOAT</code> + <li><code>H5T_TIME</code> + <li><code>H5T_STRING</code> + <li><code>H5T_BITFIELD</code> + <li><code>H5T_OPAQUE</code> + <li><code>H5T_COMPOUND</code> + <li><code>H5T_REFERENCE</code> + <li><code>H5T_ENUM</code> + <li><code>H5T_VLEN</code> + <li><code>H5T_ARRAY</code> + </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Returns the number of significant bits if successful; - otherwise 0. + <dd>Returns datatype class identifier if successful; + otherwise <code>H5T_NO_CLASS</code> (-1). <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_precision_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_class_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1354,40 +1153,32 @@ H5Tget_overflow () </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tset_precision" --> +<!-- HEADER RIGHT "H5Tget_cset" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-SetPrecision">H5Tset_precision</a> +<dt><strong>Name:</strong> <a name="Datatype-GetCset">H5Tget_cset</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_precision</code>(<em>hid_t </em><code>type_id</code>, - <em>size_t</em><code>precision</code> + <dd><em>H5T_cset_t </em><code>H5Tget_cset</code>(<em>hid_t </em><code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Sets the precision of an atomic datatype. + <dd>Retrieves the character set type of a string datatype. <dt><strong>Description:</strong> - <dd><code>H5Tset_precision</code> sets the precision of an atomic datatype. - The precision is the number of significant bits which, unless padding - is present, is 8 times larger than the value returned by H5Tget_size(). - <P>If the precision is increased then the offset is decreased and then - the size is increased to insure that significant bits do not "hang - over" the edge of the datatype. - <P>Changing the precision of an H5T_STRING automatically changes the - size as well. The precision must be a multiple of 8. - <P>When decreasing the precision of a floating point type, set the - locations and sizes of the sign, mantissa, and exponent fields - first. + <dd><code>H5Tget_cset</code> retrieves the character set type + of a string datatype. Valid character set types are: + <ul> <dl> + <dt>H5T_CSET_ASCII (<code>0</code>) + <dd>Character set is US ASCII + </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to set. - <dt><em>size_t</em> <code>precision</code> - <dd>Number of bits of precision for datatype. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. + <dd>Returns a valid character set type if successful; + otherwise <code>H5T_CSET_ERROR</code> (-1). <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tset_precision_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_cset_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1396,73 +1187,27 @@ H5Tget_overflow () </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_offset" --> +<!-- HEADER RIGHT "H5Tget_ebias" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetOffset">H5Tget_offset</a> +<dt><strong>Name:</strong> <a name="Datatype-GetEbias">H5Tget_ebias</a> <dt><strong>Signature:</strong> - <dd><em>int </em><code>H5Tget_offset</code>(<em>hid_t </em><code>type_id</code> + <dd><em>size_t </em><code>H5Tget_ebias</code>(<em>hid_t </em><code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves the bit offset of the first significant bit. + <dd>Retrieves the exponent bias of a floating-point type. <dt><strong>Description:</strong> - <dd><code>H5Tget_offset</code> retrieves the bit offset of the first significant bit. - The significant bits of an atomic datum can be offset from the beginning - of the memory for that datum by an amount of padding. The `offset' - property specifies the number of bits of padding that appear to the - "right of" the value. That is, if we have a 32-bit datum with 16-bits - of precision having the value 0x1122 then it will be laid out in - memory as (from small byte address toward larger byte addresses): - <br> - <br> - - <table border align=center cellpadding=4 width="80%"> - <tr align=center> - <th width="20%">Byte Position</th> - <th width="20%">Big-Endian Offset=0</th> - <th width="20%">Big-Endian Offset=16</th> - <th width="20%">Little-Endian Offset=0</th> - <th width="20%">Little-Endian Offset=16</th> - </tr> - <tr align=center> - <td>0:</td> - <td>[ pad]</td> - <td>[0x11]</td> - <td>[0x22]</td> - <td>[ pad]</td> - </tr> - <tr align=center> - <td>1:</td> - <td>[ pad]</td> - <td>[0x22]</td> - <td>[0x11]</td> - <td>[ pad]</td> - </tr> - <tr align=center> - <td>2:</td> - <td>[0x11]</td> - <td>[ pad]</td> - <td>[ pad]</td> - <td>[0x22]</td> - </tr> - <tr align=center> - <td>3:</td> - <td>[0x22]</td> - <td>[ pad]</td> - <td>[ pad]</td> - <td>[0x11]</td> - </tr> - </table> + <dd><code>H5Tget_ebias</code> retrieves the exponent bias of a floating-point type. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Returns an offset value if successful; - otherwise returns a negative value. + <dd>Returns the bias if successful; + otherwise 0. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_offset_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_ebiass_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1471,83 +1216,46 @@ H5Tget_overflow () </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tset_offset" --> +<!-- HEADER RIGHT "H5Tget_fields" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-SetOffset">H5Tset_offset</a> +<dt><strong>Name:</strong> <a name="Datatype-GetFields">H5Tget_fields</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_offset</code>(<em>hid_t </em><code>type_id</code>, - <em>size_t</em> <code>offset</code> + <dd><em>herr_t </em><code>H5Tget_fields</code>(<em>hid_t </em><code>type_id</code>, + <em>size_t *</em><code>spos</code>, + <em>size_t *</em><code>epos</code>, + <em>size_t *</em><code>esize</code>, + <em>size_t *</em><code>mpos</code>, + <em>size_t *</em><code>msize</code> ) <dt><strong>Purpose:</strong> - <dd>Sets the bit offset of the first significant bit. + <dd>Retrieves floating point datatype bit field information. <dt><strong>Description:</strong> - <dd><code>H5Tset_offset</code> sets the bit offset of the first significant bit. The - significant bits of an atomic datum can be offset from the beginning of - the memory for that datum by an amount of padding. The `offset' - property specifies the number of bits of padding that appear to the - "right of" the value. That is, if we have a 32-bit datum with 16-bits - of precision having the value 0x1122 then it will be laid out in - memory as (from small byte address toward larger byte addresses): - <br> - <br> - - <table border align=center cellpadding=4 width="80%"> - <tr align=center> - <th width="20%">Byte Position</th> - <th width="20%">Big-Endian Offset=0</th> - <th width="20%">Big-Endian Offset=16</th> - <th width="20%">Little-Endian Offset=0</th> - <th width="20%">Little-Endian Offset=16</th> - </tr> - <tr align=center> - <td>0:</td> - <td>[ pad]</td> - <td>[0x11]</td> - <td>[0x22]</td> - <td>[ pad]</td> - </tr> - <tr align=center> - <td>1:</td> - <td>[ pad]</td> - <td>[0x22]</td> - <td>[0x11]</td> - <td>[ pad]</td> - </tr> - <tr align=center> - <td>2:</td> - <td>[0x11]</td> - <td>[ pad]</td> - <td>[ pad]</td> - <td>[0x22]</td> - </tr> - <tr align=center> - <td>3:</td> - <td>[0x22]</td> - <td>[ pad]</td> - <td>[ pad]</td> - <td>[0x11]</td> - </tr> - </table> - -<P>If the offset is incremented then the total size is -incremented also if necessary to prevent significant bits of -the value from hanging over the edge of the datatype. - -<P>The offset of an H5T_STRING cannot be set to anything but -zero. + <dd><code>H5Tget_fields</code> retrieves information about the locations of the various + bit fields of a floating point datatype. The field positions are bit + positions in the significant region of the datatype. Bits are + numbered with the least significant bit number zero. + Any (or even all) of the arguments can be null pointers. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to set. - <dt><em>size_t</em> <code>offset</code> - <dd>Offset of first significant bit. + <dd>IN: Identifier of datatype to query. + <dt><em>size_t *</em><code>spos</code> + <dd>OUT: Pointer to location to return floating-point sign bit. + <dt><em>size_t *</em><code>epos</code> + <dd>OUT: Pointer to location to return exponent bit-position. + <dt><em>size_t *</em><code>esize</code> + <dd>OUT: Pointer to location to return size of exponent in bits. + <dt><em>size_t *</em><code>mpos</code> + <dd>OUT: Pointer to location to return mantissa bit-position. + <dt><em>size_t *</em><code>msize</code> + <dd>OUT: Pointer to location to return size of mantissa in bits. </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/h5t_FORTRAN.html#h5tset_offset_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_fields_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1556,20 +1264,19 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_pad" --> +<!-- HEADER RIGHT "H5Tget_inpad" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetPad">H5Tget_pad</a> +<dt><strong>Name:</strong> <a name="Datatype-GetInpad">H5Tget_inpad</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tget_pad</code>(<em>hid_t </em><code>type_id</code>, - <em>H5T_pad_t *</em> <code>lsb</code>, - <em>H5T_pad_t *</em> <code>msb</code> + <dd><em>H5T_pad_t </em><code>H5Tget_inpad</code>(<em>hid_t </em><code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves the padding type of the least and most-significant bit padding. + <dd>Retrieves the internal padding type for unused bits in floating-point datatypes. <dt><strong>Description:</strong> - <dd><code>H5Tget_pad</code> retrieves the padding type of the least and most-significant - bit padding. Valid types are: + <dd><code>H5Tget_inpad</code> retrieves the internal padding type for + unused bits in floating-point datatypes. + Valid padding types are: <ul> <dl> <dt>H5T_PAD_ZERO (<code>0</code>) <dd>Set background to zeros. @@ -1581,20 +1288,51 @@ zero. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>IN: Identifier of datatype to query. - <dt><em>H5T_pad_t *</em> <code>lsb</code> - <dd>OUT: Pointer to location to return least-significant - bit padding type. - <dt><em>H5T_pad_t *</em> <code>msb</code> - <dd>OUT: Pointer to location to return most-significant - bit padding type. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; + <dd>Returns a valid padding type if successful; + otherwise <code>H5T_PAD_ERROR</code> (-1). +<dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_inpad_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 "H5Tget_member_class" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetMemberClass">H5Tget_member_class</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_class_t</em> <code>H5Tget_member_class</code>( + <em>hid_t</em> <code>cdtype_id</code>, + <em>int </em><code>member_no</code> + ) +<dt><strong>Purpose:</strong> + <dd>Returns datatype class of compound datatype member. +<dt><strong>Description:</strong> + <dd>Given a compound datatype, <code>cdtype_id</code>, the function + <code>H5Tget_member_class</code> returns the datatype class of + the compound datatype member specified by <code>member_no</code>. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>cdtype_id</code> + <dd>IN: Datatype identifier of compound object. + <dt><em>int</em> <code>member_no</code> + <dd>IN: Compound object member number. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns the datatype class, a non-negative value, if successful; otherwise returns a negative value. +<!-- <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_pad_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5txxx_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> +--> <!-- <img src="Graphics/Java.gif"> <img src="Graphics/C++.gif"> @@ -1602,42 +1340,41 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tset_pad" --> +<!-- HEADER RIGHT "H5Tget_member_index" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-SetPad">H5Tset_pad</a> +<dt><strong>Name:</strong> <a name="Datatype-GetMemberIndex">H5Tget_member_index</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_pad</code>(<em>hid_t </em><code>type_id</code>, - <em>H5T_pad_t</em> <code>lsb</code>, - <em>H5T_pad_t</em> <code>msb</code> + <dd><em>int</em> <code>H5Tget_member_index</code>(<em>hid_t </em><code>type_id</code>, + <em>const char *</em> <code>field_name</code> ) <dt><strong>Purpose:</strong> - <dd>Sets the least and most-significant bits padding types. + <dd>Retrieves the index of a compound or enumeration datatype member. <dt><strong>Description:</strong> - <dd><code>H5Tset_pad</code> sets the least and most-significant bits padding types. - <ul> <dl> - <dt>H5T_PAD_ZERO (<code>0</code>) - <dd>Set background to zeros. - <dt>H5T_PAD_ONE (<code>1</code>) - <dd>Set background to ones. - <dt>H5T_PAD_BACKGROUND (<code>2</code>) - <dd>Leave background alone. - </dl> </ul> + <dd><code>H5Tget_member_index</code> retrieves the index of a field + of a compound datatype or an element of an enumeration datatype. + <p> + The name of the target field or element is specified in + <code>field_name</code>. + <p> + Fields are stored in no particular order + with index values of 0 through <em>N</em>-1, where <em>N</em> is + the value returned by <code>H5Tget_nmembers</code>. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to set. - <dt><em>H5T_pad_t</em> <code>lsb</code> - <dd>Padding type for least-significant bits. - <dt><em>H5T_pad_t</em> <code>msb</code> - <dd>Padding type for most-significant bits. + <dd>Identifier of datatype to query. + <dt><em>const char *</em> <code>field_name</code> + <dd>Name of the field or member whose index is to be retrieved. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; + <dd>Returns a valid field or member index if successful; otherwise returns a negative value. +<!-- <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tset_pad_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_index_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> +--> <!-- <img src="Graphics/Java.gif"> <img src="Graphics/C++.gif"> @@ -1645,34 +1382,44 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_sign" --> +<!-- HEADER RIGHT "H5Tget_member_name" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetSign">H5Tget_sign</a> +<dt><strong>Name:</strong> <a name="Datatype-GetMemberName">H5Tget_member_name</a> <dt><strong>Signature:</strong> - <dd><em>H5T_sign_t </em><code>H5Tget_sign</code>(<em>hid_t </em><code>type_id</code> + <dd><em>char *</em> <code>H5Tget_member_name</code>(<em>hid_t </em><code>type_id</code>, + <em>int</em> <code>field_idx</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves the sign type for an integer type. + <dd>Retrieves the name of a compound or enumeration datatype member. <dt><strong>Description:</strong> - <dd><code>H5Tget_sign</code> retrieves the sign type for an integer type. - Valid types are: - <ul> <dl> - <dt>H5T_SGN_NONE (<code>0</code>) - <dd>Unsigned integer type. - <dt>H5T_SGN_2 (<code>1</code>) - <dd>Two's complement signed integer type. - </dl> </ul> + <dd><code>H5Tget_member_name</code> retrieves the name of a field + of a compound datatype or an element of an enumeration datatype. + <p> + The index of the target field or element is specified in + <code>field_idx</code>. + Compound datatype fields and enumeration datatype elements + are stored in no particular order + with index values of 0 through <em>N</em>-1, where <em>N</em> + is the value returned by <code>H5Tget_nmembers</code>. + <p> + A buffer to receive the name of the field is + allocated with <code>malloc()</code> and the caller is responsible + for freeing the memory used. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> <dd>Identifier of datatype to query. + <dt><em>int</em> <code>field_idx</code> + <dd>Zero-based index of the field or element whose name + is to be retrieved. </dl> <dt><strong>Returns:</strong> - <dd>Returns a valid sign type if successful; - otherwise <code>H5T_SGN_ERROR</code> (-1). + <dd>Returns a valid pointer to a string allocated with + <code>malloc()</code> if successful; + otherwise returns NULL. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_sign_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_name_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1681,36 +1428,36 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tset_sign" --> +<!-- HEADER RIGHT "H5Tget_member_offset" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-SetSign">H5Tset_sign</a> +<dt><strong>Name:</strong> <a name="Datatype-GetMemberOffset">H5Tget_member_offset</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_sign</code>(<em>hid_t </em><code>type_id</code>, - <em>H5T_sign_t</em> <code>sign</code> + <dd><em>size_t</em> <code>H5Tget_member_offset</code>(<em>hid_t </em><code>type_id</code>, + <em>int</em> <code>memb_no</code> ) <dt><strong>Purpose:</strong> - <dd>Sets the sign property for an integer type. + <dd>Retrieves the offset of a field of a compound datatype. <dt><strong>Description:</strong> - <dd><code>H5Tset_sign</code> sets the sign property for an integer type. - <ul> <dl> - <dt>H5T_SGN_NONE (<code>0</code>) - <dd>Unsigned integer type. - <dt>H5T_SGN_2 (<code>1</code>) - <dd>Two's complement signed integer type. - </dl> </ul> + <dd><code>H5Tget_member_offset</code> retrieves the + byte offset of the beginning of a field within a + compound datatype with respect to the beginning + of the compound data type datum. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to set. - <dt><em>H5T_sign_t</em> <code>sign</code> - <dd>Sign type. + <dd>Identifier of datatype to query. + <dt><em>int</em> <code>memb_no</code> + <dd>Number of the field whose offset is requested. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. + <dd>Returns the byte offset of the field if successful; + otherwise returns <code>0</code> (zero). + Note that zero is a valid offset and that this function + will fail only if a call to <code>H5Tget_member_class()</code> + fails with the same arguments. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tset_sign_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_offset_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1719,46 +1466,32 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_fields" --> +<!-- HEADER RIGHT "H5Tget_member_type" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetFields">H5Tget_fields</a> +<dt><strong>Name:</strong> <a name="Datatype-GetMemberType">H5Tget_member_type</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tget_fields</code>(<em>hid_t </em><code>type_id</code>, - <em>size_t *</em><code>spos</code>, - <em>size_t *</em><code>epos</code>, - <em>size_t *</em><code>esize</code>, - <em>size_t *</em><code>mpos</code>, - <em>size_t *</em><code>msize</code> + <dd><em>hid_t</em> <code>H5Tget_member_type</code>(<em>hid_t </em><code>type_id</code>, + <em>int</em> <code>field_idx</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves floating point datatype bit field information. + <dd>Returns the datatype of the specified member. <dt><strong>Description:</strong> - <dd><code>H5Tget_fields</code> retrieves information about the locations of the various - bit fields of a floating point datatype. The field positions are bit - positions in the significant region of the datatype. Bits are - numbered with the least significant bit number zero. - Any (or even all) of the arguments can be null pointers. + <dd><code>H5Tget_member_type</code> returns the datatype of the specified member. The caller + should invoke H5Tclose() to release resources associated with the type. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>IN: Identifier of datatype to query. - <dt><em>size_t *</em><code>spos</code> - <dd>OUT: Pointer to location to return floating-point sign bit. - <dt><em>size_t *</em><code>epos</code> - <dd>OUT: Pointer to location to return exponent bit-position. - <dt><em>size_t *</em><code>esize</code> - <dd>OUT: Pointer to location to return size of exponent in bits. - <dt><em>size_t *</em><code>mpos</code> - <dd>OUT: Pointer to location to return mantissa bit-position. - <dt><em>size_t *</em><code>msize</code> - <dd>OUT: Pointer to location to return size of mantissa in bits. + <dd>Identifier of datatype to query. + <dt><em>int</em> <code>field_idx</code> + <dd>Field index (0-based) of the field type to retrieve. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; + <dd>Returns the identifier of a copy of the datatype of the field + if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_fields_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_type_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1767,49 +1500,38 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tset_fields" --> +<!-- HEADER RIGHT "H5Tget_member_value" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-SetFields">H5Tset_fields</a> +<dt><strong>Name:</strong> <a name="Datatype-GetMemberValue">H5Tget_member_value</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_fields</code>(<em>hid_t </em><code>type_id</code>, - <em>size_t</em> <code>spos</code>, - <em>size_t</em> <code>epos</code>, - <em>size_t</em> <code>esize</code>, - <em>size_t</em> <code>mpos</code>, - <em>size_t</em> <code>msize</code> + <dd><em>hid_t</em> <code>H5Tget_member_value</code>(<em>hid_t</em> <code>type</code> + <em>int</em> <code>memb_no</code>, + <em>void</em> *<code>value</code> ) <dt><strong>Purpose:</strong> - <dd>Sets locations and sizes of floating point bit fields. + <dd>Returns the value of an enumeration datatype member. <dt><strong>Description:</strong> - <dd><code>H5Tset_fields</code> sets the locations and sizes of the various - floating-point bit fields. The field positions are bit positions in the - significant region of the datatype. Bits are numbered with the least - significant bit number zero. - - <P>Fields are not allowed to extend beyond the number of bits of - precision, nor are they allowed to overlap with one another. + <dd><code>H5Tget_member_value</code> returns the value of + the enumeration datatype member <code>memb_no</code>. + <p> + The member value is returned in a user-supplied buffer + pointed to by <code>value</code>. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to set. - <dt><em>size_t</em> <code>spos</code> - <dd>Sign position, i.e., the bit offset of the floating-point - sign bit. - <dt><em>size_t</em> <code>epos</code> - <dd>Exponent bit position. - <dt><em>size_t</em> <code>esize</code> - <dd>Size of exponent in bits. - <dt><em>size_t</em> <code>mpos</code> - <dd>Mantissa bit position. - <dt><em>size_t</em> <code>msize</code> - <dd>Size of mantissa in bits. + <dt><em>hid_t</em> <code>type</code> + <dd>IN: Datatype identifier for the enumeration datatype. + <dt><em>int</em> <code>memb_no</code>, + <dd>IN: Number of the enumeration datatype member. + <dt><em>void</em> *<code>value</code> + <dd>OUT: Pointer to a buffer for output of the + value of the enumeration datatype 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/h5t_FORTRAN.html#h5tset_fields_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_value_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1818,59 +1540,118 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_ebias" --> +<!-- HEADER RIGHT "H5Tget_native_type" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetEbias">H5Tget_ebias</a> +<dt><strong>Name:</strong> <a name="Datatype-GetNativeType">H5Tget_native_type</a> <dt><strong>Signature:</strong> - <dd><em>size_t </em><code>H5Tget_ebias</code>(<em>hid_t </em><code>type_id</code> + <dd><em>hid_t</em> <code>H5Tget_native_type</code>(<em>hid_t</em> <code>type_id</code>, + <em>H5T_direction_t</em> <code>direction</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves the exponent bias of a floating-point type. + <dd>Returns the native datatype of a specified datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_ebias</code> retrieves the exponent bias of a floating-point type. + <dd><code>H5Tget_native_type</code> returns the equivalent native datatype + for the datatype specified in <code>type_id</code>. + <p> + <code>H5Tget_native_type</code> is a high-level function designed + primarily to facilitate use of the <code>H5Dread</code> function, + for which users otherwise must undertake a multi-step process to + determine the native datatype of a dataset prior to reading it + into memory. + It can be used not only to determine + the native datatype for atomic datatypes, + but also to determine the native datatypes of the individual components of + a compound datatype, an enumerated datatype, an array datatype, or + a variable-length datatype. + <p> + <code>H5Tget_native_type</code> selects the matching native datatype + from the following list: + <pre> H5T_NATIVE_CHAR + H5T_NATIVE_SHORT + H5T_NATIVE_INT + H5T_NATIVE_LONG + H5T_NATIVE_LLONG + + H5T_NATIVE_UCHAR + H5T_NATIVE_USHORT + H5T_NATIVE_UINT + H5T_NATIVE_ULONG + H5T_NATIVE_ULLONG + + H5T_NATIVE_FLOAT + H5T_NATIVE_DOUBLE + H5T_NATIVE_LDOUBLE</pre> + <p> + The <code>direction</code> parameter indicates the order + in which the library searches for a native datatype match. + Valid values for <code>direction</code> are as follows: + <table border=0> + <tr valign=top><td> </td><td> + <code>H5T_DIR_ASCEND</code></td><td> + Searches the above list in ascending size of the datatype,<br> + i.e., from top to bottom. (Default) + </td></tr> + <tr valign=top><td> </td><td> + <code>H5T_DIR_DESCEND</code> </td><td> + Searches the above list in descending size of the datatype,<br> + i.e., from bottom to top. + </td></tr> + </table> + <p> + <code>H5Tget_native_type</code> is designed primarily for + use with intenger and floating point datatypes. + Time, bifield, opaque, and reference datatypes are returned + as a copy of <code>type_id</code>. + <p> + The identifier returned by <code>H5Tget_native_type</code> + should eventually be closed by calling <code>H5Tclose</code> + to release resources. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to query. + <dd>Datatype identifier for the dataset datatype. + <dt><em>H5T_direction_t</em> <code>direction</code> + <dd>Direction of search. </dl> <dt><strong>Returns:</strong> - <dd>Returns the bias if successful; - otherwise 0. + <dd>Returns the native datatype identifier for the + specified dataset datatype if successful; + otherwise returns a negative value. +<!-- <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_ebiass_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_native_type_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 "H5Tset_ebias" --> +<!-- HEADER RIGHT "H5Tget_nmembers" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-SetEbias">H5Tset_ebias</a> +<dt><strong>Name:</strong> <a name="Datatype-GetNmembers">H5Tget_nmembers</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_ebias</code>(<em>hid_t </em><code>type_id</code>, - <em>size_t</em> <code>ebias</code> + <dd><em>int </em><code>H5Tget_nmembers</code>(<em>hid_t </em><code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Sets the exponent bias of a floating-point type. + <dd>Retrieves the number of elements in a compound or enumeration datatype. <dt><strong>Description:</strong> - <dd><code>H5Tset_ebias</code> sets the exponent bias of a floating-point type. + <dd><code>H5Tget_nmembers</code> retrieves + the number of fields in a compound datatype or + the number of members of an enumeration datatype. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to set. - <dt><em>size_t</em> <code>ebias</code> - <dd>Exponent bias value. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; + <dd>Returns the number of elements if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tset_ebiass_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_nmembers_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1917,39 +1698,73 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tset_norm" --> +<!-- HEADER RIGHT "H5Tget_offset" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-SetNorm">H5Tset_norm</a> +<dt><strong>Name:</strong> <a name="Datatype-GetOffset">H5Tget_offset</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_norm</code>(<em>hid_t </em><code>type_id</code>, - <em>H5T_norm_t</em> <code>norm</code> + <dd><em>int </em><code>H5Tget_offset</code>(<em>hid_t </em><code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Sets the mantissa normalization of a floating-point datatype. + <dd>Retrieves the bit offset of the first significant bit. <dt><strong>Description:</strong> - <dd><code>H5Tset_norm</code> sets the mantissa normalization of - a floating-point datatype. Valid normalization types are: - <ul> <dl> - <dt>H5T_NORM_IMPLIED (<code>0</code>) - <dd>MSB of mantissa is not stored, always 1 - <dt>H5T_NORM_MSBSET (<code>1</code>) - <dd>MSB of mantissa is always 1 - <dt>H5T_NORM_NONE (<code>2</code>) - <dd>Mantissa is not normalized - </dl> </ul> + <dd><code>H5Tget_offset</code> retrieves the bit offset of the first significant bit. + The significant bits of an atomic datum can be offset from the beginning + of the memory for that datum by an amount of padding. The `offset' + property specifies the number of bits of padding that appear to the + "right of" the value. That is, if we have a 32-bit datum with 16-bits + of precision having the value 0x1122 then it will be laid out in + memory as (from small byte address toward larger byte addresses): + <br> + <br> + + <table border align=center cellpadding=4 width="80%"> + <tr align=center> + <th width="20%">Byte Position</th> + <th width="20%">Big-Endian Offset=0</th> + <th width="20%">Big-Endian Offset=16</th> + <th width="20%">Little-Endian Offset=0</th> + <th width="20%">Little-Endian Offset=16</th> + </tr> + <tr align=center> + <td>0:</td> + <td>[ pad]</td> + <td>[0x11]</td> + <td>[0x22]</td> + <td>[ pad]</td> + </tr> + <tr align=center> + <td>1:</td> + <td>[ pad]</td> + <td>[0x22]</td> + <td>[0x11]</td> + <td>[ pad]</td> + </tr> + <tr align=center> + <td>2:</td> + <td>[0x11]</td> + <td>[ pad]</td> + <td>[ pad]</td> + <td>[0x22]</td> + </tr> + <tr align=center> + <td>3:</td> + <td>[0x22]</td> + <td>[ pad]</td> + <td>[ pad]</td> + <td>[0x11]</td> + </tr> + </table> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to set. - <dt><em>H5T_norm_t</em> <code>norm</code> - <dd>Mantissa normalization type. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; + <dd>Returns an offset value if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tset_norm_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_offset_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1958,37 +1773,38 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_inpad" --> +<!-- HEADER RIGHT "H5Tget_order" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetInpad">H5Tget_inpad</a> +<dt><strong>Name:</strong> <a name="Datatype-GetOrder">H5Tget_order</a> <dt><strong>Signature:</strong> - <dd><em>H5T_pad_t </em><code>H5Tget_inpad</code>(<em>hid_t </em><code>type_id</code> + <dd><em>H5T_order_t </em><code>H5Tget_order</code>(<em>hid_t </em><code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves the internal padding type for unused bits in floating-point datatypes. + <dd>Returns the byte order of an atomic datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_inpad</code> retrieves the internal padding type for - unused bits in floating-point datatypes. - Valid padding types are: - <ul> <dl> - <dt>H5T_PAD_ZERO (<code>0</code>) - <dd>Set background to zeros. - <dt>H5T_PAD_ONE (<code>1</code>) - <dd>Set background to ones. - <dt>H5T_PAD_BACKGROUND (<code>2</code>) - <dd>Leave background alone. - </dl> </ul> + <dd><code>H5Tget_order</code> returns the byte order of an + atomic datatype. + <p> + Possible return values are: + <ul><dl> + <dt><code>H5T_ORDER_LE</code> (<code>0</code>) + <dd>Little endian byte ordering (default). + <dt><code>H5T_ORDER_BE</code> (<code>1</code>) + <dd>Big endian byte ordering. + <dt><code>H5T_ORDER_VAX</code> (<code>2</code>) + <dd>VAX mixed byte ordering (not currently supported). + </dl></ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Returns a valid padding type if successful; - otherwise <code>H5T_PAD_ERROR</code> (-1). + <dd>Returns a byte order constant if successful; + otherwise <code>H5T_ORDER_ERROR</code> (-1). <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_inpad_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_order_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -1997,76 +1813,79 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tset_inpad" --> +<!-- HEADER RIGHT "H5Tget_overflow" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-SetInpad">H5Tset_inpad</a> +<dt><strong>Name:</strong> <a name="Datatype-GetOverflow">H5Tget_overflow</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_inpad</code>(<em>hid_t </em><code>type_id</code>, - <em>H5T_pad_t</em> <code>inpad</code> - ) + + +H5Tget_overflow () + <dd><em>H5T_overflow_t</em> <code>H5Tget_overflow</code>(<code>void</code>) <dt><strong>Purpose:</strong> - <dd>Fills unused internal floating point bits. + <dd>Returns a pointer to the current global overflow function. <dt><strong>Description:</strong> - <dd>If any internal bits of a floating point type are unused - (that is, those significant bits which are not part of the - sign, exponent, or mantissa), then <code>H5Tset_inpad</code> will be filled - according to the value of the padding value property <code>inpad</code>. - Valid padding types are: - <ul> <dl> - <dt>H5T_PAD_ZERO (<code>0</code>) - <dd>Set background to zeros. - <dt>H5T_PAD_ONE (<code>1</code>) - <dd>Set background to ones. - <dt>H5T_PAD_BACKGROUND (<code>2</code>) - <dd>Leave background alone. - </dl> </ul> + <dd><code>H5Tset_overflow</code> returns a pointer + to the current global overflow function. + This is an application-defined function that is called whenever a + datatype conversion causes an overflow. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to modify. - <dt><em>H5T_pad_t</em> <code>pad</code> - <dd>Padding type. + <dt>None. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. + <dd>Returns a pointer to an application-defined function if successful. + Otherwise returns NULL; this can happen if no overflow handling + function is registered. +<!-- <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tset_inpad_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_overflow_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 "H5Tget_cset" --> +<!-- HEADER RIGHT "H5Tget_pad" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetCset">H5Tget_cset</a> +<dt><strong>Name:</strong> <a name="Datatype-GetPad">H5Tget_pad</a> <dt><strong>Signature:</strong> - <dd><em>H5T_cset_t </em><code>H5Tget_cset</code>(<em>hid_t </em><code>type_id</code> + <dd><em>herr_t </em><code>H5Tget_pad</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_pad_t *</em> <code>lsb</code>, + <em>H5T_pad_t *</em> <code>msb</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves the character set type of a string datatype. + <dd>Retrieves the padding type of the least and most-significant bit padding. <dt><strong>Description:</strong> - <dd><code>H5Tget_cset</code> retrieves the character set type - of a string datatype. Valid character set types are: + <dd><code>H5Tget_pad</code> retrieves the padding type of the least and most-significant + bit padding. Valid types are: <ul> <dl> - <dt>H5T_CSET_ASCII (<code>0</code>) - <dd>Character set is US ASCII + <dt>H5T_PAD_ZERO (<code>0</code>) + <dd>Set background to zeros. + <dt>H5T_PAD_ONE (<code>1</code>) + <dd>Set background to ones. + <dt>H5T_PAD_BACKGROUND (<code>2</code>) + <dd>Leave background alone. </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to query. + <dd>IN: Identifier of datatype to query. + <dt><em>H5T_pad_t *</em> <code>lsb</code> + <dd>OUT: Pointer to location to return least-significant + bit padding type. + <dt><em>H5T_pad_t *</em> <code>msb</code> + <dd>OUT: Pointer to location to return most-significant + bit padding type. </dl> <dt><strong>Returns:</strong> - <dd>Returns a valid character set type if successful; - otherwise <code>H5T_CSET_ERROR</code> (-1). + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_cset_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_pad_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -2075,38 +1894,29 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tset_cset" --> +<!-- HEADER RIGHT "H5Tget_precision" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-SetCset">H5Tset_cset</a> +<dt><strong>Name:</strong> <a name="Datatype-GetPrecision">H5Tget_precision</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_cset</code>(<em>hid_t </em><code>type_id</code>, - <em>H5T_cset_t</em> <code>cset</code> + <dd><em>size_t </em><code>H5Tget_precision</code>(<em>hid_t </em><code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Sets character set to be used. + <dd>Returns the precision of an atomic datatype. <dt><strong>Description:</strong> - <dd><code>H5Tset_cset</code> the character set to be used. - <p> - HDF5 is able to distinguish between character sets of different - nationalities and to convert between them to the extent possible. - Valid character set types are: - <ul> <dl> - <dt>H5T_CSET_ASCII (<code>0</code>) - <dd>Character set is US ASCII. - </dl> </ul> + <dd><code>H5Tget_precision</code> returns the precision of an atomic datatype. The + precision is the number of significant bits which, unless padding is + present, is 8 times larger than the value returned by H5Tget_size(). <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to modify. - <dt><em>H5T_cset_t</em> <code>cset</code> - <dd>Character set type. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. + <dd>Returns the number of significant bits if successful; + otherwise 0. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tset_cset_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_precision_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -2115,29 +1925,34 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_strpad" --> +<!-- HEADER RIGHT "H5Tget_sign" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetStrpad">H5Tget_strpad</a> +<dt><strong>Name:</strong> <a name="Datatype-GetSign">H5Tget_sign</a> <dt><strong>Signature:</strong> - <dd><em>H5T_str_t </em><code>H5Tget_strpad</code>(<em>hid_t </em><code>type_id</code> + <dd><em>H5T_sign_t </em><code>H5Tget_sign</code>(<em>hid_t </em><code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves the storage mechanism for a string datatype. + <dd>Retrieves the sign type for an integer type. <dt><strong>Description:</strong> - <dd><code>H5Tget_strpad</code> retrieves the storage mechanism - for a string datatype, as defined in - <a href="#Datatype-SetStrpad"><code>H5Tset_strpad</code></a>. + <dd><code>H5Tget_sign</code> retrieves the sign type for an integer type. + Valid types are: + <ul> <dl> + <dt>H5T_SGN_NONE (<code>0</code>) + <dd>Unsigned integer type. + <dt>H5T_SGN_2 (<code>1</code>) + <dd>Two's complement signed integer type. + </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Returns a valid string storage mechanism if successful; - otherwise <code>H5T_STR_ERROR</code> (-1). + <dd>Returns a valid sign type if successful; + otherwise <code>H5T_SGN_ERROR</code> (-1). <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_strpad_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_sign_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -2146,59 +1961,27 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tset_strpad" --> +<!-- HEADER RIGHT "H5Tget_size" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-SetStrpad">H5Tset_strpad</a> +<dt><strong>Name:</strong> <a name="Datatype-GetSize">H5Tget_size</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tset_strpad</code>(<em>hid_t </em><code>type_id</code>, - <em>H5T_str_t</em> <code>strpad</code> + <dd><em>size_t </em><code>H5Tget_size</code>(<em>hid_t </em><code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Defines the storage mechanism for character strings. + <dd>Returns the size of a datatype. <dt><strong>Description:</strong> - <dd><code>H5Tset_strpad</code> defines the storage mechanism for the string. - <p> - The method used to store character strings differs with the - programming language: - <ul> - <li>C usually null terminates strings while - <li>Fortran left-justifies and space-pads strings. - </ul> - Valid string padding values, as passed in the parameter - <code>strpad</code>, are as follows: - <ul> <dl> - <dt>H5T_STR_NULLTERM (<code>0</code>) - <dd>Null terminate (as C does) - <dt>H5T_STR_NULLPAD (<code>1</code>) - <dd>Pad with zeros - <dt>H5T_STR_SPACEPAD (<code>2</code>) - <dd>Pad with spaces (as FORTRAN does) - </dl> </ul> - <p> - When converting from a longer string to a shorter string, - the behavior is as follows. - If the short string is <code>H5T_STR_NULLPAD</code> or - <code>H5T_STR_SPACEPAD</code>, then the string is simply truncated. - If the short string is <code>H5T_STR_NULLTERM</code>, it is - truncated and a null terminator is appended. - <p> - When converting from a shorter string to a longer string, - the long string is padded on the end by appending nulls or spaces. - - + <dd><code>H5Tget_size</code> returns the size of a datatype in bytes. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to modify. - <dt><em>H5T_str_t</em> <code>strpad</code> - <dd>String padding type. + <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. + <dd>Returns the size of the datatype in bytes if successful; + otherwise 0. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tset_strpad_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_size_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -2207,29 +1990,29 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_nmembers" --> +<!-- HEADER RIGHT "H5Tget_strpad" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetNmembers">H5Tget_nmembers</a> +<dt><strong>Name:</strong> <a name="Datatype-GetStrpad">H5Tget_strpad</a> <dt><strong>Signature:</strong> - <dd><em>int </em><code>H5Tget_nmembers</code>(<em>hid_t </em><code>type_id</code> + <dd><em>H5T_str_t </em><code>H5Tget_strpad</code>(<em>hid_t </em><code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves the number of elements in a compound or enumeration datatype. + <dd>Retrieves the storage mechanism for a string datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_nmembers</code> retrieves - the number of fields in a compound datatype or - the number of members of an enumeration datatype. + <dd><code>H5Tget_strpad</code> retrieves the storage mechanism + for a string datatype, as defined in + <a href="#Datatype-SetStrpad"><code>H5Tset_strpad</code></a>. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> <dd>Identifier of datatype to query. </dl> <dt><strong>Returns:</strong> - <dd>Returns the number of elements if successful; - otherwise returns a negative value. + <dd>Returns a valid string storage mechanism if successful; + otherwise <code>H5T_STR_ERROR</code> (-1). <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_nmembers_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_strpad_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -2238,36 +2021,31 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_member_class" --> +<!-- HEADER RIGHT "H5Tget_super" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetMemberClass">H5Tget_member_class</a> +<dt><strong>Name:</strong> <a name="Datatype-GetSuper">H5Tget_super</a> <dt><strong>Signature:</strong> - <dd><em>H5T_class_t</em> <code>H5Tget_member_class</code>( - <em>hid_t</em> <code>cdtype_id</code>, - <em>int </em><code>member_no</code> + <dd><em>hid_t</em> <code>H5Tget_super</code>(<em>hid_t</em> <code>type</code> ) <dt><strong>Purpose:</strong> - <dd>Returns datatype class of compound datatype member. + <dd>Returns the base datatype from which a datatype is derived. <dt><strong>Description:</strong> - <dd>Given a compound datatype, <code>cdtype_id</code>, the function - <code>H5Tget_member_class</code> returns the datatype class of - the compound datatype member specified by <code>member_no</code>. + <dd><code>H5Tget_super</code> returns the base datatype from which the + datatype <code>type</code> is derived. + <P> + In the case of an enumeration type, the return value is an integer type. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>cdtype_id</code> - <dd>IN: Datatype identifier of compound object. - <dt><em>int</em> <code>member_no</code> - <dd>IN: Compound object member number. + <dt><em>hid_t</em> <code>type</code> + <dd>Datatype identifier for the derived datatype. </dl> <dt><strong>Returns:</strong> - <dd>Returns the datatype class, a non-negative value, if successful; + <dd>Returns the datatype identifier for the base datatype if successful; otherwise returns a negative value. -<!-- <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5txxx_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_super_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> ---> <!-- <img src="Graphics/Java.gif"> <img src="Graphics/C++.gif"> @@ -2275,44 +2053,31 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_member_name" --> +<!-- HEADER RIGHT "H5Tget_tag" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetMemberName">H5Tget_member_name</a> +<dt><strong>Name:</strong> <a name="Datatype-GetTag">H5Tget_tag</a> <dt><strong>Signature:</strong> - <dd><em>char *</em> <code>H5Tget_member_name</code>(<em>hid_t </em><code>type_id</code>, - <em>int</em> <code>field_idx</code> + <dd><em>char</em> *<code>H5Tget_tag</code>(<em>hid_t</em> <code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves the name of a compound or enumeration datatype member. + <dd>Gets the tag associated with an opaque datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_member_name</code> retrieves the name of a field - of a compound datatype or an element of an enumeration datatype. - <p> - The index of the target field or element is specified in - <code>field_idx</code>. - Compound datatype fields and enumeration datatype elements - are stored in no particular order - with index values of 0 through <em>N</em>-1, where <em>N</em> - is the value returned by <code>H5Tget_nmembers</code>. - <p> - A buffer to receive the name of the field is - allocated with <code>malloc()</code> and the caller is responsible - for freeing the memory used. + <dd><code>H5Tget_tag</code> returns the tag associated with + the opaque datatype <code>type_id</code>. + <P> + The tag is returned via a pointer to an + allocated string, which the caller must free. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to query. - <dt><em>int</em> <code>field_idx</code> - <dd>Zero-based index of the field or element whose name - is to be retrieved. + <dd>Datatype identifier for the opaque datatype. </dl> <dt><strong>Returns:</strong> - <dd>Returns a valid pointer to a string allocated with - <code>malloc()</code> if successful; - otherwise returns NULL. + <dd>Returns a pointer to an allocated string if successful; + otherwise returns <code>NULL</code>. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_name_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tget_tag_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -2321,41 +2086,45 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_member_index" --> +<!-- HEADER RIGHT "H5Tinsert" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetMemberIndex">H5Tget_member_index</a> +<dt><strong>Name:</strong> <a name="Datatype-Insert">H5Tinsert</a> <dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Tget_member_index</code>(<em>hid_t </em><code>type_id</code>, - <em>const char *</em> <code>field_name</code> + <dd><em>herr_t</em> <code>H5Tinsert</code>(<em>hid_t </em><code>type_id</code>, + <em>const char *</em> <code>name</code>, + <em>size_t</em> <code>offset</code>, + <em>hid_t</em> <code>field_id</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves the index of a compound or enumeration datatype member. + <dd>Adds a new member to a compound datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_member_index</code> retrieves the index of a field - of a compound datatype or an element of an enumeration datatype. - <p> - The name of the target field or element is specified in - <code>field_name</code>. - <p> - Fields are stored in no particular order - with index values of 0 through <em>N</em>-1, where <em>N</em> is - the value returned by <code>H5Tget_nmembers</code>. + <dd><code>H5Tinsert</code> adds another member to the compound datatype + <code>type_id</code>. The new member has a <code>name</code> which + must be unique within the compound datatype. + The <code>offset</code> argument defines the start of the member + in an instance of the compound datatype, and <code>field_id</code> + is the datatype identifier of the new member. + <P> + Note: Members of a compound datatype do not have to be atomic datatypes; + a compound datatype can have a member which is a compound datatype. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to query. - <dt><em>const char *</em> <code>field_name</code> - <dd>Name of the field or member whose index is to be retrieved. + <dd>Identifier of compound datatype to modify. + <dt><em>const char *</em> <code>name</code> + <dd>Name of the field to insert. + <dt><em>size_t</em> <code>offset</code> + <dd>Offset in memory structure of the field to insert. + <dt><em>hid_t</em> <code>field_id</code> + <dd>Datatype identifier of the field to insert. </dl> <dt><strong>Returns:</strong> - <dd>Returns a valid field or member index if successful; + <dd>Returns a non-negative value if successful; otherwise returns a negative value. -<!-- <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_index_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tinsert_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> ---> <!-- <img src="Graphics/Java.gif"> <img src="Graphics/C++.gif"> @@ -2363,36 +2132,31 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_member_offset" --> +<!-- HEADER RIGHT "H5Tis_variable_str" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetMemberOffset">H5Tget_member_offset</a> +<dt><strong>Name:</strong> <a name="Datatype-IsVariableString">H5Tis_variable_str</a> <dt><strong>Signature:</strong> - <dd><em>size_t</em> <code>H5Tget_member_offset</code>(<em>hid_t </em><code>type_id</code>, - <em>int</em> <code>memb_no</code> + <dd><em>htri_t </em><code>H5Tis_variable_str</code>(<em>hid_t </em><code>dtype_id</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves the offset of a field of a compound datatype. + <dd>Determines whether datatype is a variable-length string. <dt><strong>Description:</strong> - <dd><code>H5Tget_member_offset</code> retrieves the - byte offset of the beginning of a field within a - compound datatype with respect to the beginning - of the compound data type datum. + <dd><code>H5Tvlen_create</code> determines whether the datatype + identified in <code>dtype_id</code> is a variable-length string. + <p> + This function can be used to distinguish between + fixed and variable-length string datatypes. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to query. - <dt><em>int</em> <code>memb_no</code> - <dd>Number of the field whose offset is requested. + <dt><em>hid_t</em> <code>dtype_id</code> + <dd>Datatype identifier. </dl> <dt><strong>Returns:</strong> - <dd>Returns the byte offset of the field if successful; - otherwise returns <code>0</code> (zero). - Note that zero is a valid offset and that this function - will fail only if a call to <code>H5Tget_member_class()</code> - fails with the same arguments. + <dd>Returns <code>TRUE</code> or <code>FALSE</code> if successful; + otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_offset_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tis_variable_str_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -2401,78 +2165,69 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_member_type" --> +<!-- HEADER RIGHT "H5Tlock" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetMemberType">H5Tget_member_type</a> +<dt><strong>Name:</strong> <a name="Datatype-Lock">H5Tlock</a> <dt><strong>Signature:</strong> - <dd><em>hid_t</em> <code>H5Tget_member_type</code>(<em>hid_t </em><code>type_id</code>, - <em>int</em> <code>field_idx</code> + <dd><em>herr_t </em><code>H5Tlock</code>(<em>hid_t </em><code>type_id</code> ) <dt><strong>Purpose:</strong> - <dd>Returns the datatype of the specified member. + <dd>Locks a datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_member_type</code> returns the datatype of the specified member. The caller - should invoke H5Tclose() to release resources associated with the type. + <dd><code>H5Tlock</code> locks the datatype specified by the + <code>type_id</code> identifier, making it read-only and + non-destructible. This is normally done by the library for + predefined datatypes so the application does not + inadvertently change or delete a predefined type. + Once a datatype is locked it can never be unlocked. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to query. - <dt><em>int</em> <code>field_idx</code> - <dd>Field index (0-based) of the field type to retrieve. + <dd>Identifier of datatype to lock. </dl> <dt><strong>Returns:</strong> - <dd>Returns the identifier of a copy of the datatype of the field - if successful; + <dd>Returns a non-negative value if successful; otherwise returns a negative value. +<!-- <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_member_type_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tlock_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 "H5Tinsert" --> +<!-- HEADER RIGHT "H5Topen" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-Insert">H5Tinsert</a> +<dt><strong>Name:</strong> <a name="Datatype-Open">H5Topen</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Tinsert</code>(<em>hid_t </em><code>type_id</code>, - <em>const char *</em> <code>name</code>, - <em>size_t</em> <code>offset</code>, - <em>hid_t</em> <code>field_id</code> + <dd><em>hid_t</em><code>H5Topen</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em> <code>name</code> ) <dt><strong>Purpose:</strong> - <dd>Adds a new member to a compound datatype. + <dd>Opens a named datatype. <dt><strong>Description:</strong> - <dd><code>H5Tinsert</code> adds another member to the compound datatype - <code>type_id</code>. The new member has a <code>name</code> which - must be unique within the compound datatype. - The <code>offset</code> argument defines the start of the member - in an instance of the compound datatype, and <code>field_id</code> - is the datatype identifier of the new member. - <P> - Note: Members of a compound datatype do not have to be atomic datatypes; - a compound datatype can have a member which is a compound datatype. + <dd><code>H5Topen</code> opens a named datatype at the location + specified by <code>loc_id</code> and returns an identifier + for the datatype. <code>loc_id</code> is either a file or + group identifier. The identifier should eventually be closed + by calling <code>H5Tclose</code> to release resources. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of compound datatype to modify. + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: A file or group identifier. <dt><em>const char *</em> <code>name</code> - <dd>Name of the field to insert. - <dt><em>size_t</em> <code>offset</code> - <dd>Offset in memory structure of the field to insert. - <dt><em>hid_t</em> <code>field_id</code> - <dd>Datatype identifier of the field to insert. + <dd>IN: A datatype name, defined within the file or group identified by <code>loc_id</code>. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; + <dd>Returns a named datatype identifier if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tinsert_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5topen_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -2609,62 +2364,70 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tunregister" --> +<!-- HEADER RIGHT "H5Tset_cset" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-Unregister">H5Tunregister</a> +<dt><strong>Name:</strong> <a name="Datatype-SetCset">H5Tset_cset</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Tunregister</code>(<em>H5T_conv_t</em> <code>func</code> + <dd><em>herr_t </em><code>H5Tset_cset</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_cset_t</em> <code>cset</code> ) <dt><strong>Purpose:</strong> - <dd>Removes a conversion function from all conversion paths. + <dd>Sets character set to be used. <dt><strong>Description:</strong> - <dd><code>H5Tunregister</code> removes a conversion function from all conversion paths. - <P> - The conversion function pointer type declaration is described in - <a href="#Datatype-Register">H5Tregister</a>. + <dd><code>H5Tset_cset</code> the character set to be used. + <p> + HDF5 is able to distinguish between character sets of different + nationalities and to convert between them to the extent possible. + Valid character set types are: + <ul> <dl> + <dt>H5T_CSET_ASCII (<code>0</code>) + <dd>Character set is US ASCII. + </dl> </ul> <dt><strong>Parameters:</strong> <dl> - <dt><em>H5T_conv_t</em> <code>func</code> - <dd>Function to remove from conversion paths. + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to modify. + <dt><em>H5T_cset_t</em> <code>cset</code> + <dd>Character set type. </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/h5t_FORTRAN.html#h5tunregister_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tset_cset_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 "H5Tenum_create" --> +<!-- HEADER RIGHT "H5Tset_ebias" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-EnumCreate">H5Tenum_create</a> +<dt><strong>Name:</strong> <a name="Datatype-SetEbias">H5Tset_ebias</a> <dt><strong>Signature:</strong> - <dd><em>hid_t</em> <code>H5Tenum_create</code>(<em>hid_t</em> <code>parent_id</code> + <dd><em>herr_t </em><code>H5Tset_ebias</code>(<em>hid_t </em><code>type_id</code>, + <em>size_t</em> <code>ebias</code> ) <dt><strong>Purpose:</strong> - <dd>Creates a new enumeration datatype. + <dd>Sets the exponent bias of a floating-point type. <dt><strong>Description:</strong> - <dd><code>H5Tenum_create</code> creates a new enumeration datatype - based on the specified base datatype, <code>parent_id</code>, - which must be an integer type. + <dd><code>H5Tset_ebias</code> sets the exponent bias of a floating-point type. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>parent_id</code> - <dd>IN: Datatype identifier for the base datatype. + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to set. + <dt><em>size_t</em> <code>ebias</code> + <dd>Exponent bias value. </dl> <dt><strong>Returns:</strong> - <dd>Returns the datatype identifier for the new enumeration datatype if successful; + <dd>Returns a non-negative value if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tenum_create_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tset_ebiass_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -2673,44 +2436,49 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tenum_insert" --> +<!-- HEADER RIGHT "H5Tset_fields" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-EnumInsert">H5Tenum_insert</a> +<dt><strong>Name:</strong> <a name="Datatype-SetFields">H5Tset_fields</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Tenum_insert</code>(<em>hid_t</em> <code>type</code>, - <em>const char</em> *<code>name</code>, - <em>void</em> *<code>value</code> + <dd><em>herr_t </em><code>H5Tset_fields</code>(<em>hid_t </em><code>type_id</code>, + <em>size_t</em> <code>spos</code>, + <em>size_t</em> <code>epos</code>, + <em>size_t</em> <code>esize</code>, + <em>size_t</em> <code>mpos</code>, + <em>size_t</em> <code>msize</code> ) <dt><strong>Purpose:</strong> - <dd>Inserts a new enumeration datatype member. + <dd>Sets locations and sizes of floating point bit fields. <dt><strong>Description:</strong> - <dd><code>H5Tenum_insert</code> inserts a - new enumeration datatype member into an enumeration datatype. - <p> - <code>type</code> is the enumeration datatype, - <code>name</code> is the name of the new member, and - <code>value</code> points to the value of the new member. - <p> - <code>name</code> and <code>value</code> must both - be unique within <code>type</code>. - <p> - <code>value</code> points to data which is of the - datatype defined when the enumeration datatype was created. + <dd><code>H5Tset_fields</code> sets the locations and sizes of the various + floating-point bit fields. The field positions are bit positions in the + significant region of the datatype. Bits are numbered with the least + significant bit number zero. + + <P>Fields are not allowed to extend beyond the number of bits of + precision, nor are they allowed to overlap with one another. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>type</code> - <dd>IN: Datatype identifier for the enumeration datatype. - <dt><em>const char</em> *<code>name</code> - <dd>IN: Name of the new member. - <dt><em>void</em> *<code>value</code> - <dd>IN: Pointer to the value of the new member. + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to set. + <dt><em>size_t</em> <code>spos</code> + <dd>Sign position, i.e., the bit offset of the floating-point + sign bit. + <dt><em>size_t</em> <code>epos</code> + <dd>Exponent bit position. + <dt><em>size_t</em> <code>esize</code> + <dd>Size of exponent in bits. + <dt><em>size_t</em> <code>mpos</code> + <dd>Mantissa bit position. + <dt><em>size_t</em> <code>msize</code> + <dd>Size of mantissa in bits. </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/h5t_FORTRAN.html#h5tenum_insert_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tset_fields_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -2719,48 +2487,42 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tenum_nameof" --> +<!-- HEADER RIGHT "H5Tset_inpad" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-EnumNameOf">H5Tenum_nameof</a> +<dt><strong>Name:</strong> <a name="Datatype-SetInpad">H5Tset_inpad</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Tenum_nameof</code>(<em>hid_t</em> <code>type</code> - <em>void</em> *<code>value</code>, - <em>char</em> *<code>name</code>, - <em>size_t</em> <code>size</code> + <dd><em>herr_t </em><code>H5Tset_inpad</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_pad_t</em> <code>inpad</code> ) <dt><strong>Purpose:</strong> - <dd>Returns the symbol name corresponding to a specified member of an enumeration datatype. + <dd>Fills unused internal floating point bits. <dt><strong>Description:</strong> - <dd><code>H5Tenum_nameof</code> finds the symbol name that - corresponds to the specified <code>value</code> - of the enumeration datatype <code>type</code>. - <p> - At most <code>size</code> characters of the symbol - name are copied into the <code>name</code> buffer. - If the entire symbol name and null terminator - do not fit in the <code>name</code> buffer, then as - many characters as possible are copied - (not null terminated) and the function fails. + <dd>If any internal bits of a floating point type are unused + (that is, those significant bits which are not part of the + sign, exponent, or mantissa), then <code>H5Tset_inpad</code> will be filled + according to the value of the padding value property <code>inpad</code>. + Valid padding types are: + <ul> <dl> + <dt>H5T_PAD_ZERO (<code>0</code>) + <dd>Set background to zeros. + <dt>H5T_PAD_ONE (<code>1</code>) + <dd>Set background to ones. + <dt>H5T_PAD_BACKGROUND (<code>2</code>) + <dd>Leave background alone. + </dl> </ul> <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>type</code> - <dd>IN: Enumeration datatype identifier. - <dt><em>void</em> *<code>value</code>, - <dd>IN: Value of the enumeration datatype. - <dt><em>char</em> *<code>name</code>, - <dd>OUT: Buffer for output of the symbol name. - <dt><em>size_t</em> <code>size</code> - <dd>IN: Anticipated size of the symbol name, in bytes (characters). + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to modify. + <dt><em>H5T_pad_t</em> <code>pad</code> + <dd>Padding type. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful. - Otherwise returns a negative value - and, if <code>size</code> allows it, - the first character of <code>name</code> is - set to <code>NULL</code>. + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tenum_nameof_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tset_inpad_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -2769,39 +2531,39 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tenum_valueof" --> +<!-- HEADER RIGHT "H5Tset_norm" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-EnumValueOf">H5Tenum_valueof</a> +<dt><strong>Name:</strong> <a name="Datatype-SetNorm">H5Tset_norm</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Tenum_valueof</code>(<em>hid_t</em> <code>type</code> - <em>char</em> *<code>name</code>, - <em>void</em> *<code>value</code> + <dd><em>herr_t </em><code>H5Tset_norm</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_norm_t</em> <code>norm</code> ) <dt><strong>Purpose:</strong> - <dd>Returns the value corresponding to a specified member of an enumeration datatype. + <dd>Sets the mantissa normalization of a floating-point datatype. <dt><strong>Description:</strong> - <dd><code>H5Tenum_valueof</code> finds the value that - corresponds to the specified <code>name</code> - of the enumeration datatype <code>type</code>. - <p> - The <code>value</code> argument should be at least - as large as the value of <code>H5Tget_size(type)</code> - in order to hold the result. + <dd><code>H5Tset_norm</code> sets the mantissa normalization of + a floating-point datatype. Valid normalization types are: + <ul> <dl> + <dt>H5T_NORM_IMPLIED (<code>0</code>) + <dd>MSB of mantissa is not stored, always 1 + <dt>H5T_NORM_MSBSET (<code>1</code>) + <dd>MSB of mantissa is always 1 + <dt>H5T_NORM_NONE (<code>2</code>) + <dd>Mantissa is not normalized + </dl> </ul> <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>type</code> - <dd>IN: Enumeration datatype identifier. - <dt><em>const char</em> *<code>name</code>, - <dd>IN: Symbol name of the enumeration datatype. - <dt><em>void</em> *<code>value</code>, - <dd>OUT: Buffer for output of the value of the enumeration datatype. + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to set. + <dt><em>H5T_norm_t</em> <code>norm</code> + <dd>Mantissa normalization type. </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/h5t_FORTRAN.html#h5tenum_valueof_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tset_norm_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -2810,38 +2572,83 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_member_value" --> +<!-- HEADER RIGHT "H5Tset_offset" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetMemberValue">H5Tget_member_value</a> +<dt><strong>Name:</strong> <a name="Datatype-SetOffset">H5Tset_offset</a> <dt><strong>Signature:</strong> - <dd><em>hid_t</em> <code>H5Tget_member_value</code>(<em>hid_t</em> <code>type</code> - <em>int</em> <code>memb_no</code>, - <em>void</em> *<code>value</code> + <dd><em>herr_t </em><code>H5Tset_offset</code>(<em>hid_t </em><code>type_id</code>, + <em>size_t</em> <code>offset</code> ) <dt><strong>Purpose:</strong> - <dd>Returns the value of an enumeration datatype member. + <dd>Sets the bit offset of the first significant bit. <dt><strong>Description:</strong> - <dd><code>H5Tget_member_value</code> returns the value of - the enumeration datatype member <code>memb_no</code>. - <p> - The member value is returned in a user-supplied buffer - pointed to by <code>value</code>. + <dd><code>H5Tset_offset</code> sets the bit offset of the first significant bit. The + significant bits of an atomic datum can be offset from the beginning of + the memory for that datum by an amount of padding. The `offset' + property specifies the number of bits of padding that appear to the + "right of" the value. That is, if we have a 32-bit datum with 16-bits + of precision having the value 0x1122 then it will be laid out in + memory as (from small byte address toward larger byte addresses): + <br> + <br> + + <table border align=center cellpadding=4 width="80%"> + <tr align=center> + <th width="20%">Byte Position</th> + <th width="20%">Big-Endian Offset=0</th> + <th width="20%">Big-Endian Offset=16</th> + <th width="20%">Little-Endian Offset=0</th> + <th width="20%">Little-Endian Offset=16</th> + </tr> + <tr align=center> + <td>0:</td> + <td>[ pad]</td> + <td>[0x11]</td> + <td>[0x22]</td> + <td>[ pad]</td> + </tr> + <tr align=center> + <td>1:</td> + <td>[ pad]</td> + <td>[0x22]</td> + <td>[0x11]</td> + <td>[ pad]</td> + </tr> + <tr align=center> + <td>2:</td> + <td>[0x11]</td> + <td>[ pad]</td> + <td>[ pad]</td> + <td>[0x22]</td> + </tr> + <tr align=center> + <td>3:</td> + <td>[0x22]</td> + <td>[ pad]</td> + <td>[ pad]</td> + <td>[0x11]</td> + </tr> + </table> + +<P>If the offset is incremented then the total size is +incremented also if necessary to prevent significant bits of +the value from hanging over the edge of the datatype. + +<P>The offset of an H5T_STRING cannot be set to anything but +zero. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>type</code> - <dd>IN: Datatype identifier for the enumeration datatype. - <dt><em>int</em> <code>memb_no</code>, - <dd>IN: Number of the enumeration datatype member. - <dt><em>void</em> *<code>value</code> - <dd>OUT: Pointer to a buffer for output of the - value of the enumeration datatype member. + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to set. + <dt><em>size_t</em> <code>offset</code> + <dd>Offset of first significant bit. </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/h5t_FORTRAN.html#h5tget_member_value_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tset_offset_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -2850,32 +2657,39 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tset_tag" --> +<!-- HEADER RIGHT "H5Tset_order" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-SetTag">H5Tset_tag</a> +<dt><strong>Name:</strong> <a name="Datatype-SetOrder">H5Tset_order</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Tset_tag</code>(<em>hid_t</em> <code>type_id</code> - <em>const char</em> *<code>tag</code> + <dd><em>herr_t </em><code>H5Tset_order</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_order_t</em><code>order</code> ) <dt><strong>Purpose:</strong> - <dd>Tags an opaque datatype. + <dd>Sets the byte ordering of an atomic datatype. <dt><strong>Description:</strong> - <dd><code>H5Tset_tag</code> tags an opaque datatype <code>type_id</code> - with a descriptive ASCII identifier,<code> tag</code>. + <dd><code>H5Tset_order</code> sets the byte ordering of an atomic datatype. + Byte orderings currently supported are: + <ul> <dl> + <dt>H5T_ORDER_LE (<code>0</code>) + <dd> Little-endian byte ordering (default). + <dt>H5T_ORDER_BE (<code>1</code>) + <dd> Big-endian byte ordering. + <dt>H5T_ORDER_VAX (<code>2</code>) + <dd>VAX mixed byte ordering (not currently supported). + </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>IN: Datatype identifier for the opaque datatype to be tagged. - <dt><em>const char</em> *<code>tag</code> - <dd>IN: Descriptive ASCII string with which the - opaque datatype is to be tagged. + <dd>Identifier of datatype to set. + <dt><em>H5T_order_t</em> <code>order</code> + <dd>Byte ordering constant. </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/h5t_FORTRAN.html#h5tset_tag_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tset_order_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -2884,31 +2698,83 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_tag" --> +<!-- HEADER RIGHT "H5Tset_overflow" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetTag">H5Tget_tag</a> +<dt><strong>Name:</strong> <a name="Datatype-SetOverflow">H5Tset_overflow</a> <dt><strong>Signature:</strong> - <dd><em>char</em> *<code>H5Tget_tag</code>(<em>hid_t</em> <code>type_id</code> + <dd><em>herr_t</em> <code>H5Tset_overflow</code>(<em>H5T_overflow_t</em> <code>func</code>) +<dt><strong>Purpose:</strong> + <dd>Sets the overflow handler to a specified function. +<dt><strong>Description:</strong> + <dd><code>H5Tset_overflow</code> sets the overflow handler + to be the function specified by <code>func</code>. + <code>func</code> will be called for all datatype conversions that + result in an overflow. + <p> + See the definition of <code>H5T_overflow_t</code> in + <code>H5Tpublic.h</code> for documentation + of arguments and return values. + The prototype for <code>H5T_overflow_t</code> is as follows:<br> + <code>herr_t (*H5T_overflow_t)(hid_t src_id, hid_t dst_id, + void *src_buf, void *dst_buf); + </code> + <p> + The NULL pointer may be passed to remove the overflow handler. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5T_overflow_t</em> <code>func</code> + <dd>Overflow 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/h5t_FORTRAN.html#h5tset_overflow_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 "H5Tset_pad" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetPad">H5Tset_pad</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_pad</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_pad_t</em> <code>lsb</code>, + <em>H5T_pad_t</em> <code>msb</code> ) <dt><strong>Purpose:</strong> - <dd>Gets the tag associated with an opaque datatype. + <dd>Sets the least and most-significant bits padding types. <dt><strong>Description:</strong> - <dd><code>H5Tget_tag</code> returns the tag associated with - the opaque datatype <code>type_id</code>. - <P> - The tag is returned via a pointer to an - allocated string, which the caller must free. + <dd><code>H5Tset_pad</code> sets the least and most-significant bits padding types. + <ul> <dl> + <dt>H5T_PAD_ZERO (<code>0</code>) + <dd>Set background to zeros. + <dt>H5T_PAD_ONE (<code>1</code>) + <dd>Set background to ones. + <dt>H5T_PAD_BACKGROUND (<code>2</code>) + <dd>Leave background alone. + </dl> </ul> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>Datatype identifier for the opaque datatype. + <dd>Identifier of datatype to set. + <dt><em>H5T_pad_t</em> <code>lsb</code> + <dd>Padding type for least-significant bits. + <dt><em>H5T_pad_t</em> <code>msb</code> + <dd>Padding type for most-significant bits. </dl> <dt><strong>Returns:</strong> - <dd>Returns a pointer to an allocated string if successful; - otherwise returns <code>NULL</code>. + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_tag_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tset_pad_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -2917,56 +2783,40 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tarray_create" --> +<!-- HEADER RIGHT "H5Tset_precision" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-ArrayCreate">H5Tarray_create</a> +<dt><strong>Name:</strong> <a name="Datatype-SetPrecision">H5Tset_precision</a> <dt><strong>Signature:</strong> - <dd><em>hid_t</em> <code>H5Tarray_create</code>( - <em>hid_t</em> <code>base</code>, - <em>int</em> <code>rank</code>, - <em>const hsize_t</em> <code>dims[/*rank*/]</code>, - <em>const int</em> <code>perm[/*rank*/]</code> + <dd><em>herr_t </em><code>H5Tset_precision</code>(<em>hid_t </em><code>type_id</code>, + <em>size_t</em><code>precision</code> ) <dt><strong>Purpose:</strong> - <dd>Creates an array datatype object. + <dd>Sets the precision of an atomic datatype. <dt><strong>Description:</strong> - <dd><code>H5Tarray_create</code> creates a new array datatype object. - <p> - <code>base</code> is the datatype of every element of the array, - i.e., of the number at each position in the array. - <p> - <code>rank</code> is the number of dimensions and the - size of each dimension is specified in the array <code>dims</code>. - The value of <code>rank</code> is currently limited to - <code>H5S_MAX_RANK</code> and must be greater than <code>0</code> - (zero). - All dimension sizes specified in <code>dims</code> must be greater - than <code>0</code> (zero). - <p> - The array <code>perm</code> is designed to contain the dimension - permutation, i.e. C versus FORTRAN array order. - - <b><i>(The parameter </i><code>perm</code><i> is currently unused and is not yet implemented.)</i></b> - <p> + <dd><code>H5Tset_precision</code> sets the precision of an atomic datatype. + The precision is the number of significant bits which, unless padding + is present, is 8 times larger than the value returned by H5Tget_size(). + <P>If the precision is increased then the offset is decreased and then + the size is increased to insure that significant bits do not "hang + over" the edge of the datatype. + <P>Changing the precision of an H5T_STRING automatically changes the + size as well. The precision must be a multiple of 8. + <P>When decreasing the precision of a floating point type, set the + locations and sizes of the sign, mantissa, and exponent fields + first. <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>base</code> - <dd>IN: Datatype identifier for the array base datatype. - <dt><em>int</em> <code>rank</code> - <dd>IN: Rank of the array. - <dt><em>const hsize_t</em> <code>dims[/*rank*/]</code> - <dd>IN: Size of each array dimension. - <dt><em>const int</em> <code>perm[/*rank*/]</code> - <dd>IN: Dimension permutation. - - <b><i>(Currently not implemented.)</i></b> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to set. + <dt><em>size_t</em> <code>precision</code> + <dd>Number of bits of precision for datatype. </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/h5t_FORTRAN.html#h5tarray_create_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tset_precision_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -2975,29 +2825,36 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_array_ndims" --> +<!-- HEADER RIGHT "H5Tset_sign" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetArrayNdims">H5Tget_array_ndims</a> +<dt><strong>Name:</strong> <a name="Datatype-SetSign">H5Tset_sign</a> <dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Tget_array_ndims</code>( - <em>hid_t</em> <code>adtype_id</code> + <dd><em>herr_t </em><code>H5Tset_sign</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_sign_t</em> <code>sign</code> ) <dt><strong>Purpose:</strong> - <dd>Returns the rank of an array datatype. + <dd>Sets the sign property for an integer type. <dt><strong>Description:</strong> - <dd><code>H5Tget_array_ndims</code> returns the rank, - the number of dimensions, of an array datatype object. + <dd><code>H5Tset_sign</code> sets the sign property for an integer type. + <ul> <dl> + <dt>H5T_SGN_NONE (<code>0</code>) + <dd>Unsigned integer type. + <dt>H5T_SGN_2 (<code>1</code>) + <dd>Two's complement signed integer type. + </dl> </ul> <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>adtype_id</code> - <dd>IN: Datatype identifier of array object. + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to set. + <dt><em>H5T_sign_t</em> <code>sign</code> + <dd>Sign type. </dl> <dt><strong>Returns:</strong> - <dd>Returns the rank of the array if successful; + <dd>Returns a non-negative value if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_array_ndims_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tset_sign_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -3006,39 +2863,102 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tget_array_dims" --> +<!-- HEADER RIGHT "H5Tset_size" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-GetArrayDims">H5Tget_array_dims</a> +<dt><strong>Name:</strong> <a name="Datatype-SetSize">H5Tset_size</a> <dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Tget_array_dims</code>( - <em>hid_t</em> <code>adtype_id</code>, - <em>hsize_t *</em><code>dims[]</code>, - <em>int *</em><code>perm[]</code> + <dd><em>herr_t </em><code>H5Tset_size</code>(<em>hid_t </em><code>type_id</code>, + <em>size_t</em><code>size</code> ) <dt><strong>Purpose:</strong> - <dd>Retrieves sizes of array dimensions and dimension permutations. + <dd>Sets the total size for an atomic datatype. <dt><strong>Description:</strong> - <dd><code>H5Tget_array_dims</code> returns the sizes of the dimensions - and the dimension permutations of the specified array datatype object. + <dd><code>H5Tset_size</code> sets the total size in bytes, + <code>size</code>, for a datatype. If the datatype is atomic and size + is decreased so that the significant bits of the datatype extend beyond + the edge of the new size, then the `offset' property is decreased + toward zero. If the `offset' becomes zero and the significant + bits of the datatype still hang over the edge of the new size, then + the number of significant bits is decreased. + The size set for a string should include space for the null-terminator + character, otherwise it will not be stored on (or retrieved from) disk. + Adjusting the size of an string automatically sets the precision + to 8*size. A compound datatype may increase in size, but may not + shrink. All datatypes must have a positive size. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to change size. + <dt><em>size_t</em> <code>size</code> + <dd>Size in bytes to modify datatype. + </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/h5t_FORTRAN.html#h5tset_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 "H5Tset_strpad" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetStrpad">H5Tset_strpad</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_strpad</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_str_t</em> <code>strpad</code> + ) +<dt><strong>Purpose:</strong> + <dd>Defines the storage mechanism for character strings. +<dt><strong>Description:</strong> + <dd><code>H5Tset_strpad</code> defines the storage mechanism for the string. <p> - The sizes of the dimensions are returned in the array <code>dims</code>. - The dimension permutations, i.e., C versus FORTRAN array order, - are returned in the array <code>perm</code>. + The method used to store character strings differs with the + programming language: + <ul> + <li>C usually null terminates strings while + <li>Fortran left-justifies and space-pads strings. + </ul> + Valid string padding values, as passed in the parameter + <code>strpad</code>, are as follows: + <ul> <dl> + <dt>H5T_STR_NULLTERM (<code>0</code>) + <dd>Null terminate (as C does) + <dt>H5T_STR_NULLPAD (<code>1</code>) + <dd>Pad with zeros + <dt>H5T_STR_SPACEPAD (<code>2</code>) + <dd>Pad with spaces (as FORTRAN does) + </dl> </ul> + <p> + When converting from a longer string to a shorter string, + the behavior is as follows. + If the short string is <code>H5T_STR_NULLPAD</code> or + <code>H5T_STR_SPACEPAD</code>, then the string is simply truncated. + If the short string is <code>H5T_STR_NULLTERM</code>, it is + truncated and a null terminator is appended. + <p> + When converting from a shorter string to a longer string, + the long string is padded on the end by appending nulls or spaces. + + <dt><strong>Parameters:</strong> <dl> - <dt><em>hid_t</em> <code>adtype_id</code> - <dd>IN: Datatype identifier of array object. - <dt><em>hsize_t *</em><code>dims[]</code> - <dd>OUT: Sizes of array dimensions. - <dt><em>int *</em><code>perm[]</code> - <dd>OUT: Dimension permutations. + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of datatype to modify. + <dt><em>H5T_str_t</em> <code>strpad</code> + <dd>String padding type. </dl> <dt><strong>Returns:</strong> - <dd>Returns the non-negative number of dimensions of the array type if successful; + <dd>Returns a non-negative value if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5t_FORTRAN.html#h5tget_array_dims_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tset_strpad_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -3047,29 +2967,32 @@ zero. </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Tclose" --> +<!-- HEADER RIGHT "H5Tset_tag" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Datatype-Close">H5Tclose</a> +<dt><strong>Name:</strong> <a name="Datatype-SetTag">H5Tset_tag</a> <dt><strong>Signature:</strong> - <dd><em>herr_t </em><code>H5Tclose</code>(<em>hid_t </em><code>type_id</code> + <dd><em>herr_t</em> <code>H5Tset_tag</code>(<em>hid_t</em> <code>type_id</code> + <em>const char</em> *<code>tag</code> ) <dt><strong>Purpose:</strong> - <dd>Releases a datatype. + <dd>Tags an opaque datatype. <dt><strong>Description:</strong> - <dd><code>H5Tclose</code> releases a datatype. Further access - through the datatype identifier is illegal. Failure to release - a datatype with this call will result in resource leaks. + <dd><code>H5Tset_tag</code> tags an opaque datatype <code>type_id</code> + with a descriptive ASCII identifier,<code> tag</code>. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> - <dd>Identifier of datatype to release. + <dd>IN: Datatype identifier for the opaque datatype to be tagged. + <dt><em>const char</em> *<code>tag</code> + <dd>IN: Descriptive ASCII string with which the + opaque datatype is to be tagged. </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/h5t_FORTRAN.html#h5tclose_f" + <dd><a href="fortran/h5t_FORTRAN.html#h5tset_tag_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -3077,6 +3000,81 @@ zero. --> </dl> +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Tunregister" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Unregister">H5Tunregister</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Tunregister</code>(<em>H5T_conv_t</em> <code>func</code> + ) +<dt><strong>Purpose:</strong> + <dd>Removes a conversion function from all conversion paths. +<dt><strong>Description:</strong> + <dd><code>H5Tunregister</code> removes a conversion function from all conversion paths. + <P> + The conversion function pointer type declaration is described in + <a href="#Datatype-Register">H5Tregister</a>. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5T_conv_t</em> <code>func</code> + <dd>Function to remove from conversion paths. + </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/h5t_FORTRAN.html#h5tunregister_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 "H5Tvlen_create" --> +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-VLCreate">H5Tvlen_create</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Tvlen_create</code>(<em>hid_t </em><code>base_type_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Creates a new variable-length datatype. +<dt><strong>Description:</strong> + <dd><code>H5Tvlen_create</code> creates a new variable-length (VL) datatype. + <p> + The base datatype will be the datatype that the sequence is composed of, + characters for character strings, vertex coordinates for polygon lists, etc. + The base type specified for the VL datatype can be of any HDF5 datatype, + including another VL datatype, a compound datatype or an atomic datatype. + <p> + When necessary, use <code>H5Tget_super</code> to determine the base type + of the VL datatype. + <p> + The datatype identifier returned from this function should be + released with <code>H5Tclose</code> or resource leaks will result. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>base_type_id</code> + <dd>Base type of datatype to create. + </dl> +<dt><strong>See Also:</strong> + <dd><a href="RM_H5D.html#Dataset-GetVLBuf">H5Dget_vlen_buf_size</a> + <dd><a href="RM_H5D.html#Dataset-VLReclaim">H5Dvlen_reclaim</a> +<dt><strong>Returns:</strong> + <dd>Returns datatype identifier if successful; + otherwise returns a negative value. +<dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5t_FORTRAN.html#h5tvlen_create_f" + target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> + <!-- + <img src="Graphics/Java.gif"> + <img src="Graphics/C++.gif"> + --> +</dl> <!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr> <center> @@ -3111,14 +3109,13 @@ 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 --><SCRIPT LANGUAGE="JAVASCRIPT"> <!-- -document.writeln("Last modified: 3 July 2003"); +document.writeln("Last modified: 3 October 2003"); --> </SCRIPT> diff --git a/doc/html/RM_H5Z.html b/doc/html/RM_H5Z.html index 27e6491..87fb4e2 100644 --- a/doc/html/RM_H5Z.html +++ b/doc/html/RM_H5Z.html @@ -62,8 +62,7 @@ And in this document, the </td></tr> </table> </center> -<hr> -<!-- #EndLibraryItem --><center> +<hr><!-- #EndLibraryItem --><center> <h1>H5Z: Filter and Compression Interface</h1> </center> @@ -154,6 +153,35 @@ facilitate moving easily between them.</i> <!-- NEW PAGE --> <!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Zfilter_avail" --> +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Compression-FilterAvail">H5Zfilter_avail</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Zfilter_avail</code>(<em>H5Z_filter_t</em> <code>filter</code>) + <dt><strong>Purpose:</strong> + <dd>Determines whether a filter is available. + <dt><strong>Description:</strong> + <dd><code>H5Zfilter_avail</code> determines whether the filter + specified in <code>filter</code> is available to the application. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>H5Z_filter_t</em> <code>filter</code> + <dd>IN: Filter 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/h5z_FORTRAN.html#h5zfilter_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 "H5Zregister" --> <hr> <dl> @@ -393,41 +421,6 @@ facilitate moving easily between them.</i> --> </dl> -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Zfilter_avail" --> -<hr> -<dl> - <dt><strong>Name:</strong> <a name="Compression-FilterAvail">H5Zfilter_avail</a> - <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Zfilter_avail</code>(<em>H5Z_filter_t</em> <code>filter</code>) - <dt><strong>Purpose:</strong> - <dd>Determines whether a filter is available. - <dt><strong>Description:</strong> - <dd><code>H5Zfilter_avail</code> determines whether the filter - specified in <code>filter</code> is available to the application. - <dt><strong>Parameters:</strong> - <dl> - <dt><em>H5Z_filter_t</em> <code>filter</code> - <dd>IN: Filter 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/h5z_FORTRAN.html#h5zfilter_avail_f" - target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> - <!-- - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - - - - - - - <!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr> <center> @@ -462,14 +455,13 @@ 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 --><SCRIPT LANGUAGE="JAVASCRIPT"> <!-- -document.writeln("Last modified: 10 June 2003"); +document.writeln("Last modified: 3 October 2003"); --> </SCRIPT> |