diff options
Diffstat (limited to 'doc/html/Tutor/reftoobj.html')
| -rw-r--r-- | doc/html/Tutor/reftoobj.html | 570 |
1 files changed, 207 insertions, 363 deletions
diff --git a/doc/html/Tutor/reftoobj.html b/doc/html/Tutor/reftoobj.html index 43a6375..1860367 100644 --- a/doc/html/Tutor/reftoobj.html +++ b/doc/html/Tutor/reftoobj.html @@ -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,398 +53,244 @@ 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> +<A NAME="def2"> +<H2>Reading References and Accessing Objects Using References</H2> + +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 +<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. +<P> +<LI> Open the dereferenced object and perform the desired operations. +<P> +<LI> Close all objects when the task is complete. +</OL> <H2> Programming Example</H2> -<A NAME="desc1"> +<A NAME="desc"> <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 <hdf5.h> - -#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 < 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); +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. - /* Write selection to disk */ - ret=H5Dwrite(dataset,H5T_STD_REF_OBJ,H5S_ALL,H5S_ALL,H5P_DEFAULT,wbuf); +<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> + Data has been successfully written to the dataset + Stored datatype is of a FLOAT class +</PRE> - /* 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"> +<A NAME="rem"> <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 +<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 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> +<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> <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> <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 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), + <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. - <LI> The fifth argument specifies the space identifier. When references - to the objects are created it should be set to -1. +<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> <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> -<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. + <UL> + <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="fc1"> + + +<A NAME="fc"> <H3><U>File Contents</U></H3> -The contents of the "trefer1.h5" file created by this example are as follows: -<PRE> - Fig "trefer1.h5" -============================================================================== +<P> +<I><U>HDF5 File Created by C Example</U></I> +<p> +<B>Fig. A</B> <I><code>REF_OBJ.h5</code> in DDL</I> -HDF5 "trefer1.h5" { +<PRE> +HDF5 "REF_OBJ.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" { + GROUP "GROUP2" { } } - 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 - } + DATASET "INTEGERS" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 5 ) / ( 5 ) } + DATA { + 1, 2, 3, 4, 5 } - DATATYPE "Datatype1" { - H5T_STD_I32BE "a"; - H5T_STD_I32BE "b"; - H5T_IEEE_F32BE "c"; + } + 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> -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: -<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. -<P> -<LI> Use the read reference to obtain the identifier of the object the - reference points to. -<P> -<LI> Open the dereferenced object and perform the desired operations. -<P> -<LI> Close all objects when the task is complete. -</OL> - -<H2> Programming Example</H2> -<A NAME="desc2"> -<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> ] +</PRE> +<I><U>HDF5 File Created by FORTRAN Example</U></I>: +<p> +<B>Fig. B</B> <I><code>FORTRAN.h5</code> in DDL</I> <PRE> -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -#include <stdlib.h> -#include <hdf5.h> - -#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 < 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; -} -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +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> -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"> -<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 - 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> - <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. - </UL> -</UL> - +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,11 @@ 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> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: January 19, 2000</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"> --> |