diff options
| author | Elena Pourmal <epourmal@hdfgroup.org> | 1998-07-08 22:28:21 (GMT) |
|---|---|---|
| committer | Elena Pourmal <epourmal@hdfgroup.org> | 1998-07-08 22:28:21 (GMT) |
| commit | 49f626b81f028a09d5c287156120a5d405008335 (patch) | |
| tree | ee0178875371da97373cb5c08a2fa7a276f94ccd /doc/src | |
| parent | 2f1f2ac4e44efef28ac7b7edaf4f9470b866c9fc (diff) | |
| download | hdf5-49f626b81f028a09d5c287156120a5d405008335.zip hdf5-49f626b81f028a09d5c287156120a5d405008335.tar.gz hdf5-49f626b81f028a09d5c287156120a5d405008335.tar.bz2 | |
[svn-r475] HDF5 Reference Manual files.
Main file is RM_H5Front.html. Created from the Alpha1 Ref. Manual, Alpha1
User's Guide Documents and the Alpha2 Source Code.
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/RM_H5A.html | 506 | ||||
| -rw-r--r-- | doc/src/RM_H5D.html | 374 | ||||
| -rw-r--r-- | doc/src/RM_H5E.html | 377 | ||||
| -rw-r--r-- | doc/src/RM_H5F.html | 192 | ||||
| -rw-r--r-- | doc/src/RM_H5Front.html | 258 | ||||
| -rw-r--r-- | doc/src/RM_H5G.html | 882 | ||||
| -rw-r--r-- | doc/src/RM_H5P.html | 1693 | ||||
| -rw-r--r-- | doc/src/RM_H5S.html | 291 | ||||
| -rw-r--r-- | doc/src/RM_H5T.html | 1323 | ||||
| -rw-r--r-- | doc/src/RM_H5Z.html | 93 |
10 files changed, 5989 insertions, 0 deletions
diff --git a/doc/src/RM_H5A.html b/doc/src/RM_H5A.html new file mode 100644 index 0000000..a6738e4 --- /dev/null +++ b/doc/src/RM_H5A.html @@ -0,0 +1,506 @@ +<html> +<head><title> +HDF5/H5A Draft API Specification +</title></head> + +<body> + +<center> +<h1>H5A: Attribute Interface</h1> +</center> + +<h2>Attribute API Functions</h2> + +These functions create and manipulate attributes +and information about attributes. + +<table border=0> +<tr><td valign=top> +<ul> + <li><a href="#Annot-Create">H5Acreate</a> + <li><a href="#Annot-Write">H5Awrite</a> + <li><a href="#Annot-Read">H5Aread</a> + <li><a href="#Annot-Close">H5Aclose</a> +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#Annot-GetName">H5Aget_name</a> + <li><a href="#Annot-OpenName">H5Aopen_name</a> + <li><a href="#Annot-OpenIdx">H5Aopen_idx</a> + <li><a href="#Annot-GetSpace">H5Aget_space</a> +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#Annot-GetType">H5Aget_type</a> + <li><a href="#Annot-NumAttrs">H5Anum_attrs</a> + <li><a href="#Annot-Iterate">H5Aiterate</a> + <li><a href="#Annot-Delete">H5Adelete</a> +</ul> +</td></tr> +</table> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Annot-Create">H5Acreate</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t</em> <code>H5Acreate</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code>, + <em>hid_t</em> <code>datatype</code>, + <em>hid_t</em> <code>dataspace</code>, + <em>hid_t</em> <code>create_plist</code> + ) +<dt><strong>Purpose:</strong> + <dd>Creates a dataset as an attribute of another dataset or group. +<dt><strong>Description:</strong> + <dd>SC: <code>H5Acreate</code> creates an attribute which is attached to the object + specified with 'location_id'. The name specified with 'name' for each + attribute for an object must be unique for that object. The 'type_id' + and 'space_id' are created with the H5T and H5S interfaces respectively. + Currently only simple dataspaces are allowed for attribute dataspaces. + The 'create_plist_id' property list is currently un-used, but will be + used int the future for optional properties of attributes. The attribute + identifier returned from this function must be released with H5Aclose or resource + leaks will develop. + <p> + The link created (see H5G API documentation for more information on + link types) is a hard link, so the attribute may be shared among datasets + and will not be removed from the file until the reference count for the + attribute is reduced to zero. + <p> + The location object may be either a group or a dataset, both of + which may have any sort of attribute. + <p> + UG: <code>H5Acreate</code> creates an attribute which is attached to the object + specified with <em>loc_id</em>. The name specified with <em>name</em> + for each attribute for an object must be unique for that object. The <em>type_id</em> + and <em>space_id</em> are created with the H5T and H5S interfaces + respectively. Currently only simple dataspaces are allowed for attribute + dataspaces. The <em>create_plist_id</em> property list is currently + unused, but will be used int the future for optional properties of + attributes. The attribute identifier returned from this function must be released + with H5Aclose or resource leaks will develop. Attempting to create an + attribute with the same name as an already existing attribute will fail, + leaving the pre-existing attribute in place. + <p> + <b>datatype, dataspace, create_plist in the UG are + type_id, space_id, and create_plist_id, respectively, in the SC</b> + <p> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: Object (dataset or group) to be attached to + <dt><em>const char *</em><code>name</code> + <dd>IN: Name of attribute to create + <dt><em>hid_t</em> <code>datatype</code> + <dd>IN: Identifier of datatype for attribute + <dt><em>hid_t</em> <code>dataspace</code> + <dd>IN: Identifier of dataspace for attribute + <dt><em>hid_t</em> <code>create_plist</code> + <dd>IN: Identifier of creation property list (currently not used) + </dl> +<dt><strong>Returns:</strong> + <dd>Returns an attribute identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Annot-OpenName">H5Aopen_name</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t</em> <code>H5Aopen_name</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code> + ) +<dt><strong>Purpose:</strong> + <dd> Opens an attribute for an object by looking up the attribute name. +<dt><strong>Description:</strong> + <dd> SC: <code>H5Aopen_name</code> opens an existing attribute for access. The attribute + name specified is used to look up the corresponding attribute for the + object. The attribute identifier returned from this function must be released with + H5Aclose or resource leaks will develop. + <p> + The location object may be either a group or a dataset, both of + which may have any sort of attribute. + <p> + UG: <code>H5Aopen_name</code> opens an attribute which is attached to the object + specified with loc_id. The name specified with name indicates the + attribute to access. The attribute identifier returned from this function must + be released with H5Aclose or resource leaks will develop. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: Object (dataset or group) to be attached to + <dt><em>const char *</em><code>name</code> + <dd>IN: Name of attribute to locate and open + </dl> +<dt><strong>Returns:</strong> + <dd>Returns attribute identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Annot-OpenIdx">H5Aopen_idx</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t</em> <code>H5Aopen_idx</code>(<em>hid_t</em> <code>loc_id</code>, + <em>unsigned int</em> <code>idx</code> + ) +<dt><strong>Purpose:</strong> + <dd>Opens the <i>n</i>th attribute for an object. +<dt><strong>Description:</strong> + <dd>SC: <code>H5Aopen_idx</code> opens an existing attribute for access. The attribute + index specified is used to look up the corresponding attribute for the + object. The attribute identifier returned from this function must be released with + H5Aclose or resource leaks will develop. + <p> + The location object may be either a group or a dataset, both of + which may have any sort of attribute. + <p> + UG: <code>H5Aopen_idx</code> opens an attribute which is attached to the object + specified with loc_id. The attribute specified with idx indicates the + <i>idx</i>th attribute to access, starting with '0'. + The attribute identifier returned from this function must be released with + H5Aclose or resource leaks will develop. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: Object (dataset or group) to be attached to + <dt><em>unsigned int</em> <code>idx</code> + <dd>IN: Index (0-based) attribute to open + </dl> +<dt><strong>Returns:</strong> + <dd>Returns attribute identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Annot-Write">H5Awrite</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Awrite</code>(<em>hid_t</em> <code>attr_id</code>, + <em>hid_t</em> <code>mem_dt</code>, + <em>void *</em><code>buf</code> + ) +<dt><strong>Purpose:</strong> + <dd>Write out data to an attribute. +<dt><strong>Description:</strong> + <dd>SC: <code>H5Awrite</code> writes a complete attribute to disk. + <p> + UG: <code>H5Awrite</code> writes an attribute, specified with attr_id, + with mem_type_id specifying the datatype in memory. + The entire attribute is written from buf to the file. + This function returns non-negative on success, negative on failure. + <p> + <b>mem_dt in SC is mem_type_id in UG.</b> + <p> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>attr_id</code> + <dd>IN: Attribute to write + <dt><em>hid_t</em> <code>mem_dt</code> + <dd>IN: Memory datatype of buffer + <dt><em>void *</em><code>buf</code> + <dd>IN: Buffer of data to write + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Annot-Read">H5Aread</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Aread</code>(<em>hid_t</em> <code>attr_id</code>, + <em>hid_t</em> <code>mem_dt</code>, + <em>void *</em><code>buf</code> + ) +<dt><strong>Purpose:</strong> + <dd>Read in data from an attribute. +<dt><strong>Description:</strong> + <dd>SC: <code>H5Aread</code> reads a complete attribute from disk. + <p> + UG: <code>H5Aread</code> reads an attribute, specified with attr_id, + with mem_type_id specifying the datatype in memory. + The entire attribute is read into buf from the file. + This function returns non-negative on success, negative on failure. + <p> + <b>mem_dt in SC is mem_type_id in UG.</b> + <p> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>attr_id</code> + <dd>IN: Attribute to read + <dt><em>hid_t</em> <code>mem_dt</code> + <dd>IN: Memory datatype of buffer + <dt><em>void *</em><code>buf</code> + <dd>IN: Buffer for data to read + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Annot-GetSpace">H5Aget_space</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t</em> <code>H5Aget_space</code>(<em>hid_t</em> <code>attr_id</code>) +<dt><strong>Purpose:</strong> + <dd>Gets a copy of the dataspace for an attribute. +<dt><strong>Description:</strong> + <dd><code>H5Aget_space</code> retrieves a copy of the dataspace for an attribute. + The dataspace identifier returned from this function must be released with H5Sclose + or resource leaks will develop. + <p> + <i>(Identical desc in UG and SC.)</i> + <p> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>attr_id</code> + <dd>IN: Attribute to get dataspace of + </dl> +<dt><strong>Returns:</strong> + <dd>Returns dataspace identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Annot-GetType">H5Aget_type</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t</em> <code>H5Aget_type</code>(<em>hid_t</em> <code>attr_id</code>) +<dt><strong>Purpose:</strong> + <dd>Gets a copy of the datatype for an attribute. +<dt><strong>Description:</strong> + <dd><code>H5Aget_type</code> retrieves a copy of the datatype for an attribute. + The datatype identifier returned from this function must be released with + H5Tclose or resource leaks will develop. + <p> + <i>(Identical desc in UG and SC.)</i> + <p> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>attr_id</code> + <dd>IN: Attribute to get datatype of + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a datatype identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Annot-GetName">H5Aget_name</a> +<dt><strong>Signature:</strong> + <dd><em>size_t</em> <code>H5Aget_name</code>(<em>hid_t</em> <code>attr_id</code>, + <em>char *</em><code>buf</code>, + <em>size_t</em> <code>buf_size</code> + ) +<dt><strong>Purpose:</strong> + <dd>Gets a copy of the name for an attribute. +<dt><strong>Description:</strong> + <dd><code>H5Aget_name</code> retrieves the name of an attribute for an attribute identifier. + Up to 'buf_size' characters are stored in 'buf' followed by a '\0' string + terminator. If the name of the attribute is longer than 'buf_size'-1, + the string terminator is stored in the last position of the buffer to + properly terminate the string. + <p> + <i>(Identical desc in UG and SC.)</i> + <p> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>attr_id</code> + <dd>IN: Attribute to get name of + <dt><em>char *</em><code>buf</code> + <dd>IN: Buffer to store name in + <dt><em>size_t</em> <code>buf_size</code> + <dd>IN: The size of the buffer to store the string in + </dl> +<dt><strong>Returns:</strong> + <dd>Returns the length of the attribute's name, which may be + longer than <code>buf_size</code>, if successful. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Annot-NumAttrs">H5Anum_attrs</a> +<dt><strong>Signature:</strong> + <dd><em>int</em> <code>H5Anum_attrs</code>(<em>hid_t</em> <code>loc_id</code>) +<dt><strong>Purpose:</strong> + <dd>Determines the number of attributes attached to an object. +<dt><strong>Description:</strong> + <dd><code>H5Anum_attrs</code> returns the number of attributes attached to the dataset or + group, <code>loc_id</code>. + <p> + <i>(Identical desc in UG and SC.)</i> + <p> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: The object, a dataset or group, to be queried + </dl> +<dt><strong>Returns:</strong> + <dd>Returns the number of attributes if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Annot-Iterate">H5Aiterate</a> +<dt><strong>Signature:</strong> + <dd><em>int</em> <code>H5Aiterate</code>(<em>hid_t</em> <code>loc_id</code>, + <em>unsigned *</em> <code>attr_num</code>, + <em>H5A_operator_t</em> <code>op</code>, + <em>void *</em><code>op_data</code> + ) +<dt><strong>Purpose:</strong> + <dd>Calls a user's function for each attribute on an object. +<dt><strong>Description:</strong> + <dd>SC: H5Aiterate interates over the attributes of dataset or group + specified with 'loc_id'. For each attribute of the object, the + 'op_data' and some additional information (specified below) are passed + to the 'op' function. The iteration begins with the '*attr_number' + object in the group and the next attribute to be processed by the operator + is returned in '*attr_number'. + <p> + The operation receives the identifier for the group or dataset being iterated + over ('loc_id'), the name of the current attribute about the object + ('attr_name') and the pointer to the operator data passed in to H5Aiterate + ('op_data'). The return values from an operator are: + <ul> + <li>Zero causes the iterator to continue, returning zero when all + attributes have been processed. + <li>Positive causes the iterator to immediately return that positive + value, indicating short-circuit success. The iterator can be + restarted at the next attribute. + <li>Negative causes the iterator to immediately return that value, + indicating failure. The iterator can be restarted at the next + attribute. + </ul> + <dd>UG: <code>H5Aiterate</code> interates over the attributes of dataset or group + specified with loc_id. For each attribute of the object, + the operator_data and some additional information (specified below) + are passed to the operator function. The iteration begins with + the *attr_number object in the group and the next attribute to be + processed by the operator is returned in *attr_number. + <p> + The prototype for H5A_operator_t is: <br> + <code>typedef herr_t (*H5A_operator_t)(hid_t <em>loc_id</em>, + const char *<em>attr_name</em>, void *<em>operator_data</em>);</code> + <p> + The operation receives the identifier for the group or dataset being iterated over + (<em>loc_id</em>), the name of the current attribute about the object (<em>attr_name</em>) + and the pointer to the operator data passed in to H5Aiterate + (<em>operator_data</em>). The return values from an operator are: + <ul> + <li>Zero causes the iterator to continue, returning zero when all + attributes have been processed. + <li>Positive causes the iterator to immediately return that positive + value, indicating short-circuit success. The iterator can be + restarted at the next attribute. + <li>Negative causes the iterator to immediately return that value, + indicating failure. The iterator can be restarted at the next + attribute. + </ul> + <dd><b>attr_num, op, and op_data in SC are + attr_number, operator, and operator_data, respectively, in UG.</b> + <p> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: Object (dataset or group) to be iterated over + <dt><em>unsigned *</em> <code>attr_num</code> + <dd>IN/OUT: Starting (IN) & Ending (OUT) attribute number + <dt><em>H5A_operator_t</em> <code>op</code> + <dd>IN: User's function to pass each attribute to + <dt><em>void *</em><code>op_data</code> + <dd>IN/OUT: User's data to pass through to iterator operator function + </dl> +<dt><strong>Returns:</strong> + <dd>If successful, returns the return value of the last operator + if it was non-zero, or zero if all attributes were processed. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Annot-Delete">H5Adelete</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Adelete</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code> + ) +<dt><strong>Purpose:</strong> + <dd>Deletes an attribute from a location. +<dt><strong>Description:</strong> + <dd>SC: <code>H5Adelete</code> removes the named attribute from a dataset or group. + This function should not be used when attribute identifiers are open on 'loc_id' + as it may cause the internal indexes of the attributes to change and future + writes to the open attributes to produce incorrect results. + <p> + UG: <code>H5Adelete</code> removes the named attribute from a dataset or group. + This function should not be used when attribute identifiers are open on loc_id as + it may cause the internal indexes of the attributes to change and future + writes to the open attributes to produce incorrect results. + Returns non-negative on success, negative on failure. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: Object (dataset or group) to have attribute deleted from + <dt><em>const char *</em><code>name</code> + <dd>IN: Name of attribute to delete + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Annot-Close">H5Aclose</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Aclose</code>(<em>hid_t</em> <code>attr_id</code>) +<dt><strong>Purpose:</strong> + <dd>Close an attribute identifier. +<dt><strong>Description:</strong> + <dd>SC: <code>H5Aclose</code> releases an attribute from use. Further use of the + attribute identifier will result in undefined behavior. + <p> + UG: <code>H5Aclose</code> releases an attribute from use. + Further use of the attribute identifier will result in undefined behavior. + This function returns non-negative on success, negative on failure. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>attr_id</code> + <dd>IN: Attribute to release access to + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise 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: 6 July 1998 + +</body> +</html> diff --git a/doc/src/RM_H5D.html b/doc/src/RM_H5D.html new file mode 100644 index 0000000..a9f5189 --- /dev/null +++ b/doc/src/RM_H5D.html @@ -0,0 +1,374 @@ +<html> +<head><title> +HDF5/H5D Draft API Specification +</title></head> + +<body> + +<center> +<h1>H5D: Datasets Interface</h1> +</center> + +<h2>Dataset Object API Functions</h2> + +These functions create and manipulate dataset objects, +and set and retrieve their constant or persistent properties. + +<table border=0> +<tr><td valign=top> +<ul> + <li><a href="#Dataset-Create">H5Dcreate</a> + <li><a href="#Dataset-Open">H5Dopen</a> + <li><a href="#Dataset-GetSpace">H5Dget_space</a> +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#Dataset-GetType">H5Dget_type</a> + <li><a href="#Dataset-GetCreatePlist">H5Dget_create_plist</a> + <li><a href="#Dataset-Read">H5Dread</a> +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#Dataset-Write">H5Dwrite</a> + <li><a href="#Dataset-Extend">H5Dextend</a> + <li><a href="#Dataset-Close">H5Dclose</a> +</ul> +</td></tr> +</table> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataset-Create">H5Dcreate</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Dcreate</code>(<em>hid_t </em><code>loc_id</code>, + <em>const char *</em><code>name</code>, + <em>hid_t</em><code>type_id</code>, + <em>hid_t</em><code>space_id</code>, + <em>hid_t</em><code>create_plist_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Creates a dataset at the specified location. +<dt><strong>Description:</strong> + <dd><code>H5Dcreate</code> creates a data set with a name, + <code>name</code>, in the file or in the group specified by + the identifier <code>loc_id</code>. + The dataset has the datatype and dataspace identified by + <code>type_id</code> and <code>space_id</code>, respectively. + The specified datatype and dataspace are the datatype and + dataspace of the dataset as it will exist in the file, + which may be different than in application memory. + Dataset creation properties are specified by the argument + <code>create_plist_id</code>. + <p> + <code>create_plist_id</code> is a <code>H5P_DATASET_CREATE</code> + property list created with <code>H5Pcreate()</code> and + initialized with the various functions described above. + <code>H5Dcreate()</code> returns a dataset identifier for success + or negative for failure. The identifier should eventually be + closed by calling <code>H5Dclose()</code> to release resources + it uses. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>Identifier of the file or group to create the dataset within. + <dt><em>const char *</em> <code>name</code> + <dd>The name of the dataset to create. + <dt><em>hid_t</em> <code>type_id</code> + <dd>Identifier of the datatype to use when creating the dataset. + <dt><em>hid_t</em> <code>space_id</code> + <dd>Identifier of the dataspace to use when creating the dataset. + <dt><em>hid_t</em> <code>create_plist_id</code> + <dd>Identifier of the set creation property list. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a dataset identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataset-Open">H5Dopen</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Dopen</code>(<em>hid_t </em><code>loc_id</code>, + <em>const char *</em><code>name</code> + ) +<dt><strong>Purpose:</strong> + <dd>Opens an existing dataset. +<dt><strong>Description:</strong> + <dd><code>H5Dopen</code> opens an existing dataset for access in the file + or group specified in <code>loc_id</code>. <code>name</code> is + a dataset name and is used to identify the dataset in the file. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>Identifier of the file to access the dataset within. + <dt><em>const char *</em> <code>name</code> + <dd>The name of the dataset to access. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a dataset identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataset-GetSpace">H5Dget_space</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Dget_space</code>(<em>hid_t </em><code>dataset_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Returns an identifier for a copy of the dataspace for a dataset. +<dt><strong>Description:</strong> + <dd><code>H5Dget_space</code> returns an identifier for a copy of the + dataspace for a dataset. + The dataspace identifier should be released with the + <code>H5Sclose()</code> function. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>dataset_id</code> + <dd>Identifier of the dataset to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a dataspace identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataset-GetType">H5Dget_type</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Dget_type</code>(<em>hid_t </em><code>dataset_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Returns an identifier for a copy of the datatype for a dataset. +<dt><strong>Description:</strong> + <dd><code>H5Dget_type</code> returns an identifier for a copy of the + datatype for a dataset. + The datatype should be released with the <code>H5Tclose()</code> function. + <p> + If a dataset has a named datatype, then an identifier to the + opened datatype is returned. + Otherwise, the returned datatype is read-only. + If atomization of the datatype fails, then the datatype is closed. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>dataset_id</code> + <dd>Identifier of the dataset to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a datatype identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataset-GetCreatePlist">H5Dget_create_plist</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Dget_create_plist</code>(<em>hid_t </em><code>dataset_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Returns an identifier for a copy of the + dataset creation property list for a dataset. +<dt><strong>Description:</strong> + <dd><code>H5Dget_create_plist</code> returns an identifier for a + copy of the dataset creation property list for a dataset. + The creation property list identifier should be released with + the <code>H5Pclose()</code> function. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>dataset_id</code> + <dd>Identifier of the dataset to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a dataset creation property list identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataset-Read">H5Dread</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Dread</code>(<em>hid_t </em><code>dataset_id</code>, + <em>hid_t</em> <code>mem_type_id</code>, + <em>hid_t</em> <code>mem_space_id</code>, + <em>hid_t</em> <code>file_space_id</code>, + <em>hid_t</em> <code>xfer_plist_id</code>, + <em>void *</em> <code>buf</code> + ) +<dt><strong>Purpose:</strong> + <dd>Reads raw data from the specified dataset into <code>buf</code>, + converting from file datatype and dataspace to + memory datatype and dataspace. +<dt><strong>Description:</strong> + <dd><code>H5Dread</code> reads a (partial) dataset, specified by its + identifier <code>dataset_id</code>, from the file into the + application memory buffer <code>buf</code>. + Data transfer properties are defined by the argument + <code>xfer_plist_id</code>. + The memory datatype of the (partial) dataset is identified by + the identifier <code>mem_type_id</code>. + The part of the dataset to read is defined by + <code>mem_space_id</code> and <code>file_space_id</code>. + <p> + <code>file_space_id</code> can be the constant <code>H5S_ALL</code>, + which indicates that the entire file data space is to be referenced. + <p> + <code>mem_space_id</code> can be the constant <code>H5S_ALL</code>, + in which case the memory data space is the same as the file data space + defined when the dataset was created. + <p> + The number of elements in the memory data space must match + the number of elements in the file data space. + <p> + <code>xfer_plist_id</code> can be the constant <code>H5P_DEFAULT</code>, + in which case the default data transfer properties are used. + +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>dataset_id</code> + <dd>Identifier of the dataset read from. + <dt><em>hid_t</em> <code>mem_type_id</code> + <dd>Identifier of the memory datatype. + <dt><em>hid_t</em> <code>mem_space_id</code> + <dd>Identifier of the memory dataspace. + <dt><em>hid_t</em> <code>file_space_id</code> + <dd>Identifier of the dataset's dataspace in the file. + <dt><em>hid_t</em> <code>xfer_plist_id</code> + <dd>Identifier of a transfer property list for this I/O operation. + <dt><em>void *</em> <code>buf</code> + <dd>Buffer to store data read from the file. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataset-Write">H5Dwrite</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Dwrite</code>(<em>hid_t </em><code>dataset_id</code>, + <em>hid_t</em> <code>mem_type_id</code>, + <em>hid_t</em> <code>mem_space_id</code>, + <em>hid_t</em> <code>file_space_id</code>, + <em>hid_t</em> <code>xfer_plist_id</code>, + <em>const void *</em> <code>buf</code> + ) +<dt><strong>Purpose:</strong> + <dd>Writes raw data from an application buffer <code>buf</code> to + the specified dataset, converting from + memory datatype and dataspace to file datatype and dataspace. +<dt><strong>Description:</strong> + <dd><code>H5Dwrite</code> writes a (partial) dataset, specified by its + identifier <code>dataset_id</code>, from the + application memory buffer <code>buf</code> into the file. + Data transfer properties are defined by the argument + <code>xfer_plist_id</code>. + The memory datatype of the (partial) dataset is identified by + the identifier <code>mem_type_id</code>. + The part of the dataset to write is defined by + <code>mem_space_id</code> and <code>file_space_id</code>. + <p> + <code>file_space_id</code> can be the constant <code>H5S_ALL</code>. + which indicates that the entire file data space is to be referenced. + <p> + <code>mem_space_id</code> can be the constant <code>H5S_ALL</code>, + in which case the memory data space is the same as the file data space + defined when the dataset was created. + <p> + The number of elements in the memory data space must match + the number of elements in the file data space. + <p> + <code>xfer_plist_id</code> can be the constant <code>H5P_DEFAULT</code>. + in which case the default data transfer properties are used. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>dataset_id</code> + <dd>Identifier of the dataset read from. + <dt><em>hid_t</em> <code>mem_type_id</code> + <dd>Identifier of the memory datatype. + <dt><em>hid_t</em> <code>mem_space_id</code> + <dd>Identifier of the memory dataspace. + <dt><em>hid_t</em> <code>file_space_id</code> + <dd>Identifier of the dataset's dataspace in the file. + <dt><em>hid_t</em> <code>xfer_plist_id</code> + <dd>Identifier of a transfer property list for this I/O operation. + <dt><em>const void *</em> <code>buf</code> + <dd>Buffer with data to be written to the file. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataset-Extend">H5Dextend</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Dextend</code>(<em>hid_t </em><code>dataset_id</code>, + <em>const hsize_t *</em> <code>size</code> + ) +<dt><strong>Purpose:</strong> + <dd>Extends a dataset with unlimited dimension. +<dt><strong>Description:</strong> + <dd><code>H5Dextend</code> verifies that the dataset is at least of size + <code>size</code>. + The dimensionality of <code>size</code> is the same as that of + the dataspace of the dataset being changed. + This function cannot be applied to a dataset with fixed dimensions. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>dataset_id</code> + <dd>Identifier of the dataset. + <dt><em>const hsize_t *</em> <code>size</code> + <dd>Array containing the new magnitude of each dimension. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataset-Close">H5Dclose</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Dclose</code>(<em>hid_t </em><code>dataset_id</code> + ) +<dt><strong>Purpose:</strong> + <dd> +<dt><strong>Description:</strong> + <dd><code>H5Dclose</code> ends access to a dataset specified by + <code>dataset_id</code> and releases resources used by it. + Further use of the dataset identifier is illegal in calls to + the dataset API. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>dataset_id</code> + <dd>Identifier of the dataset to finish access to. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise 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> diff --git a/doc/src/RM_H5E.html b/doc/src/RM_H5E.html new file mode 100644 index 0000000..0065e90 --- /dev/null +++ b/doc/src/RM_H5E.html @@ -0,0 +1,377 @@ +<html> +<head><title> +HDF5/H5E Draft API Specification +</title></head> + +<body> + +<center> +<h1>H5E: Error Interface</h1> +</center> + +<h2>Error API Functions</h2> + +These functions provide error handling capabilities in the HDF5 environment. +<p> +Provides error handling in the form of a stack. The FUNC_ENTER() macro +clears the error stack whenever an API function is entered. When an error +is detected, an entry is pushed onto the stack. As the functions unwind +additional entries are pushed onto the stack. The API function will return +some indication that an error occurred and the application can print the +error stack. +<p> +Certain API functions in the H5E package (such as H5Eprint()) +do not clear the error stack. Otherwise, any function which +doesn't have an underscore immediately after the package name +will clear the error stack. For instance, H5Fopen() clears +the error stack while H5F_open() does not. +<p> +An error stack has a fixed maximum size. If this size is +exceeded then the stack will be truncated and only the +inner-most functions will have entries on the stack. This is +expected to be a rare condition. +<p> +Each thread has its own error stack, but since +multi-threading has not been added to the library yet, this +package maintains a single error stack. The error stack is +statically allocated to reduce the complexity of handling +errors within the H5E package. + +<table border=0> +<tr><td valign=top> +<ul> + <li><a href="#Error-SetAuto">H5Eset_auto</a> + <li><a href="#Error-GetAuto">H5Eget_auto</a> + <li><a href="#Error-Clear">H5Eclear</a> +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#Error-Print">H5Eprint</a> + <li><a href="#Error-Walk">H5Ewalk</a> + <li><a href="#Error-WalkCB">H5Ewalk_cb</a> +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#Error-GetMajor">H5Eget_major</a> + <li><a href="#Error-GetMinor">H5Eget_minor</a> +</ul> +</td></tr> +</table> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Error-SetAuto">H5Eset_auto</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Eset_auto</code>(<em>H5E_auto_t</em> <code>func</code>, + <em>void *</em><code>client_data</code> + ) +<dt><strong>Purpose:</strong> + <dd>Turns automatic error printing on or off. +<dt><strong>Description:</strong> + <dd>SC: H5Eset_auto turns on or off automatic printing of errors. + When turned on (non-null <code>func</code> pointer), + any API function which returns an error indication will + first call <code>func</code>, passing it <code>client_data</code> + as an argument. + <p> + The default values before this function is called are + H5Eprint() with client data being the standard error stream, + stderr. + <p> + Automatic stack traversal is always in the H5E_WALK_DOWNWARD + direction. + <p> + UG: If <em>func</em> is not a null pointer, then the function to + which it points will be called automatically when an API + function is about to return an indication of failure. The + function is called with a single argument, the + <em>client_data</em> pointer. When the library is first + initialized the auto printing function is set to + <code>H5Eprint()</code> (cast appropriately) and + <em>client_data</em> is the standard error stream pointer, + <code>stderr</code>. + <p> + <b>UG signature line reads</b> + <br><code>herr_t H5Eset_auto (herr_t(*<em>func</em>)(void*), + void *<em>client_data</em>)</code>. + <br><b>The UG signature line for H5Eget_auto reads similarly.</b> + <p> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5E_auto_t</em> <code>func</code> + <dd>Function to be called upon an error condition. + <dt><em>void *</em><code>client_data</code> + <dd>Data passed to the error function. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Error-GetAuto">H5Eget_auto</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Eget_auto</code>(<em>H5E_auto_t *</em> <code>func</code>, + <em>void **</em><code>client_data</code> + ) +<dt><strong>Purpose:</strong> + <dd>Returns the current settings for the automatic error stack + traversal function and its data. +<dt><strong>Description:</strong> + <dd>SC: H5Eget_auto returns the current settings for the automatic error stack + traversal function and its data. Either (or both) arguments + may be null in which case the value is not returned. + <p> + UG: This function returns the current automatic error traversal + settings through the <em>func</em> and <em>client_data</em> + arguments. Either (or both) arguments may be null pointers in + which case the corresponding information is not returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5E_auto_t *</em> <code>func</code> + <dd>Current setting for the function to be called upon an + error condition. + <dt><em>void **</em><code>client_data</code> + <dd>Current setting for the data passed to the error function. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Error-Clear">H5Eclear</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Eclear</code>(<code>void</code>) +<dt><strong>Purpose:</strong> + <dd>Clears the error stack for the current thread. +<dt><strong>Description:</strong> + <dd>SC: H5Eclear clears the error stack for the current thread. + <p> + This function can fail if there are problems initializing the library. + <p> + UG: The error stack can be explicitly cleared by calling this + function. The stack is also cleared whenever an API function + is called, with certain exceptions (for instance, + <code>H5Eprint()</code>). +<dt><strong>Parameters:</strong> + <dl> + <dt><em>paramtype</em> <code>param</code> + <dd>xxx + <dt><i>Should this say "None"?</i> + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Error-Print">H5Eprint</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Eprint</code>(<em>FILE *</em> <code>stream</code>) +<dt><strong>Purpose:</strong> + <dd>Prints the error stack in a default manner. +<dt><strong>Description:</strong> + <dd>SC: H5Eprint prints the error stack in some default way. This is just a + convenience function for H5Ewalk() with a function that + prints error messages. Users are encouraged to write there + own more specific error handlers. + <p> + UG: The error stack is printed on the specified stream. Even if + the error stack is empty a one-line message will be printed: + <code>HDF5-DIAG: Error detected in thread 0.</code> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>FILE *</em> <code>stream</code> + <dd>xxx + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Error-Walk">H5Ewalk</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Ewalk</code>(<em>H5E_direction_t</em> <code>direction</code>, + <em>H5E_walk_t</em> <code>func</code>, + <em>void *</em> <code>client_data</code> + ) +<dt><strong>Purpose:</strong> + <dd>Walks the error stack for the current thread, calling a specified + function. +<dt><strong>Description:</strong> + <dd>SC: <code>H5Ewalk</code> walks the error stack for the current thread + and calls the specified function for each error along the way. + <p> + <code>direction</code> determines whether the stack is walked + from the inside out or the outside in. + A value of <code>H5E_WALK_UPWARD</code> means begin with the + most specific error and end at the API; + a value of <code>H5E_WALK_DOWNWARD</code> means to start at the + API and end at the inner-most function where the error was first + detected. + <p> + <code>func</code> will be called for each error in the error stack. + It's arguments will include an index number (beginning at zero + regardless of stack traversal direction), an error stack entry, + and the <code>client_data</code> pointer passed to + <code>H5E_print</code>. + <p> + <code>H5Ewalk</code> can fail if there are problems initializing the library. + <p> + UG: The error stack is traversed and <em>func</em> is called for + each member of the stack. Its arguments are an integer + sequence number beginning at zero (regardless of + <em>direction</em>), a pointer to an error description record, + and the <em>client_data</em> pointer. If <em>direction</em> + is <code>H5E_WALK_UPWARD</code> then traversal begins at the + inner-most function that detected the error and concludes with + the API function. The opposite order is + <code>H5E_WALK_DOWNWARD</code>. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5E_direction_t</em> <code>direction</code> + <dd>Direction in which the error stack is to be walked. + <dt><em>H5E_walk_t</em> <code>func</code> + <dd>Function to be called for each error encountered. + <dt><em>void *</em> <code>client_data</code> + <dd>Data to be passed with <code>func</code>. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Error-WalkCB">H5Ewalk_cb</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Ewalk_cb</code>(<em>int</em> <code>n</code>, + <em>H5E_error_t *</em><code>err_desc</code>, + <em>void</em> <code>*client_data</code> + ) +<dt><strong>Purpose:</strong> + <dd>Default error stack traversal callback function + that prints error messages to the specified output stream. +<dt><strong>Description:</strong> + <dd><code>H5Ewalk_cb</code> is a default error stack traversal callback function + that prints error messages to the specified output stream. + It is not meant to be called directly but rather as an + argument to the H5Ewalk() function. This function is called + also by H5Eprint(). Application writers are encouraged to + use this function as a model for their own error stack + walking functions. + <p> + <code>n</code> is a counter for how many times this function has been + called for this particular traversal of the stack. It always + begins at zero for the first error on the stack (either the + top or bottom error, or even both, depending on the traversal + direction and the size of the stack). + <p> + ERR_DESC is an error description. It contains all the + information about a particular error. + <p> + CLIENT_DATA is the same pointer that was passed as the + CLIENT_DATA argument of H5Ewalk(). It is expected to be a + file pointer (or stderr if null). +<dt><strong>Parameters:</strong> + <dl> + <dt><em>int</em> <code>n</code> + <dd>Number of times this function has been called + for this traversal of the stack. + <dt><em>H5E_error_t *</em><code>err_desc</code> + <dd>Error description. + <dt><em>void</em> <code>*client_data</code> + <dd>A file pointer, or <code>stderr</code> if null. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Error-GetMajor">H5Eget_major</a> +<dt><strong>Signature:</strong> + <dd><em>const char *</em> <code>H5Eget_major</code>(<em>H5E_major_t</em> <code>n</code>) +<dt><strong>Purpose:</strong> + <dd>Returns a character string describing a major error. +<dt><strong>Description:</strong> + <dd>Given a major error number, H5Eget_major returns a constant character string + that describes the error. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5E_major_t</em> <code>n</code> + <dd>Major error number. + </dl> +<dt><strong>Returns:</strong> + <dd> Returns a pointer to a character string if successful. + Otherwise returns a pointer to "Invalid major error number". + <br> + <i> ...or how about... </i> + <br> + Returns a pointer to a character string describing the error if successful. + Otherwise returns a pointer to "Invalid major error number". + <br> + <i> ...or ... </i> + <br> + Returns a character string describing the error if successful. + Otherwise returns "Invalid major error number." +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Error-GetMinor">H5Eget_minor</a> +<dt><strong>Signature:</strong> + <dd><em>const char *</em> <code>H5Eget_minor</code>(<em>H5E_minor_t</em> <code>n</code>) +<dt><strong>Purpose:</strong> + <dd>Returns a character string describing a minor error. +<dt><strong>Description:</strong> + <dd>Given a minor error number, H5Eget_minor returns a constant character string + that describes the error. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5E_minor_t</em> <code>n</code> + <dd>Minor error number. + </dl> +<dt><strong>Returns:</strong> + <dd> Returns a pointer to a character string if successful. + Otherwise returns a pointer to "Invalid minor error number". + <br> + <i> ...or how about... </i> + <br> + Returns a pointer to a character string describing the error if successful. + Otherwise returns a pointer to "Invalid minor error number". + <br> + <i> ...or ... </i> + <br> + Returns a character string describing the error if successful. + Otherwise returns "Invalid minor error number." +</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: 6 July 1998 + +</body> +</html> diff --git a/doc/src/RM_H5F.html b/doc/src/RM_H5F.html new file mode 100644 index 0000000..912df51 --- /dev/null +++ b/doc/src/RM_H5F.html @@ -0,0 +1,192 @@ +<html> +<head><title> +HDF5/H5F Draft API Specification +</title></head> + +<body> + +<center> +<h1>H5F: File Interface</h1> +</center> + +<h2>File API Functions</h2> + +These functions are designed to provide file-level access to HDF5 files. +Further manipulation of objects inside a file is performed through one of APIs +documented below. + +<table border=0> +<tr><td valign=top> +<ul> + <li><a href="#File-Open">H5Fopen</a> + <li><a href="#File-Create">H5Fcreate</a> +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#File-IsHDF5">H5Fis_hdf5</a> + <li><a href="#File-GetCreateTemplate">H5Fget_create_template</a> +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#File-Close">H5Fclose</a> +</ul> +</td></tr> +</table> + +<hr> + +<dl> +<dt><strong>Name:</strong> <a name="File-Open">H5Fopen</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Fopen</code>(<em>const char *</em><code>name</code>, + <em>uintn</em> <code>flags</code>, + <em>hid_t</em> <code>access_template</code> + ) +<dt><strong>Description:</strong> + <dd>This is the primary function for opening existing HDF5 files. + The <code>flags</code> parameter determines the file access mode. + There is no read flag, all open files are implicitily opened for + read access. + All flags may be combined with the '|' (boolean OR operator) to + change the behavior of the file open call. + The <code>access_template</code> parameter is a template containing + additional information required for specific methods of access, + parallel I/O for example. The paramters for access templates are + described in the H5P API documentation. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>const char *</em><code>name</code> + <dd>Name of the file to access. + <dt><em>uintn</em> <code>flags</code> + <dd>File access flags: + <ul><dl> + <dt>H5F_ACC_RDWR + <dd>Allow read and write access to file. + </dl></ul> + <dt><em>hid_t</em><code>access_template</code> + <dd>Template indicating the file access properties. + If parallel file access is desired, this is a collective + call according to the communicator stored in the + access_template. Use 0 for default access template. + </dl> +<dt><strong>Returns:</strong> + <dd>An ID (of type <em>hid_t</em>) for the file upon success, + otherwise negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="File-Create">H5Fcreate</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Fcreate</code>(<em>const char *</em><code>name</code>, + <em>uintn</em> <code>flags</code>, + <em>hid_t</em> <code>create_template</code>, + <em>hid_t</em> <code>access_template</code> + ) +<dt><strong>Description:</strong> + <dd>This is the primary function for opening and creating HDF5 files. + The <code>flags</code> parameter determines whether an existing + file will be overwritten or not. All newly created files are opened + for both reading and writing. + All flags may be combined with the '|' (boolean OR operator) to + change the behavior of the file open call. + The <code>create_template</code> and <code>access_template</code> + parameters are templates containing additional information required + for specific methods of access or particular aspects of the file + to set when creating a file. + The parameters for creation and access templates are + described in the H5P API documentation. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>const char *</em><code>name</code> + <dd>Name of the file to access. + <dt><em>uintn</em> <code>flags</code> + <dd>File access flags: + <ul><dl> + <dt>H5F_ACC_TRUNC + <dd>Truncate file, if it already exists. The file will + be truncated, erasing all data previously stored in + the file. + </dl></ul> + <dt><em>hid_t</em><code>create_template</code> + <dd>File creation template ID, used when modifying default file meta-data + <dt><em>hid_t</em><code>access_template</code> + <dd>Template indicating the file access properties. + If parallel file access is desired, this is a collective + call according to the communicator stored in the + access_template. Use 0 for default access template. + </dl> +<dt><strong>Returns:</strong> + <dd>An ID (of type <em>hid_t</em>) for the file upon success, + otherwise negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="File-IsHDF5">H5Fis_hdf5</a> +<dt><strong>Signature:</strong> + <dd><em>hbool_t </em><code>H5Fis_hdf5</code>(<em>const char *</em><code>name</code> + ) +<dt><strong>Description:</strong> + <dd>This function determines whether a file is in the HDF5 format. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>const char *</em><code>name</code> + <dd>File name to check format. + </dl> +<dt><strong>Returns:</strong> + <dd>TRUE/FALSE/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="File-GetCreateTemplate">H5Fget_create_template</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Fget_create_template</code>(<em>hid_t</em> <code>file_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function returns an template ID with a copy of the parameters + used to create this file. Useful for duplicating the parameters + when creating another file. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>file_id</code> + <dd>File ID to get creation template of + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="File-Close">H5Fclose</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Fclose</code>(<em>hid_t</em> <code>file_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function terminates access to an HDF5 file. If this is the + last file ID open for a file and if access IDs are still in use, + this function will fail. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>file_id</code> + <dd>File ID to terminate access to. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> + +<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: 29 June 1998 + +</body> +</html> diff --git a/doc/src/RM_H5Front.html b/doc/src/RM_H5Front.html new file mode 100644 index 0000000..374a1ad --- /dev/null +++ b/doc/src/RM_H5Front.html @@ -0,0 +1,258 @@ +<html> +<head><title> +HDF5 Draft API Specification +</title></head> +<body> + +<center> +<h1>HDF5: API Specification<br>Reference Manual</h1> +</center> + +The HDF5 libraries provide several interfaces, each of which provides the +tools required to meet specific aspects of the HDF5 data-handling requirements. + +<ul> + +<!-- +<li><a href="#Library">Library</a> - H5<name> - API for global library HDF information/modification. +<ol type=A> + <li><a href="#Library-DontAtExit">H5dont_atexit</a> + <li><a href="#Library-Close">H5close</a> + <li><a href="#Library-Version">H5version</a> +</ol> +--> + +<li><a href="RM_H5F.html">File Interface</a> -- The <strong>H5F</strong> API for accessing HDF files. +<!-- +<ul type=A> + <li><font size=-2> + ( <a href="RM_H5F.html#File-Open">H5Fopen</a> + <a href="RM_H5F.html#File-Create">H5Fcreate</a> + <a href="RM_H5F.html#File-IsHDF5">H5Fis_hdf5</a> + <a href="RM_H5F.html#File-GetCreateTemplate">H5Fget_create_template</a> + <a href="RM_H5F.html#File-Close">H5Fclose</a> ) + </font> +</ul> +--> + +<li><a href="RM_H5P.html">Property List Interface</a> -- The <strong>H5P</strong> API for manipulating object templates. +<!-- +<ul type=A> + <li><font size=-2> + ( <a href="RM_H5P.html#Template-Create">H5Pcreate</a> + <a href="RM_H5P.html#Template-GetClass">H5Pget_class</a> + <a href="RM_H5P.html#Template-Copy">H5Pcopy</a> + <a href="RM_H5P.html#Template-Close">H5Pclose</a> + <a href="RM_H5P.html#Template-GetVersion">H5Pget_version</a> + <a href="RM_H5P.html#Template-SetUserblock">H5Pset_userblock</a> + <a href="RM_H5P.html#Template-GetUserblock">H5Pget_userblock</a> + <a href="RM_H5P.html#Template-SetSizes">H5Pset_sizes</a> + <a href="RM_H5P.html#Template-GetSizes">H5Pget_sizes</a> + <a href="RM_H5P.html#Template-SetMPI">H5Pset_mpi</a> + <a href="RM_H5P.html#Template-GetMPI">H5Pget_mpi</a> + <a href="RM_H5P.html#Template-SetXfer">H5Pset_xfer</a> + <a href="RM_H5P.html#Template-GetXfer">H5Pget_xfer</a> + <a href="RM_H5P.html#Template-SetSymK">H5Pset_sym_k</a> + <a href="RM_H5P.html#Template-GetSymK">H5Pget_sym_k</a> + <a href="RM_H5P.html#Template-SetIstoreK">H5Pset_istore_k</a> + <a href="RM_H5P.html#Template-GetIstoreK">H5Pget_istore_k</a> + <a href="RM_H5P.html#Template-SetLayout">H5Pset_layout</a> + <a href="RM_H5P.html#Template-GetLayout">H5Pget_layout</a> + <a href="RM_H5P.html#Template-SetChunk">H5Pset_chunk</a> + <a href="RM_H5P.html#Template-GetChunk">H5Pget_chunk</a> ) + </font> +</ul> +--> + +<!-- +<li><a href="#Error">Error</a> - H5E<name> - API for error reporting +<ol type=A> + <li><a href="#Error-SetPush">H5Eset_push</a> +</ol> +--> + +<!-- +<li><a href="#Relationships">Relationships</a> - H5R<name> - API for logically linking objects together (ie. attributes). +<ol type=A> + <li><a href="#Relationships-GetNumRelations">H5Rget_num_relations</a> + <li><a href="#Relationships-GetMemberOfOIDs">H5Rget_memberof_oids</a> + <li><a href="#Relationships-GetAttachedOIDs">H5Rget_attached_oids</a> + <li><a href="#Relationships-Attach">H5Rattach_oid</a> +</ol> +--> + +<li><a href="RM_H5D.html">Dataset Interface</a> -- The <strong>H5D</strong> API for manipulating scientific datasets. +<!-- +<table border=0 width=100> + <tr><td> </td><td width=200> + <a href="RM_H5D.html#Dataset-Create"><font size=-2>H5Dcreate</font></a> + </td><td> </td><td width=200> + <a href="RM_H5D.html#Dataset-Open"><font size=-2>H5Dopen</font></a> + </td><td> </td><td width=200> + <a href="RM_H5D.html#Dataset-GetSpace"><font size=-2>H5Dget_space</font></a> + </td><td> </td><td width=200> + <a href="RM_H5D.html#Dataset-GetType"><font size=-2>H5Dget_type</font></a> + </td></tr><tr><td></td><td> + <a href="RM_H5D.html#Dataset-GetCreateParms"><font size=-2>H5Dget_create_parms</font></a> + </td><td> </td><td> + <a href="RM_H5D.html#Dataset-Read"><font size=-2>H5Dread</font></a> + </td><td> </td><td> + <a href="RM_H5D.html#Dataset-Write"><font size=-2>H5Dwrite</font></a> + </td><td> </td><td> + <a href="RM_H5D.html#Dataset-Extend"><font size=-2>H5Dextend</font></a> + </td></tr><tr><td></td><td> + <a href="RM_H5D.html#Dataset-Close"><font size=-2>H5Dclose</font></a> +</table> +--> + +<li><a href="RM_H5T.html">Datatype Interface</a> -- The <strong>H5T</strong> API for defining dataset element information. +<!-- +<table border=0> +<tr><td valign=top> +<font size=-2> +<ul> + <li><a href="RM_H5T.html#Datatype-Create">H5Tcreate</a> + <li><a href="RM_H5T.html#Datatype-Copy">H5Tcopy</a> + <li><a href="RM_H5T.html#Datatype-Equal">H5Tequal</a> + <li><a href="RM_H5T.html#Datatype-Lock">H5Tlock</a> + <li><a href="RM_H5T.html#Datatype-GetClass">H5Tget_class</a> + <li><a href="RM_H5T.html#Datatype-GetSize">H5Tget_size</a> + <li><a href="RM_H5T.html#Datatype-SetSize">H5Tset_size</a> + <li><a href="RM_H5T.html#Datatype-GetOrder">H5Tget_order</a> + <li><a href="RM_H5T.html#Datatype-SetOrder">H5Tset_order</a> + <li><a href="RM_H5T.html#Datatype-GetPrecision">H5Tget_precision</a> +</ul> +</font> +</td><td> </td><td valign=top> +<font size=-2> +<ul> + <li><a href="RM_H5T.html#Datatype-SetPrecision">H5Tset_precision</a> + <li><a href="RM_H5T.html#Datatype-GetOffset">H5Tget_offset</a> + <li><a href="RM_H5T.html#Datatype-SetOffset">H5Tset_offset</a> + <li><a href="RM_H5T.html#Datatype-GetPad">H5Tget_pad</a> + <li><a href="RM_H5T.html#Datatype-SetPad">H5Tset_pad</a> + <li><a href="RM_H5T.html#Datatype-GetSign">H5Tget_sign</a> + <li><a href="RM_H5T.html#Datatype-SetSign">H5Tset_sign</a> + <li><a href="RM_H5T.html#Datatype-GetFields">H5Tget_fields</a> + <li><a href="RM_H5T.html#Datatype-SetFields">H5Tset_fields</a> + <li><a href="RM_H5T.html#Datatype-GetEbias">H5Tget_ebias</a> +</ul> +</font> +</td><td> </td><td valign=top> +<font size=-2> +<ul> + <li><a href="RM_H5T.html#Datatype-SetEbias">H5Tset_ebias</a> + <li><a href="RM_H5T.html#Datatype-GetNorm">H5Tget_norm</a> + <li><a href="RM_H5T.html#Datatype-SetNorm">H5Tset_norm</a> + <li><a href="RM_H5T.html#Datatype-GetInpad">H5Tget_inpad</a> + <li><a href="RM_H5T.html#Datatype-SetInpad">H5Tset_inpad</a> + <li><a href="RM_H5T.html#Datatype-GetCset">H5Tget_cset</a> + <li><a href="RM_H5T.html#Datatype-SetCset">H5Tset_cset</a> + <li><a href="RM_H5T.html#Datatype-GetStrpad">H5Tget_strpad</a> + <li><a href="RM_H5T.html#Datatype-SetStrpad">H5Tset_strpad</a> + <li><a href="RM_H5T.html#Datatype-GetNmembers">H5Tget_nmembers</a> +</ul> +</font> +</td><td> </td><td valign=top> +<font size=-2> +<ul> + <li><a href="RM_H5T.html#Datatype-GetMemberName">H5Tget_member_name</a> + <li><a href="RM_H5T.html#Datatype-GetMemberOffset">H5Tget_member_offset</a> + <li><a href="RM_H5T.html#Datatype-GetMemberDims">H5Tget_member_dims</a> + <li><a href="RM_H5T.html#Datatype-GetMemberType">H5Tget_member_type</a> + <li><a href="RM_H5T.html#Datatype-Insert">H5Tinsert</a> + <li><a href="RM_H5T.html#Datatype-Pack">H5Tpack</a> + <li><a href="RM_H5T.html#Datatype-RegisterHard">H5Tregister_hard</a> + <li><a href="RM_H5T.html#Datatype-RegisterSoft">H5Tregister_soft</a> + <li><a href="RM_H5T.html#Datatype-Unregister">H5Tunregister</a> + <li><a href="RM_H5T.html#Datatype-Close">H5Tclose</a> +</ul> +</td></tr> +</table> +--> + +<li><a href="RM_H5S.html">Dataspace Interface</a> -- The <strong>H5S</strong> API for defining dataset dataspace. +<!-- +<table border=0> +<tr></td><td> </td><td valign=top> +<font size=-2> + <a href="RM_H5S.html#Dataspace-CreateSimple">H5Screate_simple</a> <br> + <a href="RM_H5S.html#Dataspace-Copy">H5Scopy</a> <br> + <a href="RM_H5S.html#Dataspace-GetNpoints">H5Sget_npoints</a> <br> +</ul> +</font> +</td><td> </td><td valign=top> +<font size=-2> + <a href="RM_H5S.html#Dataspace-GetNdims">H5Sget_ndims</a> <br> + <a href="RM_H5S.html#Dataspace-GetDims">H5Sget_dims</a> <br> + <a href="RM_H5S.html#Dataspace-IsSimple">H5Sis_simple</a> <br> +</ul> +</font> +</td><td> </td><td valign=top> +<font size=-2> + <a href="RM_H5S.html#Dataspace-SetSpace">H5Sset_space</a> <br> + <a href="RM_H5S.html#Dataspace-SetHyperslab">H5Sset_hyperslab</a> <br> + <a href="RM_H5S.html#Dataspace-GetHyperslab">H5Sget_hyperslab</a> <br> +</ul> +</font> +</td><td> </td><td valign=top> +<font size=-2> + <a href="RM_H5S.html#Dataspace-Close">H5Sclose</a> <br> +</ul> +</td></tr> +</table> +--> + +<li><a href="RM_H5G.html">Group Interface</a> -- The <strong>H5G</strong> API for creating physical groups of objects on disk. +<!-- +<ol type=A> + <li><a href="RM_H5G.html#Group-Create">H5Gcreate</a> + <li><a href="RM_H5G.html#Group-Open">H5Gopen</a> + <li><a href="RM_H5G.html#Group-Set">H5Gset</a> + <li><a href="RM_H5G.html#Group-Push">H5Gpush</a> + <li><a href="RM_H5G.html#Group-Pop">H5Gpop</a> + <li><a href="RM_H5G.html#Group-Close">H5Gclose</a> +sub-commented-------- + <li><a href="RM_H5G.html#Group-GetNumContents">get_num_contents</a> + <li><a href="RM_H5G.html#Group-GetContentInfo">get_content_info</a> + <li><a href="RM_H5G.html#Group-GetContentInfoMult">get_content_info_mult</a> + <li><a href="RM_H5G.html#Group-GetOIDByName">get_oid_by_name</a> + <li><a href="RM_H5G.html#Group-GetOIDByIndex">get_oid_by_index</a> + <li><a href="RM_H5G.html#Group-GetNameByOID">get_name_by_oid</a> + <li><a href="RM_H5G.html#Group-GetNameByIndex">get_name_by_index</a> + <li><a href="RM_H5G.html#Group-InsertItem">insert_item</a> + <li><a href="RM_H5G.html#Group-InsertItemMult">insert_item_mult</a> + <li><a href="RM_H5G.html#Group-RemoveItem">remove_item</a> + <li><a href="RM_H5G.html#Group-RemoveItemMult">remove_item_mult</a> +--------sub-commented +</ol> +--> + +<li><a href="RM_H5E.html">Error Interface</a> -- The <strong>H5E</strong> API for error handling. +<li><a href="RM_H5Z.html">Compression Interface</a> -- The <strong>H5Z</strong> API for compression. +<li><a href="RM_H5A.html">Annotation Interface</a> -- The <strong>H5A</strong> API for annotations. + +<li><a href="Glossary.html">Glossary</a> -- A glossary of data-types used in the APIs. +<!-- +<ol type=A> + <li><a href="Glossary.html#Glossary-Basic">Basic Types</a> + <li><a href="Glossary.html#Glossary-Complex">Complex Types</a> + <li><a href="Glossary.html#Glossary-DiskIO">Disk I/O Types</a> +</ol> +--> + + +</ul> + +<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: 29 June 1998 + +</body> +</html> diff --git a/doc/src/RM_H5G.html b/doc/src/RM_H5G.html new file mode 100644 index 0000000..b4baa99 --- /dev/null +++ b/doc/src/RM_H5G.html @@ -0,0 +1,882 @@ +<html> +<head><title> +HDF5/H5G Draft API Specification +</title></head> + +<body> + +<center> +<h1>H5G: Group Interface</h1> +</center> + +<h2>Group Object API Functions</h2> + +The Group interface functions create and manipulate physical groups +of objects on disk. + +<table border=0> +<tr><td valign=top> +<ul> + <li><a href="#Group-Create">H5Gcreate</a> + <li><a href="#Group-Open">H5Gopen</a> + <li><a href="#Group-Set">H5Gset</a> + <li><a href="#Group-Close">H5Gclose</a> +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#Group-Push">H5Gpush</a> + <li><a href="#Group-Pop">H5Gpop</a> + <li><a href="#Group-Link">H5Glink</a> + <li><a href="#Group-Unlink">H5Gunlink</a> (NYI) +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#Group-Iterate">H5Giterate</a> + <li><a href="#Group-Move">H5Gmove</a> (NYI) + <li><a href="#Group-Stat">H5Gstat</a> + <li><a href="#Group-GetLinkval">H5Gget_linkval</a> +</ul> +</td></tr><tr><td colspan=5 align=right> +<font size=-2>(NYI = Not yet implemented)</font> +</td></tr> +</table> + +<p> +A group associates names with objects and provides a mechanism +for mapping a name to an object. Since all objects appear in at +least one group (with the possible exception of the root object) +and since objects can have names in more than one group, the set +of all objects in an HDF5 file is a directed graph. The internal +nodes (nodes with out-degree greater than zero) must be groups +while the leaf nodes (nodes with out-degree zero) are either empty +groups or objects of some other type. Exactly one object in every +non-empty file is the root object. The root object always has a +positive in-degree because it is pointed to by the file boot block. + +<p> +Every file identifier returned by <code>H5Fcreate</code> or +<code>H5Fopen</code> maintains an independent current working group +stack, the top item of which is the current working group. The +stack can be manipulated with <code>H5Gset</code>, <code>H5Gpush</code>, +and <code>H5Gpop</code>. The root object is the current working group +if the stack is empty. + +<p> +An object name consists of one or more components separated from +one another by slashes. An absolute name begins with a slash and the +object is located by looking for the first component in the root +object, then looking for the second component in the first object, etc., +until the entire name is traversed. A relative name does not begin +with a slash and the traversal begins with the current working group. + +<p> +The library does not maintain the full absolute name of its current +working group because (1) cycles in the graph can make the name length +unbounded and (2) a group does not necessarily have a unique name. A +more Unix-like hierarchical naming scheme can be implemented on top of +the directed graph scheme by creating a ".." entry in each group that +points to its single predecessor; a <code>getcwd</code> function would +then be trivial. + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Create">H5Gcreate</a> + <dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Gcreate</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code>, + <em>size_t</em> <code>size_hint</code> + ) + <dt><strong>Purpose:</strong> + <dd>Creates a new empty group and gives it a name. + <dt><strong>Description:</strong> + <dd><code>H5Gcreate</code> creates a new group with the specified + name at the specified location, <code>loc_id</code>. + The location is identified by a file or group identifier. + The name, <code>name</code>, must not already be taken by some + other object and all parent groups must already exist. + <p> + <code>size_hint</code> is a hint for the number of bytes to + reserve to store the names which will be eventually added to + the new group. Passing a value of zero for <code>size_hint</code> + is usually adequate since the library is able to dynamically + resize the name heap, but a correct hint may result in better + performance. + If a non-positive value is supplied for size_hint, + then a default size is chosen. + <p> + The return value is a group identifier for the open group. + This group identifier should be closed by calling + <code>H5Gclose()</code> when it is no longer needed. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>The file or group identifier. + <dt><em>const char *</em><code>name</code> + <dd>The absolute or relative name of the new group. + <dt><em>size_t</em> <code>size_hint</code> + <dd>An optional parameter indicating the number of bytes + to reserve for the names that will appear in the group. + A conservative estimate could result in multiple + system-level I/O requests to read the group name heap; + a liberal estimate could result in a single large + I/O request even when the group has just a few names. + HDF5 stores each name with a null terminator. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a valid group identifier for the open group if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Open">H5Gopen</a> + <dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Gopen</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code> + ) + <dt><strong>Purpose:</strong> + <dd>Opens an existing group for modification and returns a group + identifier for that group. + <dt><strong>Description:</strong> + <dd><code>H5Gopen</code> opens an existing group with the specified name at + the specified location, <code>loc_id</code>. + The location is identified by a file or + group identifier, and returns a group identifier for the group. + The obtained group identifier should be released by calling + <code>H5Gclose()</code> when it is no longer needed. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>File or group identifier within which group is to be open. + <dt><em>const char *</em> <code>name</code> + <dd>Name of group to open. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a valid group identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Set">H5Gset</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Gset</code> (<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the current working group within a file. + <dt><strong>Description:</strong> + <dd><code>H5Gset</code> sets the group with the specified name + to be the current working group for the file which contains it. + This function sets the current working group by modifying the + top element of the current working group stack or, if the + stack is empty, by pushing a new element onto the stack. + The initial current working group is the root group. + <p> + <code>loc_id</code> can be a file identifier or a group identifier. + <p> + <code>name</code> is an absolute or relative name and is resolved as follows. Each file identifier + has a current working group, initially the root group of the + file. Relative names do not begin with a slash and are relative + to the specified group or to the current working group. + Absolute names begin with a slash and are relative to the file's + root group. For instance, the name <code>/Foo/Bar/Baz</code> is + resolved by first looking up <code>Foo</code> in the root group; + the name <code>Foo/Bar/Baz</code> is resolved by first looking + up the name <code>Foo</code> in the current working group. + <p> + Each file identifier maintains its own notion of the current + working group. If <code>loc_id</code> is a group identifier, the + file identifier is derived from the group identifier. + <p> + If a single file is opened with multiple calls to <code>H5Fopen()</code>, + which would return multiple file identifiers, then each + identifier's current working group can be set independently + of the other file identifiers for that file. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>The file or group identifier. + <dt><em>const char *</em><code>name</code> + <dd>The name of the new current working group. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Push">H5Gpush</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Gpush</code> (<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the current working group by pushing a + new element onto the current working group stack. + <dt><strong>Description:</strong> + <dd>Each file identifier maintains a stack of groups, the top group + of which is the current working group. The stack initially + contains only the root group. <code>H5Gpush</code> pushes a new group + onto the stack, thus setting a new current working group. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>File or group identifier. + <dt><em>const char *</em><code>name</code> + <dd>The name of the new current working group. The name may be + an absolute or relative name. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Pop">H5Gpop</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Gpop</code> (<em>hid_t</em> <code>loc_id</code>) + <dt><strong>Purpose:</strong> + <dd>Removes the top, or latest, entry from the working group stack, + setting the current working group to the previous value. + <dt><strong>Description:</strong> + <dd><code>H5Gpop</code> restores the previous current working group by + popping an element from the current working group stack. + An empty stack implies that the current working group is the root + object. Attempting to pop an empty stack results in failure. + <p> + Each file identfier maintains its own notion of the current + working group. That is, if a single file is opened with + multiple calls to <code>H5Fopen()</code>, which returns multiple file + handles, then each identfier's current working group can be + set independently of the other file identfiers for that file. + <p> + If <code>loc_id</code> is a group identifier, it is used only to determine the + file identifier for the stack from which to pop the top entry. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>The file or group identifier. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Close">H5Gclose</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Gclose</code>(<em>hid_t </em><code>group_id</code>) + <dt><strong>Purpose:</strong> + <dd>Closes the specified group. + <dt><strong>Description:</strong> + <dd><code>H5Gclose</code> releases resources used by a group which was + opened by <code>H5Gcreate()</code> or <code>H5Gopen()</code>. + After closing a group, the <code>group_id</code> cannot be used again. + <p> + Failure to release a group with this call will result in resource leaks. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>group_id</code> + <dd>Group identifier to release. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Link">H5Glink</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Glink</code>(<em>hid_t</em> <code>loc_id</code>, + <em>H5G_link_t</em> <code>link_type</code>, + <em>const char *</em><code>current_name</code>, + <em>const char *</em><code>new_name</code> + ) + <dt><strong>Purpose:</strong> + <dd>Creates a link of the specified type from <code>new_name</code> + to <code>current_name</code>. + <dt><strong>Description:</strong> + <dd><code>H5Glink</code> creates a new name for an object that has some current + name, possibly one of many names it currently has. + <p> + If <code>link_type</code> is <code>H5G_LINK_HARD</code>, then + <code>current_name</code> must name an existing object and both + names are interpreted relative to <code>loc_id</code>, which is + either a file identifier or a group identifier. + <p> + If <code>link_type</code> is <code>H5G_LINK_SOFT</code>, then + <code>current_name</code> can be anything and is interpreted at + lookup time relative to the group which contains the final + component of <code>new_name</code>. For instance, if + <code>current_name</code> is <code>./foo</code>, + <code>new_name</code> is <code>./x/y/bar</code>, and a request + is made for <code>./x/y/bar</code>, then the actual object looked + up is <code>./x/y/./foo</code>. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>File or group identifier. + <dt><em>H5G_link_t</em> <code>link_type</code> + <dd>Link type. + Possible values are <code>H5G_LINK_HARD</code> and <code>H5G_LINK_SOFT</code>. + <dt><em>const char *</em> <code>current_name</code> + <dd>Name of the existing object if link is a hard link. + Can be anything for the soft link. + <dt><em>const char *</em> <code>new_name</code> + <dd>New name for the object. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Unlink">H5Gunlink</a> + + <strong>(Not implemented in this release.)</strong> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Gunlink</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code> + ) + <dt><strong>Purpose:</strong> + <dd>Removes the specified <code>name</code> from the group graph and + decrements the link count for the object to which <code>name</code> points + <dt><strong>Description:</strong> + <dd><code>H5Gunlink</code> removes an association between a name and an object. + Object headers keep track of how many hard links refer to the object; + when the hard link count reaches zero, the object can be removed + from the file. Objects which are open are not removed until all + identifiers to the object are closed. + <p> + If the link count reaches zero, all file-space associated with + the object will be reclaimed. If the object is open, the + reclamation of the file space is delayed until all handles to the + object are closed. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>Identifier of the file containing the object. + <dt><em>const char *</em> <code>name</code> + <dd>Name of the object to unlink. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Iterate">H5Giterate</a> + <dt><strong>Signature:</strong> + <dd><em>int</em> <code>H5Giterate</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char</em> <code>*name</code>, + <em>int</em> <code>*idx</code>, + <em>H5G_operator_t</em> <code>operator</code>, + <em>void</em> <code>*operator_data</code> + ) + <dt><strong>Purpose:</strong> + <dd>Iterates an operation over the entries of a group. + <dt><strong>Description:</strong> + <dd><code>H5Giterate</code> iterates over the members of + <code>name</code> in the file or group specified with + <code>loc_id</code>. + For each object in the group, the <code>operator_data</code> + and some additional information, specified below, are + passed to the <code>operator</code> function. + The iteration begins with the <code>idx</code> object in the + group and the next element to be processed by the operator is + returned in <code>idx</code>. If <code>idx</code> + is NULL, then the iterator starts at the first group member; + since no stopping point is returned in this case, the iterator + cannot be restarted if one of the calls to its operator returns + non-zero. + <p> + The prototype for <code>H5G_operator_t</code> is: + <ul><dl> + <dd><code>typedef</code> <em>herr_t *</em>(<code>H5G_operator_t</code>)(<em>hid_t</em> <code>group_id</code>, + <em>const char *</em><code>member_name</code>, <em>void *</em><code>operator_data/*in,out*/</code>); + </dl></ul> + <dd>The operation receives the group identifier for the group being + iterated over, <code>group_id</code>, the name of the current + object within the group, <code>member_name</code>, and the + pointer to the operator data passed in to <code>H5Giterate</code>, + <code>operator_data</code>. + <p> + The return values from an operator are: + <ul> + <li>Zero causes the iterator to continue, returning + zero when all group members have been processed. + <li>Positive causes the iterator to immediately return that positive + value, indicating short-circuit success. The iterator can be + restarted at the next group member. + <li>Negative causes the iterator to immediately return that value, + indicating failure. The iterator can be restarted at the next + group member. + </ul> + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: File or group identifier. + <dt><em>const char</em> <code>*name</code> + <dd>IN: Group over which the iteration is performed. + <dt><em>int</em> <code>*idx</code> + <dd>IN/OUT: Location at which to begin the iteration. + <dt><em>H5G_iterate_t</em> <code>operator</code> + <dd>IN: Operation to be performed on an object at each step of + the iteration. + <dt><em>void</em> <code>*operator_data</code> + <dd>IN/OUT: Data associated with the operation. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns the return value of the last operator if it was non-zero, + or zero if all group members were processed. + Otherwise, returns FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Move">H5Gmove</a> + + <strong>(Not implemented in this release.)</strong> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Gmove</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char</em> <code>*src</code>, + <em>const char</em> <code>*dst</code> + ) + <dt><strong>Purpose:</strong> + <dd>Renames an object within an HDF5 file. + <dt><strong>Description:</strong> + <dd><code>H5Gmove</code> renames an object within an HDF5 file. + The original name, <code>src</code>, is unlinked from the + group graph and the new name, <code>dst</code>, is inserted + as an atomic operation. Both names are interpreted relative + to <code>loc_id</code>, which is either a file or a group + identifier. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>File or group identifier. + <dt><em>const char</em> <code>*src</code> + <dd>Object's original name. + <dt><em>const char</em> <code>*dst</code> + <dd>Object's new name. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Stat">H5Gstat</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Gstat</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code>, + <em>hbool_t</em> <code>follow_link</code>, + <em>H5G_stat_t *</em><code>statbuf</code> + ) + <dt><strong>Purpose:</strong> + <dd>Returns information about an object. + <dt><strong>Description:</strong> + <dd><code>H5Gstat</code> returns information about the + specified object through the <code>statbuf</code> argument. + <code>loc_id</code> (a file, group, or dataset identifier) and + <code>name</code> together determine the object. + If the object is a symbolic link and <code>follow_link</code> is + zero (<code>0</code>), then the information returned is that for the link itself; + otherwise the link is followed and information is returned about + the object to which the link points. + If <code>follow_link</code> is non-zero but the final symbolic link + is dangling (does not point to anything), then an error is returned. + The <code>statbuf</code> fields are undefined for an error. + The existence of an object can be tested by calling this function + with a null <code>statbuf</code>. + <p> + <code>H5Gstat()</code> fills in the following data structure: + <pre> + typedef struct H5G_stat_t { + unsigned long fileno[2]; + unsigned long objno[2]; + unsigned nlink; + H5G_type_t type; + size_t linklen; + } H5G_stat_t + </pre> + The <code>fileno</code> and <code>objno</code> fields contain + four values which uniquely itentify an object among those + HDF5 files which are open: if all four values are the same + between two objects, then the two objects are the same + (provided both files are still open). + The <code>nlink</code> field is the number of hard links to + the object or zero when information is being returned about a + symbolic link (symbolic links do not have hard links but + all other objects always have at least one). + The <code>type</code> field contains the type of the object, + one of <code>H5G_GROUP</code>, <code>H5G_DATASET</code>, + or <code>H5G_LINK</code>. + If information is being returned about a symbolic link then + <code>linklen</code> will be the length of the link value + (the name of the pointed-to object with the null terminator); + otherwise <code>linklen</code> will be zero. + Other fields may be added to this structure in the future. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: File, group, or dataset identifier. + <dt><em>const char</em> <code>*name</code> + <dd>IN: Name of the object for which status is being sought. + <dt><em>hbool_t</em> <code>follow_link</code> + <dd>IN: Link flag. + <dt><em>H5G_stat_t</em> <code>*statbuf</code> + <dd>OUT: Buffer in which to return information about the object. + </dl> + <dt><strong>Returns:</strong> + <dd> Returns SUCCEED (0) with the fields of STATBUF (if non-null) initialized. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-GetLinkval">H5Gget_linkval</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Gget_linkval</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code>, + <em>size_t</em> <code>size</code>, + <em>char *</em><code>value</code> + ) + <dt><strong>Purpose:</strong> + <dd>Returns link value. + <dt><strong>Description:</strong> + <dd><code>H5Gget_linkval</code> returns <code>size</code> + characters of the link value through the <code>value</code> + argument if <code>loc_id</code> (a file or group identifier) + and <code>name</code> specify a symbolic link. + If <code>size</code> is smaller than the link value, then + <code>value</code> will not be null terminated. + <p> + This function fails if the specified object is not a symbolic link. + The presence of a symbolic link can be tested by passing zero for + <code>size</code> and NULL for <code>value</code>. + <p> + Use <code>H5Gstat()</code> to get the size of a link value. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: Identifier of the file or group . + <dt><em>const char *</em><code>name</code> + <dd>IN: Name of the object whose link value is to be checked. + <dt><em>size_t</em> <code>size</code> + <dd>IN: Maximum number of characters of <code>value</code> + to be returned. + <dt><em>char *</em><code>value</code> + <dd>OUT: Link value. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0), with the link value in <code>value</code>, + if successful. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<hr> +</b>UNUSED PORTIONS OF EMAIL NOTES.</b> +<br> +<code>....</code> in left margin indicates where material was pulled out for use. +<HR> +<HR> +<pre> + +Hi Elena, here's a hodgepodge of stuff from html documents and +previous e-mails to answer your questions. Let me know if you need +further clarification. + +.... +.... [H5Gmove and H5Gunlink "NYI" comments were here] +.... + +Elena> We need little bit more user-friendly description of the H5Gstat and +Elena> H5Giterate functions. + +>From a Mar 31 e-mail... + +Robb> +.... +.... [H5Giterate was here] +.... +Robb> +Robb> +Robb> Group Information Functions: +.... +.... [H5Gstat was here] +.... +Robb> +Robb> herr_t H5Gname(hid_t group_id, char *name, size_t max_name_len); +Robb> +Robb> This function retrieves the name of the group for a group ID. The +Robb> name is returned in 'name' up to the length specified in 'max_name_len'. +Robb> +.... +.... [H5Gget_linkval was here] +.... +Robb> +Robb> H5Giterate example #1: The operator just looks at the member name and if it has an +Robb> `X' in it then it returns 1, otherwise return zero. Returning 1 (or any +Robb> positive value) causes the iterator to immediately return that value. If +Robb> none of the operators return 1 then the iterator eventually returns zero. +Robb> +Robb> 1 herr_t +Robb> 2 any_X (hid_t group_id/*unused*/, +Robb> 4 const char *member_name, +Robb> 5 void *op_data/*unused*/) +Robb> 6 { +Robb> 7 return strchr(member_name,'X') ? 1 : 0; +Robb> 8 } +Robb> +Robb> The iterator is invoked as: +Robb> +Robb> 9 int elmt=0; +Robb> 10 herr_t found = H5Giterate(file_id, "/foo", &elmt, any_X, NULL); +Robb> 11 +Robb> 12 if (found<0) { +Robb> 13 printf ("Error iterating through group, at member %d\n", elmt); +Robb> 14 } else if (found) { +Robb> 15 printf ("Yes, member %d has an `X' in the name\n", elmt); +Robb> 16 } else { +Robb> 17 printf ("No member name contains an `X'\n"); +Robb> 18 } +Robb> +Robb> H5Giterate example #2: An iterator to find an object whose name contains an `X' +Robb> This is the same as Example 1 except the operator also returns the name +Robb> that contains the `X'. We do this by passing a pointer to a `char*' as the +Robb> operator data and the operator will initialize that `char*' by strdup'ing +Robb> the object name. +Robb> +Robb> 1 herr_t +Robb> 2 find_X (hid_t group_id/*unused*/, +Robb> 4 const char *member_name, +Robb> 5 void *op_data/*out*/) +Robb> 6 { +Robb> 7 if (strchr(member_name,'X')) { +Robb> 8 *((char**)op_data) = strdup(member_name); +Robb> 9 return 1; +Robb> 10 } +Robb> 11 return 0; +Robb> 12 } +Robb> +Robb> To print all the names with an `X' the iterator is invoked +Robb> repeatedly until it returns zero. +Robb> +Robb> 13 int elmt = 0; +Robb> 14 char *name; +Robb> 15 while (H5Giterate(file_id, "/foo", &elmt, find_X, &name)) { +Robb> 16 puts (name); +Robb> 17 free (name); +Robb> 18 } +Robb> +Robb> H5Giterate example #3: Print all names that contain the specified character. +Robb> This is the same as Example 2 except we have to pass data into the operator +Robb> as well as get data out. We create a struct that contains the input data +Robb> (character to look for) and a slot for the output data (the name) and pass +Robb> that as the operator data. +Robb> +Robb> 1 typedef struct { +Robb> 2 char look_for; +Robb> 3 char *name; +Robb> 4 } find_char_t; +Robb> 5 +Robb> 6 herr_t +Robb> 7 find_char (hid_t group_id/*unused*/, +Robb> 9 const char *member_name, +Robb> 10 find_char_t *op_data/*in,out*/) +Robb> 11 { +Robb> 13 if (strchr(member_name, op_data->look_for)) { +Robb> 14 op_data->name = strdup (member_name); +Robb> 15 return 1; +Robb> 16 } +Robb> 17 return 0; +Robb> 18 } +Robb> +Robb> To print all names that have a `Y' one would say +Robb> +Robb> 19 find_char_t op_data; +Robb> 20 int elmt = 0; +Robb> 21 op_data->look_for = 'Y'; +Robb> 22 while (H5Giterate(file_id, "/foo", &elmt, find_X, &op_data)) { +Robb> 23 puts (op_data->name); +Robb> 24 free (op_data->name); +Robb> 25 } +Robb> +Robb> H5Giterate example #4: Efficient version of Example 3. +Robb> Examples 2 and 3 weren't too efficient because we kept interrupting the +Robb> iterator and it had to start over, albeit from the middle of the search. If +Robb> we could allow the iterator to go further then we wouldn't end up scanning +Robb> through the leaf nodes of the symbol table so often (searching for a +Robb> particular index, n, in a B-tree is an O(n) operation). +Robb> The H5Glist() function defined earlier returns the names of all the group +Robb> members which belong to a certain class, H5G_ALL, H5G_DATASET, or H5G_GROUP. +Robb> This example shows how to implement that functionality. +Robb> First we need a struct to describe the operator data and it's return +Robb> value(s). These correspond to the arguments presented for H5Glist, whose +Robb> definition is at the end of this example. (Since most of the work is done by +Robb> the operator we have to pass all this stuff back and forth through the +Robb> iterator). +Robb> +Robb> 1 typedef struct { +Robb> 2 size_t name_heap_size; +Robb> 3 char *name_heap; +Robb> 4 unsigned max_entries; +Robb> 5 char *names[]; +Robb> 6 int type; +Robb> 7 unsigned cur_entries; /* How many names read so far */ +Robb> 8 size_t cur_heap_size; /* How large is the heap */ +Robb> 9 } H5G_list_t; +Robb> +Robb> The operator checks if an object is the right type, and if so adds it to +Robb> the return value arrays in the op_data struct. If the arrays become full +Robb> then the operator returns 1 to stop the iterator. The H5*isa() functions +Robb> return true iff the named object is of the * type (sans error handling). +Robb> +Robb> 10 herr_t +Robb> 11 H5G_list_op (hid_t grp_id, const char *memb_name, +Robb> 12 H5G_list_t *op_data) +Robb> 13 { +Robb> 14 char *out_name; +Robb> 15 +Robb> 16 if (H5G_ALL==op_data->type || +Robb> 17 (H5G_DATASET==op_data->type && H5Disa(grp_id,memb_name)) || +Robb> 18 (H5G_GROUP==op_data->type && H5Gisa(grp_id, memb_name))) { +Robb> 19 +Robb> 20 /* Is there enough room for the name in the heap? */ +Robb> 21 if (op_data->cur_heap_size + strlen(memb_name) + 1 > +Robb> 22 op_data->name_heap_size) { +Robb> 23 return 2; /*try again later, see lines 59-62*/ +Robb> 24 } +Robb> 25 +Robb> 26 /* Add name to op_data return value arrays */ +Robb> 27 out_name = op_data->name_heap + op_data->cur_heap_size; +Robb> 28 strcpy (out_name, memb_name); +Robb> 29 op_data->names[op_data->cur_entries] = out_name; +Robb> 30 op_data->cur_heap_size += strlen(memb_name) + 1; +Robb> 31 +Robb> 32 /* Is the output full? */ +Robb> 33 if (op_data->cur_entries >= op_data->max_entries) { +Robb> 34 return 1; +Robb> 35 } +Robb> 36 } +Robb> 37 return 0; +Robb> 38 } +Robb> +Robb> And finally, the definition of H5Glist(): +Robb> +Robb> 39 int +Robb> 40 H5Glist (hid_t group_id, size_t name_heap_size, char *name_heap, +Robb> 41 int *start_idx, unsigned max_entries, char *names[], +Robb> 42 int type) +Robb> 43 { +Robb> 44 H5G_list_t op_data; +Robb> 45 herr_t status; +Robb> 46 +Robb> 47 op_data->name_heap_size = name_heap_size; +Robb> 48 op_data->name_heap = name_heap; +Robb> 49 op_data->max_entries = max_entries; +Robb> 50 op_data->names = names; +Robb> 51 op_data->type = type; +Robb> 52 op_data->cur_entries = 0; +Robb> 53 op_data->cur_heap_size = 0; +Robb> 54 +Robb> 55 if (0==cur_entries) return 0; +Robb> 56 status = H5Giterate (group_id, ".", start_idx, H5G_list_op, +Robb> 57 &op_data); +Robb> 58 +Robb> 59 if (2==status && 0==op_data->cur_entries) { +Robb> 60 return -1; /*heap not large enough for even one name*/ +Robb> 61 } else if (2==status) { +Robb> 62 --*start_idx; /*heap overflow, try again later*/ +Robb> 63 } else if (status<0) { +Robb> 64 return status; /*iterator or operator error*/ +Robb> 65 } +Robb> 66 return op_data->cur_entries; +Robb> 67 } +Robb> +Robb> The only other really interesting thing in this example are lines 23, 61, +Robb> and 62. We don't know if the name heap will overflow until we find a name to +Robb> put there. And then if it does, we need to be able to restart the iterator at +Robb> the entry that failed instead of the following entry. +Robb> +Robb> H5Giterate example #5: Print all the names of objects in a group, without any +Robb> buffers. +Robb> --------------------- +Robb> +Robb> herr_t print_names (hid_t grp_id, const char *name, void *opdata) +Robb> { +Robb> puts (name); +Robb> return 0; +Robb> } +Robb> +Robb> { +Robb> H5Giterate (file_id, "/foo/bar", NULL, print_names, NULL); +Robb> } + +Elena> I believe there is a typo in the H5Pget_layout function in the source +Elena> code. Second argument ( H5D_layout_t *layout is missing....) + +It's returned by value, not reference. It returns only the class of +layout and then, based on the class, you must call some other H5Pget +function like H5Pget_chunk() like this: + + hid_t dcpl; /*dataset creation property list*/ + hsize_t dims[32]; /*chunk dimensions*/ + ... + switch (H5Pget_layout(dcpl)) { + case H5D_CHUNKED: + H5Pget_chunk(dcpl, NELMTS(dims), dims); + break; + ... + case H5D_LAYOUT_ERROR: + ... + ... + } + + +Quincy and html> +Quincy and html> +.... +.... [Datatype material move to H5T.html] +.... +Quincy and html> +Quincy and html> + + +</pre> +<hr> +<hr> + +<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> 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> diff --git a/doc/src/RM_H5S.html b/doc/src/RM_H5S.html new file mode 100644 index 0000000..903d720 --- /dev/null +++ b/doc/src/RM_H5S.html @@ -0,0 +1,291 @@ +<html> +<head><title> +HDF5/H5S Draft API Specification +</title></head> + +<body> + +<center> +<h1>H5S: Dataspace Interface</h1> +</center> + +<h2>Dataspace Object API Functions</h2> + +These functions create and manipulate the dataspace in which to store the +elements of a dataset. + +<table border=0> +<tr><td valign=top> +<ul> + <li><a href="#Dataspace-CreateSimple">H5Screate_simple</a> + <li><a href="#Dataspace-Copy">H5Scopy</a> + <li><a href="#Dataspace-GetNpoints">H5Sget_npoints</a> + <li><a href="#Dataspace-GetNdims">H5Sget_ndims</a> +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#Dataspace-GetDims">H5Sget_dims</a> + <li><a href="#Dataspace-IsSimple">H5Sis_simple</a> + <li><a href="#Dataspace-SetSpace">H5Sset_space</a> + <li><a href="#Dataspace-SetHyperslab">H5Sset_hyperslab</a> +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#Dataspace-GetHyperslab">H5Sget_hyperslab</a> + <li><a href="#Dataspace-Close">H5Sclose</a> +</ul> +</td></tr> +</table> + +<hr> + +<dl> +<dt><strong>Name:</strong> <a name="Dataspace-CreateSimple">H5Screate_simple</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t</em> <code>H5Screate_simple</code>(<em>int</em> <code>rank</code>, + <em>const hsize_t *</em> <code>dims</code>, + <em>const hsize_t *</em> <code>maxdims</code> + ) +<dt><strong>Description:</strong> + <dd>This function creates a new simple data space object and opens it for + access. The <code>rank</code> is the number of dimensions used in the + dataspace. The <code>dims</code> argument is the size of the simple + dataset and the <code>maxdims</code> argument is the upper limit on the + size of the dataset. <code>maxdims</code> may be the null pointer in + which case the upper limit is the same as <code>dims</code>. If an + element of <code>maxdims</code> is zero then the corresponding dimension + is unlimited, otherwise no element of <code>maxdims</code> should be + smaller than the corresponding element of <code>dims</code>. The + dataspace ID returned from this function should be released with + H5Sclose or resource leaks will occur. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>int</em> <code>rank</code> + <dd>Number of dimensions of dataspace. + <dt><em>const hsize_t *</em> <code>dims</code> + <dd>An array of the size of each dimension. + <dt><em>const hsize_t *</em> <code>maxdims</code> + <dd>An array of the maximum size of each dimension. + </dl> +<dt><strong>Returns:</strong> + <dd>A dataspace ID on success, negative on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataspace-Copy">H5Scopy</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Scopy</code>(<em>hid_t </em><code>space_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function copies a dataspace. The dataspace ID returned from this + function should be released with H5Sclose or resource leaks will occur. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>space_id</code> + <dd>ID of dataspace to copy. + </dl> +<dt><strong>Returns:</strong> + <dd>A dataspace ID on success, negative on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataspace-GetNpoints">H5Sget_npoints</a> +<dt><strong>Signature:</strong> + <dd><em>hsize_t</em> <code>H5Sget_npoints</code>(<em>hid_t </em><code>space_id</code>) +<dt><strong>Description:</strong> + <dd>This function determines the number of elements in a dataspace. For + example, a simple 3-dimensional dataspace with dimensions 2, 3 and 4 + would have 24 elements. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>space_id</code> + <dd>ID of the dataspace object to query + </dl> +<dt><strong>Returns:</strong> + <dd>Number of elements in the dataspace, 0 on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataspace-GetNdims">H5Sget_ndims</a> +<dt><strong>Signature:</strong> + <dd><em>int</em> <code>H5Sget_ndims</code>(<em>hid_t</em> <code>space_id</code>) +<dt><strong>Description:</strong> + <dd>This function determines the dimensionality (or rank) of a dataspace. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>space_id</code> + <dd>ID of the dataspace object to query + </dl> +<dt><strong>Returns:</strong> + <dd>Number of dimensions in the dataspace, negative on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataspace-GetDims">H5Sget_dims</a> +<dt><strong>Signature:</strong> + <dd><em>int</em> <code>H5Sget_dims</code>(<em>hid_t</em> <code>space_id</code>, + <em>hsize_t *</em><code>dims</code>, + <em>hsize_t *</em><code>maxdims</code> + ) +<dt><strong>Description:</strong> + <dd>This function returns the size of each dimension in a dataspace through + the <code>dims</code> parameter. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>space_id</code> + <dd>ID of the dataspace object to query + <dt><em>hsize_t *</em><code>dims</code> + <dd>Pointer to array to store the size of each dimension. + <dt><em>hsize_t *</em><code>maxdims</code> + <dd>Pointer to array to store the maximum size of each dimension. + </dl> +<dt><strong>Returns:</strong> + <dd>Number of dimensions in the dataspace, negative on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataspace-IsSimple">H5Sis_simple</a> +<dt><strong>Signature:</strong> + <dd><em>hbool_t </em><code>H5Sis_simple</code>(<em>hid_t </em><code>space_id</code>) +<dt><strong>Description:</strong> + <dd>This function determines whether a dataspace object is a simple + dataspace or not. [Currently, all dataspace objects are simple + dataspaces, complex dataspace support will be added in the future] +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>space_id</code> + <dd>ID of the dataspace object to query + </dl> +<dt><strong>Returns:</strong> + <dd>TRUE or FALSE on success, negative on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataspace-SetSpace">H5Sset_space</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Sset_space</code>(<em>hid_t </em><code>space_id</code>, + <em>uint32 </em><code>rank</code>, + <em>uint32 *</em><code>dims</code> + ) +<dt><strong>Description:</strong> + <dd>This function determines the number of dimensions and the size of each + dimension for the space that a dataset is stored within. This function + only creates simple dataspace objects. Setting the rank to a + value of zero allows scalar objects to be created. Dimensions are + specified from slowest to fastest changing in the <code>dims</code> + array (i.e. 'C' order). Setting the size of a dimension to zero + indicates that the dimension is of unlimited size and should be allowed + to expand. Currently, only the first dimension in the array (the + slowest) may be unlimited in size. + [Currently, all dataspace objects are simple + dataspaces, complex dataspace support will be added in the future] +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>space_id</code> + <dd>ID of the dataspace object. + <dt><em>uint32</em> <code>rank</code> + <dd>The number of dimensions the object is composed of. + <dt><em>uint32 *</em> <code>dims</code> + <dd>An array of the size of each dimension. (NULL for scalar objects) + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataspace-SetHyperslab">H5Sset_hyperslab</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Sset_hyperslab</code>(<em>hid_t</em> <code>space_id</code>, + <em>const hssize_t *</em><code>start</code>, + <em>const hsize_t *</em><code>count</code>, + <em>const hsize_t *</em><code>stride</code> + ) +<dt><strong>Description:</strong> + <dd>This function selects a hyperslab from a simple dataspace. The stride + array may be used to sub-sample the hyperslab chosen, a value of 1 in each + position of the stride array selects contiguous elements in the array, + a value of 2 selects every other element, etc. If the stride parameter is + set to NULL, a contiguous hyperslab is chosen. The values in the start and + count arrays may be negative, to allow for selecting hyperslabs in chunked + datasets which extend in arbitrary directions. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>space_id</code> + <dd>ID of the dataspace object to set hyperslab in. + <dt><em>const hssize_t *</em><code>start</code> + <dd>Pointer to array of starting location for hyperslab. + <dt><em>const hsize_t *</em><code>count</code> + <dd>Pointer to array of magnitude of hyperslab. + <dt><em>const hsize_t *</em><code>stride</code> + <dd>Pointer to array of stride of hyperslab. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataspace-GetHyperslab">H5Sget_hyperslab</a> +<dt><strong>Signature:</strong> + <dd><em>int</em> <code>H5Sget_hyperslab</code>(<em>hid_t</em> <code>space_id</code>, + <em>hssize_t *</em><code>start</code>, + <em>hsize_t *</em><code>count</code>, + <em>hsize_t *</em><code>stride</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves information about the hyperslab from a simple + dataspace. If no hyperslab has been defined then the hyperslab is the + same as the entire array. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>space_id</code> + <dd>ID of the dataspace object to set hyperslab in. + <dt><em>hssize_t *</em><code>start</code> + <dd>Pointer to array to store starting location of hyperslab. + <dt><em>hsize_t *</em><code>count</code> + <dd>Pointer to array to store magnitude of hyperslab. + <dt><em>hsize_t *</em><code>stride</code> + <dd>Pointer to array to store stride of hyperslab. + </dl> +<dt><strong>Returns:</strong> + <dd>Hyperslab dimensionality on success, negative on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataspace-Close">H5Sclose</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Sclose</code>(<em>hid_t </em><code>space_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function releases a dataspace. Further access through the dataspace + ID is illegal. Failure to release a dataspace with this call will + result in resource leaks. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>space_id</code> + <dd>ID of dataspace to release. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</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: 29 June 1998 + +</body> +</html> diff --git a/doc/src/RM_H5T.html b/doc/src/RM_H5T.html new file mode 100644 index 0000000..46fe6fc --- /dev/null +++ b/doc/src/RM_H5T.html @@ -0,0 +1,1323 @@ +<html> +<head><title> +HDF5/H5T Draft API Specification +</title></head> + +<body> + +<center> +<h1>H5T: Datatype Interface</h1> +</center> + +<h2>Datatype Object API Functions</h2> + +These functions create and manipulate the datatype which describes elements +of a dataset. + +<table border=0> +<tr><td valign=top> +<ul> + <li><a href="#Datatype-Create">H5Tcreate</a> + <li><a href="#Datatype-Copy">H5Tcopy</a> + <li><a href="#Datatype-Equal">H5Tequal</a> + <li><a href="#Datatype-Lock">H5Tlock</a> + <li><a href="#Datatype-GetClass">H5Tget_class</a> + <li><a href="#Datatype-GetSize">H5Tget_size</a> + <li><a href="#Datatype-SetSize">H5Tset_size</a> + <li><a href="#Datatype-GetOrder">H5Tget_order</a> + <li><a href="#Datatype-SetOrder">H5Tset_order</a> + <li><a href="#Datatype-GetPrecision">H5Tget_precision</a> + <li><a href="#Datatype-SetPrecision">H5Tset_precision</a> + <li><a href="#Datatype-GetOffset">H5Tget_offset</a> + <li><a href="#Datatype-SetOffset">H5Tset_offset</a> + <li><a href="#Datatype-GetPad">H5Tget_pad</a> +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#Datatype-SetPad">H5Tset_pad</a> + <li><a href="#Datatype-GetSign">H5Tget_sign</a> + <li><a href="#Datatype-SetSign">H5Tset_sign</a> + <li><a href="#Datatype-GetFields">H5Tget_fields</a> + <li><a href="#Datatype-SetFields">H5Tset_fields</a> + <li><a href="#Datatype-GetEbias">H5Tget_ebias</a> + <li><a href="#Datatype-SetEbias">H5Tset_ebias</a> + <li><a href="#Datatype-GetNorm">H5Tget_norm</a> + <li><a href="#Datatype-SetNorm">H5Tset_norm</a> + <li><a href="#Datatype-GetInpad">H5Tget_inpad</a> + <li><a href="#Datatype-SetInpad">H5Tset_inpad</a> + <li><a href="#Datatype-GetCset">H5Tget_cset</a> + <li><a href="#Datatype-SetCset">H5Tset_cset</a> + <li><a href="#Datatype-GetStrpad">H5Tget_strpad</a> +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#Datatype-SetStrpad">H5Tset_strpad</a> + <li><a href="#Datatype-GetNmembers">H5Tget_nmembers</a> + <li><a href="#Datatype-GetMemberName">H5Tget_member_name</a> + <li><a href="#Datatype-GetMemberOffset">H5Tget_member_offset</a> + <li><a href="#Datatype-GetMemberDims">H5Tget_member_dims</a> + <li><a href="#Datatype-GetMemberType">H5Tget_member_type</a> + <li><a href="#Datatype-Insert">H5Tinsert</a> + <li><a href="#Datatype-Pack">H5Tpack</a> + <li><a href="#Datatype-RegisterHard">H5Tregister_hard</a> + <li><a href="#Datatype-RegisterSoft">H5Tregister_soft</a> + <li><a href="#Datatype-Unregister">H5Tunregister</a> + <li><a href="#Datatype-Close">H5Tclose</a> +</ul> +</td></tr> +</table> + +<hr> + +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Create">H5Tcreate</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Tcreate</code>(<em>H5T_class_t </em><code>class</code>, + <em>size_t</em><code>size</code> + ) +<dt><strong>Description:</strong> + <dd>This function creates a new dataype of the specified class with the + specified number of bytes. Currently, only the <code>H5T_COMPOUND</code> + datatype class is supported with this function, use <code>H5Tcopy</code> + to create integer or floating-point datatypes. The datatype ID + returned from this function should be released with H5Tclose or resource + leaks will result. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5T_class_t</em> <code>class</code> + <dd>Class of datatype to create. + <dt><em>size_t</em> <code>size</code> + <dd>The number of bytes in the datatype to create. + </dl> +<dt><strong>Returns:</strong> + <dd>Datatype ID on success, negative on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Copy">H5Tcopy</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Tcopy</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function copies an existing datatype. The datatype ID returned + should be released with H5Tclose or resource leaks will occur. Native + datatypes supported by the library are: + <ul> <dl> + <dt>H5T_NATIVE_CHAR + <dd> Native character type, declare dataset array as 'char' + <dt>H5T_NATIVE_UCHAR + <dd> Native unsigned character type, declare dataset array as 'unsigned char' + <dt>H5T_NATIVE_SHORT + <dd> Native short type, declare dataset array as 'short' + <dt>H5T_NATIVE_USHORT + <dd> Native unsigned short type, declare dataset array as 'unsigned short' + <dt>H5T_NATIVE_INT + <dd> Native int type, declare dataset array as 'int' + <dt>H5T_NATIVE_UINT + <dd> Native unsigned int type, declare dataset array as 'unsigned int' + <dt>H5T_NATIVE_LONG + <dd> Native long type, declare dataset array as 'unsigned long' + <dt>H5T_NATIVE_ULONG + <dd> Native unsigned long type, declare dataset array as 'unsigned long' + <dt>H5T_NATIVE_LLONG + <dd> Native long long type, declare dataset array as 'unsigned long long' + <dt>H5T_NATIVE_ULLONG + <dd> Native unsigned long long type, declare dataset array as 'unsigned long long' + <dt>H5T_NATIVE_INT8 + <dd> Native signed 8-bit type, declare dataset array as 'int8' + <dt>H5T_NATIVE_UINT8 + <dd> Native unsigned 8-bit type, declare dataset array as 'uint8' + <dt>H5T_NATIVE_INT16 + <dd> Native signed 16-bit type, declare dataset array as 'int16' + <dt>H5T_NATIVE_UINT16 + <dd> Native unsigned 16-bit type, declare dataset array as 'uint16' + <dt>H5T_NATIVE_INT32 + <dd> Native signed 32-bit type, declare dataset array as 'int32' + <dt>H5T_NATIVE_UINT32 + <dd> Native unsigned 32-bit type, declare dataset array as 'uint32' + <dt>H5T_NATIVE_INT64 + <dd> Native signed 64-bit type, declare dataset array as 'uint64' + <dt>H5T_NATIVE_UINT64 + <dd> Native unsigned 64-bit type, declare dataset array as 'uint64' + <dt>H5T_NATIVE_FLOAT + <dd> Native single-precision float type, declare dataset array as 'float' + <dt>H5T_NATIVE_DOUBLE + <dd> Native double-precision float type, declare dataset array as 'double' + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to copy. + </dl> +<dt><strong>Returns:</strong> + <dd>Datatype ID on success, negative on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Equal">H5Tequal</a> +<dt><strong>Signature:</strong> + <dd><em>hbool_t </em><code>H5Tequal</code>(<em>hid_t </em><code>type_id1</code>, + <em>hid_t</em><code>type_id2</code> + ) +<dt><strong>Description:</strong> + <dd>This function determines if two datatype IDs refer to the same + datatype. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id1</code> + <dd>ID of datatype to compare. + <dt><em>hid_t</em> <code>type_id2</code> + <dd>ID of datatype to compare. + </dl> +<dt><strong>Returns:</strong> + <dd>TRUE/FALSE/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Lock">H5Tlock</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tlock</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function locks a type, making it read-only and non-destrucible. + This is normally done by the library for predefined data types so the + application doesn't inadvertently change or delete a predefined type. + Once a data type is locked it can never be unlocked. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to lock. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetClass">H5Tget_class</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_class_t </em><code>H5Tget_class</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function returns the base class of a datatype. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Non-negative type class on success, negative on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetSize">H5Tget_size</a> +<dt><strong>Signature:</strong> + <dd><em>size_t </em><code>H5Tget_size</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function returns the size of a datatype in bytes. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Positve size in bytes on success, 0 on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetSize">H5Tset_size</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_size</code>(<em>hid_t </em><code>type_id</code>, + <em>size_t</em><code>size</code> + ) +<dt><strong>Description:</strong> + <dd>This function sets the total size in bytes for an atomic data type (this + operation is not permitted on compound data types). If the size is + decreased so that the significant bits of the data type extend beyond + the edge of the new size, then the `offset' property is decreased + toward zero. If the `offset' becomes zero and the significant + bits of the data type still hang over the edge of the new size, then + the number of significant bits is decreased. + Adjusting the size of an H5T_STRING automatically sets the precision + to 8*size. All data types have a positive size. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to change size. + <dt><em>size_t</em> <code>size</code> + <dd>Size in bytes to modify datatype. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetOrder">H5Tget_order</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_order_t </em><code>H5Tget_order</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function returns the byte order of an atomic datatype. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Byte order constant on success, negative on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetOrder">H5Tset_order</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_order</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_order_t</em><code>order</code> + ) +<dt><strong>Description:</strong> + <dd>This function sets the byte ordering of an atomic datatype. + Byte orderings currently supported are: + <ul> <dl> + <dt>H5T_ORDER_LE + <dd> Little-endian byte ordering (default) + <dt>H5T_ORDER_BE + <dd> Big-endian byte ordering + <dt>H5T_ORDER_Vax + <dd> VAX-endianness byte ordering (not currently supported) + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to set. + <dt><em>H5T_order_t</em> <code>order</code> + <dd>Byte ordering constant. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetPrecision">H5Tget_precision</a> +<dt><strong>Signature:</strong> + <dd><em>size_t </em><code>H5Tget_precision</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function returns the precision of an atomic data type. The + precision is the number of significant bits which, unless padding is + present, is 8 times larger than the value returned by H5Tget_size(). +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Number of significant bits on success, 0 on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetPrecision">H5Tset_precision</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_precision</code>(<em>hid_t </em><code>type_id</code>, + <em>size_t</em><code>precision</code> + ) +<dt><strong>Description:</strong> + <dd>This function sets the precision of an atomic data type. The precision + is the number of significant bits which, unless padding is present, is 8 + times larger than the value returned by H5Tget_size(). + <P>If the precision is increased then the offset is decreased and then + the size is increased to insure that significant bits do not "hang + over" the edge of the data type. + <P>Changing the precision of an H5T_STRING automatically changes the + size as well. The precision must be a multiple of 8. + <P>When decreasing the precision of a floating point type, set the + locations and sizes of the sign, mantissa, and exponent fields + first. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to set. + <dt><em>size_t</em> <code>precision</code> + <dd>Number of bits of precision for datatype. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetOffset">H5Tget_offset</a> +<dt><strong>Signature:</strong> + <dd><em>size_t </em><code>H5Tget_offset</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the bit offset of the first significant bit. + The signficant bits of an atomic datum can be offset from the beginning + of the memory for that datum by an amount of padding. The `offset' + property specifies the number of bits of padding that appear to the + "right of" the value. That is, if we have a 32-bit datum with 16-bits + of precision having the value 0x1122 then it will be layed out in + memory as (from small byte address toward larger byte addresses): + <br> + <br> + + <table border align=center cellpadding=4 width="80%"> + <tr align=center> + <th width="20%">Byte Position</th> + <th width="20%">Big-Endian Offset=0</th> + <th width="20%">Big-Endian Offset=16</th> + <th width="20%">Little-Endian Offset=0</th> + <th width="20%">Little-Endian Offset=16</th> + </tr> + <tr align=center> + <td>0:</td> + <td>[ pad]</td> + <td>[0x11]</td> + <td>[0x22]</td> + <td>[ pad]</td> + </tr> + <tr align=center> + <td>1:</td> + <td>[ pad]</td> + <td>[0x22]</td> + <td>[0x11]</td> + <td>[ pad]</td> + </tr> + <tr align=center> + <td>2:</td> + <td>[0x11]</td> + <td>[ pad]</td> + <td>[ pad]</td> + <td>[0x22]</td> + </tr> + <tr align=center> + <td>3:</td> + <td>[0x22]</td> + <td>[ pad]</td> + <td>[ pad]</td> + <td>[0x11]</td> + </tr> + </table> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Positive offset value on success, 0 on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetOffset">H5Tset_offset</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_offset</code>(<em>hid_t </em><code>type_id</code>, + <em>size_t</em> <code>offset</code> + ) +<dt><strong>Description:</strong> + <dd>This function sets the bit offset of the first significant bit. The + signficant bits of an atomic datum can be offset from the beginning of + the memory for that datum by an amount of padding. The `offset' + property specifies the number of bits of padding that appear to the + "right of" the value. That is, if we have a 32-bit datum with 16-bits + of precision having the value 0x1122 then it will be layed out in + memory as (from small byte address toward larger byte addresses): + <br> + <br> + + <table border align=center cellpadding=4 width="80%"> + <tr align=center> + <th width="20%">Byte Position</th> + <th width="20%">Big-Endian Offset=0</th> + <th width="20%">Big-Endian Offset=16</th> + <th width="20%">Little-Endian Offset=0</th> + <th width="20%">Little-Endian Offset=16</th> + </tr> + <tr align=center> + <td>0:</td> + <td>[ pad]</td> + <td>[0x11]</td> + <td>[0x22]</td> + <td>[ pad]</td> + </tr> + <tr align=center> + <td>1:</td> + <td>[ pad]</td> + <td>[0x22]</td> + <td>[0x11]</td> + <td>[ pad]</td> + </tr> + <tr align=center> + <td>2:</td> + <td>[0x11]</td> + <td>[ pad]</td> + <td>[ pad]</td> + <td>[0x22]</td> + </tr> + <tr align=center> + <td>3:</td> + <td>[0x22]</td> + <td>[ pad]</td> + <td>[ pad]</td> + <td>[0x11]</td> + </tr> + </table> + +<P>If the offset is incremented then the total size is +incremented also if necessary to prevent significant bits of +the value from hanging over the edge of the data type. + +<P>The offset of an H5T_STRING cannot be set to anything but +zero. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to set. + <dt><em>size_t</em> <code>offset</code> + <dd>Offset of first significant bit. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetPad">H5Tget_pad</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tget_pad</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_pad_t *</em> <code>lsb</code>, + <em>H5T_pad_t *</em> <code>msb</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the padding type of the least and most-significant + bit padding. Valid types are: + <ul> <dl> + <dt>H5T_PAD_ZERO + <dd>Set background to zeros. + <dt>H5T_PAD_ONE + <dd>Set background to ones. + <dt>H5T_PAD_BACKGROUND + <dd>Leave background alone. + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to query. + <dt><em>H5T_pad_t *</em> <code>lsb</code> + <dd>Pointer to location to return least-significant bit padding type. + <dt><em>H5T_pad_t *</em> <code>msb</code> + <dd>Pointer to location to return most-significant bit padding type. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetPad">H5Tset_pad</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_pad</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_pad_t</em> <code>lsb</code>, + <em>H5T_pad_t</em> <code>msb</code> + ) +<dt><strong>Description:</strong> + <dd>This function sets the least and most-significant bits padding types. + <ul> <dl> + <dt>H5T_PAD_ZERO + <dd>Set background to zeros. + <dt>H5T_PAD_ONE + <dd>Set background to ones. + <dt>H5T_PAD_BACKGROUND + <dd>Leave background alone. + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to set. + <dt><em>H5T_pad_t</em> <code>lsb</code> + <dd>Padding type for least-significant bits. + <dt><em>H5T_pad_t</em> <code>msb</code> + <dd>Padding type for most-significant bits. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetSign">H5Tget_sign</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_sign_t </em><code>H5Tget_sign</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the sign type for an integer type. + Valid types are: + <ul> <dl> + <dt>H5T_SGN_NONE + <dd>Unsigned integer type. + <dt>H5T_SGN_2 + <dd>Two's complement signed integer type. + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Non-negative sign type on success, negative on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetSign">H5Tset_sign</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_sign</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_sign_t</em> <code>sign</code> + ) +<dt><strong>Description:</strong> + <dd>This function sets the sign proprety for an integer type. + <ul> <dl> + <dt>H5T_SGN_NONE + <dd>Unsigned integer type. + <dt>H5T_SGN_2 + <dd>Two's complement signed integer type. + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to set. + <dt><em>H5T_sign_t</em> <code>sign</code> + <dd>Sign type. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetFields">H5Tget_fields</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tget_fields</code>(<em>hid_t </em><code>type_id</code>, + <em>size_t *</em> <code>epos</code>, + <em>size_t *</em> <code>esize</code>, + <em>size_t *</em> <code>mpos</code>, + <em>size_t *</em> <code>msize</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves information about the locations of the various + bit fields of a floating point data type. The field positions are bit + positions in the significant region of the data type. Bits are + numbered with the least significant bit number zero. + Any (or even all) of the arguments can be null pointers. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to query. + <dt><em>size_t *</em> <code>epos</code> + <dd>Pointer to location to return exponent bit-position. + <dt><em>size_t *</em> <code>esize</code> + <dd>Pointer to location to return size of exponent in bits. + <dt><em>size_t *</em> <code>mpos</code> + <dd>Pointer to location to return mantissa bit-position. + <dt><em>size_t *</em> <code>msize</code> + <dd>Pointer to location to return size of mantissa in bits. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetFields">H5Tset_fields</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_fields</code>(<em>hid_t </em><code>type_id</code>, + <em>size_t</em> <code>epos</code>, + <em>size_t</em> <code>esize</code>, + <em>size_t</em> <code>mpos</code>, + <em>size_t</em> <code>msize</code> + ) +<dt><strong>Description:</strong> + <dd>This function sets the locations and sizes of the various floating + point bit fields. The field positions are bit positions in the + significant region of the data type. Bits are numbered with the least + significant bit number zero. + + <P>Fields are not allowed to extend beyond the number of bits of + precision, nor are they allowed to overlap with one another. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to set. + <dt><em>size_t</em> <code>epos</code> + <dd>Exponent bit position. + <dt><em>size_t</em> <code>esize</code> + <dd>Size of exponent in bits. + <dt><em>size_t</em> <code>mpos</code> + <dd>Mantissa bit position. + <dt><em>size_t</em> <code>msize</code> + <dd>Size of mantissa in bits. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetEbias">H5Tget_ebias</a> +<dt><strong>Signature:</strong> + <dd><em>size_t </em><code>H5Tget_ebias</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the exponent bias of a floating-point type. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Positive value on success, 0 on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetEbias">H5Tset_ebias</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_ebias</code>(<em>hid_t </em><code>type_id</code>, + <em>size_t</em> <code>ebias</code> + ) +<dt><strong>Description:</strong> + <dd>This function sets the exponent bias of a floating-point type. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to set. + <dt><em>size_t</em> <code>ebias</code> + <dd>Exponent bias value. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetNorm">H5Tget_norm</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_norm_t </em><code>H5Tget_norm</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the mantissa normalization of a floating-point + datatype. Valid normalization values are: + <ul> <dl> + <dt>H5T_NORM_IMPLIED + <dd>MSB of mantissa isn't stored, always 1 + <dt>H5T_NORM_MSBSET + <dd>MSB of mantissa is always 1 + <dt>H5T_NORM_NONE + <dd>Mantissa is not normalized + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Non-negative normalization type on success, negative on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetNorm">H5Tset_norm</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_norm</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_norm_t</em> <code>norm</code> + ) +<dt><strong>Description:</strong> + <dd>This function sets the mantissa normalization of a floating-point + datatype. Valid normalization values are: + <ul> <dl> + <dt>H5T_NORM_IMPLIED + <dd>MSB of mantissa isn't stored, always 1 + <dt>H5T_NORM_MSBSET + <dd>MSB of mantissa is always 1 + <dt>H5T_NORM_NONE + <dd>Mantissa is not normalized + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to set. + <dt><em>H5T_norm_t</em> <code>norm</code> + <dd>Mantissa normalization type. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetInpad">H5Tget_inpad</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_pad_t </em><code>H5Tget_inpad</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the internal padding type for unused bits in + floating-point datatypes. + Valid padding values are: + <ul> <dl> + <dt>H5T_PAD_ZERO + <dd>Set background to zeros. + <dt>H5T_PAD_ONE + <dd>Set background to ones. + <dt>H5T_PAD_BACKGROUND + <dd>Leave background alone. + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Non-negative padding type on success, negative on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetInpad">H5Tset_inpad</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_inpad</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_pad_t</em> <code>inpad</code> + ) +<dt><strong>Description:</strong> + <dd>If any internal bits of a floating point type are unused + (that is, those significant bits which are not part of the + sign, exponent, or mantissa) then they will be filled + according to the value of this property. + Valid padding values are: + <ul> <dl> + <dt>H5T_PAD_ZERO + <dd>Set background to zeros. + <dt>H5T_PAD_ONE + <dd>Set background to ones. + <dt>H5T_PAD_BACKGROUND + <dd>Leave background alone. + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to modify. + <dt><em>H5T_pad_t</em> <code>pad</code> + <dd>Padding type. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetCset">H5Tget_cset</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_cset_t </em><code>H5Tget_cset</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the character set type of a string datatype. + Valid character set values are: + <ul> <dl> + <dt>H5T_CSET_ASCII + <dd>Character set is US ASCII + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Non-negative character set type on success, negative on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetCset">H5Tset_cset</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_cset</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_cset_t</em> <code>cset</code> + ) +<dt><strong>Description:</strong> + <dd>HDF5 is able to distinguish between character sets of different + nationalities and to convert between them to the extent possible. + Valid character set values are: + <ul> <dl> + <dt>H5T_CSET_ASCII + <dd>Character set is US ASCII + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to modify. + <dt><em>H5T_cset_t</em> <code>cset</code> + <dd>Character set type. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetStrpad">H5Tget_strpad</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_str_t </em><code>H5Tget_strpad</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the string padding method for a string datatype. + Valid string padding values are: + <ul> <dl> + <dt>H5T_STR_NULL + <dd>Pad with zeros (as C does) + <dt>H5T_STR_SPACE + <dd>Pad with spaces (as FORTRAN does) + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Non-negative string padding type on success, negative on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetStrpad">H5Tset_strpad</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tset_strpad</code>(<em>hid_t </em><code>type_id</code>, + <em>H5T_str_t</em> <code>strpad</code> + ) +<dt><strong>Description:</strong> + <dd>The method used to store character strings differs with the programming + language: C usually null terminates strings while Fortran + left-justifies and space-pads strings. This property defines the + storage mechanism for the string. + Valid string padding values are: + <ul> <dl> + <dt>H5T_STR_NULL + <dd>Pad with zeros (as C does) + <dt>H5T_STR_SPACE + <dd>Pad with spaces (as FORTRAN does) + </dl> </ul> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to modify. + <dt><em>H5T_str_t</em> <code>strpad</code> + <dd>String padding type. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetNmembers">H5Tget_nmembers</a> +<dt><strong>Signature:</strong> + <dd><em>intn </em><code>H5Tget_nmembers</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the number of fields a compound datatype has. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Number of members datatype has on success, negative on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetMemberName">H5Tget_member_name</a> +<dt><strong>Signature:</strong> + <dd><em>char *</em> <code>H5Tget_member_name</code>(<em>hid_t </em><code>type_id</code>, + <em>intn</em> <code>fieldno</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the name of a field of a compound data type. + Fields are stored in no particular order with numbers 0 through N-1 + where N is the value returned by H5Tget_nmembers(). The name of the + field is allocated with malloc() and the caller is responsible for + freeing the memory used by the name. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to query. + <dt><em>intn</em> <code>fieldno</code> + <dd>Field number (indexed from 0) of the field name to retrieve. + </dl> +<dt><strong>Returns:</strong> + <dd>Valid pointer on success, NULL on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetMemberDims">H5Tget_member_dims</a> +<dt><strong>Signature:</strong> + <dd><em>int</em> <code>H5Tget_member_dims</code>(<em>hid_t </em><code>type_id</code>, + <em>intn</em> <code>fieldno</code>, + <em>size_t *</em> <code>dims</code>, + <em>int *</em> <code>perm</code> + ) +<dt><strong>Description:</strong> + <dd>This function returns the dimensionality of the field. The dimensions + and permuation vector are returned through arguments <code>dims</code> + and <code>perm</code>, both arrays of at least four elements. Either + (or even both) may be null pointers. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to query. + <dt><em>intn</em> <code>fieldno</code> + <dd>Field number (indexed from 0) of the field dims to retrieve. + <dt><em>size_t *</em> <code>dims</code> + <dd>Pointer to buffer to store the dimensions of the field. + <dt><em>int *</em> <code>perm</code> + <dd>Pointer to buffer to store the permutation vector of the field. + </dl> +<dt><strong>Returns:</strong> + <dd>Number of dimensions on success, negative on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetMemberType">H5Tget_member_type</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t</em> <code>H5Tget_member_type</code>(<em>hid_t </em><code>type_id</code>, + <em>intn</em> <code>fieldno</code> + ) +<dt><strong>Description:</strong> + <dd>This function returns the data type of the specified member. The caller + should invoke H5Tclose() to release resources associated with the type. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to query. + <dt><em>intn</em> <code>fieldno</code> + <dd>Field number (indexed from 0) of the field type to retrieve. + </dl> +<dt><strong>Returns:</strong> + <dd>The ID of a copy of the datatype of the field, negative on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Insert">H5Tinsert</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Tinsert</code>(<em>hid_t </em><code>type_id</code>, + <em>const char *</em> <code>name</code>, + <em>off_t</em> <code>offset</code>, + <em>hid_t</em> <code>field_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function adds another member to the compound data type + <code>type_id</code>. The new member has a <code>name</code> which + must be unique within the compound data type. The <code>offset</code> + argument defines the start of the member in an instance of the compound + data type, and <code>field_id</code> is the type of the new member. + + <P>Note: All members of a compound data type must be atomic; a + compound data type cannot have a member which is a compound data + type. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of compound datatype to modify. + <dt><em>const char *</em> <code>name</code> + <dd>Name of the field to insert. + <dt><em>off_t</em> <code>offset</code> + <dd>Offset in memory structure of the field to insert. + <dt><em>hid_t</em> <code>field_id</code> + <dd>Datatype ID of the field to insert. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Pack">H5Tpack</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Tpack</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function recursively removes padding from within a compound + datatype to make it more efficient (space-wise) to store that data. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to modify. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-RegisterHard">H5Tregister_hard</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Tregister_hard</code>(<em>const char + *</em> <code>name</code>, <em>hid_t </em><code>src_id</code>, + <em>hid_t</em> <code>dst_id</code>, + <em>H5T_conv_t</em> <code>func</code> + ) +<dt><strong>Description:</strong> + <dd>This function registers a hard conversion function for a data type + conversion path. The path is specified by the source and destination + datatypes <code>src_id</code> and <code>dst_id</code>. A conversion + path can only have one hard function, so <code>func</code> replaces any + previous hard function. + <P>If <code>func</code> is the null pointer then any hard function + registered for this path is removed from this path. The soft functions + are then used when determining which conversion function is appropriate + for this path. The <code>name</code> argument is used only + for debugging and should be a short identifier for the function. + <P>The type of the conversion function pointer is declared as: + typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, + size_t nelmts, void *buf, void *bkg); +<dt><strong>Parameters:</strong> + <dl> + <dt><em>const char *</em> <code>name</code> + <dd>Name displayed in diagnostic output. + <dt><em>hid_t</em> <code>src_id</code> + <dd>ID of source datatype. + <dt><em>hid_t</em> <code>dst_id</code> + <dd>ID of destination datatype. + <dt><em>H5T_conv_t</em> <code>func</code> + <dd>Function to convert between source and destination datatypes. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-RegisterSoft">H5Tregister_soft</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Tregister_soft</code>(<em>const char + *</em> <code>name</code>, <em>hid_t </em><code>src_id</code>, + <em>hid_t</em> <code>dst_id</code>, + <em>H5T_conv_t</em> <code>func</code> + ) +<dt><strong>Description:</strong> + <dd>This function registers a soft conversion function by adding it to the + end of the master soft list and replacing the soft function in all + applicable existing conversion paths. The <code>name</code> + is used only for debugging and should be a short identifier + for the function. + <P>The type of the conversion function pointer is declared as: + typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, + size_t nelmts, void *buf, void *bkg); +<dt><strong>Parameters:</strong> + <dl> + <dt><em>const char *</em> <code>name</code> + <dd>Name displayed in diagnostic output. + <dt><em>hid_t</em> <code>src_id</code> + <dd>ID of source datatype. + <dt><em>hid_t</em> <code>dst_id</code> + <dd>ID of destination datatype. + <dt><em>H5T_conv_t</em> <code>func</code> + <dd>Function to convert between source and destination datatypes. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Unregister">H5Tunregister</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Tunregister</code>(<em>H5T_conv_t</em> <code>func</code> + ) +<dt><strong>Description:</strong> + <dd>This function removes a conversion function from all conversion paths. + <P>The type of the conversion function pointer is declared as: + typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, + size_t nelmts, void *buf, void *bkg); +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5T_conv_t</em> <code>func</code> + <dd>Function to remove from conversion paths. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Close">H5Tclose</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Tclose</code>(<em>hid_t </em><code>type_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function releases a datatype. Further access through the datatype + ID is illegal. Failure to release a datatype with this call will + result in resource leaks. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>type_id</code> + <dd>ID of datatype to release. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + + + +<hr> +<hr> +</b>UNUSED PORTIONS OF EMAIL NOTES.</b> +<br> +<code>....</code> in left margin indicates where material was + pulled out for inclusion above. +<HR> +<HR> +<pre> + +Elena> Datatype Interface: +Elena> Do we have description of the named datatypes somewhere? + +>From Datatypes.html... + +html> 7. Sharing Data Types among Datasets +html> +html> If a file has lots of datasets which have a common data type +html> then the file could be made smaller by having all the datasets +html> share a single data type. Instead of storing a copy of the data +html> type in each dataset object header, a single data type is stored +html> and the object headers point to it. The space savings is +html> probably only significant for datasets with a compound data type +html> since the simple data types can be described with just a few +html> bytes anyway. +html> +html> To create a bunch of datasets that share a single data type just +html> create the datasets with a committed (named) data type. +html> +html> To create two datasets that share a common data type one just +html> commits the data type, giving it a name, and then uses that +html> data type to create the datasets. +html> +html> hid_t t1 = ...some transient type...; +html> H5Tcommit (file, "shared_type", t1); +html> hid_t dset1 = H5Dcreate (file, "dset1", t1, space, H5P_DEFAULT); +html> hid_t dset2 = H5Dcreate (file, "dset2", t1, space, H5P_DEFAULT); +html> +html> +html> And to create two additional datasets later which share the +html> same type as the first two datasets: +html> +html> hid_t dset1 = H5Dopen (file, "dset1"); +html> hid_t t2 = H5Dget_type (dset1); +html> hid_t dset3 = H5Dcreate (file, "dset3", t2, space, H5P_DEFAULT); +html> hid_t dset4 = H5Dcreate (file, "dset4", t2, space, H5P_DEFAULT); +html> +html> +html> Example: Shared Types + +Mail from Quincey summarizing shared data types: + +Quincey> Hi Robb, +Quincey> Everything looks good, I just have a couple of minor comments below: +Quincey> +Quincey> > A very quick data types summary (so I can remember it next week :-) +Quincey> > +Quincey> > * Handles to named types are immutable. +Quincey> > +Quincey> > * A transient type handle can be converted to a named type handle +Quincey> > by calling H5Tcommit(). This can only be called for transient +Quincey> > types which are not locked or predefined. +Quincey> > +Quincey> > * H5Topen() returns a handle to a named immutable type. +Quincey> > +Quincey> > * H5Tcopy() returns a handle to a transient type. +Quincey> H5Tcreate also returns a handle to a transient type. +Quincey> +Quincey> > * Using a named type in H5Dcreate() causes the dataset object +Quincey> > header to point to the named type (shared). The link count on +Quincey> > the named type is incremented. +Quincey> > +Quincey> > * Using a transient type in H5Dcreate() causes the type to be +Quincey> > copied and stored in the dataset header (unshared). +Quincey> > +Quincey> > * Type handles returned from H5Dget_type() are immutable. +Quincey> > +Quincey> > * If the dataset is using a shared type (dataset object header +Quincey> > points to some other object header with a type message, e.g., a +Quincey> > named type) then H5Dget_type() returns a handle to that named +Quincey> > type. +Quincey> > +Quincey> > * If the dataset has a private type (data type is stored in the +Quincey> > dataset object header) then H5Dget_type() returns a handle to a +Quincey> > transient immutable type. +Quincey> > +Quincey> > * The name of a data type can be removed from a group, but unless +Quincey> > the reference count becomes zero the type continues to exist. +Quincey> > (Other objects work this way too). +Quincey> > +Quincey> > * H5Tcopy() applied to a dataset returns a transient, modifiable +Quincey> > copy of that dataset's data type. +Quincey> > +Quincey> > * H5Topen() applied to a dataset returns either a transient +Quincey> > immutable or named immutable data type depending on whether the +Quincey> > dataset has a shared data type. +Quincey> Hmm, do we want to allow this? It makes a certain amount of sense, but +Quincey> is a little unusual... :-) +Quincey> + +Elena, we decided not not to allow H5Topen() on a dataset. + +Quincey> +Quincey> > * The H5Tshare() and H5Tis_shared() will be removed. Data types +Quincey> > will not be stored in the global heap. A new type of shared +Quincey> > message header will be added to the object headers that points to +Quincey> > another object header instead of the global heap +Quincey> +Quincey> > * Still to discuss: Attributes on named data types? +Quincey> I think we should all them. +Quincey> + +Elena, attributes work for named data types just like they do for +datasets. + +Quincey> +Quincey> > * Still to discuss: compound types whose members point to other types. +Quincey> I like this concept a lot and this we should figure out a way to do it. +Quincey> This allows the "is a" relationship to be used very nicely for named datatypes. +Quincey> +Quincey> > * Still to discuss: datasets that point to data types in other +Quincey> > files by symbolic link. +Quincey> Probably a good idea also, just ugly to implement. +Quincey> + +</pre> +<hr> +<hr> + + + + +<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: 29 June 1998 + +</body> +</html> diff --git a/doc/src/RM_H5Z.html b/doc/src/RM_H5Z.html new file mode 100644 index 0000000..a5ef92c --- /dev/null +++ b/doc/src/RM_H5Z.html @@ -0,0 +1,93 @@ +<html> +<head><title> +HDF5/H5Z Draft API Specification +</title></head> + +<body> + +<center> +<h1>H5Z: Compression Interface</h1> +</center> + +<h2>Compression API Functions</h2> + +This function enable the user to configure a new compression +method for the local environment. + +<table border=0> +<tr><td valign=top> +<ul> + <li><a href="#Compression-Register">H5Zregister</a> +</ul> +</td><td> </td><td valign=top> +<ul> + +</ul> +</td></tr> +</table> + +<p> +HDF5 supports compression of raw data by compression methods +built into the library or defined by an application. +A compression method is associated with a dataset when the dataset is +created and is applied independently to each storage chunk of the dataset. +The dataset must use the <code>H5D_CHUNKED</code> storage layout. +<p> +The HDF5 library does not support compression for contiguous datasets +because of the difficulty of implementing random access for partial I/O. +Compact dataset compression is not supported because it would not produce +significant results. +<p> +See <a href="../UG/Compression.html"><cite>Compression</cite></a> in the +<cite>HDF5 User's Guide</cite> for further information. + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Compression-Register">H5Zregister</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Zregister</code>(<em>H5Z_method_t</em> <code>method</code>, + <em>const char *</em><code>name</code>, + <em>H5Z_func_t</em><code>cfunc</code>, + <em>H5Z_func_t</em> <code>ufunc</code> + ) +<dt><strong>Purpose:</strong> + <dd> Registers new compression and uncompression functions for a + method specified by a method number. +<dt><strong>Description:</strong> + <dd><code>H5Zregister</code> registers new compression and uncompression + functions for a method specified by a method number, <code>method</code>. + <code>name</code> is used for debugging and may be the null pointer. + Either or both of <code>cfunc</code> (the compression function) and + <code>ufunc</code> (the uncompression method) may be null pointers. + <p> + The statistics associated with a method number are not reset + by this function; they accumulate over the life of the library. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5Z_method_t</em> <code>method</code> + <dd>Number specifying compression method. + <dt><em>const char *</em><code>name</code> + <dd>Name associated with the method number. + <dt><em>H5Z_func_t</em> <code>cfunc</code> + <dd>Compression method. + <dt><em>H5Z_func_t</em> <code>ufunc</code> + <dd>Uncompression method. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise 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> |