mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-21 01:04:10 +08:00
284 lines
12 KiB
HTML
284 lines
12 KiB
HTML
<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>
|