summaryrefslogtreecommitdiffstats
path: root/doc/html/review1.html
diff options
context:
space:
mode:
authorQuincey Koziol <koziol@hdfgroup.org>1998-07-08 14:54:54 (GMT)
committerQuincey Koziol <koziol@hdfgroup.org>1998-07-08 14:54:54 (GMT)
commitbd1e676c521d881b3143829f493a28b5ced1294b (patch)
tree69c50f9fe21ce87f293d8617a6bd51b4cc1e0244 /doc/html/review1.html
parent73345095897d9698bb1f2f7df830bf80a56dc65a (diff)
downloadhdf5-bd1e676c521d881b3143829f493a28b5ced1294b.zip
hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.gz
hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.bz2
[svn-r467] Restructuring documentation.
Diffstat (limited to 'doc/html/review1.html')
-rw-r--r--doc/html/review1.html283
1 files changed, 283 insertions, 0 deletions
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&lt;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);
+
+ &lt;initialize data array&gt;
+
+ /* Write the entire dataset out */
+ <A HREF="H5.apiv3.html#Dataset-Write">H5Dwrite</a>(dataset_id,H5S_SCALAR,data);
+ &lt;or&gt;
+ <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);
+
+ &lt;initialize data array&gt;
+
+ /* 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);
+
+ &lt;initialize data array&gt;
+
+ /* 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)
+ {
+ &lt;set up for compound object&gt;
+ }
+ else
+ {
+ &lt;set up for homogenous object&gt;
+ }
+
+ 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);
+ &lt;allocate space based on element size and number of elements &gt;
+
+ /* Read in the dataset */
+ <A HREF="H5.apiv3.html#Dataset-Read">H5Dwrite</a>(dataset_id,H5S_SCALAR,data);
+ &lt;or&gt;
+ <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>