philipp/hdf5
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[svn-r3659]

Browse Source 
Added html files with references to the fortran 90 files.
(under examples/)
This commit is contained in:
Barbara Jones
2001-03-19 09:26:47 -05:00
parent 380eb42bc5
commit f11cef2c56
30 changed files with 2967 additions and 3139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

577
doc/html/Tutor/reftoobj.html
View File

@@ -23,24 +23,19 @@ width=78 height=27 alt="NCSA"><P></A>
<UL>
<LI><A HREF="#def">References to Objects</A>
<LI> <A HREF="#def1">Creating and Storing References to Objects</A>
<LI> Programming Example
<UL>
<LI> <A HREF="#desc1">Description</A>
<LI> <A HREF="#rem1">Remarks</A>
<LI> <A HREF="#fc1">File Contents</A>
</UL>
<LI> <A HREF="#def2">Reading References and Accessing Objects Using
References</A>
<LI> Programming Example
<UL>
<LI> <A HREF="#desc2">Description</A>
<LI> <A HREF="#rem2">Remarks</A>
<LI> <A HREF="#desc">Description</A>
<LI> <A HREF="#rem">Remarks</A>
<LI> <A HREF="#fc">File Contents</A>
</UL>
</UL>
<HR>
<A NAME="def">
<H2>References to Objects</H2>
In HDF5, objects (i.e. groups, datasets, and named data types) are usually
In HDF5, objects (i.e. groups, datasets, and named datatypes) are usually
accessed by name. This access method was discussed in previous sections.
There is another way to access stored objects - by reference.
<P>
@@ -58,239 +53,22 @@ to objects:
<OL>
<LI> Create the objects or open them if they already exist in the file.
<P>
<LI> Create a dataset to store the objects' references.
<LI> Create a dataset to store references to the objects.
<P>
<LI> Create and store references to the objects in a buffer.
<P>
<LI> Write a buffer with the references to the dataset.
<LI> Write the buffer containing the references to the dataset.
</OL>
<H2> Programming Example</H2>
<A NAME="desc1">
<H3><U>Description</U></H3>
The example below creates a group and two datasets and a named data type in the
group. References to these four objects are stored in the dataset in the root
group. [<A HREF="examples/h5_ref2objw.c">Download h5_ref2objw.c</A>]
<PRE>
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
#include &lt;hdf5.h&gt;
#define FILE1 "trefer1.h5"
/* 1-D dataset with fixed dimensions */
#define SPACE1_NAME "Space1"
#define SPACE1_RANK 1
#define SPACE1_DIM1 4
/* 2-D dataset with fixed dimensions */
#define SPACE2_NAME "Space2"
#define SPACE2_RANK 2
#define SPACE2_DIM1 10
#define SPACE2_DIM2 10
int
main(void) {
hid_t fid1; /* HDF5 File IDs */
hid_t dataset; /* Dataset ID */
hid_t group; /* Group ID */
hid_t sid1; /* Dataspace ID */
hid_t tid1; /* Datatype ID */
hsize_t dims1[] = {SPACE1_DIM1};
hobj_ref_t *wbuf; /* buffer to write to disk */
int *tu32; /* Temporary pointer to int data */
int i; /* counting variables */
const char *write_comment="Foo!"; /* Comments for group */
herr_t ret; /* Generic return value */
/* Compound datatype */
typedef struct s1_t {
unsigned int a;
unsigned int b;
float c;
} s1_t;
/* Allocate write buffers */
wbuf=(hobj_ref_t *)malloc(sizeof(hobj_ref_t)*SPACE1_DIM1);
tu32=malloc(sizeof(int)*SPACE1_DIM1);
/* Create file */
fid1 = H5Fcreate(FILE1, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
/* Create dataspace for datasets */
sid1 = H5Screate_simple(SPACE1_RANK, dims1, NULL);
/* Create a group */
group=H5Gcreate(fid1,"Group1",-1);
/* Set group's comment */
ret=H5Gset_comment(group,".",write_comment);
/* Create a dataset (inside Group1) */
dataset=H5Dcreate(group,"Dataset1",H5T_STD_U32LE,sid1,H5P_DEFAULT);
for(i=0; i &lt; SPACE1_DIM1; i++)
tu32[i] = i*3;
/* Write selection to disk */
ret=H5Dwrite(dataset,H5T_NATIVE_INT,H5S_ALL,H5S_ALL,H5P_DEFAULT,tu32);
/* Close Dataset */
ret = H5Dclose(dataset);
/* Create another dataset (inside Group1) */
dataset=H5Dcreate(group,"Dataset2",H5T_NATIVE_UCHAR,sid1,H5P_DEFAULT);
/* Close Dataset */
ret = H5Dclose(dataset);
/* Create a datatype to refer to */
tid1 = H5Tcreate (H5T_COMPOUND, sizeof(s1_t));
/* Insert fields */
ret=H5Tinsert (tid1, "a", HOFFSET(s1_t,a), H5T_NATIVE_INT);
ret=H5Tinsert (tid1, "b", HOFFSET(s1_t,b), H5T_NATIVE_INT);
ret=H5Tinsert (tid1, "c", HOFFSET(s1_t,c), H5T_NATIVE_FLOAT);
/* Save datatype for later */
ret=H5Tcommit (group, "Datatype1", tid1);
/* Close datatype */
ret = H5Tclose(tid1);
/* Close group */
ret = H5Gclose(group);
/* Create a dataset to store references */
dataset=H5Dcreate(fid1,"Dataset3",H5T_STD_REF_OBJ,sid1,H5P_DEFAULT);
/* Create reference to dataset */
ret = H5Rcreate(&wbuf[0],fid1,"/Group1/Dataset1",H5R_OBJECT,-1);
/* Create reference to dataset */
ret = H5Rcreate(&wbuf[1],fid1,"/Group1/Dataset2",H5R_OBJECT,-1);
/* Create reference to group */
ret = H5Rcreate(&wbuf[2],fid1,"/Group1",H5R_OBJECT,-1);
/* Create reference to named datatype */
ret = H5Rcreate(&wbuf[3],fid1,"/Group1/Datatype1",H5R_OBJECT,-1);
/* Write selection to disk */
ret=H5Dwrite(dataset,H5T_STD_REF_OBJ,H5S_ALL,H5S_ALL,H5P_DEFAULT,wbuf);
/* Close disk dataspace */
ret = H5Sclose(sid1);
/* Close Dataset */
ret = H5Dclose(dataset);
/* Close file */
ret = H5Fclose(fid1);
free(wbuf);
free(tu32);
return 0;
}
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
</PRE>
<A NAME="rem1">
<H3><U>Remarks</U></H3>
<UL>
<LI> The following code,
<PRE>
dataset = H5Dcreate ( fid1,"Dataset3",H5T_STD_REF_OBJ,sid1,H5P_DEFAULT );
</PRE>
creates a dataset to store references. Notice that the H5T_SDT_REF_OBJ
data type is used to specify that references to objects will be
stored. The data type H5T_STD_REF_DSETREG is used to store the dataset
region references and will be discussed later in this tutorial.
<P>
<LI>The next few calls to the H5Rcreate function create references to the
objects and store them in the buffer <I>wbuf</I>. The signature of the
H5Rcreate function is:
<PRE>
herr_t H5Rcreate ( void* buf, hid_t loc_id, const char *name,
H5R_type_t ref_type, hid_t space_id )
</PRE>
<UL>
<LI> The first argument specifies the buffer to store the reference.
<LI> The second and third arguments specify the name of the referenced
object. In our example, the file identifier <I>fid1</I> and
absolute name of the dataset "/Group1/Dataset1" were used to
identify the dataset. One could also use the group identifier
of group "Group1" and the relative name of the dataset "Dataset1"
to create the same reference.
<LI> The fourth argument specifies the type of the reference. Our example
uses references to the objects (H5R_OBJECT). Another type of
reference, reference to the dataset region ( H5R_DATASET_REGION),
will be discussed later in this tutorial.
<LI> The fifth argument specifies the space identifier. When references
to the objects are created it should be set to -1.
</UL>
<P>
<LI>The H5Dwrite function writes a dataset with the references to the file.
Notice that the H5T_SDT_REF_OBJ data type is used to describe the
dataset's memory data type.
<P>
</UL>
<A NAME="fc1">
<H3><U>File Contents</U></H3>
The contents of the "trefer1.h5" file created by this example are as follows:
<PRE>
Fig "trefer1.h5"
==============================================================================
HDF5 "trefer1.h5" {
GROUP "/" {
DATASET "Dataset3" {
DATATYPE { H5T_REFERENCE }
DATASPACE { SIMPLE ( 4 ) / ( 4 ) }
DATA {
DATASET 0:1696, DATASET 0:2152, GROUP 0:1320, DATATYPE 0:2268
}
}
GROUP "Group1" {
DATASET "Dataset1" {
DATATYPE { H5T_STD_U32LE }
DATASPACE { SIMPLE ( 4 ) / ( 4 ) }
DATA {
0, 3, 6, 9
}
}
DATASET "Dataset2" {
DATATYPE { H5T_STD_U8LE }
DATASPACE { SIMPLE ( 4 ) / ( 4 ) }
DATA {
0, 0, 0, 0
}
}
DATATYPE "Datatype1" {
H5T_STD_I32BE "a";
H5T_STD_I32BE "b";
H5T_IEEE_F32BE "c";
}
}
}
}
===============================================================================
</PRE>
Notice how the data in dataset "Dataset3" is described. The two numbers
with the colon in between represent a unique identifier of the object. These
numbers are constant for the life of the object.
<A NAME="def2">
<H2>Reading References and Accessing Objects Using References</H2>
The following steps are involved:
The following steps are involved in reading references to objects and
accessing objects using references:
<OL>
<LI> Open the dataset with the references and read them. The H5T_STD_REF_OBJ
data type must be used to describe the memory data type.
<LI> Open the dataset with the references and read them. The
<CODE>H5T_STD_REF_OBJ</CODE>
datatype must be used to describe the memory datatype.
<P>
<LI> Use the read reference to obtain the identifier of the object the
reference points to.
@@ -301,155 +79,218 @@ The following steps are involved:
</OL>
<H2> Programming Example</H2>
<A NAME="desc2">
<A NAME="desc">
<H3><U>Description</U></H3>
The example below opens and reads dataset "Dataset3" from the file created
previously. Then the program dereferences the references to
dataset "Dataset1", the group and the named data type, and opens those objects.
The program reads and displays the dataset's data, the group's comment and
the number of members of the compound data type.
[ <A HREF="examples/h5_ref2objr.c">Download h5_ref2objr.c</A> ]
The example below first creates a group in the file.
It then creates two datasets and a named datatype in that group.
References to these four objects are stored in a dataset in the root group.
<P>
After that, it opens and reads the reference dataset from the file created
previously, then dereferences the references.
<UL>
[<A HREF="examples/h5_ref2obj.c">C example</A> ]
- <code>h5_ref2obj.c</code><BR>
[<A HREF="examples/refobjexample.f90">FORTRAN example</A> ]
- <code>refobjexample.f90</code>
</UL>
<B>NOTE:</B> To download a tar file of the examples, including a Makefile,
please go to the <A HREF="references.html">References</A> page.
<P>
Following is the output from the examples:
<PRE>
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
#include &lt;stdlib.h&gt;
#include &lt;hdf5.h&gt;
#define FILE1 "trefer1.h5"
/* dataset with fixed dimensions */
#define SPACE1_NAME "Space1"
#define SPACE1_RANK 1
#define SPACE1_DIM1 4
int
main(void)
{
hid_t fid1; /* HDF5 File IDs */
hid_t dataset, /* Dataset ID */
dset2; /* Dereferenced dataset ID */
hid_t group; /* Group ID */
hid_t sid1; /* Dataspace ID */
hid_t tid1; /* Datatype ID */
hobj_ref_t *rbuf; /* buffer to read from disk */
int *tu32; /* temp. buffer read from disk */
int i; /* counting variables */
char read_comment[10];
herr_t ret; /* Generic return value */
/* Allocate read buffers */
rbuf = malloc(sizeof(hobj_ref_t)*SPACE1_DIM1);
tu32 = malloc(sizeof(int)*SPACE1_DIM1);
/* Open the file */
fid1 = H5Fopen(FILE1, H5F_ACC_RDWR, H5P_DEFAULT);
/* Open the dataset */
dataset=H5Dopen(fid1,"/Dataset3");
/* Read selection from disk */
ret=H5Dread(dataset,H5T_STD_REF_OBJ,H5S_ALL,H5S_ALL,H5P_DEFAULT,rbuf);
/* Open dataset object */
dset2 = H5Rdereference(dataset,H5R_OBJECT,&rbuf[0]);
/* Check information in referenced dataset */
sid1 = H5Dget_space(dset2);
ret=H5Sget_simple_extent_npoints(sid1);
/* Read from disk */
ret=H5Dread(dset2,H5T_NATIVE_INT,H5S_ALL,H5S_ALL,H5P_DEFAULT,tu32);
printf("Dataset data : \n");
for (i=0; i &lt; SPACE1_DIM1 ; i++) printf (" %d ", tu32[i]);
printf("\n");
printf("\n");
/* Close dereferenced Dataset */
ret = H5Dclose(dset2);
/* Open group object */
group = H5Rdereference(dataset,H5R_OBJECT,&rbuf[2]);
/* Get group's comment */
ret=H5Gget_comment(group,".",10,read_comment);
printf("Group comment is %s \n", read_comment);
printf(" \n");
/* Close group */
ret = H5Gclose(group);
/* Open datatype object */
tid1 = H5Rdereference(dataset,H5R_OBJECT,&rbuf[3]);
/* Verify correct datatype */
{
H5T_class_t tclass;
tclass= H5Tget_class(tid1);
if ((tclass == H5T_COMPOUND))
printf ("Number of compound datatype members is %d \n", H5Tget_nmembers(tid1));
printf(" \n");
}
/* Close datatype */
ret = H5Tclose(tid1);
/* Close Dataset */
ret = H5Dclose(dataset);
/* Close file */
ret = H5Fclose(fid1);
/* Free memory buffers */
free(rbuf);
free(tu32);
return 0;
}
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Data has been successfully written to the dataset
Stored datatype is of a FLOAT class
</PRE>
Following is the output of this program:
<PRE>
Dataset data :
0 3 6 9
Group comment is Foo!
Number of compound datatype members is 3
</PRE>
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
<A NAME="rem2">
<A NAME="rem">
<H3><U>Remarks</U></H3>
<UL>
<LI> The H5Dread function was used to read dataset "Dataset3" containing the
references to the objects. The H5T_STD_REF_OBJ memory data type was
<LI> The following code creates a dataset in which to store the references.
<P>
<I><B>C:</B></I> <pre>
dset2_id = H5Dcreate (file_id, dsetname, H5T_STD_REF_OBJ,
space_id, H5P_DEFAULT);
</pre>
<P>
<I><B>FORTRAN:</B></I><pre>
CALL h5dcreate_f (file_id, dsetname, H5T_STD_REF_OBJ, &
space_id, dset2_id, hdferr)
</pre>
<P>
Notice that the <CODE>H5T_SDT_REF_OBJ</CODE>
datatype is used to specify that references to objects will be
stored. The datatype <CODE>H5T_STD_REF_DSETREG</CODE> is
used to store the dataset
region references and will be discussed later in this tutorial.
<P>
<LI>The next few calls to <CODE>H5Rcreate</CODE> / <CODE>h5rcreate_f</CODE>
create references to the objects. The signature of
<CODE>H5Rcreate</CODE> / <CODE>h5rcreate_f</CODE> is as follows:
<P>
<I><B>C:</B></I> &nbsp; <pre>
herr_t H5Rcreate (void* ref, hid_t loc_id, const char *name,
H5R_type_t ref_type, hid_t space_id)
</pre>
<P>
<I><B>FORTRAN:</B></I> &nbsp; <pre>
h5rcreate_f (loc_id, name, ref, hdferr)
loc_id IN: INTEGER (HID_T)
name IN: CHARACTER(LEN=*)
ref OUT: TYPE (hobj_ref_t_f)
hdferr OUT: INTEGER
</pre>
<P>
<UL>
<LI> The <em>ref</em> argument specifies the buffer
in which to store the reference.
<P>
<LI> The <I>loc_id</I> and <I>name</I> arguments specify the name of
the referenced object.
<P>
<LI> In C, the <I>ref_type</I> argument specifies the type of the
reference.
Our example uses references to objects, <CODE>H5R_OBJECT</CODE>.
References to dataset regions, <CODE>H5R_DATASET_REGION</CODE>,
will be discussed later in this tutorial.
<P>
<LI> In C, the <I>space_id</I> argument specifies the dataspace
identifier. When references
to the objects are created, this argument should be set to -1.
<P>
<LI> In FORTRAN, the return value from the <CODE>h5rcreate_f</CODE>
call is in <I>hdferr</I>: 0 if successful, -1 otherwise.
In C, <CODE>H5Rcreate</CODE> returns a non-negative value if
successful and a negative value otherwise.
</UL>
<P>
<LI><CODE>H5Dwrite</CODE> / <CODE>h5dwrite_f</CODE> writes a
dataset containing the references.
Notice that the <CODE>H5T_SDT_REF_OBJ</CODE> datatype is used to
describe the dataset's memory datatype.
<P>
</UL>
<UL>
<LI> <CODE>H5Dread</CODE> / <CODE>h5dread_f</CODE>
reads the dataset containing the
references to the objects. The <CODE>H5T_STD_REF_OBJ</CODE> memory
datatype was
used to read references to memory.
<P>
<LI> H5Rdereference obtains the object's identifier. The signature of this
function is:
<PRE>
hid_t H5Rdereference (hid_t datatset, H5R_type_t ref_type, void *ref)
</PRE>
<LI> <CODE>H5Rdereference</CODE> / <CODE>h5rdereference_f</CODE> obtains
the object's identifier. The signature is as follows:
<P>
<I><B>C</B></I>: <pre>
hid_t H5Rdereference (hid_t dset_id, H5R_type_t ref_type,
void *ref)
</pre>
<P>
<I><B>FORTRAN</B></I>: <pre>
h5rdereference_f (dset_id, ref, obj_id, hdferr)
dset_id IN: INTEGER (HID_T)
ref IN: TYPE (hobj_ref_t_f)
obj_id OUT: INTEGER (HID_T)
hdferr OUT: INTEGER
</pre>
<P>
<UL>
<LI> The first argument is an identifier of the dataset with the references.
<LI> The second argument specifies the reference type. We used
H5R_OBJECT to
specify a reference to an object. Another type is
H5R_DATASET_REGION to specify a reference to a dataset region.
This will be discussed later in this tutorial.
<LI> The third argument is a buffer to store the reference to be read.
<LI> The function returns an identifier of the object the reference
points to. In our simplified situation we know what type was
stored in the dataset. When the type of the object is unknown, then
H5Rget_object_type should be used to identify the type of object
the reference points to.
<LI> The <I>dset_id</I> argument is the identifier of the dataset
containing the references.
<P>
<LI> In C, the <I>ref_type</I> argument specifies the reference type.
<P>
<LI> The <I>ref</I> argument is a buffer containing the reference
to be dereferenced.
<P>
<LI> The C function returns the identifier of the object that the
reference points to or a negative value if it is unsuccessful.
In FORTRAN, the object identifier is returned in <I>obj_id</I>
and the return code is returned in <I>hdferr</I>.
<P>
In our simplified situation, we know what type of object was
stored in the dataset. When the type of the object is unknown,
<CODE>H5Rget_object_type</CODE> should be used to identify the type
of object the reference points to.
</UL>
</UL>
<A NAME="fc">
<H3><U>File Contents</U></H3>
<P>
<I><U>HDF5 File Created by C Example</U></I>
<p>
<B>Fig. A</B> &nbsp; <I><code>REF_OBJ.h5</code> in DDL</I>
<PRE>
HDF5 "REF_OBJ.h5" {
GROUP "/" {
GROUP "GROUP1" {
GROUP "GROUP2" {
}
}
DATASET "INTEGERS" {
DATATYPE { H5T_STD_I32BE }
DATASPACE { SIMPLE ( 5 ) / ( 5 ) }
DATA {
1, 2, 3, 4, 5
}
}
DATATYPE "MYTYPE" {
}
DATASET "OBJECT_REFERENCES" {
DATATYPE { H5T_REFERENCE }
DATASPACE { SIMPLE ( 4 ) / ( 4 ) }
DATA {
GROUP 0:1320, GROUP 0:2272, DATASET 0:2648, DATATYPE 0:3244
}
}
}
}
</PRE>
<I><U>HDF5 File Created by FORTRAN Example</U></I>:
<p>
<B>Fig. B</B> &nbsp; <I><code>FORTRAN.h5</code> in DDL</I>
<PRE>
HDF5 "FORTRAN.h5" {
GROUP "/" {
GROUP "GROUP1" {
GROUP "GROUP2" {
}
}
DATASET "INTEGERS" {
DATATYPE { H5T_STD_I32BE }
DATASPACE { SIMPLE ( 5 ) / ( 5 ) }
DATA {
1, 2, 3, 4, 5
}
}
DATATYPE "MyType" {
}
DATASET "OBJECT_REFERENCES" {
DATATYPE { H5T_REFERENCE }
DATASPACE { SIMPLE ( 4 ) / ( 4 ) }
DATA {
GROUP 0:1344, GROUP 0:2320, DATASET 0:2696, DATATYPE 0:3292
}
}
}
}
</PRE>
<P>
Notice how the data in the reference dataset is described. The two numbers
separated by a colon represent a unique identifier of the object. These
numbers are constant for the life of the object.
<!-- BEGIN FOOTER INFO -->
@@ -465,8 +306,10 @@ Number of compound datatype members is 3
<!-- <A HREF="helpdesk.mail.html"> -->
<A HREF="mailto:hdfhelp@ncsa.uiuc.edu">
hdfhelp@ncsa.uiuc.edu</A>
<BR> <H6>Last Modified: August 27, 1999</H6><BR>
<br>
<BR> <H6>Last Modified: March 16, 2001</H6><BR>
<!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu -->
<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu -->
</FONT>
<BR>
<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> -->