diff options
| author | Quincey Koziol <koziol@hdfgroup.org> | 1998-07-08 14:54:54 (GMT) |
|---|---|---|
| committer | Quincey Koziol <koziol@hdfgroup.org> | 1998-07-08 14:54:54 (GMT) |
| commit | bd1e676c521d881b3143829f493a28b5ced1294b (patch) | |
| tree | 69c50f9fe21ce87f293d8617a6bd51b4cc1e0244 /doc/html | |
| parent | 73345095897d9698bb1f2f7df830bf80a56dc65a (diff) | |
| download | hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.zip hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.gz hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.bz2 | |
[svn-r467] Restructuring documentation.
Diffstat (limited to 'doc/html')
71 files changed, 20819 insertions, 0 deletions
diff --git a/doc/html/Attributes.html b/doc/html/Attributes.html new file mode 100644 index 0000000..85fe70f --- /dev/null +++ b/doc/html/Attributes.html @@ -0,0 +1,177 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>Attributes</title> + </head> + + <body> + <h1>Attributes</h1> + + <h2>1. Introduction</h2> + + <p>The appribute API (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>Attributes are not seperate objects in the file, they are always + contained in the object header of the object they are attached to. The + I/O functions defined below are required to read or write attribute + information, not the H5D I/O routines. + + <h2>2. Creating, Opening, Closing and Deleting Attributes</h2> + + <p>Attributes are created with the <code>H5Acreate()</code> function, + and existing attributes can be accessed with either the + <code>H5Aopen_name()</code> or <code>H5Aopen_idx()</code> functions. All + three functions return an object ID which should be eventually released + by calling <code>H5Aclose()</code>. + + <dl> + <dt><code>hid_t H5Acreate (hid_t <em>loc_id</em>, const char + *<em>name</em>, hid_t <em>type_id</em>, hid_t <em>space_id</em>, + hid_t <em>create_plist_id</em>)</code> + <dd>This function 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 ID 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. + This function returns a attribute ID for success or negative for failure. + + <br><br> + <dt><code>hid_t H5Aopen_name (hid_t <em>loc_id</em>, const char + *<em>name</em>)</code> + <dd> This function opens an attribute which is attached to the object + specified with <em>loc_id</em>. The name specified with <em>name</em> + indicates the attribute to access. The attribute ID returned from this + function must be released with H5Aclose or resource leaks will develop. + This function returns a attribute ID for success or negative for failure. + + <br><br> + <dt><code>hid_t H5Aopen_idx (hid_t <em>loc_id</em>, unsigned + <em>idx</em>)</code> + <dd>This function opens an attribute which is attached to the object + specified with <em>loc_id</em>. The attribute specified with <em>idx</em> + indicates the <em>idx</em>th attribute to access, starting with '0'. The + attribute ID returned from this function must be released with H5Aclose or + resource leaks will develop. + This function returns a attribute ID for success or negative for failure. + + <br><br> + <dt><code>herr_t H5Aclose (hid_t <em>attr_id</em>)</code> + <dd>This function releases an attribute from use. Further use of the + attribute ID will result in undefined behavior. + This function returns non-negative on success, negative on failure. + + <br><br> + <dt><code>herr_t H5Adelete (hid_t <em>loc_id</em>, + const char *<em>name</em>)</code> + <dd>This function removes the named attribute from a dataset or group. + This function should not be used when attribute IDs are open on <em>loc_id</em> + 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. + </dl> + + <h2>3. Attribute I/O Functions</h2> + + <p>Attributes may only be written as an entire object, no partial I/O + is currently supported. + + <dl> + <dt><code>herr_t H5Awrite (hid_t <em>attr_id</em>, + hid_t <em>mem_type_id</em>, void *<em>buf</em>)</code> + <dd>This function writes an attribute, specified with <em>attr_id</em>, + with <em>mem_type_id</em> specifying the datatype in memory. The entire + attribute is written from <em>buf</em> to the file. + This function returns non-negative on success, negative on failure. + + <br><br> + <dt><code>herr_t H5Aread (hid_t <em>attr_id</em>, + hid_t <em>mem_type_id</em>, void *<em>buf</em>)</code> + <dd>This function read an attribute, specified with <em>attr_id</em>, with + <em>mem_type_id</em> specifying the datatype in memory. The entire + attribute is read into <em>buf</em> from the file. + This function returns non-negative on success, negative on failure. + + </dl> + + <h2>4. Attribute Inquiry Functions</h2> + + <dl> + <dt><code>int H5Aiterate (hid_t <em>loc_id</em>, + unsigned *<em>attr_number</em>, + H5A_operator <em>operator</em>, + void *<em>operator_data</em>)</code> + <dd> This function interates over the attributes of dataset or group + specified with <em>loc_id</em>. For each attribute of the object, the + <em>operator_data</em> and some additional information (specified below) + are passed to the <em>operator</em> function. The iteration begins with + the <em>*attr_number</em> object in the group and the next attribute to be + processed by the operator is returned in <em>*attr_number</em>. + <P>The iterator returns a negative value if something is wrong, the return + value of the last operator if it was non-zero, or zero if all attributes + were processed. + <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 ID 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> + <br><br> + <dt><code>hid_t H5Aget_space (hid_t <em>attr_id</em>)</code> + <dd>This function retrieves a copy of the dataspace for an attribute. + The dataspace ID returned from this function must be released with H5Sclose + or resource leaks will develop. + This function returns a dataspace ID for success or negative for failure. + <br><br> + <dt><code>hid_t H5Aget_type (hid_t <em>attr_id</em>)</code> + <dd>This function retrieves a copy of the datatype for an attribute. + The datatype ID returned from this function must be released with H5Tclose + or resource leaks will develop. + This function returns a datatype ID for success or negative for failure. + <br><br> + <dt><code>size_t H5Aget_name (hid_t <em>attr_id</em>, + char *<em>buf</em>, size_t <em>buf_size</em>)</code> + <dd>This function retrieves the name of an attribute for an attribute ID. + Up to <em>buf_size</em> characters are stored in <em>buf</em> followed by a + '\0' string terminator. If the name of the attribute is longer than + <em>buf_size</em>-1, the string terminator is stored in the last position + of the buffer to properly terminate the string. + This function returns the length of the attribute's name (which may be + longer than <em>buf_size</em>) on success or negative for failure. + <br><br> + <dt><code>int H5Anum_attrs (hid_t <em>loc_id</em>)</code> + <dd>This function returns the number of attributes attached to a dataset or + group, <em>loc_id</em>. + This function returns non-negative for success or negative for failure. + </dl> + + <hr> + <address><a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Support</a></address> + </body> +</html> diff --git a/doc/html/Big.html b/doc/html/Big.html new file mode 100644 index 0000000..080f786 --- /dev/null +++ b/doc/html/Big.html @@ -0,0 +1,111 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>Big Datasets on Small Machines</title> + </head> + + <body> + <h1>Big Datasets on Small Machines</h1> + + <h2>1. Introduction</h2> + + <p>The HDF5 library is able to handle files larger than the + maximum file size, and datasets larger than the maximum memory + size. For instance, a machine where <code>sizeof(off_t)</code> + and <code>sizeof(size_t)</code> are both four bytes can handle + datasets and files as large as 18x10^18 bytes. However, most + Unix systems limit the number of concurrently open files, so a + practical file size limit is closer to 512GB or 1TB. + + <p>Two "tricks" must be imployed on these small systems in order + to store large datasets. The first trick circumvents the + <code>off_t</code> file size limit and the second circumvents + the <code>size_t</code> main memory limit. + + <h2>2. File Size Limits</h2> + + <p>Some 32-bit operating systems have special file systems that + can support large (>2GB) files and HDF5 will detect these and + use them automatically. If this is the case, the output from + configure will show: + + <p><code><pre> +checking for lseek64... yes +checking for fseek64... yes + </pre></code> + + <p>Otherwise one must use an HDF5 file family. Such a family is + created by setting file family properties in a file access + property list and then supplying a file name that includes a + <code>printf</code>-style integer format. For instance: + + <p><code><pre> +hid_t plist, file; +plist = H5Pcreate (H5P_FILE_ACCESS); +H5Pset_family (plist, 1<<30, H5P_DEFAULT); +file = H5Fcreate ("big%03d.h5", H5F_ACC_TRUNC, H5P_DEFAULT, plist); + </code></pre> + + <p>The second argument (<code>30</code>) to + <code>H5Pset_family()</code> indicates that the family members + are to be 2^30 bytes (1GB) each. In general, family members + cannot be 2GB because writes to byte number 2,147,483,647 will + fail, so the largest safe value for a family member is + 2,147,483,647. HDF5 will create family members on demand as the + HDF5 address space increases, but since most Unix systems limit + the number of concurrently open files the effective maximum size + of the HDF5 address space will be limited. + + <p>If the effective HDF5 address space is limited then one may be + able to store datasets as external datasets each spanning + multiple files of any length since HDF5 opens external dataset + files one at a time. To arrange storage for a 5TB dataset one + could say: + + <p><code><pre> +hid_t plist = H5Pcreate (H5P_DATASET_CREATE); +for (i=0; i<5*1024; i++) { + sprintf (name, "velocity-%04d.raw", i); + H5Pset_external (plist, name, 0, (size_t)1<<30); +} + </code></pre> + + <h2>3. Dataset Size Limits</h2> + + <p>The second limit which must be overcome is that of + <code>sizeof(size_t)</code>. HDF5 defines a new data type + called <code>hsize_t</code> which is used for sizes of datasets + and is, by default, defined as <code>unsigned long long</code>. + + <p>To create a dataset with 8*2^30 4-byte integers for a total of + 32GB one first creates the dataspace. We give two examples + here: a 4-dimensional dataset whose dimension sizes are smaller + than the maximum value of a <code>size_t</code>, and a + 1-dimensional dataset whose dimension size is too large to fit + in a <code>size_t</code>. + + <p><code><pre> +hsize_t size1[4] = {8, 1024, 1024, 1024}; +hid_t space1 = H5Screate_simple (4, size1, size1); + +hsize_t size2[1] = {8589934592LL}; +hid_t space2 = H5Screate_simple (1, size2, size2}; + </pre></code> + + <p>However, the <code>LL</code> suffix is not portable, so it may + be better to replace the number with + <code>(hsize_t)8*1024*1024*1024</code>. + + <p>For compilers that don't support <code>long long</code> large + datasets will not be possible. The library performs too much + arithmetic on <code>hsize_t</code> types to make the use of a + struct feasible. + + <hr> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- Created: Fri Apr 10 13:26:04 EDT 1998 --> +<!-- hhmts start --> +Last modified: Wed May 13 12:36:47 EDT 1998 +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/Caching.html b/doc/html/Caching.html new file mode 100644 index 0000000..4e5a6ac --- /dev/null +++ b/doc/html/Caching.html @@ -0,0 +1,82 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>Data Caching</title> + </head> + + <body> + <h1>Meta Data Caching</h1> + + <p>The HDF5 library caches two types of data: meta data and raw + data. The meta data cache holds file objects like the file + header, symbol table nodes, global heap collections, object + headers and their messages, etc. in a partially decoded + state. The cache has a fixed number of entries which is set with + the file access property list (defaults to 10k) and each entry + can hold a single meta data object. Collisions between objects + are handled by preempting the older object in favor of the new + one. + + <h1>Raw Data Chunk Caching</h1> + + <p>Raw data chunks are cached because I/O requests at the + application level typically don't map well to chunks at the + storage level. The chunk cache has a maximum size in bytes + set with the file access property list (defaults to 1MB) and + when the limit is reached chunks are preempted based on the + following set of heuristics. + + <ul> + <li>Chunks which have not been accessed for a long time + relative to other chunks are penalized. + <li>Chunks which have been accessed frequently in the recent + past are favored. + <li>Chunks which are completely read and not written, completely + written but not read, or completely read and completely + written are penalized according to <em>w0</em>, an + application-defined weight between 0 and 1 inclusive. A weight + of zero does not penalize such chunks while a weight of 1 + penalizes those chunks more than all other chunks. The + default is 0.75. + <li>Chunks which are larger than the maximum cache size do not + participate in the cache. + </ul> + + <p>One should choose large values for <em>w0</em> if I/O requests + typically do not overlap but smaller values for <em>w0</em> if + the requests do overlap. For instance, reading an entire 2d + array by reading from non-overlapping "windows" in a row-major + order would benefit from a high <em>w0</em> value while reading + a diagonal accross the dataset where each request overlaps the + previous request would benefit from a small <em>w0</em>. + + <h1>The API</h1> + + <p>The cache parameters for both caches are part of a file access + property list and are set and queried with this pair of + functions: + + <dl> + <dt><code>herr_t H5Pset_cache(hid_t <em>plist</em>, unsigned int + <em>mdc_nelmts</em>, size_t <em>rdcc_nbytes</em>, double + <em>w0</em>)</code> + <dt><code>herr_t H5Pget_cache(hid_t <em>plist</em>, unsigned int + *<em>mdc_nelmts</em>, size_t *<em>rdcc_nbytes</em>, double + <em>w0</em>)</code> + <dd>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. + </dl> + + <hr> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- Created: Tue May 26 15:20:14 EDT 1998 --> +<!-- hhmts start --> +Last modified: Tue May 26 15:38:27 EDT 1998 +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/CodeReview.html b/doc/html/CodeReview.html new file mode 100644 index 0000000..213cbbe --- /dev/null +++ b/doc/html/CodeReview.html @@ -0,0 +1,300 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>Code Review</title> + </head> + <body> + <center><h1>Code Review 1</h1></center> + + <h3>Some background...</h3> + <p>This is one of the functions exported from the + <code>H5B.c</code> file that implements a B-link-tree class + without worrying about concurrency yet (thus the `Note:' in the + function prologue). The <code>H5B.c</code> file provides the + basic machinery for operating on generic B-trees, but it isn't + much use by itself. Various subclasses of the B-tree (like + symbol tables or indirect storage) provide their own interface + and back end to this function. For instance, + <code>H5G_stab_find()</code> takes a symbol table OID and a name + and calls <code>H5B_find()</code> with an appropriate + <code>udata</code> argument that eventually gets passed to the + <code>H5G_stab_find()</code> function. + + <p><code><pre> + 1 /*------------------------------------------------------------------------- + 2 * Function: H5B_find + 3 * + 4 * Purpose: Locate the specified information in a B-tree and return + 5 * that information by filling in fields of the caller-supplied + 6 * UDATA pointer depending on the type of leaf node + 7 * requested. The UDATA can point to additional data passed + 8 * to the key comparison function. + 9 * +10 * Note: This function does not follow the left/right sibling +11 * pointers since it assumes that all nodes can be reached +12 * from the parent node. +13 * +14 * Return: Success: SUCCEED if found, values returned through the +15 * UDATA argument. +16 * +17 * Failure: FAIL if not found, UDATA is undefined. +18 * +19 * Programmer: Robb Matzke +20 * matzke@llnl.gov +21 * Jun 23 1997 +22 * +23 * Modifications: +24 * +25 *------------------------------------------------------------------------- +26 */ +27 herr_t +28 H5B_find (H5F_t *f, const H5B_class_t *type, const haddr_t *addr, void *udata) +29 { +30 H5B_t *bt=NULL; +31 intn idx=-1, lt=0, rt, cmp=1; +32 int ret_value = FAIL; + </pre></code> + + <p>All pointer arguments are initialized when defined. I don't + worry much about non-pointers because it's usually obvious when + the value isn't initialized. + + <p><code><pre> +33 +34 FUNC_ENTER (H5B_find, NULL, FAIL); +35 +36 /* +37 * Check arguments. +38 */ +39 assert (f); +40 assert (type); +41 assert (type->decode); +42 assert (type->cmp3); +43 assert (type->found); +44 assert (addr && H5F_addr_defined (addr)); + </pre></code> + + <p>I use <code>assert</code> to check invariant conditions. At + this level of the library, none of these assertions should fail + unless something is majorly wrong. The arguments should have + already been checked by higher layers. It also provides + documentation about what arguments might be optional. + + <p><code><pre> +45 +46 /* +47 * Perform a binary search to locate the child which contains +48 * the thing for which we're searching. +49 */ +50 if (NULL==(bt=H5AC_protect (f, H5AC_BT, addr, type, udata))) { +51 HGOTO_ERROR (H5E_BTREE, H5E_CANTLOAD, FAIL); +52 } + </pre></code> + + <p>You'll see this quite often in the low-level stuff and it's + documented in the <code>H5AC.c</code> file. The + <code>H5AC_protect</code> insures that the B-tree node (which + inherits from the H5AC package) whose OID is <code>addr</code> + is locked into memory for the duration of this function (see the + <code>H5AC_unprotect</code> on line 90). Most likely, if this + node has been accessed in the not-to-distant past, it will still + be in memory and the <code>H5AC_protect</code> is almost a + no-op. If cache debugging is compiled in, then the protect also + prevents other parts of the library from accessing the node + while this function is protecting it, so this function can allow + the node to be in an inconsistent state while calling other + parts of the library. + + <p>The alternative is to call the slighlty cheaper + <code>H5AC_find</code> and assume that the pointer it returns is + valid only until some other library function is called, but + since we're accessing the pointer throughout this function, I + chose to use the simpler protect scheme. All protected objects + <em>must be unprotected</em> before the file is closed, thus the + use of <code>HGOTO_ERROR</code> instead of + <code>HRETURN_ERROR</code>. + + <p><code><pre> +53 rt = bt->nchildren; +54 +55 while (lt<rt && cmp) { +56 idx = (lt + rt) / 2; +57 if (H5B_decode_keys (f, bt, idx)<0) { +58 HGOTO_ERROR (H5E_BTREE, H5E_CANTDECODE, FAIL); +59 } +60 +61 /* compare */ +62 if ((cmp=(type->cmp3)(f, bt->key[idx].nkey, udata, +63 bt->key[idx+1].nkey))<0) { +64 rt = idx; +65 } else { +66 lt = idx+1; +67 } +68 } +69 if (cmp) { +70 HGOTO_ERROR (H5E_BTREE, H5E_NOTFOUND, FAIL); +71 } + </pre></code> + + <p>Code is arranged in paragraphs with a comment starting each + paragraph. The previous paragraph is a standard binary search + algorithm. The <code>(type->cmp3)()</code> is an indirect + function call into the subclass of the B-tree. All indirect + function calls have the function part in parentheses to document + that it's indirect (quite obvious here, but not so obvious when + the function is a variable). + + <p>It's also my standard practice to have side effects in + conditional expressions because I can write code faster and it's + more apparent to me what the condition is testing. But if I + have an assignment in a conditional expr, then I use an extra + set of parens even if they're not required (usually they are, as + in this case) so it's clear that I meant <code>=</code> instead + of <code>==</code>. + + <p><code><pre> +72 +73 /* +74 * Follow the link to the subtree or to the data node. +75 */ +76 assert (idx>=0 && idx<bt->nchildren); +77 if (bt->level > 0) { +78 if ((ret_value = H5B_find (f, type, bt->child+idx, udata))<0) { +79 HGOTO_ERROR (H5E_BTREE, H5E_NOTFOUND, FAIL); +80 } +81 } else { +82 ret_value = (type->found)(f, bt->child+idx, bt->key[idx].nkey, +83 udata, bt->key[idx+1].nkey); +84 if (ret_value<0) { +85 HGOTO_ERROR (H5E_BTREE, H5E_NOTFOUND, FAIL); +86 } +87 } + </pre></code> + + <p>Here I broke the "side effect in conditional" rule, which I + sometimes do if the expression is so long that the + <code><0</code> gets lost at the end. Another thing to note is + that success/failure is always determined by comparing with zero + instead of <code>SUCCEED</code> or <code>FAIL</code>. I do this + because occassionally one might want to return other meaningful + values (always non-negative) or distinguish between various types of + failure (always negative). + + <p><code><pre> +88 +89 done: +90 if (bt && H5AC_unprotect (f, H5AC_BT, addr, bt)<0) { +91 HRETURN_ERROR (H5E_BTREE, H5E_PROTECT, FAIL); +92 } +93 FUNC_LEAVE (ret_value); +94 } + </pre></code> + + <p>For lack of a better way to handle errors during error cleanup, + I just call the <code>HRETURN_ERROR</code> macro even though it + will make the error stack not quite right. I also use short + circuiting boolean operators instead of nested <code>if</code> + statements since that's standard C practice. + + <center><h1>Code Review 2</h1></center> + + + <p>The following code is an API function from the H5F package... + + <p><code><pre> + 1 /*-------------------------------------------------------------------------- + 2 NAME + 3 H5Fflush + 4 + 5 PURPOSE + 6 Flush all cached data to disk and optionally invalidates all cached + 7 data. + 8 + 9 USAGE +10 herr_t H5Fflush(fid, invalidate) +11 hid_t fid; IN: File ID of file to close. +12 hbool_t invalidate; IN: Invalidate all of the cache? +13 +14 ERRORS +15 ARGS BADTYPE Not a file atom. +16 ATOM BADATOM Can't get file struct. +17 CACHE CANTFLUSH Flush failed. +18 +19 RETURNS +20 SUCCEED/FAIL +21 +22 DESCRIPTION +23 This function flushes all cached data to disk and, if INVALIDATE +24 is non-zero, removes cached objects from the cache so they must be +25 re-read from the file on the next access to the object. +26 +27 MODIFICATIONS: +28 --------------------------------------------------------------------------*/ + </pre></code> + + <p>An API prologue is used for each API function instead of my + normal function prologue. I use the prologue from Code Review 1 + for non-API functions because it's more suited to C programmers, + it requires less work to keep it synchronized with the code, and + I have better editing tools for it. + + <p><code><pre> +29 herr_t +30 H5Fflush (hid_t fid, hbool_t invalidate) +31 { +32 H5F_t *file = NULL; +33 +34 FUNC_ENTER (H5Fflush, H5F_init_interface, FAIL); +35 H5ECLEAR; + </pre></code> + + <p>API functions are never called internally, therefore I always + clear the error stack before doing anything. + + <p><code><pre> +36 +37 /* check arguments */ +38 if (H5_FILE!=H5Aatom_group (fid)) { +39 HRETURN_ERROR (H5E_ARGS, H5E_BADTYPE, FAIL); /*not a file atom*/ +40 } +41 if (NULL==(file=H5Aatom_object (fid))) { +42 HRETURN_ERROR (H5E_ATOM, H5E_BADATOM, FAIL); /*can't get file struct*/ +43 } + </pre></code> + + <p>If something is wrong with the arguments then we raise an + error. We never <code>assert</code> arguments at this level. + We also convert atoms to pointers since atoms are really just a + pointer-hiding mechanism. Functions that can be called + internally always have pointer arguments instead of atoms + because (1) then they don't have to always convert atoms to + pointers, and (2) the various pointer data types provide more + documentation and type checking than just an <code>hid_t</code> + type. + + <p><code><pre> +44 +45 /* do work */ +46 if (H5F_flush (file, invalidate)<0) { +47 HRETURN_ERROR (H5E_CACHE, H5E_CANTFLUSH, FAIL); /*flush failed*/ +48 } + </pre></code> + + <p>An internal version of the function does the real work. That + internal version calls <code>assert</code> to check/document + it's arguments and can be called from other library functions. + + <p><code><pre> +49 +50 FUNC_LEAVE (SUCCEED); +51 } + </pre></code> + + <hr> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- Created: Sat Nov 8 17:09:33 EST 1997 --> +<!-- hhmts start --> +Last modified: Mon Nov 10 15:33:33 EST 1997 +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/Coding.html b/doc/html/Coding.html new file mode 100644 index 0000000..dbf55bf --- /dev/null +++ b/doc/html/Coding.html @@ -0,0 +1,300 @@ +<HTML> +<HEAD><TITLE> + HDF5 Naming Scheme + </TITLE> </HEAD> + +<BODY bgcolor="#ffffff"> + + +<H1> +<FONT color="#c80028" + <I> <B> <CENTER> HDF5 Naming Scheme for </CENTER> </B> </I> </H1> +</FONT> +<P> +<UL> + +<LI> <A HREF = "#01"><I> FILES </I> </A> +<LI> <A HREF = "#02"><I> PACKAGES </I> </A> +<LI> <A HREF = "#03"><I> PUBLIC vs PRIVATE </I> </A> +<LI> <A HREF = "#04"><I> INTEGRAL TYPES </I> </A> +<LI> <A HREF = "#05"><I> OTHER TYPES </I> </A> +<LI> <A HREF = "#06"><I> GLOBAL VARIABLES </I> </A> +<LI> <A HREF = "#07"><I> MACROS, PREPROCESSOR CONSTANTS, AND ENUM MEMEBERs </I> </A> + +</UL> +<P> +<center> + Authors: <A HREF = "mailto:koziol@ncsa.uiuc.edu"> + <I>Quincey Koziol</I> </A> and + <A HREF = "mailto:matzke@llnl.gov"> + <I> Robb Matzke </I> </A> + +</center> +<UL> + +<FONT color="#c80028" +<LI> <A NAME="01"> <B> <I> FILES </I> </B> </A> +</FONT> + +<UL> + + <LI> Source files are named according to the package they contain (see + below). All files will begin with `H5' so we can stuff our + object files into someone else's library and not worry about file + name conflicts. + <P>For Example: +<i><b> +<dd> H5.c -- "Generic" library functions + <br> +<dd> H5B.c -- B-link tree functions +</i></b> + <p> + <LI> If a package is in more than one file, then another name is tacked + on. It's all lower case with no underscores or hyphens. + <P>For Example: +<i><b> +<dd> H5F.c -- the file for this package + <br> +<dd> H5Fstdio.c -- stdio functions (just an example) + <br> +<dd> H5Ffcntl.c -- fcntl functions (just an example) +</i></b> + <p> + <LI> Each package file has a header file of API stuff (unless there is + no API component to the package) + <P>For Example: +<i><b> +<dd> H5F.h -- things an application would see. </i> </b> + <P> + and a header file of private stuff +<i><b> + <p> +<dd> H5Fprivate.h -- things an application wouldn't see. The + private header includes the public header. +</i></b> + <p> + and a header for private prototypes +<i><b> + <p> +<dd> H5Fproto.h -- prototypes for internal functions. +</i></b> + <P> + By splitting the prototypes into separate include files we don't + have to recompile everything when just one function prototype + changes. + + <LI> The main API header file is `hdf5.h' and it includes each of the + public header files but none of the private header files. Or the + application can include just the public header files it needs. + + <LI> There is no main private or prototype header file because it + prevents make from being efficient. Instead, each source file + includes only the private header and prototype files it needs + (first all the private headers, then all the private prototypes). + + <LI> Header files should include everything they need and nothing more. + +</UL> +<P> + +<FONT color="#c80028" +<LI> <A NAME="02"> <B> <I> PACKAGES </I> </B> </A> +</FONT> + +<P> +Names exported beyond function scope begin with `H5' followed by zero, +one, or two upper-case letters that describe the class of object. +This prefix is the package name. The implementation of packages +doesn't necessarily have to map 1:1 to the source files. +<P> +<i><b> +<dd> H5 -- library functions +<br> +<dd> H5A -- atoms +<br> +<dd> H5AC -- cache +<br> +<dd> H5B -- B-link trees +<br> +<dd> H5D -- datasets +<br> +<dd> H5E -- error handling +<br> +<dd> H5F -- files +<br> +<dd> H5G -- groups +<br> +<dd> H5M -- meta data +<br> +<dd> H5MM -- core memory management +<br> +<dd> H5MF -- file memory management +<br> +<dd> H5O -- object headers +<br> +<dd> H5P -- Property Lists +<br> +<dd> H5S -- dataspaces +<br> +<dd> H5R -- relationships +<br> +<dd> H5T -- datatype +</i></b> +<p> +Each package implements a single main class of object (e.g., the H5B +package implements B-link trees). The main data type of a package is +the package name followed by `_t'. +<p> +<i><b> +<dd> H5F_t -- HDF5 file type +<br> +<dd> H5B_t -- B-link tree data type +</i></b> +<p> + +Not all packages implement a data type (H5, H5MF) and some +packages provide access to a preexisting data type (H5MM, H5S). +<p> + + +<FONT color="#c80028" +<LI> <A NAME="03"> <B> <I> PUBLIC vs PRIVATE </I> </B> </A> +</FONT> +<p> +If the symbol is for internal use only, then the package name is +followed by an underscore and the rest of the name. Otherwise, the +symbol is part of the API and there is no underscore between the +package name and the rest of the name. +<p> +<i><b> +<dd> H5Fopen -- an API function. +<br> +<dd> H5B_find -- an internal function. +</i></b> +<p> +For functions, this is important because the API functions never pass +pointers around (they use atoms instead for hiding the implementation) +and they perform stringent checks on their arguments. Internal +unctions, on the other hand, check arguments with assert(). +<p> +Data types like H5B_t carry no information about whether the type is +public or private since it doesn't matter. + +<p> + + +<FONT color="#c80028" +<LI> <A NAME="04"> <B> <I> INTEGRAL TYPES </I> </B> </A> +</FONT> +<p> +Integral fixed-point type names are an optional `u' followed by `int' +followed by the size in bits (8, 16, +32, or 64). There is no trailing `_t' because these are common +enough and follow their own naming convention. +<p> +<pre><H4> +<dd> hbool_t -- boolean values (BTRUE, BFALSE, BFAIL) +<br> +<dd> int8 -- signed 8-bit integers +<br> +<dd> uint8 -- unsigned 8-bit integers +<br> +<dd> int16 -- signed 16-bit integers +<br> +<dd> uint16 -- unsigned 16-bit integers +<br> +<dd> int32 -- signed 32-bit integers +<br> +<dd> uint32 -- unsigned 32-bit integers +<br> +<dd> int64 -- signed 64-bit integers +<br> +<dd> uint64 -- unsigned 64-bit integers +<br> +<dd> intn -- "native" integers +<br> +<dd> uintn -- "native" unsigned integers + +</pre></H4> +<p> + +<FONT color="#c80028" +<LI> <A NAME="05"> <B> <I> OTHER TYPES </I> </B> </A> +</FONT> + +<p> + +Other data types are always followed by `_t'. +<p> +<pre><H4> +<dd> H5B_key_t-- additional data type used by H5B package. +</pre></H4> +<p> + +However, if the name is so common that it's used almost everywhere, +then we make an alias for it by removing the package name and leading +underscore and replacing it with an `h' (the main datatype for a +package already has a short enough name, so we don't have aliases for +them). +<P> +<pre><H4> +<dd> typedef H5E_err_t herr_t; +</pre> </H4> +<p> + +<FONT color="#c80028" +<LI> <A NAME="06"> <B> <I> GLOBAL VARIABLES </I> </B> </A> +</FONT> +<p> +Global variables include the package name and end with `_g'. +<p> +<pre><H4> +<dd> H5AC_methods_g -- global variable in the H5AC package. +</pre> </H4> +<p> + + +<FONT color="#c80028" +<LI> <A NAME="07"> +<I> <B> +MACROS, PREPROCESSOR CONSTANTS, AND ENUM MEMBERS + </I> </B> </A> +</FONT> +<p> +Same rules as other symbols except the name is all upper case. There +are a few exceptions: <br> +<ul> +<li> Constants and macros defined on a system that is deficient: + <p><pre><H4> +<dd> MIN(x,y), MAX(x,y) and their relatives + </pre></H4> + +<li> Platform constants : + <P> + No naming scheme; determined by OS and compiler.<br> + These appear only in one header file anyway. + <p> +<li> Feature test constants (?)<br> + Always start with `HDF5_HAVE_' like HDF5_HAVE_STDARG_H for a + header file, or HDF5_HAVE_DEV_T for a data type, or + HDF5_HAVE_DIV for a function. +</UL> +<p> + +</UL> +<p> +<H6> +<center> + This file /hdf3/web/hdf/internal/HDF_standard/HDF5.coding_standard.html is + maintained by Elena Pourmal <A HREF = "mailto:epourmal@ncsa.uiuc.edu"> + <I>epourmal@ncsa.uiuc.edu</I> </A>. +</center> +<p> +<center> + Last modified August 5, 1997 +</center> + +</H6> +</BODY> +<HTML> + diff --git a/doc/html/Compression.html b/doc/html/Compression.html new file mode 100644 index 0000000..c3a2a45 --- /dev/null +++ b/doc/html/Compression.html @@ -0,0 +1,409 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>Compression</title> + </head> + + <body> + <h1>Compression</h1> + + <h2>1. Introduction</h2> + + <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. The library doesn't support compression for contiguous + datasets because of the difficulty of implementing random access + for partial I/O, and compact dataset compression is not + supported because it wouldn't produce significant results. + + <h2>2. Supported Compression Methods</h2> + + <p>The library identifies compression methods with small + integers, with values less than 16 reserved for use by NCSA and + values between 16 and 255 (inclusive) available for general + use. This range may be extended in the future if it proves to + be too small. + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Method Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td><code>H5Z_NONE</code></td> + <td>The default is to not use compression. Specifying + <code>H5Z_NONE</code> as the compression method results + in better perfomance than writing a function that just + copies data because the library's I/O pipeline + recognizes this method and is able to short circuit + parts of the pipeline.</td> + </tr> + + <tr valign=top> + <td><code>H5Z_DEFLATE</code></td> + <td>The <em>deflate</em> method is the algorithm used by + the GNU <code>gzip</code>program. It's a combination of + a Huffman encoding followed by a 1977 Lempel-Ziv (LZ77) + dictionary encoding. The aggressiveness of the + compression can be controlled by passing an integer value + to the compressor with <code>H5Pset_deflate()</code> + (see below). In order for this compression method to be + used, the HDF5 library must be configured and compiled + in the presence of the GNU zlib version 1.1.2 or + later.</td> + </tr> + + <tr valign=top> + <td><code>H5Z_RES_<em>N</em></code></td> + <td>These compression methods (where <em>N</em> is in the + range two through 15, inclusive) are reserved by NCSA + for future use.</td> + </tr> + + <tr valign=top> + <td>Values of <em>N</em> between 16 and 255, inclusive</td> + <td>These values can be used to represent application-defined + compression methods. We recommend that methods under + testing should be in the high range and when a method is + about to be published it should be given a number near + the low end of the range (or even below 16). Publishing + the compression method and its numeric ID will make a + file sharable.</td> + </tr> + </table> + </center> + + <p>Setting the compression for a dataset to a method which was + not compiled into the library and/or not registered by the + application is allowed, but writing to such a dataset will + silently <em>not</em> compress the data. Reading a compressed + dataset for a method which is not available will result in + errors (specifically, <code>H5Dread()</code> will return a + negative value). The errors will be displayed in the + compression statistics if the library was compiled with + debugging turned on for the "z" package. See the + section on diagnostics below for more details. + + <h2>3. Application-Defined Methods</h2> + + <p>Compression methods 16 through 255 can be defined by an + application. As mentioned above, methods that have not been + released should use high numbers in that range while methods + that have been published will be assigned an official number in + the low region of the range (possibly less than 16). Users + should be aware that using unpublished compression methods + results in unsharable files. + + <p>A compression method has two halves: one have handles + compression and the other half handles uncompression. The + halves are implemented as functions + <code><em>method</em>_c</code> and + <code><em>method</em>_u</code> respectively. One should not use + the names <code>compress</code> or <code>uncompress</code> since + they are likely to conflict with other compression libraries + (like the GNU zlib). + + <p>Both the <code><em>method</em>_c</code> and + <code><em>method</em>_u</code> functions take the same arguments + and return the same values. They are defined with the type: + + <dl> + <dt><code>typedef size_t (*H5Z_func_t)(unsigned int + <em>flags</em>, size_t <em>cd_size</em>, const void + *<em>client_data</em>, size_t <em>src_nbytes</em>, const + void *<em>src</em>, size_t <em>dst_nbytes</em>, void + *<em>dst</em>/*out*/)</code> + <dd>The <em>flags</em> are an 8-bit vector which is stored in + the file and which is defined when the compression method is + defined. The <em>client_data</em> is a pointer to + <em>cd_size</em> bytes of configuration data which is also + stored in the file. The function compresses or uncompresses + <em>src_nbytes</em> from the source buffer <em>src</em> into + at most <em>dst_nbytes</em> of the result buffer <em>dst</em>. + The function returns the number of bytes written to the result + buffer or zero if an error occurs. But if a result buffer + overrun occurs the function should return a value at least as + large as <em>dst_size</em> (the uncompressor will see an + overrun only for corrupt data). + </dl> + + <p>The application associates the pair of functions with a name + and a method number by calling <code>H5Zregister()</code>. This + function can also be used to remove a compression method from + the library by supplying null pointers for the functions. + + <dl> + <dt><code>herr_t H5Zregister (H5Z_method_t <em>method</em>, + const char *<em>name</em>, H5Z_func_t <em>method_c</em>, + H5Z_func_t <em>method_u</em>)</code> + <dd>The pair of functions to be used for compression + (<em>method_c</em>) and uncompression (<em>method_u</em>) are + associated with a short <em>name</em> used for debugging and a + <em>method</em> number in the range 16 through 255. This + function can be called as often as desired for a particular + compression method with each call replacing the information + stored by the previous call. Sometimes it's convenient to + supply only one half of the compression, for instance in an + application that opens files for read-only. Compression + statistics for the method are accumulated across calls to this + function. + </dl> + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example: Registering an + Application-Defined Compression Method</h4></caption> + <tr> + <td> + <p>Here's a simple-minded "compression" method + that just copies the input value to the output. It's + similar to the <code>H5Z_NONE</code> method but + slower. Compression and uncompression are performed + by the same function. + + <p><code><pre> +size_t +bogus (unsigned int flags, + size_t cd_size, const void *client_data, + size_t src_nbytes, const void *src, + size_t dst_nbytes, void *dst/*out*/) +{ + memcpy (dst, src, src_nbytes); + return src_nbytes; +} + </pre></code> + + <p>The function could be registered as method 250 as + follows: + + <p><code><pre> +#define H5Z_BOGUS 250 +H5Zregister (H5Z_BOGUS, "bogus", bogus, bogus); + </pre></code> + + <p>The function can be unregistered by saying: + + <p><code><pre> +H5Zregister (H5Z_BUGUS, "bogus", NULL, NULL); + </pre></code> + + <p>Notice that we kept the name "bogus" even + though we unregistered the functions that perform the + compression and uncompression. This makes compression + statistics more understandable when they're printed. + </td> + </tr> + </table> + </center> + + <h2>4. Enabling Compression for a Dataset</h2> + + <p>If a dataset is to be compressed then the compression + information must be specified when the dataset is created since + once a dataset is created compression parameters cannot be + adjusted. The compression is specified through the dataset + creation property list (see <code>H5Pcreate()</code>). + + <dl> + <dt><code>herr_t H5Pset_deflate (hid_t <em>plist</em>, int + <em>level</em>)</code> + <dd>The compression method for dataset creation property list + <em>plist</em> is set to <code>H5Z_DEFLATE</code> and the + aggression level is set to <em>level</em>. The <em>level</em> + must be a value between one and nine, inclusive, where one + indicates no (but fast) compression and nine is aggressive + compression. + + <br><br> + <dt><code>int H5Pget_deflate (hid_t <em>plist</em>)</code> + <dd>If dataset creation property list <em>plist</em> is set to + use <code>H5Z_DEFLATE</code> compression then this function + will return the aggression level, an integer between one and + nine inclusive. If <em>plist</em> isn't a valid dataset + creation property list or it isn't set to use the deflate + method then a negative value is returned. + + <br><br> + <dt><code>herr_t H5Pset_compression (hid_t <em>plist</em>, + H5Z_method_t <em>method</em>, unsigned int <em>flags</em>, + size_t <em>cd_size</em>, const void *<em>client_data</em>)</code> + <dd>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. + + <br><br> + <dt><code>H5Z_method_t H5Pget_compression (hid_t <em>plist</em>, + unsigned int *<em>flags</em>, size_t *<em>cd_size</em>, void + *<em>client_data</em>)</code> + <dd>This is a catch-all function for querying the compression + method associated with dataset creation property list + <em>plist</em> and is intended to be called from a wrapper + function such as <code>H5Pget_deflate()</code>. The + compression method (or a negative value on error) is returned + by value, and compression flags and client data is returned by + argument. The application should allocate the + <em>client_data</em> and pass its size as the + <em>cd_size</em>. On return, <em>cd_size</em> will contain + the actual size of the client data. If <em>client_data</em> + is not large enough to hold the entire client data then + <em>cd_size</em> bytes are copied into <em>client_data</em> + and <em>cd_size</em> is set to the total size of the client + data, a value larger than the original. + </dl> + + <p>It is possible to set the compression to a method which hasn't + been defined with <code>H5Zregister()</code> and which isn't + supported as a predefined method (for instance, setting the + method to <code>H5Z_DEFLATE</code> when the GNU zlib isn't + available). If that happens then data will be written to the + file in its uncompressed form and the compression statistics + will show failures for the compression. + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example: Statistics for an + Unsupported Compression Method</h4></caption> + <tr> + <td> + <p>If an application attempts to use an unsupported + method then the compression statistics will show large + numbers of compression errors and no data + uncompressed. + + <p><code><pre> +H5Z: compression statistics accumulated over life of library: + Method Total Overrun Errors User System Elapsed Bandwidth + ------ ----- ------- ------ ---- ------ ------- --------- + deflate-c 160000 0 160000 0.00 0.01 0.01 1.884e+07 + deflate-u 0 0 0 0.00 0.00 0.00 NaN + </pre></code> + + <p>This example is from a program that tried to use + <code>H5Z_DEFLATE</code> on a system that didn't have + the GNU zlib to write to a dataset and then read the + result. The read and write both succeeded but the + data was not compressed. + </td> + </tr> + </table> + </center> + + <h2>5. Compression Diagnostics</h2> + + <p>If the library is compiled with debugging turned on for the H5Z + layer (usually as a result of <code>configure --enable-debug=z</code>) + then statistics about data compression are printed when the + application exits normally or the library is closed. The + statistics are written to the standard error stream and include + two lines for each compression method that was used: the first + line shows compression statistics while the second shows + uncompression statistics. The following fields are displayed: + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Method</td> + <td>This is the name of the method as defined with + <code>H5Zregister()</code> with the letters + "-c" or "-u" appended to indicate + compression or uncompression.</td> + </tr> + + <tr valign=top> + <td>Total</td> + <td>The total number of bytes compressed or decompressed + including buffer overruns and errors. Bytes of + non-compressed data are counted.</td> + </tr> + + <tr valign=top> + <td>Overrun</td> + <td>During compression, if the algorithm causes the result + to be at least as large as the input then a buffer + overrun error occurs. This field shows the total number + of bytes from the Total column which can be attributed to + overruns. Overruns for decompression can only happen if + the data has been corrupted in some way and will result + in failure of <code>H5Dread()</code>.</td> + </tr> + + <tr valign=top> + <td>Errors</td> + <td>If an error occurs during compression the data is + stored in it's uncompressed form; and an error during + uncompression causes <code>H5Dread()</code> to return + failure. This field shows the number of bytes of the + Total column which can be attributed to errors.</td> + </tr> + + <tr valign=top> + <td>User, System, Elapsed</td> + <td>These are the amount of user time, system time, and + elapsed time in seconds spent by the library to perform + compression. Elapsed time is sensitive to system + load. These times may be zero on operating systems that + don't support the required operations.</td> + </tr> + + <tr valign=top> + <td>Bandwidth</td> + <td>This is the compression bandwidth which is the total + number of bytes divided by elapsed time. Since elapsed + time is subject to system load the bandwidth numbers + cannot always be trusted. Furthermore, the bandwidth + includes overrun and error bytes which may significanly + taint the value.</td> + </tr> + </table> + </center> + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example: Compression + Statistics</h4></caption> + <tr> + <td> + <p><code><pre> +H5Z: compression statistics accumulated over life of library: + Method Total Overrun Errors User System Elapsed Bandwidth + ------ ----- ------- ------ ---- ------ ------- --------- + deflate-c 160000 200 0 0.62 0.74 1.33 1.204e+05 + deflate-u 120000 0 0 0.11 0.00 0.12 9.885e+05 + </pre></code> + </td> + </tr> + </table> + </center> + + <hr> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- Created: Fri Apr 17 13:39:35 EDT 1998 --> +<!-- hhmts start --> +Last modified: Fri Apr 17 16:15:21 EDT 1998 +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/Datasets.html b/doc/html/Datasets.html new file mode 100644 index 0000000..e0f9680 --- /dev/null +++ b/doc/html/Datasets.html @@ -0,0 +1,839 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>The Dataset Interface (H5D)</title> + </head> + + <body> + <h1>The Dataset Interface (H5D)</h1> + + <h2>1. Introduction</h2> + + <p>The purpose of the dataset interface is to provide a mechanism + to describe properties of datasets and to transfer data between + memory and disk. A dataset is composed of a collection of raw + data points and four classes of meta data to describe the data + points. The interface is hopefully designed in such a way as to + allow new features to be added without disrupting current + applications that use the dataset interface. + + <p>The four classes of meta data are: + + <dl> + <dt>Constant Meta Data + <dd>Meta data that is created when the dataset is created and + exists unchanged for the life of the dataset. For instance, + the data type of stored array elements is defined when the + dataset is created and cannot be subsequently changed. + + <dt>Persistent Meta Data + <dd>Meta data that is an integral and permanent part of a + dataset but can change over time. For instance, the size in + any dimension can increase over time if such an increase is + allowed when the dataset was created. + + <dt>Memory Meta Data + <dd>Meta data that exists to describe how raw data is organized + in the application's memory space. For instance, the data + type of elements in an application array might not be the same + as the data type of those elements as stored in the HDF5 file. + + <dt>Transport Meta Data + <dd>Meta data that is used only during the transfer of raw data + from one location to another. For instance, the number of + processes participating in a collective I/O request or hints + to the library to control caching of raw data. + </dl> + + <p>Each of these classes of meta data is handled differently by + the library although the same API might be used to create them. + For instance, the data type exists as constant meta data and as + memory meta data; the same API (the <code>H5T</code> API) is + used to manipulate both pieces of meta data but they're handled + by the dataset API (the <code>H5D</code> API) in different + manners. + + + + <h2>2. Storage Layout Properties</h2> + + <p>The dataset API partitions these terms on three orthogonal axes + (layout, compression, and external storage) and uses a + <em>dataset creation property list</em> to hold the various + settings and pass them through the dataset interface. This is + similar to the way HDF5 files are created with a file creation + property list. A dataset creation property list is always + derived from the default dataset creation property list (use + <code>H5Pcreate()</code> to get a copy of the default property + list) by modifying properties with various + <code>H5Pset_<em>property</em>()</code> functions. + + <dl> + <dt><code>herr_t H5Pset_layout (hid_t <em>plist_id</em>, + H5D_layout_t <em>layout</em>)</code> + <dd>The storage layout is a piece of constant meta data that + describes what method the library uses to organize the raw + data on disk. The default layout is contiguous storage. + + <br><br> + <dl> + <dt><code>H5D_COMPACT</code> + <dd>The raw data is presumably small and can be stored + directly in the object header. Such data is + non-extendible, non-compressible, non-sparse, and cannot + be stored externally. Most of these restrictions are + arbitrary but are enforced because of the small size of + the raw data. Storing data in this format eliminates the + disk seek/read request normally necessary to read raw + data. <b>This layout is not implemented yet.</b> + + <br><br> + <dt><code>H5D_CONTIGUOUS</code> + <dd>The raw data is large, non-extendible, non-compressible, + non-sparse, and can be stored externally. This is the + default value for the layout property. The term + <em>large</em> means that it may not be possible to hold + the entire dataset in memory. The non-compressibility is + a side effect of the data being large, contiguous, and + fixed-size at the physical level, which could cause + partial I/O requests to be extremely expensive if + compression were allowed. + + <br><br> + <dt><code>H5D_CHUNKED</code> + <dd>The raw data is large and can be extended in any + dimension at any time (provided the data space also allows + the extension). It may be sparse at the chunk level (each + chunk is non-sparse, but there might only be a few chunks) + and each chunk can be compressed and/or stored externally. + A dataset is partitioned into chunks so each chunk is the + same logical size. The chunks are indexed by a B-tree and + are allocated on demand (although it might be useful to be + able to preallocate storage for parts of a chunked array + to reduce contention for the B-tree in a parallel + environment). The chunk size must be defined with + <code>H5Pset_chunk()</code>. + + <br><br> + <dt><em>others...</em> + <dd>Other layout types may be defined later without breaking + existing code. However, to be able to correctly read or + modify data stored with one of these new layouts, the + application will need to be linked with a new version of + the library. This happens automatically on systems with + dynamic linking. + </dl> + </dl> + + <p>Once the general layout is defined, the user can define + properties of that layout. Currently, the only layout that has + user-settable properties is the <code>H5D_CHUNKED</code> layout, + which needs to know the dimensionality and chunk size. + + <dl> + <dt><code>herr_t H5Pset_chunk (hid_t <em>plist_id</em>, int + <em>ndims</em>, hsize_t <em>dim</em>[])</code> + <dd>This function defines the logical size of a chunk for + chunked layout. If the layout property is set to + <code>H5D_CHUNKED</code> and the chunk size is set to + <em>dim</em>. The number of elements in the <em>dim</em> array + is the dimensionality, <em>ndims</em>. One need not call + <code>H5Dset_layout()</code> when using this function since + the chunked layout is implied. + </dl> + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example: Chunked Storage</h4></caption> + <tr> + <td> + <p>This example shows how a two-dimensional dataset + is partitioned into chunks. The library can manage file + memory by moving the chunks around, and each chunk could be + compressed. The chunks are allocated in the file on demand + when data is written to the chunk. + <center> + <img alt="Chunked Storage" src="chunk1.gif"> + </center> + + <p><code><pre> +size_t hsize[2] = {1000, 1000}; +plist = H5Pcreate (H5P_DATASET_CREATE); +H5Pset_chunk (plist, 2, size); + </pre></code> + </td> + </tr> + </table> + </center> + + + <p>Although it is most efficient if I/O requests are aligned on chunk + boundaries, this is not a constraint. The application can perform I/O + on any set of data points as long as the set can be described by the + data space. The set on which I/O is performed is called the + <em>selection</em>. + + <h2>3. Compression Properties</h2> + + <p>Some types of storage layout allow data compression which is + defined by the functions described here. <b>Compression is not + implemented yet.</b> + + <dl> + <dt><code>herr_t H5Pset_compression (hid_t <em>plist_id</em>, + H5Z_method_t <em>method</em>)</code> + <dt><code>H5Z_method_t H5Pget_compression (hid_t + <em>plist_id</em>)</code> + <dd>These functions set and query the compression method that + is used to compress the raw data of a dataset. The + <em>plist_id</em> is a dataset creation property list. The + possible values for the compression method are: + + <br><br> + <dl> + <dt><code>H5Z_NONE</code> + <dd>This is the default and specifies that no compression is + to be performed. + + <br><br> + <dt><code>H5Z_DEFLATE</code> + <dd>This specifies that a variation of the Lempel-Ziv 1977 + (LZ77) encoding is used, the same encoding used by the + free GNU <code>gzip</code> program. + </dl> + + <br><br> + <dt><code>herr_t H5Pset_deflate (hid_t <em>plist_id</em>, + int <em>level</em>)</code> + <dt><code>int H5Pget_deflate (hid_t <em>plist_id</em>)</code> + <dd>These functions set or query the deflate level of + dataset creation property list <em>plist_id</em>. The + <code>H5Pset_deflate()</code> sets the compression method to + <code>H5Z_DEFLATE</code> and sets the compression level to + some integer between one and nine (inclusive). One results in + the fastest compression while nine results in the best + compression ratio. The default value is six if + <code>H5Pset_deflate()</code> isn't called. The + <code>H5Pget_deflate()</code> returns the compression level + for the deflate method, or negative if the method is not the + deflate method. + </dl> + + <h2>4. External Storage Properties</h2> + + <p>Some storage formats may allow storage of data across a set of + non-HDF5 files. Currently, only the <code>H5D_CONTIGUOUS</code> storage + format allows external storage. A set segments (offsets and sizes) in + one or more files is defined as an external file list, or <em>EFL</em>, + and the contiguous logical addresses of the data storage are mapped onto + these segments. + + <dl> + <dt><code>herr_t H5Pset_external (hid_t <em>plist</em>, const + char *<em>name</em>, off_t <em>offset</em>, hsize_t + <em>size</em>)</code> + <dd>This function adds a new segment to the end of the external + file list of the specified dataset creation property list. The + segment begins a byte <em>offset</em> of file <em>name</em> and + continues for <em>size</em> bytes. The space represented by this + segment is adjacent to the space already represented by the external + file list. The last segment in a file list may have the size + <code>H5F_UNLIMITED</em>. + + <br><br> + <dt><code>int H5Pget_external_count (hid_t <em>plist</em>)</code> + <dd>Calling this function returns the number of segments in an + external file list. If the dataset creation property list has no + external data then zero is returned. + + <br><br> + <dt><code>herr_t H5Pget_external (hid_t <em>plist</em>, int + <em>idx</em>, size_t <em>name_size</em>, char *<em>name</em>, off_t + *<em>offset</em>, hsize_t *<em>size</em>)</code> + <dd>This is the counterpart for the <code>H5Pset_external()</code> + function. Given a dataset creation property list and a zero-based + index into that list, the file name, byte offset, and segment size are + returned through non-null arguments. At most <em>name_size</em> + characters are copied into the <em>name</em> argument which is not + null terminated if the file name is longer than the supplied name + buffer (this is similar to <code>strncpy()</code>). + </dl> + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example: Multiple Segments</h4></caption> + <tr> + <td> + <p>This example shows how a contiguous, one-dimensional dataset + is partitioned into three parts and each of those parts is + stored in a segment of an external file. The top rectangle + represents the logical address space of the dataset + while the bottom rectangle represents an external file. + <center> + <img alt="Multiple Segments" src="extern1.gif"> + </center> + + <p><code><pre> +plist = H5Pcreate (H5P_DATASET_CREATE); +H5Pset_external (plist, "velocity.data", 3000, 1000); +H5Pset_external (plist, "velocity.data", 0, 2500); +H5Pset_external (plist, "velocity.data", 4500, 1500); + </pre></code> + + <p>One should note that the segments are defined in order of the + logical addresses they represent, not their order within the + external file. It would also have been possible to put the + segments in separate files. Care should be taken when setting + up segments in a single file since the library doesn't + automatically check for segments that overlap. + </td> + </tr> + </table> + </center> + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example: Multi-Dimensional</h4></caption> + <tr> + <td> + <p>This example shows how a contiguous, two-dimensional dataset + is partitioned into three parts and each of those parts is + stored in a separate external file. The top rectangle + represents the logical address space of the dataset + while the bottom rectangles represent external files. + <center> + <img alt="Multiple Dimensions" src="extern2.gif"> + </center> + + <p><code><pre> +plist = H5Pcreate (H5P_DATASET_CREATE); +H5Pset_external (plist, "scan1.data", 0, 24); +H5Pset_external (plist, "scan2.data", 0, 24); +H5Pset_external (plist, "scan3.data", 0, 16); + </pre></code> + + <p>The library maps the multi-dimensional array onto a linear + address space like normal, and then maps that address space + into the segments defined in the external file list. + </td> + </tr> + </table> + </center> + + <p>The segments of an external file can exist beyond the end of the + file. The library reads that part of a segment as zeros. When writing + to a segment that exists beyond the end of a file, the file is + automatically extended. Using this feature, one can create a segment + (or set of segments) which is larger than the current size of the + dataset, which allows to dataset to be extended at a future time + (provided the data space also allows the extension). + + <p>All referenced external data files must exist before performing raw + data I/O on the dataset. This is normally not a problem since those + files are being managed directly by the application, or indirectly + through some other library. + + + <h2>5. Data Type</h2> + + <p>Raw data has a constant data type which describes the data type + of the raw data stored in the file, and a memory data type that + describes the data type stored in application memory. Both data + types are manipulated with the <a + href="Datatypes.html"><code>H5T</code></a> API. + + <p>The constant file data type is associated with the dataset when + the dataset is created in a manner described below. Once + assigned, the constant datatype can never be changed. + + <p>The memory data type is specified when data is transferred + to/from application memory. In the name of data sharability, + the memory data type must be specified, but can be the same + type identifier as the constant data type. + + <p>During dataset I/O operations, the library translates the raw + data from the constant data type to the memory data type or vice + versa. Structured data types include member offsets to allow + reordering of struct members and/or selection of a subset of + members and array data types include index permutation + information to allow things like transpose operations (<b>the + prototype does not support array reordering</b>) Permutations + are relative to some extrinsic descritpion of the dataset. + + + + <h2>6. Data Space</h2> + + <p>The dataspace of a dataset defines the number of dimensions + and the size of each dimension and is manipulated with the + <code>H5S</code> API. The <em>simple</em> dataspace consists of + maximum dimension sizes and actual dimension sizes, which are + usually the same. However, maximum dimension sizes can be the + constant <code>H5D_UNLIMITED</code> in which case the actual + dimension size can be incremented with calls to + <code>H5Dextend()</code>. The maximium dimension sizes are + constant meta data while the actual dimension sizes are + persistent meta data. Initial actual dimension sizes are + supplied at the same time as the maximum dimension sizes when + the dataset is created. + + <p>The dataspace can also be used to define partial I/O + operations. Since I/O operations have two end-points, the raw + data transfer functions take two data space arguments: one which + describes the application memory data space or subset thereof + and another which describes the file data space or subset + thereof. + + + <h2>7. Setting Constant or Persistent Properties</h2> + + <p>Each dataset has a set of constant and persistent properties + which describe the layout method, pre-compression + transformation, compression method, data type, external storage, + and data space. The constant properties are set as described + above in a dataset creation property list whose identifier is + passed to <code>H5Dcreate()</code>. + + <dl> + <dt><code>hid_t H5Dcreate (hid_t <em>file_id</em>, const char + *<em>name</em>, hid_t <em>type_id</em>, hid_t + <em>space_id</em>, hid_t <em>create_plist_id</em>)</code> + <dd>A dataset is created by calling <code>H5Dcreate</code> with + a file identifier, a dataset name, a data type, a data space, + and constant properties. The data type and data space are the + type and space of the dataset as it will exist in the file, + which may be different than in application memory. The + <em>create_plist_id</em> 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 handle for success + or negative for failure. The handle should eventually be + closed by calling <code>H5Dclose()</code> to release resources + it uses. + + <br><br> + <dt><code>hid_t H5Dopen (hid_t <em>file_id</em>, const char + *<em>name</em>)</code> + <dd>An existing dataset can be opened for access by calling this + function. A dataset handle is returned for success or a + negative value is returned for failure. The handle should + eventually be closed by calling <code>H5Dclose()</code> to + release resources it uses. + + <br><br> + <dt><code>herr_t H5Dclose (hid_t <em>dataset_id</em>)</code> + <dd>This function closes a dataset handle and releases all + resources it might have been using. The handle should not be + used in subsequent calls to the library. + + <br><br> + <dt><code>herr_t H5Dextend (hid_t <em>dataset_id</em>, + hsize_t <em>dim</em>[])</code> + <dd>This function extends a dataset by increasing the size in + one or more dimensions. Not all datasets can be extended. + </dl> + + + + <h2>8. Querying Constant or Persistent Properties</h2> + + <p>Constant or persistent properties can be queried with a set of + three functions. Each function returns an identifier for a copy + of the requested properties. The identifier can be passed to + various functions which modify the underlying object to derive a + new object; the original dataset is completely unchanged. The + return values from these functions should be properly destroyed + when no longer needed. + + <dl> + <dt><code>hid_t H5Dget_type (hid_t <em>dataset_id</em>)</code> + <dd>Returns an identifier for a copy of the dataset permanent + data type or negative for failure. + + <dt><code>hid_t H5Dget_space (hid_t <em>dataset_id</em>)</code> + <dd>Returns an identifier for a copy of the dataset permanent + data space, which also contains information about the current + size of the dataset if the data set is extendable with + <code>H5Dextend()</code>. + + <dt><code>hid_t H5Dget_create_plist (hid_t + <em>dataset_id</em>)</code> + <dd>Returns an identifier for a copy of the dataset creation + property list. The new property list is created by examining + various permanent properties of the dataset. This is mostly a + catch-all for everything but type and space. + </dl> + + + + <h2>9. Setting Memory and Transfer Properties</h2> + + <p>A dataset also has memory properties which describe memory + within the application, and transfer properties that control + various aspects of the I/O operations. The memory can have a + data type different than the permanent file data type (different + number types, different struct member offsets, different array + element orderings) and can also be a different size (memory is a + subset of the permanent dataset elements, or vice versa). The + transfer properties might provide caching hints or collective + I/O information. Therefore, each I/O operation must specify + memory and transfer properties. + + <p>The memory properties are specified with <em>type_id</em> and + <em>space_id</em> arguments while the transfer properties are + specified with the <em>transfer_id</em> property list for the + <code>H5Dread()</code> and <code>H5Dwrite()</code> functions + (these functions are described below). + + <dl> + <dt><code>herr_t H5Pset_buffer (hid_t <em>xfer_plist</em>, + size_t <em>max_buf_size</em>, void *<em>tconv_buf</em>, void + *<em>bkg_buf</em>)</code> + <dt><code>size_t H5Pget_buffer (hid_t <em>xfer_plist</em>, void + **<em>tconv_buf</em>, void **<em>bkg_buf</em>)</code> + <dd>Sets or retrieves the maximum size in bytes of the temporary + buffer used for data type conversion in the I/O pipeline. An + application-defined buffer can also be supplied as the + <em>tconv_buf</em> argument, otherwise a buffer will be + allocated and freed on demand by the library. A second + temporary buffer <em>bkg_buf</em> can also be supplied and + should be the same size as the <em>tconv_buf</em>. The + default values are 1MB for the maximum buffer size, and null + pointers for each buffer indicating that they should be + allocated on demand and freed when no longer needed. The + <code>H5Pget_buffer()</code> function returns the maximum + buffer size or zero on error. + </dl> + + <p>If the maximum size of the temporary I/O pipeline buffers is + too small to hold the entire I/O request, then the I/O request + will be fragmented and the transfer operation will be strip + mined. However, certain restrictions apply to the strip + mining. For instance, when performing I/O on a hyperslab of a + simple data space the strip mining is in terms of the slowest + varying dimension. So if a 100x200x300 hyperslab is requested, + the temporary buffer must be large enough to hold a 1x200x300 + sub-hyperslab. + + <p>To prevent strip mining from happening, the application should + use <code>H5Pset_buffer()</code> to set the size of the + temporary buffer so it's large enough to hold the entire + request. + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example</h4></caption> + <tr> + <td> + <p>This example shows how to define a function that sets + a dataset transfer property list so that strip mining + does not occur. It takes an (optional) dataset transfer + property list, a dataset, a data space that describes + what data points are being transfered, and a data type + for the data points in memory. It returns a (new) + dataset transfer property list with the temporary + buffer size set to an appropriate value. The return + value should be passed as the fifth argument to + <code>H5Dread()</code> or <code>H5Dwrite()</code>. + <p><code><pre> + 1 hid_t + 2 disable_strip_mining (hid_t xfer_plist, hid_t dataset, + 3 hid_t space, hid_t mem_type) + 4 { + 5 hid_t file_type; /* File data type */ + 6 size_t type_size; /* Sizeof larger type */ + 7 size_t size; /* Temp buffer size */ + 8 hid_t xfer_plist; /* Return value */ + 9 +10 file_type = H5Dget_type (dataset); +11 type_size = MAX(H5Tget_size(file_type), H5Tget_size(mem_type)); +12 H5Tclose (file_type); +13 size = H5Sget_npoints(space) * type_size; +14 if (xfer_plist<0) xfer_plist = H5Pcreate (H5P_DATASET_XFER); +15 H5Pset_buffer(xfer_plist, size, NULL, NULL); +16 return xfer_plist; +17 } + </pre></code> + </td> + </tr> + </table> + </center> + + + + <h2>10. Querying Memory or Transfer Properties</h2> + + <p>Unlike constant and persistent properties, a dataset cannot be + queried for it's memory or transfer properties. Memory + properties cannot be queried because the application already + stores those properties separate from the buffer that holds the + raw data, and the buffer may hold multiple segments from various + datasets and thus have more than one set of memory properties. + The transfer properties cannot be queried from the dataset + because they're associated with the transfer itself and not with + the dataset (but one can call + <code>H5Pget_<em>property</em>()</code> to query transfer + properties from a tempalate). + + + <h2>11. Raw Data I/O</h2> + + <p>All raw data I/O is accomplished through these functions which + take a dataset handle, a memory data type, a memory data space, + a file data space, transfer properties, and an application + memory buffer. They translate data between the memory data type + and space and the file data type and space. The data spaces can + be used to describe partial I/O operations. + + <dl> + <dt><code>herr_t H5Dread (hid_t <em>dataset_id</em>, hid_t + <em>mem_type_id</em>, hid_t <em>mem_space_id</em>, hid_t + <em>file_space_id</em>, hid_t <em>xfer_plist_id</em>, + void *<em>buf</em>/*out*/)</code> + <dd>Reads raw data from the specified dataset into <em>buf</em> + converting from file data type and space to memory data type + and space. + + <br><br> + <dt><code>herr_t H5Dwrite (hid_t <em>dataset_id</em>, hid_t + <em>mem_type_id</em>, hid_t <em>mem_space_id</em>, hid_t + <em>file_space_id</em>, hid_t <em>xfer_plist_id</em>, + const void *<em>buf</em>)</code> + <dd>Writes raw data from an application buffer <em>buf</em> to + the specified dataset converting from memory data type and + space to file data type and space. + </dl> + + + <p>In the name of sharability, the memory datatype must be + supplied. However, it can be the same identifier as was used to + create the dataset or as was returned by + <code>H5Dget_type()</code>; the library will not implicitly + derive memory data types from constant data types. + + <p>For complete reads of the dataset one may supply + <code>H5S_ALL</code> as the argument for the file data space. + If <code>H5S_ALL</code> is also supplied as the memory data + space then no data space conversion is performed. This is a + somewhat dangerous situation since the file data space might be + different than what the application expects. + + + + <h2>12. Examples</h2> + + <p>The examples in this section illustrate some common dataset + practices. + + + <p>This example shows how to create a dataset which is stored in + memory as a two-dimensional array of native <code>double</code> + values but is stored in the file in Cray <code>float</code> + format using LZ77 compression. The dataset is written to the + HDF5 file and then read back as a two-dimensional array of + <code>float</code> values. + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example 1</h4></caption> + <tr> + <td> + <p><code><pre> + 1 hid_t file, data_space, dataset, properties; + 2 double dd[500][600]; + 3 float ff[500][600]; + 4 hsize_t dims[2], chunk_size[2]; + 5 + 6 /* Describe the size of the array */ + 7 dims[0] = 500; + 8 dims[1] = 600; + 9 data_space = H5Screate_simple (2, dims); +10 +11 +12 /* +13 * Create a new file using with read/write access, +14 * default file creation properties, and default file +15 * access properties. +16 */ +17 file = H5Fcreate ("test.h5", H5F_ACC_RDWR, H5P_DEFAULT, +18 H5P_DEFAULT); +19 +20 /* +21 * Set the dataset creation plist to specify that +22 * the raw data is to be partitioned into 100x100 element +23 * chunks and that each chunk is to be compressed with +24 * LZ77. +25 */ +26 chunk_size[0] = chunk_size[1] = 100; +27 properties = H5Pcreate (H5P_DATASET_CREATE); +28 H5Pset_chunk (properties, 2, chunk_size); +29 H5Pset_compression (properties, H5D_COMPRESS_LZ77); +30 +31 /* +32 * Create a new dataset within the file. The data type +33 * and data space describe the data on disk, which may +34 * be different than the format used in the application's +35 * memory. +36 */ +37 dataset = H5Dcreate (file, "dataset", H5T_CRAY_FLOAT, +38 data_space, properties); +39 +40 /* +41 * Write the array to the file. The data type and data +42 * space describe the format of the data in the `dd' +43 * buffer. The raw data is translated to the format +44 * required on disk defined above. We use default raw +45 * data transfer properties. +46 */ +47 H5Dwrite (dataset, H5T_NATIVE_DOUBLE, H5S_ALL, H5S_ALL, +48 H5P_DEFAULT, dd); +49 +50 /* +51 * Read the array as floats. This is similar to writing +52 * data except the data flows in the opposite direction. +53 */ +54 H5Dread (dataset, H5T_NATIVE_FLOAT, H5S_ALL, H5S_ALL, +55 H5P_DEFAULT, ff); +56 +64 H5Dclose (dataset); +65 H5Sclose (data_space); +66 H5Pclose (properties); +67 H5Fclose (file); + </pre></code> + </td> + </tr> + </table> + </center> + + <p>This example uses the file created in Example 1 and reads a + hyperslab of the 500x600 file dataset. The hyperslab size is + 100x200 and it is located beginning at element + <200,200>. We read the hyperslab into an 200x400 array in + memory beginning at element <0,0> in memory. Visually, + the transfer looks something like this: + + <center> + <img alt="Raw Data Transfer" src="dataset_p1.gif"> + </center> + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example 2</h4></caption> + <tr> + <td> + <p><code><pre> + 1 hid_t file, mem_space, file_space, dataset; + 2 double dd[200][400]; + 3 hssize_t offset[2]; + 4 hsize size[2]; + 5 + 6 /* + 7 * Open an existing file and its dataset. + 8 */ + 9 file = H5Fopen ("test.h5", H5F_ACC_RDONLY, H5P_DEFAULT); +10 dataset = H5Dopen (file, "dataset"); +11 +12 /* +13 * Describe the file data space. +14 */ +15 offset[0] = 200; /*offset of hyperslab in file*/ +16 offset[1] = 200; +17 size[0] = 100; /*size of hyperslab*/ +18 size[1] = 200; +19 file_space = H5Dget_space (dataset); +20 H5Sset_hyperslab (file_space, 2, offset, size); +21 +22 /* +23 * Describe the memory data space. +24 */ +25 size[0] = 200; /*size of memory array*/ +26 size[1] = 400; +27 mem_space = H5Screate_simple (2, size); +28 +29 offset[0] = 0; /*offset of hyperslab in memory*/ +30 offset[1] = 0; +31 size[0] = 100; /*size of hyperslab*/ +32 size[1] = 200; +33 H5Sset_hyperslab (mem_space, 2, offset, size); +34 +35 /* +36 * Read the dataset. +37 */ +38 H5Dread (dataset, H5T_NATIVE_DOUBLE, mem_space, +39 file_space, H5P_DEFAULT, dd); +40 +41 /* +42 * Close/release resources. +43 */ +44 H5Dclose (dataset); +45 H5Sclose (mem_space); +46 H5Sclose (file_space); +47 H5Fclose (file); + </pre></code> + </td> + </tr> + </table> + </center> + + <p>If the file contains a compound data structure one of whose + members is a floating point value (call it "delta") but the + application is interested in reading an array of floating point + values which are just the "delta" values, then the application + should cast the floating point array as a struct with a single + "delta" member. + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example 3</h4></caption> + <tr> + <td> + <p><code><pre> + 1 hid_t file, dataset, type; + 2 double delta[200]; + 3 + 4 /* + 5 * Open an existing file and its dataset. + 6 */ + 7 file = H5Fopen ("test.h5", H5F_ACC_RDONLY, H5P_DEFAULT); + 8 dataset = H5Dopen (file, "dataset"); + 9 +10 /* +11 * Describe the memory data type, a struct with a single +12 * "delta" member. +13 */ +14 type = H5Tcreate (H5T_COMPOUND, sizeof(double)); +15 H5Tinsert (type, "delta", 0, H5T_NATIVE_DOUBLE); +16 +17 /* +18 * Read the dataset. +19 */ +20 H5Dread (dataset, type, H5S_ALL, H5S_ALL, +21 H5P_DEFAULT, dd); +22 +23 /* +24 * Close/release resources. +25 */ +26 H5Dclose (dataset); +27 H5Tclose (type); +28 H5Fclose (file); + </pre></code> + </td> + </tr> + </table> + </center> + + <hr> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- Created: Tue Dec 2 09:17:09 EST 1997 --> +<!-- hhmts start --> +Last modified: Wed May 13 18:57:47 EDT 1998 +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/Dataspaces.html b/doc/html/Dataspaces.html new file mode 100644 index 0000000..d2579b6 --- /dev/null +++ b/doc/html/Dataspaces.html @@ -0,0 +1,568 @@ +<HTML> +<HEAD> + <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> + <TITLE>The Data Space Interface (H5S)</TITLE> +</HEAD> +<BODY> + +<H1> +The Dataspace Interface (H5S)</H1> + +<H2> +1. Introduction</H2> +The dataspace interface (H5S) provides a mechanism to describe the positions +of the elements of a dataset and is designed in such a way as to allow +new features to be easily added without disrupting applications that use +the dataspace interface. A dataset (defined with the dataset interface) is +composed of a collection of raw data points of homogeneous type, defined in the +datatype (H5T) interface, organized according to the dataspace with this +interface. + +<P>A dataspace describes the locations that dataset elements are located at. +A dataspace is either a regular N-dimensional array of data points, +called a <I>simple</I> dataspace, or a more general collection of data +points organized in another manner, called a <I>complex</I> dataspace. +A <I>scalar</I> dataspace is a special case of the <I>simple</I> data +space and is defined to be a 0-dimensional single data point in size. Currently +only <I>scalar</I> and <I>simple</I> dataspaces are supported with this version +of the H5S interface. +<I>Complex</I> dataspaces will be defined and implemented in a future +version. <I>Complex</I> dataspaces are intended to be used for such structures +which are awkward to express in <I>simple</I> dataspaces, such as irregularly +gridded data or adaptive mesh refinement data. This interface provides +functions to set and query properties of a dataspace. + +<P>Operations on a dataspace include defining or extending the extent of +the dataspace, selecting portions of the dataspace for I/O and storing the +dataspaces in the file. The extent of a dataspace is the range of coordinates +over which dataset elements are defined and stored. Dataspace selections are +subsets of the extent (up to the entire extent) which are selected for some +operation. + +<P>For example, a 2-dimensional dataspace with an extent of 10 by 10 may have +the following very simple selection: + <br><br><center> + <table border cellpadding=4> + <tr align=center> + <th > </th> <th >0</th> <th >1</th> <th >2</th> <th >3</th> <th >4</th> <th >5</th> <th >6</th> <th >7</th> <th >8</th> <th >9</th> + <tr align=center> + <th>0</th> + <td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>1</th> + <td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>2</th> + <td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>3</th> + <td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>4</th> + <td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>5</th> + <td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>6</th> + <td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>7</th> + <td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>8</th> + <td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>9</th> + <td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + </table> + <br><strong>Example 1: Contiguous rectangular selection</strong> + </center> + + +<br>Or, a more complex selection may be defined: + <br><br><center> + <table border cellpadding=4> + <tr align=center> + <th > </th> <th >0</th> <th >1</th> <th >2</th> <th >3</th> <th >4</th> <th >5</th> <th >6</th> <th >7</th> <th >8</th> <th >9</th> + <tr align=center> + <th>0</th> + <td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>1</th> + <td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>X</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>2</th> + <td>-</td><td>X</td><td>-</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>3</th> + <td>-</td><td>X</td><td>-</td><td>X</td><td>-</td><td>-</td><td>X</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>4</th> + <td>-</td><td>X</td><td>-</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>5</th> + <td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>X</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>6</th> + <td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>7</th> + <td>-</td><td>-</td><td>X</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>8</th> + <td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>9</th> + <td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + </table> + <br><strong>Example 2: Non-contiguous selection</strong> + </center> + +<P>Selections within dataspaces have an offset within the extent which is used +to locate the selection within the extent of the dataspace. Selection offsets +default to 0 in each dimension, but may be changed to move the selection within +a dataspace. In example 2 above, if the offset was changed to 1,1, the selection +would look like this: + <br><br><center> + <table border cellpadding=4> + <tr align=center> + <th > </th> <th >0</th> <th >1</th> <th >2</th> <th >3</th> <th >4</th> <th >5</th> <th >6</th> <th >7</th> <th >8</th> <th >9</th> + <tr align=center> + <th>0</th> + <td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>1</th> + <td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>2</th> + <td>-</td><td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>X</td><td>-</td><td>-</td> + <tr align=center> + <th>3</th> + <td>-</td><td>-</td><td>X</td><td>-</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>4</th> + <td>-</td><td>-</td><td>X</td><td>-</td><td>X</td><td>-</td><td>-</td><td>X</td><td>-</td><td>-</td> + <tr align=center> + <th>5</th> + <td>-</td><td>-</td><td>X</td><td>-</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>6</th> + <td>-</td><td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>X</td><td>-</td><td>-</td> + <tr align=center> + <th>7</th> + <td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>8</th> + <td>-</td><td>-</td><td>-</td><td>X</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>-</td> + <tr align=center> + <th>9</th> + <td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td> + </table> + <br><strong>Example 3: Non-contiguous selection with 1,1 offset</strong> + </center> + +<P>Selections also have an linearization ordering of the points selected +(defaulting to "C" order, ie. last dimension changing fastest). The +linearization order may be specified for each point or it may be chosen by +the axis of the dataspace. For example, with the default "C" ordering, +example 1's selected points are iterated through in this order: (1,1), (2,1), +(3,1), (1,2), (2,2), etc. With "FORTRAN" ordering, example 1's selected points +would be iterated through in this order: (1,1), (1,2), (1,3), (1,4), (1,5), +(2,1), (2,2), etc. + +<P>A dataspace may be stored in the file as a permanent object, to allow many +datasets to use a commonly defined dataspace. Dataspaces with extendable +extents (ie. unlimited dimensions) are not able to be stored as permanent +dataspaces. + +<P>Dataspaces may be created using an existing permanent dataspace as a +container to locate the new dataspace within. These dataspaces are complete +dataspaces and may be used to define datasets. A dataspaces with a "parent" +can be queried to determine the parent dataspace and the location within the +parent. These dataspaces must currently be the same number of dimensions as +the parent dataspace. + +<H2> 2. General Dataspace Operations</H2> +The functions defined in this section operate on dataspaces as a whole. +New dataspaces can be created from scratch or copied from existing data +spaces. When a dataspace is no longer needed its resources should be released +by calling <TT>H5Sclose()</TT>. +<DL> + +<DT> +<TT>hid_t H5Screate(H5S_class_t <I>type</I>)</TT></DT> + +<DD> + This function creates a new dataspace of a particular <I>type</I>. The +types currently supported are H5S_SCALAR, H5S_SIMPLE, or H5S_NONE, although +others are planned to be added later. The H5S_NONE dataspace can only hold a +selection, not an extent. +</DD> + +<DT> +<TT>hid_t H5Sopen(hid_t <I>location</I>, const char *<I>name</I>)</TT></DT> + +<DD> + This function opens a permanent dataspace for use in an application. +The <I>location</I> argument is a file or group ID and <I>name</I> is +an absolute or relative path to the permanent dataspace. The dataspace ID which +is returned is a handle to a permanent dataspace which can't be modified. +</DD> + +<DT> +<TT>hid_t H5Scopy (hid_t <I>space</I>)</TT></DT> + +<DD> + This function creates a new dataspace which is an exact copy of the +dataspace <I>space</I>. +</DD> + +<DT> +<TT>hid_t H5Ssubspace (hid_t <I>space</I>)</TT></DT> + +<DD> + This function uses the currently defined selection and offset in <I>space</I> +to create a dataspace which is located within <I>space</I>. The <I>space</I> +dataspace must be a sharable dataspace located in the file, not a dataspace for +a dataset. The relationship of the new dataspace within the existing dataspace +is preserved when the new dataspace is used to create datasets. Currently, +only subspaces which are equivalent to simple dataspaces (ie. rectangular +contiguous areas) are allowed. A subspace is not "simplified" or reduced in +the number of dimensions used if the selection is "flat" in one dimension, they +always have the same number of dimensions as their parent dataspace. +</DD> + +<DT> +<TT>herr_t H5Scommit (hid_t <I>location</I>, const char *<I>name</I>, hid_t <I>space</I>)</TT></DT> + +<DD> + The dataspaces specified with <I>space</I> is stored in the file specified +by <I>location</I>. <I>Location</I> may be either a file or group handle +and <I>name</I> is an absolute or relative path to the location to store the +dataspace. After this call, the dataspace is permanent and can't be modified. +</DD> + +<DT> +<TT>herr_t H5Sclose (hid_t <I>space</I>)</TT></DT> + +<DD> +Releases resources associated with a dataspace. Subsequent use of the +dataspace identifier after this call is undefined. +</DD> + +<DT> +<TT>H5S_class_t H5Sget_class (hid_t <I>space</I>)</TT></DT> + +<DD> +Query a dataspace to determine the current class of a dataspace. The value +which is returned is one of: H5S_SCALAR, H5S_SIMPLE, or H5S_NONE on success or +FAIL on failure. +</DD> +</DL> + + +<H2> 3. Dataspace Extent Operations</H2> +These functions operate on the extent portion of a dataspace. + +<DL> +<DT> +<TT>herr_t H5Sset_extent_simple (hid_t <I>space</I>, int <I>rank</I>, const hsize_t +*<I>current_size</I>, const hsize_t *<I>maximum_size</I>)</TT></DT> + +<DD> +Sets or resets the size of an existing dataspace, where <I>rank</I> is +the dimensionality, or number of dimensions, of the dataspace. +<I>current_size</I> is an array of size <I>rank</I> which contains the new size +of each dimension in the dataspace. <I>maximum_size</I> is an array of size +<I>rank</I> which contains the maximum size of each dimension in the dataspace. +Any previous extent is removed from the dataspace, the dataspace type is set to +H5S_SIMPLE and the extent is set as specified. +</DD> + +<DT> +<TT>herr_t H5Sset_extent_none (hid_t <I>space</I>)</TT></DT> + +<DD> +Removes the extent from a dataspace and sets the type to H5S_NONE. +</DD> + +<DT> +<TT>herr_t H5Sextent_copy (hid_t <I>dest_space</I>, + hid_t <I>source_space</I>)</TT></DT> + +<DD> +Copies the extent from <I>source_space</I> to <I>dest_space</I>, which may +change the type of the dataspace. Returns non-negative on success, negative on +failure. +</DD> + +<DT> +<TT>hsize_t H5Sextent_npoints (hid_t <I>space</I>)</TT></DT> + +<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. +Returns the number of elements in the dataspace, negative on failure. +</DD> + +<DT> +<TT>int H5Sextent_ndims (hid_t <I>space</I>)</TT></DT> + +<DD> +This function determines the dimensionality (or rank) of a dataspace. +Returns the number of dimensions in the dataspace, negative on failure. +</DD> + +<DT> +<TT>herr_t H5Sextent_dims (hid_t <I>space</I>, hsize_t *<I>dims</I>, + hsize_t *<I>max</I>)</TT></DT> + +<DD> +The function retrieves the size of the extent of the dataspace <I>space</I> by +placing the size of each dimension in the array <I>dims</I>. Also retrieves +the size of the maximum extent of the dataspace, placing the results in +<I>max</I>. +Returns non-negative on success, negative on failure. +</DD> + +</DL> + +<H2> 4. Dataspace Selection Operations</H2> +Selections are maintained separately from extents in dataspaces and operations +on the selection of a dataspace do not affect the extent of the dataspace. +Selections are independent of extent type and the boundaries of selections are +reconciled with the extent at the time of the data transfer. Selection offsets +apply a selection to a location within an extent, allowing the same selection +to be moved within the extent without requiring a new selection to be specified. +Offsets default to 0 when the dataspace is created. Offsets are applied when +an I/O transfer is performed (and checked during calls to H5Sselect_valid). +Selections have an iteration order for the points selected, which can be any +permutation of the dimensions involved (defaulting to 'C' array order) or a +specific order for the selected points, for selections composed of single array +elements with H5Sselect_elements. Selections can also be copied or combined +together in various ways with H5Sselect_op. Further methods of selecting +portions of a dataspace may be added in the future. + +<DL> +<DT> +<TT>herr_t H5Sselect_hyperslab (hid_t <I>space</I>, h5s_selopt_t <I>op</I>, + const hssize_t * <I>start</I>, const hsize_t * <I>stride</I>, + const hsize_t * <I>count</I>, const hsize_t * <I>block</I>)</TT></DT> + +<DD> +This function selects a hyperslab region to add to the current selected region +for the <I>space</I> dataspace. The <I>start</I>, <I>stride</I>, <I>count</I> +and <I>block</I> arrays must be the same size as the rank of the dataspace. +The selection operator <I>op</I> determines how the new selection is to be +combined with the already existing selection for the dataspace. Currently, +only the H5S_SELECT_SET operator is supported, which replaces the existing +selection with the parameters from this call. Overlapping blocks are not +supported with the H5S_SELECT_SET operator. +<P>The <I>start</I> array determines the starting coordinates of the hyperslab +to select. The <I>stride</I> array chooses array locations from the dataspace +with each value in the <I>stride</I> array determining how many elements to move +in each dimension. Setting a value in the <I>stride</I> array to 1 moves to +each element in that dimension of the dataspace, setting a value of 2 in a +location in the <I>stride</I> array moves to every other element in that +dimension of the dataspace. In other words, the <I>stride</I> determines the +number of elements to move from the <I>start</I> location in each dimension. +Stride values of 0 are not allowed. If the <I>stride</I> parameter is <TT>NULL</TT>, +a contiguous hyperslab is selected (as if each value in the <I>stride</I> array +was set to all 1's). The <I>count</I> array determines how many blocks to +select from the dataspace, in each dimension. The <I>block</I> array determines +the size of the element block selected from the dataspace. If the <I>block</I> +parameter is set to <TT>NULL</TT>, the block size defaults to a single element +in each dimension (as if the <I>block</I> array was set to all 1's). +<P>For example, in a 2-dimensional dataspace, setting <I>start</I> to [1,1], +<I>stride</I> to [4,4], <I>count</I> to [3,7] and <I>block</I> to [2,2] selects +21 2x2 blocks of array elements starting with location (1,1) and selecting +blocks at locations (1,1), (5,1), (9,1), (1,5), (5,5), etc. +<P>Regions selected with this function call default to 'C' order iteration when +I/O is performed. +</DD> + +<DT> +<TT>herr_t H5Sselect_elements (hid_t <I>space</I>, h5s_selopt_t <I>op</I>, + const size_t <I>num_elements</I>, const hssize_t *<I>coord</I>[])</TT></DT> + +<DD> +This function selects array elements to be included in the selection for the +<I>space</I> dataspace. The number of elements selected must be set with the +<I>num_elements</I>. The <I>coord</I> array is a two-dimensional array of size +<dataspace rank> by <<I>num_elements</I>> in size (ie. a list of +coordinates in the array). The order of the element coordinates in the +<I>coord</I> array also specifies the order that the array elements are +iterated through when I/O is performed. Duplicate coordinate locations are not +checked for. + +<P>The selection operator <I>op</I> determines how the new selection is to be +combined with the already existing selection for the dataspace. Currently, +only the H5S_SELECT_SET operator is supported, which replaces the existing +selection with the parameters from this call. When operators other than +H5S_SELECT_SET are used to combine a new selection with an existing selection, +the selection ordering is reset to 'C' array ordering. +</DD> + +<DT> +<TT>herr_t H5Sselect_all (hid_t <I>space</I>)</TT></DT> + +<DD> +This function selects the special H5S_SELECT_ALL region for the <I>space</I> +dataspace. H5S_SELECT_ALL selects the entire dataspace for any dataspace is is +applied to. +</DD> + +<DT> +<TT>herr_t H5Sselect_none (hid_t <I>space</I>)</TT></DT> + +<DD> +This function resets the selection region for the <I>space</I> +dataspace not to include any elements. +</DD> + +<DT> +<TT>herr_t H5Sselect_op (hid_t <I>space1</I>, h5s_selopt_t <I>op</I>, + hid_t <I>space2</I>)</TT></DT> + +<DD> +Uses <I>space2</I> to perform an operation on <I>space1</I>. The valid +operations for <I>op</I> are: +<DL> + <DT>H5S_SELECT_COPY + <DD>Copies the selection from <I>space2</I> into <I>space1</I>, removing any + previously defined selection for <I>space1</I>. The selection order + and offset are also copied to <I>space1</I> + <DT>H5S_SELECT_UNION + <DD>Performs a set union of the selection of the dataspace <I>space2</I> + with the selection from the dataspace <I>space1</I>, with the result + being stored in <I>space1</I>. The selection order for <I>space1</I> is + reset to 'C' order. + <DT>H5S_SELECT_INTERSECT + <DD>Performs an set intersection of the selection from <I>space2</I> with + <I>space1</I>, with the result being stored in <I>space1</I>. The + selection order for <I>space1</I> is reset to 'C' order. + <DT>H5S_SELECT_DIFFERENCE + <DD>Performs a set difference of the selection from <I>space2</I> with + <I>space1</I>, with the result being stored in <I>space1</I>. The + selection order for <I>space1</I> is reset to 'C' order. +</DL> + +</DD> + +<DT> +<TT>herr_t H5Sselect_order (hid_t <I>space</I>, + hsize_t <I>perm_vector</I>[])</TT></DT> + +<DD> +This function selects the order to iterate through the dimensions of a dataspace +when performing I/O on a selection. If a specific order has already been +selected for the selection with H5Sselect_elements, this function will remove +it and use a dimension oriented ordering on the selected elements. The elements +of the <I>perm_vector</I> array must be unique and between 0 and the rank of the +dataspace, minus 1. The order of the elements in <I>perm_vector</I> specify +the order to iterate through the selection for each dimension of the dataspace. +To iterate through a 3-dimensional dataspace selection in 'C' order, specify +the elements of the <I>perm_vector</I> as [0, 1, 2], for FORTRAN order they +would be [2, 1, 0]. Other orderings, such as [1, 2, 0] are also possible, but +may execute slower. +</DD> + +<DT> +<TT>hbool_t H5Sselect_valid (hid_t <I>space</I>)</TT></DT> + +<DD> +This function verifies that the selection for a dataspace is within the extent +of the dataspace, if the currently set offset for the dataspace is used. +Returns TRUE if the selection is contained within the extent, FALSE if it +is not contained within the extent and FAIL on error conditions (such as if +the selection or extent is not defined). +</DD> + +<DT> +<TT>hsize_t H5Sselect_npoints (hid_t <I>space</I>)</TT></DT> + +<DD> +This function determines the number of elements in the current selection +of a dataspace. +</DD> + +<DT> +<TT>herr_t H5Soffset_simple (hid_t <I>space</I>, const hssize_t * + <I>offset</I>)</TT></DT> + +<DD> +Sets the offset of a simple dataspace <I>space</I>. The <I>offset</I> array +must be the same number of elements as the number of dimensions for the +dataspace. If the <I>offset</I> array is set to <TT>NULL</TT>, the offset +for the dataspace is reset to 0. +</DD> + +</DL> + +<H2> 5. Misc. Dataspace Operations</H2> + +<DL> + +<DT> +<TT>herr_t H5Slock (hid_t <I>space</I>)</TT></DT> + +<DD> +Locks the dataspace so that it cannot be modified or closed. When the library +exits, the dataspace will be unlocked and closed. +</DD> + +<DT> +<TT>hid_t H5Screate_simple(int <I>rank</I>, const hsize_t *<I>current_size</I>, + const hsize_t *<I>maximum_size</I>)</TT></DT> + +<DD> + This function is a "convenience" wrapper to create a simple dataspace +and set it's extent in one call. It is equivalent to calling H5Screate +and H5Sset_extent_simple() in two steps. +</DD> + +<DT> +<TT>int H5Sis_subspace(hid_t <I>space</I>)</TT></DT> + +<DD> + This function returns positive if <I>space</I> is located within another +dataspace, zero if it is not, and negative on a failure. +</DD> + +<DT> +<TT>char *H5Ssubspace_name(hid_t <I>space</I>)</TT></DT> + +<DD> + This function returns the name of the named dataspace that <I>space</I> +is located within. If <I>space</I> is not located within another dataspace, +or an error occurs, NULL is returned. The application is responsible for +freeing the string returned. +</DD> + +<DT> +<TT>herr_t H5Ssubspace_location(hid_t <I>space</I>, hsize_t *<I>loc</I>)</TT></DT> + +<DD> + If <I>space</I> is located within another dataspace, this function puts +the location of the origin of <I>space</I> in the <I>loc</I> array. The <I>loc</I> +array must be at least as large as the number of dimensions of <I>space</I>. +If <I>space</I> is not located within another dataspace +or an error occurs, a negative value is returned, otherwise a non-negative value +is returned. +</DD> + +</DL> + +<HR> +<ADDRESS> +<A HREF="mailto:matzke@llnl.gov">Robb Matzke</A></ADDRESS> + +<ADDRESS> +<A HREF="mailto:koziol@ncsa.uiuc.edu">Quincey Koziol</A></ADDRESS> + +<BR><!-- Created: Thu Dec 4 14:57:32 EST 1997 --><!-- hhmts start -->Last +modified: Thu May 28 15:12:04 EST 1998 <!-- hhmts end --> +</BODY> +</HTML> diff --git a/doc/html/Datatypes.html b/doc/html/Datatypes.html new file mode 100644 index 0000000..75bc57e --- /dev/null +++ b/doc/html/Datatypes.html @@ -0,0 +1,1370 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>The Data Type Interface (H5T)</title> + </head> + + <body> + <h1>The Data Type Interface (H5T)</h1> + + <h2>1. Introduction</h2> + + <p>The data type interface 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>data type</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. + + <h2>2. General Data Type Operations</h2> + + <p>The functions defined in this section operate on data types as + a whole. New data types can be created from scratch or copied + from existing data types. When a data type is no longer needed + its resources should be released by calling <code>H5Tclose()</code>. + + <p>Data types come in two flavors: named data types and transient + data types. A named data type is stored in a file while the + transient flavor is independent of any file. Named data types + are always read-only, but transient types come in three + varieties: modifiable, read-only, and immutable. The difference + between read-only and immutable types is that immutable types + cannot be closed except when the entire library is closed (the + predefined types like <code>H5T_NATIVE_INT</code> are immutable + transient types). + + <dl> + <dt><code>hid_t H5Tcreate (H5T_class_t <em>class</em>, size_t + <em>size</em>)</code> + <dd>Data types can be created by calling this + function, where <em>class</em> is a data type class + identifier. However, the only class currently allowed is + <code>H5T_COMPOUND</code> to create a new empty compound data + type where <em>size</em> is the total size in bytes of an + instance of this data type. Other data types are created with + <code>H5Tcopy()</code>. All functions that return data type + identifiers return a negative value for failure. + + <br><br> + <dt><code>hid_t H5Topen (hid_t <em>location</em>, const char + *<em>name</em>)</code> + <dd>A named data type can be opened by calling this function, + which returns a handle to the data type. The handle should + eventually be closed by calling <code>H5Tclose()</code> to + release resources. The named data type returned by this + function is read-only or a negative value is returned for + failure. The <em>location</em> is either a file or group + handle. + + <br><br> + <dt><code>herr_t H5Tcommit (hid_t <em>location</em>, const char + *<em>name</em>, hid_t <em>type</em>)</code> + <dd>A transient data type (not immutable) can be committed to a + file and turned into a named data type by calling this + function. The <em>location</em> is either a file or group + handle and when combined with <em>name</em> refers to a new + named data type. + + <br><br> + <dt><code>hbool_t H5Tcommitted (hid_t <em>type</em>)</code> + <dd>A type can be queried to determine if 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. + + <br><br> + <dt><code>hid_t H5Tcopy (hid_t <em>type</em>)</code> + <dd>This function returns a modifiable transient data type + which is a copy of <em>type</em> or a negative value for + failure. If <em>type</em> is a dataset handle then the type + returned is a modifiable transient copy of the data type of + the specified dataset. + + <br><br> + <dt><code>herr_t H5Tclose (hid_t <em>type</em>)</code> + <dd>Releases resources associated with a data type. The data + type identifier should not be subsequently used since the + results would be unpredictable. It is illegal to close an + immutable transient data type. + + <br><br> + <dt><code>hbool_t H5Tequal (hid_t <em>type1</em>, hid_t + <em>type2</em>)</code> + <dd>Determines if two types are equal. If <em>type1</em> and + <em>type2</em> are the same then this function returns + <code>TRUE</code>, otherwise it returns <code>FALSE</code> (an + error results in a negative return value). + + <br><br> + <dt><code>herr_t H5Tlock (hid_t <em>type</em>)</code> + <dd>A transient data type can be locked, making it immutable + (read-only and not closable). The library does this to all + predefined types to prevent the application from inadvertently + modifying or deleting (closing) them, but the application is + also allowed to do this for its own data types. Immutable + data types are closed when the library closes (either by + <code>H5close()</code> or by normal program termination). + </dl> + + <h2>3. Properties of Atomic Types</h2> + + <p>An atomic type is a type which cannot be decomposed into + smaller units at the API level. All atomic types have a common + set of properties which are augmented by properties specific to + a particular type class. Some of these properties also apply to + compound data types, but we discuss them only as they apply to + atomic data types here. The properties and the functions that + query and set their values are: + + <dl> + <dt><code>H5T_class_t H5Tget_class (hid_t <em>type</em>)</code> + <dd>This property holds one of the class names: + <code>H5T_INTEGER, H5T_FLOAT, H5T_TIME, H5T_STRING, + H5T_BITFIELD</code>, or <code>H5T_OPAQUE</code>. This + property is read-only and is set when the datatype is + created or copied (see <code>H5Tcreate()</code>, + <code>H5Tcopy()</code>). If this function fails it returns + <code>H5T_NO_CLASS</code> which has a negative value (all + other class constants are non-negative). + + <br><br> + <dt><code>size_t H5Tget_size (hid_t <em>type</em>)</code> + <dt><code>herr_t H5Tset_size (hid_t <em>type</em>, size_t + <em>size</em>)</code> + <dd>This property is total size of the datum in bytes, including + padding which may appear on either side of the actual value. + If this property is reset to a smaller value which would cause + the significant part of the data to extend beyond the edge of + the data type then the <code>offset</code> property is + decremented a bit at a time. If the offset reaches zero and + the significant part of the data still extends beyond the edge + of the data type then the <code>precision</code> property is + decremented a bit at a time. Decreasing the size of a data + type may fail if the precesion must be decremented and the + data type is of the <code>H5T_OPAQUE</code> class or the + <code>H5T_FLOAT</code> bit fields would extend beyond the + significant part of the type. Increasing the size of an + <code>H5T_STRING</code> automatically increases the precision + as well. On error, <code>H5Tget_size()</code> returns zero + which is never a valid size. + + <br><br> + <dt><code>H5T_order_t H5Tget_order (hid_t <em>type</em>)</code> + <dt><code>herr_t H5Tset_order (hid_t <em>type</em>, H5T_order_t + <em>order</em>)</code> + <dd>All atomic data types have a byte order which describes how + the bytes of the data type are layed out in memory. If the + lowest memory address contains the least significant byte of + the datum then it is said to be <em>little-endian</em> or + <code>H5T_ORDER_LE</code>. If the bytes are in the oposite + order then they are said to be <em>big-endian</em> or + <code>H5T_ORDER_BE</code>. Some data types have the same byte + order on all machines and are <code>H5T_ORDER_NONE</code> + (like character strings). If <code>H5Tget_order()</code> + fails then it returns <code>H5T_ORDER_ERROR</code> which is a + negative value (all successful return values are + non-negative). + + <br><br> + <dt><code>size_t H5Tget_precision (hid_t <em>type</em>)</code> + <dt><code>herr_t H5Tset_precision (hid_t <em>type</em>, size_t + <em>precision</em>)</code> + <dd>Some data types occupy more bytes than what is needed to + store the value. For instance, a <code>short</code> on a Cray + is 32 significant bits in an eight-byte field. The + <code>precision</code> property identifies the number of + significant bits of a datatype and the <code>offset</code> + property (defined below) identifies its location. The + <code>size</code> property defined above represents the entire + size (in bytes) of the data type. If the precision is + decreased then padding bits are inserted on the MSB side of + the significant bits (this will fail for + <code>H5T_FLOAT</code> types if it results in the sign, + mantissa, or exponent bit field extending beyond the edge of + the significant bit field). On the other hand, if the + precision is increased so that it "hangs over" the edge of the + total size then the <code>offset</code> property is + decremented a bit at a time. If the <code>offset</code> + reaches zero and the significant bits still hang over the + edge, then the total size is increased a byte at a time. The + precision of an <code>H5T_STRING</code> is read-only and is + always eight times the value returned by + <code>H5Tget_size()</code>. <code>H5Tget_precision()</code> + returns zero on failure since zero is never a valid precision. + + <br><br> + <dt><code>size_t H5Tget_offset (hid_t <em>type</em>)</code> + <dt><code>herr_t H5Tset_offset (hid_t <em>type</em>, size_t + <em>offset</em>)</code> + <dd>While the <code>precision</code> property defines the number + of significant bits, the <code>offset</code> property defines + the location of those bits within the entire datum. The bits + of the entire data are numbered beginning at zero at the least + significant bit of the least significant byte (the byte at the + lowest memory address for a little-endian type or the byte at + the highest address for a big-endian type). The + <code>offset</code> property defines the bit location of the + least signficant bit of a bit field whose length is + <code>precision</code>. If the offset is increased so the + significant bits "hang over" the edge of the datum, then the + <code>size</code> property is automatically incremented. The + offset is a read-only property of an <code>H5T_STRING</code> + and is always zero. <code>H5Tget_offset()</code> returns zero + on failure which is also a valid offset, but is guaranteed to + succeed if a call to <code>H5Tget_precision()</code> succeeds + with the same arguments. + + <br><br> + <dt><code>herr_t H5Tget_pad (hid_t <em>type</em>, H5T_pad_t + *<em>lsb</em>, H5T_pad_t *<em>msb</em>)</code> + <dt><code>herr_t H5Tset_pad (hid_t <em>type</em>, H5T_pad_t + <em>lsb</em>, H5T_pad_t <em>msb</em>)</code> + <dd>The bits of a datum which are not significant as defined by + the <code>precision</code> and <code>offset</code> properties + are called <em>padding</em>. Padding falls into two + categories: padding in the low-numbered bits is <em>lsb</em> + padding and padding in the high-numbered bits is <em>msb</em> + padding (bits are numbered according to the description for + the <code>offset</code> property). Padding bits can always be + set to zero (<code>H5T_PAD_ZERO</code>) or always set to one + (<code>H5T_PAD_ONE</code>). The current pad types are returned + through arguments of <code>H5Tget_pad()</code> either of which + may be null pointers. + </dl> + + <h3>3.1. Properties of Integer Atomic Types</h3> + + <p>Integer atomic types (<code>class=H5T_INTEGER</code>) + describe integer number formats. Such types include the + following information which describes the type completely and + allows conversion between various integer atomic types. + + <dl> + <dt><code>H5T_sign_t H5Tget_sign (hid_t <em>type</em>)</code> + <dt><code>herr_t H5Tset_sign (hid_t <em>type</em>, H5T_sign_t + <em>sign</em>)</code> + <dd>Integer data can be signed two's complement + (<code>H5T_SGN_2</code>) or unsigned + (<code>H5T_SGN_NONE</code>). Whether data is signed or not + becomes important when converting between two integer data + types of differing sizes as it determines how values are + truncated and sign extended. + </dl> + + <h3>3.2. Properties of Floating-point Atomic Types</h3> + + <p>The library supports floating-point atomic types + (<code>class=H5T_FLOAT</code>) as long as the bits of the + exponent are contiguous and stored as a biased positive number, + the bits of the mantissa are contiguous and stored as a positive + magnitude, and a sign bit exists which is set for negative + values. Properties specific to floating-point types are: + + <dl> + <dt><code>herr_t H5Tget_fields (hid_t <em>type</em>, size_t + *<em>spos</em>, size_t *<em>epos</em>, size_t + *<em>esize</em>, size_t *<em>mpos</em>, size_t + *<em>msize</em>)</code> + <dt><code>herr_t H5Tset_fields (hid_t <em>type</em>, size_t + <em>spos</em>, size_t <em>epos</em>, size_t <em>esize</em>, + size_t <em>mpos</em>, size_t <em>msize</em>)</code> + <dd>A floating-point datum has bit fields which are the exponent + and mantissa as well as a mantissa sign bit. These properties + define the location (bit position of least significant bit of + the field) and size (in bits) of each field. The bit + positions are numbered beginning at zero at the beginning of + the significant part of the datum (see the descriptions of the + <code>precision</code> and <code>offset</code> + properties). The sign bit is always of length one and none of + the fields are allowed to overlap. When expanding a + floating-point type one should set the precision first; when + decreasing the size one should set the field positions and + sizes first. + + <br><br> + <dt><code>size_t H5Tget_ebias (hid_t <em>type</em>)</code> + <dt><code>herr_t H5Tset_ebias (hid_t <em>type</em>, size_t + <em>ebias</em>)</code> + <dd>The exponent is stored as a non-negative value which is + <code>ebias</code> larger than the true exponent. + <code>H5Tget_ebias()</code> returns zero on failure which is + also a valid exponent bias, but the function is guaranteed to + succeed if <code>H5Tget_precision()</code> succeeds when + called with the same arguments. + + <br><br> + <dt><code>H5T_norm_t H5Tget_norm (hid_t <em>type</em>)</code> + <dt><code>herr_t H5Tset_norm (hid_t <em>type</em>, H5T_norm_t + <em>norm</em>)</code> + <dd>This property determines the normalization method of the + mantissa. + <ul> + <li>If the value is <code>H5T_NORM_MSBSET</code> then the + mantissa is shifted left (if non-zero) until the first bit + after the radix point is set and the exponent is adjusted + accordingly. All bits of the mantissa after the radix + point are stored. + + <li>If its value is <code>H5T_NORM_IMPLIED</code> then the + mantissa is shifted left (if non-zero) until the first bit + after the radix point is set and the exponent is adjusted + accordingly. The first bit after the radix point is not stored + since it's always set. + + <li>If its value is <code>H5T_NORM_NONE</code> then the fractional + part of the mantissa is stored without normalizing it. + </ul> + + <br><br> + <dt><code>H5T_pad_t H5Tget_inpad (hid_t <em>type</em>)</code> + <dt><code>herr_t H5Tset_inpad (hid_t <em>type</em>, H5T_pad_t + <em>inpad</em>)</code> + <dd>If any internal bits (that is, bits between the sign bit, + the mantissa field, and the exponent field but within the + precision field) are unused, then they will be filled + according to the value of this property. The <em>inpad</em> + argument can be <code>H5T_PAD_ZERO</code> if the internal + padding should always be set to zero, or <code>H5T_PAD_ONE</code> + if it should always be set to one. + <code>H5Tget_inpad()</code> returns <code>H5T_PAD_ERROR</code> + on failure which is a negative value (successful return is + always non-negative). + </dl> + + <h3>3.3. Properties of Date and Time Atomic Types</h3> + + <p>Dates and times (<code>class=H5T_TIME</code>) are stored as + character strings in one of the ISO-8601 formats like + "<em>1997-12-05 16:25:30</em>"; as character strings using the + Unix asctime(3) format like "<em>Thu Dec 05 16:25:30 1997</em>"; + as an integer value by juxtaposition of the year, month, and + day-of-month, hour, minute and second in decimal like + <em>19971205162530</em>; as an integer value in Unix time(2) + format; or other variations. + + <p>I'm deferring definition until later since they're probably not + as important as the other data types. + + <h3>3.4. Properties of Character String Atomic Types</h3> + + <p>Fixed-length character string types are used to store textual + information. The <code>offset</code> property of a string is + always zero and the <code>precision</code> property is eight + times as large as the value returned by + <code>H5Tget_size()</code> (since precision is measured in bits + while size is measured in bytes). Both properties are + read-only. + + <dl> + <dt><code>H5T_cset_t H5Tget_cset (hid_t <em>type</em>)</code> + <dt><code>herr_t H5Tset_cset (hid_t <em>type</em>, H5T_cset_t + <em>cset</em>)</code> + <dd>HDF5 is able to distinguish between character sets of + different nationalities and to convert between them to the + extent possible. The only character set currently supported + is <code>H5T_CSET_ASCII</code>. + + <br><br> + <dt><code>H5T_str_t H5Tget_strpad (hid_t <em>type</em>)</code> + <dt><code>herr_t H5Tset_strpad (hid_t <em>type</em>, H5T_str_t + <em>strpad</em>)</code> + <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 and can be + <code>H5T_STR_NULL</code> for C-style strings or + <code>H5T_STR_SPACE</code> for Fortran-style + strings. <code>H5Tget_strpad()</code> returns + <code>H5T_STR_ERROR</code> on failure, a negative value (all + successful return values are non-negative). + </dl> + + <h3>3.5. Properties of Bit Field Atomic Types</h3> + + <p>Converting a bit field (<code>class=H5T_BITFIELD</code>) from + one type to another simply copies the significant bits. If the + destination is smaller than the source then bits are truncated. + Otherwise new bits are filled according to the <code>msb</code> + padding type. + + <h3>3.6. Properties of Opaque Atomic Types</h3> + + <p>Opaque atomic types (<code>class=H5T_OPAQUE</code>) act like + bit fields except conversions which change the precision are not + allowed. However, padding can be added or removed from either + end and the bytes can be reordered. Opaque types can be used to + create novel data types not directly supported by the library, + but the application is responsible for data conversion of these + types. + + <h2>4. Properties of Compound Types</h2> + + <p>A compound data type is similar to a <code>struct</code> in C + or a common block in Fortran: it is a collection of one or more + atomic types or small arrays of such types. Each + <em>member</em> of a compound type has a name which is unique + within that type, and a byte offset that determines the first + byte (smallest byte address) of that member in a compound datum. + A compound data type has the following properties: + + <dl> + <dt><code>H5T_class_t H5Tget_class (hid_t <em>type</em>)</code> + <dd>All compound data types belong to the type class + <code>H5T_COMPOUND</code>. This property is read-only and is + defined when a data type is created or copied (see + <code>H5Tcreate()</code> or <code>H5Tcopy()</code>). + + <br><br> + <dt><code>size_t H5Tget_size (hid_t <em>type</em>)</code> + <dd>Compound data types have a total size in bytes which is + returned by this function. All members of a compound data + type must exist within this size. A value of zero is returned + for failure; all successful return values are positive. + + <br><br> + <dt><code>int H5Tget_nmembers (hid_t <em>type</em>)</code> + <dd>A compound data type consists of zero or more members + (defined in any order) with unique names and which occupy + non-overlapping regions within the datum. In the functions + that follow, individual members are referenced by an index + number between zero and <em>N</em>-1, inclusive, where + <em>N</em> is the value returned by this function. + <code>H5Tget_nmembers()</code> returns -1 on failure. + + <br><br> + <dt><code>char *H5Tget_member_name (hid_t <em>type</em>, int + <em>membno</em>)</code> + <dd>Each member has a name which is unique among its siblings in + a compound data type. This function returns a pointer to a + null-terminated copy of the name allocated with + <code>malloc()</code> or the null pointer on failure. The + caller is responsible for freeing the memory returned by this + function. + + <br><br> + <dt><code>size_t H5Tget_member_offset (hid_t <em>type</em>, int + <em>membno</em>)</code> + <dd>The byte offset of member number <em>membno</em> with + respect to the beginning of the containing compound datum is + returned by this function. A zero is returned on failure + which is also a valid offset, but this function is guaranteed + to succeed if a call to <code>H5Tget_member_dims()</code> + succeeds when called with the same <em>type</em> and + <em>membno</em> arguments. + + <br><br> + <dt><code>int H5Tget_member_dims (hid_t <em>type</em>, int + <em>membno</em>, int <em>dims</em>[4], int + <em>perm</em>[4])</code> + <dd>Each member can be a small array of up to four dimensions, + making it convenient to describe things like transposition + matrices. The dimensionality of the member is returned (or + negative for failure) and the size in each dimension is + returned through the <em>dims</em> argument. The + <em>perm</em> argument describes how the array's elements are + mapped to the linear address space of memory with respect to + some reference order (the reference order is specified in + natural language documentation which describes the compound + data type). The application which "invented" the type will + often use the identity permutation and other applications will + use a permutation that causes the elements to be rearranged to + the desired order. Only the first few elements of + <em>dims</em> and <em>perm</em> are initialized according to + the dimensionality of the member. Scalar members have + dimensionality zero. + + <b>The only permutations supported at this + time are the identity permutation and the transpose + permutation (in the 4d case, {0,1,2,3} and {3,2,1,0}).</b> + + <br><br> + <dt><code>hid_t H5Tget_member_type (hid_t <em>type</em>, int + <em>membno</em>)</code> + <dd>Each member has its own data type, a copy of which is + returned by this function. The returned data type identifier + should be released by eventually calling + <code>H5Tclose()</code> on that type. + </dl> + + <p>Properties of members of a compound data type are + defined when the member is added to the compound type (see + <code>H5Tinsert()</code>) and cannot be subsequently modified. + This makes it imposible to define recursive data structures. + + <h2>5. Predefined Atomic Data Types</h2> + + <p>The library predefines a modest number of data types having + names like <code>H5T_<em>arch</em>_<em>base</em></code> where + <em>arch</em> is an architecture name and <em>base</em> is a + programming type name. New types can be derived from the + predifined types by copying the predefined type (see + <code>H5Tcopy()</code>) and then modifying the result. + + <p> + <center> + <table align=center width="80%"> + <tr> + <th align=left width="20%">Architecture Name</th> + <th align=left width="80%">Description</th> + </tr> + + <tr valign=top> + <td><code>IEEE</code></td> + <td>This architecture defines standard floating point + types in various byte orders.</td> + </tr> + + <tr valign=top> + <td><code>STD</code></td> + <td>This is an architecture that contains semi-standard + datatypes like signed two's complement integers, + unsigned integers, and bitfields in various byte + orders.</td> + </tr> + + <tr valign=top> + <td><code>UNIX</code></td> + <td>Types which are specific to Unix operating systems are + defined in this architecture. The only type currently + defined is the Unix date and time types + (<code>time_t</code>).</td> + </tr> + + <tr valign=top> + <td><code>C<br>FORTRAN</code></td> + <td>Types which are specific to the C or Fortran + programming languages are defined in these + architectures. For instance, <code>H5T_C_STRING</code> + defines a base string type with null termination which + can be used to derive string types of other + lengths.</td> + </tr> + + <tr valign=top> + <td><code>NATIVE</code></td> + <td>This architecture contains C-like data types for the + machine on which the library was compiled. The types + were actually defined by running the + <code>H5detect</code> program when the library was + compiled. In order to be portable, applications should + almost always use this architecture to describe things + in memory.</td> + </tr> + + <tr valign=top> + <td><code>CRAY</code></td> + <td>Cray architectures. These are word-addressable, + big-endian systems with non-IEEE floating point.</td> + </tr> + + <tr valign=top> + <td><code>INTEL</code></td> + <td>All Intel and compatible CPU's including 80286, 80386, + 80486, Pentium, Pentium-Pro, and Pentium-II. These are + little-endian systems with IEEE floating-point.</td> + </tr> + + <tr valign=top> + <td><code>MIPS</code></td> + <td>All MIPS CPU's commonly used in SGI systems. These + are big-endian systems with IEEE floating-point.</td> + </tr> + + <tr valign=top> + <td><code>ALPHA</code></td> + <td>All DEC Alpha CPU's, little-endian systems with IEEE + floating-point.</td> + </tr> + </table> + </center> + + <p>The base name of most types consists of a letter, a precision + in bits, and an indication of the byte order. The letters are: + + <p> + <center> + <table border align=center width="40%"> + <tr> + <td align=center width="30%">B</td> + <td width="70%">Bitfield</td> + </tr> + <tr> + <td align=center>D</td> + <td>Date and time</td> + </tr> + <tr> + <td align=center>F</td> + <td>Floating point</td> + </tr> + <tr> + <td align=center>I</td> + <td>Signed integer</td> + </tr> + <tr> + <td align=center>S</td> + <td>Character string</td> + </tr> + <tr> + <td align=center>U</td> + <td>Unsigned integer</td> + </tr> + </table> + </center> + + <p>The byte order is a two-letter sequence: + + <p> + <center> + <table border align=center width="40%"> + <tr> + <td align=center width="30%">BE</td> + <td width="70%">Big endian</td> + </tr> + <tr> + <td align=center>LE</td> + <td>Little endian</td> + </tr> + <tr> + <td align=center>VX</td> + <td>Vax order</td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th align=left><br><br>Example</th> + <th align=left><br><br>Description</th> + </tr> + + <tr valign=top> + <td><code>H5T_IEEE_F64LE</code></td> + <td>Eight-byte, little-endian, IEEE floating-point</td> + </tr> + <tr valign=top> + <td><code>H5T_IEEE_F32BE</code></td> + <td>Four-byte, big-endian, IEEE floating point</td> + </tr> + <tr valign=top> + <td><code>H5T_STD_I32LE</code></td> + <td>Four-byte, little-endian, signed two's complement integer</td> + </tr> + <tr valign=top> + <td><code>H5T_STD_U16BE</code></td> + <td>Two-byte, big-endian, unsigned integer</td> + </tr> + <tr valign=top> + <td><code>H5T_UNIX_D32LE</code></td> + <td>Four-byte, little-endian, time_t</td> + </tr> + <tr valign=top> + <td><code>H5T_C_S1</code></td> + <td>One-byte, null-terminated string of eight-bit characters</td> + </tr> + <tr valign=top> + <td><code>H5T_INTEL_B64</code></td> + <td>Eight-byte bit field on an Intel CPU</td> + </tr> + <tr valign=top> + <td><code>H5T_CRAY_F64</code></td> + <td>Eight-byte Cray floating point</td> + </tr> + </table> + </center> + + <p>The <code>NATIVE</code> architecture has base names which don't + follow the same rules as the others. Instead, native type names + are similar to the C type names. Here are some examples: + + <p> + <center> + <table align=center width="80%"> + <tr> + <th align=left><br><br>Example</th> + <th align=left><br><br>Corresponding C Type</th> + </tr> + <tr> + <td><code>H5T_NATIVE_CHAR</code></td> + <td><code>signed char</code></td> + </tr> + <tr> + <td><code>H5T_NATIVE_UCHAR</code></td> + <td><code>unsigned char</code></td> + </tr> + <tr> + <td><code>H5T_NATIVE_SHORT</code></td> + <td><code>short</code></td> + </tr> + <tr> + <td><code>H5T_NATIVE_USHORT</code></td> + <td><code>unsigned short</code></td> + </tr> + <tr> + <td><code>H5T_NATIVE_INT</code></td> + <td><code>int</code></td> + </tr> + <tr> + <td><code>H5T_NATIVE_UINT</code></td> + <td><code>unsigned</code></td> + </tr> + <tr> + <td><code>H5T_NATIVE_LONG</code></td> + <td><code>long</code></td> + </tr> + <tr> + <td><code>H5T_NATIVE_ULONG</code></td> + <td><code>unsigned long</code></td> + </tr> + <tr> + <td><code>H5T_NATIVE_LLONG</code></td> + <td><code>long long</code></td> + </tr> + <tr> + <td><code>H5T_NATIVE_ULLONG</code></td> + <td><code>unsigned long long</code></td> + </tr> + <tr> + <td><code>H5T_NATIVE_FLOAT</code></td> + <td><code>float</code></td> + </tr> + <tr> + <td><code>H5T_NATIVE_DOUBLE</code></td> + <td><code>double</code></td> + </tr> + <tr> + <td><code>H5T_NATIVE_LDOUBLE</code></td> + <td><code>long double</code></td> + </tr> + </table> + </center> + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example: A 128-bit + integer</h4></caption> + <tr> + <td> + <p>To create a 128-bit, little-endian signed integer + type one could use the following (increasing the + precision of a type automatically increases the total + size): + + <p><code><pre> +hid_t new_type = H5Tcopy (H5T_NATIVE_INT); +H5Tset_precision (new_type, 128); +H5Tset_order (new_type, H5T_ORDER_LE); + </pre></code> + </td> + </tr> + </table> + </center> + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example: An 80-character + string</h4></caption> + <tr> + <td> + <p>To create an 80-byte null terminated string type one + might do this (the offset of a character string is + always zero and the precision is adjusted + automatically to match the size): + + <p><code><pre> +hid_t str80 = H5Tcopy (H5T_C_S1); +H5Tset_size (str80, 80); + </pre></code> + </td> + </tr> + </table> + </center> + + <h2>6. Defining Compound Data Types</h2> + + <p>Unlike atomic data types which are derived from other atomic + data types, compound data types are created from scratch. First, + one creates an empty compound data type and specifies it's total + size. Then members are added to the compound data type in any + order. + + <p>Usually a C struct will be defined to hold a data point in + memory, and the offsets of the members in memory will be the + offsets of the struct members from the beginning of an instance + of the struct. + + <dl> + <dt><code>HOFFSET(s,m)</code> + <dd>This macro computes the offset of member <em>m</em> within + a struct <em>s</em>. + <dt><code>offsetof(s,m)</code> + <dd>This macro defined in <code>stddef.h</code> does + exactly the same thing as the <code>HOFFSET()</code> macro. + </dl> + + <p>Each member must have a descriptive name which is the + key used to uniquely identify the member within the compound + data type. A member name in an HDF5 data type does not + necessarily have to be the same as the name of the member in the + C struct, although this is often the case. Nor does one need to + define all members of the C struct in the HDF5 compound data + type (or vice versa). + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example: A simple struct</h4></caption> + <tr> + <td> + <p>An HDF5 data type is created to describe complex + numbers whose type is defined by the + <code>complex_t</code> struct. + + <p><code><pre> +typedef struct { + double re; /*real part*/ + double im; /*imaginary part*/ +} complex_t; + +hid_t complex_id = H5Tcreate (H5T_COMPOUND, sizeof tmp); +H5Tinsert (complex_id, "real", HOFFSET(complex_t,re), + H5T_NATIVE_DOUBLE); +H5Tinsert (complex_id, "imaginary", HOFFSET(complex_t,im), + H5T_NATIVE_DOUBLE); + </pre></code> + </td> + </tr> + </table> + </center> + + <p>Member alignment is handled by the <code>HOFFSET</code> + macro. However, data stored on disk does not require alignment, + so unaligned versions of compound data structures can be created + to improve space efficiency on disk. These unaligned compound + data types can be created by computing offsets by hand to + eliminate inter-member padding, or the members can be packed by + calling <code>H5Tpack()</code> (which modifies a data type + directly, so it is usually preceded by a call to + <code>H5Tcopy()</code>): + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example: A packed struct</h4></caption> + <tr> + <td> + <p>This example shows how to create a disk version of a + compound data type in order to store data on disk in + as compact a form as possible. Packed compound data + types should generally not be used to describe memory + as they may violate alignment constraints for the + architecture being used. Note also that using a + packed data type for disk storage may involve a higher + data conversion cost. + <p><code><pre> +hid_t complex_disk_id = H5Tcopy (complex_id); +H5Tpack (complex_disk_id); + </pre></code> + </td> + </tr> + </table> + </center> + + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example: A flattened struct</h4></caption> + <tr> + <td> + <p>Compound data types that have a compound data type + member can be handled two ways. This example shows + that the compound data type can be flattened, + resulting in a compound type with only atomic + members. + + <p><code><pre> +typedef struct { + complex_t x; + complex_t y; +} surf_t; + +hid_t surf_id = H5Tcreate (H5T_COMPOUND, sizeof tmp); +H5Tinsert (surf_id, "x-re", HOFFSET(surf_t,x.re), + H5T_NATIVE_DOUBLE); +H5Tinsert (surf_id, "x-im", HOFFSET(surf_t,x.im), + H5T_NATIVE_DOUBLE); +H5Tinsert (surf_id, "y-re", HOFFSET(surf_t,y.re), + H5T_NATIVE_DOUBLE); +H5Tinsert (surf_id, "y-im", HOFFSET(surf_t,y.im), + H5T_NATIVE_DOUBLE); + </code></pre> + </td> + </tr> + </table> + </center> + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example: A nested struct</h4></caption> + <tr> + <td> + <p>However, when the <code>complex_t</code> is used + often it becomes inconvenient to list its members over + and over again. So the alternative approach to + flattening is to define a compound data type and then + use it as the type of the compound members, as is done + here (the typedefs are defined in the previous + examples). + + <p><code><pre> +hid_t complex_id, surf_id; /*hdf5 data types*/ + +complex_id = H5Tcreate (H5T_COMPOUND, sizeof c); +H5Tinsert (complex_id, "re", HOFFSET(complex_t,re), + H5T_NATIVE_DOUBLE); +H5Tinsert (complex_id, "im", HOFFSET(complex_t,im), + H5T_NATIVE_DOUBLE); + +surf_id = H5Tcreate (H5T_COMPOUND, sizeof s); +H5Tinsert (surf_id, "x", HOFFSET(surf_t,x), complex_id); +H5Tinsert (surf_id, "y", HOFFSET(surf_t,y), complex_id); + </code></pre> + </td> + </tr> + </table> + </center> + + <h2>7. Sharing Data Types among Datasets</h2> + + <p>If a file has lots of datasets which have a common data type + then the file could be made smaller by having all the datasets + share a single data type. Instead of storing a copy of the data + type in each dataset object header, a single data type is stored + and the object headers point to it. The space savings is + probably only significant for datasets with a compound data type + since the simple data types can be described with just a few + bytes anyway. + + <p>To create a bunch of datasets that share a single data type + just create the datasets with a committed (named) data type. + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example: Shared Types</h4></caption> + <tr> + <td> + <p>To create two datasets that share a common data type + one just commits the data type, giving it a name, and + then uses that data type to create the datasets. + + <p><code><pre> +hid_t t1 = ...some transient type...; +H5Tcommit (file, "shared_type", t1); +hid_t dset1 = H5Dcreate (file, "dset1", t1, space, H5P_DEFAULT); +hid_t dset2 = H5Dcreate (file, "dset2", t1, space, H5P_DEFAULT); + </code></pre> + + <p>And to create two additional datasets later which + share the same type as the first two datasets: + + <p><code><pre> +hid_t dset1 = H5Dopen (file, "dset1"); +hid_t t2 = H5Dget_type (dset1); +hid_t dset3 = H5Dcreate (file, "dset3", t2, space, H5P_DEFAULT); +hid_t dset4 = H5Dcreate (file, "dset4", t2, space, H5P_DEFAULT); + </code></pre> + </td> + </tr> + </table> + </center> + + <h2>8. Data Conversion</h2> + + <p>The library is capable of converting data from one type to + another and does so automatically when reading or writing the + raw data of a dataset. The data type interface does not provide + functions to the application for changing data types directly, + but the user is allowed a certain amount of control over the + conversion process. + + <p>In order to insure that data conversion exceeds disk I/O rates, + common data conversion paths can be hand-tuned and optimized for + performance. If a hand-tuned conversion function is not + available, then the library falls back to a slower but more + general conversion function. Although conversion paths include + data space conversion, only data type conversions are described + here. Most applications will not be concerned with data type + conversions since the library will contain hand-tuned conversion + functions for many common conversion paths. In fact, if an + application does define a conversion function which would be of + general interest, we request that the function be submitted to + the HDF5 development team for inclusion in the library (there + might be less overhead involved with calling an internal + conversion functions than calling an application-defined + conversion function). + + <p><b>Note:</b> The alpha version of the library does not contain + a full set of conversions. It can convert from one integer + format to another and one struct to another. It can also + perform byte swapping when the source and destination types are + otherwise the same. + + <p>A conversion path contains a source and destination data type + and each path contains a <em>hard</em> conversion function + and/or a <em>soft</em> conversion function. The only difference + between hard and soft functions is the way in which the library + chooses which function applies: A hard function applies to a + specific conversion path while a soft function may apply to + multiple paths. When both hard and soft functions apply to a + conversion path, then the hard function is favored and when + multiple soft functions apply, the one defined last is favored. + + <p>A data conversion function is of type <code>H5T_conv_t</em> + which is defined as: + + <p> + <code><pre> +typedef herr_t (*H5T_conv_t)(hid_t <em>src_type</em>, + hid_t <em>dest_type</em>, + H5T_cdata_t *<em>cdata</em>, + size_t <em>nelmts</em>, + void *<em>buffer</em>, + void *<em>background</em>); + </pre></code> + + <p>The conversion function is called with the source and + destination data types (<em>src_type</em> and + <em>dst_type</em>), path-constant data (<em>cdata</em>), the + number of instances of the data type to convert + (<em>nelmts</em>), a buffer which initially contains an array of + data having the source type and on return will contain an array + of data having the destination type (<em>buffer</em>), and a + temporary or background buffer (<em>background</em>). Functions + return a negative value on failure and some other value on + success. + + <p>The <code>command</code> field of the <em>cdata</em> argument + determines what happens within the conversion function. It's + values can be: + + <dl> + <dt><code>H5T_CONV_INIT</code> + <dd>This command is to hard conversion functions when they're + registered or soft conversion functions when the library is + determining if a conversion can be used for a particular path. + The <em>src_type</em> and <em>dst_type</em> are the end-points + of the path being queried and <em>cdata</em> is all zero. The + library should examine the source and destination types and + return zero if the conversion is possible and negative + otherwise (hard conversions need not do this since they've + presumably been registered only on paths they support). If + the conversion is possible the library may allocate and + initialize private data and assign the pointer to the + <code>priv</code> field of <em>cdata</em> (or private data can + be initialized later). It should also initialize the + <code>need_bkg</code> field described below. The <em>buf</em> + and <em>background</em> pointers will be null pointers. + + <br><br> + <dt><code>H5T_CONV_CONV</code> + <dd>This is the usually command which indicates that + data points should be converted. The conversion function + should initialize the <code>priv</code> field of + <em>cdata</em> if it wasn't initialize during the + <code>H5T_CONV_INIT</code> command and then convert + <em>nelmts</em> instances of the <em>src_type</em> to the + <em>dst_type</em>. The <em>buffer</em> serves as both input + and output. The <em>background</em> buffer is supplied + according to the value of the <code>need_bkg</code> field of + <em>cdata</em> (the values are described below). + + <br><br> + <dt><code>H5T_CONV_FREE</code> + <dd>The conversion function is about to be removed from some + path and the private data (the + <code><em>cdata</em>->priv</code> pointer) should be freed and + set to null. All other pointer arguments are null and the + <em>nelmts</em> argument is zero. + + <br><br> + <dt><em>Others...</em> + <dd>Other commands might be implemented later and conversion + functions that don't support those commands should return a + negative value. + </dl> + + + <p>Whether a background buffer is supplied to a conversion + function, and whether the background buffer is initialized + depends on the value of <code><em>cdata</em>->need_bkg</code> + which the conversion function should have initialized during the + H5T_CONV_INIT command. It can have one of these values: + + <dl> + <dt><code>H5T_BKG_NONE</code> + <dd>No background buffer will be supplied to the conversion + function. This is the default. + + <br><br> + <dt><code>H5T_BKG_TEMP</code> + <dd>A background buffer will be supplied but it will not be + initialized. This is useful for those functions requiring some + extra buffer space as the buffer can probably be allocated + more efficiently by the library (the application can supply + the buffer as part of the dataset transfer template). + + <br><br> + <dt><code>H5T_BKG_YES</code> + <dd>An initialized background buffer is passed to the conversion + function. The buffer is initialized with the current values + of the destination for the data which is passed in through the + <em>buffer</em> argument. It can be used to "fill in between + the cracks". For instance, if the destination type is a + compound data type and we are initializing only part of the + compound data type from the source type then the background + buffer can be used to initialize the other part of the + destination. + </dl> + + <p>Other fields of <em>cdata</em> can be read or written by + the conversion functions. Many of these contain + performance-measuring fields which can be printed by the + conversion function during the <code>H5T_CONV_FREE</code> + command which is issued whenever the function is removed from a + conversion path. + + <dl> + <dt><code>hbool_t recalc</code> + <dd>This field is set by the library when any other data type + conversion function is registered or unregistered. It allows + conversion functions to cache pointers to other conversion + functions and be notified when the cache should be + recalculated. + + <br><br> + <dt><code>unsigned long ncalls</code> + <dd>This field contains the number of times the conversion + function was called with the command + <code>H5T_CONV_CONV</code>. It is updated automatically by + the library. + + <br><br> + <dt><code>unsigned long nelmts</code> + <dd>This is the total number of data points converted by this + function and is updated automatically by the library. + </dl> + + + + <p>Once a conversion function is written it can be registered and + unregistered with these functions: + + <dl> + <dt><code>herr_t H5Tregister_hard (const char *<em>name</em>, + hid_t <em>src_type</em>, hid_t <em>dest_type</em>, + H5T_conv_t <em>func</em>)</code> + <dd>Once a conversion function is written, the library must be + notified so it can be used. The function can be registered as a + hard conversion for one or more conversion paths by calling + <code>H5Tregister_hard()</code>, displacing any previous hard + conversion for those paths. The <em>name</em> is used only + for debugging but must be supplied. + + <br><br> + <dt><code>herr_t H5Tregister_soft (const char *<em>name</em>, + H5T_class_t <em>src_class</em>, H5T_class_t <em>dest_class</em>, + H5T_conv_t <em>func</em>)</code> + <dd>The function can be registered as a generic function which + will be automatically added to any conversion path for which + it returns an indication that it applies. The name is used + only for debugging but must be supplied. + + <br><br> + <dt><code>herr_t H5Tunregister (H5T_conv_t <em>func</em>)</code> + <dd>A function can be removed from the set of known conversion + functions by calling <code>H5Tunregister()</code>. The + function is removed from all conversion paths. + </dl> + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example: A conversion + function</h4></caption> + <tr> + <td> + <p>Here's an example application-level function that + converts Cray <code>unsigned short</code> to any other + 16-bit unsigned big-endian integer. A cray + <code>short</code> is a big-endian value which has 32 + bits of precision in the high-order bits of a 64-bit + word. + + <p><code><pre> + 1 typedef struct { + 2 size_t dst_size; + 3 int direction; + 4 } cray_ushort2be_t; + 5 + 6 herr_t + 7 cray_ushort2be (hid_t src, hid_t dst, + 8 H5T_cdata_t *cdata, + 9 size_t nelmts, void *buf, +10 const void *background) +11 { +12 unsigned char *src = (unsigned char *)buf; +13 unsigned char *dst = src; +14 cray_ushort2be_t *priv = NULL; +15 +16 switch (cdata->command) { +17 case H5T_CONV_INIT: +18 /* +19 * We are being queried to see if we handle this +20 * conversion. We can handle conversion from +21 * Cray unsigned short to any other big-endian +22 * unsigned integer that doesn't have padding. +23 */ +24 if (!H5Tequal (src, H5T_CRAY_USHORT) || +25 H5T_ORDER_BE != H5Tget_order (dst) || +26 H5T_SGN_NONE != H5Tget_signed (dst) || +27 8*H5Tget_size (dst) != H5Tget_precision (dst)) { +28 return -1; +29 } +30 +31 /* +32 * Initialize private data. If the destination size +33 * is larger than the source size, then we must +34 * process the elements from right to left. +35 */ +36 cdata->priv = priv = malloc (sizeof(cray_ushort2be_t)); +37 priv->dst_size = H5Tget_size (dst); +38 if (priv->dst_size>8) { +39 priv->direction = -1; +40 } else { +41 priv->direction = 1; +42 } +43 break; +44 +45 case H5T_CONV_FREE: +46 /* +47 * Free private data. +48 */ +49 free (cdata->priv); +50 cdata->priv = NULL; +51 break; +52 +53 case H5T_CONV_CONV: +54 /* +55 * Convert each element, watch out for overlap src +56 * with dst on the left-most element of the buffer. +57 */ +58 priv = (cray_ushort2be_t *)(cdata->priv); +59 if (priv->direction<0) { +60 src += (nelmts - 1) * 8; +61 dst += (nelmts - 1) * dst_size; +62 } +63 for (i=0; i<n; i++) { +64 if (src==dst && dst_size<4) { +65 for (j=0; j<dst_size; j++) { +66 dst[j] = src[j+4-dst_size]; +67 } +68 } else { +69 for (j=0; j<4 && j<dst_size; j++) { +70 dst[dst_size-(j+1)] = src[3-j]; +71 } +72 for (j=4; j<dst_size; j++) { +73 dst[dst_size-(j+1)] = 0; +74 } +75 } +76 src += 8 * direction; +77 dst += dst_size * direction; +78 } +79 break; +80 +81 default: +82 /* +83 * Unknown command. +84 */ +85 return -1; +86 } +87 return 0; +88 } + </pre></code> + + <p>The <em>background</em> argument is ignored since + it's generally not applicable to atomic data types. + </td> + </tr> + </table> + </center> + + <p> + <center> + <table border align=center width="100%"> + <caption align=bottom><h4>Example: Soft + Registration</h4></caption> + <tr> + <td> + <p>The convesion function described in the previous + example applies to more than one conversion path. + Instead of enumerating all possible paths, we register + it as a soft function and allow it to decide which + paths it can handle. + + <p><code><pre> +H5Tregister_soft ("cus2be", H5T_INTEGER, H5T_INTEGER, cray_ushort2be); + </pre></code> + + <p>This causes it to be consulted for any conversion + from an integer type to another integer type. The + first argument is just a short identifier which will + be printed with the data type conversion statistics. + </td> + </tr> + </table> + </center> + + + <p><b>NOTE:</b> The idea of a master soft list and being able to + query conversion functions for their abilities tries to overcome + problems we saw with AIO. Namely, that there was a dichotomy + between generic conversions and specific conversions that made + it very difficult to write a conversion function that operated + on, say, integers of any size and order as long as they don't + have zero padding. The AIO mechanism required such a function + to be explicitly registered (like + <code>H5Tregister_hard()</code>) for each an every possible + conversion path whether that conversion path was actually used + or not. + + <hr> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> + <address><a href="mailto:koziol@ncsa.uiuc.edu">Quincey Koziol</a></address> +<!-- Created: Thu Dec 4 14:57:32 EST 1997 --> +<!-- hhmts start --> +Last modified: Thu Jun 18 13:59:12 EDT 1998 +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/Errors.html b/doc/html/Errors.html new file mode 100644 index 0000000..4c3637d --- /dev/null +++ b/doc/html/Errors.html @@ -0,0 +1,281 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>The Error Handling Interface (H5E)</title> + </head> + + <body> + <h1>The Error Handling Interface (H5E)</h1> + + <h2>1. Introduction</h2> + + <p>When an error occurs deep within the HDF5 library a record is + pushed onto an error stack and that function returns a failure + indication. Its caller detects the failure, pushes another + record onto the stack, and returns a failure indication. This + continues until the application-called API function returns a + failure indication (a negative integer or null pointer). The + next API function which is called (with a few exceptions) resets + the stack. + + <p>In normal circumstances, an error causes the stack to be + printed on the standard error stream. The first item, number + "#000" is produced by the API function itself and is usually + sufficient to indicate to the application programmer what went + wrong. + + <p> + <center> + <table border align=center width="100%"> + <caption align=top><h4>Example: An Error Message</h4></caption> + <tr> + <td> + <p>If an application calls <code>H5Tclose</code> on a + predefined data type then the following message is + printed on the standard error stream. This is a + simple error that has only one component, the API + function; other errors may have many components. + + <p><code><pre> +HDF5-DIAG: Error detected in thread 0. Back trace follows. + #000: H5T.c line 462 in H5Tclose(): predefined data type + major(01): Function argument + minor(05): Bad value + </code></pre> + </td> + </tr> + </table> + </center> + + <p>The error stack can also be printed and manipulated by these + functions, but if an application wishes make explicit calls to + <code>H5Eprint()</code> then the automatic printing should be + turned off to prevent error messages from being displayed twice + (see <code>H5Eset_auto()</code> below). + + <dl> + <dt><code>herr_t H5Eprint (FILE *<em>stream</em>)</code> + <dd>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> + + <br><br> + <dt><code>herr_t H5Eclear (void)</code> + <dd>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>). + </dl> + + <p>Sometimes an application will call a function for the sake of + its return value, fully expecting the function to fail. Under + these conditions, it would be misleading if an error message + were automatically printed. Automatic printing of messages is + controlled by the <code>H5Eset_auto()</code> function: + + <dl> + <dt><code>herr_t H5Eset_auto (herr_t(*<em>func</em>)(void*), + void *<em>client_data</em>)</code> + <dd>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>. + + <br><br> + <dt><code>herr_t H5Eget_auto (herr_t(**<em>func</em>)(void*), + void **<em>client_data</em>)</code> + <dd>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. + </dl> + + <p> + <center> + <table border align=center width="100%"> + <caption align=top><h4>Example: Error Control</h4></caption> + <tr> + <td> + <p>An application can temporarily turn off error + messages while "probing" a function. + + <p><code><pre> +/* Save old error handler */ +herr_t (*old_func)(void*); +void *old_client_data; +H5Eget_auto(&old_func, &old_client_data); + +/* Turn off error handling */ +H5Eset_auto(NULL, NULL); + +/* Probe. Likely to fail, but that's okay */ +status = H5Fopen (......); + +/* Restore previous error handler */ +H5Eset_auto(old_func, old_client_data); + </code></pre> + + <p>Or automatic printing can be disabled altogether and + error messages can be explicitly printed. + + <p><code><pre> +/* Turn off error handling permanently */ +H5Eset_auto (NULL, NULL); + +/* If failure, print error message */ +if (H5Fopen (....)<0) { + H5Eprint (stderr); + exit (1); +} + </code></pre> + </td> + </tr> + </table> + </center> + + <p>The application is allowed to define an automatic error + traversal function other than the default + <code>H5Eprint()</code>. For instance, one could define a + function that prints a simple, one-line error message to the + standard error stream and then exits. + + <p> + <center> + <table border align=center width="100%"> + <caption align=top><h4>Example: Simple Messages</h4></caption> + <tr> + <td> + <p>The application defines a function to print a simple + error message to the standard error stream. + + <p><code><pre> +herr_t +my_hdf5_error_handler (void *unused) +{ + fprintf (stderr, "An HDF5 error was detected. Bye.\n"); + exit (1); +} + </code></pre> + + <p>The function is installed as the error handler by + saying + + <p><code><pre> +H5Eset_auto (my_hdf5_error_handler, NULL); + </code></pre> + </td> + </tr> + </table> + </center> + + <p>The <code>H5Eprint()</code> function is actually just a wrapper + around the more complex <code>H5Ewalk()</code> function which + traverses an error stack and calls a user-defined function for + each member of the stack. + + <dl> + <dt><code>herr_t H5Ewalk (H5E_direction_t <em>direction</em>, + H5E_walk_t <em>func</em>, void *<em>client_data</em>)</code> + <dd>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</em> 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>. + + <br><br> + <dt><code>typedef herr_t (*H5E_walk_t)(int <em>n</em>, + H5E_error_t *<em>eptr</em>, void + *<em>client_data</em>)</code> + <dd>An error stack traversal callback function takes three + arguments: <em>n</em> is a sequence number beginning at zero + for each traversal, <em>eptr</em> is a pointer to an error + stack member, and <em>client_data</em> is the same pointer + passed to <code>H5Ewalk()</code>. + + <br><br> + <dt><pre><code>typedef struct { + H5E_major_t <em>maj_num</em>; + H5E_minor_t <em>min_num</em>; + const char *<em>func_name</em>; + const char *<em>file_name</em>; + unsigned <em>line</em>; + const char *<em>desc</em>; +} H5E_error_t;</code></pre> + <dd>The <em>maj_num</em> and <em>min_num</em> are major + and minor error numbers, <em>func_name</em> is the name of + the function where the error was detected, + <em>file_name</em> and <em>line</em> locate the error + within the HDF5 library source code, and <em>desc</em> + points to a description of the error. + + <br><br> + <dt><code>const char *H5Eget_major (H5E_major_t <em>num</em>)</code> + <dt><code>const char *H5Eget_minor (H5E_minor_t <em>num</em>)</code> + <dd>These functions take a major or minor error number and + return a constant string which describes the error. If + <em>num</em> is out of range than a string like "Invalid major + error number" is returned. + </dl> + + <p> + <center> + <table border align=center width="100%"> + <caption align=top><h4>Example: H5Ewalk_cb</h4></caption> + <tr> + <td> + <p>This is the implementation of the default error stack + traversal callback. + + <p><code><pre> +herr_t +H5Ewalk_cb(int n, H5E_error_t *err_desc, void *client_data) +{ + FILE *stream = (FILE *)client_data; + const char *maj_str = NULL; + const char *min_str = NULL; + const int indent = 2; + + /* Check arguments */ + assert (err_desc); + if (!client_data) client_data = stderr; + + /* Get descriptions for the major and minor error numbers */ + maj_str = H5Eget_major (err_desc->maj_num); + min_str = H5Eget_minor (err_desc->min_num); + + /* Print error message */ + fprintf (stream, "%*s#%03d: %s line %u in %s(): %s\n", + indent, "", n, err_desc->file_name, err_desc->line, + err_desc->func_name, err_desc->desc); + fprintf (stream, "%*smajor(%02d): %s\n", + indent*2, "", err_desc->maj_num, maj_str); + fprintf (stream, "%*sminor(%02d): %s\n", + indent*2, "", err_desc->min_num, min_str); + + return 0; +} + </code></pre> + </td> + </tr> + </table> + </center> + + + + <hr> + <address><a href="mailto:hdf5dev@ncsa.uiuc.edu">Robb Matzke</a></address> +<!-- Created: Fri Feb 27 23:42:52 EST 1998 --> +<!-- hhmts start --> +Last modified: Wed Mar 4 10:06:17 EST 1998 +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/ExternalFiles.html b/doc/html/ExternalFiles.html new file mode 100644 index 0000000..39ebd2b --- /dev/null +++ b/doc/html/ExternalFiles.html @@ -0,0 +1,278 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>External Files in HDF5</title> + </head> + + <body> + <center><h1>External Files in HDF5</h1></center> + + <h3>Overview of Layers</h3> + + <p>This table shows some of the layers of HDF5. Each layer calls + functions at the same or lower layers and never functions at + higher layers. An object identifier (OID) takes various forms + at the various layers: at layer 0 an OID is an absolute physical + file address; at layers 1 and 2 it's an absolute virtual file + address. At layers 3 through 6 it's a relative address, and at + layers 7 and above it's an object handle. + + <p><center> + <table border cellpadding=4 width="60%"> + <tr align=center> + <td>Layer-7</td> + <td>Groups</td> + <td>Datasets</td> + </tr> + <tr align=center> + <td>Layer-6</td> + <td>Indirect Storage</td> + <td>Symbol Tables</td> + </tr> + <tr align=center> + <td>Layer-5</td> + <td>B-trees</td> + <td>Object Hdrs</td> + <td>Heaps</td> + </tr> + <tr align=center> + <td>Layer-4</td> + <td>Caching</td> + </tr> + <tr align=center> + <td>Layer-3</td> + <td>H5F chunk I/O</td> + </tr> + <tr align=center> + <td>Layer-2</td> + <td>H5F low</td> + </tr> + <tr align=center> + <td>Layer-1</td> + <td>File Family</td> + <td>Split Meta/Raw</td> + </tr> + <tr align=center> + <td>Layer-0</td> + <td>Section-2 I/O</td> + <td>Standard I/O</td> + <td>Malloc/Free</td> + </tr> + </table> + </center> + + <h3>Single Address Space</h3> + + <p>The simplest form of hdf5 file is a single file containing only + hdf5 data. The file begins with the boot block, which is + followed until the end of the file by hdf5 data. The next most + complicated file allows non-hdf5 data (user defined data or + internal wrappers) to appear before the boot block and after the + end of the hdf5 data. The hdf5 data is treated as a single + linear address space in both cases. + + <p>The next level of complexity comes when non-hdf5 data is + interspersed with the hdf5 data. We handle that by including + the non-hdf5 interspersed data in the hdf5 address space and + simply not referencing it (eventually we might add those + addresses to a "do-not-disturb" list using the same mechanism as + the hdf5 free list, but it's not absolutely necessary). This is + implemented except for the "do-not-disturb" list. + + <p>The most complicated single address space hdf5 file is when we + allow the address space to be split among multiple physical + files. For instance, a >2GB file can be split into smaller + chunks and transfered to a 32 bit machine, then accessed as a + single logical hdf5 file. The library already supports >32 bit + addresses, so at layer 1 we split a 64-bit address into a 32-bit + file number and a 32-bit offset (the 64 and 32 are + arbitrary). The rest of the library still operates with a linear + address space. + + <p>Another variation might be a family of two files where all the + meta data is stored in one file and all the raw data is stored + in another file to allow the HDF5 wrapper to be easily replaced + with some other wrapper. + + <p>The <code>H5Fcreate</code> and <code>H5Fopen</code> functions + would need to be modified to pass file-type info down to layer 2 + so the correct drivers can be called and parameters passed to + the drivers to initialize them. + + <h4>Implementation</h4> + + <p>I've implemented fixed-size family members. The entire hdf5 + file is partitioned into members where each member is the same + size. The family scheme is used if one passes a name to + <code>H5F_open</code> (which is called by <code>H5Fopen()</code> + and <code>H5Fcreate</code>) that contains a + <code>printf(3c)</code>-style integer format specifier. + Currently, the default low-level file driver is used for all + family members (H5F_LOW_DFLT, usually set to be Section 2 I/O or + Section 3 stdio), but we'll probably eventually want to pass + that as a parameter of the file access template, which hasn't + been implemented yet. When creating a family, a default family + member size is used (defined at the top H5Ffamily.c, currently + 64MB) but that also should be settable in the file access + template. When opening an existing family, the size of the first + member is used to determine the member size (flushing/closing a + family ensures that the first member is the correct size) but + the other family members don't have to be that large (the local + address space, however, is logically the same size for all + members). + + <p>I haven't implemented a split meta/raw family yet but am rather + curious to see how it would perform. I was planning to use the + `.h5' extension for the meta data file and `.raw' for the raw + data file. The high-order bit in the address would determine + whether the address refers to meta data or raw data. If the user + passes a name that ends with `.raw' to <code>H5F_open</code> + then we'll chose the split family and use the default low level + driver for each of the two family members. Eventually we'll + want to pass these kinds of things through the file access + template instead of relying on naming convention. + + <h3>External Raw Data</h3> + + <p>We also need the ability to point to raw data that isn't in the + HDF5 linear address space. For instance, a dataset might be + striped across several raw data files. + + <p>Fortunately, the only two packages that need to be aware of + this are the packages for reading/writing contiguous raw data + and discontiguous raw data. Since contiguous raw data is a + special case, I'll discuss how to implement external raw data in + the discontiguous case. + + <p>Discontiguous data is stored as a B-tree whose keys are the + chunk indices and whose leaf nodes point to the raw data by + storing a file address. So what we need is some way to name the + external files, and a way to efficiently store the external file + name for each chunk. + + <p>I propose adding to the object header an <em>External File + List</em> message that is a 1-origin array of file names. + Then, in the B-tree, each key has an index into the External + File List (or zero for the HDF5 file) for the file where the + chunk can be found. The external file index is only used at + the leaf nodes to get to the raw data (the entire B-tree is in + the HDF5 file) but because of the way keys are copied among + the B-tree nodes, it's much easier to store the index with + every key. + + <h3>Multiple HDF5 Files</h3> + + <p>One might also want to combine two or more HDF5 files in a + manner similar to mounting file systems in Unix. That is, the + group structure and meta data from one file appear as though + they exist in the first file. One opens File-A, and then + <em>mounts</em> File-B at some point in File-A, the <em>mount + point</em>, so that traversing into the mount point actually + causes one to enter the root object of File-B. File-A and + File-B are each complete HDF5 files and can be accessed + individually without mounting them. + + <p>We need a couple additional pieces of machinery to make this + work. First, an haddr_t type (a file address) doesn't contain + any info about which HDF5 file's address space the address + belongs to. But since haddr_t is an opaque type except at + layers 2 and below, it should be quite easy to add a pointer to + the HDF5 file. This would also remove the H5F_t argument from + most of the low-level functions since it would be part of the + OID. + + <p>The other thing we need is a table of mount points and some + functions that understand them. We would add the following + table to each H5F_t struct: + + <p><code><pre> +struct H5F_mount_t { + H5F_t *parent; /* Parent HDF5 file if any */ + struct { + H5F_t *f; /* File which is mounted */ + haddr_t where; /* Address of mount point */ + } *mount; /* Array sorted by mount point */ + intn nmounts; /* Number of mounted files */ + intn alloc; /* Size of mount table */ +} + </pre></code> + + <p>The <code>H5Fmount</code> function takes the ID of an open + file, the name of a to-be-mounted file, the name of the mount + point, and a file access template (like <code>H5Fopen</code>). + It opens the new file and adds a record to the parent's mount + table. The <code>H5Funmount</code> function takes the parent + file ID and the name of the mount point and closes the file + that's mounted at that point. The <code>H5Fclose</code> + function closes/unmounts files recursively. + + <p>The <code>H5G_iname</code> function which translates a name to + a file address (<code>haddr_t</code>) looks at the mount table + at each step in the translation and switches files where + appropriate. All name-to-address translations occur through + this function. + + <h3>How Long?</h3> + + <p>I'm expecting to be able to implement the two new flavors of + single linear address space in about two days. It took two hours + to implement the malloc/free file driver at level zero and I + don't expect this to be much more work. + + <p>I'm expecting three days to implement the external raw data for + discontiguous arrays. Adding the file index to the B-tree is + quite trivial; adding the external file list message shouldn't + be too hard since the object header message class from wich this + message derives is fully implemented; and changing + <code>H5F_istore_read</code> should be trivial. Most of the + time will be spent designing a way to cache Unix file + descriptors efficiently since the total number open files + allowed per process could be much smaller than the total number + of HDF5 files and external raw data files. + + <p>I'm expecting four days to implement being able to mount one + HDF5 file on another. I was originally planning a lot more, but + making <code>haddr_t</code> opaque turned out to be much easier + than I planned (I did it last Fri). Most of the work will + probably be removing the redundant H5F_t arguments for lots of + functions. + + <h3>Conclusion</h3> + + <p>The external raw data could be implemented as a single linear + address space, but doing so would require one to allocate large + enough file addresses throughout the file (>32bits) before the + file was created. It would make mixing an HDF5 file family with + external raw data, or external HDF5 wrapper around an HDF4 file + a more difficult process. So I consider the implementation of + external raw data files as a single HDF5 linear address space a + kludge. + + <p>The ability to mount one HDF5 file on another might not be a + very important feature especially since each HDF5 file must be a + complete file by itself. It's not possible to stripe an array + over multiple HDF5 files because the B-tree wouldn't be complete + in any one file, so the only choice is to stripe the array + across multiple raw data files and store the B-tree in the HDF5 + file. On the other hand, it might be useful if one file + contains some public data which can be mounted by other files + (e.g., a mesh topology shared among collaborators and mounted by + files that contain other fields defined on the mesh). Of course + the applications can open the two files separately, but it might + be more portable if we support it in the library. + + <p>So we're looking at about two weeks to implement all three + versions. I didn't get a chance to do any of them in AIO + although we had long-term plans for the first two with a + possibility of the third. They'll be much easier to implement in + HDF5 than AIO since I've been keeping these in mind from the + start. + + <hr> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- Created: Sat Nov 8 18:08:52 EST 1997 --> +<!-- hhmts start --> +Last modified: Wed Nov 12 15:01:14 EST 1997 +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/Files.html b/doc/html/Files.html new file mode 100644 index 0000000..791cc1f --- /dev/null +++ b/doc/html/Files.html @@ -0,0 +1,529 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>HDF5 Files</title> + </head> + + <body> + <h1>Files</h1> + + <h2>1. Introduction</h2> + + <p>HDF5 files are composed of a "boot block" describing information + required to portably access files on multiple platforms, followed + by information about the groups in a file and the datasets in the + file. The boot block contains information about the size of offsets + and lengths of objects, the number of entries in symbol tables + (used to store groups) and additional version information for the + file. + + <h2>2. File access modes</h2> + + <p>The HDF5 library assumes that all files are implicitly opened for read + access at all times. Passing the <code>H5F_ACC_RDWR</code> + parameter to <code>H5Fopen()</code> allows write access to a + file also. <code>H5Fcreate()</code> assumes write access as + well as read access, passing <code>H5F_ACC_TRUNC</code> forces + the truncation of an existing file, otherwise H5Fcreate will + fail to overwrite an existing file. + + <h2>3. Creating, Opening, and Closing Files</h2> + + <p>Files are created with the <code>H5Fcreate()</code> function, + and existing files can be accessed with <code>H5Fopen()</code>. Both + functions return an object ID which should be eventually released by + calling <code>H5Fclose()</code>. + + <dl> + <dt><code>hid_t H5Fcreate (const char *<em>name</em>, uintn + <em>flags</em>, hid_t <em>create_properties</em>, hid_t + <em>access_properties</em>)</code> + <dd>This function creates a new file with the specified name in + the current directory. The file is opened with read and write + permission, and if the <code>H5F_ACC_TRUNC</code> flag is set, + any current file is truncated when the new file is created. + If a file of the same name exists and the + <code>H5F_ACC_TRUNC</code> flag is not set (or the + <code>H5F_ACC_EXCL</code> bit is set), this function will + fail. Passing <code>H5P_DEFAULT</code> for the creation + and/or access property lists uses the library's default + values for those properties. Creating and changing the + values of a property list is documented further below. The + return value is an ID for the open file and it should be + closed by calling <code>H5Fclose()</code> when it's no longer + needed. A negative value is returned for failure. + + <br><br> + <dt><code>hid_t H5Fopen (const char *<em>name</em>, uintn + <em>flags</em>, hid_t <em>access_properties</em>)</code> + <dd>This function opens an existing file with read permission + and write permission if the <code>H5F_ACC_RDWR</code> flag is + set. The <em>access_properties</em> is a file access property + list ID or <code>H5P_DEFAULT</code> for the default I/O access + parameters. Creating and changing the parameters for access + templates is documented further below. Files which are opened + more than once return a unique identifier for each + <code>H5Fopen()</code> call and can be accessed through all + file IDs. The return value is an ID for the open file and it + should be closed by calling <code>H5Fclose()</code> when it's + no longer needed. A negative value is returned for failure. + + <br><br> + <dt><code>herr_t H5Fclose (hid_t <em>file_id</em>)</code> + <dd>This function releases resources used by a file which was + opened by <code>H5Fcreate()</code> or <code>H5Fopen()</code>. After + closing a file the <em>file_id</em> should not be used again. This + function returns zero for success or a negative value for failure. + </dl> + + <h2>4. File Property Lists</h2> + + <p>Additional parameters to <code>H5Fcreate()</code> or + <code>H5Fopen()</code> are passed through property list + objects, which are created with the <code>H5Pcreate()</code> + function. These objects allow many parameters of a file's + creation or access to be changed from the default values. + Property lists are used as a portable and extensible method of + modifying multiple parameter values with simple API functions. + There are two kinds of file-related property lists, + namely file creation properties and file access properties. + + <h3>4.1. File Creation Properties</h3> + + <P>File creation property lists apply to <code>H5Fcreate()</code> only + and are used to control the file meta-data which is maintained + in the boot block of the file. The parameters which can be + modified are: + + <dl> + <dt>User-Block Size <dd>The "user-block" is a fixed length block of + data located at the beginning of the file which is ignored by the + HDF5 library and may be used to store any data information found + to be useful to applications. This value may be set to any power + of two equal to 512 or greater (i.e. 512, 1024, 2048, etc). This + parameter is set and queried with the + <code>H5Pset_userblock()</code> and + <code>H5Pget_userblock()</code> calls. + + <br><br> + <dt>Offset and Length Sizes + <dd>The number of bytes used to store the offset and length of + objects in the HDF5 file can be controlled with this + parameter. Values of 2, 4 and 8 bytes are currently + supported to allow 16-bit, 32-bit and 64-bit files to + be addressed. These parameters are set and queried + with the <code>H5Pset_sizes()</code> and + <code>H5Pget_sizes()</code> calls. + + <br><br> + <dt>Symbol Table Parameters + <dd>The size of symbol table B-trees can be controlled by setting + the 1/2 rank and 1/2 node size parameters of the B-tree. These + parameters are set and queried with the + <code>H5Pset_sym_k()</code> and <code>H5Pget_sym_k()</code> calls. + + <br><br> + <dt>Indexed Storage Parameters + <dd>The size of indexed storage B-trees can be controlled by + setting the 1/2 rank and 1/2 node size parameters of the B-tree. + These parameters are set and queried with the + <code>H5Pset_istore_k()</code> and <code>H5Pget_istore_k()</code> + calls. + </dl> + + <h3>4.2. File Access Property Lists</h3> + + <p>File access property lists apply to <code>H5Fcreate()</code> or + <code>H5Fopen()</code> and are used to control different methods of + performing I/O on files. + + <dl> + <dt>Unbuffered I/O + <dd>Local permanent files can be accessed with the functions described + in Section 2 of the Posix manual, namely <code>open()</code>, + <code>lseek()</code>, <code>read()</code>, <code>write()</code>, and + <code>close()</code>. The <code>lseek64()</code> function is used + on operating systems that support it. This driver is enabled and + configured with <code>H5Pset_sec2()</code>, and queried with + <code>H5Pget_sec2()</code>. + + <br><br> + <dt>Buffered I/O + <dd>Local permanent files can be accessed with the functions declared + in the <code>stdio.h</code> header file, namely + <code>fopen()</code>, <code>fseek()</code>, <code>fread()</code>, + <code>fwrite()</code>, and <code>fclose()</code>. The + <code>fseek64()</code> function is used on operating systems that + support it. This driver is enabled and configured with + <code>H5Pset_stdio()</code>, and queried with + <code>H5Pget_stdio()</code>. + + <br><br> + <dt>Memory I/O + <dd>Local temporary files can be created and accessed directly from + memory without ever creating permanent storage. The library uses + <code>malloc()</code> and <code>free()</code> to create storage + space for the file. The total size of the file must be small enough + to fit in virtual memory. The name supplied to + <code>H5Fcreate()</code> is irrelevant, and <code>H5Fopen()</code> + will always fail. + + <br><br> + <dt>Parallel Files using MPI I/O + <dd>This driver allows parallel access to a file through the MPI I/O + library. The parameters which can be modified are the MPI + communicator, the info object, and the access mode. + The communicator and info object are saved and then + passed to <code>MPI_File_open()</code> during file creation or open. + The access_mode controls the kind of parallel access the application + intends. (Note that it is likely that the next API revision will + remove the access_mode parameter and have access control specified + via the raw data transfer property list of <code>H5Dread()</code> + and <code>H5Dwrite()</code>.) These parameters are set and queried + with the <code>H5Pset_mpi()</code> and <code>H5Pget_mpi()</code> + calls. + + <br><br> + <dt>Data Alignment + <dd>Sometimes file access is faster if certain things are + aligned on file blocks. This can be controlled by setting + alignment properties of a file access property list with the + <code>H5Pset_alignment()</code> function. Any allocation + request at least as large as some threshold will be aligned on + an address which is a multiple of some number. + </dl> </ul> + + <h2>5. Examples of using file templates</h2> + + <h3>5.1. Example of using file creation templates</h3> + + <p>This following example shows how to create a file with 64-bit object + offsets and lengths:<br> + <pre> + hid_t create_template; + hid_t file_id; + + create_template = H5Pcreate(H5P_FILE_CREATE); + H5Pset_sizes(create_template, 8, 8); + + file_id = H5Fcreate("test.h5", H5F_ACC_TRUNC, + create_template, H5P_DEFAULT); + . + . + . + H5Fclose(file_id); + </pre> + + <h3>5.2. Example of using file creation templates</h3> + + <p>This following example shows how to open an existing file for + independent datasets access by MPI parallel I/O:<br> + <pre> + hid_t access_template; + hid_t file_id; + + access_template = H5Pcreate(H5P_FILE_ACCESS); + H5Pset_mpi(access_template, MPI_COMM_WORLD, MPI_INFO_NULL); + + /* H5Fopen must be called collectively */ + file_id = H5Fopen("test.h5", H5F_ACC_RDWR, access_template); + . + . + . + /* H5Fclose must be called collectively */ + H5Fclose(file_id); + </pre> + + + <h2>6. Low-level File Drivers</h2> + + <p>HDF5 is able to access its address space through various types of + low-level <em>file drivers</em>. For instance, an address space might + correspond to a single file on a Unix file system, multiple files on a + Unix file system, multiple files on a parallel file system, or a block + of memory within the application. Generally, an HDF5 address space is + referred to as an "HDF5 file" regardless of how the space is organized + at the storage level. + + <h3>6.1 Unbuffered Permanent Files</h3> + + <p>The <em>sec2</em> driver uses functions from section 2 of the + Posix manual to access files stored on a local file system. These are + the <code>open()</code>, <code>close()</code>, <code>read()</code>, + <code>write()</code>, and <code>lseek()</code> functions. If the + operating system supports <code>lseek64()</code> then it is used instead + of <code>lseek()</code>. The library buffers meta data regardless of + the low-level driver, but using this driver prevents data from being + buffered again by the lowest layers of the HDF5 library. + + <dl> + <dt><code>H5F_driver_t H5Pget_driver (hid_t + <em>access_properties</em>)</code> + <dd>This function returns the constant <code>H5F_LOW_SEC2</code> if the + <em>sec2</em> driver is defined as the low-level driver for the + specified access property list. + + <br><br> + <dt><code>herr_t H5Pset_sec2 (hid_t <em>access_properties</em>)</code> + <dd>The file access properties are set to use the <em>sec2</em> + driver. Any previously defined driver properties are erased from the + property list. Additional parameters may be added to this function in + the future. + + <br><br> + <dt><code>herr_t H5Pget_sec2 (hid_t <em>access_properties</em>)</code> + <dd>If the file access property list is set to the <em>sec2</em> driver + then this function returns zero; otherwise it returns a negative + value. In the future, additional arguments may be added to this + function to match those added to <code>H5Pset_sec2()</code>. + </dl> + + <h3>6.2 Buffered Permanent Files</h3> + + <p>The <em>stdio</em> driver uses the functions declared in the + <code>stdio.h</code> header file to access permanent files in a local + file system. These are the <code>fopen()</code>, <code>fclose()</code>, + <code>fread()</code>, <code>fwrite()</code>, and <code>fseek()</code> + functions. If the operating system supports <code>fseek64()</code> then + it is used instead of <code>fseek()</code>. Use of this driver + introduces an additional layer of buffering beneath the HDF5 library. + + <dl> + <dt><code>H5F_driver_t H5Pget_driver(hid_t + <em>access_properties</em>)</code> + <dd>This function returns the constant <code>H5F_LOW_STDIO</code> if the + <em>stdio</em> driver is defined as the low-level driver for the + specified access property list. + + <br><br> + <dt><code>herr_t H5Pset_stdio (hid_t <em>access_properties</em>)</code> + <dd>The file access properties are set to use the <em>stdio</em> + driver. Any previously defined driver properties are erased from the + property list. Additional parameters may be added to this function in + the future. + + <br><br> + <dt><code>herr_t H5Pget_stdio (hid_t <em>access_properties</em>)</code> + <dd>If the file access property list is set to the <em>stdio</em> driver + then this function returns zero; otherwise it returns a negative + value. In the future, additional arguments may be added to this + function to match those added to <code>H5Pset_stdio()</code>. + </dl> + + <h3>6.3 Buffered Temporary Files</h3> + + <p>The <em>core</em> driver uses <code>malloc()</code> and + <code>free()</code> to allocated space for a file in the heap. Reading + and writing to a file of this type results in mem-to-mem copies instead + of disk I/O and as a result is somewhat faster. However, the total file + size must not exceed the amount of available virtual memory, and only + one HDF5 file handle can access the file (because the name of such a + file is insignificant and <code>H5Fopen()</code> always fails). + + <dl> + <dt><code>H5F_driver_t H5Pget_driver (hid_t + <em>access_properties</em>)</code> + <dd>This function returns the constant <code>H5F_LOW_CORE</code> if the + <em>core</em> driver is defined as the low-level driver for the + specified access property list. + + <br><br> + <dt><code>herr_t H5Pset_core (hid_t <em>access_properties</em>, size_t + <em>block_size</em>)</code> + <dd>The file access properties are set to use the <em>core</em> + driver and any previously defined driver properties are erased from + the property list. Memory for the file will always be allocated in + units of the specified <em>block_size</em>. Additional parameters may + be added to this function in the future. + + <br><br> + <dt><code>herr_t H5Pget_core (hid_t <em>access_properties</em>, size_t + *<em>block_size</em>)</code> + <dd>If the file access property list is set to the <em>core</em> driver + then this function returns zero and <em>block_size</em> is set to the + block size used for the file; otherwise it returns a negative + value. In the future, additional arguments may be added to this + function to match those added to <code>H5Pset_core()</code>. + </dl> + + <h3>6.4 Parallel Files</h3> + + <p>This driver uses MPI I/O to provide parallel access to a file. + + <dl> + <dt><code>H5F_driver_t H5Pget_driver (hid_t + <em>access_properties</em>)</code> + <dd>This function returns the constant <code>H5F_LOW_MPI</code> if the + <em>mpi</em> driver is defined as the low-level driver for the + specified access property list. + + <br><br> + <dt><code>herr_t H5Pset_mpi (hid_t <em>access_properties</em>, MPI_Comm + <em>comm</em>, MPI_info <em>info</em>)</code> + <dd>The file access properties are set to use the <em>mpi</em> + driver and any previously defined driver properties are erased from + the property list. Additional parameters may be added to this + function in the future. + + <br><br> + <dt><code>herr_t H5Pget_mpi (hid_t <em>access_properties</em>, MPI_Comm + *<em>comm</em>, MPI_info *<em>info</em>)</code> + <dd>If the file access property list is set to the <em>mpi</em> driver + then this function returns zero and <em>comm</em>, and <em>info</em> + are set to the values stored in the property + list; otherwise the function returns a negative value. In the future, + additional arguments may be added to this function to match those + added to <code>H5Pset_mpi()</code>. + </dl> + + <h3>6.4 File Families</h3> + + <p>A single HDF5 address space may be split into multiple files which, + together, form a file family. Each member of the family must be the + same logical size although the size and disk storage reported by + <code>ls</code>(1) may be substantially smaller. The name passed to + <code>H5Fcreate()</code> or <code>H5Fopen()</code> should include a + <code>printf(3c)</code> style integer format specifier which will be + replaced with the family member number (the first family member is + zero). + + <p>Any HDF5 file can be split into a family of files by running + the file through <code>split</code>(1) and numbering the output + files. However, because HDF5 is lazy about extending the size + of family members, a valid file cannot generally be created by + concatenation of the family members. Additionally, + <code>split</code> and <code>cat</code> don't attempt to + generate files with holes. The <code>h5repart</code> program + can be used to repartition an HDF5 file or family into another + file or family and preserves holes in the files. + + <dl> + <dt><code>h5repart</code> [<code>-v</code>] [<code>-b</code> + <em>block_size</em>[<em>suffix</em>]] [<code>-m</code> + <em>member_size</em>[<em>suffix</em>]] <em>source + destination</em> + <dd>This program repartitions an HDF5 file by copying the source + file or family to the destination file or family preserving + holes in the underlying Unix files. Families are used for the + source and/or destination if the name includes a + <code>printf</code>-style integer format such as "%d". The + <code>-v</code> switch prints input and output file names on + the standard error stream for progress monitoring, + <code>-b</code> sets the I/O block size (the default is 1kB), + and <code>-m</code> sets the output member size if the + destination is a family name (the default is 1GB). The block + and member sizes may be suffixed with the letters + <code>g</code>, <code>m</code>, or <code>k</code> for GB, MB, + or kB respectively. + + <br><br> + <dt><code>H5F_driver_t H5Pget_driver (hid_t + <em>access_properties</em>)</code> + <dd>This function returns the constant <code>H5F_LOW_FAMILY</code> if + the <em>family</em> driver is defined as the low-level driver for the + specified access property list. + + <br><br> + <dt><code>herr_t H5Pset_family (hid_t <em>access_properties</em>, + hsize_t <em>memb_size</em>, hid_t <em>member_properties</em>)</code> + <dd>The file access properties are set to use the <em>family</em> + driver and 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. + + <br><br> + <dt><code>herr_t H5Pget_family (hid_t <em>access_properties</em>, + hsize_t *<em>memb_size</em>, hid_t + *<em>member_properties</em>)</code> + <dd>If the file access property list is set to the <em>family</em> + driver then this function returns zero; otherwise the function + returns a negative value. 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()</em> 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>. + </dl> + + <h3>6.5 Split Meta/Raw Files</h3> + + <p>On occasion, it might be useful to separate meta data from raw + data. The <em>split</em> driver does this by creating two files: one for + meta data and another for raw data. The application provides a base + file name to <code>H5Fcreate()</code> or <code>H5Fopen()</code> and this + driver appends a file extension which defaults to ".meta" for the meta + data file and ".raw" for the raw data file. Each file can have its own + file access property list which allows, for instance, a split file with + meta data stored with the <em>core</em> driver and raw data stored with + the <em>sec2</em> driver. + + <dl> + <dt><code>H5F_driver_t H5Pget_driver (hid_t + <em>access_properties</em>)</code> + <dd>This function returns the constant <code>H5F_LOW_SPLIT</code> if + the <em>split</em> driver is defined as the low-level driver for the + specified access property list. + + <br><br> + <dt><code>herr_t H5Pset_split (hid_t <em>access_properties</em>, + const char *<em>meta_extension</em>, hid_t + <em>meta_properties</em>, const char *<em>raw_extension</em>, hid_t + <em>raw_properties</em>)</code> + <dd>The file access properties are set to use the <em>split</em> + driver and any previously defined driver properties are erased from + the property list. The meta file will have a name which is formed by + adding <em>meta_extension</em> (or ".meta") 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> (or ".raw") 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. + + <br><br> + <dt><code>herr_t H5Pget_split (hid_t <em>access_properties</em>, + size_t <em>meta_ext_size</em>, const char *<em>meta_extension</em>, + hid_t <em>meta_properties</em>, size_t <em>raw_ext_size</em>, const + char *<em>raw_extension</em>, hid_t *<em>raw_properties</em>)</code> + <dd>If the file access property list is set to the <em>split</em> + driver then this function returns zero; otherwise the function + returns a negative value. 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()</em> 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 handle. 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>. + </dl> + + + <hr> + <address><a href="mailto:koziol@ncsa.uiuc.edu">Quincey Koziol</a></address> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- Created: Tue Jan 27 09:11:27 EST 1998 --> +<!-- hhmts start --> +Last modified: Tue Jun 9 15:03:44 EDT 1998 +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/Groups.html b/doc/html/Groups.html new file mode 100644 index 0000000..b1be2f1 --- /dev/null +++ b/doc/html/Groups.html @@ -0,0 +1,288 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>Groups</title> + </head> + + <body> + <h1>Groups</h1> + + <h2>1. Introduction</h2> + + <p>An object in HDF5 consists of an object header at a fixed file + address that contains messages describing various properties of + the object such as its storage location, layout, compression, + etc. and some of these messages point to other data such as the + raw data of a dataset. The address of the object header is also + known as an <em>OID</em> and HDF5 has facilities for translating + names to OIDs. + + <p>Every HDF5 object has at least one name and a set of names can + be stored together in a group. Each group implements a name + space where the names are any length and unique with respect to + other names in the group. + + <p>Since a group is a type of HDF5 object it has an object header + and a name which exists as a member of some other group. In this + way, groups can be linked together to form a directed graph. + One particular group is called the <em>Root Group</em> and is + the group to which the HDF5 file boot block points. Its name is + "/" by convention. The <em>full name</em> of an object is + created by joining component names with slashes much like Unix. + + <p> + <center> + <img alt="Group Graph Example" src="group_p1.gif"> + </center> + + <p>However, unlike Unix which arranges directories hierarchically, + HDF5 arranges groups in a directed graph. Therefore, there is + no ".." entry in a group since a group can have more than one + parent. There is no "." entry either but the library understands + it internally. + + <h2>2. Names</h2> + + <p>HDF5 places few restrictions on names: component names may be + any length except zero and may contain any character except + slash ("/") and the null terminator. A full name may be + composed of any number of component names separated by slashes, + with any of the component names being the special name ".". A + name which begins with a slash is an <em>absolute</em> name + which is looked up beginning at the root group of the file while + all other <em>relative</em> names are looked up beginning at the + current working group (described below) or a specified group. + Multiple consecutive slashes in a full name are treated as + single slashes and trailing slashes are not significant. A + special case is the name "/" (or equivalent) which refers to the + root group. + + <p>Functions which operate on names generally take a location + identifier which is either a file ID or a group ID and perform + the lookup with respect to that location. Some possibilities + are: + + <p> + <center> + <table border cellpadding=4> + <tr> + <th>Location Type</th> + <th>Object Name</th> + <th>Description</th> + </tr> + + <tr> + <td>File ID</td> + <td><code>/foo/bar</code></td> + <td>The object <code>bar</code> in group <code>foo</code> + in the root group of the specified file.</td> + </tr> + + <tr> + <td>Group ID</td> + <td><code>/foo/bar</code></td> + <td>The object <code>bar</code> in group <code>foo</code> + in the root group of the file containing the specified + group. In other words, the group ID's only purpose is + to supply a file.</td> + </tr> + + <tr> + <td>File ID</td> + <td><code>/</code></td> + <td>The root group of the specified file.</td> + </tr> + + <tr> + <td>Group ID</td> + <td><code>/</code></td> + <td>The root group of the file containing the specified + group.</td> + </tr> + + <tr> + <td>File ID</td> + <td><code>foo/bar</code></td> + <td>The object <code>bar</code> in group <code>foo</code> + in the current working group of the specified file. The + initial current working group is the root group of the + file as described below.</td> + </tr> + + <tr> + <td>Group ID</td> + <td><code>foo/bar</code></td> + <td>The object <code>bar</code> in group <code>foo</code> + in the specified group.</td> + </tr> + + <tr> + <td>File ID</td> + <td><code>.</code></td> + <td>The current working group of the specified file.</td> + </tr> + + <tr> + <td>Group ID</td> + <td><code>.</code></td> + <td>The specified group.</td> + </tr> + + <tr> + <td>Other ID</td> + <td><code>.</code></td> + <td>The specified object.</td> + </tr> + + </table> + </center> + + + <h2>3. Creating, Opening, and Closing Groups</h2> + + <p>Groups are created with the <code>H5Gcreate()</code> function, + and existing groups can be access with + <code>H5Gopen()</code>. Both functions return an object ID which + should be eventually released by calling + <code>H5Gclose()</code>. + + <dl> + <dt><code>hid_t H5Gcreate (hid_t <em>location_id</em>, const char + *<em>name</em>, size_t <em>size_hint</em>)</code> + <dd>This function creates a new group with the specified + name at the specified location which is either a file ID or a + group ID. The name must not already be taken by some other + object and all parent groups must already exist. The + <em>size_hint</em> 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 <em>size_hint</em> + is usually adequate since the library is able to dynamically + resize the name heap, but a correct hint may result in better + performance. The return value is a handle for the open group + and it should be closed by calling <code>H5Gclose()</code> + when it's no longer needed. A negative value is returned for + failure. + + <br><br> + <dt><code>hid_t H5Gopen (hid_t <em>location_id</em>, const char + *<em>name</em>)</code> + <dd>This function opens an existing group with the specified + name at the specified location which is either a file ID or a + group ID and returns an object ID. The object ID should be + released by calling <code>H5Gclose()</code> when it is no + longer needed. A negative value is returned for failure. + + <br><br> + <dt><code>herr_t H5Gclose (hid_t <em>group_id</em>)</code> + <dd>This function releases resources used by an group which was + opened by <code>H5Gcreate()</code> or + <code>H5Gopen()</code>. After closing a group the + <em>group_id</em> should not be used again. This function + returns zero for success or a negative value for failure. + </dl> + + <h2>4. Current Working Group</h2> + + <p>Each file handle (<code>hid_t <em>file_id</em></code>) has a + current working group, initially the root group of the file. + Names which do not begin with a slash are relative to the + specified group or to the current working group as described + above. For instance, the name "/Foo/Bar/Baz" is resolved by + first looking up "Foo" in the root group. But the name + "Foo/Bar/Baz" is resolved by first looking up "Foo" in the + current working group. + + <dl> + <dt><code>herr_t H5Gset (hid_t <em>location_id</em>, const char + *<em>name</em>)</code> + <dd>The group with the specified name is made the current + working group for the file which contains it. The + <em>location_id</em> can be a file handle or a group handle + and the name is resolved as described above. Each file handle + has it's own current working group and if the + <em>location_id</em> is a group handle then the file handle is + derived from the group handle. This function returns zero for + success or negative for failure. + + <br><br> + <dt><code>herr_t H5Gpush (hid_t <em>location_id</em>, const char + *<em>name</em>)</code> + <dd>Each file handle has a stack of groups and the top group on + that stack is the current working group. The stack initially + contains only the root group. This function pushes a new + group onto the stack and returns zero for success or negative + for failure. + + <br><br> + <dt><code>herr_t H5Gpop (hid_t <em>location_id</em>)</code> + <dd>This function pops one group off the group stack for the + specified file (if the <em>location_id</em> is a group then + the file is derived from that group), changing the current + working group to the new top-of-stack group. The function + returns zero for success or negative for failure (failure + includes attempting to pop from an empty stack). If the last + item is popped from the stack then the current working group + is set to the root group. + </dl> + + <h2>5. Objects with Multiple Names</h2> + + <p>An object (including a group) can have more than one + name. Creating the object gives it the first name, and then + functions described here can be used to give it additional + names. The association between a name and the object is called + a <em>link</em> and HDF5 supports two types of links: a <em>hard + link</em> is a direct association between the name and the + object where both exist in a single HDF5 address space, and a + <em>soft link</em> is an indirect association. + + <p> + <center> + <img alt="Hard Link Example" src="group_p2.gif"> + </center> + + <p> + <center> + <img alt="Soft Link Example" src="group_p3.gif"> + </center> + + <dl> + <dt>Object Creation</dt> + <dd>The creation of an object creates a hard link which is + indistinguishable from other hard links that might be added + later. + + <br><br> + <dt><code>herr_t H5Glink (hid_t <em>file_id</em>, H5G_link_t + <em>link_type</em>, const char *<em>current_name</em>, + const char *<em>new_name</em>)</code> + <dd>Creates a new name for an object that has some current name + (possibly one of many names it currently has). If the + <em>link_type</em> is <code>H5G_LINK_HARD</code> then a new + hard link is created. Otherwise if <em>link_type</em> is + <code>H5T_LINK_SOFT</code> a soft link is created which is an + alias for the <em>current_name</em>. When creating a soft + link the object need not exist. This function returns zero + for success or negative for failure. <b>This function is not + part of the prototype API.</b> + + <br><br> + <dt><code>herr_t H5Gunlink (hid_t <em>file_id</em>, const char + *<em>name</em>)</code> + <dd>This function removes an association between a name and an + object. Object headers keep track of how many hard links refer + to the object and when the hard link count reaches zero the + object can be removed from the file (but objects which are + open are not removed until all handles to the object are + closed). <b>This function is not part of the prototype + API.</b> + </dl> + + <hr> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- Created: Tue Jan 27 09:11:27 EST 1998 --> +<!-- hhmts start --> +Last modified: Tue Mar 24 15:52:14 EST 1998 +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/H5.api.html b/doc/html/H5.api.html new file mode 100644 index 0000000..b2402a5 --- /dev/null +++ b/doc/html/H5.api.html @@ -0,0 +1,4611 @@ +<html><head><title> +HDF5 Draft API Specification +</title></head><body> + +<center> +<h1>HDF5: API Specification</h1> +</center> + +<ol type=I> +<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="#File">File</a> - H5F<name> - API for accessing HDF files +<ol type=A> + <li><a href="#File-Open">H5Fopen</a> + <li><a href="#File-Create">H5Fcreate</a> + <li><a href="#File-IsHDF5">H5Fis_hdf5</a> + <li><a href="#File-GetCreateTemplate">H5Fget_create_template</a> + <li><a href="#File-Close">H5Fclose</a> +</ol> + +<li><a href="#Template">Template</a> - H5P<name> - API for manipulating object templates +<ol type=A> + <li><a href="#Template-Create">H5Pcreate</a> + <li><a href="#Template-GetClass">H5Pget_class</a> + <li><a href="#Template-Copy">H5Pcopy</a> + <li><a href="#Template-Close">H5Pclose</a> + <li><a href="#Template-GetVersion">H5Pget_version</a> + <li><a href="#Template-SetUserblock">H5Pset_userblock</a> + <li><a href="#Template-GetUserblock">H5Pget_userblock</a> + <li><a href="#Template-SetSizes">H5Pset_sizes</a> + <li><a href="#Template-GetSizes">H5Pget_sizes</a> + <li><a href="#Template-SetMPI">H5Pset_mpi</a> + <li><a href="#Template-GetMPI">H5Pget_mpi</a> + <li><a href="#Template-SetXfer">H5Pset_xfer</a> + <li><a href="#Template-GetXfer">H5Pget_xfer</a> + <li><a href="#Template-SetSymK">H5Pset_sym_k</a> + <li><a href="#Template-GetSymK">H5Pget_sym_k</a> + <li><a href="#Template-SetIstoreK">H5Pset_istore_k</a> + <li><a href="#Template-GetIstoreK">H5Pget_istore_k</a> + <li><a href="#Template-SetLayout">H5Pset_layout</a> + <li><a href="#Template-GetLayout">H5Pget_layout</a> + <li><a href="#Template-SetChunk">H5Pset_chunk</a> + <li><a href="#Template-GetChunk">H5Pget_chunk</a> +</ol> + +<!-- +<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="#Dataset">Dataset</a> - H5D<name> - API for manipulating scientific datasets. See <a href="Datasets.html">datasets</a>. +<ol type=A> + <li><a href="#Dataset-Create">H5Dcreate</a> + <li><a href="#Dataset-Open">H5Dopen</a> + <li><a href="#Dataset-GetSpace">H5Dget_space</a> + <li><a href="#Dataset-GetType">H5Dget_type</a> + <li><a href="#Dataset-GetCreateParms">H5Dget_create_parms</a> + <li><a href="#Dataset-Read">H5Dread</a> + <li><a href="#Dataset-Write">H5Dwrite</a> + <li><a href="#Dataset-Extend">H5Dextend</a> + <li><a href="#Dataset-Close">H5Dclose</a> +</ol> + +<li><a href="#Datatype">Datatype</a> - H5T<name> - API for defining dataset element information. See <a href="Datatypes.html">data types</a>. +<ol type=A> + <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> + <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> + <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> +</ol> + +<li><a href="#Dataspace">Dataspace</a> - H5S<name> - API for defining dataset dataspace +<ol type=A> + <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> + <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> + <li><a href="#Dataspace-GetHyperslab">H5Sget_hyperslab</a> + <li><a href="#Dataspace-Close">H5Sclose</a> +</ol> + +<li><a href="#Group">Group</a> - H5G<name> - API for creating physical groups of objects on disk. +<ol type=A> + <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-Push">H5Gpush</a> + <li><a href="#Group-Pop">H5Gpop</a> + <li><a href="#Group-Close">H5Gclose</a> +<!-- + <li><a href="#Group-GetNumContents">get_num_contents</a> + <li><a href="#Group-GetContentInfo">get_content_info</a> + <li><a href="#Group-GetContentInfoMult">get_content_info_mult</a> + <li><a href="#Group-GetOIDByName">get_oid_by_name</a> + <li><a href="#Group-GetOIDByIndex">get_oid_by_index</a> + <li><a href="#Group-GetNameByOID">get_name_by_oid</a> + <li><a href="#Group-GetNameByIndex">get_name_by_index</a> + <li><a href="#Group-InsertItem">insert_item</a> + <li><a href="#Group-InsertItemMult">insert_item_mult</a> + <li><a href="#Group-RemoveItem">remove_item</a> + <li><a href="#Group-RemoveItemMult">remove_item_mult</a> +--> +</ol> + +<li><a href="#Glossary">Glossary</a> - A glossary of data-types used in the APIs +<ol type=A> + <li><a href="#Glossary-Basic">Basic Types</a> + <li><a href="#Glossary-Complex">Complex Types</a> + <li><a href="#Glossary-DiskIO">Disk I/O Types</a> +</ol> + +</ol> + +<hr> +<h2><a name="Library">Library API Functions</a></h2> +<P>These functions are designed to provide access to HDF5 application/library +behavior. They are used to get information about or change global library +parameters. +<br> +<br> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Library-DontAtExit">H5dont_atexit</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5dont_atexit</code>(<em>void</em>) +<dt><strong>Description:</strong> + <dd>This routine indicates to the library that an 'atexit()' cleanup routine + should not be installed. The major (only?) purpose for this is in + situations where the library is dynamically linked into an application and + is un-linked from the application before 'exit()' gets callled. In those + situations, a routine installed with 'atexit()' would jump to a routine + which was no longer in memory, causing errors. + In order to be effective, this routine <em>must</em> be called before any other + HDF function calls, and must be called each time the library is loaded/ + linked into the application. (the first time and after it's been un-loaded) +<dt><strong>Parameters:</strong> <em>none</em> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Library-Close">H5close</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5close</code>(<em>void</em>) +<dt><strong>Description:</strong> + <dd>This routines flushes all data to disk, closes all file handles and + cleans up all memory used by the library. Generally it is installed + to be called when the application calls <em>exit</em>, but may be + called earlier in event of an emergency shutdown or out of desire + to free all resources used by the HDF5 library. +<dt><strong>Parameters:</strong> none +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Library-Version">H5version</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5version</code>(<em>uintn *</em><code>majversion</code>, + <em>uintn *</em><code>minversion</code>, + <em>uintn *</em><code>relversion</code>, + <em>uintn *</em><code>patversion</code> + ) +<dt><strong>Description:</strong> + <dd>This routine retrieves the major, minor, release and patch versions + of the library which is linked to the application. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>uintn *</em><code>majversion</code> + <dd>The major version of the library. + <dt><em>uintn *</em><code>minversion</code> + <dd>The minor version of the library. + <dt><em>uintn *</em><code>relversion</code> + <dd>The release number of the library. + <dt><em>uintn *</em><code>patversion</code> + <dd>The patch number of the library. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<h2><a name="File">File API Functions</a></h2> +<P>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. +<br> +<br> + +<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> +<h2><a name="Template">Template API Functions</a></h2> +<P>These functions manipulate template objects to allow objects which require +many different parameters to be easily manipulated. +<br> +<br> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-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>Description:</strong> + <dd>This function returns a template ID for a copy of the default + template of a given type. + <br> + <dl> + <dt>Template Types and Uses: + <ul><dl> + <dt>H5P_FILE_CREATE + <dd>Used to set the metadata information about a file during + file creation. + <dt>H5P_FILE_ACCESS + <dd>Used to set I/O access information about a file. + <dt>H5P_DATASET_CREATE + <dd>Used to set information about a dataset when it is + created. + <dt>H5P_DATASET_XFER + <dd>Used to set access information about a memory to dataset + transfer. + </dl></ul> + </dl> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5P_class_t</em> <code>type</code> + <dd>The type of template to create. + </dl> +<dt><strong>Returns:</strong> + <dd>Valid ID on success, negative on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-Close">H5Pclose</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pclose</code>(<em>hid_t</em> <code>template_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function terminates access to a template. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>template_id</code> + <dd>Template ID to terminate access to. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-GetClass">H5Pget_class</a> +<dt><strong>Signature:</strong> + <dd><em>H5P_class_t </em><code>H5Pget_class</code>(<em>hid_t</em> <code>template_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function queries the class of a template ID. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>template_id</code> + <dd>Template ID to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Template class code on success, negative on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-Copy">H5Pcopy</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Pcopy</code>(<em>hid_t</em> <code>template_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function makes a copy of a template ID. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>template_id</code> + <dd>Template ID to duplicate. + </dl> +<dt><strong>Returns:</strong> + <dd>Template ID on success, negative on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-GetVersion">H5Pget_version</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pget_version</code>(<em>hid_t</em> <code>template_id</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>Description:</strong> + <dd>This function queries the version information of various objects + for a file creation template. Any pointer parameters which are + passed as NULL are not queried. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>template_id</code> + <dd>Template ID to query. + <dt><em>int *</em> <code>boot</code> + <dd>Pointer to location to return boot block version number. + <dt><em>int *</em> <code>freelist</code> + <dd>Pointer to location to return global freelist version number. + <dt><em>int *</em> <code>stab</code> + <dd>Pointer to location to return symbol table version number. + <dt><em>int *</em> <code>shhdr</code> + <dd>Pointer to location to return shared object header version number. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-SetUserblock">H5Pset_userblock</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pset_userblock</code>(<em>hid_t</em> <code>template_id</code>, + <em>hsize_t</em> <code>size</code> + ) +<dt><strong>Description:</strong> + <dd>This function sets the size of the user-block located at the + beginning of an HDF5 file. This function is only valid for + file creation templates. The default user-block size is 0. + Only values which are powers of 2 larger equal to 512 or larger + may be used as a valid user-block size. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>template_id</code> + <dd>Template to modify. + <dt><em>hsize_t</em> <code>size</code> + <dd>Size of the user-block in bytes. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-GetUserblock">H5Pget_userblock</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pget_userblock</code>(<em>hid_t</em> <code>template_id</code>, + <em>hsize_t *</em> <code>size</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the size of the user-block located at the + beginning of an HDF5 file. This function is only valid for + file creation templates. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>template_id</code> + <dd>Template ID to query. + <dt><em>hsize_t *</em> <code>size</code> + <dd>Pointer to location to return user-block size. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-SetSizes">H5Pset_sizes</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pset_sizes</code>(<em>hid_t</em> <code>template_id</code>, + <em>size_t</em> <code>sizeof_addr</code>, + <em>size_t</em> <code>sizeof_size</code> + ) +<dt><strong>Description:</strong> + <dd>This function 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 templates. 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>template_id</code> + <dd>Template to modify. + <dt><em>size_t</em> <code>sizeof_addr</code> + <dd>Size of an object offset in bytes. + <dt><em>size_t</em> <code>sizeof_size</code> + <dd>Size of an object length in bytes. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-GetSizes">H5Pget_sizes</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pget_sizes</code>(<em>hid_t</em> <code>template_id</code>, + <em>size_t *</em> <code>sizeof_addr</code>, + <em>size_t *</em> <code>sizeof_size</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the size of the offsets and lengths used + in an HDF5 file. This function is only valid for file creation + templates. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>template_id</code> + <dd>Template ID to query. + <dt><em>size_t *</em> <code>size</code> + <dd>Pointer to location to return offset size in bytes. + <dt><em>size_t *</em> <code>size</code> + <dd>Pointer to location to return length size in bytes. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-SetMPI">H5Pset_mpi</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pset_mpi</code>(<em>hid_t</em> <code>tid</code>, + <em>MPI_Comm</em> <code>comm</code>, + <em>MPI_Info</em> <code>info</code> + ) +<dt><strong>Description:</strong> + <dd>Store the access mode for parallel I/O call and the user supplied + communicator and info in the access template which can then + be used to open file. This function is available only in the + parallel HDF5 library. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tid</code> + <dd>ID of template to modify + <dt><em>MPI_Comm</em> <code>comm</code> + <dd> + MPI communicator to be used for file open as defined in + MPI_FILE_OPEN of MPI-2. This function does not make a + duplicated communicator. Any modification to comm after + this function call returns may have undetermined effect + to the access template. Users should call this function + again to setup the template. + <dt><em>MPI_Info</em> <code>info</code> + <dd> + 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 info. Any modification to info after + this function call returns may have undetermined effect + to the access template. Users should call this function + again to setup the template. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-GetMPI">H5Pget_mpi</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pget_mpi</code>(<em>hid_t</em> <code>tid</code>, + <em>MPI_Comm</em> <code>*comm</code>, + <em>MPI_Info</em> <code>*info</code> + ) +<dt><strong>Description:</strong> + <dd>Retrieves the communicator and info object + that have been set by H5Pset_mpi. + This function is available only in the parallel HDF5 library. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tid</code> + <dd>ID of a file access property list that has been set + successfully by H5Pset_mpi. + <dt><em>MPI_Comm *</em> <code>comm</code> + <dd>Pointer to location to return the communicator. + <dt><em>MPI_Info *</em> <code>info</code> + <dd>Pointer to location to return the info object. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-SetXfer">H5Pset_xfer</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pset_xfer</code>(<em>hid_t</em> <code>tid</code>, + <em>H5D_transfer_t</em> <code>data_xfer_mode</code> + ) +<dt><strong>Description:</strong> + <dd>Set 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. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tid</code> + <dd>ID of a dataset transfer property list + <dt><em>H5D_transfer_t</em> <code>data_xfer_mode</code> + <dd>Data transfer modes: + <ul><dl> + <dt>H5D_XFER_INDEPENDENT + <dd>Use independent I/O access. + <dt>H5D_XFER_COLLECTIVE + <dd>Use MPI collective I/O access. + </dl></ul> + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-GetXfer">H5Pget_xfer</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pget_xfer</code>(<em>hid_t</em> <code>tid</code>, + <em>H5D_transfer_t *</em> <code>data_xfer_mode</code> + ) +<dt><strong>Description:</strong> + <dd>Retrieves the transfer mode from the dataset + transfer property list. + This function is available only in the parallel HDF5 library. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tid</code> + <dd>ID of a dataset transfer property list. + <dt><em>H5D_transfer_t *</em> <code>data_xfer_mode</code> + <dd>Pointer to location to return the data_xfer_mode. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-SetSymK">H5Pset_sym_k</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pset_sym_k</code>(<em>hid_t</em> <code>template_id</code>, + <em>size_t</em> <code>ik</code>, + <em>size_t</em> <code>lk</code> + ) +<dt><strong>Description:</strong> + <dd>This function sets the size of parameters used to control the + symbol table nodes. This function is only valid for + file creation templates. Passing in a value of 0 for one of the + parameters retains the current value. + <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>. + <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>template_id</code> + <dd>Template ID to query. + <dt><em>size_t</em> <code>ik</code> + <dd>Symbol table tree rank. + <dt><em>size_t</em> <code>lk</code> + <dd>Symbol table node size. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-GetSymK">H5Pget_sym_k</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pget_sym_k</code>(<em>hid_t</em> <code>template_id</code>, + <em>size_t *</em> <code>ik</code>, + <em>size_t *</em> <code>lk</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the size of the symbol table's B-tree + 1/2 rank and the symbol table's leaf node 1/2 size. See + information for <a href="#Template-SetSymK">H5Pset_sym_k</a> for + more information. This function is only valid for file creation + templates. If a parameter valued is set to NULL, that parameter is + not retrieved. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>template_id</code> + <dd>Template ID to query. + <dt><em>size_t *</em> <code>ik</code> + <dd>Pointer to location to return the symbol table's B-tree 1/2 rank. + <dt><em>size_t *</em> <code>size</code> + <dd>Pointer to location to return the symbol table's leaf node 1/2 size. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-SetIstoreK">H5Pset_istore_k</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pset_istore_k</code>(<em>hid_t</em> <code>template_id</code>, + <em>size_t</em> <code>ik</code> + ) +<dt><strong>Description:</strong> + <dd>This function sets the size of the parameter used to control the + B-trees for indexing chunked datasets. This function is only valid for + file creation templates. Passing in a value of 0 for one of the + parameters retains the current value. + <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>template_id</code> + <dd>Template ID to query. + <dt><em>size_t</em> <code>ik</code> + <dd>1/2 rank of chunked storage B-tree. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-GetIstoreK">H5Pget_istore_k</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pget_istore_k</code>(<em>hid_t</em> <code>template_id</code>, + <em>size_t *</em> <code>ik</code> + ) +<dt><strong>Description:</strong> + <dd>Queries the 1/2 rank of an indexed storage B-tree. See + <a href="#Template-SetIstoreK">H5Pset_istore_k</a> for details. + The argument <code>ik</code> may be the null pointer. This + function is only valid for file creation templates. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>template_id</code> + <dd>Template ID to query. + <dt><em>size_t *</em> <code>ik</code> + <dd>Pointer to location to return the chunked storage B-tree 1/2 rank. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-SetLayout">H5Pset_layout</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pset_layout</code>(<em>hid_t</em> <code>template_id</code>, + <em>H5D_layout_t</em> <code>layout</code> + ) +<dt><strong>Description:</strong> + <dd>This function sets the type of storage used store the raw data for + a dataset. This function is only valid for dataset creation templates. + Valid parameter 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>template_id</code> + <dd>Template ID to query. + <dt><em>H5D_layout_t</em> <code>layout</code> + <dd>Type of storage layout for raw data. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-GetLayout">H5Pget_layout</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pget_layout</code>(<em>hid_t</em> <code>template_id</code>, + <em>H5D_layout_t *</em> <code>layout</code> + ) +<dt><strong>Description:</strong> + <dd>Queries the layout of the raw data for a dataset. + This function is only valid for dataset creation templates. + 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>template_id</code> + <dd>Template ID to query. + <dt><em>H5D_layout_t *</em> <code>layout</code> + <dd>Pointer to location to return the storage layout. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-SetChunk">H5Pset_chunk</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pset_chunk</code>(<em>hid_t</em> <code>template_id</code>, + <em>int</em> <code>ndims</code>, + <em>const hsize_t *</em> <code>dim</code> + ) +<dt><strong>Description:</strong> + <dd>This function sets the size of the chunks used to store a chunked + layout dataset. This function is only valid for dataset creation + templates. 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>template_id</code> + <dd>Template ID to query. + <dt><em>int</em> <code>ndims</code> + <dd>The number of dimensions of each chunk. + <dt><em>const hsize_t *</em> <code>dim</code> + <dd>An array containing the size of each chunk. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Template-GetChunk">H5Pget_chunk</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Pget_chunk</code>(<em>hid_t</em> <code>template_id</code>, + <em>int</em> <code>max_ndims</code> + <em>hsize_t *</em> <code>dims</code> + ) +<dt><strong>Description:</strong> + <dd>Queries the size of chunks for the raw data of a chunked layout + dataset. This function is only valid for dataset creation + templates. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>template_id</code> + <dd>Template ID to query. + <dt><em>int</em> <code>max_ndims</code> + <dd>Size of the <code>dims</code> array. + <dt><em>hsize_t *</em> <code>dims</code> + <dd>Array to store the chunk dimensions. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<!-- +<hr> +<h2><a name="Error">Error API Functions</a></h2> +<P>These functions allow flexible error reporting for the HDF5 library. +<br> +<br> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Error-SetPush">H5Eset_push</a> +<dt><strong>Signature:</strong> + <dd><em>H5E_push_func_t </em><code>H5Eset_push</code>(<em>H5E_push_func_t</em> <code>func</code> + ) +<dt><strong>Description:</strong> + <dd>This function sets a function to call when an error is detected in + the library. The prototype of the H5E_push_func_t is: <br> +void H5E_push_func_t(int32 errid, hdf_maj_err_code_t maj, hdf_min_err_code_t min, const char *function_name, const char *file_name, intn line); +<dt><strong>Parameters:</strong> + <dl> + <dt><em>H5E_push_func_t</em><code>func</code> + <dd>Pointer to the error reporting function. + </dl> +<dt><strong>Returns:</strong> + <dd>The pointer to the previous error repoting function on succes, NULL on failure +</dl> +--> + +<!-- +<hr> +<h2><a name="Relationships">Relationships API Functions</a></h2> +<P>These functions provide methods of creating links between logically +related objects in a file. +<br> +<br> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Relationships-GetNumRelations">H5Rget_num_relations</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Rget_num_relations</code>(<em>hid_t </em><code>obj_id</code>, + <em>int32 *</em><code>num_attached</code>, + <em>int32 *</em><code>num_memberof</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the number of relationships attached to the + object and the number of other objects that the object is a member of + itself. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>obj_id</code> + <dd>ID of the object to query the number of attached relations + <dt><em>int32 *</em> <code>num_attached</code> + <dd>Number of objects attached to the object + <dt><em>int32 *</em> <code>num_memberof</code> + <dd>Number of objects that the object is a member of + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Relationships-GetMemberOfOIDs">H5Rget_memberof_oids</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Rget_memberof_oids</code>(<em>hid_t </em><code>obj_id</code>, + <em>hoid_t </em><code>memberof_list[]</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the OIDs of the objects that the object is a + member of. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>obj_id</code> + <dd>ID of the object to get the members of list + <dt><em>hoid_t *</em> <code>memberof_list</code> + <dd>A list of the OIDs for objects which the object is attached to. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Relationships-GetAttachedOIDs">H5Rget_attached_oids</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Rget_attached_oids</code>(<em>hid_t </em><code>obj_id</code>, + <em>hoid_t </em><code>attached_list[]</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the OIDs of the objects that are attached to + the object. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>obj_id</code> + <dd>ID of the object to get the attached OIDs from + <dt><em>hoid_t *</em> <code>attached_list</code> + <dd>A list of the OIDs for objects which are attached to the + object + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Relationships-Attach">H5Rattach_oid</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Rattach_oid</code>(<em>hid_t </em><code>obj_id</code>, + <em>hoid_t </em><code>attach</code> + ) +<dt><strong>Description:</strong> + <dd>This function attaches an OID to the object. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>obj_id</code> + <dd>ID of the object to attach an OID to + <dt><em>hoid_t </em> <code>attach</code> + <dd>The OID to attach to the object + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> +--> + +<hr> +<h2><a name="Dataset">Dataset Object API Functions</a></h2> +<P>These functions create and manipulate dataset objects. Each dataset must +be constructed from a datatype and a dataspace. +<br> +<br> + +<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>file_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>template_id</code> + ) +<dt><strong>Description:</strong> + <dd>This function creates a new dataset in the file specified with the + <code>file_id</code>. The <code>type_id</code> and <code>space_id</code> + are the IDs of the datatype and dataspace used to construct the + framework of the dataset. The datatype and dataspace parameters + describe the dataset as it will exist in the file, which is not + necessarily the same as it exists in memory. The <code>template_id</code> + contains either the default template (H5P_DEFAULT) or a template_id + with particular constant properties used to create the dataset. The + <code>name</code> is used to identify the dataset in a group and must + be unique within that group. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>file_id</code> + <dd>ID of the file 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>ID of the datatype to use when creating the dataset. + <dt><em>hid_t</em> <code>space_id</code> + <dd>ID of the dataspace to use when creating the dataset. + <dt><em>hid_t</em> <code>template_id</code> + <dd>ID of the dataset creation template. + </dl> +<dt><strong>Returns:</strong> + <dd>Dataset ID on success, negative on failure. +</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>file_id</code>, + <em>const char *</em><code>name</code> + ) +<dt><strong>Description:</strong> + <dd>This function opens an existing dataset for access in the file + specified with the <code>file_id</code>. The <code>name</code> is + used to identify the dataset in the file. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>file_id</code> + <dd>ID 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>Dataset ID on success, negative on failure. +</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>Description:</strong> + <dd>This function returns a copy of the dataspace for a dataset. The + dataspace should be released with the H5Sclose() function. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>dataset_id</code> + <dd>ID of the dataset to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Dataspace ID on success, negative on failure. +</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>Description:</strong> + <dd>This function returns a copy of the datatype for a dataset. The + dataspace should be released with the H5Tclose() function. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>dataset_id</code> + <dd>ID of the dataset to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Datatype ID on success, negative on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Dataset-GetCreateParms">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>Description:</strong> + <dd>This function returns a copy of the dataset creation template for a + dataset. The template should be released with the H5Pclose() function. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>dataset_id</code> + <dd>ID of the dataset to query. + </dl> +<dt><strong>Returns:</strong> + <dd>Dataset creation template ID on success, negative on failure. +</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>transfer_template_id</code>, + <em>void *</em> <code>buf</code> + ) +<dt><strong>Description:</strong> + <dd>This function reads raw data from the specified dataset into <code>buf</code>, + converting from the file datatype of the dataset into the memory + datatype specified in <code>mem_type_id</code>. The portion of the + dataset to read from disk is specified with the <code>file_spaceid</code> + which can contain a dataspace with a hyperslab selected or the constant + H5S_ALL, which indicates the entire dataset is to be read. The portion + of the dataset read into the memory buffer is specified with the + <code>mem_space_id</code> which can also be a hyperslab of the same + size or the H5S_ALL parameter to store the entire dataset. The + <code>transfer_template_id</code> is a dataset transfer template ID which + is used to provide addition parameters for the I/O operation or can + be H5P_DEFAULT for the default library behavior. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>dataset_id</code> + <dd>ID of the dataset read from. + <dt><em>hid_t</em> <code>mem_type_id</code> + <dd>ID of the memory datatype. + <dt><em>hid_t</em> <code>mem_space_id</code> + <dd>ID of the memory dataspace. + <dt><em>hid_t</em> <code>file_space_id</code> + <dd>ID of the dataset's dataspace in the file. + <dt><em>hid_t</em> <code>transfer_template_id</code> + <dd>ID of a transfer template for this I/O operation. + <dt><em>void *</em> <code>buf</code> + <dd>Buffer to store information read from the file. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</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>transfer_template_id</code>, + <em>const void *</em> <code>buf</code> + ) +<dt><strong>Description:</strong> + <dd>This function writes raw data from memory into the specified dataset + converting from the memory datatype of the dataset specified in + <code>mem_type_id</code> into the file datatype. + The portion of the + dataset to written to disk is specified with the <code>file_spaceid</code> + which can contain a dataspace with a hyperslab selected or the constant + H5S_ALL, which indicates the entire dataset is to be written. The portion + of the dataset written from the memory buffer is specified with the + <code>mem_space_id</code> which can also be a hyperslab of the same + size or the H5S_ALL parameter to store the entire dataset. The + <code>transfer_template_id</code> is a dataset transfer template ID which + is used to provide addition parameters for the I/O operation or can + be H5P_DEFAULT for the default library behavior. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>dataset_id</code> + <dd>ID of the dataset read from. + <dt><em>hid_t</em> <code>mem_type_id</code> + <dd>ID of the memory datatype. + <dt><em>hid_t</em> <code>mem_space_id</code> + <dd>ID of the memory dataspace. + <dt><em>hid_t</em> <code>file_space_id</code> + <dd>ID of the dataset's dataspace in the file. + <dt><em>hid_t</em> <code>transfer_template_id</code> + <dd>ID of a transfer template for this I/O operation. + <dt><em>const void *</em> <code>buf</code> + <dd>Buffer to store information to be written to the file. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</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>Description:</strong> + <dd>This function increases the size of the dataspace of a dataset with + unlimited dimensions. It cannot be used to extend the size of a + dataspace's fixed dimensions. The <code>size</code> array must have + the same number of entries as the rank of the dataset's dataspace. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>dataset_id</code> + <dd>ID of the dataset read from. + <dt><em>const hsize_t *</em> <code>size</code> + <dd>Array containing the new magnitude of each dimension. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</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>Description:</strong> + <dd>This function ends access to a dataset and releases resources used by + it. Further use of the dataset ID is illegal in calls to the dataset + API. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>dataset_id</code> + <dd>ID of the dataset to finish access to. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<h2><a name="Datatype">Datatype Object API Functions</a></h2> +<P>These functions create and manipulate the datatype which describes elements +of a dataset. +<br> +<br> + +<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> +<h2><a name="Dataspace">Dataspace Object API Functions</a></h2> +<P>These functions create and manipulate the dataspace in which to store the +elements of a dataset. +<br> +<br> + +<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> +<h2><a name="Group">Group Object API Functions</a></h2> + +<p>A group associates names with objects and provides a mechanism +which can map 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 handle 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 root +object is the current working group if the stack is empty). The stack +can be manipulated with <code>H5Gset</code>, <code>H5Gpush</code>, and +<code>H5Gpop</code>. + +<p>An object name consists of one or more components separated from +one another by slashes. If the name begins with a slash then the +object is located by looking for the first component in the root +object, then looking for the second component in that object, etc., +until the entire name is traversed. If the name doesn't begin with a +slash then 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 doesn't 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 and then a <code>getcwd</code> +function would be trivial. + +<br> +<br> + +<hr> + <dl> + <dt><strong>Name:</strong> <a name="Group-Create">H5Gcreate</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Gset</code> (<em>hid_t</em> + <code>file</code>, <em>const char *</em><code>name</code>, + <em>size_t</em> <code>size_hint</code>) + <dt><strong>Description:</strong> + <dd>This function creates a new empty group and gives it a name. + <dt><strong>Parameters:</strong> + <dd> + <dl> + <dt><em>hid_t</em> <code>file</code> + <dd>The file handle returned by <code>H5Fcreate</code> or + <code>H5Fopen</code>. + <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>The size hint is an optional parameter that indicates + 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 while 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 negative value on failure, non-negative otherwise. + </dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Group-Open">H5Sopen</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Gopen</code>(<em>hid_t</em> <code>file_id</code>, + <em>const char *</em><code>name</code> + ) +<dt><strong>Description:</strong> + <dd>This function opens an existing group for modification. When finished, + call H5Gclose() to close it and release resources. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>file_id</code> + <dd>ID of file to open group within. + <dt><em>const char *</em> <code>name</code> + <dd>Name of group to open. + </dl> +<dt><strong>Returns:</strong> + <dd>Valid group ID on success, negative on failure. +</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>file</code>, <em>const char *</em><code>name</code>) + <dt><strong>Description:</strong> + <dd>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. + <dt><strong>Parameters:</strong> + <dd> + <dl> + <dt><em>hid_t</em> <code>file</code> + <dd>The file handle returned by <code>H5Fcreate</code> or + <code>H5Fopen</code>. + <dt><em>const char *</em><code>name</code> + <dd>The name of the new current working group. If the name + doesn't begin with a slash then it is looked up relative the + the previous current working group. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a negative value on failure, non-negative otherwise. + </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>file</code>, <em>const char *</em><code>name</code>) + <dt><strong>Description:</strong> + <dd>This function sets the current working group by pushing a + new element onto the current working group stack. + <dt><strong>Parameters:</strong> + <dd> + <dl> + <dt><em>hid_t</em> <code>file</code> + <dd>The file handle returned by <code>H5Fcreate</code> or + <code>H5Fopen</code>. + <dt><em>const char *</em><code>name</code> + <dd>The name of the new current working group. If the name + doesn't begin with a slash then it is looked up relative the + the previous current working group. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a negative value on failure, non-negative otherwise. + </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>file</code>) + <dt><strong>Description:</strong> + <dd>This function 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. + <dt><strong>Parameters:</strong> + <dd> + <dl> + <dt><em>hid_t</em> <code>file</code> + <dd>The file handle returned by <code>H5Fcreate</code> or + <code>H5Fopen</code>. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a negative value on failure, non-negative otherwise. + </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>Description:</strong> + <dd>This function releases a group. Further access through the group + ID is illegal. 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>ID of group to release. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<!-- +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Group-GetNumContents">H5Gget_num_contents</a> +<dt><strong>Signature:</strong> + <dd><em>uint32 </em><code>H5Gget_num_contents</code>(<em>hid_t </em><code>grp_id</code>) +<dt><strong>Description:</strong> + <dd>This function retrieves the number of objects in the contents of the + group. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>grp_id</code> + <dd>ID of the group object to query + </dl> +<dt><strong>Returns:</strong> + <dd>Number of objects in group's contents on success, Unegative on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Group-GetContentInfo">H5Gget_content_info</a> +<dt><strong>Signature:</strong> + <dd><em>uint32 </em><code>H5Gget_content_info</code>(<em>hid_t </em><code>grp_id</code>, + <em>int32 </em><code>index</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the type (dataset, dimension, datatype or + group) of an item in a group. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>grp_id</code> + <dd>ID of the group object to query + <dt><em>uint32</em> <code>index</code> + <dd>Item index in the group to query the type of + </dl> +<dt><strong>Returns:</strong> + <dd>The type of the object for an item on success, or Unegative on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Group-GetContentInfoMult">H5Gget_content_info_mult</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Gget_content_info</code>(<em>hid_t </em><code>grp_id</code>, + <em>int32 </em><code>start_index</code>, + <em>int32 </em><code>num_items</code>, + <em>int32 </em><code>itemtype_list[]</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the type (dataset, dimension, datatype or + group) of a list of items in a group. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>grp_id</code> + <dd>ID of the group object to query + <dt><em>uint32</em> <code>start_index</code> + <dd>The starting index to query the types of items + <dt><em>uint32</em> <code>num_items</code> + <dd>The number of items to query the types of + <dt><em>uint32</em> <code>itemtype_list[]</code> + <dd>A list to store the types of the items in + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Group-GetOIDByName">H5Gget_oid_by_name</a> +<dt><strong>Signature:</strong> + <dd><em>hoid_t </em><code>H5Gget_oid_by_name</code>(<em>hid_t </em><code>grp_id</code>, + <em>char *</em><code>name</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the OID of an item in the group which matches + the name supplied. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>grp_id</code> + <dd>ID of the group object to query + <dt><em>char *</em> <code>name</code> + <dd>The name of the item to find + </dl> +<dt><strong>Returns:</strong> + <dd>A valid OID on success, or negative on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Group-GetOIDByIndex">H5Gget_oid_by_index</a> +<dt><strong>Signature:</strong> + <dd><em>hoid_t </em><code>H5Gget_oid_by_index</code>(<em>hid_t </em><code>grp_id</code>, + <em>uint32</em><code>index</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the OID of the n'th item in a group. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>grp_id</code> + <dd>ID of the group object to query + <dt><em>uint32</em> <code>index</code> + <dd>The index of the item in the group + </dl> +<dt><strong>Returns:</strong> + <dd>A valid OID on success, or negative on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Group-GetNameByOID">H5Gget_name_by_oid</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Gget_name_by_oid</code>(<em>hid_t </em><code>grp_id</code>, + <em>hoid_t</em><code>oid</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the name of the item in a group whose OID + matches the one supplied. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>grp_id</code> + <dd>ID of the group object to query + <dt><em>hoid_t</em> <code>oid</code> + <dd>The OID of the item in the group + </dl> +<dt><strong>Returns:</strong> + <dd>An atom for the string on success, NULL on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Group-GetNameByIndex">H5Gget_name_by_index</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Gget_name_by_index</code>(<em>hid_t </em><code>grp_id</code>, + <em>uint32</em><code>index</code> + ) +<dt><strong>Description:</strong> + <dd>This function retrieves the name of the n'th item in a group +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>grp_id</code> + <dd>ID of the group object to query + <dt><em>uint32</em> <code>index</code> + <dd>The index of the item in the group + </dl> +<dt><strong>Returns:</strong> + <dd>An atom for the string on success, NULL on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Group-InsertItem">H5Ginsert_item</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Ginsert_item</code>(<em>hid_t </em><code>grp_id</code>, + <em>hoid_t</em><code>item</code> + ) +<dt><strong>Description:</strong> + <dd>This function inserts the item into a group +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>grp_id</code> + <dd>ID of the group object to change + <dt><em>hoid_t</em> <code>item</code> + <dd>The OID of the item to insert into the group + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Group-InsertItemMult">H5Ginsert_item_mult</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Ginsert_item_mult</code>(<em>hid_t </em><code>grp_id</code>, + <em>uint32</em><code>num_items</code> + <em>hoid_t</em><code>item_list[]</code> + ) +<dt><strong>Description:</strong> + <dd>This function inserts multiple items into a group +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>grp_id</code> + <dd>ID of the group object to change + <dt><em>hoid_t</em> <code>num_items</code> + <dd>The number of items to insert into the group + <dt><em>hoid_t</em> <code>item_list[]</code> + <dd>The OIDs of the items to insert + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Group-RemoveItem">H5Gremove_item</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Gremove_item</code>(<em>hid_t </em><code>grp_id</code>, + <em>hoid_t</em><code>item</code> + ) +<dt><strong>Description:</strong> + <dd>This function removes an item from a group +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>grp_id</code> + <dd>ID of the group object to change + <dt><em>hoid_t</em> <code>item_list[]</code> + <dd>The OID of the items to remove + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Group-RemoveItemMult">H5Gremove_item_mult</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Gremove_item_mult</code>(<em>hid_t </em><code>grp_id</code>, + <em>uint32</em><code>num_items</code> + <em>hoid_t</em><code>item_list[]</code> + ) +<dt><strong>Description:</strong> + <dd>This function removes multiple items from a group +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>grp_id</code> + <dd>ID of the group object to change + <dt><em>hoid_t</em> <code>num_items</code> + <dd>The number of items to remove from the group + <dt><em>hoid_t</em> <code>item_list[]</code> + <dd>The OIDs of the items to remove + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> +--> + +<!-- +<hr> +<h2><a name="LinkList">Linked-List Object API Functions</a></h2> +<P>These functions manage in-memory linked lists in various useful ways. +<br> +<br> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-AddToBeginning">H5Ladd_to_beginning</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Ladd_to_beginning</code>(<em>hid_t </em><code>lst_id</code>, + <em>VOIDP</em><code>item</code> + ) +<dt><strong>Description:</strong> + <dd>This function adds an object to the beginning of a linked list +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + <dt><em>VOIDP</em> <code>item</code> + <dd>A pointer to the object to add to the list. This must not + be NULL. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-AddToEnd">H5Ladd_to_end</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Ladd_to_end</code>(<em>hid_t </em><code>lst_id</code>, + <em>VOIDP</em><code>item</code> + ) +<dt><strong>Description:</strong> + <dd>This function adds an object to the end of a linked list +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + <dt><em>VOIDP</em> <code>item</code> + <dd>A pointer to the object to add to the list. This must not + be NULL. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-RemoveFromBeginning">H5Lremove_from_beginning</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Lremove_from_beginning</code>(<em>hid_t </em><code>lst_id</code>) +<dt><strong>Description:</strong> + <dd>This function removes an object from the front of a linked list and + returns it. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-RemoveFromEnd">H5Lremove_from_end</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Lremove_from_end</code>(<em>hid_t </em><code>lst_id</code>) +<dt><strong>Description:</strong> + <dd>This function removes an object from the back of a linked list and + returns it. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-RemoveCurrent">H5Lremove_current</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Lremove_current</code>(<em>hid_t </em><code>lst_id</code>) +<dt><strong>Description:</strong> + <dd>This function removes the current object from the list and returns + a pointer to it. The list's current object is moved back to the + previous item in the list, or set to NULL if the object removed is at + the beginning of the list. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-DeleteAll">H5Ldelete_all</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Ldelete_all</code>(<em>hid_t </em><code>lst_id</code>, + <em>void</em><code>(*free_func)(VOIDP)</code> + ) +<dt><strong>Description:</strong> + <dd>This function removes all the objects from a list. If + <code>free_func</code> is not NULL, each object removed from the list + is passed to <code>free_func</code> before being removed from the list. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + <dt><em>void</em> <code>(*free_func)(VOIDP)</code> + <dd>Pointer to the function to call for each item removed from + the list. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-Index">H5Lindex</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Lindex</code>(<em>hid_t </em><code>lst_id</code>, + <em>uintn</em><code>indx</code> + ) +<dt><strong>Description:</strong> + <dd>This function finds the n'th object in a list and returns it. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + <dt><em>uintn</em> <code>indx</code> + <dd>Index of the object to return. + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-PeekAtBeginning">H5Lpeek_at_beginning</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Lpeek_at_beginning</code>(<em>hid_t </em><code>lst_id</code>) +<dt><strong>Description:</strong> + <dd>This function returns a pointer to the first object in the list. If + the list is empty, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-PeekAtEnd">H5Lpeek_at_end</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Lpeek_at_end</code>(<em>hid_t </em><code>lst_id</code>) +<dt><strong>Description:</strong> + <dd>This function returns a pointer to the last object in the list. If + the list is empty, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-FirstInList">H5Lfirst_in_list</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Lfirst_in_list</code>(<em>hid_t </em><code>lst_id</code>) +<dt><strong>Description:</strong> + <dd>This function returns a pointer to the first object in the list, and + marks it as the current object. If the list is empty, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-LastInList">H5Llast_in_list</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Llast_in_list</code>(<em>hid_t </em><code>lst_id</code>) +<dt><strong>Description:</strong> + <dd>This function returns a pointer to the last object in the list, and + marks it as the current object. If the list is empty, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-CurrentInList">H5Lcurrent_in_list</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Lcurrent_in_list</code>(<em>hid_t </em><code>lst_id</code>) +<dt><strong>Description:</strong> + <dd>This function returns a pointer to the object that is considered the + "current object" in the list. + If the current object has been removed, or current points before or + after the list or the list is empty, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-NextInList">H5Lnext_in_list</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Lnext_in_list</code>(<em>hid_t </em><code>lst_id</code>) +<dt><strong>Description:</strong> + <dd>This function returns a pointer to the next object in the list and marks + it as the current object. + If the end of the list has been reached or the list is empty, NULL is + returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-PreviousInList">H5Lprevious_in_list</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Lprevious_in_list</code>(<em>hid_t </em><code>lst_id</code>) +<dt><strong>Description:</strong> + <dd>This function returns a pointer to the previous object in the list and + marks it as the current object. + If the beginning of the list has been reached or the list is empty, NULL + is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-ResetToBeginning">H5Lreset_to_beginning</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Lreset_to_beginning</code>(<em>hid_t </em><code>lst_id</code>) +<dt><strong>Description:</strong> + <dd>This function resets the "current object" to the beginning of the list. + Therefore the next object in the list is the first object. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-ResetToEnd">H5Lreset_to_end</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Lreset_to_end</code>(<em>hid_t </em><code>lst_id</code>) +<dt><strong>Description:</strong> + <dd>This function resets the "current object" to the end of the list. + Therefore the previous object in the list is the last object. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-NumOfObjects">H5Lnum_of_objects</a> +<dt><strong>Signature:</strong> + <dd><em>uintn </em><code>H5Lnum_of_objects</code>(<em>hid_t </em><code>lst_id</code>) +<dt><strong>Description:</strong> + <dd>This function returns the number of objects in the list. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + </dl> +<dt><strong>Returns:</strong> + <dd>The number of nodes in the list (possibly zero) on success or UFAIL on + failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-IsEmpty">H5Lis_empty</a> +<dt><strong>Signature:</strong> + <dd><em>hbool_t </em><code>H5Lis_empty</code>(<em>hid_t </em><code>lst_id</code>) +<dt><strong>Description:</strong> + <dd>This function determines if the list is empty. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + </dl> +<dt><strong>Returns:</strong> + <dd>TRUE if the list is empty, FALSE if the list has objects, negative on + failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-IsInList">H5Lis_in_list</a> +<dt><strong>Signature:</strong> + <dd><em>hbool_t </em><code>H5Lis_in_list</code>(<em>hid_t </em><code>lst_id</code>, + <em>VOIDP</em><code>search_ptr</code> + ) +<dt><strong>Description:</strong> + <dd>This function determines if an object is in the list. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + <dt><em>VOIDP</em> <code>search_ptr</code> + <dd>Pointer to look for in list + </dl> +<dt><strong>Returns:</strong> + <dd>TRUE if the list contains the pointer, FALSE if the list has does not, + negative on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-CopyList">H5Lcopy_list</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Lcopy_list</code>(<em>hid_t </em><code>lst_id</code>) +<dt><strong>Description:</strong> + <dd>This function makes a copy of the list. The objects themselves are not + copied, only new references to them are made. The new list has no + current object set. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + </dl> +<dt><strong>Returns:</strong> + <dd>A valid list atom on success, negative on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-PerformOnList">H5Lperform_on_list</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Lperform_on_list</code>(<em>hid_t </em><code>lst_id</code>, + <em>void</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, + <em>VOIDP</em><code>args</code>, + ) +<dt><strong>Description:</strong> + <dd>This function performs the specified function on each object in the + list. Any options arguments required can be passed through the "args" + pointer. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + <dt><em>void</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> + <dd>Pointer to the function to operate on the objects + <dt><em>VOIDP</em> <code>args</code> + <dd>Pointer any additional arguments needed by the function as + it is operating on the objects. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-FirstThat">H5Lfirst_that</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Lfirst_that</code>(<em>hid_t </em><code>lst_id</code>, + <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, + <em>VOIDP</em><code>args</code>, + ) +<dt><strong>Description:</strong> + <dd>This function will find and return the first object in the list which + causes the specified function to return a TRUE (non-zero) value. Any + optional arguments required can be passed through the "args" variable. + The found object is then marked as the current object. If no objects + in the list meet the criteria of the specified function or an error + occurs, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> + <dd>Pointer to the function to operate on the objects + <dt><em>VOIDP</em> <code>args</code> + <dd>Pointer any additional arguments needed by the function as + it is operating on the objects. + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure or no matching objects +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-NextThat">H5Lnext_that</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Lnext_that</code>(<em>hid_t </em><code>lst_id</code>, + <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, + <em>VOIDP</em><code>args</code>, + ) +<dt><strong>Description:</strong> + <dd>This function will find and return the next object in the list which + causes the specified function to return a TRUE (non-zero) value. Any + optional arguments required can be passed through the "args" variable. + The found object is then marked as the current object. If no objects + in the list meet the criteria of the specified function or an error + occurs, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> + <dd>Pointer to the function to operate on the objects + <dt><em>VOIDP</em> <code>args</code> + <dd>Pointer any additional arguments needed by the function as + it is operating on the objects. + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure or no matching objects +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-PreviousThat">H5Lprevious_that</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Lprevious_that</code>(<em>hid_t </em><code>lst_id</code>, + <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, + <em>VOIDP</em><code>args</code>, + ) +<dt><strong>Description:</strong> + <dd>This function will find and return the previous object in the list which + causes the specified function to return a TRUE (non-zero) value. Any + optional arguments required can be passed through the "args" variable. + The found object is then marked as the current object. If no objects + in the list meet the criteria of the specified function or an error + occurs, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> + <dd>Pointer to the function to operate on the objects + <dt><em>VOIDP</em> <code>args</code> + <dd>Pointer any additional arguments needed by the function as + it is operating on the objects. + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure or no matching objects +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-LastThat">H5Llast_that</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Llast_that</code>(<em>hid_t </em><code>lst_id</code>, + <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, + <em>VOIDP</em><code>args</code>, + ) +<dt><strong>Description:</strong> + <dd>This function will find and return the last object in the list which + causes the specified function to return a TRUE (non-zero) value. Any + optional arguments required can be passed through the "args" variable. + The found object is then marked as the current object. If no objects + in the list meet the criteria of the specified function or an error + occurs, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> + <dd>Pointer to the function to operate on the objects + <dt><em>VOIDP</em> <code>args</code> + <dd>Pointer any additional arguments needed by the function as + it is operating on the objects. + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure or no matching objects +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-AllSuchThat">H5Lall_such_that</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Lall_such_that</code>(<em>hid_t </em><code>lst_id</code>, + <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, + <em>VOIDP</em><code>args</code>, + ) +<dt><strong>Description:</strong> + <dd>This function will return a new list containing all of the objects in + the list which cause the specified function to return a TRUE (non-zero) + value. Any optional arguments required can be passed through the "args" + variable. The objects themselves are not copied, onle new references + to them are made. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> + <dd>Pointer to the function to operate on the objects + <dt><em>VOIDP</em> <code>args</code> + <dd>Pointer any additional arguments needed by the function as + it is operating on the objects. + </dl> +<dt><strong>Returns:</strong> + <dd>A valid list atom on success, negative on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="LinkList-RemoveAllSuchThat">H5Lremove_all_such_that</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Lremove_all_such_that</code>(<em>hid_t </em><code>lst_id</code>, + <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, + <em>VOIDP</em><code>args</code>, + ) +<dt><strong>Description:</strong> + <dd>This function will remove all of the objects in the list which cause + the specified function to return a TRUE (non-zero) value. Any optional + arguments required can be passed through the "args" variable. Note that + the memory for the objects will not be reclaimed, so if the objects have + no other references, it is best to avoid this function and remove the + objects one by one, freeing them when necessary. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>lst_id</code> + <dd>ID of the list object + <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> + <dd>Pointer to the function to operate on the objects + <dt><em>VOIDP</em> <code>args</code> + <dd>Pointer any additional arguments needed by the function as + it is operating on the objects. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<h2><a name="TBBT">Threaded, Balanced, Binary-Tree Object API Functions</a></h2> +<P>These functions manage in-memory TBBTs in various useful ways. +<br> +<br> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-Add">H5Badd</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Badd</code>(<em>hid_t </em><code>tree_id</code>, + <em>VOIDP</em><code>item</code>, + <em>VOIDP</em><code>key</code> + ) +<dt><strong>Description:</strong> + <dd>This function inserts a new node having a key value of <code>key</code> + and a data pointer of <code>item</code> into the tree. If a node + already exists in the tree with the same key value or an error occurs, + negative is returned, otherwise, zero is returned. The comparison + function which the tree was created with is used to determine the + location of the new node in the tree. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + <dt><em>VOIDP</em> <code>item</code> + <dd>Pointer to the data of the object to insert into the tree. + <dt><em>VOIDP</em> <code>key</code> + <dd>Pointer to the key of the object to insert into the tree. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-Remove">H5Bremove</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Bremove</code>(<em>hid_t </em><code>tree_id</code>, + <em>VOIDP</em><code>key</code> + ) +<dt><strong>Description:</strong> + <dd>This function removes a node with a key value of <code>key</code>. + The data pointer corresponding to the key is returned on success, or + a NULL value is returned on failure. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + <dt><em>VOIDP</em> <code>key</code> + <dd>Pointer to the key of the object to remove from the tree. + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to the data item on success, NULL on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-RemoveAll">H5Bremove_all</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Bremove_all</code>(<em>hid_t </em><code>tree_id</code>, + <em>void</em><code>(*free_func)(VOIDP)</code> + ) +<dt><strong>Description:</strong> + <dd>This function removes all nodes from the tree. If + <code>free_func</code> is not NULL, each object removed from the list + is passed to <code>free_func</code> before being removed from the list. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + <dt><em>void</em> <code>(*free_func)(VOIDP)</code> + <dd>Pointer to the function to call for each item removed from + the list. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-RemoveCurrent">H5Bremove_current</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Bremove_all</code>(<em>hid_t </em><code>tree_id</code>) +<dt><strong>Description:</strong> + <dd>This function removes the "current object" from the tree and returns + a pointer to it. The tree's current object is moved back to the + previous node in the tree, or set to NULL if the object removed is at + the beginning of the tree. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to the data item removed on success, NULL on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-PeekAtBeginning">H5Bpeek_at_beginning</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Bpeek_at_beginning</code>(<em>hid_t </em><code>tree_id</code>) +<dt><strong>Description:</strong> + <dd>This function returns a pointer to the first object in the tree. If + the tree is empty, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to the first data item on success, NULL on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-PeekAtEnd">H5Bpeek_at_end</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Bpeek_at_end</code>(<em>hid_t </em><code>tree_id</code>) +<dt><strong>Description:</strong> + <dd>This function returns a pointer to the last object in the tree. If + the tree is empty, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to the last data item on success, NULL on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-Find">H5Bfind</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Bfind</code>(<em>hid_t </em><code>tree_id</code>, + <em>VOIDP</em><code>key</code> + ) +<dt><strong>Description:</strong> + <dd>This function returns a pointer to the object in the tree who's key + matches the argument passed in. If the no match is found, NULL is + returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + <dt><em>VOIDP</em> <code>key</code> + <dd>Pointer to the key of the object to search for the tree. + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to the data item on success, NULL on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-Index">H5Bindex</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Bindex</code>(<em>hid_t </em><code>tree_id</code>, + <em>uintn</em><code>indx</code> + ) +<dt><strong>Description:</strong> + <dd>This function finds the n'th object in a tree and returns it. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + <dt><em>uintn</em> <code>indx</code> + <dd>Index of the object to return. + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to the data item on success, NULL on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-FirstInTree">H5Bfirst_in_tree</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Bfirst_in_tree</code>(<em>hid_t </em><code>tree_id</code>) +<dt><strong>Description:</strong> + <dd>This function returns a pointer to the first object in the tree, and + marks it as the current object. If the tree is empty, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to the data item on success, NULL on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-LastInTree">H5Blast_in_tree</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Blast_in_tree</code>(<em>hid_t </em><code>tree_id</code>) +<dt><strong>Description:</strong> + <dd>This function returns a pointer to the last object in the tree, and + marks it as the current object. If the tree is empty, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to the data item on success, NULL on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-CurrentInTree">H5Bcurrent_in_tree</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Bcurrent_in_tree</code>(<em>hid_t </em><code>tree_id</code>) +<dt><strong>Description:</strong> + <dd>This function returns a pointer to the object that is considered the + "current object" in the tree. + If the current object has been removed, or current points before or + after the tree or the tree is empty, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to the data item on success, NULL on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-NextInTree">H5Bnext_in_tree</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Bnext_in_tree</code>(<em>hid_t </em><code>tree_id</code>) +<dt><strong>Description:</strong> + <dd>This function returns a pointer to the next object in the tree and marks + it as the current object. + If the end of the tree has been reached or the tree is empty, NULL is + returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to the data item on success, NULL on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-PreviousInTree">H5Bprevious_in_tree</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Bprevious_in_tree</code>(<em>hid_t </em><code>tree_id</code>) +<dt><strong>Description:</strong> + <dd>This function returns a pointer to the previous object in the tree and + marks it as the current object. + If the beginning of the tree has been reached or the tree is empty, NULL + is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to the data item on success, NULL on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-ResetToBeginning">H5Breset_to_beginning</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Breset_to_beginning</code>(<em>hid_t </em><code>tree_id</code>) +<dt><strong>Description:</strong> + <dd>This function resets the "current object" to the beginning of the tree. + Therefore the next object in the tree is the first object. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to the data item on success, NULL on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-ResetToEnd">H5Breset_to_end</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Breset_to_end</code>(<em>hid_t </em><code>tree_id</code>) +<dt><strong>Description:</strong> + <dd>This function resets the "current object" to the end of the tree. + Therefore the previous object in the tree is the last object. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to the data item on success, NULL on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-NumOfObjects">H5Bnum_of_objects</a> +<dt><strong>Signature:</strong> + <dd><em>uintn </em><code>H5Bnum_of_objects</code>(<em>hid_t </em><code>tree_id</code>) +<dt><strong>Description:</strong> + <dd>This function returns the number of objects in the tree. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + </dl> +<dt><strong>Returns:</strong> + <dd>The number of nodes in the tree (possibly zero) on success or UFAIL on + failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-IsEmpty">H5Bis_empty</a> +<dt><strong>Signature:</strong> + <dd><em>hbool_t </em><code>H5Bis_empty</code>(<em>hid_t </em><code>tree_id</code>) +<dt><strong>Description:</strong> + <dd>This function determines if the tree is empty. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + </dl> +<dt><strong>Returns:</strong> + <dd>TRUE if the tree is empty, FALSE if the tree has objects, negative on + failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-IsInTree">H5Bis_in_tree</a> +<dt><strong>Signature:</strong> + <dd><em>hbool_t </em><code>H5Bis_in_tree</code>(<em>hid_t </em><code>tree_id</code>, + <em>VOIDP</em><code>item</code>, + <em>VOIDP</em><code>key</code> + ) +<dt><strong>Description:</strong> + <dd>This function determines if an object is in the tree. If + <code>item</code> is NULL, only the key pointer will be used to search + for nodes in the tree. If <code>key</code> is NULL, only the item pointer + will be used to search for nodes in the tree. If both <code>item</code> + and <code>key</code> are not NULL, only a node which matches both pointers + will be considered a match for the search. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + <dt><em>VOIDP</em> <code>item</code> + <dd>Pointer to the data of the object to search for in the tree. + <dt><em>VOIDP</em> <code>key</code> + <dd>Pointer to the key of the object to search for in the tree. + </dl> +<dt><strong>Returns:</strong> + <dd>TRUE if a search node is found, FALSE if no nodes match, negative on + failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-CopyTree">H5Bcopy_tree</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Bcopy_tree</code>(<em>hid_t </em><code>tree_id</code>) +<dt><strong>Description:</strong> + <dd>This function makes a copy of the tree. The objects themselves are not + copied, only new references to them are made. The new tree has no + current object set. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + </dl> +<dt><strong>Returns:</strong> + <dd>A valid tree atom on success, negative on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-PerformOnTree">H5Bperform_on_tree</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Bperform_on_tree</code>(<em>hid_t </em><code>tree_id</code>, + <em>void</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, + <em>VOIDP</em><code>args</code>, + ) +<dt><strong>Description:</strong> + <dd>This function performs the specified function on each object in the + tree. Any options arguments required can be passed through the "args" + pointer. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + <dt><em>void</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> + <dd>Pointer to the function to operate on the objects + <dt><em>VOIDP</em> <code>args</code> + <dd>Pointer any additional arguments needed by the function as + it is operating on the objects. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-FirstThat">H5Bfirst_that</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Bfirst_that</code>(<em>hid_t </em><code>tree_id</code>, + <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, + <em>VOIDP</em><code>args</code>, + ) +<dt><strong>Description:</strong> + <dd>This function will find and return the first object in the tree which + causes the specified function to return a TRUE (non-zero) value. Any + optional arguments required can be passed through the "args" variable. + The found object is then marked as the current object. If no objects + in the tree meet the criteria of the specified function or an error + occurs, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> + <dd>Pointer to the function to operate on the objects + <dt><em>VOIDP</em> <code>args</code> + <dd>Pointer any additional arguments needed by the function as + it is operating on the objects. + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure or no matching objects +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-NextThat">H5Bnext_that</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Bnext_that</code>(<em>hid_t </em><code>tree_id</code>, + <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, + <em>VOIDP</em><code>args</code>, + ) +<dt><strong>Description:</strong> + <dd>This function will find and return the next object in the tree which + causes the specified function to return a TRUE (non-zero) value. Any + optional arguments required can be passed through the "args" variable. + The found object is then marked as the current object. If no objects + in the tree meet the criteria of the specified function or an error + occurs, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> + <dd>Pointer to the function to operate on the objects + <dt><em>VOIDP</em> <code>args</code> + <dd>Pointer any additional arguments needed by the function as + it is operating on the objects. + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure or no matching objects +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-PreviousThat">H5Bprevious_that</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Bprevious_that</code>(<em>hid_t </em><code>tree_id</code>, + <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, + <em>VOIDP</em><code>args</code>, + ) +<dt><strong>Description:</strong> + <dd>This function will find and return the previous object in the tree which + causes the specified function to return a TRUE (non-zero) value. Any + optional arguments required can be passed through the "args" variable. + The found object is then marked as the current object. If no objects + in the tree meet the criteria of the specified function or an error + occurs, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> + <dd>Pointer to the function to operate on the objects + <dt><em>VOIDP</em> <code>args</code> + <dd>Pointer any additional arguments needed by the function as + it is operating on the objects. + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure or no matching objects +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-LastThat">H5Blast_that</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Blast_that</code>(<em>hid_t </em><code>tree_id</code>, + <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, + <em>VOIDP</em><code>args</code>, + ) +<dt><strong>Description:</strong> + <dd>This function will find and return the last object in the tree which + causes the specified function to return a TRUE (non-zero) value. Any + optional arguments required can be passed through the "args" variable. + The found object is then marked as the current object. If no objects + in the tree meet the criteria of the specified function or an error + occurs, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> + <dd>Pointer to the function to operate on the objects + <dt><em>VOIDP</em> <code>args</code> + <dd>Pointer any additional arguments needed by the function as + it is operating on the objects. + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure or no matching objects +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-AllSuchThat">H5Ball_such_that</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Ball_such_that</code>(<em>hid_t </em><code>tree_id</code>, + <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, + <em>VOIDP</em><code>args</code>, + ) +<dt><strong>Description:</strong> + <dd>This function will return a new tree containing all of the objects in + the tree which cause the specified function to return a TRUE (non-zero) + value. Any optional arguments required can be passed through the "args" + variable. The objects themselves are not copied, onle new references + to them are made. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> + <dd>Pointer to the function to operate on the objects + <dt><em>VOIDP</em> <code>args</code> + <dd>Pointer any additional arguments needed by the function as + it is operating on the objects. + </dl> +<dt><strong>Returns:</strong> + <dd>A valid tree atom on success, negative on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="TBBT-RemoveAllSuchThat">H5Bremove_all_such_that</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Bremove_all_such_that</code>(<em>hid_t </em><code>tree_id</code>, + <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, + <em>VOIDP</em><code>args</code>, + ) +<dt><strong>Description:</strong> + <dd>This function will remove all of the objects in the tree which cause + the specified function to return a TRUE (non-zero) value. Any optional + arguments required can be passed through the "args" variable. Note that + the memory for the objects will not be reclaimed, so if the objects have + no other references, it is best to avoid this function and remove the + objects one by one, freeing them when necessary. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>tree_id</code> + <dd>ID of the TBBT object + <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> + <dd>Pointer to the function to operate on the objects + <dt><em>VOIDP</em> <code>args</code> + <dd>Pointer any additional arguments needed by the function as + it is operating on the objects. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<h2><a name="BitVector">Bit-Vector Object API Functions</a></h2> +<P>These functions manage in-memory bit-vectors used to provide "set" +operations and maintain groups of flags about file information. +<br> +<br> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="BitVector-Set">H5Vset</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Vset</code>(<em>hid_t </em><code>bv_id</code>, + <em>uint32</em><code>bit_num</code>, + <em>hbool_t</em><code>value</code> + ) +<dt><strong>Description:</strong> + <dd>This function sets a bit in a bit-vector to a given boolean value. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>bv_id</code> + <dd>ID of the bit-vector object. + <dt><em>uint32</em> <code>bit_num</code> + <dd>Which bit in the vector to set. + <dt><em>hbool_t</em> <code>value</code> + <dd>Value to set the bit to. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="BitVector-Get">H5Vget</a> +<dt><strong>Signature:</strong> + <dd><em>hbool_t </em><code>H5Vget</code>(<em>hid_t </em><code>bv_id</code>, + <em>uint32</em><code>bit_num</code> + ) +<dt><strong>Description:</strong> + <dd>This function gets the value of a bit in a bit-vector. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>bv_id</code> + <dd>ID of the bit-vector object. + <dt><em>uint32</em> <code>bit_num</code> + <dd>Which bit in the vector to get. + </dl> +<dt><strong>Returns:</strong> + <dd>Value of the bit or negative on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="BitVector-Clear">H5Vclear</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Vclear</code>(<em>hid_t </em><code>bv_id</code>, + <em>hbool_t</em><code>value</code> + ) +<dt><strong>Description:</strong> + <dd>This function clears an entire bit-vector to a given boolean value. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>bv_id</code> + <dd>ID of the bit-vector object. + <dt><em>hbool_t</em> <code>value</code> + <dd>The value to clear the bit-vector to. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="BitVector-Size">H5Vsize</a> +<dt><strong>Signature:</strong> + <dd><em>uint32 </em><code>H5Vclear</code>(<em>hid_t </em><code>bv_id</code>) +<dt><strong>Description:</strong> + <dd>This function reports the number of bits used in a bit-vector. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>bv_id</code> + <dd>ID of the bit-vector object. + </dl> +<dt><strong>Returns:</strong> + <dd>The number of bits in the bit-vector (possibly zero) on success or + UFAIL on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="BitVector-Find">H5Vfind</a> +<dt><strong>Signature:</strong> + <dd><em>uint32 </em><code>H5Vfind</code>(<em>hid_t </em><code>bv_id</code>, + <em>hbool_t</em><code>value</code> + ) +<dt><strong>Description:</strong> + <dd>This function finds the first bit in a bit-vector with a given value. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>bv_id</code> + <dd>ID of the bit-vector object. + <dt><em>hbool_t</em> <code>value</code> + <dd>The value to search for. + </dl> +<dt><strong>Returns:</strong> + <dd>The position of the first bit with the given value on success or UFAIL + on failure. +</dl> + +<hr> +<h2><a name="Atom">Atom Object API Functions</a></h2> +<P>These functions manage in-memory atoms, which provide a portable and +protected way of refering to memory structures. +<br> +<br> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Atom-Register">H5Aregister</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Aregister</code>(<em>hgroup_t </em><code>grp_id</code>, + <em>VOIDP</em><code>ptr</code> + ) +<dt><strong>Description:</strong> + <dd>This function registers a pointer (to a data-structure, usually) in a + group and provides an atom for it. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hgroup_t</em> <code>grp_id</code> + <dd>ID of the atom group. + <dt><em>VOIDP</em> <code>ptr</code> + <dd>The pointer (to a data-structure) to register in the group. + </dl> +<dt><strong>Returns:</strong> + <dd>A value atom on success, negative on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Atom-Unregister">H5Aunregister</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Aunregister</code>(<em>hid_t </em><code>atm</code>) +<dt><strong>Description:</strong> + <dd>This function removes an atom from a group and returns a pointer to + the structure which was registered. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>atm</code> + <dd>Atom to remove. + </dl> +<dt><strong>Returns:</strong> + <dd>A valid memory pointer on success, NULL on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Atom-LookupObject">H5Alookup_object</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Alookup_object</code>(<em>hid_t </em><code>atm</code>) +<dt><strong>Description:</strong> + <dd>This function retrieves the memory pointer which is associated with + the atom. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>atm</code> + <dd>Atom to look up. + </dl> +<dt><strong>Returns:</strong> + <dd>A valid memory pointer on success, NULL on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Atom-LookupGroup">H5Alookup_group</a> +<dt><strong>Signature:</strong> + <dd><em>hgroup_t </em><code>H5Alookup_group</code>(<em>hid_t </em><code>atm</code>) +<dt><strong>Description:</strong> + <dd>This function retrieves the group that the atom is in. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>atm</code> + <dd>Atom to look up. + </dl> +<dt><strong>Returns:</strong> + <dd>A valid atom group on success, negative on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="Atom-Search">H5Asearch</a> +<dt><strong>Signature:</strong> + <dd><em>VOIDP </em><code>H5Asearch</code>(<em>hgroup_t </em><code>grp</code>, + <em>intn</em><code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code>, + <em>VOIDP</em><code>args</code>, + ) +<dt><strong>Description:</strong> + <dd>This function will find and return the first object in the atomic + group which causes the specified function to return a TRUE (non-zero) + value. Any optional arguments required can be passed through the + "args" variable. Currently, there is no way to resume a search. + If no objects in the group meet the criteria of the specified function + or an error occurs, NULL is returned. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hgroup_t</em> <code>grp</code> + <dd>ID of the atom group to search. + <dt><em>intn</em> <code>(*fcn)(VOIDP /* object */, VOIDP /* args */)</code> + <dd>Pointer to the function to operate on the objects + <dt><em>VOIDP</em> <code>args</code> + <dd>Pointer any additional arguments needed by the function as + it is operating on the objects. + </dl> +<dt><strong>Returns:</strong> + <dd>A pointer to an object on success/NULL on failure or no matching objects +</dl> + +<hr> +<h2><a name="String">String Object API Functions</a></h2> +<P>These functions manage in-memory character strings in an object-oriented +way. +<br> +<br> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="String-Copy">H5Scopy</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Scopy</code>(<em>hid_t </em><code>strg_id1</code>, + <em>hid_t</em><code>strg_id2</code> + ) +<dt><strong>Description:</strong> + <dd>This function copies a string from one string object to another. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>strg_id1</code> + <dd>ID of the destination string. + <dt><em>hid_t</em> <code>strg_id2</code> + <dd>ID of the source string. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="String-Convert">H5Sconvert</a> +<dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Sconvert</code>(<em>hid_t </em><code>strg_id/code>, + <em>char *</em><code>buf</code> + ) +<dt><strong>Description:</strong> + <dd>This function copies a string object into a zero-terminated character + buffer. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>strg_id</code> + <dd>ID of the destination string. + <dt><em>char *</em> <code>buf</code> + <dd>Character buffer to store string in. + </dl> +<dt><strong>Returns:</strong> + <dd>zero/negative +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="String-Len">H5Slen</a> +<dt><strong>Signature:</strong> + <dd><em>uintn </em><code>H5Slen</code>(<em>hid_t </em><code>strg_id</code>) +<dt><strong>Description:</strong> + <dd>This function return the length of a string in characters. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>strg_id</code> + <dd>ID of the string. + </dl> +<dt><strong>Returns:</strong> + <dd>The length of the string (possibly 0) on success, or UFAIL on failure. +</dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="String-Compare">H5Scompare</a> +<dt><strong>Signature:</strong> + <dd><em>intn </em><code>H5Scompare</code>(<em>hid_t </em><code>strg_id1</code>, + <em>hid_t</em><code>strg_id2</code> + ) +<dt><strong>Description:</strong> + <dd>This function compares the two strings, returning an integer less than, + equal to, or greater than zero, indicating that the string referenced + by <code>strg_id1</code> is less than, equal to, or greater than the + string referenced by <code>strg_id2</code>. +<dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>strg_id1</code> + <dd>ID of the first string. + <dt><em>hid_t</em> <code>strg_id1</code> + <dd>ID of the second string. + </dl> +<dt><strong>Returns:</strong> + <dd>An integer less than, equal to, or greater than zero based on the values + of the strings. +</dl> +--> + +<hr> +<h2><a name="Glossary">Glossary of data-types used</a></h2> +<P>Since many of the typedefs in the HDF5 API are not well-defined yet, +the types below may change radically en route to a final API... +<br> +<br> + +<a name="Glossary-Basic">Basic Types:</a> +<ul> + <li>char - 8-bit character (only for ASCII information) + <li>int8 - 8-bit signed integer + <li>uint8 - 8-bit unsigned integer + <li>int16 - 16-bit signed integer + <li>uint16 - 16-bit unsigned integer + <li>int32 - 32-bit signed integer + <li>uint32 - 32-bit unsigned integer + <li>intn - "native" signed integer + <li>uintn - "native" unsigned integer + <li>int64 - 64-bit signed integer (new) + <li>uint64 - 64-bit unsigned integer (new) + <li>float32 - 32-bit IEEE float + <li>float64 - 64-bit IEEE float +</ul> + +<a name="Glossary-Complex">Complex Types:</a> +<ul> + <li>hid_t - 32-bit unsigned integer used as ID for memory objects + <li>hoid_t - 32-bit unsigned integer (currently) used as ID for disk-based + objects + <li>hbool_t - boolean to indicate true/false/error codes from functions + <li>herr_t - 32-bit integer to indicate succeed/fail codes from functions +</ul> + +<a name="Glossary-DiskIO">Disk I/O Types:</a> +<ul> + <li>hoff_t - (64-bit?) offset on disk in bytes + <li>hlen_t - (64-bit?) length on disk in bytes +</ul> + diff --git a/doc/html/H5.api_map.html b/doc/html/H5.api_map.html new file mode 100644 index 0000000..c35102a --- /dev/null +++ b/doc/html/H5.api_map.html @@ -0,0 +1,849 @@ +<html><head><title> +HDF5 Legacy API Equivalence +</title></head><body> + +<center> +<h1>HDF5: API Mapping to legacy APIs</h1> +</center> + +<table border=1 cellpadding=2 cellspacing=0> +<tr> +<th>Functionality</th> +<th>netCDF</th> +<th>SD</th> +<th>AIO</th> +<th>HDF5</th> +<th>Comments</th> +</tr> + +<tr align=center> +<td>Open existing file for read/write</td> +<td>ncopen</td> +<td>SDstart</td> +<td>AIO_open</td> +<td>H5Fopen</td> +</tr> + +<tr align=center> +<td>Creates new file for read/write.</td> +<td>nccreate</td> +<td><hr></td> +<td><hr></td> +<td>H5Fcreate</td> +<td>SD API handles this with SDopen</td> +</tr> + +<tr align=center> +<td>Close file</td> +<td>ncclose</td> +<td>SDend</td> +<td>AIO_close</td> +<td>H5Fclose</td> +</tr> + +<tr align=center> +<td>Redefine parameters</td> +<td>ncredef</td> +<td><hr></td> +<td><hr></td> +<td><hr></td> +<td>Unneccessary under SD & HDF5 data-models</td> +</tr> + +<tr align=center> +<td>End "define" mode</td> +<td>ncendef</td> +<td><hr></td> +<td><hr></td> +<td><hr></td> +<td>Unneccessary under SD & HDF5 data-models</td> +</tr> + +<tr align=center> +<td>Query the number of datasets, dimensions and attributes in a file</td> +<td>ncinquire</td> +<td>SDfileinfo</td> +<td><hr></td> +<td>H5Dget_info<br>H5Rget_num_relations<br>H5Gget_num_contents</td> +<td>HDF5 interface is more granular and flexible</td> +</tr> + +<tr align=center> +<td>Update a writeable file with current changes</td> +<td>ncsync</td> +<td><hr></td> +<td>AIO_flush</td> +<td>H5Mflush</td> +<td>HDF5 interface is more flexible because it can be applied to parts of the +file hierarchy instead of the whole file at once. The SD interface does not +have this feature, although most of the lower HDF library supports it.</td> +</tr> + +<tr align=center> +<td>Close file access without applying recent changes</td> +<td>ncabort</td> +<td><hr></td> +<td><hr></td> +<td><hr></td> +<td>How useful is this feature?</td> +</tr> + +<tr align=center> +<td>Create new dimension</td> +<td>ncdimdef</td> +<td>SDsetdimname</td> +<td><hr></td> +<td>H5Mcreate</td> +<td>SD interface actually creates dimensions with datasets, this just allows +naming them</td> +</tr> + +<tr align=center> +<td>Get ID of existing dimension</td> +<td>ncdimid</td> +<td>SDgetdimid</td> +<td><hr></td> +<td>H5Maccess</td> +<td>SD interface looks up dimensions by index and the netCDF interface uses +names, but they are close enough. The HDF5 interface does not current allow +access to particular dimensions, only the dataspace as a whole.</td> +</tr> + +<tr align=center> +<td>Get size & name of dimension</td> +<td>ncdiminq</td> +<td>SDdiminfo</td> +<td><hr></td> +<td>H5Mget_name<br>H5Sget_lrank</td> +<td>Only a rough match</td> +</tr> + +<tr align=center> +<td>Rename dimension</td> +<td>ncdimrename</td> +<td>SDsetdimname</td> +<td><hr></td> +<td>H5Mset_name</td> +<td></td> +</tr> + +<tr align=center> +<td>Create a new dataset</td> +<td>ncvardef</td> +<td>SDcreate</td> +<td>AIO_mkarray</td> +<td>H5Mcreate</td> +<td></td> +</tr> + +<tr align=center> +<td>Attach to an existing dataset</td> +<td>ncvarid</td> +<td>SDselect</td> +<td>AIO_arr_load</td> +<td>H5Maccess</td> +<td></td> +</tr> + +<tr align=center> +<td>Get basic information about a dataset</td> +<td>ncvarinq</td> +<td>SDgetinfo</td> +<td>AIO_arr_get_btype<br>AIO_arr_get_nelmts<br>AIO_arr_get_nbdims<br>AIO_arr_get_bdims<br>AIO_arr_get_slab</td> +<td>H5Dget_info</td> +<td>All interfaces have different levels of information that they return, some +use of auxilliary functions is required to get equivalent amount of information</td> +</tr> + +<tr align=center> +<td>Write a single value to a dataset</td> +<td>ncvarput1</td> +<td>SDwritedata</td> +<td>AIO_write</td> +<td>H5Dwrite</td> +<td>What is this useful for?</td> +</tr> + +<tr align=center> +<td>Read a single value from a dataset</td> +<td>ncvarget1</td> +<td>SDreaddata</td> +<td>AIO_read</td> +<td>H5Dread</td> +<td>What is this useful for?</td> +</tr> + +<tr align=center> +<td>Write a solid hyperslab of data (i.e. subset) to a dataset</td> +<td>ncvarput</td> +<td>SDwritedata</td> +<td>AIO_write</td> +<td>H5Dwrite</td> +<td></td> +</tr> + +<tr align=center> +<td>Read a solid hyperslab of data (i.e. subset) from a dataset</td> +<td>ncvarget</td> +<td>SDreaddata</td> +<td>AIO_read</td> +<td>H5Dread</td> +<td></td> +</tr> + +<tr align=center> +<td>Write a general hyperslab of data (i.e. possibly subsampled) to a dataset</td> +<td>ncvarputg</td> +<td>SDwritedata</td> +<td>AIO_write</td> +<td>H5Dwrite</td> +<td></td> +</tr> + +<tr align=center> +<td>Read a general hyperslab of data (i.e. possibly subsampled) from a dataset</td> +<td>ncvargetg</td> +<td>SDreaddata</td> +<td>AIO_read</td> +<td>H5Dread</td> +<td></td> +</tr> + +<tr align=center> +<td>Rename a dataset variable</td> +<td>ncvarrename</td> +<td><hr></td> +<td><hr></td> +<td>H5Mset_name</td> +<td></td> +</tr> + +<tr align=center> +<td>Add an attribute to a dataset</td> +<td>ncattput</td> +<td>SDsetattr</td> +<td><hr></td> +<td>H5Rattach_oid</td> +<td>HDF5 requires creating a seperate object to attach to a dataset, but it also +allows objects to be attributes of any other object, even nested.</td> +</tr> + +<tr align=center> +<td>Get attribute information</td> +<td>ncattinq</td> +<td>SDattrinfo</td> +<td><hr></td> +<td>H5Dget_info</td> +<td>HDF5 has no specific function for attributes, they are treated as all other +objects in the file.</td> +</tr> + +<tr align=center> +<td>Retrieve attribute for a dataset</td> +<td>ncattget</td> +<td>SDreadattr</td> +<td><hr></td> +<td>H5Dread</td> +<td>HDF5 uses general dataset I/O for attributes.</td> +</tr> + +<tr align=center> +<td>Copy attribute from one dataset to another</td> +<td>ncattcopy</td> +<td><hr></td> +<td><hr></td> +<td><hr></td> +<td>What is this used for?</td> +</tr> + +<tr align=center> +<td>Get name of attribute</td> +<td>ncattname</td> +<td>SDattrinfo</td> +<td><hr></td> +<td>H5Mget_name</td> +<td></td> +</tr> + +<tr align=center> +<td>Rename attribute</td> +<td>ncattrename</td> +<td><hr></td> +<td><hr></td> +<td>H5Mset_name</td> +<td></td> +</tr> + +<tr align=center> +<td>Delete attribute</td> +<td>ncattdel</td> +<td><hr></td> +<td><hr></td> +<td>H5Mdelete</td> +<td>This can be faked in current HDF interface with lower-level calls</td> +</tr> + +<tr align=center> +<td>Compute # of bytes to store a number-type</td> +<td>nctypelen</td> +<td>DFKNTsize</td> +<td><hr></td> +<td><hr></td> +<td>Hmm, the HDF5 Datatype interface needs this functionality.</td> +</tr> + +<tr align=center> +<td>Indicate that fill-values are to be written to dataset</td> +<td>ncsetfill</td> +<td>SDsetfillmode</td> +<td><hr></td> +<td><hr></td> +<td>HDF5 Datatype interface should work on this functionality</td> +</tr> + +<tr align=center> +<td>Get information about "record" variables (Those datasets which share the +same unlimited dimension</td> +<td>ncrecinq</td> +<td><hr></td> +<td><hr></td> +<td><hr></td> +<td>This should probably be wrapped in a higher layer interface, if it's +needed for HDF5.</td> +</tr> + +<tr align=center> +<td>Get a record from each dataset sharing the unlimited dimension</td> +<td>ncrecget</td> +<td><hr></td> +<td><hr></td> +<td><hr></td> +<td>This is somewhat equivalent to reading a vdata with non-interlaced +fields, only in a dataset oriented way. This should also be wrapped in a +higher layer interface if it's necessary for HDF5.</td> +</tr> + +<tr align=center> +<td>Put a record from each dataset sharing the unlimited dimension</td> +<td>ncrecput</td> +<td><hr></td> +<td><hr></td> +<td><hr></td> +<td>This is somewhat equivalent to writing a vdata with non-interlaced +fields, only in a dataset oriented way. This should also be wrapped in a +higher layer interface if it's necessary for HDF5.</td> +</tr> + +<tr align=center> +<td>Map a dataset's name to an index to reference it with</td> +<td><hr></td> +<td>SDnametoindex</td> +<td><hr></td> +<td>H5Mfind_name</td> +<td>Equivalent functionality except HDF5 call returns an OID instead of an +index.</td> +</tr> + +<tr align=center> +<td>Get the valid range of values for data in a dataset</td> +<td><hr></td> +<td>SDgetrange</td> +<td><hr></td> +<td><hr></td> +<td>Easily implemented with attributes at a higher level for HDF5.</td> +</tr> + +<tr align=center> +<td>Release access to a dataset</td> +<td><hr></td> +<td>SDendaccess</td> +<td>AIO_arr_destroy</td> +<td>H5Mrelease</td> +<td>Odd that the netCDF API doesn't have this...</td> +</tr> + +<tr align=center> +<td>Set the valid range of data in a dataset</td> +<td><hr></td> +<td>SDsetrange</td> +<td><hr></td> +<td><hr></td> +<td>Easily implemented with attributes at a higher level for HDF5.</td> +</tr> + +<tr align=center> +<td>Set the label, units, format, etc. of the data values in a dataset</td> +<td><hr></td> +<td>SDsetdatastrs</td> +<td><hr></td> +<td><hr></td> +<td>Easily implemented with attributes at a higher level for HDF5.</td> +</tr> + +<tr align=center> +<td>Get the label, units, format, etc. of the data values in a dataset</td> +<td><hr></td> +<td>SDgetdatastrs</td> +<td><hr></td> +<td><hr></td> +<td>Easily implemented with attributes at a higher level for HDF5.</td> +</tr> + +<tr align=center> +<td>Set the label, units, format, etc. of the dimensions in a dataset</td> +<td><hr></td> +<td>SDsetdimstrs</td> +<td><hr></td> +<td><hr></td> +<td>Easily implemented with attributes at a higher level for HDF5.</td> +</tr> + +<tr align=center> +<td>Get the label, units, format, etc. of the dimensions in a dataset</td> +<td><hr></td> +<td>SDgetdimstrs</td> +<td><hr></td> +<td><hr></td> +<td>Easily implemented with attributes at a higher level for HDF5.</td> +</tr> + +<tr align=center> +<td>Set the scale of the dimensions in a dataset</td> +<td><hr></td> +<td>SDsetdimscale</td> +<td><hr></td> +<td><hr></td> +<td>Easily implemented with attributes at a higher level for HDF5.</td> +</tr> + +<tr align=center> +<td>Get the scale of the dimensions in a dataset</td> +<td><hr></td> +<td>SDgetdimscale</td> +<td><hr></td> +<td><hr></td> +<td>Easily implemented with attributes at a higher level for HDF5.</td> +</tr> + +<tr align=center> +<td>Set the calibration parameters of the data values in a dataset</td> +<td><hr></td> +<td>SDsetcal</td> +<td><hr></td> +<td><hr></td> +<td>Easily implemented with attributes at a higher level for HDF5.</td> +</tr> + +<tr align=center> +<td>Get the calibration parameters of the data values in a dataset</td> +<td><hr></td> +<td>SDgetcal</td> +<td><hr></td> +<td><hr></td> +<td>Easily implemented with attributes at a higher level for HDF5.</td> +</tr> + +<tr align=center> +<td>Set the fill value for the data values in a dataset</td> +<td><hr></td> +<td>SDsetfillvalue</td> +<td><hr></td> +<td><hr></td> +<td>HDF5 needs something like this, I'm not certain where to put it.</td> +</tr> + +<tr align=center> +<td>Get the fill value for the data values in a dataset</td> +<td><hr></td> +<td>SDgetfillvalue</td> +<td><hr></td> +<td><hr></td> +<td>HDF5 needs something like this, I'm not certain where to put it.</td> +</tr> + +<tr align=center> +<td>Move/Set the dataset to be in an 'external' file</td> +<td><hr></td> +<td>SDsetexternalfile</td> +<td><hr></td> +<td>H5Dset_storage</td> +<td>HDF5 has simple functions for this, but needs an API for setting up the +storage flow.</td> +</tr> + +<tr align=center> +<td>Move/Set the dataset to be stored using only certain bits from the dataset</td> +<td><hr></td> +<td>SDsetnbitdataset</td> +<td><hr></td> +<td>H5Dset_storage</td> +<td>HDF5 has simple functions for this, but needs an API for setting up the +storage flow.</td> +</tr> + +<tr align=center> +<td>Move/Set the dataset to be stored in compressed form</td> +<td><hr></td> +<td>SDsetcompress</td> +<td><hr></td> +<td>H5Dset_storage</td> +<td>HDF5 has simple functions for this, but needs an API for setting up the +storage flow.</td> +</tr> + +<tr align=center> +<td>Search for an dataset attribute with particular name</td> +<td><hr></td> +<td>SDfindattr</td> +<td><hr></td> +<td>H5Mfind_name<br>H5Mwild_search</td> +<td>HDF5 can handle wildcard searchs for this feature.</td> +</tr> + +<tr align=center> +<td>Map a run-time dataset handle to a persistant disk reference</td> +<td><hr></td> +<td>SDidtoref</td> +<td><hr></td> +<td><hr></td> +<td>I'm not certain this is needed for HDF5.</td> +</tr> + +<tr align=center> +<td>Map a persistant disk reference for a dataset to an index in a group</td> +<td><hr></td> +<td>SDreftoindex</td> +<td><hr></td> +<td><hr></td> +<td>I'm not certain this is needed for HDF5.</td> +</tr> + +<tr align=center> +<td>Determine if a dataset is a 'record' variable (i.e. it has an unlimited dimension)</td> +<td><hr></td> +<td>SDisrecord</td> +<td><hr></td> +<td><hr></td> +<td>Easily implemented by querying the dimensionality at a higher level for HDF5.</td> +</tr> + +<tr align=center> +<td>Determine if a dataset is a 'coordinate' variable (i.e. it is used as a dimension)</td> +<td><hr></td> +<td>SDiscoord</td> +<td><hr></td> +<td><hr></td> +<td>I'm not certain this is needed for HDF5.</td> +</tr> + +<tr align=center> +<td>Set the access type (i.e. parallel or serial) for dataset I/O</td> +<td><hr></td> +<td>SDsetaccesstype</td> +<td><hr></td> +<td><hr></td> +<td>HDF5 has functions for reading the information about this, but needs a better +API for setting up the storage flow.</td> +</tr> + +<tr align=center> +<td>Set the size of blocks used to store a dataset with unlimited dimensions</td> +<td><hr></td> +<td>SDsetblocksize</td> +<td><hr></td> +<td><hr></td> +<td>HDF5 has functions for reading the information about this, but needs a better +API for setting up the storage flow.</td> +</tr> + +<tr align=center> +<td>Sets backward compatibility of dimensions created.</td> +<td><hr></td> +<td>SDsetdimval_comp</td> +<td><hr></td> +<td><hr></td> +<td>Unneccessary in HDF5.</td> +</tr> + +<tr align=center> +<td>Checks backward compatibility of dimensions created.</td> +<td><hr></td> +<td>SDisdimval_comp</td> +<td><hr></td> +<td><hr></td> +<td>Unneccessary in HDF5.</td> +</tr> + +<tr align=center> +<td>Move/Set the dataset to be stored in chunked form</td> +<td><hr></td> +<td>SDsetchunk</td> +<td><hr></td> +<td>H5Dset_storage</td> +<td>HDF5 has simple functions for this, but needs an API for setting up the +storage flow.</td> +</tr> + +<tr align=center> +<td>Get the chunking information for a dataset stored in chunked form</td> +<td><hr></td> +<td>SDgetchunkinfo</td> +<td><hr></td> +<td>H5Dstorage_detail</td> +<td></td> +</tr> + +<tr align=center> +<td>Read/Write chunks of a dataset using a chunk index</td> +<td><hr></td> +<td>SDreadchunk<br>SDwritechunk</td> +<td><hr></td> +<td><hr></td> +<td>I'm not certain that HDF5 needs something like this.</td> +</tr> + +<tr align=center> +<td>Tune chunk caching parameters for chunked datasets</td> +<td><hr></td> +<td>SDsetchunkcache</td> +<td><hr></td> +<td><hr></td> +<td>HDF5 needs something like this.</td> +</tr> + +<tr align=center> +<td>Change some default behavior of the library</td> +<td><hr></td> +<td><hr></td> +<td>AIO_defaults</td> +<td><hr></td> +<td>Something like this would be useful in HDF5, to tune I/O pipelines, etc.</td> +</tr> + +<tr align=center> +<td>Flush and close all open files</td> +<td><hr></td> +<td><hr></td> +<td>AIO_exit</td> +<td><hr></td> +<td>Something like this might be useful in HDF5, although it could be + encapsulated with a higher-level function.</td> +</tr> + +<tr align=center> +<td>Target an architecture for data-type storage</td> +<td><hr></td> +<td><hr></td> +<td>AIO_target</td> +<td><hr></td> +<td>There are some rough parallels with using the data-type in HDF5 to create + data-type objects which can be used to write out future datasets.</td> +</tr> + +<tr align=center> +<td>Map a filename to a file ID</td> +<td><hr></td> +<td><hr></td> +<td>AIO_filename</td> +<td>H5Mget_name</td> +<td></td> +</tr> + +<tr align=center> +<td>Get the active directory (where new datasets are created)</td> +<td><hr></td> +<td><hr></td> +<td>AIO_getcwd</td> +<td><hr></td> +<td>HDF5 allows multiple directories (groups) to be attached to, any of which + can have new datasets created within it.</td> +</tr> + +<tr align=center> +<td>Change active directory</td> +<td><hr></td> +<td><hr></td> +<td>AIO_chdir</td> +<td><hr></td> +<td>Since HDF5 has a slightly different access method for directories (groups), + this functionality can be wrapped around calls to H5Gget_oid_by_name.</td> +</tr> + +<tr align=center> +<td>Create directory</td> +<td><hr></td> +<td><hr></td> +<td>AIO_mkdir</td> +<td>H5Mcreate</td> +<td></td> +</tr> + +<tr align=center> +<td>Return detailed information about an object</td> +<td><hr></td> +<td><hr></td> +<td>AIO_stat</td> +<td>H5Dget_info<br>H5Dstorage_detail</td> +<td>Perhaps more information should be provided through another function in + HDF5?</td> +</tr> + +<tr align=center> +<td>Get "flag" information</td> +<td><hr></td> +<td><hr></td> +<td>AIO_getflags</td> +<td><hr></td> +<td>Not required in HDF5.</td> +</tr> + +<tr align=center> +<td>Set "flag" information</td> +<td><hr></td> +<td><hr></td> +<td>AIO_setflags</td> +<td><hr></td> +<td>Not required in HDF5.</td> +</tr> + +<tr align=center> +<td>Get detailed information about all objects in a directory</td> +<td><hr></td> +<td><hr></td> +<td>AIO_ls</td> +<td>H5Gget_content_info_mult<br>H5Dget_info<br>H5Dstorage_detail</td> +<td>Only roughly equivalent functionality in HDF5, perhaps more should be + added?</td> +</tr> + +<tr align=center> +<td>Get base type of object</td> +<td><hr></td> +<td><hr></td> +<td>AIO_BASIC</td> +<td>H5Gget_content_info</td> +<td></td> +</tr> + +<tr align=center> +<td>Set base type of dataset</td> +<td><hr></td> +<td><hr></td> +<td>AIO_arr_set_btype</td> +<td>H5Mcreate(DATATYPE)</td> +<td></td> +</tr> + +<tr align=center> +<td>Set dimensionality of dataset</td> +<td><hr></td> +<td><hr></td> +<td>AIO_arr_set_bdims</td> +<td>H5Mcreate(DATASPACE)</td> +<td></td> +</tr> + +<tr align=center> +<td>Set slab of dataset to write</td> +<td><hr></td> +<td><hr></td> +<td>AIO_arr_set_slab</td> +<td><hr></td> +<td>This is similar to the process of creating a dataspace for use when + performing I/O on an HDF5 dataset</td> +</tr> + +<tr align=center> +<td>Describe chunking of dataset to write</td> +<td><hr></td> +<td><hr></td> +<td>AIO_arr_set_chunk</td> +<td>H5Dset_storage</td> +<td></td> +</tr> + +<tr align=center> +<td>Describe array index permutation of dataset to write</td> +<td><hr></td> +<td><hr></td> +<td>AIO_arr_set_perm</td> +<td>H5Dset_storage</td> +<td></td> +</tr> + +<tr align=center> +<td>Create a new dataset with dataspace and datatype information from an + existing dataset.</td> +<td><hr></td> +<td><hr></td> +<td>AIO_arr_copy</td> +<td><hr></td> +<td>This can be mimicked in HDF5 by attaching to the datatype and dataspace of +an existing dataset and using the IDs to create new datasets.</td> +</tr> + +<tr align=center> +<td>Create a new directory to group objects within</td> +<td><hr></td> +<td><hr></td> +<td>AIO_mkgroup</td> +<td>H5Mcreate(GROUP)</td> +<td></td> +</tr> + +<tr align=center> +<td>Read name of objects in directory</td> +<td><hr></td> +<td><hr></td> +<td>AIO_read_group</td> +<td>H5Gget_content_info_mult</td> +<td></td> +</tr> + +<tr align=center> +<td>Add objects to directory</td> +<td><hr></td> +<td><hr></td> +<td>AIO_write_group</td> +<td>H5Ginsert_item_mult</td> +<td></td> +</tr> + +<tr align=center> +<td>Combine an architecture and numeric type to derive the format's datatype</td> +<td><hr></td> +<td><hr></td> +<td>AIO_COMBINE</td> +<td><hr></td> +<td>This is a nice feature to add to HDF5.</td> +</tr> + +<tr align=center> +<td>Derive an architecture from the format's datatype</td> +<td><hr></td> +<td><hr></td> +<td>AIO_ARCH</td> +<td><hr></td> +<td>This is a nice feature to add to HDF5.</td> +</tr> + +<tr align=center> +<td>Derive a numeric type from the format's datatype</td> +<td><hr></td> +<td><hr></td> +<td>AIO_PNT</td> +<td><hr></td> +<td>This is a nice feature to add to HDF5.</td> +</tr> + +<tr align=center> +<td>Register error handling function for library to call when errors occur</td> +<td><hr></td> +<td><hr></td> +<td>AIO_error_handler</td> +<td><hr></td> +<td>This should be added to HDF5.</td> +</tr> + +</table> + diff --git a/doc/html/H5.format.html b/doc/html/H5.format.html new file mode 100644 index 0000000..a3c9a7c --- /dev/null +++ b/doc/html/H5.format.html @@ -0,0 +1,3183 @@ +<html> + <head> + <title> + HDF5 Draft Disk-Format Specification + </title> + </head> + <body> + <center><h1>HDF5: Disk Format Implementation</h1></center> + + <ol type=I> + <li><a href="#BootBlock"> + Disk Format Level 0 - File Signature and Boot Block</a> + <li><a href="#ObjectDir"> + Disk Format Level 1 - File Infrastructure</a> + <ol type=A> + <li><a href="#Btrees"> + Disk Format Level 1A - B-link Trees</a> + <li><a href="#SymbolTable"> + Disk Format Level 1B - Symbol Table</a> + <li><a href="#SymbolTableEntry"> + Disk Format Level 1C - Symbol Table Entry</a> + <li><a href="#LocalHeap"> + Disk Format Level 1D - Local Heaps</a> + <li><a href="#GlobalHeap"> + Disk Format Level 1E - Global Heap</a> + <li><a href="#FreeSpaceIndex"> + Disk Format Level 1F - Free-Space Index</a> + </ol> + <li><a href="#DataObject"> + Disk Format Level 2 - Data Objects</a> + <ol type=A> + <li><a href="#ObjectHeader"> + Disk Format Level 2a - Data Object Headers</a> + <ol type=1> + <li><a href="#NILMessage"> <!-- 0x0000 --> + Name: NIL</a> + <li><a href="#SimpleDataSpace"> <!-- 0x0001 --> + Name: Simple Data Space</a> + <li><a href="#DataSpaceMessage"> <!-- 0x0002 --> + Name: Data-Space</a> + <li><a href="#DataTypeMessage"> <!-- 0x0003 --> + Name: Data-Type</a> + <li><a href="#ReservedMessage_0004"> <!-- 0x0004 --> + Name: Reserved - not assigned yet</a> + <li><a href="#ReservedMessage_0005"> <!-- 0x0005 --> + Name: Reserved - not assigned yet</a> + <li><a href="#CompactDataStorageMessage"> <!-- 0x0006 --> + Name: Data Storage - Compact</a> + <li><a href="#ExternalFileListMessage"> <!-- 0x0007 --> + Name: Data Storage - External Data Files</a> + <li><a href="#LayoutMessage"> <!-- 0x0008 --> + Name: Data Storage - Layout</a> + <li><a href="#ReservedMessage_0009"> <!-- 0x0009 --> + Name: Reserved - not assigned yet</a> + <li><a href="#ReservedMessage_000A"> <!-- 0x000a --> + Name: Reserved - not assigned yet</a> + <li><a href="#CompressionMessage"> <!-- 0x000b --> + Name: Data Storage - Compressed</a> + <li><a href="#AttributeListMessage"> <!-- 0x000c --> + Name: Attribute List</a> + <li><a href="#NameMessage"> <!-- 0x000d --> + Name: Object Name</a> + <li><a href="#ModifiedMessage"> <!-- 0x000e --> + Name: Object Modification Date & Time</a> + <li><a href="#SharedMessage"> <!-- 0x000f --> + Name: Shared Object Message</a> + <li><a href="#ContinuationMessage"> <!-- 0x0010 --> + Name: Object Header Continuation</a> + <li><a href="#SymbolTableMessage"> <!-- 0x0011 --> + Name: Symbol Table Message</a> + </ol> + <li><a href="#SharedObjectHeader"> + Disk Format: Level 2b - Shared Data Object Headers</a> + <li><a href="#DataStorage"> + Disk Format: Level 2c - Data Object Data Storage</a> + </ol> + </ol> + + + <h2>Disk Format Implementation</h2> + + <P>The format of a HDF5 file on disk encompasses several + key ideas of the current HDF4 & AIO file formats as well as + addressing some short-comings therein. The new format will be + more self-describing than the HDF4 format and will be more + uniformly applied to data objects in the file. + + + <P>Three levels of information compose the file format. The level + 0 contains basic information for identifying and + "boot-strapping" the file. Level 1 information is composed of + the object directory (stored as a B-tree) and is used as the + index for all the objects in the file. The rest of the file is + composed of data-objects at level 2, with each object + partitioned into header (or "meta") information and data + information. + + <p>The sizes of various fields in the following layout tables are + determined by looking at the number of columns the field spans + in the table. There are three exceptions: (1) The size may be + overridden by specifying a size in parentheses, (2) the size of + addresses is determined by the <em>Size of Addresses</em> field + in the boot block, and (3) the size of size fields is determined + by the <em>Size of Sizes</em> field in the boot block. + + <h3><a name="BootBlock"> + Disk Format: Level 0 - File Signature and Boot Block</a></h3> + + <P>The boot block may begin at certain predefined offsets within + the HDF5 file, allowing a block of unspecified content for + users to place additional information at the beginning (and + end) of the HDF5 file without limiting the HDF5 library's + ability to manage the objects within the file itself. This + feature was designed to accommodate wrapping an HDF5 file in + another file format or adding descriptive information to the + file without requiring the modification of the actual file's + information. The boot-block is located by searching for the + HDF5 file signature at byte offset 0, byte offset 512 and at + successive locations in the file, each a multiple of two of + the previous location, i.e. 0, 512, 1024, 2048, etc. + + <P>The boot-block is composed of a file signature, followed by + boot block and object directory version numbers, information + about the sizes of offset and length values used to describe + items within the file, the size of each object directory page, + and a symbol table entry for the root object in the file. + + <p> + <center> + <table border align=center cellpadding=4 width="80%"> + <caption align=top> + <B>HDF5 Boot Block Layout</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4><br>HDF5 File Signature (8 bytes)<br><br></td> + </tr> + + <tr align=center> + <td>Version # of Boot Block</td> + <td>Version # of Global Free-Space Storage</td> + <td>Version # of Object Directory</td> + <td>Reserved</td> + </tr> + + <tr align=center> + <td>Version # of Shared Header Message Format</td> + <td>Size of Addresses</td> + <td>Size of Sizes</td> + <td>Reserved (zero)</td> + </tr> + + <tr align=center> + <td colspan=2>Symbol Table Leaf Node K</td> + <td colspan=2>Symbol Table Internal Node K</td> + </tr> + + <tr align=center> + <td colspan=4>File Consistency Flags</td> + </tr> + + <tr align=center> + <td colspan=4>Base Address</td> + </tr> + + <tr align=center> + <td colspan=4>Address of Global Free-Space Heap</td> + </tr> + + <tr align=center> + <td colspan=4>End of File Address</td> + </tr> + + <tr align=center> + <td colspan=4><br> + Symbol-Table Entry of the "Root Object" + <br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>File Signature</td> + <td>This field contains a constant value and can be used to + quickly identify a file as being an HDF5 file. The + constant value is designed to allow easy identification of + an HDF5 file and to allow certain types of data corruption + to be detected. The file signature of a HDF5 file always + contain the following values: + + <br><br><center> + <table border align=center cellpadding=4 width="80%"> + <tr align=center> + <td>decimal</td> + <td width="8%">137</td> + <td width="8%">72</td> + <td width="8%">68</td> + <td width="8%">70</td> + <td width="8%">13</td> + <td width="8%">10</td> + <td width="8%">26</td> + <td width="8%">10</td> + </tr> + + <tr align=center> + <td>hexadecimal</td> + <td width="8%">89</td> + <td width="8%">48</td> + <td width="8%">44</td> + <td width="8%">46</td> + <td width="8%">0d</td> + <td width="8%">0a</td> + <td width="8%">1a</td> + <td width="8%">0a</td> + </tr> + + <tr align=center> + <td>ASCII C Notation</td> + <td width="8%">\211</td> + <td width="8%">H</td> + <td width="8%">D</td> + <td width="8%">F</td> + <td width="8%">\r</td> + <td width="8%">\n</td> + <td width="8%">\032</td> + <td width="8%">\n</td> + </tr> + </table> + </center> + <br> + + This signature both identifies the file as a HDF5 file + and provides for immediate detection of common + file-transfer problems. The first two bytes distinguish + HDF5 files on systems that expect the first two bytes to + identify the file type uniquely. The first byte is + chosen as a non-ASCII value to reduce the probability + that a text file may be misrecognized as a HDF5 file; + also, it catches bad file transfers that clear bit + 7. Bytes two through four name the format. The CR-LF + sequence catches bad file transfers that alter newline + sequences. The control-Z character stops file display + under MS-DOS. The final line feed checks for the inverse + of the CR-LF translation problem. (This is a direct + descendent of the PNG file signature.)</td> + </tr> + + <tr valign=top> + <td>Version # of the Boot Block</td> + <td>This value is used to determine the format of the + information in the boot block. When the format of the + information in the boot block is changed, the version # + is incremented to the next integer and can be used to + determine how the information in the boot block is + formatted.</td> + </tr> + + <tr valign=top> + <td>Version # of the Global Free-Space Storage</td> + <td>This value is used to determine the format of the + information in the Global Free-Space Heap. Currently, + this is implemented as a B-tree of length/offset pairs + to locate free space in the file, but future advances in + the file-format could change the method of finding + global free-space. When the format of the information + is changed, the version # is incremented to the next + integer and can be used to determine how the information + is formatted.</td> + </tr> + + <tr valign=top> + <td>Version # of the Object Directory</td> + <td>This value is used to determine the format of the + information in the Object Directory. When the format of + the information in the Object Directory is changed, the + version # is incremented to the next integer and can be + used to determine how the information in the Object + Directory is formatted.</td> + </tr> + + <tr valign=top> + <td>Version # of the Shared Header Message Format</td> + <td>This value is used to determine the format of the + information in a shared object header message, which is + stored in the global small-data heap. Since the format + of the shared header messages differ from the private + header messages, a version # is used to identify changes + in the format.</td> + </tr> + + <tr valign=top> + <td>Size of Addresses</td> + <td>This value contains the number of bytes used for + addresses in the file. The values for the addresses of + objects in the file are relative to a base address, + usually the address of the boot block signature. This + allows a wrapper to be added after the file is created + without invalidating the internal offset locations.</td> + </tr> + + <tr valign=top> + <td>Size of Sizes</td> + <td>This value contains the number of bytes used to store + the size of an object.</td> + </tr> + + <tr valign=top> + <td>Symbol Table Leaf Node K</td> + <td>Each leaf node of a symbol table B-tree will have at + least this many entries but not more than twice this + many. If a symbol table has a single leaf node then it + may have fewer entries.</td> + </tr> + + <tr valign=top> + <td>Symbol Table Internal Node K</td> + <td>Each internal node of a symbol table B-tree will have + at least K pointers to other nodes but not more than 2K + pointers. If the symbol table has only one internal + node then it might have fewer than K pointers.</td> + </tr> + + <tr valign=top> + <td>Bytes per B-Tree Page</td> + <td>This value contains the # of bytes used for symbol + pairs per page of the B-Trees used in the file. All + B-Tree pages will have the same size per page. <br>(For + 32-bit file offsets, 340 objects is the maximum per 4KB + page, and for 64-bit file offset, 254 objects will fit + per 4KB page. In general, the equation is: <br> <# + of objects> = FLOOR((<page size>-<offset + size>)/(<Symbol size>+<offset size>))-1 )</td> + </tr> + + <tr valign=top> + <td>File Consistency Flags</td> + <td>This value contains flags to indicate information + about the consistency of the information contained + within the file. Currently, the following bit flags are + defined: bit 0 set indicates that the file is opened for + write-access and bit 1 set indicates that the file has + been verified for consistency and is guaranteed to be + consistent with the format defined in this document. + Bits 2-31 are reserved for future use. Bit 0 should be + set as the first action when a file is opened for write + access and should be cleared only as the final action + when closing a file. Bit 1 should be cleared during + normal access to a file and only set after the file's + consistency is guaranteed by the library or a + consistency utility.</td> + </tr> + + <tr valign=top> + <td>Base Address</td> + <td>This is the absolute file address of the first byte of + the hdf5 data within the file. Unless otherwise noted, + all other file addresses are relative to this base + address.</td> + </tr> + + <tr valign=top> + <td>Address of Global Free-Space Heap</td> + <td>This value contains the relative address of the B-Tree + used to manage the blocks of data which are unused in the + file currently. The free-space heap is used to manage the + blocks of bytes at the file-level which become unused with + objects are moved within the file.</td> + </tr> + + <tr valign=top> + <td>End of File Address</td> + <td>This is the relative file address of the first byte past + the end of all HDF5 data. It is used to determine if a + file has been accidently truncated and as an address where + file memory allocation can occur if the free list is not + used.</td> + </tr> + + <tr valign=top> + <td>Symbol-Table Entry of the Root Object</td> + <td>This symbol-table entry (described later in this + document) refers to the entry point into the group + graph. If the file contains a single object, then that + object can be the root object and no groups are used.</td> + </tr> + </table> + </center> + + <h3><a name="Btrees">Disk Format: Level 1A - B-link Trees</a></h3> + + <p>B-link trees allow flexible storage for objects which tend to grow + in ways that cause the object to be stored discontiguously. B-trees + are described in various algorithms books including "Introduction to + Algorithms" by Thomas H. Cormen, Charles E. Leiserson, and Ronald + L. Rivest. The B-link tree, in which the sibling nodes at a + particular level in the tree are stored in a doubly-linked list, + is described in the "Efficient Locking for Concurrent Operations + on B-trees" paper by Phillip Lehman and S. Bing Yao as published + in the <em>ACM Transactions on Database Systems</em>, Vol. 6, + No. 4, December 1981. + + <p>The B-link trees implemented by the file format contain one more + key than the number of children. In other words, each child + pointer out of a B-tree node has a left key and a right key. + The pointers out of internal nodes point to sub-trees while + the pointers out of leaf nodes point to other file data types. + Notwithstanding that difference, internal nodes and leaf nodes + are identical. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <B>B-tree Nodes</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Node Signature</td> + + <tr align=center> + <td>Node Type</td> + <td>Node Level</td> + <td colspan=2>Entries Used</td> + + <tr align=center> + <td colspan=4>Address of Left Sibling</td> + + <tr align=center> + <td colspan=4>Address of Right Sibling</td> + + <tr align=center> + <td colspan=4>Key 0 (variable size)</td> + + <tr align=center> + <td colspan=4>Address of Child 0</td> + + <tr align=center> + <td colspan=4>Key 1 (variable size)</td> + + <tr align=center> + <td colspan=4>Address of Child 1</td> + + <tr align=center> + <td colspan=4>...</td> + + <tr align=center> + <td colspan=4>Key 2<em>K</em> (variable size)</td> + + <tr align=center> + <td colspan=4>Address of Child 2<em>K</em></td> + + <tr align=center> + <td colspan=4>Key 2<em>K</em>+1 (variable size)</td> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Node Signature</td> + <td>The value ASCII 'TREE' is used to indicate the + beginning of a B-link tree node. This gives file + consistency checking utilities a better chance of + reconstructing a damaged file.</td> + </tr> + + <tr valign=top> + <td>Node Type</td> + <td>Each B-link tree points to a particular type of data. + This field indicates the type of data as well as + implying the maximum degree <em>K</em> of the tree and + the size of each Key field. + <br> + <dl compact> + <dt>0 + <dd>This tree points to symbol table nodes. + <dt>1 + <dd>This tree points to a (partial) linear address space. + </dl> + </td> + </tr> + + <tr valign=top> + <td>Node Level</td> + <td>The node level indicates the level at which this node + appears in the tree (leaf nodes are at level zero). Not + only does the level indicate whether child pointers + point to sub-trees or to data, but it can also be used + to help file consistency checking utilities reconstruct + damanged trees.</td> + </tr> + + <tr valign=top> + <td>Entries Used</td> + <td>This determines the number of children to which this + node points. All nodes of a particular type of tree + have the same maximum degree, but most nodes will point + to less than that number of children. The valid child + pointers and keys appear at the beginning of the node + and the unused pointers and keys appear at the end of + the node. The unused pointers and keys have undefined + values.</td> + </tr> + + <tr valign=top> + <td>Address of Left Sibling</td> + <td>This is the file address of the left sibling of the + current node relative to the boot block. If the current + node is the left-most node at this level then this field + is the undefined address (all bits set).</td> + </tr> + + <tr valign=top> + <td>Address of Right Sibling</td> + <td>This is the file address of the right sibling of the + current node relative to the boot block. If the current + node is the right-most node at this level then this + field is the undefined address (all bits set).</td> + </tr> + + <tr valign=top> + <td>Keys and Child Pointers</td> + <td>Each tree has 2<em>K</em>+1 keys with 2<em>K</em> + child pointers interleaved between the keys. The number + of keys and child pointers actually containing valid + values is determined by the `Entries Used' field. If + that field is <em>N</em> then the B-link tree contains + <em>N</em> child pointers and <em>N</em>+1 keys.</td> + </tr> + + <tr valign=top> + <td>Key</td> + <td>The format and size of the key values is determined by + the type of data to which this tree points. The keys are + ordered and are boundaries for the contents of the child + pointer. That is, the key values represented by child + <em>N</em> fall between Key <em>N</em> and Key + <em>N</em>+1. Whether the interval is open or closed on + each end is determined by the type of data to which the + tree points.</td> + </tr> + + <tr valign=top> + <td>Address of Children</td> + <td>The tree node contains file addresses of subtrees or + data depending on the node level (0 implies data + addresses).</td> + </tr> + </table> + </center> + + <h3><a name="SymbolTable">Disk Format: Level 1B - Symbol Table</a></h3> + + <p>A symbol table is a group internal to the file that allows + arbitrary nesting of objects (including other symbol + tables). A symbol table maps a set of names to a set of file + address relative to the file boot block. Certain meta data + for an object to which the symbol table points can be cached + in the symbol table in addition to (or in place of?) the + object header. + + <p>An HDF5 object name space can be stored hierarchically by + partitioning the name into components and storing each + component in a symbol table. The symbol table entry for a + non-ultimate component points to the symbol table containing + the next component. The symbol table entry for the last + component points to the object being named. + + <p>A symbol table is a collection of symbol table nodes pointed + to by a B-link tree. Each symbol table node contains entries + for one or more symbols. If an attempt is made to add a + symbol to an already full symbol table node containing + 2<em>K</em> entries, then the node is split and one node + contains <em>K</em> symbols and the other contains + <em>K</em>+1 symbols. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <B>Symbol Table Node</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Node Signature</td> + + <tr align=center> + <td>Version Number</td> + <td>Reserved for Future Use</td> + <td colspan=2>Number of Symbols</td> + + <tr align=center> + <td colspan=4><br><br>Symbol Table Entries<br><br><br></td> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Node Signature</td> + <td>The value ASCII 'SNOD' is used to indicate the + beginning of a symbol table node. This gives file + consistency checking utilities a better chance of + reconstructing a damaged file.</td> + </tr> + + <tr valign=top> + <td>Version Number</td> + <td>The version number for the symbol table node. This + document describes version 1.</td> + </tr> + + <tr valign=top> + <td>Number of Symbols</td> + <td>Although all symbol table nodes have the same length, + most contain fewer than the maximum possible number of + symbol entries. This field indicates how many entries + contain valid data. The valid entries are packed at the + beginning of the symbol table node while the remaining + entries contain undefined values.</td> + </tr> + + <tr valign=top> + <td>Symbol Table Entries</td> + <td>Each symbol has an entry in the symbol table node. + The format of the entry is described below.</td> + </tr> + </table> + </center> + + <h3><a name="SymbolTableEntry"> + Disk Format: Level 1C - Symbol-Table Entry </a></h3> + + <p>Each symbol table entry in a symbol table node is designed to allow + for very fast browsing of commonly stored scientific objects. + Toward that design goal, the format of the symbol-table entries + includes space for caching certain constant meta data from the + object header. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <B>Symbol Table Entry</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Name Offset (<size> bytes)</td> + + <tr align=center> + <td colspan=4>Object Header Address</td> + + <tr align=center> + <td colspan=4>Symbol-Type</td> + + <tr align=center> + <td colspan=4><br><br>Scratch-pad Space (24 bytes)<br><br><br></td> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Name Offset</td> + <td>This is the byte offset into the symbol table local + heap for the name of the symbol. The name is null + terminated.</td> + </tr> + + <tr valign=top> + <td>Object Header Address</td> + <td>Every object has an object header which serves as a + permanent home for the object's meta data. In addition + to appearing in the object header, the meta data can be + cached in the scratch-pad space.</td> + </tr> + + <tr valign=top> + <td>Symbol-Type</td> + <td>The symbol type is determined from the object header. + It also determines the format for the scratch-pad space. + The value zero indicates that no object header meta data + is cached in the symbol table entry. + <br> + <dl compact> + <dt>0 + <dd>No data is cached by the symbol table entry. This + is guaranteed to be the case when an object header + has a link count greater than one. + + <dt>1 + <dd>Symbol table meta data is cached in the symbol + table entry. This implies that the symbol table + entry refers to another symbol table. + + <dt>2 + <dd>The entry is a symbolic link. The first four bytes + of the scratch pad space are the offset into the local + heap for the link value. The object header address + will be undefined. + + <dt><em>N</em> + <dd>Other cache values can be defined later and + libraries that don't understand the new values will + still work properly. + </dl> + </td> + </tr> + + <tr valign=top> + <td>Scratch-Pad Space</td> + <td>This space is used for different purposes, depending + on the value of the Symbol Type field. Any meta-data + about a dataset object represented in the scratch-pad + space is duplicated in the object header for that + dataset. Furthermore, no data is cached in the symbol + table entry scratch-pad space if the object header for + the symbol table entry has a link count greater than + one.</td> + </tr> + </table> + </center> + + <p>The symbol table entry scratch-pad space is formatted + according to the value of the Symbol Type field. If the + Symbol Type field has the value zero then no information is + stored in the scratch pad space. + + <p>If the Symbol Type field is one, then the scratch pad space + contains cached meta data for another symbol table with the format: + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <B>Symbol Table Scratch-Pad Format</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Address of B-tree</td> + + <tr align=center> + <td colspan=4>Address of Name Heap</td> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Address of B-tree</td> + <td>This is the file address for the symbol table's + B-tree.</td> + </tr> + + <tr valign=top> + <td>Address of Name Heap</td> + <td>This is the file address for the symbol table's local + heap that stores the symbol names.</td> + </tr> + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <B>Symbolic Link Scratch-Pad Format</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4>Offset to Link Value</td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Offset to Link Value</td> + <td>The value of a symbolic link (that is, the name of the + thing to which it points) is stored in the local heap. + This field is the 4-byte offset into the local heap for + the start of the link value, which is null terminated.</td> + </tr> + </table> + </center> + + <h3><a name="LocalHeap">Disk Format: Level 1D - Local Heaps</a></h3> + + <p>A heap is a collection of small heap objects. Objects can be + inserted and removed from the heap at any time and the address + of a heap doesn't change once the heap is created. Note: this + is the "local" version of the heap mostly intended for the + storage of names in a symbol table. The storage of small + objects in a global heap is described below. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Local Heaps</b> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4>Heap Signature</td> + </tr> + + <tr align=center> + <td colspan=4>Reserved (zero)</td> + </tr> + + <tr align=center> + <td colspan=4>Data Segment Size</td> + </tr> + + <tr align=center> + <td colspan=4>Offset to Head of Free-list (<size> bytes)</td> + </tr> + + <tr align=center> + <td colspan=4>Address of Data Segment</td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Heap Signature</td> + <td>The valid ASCII 'HEAP' is used to indicate the + beginning of a heap. This gives file consistency + checking utilities a better chance of reconstructing a + damaged file.</td> + </tr> + + <tr valign=top> + <td>Data Segment Size</td> + <td>The total amount of disk memory allocated for the heap + data. This may be larger than the amount of space + required by the object stored in the heap. The extra + unused space holds a linked list of free blocks.</td> + </tr> + + <tr valign=top> + <td>Offset to Head of Free-list</td> + <td>This is the offset within the heap data segment of the + first free block (or all 0xff bytes if there is no free + block). The free block contains <size> bytes that + are the offset of the next free chunk (or all 0xff bytes + if this is the last free chunk) followed by <size> + bytes that store the size of this free chunk.</td> + </tr> + + <tr valign=top> + <td>Address of Data Segment</td> + <td>The data segment originally starts immediately after + the heap header, but if the data segment must grow as a + result of adding more objects, then the data segment may + be relocated to another part of the file.</td> + </tr> + </table> + </center> + + <p>Objects within the heap should be aligned on an 8-byte boundary. + + <h3><a name="GlobalHeap">Disk Format: Level 1E - Global Heap</a></h3> + + <p>Each HDF5 file has a global heap which stores various types of + information which is typically shared between datasets. The + global heap was designed to satisfy these goals: + + <ol type="A"> + <li>Repeated access to a heap object must be efficient without + resulting in repeated file I/O requests. Since global heap + objects will typically be shared among several datasets it's + probable that the object will be accessed repeatedly. + + <br><br> + <li>Collections of related global heap objects should result in + fewer and larger I/O requests. For instance, a dataset of + void pointers will have a global heap object for each + pointer. Reading the entire set of void pointer objects + should result in a few large I/O requests instead of one small + I/O request for each object. + + <br><br> + <li>It should be possible to remove objects from the global heap + and the resulting file hole should be eligible to be reclaimed + for other uses. + <br><br> + </ol> + + <p>The implementation of the heap makes use of the memory + management already available at the file level and combines that + with a new top-level object called a <em>collection</em> to + achieve Goal B. The global heap is the set of all collections. + Each global heap object belongs to exactly one collection and + each collection contains one or more global heap objects. For + the purposes of disk I/O and caching, a collection is treated as + an atomic object. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <B>Global Heap Collection</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4>Magic Number</td> + </tr> + + <tr align=center> + <td>Version</td> + <td colspan=3>Reserved</td> + </td> + + <tr align=center> + <td colspan=4>Collection Size</td> + </tr> + + <tr align=center> + <td colspan=4><br>Object 1<br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>Object 2<br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>...<br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>Object <em>N</em><br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>Object 0 (free space)<br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Magic Number</td> + <td>The magic number for global heap collections are the + four bytes `G', `C', `O', `L'.</td> + </tr> + + <tr valign=top> + <td>Version</td> + <td>Each collection has its own version number so that new + collections can be added to old files. This document + describes version zero of the collections. + </tr> + + <tr valign=top> + <td>Collection Data Size</td> + <td>This is the size in bytes of the entire collection + including this field. The default (and minimum) + collection size is 4096 bytes which is a typical file + system block size and which allows for 170 16-byte heap + objects plus their overhead.</td> + </tr> + + <tr valign=top> + <td>Object <em>i</em> for positive <em>i</em></td> <td>The + objects are stored in any order with no intervening unused + space.</td> + </tr> + + <tr valign=top> + <td>Object 0</td> + <td>Object zero, when present, represents the free space in + the collection. Free space always appears at the end of + the collection. If the free space is too small to store + the header for object zero (described below) then the + header is implied. + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <B>Global Heap Object</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=2>Object ID</td> + <td colspan=2>Reference Count</td> + </tr> + + <tr align=center> + <td colspan=4>Object Total Size</td> + </tr> + + <tr align=center> + <td colspan=4><br>Object Data<br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Object ID</td> + <td>Each object has a unique identification number within a + collection. The identification numbers are chosen so that + new objects have the smallest value possible with the + exception that the identifier `0' always refers to the + object which represents all free space within the + collection.</td> + </tr> + + <tr valign=top> + <td>Reference Count</td> + <td>All heap objects have a reference count field. An + object which is referenced from some other part of the + file will have a positive reference count. The reference + count for Object zero is always zero.</td> + </tr> + + <tr valign=top> + <td>Object Total Size</td> + <td>This is the total size in bytes of the object. It + includes all fields listed in this table.</td> + </tr> + + <tr valign=top> + <td>Object Data</td> + <td>The object data is treated as a one-dimensional array + of bytes to be interpreted by the caller.</td> + </tr> + </table> + </center> + + <h3><a name="FreeSpaceIndex">Disk Format: Level 1F - Free-Space + Index (NOT FULLY DEFINED)</a></h3> + + <p>The Free-Space Index is a collection of blocks of data, + dispersed throughout the file, which are currently not used by + any file objects. The blocks of data are indexed by a B-tree of + their length within the file. + + <p>Each B-Tree page is composed of the following entries and + B-tree management information, organized as follows: + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Free-Space Heap Page</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Free-Space Heap Signature</td> + <tr align=center> + <td colspan=4>B-Tree Left-Link Offset</td> + <tr align=center> + <td colspan=4><br>Length of Free-Block #1<br> <br></td> + <tr align=center> + <td colspan=4><br>Offset of Free-Block #1<br> <br></td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4><br>Length of Free-Block #n<br> <br></td> + <tr align=center> + <td colspan=4><br>Offset of Free-Block #n<br> <br></td> + <tr align=center> + <td colspan=4>"High" Offset</td> + <tr align=center> + <td colspan=4>Right-Link Offset</td> + </table> + </center> + + <p> + <dl> + <dt> The elements of the free-space heap page are described below: + <dd> + <dl> + <dt>Free-Space Heap Signature: (4 bytes) + <dd>The value ASCII: 'FREE' is used to indicate the + beginning of a free-space heap B-Tree page. This gives + file consistency checking utilities a better chance of + reconstructing a damaged file. + + <dt>B-Tree Left-Link Offset: (<offset> bytes) + <dd>This value is used to indicate the offset of all offsets + in the B-link-tree which are smaller than the value of the + offset in entry #1. This value is also used to indicate a + leaf node in the B-link-tree by being set to all ones. + + <dt>Length of Free-Block #n: (<length> bytes) + <dd>This value indicates the length of an un-used block in + the file. + + <dt>Offset of Free-Block #n: (<offset> bytes) + <dd>This value indicates the offset in the file of an + un-used block in the file. + + <dt>"High" Offset: (4-bytes) + <dd>This offset is used as the upper bound on offsets + contained within a page when the page has been split. + + <dt>Right-link Offset: (<offset> bytes) + <dd>This value is used to indicate the offset of the next + child to the right of the parent of this object directory + page. When there is no node to the right, this value is + all zeros. + </dl> + </dl> + + <p>The algorithms for searching and inserting objects in the + B-tree pages are described fully in the Lehman & Yao paper, + which should be read to provide a full description of the + B-Tree's usage. + + <h3><a name="DataObject">Disk Format: Level 2 - Data Objects </a></h3> + + <p>Data objects contain the real information in the file. These + objects compose the scientific data and other information which + are generally thought of as "data" by the end-user. All the + other information in the file is provided as a framework for + these data objects. + + <p>A data object is composed of header information and data + information. The header information contains the information + needed to interpret the data information for the data object as + well as additional "meta-data" or pointers to additional + "meta-data" used to describe or annotate each data object. + + <h3><a name="ObjectHeader"> + Disk Format: Level 2a - Data Object Headers</a></h3> + + <p>The header information of an object is designed to encompass + all the information about an object which would be desired to be + known, except for the data itself. This information includes + the dimensionality, number-type, information about how the data + is stored on disk (in external files, compressed, broken up in + blocks, etc.), as well as other information used by the library + to speed up access to the data objects or maintain a file's + integrity. The header of each object is not necessarily located + immediately prior to the object's data in the file and in fact + may be located in any position in the file. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <B>Object Headers</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=1 width="25%">Version # of Object Header</td> + <td colspan=1 width="25%">Alignment of Object Header Messages</td> + <td colspan=2 width="50%">Number of Header Messages</td> + </tr> + <tr align=center> + <td colspan=4>Object Reference Count</td> + </tr> + <tr align=center> + <td colspan=4><br>Total Object-Header Size<br><br></td> + </tr> + <tr align=center> + <td colspan=2>Header Message Type #1</td> + <td colspan=2>Size of Header Message Data #1</td> + </tr> + <tr align=center> + <td>Flags</td> + <td colspan=3>Reserved</td> + </tr> + <tr align=center> + <td colspan=4>Header Message Data #1 (variable size)</td> + </tr> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + </tr> + <tr align=center> + <td colspan=2>Header Message Type #n</td> + <td colspan=2>Size of Header Message Data #n</td> + </tr> + <tr align=center> + <td>Flags</td> + <td colspan=3>Reserved</td> + </tr> + <tr align=center> + <td colspan=4>Header Message Data #n (variable)</td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Version # of the object header</td> + <td>This value is used to determine the format of the + information in the object header. When the format of the + information in the object header is changed, the version # + is incremented and can be used to determine how the + information in the object header is formatted.</td> + </tr> + + <tr valign=top> + <td>Alignment of object header messages</td> + <td>This value is used to determine the byte-alignment of + messagesin the object header. Typically set to 4, which + aligns new messages on a 4-byte boundary in the object + header.</td> + </tr> + + <tr valign=top> + <td>Number of header messages</td> + <td>This value determines the number of messages listed in + this object header. This provides a fast way for software + to prepare storage for the messages in the header.</td> + </tr> + + <tr valign=top> + <td>Object Reference Count</td> + <td>This value specifies the number of references to this + object within the current file. References to the + data-object from external files are not tracked.</td> + </tr> + + <tr valign=top> + <td>Total Object-Header Size</td> + <td>This value specifies the total number of bytes of header + message data following this length field for the current + message as well as any continuation data located elsewhere + in the file.</td> + </tr> + + <tr valign=top> + <td>Header Message Type</td> + <td>The header message type specifies the type of + information included in the header message data following + the type along with a small amount of other information. + Bit 15 of the message type is set if the message is + constant (constant messages cannot be changed since they + may be cached in symbol table entries throughout the + file). The header message types for the pre-defined + header messages will be included in further discussion + below.</td> + </tr> + + <tr valign=top> + <td>Size of Header Message Data</td> + <td>This value specifies the number of bytes of header + message data following the header message type and length + information for the current message.</td> + </tr> + + <tr valign=top> + <td>Flags</td> + <td>This is a bit field with the following definition: + <dl> + <dt><code>0</code> + <dd>If set, the message data is constant. This is used + for messages like the data type message of a dataset. + <dt><code>1</code> + <dd>If set, the message is stored in the global heap and + the Header Message Data field contains a Shared Object + message. and the Size of Header Message Data field + contains the size of that Shared Object message. + <dt><code>2-7</code> + <dd>Reserved + </dl> + </td> + + <tr valign=top> + <td>Header Message Data</td> + <td>The format and length of this field is determined by the + header message type and size respectively. Some header + message types do not require any data and this information + can be eliminated by setting the length of the message to + zero.</td> + </tr> + </table> + </center> + + <p>The header message types and the message data associated with + them compose the critical "meta-data" about each object. Some + header messages are required for each object while others are + optional. Some optional header messages may also be repeated + several times in the header itself, the requirements and number + of times allowed in the header will be noted in each header + message description below. + + <P>The following is a list of currently defined header messages: + + <hr> + <h3><a name="NILMessage">Name: NIL</a></h3> + <b>Type: </b>0x0000<br> + <b>Length:</b> varies<br> + <b>Status:</b> Optional, may be repeated.<br> + <b>Purpose and Description:</b> The NIL message is used to + indicate a message + which is to be ignored when reading the header messages for a data object. + [Probably one which has been deleted for some reason.]<br> + <b>Format of Data:</b> Unspecified.<br> + <b>Examples:</b> None. + + + <hr> + <h3><a name="SimpleDataSpace">Name: Simple Data Space/a></h3> + + <b>Type: </b>0x0001<br> + <b>Length:</b> varies<br> + <b>Status:</b> One of the <em>Simple Data Space</em> or + <em>Data-Space</em> messages is required (but not both) and may + not be repeated.<br> + + <p>The <em>Simple Dimensionality</em> message describes the number + of dimensions and size of each dimension that the data object + has. This message is only used for datasets which have a + simple, rectilinear grid layout, datasets requiring a more + complex layout (irregularly or unstructured grids, etc) must use + the <em>Data-Space</em> message for expressing the space the + dataset inhabits. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Simple Data Space Message</b> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Dimensionality</td> + <tr align=center> + <td colspan=4>Dimension Flags</td> + <tr align=center> + <td colspan=4>Dimension Size #1 (<size> bytes)</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Dimension Size #n (<size> bytes)</td> + <tr align=center> + <td colspan=4>Dimension Maximum #1 (<size> bytes)</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Dimension Maximum #n (<size> bytes)</td> + <tr align=center> + <td colspan=4>Permutation Index #1</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Permutation Index #n</td> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Dimensionality</td> + <td>This value is the number of dimensions that the data + object has.</td> + </tr> + + <tr valign=top> + <td>Dimension Flags</td> + <td>This field is used to store flags to indicate the + presence of parts of this message. Bit 0 (counting from + the right) is used to indicate that maximum dimensions are + present. Bit 1 is used to indicate that permutation + indices are present for each dimension.</td> + </tr> + + <tr valign=top> + <td>Dimension Size #n (<size&rt; bytes)</td> + <td>This value is the current size of the dimension of the + data as stored in the file. The first dimension stored in + the list of dimensions is the slowest changing dimension + and the last dimension stored is the fastest changing + dimension.</td> + </tr> + + <tr valign=top> + <td>Dimension Maximum #n (<size&rt; bytes)</td> + <td>This value is the maximum size of the dimension of the + data as stored in the file. This value may be the special + value <UNLIMITED> (0xffffffff) which indicates that + the data may expand along this dimension indefinitely. If + these values are not stored, the maximum value of each + dimension is assumed to be the same as the current size + value.</td> + </tr> + + <tr valign=top> + <td>Permutation Index #n (4 bytes)</td> + <td>This value is the index permutation used to map + each dimension from the canonical representation to an + alternate axis for each dimension. If these values are + not stored, the first dimension stored in the list of + dimensions is the slowest changing dimension and the last + dimension stored is the fastest changing dimension.</td> + </tr> + </table> + </center> + + <h4>Examples</h4> + <dl> + <dt> Example #1 + <dd>A sample 640 horizontally by 480 vertically raster image + dimension header. The number of dimensions would be set to 2 + and the first dimension's size and maximum would both be set + to 480. The second dimension's size and maximum would both be + set to 640 +. + <dt>Example #2 + <dd>A sample 4 dimensional scientific dataset which is composed + of 30x24x3 slabs of data being written out in an unlimited + series every several minutes as timestep data (currently there + are five slabs). The number of dimensions is 4. The first + dimension size is 5 and it's maximum is <UNLIMITED>. The + second through fourth dimensions' size and maximum value are + set to 3, 24, and 30 respectively. + + <dt>Example #3 + <dd>A sample unlimited length text string, currently of length + 83. The number of dimensions is 1, the size of the first + dimension is 83 and the maximum of the first dimension is set + to <UNLIMITED>, allowing further text data to be + appended to the string or possibly the string to be replaced + with another string of a different size. (This could also be + stored as a scalar dataset with number-type set to "string") + </dl> + + <hr> + <h3><a name="DataSpaceMessage">Name: Data-Space (Fiber Bundle?)</a></h3> + <b>Type: </b>0x0002<br> + <b>Length:</b> varies<br> + + <b>Status:</b> One of the <em>Simple Dimensionality</em> or + <em>Data-Space</em> messages is required (but not both) and may + not be repeated.<br> <b>Purpose and Description:</b> The + <em>Data-Space</em> message describes space that the dataset is + mapped onto in a more comprehensive way than the <em>Simple + Dimensionality</em> message is capable of handling. The + data-space of a dataset encompasses the type of coordinate system + used to locate the dataset's elements as well as the structure and + regularity of the coordinate system. The data-space also + describes the number of dimensions which the dataset inhabits as + well as a possible higher dimensional space in which the dataset + is located within. + + <br> + <b>Format of Data:</b> + + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Data-Space Message Layout</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Mesh Type</td> + <tr align=center> + <td colspan=4>Logical Dimensionality</td> + </table> + </center> + + <p> + <dl> + <dt>The elements of the dimensionality message are described below: + <dd> + <dl> + <dt>Mesh Type: (unsigned 32-bit integer) + <dd>This value indicates whether the grid is + polar/spherical/cartesion, + structured/unstructured and regular/irregular. <br> + The mesh type value is broken up as follows: <br> + + <P> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Mesh-Type Layout</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=1>Mesh Embedding</td> + <td colspan=1>Coordinate System</td> + <td colspan=1>Structure</td> + <td colspan=1>Regularity</td> + </table> + </center> + The following are the definitions of mesh-type bytes: + <dl> + <dt>Mesh Embedding + <dd>This value indicates whether the dataset data-space + is located within + another dataspace or not: + <dl> <dl> + <dt><STANDALONE> + <dd>The dataset mesh is self-contained and is not + embedded in another mesh. + <dt><EMBEDDED> + <dd>The dataset's data-space is located within + another data-space, as + described in information below. + </dl> </dl> + <dt>Coordinate System + <dd>This value defines the type of coordinate system + used for the mesh: + <dl> <dl> + <dt><POLAR> + <dd>The last two dimensions are in polar + coordinates, higher dimensions are + cartesian. + <dt><SPHERICAL> + <dd>The last three dimensions are in spherical + coordinates, higher dimensions + are cartesian. + <dt><CARTESIAN> + <dd>All dimensions are in cartesian coordinates. + </dl> </dl> + <dt>Structure + <dd>This value defines the locations of the grid-points + on the axes: + <dl> <dl> + <dt><STRUCTURED> + <dd>All grid-points are on integral, sequential + locations, starting from 0. + <dt><UNSTRUCTURED> + <dd>Grid-points locations in each dimension are + explicitly defined and + may be of any numeric data-type. + </dl> </dl> + <dt>Regularity + <dd>This value defines the locations of the dataset + points on the grid: + <dl> <dl> + <dt><REGULAR> + <dd>All dataset elements are located at the + grid-points defined. + <dt><IRREGULAR> + <dd>Each dataset element has a particular + grid-location defined. + </dl> </dl> + </dl> + <p>The following grid combinations are currently allowed: + <dl> <dl> + <dt><POLAR-STRUCTURED-REGULAR> + <dt><SPHERICAL-STRUCTURED-REGULAR> + <dt><CARTESIAN-STRUCTURED-REGULAR> + <dt><POLAR-UNSTRUCTURED-REGULAR> + <dt><SPHERICAL-UNSTRUCTURED-REGULAR> + <dt><CARTESIAN-UNSTRUCTURED-REGULAR> + <dt><CARTESIAN-UNSTRUCTURED-IRREGULAR> + </dl> </dl> + All of the above grid types can be embedded within another + data-space. + <br> <br> + <dt>Logical Dimensionality: (unsigned 32-bit integer) + <dd>This value is the number of dimensions that the dataset occupies. + + <P> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Data-Space Embedded Dimensionality Information</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Embedded Dimensionality</td> + <tr align=center> + <td colspan=4>Embedded Dimension Size #1</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Embedded Dimension Size #n</td> + <tr align=center> + <td colspan=4>Embedded Origin Location #1</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Embedded Origin Location #n</td> + </table> + </center> + + <dt>Embedded Dimensionality: (unsigned 32-bit integer) + <dd>This value is the number of dimensions of the space the + dataset is located + within. i.e. a planar dataset located within a 3-D space, + or a 3-D dataset + which is a subset of another 3-D space, etc. + <dt>Embedded Dimension Size: (unsigned 32-bit integer) + <dd>These values are the sizes of the dimensions of the + embedded data-space + that the dataset is located within. + <dt>Embedded Origin Location: (unsigned 32-bit integer) + <dd>These values comprise the location of the dataset's + origin within the embedded data-space. + </dl> + </dl> + [Comment: need some way to handle different orientations of the + dataset data-space + within the embedded data-space]<br> + + <P> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Data-Space Structured/Regular Grid Information</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Logical Dimension Size #1</td> + <tr align=center> + <td colspan=4>Logical Dimension Maximum #1</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Logical Dimension Size #n</td> + <tr align=center> + <td colspan=4>Logical Dimension Maximum #n</td> + </table> + </center> + + <p> + <dl> + <dt>The elements of the dimensionality message are described below: + <dd> + <dl> + <dt>Logical Dimension Size #n: (unsigned 32-bit integer) + <dd>This value is the current size of the dimension of the + data as stored in + the file. The first dimension stored in the list of + dimensions is the slowest + changing dimension and the last dimension stored is the + fastest changing + dimension. + <dt>Logical Dimension Maximum #n: (unsigned 32-bit integer) + <dd>This value is the maximum size of the dimension of the + data as stored in + the file. This value may be the special value + <UNLIMITED> which + indicates that the data may expand along this dimension + indefinitely. + </dl> + </dl> + <P> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Data-Space Structured/Irregular Grid Information</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4># of Grid Points in Dimension #1</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4># of Grid Points in Dimension #n</td> + <tr align=center> + <td colspan=4>Data-Type of Grid Point Locations</td> + <tr align=center> + <td colspan=4>Location of Grid Points in Dimension #1</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Location of Grid Points in Dimension #n</td> + </table> + </center> + + <P> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <B>HDF5 Data-Space Unstructured Grid Information</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4># of Grid Points</td> + <tr align=center> + <td colspan=4>Data-Type of Grid Point Locations</td> + <tr align=center> + <td colspan=4>Grid Point Locations<br>.<br>.<br></td> + </table> + </center> + + <h4><a name="DataSpaceExample">Examples:</a></h4> + Need some good examples, this is complex! + + + <hr> + <h3><a name="DataTypeMessage">Name: Data Type</a></h3> + + <b>Type:</b> 0x0003<br> + <b>Length:</b> variable<br> + <b>Status:</b> One required per dataset<br> + + <p>The data type message defines the data type for each data point + of a dataset. A data type can describe an atomic type like a + fixed- or floating-point type or a compound type like a C + struct. A data type does not, however, describe how data points + are combined to produce a dataset. Data types are stored on disk + as a data type message, which is a list of data type classes and + their associated properties. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Data Type Message</b> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td>Type Class</td> + <td colspan=3>Class Bit Field</td> + </tr> + + <tr align=center> + <td colspan=4>Size in Bytes (4 bytes)</td> + </tr> + + <tr align=center> + <td colspan=4><br><br>Properties<br><br><br></td> + </tr> + </table> + </center> + + <p>The Class Bit Field and Properties fields vary depending + on the Type Class. The type class is one of: 0 (fixed-point + number), 1 (floating-point number), 2 (date and time), 3 (text + string), 4 (bit field), 5 (opaque), 6 (compound). The Class Bit + Field is zero and the size of the Properties field is zero + except for the cases noted here. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Bit Field for Fixed-Point Numbers (Class 0)</b> + </caption> + + <tr align=center> + <th width="10%">Bits</th> + <th width="90%">Meaning</th> + </tr> + + <tr> + <td>0</td> + <td><b>Byte Order.</b> If zero, byte order is little-endian; + otherwise, byte order is big endian.</td> + </tr> + + <tr> + <td>1, 2</td> + <td><b>Padding type.</b> Bit 1 is the lo_pad type and bit 2 + is the hi_pad type. If a datum has unused bits at either + end, then the lo_pad or hi_pad bit is copied to those + locations.</td> + </tr> + + <tr> + <td>3</td> + <td><b>Signed.</b> If this bit is set then the fixed-point + number is in 2's complement form.</td> + </tr> + + <tr> + <td>4-23</td> + <td>Reserved (zero).</td> + </tr> + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Properties for Fixed-Point Numbers (Class 0)</b> + </caption> + + <tr align=center> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr align=center> + <td colspan=2>Bit Offset</td> + <td colspan=2>Bit Precision</td> + </tr> + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Bit Field for Floating-Point Numbers (Class 1)</b> + </caption> + + <tr align=center> + <th width="10%">Bits</th> + <th width="90%">Meaning</th> + </tr> + + <tr> + <td>0</td> + <td><b>Byte Order.</b> If zero, byte order is little-endian; + otherwise, byte order is big endian.</td> + </tr> + + <tr> + <td>1, 2, 3</td> + <td><b>Padding type.</b> Bit 1 is the low bits pad type, bit 2 + is the high bits pad type, and bit 3 is the internal bits + pad type. If a datum has unused bits at either or between + the sign bit, exponent, or mantissa, then the value of bit + 1, 2, or 3 is copied to those locations.</td> + </tr> + + <tr> + <td>4-5</td> + <td><b>Normalization.</b> The value can be 0 if there is no + normalization, 1 if the most significant bit of the + mantissa is always set (except for 0.0), and 2 if the most + signficant bit of the mantissa is not stored but is + implied to be set. The value 3 is reserved and will not + appear in this field.</td> + </tr> + + <tr> + <td>6-7</td> + <td>Reserved (zero).</td> + </tr> + + <tr> + <td>8-15</td> + <td><b>Sign.</b> This is the bit position of the sign + bit.</td> + </tr> + + <tr> + <td>16-23</td> + <td>Reserved (zero).</td> + </tr> + + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Properties for Floating-Point Numbers (Class 1)</b> + </caption> + + <tr align=center> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr align=center> + <td colspan=2>Bit Offset</td> + <td colspan=2>Bit Precision</td> + </tr> + + <tr align=center> + <td>Exponent Location</td> + <td>Exponent Size in Bits</td> + <td>Mantissa Location</td> + <td>Mantissa Size in Bits</td> + </tr> + + <tr align=center> + <td colspan=4>Exponent Bias</td> + </tr> + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <b>Bit Field for Compound Types (Class 6)</b> + </caption> + + <tr align=center> + <th width="10%">Bits</th> + <th width="90%">Meaning</th> + </tr> + + <tr> + <td>0-15</td> + <td><b>Number of Members.</b> This field contains the number + of members defined for the compound data type. The member + definitions are listed in the Properties field of the data + type message. + </tr> + + <tr> + <td>15-23</td> + <td>Reserved (zero).</td> + </tr> + </table> + </center> + + <p>The Properties field of a compound data type is a list of the + member definitions of the compound data type. The member + definitions appear one after another with no intervening bytes. + The member types are described with a recursive data type + message. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <b>Properties for Compound Types (Class 6)</b> + </caption> + + <tr align=center> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr align=center> + <td colspan=4><br><br>Name (null terminated, multiple of + four bytes)<br><br><br></td> + </tr> + + <tr align=center> + <td colspan=4>Byte Offset of Member in Compound Instance</td> + </tr> + + <tr> + <td>Dimensionality</td> + <td colspan=3>reserved</td> + </tr> + + <tr align=center> + <td colspan=4>Size of Dimension 0 (optional)</td> + </tr> + + <tr align=center> + <td colspan=4>Size of Dimension 1 (optional)</td> + </tr> + + <tr align=center> + <td colspan=4>Size of Dimension 2 (optional)</td> + </tr> + + <tr align=center> + <td colspan=4>Size of Dimension 3 (optional)</td> + </tr> + + <tr align=center> + <td colspan=4>Dimension Permutation</td> + </tr> + + <tr align=center> + <td colspan=4><br><br>Member Type Message<br><br><br></td> + </tr> + + </table> + </center> + + <p>Data type examples are <a href="Datatypes.html">here</a>. + + + <hr> + <h3><a name="ReservedMessage_0004">Name: Reserved - Not Assigned + Yet</a></h3> + <b>Type:</b> 0x0004<BR> + <b>Length:</b> N/A<BR> + <b>Status:</b> N/A<BR> + + + <hr> + <h3><a name="ReservedMessage_0005">Name: Reserved - Not Assigned + Yet</a></h3> + <b>Type:</b> 0x0005<br> + <b>Length:</b> N/A<br> + <b>Status:</b> N/A<br> + + + + <hr> + <h3><a name="CompactDataStorageMessage">Name: Data Storage - Compact</a></h3> + + <b>Type:</b> 0x0006<br> + <b>Length:</b> varies<br> + <b>Status:</b> Optional, may not be repeated.<br> + + <p>This message indicates that the data for the data object is + stored within the current HDF file by including the actual + data within the header data for this message. The data is + stored internally in + the "normal" format, i.e. in one chunk, un-compressed, etc. + + <P>Note that one and only one of the "Data Storage" headers can be + stored for each data object. + + <P><b>Format of Data:</b> The message data is actually composed + of dataset data, so the format will be determined by the dataset + format. + + <h4><a name="CompactDataStorageExample">Examples:</a></h4> + [very straightforward] + + <hr> + <h3><a name="ExternalFileListMessage">Name: Data Storage - + External Data Files</a></h3> + <b>Type:</b> 0x0007<BR> + <b>Length:</b> varies<BR> + <b>Status:</b> Optional, may not be repeated.<BR> + + <p><b>Purpose and Description:</b> The external object message + indicates that the data for an object is stored outside the HDF5 + file. The filename of the object is stored as a Universal + Resource Location (URL) of the actual filename containing the + data. An external file list record also contains the byte offset + of the start of the data within the file and the amount of space + reserved in the file for that data. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>External File List Message</b> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4><br>Heap Address<br><br></td> + </tr> + + <tr align=center> + <td colspan=2>Allocated Slots</td> + <td colspan=2>Used Slots</td> + </tr> + + <tr align=center> + <td colspan=4>Reserved</td> + </tr> + + <tr align=center> + <td colspan=4><br>Slot Definitions...<br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Heap Address</td> + <td>This is the address of a local name heap which contains + the names for the external files. The name at offset zero + in the heap is always the empty string.</td> + </tr> + + <tr valign=top> + <td>Allocated Slots</td> + <td>The total number of slots allocated in the message. Its + value must be at least as large as the value contained in + the Used Slots field.</td> + </tr> + + <tr valign=top> + <td>Used Slots</td> + <td>The number of initial slots which contain valid + information. The remaining slots are zero filled.</td> + </tr> + + <tr valign=top> + <td>Reserved</td> + <td>This field is reserved for future use.</td> + </tr> + + <tr valign=top> + <td>Slot Definitions</td> + <td>The slot definitions are stored in order according to + the array addresses they represent. If more slots have + been allocated than what has been used then the defined + slots are all at the beginning of the list.</td> + </tr> + </table> + </center> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>External File List Slot</b> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4><br>Name Offset (<size> bytes)<br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>File Offset (<size> bytes)<br><br></td> + </tr> + + <tr align=center> + <td colspan=4><br>Size<br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Name Offset (<size> bytes)</td> + <td>The byte offset within the local name heap for the name + of the file. File names are stored as a URL which has a + protocol name, a host name, a port number, and a file + name: + <code><em>protocol</em>:<em>port</em>//<em>host</em>/<em>file</em></code>. + If the protocol is omitted then "file:" is assumed. If + the port number is omitted then a default port for that + protocol is used. If both the protocol and the port + number are omitted then the colon can also be omitted. If + the double slash and host name are omitted then + "localhost" is assumed. The file name is the only + mandatory part, and if the leading slash is missing then + it is relative to the application's current working + directory (the use of relative names is not + recommended).</td> + </tr> + + <tr valign=top> + <td>File Offset (<size> bytes)</td> + <td>This is the byte offset to the start of the data in the + specified file. For files that contain data for a single + dataset this will usually be zero.</td> + </tr> + + <tr valign=top> + <td>Size</td> + <td>This is the total number of bytes reserved in the + specified file for raw data storage. For a file that + contains exactly one complete dataset which is not + extendable, the size will usually be the exact size of the + dataset. However, by making the size larger one allows + HDF5 to extend the dataset. The size can be set to a value + larger than the entire file since HDF5 will read zeros + past the end of the file without failing.</td> + </tr> + </table> + </center> + + + <hr> + <h3><a name="LayoutMessage">Name: Data Storage - Layout</a></h3> + + <b>Type:</b> 0x0008<BR> + <b>Length:</b> varies<BR> + <b>Status:</b> Required for datasets, may not be repeated. + + <p><b>Purpose and Description:</b> Data layout describes how the + elements of a multi-dimensional array are arranged in the linear + address space of the file. Two types of data layout are + supported: + + <ol> + <li>The array can be stored in one contiguous area of the file. + The layout requires that the size of the array be constant and + does not permit chunking or compression. The message stores + the total size of the array and the offset of an element from + the beginning of the storage area is computed as in C. + + <li>The array domain can be regularly decomposed into chunks and + each chunk is allocated separately. This layout supports + arbitrary element traversals and compression and the chunks + can be distributed across external raw data files (these + features are described in other messages). The message stores + the size of a chunk instead of the size of the entire array; + the size of the entire array can be calculated by traversing + the B-tree that stores the chunk addresses. + </ol> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <B>Data Layout Message</B> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4><br>Address<br><br></td> + </tr> + + <tr align=center> + <td>Dimensionality</td> + <td>Layout Class</td> + <td colspan=2>Reserved</td> + </tr> + + <tr align=center> + <td colspan=4>Reserved (4-bytes)</td> + </tr> + + <tr align=center> + <td colspan=4>Dimension 0 (4-bytes)</td> + </tr> + + <tr align=center> + <td colspan=4>Dimension 1 (4-bytes)</td> + </tr> + + <tr align=center> + <td colspan=4>...</td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Address</td> + <td>For contiguous storage, this is the address of the first + byte of storage. For chunked storage this is the address + of the B-tree that is used to look up the addresses of the + chunks.</td> + </tr> + + <tr valign=top> + <td>Dimensionality</td> + <td>An array has a fixed dimensionality. This field + specifies the number of dimension size fields later in the + message.</td> + </tr> + + <tr valign=top> + <td>Layout Class</td> + <td>The layout class specifies how the other fields of the + layout message are to be interpreted. A value of one + indicates contiguous storage while a value of two + indicates chunked storage. Other values will be defined + in the future.</td> + </tr> + + <tr valign=top> + <td>Dimensions</td> + <td>For contiguous storage the dimensions define the entire + size of the array while for chunked storage they define + the size of a single chunk.</td> + </tr> + </table> + </center> + + + <hr> + <h3><a name="ReservedMessage_0009">Name: Reserved - Not Assigned Yet</a></h3> + <b>Type:</b> 0x0009<BR> + <b>Length:</b> N/A<BR> + <b>Status:</b> N/A<BR> + <b>Purpose and Description:</b> N/A<BR> + <b>Format of Data:</b> N/A + + <hr> + <h3><a name="ReservedMessage_000A">Name: Reserved - Not Assigned Yet</a></h3> + <b>Type:</b> 0x000A<BR> + <b>Length:</b> N/A<BR> + <b>Status:</b> N/A<BR> + <b>Purpose and Description:</b> N/A<BR> + <b>Format of Data:</b> N/A + + <hr> + <h3><a name="CompressionMessage">Name: Data Storage - Compressed</a></h3> + <b>Type:</b> 0x000B<BR> + <b>Length:</b> varies<BR> + <b>Status:</b> Optional, may not be repeated. + + <p><b>Purpose and Description:</b> Compressed objects are + datasets which are stored in an HDF file after they have been + compressed. The encoding algorithm and its parameters are + stored in a Compression Message in the object header of the + dataset. + + <p> + <center> + <table border align=center cellpadding=4 witdh="80%"> + <caption align=top> + <b>Compression Message</b> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td>Method</td> + <td>Flags</td> + <td colspan=2>Client Data Size</td> + </tr> + + <tr align=center> + <td colspan=4><br>Client Data<br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Method</td> + <td>The compression method is a value between zero and 255, + inclusive, that is used as a index into a compression + method lookup table. The value zero indicates no + compression. The values one through 15, inclusive, are + reserved for methods defined by NCSA. All other values + are user-defined compression methods.</td> + </tr> + + <tr valign=top> + <td>Flags</td> + <td>Eight bits of flags which are passed to the compression + algorithm. There meaning depends on the compression + method.</td> + </tr> + + <tr valign=top> + <td>Client Data Size</td> + <td>The size in bytes of the optional Client Data + field.</td> + </tr> + + <tr valign=top> + <td>Client Data</td> + <td>Additional information needed by the compression method + can be stored in this field. The data will be passed to + the compression algorithm as a void pointer.</td> + </tr> + </table> + </center> + + <p>Sometimes additional redundancy can be added to the data before + it's compressed to result in a better compression ratio. The + library doesn't specifically support modeling methods to add + redundancy, but the effect can be achieved through the use of + user-defined data types. + + <p>The library uses the following compression methods. + <center> + <table align=center width="80%"> + <tr valign=top> + <td><code>0</code></td> + <td>No compression: The blocks of data are stored in + their raw format.</td> + </tr> + + <tr valign=top> + <td><code>1</code></td> + <td>Deflation: This is the same algorithm used by + GNU gzip which is a combination Huffman and LZ77 + dictionary encoder. The <code>libz</code> library version + 1.1.2 or later must be available.</td> + </tr> + + <tr valign=top> + <td><code>2</code></td> + <td>Run length encoding: Not implemented yet.</td> + </tr> + + <tr valign=top> + <td><code>3</code></td> + <td>Adaptive Huffman: Not implemented yet.</td> + </tr> + + <tr valign=top> + <td><code>4</code></td> + <td>Adaptive Arithmetic: Not implemented yet.</td> + </tr> + + <tr valign=top> + <td><code>5</code></td> + <td>LZ78 Dictionary Encoding: Not implemented yet.</td> + </tr> + + <tr valign=top> + <td><code>6</code></td> + <td>Adaptive Lempel-Ziv: Similar to Unix + <code>compress</code>. Not implemented yet.</td> + </tr> + + <tr valign=top> + <td><code>7-15</code></td> + <td>Reserved for future use.</td> + </tr> + + <tr valign=top> + <td><code>16-255</code></td> + <td>User-defined.</td> + </tr> + </table> + </center> + + <p>The compression is applied independently to each chunk of + storage (after data space and data type conversions). If the + compression is unable to make the chunk smaller than it would + normally be, the chunk is stored without compression. At the + library's discretion, chunks which fail the compression can also + be stored in their raw format. + + <!-- + <hr> + <h3><a name="BackPointerMessage">Name: Back-Pointer List</a></h3> + <b>Type:</b> 0x000C<BR> + <b>Length:</b> varies<BR> + <b>Status:</b> Optional, may be repeated.<BR> + <b>Purpose and Description:</b> The back-pointer message contains a list of + other objects which reference the current object and a reference count of the + number the current object is referenced. External references (i.e. references + to objects in the current HDF file from outside HDF files) are not + counted.<BR> + <b>Format of Data:</b> + + <P> + <center> + <table border cellpadding=4 width=60%> + <caption align=bottom> + <B>HDF5 Back-Pointer Message Layout</B> + </caption> + + <tr align=center> + <th width=25%>byte</th> + <th width=25%>byte</th> + <th width=25%>byte</th> + <th width=25%>byte</th> + + <tr align=center> + <td colspan=4>Total Reference Count</td> + <tr align=center> + <td colspan=4>Dataset offset of Object #1</td> + <tr align=center> + <td colspan=4>Reference Count of Object #1</td> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + <tr align=center> + <td colspan=4>Dataset offset of Object #n</td> + <tr align=center> + <td colspan=4>Reference Count of Object #n</td> + </table> + </center> + + <p> + <dl> + <dt>The elements of the back-pointer message are described below: + <dd> + <dl> + <dt>Total Reference Count: (32-bit unsigned integer) + <dd>This value stores the total number of times that the current dataset is + referenced by other objects within the file. + <dt>Dataset offset of Object: (<offset>-byte signed integer) + <dd>This is the dataset offset of an object in the current file which contains a pointer + to the current object. + <dt>Reference Count of Object: (32-bit unsigned integer) + <dd>This value stores the number of times that the dataset (above) references the + current object. + </dl> + </dl> + + <h4><a name="BackPointerExample">Examples:</a></h4> + <dl> + <dt>Example #1 + <dd>4 objects in an HDF file (Offsets: 1, 2, 3, 4) reference a fifth + object in the file (offset: 5) once each. The fifth object has a header message + containing a back-pointer message with the following information: + + <pre> + Total Reference Count: 4 + Offset of Object #1: 1 + Reference Count of Object #1: 1 + Offset of Object #2: 2 + Reference Count of Object #2: 1 + Offset of Object #3: 3 + Reference Count of Object #3: 1 + Offset of Object #4: 4 + Reference Count of Object #4: 1 + </pre> + <dt>Example #2 + <dd>An object in an HDF file (offset: 1) references another object in the same + HDF file (offset: 10) fourteen times. A second object (offset: 4) references object + offset:10 seven times. Object offset:10 has the following back-pointer message: + + <pre> + Total Reference Count: 21 + Offset of Object #1: 1 + Reference Count of Object #1: 14 + Offset of Object #2: 4 + Reference Count of Object #2: 7 + </pre> + </dl> + --> + + <hr> + <h3><a name="AttributeListMessage">Name: Attribute List</a></h3> + <b>Type:</b> 0x000C<BR> + <b>Length:</b> varies<BR> + <b>Status:</b> Optional, may be repeated.<BR> + + <p><b>Purpose and Description:</b> The <em>Attribute List</em> + message is used to list objects in the HDF file which are used + as attributes, or "meta-data" about the current object. Other + objects can be used as attributes for either the entire object + or portions of the current object. The attribute list is + composed of two lists of objects, the first being simple + attributes about the entire dataset, and the second being + pointers attribute objects about the entire dataset. Partial + dataset pointers are currently unspecified and + unimplemented. + + <p><b>Format of Data:</b> + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=bottom> + <b>HDF5 Attribute-List Message Layout</b> + </caption> + + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <td colspan=4>Attribute List Flags</td> + </tr> + <tr align=center> + <td colspan=4># of Simple Attributes</td> + </tr> + <tr align=center> + <td colspan=4>Simple Attribute #1 Name Offset</td> + </tr> + <tr align=center> + <td colspan=4>Simple Attribute #1 Data-Type</td> + </tr> + <tr align=center> + <td colspan=4>Simple Attribute #1 Rank</td> + </tr> + <tr align=center> + <td colspan=4>Simple Attribute #1 Dim #1 Size</td> + </tr> + <tr align=center> + <td colspan=4>Simple Attribute #1 Dim #2 Size</td> + </tr> + <tr align=center> + <td colspan=4>Simple Attribute #1 Dim #3 Size</td> + </tr> + <tr align=center> + <td colspan=4>Simple Attribute #1 Dim #4 Size</td> + </tr> + <tr align=center> + <td colspan=4>Simple Attribute #1 Data Offset</td> + </tr> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + </tr> + <tr align=center> + <td colspan=4>Simple Attribute #n Name Offset</td> + </tr> + <tr align=center> + <td colspan=4>Simple Attribute #n Data-Type</td> + </tr> + <tr align=center> + <td colspan=4>Simple Attribute #n Rank</td> + </tr> + <tr align=center> + <td colspan=4>Simple Attribute #n Dim #1 Size</td> + </tr> + <tr align=center> + <td colspan=4>Simple Attribute #n Dim #2 Size</td> + </tr> + <tr align=center> + <td colspan=4>Simple Attribute #n Dim #3 Size</td> + </tr> + <tr align=center> + <td colspan=4>Simple Attribute #n Dim #4 Size</td> + </tr> + <tr align=center> + <td colspan=4>Simple Attribute #n Data Offset</td> + </tr> + <tr align=center> + <td colspan=4># of Complex Attributes</td> + </tr> + <tr align=center> + <td colspan=4>Pointer to Complex Attribute #1</td> + </tr> + <tr align=center> + <td colspan=4>.<br>.<br>.<br></td> + </tr> + <tr align=center> + <td colspan=4>Pointer to Complex Attribute #n</td> + </tr> + </table> + </center> + + <p> + <dl> + <dt>The elements of the attribute list message are described below: + <dd> + <dl> + <dt>Attribute List Flags: (unsigned 32-bit integer) + <dd>These flags indicate the presence of simple and complex + lists of attributes for this dataset. Bit 0 indicates the + presence of a list of simple attributes and Bit 1 + indicates the presence of a list of complex attributes. + + <dt># of Simple Attributes: (unsigned 32-bit integer) + <dd>This indicates the number of simple attributes for this + dataset. + + <dt>Simple Attribute #n Name Offset: (unsigned 32-bit integer) + <dd>This is the offset of the simple attribute's name in the + global small-data heap. + + <dt>Simple Attribute #n Data-type: (unsigned 32-bit integer) + <dd>This is a simple data-type, which indicates the type of + data used for the attribute. + + <dt>Simple Attribute #n Rank: (unsigned 32-bit integer) + <dd>This is the number of dimensions of the attribute, + limited to four or less. + + <dt>Simple Attribute #n Dim #n Size: (unsigned 32-bit integer) + <dd>This is the size of the attribute's n'th dimension, + which is stored in the canonical order for dimensions + (i.e. no permutations of the indices are allowed). + + <dt>Simple Attribute #n Data Offset: (unsigned 32-bit integer) + <dd>This is the offset of the simple attribute's data in the + global small-data. + + <dt># of Complex Attributes: (unsigned 32-bit integer) + <dd>This indicates the number of complex attributes for this + dataset. + + <dt>Pointer to Complex Attribute #n: (unsigned 32-bit integer) + <dd>This is the small-data heap offset of the name of the + attribute object in the file. + </dl> + </dl> + + <p>[<b>Note:</b> It has been suggested that each attribute have an + additional "units" field, so this is being considered.] + + <h4><a name="AttributeListExample">Examples:</a></h4> + [Comment: need examples.] + + <hr> + <h3><a name="NameMessage">Name: Object Name</a></h3> + <b>Type:</b> 0x000D<BR> + <b>Length:</b> varies<BR> + <b>Status:</b> Optional [required?], may not be repeated.<BR> + <b>Purpose and Description:</b> The object name is designed to be a short + description of the instance of the data object (the class may be a short + description of the "type" of the object). An object name is a sequence of + non-zero ('\0') ASCII characters with no other formatting included by the + library.<BR> + <b>Format of Data:</b>The data for the object name is just a sequence of ASCII + characters with no special formatting. + + <hr> + <h3><a name="ModifiedMessage">Name: Object Modification Date & Time</a></h3> + <b>Type:</b> 0x000E<BR> + <b>Length:</b> fixed<BR> + <b>Status:</b> Required?, may not be repeated.<BR> + <b>Purpose and Description:</b> The object modification date and time is a + timestamp which indicates (using ISO8601 date and time format) the last + modification of a data object.<BR> + <b>Format of Data:</b> + The date is represented as a fixed length ASCII string according to the + "complete calendar date representation, without hyphens" listed in the ISO8601 + standard.<br> + The time of day is represented as a fixed length ASCII string according + to the "complete local time of day representation, without hyphens" + listed in the ISO8601 standard. + + <h4><a name="ModifiedExample">Examples:</a></h4> + "February 14, 1993, 1:10pm and 30 seconds" is represented as "19930214131030" in + the ISO standard format. + + <hr> + <h3><a name="SharedMessage">Name: Shared Object Message</a></h3> + <b>Type:</b> 0x000F<br> + <b>Length:</b> 4 Bytes<br> + <b>Status:</b> Optional, may be repeated. + + <p>A constant message can be shared among several object headers + by writing that message in the global heap and having the object + headers all point to it. The pointing is accomplished with a + Shared Object message which is understood directly by the object + header layer of the library and never actually appears as a + message in the file. It is also possible to have a message of + one object header point to a message in some other object + header, but care must be exercised to prevent cycles. + + <p>If a message is shared, then the message appears in the global + heap and its message ID appears in the Header Message Type + field of the object header. Also, the Flags field in the object + header for that message will have bit two set (the + <code>H5O_FLAG_SHARED</code> bit). The message body in the + object header will be that of a Shared Object message defined + here and not that of the pointed-to message. + + <p> + <center> + <table border cellpadding=4 width="80%"> + <caption align=top> + <b>Shared Message Message</b> + </caption> + + <tr align=center> + <th width="25%">byte</td> + <th width="25%">byte</td> + <th width="25%">byte</td> + <th width="25%">byte</td> + </tr> + + <tr align=center> + <td colspan=4>Flags</td> + </tr> + + <tr align=center> + <td colspan=4><br>Pointer<br><br></td> + </tr> + </table> + </center> + + <p> + <center> + <table align=center width="80%"> + <tr> + <th width="30%">Field Name</th> + <th width="70%">Description</th> + </tr> + + <tr valign=top> + <td>Flags</td> + <td>The Shared Message Message is a pointer to a Shared + Message. The actual shared message can appear in either + the global heap or in some other object header and this + field specifies which form is used. If the value is zero + then the actual message is the first such message in some + other object header; otherwise the actual message is + stored in the global heap.</td> + </tr> + + <tr valign=top> + <td>Pointer</td> + <td>This field points to the actual message. The format of + the pointer depends on the value of the Flags field. If + the actual message is in the global heap then the pointer + is the file address of the global heap collection that + holds the message, and a four-byte index into that + collection. Otherwise the pointer is a symbol table entry + that points to some other object header.</td> + </tr> + </table> + </center> + + +<hr> +<h3><a name="ContinuationMessage">Name: Object Header Continuation</a></h3> +<b>Type:</b> 0x0010<BR> +<b>Length:</b> fixed<BR> +<b>Status:</b> Optional, may be repeated.<BR> +<b>Purpose and Description:</b> The object header continuation is the location +in the file of more header messages for the current data object. This can be +used when header blocks are large, or likely to change over time.<BR> +<b>Format of Data:</b><p> + The object header continuation is formatted as follows (assuming a 4-byte +length & offset are being used in the current file): + +<P> +<center> +<table border cellpadding=4 width=60%> +<caption align=bottom> +<B>HDF5 Object Header Continuation Message Layout</B> +</caption> + +<tr align=center> +<th width=25%>byte</th> +<th width=25%>byte</th> +<th width=25%>byte</th> +<th width=25%>byte</th> + +<tr align=center> +<td colspan=4>Header Continuation Offset</td> +<tr align=center> +<td colspan=4>Header Continuation Length</td> +</table> +</center> + +<P> +<dl> +<dt>The elements of the Header Continuation Message are described below: +<dd> +<dl> +<dt>Header Continuation Offset: (<offset> bytes) +<dd>This value is the offset in bytes from the beginning of the file where the +header continuation information is located. +<dt>Header Continuation Length: (<length> bytes) +<dd>This value is the length in bytes of the header continuation information in +the file. +</dl> +</dl> + +<h4><a name="ContinuationExample">Examples:</a></h4> + [straightforward] + +<hr> +<h3><a name="SymbolTableMessage">Name: Symbol Table Message</a></h3> +<b>Type:</b> 0x0011<BR> +<b>Length:</b> fixed<BR> +<b>Status:</b> Required for symbol tables, may not be repeated.<BR> +<b>Purpose and Description:</b> Each symbol table has a B-tree and a +name heap which are pointed to by this message.<BR> +<b>Format of data:</b> +<p>The symbol table message is formatted as follows: + +<p> +<center> +<table border cellpadding=4 width="80%"> +<caption align=bottom> +<b>HDF5 Object Header Symbol Table Message Layout</b> +</caption> + +<tr align=center> +<th width="25%">byte</th> +<th width="25%">byte</th> +<th width="25%">byte</th> +<th width="25%">byte</th> + +<tr align=center> +<td colspan=4>B-Tree Address</td> + +<tr align=center> +<td colspan=4>Heap Address</td> +</table> +</center> + +<P> +<dl> +<dt>The elements of the Symbol Table Message are described below: +<dd> +<dl> +<dt>B-tree Address (<offset> bytes) +<dd>This value is the offset in bytes from the beginning of the file +where the B-tree is located. +<dt>Heap Address (<offset> bytes) +<dd>This value is the offset in bytes from the beginning of the file +where the symbol table name heap is located. +</dl> +</dl> + +<h3><a name="SharedObjectHeader">Disk Format: Level 2b - Shared Data Object Headers</a></h3> +<P>In order to share header messages between several dataset objects, object +header messages may be placed into the global small-data heap. Since these +messages require additional information beyond the basic object header message +information, the format of the shared message is detailed below. + +<BR> <BR> +<center> +<table border cellpadding=4 width=60%> +<caption align=bottom> +<B>HDF5 Shared Object Header Message</B> +</caption> + +<tr align=center> +<th width=25%>byte</th> +<th width=25%>byte</th> +<th width=25%>byte</th> +<th width=25%>byte</th> + +<tr align=center> +<td colspan=4>Reference Count of Shared Header Message</td> +<tr align=center> +<td colspan=4><br> Shared Object Header Message<br> <br></td> +</table> +</center> + +<p> +<dl> +<dt> The elements of the shared object header message are described below: +<dd> +<dl> +<dt>Reference Count of Shared Header Message: (32-bit unsigned integer) +<dd>This value is used to keep a count of the number of dataset objects which +refer to this message from their dataset headers. When this count reaches zero, +the shared message header may be removed from the global small-data heap. +<dt>Shared Object Header Message: (various lengths) +<dd>The data stored for the shared object header message is formatted in the +same way as the private object header messages described in the object header +description earlier in this document and begins with the header message Type. +</dl> +</dl> + + +<h3><a name="DataStorage">Disk Format: Level 2c - Data Object Data Storage</a></h3> +<P>The data information for an object is stored separately from the header +information in the file and may not actually be located in the HDF5 file +itself if the header indicates that the data is stored externally. The +information for each record in the object is stored according to the +dimensionality of the object (indicated in the dimensionality header message). +Multi-dimensional data is stored in C order [same as current scheme], i.e. the +"last" dimension changes fastest. +<P>Data whose elements are composed of simple number-types are stored in +native-endian IEEE format, unless they are specifically defined as being stored +in a different machine format with the architecture-type information from the +number-type header message. This means that each architecture will need to +[potentially] byte-swap data values into the internal representation for that +particular machine. +<P> Data with a "variable" sized number-type is stored in an data heap +internal to the HDF file [which should not be user-modifiable]. +<P>Data whose elements are composed of pointer number-types are stored in several +different ways depending on the particular pointer type involved. Simple +pointers are just stored as the dataset offset of the object being pointed to with the +size of the pointer being the same number of bytes as offsets in the file. +Partial-object pointers are stored as a heap-ID which points to the following +information within the file-heap: an offset of the object pointed to, number-type +information (same format as header message), dimensionality information (same +format as header message), sub-set start and end information (i.e. a coordinate +location for each), and field start and end names (i.e. a [pointer to the] +string indicating the first field included and a [pointer to the] string name +for the last field). +Browse pointers are stored as an heap-ID (for the name in the file-heap) +followed by a offset of the data object being referenced. +<P>Data of a compound data-type is stored as a contiguous stream of the items +in the structure, with each item formatted according to it's +data-type. + +<hr> +<address><a href="mailto:koziol@ncsa.uiuc.edu">Quincey Koziol</a></address> +<address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- hhmts start --> +Last modified: Mon Jun 1 21:44:38 EDT 1998 +<!-- hhmts end --> +</body> +</html> diff --git a/doc/html/H5.intro.html b/doc/html/H5.intro.html new file mode 100644 index 0000000..e7d5a50 --- /dev/null +++ b/doc/html/H5.intro.html @@ -0,0 +1,997 @@ +<HTML> +<HEAD> +<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252"> +<META NAME="Generator" CONTENT="Microsoft Word 97"> +<TITLE>H5introH</TITLE> +<META NAME="Template" CONTENT="C:\PROGRAM FILES\MICROSOFT OFFICE\OFFICE\html.dot"> +</HEAD> +<BODY LINK="#0000ff" VLINK="#800080"> + +<B><FONT FACE="Times" SIZE=6><P ALIGN="CENTER">Introduction to HDF5 1.0 Alpha1.0</P> +</B></FONT><FONT FACE="Times"><P>This is a brief introduction to the HDF5 data model and programming model. It is not a full user's guide, but should provide enough information for you to understand how HDF5 is meant to work. Knowledge of the current version of HDF should make it easier to follow the text, but it is not required. For further information on the topics covered here, see the HDF5 documentation at </FONT><A HREF="http://hdf.ncsa.uiuc.edu/nra/BigHDF/"><FONT FACE="Times">http://hdf.ncsa.uiuc.edu/nra/BigHDF/</FONT></A><FONT FACE="Times">. </P> +</FONT><H2>What is the HDF5 prototype?</H2> +<FONT FACE="Times"><P>HDF5 is a new, experimental version of HDF that is designed to address some of the limitations of the current version of HDF (HDF4.1) and to address current and anticipated requirements of modern systems and applications. </P> +<P>This HDF5 prototype is not complete, but it should be sufficient show the basic features of HDF5. We urge you to look at it and give us feedback on what you like or don't like about it, and what features you would like to see added to it.</P> +<B><P>Why HDF5?</B> The development of HDF5 is motivated by a number of limitations in the current HDF format, as well as limitations in the library. Some of these limitations are:</P> + +<UL> +</FONT><LI>A single file cannot store more than 20,000 complex objects, and a single file cannot be larger than 2 gigabytes </LI> +<LI>The data models are less consistent than they should be, there are more object types than necessary, and datatypes are too restricted. </LI> +<LI>The library source is old and overly complex, does not support parallel I/O effectively, and is difficult to use in threaded applications.</LI></UL> + +<FONT FACE="Times"><P>When complete HDF5 will include the following improvements.</P> + +<UL> +</FONT><LI>A new file format designed to address some of the deficiencies of HDF4.1, particularly the need to store larger files and more objects per file. </LI> +<LI>A simpler, more comprehensive data model that includes only two basic structures: a multidimensional array of record structures, and a grouping structure. </LI> +<LI>A simpler, better-engineered library and API, with improved support for parallel i/o, threads, and other requirements imposed by modern systems and applications.</LI></UL> + +<H2>Limitations of the current prototype</H2> +<FONT FACE="Times"><P>The prototype release includes most of the <I>basic</I> functionality that is planned for the HDF5 library. However, the library does not implement all of the features detailed in the format and API specifications. Here is a listing of some of the limitations of the current release: </P> + +<UL> +</FONT><LI>Attributes for data objects are not supported </LI> +<LI>Data compression is not supported </LI> +<LI>External storage of objects are not supported </LI> +<LI>Some functions for manipulating datasets, dataspaces, and groups have not been implemented </LI> +<FONT FACE="Times"><LI>Some number types, including user-defined number types are not supported. Also number type conversion is limited.</LI></UL> + +<P>See the API Specification at </FONT><A HREF="http://hdf.ncsa.uiuc.edu/nra/BigHDF/"><FONT FACE="Times">http://hdf.ncsa.uiuc.edu/nra/BigHDF/</FONT></A><FONT FACE="Times"> for a complete listing of all routines that have been implemented.</P> +</FONT><H2>HDF5 file organization and data model.</H2> +<FONT FACE="Times"><P>HDF5 files are organized in a hierarchical structure, with two primary structures: "groups" and "datasets."</P> + +<UL> +</FONT><I><LI>HDF5 group: </I>a grouping structure containing instances of zero or more groups or datasets, together with supporting metadata </LI> +<I><LI>HD5F dataset:</I> a multidimensional array of data elements, together with supporting metadata. </LI></UL> + +<FONT FACE="Times"><P>Working with groups and group members is similar in many ways to working with directories and files in UNIX. As with UNIX directories and files, objects in an HDF5 file are often described by giving their full path names. "/" signifies the root group. "/foo" signifies a member of the root group called "foo." "/foo/zoo" signifies a member of the group "foo," which in turn is a member of the root group.</P> +<P>Any HDF5 group or dataset may have an associated <I>attribute list.</I> An HDF5 <I>attribute</I> is a user-defined HDF5 structure that provides extra information about an HDF5 object. Attributes are described in more detail below. <I>(Note: attributes are not supported in the current prototype.)</P> +</I></FONT><H3>HDF5 Groups</H3> +<FONT FACE="Times"><P>An<I> HDF5 group</I> is a structure containing zero or more HDF5 objects. A group has two parts:</P> + +<UL> +</FONT><LI>A <I>group header</I>, which contains a group name and a list of group attributes. (Attributes are not yet implemented.) </LI> +<LI>A group symbol table, which is a list of the HDF5 objects that belong to the group.</LI></UL> + +<P> </P> +<H3>HDF5 Datasets</H3> +<FONT FACE="Times"><P>A dataset is stored in a file in two parts: a header and a data array. </P> +<P>The header contains information that is needed to interpret the array portion of the dataset, as well as metadata, or pointers to metadata, that describes or annotates the dataset. Header information includes the name of the object, its dimensionality, its number-type, information about how the data itself is stored on disk, and other information used by the library to speed up access to the dataset or maintain the file's integrity.</P> +<P>There are four essential classes of information in any header: <I>name</I>, <I>datatype</I>, <I>dataspace</I>, and <I>storage layout</I>:</P> +<B><P>Name</B><I>.</I> A dataset <I>name</I> is a sequence of alphanumeric ASCII characters.</P> +<B><DFN><P>Datatype</DFN><I>.</B></I> HDF5 allows one to define many different kinds of <B>datatypes</B>. There are two basic categories of data types: "atomic" types and "compound" types. Atomic types are those that are not decomposed at the data type interface level, such as integers and floats. Compound types are made up of atomic types. </P> +<I><P>Atomic datatypes</I> include integers and floating-point numbers. Each atomic type belongs to a particular class and has several properties: size, order, precision, and offset. In this introduction, we consider only a few of these properties.</P> +<P>Atomic datatypes include integer, float, date and time, string, bit field, and opaque. <I>(Note: Only integer and float classes are available in the current implementation.)</P> +</I><P>Properties of integer types include size, order (endian-ness), and signed-ness (signed/unsigned).</P> +<P>Properties of float types include the size and location of the exponent and mantissa, and the location of the sign bit.</P> +<P>The datatypes that are supported in the current implementation are: </P> + +<UL> +</FONT><LI>Integer datatypes: 8-bit, 16-bit, 32-bit, and 64-bit integers in both little and big-endian format. </LI> +<LI>Floating-point numbers: IEEE 32-bit and 64-bit floating-point numbers in both little and big-endian format.</LI></UL> + +<FONT FACE="Times"><P>A <I>compound datatype</I> is one in which a collection of simple datatypes are represented as a single unit, similar to a "struct" in C. The parts of a compound datatype are called <I>members.</I> The members of a compound datatype may be of any datatype, including another compound datatype. It is possible to read members from a compound type without reading the whole type.</P> +<B><DFN><P>Dataspace.</B> </DFN>A dataset <I>dataspace </I>describes the dimensionality of the dataset. The dimensions of a dataset can be fixed (unchanging), or they may be <I>unlimited</I>, which means that they are extendible (i.e. they can grow larger). </P> +<P>Properties of a dataspace consist of the <I>rank </I>(number of dimensions) of the data array, and the <I>actual sizes of the dimensions</I> of the array, and the <I>maximum sizes of the dimensions </I>of the array. For a fixed-dimension dataset, the actual size is the same as the maximum size of a dimension. When a dimension is unlimited, the maximum size is set to the value </FONT><FONT FACE="Courier">H5S_UNLIMITED</FONT><FONT FACE="Times">. (An example below shows how to create extendible datasets.)</P> +<P>A dataspace can also describe portions of a dataset, making it possible to do partial I/O (hyperslab) operations.</P> +<P>Since I/O operations have two end-points, the raw data transfer functions require two dataspace arguments: one describes the application memory dataspace or subset thereof, and the other describes the file dataspace or subset thereof.</P> +<B><P>Storage layout.</B> The HDF5 format makes it possible to store data in a variety of ways. The default storage layout format is <I>contiguous</I>, meaning that data is stored in the same linear way that it is organized in memory. Two other storage layout formats are currently defined for HDF5: <I>compact, </I>and<I> chunked. </I>In the future, other storage layouts may be added.<I> </P> +<P>Compact</I> storage is used when the amount of data is small and can be stored directly in the object header. <I>(Note: Compact storage is not supported in this prototype.)</I> </P> +<I><P>Chunked</I> storage involves dividing the dataset into equal-sized "chunks" that are stored separately. Chunking has three important benefits. </P> +<OL> + +<LI>It makes it possible to achieve good performance when accessing subsets of the datasets, even when the subset to be chosen is orthogonal to the normal storage order of the dataset. </LI> +<LI>It makes it possible to compress large datasets and still achieve good performance when accessing subsets of the dataset. </LI> +<LI>It makes it possible efficiently to extend the dimensions of a dataset in any direction.</LI></OL> + +</FONT><H3>HDF5 attribute lists</H3> +<FONT FACE="Times"><P>An <I>attribute list</I> for an dataset or group is a listing of objects in the HDF file that are used as attributes, or metadata for the object. The attribute list is composed of two lists of objects, the first being simple attributes about the object, and the second being pointers to attribute objects. <I>(Note: Attributes are not supported in this prototype.)</P> +</I><P> </P> +</FONT><H2>The HDF5 Applications Programming Interface (API)</H2> +<FONT FACE="Times"><P>The current HDF5 API is implemented only in C. The API provides routines for creating HDF5 files, creating and writing groups, datasets, and their attributes to HDF5 files, and reading groups, datasets and their attributes from HDF5 files.</P> +</FONT><H3>Naming conventions</H3> +<FONT FACE="Times"><P>All C routines on the HDF 5 library begin with a prefix of the form "H5*", where "*" is a single letter indicating the object on which the operation is to be performed:</P> + +<UL> +</FONT><B><LI>H5F</B>: <B>F</B>ile-level access routines. <BR> +Example: <FONT FACE="Courier">H5Fopen</FONT>, which opens an HDF5 file. </LI> +<B><LI>H5G</B>: <B>G</B>roup functions, for creating and operating on physical groups of objects. <BR> +Example: <FONT FACE="Courier">H5Gset,</FONT>which sets the working group to the specified group. </LI> +<B><LI>H5T: </B>Data<B>T</B>ype functions, for creating and operating on simple and compound datatypes to be used as the elements in data arrays.<B><BR> +</B>Example: <FONT FACE="Courier">H5Tcopy,</FONT>which creates a copy of an existing data type. </LI> +<B><LI>H5S: </B>DataS<B>P</B>ace functions, which create and manipulate the dataspace in which the elements of a data array are stored.<BR> +Example: <FONT FACE="Courier">H5Sget_ndims</FONT>, which retrieves the number of dimensions of a data array. </LI> +<B><LI>H5D: D</B>ataset functions, which manipulate the data within datasets and determine how the data is to be stored in the file. <BR> +Example: H5D<FONT FACE="Courier">read</FONT>, which reads all or part of a dataset into a buffer in memory. </LI> +<B><LI>H5P</B>: <B>T</B>emplate functions, for manipulating object templates. <BR> +Example: <FONT FACE="Courier">H5Pset_chunk</FONT>, which sets the number of dimensions and the size of a chunk.</LI></UL> + +<H3>Include files </H3> +<FONT FACE="Times"><P>There are a number definitions and declarations that should be included with any HDF5 program. These definitions and declarations are contained in several "include" files. The main include file is <I>hdf5.h</I>. This file includes all of the other files that your program is likely to need. <I>Be sure to include hdf5.h in any program that accesses HDF5.</P> +</I></FONT><H3>Predefined simple numeric scalar datatypes</H3> +<FONT FACE="Times"><P>The HDF5 prototype currently supports simple signed and unsigned 8-bit, 16-bit, 32-bit , and 64-bit integers, and floating point numbers. The naming scheme for type definitions uses the following conventions:</P> + +<UL> +</FONT><LI>"int" stands for "integer" </LI> +<LI>the prefix "u" stands for "unsigned" </LI> +<LI>the integer suffix indicates the number of bits in the number</LI></UL> + +<FONT FACE="Times"><P>For example, "uint16" indicates an unsigned 16-bit integer. Datatypes that are supported in this prototype are:</P> +</FONT><PRE> char + int8 + uint8 + int16 + uint16 + int32 + uint32 + int64 + uint64 + float32 + float64</PRE> +<FONT FACE="Times"><P>These datatypes are defined in the file H5public.h together with keywords used to refer to them. H5public.h is included by the file hdf5.h described earlier. These datatypes should be used whenever you declare a variable to be used with an HDF5 routine. For instance, a 32-bit floating point variable should always be declared using a declaration such as</P> +</FONT><CODE><PRE>float32 x;</PRE> +</CODE><H3>Programming models</H3> +<FONT FACE="Times"><P>In this section we describe how to program some basic operations on files, including how to</P> + +<UL> +</FONT><LI>create a file </LI> +<LI>create and initialize a dataset </LI> +<LI>discard objects when they are no longer needed </LI> +<LI>write a dataset to a new file </LI> +<LI>obtain information about a dataset </LI> +<LI>read a portion of a dataset </LI> +<LI>create and write compound datatypes </LI> +<LI>create and write extendible datasets </LI> +<LI>create and populate groups </LI></UL> + +<H4>How to create an HDF5 file</H4> +<FONT FACE="Times"><P>This programming model shows how to create a file and also how to close the file.</P> +<OL> + +<LI>Create the file using </FONT><FONT FACE="Courier">H5Fcreate.</FONT><FONT FACE="Times"> Obtain a file ID (e.g. </FONT><FONT FACE="Courier">file_id</FONT><FONT FACE="Times">).</LI> +<LI>Close the file with </FONT><FONT FACE="Courier">H5Fclose(file_id)</FONT><FONT FACE="Times">.</LI> +<P>The following code fragment implements the specified model. If there is a possibility that the file already exists, the user must add the flag </FONT><FONT FACE="Courier">H5F_ACC_TRUNC </FONT><FONT FACE="Times">to the access mode to overwrite the previous file's information. </P> +</FONT><CODE><PRE>hid_t file; /* handle */ +/* + * Create a new file using H5F_ACC_TRUNC access, + * default file creation properties, and default file + * access properties. + * Then close the file. + */ +file = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); +status = H5Fclose(file); </PRE> +</CODE><H4>How to create and initialize the essential components of a dataset for writing to a file.</H4> +<FONT FACE="Times"><P>Recall that datatypes and dimensionality (dataspace) are independent objects, which are created separately from any dataset that they might be attached to. Because of this the creation of a dataset requires, at a minimum, separate definitions of datatype, dimensionality, and dataset. Hence, to create a dataset the following steps need to be taken:</P> +<LI VALUE=1>Create and initialize a dataspace for the dataset to be written.</LI> +<LI>Define the datatype for the dataset to be written. </LI> +<LI>Create and initialize the dataset itself.</LI></OL> + +</FONT><FONT FACE="Courier New"><P> </P> +</FONT><FONT FACE="Times"><P>The following code illustrates the creation of these three components of a dataset object.</P> +</FONT><CODE><PRE>hid_t dataset, datatype, dataspace; /* declare handles */ + +/* + * 1. Create dataspace: Describe the size of the array and + * create the data space for fixed size dataset. + */ +dimsf[0] = NX; +dimsf[1] = NY; +dataspace = H5Screate_simple(RANK, dimsf, NULL); +/* +/* + * 2. Define datatype for the data in the file. + * We will store little endian INT32 numbers. + */ +datatype = H5Tcopy(H5T_NATIVE_INT32); +status = H5Tset_order(datatype, H5T_ORDER_LE); +/* + * 3. Create a new dataset within the file using defined + * dataspace and datatype and default dataset creation + * properties. + * NOTE: H5T_NATIVE_INT32 can be used as datatype if conversion + * to little endian is not needed. + */ +dataset = H5Dcreate(file, DATASETNAME, datatype, dataspace, H5P_DEFAULT);</PRE><DIR> +<DIR> + +</CODE><H4>How to discard objects when they are no longer needed</H4></DIR> +</DIR> + +<FONT FACE="Times"><P>The type, dataspace and dataset objects should be released once they are no longer needed by a program. Since each is an independent object, the must be released ("closed") separately. The following lines of code close the type, dataspace, datasets, and file that were created in the preceding section.</P> +</FONT><CODE><P>H5Tclose(datatype);</P> +<P>H5Dclose(dataset);</P> +<P>H5Sclose(dataspace);</P><DIR> +<DIR> + +</CODE><H4>How to write a dataset to a new file</H4></DIR> +</DIR> + +<FONT FACE="Times"><P>Having defined the datatype, dataset, and dataspace parameters, you write out the data with a call to </FONT><FONT FACE="Courier">H5Dwrite.</P> +</FONT><CODE><PRE>/* + * Write the data to the dataset using default transfer + * properties. + */ +status = H5Dwrite(dataset, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, + H5P_DEFAULT, data);</PRE> +</CODE><FONT FACE="Times"><P>The third and fourth parameters of </FONT><FONT FACE="Courier">H5Dwrite</FONT><FONT FACE="Times"> in the example describe the dataspaces in memory and in the file, respectively. They are set to the value </FONT><FONT FACE="Courier">H5S_ALL</FONT><FONT FACE="Times"> to indicate that an entire dataset is to be written. In a later section we look at how we would access a portion of a dataset.</P> +</FONT><P><A HREF="#CreateExample"><FONT FACE="Times">Example 1</FONT></A><FONT FACE="Times"> contains a program that creates a file and a dataset, and writes the dataset to the file. </P> +<P>Reading is analogous to writing. If, in the previous example, we wish to read an entire dataset, we would use the same basic calls with the same parameters. Of course, the routine </FONT><FONT FACE="Courier">H5Dread</FONT><FONT FACE="Times"> would replace </FONT><FONT FACE="Courier">H5Dwrite.</FONT><FONT FACE="Times"> </P><DIR> +<DIR> + +</FONT><H4>Getting information about a dataset</H4></DIR> +</DIR> + +<FONT FACE="Times"><P>Although reading is analogous to writing, it is often necessary to query a file to obtain information about a dataset. For instance, we often need to know about the datatype associated with a dataset, as well dataspace information (e.g. rank and dimensions). There are several "get" routines for obtaining this information The following code segment illustrates how we would get this kind of information: </P> +</FONT><CODE><PRE>/* + * Get datatype and dataspace handles and then query + * dataset class, order, size, rank and dimensions. + */ + +datatype = H5Dget_type(dataset); /* datatype handle */ +class = H5Tget_class(datatype); +if (class == H5T_INTEGER) printf("Data set has INTEGER type \n"); +order = H5Tget_order(datatype); +if (order == H5T_ORDER_LE) printf("Little endian order \n"); + +size = H5Tget_size(datatype); +printf(" Data size is %d \n", size); + +dataspace = H5Dget_space(dataset); /* dataspace handle */ +rank = H5Sget_ndims(dataspace); +status_n = H5Sget_dims(dataspace, dims_out, NULL); +printf("rank %d, dimensions %d x %d \n", rank, dims_out[0], dims_out[1]);</PRE> +</CODE><FONT FACE="Times"><P> </P><DIR> +<DIR> + +</FONT><H4>Reading a portion of a dataset: defining dataspaces</H4></DIR> +</DIR> + +<FONT FACE="Times"><P>In the previous discussion, we describe how to access an entire dataset with one write (or read) operation. To read or write a <I>portion</I> of a dataset, we need to provide more contextual information.</P> +<P>Consider the following example. Suppose there is 500x600 dataset in a file, and we wish to read from the dataset a 100x200 hyperslab located beginning at element <200,200>. In addition, suppose we wish to read the hyperslab into an 200x400 array in memory beginning at element <0,0> in memory. Visually, the transfer looks something like this: </P> +</FONT><FONT FACE="Times" SIZE=6><P> <IMG SRC="dataset_p1.gif" WIDTH=521 HEIGHT=420></P> +</FONT><FONT FACE="Times"><P>As the example illustrates, whenever we read part of a dataset from a file we must provide two dataspaces: the dataspace of the object in the file as well as the dataspace of the object in memory into which we read. There are dataspace routines (</FONT><FONT FACE="Courier">H5S...</FONT><FONT FACE="Times">) for doing this. </P> +<P>For example, suppose we want to read a 3x4 hyperslab from a dataset in a file beginning at the element <1,2> in the dataset. In order to do this, we must create a dataspace that describes the overall rank and dimensions of the dataset in the file, as well as the position and size of the hyperslab that we are extracting from that dataset. The following code illustrates how this would be done. </P> +</FONT><CODE><PRE>/* + * Get overall rank and dimensions of dataspace. + */ +dataspace = H5Dget_space(dataset); /* get dataspace handle */ +rank = H5Sget_ndims(dataspace); +status_n = H5Sget_dims(dataspace, dims_out, NULL); + +/* + * Define hyperslab in the dataset. + */ +offset[0] = 1; +offset[1] = 2; +count[0] = 3; +count[1] = 4; +status = H5Sset_hyperslab(dataspace, offset, count, NULL);</PRE> +</CODE><FONT FACE="Times"><P>This describes the dataspace from which we wish to read. We need to define the dataspace in memory analogously. Suppose, for instance, that we have in memory a 3 dimensional 7x7x3 array into which we wish to read the 3x4 hyperslab described above beginning at the element <3,0,0>. Since the in-memory dataspace has three dimensions, we have to describe the hyperslab as an array with three dimensions, with the last dimension being 1: <3,4,1>.</P> +<P>Notice that now we must describe two things: the dimensions of the in-memory array, and the size and position of the hyperslab that we wish to read in. The following code illustrates how this would be done. </P> +</FONT><CODE><PRE>/* + * Define the memory dataspace. + */ +dimsm[0] = 7; +dimsm[1] = 7; +dimsm[2] = 3; +memspace = H5Screate_simple(RANK_OUT,dimsm,NULL); + +/* + * Define memory hyperslab. + */ +offset_out[0] = 3; +offset_out[1] = 0; +offset_out[2] = 0; +count_out[0] = 3; +count_out[1] = 4; +count_out[2] = 1; +status = H5Sset_hyperslab(memspace, offset_out, count_out, NULL); + +/*</PRE> +</CODE><P><A HREF="#ReadExample"><FONT FACE="Times">Example 2</FONT></A><FONT FACE="Times"> contains a complete program that performs these operations.</P> +</FONT><H4>Creating compound datatypes</H4> +<P>Properties of compound datatypes.</B>A compound datatype is similar to a struct in C or a common block in Fortran. It is a collection of one or more atomic types or small arrays of such types. To create and use of a compound datatype requires you need to refer to various <I>properties</I> of the data compound datatype:</P> + +<UL> +<LI>It is of class <I>compound.</I> </LI> +<LI>It has a fixed total <I>size</I>, in bytes. </LI> +<LI>It consists of zero or more <I>members</I> (defined in any order) with unique names and which occupy non-overlapping regions within the datum. </LI> +<LI>Each member has its own <I>datatype</I>. </LI> +<LI>Each member is referenced by an <I>index number</I> between zero and N-1, where N is the number of members in the compound datatype. </LI> +<LI>Each member has a <I>name</I> which is unique among its siblings in a compound data type. </LI> +<LI>Each member has a fixed <I>byte offset</I>, which is the first byte (smallest byte address) of that member in a compound datatype. </LI> +<LI>Each member can be a small array of up to four dimensions.</LI></UL> + +<FONT FACE="Times"><P>Properties of members of a compound data type are defined when the member is added to the compound type and cannot be subsequently modified.</P> +<B><P>Defining compound datatypes.</P> </B> +<P>Compound datatypes must be built out of other datatypes. First, one creates an empty compound data type and specifies its total size. Then members are added to the compound data type in any order.</P> +<I><P>Member names. </I>Each member must have a descriptive name, which is the key used to uniquely identify the member within the compound data type. A member name in an HDF5 data type does not necessarily have to be the same as the name of the corresponding member in the C struct in memory, although this is often the case. Nor does one need to define all members of the C struct in the HDF5 compound data type (or vice versa). </P> +<I><P>Offsets. </I>Usually a C struct will be defined to hold a data point in memory, and the offsets of the members in memory will be the offsets of the struct members from the beginning of an instance of the struct. The library defines two macros to compute the offset of a member within a struct (The only difference between the two is that one uses </FONT><CODE>s.m</CODE><FONT FACE="Times"> as the struct member while the other uses </FONT><CODE>p->m</CODE><FONT FACE="Times" SIZE=2>)</FONT><FONT FACE="Times">: </P> +</FONT><CODE><P>HOFFSET(s,m)<FONT SIZE=5>. </FONT></CODE><FONT FACE="Times">This macro computes the offset of member </FONT><FONT FACE="Courier"><EM>m</EM> </FONT><FONT FACE="Times">within a struct variable <EM>s</EM>. </P> +</FONT><CODE><P>HPOFFSET(p,m)<FONT SIZE=5>. </FONT></CODE><FONT FACE="Times">This macro computes the offset of member </FONT><FONT FACE="Courier"><EM>m</FONT></EM><FONT FACE="Times"> from a pointer to a struct </FONT><FONT FACE="Courier"><EM>p</FONT></EM><FONT FACE="Times">. </P> +<P>Here is an example in which a compound data type is created to describe complex numbers whose type is defined by the </FONT><CODE>complex_t</CODE><FONT FACE="Times" SIZE=2> </FONT><FONT FACE="Times">struct. </P> +</FONT><CODE><PRE>typedef struct { + double re; /*real part */ + double im; /*imaginary part */ +} complex_t; + +complex_t tmp; /*used only to compute offsets */ +hid_t complex_id = H5Tcreate (H5T_COMPOUND, sizeof tmp); +H5Tinsert (complex_id, "real", HOFFSET(tmp,re), + H5T_NATIVE_DOUBLE); +H5Tinsert (complex_id, "imaginary", HOFFSET(tmp,im), + H5T_NATIVE_DOUBLE);</PRE> +</CODE> +<P> <A HREF="#CompoundExample"><FONT FACE="Times">Example 3</A> shows how to create a compound data type, + write an array that has the compound data type to the file, and read back subsets of the members.</P> +<P> </P> +</FONT><H4>Creating and writing extendible datasets</H4> +<P>An <I>extendible</I> dataset is one whose dimensions can grow. In HDF5, it is possible to define a dataset to have certain initial dimensions, then later to increase the size of any of the initial dimensions. </P> +<P>For example, you can create and store the following 3x3 HDF5 dataset:</P> +<CODE><PRE><P>1 1 1 </P> +<P>1 1 1 </P> +<P>1 1 1 </P> +</PRE> +</CODE> +<FONT FACE="Times"><P>then later to extend this into a 10x3 dataset by adding 7 rows, such as this:</P> +</FONT><CODE><PRE><P>1 1 1 </P> +<P>1 1 1 </P> +<P>1 1 1 </P> +<P>2 2 2</P> +<P>2 2 2</P> +<P>2 2 2</P> +<P>2 2 2</P> +<P>2 2 2</P> +<P>2 2 2</P> +<P>2 2 2</P> +</PRE> +</CODE> +</FONT><FONT FACE="Times"><P>then further extend it to a 10x5 dataset by adding two columns, such as this:</P> +</FONT><CODE><PRE><P>1 1 1 3 3 </P> +<P>1 1 1 3 3 </P> +<P>1 1 1 3 3 </P> +<P>2 2 2 3 3</P> +<P>2 2 2 3 3</P> +<P>2 2 2 3 3</P> +<P>2 2 2 3 3</P> +<P>2 2 2 3 3</P> +<P>2 2 2 3 3</P> +<P>2 2 2 3 3</P> +</PRE> +</CODE> +</FONT><FONT FACE="Times"><P>The current version of HDF 5 requires you to use <I>chunking</I> in order to define extendible datasets. Chunking makes it possible to extend datasets efficiently, without having to reorganize storage excessively. </P> +<P>Three operations are required in order to write an extendible dataset:</P> +<OL> + +<LI>Declare the dataspace of the dataset to have <I>unlimited dimensions</I> for all dimensions that might eventually be extended.</LI> +<LI>When creating the dataset, set the storage layout for the dataset to <I>chunked</I>.</LI> +<LI>Extend the size of the dataset.</LI></OL> + +<P>For example, suppose we wish to create a dataset similar to the one shown above. We want to start with a 3x3 dataset, then later extend it in both directions. </P> +<B><P>Declaring unlimited dimensions. </B>We could declare the dataspace to have unlimited dimensions with the following code, which uses the predefined constant H5S_UNLIMITED to specify unlimited dimensions.</P> +</FONT><CODE><PRE><P>hsize_t dims[2] = { 3, 3}; /* dataset dimensions at the creation time */ </P> +<P>hsize_t maxdims[2] = {H5S_UNLIMITED, H5S_UNLIMITED}; +</P> +<P>/*</P> +<P>* 1. Create the data space with unlimited dimensions. </P> +<P>*/</P> +<P>dataspace = H5Screate_simple(RANK, dims, maxdims); </P> +</PRE> +</CODE> +<B><P>Enabling chunking. </B>We can then modify the dataset storage layout properties to + enable chunking. We do this using the routine H5Pset_chunk: +<CODE><PRE><P>hid_t cparms; </P> +<P>hsize_t chunk_dims[2] ={2, 5};</P> +<P>/* </P> +<P>* 2. Modify dataset creation properties to enable chunking.</P> +<P>*/</P> +<P>cparms = H5Pcreate (H5P_DATASET_CREATE);</P> +<P>status = H5Pset_chunk( cparms, RANK, chunk_dims);</CODE></PRE></P> +<B>Extending dataset size. </B>Finally, when we want to extend the size of the dataset, + we invoke H5Dextend to extend the size of the dataset. In the following example, we extend the dataset along the first dimension, by seven rows, so that the new dimensions are <10,3>.: +<CODE><PRE><P>/*</P> +<P>* Extend the dataset. Dataset becomes 10 x 3.</P> +<P>*/</P> +<P>dims[0] = dims[0] + 7;</P> +<P>size[0] = dims[0]; </P> +<P>size[1] = dims[1]; </P> +<P>status = H5Dextend (dataset, size);</P> +<P> </P> +</CODE></PRE> +<A HREF="#ExtendibleExample"><FONT FACE="Times">Example 4</A> shows how to create a 3x3 extendible dataset, to extend the dataset to 10x3, then to extend it again to 10x5.</P> +</FONT><H3>Working with groups in a file</H3> +<P>Groups provide a mechanism for organizing datasets in an HDF5 file extendable meaningful ways. The H5G API contains routines for working with groups. </P> +<B>To create a group</B>, use H5Gcreate>. For example, the following code creates two groups that are members of the root group. They are called "/IntData" and "/FloatData." The return value ("dir") is the group ID. +<CODE><PRE>/*<BR> + * Create two groups in a file. + */ +dir = H5Gcreate(file, "/IntData", 0); +status = H5Gclose(dir); +dir = H5Gcreate(file,"/FloatData", 0); +status = H5Gclose(dir);</CODE></PRE></P> +</FONT><PRE>The third parameter in <CODE>H5Gcreate</CODE> optionally specifies how much file space to reserve to store the names that will appear in this group. If a non-positive value is supplied then a default size is chosen. +<CODE>H5Gclose</CODE> closes the group and releases the group ID.<P> +<B><P>Creating an object in a particular group. </B>Except for single-object HDF5 files, every object in an HDF5 file must belong to a group, and hence has a path name. Hence, we put an object in a particular group by giving its path name when we create it. For example, the following code creates a dataset "IntArray" in the group "/IntData":</P> +</FONT><CODE><PRE>/* + * Create dataset in the /IntData group by specifying full path. + */ +dims[0] = 2; +dims[1] = 3; +dataspace = H5Screate_simple(2, dims, NULL); +dataset = H5Dcreate(file, "/IntData/IntArray", H5T_NATIVE_INT, dataspace, H5P_DEFAULT); </PRE> +</CODE><B><P>Changing the current group. </B>The HDF5 Group API supports the idea of a "current," group. This is analogous to the "current working directory" idea in UNIX. You can set the current group in HDF5 with the routine H5Gset. The following code shows how to set a current group, then create a certain dataset ("FloatData") in that group. </P> +</FONT><CODE><PRE>/* + * Set current group to /FloatData. + */ +status = H5Gset (file, "/FloatData"); + +/* + * Create two datasets + */ + +dims[0] = 5; +dims[1] = 10; +dataspace = H5Screate_simple(2, dims, NULL); +dataset = H5Dcreate(file, "FloatArray", H5T_NATIVE_FLOAT, dataspace, H5P_DEFAULT); </PRE> +</CODE> +<A HREF="#GroupExample"><FONT FACE="Times">Example 5</A> shows how to create an HDF5 file with two group, and to place some datasets within those groups.</P> +</FONT><H3>Example code</H3> +<H4><A NAME="CreateExample">Example 1: How to create a homogeneous multi-dimensional dataset</A> and write it to a file.</H4> +<P>This example creates a 2-dimensional HDF 5 dataset of little endian 32-bit integers.</P> +<CODE><PRE><P><A NAME="CheckAndReadExample">/* </P> +<P>* This example writes data to HDF5 file.</P> +<P>* Data conversion is performed during write operation. </P> +<P>*/</P> +<P>#include "hdf5.h"</P> +<P>#define FILE "SDS.h5"</P> +<P>#define DATASETNAME "IntArray" </P> +<P>#define NX 5 /* dataset dimensions */</P> +<P>#define NY 6</P> +<P>#define RANK 2</P> +<P>main ()</P> +<P>{</P> +<P>hid_t file, dataset; /* file and dataset handles */</P> +<P>hid_t datatype, dataspace; /* handles */</P> +<P>hsize_t dimsf[2]; /* dataset dimensions */</P> +<P>herr_t status; </P> +<P>int32 data[NX][NY]; /* data to write */</P> +<P>int i, j;</P> +<P>/* </P> +<P>* Data and output buffer initialization. </P> +<P>*/</P> +<P>for (j = 0; j < NX; j++) {</P> +<P>for (i = 0; i < NY; i++)</P> +<P>data[j][i] = i + j;</P> +<P>} </P> +<P>/* 0 1 2 3 4 5 </P> +<P>1 2 3 4 5 6</P> +<P>2 3 4 5 6 7</P> +<P>3 4 5 6 7 8</P> +<P>4 5 6 7 8 9 */</P> +<P>/*</P> +<P>* Create a new file using H5F_ACC_TRUNC access,</P> +<P>* default file creation properties, and default file</P> +<P>* access properties.</P> +<P>*/</P> +<P>file = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);</P> +<P>/*</P> +<P>* Describe the size of the array and create the data space for fixed</P> +<P>* size dataset. </P> +<P>*/</P> +<P>dimsf[0] = NX;</P> +<P>dimsf[1] = NY;</P> +<P>dataspace = H5Screate_simple(RANK, dimsf, NULL); </P> +<P>/* </P> +<P>* Define datatype for the data in the file.</P> +<P>* We will store little endian INT32 numbers.</P> +<P>*/</P> +<P>datatype = H5Tcopy(H5T_NATIVE_INT32);</P> +<P>status = H5Tset_order(datatype, H5T_ORDER_LE);</P> +<P>/*</P> +<P>* Create a new dataset within the file using defined dataspace and</P> +<P>* datatype and default dataset creation properties.</P> +<P>*/</P> +<P>dataset = H5Dcreate(file, DATASETNAME, datatype, dataspace,</P> +<P>H5P_DEFAULT);</P> +<P>/*</P> +<P>* Write the data to the dataset using default transfer properties.</P> +<P>*/</P> +<P>status = H5Dwrite(dataset, H5T_NATIVE_INT32, H5S_ALL, H5S_ALL,</P> +<P>H5P_DEFAULT, data);</P> +<P>/*</P> +<P>* Close/release resources.</P> +<P>*/</P> +<P>H5Sclose(dataspace);</P> +<P>H5Tclose(datatype);</P> +<P>H5Dclose(dataset);</P> +<P>H5Fclose(file);</P> +<P>} </P> +<P> </P> +</CODE></PRE> +<H4><A NAME="ReadExample"> Example 2. How to read a hyperslab from file into memory.</A></H4> +<P>This example reads a hyperslab from a 2-d HDF5 dataset into a 3-d dataset in memory.</P> +<CODE><PRE><P>/* </P> +<P>* This example reads hyperslab from the SDS.h5 file </P> +<P>* created by h5_write.c program into two-dimensional</P> +<P>* plane of the tree-dimensional array. </P> +<P>* Information about dataset in the SDS.h5 file is obtained. </P> +<P>*/</P> +<P>#include "hdf5.h"</P> +<P>#define FILE "SDS.h5"</P> +<P>#define DATASETNAME "IntArray" </P> +<P>#define NX_SUB 3 /* hyperslab dimensions */ </P> +<P>#define NY_SUB 4 </P> +<P>#define NX 7 /* output buffer dimensions */ </P> +<P>#define NY 7 </P> +<P>#define NZ 3 </P> +<P>#define RANK 2</P> +<P>#define RANK_OUT 3</P> +<P>main ()</P> +<P>{</P> +<P>hid_t file, dataset; /* handles */</P> +<P>hid_t datatype, dataspace; </P> +<P>hid_t memspace; </P> +<P>H5T_class_t class; /* data type class */</P> +<P>H5T_order_t order; /* data order */</P> +<P>size_t size; /* size of the data element</P> +<P>stored in file */ </P> +<P>hsize_t dimsm[3]; /* memory space dimensions */</P> +<P>hsize_t dims_out[2]; /* dataset dimensions */ </P> +<P>herr_t status; </P> +<P>int data_out[NX][NY][NZ ]; /* output buffer */</P> +<P>hsize_t count[2]; /* size of the hyperslab in the file */</P> +<P>hssize_t offset[2]; /* hyperslab offset in the file */</P> +<P>hsize_t count_out[3]; /* size of the hyperslab in memory */</P> +<P>hssize_t offset_out[3]; /* hyperslab offset in memory */</P> +<P>int i, j, k, status_n, rank;</P> +<P>for (j = 0; j < NX; j++) {</P> +<P>for (i = 0; i < NY; i++) {</P> +<P>for (k = 0; k < NZ ; k++)</P> +<P>data_out[j][i][k] = 0;</P> +<P>}</P> +<P>} </P> +<P>/*</P> +<P>* Open the file and the dataset.</P> +<P>*/</P> +<P>file = H5Fopen(FILE, H5F_ACC_RDONLY, H5P_DEFAULT);</P> +<P>dataset = H5Dopen(file, DATASETNAME);</P> +<P>/*</P> +<P>* Get datatype and dataspace handles and then query</P> +<P>* dataset class, order, size, rank and dimensions.</P> +<P>*/</P> +<P>datatype = H5Dget_type(dataset); /* datatype handle */ </P> +<P>class = H5Tget_class(datatype);</P> +<P>if (class == H5T_INTEGER) printf("Data set has INTEGER type \n");</P> +<P>order = H5Tget_order(datatype);</P> +<P>if (order == H5T_ORDER_LE) printf("Little endian order \n");</P> +<P>size = H5Tget_size(datatype);</P> +<P>printf(" Data size is %d \n", size);</P> +<P>dataspace = H5Dget_space(dataset); /* dataspace handle */</P> +<P>rank = H5Sget_ndims(dataspace);</P> +<P>status_n = H5Sget_dims(dataspace, dims_out, NULL);</P> +<P>printf("rank %d, dimensions %d x %d \n", rank, dims_out[0], dims_out[1]);</P> +<P>/* </P> +<P>* Define hyperslab in the dataset. </P> +<P>*/</P> +<P>offset[0] = 1;</P> +<P>offset[1] = 2;</P> +<P>count[0] = NX_SUB;</P> +<P>count[1] = NY_SUB;</P> +<P>status = H5Sset_hyperslab(dataspace, offset, count, NULL);</P> +<P>/*</P> +<P>* Define the memory dataspace.</P> +<P>*/</P> +<P>dimsm[0] = NX;</P> +<P>dimsm[1] = NY;</P> +<P>dimsm[2] = NZ ;</P> +<P>memspace = H5Screate_simple(RANK_OUT,dimsm,NULL); </P> +<P>/* </P> +<P>* Define memory hyperslab. </P> +<P>*/</P> +<P>offset_out[0] = 3;</P> +<P>offset_out[1] = 0;</P> +<P>offset_out[2] = 0;</P> +<P>count_out[0] = NX_SUB;</P> +<P>count_out[1] = NY_SUB;</P> +<P>count_out[2] = 1;</P> +<P>status = H5Sset_hyperslab(memspace, offset_out, count_out, NULL);</P> +<P>/*</P> +<P>* Read data from hyperslab in the file into the hyperslab in </P> +<P>* memory and display.</P> +<P>*/</P> +<P>status = H5Dread(dataset, H5T_NATIVE_INT, memspace, dataspace,</P> +<P>H5P_DEFAULT, data_out);</P> +<P>for (j = 0; j < NX; j++) {</P> +<P>for (i = 0; i < NY; i++) printf("%d ", data_out[j][i][0]);</P> +<P>printf("\n");</P> +<P>}</P> +<P>/* 0 0 0 0 0 0 0</P> +<P>0 0 0 0 0 0 0</P> +<P>0 0 0 0 0 0 0</P> +<P>3 4 5 6 0 0 0 </P> +<P>4 5 6 7 0 0 0</P> +<P>5 6 7 8 0 0 0</P> +<P>0 0 0 0 0 0 0 */</P> +<P>/*</P> +<P>* Close/release resources.</P> +<P>*/</P> +<P>H5Tclose(datatype);</P> +<P>H5Dclose(dataset);</P> +<P>H5Sclose(dataspace);</P> +<P>H5Sclose(memspace);</P> +<P>H5Fclose(file);</P> +<P>} </P> +</CODE></PRE> +<P> </P> +<H4><A NAME="CompoundExample">Example 3. Working with compound datatypes.</A></H4> +<P>This example shows how to create a compound data type, write an array which has the compound data type to the file, and read back subsets of fields.</P> +<CODE><PRE><P>/*</P> +<P>* This example shows how to create a compound data type,</P> +<P>* write an array which has the compound data type to the file,</P> +<P>* and read back fields' subsets.</P> +<P>*/</P> +<P>#include "hdf5.h"</P> +<P>#define FILE "SDScompound.h5"</P> +<P>#define DATASETNAME "ArrayOfStructures"</P> +<P>#define LENGTH 10</P> +<P>#define RANK 1</P> +<P>main()</P> +<P>{</P> +<P>/* First structure and dataset*/</P> +<P>typedef struct s1_t {</P> +<P>int a;</P> +<P>float b;</P> +<P>double c; </P> +<P>} s1_t;</P> +<P>s1_t s1[LENGTH];</P> +<P>hid_t s1_tid; /* File datatype handle */</P> +<P>/* Second structure (subset of s1_t) and dataset*/</P> +<P>typedef struct s2_t {</P> +<P>double c;</P> +<P>int a;</P> +<P>} s2_t;</P> +<P>s2_t s2[LENGTH];</P> +<P>hid_t s2_tid; /* Memory datatype handle */</P> +<P>/* Third "structure" ( will be used to read float field of s1) */</P> +<P>hid_t s3_tid; /* Memory datatype handle */</P> +<P>float s3[LENGTH];</P> +<P>int i;</P> +<P>hid_t file, datatype, dataset, space; /* Handles */</P> +<P>herr_t status;</P> +<P>hsize_t dim[] = {LENGTH}; /* Dataspace dimensions */</P> +<P>H5T_class_t class;</P> +<P>size_t size;</P> +<P>/*</P> +<P>* Initialize the data</P> +<P>*/</P> +<P>for (i = 0; i< LENGTH; i++) {</P> +<P>s1[i].a = i;</P> +<P>s1[i].b = i*i;</P> +<P>s1[i].c = 1./(i+1);</P> +<P>}</P> +<P>/*</P> +<P>* Create the data space.</P> +<P>*/</P> +<P>space = H5Screate_simple(RANK, dim, NULL);</P> +<P>/*</P> +<P>* Create the file.</P> +<P>*/</P> +<P>file = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);</P> +<P>/*</P> +<P>* Create the memory data type. </P> +<P>*/</P> +<P>s1_tid = H5Tcreate (H5T_COMPOUND, sizeof(s1_t));</P> +<P>status = H5Tinsert(s1_tid, "a_name", HPOFFSET(s1, a), H5T_NATIVE_INT);</P> +<P>status = H5Tinsert(s1_tid, "c_name", HPOFFSET(s1, c), H5T_NATIVE_DOUBLE);</P> +<P>status = H5Tinsert(s1_tid, "b_name", HPOFFSET(s1, b), H5T_NATIVE_FLOAT);</P> +<P>/* </P> +<P>* Create the dataset.</P> +<P>*/</P> +<P>dataset = H5Dcreate(file, DATASETNAME, s1_tid, space, H5P_DEFAULT);</P> +<P>/*</P> +<P>* Write data to the dataset; </P> +<P>*/</P> +<P>status = H5Dwrite(dataset, s1_tid, H5S_ALL, H5S_ALL, H5P_DEFAULT, s1);</P> +<P>/*</P> +<P>* Release resources</P> +<P>*/</P> +<P>H5Tclose(s1_tid);</P> +<P>H5Sclose(space);</P> +<P>H5Dclose(dataset);</P> +<P>H5Fclose(file);</P> +<P>/*</P> +<P>* Open the file and the dataset.</P> +<P>*/</P> +<P>file = H5Fopen(FILE, H5F_ACC_RDONLY, H5P_DEFAULT);</P> +<P>dataset = H5Dopen(file, DATASETNAME);</P> +<P>/* </P> +<P>* Create a data type for s2</P> +<P>*/</P> +<P>s2_tid = H5Tcreate(H5T_COMPOUND, sizeof(s2_t));</P> +<P>status = H5Tinsert(s2_tid, "c_name", HPOFFSET(s2, c), H5T_NATIVE_DOUBLE);</P> +<P>status = H5Tinsert(s2_tid, "a_name", HPOFFSET(s2, a), H5T_NATIVE_INT);</P> +<P>/*</P> +<P>* Read two fields c and a from s1 dataset. Fields in the file</P> +<P>* are found by their names "c_name" and "a_name".</P> +<P>*/</P> +<P>status = H5Dread(dataset, s2_tid, H5S_ALL, H5S_ALL, H5P_DEFAULT, s2);</P> +<P>/*</P> +<P>* Display the fields</P> +<P>*/</P> +<P>printf("\n");</P> +<P>printf("Field c : \n");</P> +<P>for( i = 0; i < LENGTH; i++) printf("%.4f ", s2[i].c);</P> +<P>printf("\n");</P> +<P>printf("\n");</P> +<P>printf("Field a : \n");</P> +<P>for( i = 0; i < LENGTH; i++) printf("%d ", s2[i].a);</P> +<P>printf("\n");</P> +<P>/* </P> +<P>* Create a data type for s3.</P> +<P>*/</P> +<P>s3_tid = H5Tcreate(H5T_COMPOUND, sizeof(float));</P> +<P>status = H5Tinsert(s3_tid, "b_name", 0, H5T_NATIVE_FLOAT);</P> +<P>/*</P> +<P>* Read field b from s1 dataset. Field in the file is found by its name.</P> +<P>*/</P> +<P>status = H5Dread(dataset, s3_tid, H5S_ALL, H5S_ALL, H5P_DEFAULT, s3);</P> +<P>/*</P> +<P>* Display the field</P> +<P>*/</P> +<P>printf("\n");</P> +<P>printf("Field b : \n");</P> +<P>for( i = 0; i < LENGTH; i++) printf("%.4f ", s3[i]);</P> +<P>printf("\n");</P> +<P>/*</P> +<P>* Release resources</P> +<P>*/</P> +<P>H5Tclose(s2_tid);</P> +<P>H5Tclose(s3_tid);</P> +<P>H5Dclose(dataset);</P> +<P>H5Sclose(space);</P> +<P>H5Fclose(file);</P> +<P>}</P> +</CODE></PRE> +<P> </P> +<H4><A NAME="ExtendibleExample">Example 4. Creating and writing an extendible dataset.</A></H4> +<P>This example shows how to create a 3x3 extendible dataset, to extend the dataset to 10x3, then to extend it again to 10x5.</P> +<CODE><PRE><P>/* </P> +<P>* This example shows how to work with extendible dataset.</P> +<P>* In the current version of the library dataset MUST be</P> +<P>* chunked.</P> +<P>* </P> +<P>*/</P> +<P>#include "hdf5.h"</P> +<P>#define FILE "SDSextendible.h5"</P> +<P>#define DATASETNAME "ExtendibleArray" </P> +<P>#define RANK 2</P> +<P>#define NX 10</P> +<P>#define NY 5 </P> +<P>main ()</P> +<P>{</P> +<P>hid_t file; /* handles */</P> +<P>hid_t datatype, dataspace, dataset; </P> +<P>hid_t filespace; </P> +<P>hid_t cparms; </P> +<P>hsize_t dims[2] = { 3, 3}; /* dataset dimensions</P> +<P>at the creation time */ </P> +<P>hsize_t dims1[2] = { 3, 3}; /* data1 dimensions */ </P> +<P>hsize_t dims2[2] = { 7, 1}; /* data2 dimensions */ </P> +<P>hsize_t dims3[2] = { 2, 2}; /* data3 dimensions */ </P> +<P>hsize_t maxdims[2] = {H5S_UNLIMITED, H5S_UNLIMITED};</P> +<P>hsize_t chunk_dims[2] ={2, 5};</P> +<P>hsize_t size[2];</P> +<P>hssize_t offset[2];</P> +<P>herr_t status; </P> +<P>int data1[3][3] = { 1, 1, 1, /* data to write */</P> +<P>1, 1, 1,</P> +<P>1, 1, 1 }; </P> +<P>int data2[7] = { 2, 2, 2, 2, 2, 2, 2};</P> +<P>int data3[2][2] = { 3, 3,</P> +<P>3, 3};</P> +<P>/*</P> +<P>* Create the data space with unlimited dimensions. </P> +<P>*/</P> +<P>dataspace = H5Screate_simple(RANK, dims, maxdims); </P> +<P>/*</P> +<P>* Create a new file. If file exists its contents will be overwritten.</P> +<P>*/</P> +<P>file = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);</P> +<P>/* </P> +<P>* Modify dataset creation properties, i.e. enable chunking.</P> +<P>*/</P> +<P>cparms = H5Pcreate (H5P_DATASET_CREATE);</P> +<P>status = H5Pset_chunk( cparms, RANK, chunk_dims);</P> +<P>/*</P> +<P>* Create a new dataset within the file using cparms</P> +<P>* creation properties.</P> +<P>*/</P> +<P>dataset = H5Dcreate(file, DATASETNAME, H5T_NATIVE_INT, dataspace,</P> +<P>cparms);</P> +<P>/*</P> +<P>* Extend the dataset. This call assures that dataset is at least 3 x 3.</P> +<P>*/</P> +<P>size[0] = 3; </P> +<P>size[1] = 3; </P> +<P>status = H5Dextend (dataset, size);</P> +<P>/*</P> +<P>* Select a hyperslab.</P> +<P>*/</P> +<P>filespace = H5Dget_space (dataset);</P> +<P>offset[0] = 0;</P> +<P>offset[1] = 0;</P> +<P>status = H5Sset_hyperslab(filespace, offset, dims1, NULL); </P> +<P>/*</P> +<P>* Write the data to the hyperslab.</P> +<P>*/</P> +<P>status = H5Dwrite(dataset, H5T_NATIVE_INT, dataspace, filespace,</P> +<P>H5P_DEFAULT, data1);</P> +<P>/*</P> +<P>* Extend the dataset. Dataset becomes 10 x 3.</P> +<P>*/</P> +<P>dims[0] = dims1[0] + dims2[0];</P> +<P>size[0] = dims[0]; </P> +<P>size[1] = dims[1]; </P> +<P>status = H5Dextend (dataset, size);</P> +<P>/*</P> +<P>* Select a hyperslab.</P> +<P>*/</P> +<P>filespace = H5Dget_space (dataset);</P> +<P>offset[0] = 3;</P> +<P>offset[1] = 0;</P> +<P>status = H5Sset_hyperslab(filespace, offset, dims2, NULL); </P> +<P>/*</P> +<P>* Define memory space</P> +<P>*/</P> +<P>dataspace = H5Screate_simple(RANK, dims2, NULL); </P> +<P>/*</P> +<P>* Write the data to the hyperslab.</P> +<P>*/</P> +<P>status = H5Dwrite(dataset, H5T_NATIVE_INT, dataspace, filespace,</P> +<P>H5P_DEFAULT, data2);</P> +<P>/*</P> +<P>* Extend the dataset. Dataset becomes 10 x 5.</P> +<P>*/</P> +<P>dims[1] = dims1[1] + dims3[1];</P> +<P>size[0] = dims[0]; </P> +<P>size[1] = dims[1]; </P> +<P>status = H5Dextend (dataset, size);</P> +<P>/*</P> +<P>* Select a hyperslab</P> +<P>*/</P> +<P>filespace = H5Dget_space (dataset);</P> +<P>offset[0] = 0;</P> +<P>offset[1] = 3;</P> +<P>status = H5Sset_hyperslab(filespace, offset, dims3, NULL); </P> +<P>/*</P> +<P>* Define memory space.</P> +<P>*/</P> +<P>dataspace = H5Screate_simple(RANK, dims3, NULL); </P> +<P>/*</P> +<P>* Write the data to the hyperslab.</P> +<P>*/</P> +<P>status = H5Dwrite(dataset, H5T_NATIVE_INT, dataspace, filespace,</P> +<P>H5P_DEFAULT, data3);</P> +<P>/*</P> +<P>* Resulting dataset</P> +<P>* </P> +<P>3 3 3 2 2</P> +<P>3 3 3 2 2</P> +<P>3 3 3 0 0</P> +<P>2 0 0 0 0</P> +<P>2 0 0 0 0</P> +<P>2 0 0 0 0</P> +<P>2 0 0 0 0</P> +<P>2 0 0 0 0</P> +<P>2 0 0 0 0</P> +<P>2 0 0 0 0</P> +<P>*/ </P> +<P>/*</P> +<P>* Close/release resources.</P> +<P>*/</P> +<P>H5Dclose(dataset);</P> +<P>H5Sclose(dataspace);</P> +<P>H5Sclose(filespace);</P> +<P>H5Fclose(file);</P> +<P>} </P> +</CODE></PRE> +<P> </P> +<H4><A NAME="GroupExample">Example 5. Creating groups.</A></H4> +<P>This example shows how to create an HDF5 file with two groups, and to place some datasets within those groups.</P> +<CODE><PRE><P>/*</P> +<P>* This example shows how to create groups within the file and </P> +<P>* datasets within the file and groups.</P> +<P>*/ </P> +<P> </P> +<P>#include "hdf5.h"</P> +<P> </P> +<P>#define FILE "DIR.h5"</P> +<P>#define RANK 2</P> +<P>main()</P> +<P>{</P> +<P>hid_t file, dir;</P> +<P>hid_t dataset, dataspace;</P> +<P>herr_t status;</P> +<P>hsize_t dims[2];</P> +<P>hsize_t size[1];</P> +<P>/*</P> +<P>* Create a file.</P> +<P>*/</P> +<P>file = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);</P> +<P>/*</P> +<P>* Create two groups in a file.</P> +<P>*/</P> +<P>dir = H5Gcreate(file, "/IntData", 0);</P> +<P>status = H5Gclose(dir);</P> +<P>dir = H5Gcreate(file,"/FloatData", 0);</P> +<P>status = H5Gclose(dir);</P> +<P>/* </P> +<P>* Create dataspace for the character string</P> +<P>*/</P> +<P>size[0] = 80;</P> +<P>dataspace = H5Screate_simple(1, size, NULL);</P> +<P>/*</P> +<P>* Create dataset "String" in the root group. </P> +<P>*/</P> +<P>dataset = H5Dcreate(file, "String", H5T_NATIVE_CHAR, dataspace, H5P_DEFAULT);</P> +<P>H5Dclose(dataset);</P> +<P>/*</P> +<P>* Create dataset "String" in the /IntData group. </P> +<P>*/</P> +<P>dataset = H5Dcreate(file, "/IntData/String", H5T_NATIVE_CHAR, dataspace,</P> +<P>H5P_DEFAULT);</P> +<P>H5Dclose(dataset);</P> +<P>/*</P> +<P>* Create dataset "String" in the /FloatData group. </P> +<P>*/</P> +<P>dataset = H5Dcreate(file, "/FloatData/String", H5T_NATIVE_CHAR, dataspace,</P> +<P>H5P_DEFAULT);</P> +<P>H5Sclose(dataspace);</P> +<P>H5Dclose(dataset);</P> +<P>/*</P> +<P>* Create IntArray dataset in the /IntData group by specifying full path.</P> +<P>*/</P> +<P>dims[0] = 2;</P> +<P>dims[1] = 3;</P> +<P>dataspace = H5Screate_simple(RANK, dims, NULL);</P> +<P>dataset = H5Dcreate(file, "/IntData/IntArray", H5T_NATIVE_INT, dataspace,</P> +<P>H5P_DEFAULT); </P> +<P>H5Sclose(dataspace);</P> +<P>H5Dclose(dataset);</P> +<P>/*</P> +<P>* Set current group to /IntData and attach to the dataset String.</P> +<P>*/</P> +<P>status = H5Gset (file, "/IntData");</P> +<P>dataset = H5Dopen(file, "String");</P> +<P>if (dataset > 0) printf("String dataset in /IntData group is found\n"); </P> +<P>H5Dclose(dataset);</P> +<P>/*</P> +<P>* Set current group to /FloatData.</P> +<P>*/</P> +<P>status = H5Gset (file, "/FloatData");</P> +<P>/* </P> +<P>* Create two datasets FlatArray and DoubleArray.</P> +<P>*/</P> +<P>dims[0] = 5;</P> +<P>dims[1] = 10;</P> +<P>dataspace = H5Screate_simple(RANK, dims, NULL);</P> +<P>dataset = H5Dcreate(file, "FloatArray", H5T_NATIVE_FLOAT, dataspace, H5P_DEFAULT); </P> +<P>H5Sclose(dataspace);</P> +<P>H5Dclose(dataset);</P> +<P>dims[0] = 4;</P> +<P>dims[1] = 6;</P> +<P>dataspace = H5Screate_simple(RANK, dims, NULL);</P> +<P>dataset = H5Dcreate(file, "DoubleArray", H5T_NATIVE_DOUBLE, dataspace,</P> +<P>H5P_DEFAULT); </P> +<P>H5Sclose(dataspace);</P> +<P>H5Dclose(dataset);</P> +<P>/* </P> +<P>* Attach to /FloatData/String dataset.</P> +<P>*/</P> +<P>dataset = H5Dopen(file, "/FloatData/String");</P> +<P>if (dataset > 0) printf("/FloatData/String dataset is found\n"); </P> +<P>H5Dclose(dataset);</P> +<P>H5Fclose(file);</P> +<P>}</P></CODE></PRE></BODY> + +</HTML> diff --git a/doc/html/H5.sample_code.html b/doc/html/H5.sample_code.html new file mode 100644 index 0000000..b3e5336 --- /dev/null +++ b/doc/html/H5.sample_code.html @@ -0,0 +1,123 @@ +<html><head><title> +HDF5 Draft API Example Code +</title></head><body> + +<center> +<h1>HDF5: API Example Code</h1> +</center> + +<P>Example programs/sections of code below: +<dl COMPACT> + <dt><a href="#Example1">#1</a> + <dd>A simple example showing how to create a file. + <dt><a href="#Example2">#2</a> + <dd>A example showing how to create a homogenous multi-dimensional dataset. + <dt><a href="#Example3">#3</a> + <dd>A example showing how to read a generic dataset. +</dl> + +<hr> +<h2><a name="Example1">Simple Example showing how to create a file.</a></h2> + +<P>Notes:<br> +This example creates a new HDF5 file and allows write access. +If the file exists already, the H5F_ACC_TRUNC flag would also be necessary to +overwrite the previous file's information. + +<P>Code: + +<code> <pre> + hid_t file_id; + + file_id=<A HREF="H5.apiv2.html#File-Create">H5Fcreate</a>("example1.h5",H5F_ACC_EXCL,H5P_DEFAULT_TEMPLATE,H5P_DEFAULT_TEMPLATE); + + <A HREF="H5.apiv2.html#File-Close">H5Fclose</a>(file_id); + +</pre> </code> + +<hr> +<h2><a name="Example2">Example showing how create a homogenous multi-dimensional dataset.</a></h2> + +<P>Notes:<br> +This example creates a 4-dimensional dataset of 32-bit floating-point +numbers, corresponding to the current Scientific Dataset functionality. + +<P>Code: + +<code> <pre> + 1 hid_t file_id; /* new file's ID */ + 2 hid_t dim_id; /* new dimensionality's ID */ + 3 int rank=4; /* the number of dimensions */ + 4 hsize_t dims[4]={6,5,4,3}; /* the size of each dimension */ + 5 hid_t dataset_id; /* new dataset's ID */ + 6 float buf[6][5][4][3]; /* storage for the dataset's data */ + 7 herr_t status; /* function return status */ + 8 + 9 file_id = H5Fcreate ("example3.h5", H5F_ACC_TRUNC, H5P_DEFAULT, +10 H5P_DEFAULT); +11 assert (file_id >= 0); +12 +13 /* Create & initialize a dimensionality object */ +14 dim_id = H5Screate_simple (rank, dims); +15 assert (dim_id >= 0); +16 +17 /* Create & initialize the dataset object */ +18 dataset_id = H5Dcreate (file_id, "Simple Object", H5T_NATIVE_FLOAT, +19 dim_id, H5P_DEFAULT); +20 assert (dataset_id >= 0); +21 +22 <initialize data array> +23 +24 /* Write the entire dataset out */ +25 status = H5Dwrite (dataset_id, H5T_NATIVE_FLOAT, H5S_ALL, H5S_ALL, +26 H5P_DEFAULT, buf); +27 assert (status >= 0); +28 +29 /* Release the IDs we've created */ +30 H5Sclose (dim_id); +31 H5Dclose (dataset_id); +32 H5Fclose (file_id); +</pre> </code> + +<hr> +<h2><a name="Example3">Example showing how read a generic dataset.</a></h2> + +<P>Notes:<br> +This example shows how to get the information for and display a generic +dataset. + +<P>Code: + +<code> <pre> + 1 hid_t file_id; /* file's ID */ + 2 hid_t dataset_id; /* dataset's ID in memory */ + 3 hid_t space_id; /* dataspace's ID in memory */ + 4 uintn nelems; /* number of elements in array */ + 5 double *buf; /* pointer to the dataset's data */ + 6 herr_t status; /* function return value */ + 7 + 8 file_id = H5Fopen ("example6.h5", H5F_ACC_RDONLY, H5P_DEFAULT); + 9 assert (file_id >= 0); +10 +11 /* Attach to a datatype object */ +12 dataset_id = H5Dopen (file_id, "dataset1"); +13 assert (dataset_id >= 0); +14 +15 /* Get the OID for the dataspace */ +16 space_id = H5Dget_space (dataset_id); +17 assert (space_id >= 0); +18 +19 /* Allocate space for the data */ +20 nelems = H5Sget_npoints (space_id); +21 buf = malloc (nelems * sizeof(double)); +22 +23 /* Read in the dataset */ +24 status = H5Dread (dataset_id, H5T_NATIVE_DOUBLE, H5S_ALL,, H5S_ALL, +25 H5P_DEFAULT, buf); +26 assert (status >= 0); +27 +28 /* Release the IDs we've accessed */ +29 H5Sclose (space_id); +30 H5Dclose (dataset_id); +31 H5Fclose (file_id); +</pre> </code> diff --git a/doc/html/H5.user.html b/doc/html/H5.user.html new file mode 100644 index 0000000..3c16553 --- /dev/null +++ b/doc/html/H5.user.html @@ -0,0 +1,71 @@ +<html> + <head> + <title> + HDF5 Uer's Guide + </title> + </head> + + <body> + <center><h1>A User Guide for HDF5</h1></center> + + <p>The following documents form a loosely organized user's guide + to the HDF5 library. + + <ul> + <li><a href="Files.html">HDF5 Files</a> - + A guide to the H5F interface. + <li><a href="Datasets.html">Datasets</a> - + A guide to the H5D interface. + <li><a href="Datatypes.html">Data types</a> - + A guide to the H5T interface. + <li><a href="Dataspaces.html">Data spaces</a> - + A guide to the H5S interface. + <li><a href="Groups.html">Groups</a> - + A guide to the H5G interface. + <li><a href="Attributes.html">Attributes</a> - + A guide to the H5A interface. + <li><a href="Properties.html">Property lists</a> - + A guide to the H5P interface. + <li><a href="Errors.html">Error handling</a> - + A guide to the H5E interface. + <li><a href="Caching.html">Caching</a> - + A guide for meta and raw data caching. + </ul> + + <p>The following documents form a loosely organized developer's guide to + aspects of the HDF5 library. (Some of the following documents + may be rather out of date as they were working papers for design + goals.) + + <ul> + <li><a href="Version.html">Version Numbers</a> - + A description of HDF5 version numbers. + <li><a href="IOPipe.html">I/O Pipeline</a> - + A description of the raw data I/O pipeline. + <li><a href="Compression.html">Compression</a> - + A guide to the use of compression for datasets. + <li><a href="ExternalFiles.html">Working with external files</a> - + A guide to the use of multiple files with HDF5. + <li><a href="Big.html">Large Datasets</a> - + A guide to accessing large datasets on small computers. + <li><a href="MemoryManagement.html">Memory management</a> - + A white paper about memory management issues in HDF5. + <li><a href="Coding.html">Coding style</a> - + A white paper about coding style in the HDF5 library code. + <li><a href="compat.html">HDF4/HDF5 compatibility</a> - + A white paper about compatibility issues between HDF4 and HDF5. + <li><a href="study.html">Chunking performance study</a> - + A white paper describing the HDF5 chunking performance. + </ul> + + + + <hr> + <address><a href="mailto:koziol@ncsa.uiuc.edu">Quincey Koziol</a></address> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- hhmts start --> +Last modified: Tue May 26 15:39:47 EDT 1998 +<!-- hhmts end --> + + </body> +</html> diff --git a/doc/html/IOPipe.html b/doc/html/IOPipe.html new file mode 100644 index 0000000..7c24e2c --- /dev/null +++ b/doc/html/IOPipe.html @@ -0,0 +1,114 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>The Raw Data I/O Pipeline</title> + </head> + + <body> + <h1>The Raw Data I/O Pipeline</h1> + + <p>The HDF5 raw data pipeline is a complicated beast that handles + all aspects of raw data storage and transfer of that data + between the file and the application. Data can be stored + contiguously (internal or external), in variable size external + segments, or regularly chunked; it can be sparse, extendible, + and/or compressible. Data transfers must be able to convert from + one data space to another, convert from one number type to + another, and perform partial I/O operations. Furthermore, + applications will expect their common usage of the pipeline to + perform well. + + <p>To accomplish these goals, the pipeline has been designed in a + modular way so no single subroutine is overly complicated and so + functionality can be inserted easily at the appropriate + locations in the pipeline. A general pipeline was developed and + then certain paths through the pipeline were optimized for + performance. + + <p>We describe only the file-to-memory side of the pipeline since + the memory-to-file side is a mirror image. We also assume that a + proper hyperslab of a simple data space is being read from the + file into a proper hyperslab of a simple data space in memory, + and that the data type is a compound type which may require + various number conversions on its members. + + <img alt="Figure 1" src="pipe1.gif"> + + <p>The diagrams should be read from the top down. The Line A + in the figure above shows that <code>H5Dread()</code> copies + data from a hyperslab of a file dataset to a hyperslab of an + application buffer by calling <code>H5D_read()</code>. And + <code>H5D_read()</code> calls, in a loop, + <code>H5S_simp_fgath()</code>, <code>H5T_conv_struct()</code>, + and <code>H5S_simp_mscat()</code>. A temporary buffer, TCONV, is + loaded with data points from the file, then data type conversion + is performed on the temporary buffer, and finally data points + are scattered out to application memory. Thus, data type + conversion is an in-place operation and data space conversion + consists of two steps. An additional temporary buffer, BKG, is + large enough to hold <em>N</em> instances of the destination + data type where <em>N</em> is the same number of data points + that can be held by the TCONV buffer (which is large enough to + hold either source or destination data points). + + <p>The application sets an upper limit for the size of the TCONV + buffer and optionally supplies a buffer. If no buffer is + supplied then one will be created by calling + <code>malloc()</code> when the pipeline is executed (when + necessary) and freed when the pipeline exits. The size of the + BKG buffer depends on the size of the TCONV buffer and if the + application supplies a BKG buffer it should be at least as large + as the TCONV buffer. The default size for these buffers is one + megabyte but the buffer might not be used to full capacity if + the buffer size is not an integer multiple of the source or + destination data point size (whichever is larger, but only + destination for the BKG buffer). + + + + <p>Occassionally the destination data points will be partially + initialized and the <code>H5Dread()</code> operation should not + clobber those values. For instance, the destination type might + be a struct with members <code>a</code> and <code>b</code> where + <code>a</code> is already initialized and we're reading + <code>b</code> from the file. An extra line, G, is added to the + pipeline to provide the type conversion functions with the + existing data. + + <img alt="Figure 2" src="pipe2.gif"> + + <p>It will most likely be quite common that no data type + conversion is necessary. In such cases a temporary buffer for + data type conversion is not needed and data space conversion + can happen in a single step. In fact, when the source and + destination data are both contiguous (they aren't in the + picture) the loop degenerates to a single iteration. + + + <img alt="Figure 3" src="pipe3.gif"> + + <p>So far we've looked only at internal contiguous storage, but by + replacing Line B in Figures 1 and 2 and Line A in Figure 3 with + Figure 4 the pipeline is able to handle regularly chunked + objects. Line B of Figure 4 is executed once for each chunk + which contains data to be read and the chunk address is found by + looking at a multi-dimensional key in a chunk B-tree which has + one entry per chunk. + + <img alt="Figure 4" src="pipe4.gif"> + + <p>If a single chunk is requested and the destination buffer is + the same size/shape as the chunk, then the CHUNK buffer is + bypassed and the destination buffer is used instead as shown in + Figure 5. + + <img alt="Figure 5" src="pipe5.gif"> + + <hr> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- Created: Tue Mar 17 11:13:35 EST 1998 --> +<!-- hhmts start --> +Last modified: Wed Mar 18 10:38:30 EST 1998 +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/MemoryManagement.html b/doc/html/MemoryManagement.html new file mode 100644 index 0000000..93782b5 --- /dev/null +++ b/doc/html/MemoryManagement.html @@ -0,0 +1,510 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>Memory Management in HDF5</title> + </head> + + <body> + <h1>Memory Management in HDF5</h1> + + <!-- ---------------------------------------------------------------- --> + <h2>Is a Memory Manager Necessary?</h2> + + <p>Some form of memory management may be necessary in HDF5 when + the various deletion operators are implemented so that the + file memory is not permanently orphaned. However, since an + HDF5 file was designed with persistent data in mind, the + importance of a memory manager is questionable. + + <p>On the other hand, when certain meta data containers (file glue) + grow, they may need to be relocated in order to keep the + container contiguous. + + <blockquote> + <b>Example:</b> An object header consists of up to two + chunks of contiguous memory. The first chunk is a fixed + size at a fixed location when the header link count is + greater than one. Thus, inserting additional items into an + object header may require the second chunk to expand. When + this occurs, the second chunk may need to move to another + location in the file, freeing the file memory which that + chunk originally occupied. + </blockquote> + + <p>The relocation of meta data containers could potentially + orphan a significant amount of file memory if the application + has made poor estimates for preallocation sizes. + + <!-- ---------------------------------------------------------------- --> + <h2>Levels of Memory Management</h2> + + <p>Memory management by the library can be independent of memory + management support by the file format. The file format can + support no memory management, some memory management, or full + memory management. Similarly with the library. + + <h3>Support in the Library</h3> + + <dl> + <dt><b>No Support: I</b> + <dd>When memory is deallocated it simply becomes unreferenced + (orphaned) in the file. Memory allocation requests are + satisfied by extending the file. + + <dd>A separate off-line utility can be used to detect the + unreferenced bytes of a file and "bubble" them up to the end + of the file and then truncate the file. + + <dt><b>Some Support: II</b> + <dd>The library could support partial memory management all + the time, or full memory management some of the time. + Orphaning free blocks instead of adding them to a free list + should not affect the file integrity, nor should fulfilling + new requests by extending the file instead of using the free + list. + + <dt><b>Full Support: III</b> + <dd>The library supports space-efficient memory management by + always fulfilling allocation requests from the free list when + possible, and by coalescing adjacent free blocks into a + single larger free block. + </dl> + + <h3>Support in the File Format</h3> + + <dl> + <dt><b>No Support: A</b> + <dd>The file format does not support memory management; any + unreferenced block in the file is assumed to be free. If + the library supports full memory management then it will + have to traverse the entire file to determine which blocks + are unreferenced. + + <dt><b>Some Support: B</b> + <dd>Assuming that unreferenced blocks are free can be + dangerous in a situation where the file is not consistent. + For instance, if a directory tree becomes detached from the + main directory hierarchy, then the detached directory and + everything that is referenced only through the detached + directory become unreferenced. File repair utilities will + be unable to determine which unreferenced blocks need to be + linked back into the file hierarchy. + + <dd>Therefore, it might be useful to keep an unsorted, + doubly-linked list of free blocks in the file. The library + can add and remove blocks from the list in constant time, + and can generate its own internal free-block data structure + in time proportional to the number of free blocks instead of + the size of the file. Additionally, a library can use a + subset of the free blocks, an alternative which is not + feasible if the file format doesn't support any form of + memory management. + + <dt><b>Full Support: C</b> + <dd>The file format can mirror library data structures for + space-efficient memory management. The free blocks are + linked in unsorted, doubly-linked lists with one list per + free block size. The heads of the lists are pointed to by a + B-tree whose nodes are sorted by free block size. At the + same time, all free blocks are the leaf nodes of another + B-tree sorted by starting and ending address. When the + trees are used in combination we can deallocate and allocate + memory in O(log <em>N</em>) time where <em>N</em> is the + number of free blocks. + </dl> + + <h3>Combinations of Library and File Format Support</h3> + + <p>We now evaluate each combination of library support with file + support: + + <dl> + <dt><b>I-A</b> + <dd>If neither the library nor the file support memory + management, then each allocation request will come from the + end of the file and each deallocation request is a no-op + that simply leaves the free block unreferenced. + + <ul> + <li>Advantages + <ul> + <li>No file overhead for allocation or deallocation. + <li>No library overhead for allocation or + deallocation. + <li>No file traversal required at time of open. + <li>No data needs to be written back to the file when + it's closed. + <li>Trivial to implement (already implemented). + </ul> + + <li>Disadvantages + <ul> + <li>Inefficient use of file space. + <li>A file repair utility must reclaim lost file space. + <li>Difficulties for file repair utilities. (Is an + unreferenced block a free block or orphaned data?) + </ul> + </ul> + + <dt><b>II-A</b> + <dd>In order for the library to support memory management, it + will be required to build the internal free block + representation by traversing the entire file looking for + unreferenced blocks. + + <ul> + <li>Advantages + <ul> + <li>No file overhead for allocation or deallocation. + <li>Variable amount of library overhead for allocation + and deallocation depending on how much work the + library wants to do. + <li>No data needs to be written back to the file when + it's closed. + <li>Might use file space efficiently. + </ul> + <li>Disadvantages + <ul> + <li>Might use file space inefficiently. + <li>File traversal required at time of open. + <li>A file repair utility must reclaim lost file space. + <li>Difficulties for file repair utilities. + <li>Sharing of the free list between processes falls + outside the HDF5 file format documentation. + </ul> + </ul> + + <dt><b>III-A</b> + <dd>In order for the library to support full memory + management, it will be required to build the internal free + block representation by traversing the entire file looking + for unreferenced blocks. + + <ul> + <li>Advantages + <ul> + <li>No file overhead for allocation or deallocation. + <li>Efficient use of file space. + <li>No data needs to be written back to the file when + it's closed. + </ul> + <li>Disadvantages + <ul> + <li>Moderate amount of library overhead for allocation + and deallocation. + <li>File traversal required at time of open. + <li>A file repair utility must reclaim lost file space. + <li>Difficulties for file repair utilities. + <li>Sharing of the free list between processes falls + outside the HDF5 file format documentation. + </ul> + </ul> + + <dt><b>I-B</b> + <dd>If the library doesn't support memory management but the + file format supports some level of management, then a file + repair utility will have to be run occasionally to reclaim + unreferenced blocks. + + <ul> + <li>Advantages + <ul> + <li>No file overhead for allocation or deallocation. + <li>No library overhead for allocation or + deallocation. + <li>No file traversal required at time of open. + <li>No data needs to be written back to the file when + it's closed. + </ul> + <li>Disadvantages + <ul> + <li>A file repair utility must reclaim lost file space. + <li>Difficulties for file repair utilities. + </ul> + </ul> + + <dt><b>II-B</b> + <dd>Both the library and the file format support some level + of memory management. + + <ul> + <li>Advantages + <ul> + <li>Constant file overhead per allocation or + deallocation. + <li>Variable library overhead per allocation or + deallocation depending on how much work the library + wants to do. + <li>Traversal at file open time is on the order of the + free list size instead of the file size. + <li>The library has the option of reading only part of + the free list. + <li>No data needs to be written at file close time if + it has been amortized into the cost of allocation + and deallocation. + <li>File repair utilties don't have to be run to + reclaim memory. + <li>File repair utilities can detect whether an + unreferenced block is a free block or orphaned data. + <li>Sharing of the free list between processes might + be easier. + <li>Possible efficient use of file space. + </ul> + <li>Disadvantages + <ul> + <li>Possible inefficient use of file space. + </ul> + </ul> + + <dt><b>III-B</b> + <dd>The library provides space-efficient memory management but + the file format only supports an unsorted list of free + blocks. + + <ul> + <li>Advantages + <ul> + <li>Constant time file overhead per allocation or + deallocation. + <li>No data needs to be written at file close time if + it has been amortized into the cost of allocation + and deallocation. + <li>File repair utilities don't have to be run to + reclaim memory. + <li>File repair utilities can detect whether an + unreferenced block is a free block or orphaned data. + <li>Sharing of the free list between processes might + be easier. + <li>Efficient use of file space. + </ul> + <li>Disadvantages + <ul> + <li>O(log <em>N</em>) library overhead per allocation or + deallocation where <em>N</em> is the total number of + free blocks. + <li>O(<em>N</em>) time to open a file since the entire + free list must be read to construct the in-core + trees used by the library. + <li>Library is more complicated. + </ul> + </ul> + + <dt><b>I-C</b> + <dd>This has the same advantages and disadvantages as I-C with + the added disadvantage that the file format is much more + complicated. + + <dt><b>II-C</b> + <dd>If the library only provides partial memory management but + the file requires full memory management, then this method + degenerates to the same as II-A with the added disadvantage + that the file format is much more complicated. + + <dt><b>III-C</b> + <dd>The library and file format both provide complete data + structures for space-efficient memory management. + + <ul> + <li>Advantages + <ul> + <li>Files can be opened in constant time since the + free list is read on demand and amortised into the + allocation and deallocation requests. + <li>No data needs to be written back to the file when + it's closed. + <li>File repair utilities don't have to be run to + reclaim memory. + <li>File repair utilities can detect whether an + unreferenced block is a free block or orphaned data. + <li>Sharing the free list between processes is easy. + <li>Efficient use of file space. + </ul> + <li>Disadvantages + <ul> + <li>O(log <em>N</em>) file allocation and deallocation + cost where <em>N</em> is the total number of free + blocks. + <li>O(log <em>N</em>) library allocation and + deallocation cost. + <li>Much more complicated file format. + <li>More complicated library. + </ul> + </ul> + + </dl> + + <!-- ---------------------------------------------------------------- --> + <h2>The Algorithm for II-B</h2> + + <p>The file contains an unsorted, doubly-linked list of free + blocks. The address of the head of the list appears in the + boot block. Each free block contains the following fields: + + <center> + <table border cellpadding=4 width="60%"> + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + <tr align=center> + <th colspan=4>Free Block Signature</th> + + <tr align=center> + <th colspan=4>Total Free Block Size</th> + + <tr align=center> + <th colspan=4>Address of Left Sibling</th> + + <tr align=center> + <th colspan=4>Address of Right Sibling</th> + + <tr align=center> + <th colspan=4><br><br>Remainder of Free Block<br><br><br></th> + </table> + </center> + + <p>The library reads as much of the free list as convenient when + convenient and pushes those entries onto stacks. This can + occur when a file is opened or any time during the life of the + file. There is one stack for each free block size and the + stacks are sorted by size in a balanced tree in memory. + + <p>Deallocation involves finding the correct stack or creating + a new one (an O(log <em>K</em>) operation where <em>K</em> is + the number of stacks), pushing the free block info onto the + stack (a constant-time operation), and inserting the free + block into the file free block list (a constant-time operation + which doesn't necessarily involve any I/O since the free blocks + can be cached like other objects). No attempt is made to + coalesce adjacent free blocks into larger blocks. + + <p>Allocation involves finding the correct stack (an O(log + <em>K</em>) operation), removing the top item from the stack + (a constant-time operation), and removing the block from the + file free block list (a constant-time operation). If there is + no free block of the requested size or larger, then the file + is extended. + + <p>To provide sharability of the free list between processes, + the last step of an allocation will check for the free block + signature and if it doesn't find one will repeat the process. + Alternatively, a process can temporarily remove free blocks + from the file and hold them in it's own private pool. + + <p>To summarize... + <dl> + <dt>File opening + <dd>O(<em>N</em>) amortized over the time the file is open, + where <em>N</em> is the number of free blocks. The library + can still function without reading any of the file free + block list. + + <dt>Deallocation + <dd>O(log <em>K</em>) where <em>K</em> is the number of unique + sizes of free blocks. File access is constant. + + <dt>Allocation + <dd>O(log <em>K</em>). File access is constant. + + <dt>File closing + <dd>O(1) even if the library temporarily removes free + blocks from the file to hold them in a private pool since + the pool can still be a linked list on disk. + </dl> + + <!-- ---------------------------------------------------------------- --> + <h2>The Algorithm for III-C</h2> + + <p>The HDF5 file format supports a general B-tree mechanism + for storing data with keys. If we use a B-tree to represent + all parts of the file that are free and the B-tree is indexed + so that a free file chunk can be found if we know the starting + or ending address, then we can efficiently determine whether a + free chunk begins or ends at the specified address. Call this + the <em>Address B-Tree</em>. + + <p>If a second B-tree points to a set of stacks where the + members of a particular stack are all free chunks of the same + size, and the tree is indexed by chunk size, then we can + efficiently find the best-fit chunk size for a memory request. + Call this the <em>Size B-Tree</em>. + + <p>All free blocks of a particular size can be linked together + with an unsorted, doubly-linked, circular list and the left + and right sibling addresses can be stored within the free + chunk, allowing us to remove or insert items from the list in + constant time. + + <p>Deallocation of a block fo file memory consists of: + + <ol type="I"> + <li>Add the new free block whose address is <em>ADDR</em> to the + address B-tree. + + <ol type="A"> + <li>If the address B-tree contains an entry for a free + block that ends at <em>ADDR</em>-1 then remove that + block from the B-tree and from the linked list (if the + block was the first on the list then the size B-tree + must be updated). Adjust the size and address of the + block being freed to include the block just removed from + the free list. The time required to search for and + possibly remove the left block is O(log <em>N</em>) + where <em>N</em> is the number of free blocks. + + <li>If the address B-tree contains an entry for the free + block that begins at <em>ADDR</em>+<em>LENGTH</em> then + remove that block from the B-tree and from the linked + list (if the block was the first on the list then the + size B-tree must be updated). Adjust the size of the + block being freed to include the block just removed from + the free list. The time required to search for and + possibly remove the right block is O(log <em>N</em>). + + <li>Add the new (adjusted) block to the address B-tree. + The time for this operation is O(log <em>N</em>). + </ol> + + <li>Add the new block to the size B-tree and linked list. + + <ol type="A"> + <li>If the size B-tree has an entry for this particular + size, then add the chunk to the tail of the list. This + is an O(log <em>K</em>) operation where <em>K</em> is + the number of unique free block sizes. + + <li>Otherwise make a new entry in the B-tree for chunks of + this size. This is also O(log <em>K</em>). + </ol> + </ol> + + <p>Allocation is similar to deallocation. + + <p>To summarize... + + <dl> + <dt>File opening + <dd>O(1) + + <dt>Deallocation + <dd>O(log <em>N</em>) where <em>N</em> is the total number of + free blocks. File access time is O(log <em>N</em>). + + <dt>Allocation + <dd>O(log <em>N</em>). File access time is O(log <em>N</em>). + + <dt>File closing + <dd>O(1). + </dl> + + + <hr> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- Created: Thu Jul 24 15:16:40 PDT 1997 --> +<!-- hhmts start --> +Last modified: Thu Jul 31 14:41:01 EST +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/ObjectHeader.txt b/doc/html/ObjectHeader.txt new file mode 100644 index 0000000..d769377 --- /dev/null +++ b/doc/html/ObjectHeader.txt @@ -0,0 +1,60 @@ +OBJECT HEADERS +-------------- + +haddr_t +H5O_new (hdf5_file_t *f, intn nrefs, size_t size_hint) + + Creates a new empty object header and returns its address. + The SIZE_HINT is the initial size of the data portion of the + object header and NREFS is the number of symbol table entries + that reference this object header (normally one). + + If SIZE_HINT is too small, then at least some default amount + of space is allocated for the object header. + +intn /*num remaining links */ +H5O_link (hdf5_file_t *f, /*file containing header */ + haddr_t addr, /*header file address */ + intn adjust) /*link adjustment amount */ + + +size_t +H5O_sizeof (hdf5_file_t *f, /*file containing header */ + haddr_t addr, /*header file address */ + H5O_class_t *type, /*message type or H5O_ANY */ + intn sequence) /*sequence number, usually zero */ + + Returns the size of a particular instance of a message in an + object header. When an object header has more than one + instance of a particular message type, then SEQUENCE indicates + which instance to return. + +void * +H5O_read (hdf5_file_t *f, /*file containing header */ + haddr_t addr, /*header file address */ + H5G_entry_t *ent, /*optional symbol table entry */ + H5O_class_t *type, /*message type or H5O_ANY */ + intn sequence, /*sequence number, usually zero */ + size_t size, /*size of output message */ + void *mesg) /*output buffer */ + + Reads a message from the object header into memory. + +const void * +H5O_peek (hdf5_file_t *f, /*file containing header */ + haddr_t addr, /*header file address */ + H5G_entry_t *ent, /*optional symbol table entry */ + H5O_class_t *type, /*type of message or H5O_ANY */ + intn sequence) /*sequence number, usually zero */ + +haddr_t /*new heap address */ +H5O_modify (hdf5_file_t *f, /*file containing header */ + haddr_t addr, /*header file address */ + H5G_entry_t *ent, /*optional symbol table entry */ + hbool_t *ent_modified, /*entry modification flag */ + H5O_class_t *type, /*message type */ + intn overwrite, /*sequence number or -1 */ + void *mesg) /*the message */ + + + diff --git a/doc/html/Properties.html b/doc/html/Properties.html new file mode 100644 index 0000000..5b6c03f --- /dev/null +++ b/doc/html/Properties.html @@ -0,0 +1,81 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>Property List Interface (H5P)</title> + </head> + + <body> + <h1>Property List Interface (H5P)</h1> + + <h2>1. Introduction</h2> + + <p>The property list (a.k.a., template) interface provides a + mechanism for default named arguments for a C function + interface. A property list is a collection of name/value pairs + which can be passed to various other HDF5 functions to control + features that are typically unimportant or whose default values + are usually used. + + <p>For instance, file creation needs to know various things such + as the size of the user-block at the beginning of the file, or + the size of various file data structures. Wrapping this + information in a property list simplifies the API by reducing + the number of arguments to <code>H5Fcreate()</code>. + + <h2>2. General Property List Operations</h2> + + <p>Property lists follow the same create/open/close paradigm as + the rest of the library. + + <dl> + <dt><code>hid_t H5Pcreate (H5P_class_t <em>class</em>)</code> + <dd>A new property list can be created as an instance of some + property list class. The new property list is initialized + with default values for the specified class. The classes are: + + <br><br> + <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> + + <br><br> + <dt><code>hid_t H5Pcopy (hid_t <em>plist</em>)</code> + <dd>A property list can be copied to create a new property + list. The new property list has the same properties and values + as the original property list. + + <br><br> + <dt><code>herr_t H5Pclose (hid_t <em>plist</em>)</code> + <dd>All property lists should be closed when the application is + finished accessing them. This frees resources used by the + property list. + + <br><br> + <dt><code>H5P_class_t H5Pget_class (hid_t <em>plist</em>)</code> + <dd>The class of which the property list is a member can be + obtained by calling this function. The property list classes + are defined above for <code>H5Pcreate()</code>. + </dl> + + <hr> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> + <address><a href="mailto:koziol@ncsa.uiuc.edu">Quincey Koziol</a></address> +<!-- Created: Tue Feb 10 17:06:58 PST 1998 --> +<!-- hhmts start --> +Last modified: Tue Feb 10 17:26:41 PST 1998 +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/Version.html b/doc/html/Version.html new file mode 100644 index 0000000..6e4af9f --- /dev/null +++ b/doc/html/Version.html @@ -0,0 +1,139 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>Version Numbers</title> + </head> + + <body> + <h1>Version Numbers</h1> + + <h2>1. Introduction</h2> + + <p>The HDF5 version number is a set of three integer values and + one lower-case letter written as, for example, + <code>hdf5-1.2.0a</code>. + + <p>The <code>5</code> is part of the library name and will only + change if the entire file format and library are redesigned + similar in scope to the changes between HDF4 and HDF5. + + <p>The <code>1</code> is the <em>major version number</em> and + changes when there is an extensive change to the file format or + library. Such a change will likely require files to be + translated and applications to be modified. This number is not + expected to change frequently. + + <p>The <code>2</code> is the <em>minor version number</em> and is + incremented by each public release that presents new features. + Even numbers are reserved for stable public versions of the + library while odd numbers are reserved for developement + versions. See the diagram below for examples. + + <p>The <code>0</code> is the <em>release number</em>. For public + versions of the library, the release number is incremented each + time a bug(s) is fixed and the fix is made available to the + public. For development versions, the release number is + incremented automatically each time a CVS commit occurs anywhere + in the source tree. + + <p>The <code>a</code> is the <em>patch level</em> and is used only + for public versions. It's incremented only for very minor + changes that don't affect the usability of the library. For + instance, fixing spelling errors, changing warning messages, or + updating documentation. + + <h2>2. Abbreviated Versions</h2> + + <p>It's often convenient to drop the patch level and release + number when referring to a version of the library, like saying + version 1.2 of HDF5. The release number and patch level can be + any value in this case. + + <h2>3. Special Versions</h2> + + <p>Version 1.0.0 was released for alpha testing the first week of + March, 1998. The developement version number was incremented to + 1.0.1 and remained constant until the the last week of April, + when the release number started to increase and development + versions were made available to people outside the core HDF5 + development team. + + <p>Version 1.1.0 will be the first official beta release but the + 1.1 branch will also serve as a development branch since we're + not concerned about providing bug fixes separate from normal + development for the beta version. + + <p>Version 1.2 will be the first official HDF5 version. The + version tree will fork at this point with public bug fixes + provided on the 1.2 branch and development will continue on the + 1.3 branch. + + <h2>4. Public versus Development</h2> + + <p>The motivation for separate public and development versions is + that the public version will receive only bug fixes while the + development version will receive new features. + + <p>Eventually, the development version will near completion and a + new development branch will fork while the original one enters a + feature freeze state. When the original development branch is + ready for release the minor version number will be incremented + to an even value. + + <p> + <center> + <img alt="Version Example" src="version.gif"> + <br><b>Fig 1: Version Example</b> + </center> + + <h2>5. Version Support from the Library</h2> + + <p>The library provides a set of macros and functions to query and + check version numbers. + + <dl> + <dt><code>H5_VERS_MAJOR</code> + <dt><code>H5_VERS_MINOR</code> + <dt><code>H5_VERS_RELEASE</code> + <dt><code>H5_VERS_PATCH</code> + <dd>These preprocessor constants are defined in the public + include file and determine the version of the include files. + + <br><br> + <dt><code>herr_t H5version (unsigned *<em>majnum</em>, unsigned + *<em>minnum</em>, unsigned *<em>relnum</em>, unsigned + *<em>patnum</em>)</code> + <dd>This function returns through its arguments the version + numbers for the library to which the application is linked. + + <br><br> + <dt><code>void H5check(void)</code> + <dd>This is a macro that verifies that the version number of the + HDF5 include file used to compile the application matches the + version number of the library to which the application is + linked. This check occurs automatically when the first HDF5 + file is created or opened and is important because a mismatch + between the include files and the library is likely to result + in corrupted data and/or segmentation faults. If a mismatch + is detected the library issues an error message on the + standard error stream and aborts with a core dump. + + <br><br> + <dt><code>herr_t H5vers_check (unsigned <em>majnum</em>, + unsigned <em>minnum</em>, unsigned <em>relnum</em>, unsigned + <em>patnum</em>)</code> + <dd>This function is called by the <code>H5check()</code> macro + with the include file version constants. The function + compares its arguments to the result returned by + <code>H5version()</code> and if a mismatch is detected prints + an error message on the standard error stream and aborts. + </dl> + + <hr> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- Created: Wed Apr 22 11:24:40 EDT 1998 --> +<!-- hhmts start --> +Last modified: Wed Apr 22 12:19:53 EDT 1998 +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/chunk1.gif b/doc/html/chunk1.gif Binary files differnew file mode 100644 index 0000000..0260818 --- /dev/null +++ b/doc/html/chunk1.gif diff --git a/doc/html/chunk1.obj b/doc/html/chunk1.obj new file mode 100644 index 0000000..5936b0c --- /dev/null +++ b/doc/html/chunk1.obj @@ -0,0 +1,52 @@ +%TGIF 3.0-p5 +state(0,33,100,0,0,0,16,1,9,1,1,0,0,3,0,1,1,'Courier',0,17,0,0,0,10,0,0,1,1,0,16,0,0,1,1,1,0,1088,1408,0,0,2880). +% +% @(#)$Header$ +% %W% +% +unit("1 pixel/pixel"). +page(1,"",1). +box('black',64,64,384,384,5,2,1,29,0,0,0,0,0,'2',[ +]). +poly('black',2,[ + 128,64,128,384],0,2,1,30,0,4,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',2,[ + 192,64,192,384],0,2,1,31,0,4,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',2,[ + 256,64,256,384],0,2,1,32,0,4,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',2,[ + 320,64,320,384],0,2,1,33,0,4,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',2,[ + 64,128,384,128],0,2,1,34,0,4,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',2,[ + 64,192,384,192],0,2,1,35,0,4,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',2,[ + 64,256,384,256],0,2,1,36,0,4,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',2,[ + 64,320,384,320],0,2,1,37,0,4,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +box('black',128,448,192,512,5,2,1,56,0,0,0,0,0,'2',[ +]). +text('black',448,208,'Courier',0,17,2,1,0,1,84,28,61,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Entire array", + "5000 x 5000"]). +text('black',256,464,'Courier',0,17,2,1,0,1,84,28,63,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Single Chunk", + "1000 x 1000"]). +box('black',48,48,512,528,0,1,1,71,0,0,0,0,0,'1',[ +]). diff --git a/doc/html/compat.html b/doc/html/compat.html new file mode 100644 index 0000000..2992476 --- /dev/null +++ b/doc/html/compat.html @@ -0,0 +1,271 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>Backward/Forward Compatability</title> + </head> + + <body> + <h1>Backward/Forward Compatability</h1> + + <p>The HDF5 development must proceed in such a manner as to + satisfy the following conditions: + + <ol type=A> + <li>HDF5 applications can produce data that HDF5 + applications can read and write and HDF4 applications can produce + data that HDF4 applications can read and write. The situation + that demands this condition is obvious.</li> + + <li>HDF5 applications are able to produce data that HDF4 applications + can read and HDF4 applications can subsequently modify the + file subject to certain constraints depending on the + implementation. This condition is for the temporary + situation where a consumer has neither been relinked with a new + HDF4 API built on top of the HDF5 API nor recompiled with the + HDF5 API.</li> + + <li>HDF5 applications can read existing HDF4 files and subsequently + modify the file subject to certain constraints depending on + the implementation. This is condition is for the temporary + situation in which the producer has neither been relinked with a + new HDF4 API built on top of the HDF5 API nor recompiled with + the HDF5 API, or the permanent situation of HDF5 consumers + reading archived HDF4 files.</li> + </ul> + + <p>There's at least one invarient: new object features introduced + in the HDF5 file format (like 2-d arrays of structs) might be + impossible to "translate" to a format that an old HDF4 + application can understand either because the HDF4 file format + or the HDF4 API has no mechanism to describe the object. + + <p>What follows is one possible implementation based on how + Condition B was solved in the AIO/PDB world. It also attempts + to satisfy these goals: + + <ol type=1> + <li>The main HDF5 library contains as little extra baggage as + possible by either relying on external programs to take care + of compatability issues or by incorporating the logic of such + programs as optional modules in the HDF5 library. Conditions B + and C are separate programs/modules.</li> + + <li>No extra baggage not only means the library proper is small, + but also means it can be implemented (rather than migrated + from HDF4 source) from the ground up with minimal regard for + HDF4 thus keeping the logic straight forward.</li> + + <li>Compatability issues are handled behind the scenes when + necessary (and possible) but can be carried out explicitly + during things like data migration.</li> + </ol> + + <hr> + <h2>Wrappers</h2> + + <p>The proposed implementation uses <i>wrappers</i> to handle + compatability issues. A Format-X file is <i>wrapped</i> in a + Format-Y file by creating a Format-Y skeleton that replicates + the Format-X meta data. The Format-Y skeleton points to the raw + data stored in Format-X without moving the raw data. The + restriction is that raw data storage methods in Format-Y is a + superset of raw data storage methods in Format-X (otherwise the + raw data must be copied to Format-Y). We're assuming that meta + data is small wrt the entire file. + + <p>The wrapper can be a separate file that has pointers into the + first file or it can be contained within the first file. If + contained in a single file, the file can appear as a Format-Y + file or simultaneously a Format-Y and Format-X file. + + <p>The Format-X meta-data can be thought of as the original + wrapper around raw data and Format-Y is a second wrapper around + the same data. The wrappers are independend of one another; + modifying the meta-data in one wrapper causes the other to + become out of date. Modification of raw data doesn't invalidate + either view as long as the meta data that describes its storage + isn't modifed. For instance, an array element can change values + if storage is already allocated for the element, but if storage + isn't allocated then the meta data describing the storage must + change, invalidating all wrappers but one. + + <p>It's perfectly legal to modify the meta data of one wrapper + without modifying the meta data in the other wrapper(s). The + illegal part is accessing the raw data through a wrapper which + is out of date. + + <p>If raw data is wrapped by more than one internal wrapper + (<i>internal</i> means that the wrapper is in the same file as + the raw data) then access to that file must assume that + unreferenced parts of that file contain meta data for another + wrapper and cannot be reclaimed as free memory. + + <hr> + <h2>Implementation of Condition B</h2> + + <p>Since this is a temporary situation which can't be + automatically detected by the HDF5 library, we must rely + on the application to notify the HDF5 library whether or not it + must satisfy Condition B. (Even if we don't rely on the + application, at some point someone is going to remove the + Condition B constraint from the library.) So the module that + handles Condition B is conditionally compiled and then enabled + on a per-file basis. + + <p>If the application desires to produce an HDF4 file (determined + by arguments to <code>H5Fopen</code>), and the Condition B + module is compiled into the library, then <code>H5Fclose</code> + calls the module to traverse the HDF5 wrapper and generate an + additional internal or external HDF4 wrapper (wrapper specifics + are described below). If Condition B is implemented as a module + then it can benefit from the metadata already cached by the main + library. + + <p>An internal HDF4 wrapper would be used if the HDF5 file is + writable and the user doesn't mind that the HDF5 file is + modified. An external wrapper would be used if the file isn't + writable or if the user wants the data file to be primarily HDF5 + but a few applications need an HDF4 view of the data. + + <p>Modifying through the HDF5 library an HDF5 file that has + internal HDF4 wrapper should invalidate the HDF4 wrapper (and + optionally regenerate it when <code>H5Fclose</code> is + called). The HDF5 library must understand how wrappers work, but + not necessarily anything about the HDF4 file format. + + <p>Modifying through the HDF5 library an HDF5 file that has an + external HDF4 wrapper will cause the HDF4 wrapper to become out + of date (but possibly regenerated during <code>H5Fclose</code>). + <b>Note: Perhaps the next release of the HDF4 library should + insure that the HDF4 wrapper file has a more recent modification + time than the raw data file (the HDF5 file) to which it + points(?)</b> + + <p>Modifying through the HDF4 library an HDF5 file that has an + internal or external HDF4 wrapper will cause the HDF5 wrapper to + become out of date. However, there is now way for the old HDF4 + library to notify the HDF5 wrapper that it's out of date. + Therefore the HDF5 library must be able to detect when the HDF5 + wrapper is out of date and be able to fix it. If the HDF4 + wrapper is complete then the easy way is to ignore the original + HDF5 wrapper and generate a new one from the HDF4 wrapper. The + other approach is to compare the HDF4 and HDF5 wrappers and + assume that if they differ HDF4 is the right one, if HDF4 omits + data then it was because HDF4 is a partial wrapper (rather than + assume HDF4 deleted the data), and if HDF4 has new data then + copy the new meta data to the HDF5 wrapper. On the other hand, + perhaps we don't need to allow these situations (modifying an + HDF5 file with the old HDF4 library and then accessing it with + the HDF5 library is either disallowed or causes HDF5 objects + that can't be described by HDF4 to be lost). + + <p>To convert an HDF5 file to an HDF4 file on demand, one simply + opens the file with the HDF4 flag and closes it. This is also + how AIO implemented backward compatability with PDB in its file + format. + + <hr> + <h2>Implementation of Condition C</h2> + + <p>This condition must be satisfied for all time because there + will always be archived HDF4 files. If a pure HDF4 file (that + is, one without HDF5 meta data) is opened with an HDF5 library, + the <code>H5Fopen</code> builds an internal or external HDF5 + wrapper and then accesses the raw data through that wrapper. If + the HDF5 library modifies the file then the HDF4 wrapper becomes + out of date. However, since the HDF5 library hasn't been + released, we can at least implement it to disable and/or reclaim + the HDF4 wrapper. + + <p>If an external and temporary HDF5 wrapper is desired, the + wrapper is created through the cache like all other HDF5 files. + The data appears on disk only if a particular cached datum is + preempted. Instead of calling <code>H5Fclose</code> on the HDF5 + wrapper file we call <code>H5Fabort</code> which immediately + releases all file resources without updating the file, and then + we unlink the file from Unix. + + <hr> + <h2>What do wrappers look like?</h2> + + <p>External wrappers are quite obvious: they contain only things + from the format specs for the wrapper and nothing from the + format specs of the format which they wrap. + + <p>An internal HDF4 wrapper is added to an HDF5 file in such a way + that the file appears to be both an HDF4 file and an HDF5 + file. HDF4 requires an HDF4 file header at file offset zero. If + a user block is present then we just move the user block down a + bit (and truncate it) and insert the minimum HDF4 signature. + The HDF4 <code>dd</code> list and any other data it needs are + appended to the end of the file and the HDF5 signature uses the + logical file length field to determine the beginning of the + trailing part of the wrapper. + + <p> + <center> + <table border width="60%"> + <tr> + <td>HDF4 minimal file header. Its main job is to point to + the <code>dd</code> list at the end of the file.</td> + </tr> + <tr> + <td>User-defined block which is truncated by the size of the + HDF4 file header so that the HDF5 boot block file address + doesn't change.</td> + </tr> + <tr> + <td>The HDF5 boot block and data, unmodified by adding the + HDF4 wrapper.</td> + </tr> + <tr> + <td>The main part of the HDF4 wrapper. The <code>dd</code> + list will have entries for all parts of the file so + hdpack(?) doesn't (re)move anything.</td> + </tr> + </table> + </center> + + <p>When such a file is opened by the HDF5 library for + modification it shifts the user block back down to address zero + and fills with zeros, then truncates the file at the end of the + HDF5 data or adds the trailing HDF4 wrapper to the free + list. This prevents HDF4 applications from reading the file with + an out of date wrapper. + + <p>If there is no user block then we have a problem. The HDF5 + boot block must be moved to make room for the HDF4 file header. + But moving just the boot block causes problems because all file + addresses stored in the file are relative to the boot block + address. The only option is to shift the entire file contents + by 512 bytes to open up a user block (too bad we don't have + hooks into the Unix i-node stuff so we could shift the entire + file contents by the size of a file system page without ever + performing I/O on the file :-) + + <p>Is it possible to place an HDF5 wrapper in an HDF4 file? I + don't know enough about the HDF4 format, but I would suspect it + might be possible to open a hole at file address 512 (and + possibly before) by moving some things to the end of the file + to make room for the HDF5 signature. The remainder of the HDF5 + wrapper goes at the end of the file and entries are added to the + HDF4 <code>dd</code> list to mark the location(s) of the HDF5 + wrapper. + + <hr> + <h2>Other Thoughts</h2> + + <p>Conversion programs that copy an entire HDF4 file to a separate, + self-contained HDF5 file and vice versa might be useful. + + + + + <hr> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- Created: Fri Oct 3 11:52:31 EST 1997 --> +<!-- hhmts start --> +Last modified: Wed Oct 8 12:34:42 EST 1997 +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/dataset_p1.gif b/doc/html/dataset_p1.gif Binary files differnew file mode 100644 index 0000000..1e7cea0 --- /dev/null +++ b/doc/html/dataset_p1.gif diff --git a/doc/html/dataset_p1.obj b/doc/html/dataset_p1.obj new file mode 100644 index 0000000..42d66fc --- /dev/null +++ b/doc/html/dataset_p1.obj @@ -0,0 +1,32 @@ +%TGIF 3.0-p5 +state(0,33,100,0,0,0,16,1,9,1,1,0,0,1,0,1,1,'Helvetica',0,24,0,0,0,10,0,0,1,1,0,16,0,0,1,1,1,0,1088,1408,0,0,2880). +% +% @(#)$Header$ +% %W% +% +unit("1 pixel/pixel"). +page(1,"",1). +box('black',128,240,288,432,4,1,1,26,0,0,0,0,0,'1',[ +]). +box('black',400,272,464,400,4,1,1,27,0,0,0,0,0,'1',[ +]). +box('black',192,304,224,368,6,1,1,28,0,0,0,0,0,'1',[ +]). +box('black',400,272,432,336,6,1,1,29,0,0,0,0,0,'1',[ +]). +poly('black',2,[ + 224,304,400,272],1,1,1,32,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 224,368,400,336],1,1,1,33,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +text('black',208,208,'Helvetica',0,20,1,1,0,1,77,17,40,0,14,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "File Dataset"]). +text('black',432,208,'Helvetica',0,20,1,1,0,1,106,17,42,0,14,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Memory Dataset"]). +text('black',320,144,'Helvetica',0,24,1,1,0,1,206,29,68,0,24,5,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Raw Data Transfer"]). +box('black',96,128,512,464,0,1,1,70,0,0,0,0,0,'1',[ +]). diff --git a/doc/html/extern1.gif b/doc/html/extern1.gif Binary files differnew file mode 100644 index 0000000..dcac681 --- /dev/null +++ b/doc/html/extern1.gif diff --git a/doc/html/extern1.obj b/doc/html/extern1.obj new file mode 100644 index 0000000..9c56a50 --- /dev/null +++ b/doc/html/extern1.obj @@ -0,0 +1,40 @@ +%TGIF 3.0-p5 +state(0,33,100,0,0,0,16,1,9,1,1,0,0,1,0,1,0,'Courier',0,17,0,0,0,10,0,0,1,1,0,16,0,0,1,1,1,0,1088,1408,0,0,2880). +% +% @(#)$Header$ +% %W% +% +unit("1 pixel/pixel"). +page(1,"",1). +box('black',128,96,192,128,4,1,1,49,0,0,0,0,0,'1',[ +]). +box('black',192,96,352,128,12,1,1,50,0,0,0,0,0,'1',[ +]). +box('black',352,96,416,128,18,1,1,51,0,0,0,0,0,'1',[ +]). +box('black',64,176,224,208,12,1,1,53,0,0,0,0,0,'1',[ +]). +box('black',256,176,320,208,4,1,1,54,0,0,0,0,0,'1',[ +]). +box('black',352,176,448,208,18,1,1,55,0,0,0,0,0,'1',[ +]). +box('black',224,176,256,208,0,1,1,56,0,0,0,0,0,'1',[ +]). +box('black',320,176,352,208,0,1,1,57,0,0,0,0,0,'1',[ +]). +box('black',448,176,512,208,0,1,1,58,0,0,0,0,0,'1',[ +]). +poly('black',2,[ + 176,128,272,176],1,1,1,59,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 240,128,208,176],1,1,1,60,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 384,128,384,176],1,1,1,61,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +box('black',48,80,528,224,0,1,1,64,0,0,0,0,0,'1',[ +]). diff --git a/doc/html/extern2.gif b/doc/html/extern2.gif Binary files differnew file mode 100644 index 0000000..5f0e942 --- /dev/null +++ b/doc/html/extern2.gif diff --git a/doc/html/extern2.obj b/doc/html/extern2.obj new file mode 100644 index 0000000..3e83452 --- /dev/null +++ b/doc/html/extern2.obj @@ -0,0 +1,108 @@ +%TGIF 3.0-p5 +state(0,33,100,0,0,0,16,1,9,1,1,1,1,0,0,1,1,'Courier',0,17,0,0,0,10,0,0,1,1,0,16,0,0,1,1,1,0,1088,1408,0,0,2880). +% +% @(#)$Header$ +% %W% +% +unit("1 pixel/pixel"). +page(1,"",1). +box('black',48,48,464,432,0,1,1,144,0,0,0,0,0,'1',[ +]). +text('black',80,240,'Courier',0,17,1,0,0,1,70,14,146,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "scan1.data"]). +text('black',80,304,'Courier',0,17,1,0,0,1,70,14,148,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "scan2.data"]). +text('black',80,368,'Courier',0,17,1,0,0,1,70,14,150,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "scan3.data"]). +polygon('black',7,[ + 64,64,64,128,192,128,192,96,320,96,320,64,64,64],20,1,1,0,181,0,0,0,0,0,'1', + "00",[ +]). +polygon('black',7,[ + 64,128,64,160,320,160,320,96,192,96,192,128,64,128],4,1,1,0,182,0,0,0,0,0,'1', + "00",[ +]). +box('black',64,160,320,192,26,1,1,183,0,0,0,0,0,'1',[ +]). +poly('black',2,[ + 80,80,304,80],1,1,1,184,0,26,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 80,112,176,112],1,1,1,185,0,26,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 208,112,304,112],1,1,1,186,0,26,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 80,144,304,144],1,1,1,187,0,26,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 80,176,304,176],1,1,1,188,0,26,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +box('black',64,256,448,288,20,1,1,203,0,0,0,0,0,'1',[ +]). +box('black',64,320,448,352,4,1,1,216,0,0,0,0,0,'1',[ +]). +box('black',64,384,320,416,26,1,1,225,0,0,0,0,0,'1',[ +]). +poly('black',2,[ + 80,272,304,272],1,1,1,226,0,26,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 336,272,432,272],1,1,1,227,0,26,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 80,336,176,336],1,1,1,228,0,26,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 208,336,432,336],1,1,1,229,0,26,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 80,400,304,400],1,1,1,230,0,26,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 192,96,64,96],0,1,1,232,0,26,5,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 192,128,320,128],0,1,1,233,0,26,5,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 256,64,256,192],0,1,1,234,0,26,5,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 192,64,192,192],0,1,1,235,0,26,5,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 128,64,128,192],0,1,1,236,0,26,5,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 320,160,64,160],0,2,1,238,0,26,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',4,[ + 320,96,192,96,192,128,64,128],0,2,1,240,0,0,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',6,[ + 336,64,384,64,384,128,384,128,384,192,336,192],3,1,1,241,1,0,0,0,8,3,0,0,0,'1','8','3', + "78",[ +]). +text('black',429,124,'Courier',0,17,2,1,0,1,28,49,250,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,1,0,[ + 429,124,405,124,454,152,0,1000,-1000,0,-15,2,404,123,455,153],[ + "2-d", + "Dataset"]). diff --git a/doc/html/group_p1.gif b/doc/html/group_p1.gif Binary files differnew file mode 100644 index 0000000..5900446 --- /dev/null +++ b/doc/html/group_p1.gif diff --git a/doc/html/group_p1.obj b/doc/html/group_p1.obj new file mode 100644 index 0000000..5f41959 --- /dev/null +++ b/doc/html/group_p1.obj @@ -0,0 +1,85 @@ +%TGIF 3.0-p5 +state(0,33,100,0,0,0,8,1,9,1,1,0,2,1,0,1,1,'Times-Roman',0,24,0,0,0,10,0,0,1,1,0,16,0,0,1,1,1,0,1088,1408,0,0,2880). +% +% @(#)$Header$ +% %W% +% +unit("1 pixel/pixel"). +page(1,"",1). +text('black',80,168,'Courier',0,17,1,0,0,1,7,14,30,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',80,184,'Courier',0,17,1,0,0,1,7,14,34,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',80,200,'Courier',0,17,1,0,0,1,7,14,36,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',80,216,'Courier',0,17,1,0,0,1,21,14,38,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Foo"]). +text('black',80,232,'Courier',0,17,1,0,0,1,7,14,43,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',80,248,'Courier',0,17,1,0,0,1,7,14,47,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +rcbox('black',64,152,128,280,0,1,1,0,16,49,0,0,0,0,'1',[ +]). +text('black',208,152,'Courier',0,17,1,0,0,1,7,14,52,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',80,152,'Courier',0,17,1,0,0,1,7,14,56,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',208,168,'Courier',0,17,1,0,0,1,7,14,58,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',208,184,'Courier',0,17,1,0,0,1,21,14,60,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Bar"]). +text('black',208,200,'Courier',0,17,1,0,0,1,7,14,62,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',208,216,'Courier',0,17,1,0,0,1,7,14,64,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',208,232,'Courier',0,17,1,0,0,1,7,14,68,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',208,248,'Courier',0,17,1,0,0,1,7,14,72,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +rcbox('black',192,152,256,280,0,1,1,0,16,74,0,0,0,0,'1',[ +]). +text('black',336,152,'Courier',0,17,1,0,0,1,7,14,75,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',336,168,'Courier',0,17,1,0,0,1,7,14,77,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',336,184,'Courier',0,17,1,0,0,1,7,14,81,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',336,200,'Courier',0,17,1,0,0,1,7,14,88,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',336,216,'Courier',0,17,1,0,0,1,7,14,92,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',336,232,'Courier',0,17,1,0,0,1,7,14,94,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',336,248,'Courier',0,17,1,0,0,1,21,14,96,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Baz"]). +rcbox('black',320,152,384,280,0,1,1,0,16,98,0,0,0,0,'1',[ +]). +text('black',224,360,'NewCenturySchlbk-Roman',0,17,2,1,0,1,42,30,99,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Object", + "Header"]). +rcbox('black',192,344,256,408,0,1,1,0,16,101,0,0,0,0,'1',[ +]). +poly('black',4,[ + 112,224,136,216,152,184,192,168],1,1,1,102,2,0,0,0,8,3,0,0,0,'1','8','3', + "",[ +]). +poly('black',4,[ + 232,192,272,184,288,168,320,160],1,1,1,107,2,0,0,0,8,3,0,0,0,'1','8','3', + "",[ +]). +poly('black',4,[ + 368,256,416,272,392,336,256,352],1,1,1,110,2,0,0,0,8,3,0,0,0,'1','8','3', + "",[ +]). +text('black',96,128,'Times-Roman',0,17,1,1,0,1,40,15,120,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Group 1"]). +text('black',224,128,'Times-Roman',0,17,1,1,0,1,40,15,126,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Group 2"]). +text('black',352,128,'Times-Roman',0,17,1,1,0,1,40,15,130,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Group 3"]). +text('black',224,320,'Times-Roman',0,17,1,1,0,1,64,15,134,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Some Object"]). +text('black',224,80,'Times-Roman',0,24,1,1,0,1,258,28,138,0,22,6,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "The name \"/Foo/Bar/Baz\""]). +box('black',40,64,448,432,0,1,1,140,0,0,0,0,0,'1',[ +]). diff --git a/doc/html/group_p2.gif b/doc/html/group_p2.gif Binary files differnew file mode 100644 index 0000000..a2d12a0 --- /dev/null +++ b/doc/html/group_p2.gif diff --git a/doc/html/group_p2.obj b/doc/html/group_p2.obj new file mode 100644 index 0000000..cb91258 --- /dev/null +++ b/doc/html/group_p2.obj @@ -0,0 +1,57 @@ +%TGIF 3.0-p5 +state(0,33,100,0,0,0,8,1,9,1,1,0,2,1,0,1,0,'Courier',0,17,0,0,0,10,0,0,1,1,0,16,0,0,1,1,1,0,1088,1408,0,0,2880). +% +% @(#)$Header$ +% %W% +% +unit("1 pixel/pixel"). +page(1,"",1). +text('black',144,128,'Courier',0,17,1,0,0,1,7,14,26,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',144,144,'Courier',0,17,1,0,0,1,7,14,30,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',144,160,'Courier',0,17,1,0,0,1,21,14,34,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Foo"]). +text('black',144,176,'Courier',0,17,1,0,0,1,7,14,36,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',144,192,'Courier',0,17,1,0,0,1,7,14,38,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +rcbox('black',128,128,192,256,0,1,1,0,16,40,0,0,0,0,'1',[ +]). +text('black',144,320,'Courier',0,17,1,0,0,1,7,14,43,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',144,336,'Courier',0,17,1,0,0,1,7,14,45,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',144,352,'Courier',0,17,1,0,0,1,21,14,47,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Bar"]). +text('black',144,368,'Courier',0,17,1,0,0,1,7,14,49,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',144,384,'Courier',0,17,1,0,0,1,7,14,51,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +rcbox('black',128,320,192,448,0,1,1,0,16,53,0,0,0,0,'1',[ +]). +text('black',160,96,'NewCenturySchlbk-Roman',0,17,1,1,0,1,46,15,64,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Group 1"]). +text('black',160,288,'NewCenturySchlbk-Roman',0,17,1,1,0,1,46,15,68,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Group 2"]). +text('black',352,224,'NewCenturySchlbk-Roman',0,17,2,1,0,1,35,30,70,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Some", + "Object"]). +rcbox('black',320,256,384,384,0,1,1,0,16,72,0,0,0,0,'1',[ +]). +poly('black',4,[ + 176,168,224,192,264,240,320,264],1,1,1,73,2,0,0,0,8,3,0,0,0,'1','8','3', + "",[ +]). +poly('black',4,[ + 176,360,232,344,272,288,320,272],1,1,1,74,2,0,0,0,8,3,0,0,0,'1','8','3', + "",[ +]). +text('black',264,40,'Helvetica',0,24,1,1,0,1,206,29,93,0,24,5,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Hard Link Example"]). +box('black',88,24,424,496,0,1,1,95,0,0,0,0,0,'1',[ +]). +text('black',240,192,'Courier',0,17,1,0,0,1,63,14,129,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "hard link"]). +text('black',248,336,'Courier',0,17,1,0,0,1,63,14,131,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "hard link"]). diff --git a/doc/html/group_p3.gif b/doc/html/group_p3.gif Binary files differnew file mode 100644 index 0000000..85346de --- /dev/null +++ b/doc/html/group_p3.gif diff --git a/doc/html/group_p3.obj b/doc/html/group_p3.obj new file mode 100644 index 0000000..ad93444 --- /dev/null +++ b/doc/html/group_p3.obj @@ -0,0 +1,59 @@ +%TGIF 3.0-p5 +state(0,33,100,0,0,0,8,1,9,1,1,0,2,1,0,1,0,'Courier',0,17,0,0,0,10,0,0,1,1,0,16,0,0,1,1,1,0,1088,1408,0,0,2880). +% +% @(#)$Header$ +% %W% +% +unit("1 pixel/pixel"). +page(1,"",1). +text('black',144,128,'Courier',0,17,1,0,0,1,7,14,26,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',144,144,'Courier',0,17,1,0,0,1,7,14,30,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',144,160,'Courier',0,17,1,0,0,1,21,14,34,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Foo"]). +text('black',144,176,'Courier',0,17,1,0,0,1,7,14,36,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',144,192,'Courier',0,17,1,0,0,1,7,14,38,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +rcbox('black',128,128,192,256,0,1,1,0,16,40,0,0,0,0,'1',[ +]). +text('black',144,320,'Courier',0,17,1,0,0,1,7,14,43,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',144,336,'Courier',0,17,1,0,0,1,7,14,45,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',144,352,'Courier',0,17,1,0,0,1,21,14,47,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Bar"]). +text('black',144,368,'Courier',0,17,1,0,0,1,7,14,49,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +text('black',144,384,'Courier',0,17,1,0,0,1,7,14,51,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "."]). +rcbox('black',128,320,192,448,0,1,1,0,16,53,0,0,0,0,'1',[ +]). +text('black',160,96,'NewCenturySchlbk-Roman',0,17,1,1,0,1,46,15,64,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Group 1"]). +text('black',160,288,'NewCenturySchlbk-Roman',0,17,1,1,0,1,46,15,68,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Group 2"]). +text('black',352,96,'NewCenturySchlbk-Roman',0,17,2,1,0,1,35,30,70,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Some", + "Object"]). +rcbox('black',320,128,384,256,0,1,1,0,16,72,0,0,0,0,'1',[ +]). +text('black',264,40,'Helvetica',0,24,1,1,0,1,197,29,93,0,24,5,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Soft Link Example"]). +box('black',88,24,424,496,0,1,1,95,0,0,0,0,0,'1',[ +]). +text('black',320,352,'Courier',0,17,1,0,0,1,35,14,105,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "\"Foo\""]). +poly('black',4,[ + 176,168,232,160,264,144,320,136],1,1,1,111,2,0,0,0,8,3,0,0,0,'1','8','3', + "",[ +]). +poly('black',2,[ + 176,360,312,360],1,1,1,116,2,0,0,0,8,3,0,0,0,'1','8','3', + "",[ +]). +text('black',240,160,'Courier',0,17,1,0,0,1,63,14,119,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "hard link"]). +text('black',216,368,'Courier',0,17,1,0,0,1,63,14,121,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "soft link"]). diff --git a/doc/html/h5s.examples b/doc/html/h5s.examples new file mode 100644 index 0000000..e7a479f --- /dev/null +++ b/doc/html/h5s.examples @@ -0,0 +1,347 @@ +Example 1: Create a simple fixed size 3-D dataspace in memory and on disk and + copy the entire dataset to disk. + +{ + hid_t file; /* File ID */ + hid_t dataset; /* Dataset ID */ + hid_t mem_space, file_space; /* Dataspaces for memory and the file */ + uint8 *buf; /* Buffer for data */ + hsize_t curr_dims[3]={3,4,5}; /* Dimensions of the dataset */ + + /* Create file */ + file = H5Fcreate("example1.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + + /* Create dataspace for dataset in the file */ + /* Selection for dataspace defaults to entire space */ + file_space=H5Screate(H5S_SIMPLE); + + /* Set the extent & type of the dataset's dataspace */ + H5Sset_extent_simple(file_space,3,curr_dims,curr_dims); + + /* Create the dataspace for the dataset in memory */ + /* Selection for dataspace defaults to entire space */ + mem_space=H5Screate(H5S_SIMPLE); + + /* Set the extent & type of the memory dataspace */ + H5Sset_extent_simple(mem_space,3,curr_dims,curr_dims); + + /* Create the dataset on disk */ + dataset=H5Dcreate(file,"Dataset",H5T_NATIVE_UINT8,file_space,H5P_DEFAULT); + + /* Write the dataset to the file */ + H5Dwrite(dataset,H5T_NATIVE_UINT8,mem_space,file_space,H5P_DEFAULT,buf); + + /* Close dataspaces */ + H5Sclose(mem_space); + H5Sclose(file_space); + + /* Close dataset & file */ + H5Dclose(dataset); + H5Fclose(file); +} + + +Example 2: Create a simple fixed size 3-D dataspace in memory and on disk and + copy a hyperslab to disk. The hyperslab blocks are packed and + contiguous in memory, but are scattered when written to the dataset + on disk. + +{ + hid_t file; /* File ID */ + hid_t dataset; /* Dataset ID */ + hid_t mem_space, file_space; /* Dataspaces for memory and the file */ + uint8 *buf; /* Buffer for data */ + hssize_t start[3]={3,4,5}; /* Start of hyperslab */ + hsize_t stride[3]={1,2,2}; /* Stride for hyperslab */ + hsize_t count[3]={3,3,3}; /* Hyperslab block count in each dimension */ + hsize_t block[3]={2,2,2}; /* Hyperslab block size in each dimension */ + hsize_t curr_dims[3]={13,14,15}; /* Dimensions of the dataset */ + + /* Create file */ + file = H5Fcreate("example2.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + + /* Create dataspace for dataset in the file */ + /* Selection for dataspace defaults to entire space */ + file_space=H5Screate(H5S_SIMPLE); + + /* Set the extent & type of the dataset's dataspace */ + H5Sset_extent_simple(file_space,3,curr_dims,curr_dims); + + /* Set the hyperslab selection for a file dataspace */ + H5Sselect_hyperslab(file_space,H5S_SELECT_SET,start,stride,count,block); + + /* Create the dataspace for the dataset in memory */ + /* Selection for dataspace defaults to entire space */ + mem_space=H5Screate(H5S_SIMPLE); + + /* Set the extent & type of the memory dataspace */ + /* Compute the memory dimensions based on the hyperslab blocks to write */ + for(i=0; i<3; i++) + curr_dims[i]=count[i]*block[i]; + H5Sset_extent_simple(mem_space,3,curr_dims,curr_dims); + + /* Create the dataset on disk */ + dataset=H5Dcreate(file,"Dataset",H5T_NATIVE_UINT8,file_space,H5P_DEFAULT); + + /* Write the hyperslab to the file */ + H5Dwrite(dataset,H5T_NATIVE_UINT8,mem_space,file_space,H5P_DEFAULT,buf); + + /* Close dataspaces */ + H5Sclose(mem_space); + H5Sclose(file_space); + + /* Close dataset & file */ + H5Dclose(dataset); + H5Fclose(file); +} + + +Example 3: Create a simple fixed size 3-D dataspace in memory and on disk and + copy a specific selection of points (with a particular order) to + disk. The memory and file dataspaces are different sizes, but the number + of points selected are the same. + +{ + hid_t file; /* File ID */ + hid_t dataset; /* Dataset ID */ + hid_t mem_space, file_space; /* Dataspaces for memory and the file */ + uint8 *buf; /* Buffer for data */ + hsize_t elements[5][3]; /* Dataspace elements selected */ + hsize_t curr_dims[3]={13,14,15}; /* Dimensions of the dataset */ + + /* Create file */ + file = H5Fcreate("example3.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + + /* Create dataspace for dataset in the file */ + /* Selection for dataspace defaults to entire space */ + file_space=H5Screate(H5S_SIMPLE); + + /* Set the extent & type of the dataset's dataspace */ + H5Sset_extent_simple(file_space,3,curr_dims,curr_dims); + + /* Set the elements for the selection in the file dataspace */ + elements[0]={0,2,4}; /* Yes, I know this won't compile.. :-) */ + elements[1]={3,4,1}; + elements[2]={9,8,3}; + elements[3]={7,2,0}; + elements[4]={6,5,8}; + H5Sselect_elements(file_space,H5S_SELECT_SET,5,elements); + + /* Create the dataspace for the dataset in memory */ + /* Selection for dataspace defaults to entire space */ + mem_space=H5Screate(H5S_SIMPLE); + + /* Set the extent & type of the memory dataspace */ + curr_dims={23,15,18}; /* This won't compile either :-) */ + H5Sset_extent_simple(mem_space,3,curr_dims,curr_dims); + + /* Set the elements for the selection in the file dataspace */ + elements[0]={9,2,1}; + elements[1]={13,1,12}; + elements[2]={4,1,7}; + elements[3]={0,12,0}; + elements[4]={20,10,17}; + H5Sselect_elements(mem_space,H5S_SELECT_SET,5,elements); + + /* Create the dataset on disk */ + dataset=H5Dcreate(file,"Dataset",H5T_NATIVE_UINT8,file_space,H5P_DEFAULT); + + /* Write the hyperslab to the file */ + H5Dwrite(dataset,H5T_NATIVE_UINT8,mem_space,file_space,H5P_DEFAULT,buf); + + /* Close dataspaces */ + H5Sclose(mem_space); + H5Sclose(file_space); + + /* Close dataset & file */ + H5Dclose(dataset); + H5Fclose(file); +} + + +Example 4: Create a simple fixed size 3-D dataspace in memory and on disk and + build up selection hyperslab selections to copy from memory to disk. The + selection is the same for both dataspaces, but a different offset is used, + to illustrate the selection offsets. + +{ + hid_t file; /* File ID */ + hid_t dataset; /* Dataset ID */ + hid_t mem_space, file_space; /* Dataspaces for memory and the file */ + uint8 *buf; /* Buffer for data */ + hssize_t start[3]; /* Start of hyperslab */ + hsize_t stride[3]; /* Stride for hyperslab */ + hsize_t count[3]; /* Hyperslab block count in each dimension */ + hsize_t block[3]; /* Hyperslab block size in each dimension */ + hssize_t offset[3]; /* Selection offset */ + hsize_t curr_dims[3]={13,14,15}; /* Dimensions of the dataset */ + + /* Create file */ + file = H5Fcreate("example4.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + + /* Create dataspace for dataset in the file */ + /* Selection for dataspace defaults to entire space */ + file_space=H5Screate(H5S_SIMPLE); + + /* Set the extent & type of the dataset's dataspace */ + H5Sset_extent_simple(file_space,3,curr_dims,curr_dims); + + /* Build up the selection with a series of hyperslab selections */ + start={0,2,4}; /* Again, this won't compile.. :-) */ + stride={1,1,1}; + count={6,5,8}; + block={1,1,1}; + + /* Set the first selection, union the rest in */ + H5Sselect_hyperslab(file_space,H5S_SELECT_SET,start,stride,count,block); + + /* initialize the second hyperslab */ + start={10,9,1}; /* Again, this won't compile.. :-) */ + stride={1,1,1}; + count={2,3,10}; + block={1,1,1}; + + /* Union the second hyperslab into the file dataspace's selection */ + H5Sselect_hyperslab(file_space,H5S_SELECT_UNION,start,stride,count,block); + + /* initialize the third hyperslab */ + start={3,10,5}; /* Again, this won't compile.. :-) */ + stride={1,1,1}; + count={8,2,6}; + block={1,1,1}; + + /* Union the final hyperslab into the file dataspace's selection */ + H5Sselect_hyperslab(file_space,H5S_SELECT_UNION,start,stride,count,block); + + /* Create the dataspace for the dataset in memory */ + /* Selection for dataspace defaults to entire space */ + mem_space=H5Screate(H5S_SIMPLE); + + /* Set the extent & type of the memory dataspace */ + curr_dims={23,15,18}; /* This won't compile either :-) */ + H5Sset_extent_simple(mem_space,3,curr_dims,curr_dims); + + /* Copy the selection from the file dataspace */ + H5Sselect_op(mem_space,H5S_SELECT_COPY,file_space); + + /* Adjust the offset of the selection in the memory dataspace */ + offset={1,1,1}; + H5Soffset_simple(mem_space,offset); + + /* Create the dataset on disk */ + dataset=H5Dcreate(file,"Dataset",H5T_NATIVE_UINT8,file_space,H5P_DEFAULT); + + /* Write the hyperslab to the file */ + H5Dwrite(dataset,H5T_NATIVE_UINT8,mem_space,file_space,H5P_DEFAULT,buf); + + /* Close dataspaces */ + H5Sclose(mem_space); + H5Sclose(file_space); + + /* Close dataset & file */ + H5Dclose(dataset); + H5Fclose(file); +} + + +Example 5: Same as example 1 (create a simple fixed size 3-D dataspace in memory and on disk and + copy the entire dataset to disk), except that the selection order is changed + for the memory dataspace, to change between FORTRAN and C array ordering. + +{ + hid_t file; /* File ID */ + hid_t dataset; /* Dataset ID */ + hid_t mem_space, file_space; /* Dataspaces for memory and the file */ + uint8 *buf; /* Buffer for data */ + hsize_t order[3]; /* Dimension ordering for selection */ + hsize_t curr_dims[3]={3,4,5}; /* Dimensions of the dataset */ + + /* Create file */ + file = H5Fcreate("example5.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + + /* Create dataspace for dataset in the file */ + /* Selection for dataspace defaults to entire space and C array order */ + file_space=H5Screate(H5S_SIMPLE); + + /* Set the extent & type of the dataset's dataspace */ + H5Sset_extent_simple(file_space,3,curr_dims,curr_dims); + + /* Create the dataspace for the dataset in memory */ + /* Selection for dataspace defaults to entire space and C array order */ + mem_space=H5Screate(H5S_SIMPLE); + + /* Set the extent & type of the memory dataspace */ + H5Sset_extent_simple(mem_space,3,curr_dims,curr_dims); + + /* Change selection ordering to FORTRAN order for memory dataspace */ + order={0,1,2}; + H5Sselect_order(mem_space,order); + + /* Create the dataset on disk */ + dataset=H5Dcreate(file,"Dataset",H5T_NATIVE_UINT8,file_space,H5P_DEFAULT); + + /* Write the dataset to the file */ + H5Dwrite(dataset,H5T_NATIVE_UINT8,mem_space,file_space,H5P_DEFAULT,buf); + + /* Close dataspaces */ + H5Sclose(mem_space); + H5Sclose(file_space); + + /* Close dataset & file */ + H5Dclose(dataset); + H5Fclose(file); +} + + +Example 6: Create a stored dataspace on disk and use the H5Ssubspace function + create a dataspace located within that space. + +{ + hid_t file; /* File ID */ + hid_t space1, space2; /* Dataspace IDs */ + hssize_t start[3]; /* Start of hyperslab */ + hsize_t count[3]; /* Hyperslab block count in each dimension */ + hsize_t curr_dims[3]={13,14,15};/* Dimensions of the dataset */ + + /* Create file */ + file = H5Fcreate("example6.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + + /* Create dataspace #1 */ + space1=H5Screate(H5S_SIMPLE); + + /* Set the extent & type of dataspace #1 */ + H5Sset_extent_simple(space1,3,curr_dims,curr_dims); + + /* Store dataspace #1 on disk */ + H5Scommit(file,"/Dataspaces/Dataspace #1",space1); + + /* Select a contiguous hyperslab in dataspace #1 to create dataspace #2 with */ + start={0,2,4}; + count={6,5,8}; + + /* + * Use stride and block set to NULL to get contiguous, single element sized + * hyperslab. The stride and block parameters could also be set to all + * 1's, but this is simpler and easier. + */ + H5Sselect_hyperslab(space1,H5S_SELECT_SET,start,NULL,count,NULL); + + /* Create dataspace #2 as a dataspace located within dataspace #1 */ + space2=H5Ssubspace(space1); + + /* Store dataspace #2 on disk also */ + H5Scommit(file,"/Dataspaces/Dataspace #2",space2); + + /* + * space1 & space2 can be used to create datasets, etc. Any datasets + * created with space2 can have their dataspace queried to find the parent + * dataspace and the location within the parent dataspace + */ + + /* Close dataspaces */ + H5Sclose(space1); + H5Sclose(space2); + + /* Close file */ + H5Fclose(file); +} diff --git a/doc/html/heap.txt b/doc/html/heap.txt new file mode 100644 index 0000000..6b4c058 --- /dev/null +++ b/doc/html/heap.txt @@ -0,0 +1,72 @@ + HEAP MANAGEMENT IN HDF5 + ------------------------ + +Heap functions are in the H5H package. + + +off_t +H5H_new (hdf5_file_t *f, size_t size_hint, size_t realloc_hint); + + Creates a new heap in the specified file which can efficiently + store at least SIZE_HINT bytes. The heap can store more than + that, but doing so may cause the heap to become less efficient + (for instance, a heap implemented as a B-tree might become + discontigous). The REALLOC_HINT is the minimum number of bytes + by which the heap will grow when it must be resized. The hints + may be zero in which case reasonable (but probably not + optimal) values will be chosen. + + The return value is the address of the new heap relative to + the beginning of the file boot block. + +off_t +H5H_insert (hdf5_file_t *f, off_t addr, size_t size, const void *buf); + + Copies SIZE bytes of data from BUF into the heap whose address + is ADDR in file F. BUF must be the _entire_ heap object. The + return value is the byte offset of the new data in the heap. + +void * +H5H_read (hdf5_file_t *f, off_t addr, off_t offset, size_t size, void *buf); + + Copies SIZE bytes of data from the heap whose address is ADDR + in file F into BUF and then returns the address of BUF. If + BUF is the null pointer then a new buffer will be malloc'd by + this function and its address is returned. + + Returns buffer address or null. + +const void * +H5H_peek (hdf5_file_t *f, off_t addr, off_t offset) + + A more efficient version of H5H_read that returns a pointer + directly into the cache; the data is not copied from the cache + to a buffer. The pointer is valid until the next call to an + H5AC function directly or indirectly. + + Returns a pointer or null. Do not free the pointer. + +void * +H5H_write (hdf5_file_t *f, off_t addr, off_t offset, size_t size, + const void *buf); + + Modifies (part of) an object in the heap at address ADDR of + file F by copying SIZE bytes from the beginning of BUF to the + file. OFFSET is the address withing the heap where the output + is to occur. + + This function can fail if the combination of OFFSET and SIZE + would write over a boundary between two heap objects. + +herr_t +H5H_remove (hdf5_file_t *f, off_t addr, off_t offset, size_t size); + + Removes an object or part of an object which begins at byte + OFFSET within a heap whose address is ADDR in file F. SIZE + bytes are returned to the free list. Removing the middle of + an object has the side effect that one object is now split + into two objects. + + Returns success or failure. + + diff --git a/doc/html/index.html b/doc/html/index.html new file mode 100644 index 0000000..edd1ab0 --- /dev/null +++ b/doc/html/index.html @@ -0,0 +1,40 @@ +<html> + <head> + <title> + HDF5 - The Next Generation of the HDF library & tools + </title> + </head> + +<body> + <center><h1>HDF5 - A New Generation of HDF</h1></center> +<UL> +<LI><A HREF="H5.intro.html">An Introduction to HDF5</A> - A brief overview of + the design goals behind the HDF5 library & file format +</LI> +<LI><A HREF="H5.api.html">HDF5 Reference Manual</A> - A complete reference + manual for the HDF5 API +</LI> +<LI><A HREF="H5.user.html">HDF5 User Guide</A> - A collection of chapters on + each of the main HDF5 APIs as well as other supporting information +</LI> +<LI><A HREF="H5.format.html">HDF5 Format Specification</A> - The complete + specification of the HDF5 file format +</LI> +<LI><A HREF="ph5design.html">Parallel HDF5 Design</A> - The design +specification of the parallel HDF5 API and an example program +</LI> +<LI><A HREF="ph5implement.txt">Parallel HDF5 Implementation</A> - The +current status of implmentation of the parallel HDF5 API +</LI> +</UL> + + +<hr> +<address><a href="mailto:koziol@ncsa.uiuc.edu">Quincey Koziol</a></address> +<address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- hhmts start --> +Last modified: Feb 16, 1998 +<!-- hhmts end --> + +</body> +</html> diff --git a/doc/html/move.html b/doc/html/move.html new file mode 100644 index 0000000..ec87d11 --- /dev/null +++ b/doc/html/move.html @@ -0,0 +1,66 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>How to Relocate a File Data Structure</title> + </head> + + <body> + <h1>How to Relocate a File Data Structure</h1> + + <p>Since file data structures can be cached in memory by the H5AC + package it becomes problematic to move such a data structure in + the file. One cannot just copy a portion of the file from one + location to another because: + + <ol> + <li>the file might not contain the latest information, and</li> + <li>the H5AC package might not realize that the object's + address has changed and attempt to write the object to disk + at the old address.</li> + </ol> + + <p>Here's a correct method to move data from one location to + another. The example code assumes that one is moving a B-link + tree node from <code>old_addr</code> to <code>new_addr</code>. + + <ol> + <li>Make sure the disk is up-to-date with respect to the + cache. There is no need to remove the item from the cache, + hence the final argument to <code>H5AC_flush</code> is + <code>FALSE</code>. + <br><br> + <code> + H5AC_flush (f, H5AC_BT, old_addr, FALSE);<br> + </code> + <br> + </li> + + <li>Read the data from the old address and write it to the new + address. + <br><br> + <code> + H5F_block_read (f, old_addr, size, buf);<br> + H5F_block_write (f, new_addr, size, buf);<br> + </code> + <br> + </li> + + <li>Notify the cache that the address of the object changed. + <br><br> + <code> + H5AC_rename (f, H5AC_BT, old_addr, new_addr);<br> + </code> + <br> + </li> + </ol> + + + + <hr> + <address><a href="mailto:robb@maya.nuance.com">Robb Matzke</a></address> +<!-- Created: Mon Jul 14 15:09:06 EST 1997 --> +<!-- hhmts start --> +Last modified: Mon Jul 14 15:38:29 EST +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/ph5design.html b/doc/html/ph5design.html new file mode 100644 index 0000000..1280052 --- /dev/null +++ b/doc/html/ph5design.html @@ -0,0 +1,77 @@ +<HTML> +<HEAD> +<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252"> +<META NAME="Generator" CONTENT="Microsoft Word 97"> +<TITLE>new</TITLE> +<META NAME="Template" CONTENT="C:\PROGRAM FILES\MICROSOFT OFFICE\OFFICE\html.dot"> +</HEAD> +<BODY LINK="#0000ff" VLINK="#800080"> + +<B><FONT SIZE=6><P ALIGN="CENTER">Parallel HDF5 Design</P> +</B></FONT><P ALIGN="CENTER"> </P> +<H1>1. Design Overview</H1> +<P>In this section, I first describe the function requirements of the Parallel HDF5 (PHDF5) software and the assumed system requirements. Section 2 describes the programming model of the PHDF5 interface. Section 3 shows an example PHDF5 program. </P> +<H2>1.1. Function requirements</H2> + +<UL> +<LI>An API to support parallel file access for HDF5 files in a message passing environment. </LI> +<LI>Fast parallel I/O to large datasets through standard parallel I/O interface.</LI> +<LI>Processes are required to do collective API calls only when structural changes are needed for the HDF5 file. </LI> +<LI>Each process may do independent I/O requests to different datasets in the same or different HDF5 files. </LI> +<LI>Supports collective I/O requests for datasets (to be included in next version). </LI> +<LI>Minimize diviation from HDF5 interface.</LI> +</UL> + +<H2>1.2. System requirements</H2> + +<UL> +<LI>C language interface is the initial requirement. Fortran77 interface will be added later. </LI> +<LI>Use Message Passing Interface (MPI) for interprocess communication. </LI> +<LI>Use MPI-IO calls for parallel file accesses. </LI> +<LI>Initial platforms—IBM SP2, Intel TFLOPS and SGI Origin 2000. </LI></UL> + +<H1>2. Programming Model</H1> +<P>HDF5 uses optional access template object to control the file access +mechanism. The general model in accessing an HDF5 file in parallel +contains the following steps: </P> + +<UL> +<LI>Setup access template</LI> +<LI>File open </LI> +<LI>Dataset open </LI> +<LI>Dataset data access (zero or more) </LI> +<LI>Dataset close </LI> +<LI>File close </LI></UL> + +<H2>2.1. Setup access template</H2> +<P>Each processes of the MPI communicator creates an access template and sets +it up with MPI parallel access information (communicator, info object, +access-mode). </P> +<H2>2.1. File open</H2> +<P>All processes of the MPI communicator open an HDF5 file by a collective call +(H5FCreate or H5Fopen) with the access template. </P> +<H2>2.2. Dataset open</H2> +<P>All processes of the MPI communicator open a dataset by a collective call (H5Dcreate or H5Dopen). This version supports only collective dataset open. Future version may support datasets open by a subset of the processes that have opened the file. </P> +<H2>2.3. Dataset access</H2> +<H3>2.3.1. Independent dataset access</H3> +<P>Each process may do independent and arbitrary number of data I/O access by independent calls (H5Dread or H5Dwrite) to the dataset with the transfer template set for independent access. (The default transfer mode is independent transfer). If the dataset is an unlimited dimension one and if the H5Dwrite is writing data beyond the current dimension size of the dataset, all processes that have opened the dataset must make a collective call (H5Dallocate) to allocate more space for the dataset BEFORE the independent H5Dwrite call. </P> +<H3>2.3.2. Collective dataset access</H3> +<P>All processes that have opened the dataset may do collective data I/O access by collective calls (H5Dread or H5Dwrite) to the dataset with the transfer template set for collective access. Pre-allocation (H5Dallocate) is not needed for unlimited dimension datasets since the H5Dallocate call, if needed, is done internally by the collective data access call. </P> +<H3>2.3.3. Dataset attributes access</H3> +<P>Changes to attributes can only occur at the <I>"main process" </I>(process 0). Read only access to attributes can occur independent in each process that has opened the dataset. (API to be defined later.) <BR> + </P> +<H2>2.4. Dataset close</H2> +<P>All processes that have opened the dataset must close the dataset by a collective call (H5Dclose). </P> +<H2>2.5. File close</H2> +<P>All processes that have opened the file must close the file by a collective call (H5Fclose). <BR> + </P> +<H1>3. Parallel HDF5 Example</H1> +<PRE> +<CODE> +</CODE><A HREF="ph5example.c">Example code</A> +</PRE> +<P><HR></P> +<P>Send comments to <BR> +<A HREF="mailto:hdfparallel@ncsa.uiuc.edu">hdfparallel@ncsa.uiuc.edu</A> </P> +<H6>Last Modified: Feb 16, 1998</H6></BODY> +</HTML> diff --git a/doc/html/ph5example.c b/doc/html/ph5example.c new file mode 100644 index 0000000..8699bc9 --- /dev/null +++ b/doc/html/ph5example.c @@ -0,0 +1,1003 @@ + +/* + * Example of using the parallel HDF5 library to access datasets. + * + * This program contains two parts. In the first part, the mpi processes + * collectively create a new parallel HDF5 file and create two fixed + * dimension datasets in it. Then each process writes a hyperslab into + * each dataset in an independent mode. All processes collectively + * close the datasets and the file. + * In the second part, the processes collectively open the created file + * and the two datasets in it. Then each process reads a hyperslab from + * each dataset in an independent mode and prints them out. + * All processes collectively close the datasets and the file. + */ + +#include <assert.h> +#include <hdf5.h> +#include <mpi.h> +#include <mpio.h> + +/* Temporary source code */ +#define FAIL -1 +/* temporary code end */ + +/* Define some handy debugging shorthands, routines, ... */ +/* debugging tools */ +#define MESG(x)\ + if (verbose) printf("%s\n", x);\ + +#define MPI_BANNER(mesg)\ + {printf("--------------------------------\n");\ + printf("Proc %d: ", mpi_rank); \ + printf("*** %s\n", mesg);\ + printf("--------------------------------\n");} + +#define SYNC(comm)\ + {MPI_BANNER("doing a SYNC"); MPI_Barrier(comm); MPI_BANNER("SYNC DONE");} +/* End of Define some handy debugging shorthands, routines, ... */ + +/* Constants definitions */ +/* 24 is a multiple of 2, 3, 4, 6, 8, 12. Neat for parallel tests. */ +#define SPACE1_DIM1 24 +#define SPACE1_DIM2 24 +#define SPACE1_RANK 2 +#define DATASETNAME1 "Data1" +#define DATASETNAME2 "Data2" +#define DATASETNAME3 "Data3" +/* hyperslab layout styles */ +#define BYROW 1 /* divide into slabs of rows */ +#define BYCOL 2 /* divide into blocks of columns */ + + +/* dataset data type. Int's can be easily octo dumped. */ +typedef int DATATYPE; + +/* global variables */ +int nerrors = 0; /* errors count */ + +int mpi_size, mpi_rank; /* mpi variables */ + +/* option flags */ +int verbose = 0; /* verbose, default as no. */ +int doread=1; /* read test */ +int dowrite=1; /* write test */ + + + +/* + * Setup the dimensions of the hyperslab. + * Two modes--by rows or by columns. + * Assume dimension rank is 2. + */ +void +slab_set(hssize_t start[], hsize_t count[], hsize_t stride[], int mode) +{ + switch (mode){ + case BYROW: + /* Each process takes a slabs of rows. */ + stride[0] = 1; + stride[1] = 1; + count[0] = SPACE1_DIM1/mpi_size; + count[1] = SPACE1_DIM2; + start[0] = mpi_rank*count[0]; + start[1] = 0; + break; + case BYCOL: + /* Each process takes a block of columns. */ + stride[0] = 1; + stride[1] = 1; + count[0] = SPACE1_DIM1; + count[1] = SPACE1_DIM2/mpi_size; + start[0] = 0; + start[1] = mpi_rank*count[1]; + break; + default: + /* Unknown mode. Set it to cover the whole dataset. */ + printf("unknown slab_set mode (%d)\n", mode); + stride[0] = 1; + stride[1] = 1; + count[0] = SPACE1_DIM1; + count[1] = SPACE1_DIM2; + start[0] = 0; + start[1] = 0; + break; + } +} + + +/* + * Fill the dataset with trivial data for testing. + * Assume dimension rank is 2 and data is stored contiguous. + */ +void +dataset_fill(hssize_t start[], hsize_t count[], hsize_t stride[], DATATYPE * dataset) +{ + DATATYPE *dataptr = dataset; + int i, j; + + /* put some trivial data in the data_array */ + for (i=0; i < count[0]; i++){ + for (j=0; j < count[1]; j++){ + *dataptr++ = (i*stride[0]+start[0])*100 + (j*stride[1]+start[1]+1); + } + } +} + + +/* + * Print the content of the dataset. + */ +void dataset_print(hssize_t start[], hsize_t count[], hsize_t stride[], DATATYPE * dataset) +{ + DATATYPE *dataptr = dataset; + int i, j; + + /* print the slab read */ + for (i=0; i < count[0]; i++){ + printf("Row %d: ", (int)(i*stride[0]+start[0])); + for (j=0; j < count[1]; j++){ + printf("%03d ", *dataptr++); + } + printf("\n"); + } +} + + +/* + * Print the content of the dataset. + */ +int dataset_vrfy(hssize_t start[], hsize_t count[], hsize_t stride[], DATATYPE *dataset, DATATYPE *original) +{ +#define MAX_ERR_REPORT 10 /* Maximum number of errors reported */ + DATATYPE *dataptr = dataset; + DATATYPE *originptr = original; + + int i, j, nerrors; + + /* print it if verbose */ + if (verbose) + dataset_print(start, count, stride, dataset); + + nerrors = 0; + for (i=0; i < count[0]; i++){ + for (j=0; j < count[1]; j++){ + if (*dataset++ != *original++){ + nerrors++; + if (nerrors <= MAX_ERR_REPORT){ + printf("Dataset Verify failed at [%d][%d](row %d, col %d): expect %d, got %d\n", + i, j, + (int)(i*stride[0]+start[0]), (int)(j*stride[1]+start[1]), + *(dataset-1), *(original-1)); + } + } + } + } + if (nerrors > MAX_ERR_REPORT) + printf("[more errors ...]\n"); + if (nerrors) + printf("%d errors found in dataset_vrfy\n", nerrors); + return(nerrors); +} + + +/* + * Example of using the parallel HDF5 library to create two datasets + * in one HDF5 files with parallel MPIO access support. + * The Datasets are of sizes (number-of-mpi-processes x DIM1) x DIM2. + * Each process controls only a slab of size DIM1 x DIM2 within each + * dataset. + */ + +void +phdf5writeInd(char *filename) +{ + hid_t fid1, fid2; /* HDF5 file IDs */ + hid_t acc_tpl1; /* File access templates */ + hid_t sid1,sid2; /* Dataspace ID */ + hid_t file_dataspace; /* File dataspace ID */ + hid_t mem_dataspace; /* memory dataspace ID */ + hid_t dataset1, dataset2; /* Dataset ID */ + int rank = SPACE1_RANK; /* Logical rank of dataspace */ + hsize_t dims1[SPACE1_RANK] = + {SPACE1_DIM1,SPACE1_DIM2}; /* dataspace dim sizes */ + hsize_t dimslocal1[SPACE1_RANK] = + {SPACE1_DIM1,SPACE1_DIM2}; /* local dataspace dim sizes */ + DATATYPE data_array1[SPACE1_DIM1][SPACE1_DIM2]; /* data buffer */ + + hssize_t start[SPACE1_RANK]; /* for hyperslab setting */ + hsize_t count[SPACE1_RANK], stride[SPACE1_RANK]; /* for hyperslab setting */ + + herr_t ret; /* Generic return value */ + int i, j; + int mpi_size, mpi_rank; + char *fname; + int mrc; /* mpi return code */ + + MPI_Comm comm = MPI_COMM_WORLD; + MPI_Info info = MPI_INFO_NULL; + + if (verbose) + printf("Independent write test on file %s\n", filename); + + /* set up MPI parameters */ + MPI_Comm_size(MPI_COMM_WORLD,&mpi_size); + MPI_Comm_rank(MPI_COMM_WORLD,&mpi_rank); + + /* ------------------- + * START AN HDF5 FILE + * -------------------*/ + /* setup file access template with parallel IO access. */ + acc_tpl1 = H5Pcreate (H5P_FILE_ACCESS); + assert(acc_tpl1 != FAIL); + MESG("H5Pcreate access succeed"); + /* set Parallel access with communicator */ + ret = H5Pset_mpi(acc_tpl1, comm, info); + assert(ret != FAIL); + MESG("H5Pset_mpi succeed"); + + /* create the file collectively */ + fid1=H5Fcreate(filename,H5F_ACC_TRUNC,H5P_DEFAULT,acc_tpl1); + assert(fid1 != FAIL); + MESG("H5Fcreate succeed"); + + /* Release file-access template */ + ret=H5Pclose(acc_tpl1); + assert(ret != FAIL); + + + /* -------------------------- + * Define the dimensions of the overall datasets + * and the slabs local to the MPI process. + * ------------------------- */ + /* setup dimensionality object */ + sid1 = H5Screate_simple (SPACE1_RANK, dims1, NULL); + assert (sid1 != FAIL); + MESG("H5Screate_simple succeed"); + + + /* create a dataset collectively */ + dataset1 = H5Dcreate(fid1, DATASETNAME1, H5T_NATIVE_INT, sid1, + H5P_DEFAULT); + assert(dataset1 != FAIL); + MESG("H5Dcreate succeed"); + + /* create another dataset collectively */ + dataset2 = H5Dcreate(fid1, DATASETNAME2, H5T_NATIVE_INT, sid1, + H5P_DEFAULT); + assert(dataset2 != FAIL); + MESG("H5Dcreate succeed"); + + + + /* set up dimensions of the slab this process accesses */ + start[0] = mpi_rank*SPACE1_DIM1/mpi_size; + start[1] = 0; + count[0] = SPACE1_DIM1/mpi_size; + count[1] = SPACE1_DIM2; + stride[0] = 1; + stride[1] =1; +if (verbose) + printf("start[]=(%d,%d), count[]=(%d,%d), total datapoints=%d\n", + start[0], start[1], count[0], count[1], count[0]*count[1]); + + /* put some trivial data in the data_array */ + dataset_fill(start, count, stride, &data_array1[0][0]); + MESG("data_array initialized"); + + /* create a file dataspace independently */ + file_dataspace = H5Dget_space (dataset1); + assert(file_dataspace != FAIL); + MESG("H5Dget_space succeed"); + ret=H5Sset_hyperslab(file_dataspace, start, count, stride); + assert(ret != FAIL); + MESG("H5Sset_hyperslab succeed"); + + /* create a memory dataspace independently */ + mem_dataspace = H5Screate_simple (SPACE1_RANK, count, NULL); + assert (mem_dataspace != FAIL); + + /* write data independently */ + ret = H5Dwrite(dataset1, H5T_NATIVE_INT, mem_dataspace, file_dataspace, + H5P_DEFAULT, data_array1); + assert(ret != FAIL); + MESG("H5Dwrite succeed"); + + /* write data independently */ + ret = H5Dwrite(dataset2, H5T_NATIVE_INT, mem_dataspace, file_dataspace, + H5P_DEFAULT, data_array1); + assert(ret != FAIL); + MESG("H5Dwrite succeed"); + + /* release dataspace ID */ + H5Sclose(file_dataspace); + + /* close dataset collectively */ + ret=H5Dclose(dataset1); + assert(ret != FAIL); + MESG("H5Dclose1 succeed"); + ret=H5Dclose(dataset2); + assert(ret != FAIL); + MESG("H5Dclose2 succeed"); + + /* release all IDs created */ + H5Sclose(sid1); + + /* close the file collectively */ + H5Fclose(fid1); +} + +/* Example of using the parallel HDF5 library to read a dataset */ +void +phdf5readInd(char *filename) +{ + hid_t fid1, fid2; /* HDF5 file IDs */ + hid_t acc_tpl1; /* File access templates */ + hid_t sid1,sid2; /* Dataspace ID */ + hid_t file_dataspace; /* File dataspace ID */ + hid_t mem_dataspace; /* memory dataspace ID */ + hid_t dataset1, dataset2; /* Dataset ID */ + int rank = SPACE1_RANK; /* Logical rank of dataspace */ + hsize_t dims1[] = {SPACE1_DIM1,SPACE1_DIM2}; /* dataspace dim sizes */ + DATATYPE data_array1[SPACE1_DIM1][SPACE1_DIM2]; /* data buffer */ + DATATYPE data_origin1[SPACE1_DIM1][SPACE1_DIM2]; /* expected data buffer */ + + hssize_t start[SPACE1_RANK]; /* for hyperslab setting */ + hsize_t count[SPACE1_RANK], stride[SPACE1_RANK]; /* for hyperslab setting */ + + herr_t ret; /* Generic return value */ + int i, j; + int mpi_size, mpi_rank; + + MPI_Comm comm = MPI_COMM_WORLD; + MPI_Info info = MPI_INFO_NULL; + + if (verbose) + printf("Independent read test on file %s\n", filename); + + /* set up MPI parameters */ + MPI_Comm_size(MPI_COMM_WORLD,&mpi_size); + MPI_Comm_rank(MPI_COMM_WORLD,&mpi_rank); + + + /* setup file access template */ + acc_tpl1 = H5Pcreate (H5P_FILE_ACCESS); + assert(acc_tpl1 != FAIL); + /* set Parallel access with communicator */ + ret = H5Pset_mpi(acc_tpl1, comm, info); + assert(ret != FAIL); + + + /* open the file collectively */ + fid1=H5Fopen(filename,H5F_ACC_RDWR,acc_tpl1); + assert(fid1 != FAIL); + + /* Release file-access template */ + ret=H5Pclose(acc_tpl1); + assert(ret != FAIL); + + /* open the dataset1 collectively */ + dataset1 = H5Dopen(fid1, DATASETNAME1); + assert(dataset1 != FAIL); + + /* open another dataset collectively */ + dataset2 = H5Dopen(fid1, DATASETNAME1); + assert(dataset2 != FAIL); + + + /* set up dimensions of the slab this process accesses */ + start[0] = mpi_rank*SPACE1_DIM1/mpi_size; + start[1] = 0; + count[0] = SPACE1_DIM1/mpi_size; + count[1] = SPACE1_DIM2; + stride[0] = 1; + stride[1] =1; +if (verbose) + printf("start[]=(%d,%d), count[]=(%d,%d), total datapoints=%d\n", + start[0], start[1], count[0], count[1], count[0]*count[1]); + + /* create a file dataspace independently */ + file_dataspace = H5Dget_space (dataset1); + assert(file_dataspace != FAIL); + ret=H5Sset_hyperslab(file_dataspace, start, count, stride); + assert(ret != FAIL); + + /* create a memory dataspace independently */ + mem_dataspace = H5Screate_simple (SPACE1_RANK, count, NULL); + assert (mem_dataspace != FAIL); + + /* fill dataset with test data */ + dataset_fill(start, count, stride, &data_origin1[0][0]); + + /* read data independently */ + ret = H5Dread(dataset1, H5T_NATIVE_INT, mem_dataspace, file_dataspace, + H5P_DEFAULT, data_array1); + assert(ret != FAIL); + + /* verify the read data with original expected data */ + ret = dataset_vrfy(start, count, stride, &data_array1[0][0], &data_origin1[0][0]); + assert(ret != FAIL); + + /* read data independently */ + ret = H5Dread(dataset2, H5T_NATIVE_INT, mem_dataspace, file_dataspace, + H5P_DEFAULT, data_array1); + assert(ret != FAIL); + + /* verify the read data with original expected data */ + ret = dataset_vrfy(start, count, stride, &data_array1[0][0], &data_origin1[0][0]); + assert(ret == 0); + + /* close dataset collectively */ + ret=H5Dclose(dataset1); + assert(ret != FAIL); + ret=H5Dclose(dataset2); + assert(ret != FAIL); + + /* release all IDs created */ + H5Sclose(file_dataspace); + + /* close the file collectively */ + H5Fclose(fid1); +} + + +/* + * Example of using the parallel HDF5 library to create two datasets + * in one HDF5 file with collective parallel access support. + * The Datasets are of sizes (number-of-mpi-processes x DIM1) x DIM2. + * Each process controls only a slab of size DIM1 x DIM2 within each + * dataset. [Note: not so yet. Datasets are of sizes DIM1xDIM2 and + * each process controls a hyperslab within.] + */ + +void +phdf5writeAll(char *filename) +{ + hid_t fid1, fid2; /* HDF5 file IDs */ + hid_t acc_tpl1; /* File access templates */ + hid_t xfer_plist; /* Dataset transfer properties list */ + hid_t sid1,sid2; /* Dataspace ID */ + hid_t file_dataspace; /* File dataspace ID */ + hid_t mem_dataspace; /* memory dataspace ID */ + hid_t dataset1, dataset2; /* Dataset ID */ + int rank = SPACE1_RANK; /* Logical rank of dataspace */ + hsize_t dims1[SPACE1_RANK] = + {SPACE1_DIM1,SPACE1_DIM2}; /* dataspace dim sizes */ + DATATYPE data_array1[SPACE1_DIM1][SPACE1_DIM2]; /* data buffer */ + + hssize_t start[SPACE1_RANK]; /* for hyperslab setting */ + hsize_t count[SPACE1_RANK], stride[SPACE1_RANK]; /* for hyperslab setting */ + + herr_t ret; /* Generic return value */ + int mpi_size, mpi_rank; + + MPI_Comm comm = MPI_COMM_WORLD; + MPI_Info info = MPI_INFO_NULL; + + if (verbose) + printf("Collective write test on file %s\n", filename); + + /* set up MPI parameters */ + MPI_Comm_size(MPI_COMM_WORLD,&mpi_size); + MPI_Comm_rank(MPI_COMM_WORLD,&mpi_rank); + + /* ------------------- + * START AN HDF5 FILE + * -------------------*/ + /* setup file access template with parallel IO access. */ + acc_tpl1 = H5Pcreate (H5P_FILE_ACCESS); + assert(acc_tpl1 != FAIL); + MESG("H5Pcreate access succeed"); + /* set Parallel access with communicator */ + ret = H5Pset_mpi(acc_tpl1, comm, info); + assert(ret != FAIL); + MESG("H5Pset_mpi succeed"); + + /* create the file collectively */ + fid1=H5Fcreate(filename,H5F_ACC_TRUNC,H5P_DEFAULT,acc_tpl1); + assert(fid1 != FAIL); + MESG("H5Fcreate succeed"); + + /* Release file-access template */ + ret=H5Pclose(acc_tpl1); + assert(ret != FAIL); + + + /* -------------------------- + * Define the dimensions of the overall datasets + * and create the dataset + * ------------------------- */ + /* setup dimensionality object */ + sid1 = H5Screate_simple (SPACE1_RANK, dims1, NULL); + assert (sid1 != FAIL); + MESG("H5Screate_simple succeed"); + + + /* create a dataset collectively */ + dataset1 = H5Dcreate(fid1, DATASETNAME1, H5T_NATIVE_INT, sid1, H5P_DEFAULT); + assert(dataset1 != FAIL); + MESG("H5Dcreate succeed"); + + /* create another dataset collectively */ + dataset2 = H5Dcreate(fid1, DATASETNAME2, H5T_NATIVE_INT, sid1, H5P_DEFAULT); + assert(dataset2 != FAIL); + MESG("H5Dcreate 2 succeed"); + + /* + * Set up dimensions of the slab this process accesses. + */ + + /* Dataset1: each process takes a block of rows. */ + slab_set(start, count, stride, BYROW); +if (verbose) + printf("start[]=(%d,%d), count[]=(%d,%d), total datapoints=%d\n", + start[0], start[1], count[0], count[1], count[0]*count[1]); + + /* create a file dataspace independently */ + file_dataspace = H5Dget_space (dataset1); + assert(file_dataspace != FAIL); + MESG("H5Dget_space succeed"); + ret=H5Sset_hyperslab(file_dataspace, start, count, stride); + assert(ret != FAIL); + MESG("H5Sset_hyperslab succeed"); + + /* create a memory dataspace independently */ + mem_dataspace = H5Screate_simple (SPACE1_RANK, count, NULL); + assert (mem_dataspace != FAIL); + + /* fill the local slab with some trivial data */ + dataset_fill(start, count, stride, &data_array1[0][0]); + MESG("data_array initialized"); + if (verbose){ + MESG("data_array created"); + dataset_print(start, count, stride, &data_array1[0][0]); + } + + /* set up the collective transfer properties list */ + xfer_plist = H5Pcreate (H5P_DATASET_XFER); + assert(xfer_plist != FAIL); + ret=H5Pset_xfer(xfer_plist, H5D_XFER_COLLECTIVE); + assert(ret != FAIL); + MESG("H5Pcreate xfer succeed"); + + /* write data collectively */ + ret = H5Dwrite(dataset1, H5T_NATIVE_INT, mem_dataspace, file_dataspace, + xfer_plist, data_array1); + assert(ret != FAIL); + MESG("H5Dwrite succeed"); + + /* release all temporary handles. */ + /* Could have used them for dataset2 but it is cleaner */ + /* to create them again.*/ + H5Sclose(file_dataspace); + H5Sclose(mem_dataspace); + H5Pclose(xfer_plist); + + /* Dataset2: each process takes a block of columns. */ + slab_set(start, count, stride, BYCOL); +if (verbose) + printf("start[]=(%d,%d), count[]=(%d,%d), total datapoints=%d\n", + start[0], start[1], count[0], count[1], count[0]*count[1]); + + /* put some trivial data in the data_array */ + dataset_fill(start, count, stride, &data_array1[0][0]); + MESG("data_array initialized"); + if (verbose){ + MESG("data_array created"); + dataset_print(start, count, stride, &data_array1[0][0]); + } + + /* create a file dataspace independently */ + file_dataspace = H5Dget_space (dataset1); + assert(file_dataspace != FAIL); + MESG("H5Dget_space succeed"); + ret=H5Sset_hyperslab(file_dataspace, start, count, stride); + assert(ret != FAIL); + MESG("H5Sset_hyperslab succeed"); + + /* create a memory dataspace independently */ + mem_dataspace = H5Screate_simple (SPACE1_RANK, count, NULL); + assert (mem_dataspace != FAIL); + + /* fill the local slab with some trivial data */ + dataset_fill(start, count, stride, &data_array1[0][0]); + MESG("data_array initialized"); + if (verbose){ + MESG("data_array created"); + dataset_print(start, count, stride, &data_array1[0][0]); + } + + /* set up the collective transfer properties list */ + xfer_plist = H5Pcreate (H5P_DATASET_XFER); + assert(xfer_plist != FAIL); + ret=H5Pset_xfer(xfer_plist, H5D_XFER_COLLECTIVE); + assert(ret != FAIL); + MESG("H5Pcreate xfer succeed"); + + /* write data independently */ + ret = H5Dwrite(dataset2, H5T_NATIVE_INT, mem_dataspace, file_dataspace, + xfer_plist, data_array1); + assert(ret != FAIL); + MESG("H5Dwrite succeed"); + + /* release all temporary handles. */ + H5Sclose(file_dataspace); + H5Sclose(mem_dataspace); + H5Pclose(xfer_plist); + + + /* + * All writes completed. Close datasets collectively + */ + ret=H5Dclose(dataset1); + assert(ret != FAIL); + MESG("H5Dclose1 succeed"); + ret=H5Dclose(dataset2); + assert(ret != FAIL); + MESG("H5Dclose2 succeed"); + + /* release all IDs created */ + H5Sclose(sid1); + + /* close the file collectively */ + H5Fclose(fid1); +} + +/* + * Example of using the parallel HDF5 library to read two datasets + * in one HDF5 file with collective parallel access support. + * The Datasets are of sizes (number-of-mpi-processes x DIM1) x DIM2. + * Each process controls only a slab of size DIM1 x DIM2 within each + * dataset. [Note: not so yet. Datasets are of sizes DIM1xDIM2 and + * each process controls a hyperslab within.] + */ + +void +phdf5readAll(char *filename) +{ + hid_t fid1, fid2; /* HDF5 file IDs */ + hid_t acc_tpl1; /* File access templates */ + hid_t xfer_plist; /* Dataset transfer properties list */ + hid_t sid1,sid2; /* Dataspace ID */ + hid_t file_dataspace; /* File dataspace ID */ + hid_t mem_dataspace; /* memory dataspace ID */ + hid_t dataset1, dataset2; /* Dataset ID */ + int rank = SPACE1_RANK; /* Logical rank of dataspace */ + hsize_t dims1[] = {SPACE1_DIM1,SPACE1_DIM2}; /* dataspace dim sizes */ + DATATYPE data_array1[SPACE1_DIM1][SPACE1_DIM2]; /* data buffer */ + DATATYPE data_origin1[SPACE1_DIM1][SPACE1_DIM2]; /* expected data buffer */ + + hssize_t start[SPACE1_RANK]; /* for hyperslab setting */ + hsize_t count[SPACE1_RANK], stride[SPACE1_RANK]; /* for hyperslab setting */ + + herr_t ret; /* Generic return value */ + int mpi_size, mpi_rank; + + MPI_Comm comm = MPI_COMM_WORLD; + MPI_Info info = MPI_INFO_NULL; + + if (verbose) + printf("Collective read test on file %s\n", filename); + + /* set up MPI parameters */ + MPI_Comm_size(MPI_COMM_WORLD,&mpi_size); + MPI_Comm_rank(MPI_COMM_WORLD,&mpi_rank); + + /* ------------------- + * OPEN AN HDF5 FILE + * -------------------*/ + /* setup file access template with parallel IO access. */ + acc_tpl1 = H5Pcreate (H5P_FILE_ACCESS); + assert(acc_tpl1 != FAIL); + MESG("H5Pcreate access succeed"); + /* set Parallel access with communicator */ + ret = H5Pset_mpi(acc_tpl1, comm, info); + assert(ret != FAIL); + MESG("H5Pset_mpi succeed"); + + /* open the file collectively */ + fid1=H5Fopen(filename,H5F_ACC_RDWR,acc_tpl1); + assert(fid1 != FAIL); + MESG("H5Fopen succeed"); + + /* Release file-access template */ + ret=H5Pclose(acc_tpl1); + assert(ret != FAIL); + + + /* -------------------------- + * Open the datasets in it + * ------------------------- */ + /* open the dataset1 collectively */ + dataset1 = H5Dopen(fid1, DATASETNAME1); + assert(dataset1 != FAIL); + MESG("H5Dopen succeed"); + + /* open another dataset collectively */ + dataset2 = H5Dopen(fid1, DATASETNAME1); + assert(dataset2 != FAIL); + MESG("H5Dopen 2 succeed"); + + /* + * Set up dimensions of the slab this process accesses. + */ + + /* Dataset1: each process takes a block of columns. */ + slab_set(start, count, stride, BYCOL); +if (verbose) + printf("start[]=(%d,%d), count[]=(%d,%d), total datapoints=%d\n", + start[0], start[1], count[0], count[1], count[0]*count[1]); + + /* create a file dataspace independently */ + file_dataspace = H5Dget_space (dataset1); + assert(file_dataspace != FAIL); + MESG("H5Dget_space succeed"); + ret=H5Sset_hyperslab(file_dataspace, start, count, stride); + assert(ret != FAIL); + MESG("H5Sset_hyperslab succeed"); + + /* create a memory dataspace independently */ + mem_dataspace = H5Screate_simple (SPACE1_RANK, count, NULL); + assert (mem_dataspace != FAIL); + + /* fill dataset with test data */ + dataset_fill(start, count, stride, &data_origin1[0][0]); + MESG("data_array initialized"); + if (verbose){ + MESG("data_array created"); + dataset_print(start, count, stride, &data_array1[0][0]); + } + + /* set up the collective transfer properties list */ + xfer_plist = H5Pcreate (H5P_DATASET_XFER); + assert(xfer_plist != FAIL); + ret=H5Pset_xfer(xfer_plist, H5D_XFER_COLLECTIVE); + assert(ret != FAIL); + MESG("H5Pcreate xfer succeed"); + + /* read data collectively */ + ret = H5Dread(dataset1, H5T_NATIVE_INT, mem_dataspace, file_dataspace, + xfer_plist, data_array1); + assert(ret != FAIL); + MESG("H5Dread succeed"); + + /* verify the read data with original expected data */ + ret = dataset_vrfy(start, count, stride, &data_array1[0][0], &data_origin1[0][0]); + assert(ret != FAIL); + + /* release all temporary handles. */ + /* Could have used them for dataset2 but it is cleaner */ + /* to create them again.*/ + H5Sclose(file_dataspace); + H5Sclose(mem_dataspace); + H5Pclose(xfer_plist); + + /* Dataset2: each process takes a block of rows. */ + slab_set(start, count, stride, BYROW); +if (verbose) + printf("start[]=(%d,%d), count[]=(%d,%d), total datapoints=%d\n", + start[0], start[1], count[0], count[1], count[0]*count[1]); + + /* create a file dataspace independently */ + file_dataspace = H5Dget_space (dataset1); + assert(file_dataspace != FAIL); + MESG("H5Dget_space succeed"); + ret=H5Sset_hyperslab(file_dataspace, start, count, stride); + assert(ret != FAIL); + MESG("H5Sset_hyperslab succeed"); + + /* create a memory dataspace independently */ + mem_dataspace = H5Screate_simple (SPACE1_RANK, count, NULL); + assert (mem_dataspace != FAIL); + + /* fill dataset with test data */ + dataset_fill(start, count, stride, &data_origin1[0][0]); + MESG("data_array initialized"); + if (verbose){ + MESG("data_array created"); + dataset_print(start, count, stride, &data_array1[0][0]); + } + + /* set up the collective transfer properties list */ + xfer_plist = H5Pcreate (H5P_DATASET_XFER); + assert(xfer_plist != FAIL); + ret=H5Pset_xfer(xfer_plist, H5D_XFER_COLLECTIVE); + assert(ret != FAIL); + MESG("H5Pcreate xfer succeed"); + + /* read data independently */ + ret = H5Dread(dataset2, H5T_NATIVE_INT, mem_dataspace, file_dataspace, + xfer_plist, data_array1); + assert(ret != FAIL); + MESG("H5Dread succeed"); + + /* verify the read data with original expected data */ + ret = dataset_vrfy(start, count, stride, &data_array1[0][0], &data_origin1[0][0]); + assert(ret != FAIL); + + /* release all temporary handles. */ + H5Sclose(file_dataspace); + H5Sclose(mem_dataspace); + H5Pclose(xfer_plist); + + + /* + * All reads completed. Close datasets collectively + */ + ret=H5Dclose(dataset1); + assert(ret != FAIL); + MESG("H5Dclose1 succeed"); + ret=H5Dclose(dataset2); + assert(ret != FAIL); + MESG("H5Dclose2 succeed"); + + /* close the file collectively */ + H5Fclose(fid1); +} + +/* + * test file access by communicator besides COMM_WORLD. + * Split COMM_WORLD into two, one (even_comm) contains the original + * processes of even ranks. The other (odd_comm) contains the original + * processes of odd ranks. Processes in even_comm creates a file, then + * cloose it, using even_comm. Processes in old_comm just do a barrier + * using odd_comm. Then they all do a barrier using COMM_WORLD. + * If the file creation and cloose does not do correct collective action + * according to the communicator argument, the processes will freeze up + * sooner or later due to barrier mixed up. + */ +void +test_split_comm_access(char *filenames[]) +{ + int mpi_size, myrank; + MPI_Comm comm; + MPI_Info info = MPI_INFO_NULL; + int color, mrc; + int newrank, newprocs; + hid_t fid; /* file IDs */ + hid_t acc_tpl; /* File access properties */ + herr_t ret; /* generic return value */ + + if (verbose) + printf("Independent write test on file %s %s\n", + filenames[0], filenames[1]); + + /* set up MPI parameters */ + MPI_Comm_size(MPI_COMM_WORLD,&mpi_size); + MPI_Comm_rank(MPI_COMM_WORLD,&myrank); + color = myrank%2; + mrc = MPI_Comm_split (MPI_COMM_WORLD, color, myrank, &comm); + assert(mrc==MPI_SUCCESS); + MPI_Comm_size(comm,&newprocs); + MPI_Comm_rank(comm,&newrank); + + if (color){ + /* odd-rank processes */ + mrc = MPI_Barrier(comm); + assert(mrc==MPI_SUCCESS); + }else{ + /* even-rank processes */ + /* setup file access template */ + acc_tpl = H5Pcreate (H5P_FILE_ACCESS); + assert(acc_tpl != FAIL); + + /* set Parallel access with communicator */ + ret = H5Pset_mpi(acc_tpl, comm, info); + assert(ret != FAIL); + + /* create the file collectively */ + fid=H5Fcreate(filenames[color],H5F_ACC_TRUNC,H5P_DEFAULT,acc_tpl); + assert(fid != FAIL); + MESG("H5Fcreate succeed"); + + /* Release file-access template */ + ret=H5Pclose(acc_tpl); + assert(ret != FAIL); + + ret=H5Fclose(fid); + assert(ret != FAIL); + } + if (myrank == 0){ + mrc = MPI_File_delete(filenames[color], info); + assert(mrc==MPI_SUCCESS); + } +} + +/* + * Show command usage + */ +void +usage() +{ + printf("Usage: testphdf5 [-r] [-w] [-v]\n"); + printf("\t-r\tno read\n"); + printf("\t-w\tno write\n"); + printf("\t-v\tverbose on\n"); + printf("\tdefault do write then read\n"); + printf("\n"); +} + + +/* + * parse the command line options + */ +int +parse_options(int argc, char **argv){ + while (--argc){ + if (**(++argv) != '-'){ + break; + }else{ + switch(*(*argv+1)){ + case 'r': doread = 0; + break; + case 'w': dowrite = 0; + break; + case 'v': verbose = 1; + break; + default: usage(); + nerrors++; + return(1); + } + } + } + return(0); +} + + +main(int argc, char **argv) +{ + char *filenames[]={ "ParaEg1.h5f", "ParaEg2.h5f" }; + + int mpi_namelen; + char mpi_name[MPI_MAX_PROCESSOR_NAME]; + + MPI_Init(&argc,&argv); + MPI_Comm_size(MPI_COMM_WORLD,&mpi_size); + MPI_Comm_rank(MPI_COMM_WORLD,&mpi_rank); + MPI_Get_processor_name(mpi_name,&mpi_namelen); + /* Make sure datasets can be divided into equal chunks by the processes */ + if ((SPACE1_DIM1 % mpi_size) || (SPACE1_DIM2 % mpi_size)){ + printf("DIM1(%d) and DIM2(%d) must be multiples of processes (%d)\n", + SPACE1_DIM1, SPACE1_DIM2, mpi_size); + nerrors++; + goto finish; + } + + if (parse_options(argc, argv) != 0) + goto finish; + + if (dowrite){ + MPI_BANNER("testing PHDF5 dataset using split communicators..."); + test_split_comm_access(filenames); + MPI_BANNER("testing PHDF5 dataset independent write..."); + phdf5writeInd(filenames[0]); + MPI_BANNER("testing PHDF5 dataset collective write..."); + phdf5writeAll(filenames[1]); + } + if (doread){ + MPI_BANNER("testing PHDF5 dataset independent read..."); + phdf5readInd(filenames[0]); + MPI_BANNER("testing PHDF5 dataset collective read..."); + phdf5readAll(filenames[1]); + } + + if (!(dowrite || doread)){ + usage(); + nerrors++; + } + +finish: + if (mpi_rank == 0){ /* only process 0 reports */ + if (nerrors) + printf("***PHDF5 tests detected %d errors***\n", nerrors); + else{ + printf("===================================\n"); + printf("PHDF5 tests finished with no errors\n"); + printf("===================================\n"); + } + } + MPI_Finalize(); + + return(nerrors); +} + diff --git a/doc/html/ph5implement.txt b/doc/html/ph5implement.txt new file mode 100644 index 0000000..2fcbb3d --- /dev/null +++ b/doc/html/ph5implement.txt @@ -0,0 +1,27 @@ +Release information for parallel HDF5 +------------------------------------- + ++) Current release supports independent access to fixed dimension datasets + only. + ++) The comm and info arguments of H5Pset_mpi are not used. All parallel + I/O are done via MPI_COMM_WORLD. Access_mode for H5Pset_mpi can be + H5ACC_INDEPENDENT only. + ++) This release of parallel HDF5 has been tested on IBM SP2 and SGI + Origin 2000 systems. It uses the ROMIO version of MPIO interface + for parallel I/O supports. + ++) Useful URL's. + Parallel HDF webpage: "http://hdf.ncsa.uiuc.edu/Parallel_HDF/" + ROMIO webpage: "http://www.mcs.anl.gov/home/thakur/romio/" + ++) Some to-do items for future releases + support for Intel Teraflop platform. + support for unlimited dimension datasets. + support for file access via a communicator besides MPI_COMM_WORLD. + support for collective access to datasets. + support for independent create/open of datasets. + +---- +Last updated: Feb 16, 1998. diff --git a/doc/html/pipe1.gif b/doc/html/pipe1.gif Binary files differnew file mode 100644 index 0000000..3b489a6 --- /dev/null +++ b/doc/html/pipe1.gif diff --git a/doc/html/pipe1.obj b/doc/html/pipe1.obj new file mode 100644 index 0000000..41f3461 --- /dev/null +++ b/doc/html/pipe1.obj @@ -0,0 +1,136 @@ +%TGIF 3.0-p5 +state(1,33,100,0,0,0,8,1,9,1,1,0,0,0,0,1,1,'Helvetica',0,17,0,0,0,10,0,0,1,1,0,16,0,0,1,1,1,0,1408,1088,0,0,2880). +% +% @(#)$Header$ +% %W% +% +unit("1 pixel/pixel"). +page(1,"",1). +box('black',64,64,128,256,0,1,1,22,0,0,0,0,0,'1',[ +]). +box('black',80,96,112,224,26,1,1,23,0,0,0,0,0,'1',[ +]). +poly('black',2,[ + 128,160,912,160],1,2,1,24,0,0,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',5,[ + 160,160,144,224,160,272,176,224,160,160],1,2,1,25,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +poly('black',5,[ + 848,160,832,224,848,272,864,224,848,160],1,2,1,34,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +box('black',464,192,496,256,26,1,1,39,0,0,0,0,0,'1',[ +]). +poly('black',2,[ + 160,224,464,224],1,2,1,40,0,26,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',2,[ + 496,224,848,224],1,2,1,41,0,26,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',5,[ + 192,224,176,288,192,336,208,288,192,224],1,2,1,42,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +poly('black',5,[ + 432,224,416,288,432,336,448,288,432,224],1,2,1,43,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +poly('black',2,[ + 192,288,432,288],1,2,1,44,0,26,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +box('black',464,352,496,416,26,1,1,45,0,0,0,0,0,'1',[ +]). +poly('black',5,[ + 528,224,512,288,528,336,544,288,528,224],1,2,1,46,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +poly('black',5,[ + 816,224,800,288,816,336,832,288,816,224],1,2,1,47,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +poly('black',2,[ + 528,288,816,288],1,2,1,48,0,26,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',5,[ + 464,256,456,304,464,328,488,304,488,256],1,2,1,62,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +poly('black',2,[ + 480,352,488,304],2,2,1,85,0,0,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +box('black',912,64,976,256,0,1,1,87,0,0,0,0,0,'1',[ +]). +box('black',928,96,960,224,26,1,1,88,0,0,0,0,0,'1',[ +]). +text('black',96,48,'Helvetica',0,17,1,1,0,1,21,15,89,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "File"]). +text('black',944,48,'Helvetica',0,17,1,1,0,1,64,15,93,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Application"]). +text('black',480,144,'Helvetica',0,17,1,1,0,1,65,15,99,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5D_read()"]). +text('black',480,128,'Helvetica',0,17,1,1,0,1,58,15,108,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5Dread()"]). +text('black',304,208,'Helvetica',0,17,1,1,0,1,86,15,115,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_arr_read()"]). +text('black',304,192,'Helvetica',0,17,1,1,0,1,99,15,119,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5S_simp_fgath()"]). +text('black',296,288,'Helvetica',0,17,1,1,0,1,101,15,125,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_block_read()"]). +text('black',296,304,'Helvetica',0,17,1,1,0,1,90,15,132,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_low_read()"]). +text('black',296,320,'Helvetica',0,17,1,1,0,1,98,15,136,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_sec2_read()"]). +text('black',296,336,'Helvetica',0,17,1,1,0,1,33,15,140,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "read()"]). +text('black',664,208,'Helvetica',0,17,1,1,0,1,106,15,146,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5V_stride_copy()"]). +text('black',664,176,'Helvetica',0,17,1,1,0,1,104,15,150,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5S_simp_mscat()"]). +text('black',664,272,'Helvetica',0,17,1,1,0,1,54,15,154,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "memcpy()"]). +text('black',384,392,'Helvetica',0,17,1,1,0,1,105,15,170,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5T_conv_struct()"]). +poly('black',4,[ + 392,384,400,352,440,368,456,336],1,1,1,172,1,0,0,0,8,3,0,0,0,'1','8','3', + "6",[ +]). +text('black',480,176,'Helvetica',0,17,1,1,0,1,44,15,176,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "TCONV"]). +text('black',480,416,'Helvetica',0,17,1,1,0,1,25,15,182,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "BKG"]). +box('black',48,32,992,512,0,1,1,186,0,0,0,0,0,'1',[ +]). +poly('black',5,[ + 72,392,56,456,72,504,88,456,72,392],1,2,1,188,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +text('black',96,448,'Helvetica',0,17,1,0,0,1,46,15,189,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "== Loop"]). +poly('black',3,[ + 48,384,152,384,152,512],0,1,1,191,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +text('black',480,40,'Helvetica',0,24,1,1,0,1,380,29,197,0,24,5,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Fig 1: Internal Contiguous Storage"]). +text('black',136,144,'Helvetica',0,17,1,1,0,1,9,15,201,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "A"]). +text('black',160,208,'Helvetica',0,17,1,1,0,1,8,15,207,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "B"]). +text('black',192,272,'Helvetica',0,17,1,1,0,1,9,15,211,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "C"]). +text('black',504,208,'Helvetica',0,17,1,1,0,1,8,15,215,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "E"]). +text('black',528,272,'Helvetica',0,17,1,1,0,1,8,15,223,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "F"]). +text('black',464,304,'Helvetica',0,17,1,1,0,1,9,15,231,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "D"]). +text('black',664,192,'Helvetica',0,17,1,1,0,1,107,15,324,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5V_hyper_copy()"]). diff --git a/doc/html/pipe2.gif b/doc/html/pipe2.gif Binary files differnew file mode 100644 index 0000000..3a0c947 --- /dev/null +++ b/doc/html/pipe2.gif diff --git a/doc/html/pipe2.obj b/doc/html/pipe2.obj new file mode 100644 index 0000000..70d9c18 --- /dev/null +++ b/doc/html/pipe2.obj @@ -0,0 +1,168 @@ +%TGIF 3.0-p5 +state(1,33,100,0,0,0,8,1,9,1,1,1,1,0,0,1,1,'Helvetica',0,17,0,0,0,10,0,0,1,1,0,16,0,0,1,1,1,0,1408,1088,0,0,2880). +% +% @(#)$Header$ +% %W% +% +unit("1 pixel/pixel"). +page(1,"",1). +box('black',64,64,128,256,0,1,1,22,0,0,0,0,0,'1',[ +]). +box('black',80,96,112,224,26,1,1,23,0,0,0,0,0,'1',[ +]). +poly('black',2,[ + 128,160,912,160],1,2,1,24,0,0,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',5,[ + 160,160,144,224,160,272,176,224,160,160],1,2,1,25,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +poly('black',5,[ + 848,160,832,224,848,272,864,224,848,160],1,2,1,34,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +box('black',464,192,496,256,26,1,1,39,0,0,0,0,0,'1',[ +]). +poly('black',2,[ + 160,224,464,224],1,2,1,40,0,26,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',2,[ + 496,224,848,224],1,2,1,41,0,26,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',5,[ + 192,224,176,288,192,336,208,288,192,224],1,2,1,42,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +poly('black',5,[ + 432,224,416,288,432,336,448,288,432,224],1,2,1,43,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +poly('black',2,[ + 192,288,432,288],1,2,1,44,0,26,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +box('black',464,352,496,416,26,1,1,45,0,0,0,0,0,'1',[ +]). +poly('black',5,[ + 528,224,512,288,528,336,544,288,528,224],1,2,1,46,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +poly('black',5,[ + 816,224,800,288,816,336,832,288,816,224],1,2,1,47,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +poly('black',2,[ + 528,288,816,288],1,2,1,48,0,26,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',5,[ + 848,240,848,352,832,384,800,384,496,384],1,2,1,55,1,0,0,0,10,4,0,0,0,'2','10','4', + "70",[ +]). +poly('black',5,[ + 528,384,512,448,528,496,544,448,528,384],1,2,1,57,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +poly('black',5,[ + 800,384,784,448,800,496,816,448,800,384],1,2,1,58,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +poly('black',2,[ + 800,448,528,448],1,2,1,61,0,0,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',5,[ + 464,256,456,304,464,328,488,304,488,256],1,2,1,62,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +poly('black',2,[ + 480,352,488,304],0,2,1,85,0,0,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +box('black',912,64,976,256,0,1,1,87,0,0,0,0,0,'1',[ +]). +box('black',928,96,960,224,26,1,1,88,0,0,0,0,0,'1',[ +]). +text('black',96,48,'Helvetica',0,17,1,1,0,1,21,15,89,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "File"]). +text('black',944,48,'Helvetica',0,17,1,1,0,1,64,15,93,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Application"]). +text('black',480,144,'Helvetica',0,17,1,1,0,1,65,15,99,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5D_read()"]). +text('black',480,128,'Helvetica',0,17,1,1,0,1,58,15,108,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5Dread()"]). +text('black',304,208,'Helvetica',0,17,1,1,0,1,86,15,115,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_arr_read()"]). +text('black',304,192,'Helvetica',0,17,1,1,0,1,99,15,119,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5S_simp_fgath()"]). +text('black',296,288,'Helvetica',0,17,1,1,0,1,101,15,125,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_block_read()"]). +text('black',296,304,'Helvetica',0,17,1,1,0,1,90,15,132,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_low_read()"]). +text('black',296,320,'Helvetica',0,17,1,1,0,1,98,15,136,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_sec2_read()"]). +text('black',296,336,'Helvetica',0,17,1,1,0,1,33,15,140,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "read()"]). +text('black',664,208,'Helvetica',0,17,1,1,0,1,106,15,146,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5V_stride_copy()"]). +text('black',664,176,'Helvetica',0,17,1,1,0,1,104,15,150,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5S_simp_mscat()"]). +text('black',664,272,'Helvetica',0,17,1,1,0,1,54,15,154,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "memcpy()"]). +text('black',672,368,'Helvetica',0,17,1,1,0,1,106,15,158,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5V_stride_copy()"]). +text('black',672,336,'Helvetica',0,17,1,1,0,1,105,15,162,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5S_simp_mgath()"]). +text('black',672,432,'Helvetica',0,17,1,1,0,1,54,15,166,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "memcpy()"]). +text('black',384,392,'Helvetica',0,17,1,1,0,1,105,15,170,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5T_conv_struct()"]). +poly('black',4,[ + 392,384,400,352,440,368,456,336],1,1,1,172,1,0,0,0,8,3,0,0,0,'1','8','3', + "6",[ +]). +text('black',480,176,'Helvetica',0,17,1,1,0,1,44,15,176,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "TCONV"]). +text('black',480,416,'Helvetica',0,17,1,1,0,1,25,15,182,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "BKG"]). +box('black',48,32,992,512,0,1,1,186,0,0,0,0,0,'1',[ +]). +poly('black',5,[ + 72,392,56,456,72,504,88,456,72,392],1,2,1,188,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +text('black',96,448,'Helvetica',0,17,1,0,0,1,46,15,189,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "== Loop"]). +poly('black',3,[ + 48,384,152,384,152,512],0,1,1,191,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +text('black',480,40,'Helvetica',0,24,1,1,0,1,404,29,197,0,24,5,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Fig 2: Partially Initialized Destination"]). +text('black',136,144,'Helvetica',0,17,1,1,0,1,9,15,201,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "A"]). +text('black',160,208,'Helvetica',0,17,1,1,0,1,8,15,207,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "B"]). +text('black',192,272,'Helvetica',0,17,1,1,0,1,9,15,211,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "C"]). +text('black',504,208,'Helvetica',0,17,1,1,0,1,8,15,215,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "E"]). +text('black',528,272,'Helvetica',0,17,1,1,0,1,8,15,223,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "F"]). +text('black',856,288,'Helvetica',0,17,1,1,0,1,9,15,225,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "G"]). +text('black',800,432,'Helvetica',0,17,1,1,0,1,9,15,229,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H"]). +text('black',464,304,'Helvetica',0,17,1,1,0,1,9,15,231,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "D"]). +poly('black',4,[ + 848,240,848,224,864,224,904,224],0,2,1,318,1,0,0,0,10,4,0,0,0,'2','10','4', + "6",[ +]). +text('black',664,192,'Helvetica',0,17,1,1,0,1,107,15,326,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5V_hyper_copy()"]). +text('black',672,352,'Helvetica',0,17,1,1,0,1,107,15,334,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5V_hyper_copy()"]). diff --git a/doc/html/pipe3.gif b/doc/html/pipe3.gif Binary files differnew file mode 100644 index 0000000..26d82ad --- /dev/null +++ b/doc/html/pipe3.gif diff --git a/doc/html/pipe3.obj b/doc/html/pipe3.obj new file mode 100644 index 0000000..cdfef7c --- /dev/null +++ b/doc/html/pipe3.obj @@ -0,0 +1,70 @@ +%TGIF 3.0-p5 +state(1,33,100,0,0,0,8,1,9,1,1,0,0,0,0,1,1,'Helvetica',0,17,0,0,0,10,0,0,1,1,0,16,0,0,1,1,1,0,1408,1088,0,0,2880). +% +% @(#)$Header$ +% %W% +% +unit("1 pixel/pixel"). +page(1,"",1). +box('black',64,64,128,256,0,1,1,22,0,0,0,0,0,'1',[ +]). +box('black',80,96,112,224,26,1,1,23,0,0,0,0,0,'1',[ +]). +poly('black',2,[ + 128,160,912,160],1,2,1,24,0,0,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +box('black',912,64,976,256,0,1,1,87,0,0,0,0,0,'1',[ +]). +box('black',928,96,960,224,26,1,1,88,0,0,0,0,0,'1',[ +]). +text('black',96,48,'Helvetica',0,17,1,1,0,1,21,15,89,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "File"]). +text('black',944,48,'Helvetica',0,17,1,1,0,1,64,15,93,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Application"]). +text('black',480,104,'Helvetica',0,17,1,1,0,1,65,15,99,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5D_read()"]). +text('black',480,88,'Helvetica',0,17,1,1,0,1,58,15,108,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5Dread()"]). +box('black',48,32,992,512,0,1,1,186,0,0,0,0,0,'1',[ +]). +poly('black',5,[ + 72,392,56,456,72,504,88,456,72,392],1,2,1,188,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +text('black',96,448,'Helvetica',0,17,1,0,0,1,46,15,189,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "== Loop"]). +poly('black',3,[ + 48,384,152,384,152,512],0,1,1,191,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +text('black',480,40,'Helvetica',0,24,1,1,0,1,295,29,197,0,24,5,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Fig 3: No Type Conversion"]). +text('black',136,144,'Helvetica',0,17,1,1,0,1,9,15,201,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "A"]). +poly('black',5,[ + 152,160,136,224,152,272,168,224,152,160],1,2,1,273,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +text('black',480,120,'Helvetica',0,17,1,1,0,1,96,15,277,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5S_simp_read()"]). +text('black',480,136,'Helvetica',0,17,1,1,0,1,86,15,281,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_arr_read()"]). +poly('black',5,[ + 880,160,864,224,880,272,896,224,880,160],1,2,1,283,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +poly('black',2,[ + 152,224,880,224],1,2,1,286,0,0,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +text('black',480,232,'Helvetica',0,17,1,1,0,1,101,15,291,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_block_read()"]). +text('black',480,248,'Helvetica',0,17,1,1,0,1,90,15,293,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_low_read()"]). +text('black',480,264,'Helvetica',0,17,1,1,0,1,98,15,309,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_sec2_read()"]). +text('black',480,280,'Helvetica',0,17,1,1,0,1,33,15,311,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "read()"]). +text('black',176,208,'Helvetica',0,17,1,1,0,1,8,15,418,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "B"]). diff --git a/doc/html/pipe4.gif b/doc/html/pipe4.gif Binary files differnew file mode 100644 index 0000000..a3a857b --- /dev/null +++ b/doc/html/pipe4.gif diff --git a/doc/html/pipe4.obj b/doc/html/pipe4.obj new file mode 100644 index 0000000..6f50123 --- /dev/null +++ b/doc/html/pipe4.obj @@ -0,0 +1,92 @@ +%TGIF 3.0-p5 +state(1,33,100,0,0,0,8,1,9,1,1,1,2,1,0,1,0,'Helvetica',0,17,0,0,0,10,0,0,1,1,0,16,0,0,1,1,1,0,1408,1088,0,0,2880). +% +% @(#)$Header$ +% %W% +% +unit("1 pixel/pixel"). +page(1,"",1). +box('black',64,64,128,256,0,1,1,22,0,0,0,0,0,'1',[ +]). +box('black',80,96,112,224,26,1,1,23,0,0,0,0,0,'1',[ +]). +poly('black',2,[ + 128,160,912,160],1,2,1,24,0,0,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +box('black',912,96,944,224,26,1,1,88,0,0,0,0,0,'1',[ +]). +text('black',96,48,'Helvetica',0,17,1,1,0,1,21,15,89,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "File"]). +text('black',928,72,'Helvetica',0,17,1,1,0,1,32,15,93,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Buffer"]). +box('black',48,32,992,512,0,1,1,186,0,0,0,0,0,'1',[ +]). +poly('black',5,[ + 72,392,56,456,72,504,88,456,72,392],1,2,1,188,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +text('black',96,448,'Helvetica',0,17,1,0,0,1,46,15,189,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "== Loop"]). +poly('black',3,[ + 48,384,152,384,152,512],0,1,1,191,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +text('black',480,40,'Helvetica',0,24,1,1,0,1,372,29,197,0,24,5,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Fig 4: Regularly Chunked Storage"]). +text('black',136,144,'Helvetica',0,17,1,1,0,1,9,15,201,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "A"]). +text('black',480,104,'Helvetica',0,17,1,1,0,1,86,15,281,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_arr_read()"]). +text('black',480,120,'Helvetica',0,17,1,1,0,1,102,15,349,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_istore_read()"]). +text('black',480,136,'Helvetica',0,17,1,1,0,1,167,15,351,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_istore_copy_hyperslab()"]). +poly('black',5,[ + 160,160,144,224,160,272,176,224,160,160],1,2,1,362,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +poly('black',5,[ + 880,160,864,224,880,272,896,224,880,160],1,2,1,363,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +box('black',448,192,512,256,26,1,1,364,0,0,0,0,0,'1',[ +]). +text('black',480,176,'Helvetica',0,17,1,1,0,1,43,15,367,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "CHUNK"]). +poly('black',2,[ + 160,224,448,224],1,2,1,372,0,0,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +poly('black',2,[ + 512,224,880,224],1,2,1,373,0,0,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +text('black',288,224,'Helvetica',0,17,1,1,0,1,101,15,385,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_block_read()"]). +text('black',288,240,'Helvetica',0,17,1,1,0,1,90,15,387,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_low_read()"]). +text('black',288,256,'Helvetica',0,17,1,1,0,1,98,15,391,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_sec2_read()"]). +text('black',288,272,'Helvetica',0,17,1,1,0,1,33,15,395,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "read()"]). +poly('black',5,[ + 456,256,448,296,480,320,512,296,504,256],1,2,1,401,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +text('black',184,208,'Helvetica',0,17,1,1,0,1,8,15,422,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "B"]). +text('black',520,208,'Helvetica',0,17,1,1,0,1,9,15,434,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "D"]). +text('black',440,272,'Helvetica',0,17,1,1,0,1,9,15,440,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "C"]). +text('black',480,320,'Helvetica',0,17,1,1,0,1,107,15,444,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5Z_uncompress()"]). +text('black',672,224,'Helvetica',0,17,1,1,0,1,107,15,454,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5V_hyper_copy()"]). +text('black',672,240,'Helvetica',0,17,1,1,0,1,106,15,464,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5V_stride_copy()"]). +text('black',672,256,'Helvetica',0,17,1,1,0,1,54,15,466,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "memcpy()"]). +text('black',168,488,'Helvetica',0,17,1,0,0,1,282,15,471,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "NOTE: H5Z_uncompress() is not implemented yet."]). diff --git a/doc/html/pipe5.gif b/doc/html/pipe5.gif Binary files differnew file mode 100644 index 0000000..6ae0098 --- /dev/null +++ b/doc/html/pipe5.gif diff --git a/doc/html/pipe5.obj b/doc/html/pipe5.obj new file mode 100644 index 0000000..4738bbd --- /dev/null +++ b/doc/html/pipe5.obj @@ -0,0 +1,52 @@ +%TGIF 3.0-p5 +state(1,33,100,0,0,0,8,1,9,1,1,1,2,1,0,1,0,'Helvetica',0,17,0,0,0,10,0,0,1,1,0,16,0,0,1,1,1,0,1408,1088,0,0,2880). +% +% @(#)$Header$ +% %W% +% +unit("1 pixel/pixel"). +page(1,"",1). +box('black',64,64,128,256,0,1,1,22,0,0,0,0,0,'1',[ +]). +box('black',80,96,112,224,26,1,1,23,0,0,0,0,0,'1',[ +]). +poly('black',2,[ + 128,160,912,160],1,2,1,24,0,0,0,0,10,4,0,0,0,'2','10','4', + "0",[ +]). +box('black',912,96,944,224,26,1,1,88,0,0,0,0,0,'1',[ +]). +text('black',96,48,'Helvetica',0,17,1,1,0,1,21,15,89,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "File"]). +text('black',928,72,'Helvetica',0,17,1,1,0,1,32,15,93,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Buffer"]). +box('black',48,32,992,512,0,1,1,186,0,0,0,0,0,'1',[ +]). +text('black',480,40,'Helvetica',0,24,1,1,0,1,333,29,197,0,24,5,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Fig 5: Reading a Single Chunk"]). +text('black',136,144,'Helvetica',0,17,1,1,0,1,9,15,201,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "A"]). +text('black',480,112,'Helvetica',0,17,1,1,0,1,86,15,281,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_arr_read()"]). +text('black',480,128,'Helvetica',0,17,1,1,0,1,102,15,349,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_istore_read()"]). +text('black',480,144,'Helvetica',0,17,1,1,0,1,167,15,351,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_istore_copy_hyperslab()"]). +text('black',480,160,'Helvetica',0,17,1,1,0,1,101,15,385,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_block_read()"]). +text('black',480,176,'Helvetica',0,17,1,1,0,1,90,15,387,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_low_read()"]). +text('black',480,192,'Helvetica',0,17,1,1,0,1,98,15,391,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5F_sec2_read()"]). +text('black',480,208,'Helvetica',0,17,1,1,0,1,33,15,395,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "read()"]). +text('black',864,240,'Helvetica',0,17,1,1,0,1,107,15,444,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "H5Z_uncompress()"]). +text('black',56,488,'Helvetica',0,17,1,0,0,1,282,15,471,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "NOTE: H5Z_uncompress() is not implemented yet."]). +poly('black',5,[ + 912,176,864,176,840,208,872,232,912,216],1,2,1,490,2,0,0,0,10,4,0,0,0,'2','10','4', + "",[ +]). +text('black',896,184,'Helvetica',0,17,1,0,0,1,8,15,491,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "B"]). diff --git a/doc/html/review1.html b/doc/html/review1.html new file mode 100644 index 0000000..50d55cd --- /dev/null +++ b/doc/html/review1.html @@ -0,0 +1,283 @@ +<html><head><title> +HDF5 Draft Revised API Example Code +</title></head><body> + +<center> +<h1>HDF5: Revised API Example Code</h1> +</center> + +<P>Example programs/sections of code below: +<dl COMPACT> + <dt><a href="#Example1">#1</a> + <dd>A simple example showing how to create a file. + <dt><a href="#Example2">#2</a> + <dd>A example showing how to check if a file is an HDF5 file and list it's contents. + <dt><a href="#Example3">#3</a> + <dd>A example showing how to create a homogenous multi-dimensional dataset. + <dt><a href="#Example4">#4</a> + <dd>A example showing how to create a compound 1-D dataset. + <dt><a href="#Example5">#5</a> + <dd>A example showing how to create a compound multi-dimensional dataset. + <dt><a href="#Example6">#6</a> + <dd>A example showing how to read a generic dataset. +</dl> + +<hr> +<h2><a name="Example1">Simple Example showing how to create a file.</a></h2> + +<P>Notes:<br> +This example creates a new HDF5 file and allows write access. +If the file exists already, the H5F_ACC_TRUNC flag would also be necessary to +overwrite the previous file's information. + +<P>Code: + +<code> <pre> + hid_t file_id; + + file_id=<A HREF="H5.apiv3.html#File-Create">H5Fcreate</a>("example1.h5",0); + + <A HREF="H5.apiv3.html#File-Close">H5Fclose</a>(file_id); + +</pre> </code> + +<hr> +<h2><a name="Example2">Example showing how check if a file is an HDF5 file and list it's contents.</a></h2> + +<P>Notes:<br> +This example checks if a file is an HDF5 file and lists the contents of the top +level (file level) group. + +<P>Code: + +<code> <pre> + hid_t file_id; /* File ID */ + uint32 num_items; /* number of items in top-level group */ + intn i; /* counter */ + char *obj_name; /* object's name as string atom */ + uintn name_len; /* object name's length in chars */ + uintn buf_len=0; /* buffer length for names */ + char *buf=NULL; /* buffer for names */ + + if(<A HREF="H5.apiv3.html#File-IsHDF5">H5Fis_hdf5</a>("example2.h5")==TRUE) + { + file_id=<A HREF="H5.apiv3.html#File-Open">H5Fopen</a>("example2.h5",H5F_ACC_RDWR|H5ACC_CREATE); + num_items=<A HREF="H5.apiv3.html#Group-GetNumContents">H5GgetNumContents</a>(file_id); + for(i=0; i<num_items; i++) + { + obj_name=<A HREF="H5.apiv3.html#Group-GetNameByIndex">H5GgetNameByIndex</a>(file_id,i,NULL,0); + printf("object #%d is: %s\n",i,buf); + HDfree(obj_name); + } + <A HREF="H5.apiv3.html#File-Close">H5Fclose</a>(file_id); + } + +</pre> </code> + +<hr> +<h2><a name="Example3">Example showing how create a homogenous multi-dimensional dataset.</a></h2> + +<P>Notes:<br> +This example creates a 4-dimensional dataset of 32-bit floating-point +numbers, corresponding to the current Scientific Dataset functionality. +This example assumes that the datatype and dataspace of the dataset will not +be re-used. + +<P>Code: + +<code> <pre> + hid_t file_id; /* File's ID */ + uint32 dims[4]={6,5,4,3}; /* the size of each dimension */ + hid_t dataset_id; /* new object's ID */ + float32 obj_data[6][5][4][3]; /* storage for the dataset's data */ + + if((file_id=<A HREF="H5.apiv3.html#File-Create">H5Fcreate</a>("example3.h5",H5F_ACC_TRUNC))>=0) + { + /* Create & initialize the dataset object */ + dataset_id=<A HREF="H5.apiv3.html#Meta-Create">H5Mcreate</a>(file_id,H5OBJ_DATASET,"Simple Object"); + + /* Create & initialize a datatype object */ + <A HREF="H5.apiv3.html#Datatype-SetType">H5TsetType</a>(dataset_id,H5TYPE_FLOAT,4,H5T_BIGENDIAN); + + /* Initialize dimensionality of dataset */ + <A HREF="H5.apiv3.html#Dimensionality-SetSpace">H5SsetSpace</a>(dataset_id,rank,dims); + + <initialize data array> + + /* Write the entire dataset out */ + <A HREF="H5.apiv3.html#Dataset-Write">H5Dwrite</a>(dataset_id,H5S_SCALAR,data); + <or> + <A HREF="H5.apiv3.html#Dataset-Write">H5Dwrite</a>(dataset_id,dataset_id,data); + + /* Release the atoms we've created */ + <A HREF="H5.apiv3.html#Meta-Release">H5Mrelease</a>(dataset_id); + + /* close the file */ + <A HREF="H5.apiv3.html#File-Close">H5Fclose</a>(file_id); + } +</pre> </code> + +<hr> +<h2><a name="Example4">Example showing how create a compound 1-D dataset.</a></h2> + +<P>Notes:<br> +This example creates a 1-dimensional dataset of compound datatype records, +corresponding to the current Vdata functionality. This example also assumes +that the datatype and dataspace will not be re-used. + +<P>Code: + +<code> <pre> + hid_t file_id; /* File's ID */ + uint32 dims[1]={45}; /* the size of the dimension */ + hid_t dataset_id; /* object's ID */ + void *obj_data; /* pointer to the dataset's data */ + + if((file_id=<A HREF="H5.apiv3.html#File-Create">H5Fcreate</a>("example4.h5",H5F_ACC_TRUNC))>=0) + { + /* Create & initialize the dataset object */ + dataset_id=<A HREF="H5.apiv3.html#Meta-Create">H5Mcreate</a>(file_id,H5OBJ_DATASET,"Compound Object"); + + /* Initialize datatype */ + <A HREF="H5.apiv3.html#Datatype-SetType">H5TsetType</a>(dataset_id,H5TYPE_STRUCT); + <A HREF="H5.apiv3.html#Datatype-AddField">H5TaddField</a>(dataset_id,H5TYPE_FLOAT32,"Float32 Scalar Field",H5SPACE_SCALAR); + <A HREF="H5.apiv3.html#Datatype-AddField">H5TaddField</a>(dataset_id,H5TYPE_CHAR,"Char Field",H5SPACE_SCALAR); + <A HREF="H5.apiv3.html#Datatype-AddField">H5TaddField</a>(dataset_id,H5TYPE_UINT16,"UInt16 Field",H5SPACE_SCALAR); + <A HREF="H5.apiv3.html#Datatype-EndDefine">H5TendDefine</a>(dataset_id); + + /* Initialize dimensionality */ + <A HREF="H5.apiv3.html#Dimensionality-SetSpace">H5SsetSpace</a>(dataset_id,1,dims); + + <initialize data array> + + /* Write the entire dataset out */ + <A HREF="H5.apiv3.html#Dataset-Write">H5Dwrite</a>(dataset_id,H5S_SCALAR,data); + + /* Release the atoms we've created */ + <A HREF="H5.apiv3.html#Meta-Release">H5Mrelease</a>(dataset_id); + + /* close the file */ + <A HREF="H5.apiv3.html#File-Close">H5Fclose</a>(file_id); + } +</pre> </code> + +<hr> +<h2><a name="Example5">Example showing how create a compound multi-dimensional dataset.</a></h2> + +<P>Notes:<br> +This example creates a 3-dimensional dataset of compound datatype records, +roughly corresponding to a multi-dimensional Vdata functionality. This +example also shows the use of multi-dimensional fields in the compound datatype. +This example uses "stand-alone" datatypes and dataspaces. + +<P>Code: + +<code> <pre> + hid_t file_id; /* File's ID */ + hid_t type_id; /* datatype's ID */ + hid_t dim_id; /* dimensionality's ID */ + uint32 dims[3]={95,67,5}; /* the size of the dimensions */ + hid_t field_dim_id; /* dimensionality ID for fields in the structure */ + uint32 field_dims[4]; /* array for field dimensions */ + hid_t dataset_id; /* object's ID */ + void *obj_data; /* pointer to the dataset's data */ + + if((file_id=<A HREF="H5.apiv3.html#File-Create">H5Fcreate</a>("example5.h5",H5F_ACC_TRUNC))>=0) + { + /* Create & initialize a datatype object */ + type_id=<A HREF="H5.apiv3.html#Meta-Create">H5Mcreate</a>(file_id,H5OBJ_DATATYPE,"Compound Type #1"); + <A HREF="H5.apiv3.html#Datatype-SetType">H5TsetType</a>(type_id,H5TYPE_STRUCT); + + /* Create each multi-dimensional field in structure */ + field_dim_id=<A HREF="H5.apiv3.html#Meta-Create">H5Mcreate</a>(file_id,H5OBJ_DATASPACE,"Lat/Long Dims"); + field_dims[0]=360; + field_dims[1]=720; + <A HREF="H5.apiv3.html#Dimensionality-SetSpace">H5SsetSpace</a>(field_dim_id,2,field_dims); + <A HREF="H5.apiv3.html#Datatype-AddField">H5TaddField</a>(type_id,H5TYPE_FLOAT32,"Lat/Long Locations",field_dim_id); + <A HREF="H5.apiv3.html#Meta-Release">H5Mrelease</a>(field_dim_id); + + field_dim_id=<A HREF="H5.apiv3.html#Meta-Create">H5Mcreate</a>(file_id,H5OBJ_DATASPACE,"Browse Dims"); + field_dims[0]=40; + field_dims[1]=40; + <A HREF="H5.apiv3.html#Dimensionality-SetSpace">H5SsetSpace</a>(field_dim_id,2,field_dims); + <A HREF="H5.apiv3.html#Datatype-AddField">H5TaddField</a>(type_id,H5TYPE_CHAR,"Browse Image",field_dim_id); + <A HREF="H5.apiv3.html#Meta-Release">H5Mrelease</a>(field_dim_id); + + field_dim_id=<A HREF="H5.apiv3.html#Meta-Create">H5Mcreate</a>(file_id,H5OBJ_DATASPACE,"Multispectral Dims"); + field_dims[0]=80; + field_dims[1]=60; + field_dims[2]=40; + <A HREF="H5.apiv3.html#Dimensionality-SetSpace">H5SsetSpace</a>(field_dim_id,3,field_dims); + <A HREF="H5.apiv3.html#Datatype-AddField">H5TaddField</a>(type_id,H5TYPE_UINT16,"Multispectral Scans",field_dim_id); + <A HREF="H5.apiv3.html#Meta-Release">H5Mrelease</a>(field_dim_id); + <A HREF="H5.apiv3.html#Datatype-EndDefine">H5TendDefine</a>(type_id); + + /* Create & initialize a dimensionality object */ + dim_id=<A HREF="H5.apiv3.html#Meta-Create">H5Mcreate</a>(file_id,H5OBJ_DATASPACE,"3-D Dim"); + <A HREF="H5.apiv3.html#Dimensionality-SetSpace">H5SsetSpace</a>(dim_id,3,dims); + + /* Create & initialize the dataset object */ + dataset_id=<A HREF="H5.apiv3.html#Meta-Create">H5Mcreate</a>(file_id,H5OBJ_DATASET,"Compound Multi-Dim Object"); + <A HREF="H5.apiv3.html#Dataset-SetInfo">H5DsetInfo</a>(dataset_id,type_id,dim_id); + + <initialize data array> + + /* Write the entire dataset out */ + <A HREF="H5.apiv3.html#Dataset-Write">H5Dwrite</a>(dataset_id,H5S_SCALAR,data); + + /* Release the atoms we've created */ + <A HREF="H5.apiv3.html#Meta-Release">H5Mrelease</a>(type_id); + <A HREF="H5.apiv3.html#Meta-Release">H5Mrelease</a>(dim_id); + <A HREF="H5.apiv3.html#Meta-Release">H5Mrelease</a>(dataset_id); + + /* close the file */ + <A HREF="H5.apiv3.html#File-Close">H5Fclose</a>(file_id); + } +</pre> </code> + +<hr> +<h2><a name="Example6">Example showing how read a generic dataset.</a></h2> + +<P>Notes:<br> +This example shows how to get the information for and display a generic +dataset. + +<P>Code: + +<code> <pre> + hid_t file_id; /* File's ID */ + hid_t dataset_id; /* dataset's ID in memory */ + uintn elem_size; /* size of each element */ + uintn nelems; /* number of elements in array */ + void *obj_data; /* pointer to the dataset's data */ + + if((file_id=<A HREF="H5.apiv3.html#File-Open">H5Fopen</a>("example6.h5",0))>=0) + { + /* Attach to a datatype object */ + dataset_id=<A HREF="H5.apiv3.html#Meta-Access">H5MaccessByIndex</a>(obj_oid,0); + + if(<A HREF="H5.apiv3.html#Datatype-BaseType">H5TbaseType</a>(dataset_id)==H5T_COMPOUND) + { + <set up for compound object> + } + else + { + <set up for homogenous object> + } + + elem_size=<A HREF="H5.apiv3.html#Datatype-Size">H5Tsize</a>(dataset_id); + nelems=<A HREF="H5.apiv3.html#Dataspace-NElem">H5Snelem</a>(dataset_id); + <allocate space based on element size and number of elements > + + /* Read in the dataset */ + <A HREF="H5.apiv3.html#Dataset-Read">H5Dwrite</a>(dataset_id,H5S_SCALAR,data); + <or> + <A HREF="H5.apiv3.html#Dataset-Read">H5Dwrite</a>(dataset_id,dataset_id,data); + + /* Release the atoms we've accessed */ + <A HREF="H5.apiv3.html#Meta-Release">H5Mrelease</a>(dataset_id); + + /* close the file */ + <A HREF="H5.apiv3.html#File-Close">H5Fclose</a>(file_id); + } +</pre> </code> diff --git a/doc/html/review1a.html b/doc/html/review1a.html new file mode 100644 index 0000000..78a5a84 --- /dev/null +++ b/doc/html/review1a.html @@ -0,0 +1,252 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>Group Examples</title> + </head> + <body> + <center><h1>Group Examples</h1></center> + + <hr> + <h1>Background</h1> + + <p>Directories (or now <i>Groups</i>) are currently implemented as + a directed graph with a single entry point into the graph which + is the <i>Root Object</i>. The root object is usually a + group. All objects have at least one predecessor (the <i>Root + Object</i> always has the HDF5 file boot block as a + predecessor). The number of predecessors of a group is also + known as the <i>hard link count</i> or just <i>link count</i>. + Unlike Unix directories, HDF5 groups have no ".." entry since + any group can have multiple predecessors. Given the handle or + id of some object and returning a full name for that object + would be an expensive graph traversal. + + <p>A special optimization is that a file may contain a single + non-group object and no group(s). The object has one + predecessor which is the file boot block. However, once a root + group is created it never dissappears (although I suppose it + could if we wanted). + + <p>A special object called a <i>Symbolic Link</i> is simply a + name. Usually the name refers to some (other) object, but that + object need not exist. Symbolic links in HDF5 will have the + same semantics as symbolic links in Unix. + + <p>The symbol table graph contains "entries" for each name. An + entry contains the file address for the object header and + possibly certain messages cached from the object header. + + <p>The H5G package understands the notion of <i>opening</i> and object + which means that given the name of the object, a handle to the + object is returned (this isn't an API function). Objects can be + opened multiple times simultaneously through the same name or, + if the object has hard links, through other names. The name of + an object cannot be removed from a group if the object is opened + through that group (although the name can change within the + group). + + <p>Below the API, object attributes can be read without opening + the object; object attributes cannot change without first + opening that object. The one exception is that the contents of a + group can change without opening the group. + + <hr> + <h1>Building a hierarchy from a flat namespace</h1> + + <p>Assuming we have a flat name space (that is, the root object is + a group which contains names for all other objects in the file + and none of those objects are groups), then we can build a + hierarchy of groups that also refer to the objects. + + <p>The file initially contains `foo' `bar' `baz' in the root + group. We wish to add groups `grp1' and `grp2' so that `grp1' + contains objects `foo' and `baz' and `grp2' contains objects + `bar' and `baz' (so `baz' appears in both groups). + + <p>In either case below, one might want to move the flat objects + into some other group (like `flat') so their names don't + interfere with the rest of the hierarchy (or move the hierarchy + into a directory called `/hierarchy'). + + <h2>with symbolic links</h2> + + <p>Create group `grp1' and add symbolic links called `foo' whose + value is `/foo' and `baz' whose value is `/baz'. Similarly for + `grp2'. + + <p>Accessing `grp1/foo' involves searching the root group for + the name `grp1', then searching that group for `foo', then + searching the root directory for `foo'. Alternatively, one + could change working groups to the grp1 group and then ask for + `foo' which searches `grp1' for the name `foo', then searches + the root group for the name `foo'. + + <p>Deleting `/grp1/foo' deletes the symbolic link without + affecting the `/foo' object. Deleting `/foo' leaves the + `/grp1/foo' link dangling. + + <h2>with hard links</h2> + + <p>Creating the hierarchy is the same as with symbolic links. + + <p>Accessing `/grp1/foo' searches the root group for the name + `grp1', then searches that group for the name `foo'. If the + current working group is `/grp1' then we just search for the + name `foo'. + + <p>Deleting `/grp1/foo' leaves `/foo' and vice versa. + + <h2>the code</h2> + + <p>Depending on the eventual API... + + <code><pre> +H5Gcreate (file_id, "/grp1"); +H5Glink (file_id, H5G_HARD, "/foo", "/grp1/foo"); + </pre></code> + + or + + <code><pre> +group_id = H5Gcreate (root_id, "grp1"); +H5Glink (file_id, H5G_HARD, root_id, "foo", group_id, "foo"); +H5Gclose (group_id); + </pre></code> + + + <hr> + <h1>Building a flat namespace from a hierarchy</h1> + + <p>Similar to abvoe, but in this case we have to watch out that + we don't get two names which are the same: what happens to + `/grp1/baz' and `/grp2/baz'? If they really refer to the same + object then we just have `/baz', but if they point to two + different objects what happens? + + <p>The other thing to watch out for cycles in the graph when we + traverse it to build the flat namespace. + + <hr> + <h1>Listing the Group Contents</h1> + + <p>Two things to watch out for are that the group contents don't + appear to change in a manner which would confuse the + application, and that listing everything in a group is as + efficient as possible. + + <h2>Method A</h2> + + <p>Query the number of things in a group and then query each item + by index. A trivial implementation would be O(n*n) and wouldn't + protect the caller from changes to the directory which move + entries around and therefore change their indices. + + <code><pre> +n = H5GgetNumContents (group_id); +for (i=0; i<n; i++) { + H5GgetNameByIndex (group_id, i, ...); /*don't worry about args yet*/ +} + </pre></code> + + <h2>Method B</h2> + + <p>The API contains a single function that reads all information + from the specified group and returns that info through an array. + The caller is responsible for freeing the array allocated by the + query and the things to which it points. This also makes it + clear the the returned value is a snapshot of the group which + doesn't change if the group is modified. + + <code><pre> +n = H5Glist (file_id, "/grp1", info, ...); +for (i=0; i<n; i++) { + printf ("name = %s\n", info[i].name); + free (info[i].name); /*and maybe other fields too?*/ +} +free (info); + </pre></code> + + Notice that it would be difficult to expand the info struct since + its definition is part of the API. + + <h2>Method C</h2> + + <p>The caller asks for a snapshot of the group and then accesses + items in the snapshot through various query-by-index API + functions. When finished, the caller notifies the library that + it's done with the snapshot. The word "snapshot" makes it clear + that subsequent changes to the directory will not be reflected in + the shapshot_id. + + <code><pre> +snapshot_id = H5Gsnapshot (group_id); /*or perhaps group_name */ +n = H5GgetNumContents (snapshot_id); +for (i=0; i<n; i++) { + H5GgetNameByIndex (shapshot_id, i, ...); +} +H5Grelease (shapshot_id); + </pre></code> + + In fact, we could allow the user to leave off the H5Gsnapshot and + H5Grelease and use group_id in the H5GgetNumContents and + H5GgetNameByIndex so they can choose between Method A and Method + C. + + <hr> + <h1>An implementation of Method C</h1> + + <dl> + <dt><code>hid_t H5Gshapshot (hid_t group_id)</code> + <dd>Opens every object in the specified group and stores the + handles in an array managed by the library (linear-time + operation). Open object handles are essentialy symbol table + entries with a little extra info (symbol table entries cache + certain things about the object which are also found in the + object header). Because the objects are open (A) they cannot be + removed from the group, (B) querying the object returns the + latest info even if something else has that object open, (C) + if the object is renamed within the group then its name with + <code>H5GgetNameByIndex</code> is changed. Adding new entries + to a group doesn't affect the snapshot. + + <dt><code>char *H5GgetNameByIndex (hid_t shapshot_id, int + index)</code> + <dd>Uses the open object handle from entry <code>index</code> of + the snapshot array to get the object name. This is a + constant-time operation. The name is updated automatically if + the object is renamed within the group. + + <dt><code>H5Gget<whatever>ByIndex...()</code> + <dd>Uses the open object handle from entry <code>index</code>, + which is just a symbol table entry, and reads the appropriate + object header message(s) which might be cached in the symbol + table entry. This is a constant-time operation if cached, + linear in the number of messages if not cached. + + <dt><code>H5Grelease (hid_t snapshot_id)</code> + <dd>Closes each object refered to by the snapshot and then frees + the snapshot array. This is a linear-time operation. + </dl> + + <hr> + <h1>To return <code>char*</code> or some HDF5 string type.</h1> + + <p>In either case, the caller has to release resources associated + with the return value, calling free() or some HDF5 function. + + <p>Names in the current implementation of the H5G package don't + contain embedded null characters and are always null terminated. + + <p>Eventually the caller probably wants a <code>char*</code> so it + can pass it to some non-HDF5 function, does that require + strdup'ing the string again? Then the caller has to free() the + the char* <i>and</i> release the DHF5 string. + + <hr> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- Created: Fri Sep 26 12:03:20 EST 1997 --> +<!-- hhmts start --> +Last modified: Fri Oct 3 09:32:10 EST 1997 +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/storage.html b/doc/html/storage.html new file mode 100644 index 0000000..87ea54d --- /dev/null +++ b/doc/html/storage.html @@ -0,0 +1,274 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>Raw Data Storage in HDF5</title> + </head> + + <body> + <h1>Raw Data Storage in HDF5</h1> + + <p>This document describes the various ways that raw data is + stored in an HDF5 file and the object header messages which + contain the parameters for the storage. + + <p>Raw data storage has three components: the mapping from some + logical multi-dimensional element space to the linear address + space of a file, compression of the raw data on disk, and + striping of raw data across multiple files. These components + are orthogonal. + + <p>Some goals of the storage mechanism are to be able to + efficently store data which is: + + <dl> + <dt>Small + <dd>Small pieces of raw data can be treated as meta data and + stored in the object header. This will be achieved by storing + the raw data in the object header with message 0x0006. + Compression and striping are not supported in this case. + + <dt>Complete Large + <dd>The library should be able to store large arrays + contiguously in the file provided the user knows the final + array size a priori. The array can then be read/written in a + single I/O request. This is accomplished by describing the + storage with object header message 0x0005. Compression and + striping are not supported in this case. + + <dt>Sparse Large + <dd>A large sparse raw data array should be stored in a manner + that is space-efficient but one in which any element can still + be accessed in a reasonable amount of time. Implementation + details are below. + + <dt>Dynamic Size + <dd>One often doesn't have prior knowledge of the size of an + array. It would be nice to allow arrays to grow dynamically in + any dimension. It might also be nice to allow the array to + grow in the negative dimension directions if convenient to + implement. Implementation details are below. + + <dt>Subslab Access + <dd>Some multi-dimensional arrays are almost always accessed by + subslabs. For instance, a 2-d array of pixels might always be + accessed as smaller 1k-by-1k 2-d arrays always aligned on 1k + index values. We should be able to store the array in such a + way that striding though the entire array is not necessary. + Subslab access might also be useful with compression + algorithms where each storage slab can be compressed + independently of the others. Implementation details are below. + + <dt>Compressed + <dd>Various compression algorithms can be applied to the entire + array. We're not planning to support separate algorithms (or a + single algorithm with separate parameters) for each chunk + although it would be possible to implement that in a manner + similar to the way striping across files is + implemented. + + <dt>Striped Across Files + <dd>The array access functions should support arrays stored + discontiguously across a set of files. + </dl> + + <h1>Implementation of Indexed Storage</h1> + + <p>The Sparse Large, Dynamic Size, and Subslab Access methods + share so much code that they can be described with a single + message. The new Indexed Storage Message (<code>0x0008</code>) + will replace the old Chunked Object (<code>0x0009</code>) and + Sparse Object (<code>0x000A</code>) Messages. + + <p> + <center> + <table border cellpadding=4 width="60%"> + <caption align=bottom> + <b>The Format of the Indexed Storage Message</b> + </caption> + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4><br>Address of B-tree<br><br></td> + </tr> + <tr align=center> + <td>Number of Dimensions</td> + <td>Reserved</td> + <td>Reserved</td> + <td>Reserved</td> + </tr> + <tr align=center> + <td colspan=4>Reserved (4 bytes)</td> + </tr> + <tr align=center> + <td colspan=4>Alignment for Dimension 0 (4 bytes)</td> + </tr> + <tr align=center> + <td colspan=4>Alignment for Dimension 1 (4 bytes)</td> + </tr> + <tr align=center> + <td colspan=4>...</td> + </tr> + <tr align=center> + <td colspan=4>Alignment for Dimension N (4 bytes)</td> + </tr> + </table> + </center> + + <p>The alignment fields indicate the alignment in logical space to + use when allocating new storage areas on disk. For instance, + writing every other element of a 100-element one-dimensional + array (using one HDF5 I/O partial write operation per element) + that has unit storage alignment would result in 50 + single-element, discontiguous storage segments. However, using + an alignment of 25 would result in only four discontiguous + segments. The size of the message varies with the number of + dimensions. + + <p>A B-tree is used to point to the discontiguous portions of + storage which has been allocated for the object. All keys of a + particular B-tree are the same size and are a function of the + number of dimensions. It is therefore not possible to change the + dimensionality of an indexed storage array after its B-tree is + created. + + <p> + <center> + <table border cellpadding=4 width="60%"> + <caption align=bottom> + <b>The Format of a B-Tree Key</b> + </caption> + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4>External File Number or Zero (4 bytes)</td> + </tr> + <tr align=center> + <td colspan=4>Chunk Offset in Dimension 0 (4 bytes)</td> + </tr> + <tr align=center> + <td colspan=4>Chunk Offset in Dimension 1 (4 bytes)</td> + </tr> + <tr align=center> + <td colspan=4>...</td> + </tr> + <tr align=center> + <td colspan=4>Chunk Offset in Dimension N (4 bytes)</td> + </tr> + </table> + </center> + + <p>The keys within a B-tree obey an ordering based on the chunk + offsets. If the offsets in dimension-0 are equal, then + dimension-1 is used, etc. The External File Number field + contains a 1-origin offset into the External File List message + which contains the name of the external file in which that chunk + is stored. + + <h1>Implementation of Striping</h1> + + <p>The indexed storage will support arbitrary striping at the + chunk level; each chunk can be stored in any file. This is + accomplished by using the External File Number field of an + indexed storage B-tree key as a 1-origin offset into an External + File List Message (0x0009) which takes the form: + + <p> + <center> + <table border cellpadding=4 width="60%"> + <caption align=bottom> + <b>The Format of the External File List Message</b> + </caption> + <tr align=center> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align=center> + <td colspan=4><br>Name Heap Address<br><br></td> + </tr> + <tr align=center> + <td colspan=4>Number of Slots Allocated (4 bytes)</td> + </tr> + <tr align=center> + <td colspan=4>Number of File Names (4 bytes)</td> + </tr> + <tr align=center> + <td colspan=4>Byte Offset of Name 1 in Heap (4 bytes)</td> + </tr> + <tr align=center> + <td colspan=4>Byte Offset of Name 2 in Heap (4 bytes)</td> + </tr> + <tr align=center> + <td colspan=4>...</td> + </tr> + <tr align=center> + <td colspan=4><br>Unused Slot(s)<br><br></td> + </tr> + </table> + </center> + + <p>Each indexed storage array that has all or part of its data + stored in external files will contain a single external file + list message. The size of the messages is determined when the + message is created, but it may be possible to enlarge the + message on demand by moving it. At this time, it's not possible + for multiple arrays to share a single external file list + message. + + <dl> + <dt><code> + H5O_efl_t *H5O_efl_new (H5G_entry_t *object, intn + nslots_hint, intn heap_size_hint) + </code> + <dd>Adds a new, empty external file list message to an object + header and returns a pointer to that message. The message + acts as a cache for file descriptors of external files that + are open. + + <p><dt><code> + intn H5O_efl_index (H5O_efl_t *efl, const char *filename) + </code> + <dd>Gets the external file index number for a particular file name. + If the name isn't in the external file list then it's added to + the H5O_efl_t struct and immediately written to the object + header to which the external file list message belongs. Name + comparison is textual. Each name should be relative to the + directory which contains the HDF5 file. + + <p><dt><code> + H5F_low_t *H5O_efl_open (H5O_efl_t *efl, intn index, uintn mode) + </code> + <dd>Gets a low-level file descriptor for an external file. The + external file list caches file descriptors because we might + have many more external files than there are file descriptors + available to this process. The caller should not close this file. + + <p><dt><code> + herr_t H5O_efl_release (H5O_efl_t *efl) + </code> + <dd>Releases an external file list, closes all files + associated with that list, and if the list has been modified + since the call to <code>H5O_efl_new</code> flushes the message + to disk. + </dl> + + <hr> + <address><a href="mailto:robb@arborea.spizella.com">Robb Matzke</a></address> +<!-- Created: Fri Oct 3 09:52:32 EST 1997 --> +<!-- hhmts start --> +Last modified: Tue Nov 25 12:36:50 EST 1997 +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/study.html b/doc/html/study.html new file mode 100644 index 0000000..f9e192d --- /dev/null +++ b/doc/html/study.html @@ -0,0 +1,172 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>Testing the chunked layout of HDF5</title> + </head> + + <body> + <h1>Testing the chunked layout of HDF5</h1> + + <p>This is the results of studying the chunked layout policy in + HDF5. A 1000 by 1000 array of integers was written to a file + dataset extending the dataset with each write to create, in the + end, a 5000 by 5000 array of 4-byte integers for a total data + storage size of 100 million bytes. + + <p> + <center> + <img alt="Order that data was written" src="study_p1.gif"> + <br><b>Fig 1: Write-order of Output Blocks</b> + </center> + + <p>After the array was written, it was read back in blocks that + were 500 by 500 bytes in row major order (that is, the top-left + quadrant of output block one, then the top-right quadrant of + output block one, then the top-left quadrant of output block 2, + etc.). + + <p>I tried to answer two questions: + <ul> + <li>How does the storage overhead change as the chunk size + changes? + <li>What does the disk seek pattern look like as the chunk size + changes? + </ul> + + <p>I started with chunk sizes that were multiples of the read + block size or k*(500, 500). + + <p> + <center> + <table border> + <caption align=bottom> + <b>Table 1: Total File Overhead</b> + </caption> + <tr> + <th>Chunk Size (elements)</th> + <th>Meta Data Overhead (ppm)</th> + <th>Raw Data Overhead (ppm)</th> + </tr> + + <tr align=center> + <td>500 by 500</td> + <td>85.84</td> + <td>0.00</td> + </tr> + <tr align=center> + <td>1000 by 1000</td> + <td>23.08</td> + <td>0.00</td> + </tr> + <tr align=center> + <td>5000 by 1000</td> + <td>23.08</td> + <td>0.00</td> + </tr> + <tr align=center> + <td>250 by 250</td> + <td>253.30</td> + <td>0.00</td> + </tr> + <tr align=center> + <td>499 by 499</td> + <td>85.84</td> + <td>205164.84</td> + </tr> + </table> + </center> + + <hr> + <p> + <center> + <img alt="500x500" src="study_500x500.gif"> + <br><b>Fig 2: Chunk size is 500x500</b> + </center> + + <p>The first half of Figure 2 shows output to the file while the + second half shows input. Each dot represents a file-level I/O + request and the lines that connect the dots are for visual + clarity. The size of the request is not indicated in the + graph. The output block size is four times the chunk size which + results in four file-level write requests per block for a total + of 100 requests. Since file space for the chunks was allocated + in output order, and the input block size is 1/4 the output + block size, the input shows a staircase effect. Each input + request results in one file-level read request. The downward + spike at about the 60-millionth byte is probably the result of a + cache miss for the B-tree and the downward spike at the end is + probably a cache flush or file boot block update. + + <hr> + <p> + <center> + <img alt="1000x1000" src="study_1000x1000.gif"> + <br><b>Fig 2: Chunk size is 1000x1000</b> + </center> + + <p>In this test I increased the chunk size to match the output + chunk size and one can see from the first half of the graph that + 25 file-level write requests were issued, one for each output + block. The read half of the test shows that four times the + amount of data was read as written. This results from the fact + that HDF5 must read the entire chunk for any request that falls + within that chunk, which is done because (1) if the data is + compressed the entire chunk must be decompressed, and (2) the + library assumes that a chunk size was chosen to optimize disk + performance. + + <hr> + <p> + <center> + <img alt="5000x1000" src="study_5000x1000.gif"> + <br><b>Fig 3: Chunk size is 5000x1000</b> + </center> + + <p>Increasing the chunk size further results in even worse + performance since both the read and write halves of the test are + re-reading and re-writing vast amounts of data. This proves + that one should be careful that chunk sizes are not much larger + than the typical partial I/O request. + + <hr> + <p> + <center> + <img alt="250x250" src="study_250x250.gif"> + <br><b>Fig 4: Chunk size is 250x250</b> + </center> + + <p>If the chunk size is decreased then the amount of data + transfered between the disk and library is optimal for no + caching, but the amount of meta data required to describe the + chunk locations increases to 250 parts per million. One can + also see that the final downward spike contains more file-level + write requests as the meta data is flushed to disk just before + the file is closed. + + <hr> + <p> + <center> + <img alt="499x499" src="study_499x499.gif"> + <br><b>Fig 4: Chunk size is 499x499</b> + </center> + + <p>This test shows the result of choosing a chunk size which is + close to the I/O block size. Because the total size of the + array isn't a multiple of the chunk size, the library allocates + an extra zone of chunks around the top and right edges of the + array which are only partially filled. This results in + 20,516,484 extra bytes of storage, a 20% increase in the total + raw data storage size. But the amount of meta data overhead is + the same as for the 500 by 500 test. In addition, the mismatch + causes entire chunks to be read in order to update a few + elements along the edge or the chunk which results in a 3.6-fold + increase in the amount of data transfered. + + <hr> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- Created: Fri Jan 30 21:04:49 EST 1998 --> +<!-- hhmts start --> +Last modified: Fri Jan 30 23:51:31 EST 1998 +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/study_1000x1000.gif b/doc/html/study_1000x1000.gif Binary files differnew file mode 100644 index 0000000..b7d5a83 --- /dev/null +++ b/doc/html/study_1000x1000.gif diff --git a/doc/html/study_250x250.gif b/doc/html/study_250x250.gif Binary files differnew file mode 100644 index 0000000..fe35f39 --- /dev/null +++ b/doc/html/study_250x250.gif diff --git a/doc/html/study_499x499.gif b/doc/html/study_499x499.gif Binary files differnew file mode 100644 index 0000000..0d2038b --- /dev/null +++ b/doc/html/study_499x499.gif diff --git a/doc/html/study_5000x1000.gif b/doc/html/study_5000x1000.gif Binary files differnew file mode 100644 index 0000000..0f3c290 --- /dev/null +++ b/doc/html/study_5000x1000.gif diff --git a/doc/html/study_500x500.gif b/doc/html/study_500x500.gif Binary files differnew file mode 100644 index 0000000..38dd7d6 --- /dev/null +++ b/doc/html/study_500x500.gif diff --git a/doc/html/study_p1.gif b/doc/html/study_p1.gif Binary files differnew file mode 100644 index 0000000..938d133 --- /dev/null +++ b/doc/html/study_p1.gif diff --git a/doc/html/study_p1.obj b/doc/html/study_p1.obj new file mode 100644 index 0000000..6fbf583 --- /dev/null +++ b/doc/html/study_p1.obj @@ -0,0 +1,113 @@ +%TGIF 3.0-p5 +state(0,33,100,0,0,0,16,1,9,1,1,0,0,3,7,1,1,'Helvetica',0,24,0,0,0,10,0,0,1,1,0,16,0,0,1,1,1,0,1088,1408,0,0,2880). +% +% @(#)$Header$ +% %W% +% +unit("1 pixel/pixel"). +page(1,"",1). +box('black',64,64,384,384,0,1,1,22,0,0,0,0,0,'1',[ +]). +poly('black',2,[ + 128,64,128,384],0,1,1,23,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 192,64,192,384],0,1,1,24,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 256,64,256,384],0,1,1,25,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 320,64,320,384],0,1,1,26,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 64,128,384,128],0,1,1,27,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 64,192,384,192],0,1,1,28,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 64,256,384,256],0,1,1,29,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 64,320,384,320],0,1,1,30,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +text('black',96,80,'Courier',0,17,1,1,0,1,7,14,37,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "1"]). +text('black',160,80,'Courier',0,17,1,1,0,1,7,14,39,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "2"]). +text('black',224,80,'Courier',0,17,1,1,0,1,7,14,41,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "3"]). +text('black',288,80,'Courier',0,17,1,1,0,1,7,14,43,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "4"]). +text('black',352,80,'Courier',0,17,1,1,0,1,7,14,47,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "5"]). +text('black',96,144,'Courier',0,17,1,1,0,1,7,14,51,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "6"]). +text('black',160,144,'Courier',0,17,1,1,0,1,7,14,53,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "7"]). +text('black',224,144,'Courier',0,17,1,1,0,1,7,14,55,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "8"]). +text('black',288,144,'Courier',0,17,1,1,0,1,7,14,57,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "9"]). +text('black',352,144,'Courier',0,17,1,1,0,1,14,14,59,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "10"]). +text('black',96,208,'Courier',0,17,1,1,0,1,14,14,61,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "11"]). +text('black',160,208,'Courier',0,17,1,1,0,1,14,14,63,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "12"]). +text('black',224,208,'Courier',0,17,1,1,0,1,14,14,65,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "13"]). +text('black',288,208,'Courier',0,17,1,1,0,1,14,14,67,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "14"]). +text('black',352,208,'Courier',0,17,1,1,0,1,14,14,71,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "15"]). +text('black',96,272,'Courier',0,17,1,1,0,1,14,14,75,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "16"]). +text('black',160,272,'Courier',0,17,1,1,0,1,14,14,77,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "17"]). +text('black',224,272,'Courier',0,17,1,1,0,1,14,14,79,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "18"]). +text('black',288,272,'Courier',0,17,1,1,0,1,14,14,81,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "19"]). +text('black',352,272,'Courier',0,17,1,1,0,1,14,14,83,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "20"]). +text('black',96,336,'Courier',0,17,1,1,0,1,14,14,87,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "21"]). +text('black',160,336,'Courier',0,17,1,1,0,1,14,14,89,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "22"]). +text('black',224,336,'Courier',0,17,1,1,0,1,14,14,91,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "23"]). +text('black',288,336,'Courier',0,17,1,1,0,1,14,14,93,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "24"]). +text('black',352,336,'Courier',0,17,1,1,0,1,14,14,95,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "25"]). +poly('black',2,[ + 416,64,416,384],3,1,1,100,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 64,416,384,416],3,1,1,101,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +text('black',390,228,'Courier',0,17,1,0,0,1,14,35,102,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,1,0,[ + 390,228,390,228,425,242,0,-1000,1000,0,34,18,389,227,426,243],[ + "5,000"]). +text('black',224,432,'Courier',0,17,1,1,0,1,35,14,116,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "5,000"]). +text('black',160,512,'Courier',0,17,1,0,0,1,105,14,131,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "= 1,000 x 1,000"]). +box('black',80,480,144,544,7,1,1,134,0,0,0,0,0,'1',[ +]). +text('black',224,16,'Helvetica',0,24,1,1,0,1,296,29,144,0,24,5,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Order that data was written"]). +box('black',32,0,464,576,0,1,1,149,0,0,0,0,0,'1',[ +]). diff --git a/doc/html/symtab b/doc/html/symtab new file mode 100644 index 0000000..a657729 --- /dev/null +++ b/doc/html/symtab @@ -0,0 +1,313 @@ +A number of issues involving caching of object header messages in +symbol table entries must be resolved. + +What is the motivation for these changes? + + If we make objects completely independent of object name it allows + us to refer to one object by multiple names (a concept called hard + links in Unix file systems), which in turn provides an easy way to + share data between datasets. + + Every object in an HDF5 file has a unique, constant object header + address which serves as a handle (or OID) for the object. The + object header contains messages which describe the object. + + HDF5 allows some of the object header messages to be cached in + symbol table entries so that the object header doesn't have to be + read from disk. For instance, an entry for a directory caches the + directory disk addresses required to access that directory, so the + object header for that directory is seldom read. + + If an object has multiple names (that is, a link count greater than + one), then it has multiple symbol table entries which point to it. + All symbol table entries must agree on header messages. The + current mechanism is to turn off the caching of header messages in + symbol table entries when the header link count is more than one, + and to allow caching once the link count returns to one. + + However, in the current implementation, a package is allowed to + copy a symbol table entry and use it as a private cache for the + object header. This doesn't work for a number of reasons (all but + one require a `delete symbol entry' operation). + + 1. If two packages hold copies of the same symbol table entry, + they don't notify each other of changes to the symbol table + entry. Eventually, one package reads a cached message and + gets the wrong value because the other package changed the + message in the object header. + + 2. If one package holds a copy of the symbol table entry and + some other part of HDF5 removes the object and replaces it + with some other object, then the original package will + continue to access the non-existent object using the new + object header. + + 3. If one package holds a copy of the symbol table entry and + some other part of HDF5 (re)moves the directory which + contains the object, then the package will be unable to + update the symbol table entry with the new cached + data. Packages that refer to the object by the new name will + use old cached data. + + +The basic problem is that there may be multiple copies of the object +symbol table entry floating around in the code when there should +really be at most one per hard link. + + Level 0: A copy may exist on disk as part of a symbol table node, which + is a small 1d array of symbol table entries. + + Level 1: A copy may be cached in memory as part of a symbol table node + in the H5Gnode.c file by the H5AC layer. + + Level 2a: Another package may be holding a copy so it can perform + fast lookup of any header messages that might be cached in + the symbol table entry. It can't point directly to the + cached symbol table node because that node can dissappear + at any time. + + Level 2b: Packages may hold more than one copy of a symbol table + entry. For instance, if H5D_open() is called twice for + the same name, then two copies of the symbol table entry + for the dataset exist in the H5D package. + +How can level 2a and 2b be combined? + + If package data structures contained pointers to symbol table + entries instead of copies of symbol table entries and if H5G + allocated one symbol table entry per hard link, then it's trivial + for Level 2a and 2b to benefit from one another's actions since + they share the same cache. + +How does this work conceptually? + + Level 2a and 2b must notify Level 1 of their intent to use (or stop + using) a symbol table entry to access an object header. The + notification of the intent to access an object header is called + `opening' the object and releasing the access is `closing' the + object. + + Opening an object requires an object name which is used to locate + the symbol table entry to use for caching of object header + messages. The return value is a handle for the object. Figure 1 + shows the state after Dataset1 opens Object with a name that maps + through Entry1. The open request created a copy of Entry1 called + Shadow1 which exists even if SymNode1 is preempted from the H5AC + layer. + + ______ + Object / \ + SymNode1 +--------+ | + +--------+ _____\ | Header | | + | | / / +--------+ | + +--------+ +---------+ \______/ + | Entry1 | | Shadow1 | /____ + +--------+ +---------+ \ \ + : : \ + +--------+ +----------+ + | Dataset1 | + +----------+ + FIGURE 1 + + + + The SymNode1 can appear and disappear from the H5AC layer at any + time without affecting the Object Header data cached in the Shadow. + The rules are: + + * If the SymNode1 is present and is about to disappear and the + Shadow1 dirty bit is set, then Shadow1 is copied over Entry1, the + Entry1 dirty bit is set, and the Shadow1 dirty bit is cleared. + + * If something requests a copy of Entry1 (for a read-only peek + request), and Shadow1 exists, then a copy (not pointer) of Shadow1 + is returned instead. + + * Entry1 cannot be deleted while Shadow1 exists. + + * Entry1 cannot change directly if Shadow1 exists since this means + that some other package has opened the object and may be modifying + it. I haven't decided if it's useful to ever change Entry1 + directly (except of course within the H5G layer itself). + + * Shadow1 is created when Dataset1 `opens' the object through + Entry1. Dataset1 is given a pointer to Shadow1 and Shadow1's + reference count is incremented. + + * When Dataset1 `closes' the Object the Shadow1 reference count is + decremented. When the reference count reaches zero, if the + Shadow1 dirty bit is set, then Shadow1's contents are copied to + Entry1, and the Entry1 dirty bit is set. Shadow1 is then deleted + if its reference count is zero. This may require reading SymNode1 + back into the H5AC layer. + +What happens when another Dataset opens the Object through Entry1? + + If the current state is represented by the top part of Figure 2, + then Dataset2 will be given a pointer to Shadow1 and the Shadow1 + reference count will be incremented to two. The Object header link + count remains at one so Object Header messages continue to be cached + by Shadow1. Dataset1 and Dataset2 benefit from one another + actions. The resulting state is represented by Figure 2. + + _____ + SymNode1 Object / \ + +--------+ _____\ +--------+ | + | | / / | Header | | + +--------+ +---------+ +--------+ | + | Entry1 | | Shadow1 | /____ \_____/ + +--------+ +---------+ \ \ + : : _ \ + +--------+ |\ +----------+ + \ | Dataset1 | + \________ +----------+ + \ \ + +----------+ | + | Dataset2 | |- New Dataset + +----------+ | + / + FIGURE 2 + + +What happens when the link count for Object increases while Dataset +has the Object open? + + SymNode2 + +--------+ + SymNode1 Object | | + +--------+ ____\ +--------+ /______ +--------+ + | | / / | header | \ `| Entry2 | + +--------+ +---------+ +--------+ +--------+ + | Entry1 | | Shadow1 | /____ : : + +--------+ +---------+ \ \ +--------+ + : : \ + +--------+ +----------+ \________________/ + | Dataset1 | | + +----------+ New Link + + FIGURE 3 + + The current state is represented by the left part of Figure 3. To + create a new link the Object Header had to be located by traversing + through Entry1/Shadow1. On the way through, the Entry1/Shadow1 + cache is invalidated and the Object Header link count is + incremented. Entry2 is then added to SymNode2. + + Since the Object Header link count is greater than one, Object + header data will not be cached in Entry1/Shadow1. + + If the initial state had been all of Figure 3 and a third link is + being added and Object is open by Entry1 and Entry2, then creation + of the third link will invalidate the cache in Entry1 or Entry2. It + doesn't matter which since both caches are already invalidated + anyway. + +What happens if another Dataset opens the same object by another name? + + If the current state is represented by Figure 3, then a Shadow2 is + created and associated with Entry2. However, since the Object + Header link count is more than one, nothing gets cached in Shadow2 + (or Shadow1). + +What happens if the link count decreases? + + If the current state is represented by all of Figure 3 then it isn't + possible to delete Entry1 because the object is currently open + through that entry. Therefore, the link count must have + decreased because Entry2 was removed. + + As Dataset1 reads/writes messages in the Object header they will + begin to be cached in Shadow1 again because the Object header link + count is one. + +What happens if the object is removed while it's open? + + That operation is not allowed. + +What happens if the directory containing the object is deleted? + + That operation is not allowed since deleting the directory requires + that the directory be empty. The directory cannot be emptied + because the open object cannot be removed from the directory. + +What happens if the object is moved? + + Moving an object is a process consisting of creating a new + hard-link with the new name and then deleting the old name. + This will fail if the object is open. + +What happens if the directory containing the entry is moved? + + The entry and the shadow still exist and are associated with one + another. + +What if a file is flushed or closed when objects are open? + + Flushing a symbol table with open objects writes correct information + to the file since Shadow is copied to Entry before the table is + flushed. + + Closing a file with open objects will create a valid file but will + return failure. + +How is the Shadow associated with the Entry? + + A symbol table is composed of one or more symbol nodes. A node is a + small 1-d array of symbol table entries. The entries can move + around within a node and from node-to-node as entries are added or + removed from the symbol table and nodes can move around within a + symbol table, being created and destroyed as necessary. + + Since a symbol table has an object header with a unique and constant + file offset, and since H5G contains code to efficiently locate a + symbol table entry given it's name, we use these two values as a key + within a shadow to associate the shadow with the symbol table + entry. + + struct H5G_shadow_t { + haddr_t stab_addr; /*symbol table header address*/ + char *name; /*entry name wrt symbol table*/ + hbool_t dirty; /*out-of-date wrt stab entry?*/ + H5G_entry_t ent; /*my copy of stab entry */ + H5G_entry_t *main; /*the level 1 entry or null */ + H5G_shadow_t *next, *prev; /*other shadows for this stab*/ + }; + + The set of shadows will be organized in a hash table of linked + lists. Each linked list will contain the shadows associated with a + particular symbol table header address and the list will be sorted + lexicographically. + + Also, each Entry will have a pointer to the corresponding Shadow or + null if there is no shadow. + + When a symbol table node is loaded into the main cache, we look up + the linked list of shadows in the shadow hash table based on the + address of the symbol table object header. We then traverse that + list matching shadows with symbol table entries. + + We assume that opening/closing objects will be a relatively + infrequent event compared with loading/flushing symbol table + nodes. Therefore, if we keep the linked list of shadows sorted it + costs O(N) to open and close objects where N is the number of open + objects in that symbol table (instead of O(1)) but it costs only + O(N) to load a symbol table node (instead of O(N^2)). + +What about the root symbol entry? + + Level 1 storage for the root symbol entry is always available since + it's stored in the hdf5_file_t struct instead of a symbol table + node. However, the contents of that entry can move from the file + handle to a symbol table node by H5G_mkroot(). Therefore, if the + root object is opened, we keep a shadow entry for it whose + `stab_addr' field is zero and whose `name' is null. + + For this reason, the root object should always be read through the + H5G interface. + +One more key invariant: The H5O_STAB message in a symbol table header +never changes. This allows symbol table entries to cache the H5O_STAB +message for the symbol table to which it points without worrying about +whether the cache will ever be invalidated. + + diff --git a/doc/html/tracing.html b/doc/html/tracing.html new file mode 100644 index 0000000..18ef556 --- /dev/null +++ b/doc/html/tracing.html @@ -0,0 +1,192 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>API Tracing</title> + </head> + + <body> + <h1>API Tracing</h1> + + <h2>Introduction</h2> + + <p>The HDF5 library is now able to trace API calls by printing the + function name, the argument names and their values, and the + return value. Some people like to see lots of output during + program execution instead of using a good symbolic debugger, and + this feature is intended for their consumption. For example, + the output from <code>h5ls foo</code> after turning on tracing, + includes: + + <p> + <center> + <table border align=center width="100%"> + <caption align=top><b>Sample Output</b></caption> + <tr> + <td> + <code><pre> +H5Tcopy(type=184549388) = 184549419 (type); +H5Tcopy(type=184549392) = 184549424 (type); +H5Tlock(type=184549424) = SUCCEED; +H5Tcopy(type=184549393) = 184549425 (type); +H5Tlock(type=184549425) = SUCCEED; +H5Fopen(filename="foo", flags=0, access=H5P_DEFAULT) = FAIL; +HDF5-DIAG: Error detected in thread 0. Back trace follows. + #000: H5F.c line 1245 in H5Fopen(): unable to open file + major(04): File interface + minor(10): Unable to open file + #001: H5F.c line 846 in H5F_open(): file does not exist + major(04): File interface + minor(10): Unable to open file + </pre></code> + </td> + </tr> + </table> + </center> + + <h2>Configuation</h2> + + <p>This all happens with some magic in the configuration script, + the makefiles, and macros. First, from the end-user point of + view, the library must be configured with the + <code>--enable-tracing</code> switch. This causes the library to + include the support necessary for API tracing. + + <p> + <center> + <table border align=center width="100%"> + <caption align=top><b>Configuration</b></caption> + <tr> + <td> + <code><pre> +$ make distclean +$ sh configure --enable-tracing +$ make + </pre></code> + </td> + </tr> + </table> + </center> + + <h2>Execution</h2> + + <p>In order to actually get tracing output one must turn tracing + on and specify a file descriptor where the tracing output should + be written. This is done by assigning a file descriptor number + to the <code>HDF5_TRACE</code> environment variable. + + <p> + <center> + <table border align=center width="100%"> + <caption align=top><b>Execution Examples</b></caption> + <tr> + <td>To display the trace on the standard error stream: + <code><pre> +$ export HDF5_TRACE=2 +$ a.out + </pre></code> + </td> + </tr> + <tr> + <td>To send the trace to a file: + <code><pre> +$ export HDF5_TRACE=255 +$ a.out 255>trace-output + </pre></code> + </td> + </tr> + </table> + </center> + + <h2>Performance</h2> + + <p>If the library was not configured for tracing then there is no + unnecessary overhead since all tracing code is + excluded. + + <p>However, if tracing is enabled but not used there is a + small penalty. First, code size is larger because of extra + statically-declared character strings used to store argument + types and names and extra auto variable pointer in each + function. Also, execution is slower because each function sets + and tests a local variable and each API function calls the + <code>H5_trace()</code> function. + + <p>If tracing is enabled and turned on then the penalties from the + previous paragraph apply plus the time required to format each + line of tracing information. There is also an extra call to + H5_trace() for each API function to print the return value. + + <h2>Safety</h2> + + <p>The tracing mechanism is invoked for each API function before + arguments are checked for validity. If bad arguments are passed + to an API function it could result in a segmentation fault. + However, the tracing output is line-buffered so all previous + output will appear. + + <h2>Completeness</h2> + + <p>There are two API functions that don't participate in + tracing. They are <code>H5Eprint()</code> and + <code>H5Eprint_cb()</code> because their participation would + mess up output during automatic error reporting. + + <p>On the other hand, a number of API functions are called during + library initialization and they print tracing information. + + <h2>Implementation</h2> + + <p>For those interested in the implementation here is a + description. Each API function should have a call to one of the + <code>H5TRACE()</code> macros immediately after the + <code>FUNC_ENTER()</code> macro. The first argument is the + return type encoded as a string. The second argument is the + types of all the function arguments encoded as a string. The + remaining arguments are the function arguments. This macro was + designed to be as terse and unobtrousive as possible. + + <p>In order to keep the <code>H5TRACE()</code> calls synchronized + with the source code we've written a perl script which gets + called automatically just before Makefile dependencies are + calculated for the file. However, this only works when one is + using GNU make. To reinstrument the tracing explicitly, invoke + the <code>trace</code> program from the hdf5 bin directory with + the names of the source files that need to be updated. If any + file needs to be modified then a backup is created by appending + a tilde to the file name. + + <p> + <center> + <table border align=center width="100%"> + <caption align=top><b>Explicit Instrumentation</b></caption> + <tr> + <td> + <code><pre> +$ ../bin/trace *.c +H5E.c: in function `H5Ewalk_cb': +H5E.c:336: warning: trace info was not inserted + </pre></code> + </td> + </tr> + </table> + </center> + + <p>Note: The warning message is the result of a comment of the + form <code>/*NO TRACE*/</code> somewhere in the function + body. Tracing information will not be updated or inserted if + such a comment exists. + + <p>Error messages have the same format as a compiler so that they + can be parsed from program development environments like + Emacs. Any function which generates an error will not be + modified. + + + <hr> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- Created: Wed Jun 17 12:29:12 EDT 1998 --> +<!-- hhmts start --> +Last modified: Wed Jun 17 15:45:50 EDT 1998 +<!-- hhmts end --> + </body> +</html> diff --git a/doc/html/version.gif b/doc/html/version.gif Binary files differnew file mode 100644 index 0000000..41d4401 --- /dev/null +++ b/doc/html/version.gif diff --git a/doc/html/version.obj b/doc/html/version.obj new file mode 100644 index 0000000..96b5b7f --- /dev/null +++ b/doc/html/version.obj @@ -0,0 +1,96 @@ +%TGIF 3.0-p5 +state(0,33,100,0,0,0,8,1,9,1,1,0,2,1,0,1,0,'Courier',0,17,0,0,0,10,0,0,1,1,0,16,0,0,1,1,1,0,1088,1408,0,0,2880). +% +% @(#)$Header$ +% %W% +% +unit("1 pixel/pixel"). +page(1,"",1). +poly('black',2,[ + 128,128,128,448],0,3,1,0,0,0,0,0,12,5,0,0,0,'3','12','5', + "0",[ +]). +poly('black',2,[ + 128,128,128,64],0,3,1,1,0,0,2,0,12,5,0,0,0,'3','12','5', + "0",[ +]). +poly('black',2,[ + 128,448,128,512],0,3,1,4,0,0,2,0,12,5,0,0,0,'3','12','5', + "0",[ +]). +text('black',144,112,'Courier',0,17,1,0,0,1,42,14,22,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "1.3.30"]). +text('black',144,144,'Courier',0,17,1,0,0,1,42,14,30,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "1.3.31"]). +text('black',144,176,'Courier',0,17,1,0,0,1,42,14,32,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "1.3.32"]). +poly('black',2,[ + 256,208,256,448],0,3,1,34,0,0,0,0,12,5,0,0,0,'3','12','5', + "0",[ +]). +poly('black',2,[ + 256,448,256,512],0,3,1,36,0,0,2,0,12,5,0,0,0,'3','12','5', + "0",[ +]). +poly('black',2,[ + 128,192,256,208],1,1,1,37,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +text('black',144,224,'Courier',0,17,1,0,0,1,42,14,41,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "1.3.33"]). +text('black',144,256,'Courier',0,17,1,0,0,1,42,14,43,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "1.3.34"]). +text('black',272,224,'Courier',0,17,1,0,0,1,35,14,45,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "1.5.0"]). +text('black',272,256,'Courier',0,17,1,0,0,1,35,14,47,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "1.5.1"]). +text('black',272,288,'Courier',0,17,1,0,0,1,35,14,49,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "1.5.2"]). +text('black',272,320,'Courier',0,17,1,0,0,1,35,14,51,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "1.5.3"]). +text('black',144,288,'Courier',0,17,1,0,0,1,42,14,53,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "1.3.35"]). +text('black',144,320,'Courier',0,17,1,0,0,1,35,14,57,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "1.4.0"]). +text('black',144,368,'Courier',0,17,1,0,0,1,35,14,59,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "1.4.1"]). +text('black',272,192,'Helvetica',0,17,1,0,0,1,144,15,67,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "New development branch"]). +text('black',144,64,'Helvetica',0,17,1,0,0,1,163,15,69,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Original development branch"]). +text('black',16,208,'Helvetica',0,17,2,0,0,1,87,30,71,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Feature Freeze", + "at this point."]). +text('black',16,320,'Helvetica',0,17,2,0,0,1,84,30,73,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Public Release", + "at this point."]). +poly('black',2,[ + 104,208,128,208],1,1,1,77,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 104,320,128,320],1,1,1,78,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +poly('black',2,[ + 256,336,128,352],1,1,1,79,0,0,0,0,8,3,0,0,0,'1','8','3', + "0",[ +]). +text('black',320,368,'Helvetica',0,17,3,0,0,1,137,45,82,0,12,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "Merge a bug fix from the", + "development branch to", + "the release branch."]). +box('black',312,368,464,416,0,1,1,87,0,0,0,0,0,'1',[ +]). +poly('black',4,[ + 312,392,240,384,296,344,232,344],1,1,1,90,1,0,0,0,8,3,0,0,0,'1','8','3', + "6",[ +]). +box('black',8,208,104,240,0,1,1,95,0,0,0,0,0,'1',[ +]). +box('black',8,320,104,352,0,1,1,98,0,0,0,0,0,'1',[ +]). +text('black',144,408,'Courier',0,17,1,0,0,1,35,14,102,0,11,3,0,0,0,0,0,2,0,0,0,0,"",0,0,0,[ + "1.4.2"]). +box('black',0,40,480,528,0,1,1,104,0,0,0,0,0,'1',[ +]). |
