diff options
| -rw-r--r-- | doc/src/RM_H5A.html | 355 | ||||
| -rw-r--r-- | doc/src/RM_H5E.html | 212 | ||||
| -rw-r--r-- | doc/src/RM_H5F.html | 9 | ||||
| -rw-r--r-- | doc/src/RM_H5T.html | 534 |
4 files changed, 735 insertions, 375 deletions
diff --git a/doc/src/RM_H5A.html b/doc/src/RM_H5A.html index a6738e4..a3b46c1 100644 --- a/doc/src/RM_H5A.html +++ b/doc/src/RM_H5A.html @@ -39,6 +39,23 @@ and information about attributes. </td></tr> </table> +<p> +The Attribute interface, H5A, is primarily designed to easily allow +small datasets to be attached to primary datasets as metadata information. +Additional goals for the H5A interface include keeping storage requirement +for each attribute to a minimum and easily sharing attributes among +datasets. +<p> +Because attributes are intended to be small objects, large datasets +intended as additional information for a primary dataset should be +stored as supplemental datasets in a group with the primary dataset. +Attributes can then be attached to the group containing everything +to indicate a particular type of dataset with supplemental datasets +is located in the group. How small is "small" is not defined by the +library and is up to the user's interpretation. +<p> +See <a href="Attributes.html"><cite>Attributes</cite></a> in the +<cite>HDF5 User's Guide</cite> for further information. <hr> <dl> @@ -46,58 +63,42 @@ and information about attributes. <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>type_id</code>, + <em>hid_t</em> <code>space_id</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. + <dd>Creates a dataset as an attribute of another group, dataset, + or named datatype. <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> + <dd><code>H5Acreate</code> creates an attribute which is attached + to the object specified with <code>loc_id</code>. + <code>loc_id</code> is an identifier of a group, dataset, + or named datatype. The name specified with <code>name</code> + for each attribute for an object must be unique for that object. + The datatype and dataspace identifiers of the attribute, + <code>type_id</code> and <code>space_id</code>, respectively, + are created with the H5T and H5S interfaces, respectively. + Currently only simple dataspaces are allowed for attribute + dataspaces. The <code>create_plist_id</code> 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 <code>H5Aclose</code> 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. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>loc_id</code> - <dd>IN: Object (dataset or group) to be attached to + <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 + <dd>IN: Name of attribute to create. + <dt><em>hid_t</em> <code>type_id</code> + <dd>IN: Identifier of datatype for attribute. + <dt><em>hid_t</em> <code>space_id</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) + <dd>IN: Identifier of creation property list (currently not used). </dl> <dt><strong>Returns:</strong> <dd>Returns an attribute identifier if successful; @@ -113,26 +114,23 @@ and information about attributes. <em>const char *</em><code>name</code> ) <dt><strong>Purpose:</strong> - <dd> Opens an attribute for an object by looking up the attribute name. + <dd> Opens an attribute specified by 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. + <dd><code>H5Aopen_name</code> opens an attribute specified by + its name, <code>name</code>, which is attached to the + object specified with <code>loc_id</code>. + The location object may be either a group, dataset, or + named datatype, which may have any sort of attribute. + The attribute identifier returned from this function must + be released with <code>H5Aclose</code> 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 + <dd>IN: Identifier of a group, dataset, or named datatype + atttribute to be attached to. <dt><em>const char *</em><code>name</code> - <dd>IN: Name of attribute to locate and open + <dd>IN: Attribute name. </dl> <dt><strong>Returns:</strong> <dd>Returns attribute identifier if successful; @@ -148,27 +146,24 @@ and information about attributes. <em>unsigned int</em> <code>idx</code> ) <dt><strong>Purpose:</strong> - <dd>Opens the <i>n</i>th attribute for an object. + <dd>Opens the attribute specified by its index. <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. + <dd><code>H5Aopen_idx</code> opens an attribute which is attached + to the object specified with <code>loc_id</code>. + The location object may be either a group, dataset, or + named datatype, all of which may have any sort of attribute. + The attribute specified by the index, <code>idx</code>, + indicates the attribute to access. + The value of <code>idx</code> is a 0-based, non-negative integer. + The attribute identifier returned from this function must be + released with <code>H5Aclose</code> 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 + <dd>IN: Identifier of the group, dataset, or named datatype + attribute to be attached to. <dt><em>unsigned int</em> <code>idx</code> - <dd>IN: Index (0-based) attribute to open + <dd>IN: Index of the attribute to open. </dl> <dt><strong>Returns:</strong> <dd>Returns attribute identifier if successful; @@ -181,29 +176,24 @@ and information about attributes. <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>hid_t</em> <code>mem_type_id</code>, <em>void *</em><code>buf</code> ) <dt><strong>Purpose:</strong> - <dd>Write out data to an attribute. + <dd>Writes 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> + <dd><code>H5Awrite</code> writes an attribute, specified with + <code>attr_id</code>. The attribute's memory datatype + is specified with <code>mem_type_id</code>. The entire + attribute is written from <code>buf</code> to the file. <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 + <dd>IN: Identifier of an attribute to write. + <dt><em>hid_t</em> <code>mem_type_id</code> + <dd>IN: Identifier of the attribute datatype (in memory). <dt><em>void *</em><code>buf</code> - <dd>IN: Buffer of data to write + <dd>IN: Data to be written. </dl> <dt><strong>Returns:</strong> <dd>Returns SUCCEED (0) if successful; @@ -216,29 +206,24 @@ and information about attributes. <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>hid_t</em> <code>mem_type_id</code>, <em>void *</em><code>buf</code> ) <dt><strong>Purpose:</strong> - <dd>Read in data from an attribute. + <dd>Reads 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> + <dd><code>H5Aread</code> reads an attribute, specified with + <code>attr_id</code>. The attribute's memory datatype + is specified with <code>mem_type_id</code>. The entire + attribute is read into <code>buf</code> from the file. <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 + <dd>IN: Identifier of an attribute to read. + <dt><em>hid_t</em> <code>mem_type_id</code> + <dd>IN: Identifier of the attribute datatype (in memory). <dt><em>void *</em><code>buf</code> - <dd>IN: Buffer for data to read + <dd>IN: Buffer for data to be read. </dl> <dt><strong>Returns:</strong> <dd>Returns SUCCEED (0) if successful; @@ -254,19 +239,17 @@ and information about attributes. <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 + <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 <code>H5Sclose</code> 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 + <dd>IN: Identifier of an attribute. </dl> <dt><strong>Returns:</strong> - <dd>Returns dataspace identifier if successful; + <dd>Returns attribute dataspace identifier if successful; otherwise FAIL (-1). </dl> @@ -277,18 +260,22 @@ and information about attributes. <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. + <dd>Gets an attribute datatype. <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. + <dd><code>H5Aget_type</code> retrieves a copy of the datatype + for an attribute. <p> - <i>(Identical desc in UG and SC.)</i> + The datatype is reopened if it is a named type before returning + it to the application. The datatypes returned by this function + are always read-only. If an error occurs when atomizing the + return datatype, then the datatype is closed. <p> + The datatype identifier returned from this function must be + released with <code>H5Tclose</code> or resource leaks will develop. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>attr_id</code> - <dd>IN: Attribute to get datatype of + <dd>IN: Identifier of an attribute. </dl> <dt><strong>Returns:</strong> <dd>Returns a datatype identifier if successful; @@ -305,24 +292,23 @@ and information about attributes. <em>size_t</em> <code>buf_size</code> ) <dt><strong>Purpose:</strong> - <dd>Gets a copy of the name for an attribute. + <dd>Gets an attribute name. <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> + <dd><code>H5Aget_name</code> retrieves the name of an attribute + specified by the identifier, <code>attr_id</code>. + Up to <code>buf_size</code> characters are stored in + <code>buf</code> followed by a <code>\0</code> string + terminator. If the name of the attribute is longer than + <code>buf_size</code> -1, the string terminator is stored in the + last position of the buffer to properly terminate the string. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>attr_id</code> - <dd>IN: Attribute to get name of + <dd>IN: Identifier of the attribute. <dt><em>char *</em><code>buf</code> - <dd>IN: Buffer to store name in + <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 + <dd>IN: The size of the buffer to store the name in. </dl> <dt><strong>Returns:</strong> <dd>Returns the length of the attribute's name, which may be @@ -339,15 +325,14 @@ and information about attributes. <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> + <dd><code>H5Anum_attrs</code> returns the number of attributes + attached to the object specified by its identifier, + <code>loc_id</code>. + The object can be a group, dataset, or named datatype. <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 + <dd>IN: Identifier of a group, dataset, or named datatype. </dl> <dt><strong>Returns:</strong> <dd>Returns the number of attributes if successful; @@ -360,49 +345,37 @@ and information about attributes. <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>unsigned *</em> <code>idx</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. + <dd><code>H5Aiterate</code> iterates over the attributes of + the object specified by its identifier, <code>loc_id</code>. + The object can be a group, dataset, or named datatype. + For each attribute of the object, the <code>op_data</code> + and some additional information specified below are passed + to the operator function <code>op</code>. + The iteration begins with the attribute specified by its + index, <code>idx</code>; the index for the next attribute + to be processed by the operator, <code>op</code>, is + returned in <code>idx</code>. + If <code>idx</code> is the null pointer, then all attributes + are processed. <p> - The prototype for H5A_operator_t is: <br> + The prototype for <code>H5A_operator_t</code> 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> + 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: + The operation receives the identifier for the group, dataset + or named datatype being iterated over, <code>loc_id</code>, the + name of the current attribute about the object, <code>attr_name</code>, + and the pointer to the operator data passed in to <code>H5Aiterate</code>, + <code>op_data</code>. The return values from an operator are: <ul> <li>Zero causes the iterator to continue, returning zero when all attributes have been processed. @@ -413,15 +386,12 @@ and information about attributes. 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 + <dd>IN: Identifier of a group, dataset or named datatype. + <dt><em>unsigned *</em> <code>idx</code> + <dd>IN/OUT: Starting (IN) and ending (OUT) attribute index. <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> @@ -444,22 +414,19 @@ and information about attributes. <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. + <dd><code>H5Adelete</code> removes the attribute specified by its + name, <code>name</code>, from a dataset, group, or named datatype. + This function should not be used when attribute identifiers are + open on <code>loc_id</code> as it may cause the internal indexes + of the attributes to change and future writes to the open + attributes to produce incorrect results. <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 + <dd>IN: Identifier of the dataset, group, or named datatype + to have the attribute deleted from. <dt><em>const char *</em><code>name</code> - <dd>IN: Name of attribute to delete + <dd>IN: Name of the attribute to delete. </dl> <dt><strong>Returns:</strong> <dd>Returns SUCCEED (0) if successful; @@ -473,18 +440,16 @@ and information about attributes. <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. + <dd>Closes the specified attribute. <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. + <dd><code>H5Aclose</code> terminates access to the attribute + specified by its identifier, <code>attr_id</code>. + Further use of the attribute identifier will result in + undefined behavior. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>attr_id</code> - <dd>IN: Attribute to release access to + <dd>IN: Attribute to release access to. </dl> <dt><strong>Returns:</strong> <dd>Returns SUCCEED (0) if successful; diff --git a/doc/src/RM_H5E.html b/doc/src/RM_H5E.html index 0065e90..4c70b6a 100644 --- a/doc/src/RM_H5E.html +++ b/doc/src/RM_H5E.html @@ -12,30 +12,6 @@ HDF5/H5E Draft API Specification <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> @@ -58,6 +34,32 @@ errors within the H5E package. </td></tr> </table> +<p> +The Error interface provides error handling in the form of a stack. +The <code>FUNC_ENTER()</code> macro clears the error stack whenever +an interface 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 <code>H5Eprint()</code>, +do not clear the error stack. Otherwise, any function which +does not have an underscore immediately after the package name +will clear the error stack. For instance, <code>H5Fopen()</code> +clears the error stack while <code>H5F_open()</code> 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. + <hr> <dl> @@ -69,34 +71,19 @@ errors within the H5E package. <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), + <dd><code>H5Eset_auto</code> turns on or off automatic printing of + errors. When turned on (non-null <code>func</code> pointer), any API function which returns an error indication will first call <code>func</code>, passing it <code>client_data</code> as an argument. <p> - 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> + When the library is first initialized the auto printing function + is set to <code>H5Eprint()</code> (cast appropriately) and + <code>client_data</code> is the standard error stream pointer, + <code>stderr</code>. <p> + Automatic stack traversal is always in the + <code>H5E_WALK_DOWNWARD</code> direction. <dt><strong>Parameters:</strong> <dl> <dt><em>H5E_auto_t</em> <code>func</code> @@ -121,14 +108,10 @@ errors within the H5E package. <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. + <dd><code>H5Eget_auto</code> returns the current settings for the + automatic error stack traversal function, <code>func</code>, + and its data, <code>client_data</code>. Either (or both) + arguments may be null in which case the value is not returned. <dt><strong>Parameters:</strong> <dl> <dt><em>H5E_auto_t *</em> <code>func</code> @@ -151,19 +134,16 @@ errors within the H5E package. <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. + <dd><code>H5Eclear</code> clears the error stack for the current thread. <p> - This function can fail if there are problems initializing the library. + The stack is also cleared whenever an API function is called, + with certain exceptions (for instance, <code>H5Eprint()</code>). <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>). + <code>H5Eclear</code> can fail if there are problems initializing + the library. <dt><strong>Parameters:</strong> <dl> - <dt><em>paramtype</em> <code>param</code> - <dd>xxx - <dt><i>Should this say "None"?</i> + <dt>None </dl> <dt><strong>Returns:</strong> <dd>Returns SUCCEED (0) if successful; @@ -179,18 +159,19 @@ errors within the H5E package. <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. + <dd><code>H5Eprint</code> prints the error stack on the specified + stream, <code>stream</code>. + Even if the error stack is empty, a one-line message will be printed: + <br> + <code>HDF5-DIAG: Error detected in thread 0.</code> <p> - 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> + <code>H5Eprint</code> is a convenience function for + <code>H5Ewalk()</code> with a function that prints error messages. + Users are encouraged to write there own more specific error handlers. <dt><strong>Parameters:</strong> <dl> <dt><em>FILE *</em> <code>stream</code> - <dd>xxx + <dd>File pointer, or stderr if NULL. </dl> <dt><strong>Returns:</strong> <dd>Returns SUCCEED (0) if successful; @@ -210,7 +191,7 @@ errors within the H5E package. <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 + <dd><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 @@ -222,22 +203,13 @@ errors within the H5E package. 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 + Its 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>. + <code>H5Ewalk</code> can fail if there are problems initializing + the library. <dt><strong>Parameters:</strong> <dl> <dt><em>H5E_direction_t</em> <code>direction</code> @@ -265,26 +237,26 @@ errors within the H5E package. <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. + <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. + argument to the <code>H5Ewalk()</code> function. + This function is called also by <code>H5Eprint()</code>. + 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). + <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 + <code>err_desc</code> 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). + <code>client_data</code> is the same pointer that was passed as the + <code>client_data</code> argument of <code>H5Ewalk()</code>. + It is expected to be a file pointer (or stderr if null). <dt><strong>Parameters:</strong> <dl> <dt><em>int</em> <code>n</code> @@ -293,7 +265,7 @@ errors within the H5E package. <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. + <dd>A file pointer, or stderr if null. </dl> <dt><strong>Returns:</strong> <dd>Returns SUCCEED (0) if successful; @@ -307,27 +279,18 @@ errors within the H5E package. <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. + <dd>Returns a character string describing an error specified by a + major error number. <dt><strong>Description:</strong> - <dd>Given a major error number, H5Eget_major returns a constant character string - that describes the error. + <dd>Given a major error number, <code>H5Eget_major</code> returns a + constant character string that describes the error. <dt><strong>Parameters:</strong> <dl> <dt><em>H5E_major_t</em> <code>n</code> <dd>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. + <dd> Returns a character string describing the error if successful. Otherwise returns "Invalid major error number." </dl> @@ -338,27 +301,18 @@ errors within the H5E package. <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. + <dd>Returns a character string describing an error specified by a + minor error number. <dt><strong>Description:</strong> - <dd>Given a minor error number, H5Eget_minor returns a constant character string - that describes the error. + <dd>Given a minor error number, <code>H5Eget_minor</code> returns a + constant character string that describes the error. <dt><strong>Parameters:</strong> <dl> <dt><em>H5E_minor_t</em> <code>n</code> <dd>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. + <dd> Returns a character string describing the error if successful. Otherwise returns "Invalid minor error number." </dl> diff --git a/doc/src/RM_H5F.html b/doc/src/RM_H5F.html index 912df51..f8e25f4 100644 --- a/doc/src/RM_H5F.html +++ b/doc/src/RM_H5F.html @@ -24,11 +24,12 @@ documented below. </td><td> </td><td valign=top> <ul> <li><a href="#File-IsHDF5">H5Fis_hdf5</a> - <li><a href="#File-GetCreateTemplate">H5Fget_create_template</a> + <li><a href="#File-Close">H5Fclose</a> </ul> </td><td> </td><td valign=top> <ul> - <li><a href="#File-Close">H5Fclose</a> + <li><a href="#File-GetCreateTemplate">H5Fget_create_template</a> + <li><a href="#File-GetAccessTemplate">H5Fget_access_template</a> </ul> </td></tr> </table> @@ -70,8 +71,8 @@ documented below. 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 + <dd>A file identifier if successful; + otherwise FAIL (-1). </dl> <hr> diff --git a/doc/src/RM_H5T.html b/doc/src/RM_H5T.html index 46fe6fc..4221e93 100644 --- a/doc/src/RM_H5T.html +++ b/doc/src/RM_H5T.html @@ -17,6 +17,17 @@ of a dataset. <table border=0> <tr><td valign=top> <ul> + <li><a href="#Datatype-Open">H5Topen</a> + <li><a href="#Datatype-Commit">H5Tcommit</a> + <li><a href="#Datatype-Committed">H5Tcommitted</a> + <li><a href="#Datatype-InsertArray">H5Tinsert_array</a> + <li><a href="#Datatype-Share">H5Tshare</a> + <li><a href="#Datatype-Find">H5Tfind</a> + <li><a href="#Datatype-Convert">H5Tconvert</a> + <li><a href="#Datatype-SetOverflow">H5Tset_overflow</a> + <li><a href="#Datatype-GetOverflow">H5Tget_overflow</a> + <li> + <li><a href="#Datatype-Create">H5Tcreate</a> <li><a href="#Datatype-Copy">H5Tcopy</a> <li><a href="#Datatype-Equal">H5Tequal</a> @@ -67,16 +78,321 @@ of a dataset. </td></tr> </table> +<p> +The Datatype interface, H5T, provides a mechanism to describe the + storage format of individual data points of a data set and is + hopefully designed in such a way as to allow new features to be + easily added without disrupting applications that use the data + type interface. A dataset (the H5D interface) is composed of a + collection or raw data points of homogeneous type organized + according to the data space (the H5S interface). + +<p> +A data type is a collection of data type properties, all of + which can be stored on disk, and which when taken as a whole, + provide complete information for data conversion to or from that + data type. The interface provides functions to set and query + properties of a data type. + +<p> +A <em>data point</em> is an instance of a <em>datatype</em>, + which is an instance of a <em>type class</em>. We have defined + a set of type classes and properties which can be extended at a + later time. The atomic type classes are those which describe + types which cannot be decomposed at the data type interface + level; all other classes are compound. + +<p> +See <a href="Datatypes.html"><cite>The Datatype Interface (H5T)</cite></a> +in the <cite>HDF5 User's Guide</cite> for further information. + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Open">H5Topen</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t</em><code>H5Topen</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em> <code>name</code> + ) +<dt><strong>Purpose:</strong> + <dd>Opens a named datatype. +<dt><strong>Description:</strong> + <dd><b>From UG:</b> <code>H5Topen</code> opens a named datatype at the location + specified by <code>loc_id</code> and returns an identifier + for the data type. The identifier should eventually be closed + by calling <code>H5Tclose()</code> to release resources. + <code>loc_id</code> is either a file or group identifier. + <p> + <b>From SC:</b> Opens a named datatype. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>A file or group identifier. + <dt><em>const char *</em> <code>name</code> + <dd>A datatype name. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a named datatype identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Commit">H5Tcommit</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em><code>H5Tcommit</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em> <code>name</code>, + <em>hid_t</em> <code>type</code> + ) +<dt><strong>Purpose:</strong> + <dd>Commits a transient datatype to a file, creating a new named datatype. +<dt><strong>Description:</strong> + <dd><b>From UG:</b> <code>H5Tcommit</code> commits a transient datatype (not immutable) + to a file, turned it into a named datatype. The <code>loc_id</code> + is either a file or group identifier which, when combined with + <code>name</code>, refers to a new named data type. + <p> + <b>From SC:</b> Saves a transient data type to a file and turns + the type identifier into a named, immutable type. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>A file or group identifier. + <dt><em>const char *</em> <code>name</code> + <dd>A datatype name. + <dt><em>hid_t</em> <code>type</code> + <dd>A datatype identifier. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Committed">H5Tcommitted</a> +<dt><strong>Signature:</strong> + <dd><em>hbool_t</em><code>H5Tcommitted</code>(<em>hid_t</em> <code>type</code>) +<dt><strong>Purpose:</strong> + <dd>Determines whether a datatype is a named type or a transient type. +<dt><strong>Description:</strong> + <dd><b>From UG:</b> <code>H5Tcommitted</code> queries a type to determine whether + it is a named type or a transient type. If this function returns + a positive value, then the type is named (that is, it has been + committed, perhaps by some other application). Datasets which + return committed data types with <code>H5Dget_type()</code> are + able to share the data type with other datasets in the same file. + <p> + <b>From SC:</b> Determines whether a data type is committed. +<dt><strong>Parameters:</strong> + <dl> + <dt>hid_t</em> <code>type</code> + <dd>Datatype identifier. + </dl> +<dt><strong>Returns:</strong> + <dd><b>From UG:</b> Returns a datatype identifier if successful; + otherwise FAIL (-1). + <dd><b>From SC:</b> The successful returns values are TRUE if committed, + else FALSE. Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-InsertArray">H5Tinsert_array</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em><code>H5Tinsert_array</code>(<em>hid_t</em> <code>parent_id</code>, + <em>const char *</em><code>name</code>, + <em>size_t</em> <code>offset</code>, + <em>int</em> <code>ndims</code>, + <em>const size_t *</em><code>dim</code>, + <em>const int *</em><code>perm</code>, + <em>hid_t</em> <code>member_id</code> + ) +<dt><strong>Purpose:</strong> + <dd>Adds a new member to a compound data type. +<dt><strong>Description:</strong> + <dd><b>From SC:</b> <code>H5Tinsert_array</code> adds a new member to the + compound data type <code>parent_id</code>. The new member's name, + <code>name</code>, 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>member_id</code> is the type of the new member. + The member is an array with <code>ndims</code> dimensionality + and the size of the array is </em><code>dim</code>. + The total member size should be relatively small +<dt><strong>Parameters:</strong> + <dl> + <dt>hid_t</em> <code>parent_id</code> + <dd> + <dt><em>const char *</em><code>name</code> + <dd> + <dt><em>size_t</em> <code>offset</code> + <dd> + <dt><em>int</em> <code>ndims</code> + <dd> + <dt><em>const size_t *</em><code>dim</code> + <dd> + <dt><em>const int *</em><code>perm</code> + <dd> + <dt><em>hid_t</em> <code>member_id</code> + <dd> + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Find">H5Tfind</a> +<dt><strong>Signature:</strong> + <dd><em>H5T_conv_t</em> <code>H5Tfind</code>(<em>hid_t</em> <code>src_id</code>, + <em>hid_t</em> <code>dst_id</code>, + <em>H5T_cdata_t **</em><code>pcdata</code> + ) +<dt><strong>Purpose:</strong> + <dd>Finds a conversion function. +<dt><strong>Description:</strong> + <dd><b>From SC:</b> <code>H5Tfind</code> finds a conversion function + that can handle a conversion from type <code>src_id</code> to + type <code>dst_id</code>. + The <code>pcdata</code> argument is a pointer + to a pointer to type conversion data which was created and + initialized by the soft type conversion function of this path + when the conversion function was installed on the path. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>src_id</code> + <dd> + <dt><em>hid_t</em> <code>dst_id</code> + <dd> + <dt><em>H5T_cdata_t **</em><code>pcdata</code> + <dd> + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a pointer to a suitable conversion function if successful. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-Convert">H5Tconvert</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Tconvert</code>(<em>hid_t</em> <code>src_id</code>, + <em>hid_t</em> <code>dst_id</code>, + <em>size_t</em> <code>nelmts</code>, + <em>void *</em><code>buf</code>, + <em>void *</em><code>background</code> + ) +<dt><strong>Purpose:</strong> + <dd>Converts data from between specified datatypes. +<dt><strong>Description:</strong> + <dd><b>From SC:</b> Convert <code>nelmts</code> elements from type + <code>src_id</code> to type <code>dst_id</code>. + The source elements are packed in <code>buf</code> and on return + the destination will be packed in <code>buf</code>. + That is, the conversion is performed in place. + The optional background buffer is an array of <code>nelmts</code> + values of destination type which are merged with the converted + values to fill in cracks (for instance, <code>background</code> + might be an array of structs with the <code>a</code> and + <code>b</code> fields already initialized and the conversion + of <code>buf</code> supplies the <code>c</code> and <code>d</code> + field values). +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>src_id</code> + <dd> + <dt><em>hid_t</em> <code>dst_id</code> + <dd> + <dt><em>size_t</em> <code>nelmts</code> + <dd> + <dt><em>void *</em><code>buf</code> + <dd> + <dt><em>void *</em><code>background</code> + <dd> + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + <hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-SetOverflow">H5Tset_overflow</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Tset_overflow</code>(<em>H5T_overflow_t</em> <code>func</code>) +<dt><strong>Purpose:</strong> + <dd>Sets the overflow handler to a specified function. +<dt><strong>Description:</strong> + <dd><b>From SC:</b> <code>H5Tset_overflow</code> sets the overflow handler + to be the function specified by <code>func</code>. + <code>func</code> will be called for all data type conversions that + result in an overflow. + <p> + See the definition of <code>H5T_overflow_t</code> in + <code>H5Tpublic.h</code> for documentation + of arguments and return values. + The prototype for <code>H5T_overflow_t</code> is as follows:<br> + <code>herr_t (*H5T_overflow_t)(hid_t src_id, hid_t dst_id, + void *src_buf, void *dst_buf); + </code> + <p> + The NULL pointer may be passed to remove the overflow handler. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5T_overflow_t</em> <code>func</code> + <dd> + </dl> +<dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Datatype-GetOverflow">H5Tget_overflow</a> +<dt><strong>Signature:</strong> + + +H5Tget_overflow () + <dd><em>H5T_overflow_t</em> <code>H5Tget_overflow</code>(<code>void</code>) +<dt><strong>Purpose:</strong> + <dd>Returns a pointer to the current global overflow function. +<dt><strong>Description:</strong> + <dd><b>From SC:</b> <code>H5Tset_overflow</code> returns a pointer + to the current global overflow function. + This is an application-defined function that is called whenever a + data type conversion causes an overflow. +<dt><strong>Parameters:</strong> + <dl> + <dt>None. + </dl> +<dt><strong>Returns:</strong> + <dd>Returns a pointer to an application-defined function if successful. + Otherwise returns NULL; this can happen if no overflow handling + function is registered. +</dl> + + +<hr> <dl> <dt><strong>Name:</strong> <a name="Datatype-Create">H5Tcreate</a> <dt><strong>Signature:</strong> <dd><em>hid_t </em><code>H5Tcreate</code>(<em>H5T_class_t </em><code>class</code>, <em>size_t</em><code>size</code> ) +<dt><strong>Purpose:</strong> + <dd>Creates a new dataype. <dt><strong>Description:</strong> - <dd>This function creates a new dataype of the specified class with the + <dd><code>H5Tcreate</code> 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 @@ -93,14 +409,17 @@ of a dataset. <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>Purpose:</strong> + <dd>Copies an existing datatype. <dt><strong>Description:</strong> - <dd>This function copies an existing datatype. The datatype ID returned + <dd><code>H5Tcopy</code> 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> @@ -154,6 +473,7 @@ of a dataset. <dd>Datatype ID on success, negative on failure. </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Datatype-Equal">H5Tequal</a> @@ -161,9 +481,11 @@ of a dataset. <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>Purpose:</strong> + <dd>Determines whether two datatype identifiers refer to the same datatype. <dt><strong>Description:</strong> - <dd>This function determines if two datatype IDs refer to the same - datatype. + <dd><code>H5Tequal</code> determines whether two datatype identifiers + refer to the same datatype. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id1</code> @@ -175,14 +497,17 @@ of a dataset. <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>Purpose:</strong> + <dd>Locks a type. <dt><strong>Description:</strong> - <dd>This function locks a type, making it read-only and non-destrucible. + <dd><code>H5Tlock</code> 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. @@ -195,14 +520,17 @@ of a dataset. <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>Purpose:</strong> + <dd>Returns the base class of a datatype. <dt><strong>Description:</strong> - <dd>This function returns the base class of a datatype. + <dd><code>H5Tget_class</code> returns the base class of a datatype. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> @@ -212,14 +540,17 @@ of a dataset. <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>Purpose:</strong> + <dd>Returns the size of a datatype. <dt><strong>Description:</strong> - <dd>This function returns the size of a datatype in bytes. + <dd><code>H5Tget_size</code> returns the size of a datatype in bytes. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> @@ -229,6 +560,7 @@ of a dataset. <dd>Positve size in bytes on success, 0 on failure. </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Datatype-SetSize">H5Tset_size</a> @@ -236,8 +568,11 @@ of a dataset. <dd><em>herr_t </em><code>H5Tset_size</code>(<em>hid_t </em><code>type_id</code>, <em>size_t</em><code>size</code> ) +<dt><strong>Purpose:</strong> + <dd>Sets the total size for an atomic data type. <dt><strong>Description:</strong> - <dd>This function sets the total size in bytes for an atomic data type (this + <dd><code>H5Tset_size</code> 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 @@ -257,14 +592,17 @@ of a dataset. <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>Purpose:</strong> + <dd>Returns the byte order of an atomic datatype. <dt><strong>Description:</strong> - <dd>This function returns the byte order of an atomic datatype. + <dd><code>H5Tget_order</code> returns the byte order of an atomic datatype. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> @@ -274,6 +612,7 @@ of a dataset. <dd>Byte order constant on success, negative on failure </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Datatype-SetOrder">H5Tset_order</a> @@ -281,8 +620,10 @@ of a dataset. <dd><em>herr_t </em><code>H5Tset_order</code>(<em>hid_t </em><code>type_id</code>, <em>H5T_order_t</em><code>order</code> ) +<dt><strong>Purpose:</strong> + <dd>Sets the byte ordering of an atomic datatype. <dt><strong>Description:</strong> - <dd>This function sets the byte ordering of an atomic datatype. + <dd><code>H5Tset_order</code> sets the byte ordering of an atomic datatype. Byte orderings currently supported are: <ul> <dl> <dt>H5T_ORDER_LE @@ -303,14 +644,17 @@ of a dataset. <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>Purpose:</strong> + <dd>Returns the precision of an atomic data type. <dt><strong>Description:</strong> - <dd>This function returns the precision of an atomic data type. The + <dd><code>H5Tget_precision</code> 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> @@ -322,6 +666,7 @@ of a dataset. <dd>Number of significant bits on success, 0 on failure </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Datatype-SetPrecision">H5Tset_precision</a> @@ -329,10 +674,12 @@ of a dataset. <dd><em>herr_t </em><code>H5Tset_precision</code>(<em>hid_t </em><code>type_id</code>, <em>size_t</em><code>precision</code> ) +<dt><strong>Purpose:</strong> + <dd>Sets the precision of an atomic data type. <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(). + <dd><code>H5Tset_precision</code> 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. @@ -352,14 +699,17 @@ of a dataset. <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>Purpose:</strong> + <dd>Retrieves the bit offset of the first significant bit. <dt><strong>Description:</strong> - <dd>This function retrieves the bit offset of the first significant bit. + <dd><code>H5Tget_offset</code> 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 @@ -415,6 +765,7 @@ of a dataset. <dd>Positive offset value on success, 0 on failure. </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Datatype-SetOffset">H5Tset_offset</a> @@ -422,8 +773,10 @@ of a dataset. <dd><em>herr_t </em><code>H5Tset_offset</code>(<em>hid_t </em><code>type_id</code>, <em>size_t</em> <code>offset</code> ) +<dt><strong>Purpose:</strong> + <dd>Sets the bit offset of the first significant bit. <dt><strong>Description:</strong> - <dd>This function sets the bit offset of the first significant bit. The + <dd><code>H5Tset_offset</code> 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 @@ -488,6 +841,7 @@ zero. <dd>zero/negative </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Datatype-GetPad">H5Tget_pad</a> @@ -496,8 +850,10 @@ zero. <em>H5T_pad_t *</em> <code>lsb</code>, <em>H5T_pad_t *</em> <code>msb</code> ) +<dt><strong>Purpose:</strong> + <dd>Retrieves the padding type of the least and most-significant bit padding. <dt><strong>Description:</strong> - <dd>This function retrieves the padding type of the least and most-significant + <dd><code>H5Tget_pad</code> retrieves the padding type of the least and most-significant bit padding. Valid types are: <ul> <dl> <dt>H5T_PAD_ZERO @@ -520,6 +876,7 @@ zero. <dd>zero/negative </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Datatype-SetPad">H5Tset_pad</a> @@ -528,8 +885,10 @@ zero. <em>H5T_pad_t</em> <code>lsb</code>, <em>H5T_pad_t</em> <code>msb</code> ) +<dt><strong>Purpose:</strong> + <dd>Sets the least and most-significant bits padding types. <dt><strong>Description:</strong> - <dd>This function sets the least and most-significant bits padding types. + <dd><code>H5Tset_pad</code> sets the least and most-significant bits padding types. <ul> <dl> <dt>H5T_PAD_ZERO <dd>Set background to zeros. @@ -551,14 +910,17 @@ zero. <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>Purpose:</strong> + <dd>Retrieves the sign type for an integer type. <dt><strong>Description:</strong> - <dd>This function retrieves the sign type for an integer type. + <dd><code>H5Tget_sign</code> retrieves the sign type for an integer type. Valid types are: <ul> <dl> <dt>H5T_SGN_NONE @@ -575,6 +937,7 @@ zero. <dd>Non-negative sign type on success, negative on failure </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Datatype-SetSign">H5Tset_sign</a> @@ -582,8 +945,10 @@ zero. <dd><em>herr_t </em><code>H5Tset_sign</code>(<em>hid_t </em><code>type_id</code>, <em>H5T_sign_t</em> <code>sign</code> ) +<dt><strong>Purpose:</strong> + <dd>Sets the sign proprety for an integer type. <dt><strong>Description:</strong> - <dd>This function sets the sign proprety for an integer type. + <dd><code>H5Tset_sign</code> sets the sign proprety for an integer type. <ul> <dl> <dt>H5T_SGN_NONE <dd>Unsigned integer type. @@ -601,6 +966,7 @@ zero. <dd>zero/negative </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Datatype-GetFields">H5Tget_fields</a> @@ -611,8 +977,10 @@ zero. <em>size_t *</em> <code>mpos</code>, <em>size_t *</em> <code>msize</code> ) +<dt><strong>Purpose:</strong> + <dd>Retrieves floating point data type bit field information. <dt><strong>Description:</strong> - <dd>This function retrieves information about the locations of the various + <dd><code>H5Tget_fields</code> 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. @@ -634,6 +1002,7 @@ zero. <dd>zero/negative </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Datatype-SetFields">H5Tset_fields</a> @@ -644,8 +1013,10 @@ zero. <em>size_t</em> <code>mpos</code>, <em>size_t</em> <code>msize</code> ) +<dt><strong>Purpose:</strong> + <dd>Sets locations and sizes of floating point bit fields. <dt><strong>Description:</strong> - <dd>This function sets the locations and sizes of the various floating + <dd><code>H5Tset_fields</code> sets the locations and sizes of the various floating point bit fields. The field positions are bit positions in the significant region of the data type. Bits are numbered with the least significant bit number zero. @@ -669,14 +1040,17 @@ zero. <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>Purpose:</strong> + <dd>Retrieves the exponent bias of a floating-point type. <dt><strong>Description:</strong> - <dd>This function retrieves the exponent bias of a floating-point type. + <dd><code>H5Tget_ebias</code> retrieves the exponent bias of a floating-point type. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> @@ -686,6 +1060,7 @@ zero. <dd>Positive value on success, 0 on failure. </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Datatype-SetEbias">H5Tset_ebias</a> @@ -693,8 +1068,10 @@ zero. <dd><em>herr_t </em><code>H5Tset_ebias</code>(<em>hid_t </em><code>type_id</code>, <em>size_t</em> <code>ebias</code> ) +<dt><strong>Purpose:</strong> + <dd>Sets the exponent bias of a floating-point type. <dt><strong>Description:</strong> - <dd>This function sets the exponent bias of a floating-point type. + <dd><code>H5Tset_ebias</code> sets the exponent bias of a floating-point type. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> @@ -706,14 +1083,17 @@ zero. <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>Purpose:</strong> + <dd>Retrieves mantissa normalization of a floating-point datatype. <dt><strong>Description:</strong> - <dd>This function retrieves the mantissa normalization of a floating-point + <dd><code>H5Tget_norm</code> retrieves the mantissa normalization of a floating-point datatype. Valid normalization values are: <ul> <dl> <dt>H5T_NORM_IMPLIED @@ -732,6 +1112,7 @@ zero. <dd>Non-negative normalization type on success, negative on failure </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Datatype-SetNorm">H5Tset_norm</a> @@ -739,8 +1120,10 @@ zero. <dd><em>herr_t </em><code>H5Tset_norm</code>(<em>hid_t </em><code>type_id</code>, <em>H5T_norm_t</em> <code>norm</code> ) +<dt><strong>Purpose:</strong> + <dd>Sets the mantissa normalization of a floating-point datatype. <dt><strong>Description:</strong> - <dd>This function sets the mantissa normalization of a floating-point + <dd><code>H5Tset_norm</code> sets the mantissa normalization of a floating-point datatype. Valid normalization values are: <ul> <dl> <dt>H5T_NORM_IMPLIED @@ -761,15 +1144,18 @@ zero. <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>Purpose:</strong> + <dd>Retrieves the internal padding type for unused bits in floating-point datatypes. <dt><strong>Description:</strong> - <dd>This function retrieves the internal padding type for unused bits in - floating-point datatypes. + <dd><code>H5Tget_inpad</code> retrieves the internal padding type for + unused bits in floating-point datatypes. Valid padding values are: <ul> <dl> <dt>H5T_PAD_ZERO @@ -788,6 +1174,7 @@ zero. <dd>Non-negative padding type on success, negative on failure </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Datatype-SetInpad">H5Tset_inpad</a> @@ -795,11 +1182,13 @@ zero. <dd><em>herr_t </em><code>H5Tset_inpad</code>(<em>hid_t </em><code>type_id</code>, <em>H5T_pad_t</em> <code>inpad</code> ) +<dt><strong>Purpose:</strong> + <dd>Fills unused internal floating point bits. <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. + sign, exponent, or mantissa), then <code>H5Tset_inpad</code> will be filled + according to the value of the padding value property <code>inpad</code>. Valid padding values are: <ul> <dl> <dt>H5T_PAD_ZERO @@ -820,14 +1209,17 @@ zero. <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>Purpose:</strong> + <dd>Retrieves the character set type of a string datatype. <dt><strong>Description:</strong> - <dd>This function retrieves the character set type of a string datatype. + <dd><code>H5Tget_cset</code> retrieves the character set type of a string datatype. Valid character set values are: <ul> <dl> <dt>H5T_CSET_ASCII @@ -842,6 +1234,7 @@ zero. <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> @@ -849,6 +1242,8 @@ zero. <dd><em>herr_t </em><code>H5Tset_cset</code>(<em>hid_t </em><code>type_id</code>, <em>H5T_cset_t</em> <code>cset</code> ) +<dt><strong>Purpose:</strong> + <dd> <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. @@ -868,14 +1263,17 @@ zero. <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>Purpose:</strong> + <dd>Retrieves the string padding method for a string datatype. <dt><strong>Description:</strong> - <dd>This function retrieves the string padding method for a string datatype. + <dd><code>H5Tget_strpad</code> retrieves the string padding method for a string datatype. Valid string padding values are: <ul> <dl> <dt>H5T_STR_NULL @@ -892,6 +1290,7 @@ zero. <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> @@ -899,11 +1298,13 @@ zero. <dd><em>herr_t </em><code>H5Tset_strpad</code>(<em>hid_t </em><code>type_id</code>, <em>H5T_str_t</em> <code>strpad</code> ) +<dt><strong>Purpose:</strong> + <dd>Defines the storage mechanism for character strings. <dt><strong>Description:</strong> - <dd>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. + <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. + <code>H5Tset_strpad</code> defines the storage mechanism for the string. Valid string padding values are: <ul> <dl> <dt>H5T_STR_NULL @@ -922,14 +1323,17 @@ zero. <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>Purpose:</strong> + <dd>Retrieves the number of fields in a compound datatype. <dt><strong>Description:</strong> - <dd>This function retrieves the number of fields a compound datatype has. + <dd><code>H5Tget_nmembers</code> retrieves the number of fields a compound datatype has. <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>type_id</code> @@ -939,6 +1343,7 @@ zero. <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> @@ -946,8 +1351,10 @@ zero. <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>Purpose:</strong> + <dd>Retrieves the name of a field of a compound data type. <dt><strong>Description:</strong> - <dd>This function retrieves the name of a field of a compound data type. + <dd><code>H5Tget_member_name</code> 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 @@ -963,6 +1370,7 @@ zero. <dd>Valid pointer on success, NULL on failure </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Datatype-GetMemberDims">H5Tget_member_dims</a> @@ -972,8 +1380,10 @@ zero. <em>size_t *</em> <code>dims</code>, <em>int *</em> <code>perm</code> ) +<dt><strong>Purpose:</strong> + <dd>Returns the dimensionality of the field. <dt><strong>Description:</strong> - <dd>This function returns the dimensionality of the field. The dimensions + <dd><code>H5Tget_member_dims</code> 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. @@ -992,6 +1402,7 @@ zero. <dd>Number of dimensions on success, negative on failure. </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Datatype-GetMemberType">H5Tget_member_type</a> @@ -999,8 +1410,10 @@ zero. <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>Purpose:</strong> + <dd>Returns the data type of the specified member. <dt><strong>Description:</strong> - <dd>This function returns the data type of the specified member. The caller + <dd><code>H5Tget_member_type</code> 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> @@ -1013,6 +1426,7 @@ zero. <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> @@ -1022,8 +1436,10 @@ zero. <em>off_t</em> <code>offset</code>, <em>hid_t</em> <code>field_id</code> ) +<dt><strong>Purpose:</strong> + <dd>Adds a new member to a compound data type. <dt><strong>Description:</strong> - <dd>This function adds another member to the compound data type + <dd><code>H5Tinsert</code> 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 @@ -1047,14 +1463,17 @@ zero. <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>Purpose:</strong> + <dd>Recursively removes padding from within a compound datatype. <dt><strong>Description:</strong> - <dd>This function recursively removes padding from within a compound + <dd><code>H5Tpack</code> recursively removes padding from within a compound datatype to make it more efficient (space-wise) to store that data. <dt><strong>Parameters:</strong> <dl> @@ -1065,6 +1484,7 @@ zero. <dd>zero/negative </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Datatype-RegisterHard">H5Tregister_hard</a> @@ -1074,8 +1494,10 @@ zero. <em>hid_t</em> <code>dst_id</code>, <em>H5T_conv_t</em> <code>func</code> ) +<dt><strong>Purpose:</strong> + <dd>Registers a hard conversion function. <dt><strong>Description:</strong> - <dd>This function registers a hard conversion function for a data type + <dd><code>H5Tregister_hard</code> 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 @@ -1103,6 +1525,7 @@ zero. <dd>zero/negative </dl> + <hr> <dl> <dt><strong>Name:</strong> <a name="Datatype-RegisterSoft">H5Tregister_soft</a> @@ -1112,8 +1535,10 @@ zero. <em>hid_t</em> <code>dst_id</code>, <em>H5T_conv_t</em> <code>func</code> ) +<dt><strong>Purpose:</strong> + <dd>Registers a soft conversion function. <dt><strong>Description:</strong> - <dd>This function registers a soft conversion function by adding it to the + <dd><code>H5Tregister_soft</code> 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 @@ -1136,14 +1561,17 @@ zero. <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>Purpose:</strong> + <dd>Removes a conversion function from all conversion paths. <dt><strong>Description:</strong> - <dd>This function removes a conversion function from all conversion paths. + <dd><code>H5Tunregister</code> 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); @@ -1156,14 +1584,17 @@ zero. <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>Purpose:</strong> + <dd>Releases a datatype. <dt><strong>Description:</strong> - <dd>This function releases a datatype. Further access through the datatype + <dd><code>H5Tclose</code> 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> @@ -1176,6 +1607,15 @@ zero. </dl> +<hr> +<hr> + +<b>Aha!! And here is the reference to sharing and that command that had us +so buffaloed, <code>H5Tshare</code>!</b><br> +To quote Quincy: "The H5Tshare() and H5Tis_shared() will be removed. Data types +will not be stored in the global heap. A new type of shared +message header will be added to the object headers that points to +another object header instead of the global heap..." <hr> <hr> @@ -1317,7 +1757,7 @@ Quincey> <a href="mailto:h5docs@ncsa.uiuc.edu">HDF5 Documentation</a> <br> -Last modified: 29 June 1998 +Last modified: 9 July 1998 </body> </html> |