<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>