# HDF5: Revised API Example Code

Example programs/sections of code below:

#1
  A simple example showing how to create a file.
#2
  A example showing how to check if a file is an HDF5 file and list it's contents.
#3
  A example showing how to create a homogenous multi-dimensional dataset.
#4
  A example showing how to create a compound 1-D dataset.
#5
  A example showing how to create a compound multi-dimensional dataset.
#6
  A example showing how to read a generic dataset.

## Simple Example showing how to create a file.

Notes:
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.

Code: ``

        hid_t file_id;

        file_id=H5Fcreate("example1.h5",0);

        H5Fclose(file_id);

## Example showing how check if a file is an HDF5 file and list it's contents.

Notes:
This example checks if a file is an HDF5 file and lists the contents of the top level (file level) group.

Code: ``

        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(H5Fis_hdf5("example2.h5")==TRUE)
          {
            file_id=H5Fopen("example2.h5",H5F_ACC_RDWR|H5ACC_CREATE);
            num_items=H5GgetNumContents(file_id);
            for(i=0; i<num_items; i++)
              {
                obj_name=H5GgetNameByIndex(file_id,i,NULL,0);
                printf("object #%d is: %s\n",i,buf);
                HDfree(obj_name);
              }
            H5Fclose(file_id);
          }

## Example showing how create a homogenous multi-dimensional dataset.

Notes:
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.

Code: ``

        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=H5Fcreate("example3.h5",H5F_ACC_TRUNC))>=0)
          {
            /* Create & initialize the dataset object */
            dataset_id=H5Mcreate(file_id,H5OBJ_DATASET,"Simple Object");

            /* Create & initialize a datatype object */
            H5TsetType(dataset_id,H5TYPE_FLOAT,4,H5T_BIGENDIAN);

            /* Initialize dimensionality of dataset */
            H5SsetSpace(dataset_id,rank,dims);

            <initialize data array>

            /* Write the entire dataset out */
            H5Dwrite(dataset_id,H5S_SCALAR,data);
            <or>
            H5Dwrite(dataset_id,dataset_id,data);

            /* Release the atoms we've created */
            H5Mrelease(dataset_id);

            /* close the file */
            H5Fclose(file_id);
          }

## Example showing how create a compound 1-D dataset.

Notes:
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.

Code: ``

        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=H5Fcreate("example4.h5",H5F_ACC_TRUNC))>=0)
          {
            /* Create & initialize the dataset object */
            dataset_id=H5Mcreate(file_id,H5OBJ_DATASET,"Compound Object");

            /* Initialize datatype */
            H5TsetType(dataset_id,H5TYPE_STRUCT);
            H5TaddField(dataset_id,H5TYPE_FLOAT32,"Float32 Scalar Field",H5SPACE_SCALAR);
            H5TaddField(dataset_id,H5TYPE_CHAR,"Char Field",H5SPACE_SCALAR);
            H5TaddField(dataset_id,H5TYPE_UINT16,"UInt16 Field",H5SPACE_SCALAR);
            H5TendDefine(dataset_id);

            /* Initialize dimensionality */
            H5SsetSpace(dataset_id,1,dims);

            <initialize data array>

            /* Write the entire dataset out */
            H5Dwrite(dataset_id,H5S_SCALAR,data);

            /* Release the atoms we've created */
            H5Mrelease(dataset_id);

            /* close the file */
            H5Fclose(file_id);
          }

## Example showing how create a compound multi-dimensional dataset.

Notes:
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.

Code: ``

        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=H5Fcreate("example5.h5",H5F_ACC_TRUNC))>=0)
          {
            /* Create & initialize a datatype object */
            type_id=H5Mcreate(file_id,H5OBJ_DATATYPE,"Compound Type #1");
            H5TsetType(type_id,H5TYPE_STRUCT);

            /* Create each multi-dimensional field in structure */
            field_dim_id=H5Mcreate(file_id,H5OBJ_DATASPACE,"Lat/Long Dims");
            field_dims[0]=360;
            field_dims[1]=720;
            H5SsetSpace(field_dim_id,2,field_dims);
            H5TaddField(type_id,H5TYPE_FLOAT32,"Lat/Long Locations",field_dim_id);
            H5Mrelease(field_dim_id);

            field_dim_id=H5Mcreate(file_id,H5OBJ_DATASPACE,"Browse Dims");
            field_dims[0]=40;
            field_dims[1]=40;
            H5SsetSpace(field_dim_id,2,field_dims);
            H5TaddField(type_id,H5TYPE_CHAR,"Browse Image",field_dim_id);
            H5Mrelease(field_dim_id);

            field_dim_id=H5Mcreate(file_id,H5OBJ_DATASPACE,"Multispectral Dims");
            field_dims[0]=80;
            field_dims[1]=60;
            field_dims[2]=40;
            H5SsetSpace(field_dim_id,3,field_dims);
            H5TaddField(type_id,H5TYPE_UINT16,"Multispectral Scans",field_dim_id);
            H5Mrelease(field_dim_id);
            H5TendDefine(type_id);

            /* Create & initialize a dimensionality object */
            dim_id=H5Mcreate(file_id,H5OBJ_DATASPACE,"3-D Dim");
            H5SsetSpace(dim_id,3,dims);

            /* Create & initialize the dataset object */
            dataset_id=H5Mcreate(file_id,H5OBJ_DATASET,"Compound Multi-Dim Object");
            H5DsetInfo(dataset_id,type_id,dim_id);

            <initialize data array>

            /* Write the entire dataset out */
            H5Dwrite(dataset_id,H5S_SCALAR,data);

            /* Release the atoms we've created */
            H5Mrelease(type_id);
            H5Mrelease(dim_id);
            H5Mrelease(dataset_id);

            /* close the file */
            H5Fclose(file_id);
          }

## Example showing how read a generic dataset.

Notes:
This example shows how to get the information for and display a generic dataset.

Code: ``

        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=H5Fopen("example6.h5",0))>=0)
          {
            /* Attach to a datatype object */
            dataset_id=H5MaccessByIndex(obj_oid,0);

            if(H5TbaseType(dataset_id)==H5T_COMPOUND)
              {
                <set up for compound object>
              }
            else
              {
                <set up for homogenous object>
              }

            elem_size=H5Tsize(dataset_id);
            nelems=H5Snelem(dataset_id);
            <allocate space based on element size and number of elements >

            /* Read in the dataset */
            H5Dwrite(dataset_id,H5S_SCALAR,data);
                <or>
            H5Dwrite(dataset_id,dataset_id,data);

            /* Release the atoms we've accessed */
            H5Mrelease(dataset_id);

            /* close the file */
            H5Fclose(file_id);
          }