<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&lt;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);

        &lt;initialize data array&gt;

        /* Write the entire dataset out */
        <A HREF="H5.apiv3.html#Dataset-Write">H5Dwrite</a>(dataset_id,H5S_SCALAR,data);
        &lt;or&gt;
        <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);

        &lt;initialize data array&gt;

        /* 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);

        &lt;initialize data array&gt;

        /* 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)
          {
            &lt;set up for compound object&gt;
          } 
        else
          {
            &lt;set up for homogenous object&gt;
          } 

        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);
        &lt;allocate space based on element size and number of elements &gt;

        /* Read in the dataset */
        <A HREF="H5.apiv3.html#Dataset-Read">H5Dwrite</a>(dataset_id,H5S_SCALAR,data);
            &lt;or&gt;
        <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>