diff options
| -rw-r--r-- | doc/html/RM_H5RA.html | 370 | ||||
| -rw-r--r-- | doc/html/Ragged.html | 248 |
2 files changed, 0 insertions, 618 deletions
diff --git a/doc/html/RM_H5RA.html b/doc/html/RM_H5RA.html deleted file mode 100644 index 28e195c..0000000 --- a/doc/html/RM_H5RA.html +++ /dev/null @@ -1,370 +0,0 @@ -<html> -<head><title> -HDF5/H5RA Experimental API Specification -</title></head> - -<body bgcolor="#FFFFFF"> - - -<hr> -<center> -<table border=0 width=98%> -<tr><td valign=top align=left> -<a href="H5.intro.html">Introduction to HDF5</a> <br> -<a href="H5.user.html">HDF5 User Guide</a> <br> -<a href="index.html">Other HDF5 documents and links</a> <br> -<!-- -<a href="Glossary.html">Glossary</a><br> ---> -</td> -<td valign=top align=right> -And in this document, the -<a href="RM_H5Front.html">HDF5 Reference Manual</a> -<br> -<a href="RM_H5.html">H5</a> -<a href="RM_H5A.html">H5A</a> -<a href="RM_H5D.html">H5D</a> -<a href="RM_H5E.html">H5E</a> -<a href="RM_H5F.html">H5F</a> -<a href="RM_H5G.html">H5G</a> -<a href="RM_H5I.html">H5I</a> -<a href="RM_H5P.html">H5P</a> -<br> -<a href="RM_H5R.html">H5R</a> -H5RA -<a href="RM_H5S.html">H5S</a> -<a href="RM_H5T.html">H5T</a> -<a href="RM_H5Z.html">H5Z</a> -<a href="Tools.html">Tools</a> -<a href="PredefDTypes.html">Datatypes</a> -</td></tr> -</table> -</center> -<hr> - - -<center> -<h1>H5RA: Ragged Array Interface</h1> -</center> - -<h2>Ragged Array API Functions</h2> -<table border=1> -<tr><th align=left> -<font color=red> -The H5RA Interface is strictly experimental at this time; -the interface may change dramatically or support for ragged arrays -may be unavailable in future in releases. As a result, future releases -may be unable to retrieve data stored with this interface. -<p><center>Use these functions at your own risk!<br> -Do not create any archives using this interface!</center> -</font> -</th></tr> -</table> -<p> -These functions enable the user to store and retrieve data in ragged arrays. - -<table border=0> -<tr><td valign=top> -<ul> - <li><a href="#Ragged-Create">H5RAcreate</a> -</ul> -</td><td> </td><td valign=top> -<ul> - <li><a href="#Ragged-Open">H5RAopen</a> - <li><a href="#Ragged-Close">H5RAclose</a> -</ul> -</td><td> </td><td valign=top> -<ul> - <li><a href="#Ragged-Write">H5RAwrite</a> - <li><a href="#Ragged-Read">H5RAread</a> -</ul> -</td></tr> -</table> - -<p> -This version of the Ragged Array interface implements a -two-dimensional array where each row of the array is a different length. -It is intended for applications where the distribution of row lengths -is such that most rows are near an average length with only a few rows -that are significantly shorter or longer. The raw data is split among -two datasets, <code>raw</code> and <code>over</code>: the <code>raw</code> -dataset is a two-dimensional chunked dataset whose width is large enough -to hold most of the rows while the <code>over</code> dataset is a heap -that stores the ends of rows that overflow the first dataset. -A third dataset, called <code>meta</code>, contains one record for each -row and describes what elements, if any, overflow the <code>raw</code> -dataset and where they are stored in the <code>over</code> dataset. -All three datasets are contained in a single group whose name is the -name of the ragged array. -<p> - - - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Ragged-Create">H5RAcreate</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t</em> <code>H5RAcreate</code>(<em>hid_t</em> <code>loc_id</code>, - <em>const char *</em><code>name</code>, - <em>hid_t</em> <code>type_id</code>, - <em>hid_t</em> <code>plist_id</code> - ) -<dt><strong>Purpose:</strong> - <dd>Creates a ragged array. -<dt><strong>Description:</strong> - <dd><code>H5RAcreate</code> creates a new ragged array with the - name specified in <code>name</code>. A ragged array is - implemented as a group containing three datasets. - The dataset <code>raw</code> is a fixed width dataset - which will hold the majority of the data. - The dataset <code>over</code> is a one dimensional heap - which will hold the end of rows which are too long to fit - in <code>raw</code> - Finally, the <code>meta</code> dataset contains information - about the <code>over</code> array. All elements of the - ragged array are stored with the same data type. - <p> - The property list <code>plist_id</code> should contain - information about chunking. The chunk width will determine - the width of the <code>raw</code> dataset while the chunk - length should be such that the total chunk size is - reasonably large since I/O will be performed in units - of chunks). If the <code>plist_id</code> does not have - a chunk size defined (e.g., <code>H5P_DEFAULT</code>) - then this function will fail. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>loc_id</code> - <dd>Location identifier of the dataset. - <dt><em>const char *</em><code>name</code> - <dd>The assigned name of the data set to be stored in the - ragged array. - <dt><em>hid_t</em> <code>type_id</code> - <dd>Data type identifier for the ragged array data. - <dt><em>hid_t</em> <code>plist_id</code> - <dd>Property list of the dataset. - </dl> -<dt><strong>Returns:</strong> - <dd>Returns a ragged array identifier if successful; - otherwise returns a negative value. -</dl> - - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Ragged-Open">H5RAopen</a> -<dt><strong>Signature:</strong> - <dd><em>hid_t</em> <code>H5RAopen</code>(<em>hid_t</em> <code>loc_id</code>, - <em>const char *</em><code>name</code> - ) -<dt><strong>Purpose:</strong> - <dd>Opens a ragged array. -<dt><strong>Description:</strong> - <dd><code>H5RAopen</code> opens an existing ragged array. - <p> - The name of the array, <code>name</code>, should be the same - that was used when the array was created, i.e., the name of - the group which implements the array. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>loc_id</code> - <dd>The location identifier of the dataset. - <dt><em>const char *</em><code>name</code> - <dd>The name of the ragged array. - </dl> -<dt><strong>Returns:</strong> - <dd>Returns a ragged array identifier if successful; - otherwise returns a negative value. -</dl> - - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Ragged-Close">H5RAclose</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5RAclose</code>(<em>hid_t</em> <code>array_id</code>) -<dt><strong>Purpose:</strong> - <dd>Closes a ragged array. -<dt><strong>Description:</strong> - <dd><code>H5RAclose</code> closes the ragged array specified - with the array identifier <code>array_id</code>. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>array_id</code> - <dd>The array identifier for the ragged array to be closed. - </dl> -<dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. -</dl> - - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Ragged-Write">H5RAwrite</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5RAwrite</code>(<em>hid_t</em> <code>array_id</code>, - <em>hssize_t</em> <code>start_row</code>, - <em>hsize_t</em> <code>nrows</code>, - <em>hid_t</em> <code>type_id</code>, - <em>hsize_t</em> <code>size[/*nrows*/]</code>, - <em>void *</em><code>buf[/*nrows*/]</code> - ) -<dt><strong>Purpose:</strong> - <dd>Writes to a ragged array. -<dt><strong>Description:</strong> - <dd><code>H5RAwrite</code> writes a contiguous set of rows to a - ragged array beginning at row number <code>start_row</code> - and continuing for <code>nrows</code> rows. - <p> - Each row of the ragged array contains <code>size[]</code> - elements of type <code>type_id</code> and each row is stored - in a buffer pointed to by <code>buf[]</code>. - <p> - Datatype conversion takes place at the time of a read or write - and is automatic. See the - <a href="Datatypes.html#Datatypes-DataConversion">Data Conversion</a> - section of <cite>The Data Type Interface (H5T)</cite> in the - <cite>HDF5 User's Guide</cite> for a discussion of - data conversion, including the range of conversions currently - supported by the HDF5 libraries. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>array_id</code> - <dd>Array identifier for the ragged array to be written to. - <dt><em>hssize_t</em> <code>start_row</code> - <dd>Row at which the write will start. - <dt><em>hsize_t</em> <code>nrows</code> - <dd>Number of rows to be written - <dt><em>hid_t</em> <code>type_id</code> - <dd>Data type identifier for the data to be written. - <dt><em>hsize_t</em> <code>size[/*nrows*/]</code> - <dd>Lengths of the rows to be written. - <dt><em>void *</em><code>buf[/*nrows*/]</code> - <dd>Pointers to buffers containing the data to be written. - </dl> -<dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. -</dl> - - -<hr> -<dl> -<dt><strong>Name:</strong> <a name="Ragged-Read">H5RAread</a> -<dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5RAread</code>(<em>hid_t</em> <code>array_id</code>, - <em>hssize_t</em> <code>start_row</code>, - <em>hsize_t</em> <code>nrows</code>, - <em>hid_t</em> <code>type_id</code>, - <em>hsize_t</em> <code>size[/*nrows*/]</code>, - <em>void *</em><code>buf[/*nrows*/]</code> - ) -<dt><strong>Purpose:</strong> - <dd> -<dt><strong>Description:</strong> - <dd><code>H5RAread</code> reads the contents of one or more rows - of the ragged array pointed to by <code>array_id</code>. - <p> - The rows to be read begin at row <code>start_row</code> and - continue for <code>nrows</code> rows. - <p> - All raw data is converted to type <code>type_id</code>. - <p> - The caller must allocate the <code>size[]</code> and - <code>buf[]</code> arrays. - <p> - Memory for the data can be allocated by either the caller or - the library. In the former case, the caller should initialize - the <code>buf[]</code> array with pointers to valid memory and - the <code>size[]</code> array with the lengths of the buffers. - In the latter case, the caller should initialize - <code>buf[]</code> with null pointers (the input value of - <code>size[]</code> is irrelevant in this case) and the - library will allocate memory for each row by calling - <code>malloc()</code>. - <p> - Datatype conversion takes place at the time of a read or write - and is automatic. See the - <a href="Datatypes.html#Datatypes-DataConversion">Data Conversion</a> - section of <cite>The Data Type Interface (H5T)</cite> in the - <cite>HDF5 User's Guide</cite> for a discussion of - data conversion, including the range of conversions currently - supported by the HDF5 libraries. -<dt><strong>Parameters:</strong> - <dl> - <dt><em>hid_t</em> <code>array_id</code> - <dd>Array identifier for the ragged array to be read from. - <dt><em>hssize_t</em> <code>start_row</code> - <dd>Row at which the read will start. - <dt><em>hsize_t</em> <code>nrows</code> - <dd>Number of rows to be read - <dt><em>hid_t</em> <code>type_id</code> - <dd>Data type identifier for the data to be read. - <dt><em>hsize_t</em> <code>size[/*nrows*/]</code> - <dd>Lengths of the rows to be read. - <dt><em>void *</em><code>buf[/*nrows*/]</code> - <dd>Pointers to buffers into which the data is to be read. - </dl> -<dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful. - The values of the <code>size[]</code> array will be the - true length of each row. If a row is longer than the - caller-allocated length, then <code>size[]</code> will - contain the true length of the row although not all elements - of that row will be stored in the buffer. - <p> - Returns a negative value on failure. The <code>buf[]</code> - array will contain it's original pointers (null or otherwise), - although the caller-supplied buffers may have been modified. - The <code>size[]</code> array may also have been modified. -</dl> - - -<hr> -<center> -<table border=0 width=98%> -<tr><td valign=top align=left> -<a href="H5.intro.html">Introduction to HDF5</a> <br> -<a href="H5.user.html">HDF5 User Guide</a> <br> -<a href="index.html">Other HDF5 documents and links</a> <br> -<!-- -<a href="Glossary.html">Glossary</a><br> ---> -</td> -<td valign=top align=right> -And in this document, the -<a href="RM_H5Front.html">HDF5 Reference Manual</a> -<br> -<a href="RM_H5.html">H5</a> -<a href="RM_H5A.html">H5A</a> -<a href="RM_H5D.html">H5D</a> -<a href="RM_H5E.html">H5E</a> -<a href="RM_H5F.html">H5F</a> -<a href="RM_H5G.html">H5G</a> -<a href="RM_H5I.html">H5I</a> -<a href="RM_H5P.html">H5P</a> -<br> -<a href="RM_H5R.html">H5R</a> -H5RA -<a href="RM_H5S.html">H5S</a> -<a href="RM_H5T.html">H5T</a> -<a href="RM_H5Z.html">H5Z</a> -<a href="Tools.html">Tools</a> -<a href="PredefDTypes.html">Datatypes</a> -</td></tr> -</table> -</center> -<hr> - - -<address> -<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> - -<br> -Last modified: 8 July 1999 -<br> -Describes HDF5 Release 1.4 Beta, December 2000 - -</body> -</html> diff --git a/doc/html/Ragged.html b/doc/html/Ragged.html deleted file mode 100644 index 5646f39..0000000 --- a/doc/html/Ragged.html +++ /dev/null @@ -1,248 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> -<html> - <head> - <title>Ragged Array Experimental Interface (H5RA)</title> - </head> - - <body bgcolor="#FFFFFF"> - - -<hr> -<center> -<table border=0 width=98%> -<tr><td valign=top align=left> - <a href="H5.intro.html">Introduction to HDF5</a> <br> - <a href="RM_H5Front.html">HDF5 Reference Manual</a> <br> - <a href="index.html">Other HDF5 documents and links</a> <br> - <!-- - <a href="Glossary.html">Glossary</a><br> - --> -</td> -<td valign=top align=right> - And in this document, the - <a href="H5.user.html"><strong>HDF5 User's Guide:</strong></a> - <br> - <a href="Files.html">Files</a> - <a href="Datasets.html">Datasets</a> - <a href="Datatypes.html">Datatypes</a> - <a href="Dataspaces.html">Dataspaces</a> - <a href="Groups.html">Groups</a> - <br> - <a href="References.html">References</a> - <a href="Attributes.html">Attributes</a> - <a href="Properties.html">Property Lists</a> - <a href="Errors.html">Error Handling</a> - <br> - <a href="Filters.html">Filters</a> - <a href="Caching.html">Caching</a> - <a href="Chunking.html">Chunking</a> - <a href="MountingFiles.html">Mounting Files</a> - <br> - <a href="Performance.html">Performance</a> - <a href="Debugging.html">Debugging</a> - <a href="Environment.html">Environment</a> - <a href="ddl.html">DDL</a> - <br> - Ragged Arrays -</td></tr> -</table> -</center> -<hr> - - - <h1>The Ragged Array Interface (H5RA)</h1> - -<table border=1> -<tr><th align=left> -<font color=red> -The H5RA Interface is strictly experimental at this time; -the interface may change dramatically or support for ragged arrays -may be unavailable in future in releases. As a result, future releases -may be unable to retrieve data stored with this interface. -<p><center>Use these functions at your own risk!<br> -Do not create any archives using this interface!</center> -</font> -</th></tr> -</table> - - <h2>1. Introduction</h2> - - <p><b>Ragged arrays should be considered alpha quality. They were - added to HDF5 to satisfy the needs of the ASCI/DMF vector - bundle project; the interface and storage methods are likely - to change in the future in ways that are not backward - compatible.</b> - - <p>A two-dimensional ragged array has been added to the library - and built on top of other existing functionality. A ragged - array is a one-dimensional array of <em>rows</em> where the - length of any row is independent of the lengths of the other - rows. The number of rows and the length of each row can be - changed at any time (the current version does not support - truncating an array by removing rows). All elements of the - ragged array have the same datatype and, as with datasets, the - data is type-converted between memory buffers and files. - - <p>The current implementation works best when most of the rows are - approximately the same length since a two dimensional dataset - can be created to hold a nominal number of elements from each - row with the additional elements stored in a separate dataset - which implements a heap. - - <p>A ragged array is a composite object implemented as a group - with three datasets. The name of the group is the name of the - ragged array. The <em>raw</em> dataset is a two-dimensional - array that contains the first <em>N</em> elements of each row - where <em>N</em> is determined by the application when the array - is created. If most rows have fewer than <em>N</em> elements - then internal fragmentation may be quite bad. - - <p>The <em>over</em> dataset is a one-dimensional array that - contains elements from each row that don't fit in the - <em>raw</em> dataset. - - <p>The <em>meta</em> dataset maintains information about each row - such as the number of elements in the row, the location of the - overflow elements in the <em>over</em> dataset (if any), and the - amount of space reserved in <em>over</em> for the row. The - <em>meta</em> dataset has one entry per row and is where most of - the storage overhead is concentrated when rows are relatively - short. - - <h2>2. Opening and Closing</h2> - - <dl> - <dt><code>hid_t H5RAcreate (hid_t <em>location</em>, const char - *<em>name</em>, hid_t <em>type</em>, hid_t - <em>plist</em>)</code> - <dd>This function creates a new ragged array by creating the - group with the specified name and populating it with the - component datasets (which should not be accessed - independently). The dataset creation property list - <em>plist</em> defines the width of the <em>raw</em> dataset; - a nominal row is considered to be the width of a chunk. The - <em>type</em> argument defines the datatype which will be - stored in the file. A negative value is returned if the array - cannot be created. - - <br><br> - <dt><code>hid_t H5RAopen (hid_t <em>location</em>, const char - *<em>name</em>)</code> - <dd>This function opens a ragged array by opening the specified - group and the component datasets (which should not be accessed - indepently). A negative value is returned if the array cannot - be opened. - - <br><br> - <dt><code>herr_t H5RAclose (hid_t <em>array</em>)</code> - <dd>All ragged arrays should be closed by calling this - function. The group and component datasets will be closed - automatically by the library. - </dl> - - <h2>3. Reading and Writing</h2> - - <p>In order to be as efficient as possible the ragged array layer - operates on sets of contiguous rows and it is to the - application's advantage to perform I/O on as many rows at a time - as possible. These functions take a starting row number and the - number of rows on which to operate. - - <dl> - <dt><code>herr_t H5RAwrite (hid_t <em>array_id</em>, hssize_t - <em>start_row</em>, hsize_t <em>nrows</em>, hid_t - <em>type</em>, hsize_t <em>size</em>[], void - *<em>buf</em>[])</code> - <dd>A set of ragged array rows beginning at <em>start_row</em> - and continuing for <em>nrows</em> is written to the file, - converting the memory datatype <em>type</em> to the file data - type which was defined when the array was created. The number - of elements to write from each row is specified in the - <em>size</em> array and the data for each row is pointed to - from the <em>buf</em> array. The <em>size</em> and - <em>buf</em> are indexed so their first element corresponds to - the first row on which to operate. - - <br><br> - <dt><code>herr_t H5RAread (hid_t <em>array_id</em>, hssize_t - <em>start_row</em>, hsize_t <em>nrows</em>, hid_t - <em>type</em>, hsize_t <em>size</em>[], void - *<em>buf</em>[])</code> - <dd>A set of ragged array rows beginning at <em>start_row</em> - and continuing for <em>nrows</em> is read from the file, - converting from the file datatype which was defined when the - array was created to the memory datatype <em>type</em>. The - number of elements to read from each row is specified in the - <em>size</em> array and the buffers in which to place the - results are pointed to by the <em>buf</em> array. On return, - the <em>size</em> array will contain the actual size of the - row which may be different than the requested size. When the - request size is smaller than the actual size the row will be - truncated; otherwise the remainder of the output buffer will - be zero filled. If a pointer in the <em>buf</em> array is - null then the library will ignore the corresponding - <em>size</em> value and allocate a buffer large enough to hold - the entire row. This function returns negative for failures - with <em>buf</em> containing the original input values. - </dl> - - -<hr> -<center> -<table border=0 width=98%> -<tr><td valign=top align=left> - <a href="H5.intro.html">Introduction to HDF5</a> <br> - <a href="RM_H5Front.html">HDF5 Reference Manual</a> <br> - <a href="index.html">Other HDF5 documents and links</a> <br> - <!-- - <a href="Glossary.html">Glossary</a><br> - --> -</td> -<td valign=top align=right> - And in this document, the - <a href="H5.user.html"><strong>HDF5 User's Guide:</strong></a> - <br> - <a href="Files.html">Files</a> - <a href="Datasets.html">Datasets</a> - <a href="Datatypes.html">Datatypes</a> - <a href="Dataspaces.html">Dataspaces</a> - <a href="Groups.html">Groups</a> - <br> - <a href="References.html">References</a> - <a href="Attributes.html">Attributes</a> - <a href="Properties.html">Property Lists</a> - <a href="Errors.html">Error Handling</a> - <br> - <a href="Filters.html">Filters</a> - <a href="Caching.html">Caching</a> - <a href="Chunking.html">Chunking</a> - <a href="MountingFiles.html">Mounting Files</a> - <br> - <a href="Performance.html">Performance</a> - <a href="Debugging.html">Debugging</a> - <a href="Environment.html">Environment</a> - <a href="ddl.html">DDL</a> - <br> - Ragged Arrays -</td></tr> -</table> -</center> - - - -<hr> -<address> -<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> -</address> - -<!-- Created: Wed Aug 26 14:10:32 EDT 1998 --> -<!-- hhmts start --> -Last modified: 13 December 1999 -<!-- hhmts end --> - -<br> -Describes HDF5 Release 1.4 Beta, December 2000 - - - </body> -</html> |