diff options
author | Frank Baker <fbaker@hdfgroup.org> | 2003-10-03 22:53:10 (GMT) |
---|---|---|
committer | Frank Baker <fbaker@hdfgroup.org> | 2003-10-03 22:53:10 (GMT) |
commit | c9c54b60413e004032f52c058c97e5734f2574fe (patch) | |
tree | 8bb0b4aa932b25925940b6ca2449721efb04dd09 /doc | |
parent | 478ed94629adade57dc51bab63b2d7b03b8e7e3c (diff) | |
download | hdf5-c9c54b60413e004032f52c058c97e5734f2574fe.zip hdf5-c9c54b60413e004032f52c058c97e5734f2574fe.tar.gz hdf5-c9c54b60413e004032f52c058c97e5734f2574fe.tar.bz2 |
[svn-r7537]
Purpose:
Alphabetizing the RM function entries. This commit finishes the
task in the 1.6 release branch.
Platforms tested:
IE 5, Safari
Diffstat (limited to 'doc')
-rw-r--r-- | doc/html/RM_H5P.html | 1188 |
1 files changed, 509 insertions, 679 deletions
diff --git a/doc/html/RM_H5P.html b/doc/html/RM_H5P.html index fa725d5..e7e377b 100644 --- a/doc/html/RM_H5P.html +++ b/doc/html/RM_H5P.html @@ -4744,6 +4744,53 @@ facilitate moving easily between them.</i> --> </dl> +<!-- ********** MOVED TO TechNotes/VFLfunc.html ********** + +<hr> +<dl> + <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>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>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_dxpl_mpio" --> <hr> @@ -5466,6 +5513,56 @@ facilitate moving easily between them.</i> --> </dl> + +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Pget_fapl_mpio" --> +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetFaplMpiPosix">H5Pset_fapl_mpiposix</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 "H5Pset_fapl_multi" --> <hr> @@ -6574,87 +6671,177 @@ fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl); </dl> <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Punregister" --> +<!-- HEADER RIGHT "H5Pset_meta_block_size" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-Unregister">H5Punregister</a> - + <dt><strong>Name:</strong> <a name="Property-SetMetaBlockSize">H5Pset_meta_block_size</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> - ) - + <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> + ) <dt><strong>Purpose:</strong> - <dd>Removes a property from a property list class. - + <dd>Sets the minimum metadata block size. <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. - + <dd><code>H5Pset_meta_block_size</code> sets the + minimum size, in bytes, of metadata block allocations when + <code>H5FD_FEAT_AGGREGATE_METADATA</code> is set by a VFL driver. + <p> + Each <i>raw</i> metadata block is initially allocated to be of the + given size. Specific metadata objects (e.g., object headers, + local heaps, B-trees) are then sub-allocated from this block. + <p> + The default setting is 2048 bytes, meaning that the library + will attempt to aggregate metadata in at least 2K blocks in the file. + Setting the value to <code>0</code> (zero) with this function + will turn off metadata aggregation, even if the VFL driver attempts + to use the metadata aggregation strategy. + <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> - <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> - + <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. + </dl> <dt><strong>Returns:</strong> - <dd>Success: a non-negative value - <dd>Failure: a negative value - - <dt><strong>Non-C APIs:</strong> - <dd><a href="fortran/h5p_FORTRAN.html#h5punregister_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#h5pset_meta_block_size_f" + target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> + <!-- + <img src="Graphics/Java.gif"> + <img src="Graphics/C++.gif"> + --> </dl> - - - - - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Pset_multi_type" --> +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetMultiType">H5Pset_multi_type</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_multi_type</code> ( + <em>hid_t</em> <code>fapl_id</code>, + <em>H5FD_mem_t</em> <code>type</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets data type property for <code>MULTI</code> driver. + <dt><strong>Description:</strong> + <dd><code>H5Pset_multi_type</code> sets the data type property in the + file access or data transfer property list <code>fapl_id</code>. + This enables a user application to specifiy the type of data the + appication wishes to access so that the application + can retrieve a file handle for low-level access to the particular member + of a set of <code>MULTI</code> files in which that type of data is stored. + The file handle is retrieved with a separate call + to <a href="RM_H5F.html#File-GetVfdHandle"><code>H5Fget_vfd_handle</code></a> + (or, in special circumstances, to <code>H5FDget_vfd_handle</code>; + see <cite>Virtual File Layer</cite> and <cite>List of VFL Functions</cite> + in <a href="TechNotes.html"><cite>HDF5 Technical Notes</cite></a>). + <p> + The type of data specified in <code>type</code> may be one of the following: + <table border=0> + <tr valign=top align=left><td> </td><td> + <code>H5FD_MEM_DEFAULT</code> + </td><td> + Need description.... + </td></tr> + <tr valign=top align=left><td> </td><td> + <code>H5FD_MEM_SUPER</code> + </td><td> + Super block ... need description.... + </td></tr> + <tr valign=top align=left><td> </td><td> + <code>H5FD_MEM_BTREE</code> + </td><td> + Btree ... need description.... + </td></tr> + <tr valign=top align=left><td> </td><td> + <code>H5FD_MEM_DRAW</code> + </td><td> + Need description.... + </td></tr> + <tr valign=top align=left><td> </td><td> + <code>H5FD_MEM_GHEAP</code> + </td><td> + Global heap ... need description.... + </td></tr> + <tr valign=top align=left><td> </td><td> + <code>H5FD_MEM_LHEAP</code> + </td><td> + Local Heap ... need description.... + </td></tr> + <tr valign=top align=left><td> </td><td> + <code>H5FD_MEM_OHDR</code> + </td><td> + Need description.... + </td></tr> + </table> + <p> + Use of this function is only appropriate for an HDF5 file written + as a set of files with the <code>MULTI</code> file driver. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>fapl_id</code> + <dd>IN: File access property list or data transfer property list identifier. + <dt><em>H5FD_mem_t</em> <code>type</code> + <dd>OUT: Type of data. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. + <!-- + <dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5p_FORTRAN.html#h5pxxx_f" + 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" --> +<!-- HEADER RIGHT "H5Pset_preserve" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetUserblock">H5Pset_userblock</a> + <dt><strong>Name:</strong> <a name="Property-SetPreserve">H5Pset_preserve</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>H5Pset_preserve</code>(<em>hid_t</em> <code>plist</code>, + <em>hbool_t</em> <code>status</code> ) <dt><strong>Purpose:</strong> - <dd>Sets user block size. + <dd>Sets the dataset transfer property list status to TRUE or FALSE. <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>H5Pset_preserve</code> sets the + dataset transfer property list status to TRUE or FALSE. + <p> + When reading or writing compound data types and the + destination is partially initialized and the read/write is + intended to initialize the other members, one must set this + property to TRUE. Otherwise the I/O pipeline treats the + destination datapoints as completely uninitialized. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>plist</code> - <dd>IN: Identifier of property list to modify. - <dt><em>hsize_t</em> <code>size</code> - <dd>IN: Size of the user-block in bytes. + <dd>IN: Identifier for the dataset transfer property list. + <dt><em>hbool_t</em> <code>status</code> + <dd>IN: Status of for the dataset transfer property list + (TRUE/FALSE). </dl> <dt><strong>Returns:</strong> <dd>Returns a non-negative value if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5p_FORTRAN.html#h5pset_userblock_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"> @@ -6662,7 +6849,97 @@ fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl); --> </dl> +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Pset_shuffle" --> +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetShuffle">H5Pset_shuffle</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_shuffle</code>(<em>hid_t</em> <code>plist_id</code>) + <dt><strong>Purpose:</strong> + <dd>Sets up use of the shuffle filter. + <dt><strong>Description:</strong> + <dd><code>H5Pset_shuffle</code> sets the shuffle filter, + <code>H5Z_FILTER_SHUFFLE</code>, + in the dataset creation property list <code>plist_id</code>. + <p> + The shuffle filter <span class=termEmphasis>de-interlaces</span> + a block of data by reordering the bytes. + All the bytes from one consistent byte position of + each data element are placed together in one block; + all bytes from a second consistent byte position of + each data element are placed together a second block; etc. + For example, given three data elements of a 4-byte datatype + stored as <code>012301230123</code>, + shuffling will re-order data as <code>000111222333</code>. + This can be a valuable step in an effective compression + algorithm because the bytes in each byte position are often + closely related to each other and putting them together + can increase the compression ratio. + <p> + This filter is designed to be used in combination with + a compression filter. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist_id</code> + <dd>IN: Dataset creation property list identifier. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. + <dt><strong>Non-C API(s):</strong> + <dd><a href="fortran/h5p_FORTRAN.html#h5pset_shuffle_f" + target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> + <!-- + <img src="Graphics/Java.gif"> + <img src="Graphics/C++.gif"> + --> +</dl> +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Pset_sieve_buf_size" --> +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetSieveBufSize">H5Pset_sieve_buf_size</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_sieve_buf_size</code>( + <em>hid_t</em> <code>fapl_id</code>, + <em>hsize_t</em> <code>size</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the maximum size of the data sieve buffer. + <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. + <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. + </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_sieve_buf_size_f" + target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> + <!-- + <img src="Graphics/Java.gif"> + <img src="Graphics/C++.gif"> + --> +</dl> <!-- NEW PAGE --> <!-- HEADER RIGHT "H5Pset_sizes" --> @@ -6706,7 +6983,64 @@ fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl); --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5Pset_small_data_block_size" --> +<hr> +<dl> + <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_small_data_block_size</code>(<em>hid_t</em> <code>fapl_id</code>, + <em>hsize_t</em> <code>size</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the size of a contiguous block reserved for small data. + <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. + <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>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 a negative value. + <dt><strong>Non-C API(s):</strong> + <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 "H5Pset_sym_k" --> @@ -6759,105 +7093,6 @@ fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl); --> </dl> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_shuffle" --> -<hr> -<dl> - <dt><strong>Name:</strong> <a name="Property-SetShuffle">H5Pset_shuffle</a> - <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Pset_shuffle</code>(<em>hid_t</em> <code>plist_id</code>) - <dt><strong>Purpose:</strong> - <dd>Sets up use of the shuffle filter. - <dt><strong>Description:</strong> - <dd><code>H5Pset_shuffle</code> sets the shuffle filter, - <code>H5Z_FILTER_SHUFFLE</code>, - in the dataset creation property list <code>plist_id</code>. - <p> - The shuffle filter <span class=termEmphasis>de-interlaces</span> - a block of data by reordering the bytes. - All the bytes from one consistent byte position of - each data element are placed together in one block; - all bytes from a second consistent byte position of - each data element are placed together a second block; etc. - For example, given three data elements of a 4-byte datatype - stored as <code>012301230123</code>, - shuffling will re-order data as <code>000111222333</code>. - This can be a valuable step in an effective compression - algorithm because the bytes in each byte position are often - closely related to each other and putting them together - can increase the compression ratio. - <p> - This filter is designed to be used in combination with - a compression filter. - <dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>plist_id</code> - <dd>IN: Dataset creation property list identifier. - </dl> - <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. - <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5p_FORTRAN.html#h5pset_shuffle_f" - target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> - <!-- - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> - - - <!-- NEW PAGE --> <!-- HEADER RIGHT "H5Pset_szip" --> <hr> @@ -7068,57 +7303,34 @@ END LIBRARY-SET OPTION TAGS --> --> </dl> - - - - - - <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_meta_block_size" --> +<!-- HEADER RIGHT "H5Pset_userblock" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetMetaBlockSize">H5Pset_meta_block_size</a> + <dt><strong>Name:</strong> <a name="Property-SetUserblock">H5Pset_userblock</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>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 the minimum metadata block size. + <dd>Sets user block size. <dt><strong>Description:</strong> - <dd><code>H5Pset_meta_block_size</code> sets the - minimum size, in bytes, of metadata block allocations when - <code>H5FD_FEAT_AGGREGATE_METADATA</code> is set by a VFL driver. - <p> - Each <i>raw</i> metadata block is initially allocated to be of the - given size. Specific metadata objects (e.g., object headers, - local heaps, B-trees) are then sub-allocated from this block. - <p> - The default setting is 2048 bytes, meaning that the library - will attempt to aggregate metadata in at least 2K blocks in the file. - Setting the value to <code>0</code> (zero) with this function - will turn off metadata aggregation, even if the VFL driver attempts - to use the metadata aggregation strategy. - <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. + <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>fapl_id</code> - <dd>IN: File access property list identifier. + <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: Minimum size, in bytes, of metadata block allocations. + <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. + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5p_FORTRAN.html#h5pset_meta_block_size_f" + <dd><a href="fortran/h5p_FORTRAN.html#h5pset_userblock_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -7126,181 +7338,141 @@ END LIBRARY-SET OPTION TAGS --> --> </dl> - - <!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_sieve_buf_size" --> +<!-- HEADER RIGHT "H5Pset_vlen_mem_manager" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetSieveBufSize">H5Pset_sieve_buf_size</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_sieve_buf_size</code>( - <em>hid_t</em> <code>fapl_id</code>, - <em>hsize_t</em> <code>size</code> + <dd><em>herr_t</em> <code>H5Pset_vlen_mem_manager</code>(<em>hid_t</em> <code>plist</code>, + <em>H5MM_allocate_t</em> <code>alloc</code>, + <em>void</em> *<code>alloc_info</code>, + <em>H5MM_free_t</em> <code>free</code>, + <em>void</em> *<code>free_info</code> ) <dt><strong>Purpose:</strong> - <dd>Sets the maximum size of the data sieve buffer. - <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. - <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. - </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_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_small_data_block_size" --> -<hr> -<dl> - <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_small_data_block_size</code>(<em>hid_t</em> <code>fapl_id</code>, - <em>hsize_t</em> <code>size</code> - ) - <dt><strong>Purpose:</strong> - <dd>Sets the size of a contiguous block reserved for small data. + <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_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_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 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 <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 small data block size is set as an allocation property in the - file access property list identified by <code>fapl_id</code>. + 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> - Setting <code>size</code> to zero (<code>0</code>) disables the - small data block mechanism. + 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>hsize_t</em> <code>size</code> - <dd>IN: Maximum size, in bytes, of the small data block. + <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> - The default size is <code>2048</code>. + 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 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#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_preserve" --> +<!-- HEADER RIGHT "H5Punregister" --> <hr> <dl> - <dt><strong>Name:</strong> <a name="Property-SetPreserve">H5Pset_preserve</a> + <dt><strong>Name:</strong> <a name="Property-Unregister">H5Punregister</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>H5Punregister</code>( + <em>H5P_class_t</em> <code>class</code>, + <em>const char *</em><code>name</code> ) + <dt><strong>Purpose:</strong> - <dd>Sets the dataset transfer property list status to TRUE or FALSE. + <dd>Removes a property from a property list class. + <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>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> - <dl> - <dt><em>hid_t</em> <code>plist</code> - <dd>IN: Identifier for the dataset transfer property list. - <dt><em>hbool_t</em> <code>status</code> - <dd>IN: Status of for the dataset transfer property list - (TRUE/FALSE). - </dl> - <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. - <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5p_FORTRAN.html#h5pset_preserve_f" - target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> - <!-- - <img src="Graphics/Java.gif"> - <img src="Graphics/C++.gif"> - --> -</dl> + <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> <!-- @@ -7409,8 +7581,6 @@ END LIBRARY-SET OPTION TAGS --> --> - - <!-- <hr> @@ -7442,346 +7612,6 @@ END LIBRARY-SET OPTION TAGS --> --> -<!-- NEW PAGE --> -<!-- HEADER RIGHT "H5Pset_vlen_mem_manager" --> -<hr> -<dl> - <dt><strong>Name:</strong> <a name="Property-SetVLMemManager">H5Pset_vlen_mem_manager</a> - <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Pset_vlen_mem_manager</code>(<em>hid_t</em> <code>plist</code>, - <em>H5MM_allocate_t</em> <code>alloc</code>, - <em>void</em> *<code>alloc_info</code>, - <em>H5MM_free_t</em> <code>free</code>, - <em>void</em> *<code>free_info</code> - ) - <dt><strong>Purpose:</strong> - <dd>Sets the memory manager for variable-length datatype allocation in - <code>H5Dread</code> and <code>H5Dvlen_reclaim</code>. - <dt><strong>Description:</strong> - <dd><code>H5Pset_vlen_mem_manager</code> sets the memory manager for - variable-length datatype allocation in <code>H5Dread</code> - and free in <code>H5Dvlen_reclaim</code>. - <p> - The <code>alloc</code> and <code>free</code> parameters - identify the memory management routines to be used. - If the user has defined custom memory management routines, - <code>alloc</code> and/or <code>free</code> should be set to make - those routine calls (i.e., the name of the routine is used as - the value of the parameter); - if the user prefers to use the system's <code> malloc</code> - and/or <code>free</code>, the <code>alloc</code> and - <code>free</code> parameters, respectively, should be set to - <code> NULL</code> - <p> - The prototypes for these user-defined functions would appear as follows: - <br> - <em>typedef void</em> *(*<code>H5MM_allocate_t</code>)(<em>size_t</em> <code>size</code>, - <em>void</em> *<code>alloc_info</code>) ; - - <br> - <em>typedef void</em> (*<code>H5MM_free_t</code>)(<em>void</em> *<code>mem</code>, - <em>void</em> *<code>free_info</code>) ; - <br> - The <code>alloc_info</code> and <code>free_info</code> parameters - can be used to pass along any required information to - the user's memory management routines. - <p> - In summary, if the user has defined custom memory management - routines, the name(s) of the routines are passed in the - <code>alloc</code> and <code>free</code> parameters and the - custom routines' parameters are passed in the - <code>alloc_info</code> and <code>free_info</code> parameters. - If the user wishes to use the system <code> malloc</code> and - <code>free</code> functions, the <code>alloc</code> and/or - <code>free</code> parameters are set to <code> NULL</code> - and the <code>alloc_info</code> and <code>free_info</code> - parameters are ignored. - <dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>plist</code> - <dd>IN: Identifier for the dataset transfer property list. - <dt><em>H5MM_allocate_t</em> <code>alloc</code> - <dd>IN: User's allocate routine, or <code> NULL</code> - for system <code> malloc</code>. - <dt><em>void</em> *<code>alloc_info</code> - <dd>IN: Extra parameter for user's allocation routine. - <br> - Contents are ignored if preceding parameter is - <code> NULL</code>. - <dt><em>H5MM_free_t</em> <code>free</code> - <dd>IN: User's free routine, or <code> NULL</code> - for system <code>free</code>. - <dt><em>void</em> *<code>free_info</code> - <dd>IN: Extra parameter for user's free routine. - <br> - Contents are ignored if preceding parameter is - <code> NULL</code>. - </dl> - <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. - <!-- - <dt><strong>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> - - - - -<!-- --> -<!-- The new *fapl* functions with R1.4 --> -<!-- --> - - - - - - - - - - - - - - - -<!-- 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 "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> - - - - - - - - - - - - -<!-- ********** MOVED TO TechNotes/VFLfunc.html ********** - -<hr> -<dl> - <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>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>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> - ---> - - - - - - - - - - - - - - - - - - - - - - - <!-- ***** TEMPLATE ***** |