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/review1.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/review1.html')
| -rw-r--r-- | doc/html/review1.html | 283 |
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<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> |