diff options
Diffstat (limited to 'doc/src/RM_H5P.html')
| -rw-r--r-- | doc/src/RM_H5P.html | 1693 |
1 files changed, 1693 insertions, 0 deletions
diff --git a/doc/src/RM_H5P.html b/doc/src/RM_H5P.html new file mode 100644 index 0000000..90d6920 --- /dev/null +++ b/doc/src/RM_H5P.html @@ -0,0 +1,1693 @@ +<html> +<head><title> +HDF5/H5P Draft API Specification +</title></head> + +<body> + +<center> +<h1>H5P: Property List Interface</h1> +</center> + +<h2>Property List API Functions</h2> + +These functions manipulate property list objects to allow objects which require +many different parameters to be easily manipulated. + +<dir> +<table border=0> +<tr><td valign=top> + + <i>General Property List Operations</i> + <ul> + <li><a href="#Property-Create">H5Pcreate</a> + <li><a href="#Property-GetClass">H5Pget_class</a> + <li><a href="#Property-Copy">H5Pcopy</a> + <li><a href="#Property-Close">H5Pclose</a> + </ul> + + <p><i>File Creation Properties</i> + <ul> + <li><a href="#Property-GetVersion">H5Pget_version</a> + <li><a href="#Property-SetUserblock">H5Pset_userblock</a> + <li><a href="#Property-GetUserblock">H5Pget_userblock</a> + <li><a href="#Property-SetSizes">H5Pset_sizes</a> + <li><a href="#Property-GetSizes">H5Pget_sizes</a> + <li><a href="#Property-SetSymK">H5Pset_sym_k</a> + <li><a href="#Property-GetSymK">H5Pget_sym_k</a> + <li><a href="#Property-SetIstoreK">H5Pset_istore_k</a> + <li><a href="#Property-GetIstoreK">H5Pget_istore_k</a> + </ul> + +</td><td> </td><td valign=top> + + <i>File Access Properties</i> + <ul> + <li><a href="#Property-GetDriver">H5Pget_driver</a> + <li><a href="#Property-SetStdio">H5Pset_stdio</a> + <li><a href="#Property-GetStdio">H5Pget_stdio</a> + <li><a href="#Property-SetSec2">H5Pset_sec2</a> + <li><a href="#Property-GetSec2">H5Pget_sec2</a> + <li><a href="#Property-SetAlignment">H5Pset_alignment</a> + <li><a href="#Property-GetAlignment">H5Pget_alignment</a> + <li><a href="#Property-SetCore">H5Pset_core</a> + <li><a href="#Property-GetCore">H5Pget_core</a> + <li><a href="#Property-SetMPI">H5Pset_mpi</a> || + <li><a href="#Property-GetMPI">H5Pget_mpi</a> || + <li><a href="#Property-SetFamily">H5Pset_family</a> + <li><a href="#Property-GetFamily">H5Pget_family</a> + <li><a href="#Property-SetCache">H5Pset_cache</a> + <li><a href="#Property-GetCache">H5Pget_cache</a> + <li><a href="#Property-SetSplit">H5Pset_split</a> + <li><a href="#Property-GetSplit">H5Pget_split</a> + </ul> + +</td><td> </td><td valign=top> + + <i>Dataset Creation Properties</i> + <ul> + <li><a href="#Property-SetLayout">H5Pset_layout</a> + <li><a href="#Property-GetLayout">H5Pget_layout</a> + <li><a href="#Property-SetChunk">H5Pset_chunk</a> + <li><a href="#Property-GetChunk">H5Pget_chunk</a> + <li><a href="#Property-SetDeflate">H5Pset_deflate</a> + <li><a href="#Property-GetDeflate">H5Pget_deflate</a> + <li><a href="#Property-SetCompression">H5Pset_compression</a> + <li><a href="#Property-GetCompression">H5Pget_compression</a> + <li><a href="#Property-SetExternal">H5Pset_external</a> + <li><a href="#Property-GetExternalCount">H5Pget_external_count</a> + <li><a href="#Property-GetExternal">H5Pget_external</a> + </ul> + + <p><i>Dataset Memory and Transfer Properties</i> + <ul> + <li><a href="#Property-SetBuffer">H5Pset_buffer</a> + <li><a href="#Property-GetBuffer">H5Pget_buffer</a> + <li><a href="#Property-SetPreserve">H5Pset_preserve</a> + <li><a href="#Property-GetPreserve">H5Pget_preserve</a> + <li><a href="#Property-SetXfer">H5Pset_xfer</a> || + <li><a href="#Property-GetXfer">H5Pget_xfer</a> || + </ul> + +</td></tr> + +<tr><td colspan=5 align=right> +<br> +|| <i>Available only in the parallel HDF5 library.</i> +</td></tr> + +</table> +</dir + + +<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">H5F</a> + for details about the file creation properties. + <dt><code>H5P_FILE_ACCESS</code> + <dd>Properties for file access. + See <a href="../Files.html">H5F</a> + for details about the file creation properties. + <dt><code>H5P_DATASET_CREATE</code> + <dd>Properties for dataset creation. + See <a href="../Datasets.html">H5D</a> + for details about dataset creation properties. + <dt><code>H5P_DATASET_XFER</code> + <dd>Properties for raw data transfer. + See <a href="../Datasets.html">H5D</a> + for details about raw data transfer properties. + </dl> + <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). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-Close">H5Pclose</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pclose</code>(<em>hid_t</em> <code>plist</code> + ) + <dt><strong>Purpose:</strong> + <dd>Terminates access to a property list. + <dt><strong>Description:</strong> + <dd><code>H5Pclose</code> terminates access to a property list. + All property lists should be closed when the application is + finished accessing them. + This frees resources used by the property list. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of the property list to terminate access to. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetClass">H5Pget_class</a> + <dt><strong>Signature:</strong> + <dd><em>H5P_class_t </em><code>H5Pget_class</code>(<em>hid_t</em> <code>plist</code> + ) + <dt><strong>Purpose:</strong> + <dd>Returns the property list class for a property list. + <dt><strong>Description:</strong> + <dd><code>H5Pget_class</code> returns the property list class for the + property list identied by the <code>plist</code> parameter. + Valid property list classes are defined in the description of + <code>H5Pcreate()</code>. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of property list to query. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a property list class if successful. + Otherwise returns H5P_NO_CLASS (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-Copy">H5Pcopy</a> + <dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Pcopy</code>(<em>hid_t</em> <code>plist</code> + ) + <dt><strong>Purpose:</strong> + <dd>Copies an existing property list to create a new property list. + <dt><strong>Description:</strong> + <dd><code>H5Pcopy</code> copies an existing property list to create + a new property list. + The new property list has the same properties and values + as the original property list. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of property list to duplicate. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a property list identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetVersion">H5Pget_version</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>boot</code>, + <em>int *</em> <code>freelist</code>, + <em>int *</em> <code>stab</code>, + <em>int *</em> <code>shhdr</code> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves the version information of various objects for + a file creation 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. + <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>boot</code> + <dd>OUT: Pointer to location to return boot 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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetUserblock">H5Pget_userblock</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> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves the size of a user block. + <dt><strong>Description:</strong> + <dd><code>H5Pget_userblock</code> retrieves the size of a user block + in a file creation property list. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: 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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<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 4 bytes. Valid values currenly 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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<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: 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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetMPI">H5Pset_mpi</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pset_mpi</code>(<em>hid_t</em> <code>plist</code>, + <em>MPI_Comm</em> <code>comm</code>, + <em>MPI_Info</em> <code>info</code> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves the access mode for parallel I/O and the user supplied + communicator and info object. + <dt><strong>Description:</strong> + <dd><code>H5Pset_mpi</code> stores the access mode for MPIO call and the user supplied + communicator and info in the access property list, which can then + be used to open file. This function is available only in the + parallel HDF5 library and 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 modify + <dt><em>MPI_Comm</em> <code>comm</code> + <dd>IN: MPI communicator to be used for file open as defined in + MPI_FILE_OPEN of MPI-2. This function does not make a + duplicated <code>comm</code>. Any modification to <code>comm</code> after + this function call returns may have undetermined effect + to the access property list. Users should call this function + again to setup the property list. + <dt><em>MPI_Info</em> <code>info</code> + <dd>IN: MPI info object to be used for file open as defined in + MPI_FILE_OPEN of MPI-2. This function does not make a + duplicated <code>info</code>. Any modification to <code>info</code> after + this function call returns may have undetermined effect + to the access property list. Users should call this function + again to setup the property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetMPI">H5Pget_mpi</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pget_mpi</code>(<em>hid_t</em> <code>plist</code>, + <em>MPI_Comm</em> <code>*comm</code>, + <em>MPI_Info</em> <code>*info</code> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves the communicator and info object. + <dt><strong>Description:</strong> + <dd><code>H5Pget_mpi</code> retrieves the communicator and info object + that have been set by H5Pset_mpi. + This function is available only in the parallel HDF5 library + and is not a collective function. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a file access property list that has been set + successfully by H5Pset_mpi. + <dt><em>MPI_Comm *</em> <code>comm</code> + <dd>OUT: Pointer to location to return the communicator. + <dt><em>MPI_Info *</em> <code>info</code> + <dd>OUT: Pointer to location to return the info object. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if the file access property list is set to the MPI. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetXfer">H5Pset_xfer</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pset_xfer</code>(<em>hid_t</em> <code>plist</code>, + <em>H5D_transfer_t</em> <code>data_xfer_mode</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the transfer mode of the dataset transfer property list. + <dt><strong>Description:</strong> + <dd><code>H5Pset_xfer</code> sets the transfer mode of the dataset transfer property list. + The list can then be used to control the I/O transfer mode + during dataset accesses. This function is available only + in the parallel HDF5 library and is not a collective function. + <p> + Valid data transfer modes are: + <ul><dl> + <dt>H5D_XFER_INDEPENDENT + <dd>Use independent I/O access. + (Currently the default mode.) + <dt>H5D_XFER_COLLECTIVE + <dd>Use MPI collective I/O access. + <dt>H5D_XFER_DFLT + <dd>User default I/O access. + </dl></ul> + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a dataset transfer property list + <dt><em>H5D_transfer_t</em> <code>data_xfer_mode</code> + <dd>IN: Data transfer mode. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetXfer">H5Pget_xfer</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pget_xfer</code>(<em>hid_t</em> <code>plist</code>, + <em>H5D_transfer_t *</em> <code>data_xfer_mode</code> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves the transfer mode from the dataset transfer property list. + <dt><strong>Description:</strong> + <dd><code>H5Pget_xfer</code> retrieves the transfer mode from the dataset + transfer property list. + This function is available only in the parallel HDF5 library + and is not a collective function. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a dataset transfer property list. + <dt><em>H5D_transfer_t *</em> <code>data_xfer_mode</code> + <dd>OUT: Pointer to location to return the data transfer mode. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetSymK">H5Pget_sym_k</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> + ) + <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. + <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 creationproperty 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</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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<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. 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 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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetIstoreK">H5Pget_istore_k</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> + ) + <dt><strong>Purpose:</strong> + <dd>Queries the 1/2 rank of an indexed storage B-tree. + <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. + <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> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<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 store the raw data for a dataset. + <dt><strong>Description:</strong> + <dd><code>H5Pset_layout</code> sets the type of storage used store the + raw data for a dataset. + This function is only valid for dataset creation property lists. + Valid parameters for <code>layout</code> are: + <ul><dl> + <dt>H5D_COMPACT + <dd>Store raw data and object header contiguously in file. + This should only be used for very small amounts of raw + data (suggested less than 1KB). + <dt>H5D_CONTIGUOUS + <dd>Store raw data seperately from object header in one + large chunk in the file. + <dt>H5D_CHUNKED + <dd>Store raw data seperately from object header in one + large chunk in the file and store chunks of the raw + data in seperate 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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetLayout">H5Pget_layout</a> + <dt><strong>Signature:</strong> + <dd><em>H5D_layout_t</em> <code>H5Pget_layout</code>(<em>hid_t</em> <code>plist</code>) + <dt><strong>Purpose:</strong> + <dd>Returns the layout of the raw data for a dataset. + <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. + Valid types for <code>layout</code> are: + <ul> <dl> + <dt>H5D_COMPACT + <dd>Raw data and object header stored contiguously in file. + <dt>H5D_CONTIGUOUS + <dd>Raw data stored seperately from object header in one + large chunk in the file. + <dt>H5D_CHUNKED + <dd>Raw data stored seperately from object header in + chunks in seperate locations in the file. + </dl> </ul> + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier for property list to query. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns the layout type of a a dataset creation property list + if successful. + Otherwise returns H5D_LAYOUT_ERROR (-1). +</dl> + + +<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 H5D_CHUNKED, if it isn't 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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetChunk">H5Pget_chunk</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> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves the size of chunks for the raw data of a chunked layout dataset. + <dt><strong>Description:</strong> + <dd><code>H5Pget_chunk</code> retrieves the size of chunks for the + raw data of a chunked layout dataset. + This function is only valid for dataset creation property lists. + At most, <code>max_ndims</code> elements of <code>dims</code> + will be initialized. + <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>OUT: 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 chunk dimensionality successful; + otherwise FAIL (-1). +</dl> + + +<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 alignment properties of a file access property list. + <dt><strong>Description:</strong> + <dd><code>H5Pset_alignment</code> sets the alignment properties + of a file access property list + so that any file object >= THRESHOLD bytes will be aligned on + an address which is a multiple of ALIGNMENT. 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 ALIGNMENT. + <p> + Default values for THRESHOLD and ALIGNMENT 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>plist</code> + <dd>IN: Identifier for a file access property list. + <dt><em>hsize_t</em> <code>threshold</code> + <dd>IN: Threshhold value. + <dt><em>hsize_t</em> <code>alignment</code> + <dd>IN: Alignment value. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetAlignment">H5Pget_alignment</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> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves the current settings for alignment properties from a + file access property list. + <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). + <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 threshhold 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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetExternal">H5Pset_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> + ) + <dt><strong>Purpose:</strong> + <dd>Adds an external file to the list of external files. + <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 SIZE 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). + <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. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetExternalCount">H5Pget_external_count</a> + <dt><strong>Signature:</strong> + <dd><em>int</em> <code>H5Pget_external_count</code>(<em>hid_t</em> <code>plist</code>, + ) + <dt><strong>Purpose:</strong> + <dd>Returns the number of external files for a dataset. + <dt><strong>Description:</strong> + <dd><code>H5Pget_external_count</code> returns the number of external files + for the specified dataset. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a dataset creation property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns the number of external files if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetExternal">H5Pget_external</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> + ) + <dt><strong>Purpose:</strong> + <dd>Returns information about an external file. + <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. + <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. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetDriver">H5Pget_driver</a> + <dt><strong>Signature:</strong> + <dd><em>H5F_driver_t</em> <code>H5Pget_driver</code>(<em>hid_t</em> <code>plist</code>, + ) + <dt><strong>Purpose:</strong> + <dd>Returns a low-level file driver identifier. + <dt><strong>Description:</strong> + <dd><code>H5Pget_driver</code> returns the identifier of the + low-level file driver. Valid identifiers are: + <ul> + <li>H5F_LOW_STDIO (0) + <li>H5F_LOW_SEC2 (1) + <li>H5F_LOW_MPIO (2) + <li>H5F_LOW_CORE (3) + <li>H5F_LOW_SPLIT (4) + <li>H5F_LOW_FAMILY (5) + </ul> + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a file access property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a low-level driver identifier if successful. + Otherwise returns H5F_LOW_ERROR (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetStdio">H5Pset_stdio</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_stdio</code>(<em>hid_t</em> <code>plist</code>) + <dt><strong>Purpose:</strong> + <dd>Sets the low level file driver to use the functions declared + in the stdio.h. + <dt><strong>Description:</strong> + <dd><code>H5Pset_stdio</code> sets the low level file driver to use + the functions declared + in the stdio.h file: fopen(), fseek() or fseek64(), fread(), + fwrite(), and fclose(). + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a file access property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetStdio">H5Pget_stdio</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pget_stdio</code>(<em>hid_t</em> <code>plist</code>) + <dt><strong>Purpose:</strong> + <dd>Determines whether the file access property list is set to + the stdio driver. + <dt><strong>Description:</strong> + <dd><code>H5Pget_stdio</code> checks to determine whether the + file access property list is set to the stdio driver. + In the future, additional arguments may be added to this + function to match those added to H5Pset_stdio(). + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a file access property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if the file access propety list is set + to the stdio driver. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetSec2">H5Pset_sec2</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_sec2</code>(<em>hid_t</em> <code>plist</code>, + ) + <dt><strong>Purpose:</strong> + <dd>Sets the low-level file driver to use the declared functions. + <dt><strong>Description:</strong> + <dd><code>H5Pset_sec2</code> sets the low-level file driver to use + the functions declared + in the unistd.h file: open(), lseek() or lseek64(), read(), + write(), and close(). + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a file access property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetSec2">H5Pget_sec2</a> + <dt><strong>Signature:</strong> + <dd><em>returntype</em> <code>H5Pget_sec2</code>(<em>hid_t</em> <code>plist</code>) + <dt><strong>Purpose:</strong> + <dd>Checks whether the file access propety list is set + to the sec2 driver. + <dt><strong>Description:</strong> + <dd><code>H5Pget_sec2</code> checks to determine whether the + file access property list is set to the sec2 driver. + In the future, additional arguments may be + added to this function to match those added to H5Pset_sec2(). + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a file access property list. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if the file access propety list is set + to the sec2 driver. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetCore">H5Pset_core</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_core</code>(<em>hid_t</em> <code>plist</code>, + <em>size_t</em> <code>increment</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the low-level file driver to use malloc() and free(). + <dt><strong>Description:</strong> + <dd><code>H5Pset_core</code> sets the low-level file driver to use malloc() and free(). + This driver is restricted to temporary files which are not + larger than the amount of virtual memory available. The + INCREMENT argument determines the file block size and memory + will be allocated in multiples of INCREMENT bytes. A liberal + INCREMENT results in fewer calls to realloc() and probably + less memory fragmentation. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of a file access property list. + <dt><em>size_t</em> <code>increment</code> + <dd>IN: File block size in bytes. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetCore"></a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pget_core</code>(<em>hid_t</em> <code>plist</code>, + <em>size_t</em> <code>*increment</code> + ) + <dt><strong>Purpose:</strong> + <dd>Determines whether the file access property list is set + to the core driver. + <dt><strong>Description:</strong> + <dd><code>H5Pget_core</code> checks to determine whether the + file access property list is set to the core driver. + On success, the block size is returned + through the INCREMENT argument if it isn't the null pointer. + In the future, additional arguments may be added to this + function to match those added to H5Pset_core(). + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of the file access property list. + <dt><em>size_t</em> <code>*increment</code> + <dd>OUT: Pointer to a location to return the file block size (in bytes). + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if the file access propety list is set + to the core driver. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetSplit">H5Pset_split</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_split</code>(<em>hid_t</em> <code>plist</code>, + <em>const char</em> <code>*meta_ext</code>, + <em>hid_t</em> <code>meta_plist</code>, + <em>const char</em> <code>*raw_ext</code>, + <em>hid_t</em> <code>raw_plist</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the low-level driver to split meta data from raw data. + <dt><strong>Description:</strong> + <dd><code>H5Pset_split</code> sets the low-level driver to + split meta data from raw data, storing meta data in one file and + raw data in another file. The meta file will have a name + which is formed by adding <em>meta_extension</em> (recommended + default value: <code>.meta</code>) to the end of the base name + and will be accessed according to the <em>meta_properties</em>. + The raw file will have a name which is formed by appending + <em>raw_extension</em> (recommended default value: + <code>.raw</code>) to the base name and will be accessed according + to the <em>raw_properties</em>. + Additional parameters may be added to this function in the future. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of the file access property list. + <dt><em>const char</em> <code>*meta_ext</code> + <dd>IN: Name of the extension for the metafile filename. + Recommended default value: <code>.meta</code>. + <dt><em>hid_t</em> <code>meta_plist</code> + <dd>IN: Identifier of the meta file access property list. + <dt><em>const char</em> <code>*raw_ext</code> + <dd>IN: Name extension for the raw file filename. + Recommended default value: <code>.raw</code>. + <dt><em>hid_t</em> <code>raw_plist</code> + <dd>IN: Identifier of the raw file access property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetSplit">H5Pget_split</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pget_split</code>(<em>hid_t</em> <code>plist</code>, + <em>size_t</em> <code>meta_ext_size</code>, + <em>char</em> <code>*meta_ext</code>, + <em>hid_t</em> <code>*meta_properties</code>, + <em>size_t</em> <code>raw_ext_size</code>, + <em>char</em> <code>*raw_ext</code>, + <em>hid_t</em> <code>*raw_properties</code> + ) + <dt><strong>Purpose:</strong> + <dd>Determines whether the file access property list is set + to the split driver. + <dt><strong>Description:</strong> + <dd><code>H5Pget_split</code> checks to determine whether the file + access property list is set to the split driver. + On successful return, + <em>meta_properties</em> and <em>raw_properties</em> will + point to copies of the meta and raw access property lists + which should be closed by calling <code>H5Pclose()</code> when + the application is finished with them, but if the meta and/or + raw file has no property list then a negative value is + returned for that property list identifier. Also, if + <em>meta_extension</em> and/or <em>raw_extension</em> are + non-null pointers, at most <em>meta_ext_size</em> or + <em>raw_ext_size</em> characters of the meta or raw file name + extension will be copied to the specified buffer. If the + actual name is longer than what was requested then the result + will not be null terminated (similar to + <code>strncpy()</code>). In the future, additional arguments + may be added to this function to match those added to + <code>H5Pset_split()</code>. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of the file access property list. + <dt><em>size_t</em> <code>meta_ext_size</code> + <dd>IN: Number of characters of the meta file extension to be + copied to the <code>meta_ext</code> buffer. + <dt><em>OUT</em> <code>*meta_ext</code> + <dd>IN: Meta file extension. + <dt><em>hid_t</em> <code>*meta_properties</code> + <dd>OUT: Pointer to a copy of the meta file access property list. + <dt><em>size_t</em> <code>raw_ext_size</code> + <dd>IN: Number of characters of the raw file extension to be + copied to the <code>raw_ext</code> buffer. + <dt><em>char</em> <code>*raw_ext</code> + <dd>OUT: Raw file extension. + <dt><em>hid_t</em> <code>*raw_properties</code> + <dd>OUT: Pointer to a copy of the raw file access property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if the file access propety list is set + to the split driver. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetFamily">H5Pset_family</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_family</code>(<em>hid_t</em> <code>plist</code>, + <em>hsize_t</em> <code>memb_size</code>, + <em>hid_t</em> <code>memb_plist</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the file access properties list to the <em>family</em> + driver. + <dt><strong>Description:</strong> + <dd><code>H5Pset_family</code> sets the file access properties + to use the <em>family</em> + driver; any previously defined driver properties are erased + from the property list. Each member of the file family will + use <em>member_properties</em> as its file access property + list. The <em>memb_size</em> argument gives the logical size + in bytes of each family member but the actual size could be + smaller depending on whether the file contains holes. The + member size is only used when creating a new file or + truncating an existing file; otherwise the member size comes + from the size of the first member of the family being + opened. Note: if the size of the <code>off_t</code> type is + four bytes then the maximum family member size is usually + 2^31-1 because the byte at offset 2,147,483,647 is generally + inaccessable. Additional parameters may be added to this + function in the future. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of the file access property list. + <dt><em>hsize_t</em> <code>memb_size</code> + <dd>IN: Logical size, in bytes, of each family member. + <dt><em>hid_t</em> <code>memb_plist</code> + <dd>IN: Identifier of the file access property list + for each member of the family. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetFamily">H5Pget_family</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pget_family</code>(<em>hid_t</em> <code>tid</code>, + <em>hsize_t</em> <code>*memb_size</code>, + <em>hid_t</em> <code>*memb_plist</code> + ) + <dt><strong>Purpose:</strong> + <dd>Determines whether the file access property list + is set to the family driver. + <dt><strong>Description:</strong> + <dd><code>H5Pget_family</code> checks to determine whether the + file access property list is set to the family driver. + On successful return, + <em>access_properties</em> will point to a copy of the member + access property list which should be closed by calling + <code>H5Pclose()</code> when the application is finished with + it. If <em>memb_size</em> is non-null then it will contain + the logical size in bytes of each family member. In the + future, additional arguments may be added to this function to + match those added to <code>H5Pset_family()</code>. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier of the file access property list. + <dt><em>hsize_t</em> <code>*memb_size</code> + <dd>OUT: Logical size, in bytes, of each family member. + <dt><em>hid_t</em> <code>*memb_plist</code> + <dd>OUT: Identifier of the file access property list + for each member of the family. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if the file access propety list is set + to the family driver. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetCache">H5Pset_cache</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_cache</code>(<em>hid_t</em> <code>plist</code>, + <em>int</em> <code>mdc_nelmts</code>, + <em>size_t</em> <code>rdcc_nbytes</code>, + <em>double</em> <code>rdcc_w0</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the number of elements in the meta data cache and the + total number of bytes in the raw data chunk cache. + <dt><strong>Description:</strong> + <dd><code>H5Pset_cache</code> sets the number of elements (objects) in the meta data cache and the + total number of bytes in the raw data chunk cache. + <p> + Sets or queries the meta data cache and raw data chunk cache + parameters. The <em>plist</em> is a file access property + list. The number of elements (objects) in the meta data cache + is <em>mdc_nelmts</em>. The total size of the raw data chunk + cache and the preemption policy is <em>rdcc_nbytes</em> and + <em>w0</em>. For <code>H5Pget_cache()</code> any (or all) of + the pointer arguments may be null pointers. + <p> + The RDCC_W0 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>plist</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>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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetCache">H5Pget_cache</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pget_cache</code>(<em>hid_t</em> <code>plist</code>, + <em>int</em> <code>*mdc_nelmts</code>, + <em>size_t</em> <code>*rdcc_nbytes</code>, + <em>double</em> <code>*rdcc_w0</code> + ) + <dt><strong>Purpose:</strong> + <dd>Retrieves maximun sizes of meta data cache and RDCC_WO. + <dt><strong>Description:</strong> + <dd>Retrieves the maximum possible number of elements in the meta + data cache and the maximum possible number of bytes and the + RDCC_W0 value in the raw data chunk cache. 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 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>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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetBuffer">H5Pset_buffer</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_buffer</code>(<em>hid_t</em> <code>plist</code>, + <em>size_t</em> <code>size</code>, + <em>void</em> <code>*tconv</code>, + <em>void</em> <code>*bkg</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets type conversion and background buffers. + <dt><strong>Description:</strong> + <dd> Given a dataset transfer property list, <code>H5Pset_buffer</code> + sets the maximum size + for the type conversion buffer and background buffer and + optionally supply pointers to application-allocated buffers. + If the buffer size is smaller than the entire amount of data + being transfered between application and file, and a type + conversion buffer or background buffer is required then + strip mining will be used. However, certain restrictions + apply for the size of buffer which can be used for strip + mining. For instance, when strip mining a 100x200x300 + hyperslab of a simple data space the buffer must be large + enough to hold a 1x200x300 slab. + <p> + If TCONV and/or BKG are null pointers then buffers will be + allocated and freed during the data transfer. + <p> + The default value for the maximum buffer is 1 Mb. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier for the dataset transfer property list. + <dt><em>size_t</em> <code>size</code> + <dd>IN: Size for the type conversion and background buffers. + <dt><em>void</em> <code>tconv</code> + <dd>IN: Pointer to application-allocated type conversion buffer. + <dt><em>void</em> <code>bkg</code> + <dd>IN: Pointer to application-allocated background buffer. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetBuffer">H5Pget_buffer</a> + <dt><strong>Signature:</strong> + <dd><em>size_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 if successful; + otherwise 0 on failure. +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetPreserve">H5Pset_preserve</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Pset_preserve</code>(<em>hid_t</em> <code>plist</code>, + <em>hbool_t</em> <code>status</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the dataset transfer property list status to TRUE or FALSE. + <dt><strong>Description:</strong> + <dd><code>H5Pset_preserve</code> sets the + dataset transfer property list status to TRUE or FALSE. + <p> + When reading or writing compound data types and the + destination is partially initialized and the read/write is + intended to initialize the other members, one must set this + property to TRUE. Otherwise the I/O pipeline treats the + destination datapoints as completely uninitialized. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier for the dataset transfer property list. + <dt><em>hbool_t</em> <code>status</code> + <dd>IN: Status of for the dataset transfer property list + (TRUE/FALSE). + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-GetPreserve">H5Pget_preserve</a> + <dt><strong>Signature:</strong> + <dd><em>int</em> <code>H5Pget_preserve</code>(<em>hid_t</em> <code>plist</code>) + <dt><strong>Purpose:</strong> + <dd>Checks status of the dataset transfer property list. + <dt><strong>Description:</strong> + <dd><code>H5Pget_preserve</code> checks the status of the + dataset transfer property list. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>plist</code> + <dd>IN: Identifier for the dataset transfer property list. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns TRUE or FALSE if successful; + otherwise FAIL (-1). +</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 compresion 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="UG/Compression.html"><cite>Compression</cite></a> + in the <cite>HDF5 User's Guide</cite> for further information. + <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 SUCCEED (0) if successful; + otherwise FAIL (-1). +</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 CLIENT_DATA buffer is initially CD_SIZE bytes. + On return, CLIENT_DATA will be initialized + with at most that many bytes, and CD_SIZE 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 FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Property-SetDeflate">H5Pset_deflate</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> + ) + <dt><strong>Purpose:</strong> + <dd>Sets compression method and compression level. + <dt><strong>Description:</strong> + <dd><code>H5Pset_deflate</code> sets the compression method for a + dataset creation property + list to H5D_COMPRESS_DEFLATE and the compression level to + LEVEL which should be a value between zero and 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 creation property list. + <dt><em>int</em> <code>level</code> + <dd>IN: Compression level. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</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 FAIL (-1). +</dl> + + +<hr> + +<address> +<a href="mailto:fbaker@ncsa.uiuc.edu">Frank Baker</a> +<br> +<a href="mailto:h5docs@ncsa.uiuc.edu">HDF5 Documentation</a> + +<br> +Last modified: 8 July 1998 + +</body> +</html> |