From 099c5c9d7e7747ce197249dcda2062e209e28105 Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Fri, 9 Feb 2001 12:56:25 -0500 Subject: [svn-r3386] Purpose: Contains code examples from doc/H5.intro.html (Intro to HDF5). These were moved so that examples can be displayed in a separate browser window and viewed in parallel with reading the document. Platforms tested: IE 5 --- doc/html/Intro/IntroExamples.html | 2111 +++++++++++++++++++++++++++++++++++++ 1 file changed, 2111 insertions(+) create mode 100644 doc/html/Intro/IntroExamples.html diff --git a/doc/html/Intro/IntroExamples.html b/doc/html/Intro/IntroExamples.html new file mode 100644 index 0000000..b2f5da5 --- /dev/null +++ b/doc/html/Intro/IntroExamples.html @@ -0,0 +1,2111 @@ + + + + +Introduction to HDF5 + + + + + +

+ + + + +

+Introduction to HDF5
+HDF5 User Guide + +

+HDF5 Reference Manual
+Other HDF5 documents and links +

+ +

+ + +

Introduction to HDF5 -- Example Codes

+ + + +

+ + + + +

Table of Contents
+ + + + 1: Creating and writing a + dataset + + 2. Reading a hyperslab + + 3. Writing selected data + + 4. Working with compound datatypes + + 5. Creating and writing an extendible + + + dataset + + 6. Reading data + + 7. Creating groups + + +		+ + + + 8. Writing and reading + attributes + + 9. Creating and writing references + + + to objects + + 10. Reading references to objects + + 11. Creating and writing references + + + to dataset regions + + 12. Reading references to dataset + + + regions + +

+ +

+ + + +

Example 1: How to create a homogeneous multi-dimensional dataset and write it to a file.

This example creates a 2-dimensional HDF 5 dataset of little endian 32-bit integers. +

+
+/*  
+ *  This example writes data to the HDF5 file.
+ *  Data conversion is performed during write operation.  
+ */
+ 
+#include 
+
+#define FILE        "SDS.h5"
+#define DATASETNAME "IntArray" 
+#define NX     5                      /* dataset dimensions */
+#define NY     6
+#define RANK   2
+
+int
+main (void)
+{
+    hid_t       file, dataset;         /* file and dataset handles */
+    hid_t       datatype, dataspace;   /* handles */
+    hsize_t     dimsf[2];              /* dataset dimensions */
+    herr_t      status;                             
+    int         data[NX][NY];          /* data to write */
+    int         i, j;
+
+    /* 
+     * Data  and output buffer initialization. 
+     */
+    for (j = 0; j < NX; j++) {
+	for (i = 0; i < NY; i++)
+	    data[j][i] = i + j;
+    }     
+    /*
+     * 0 1 2 3 4 5 
+     * 1 2 3 4 5 6
+     * 2 3 4 5 6 7
+     * 3 4 5 6 7 8
+     * 4 5 6 7 8 9
+     */
+
+    /*
+     * Create a new file using H5F_ACC_TRUNC access,
+     * default file creation properties, and default file
+     * access properties.
+     */
+    file = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+
+    /*
+     * Describe the size of the array and create the data space for fixed
+     * size dataset. 
+     */
+    dimsf[0] = NX;
+    dimsf[1] = NY;
+    dataspace = H5Screate_simple(RANK, dimsf, NULL); 
+
+    /* 
+     * Define datatype for the data in the file.
+     * We will store little endian INT numbers.
+     */
+    datatype = H5Tcopy(H5T_NATIVE_INT);
+    status = H5Tset_order(datatype, H5T_ORDER_LE);
+
+    /*
+     * Create a new dataset within the file using defined dataspace and
+     * datatype and default dataset creation properties.
+     */
+    dataset = H5Dcreate(file, DATASETNAME, datatype, dataspace,
+			H5P_DEFAULT);
+
+    /*
+     * Write the data to the dataset using default transfer properties.
+     */
+    status = H5Dwrite(dataset, H5T_NATIVE_INT, H5S_ALL, H5S_ALL,
+		      H5P_DEFAULT, data);
+
+    /*
+     * Close/release resources.
+     */
+    H5Sclose(dataspace);
+    H5Tclose(datatype);
+    H5Dclose(dataset);
+    H5Fclose(file);
+ 
+    return 0;
+}     
+

+ + + + +

(Return to TOC) + + + +

Example 2. How to read a hyperslab from file into memory.

This example reads a hyperslab from a 2-d HDF5 dataset into a 3-d dataset in memory. +

+
+/*  
+ *   This example reads hyperslab from the SDS.h5 file 
+ *   created by h5_write.c program into two-dimensional
+ *   plane of the three-dimensional array. 
+ *   Information about dataset in the SDS.h5 file is obtained. 
+ */
+ 
+#include "hdf5.h"
+
+#define FILE        "SDS.h5"
+#define DATASETNAME "IntArray" 
+#define NX_SUB  3           /* hyperslab dimensions */ 
+#define NY_SUB  4 
+#define NX 7           /* output buffer dimensions */ 
+#define NY 7 
+#define NZ  3 
+#define RANK         2
+#define RANK_OUT     3
+
+int
+main (void)
+{
+    hid_t       file, dataset;         /* handles */
+    hid_t       datatype, dataspace;   
+    hid_t       memspace; 
+    H5T_class_t class;                 /* datatype class */
+    H5T_order_t order;                 /* data order */
+    size_t      size;                  /*
+				        * size of the data element	       
+				        * stored in file
+				        */
+    hsize_t     dimsm[3];              /* memory space dimensions */
+    hsize_t     dims_out[2];           /* dataset dimensions */      
+    herr_t      status;                             
+
+    int         data_out[NX][NY][NZ ]; /* output buffer */
+   
+    hsize_t      count[2];              /* size of the hyperslab in the file */
+    hssize_t     offset[2];             /* hyperslab offset in the file */
+    hsize_t      count_out[3];          /* size of the hyperslab in memory */
+    hssize_t     offset_out[3];         /* hyperslab offset in memory */
+    int          i, j, k, status_n, rank;
+
+    for (j = 0; j < NX; j++) {
+	for (i = 0; i < NY; i++) {
+	    for (k = 0; k < NZ ; k++)
+		data_out[j][i][k] = 0;
+	}
+    } 
+ 
+    /*
+     * Open the file and the dataset.
+     */
+    file = H5Fopen(FILE, H5F_ACC_RDONLY, H5P_DEFAULT);
+    dataset = H5Dopen(file, DATASETNAME);
+
+    /*
+     * Get datatype and dataspace handles and then query
+     * dataset class, order, size, rank and dimensions.
+     */
+    datatype  = H5Dget_type(dataset);     /* datatype handle */ 
+    class     = H5Tget_class(datatype);
+    if (class == H5T_INTEGER) printf("Data set has INTEGER type \n");
+    order     = H5Tget_order(datatype);
+    if (order == H5T_ORDER_LE) printf("Little endian order \n");
+
+    size  = H5Tget_size(datatype);
+    printf(" Data size is %d \n", size);
+
+    dataspace = H5Dget_space(dataset);    /* dataspace handle */
+    rank      = H5Sget_simple_extent_ndims(dataspace);
+    status_n  = H5Sget_simple_extent_dims(dataspace, dims_out, NULL);
+    printf("rank %d, dimensions %lu x %lu \n", rank,
+	   (unsigned long)(dims_out[0]), (unsigned long)(dims_out[1]));
+
+    /* 
+     * Define hyperslab in the dataset. 
+     */
+    offset[0] = 1;
+    offset[1] = 2;
+    count[0]  = NX_SUB;
+    count[1]  = NY_SUB;
+    status = H5Sselect_hyperslab(dataspace, H5S_SELECT_SET, offset, NULL, 
+				 count, NULL);
+
+    /*
+     * Define the memory dataspace.
+     */
+    dimsm[0] = NX;
+    dimsm[1] = NY;
+    dimsm[2] = NZ ;
+    memspace = H5Screate_simple(RANK_OUT,dimsm,NULL);   
+
+    /* 
+     * Define memory hyperslab. 
+     */
+    offset_out[0] = 3;
+    offset_out[1] = 0;
+    offset_out[2] = 0;
+    count_out[0]  = NX_SUB;
+    count_out[1]  = NY_SUB;
+    count_out[2]  = 1;
+    status = H5Sselect_hyperslab(memspace, H5S_SELECT_SET, offset_out, NULL, 
+				 count_out, NULL);
+
+    /*
+     * Read data from hyperslab in the file into the hyperslab in 
+     * memory and display.
+     */
+    status = H5Dread(dataset, H5T_NATIVE_INT, memspace, dataspace,
+		     H5P_DEFAULT, data_out);
+    for (j = 0; j < NX; j++) {
+	for (i = 0; i < NY; i++) printf("%d ", data_out[j][i][0]);
+	printf("\n");
+    }
+    /*
+     * 0 0 0 0 0 0 0
+     * 0 0 0 0 0 0 0
+     * 0 0 0 0 0 0 0
+     * 3 4 5 6 0 0 0  
+     * 4 5 6 7 0 0 0
+     * 5 6 7 8 0 0 0
+     * 0 0 0 0 0 0 0
+     */
+
+    /*
+     * Close/release resources.
+     */
+    H5Tclose(datatype);
+    H5Dclose(dataset);
+    H5Sclose(dataspace);
+    H5Sclose(memspace);
+    H5Fclose(file);
+
+    return 0;
+}     
+

+ + + + + +

(Return to TOC) + + +

Example 3. Writing selected data from memory to a file.

This example shows how to use the selection capabilities of HDF5 to write selected data to a file. It includes the examples discussed in the text. + +

+
+/* 
+ *  This program shows how the H5Sselect_hyperslab and H5Sselect_elements
+ *  functions are used to write selected data from memory to the file.
+ *  Program takes 48 elements from the linear buffer and writes them into
+ *  the matrix using 3x2 blocks, (4,3) stride and (2,4) count. 
+ *  Then four elements  of the matrix are overwritten with the new values and 
+ *  file is closed. Program reopens the file and reads and displays the result.
+ */ 
+ 
+#include 
+
+#define FILE "Select.h5"
+
+#define MSPACE1_RANK     1          /* Rank of the first dataset in memory */
+#define MSPACE1_DIM      50         /* Dataset size in memory */ 
+
+#define MSPACE2_RANK     1          /* Rank of the second dataset in memory */ 
+#define MSPACE2_DIM      4          /* Dataset size in memory */ 
+
+#define FSPACE_RANK      2          /* Dataset rank as it is stored in the file */
+#define FSPACE_DIM1      8          /* Dimension sizes of the dataset as it is
+                                       stored in the file */
+#define FSPACE_DIM2      12 
+
+                                    /* We will read dataset back from the file
+                                       to the dataset in memory with these
+                                       dataspace parameters. */  
+#define MSPACE_RANK      2
+#define MSPACE_DIM1      8 
+#define MSPACE_DIM2      12 
+
+#define NPOINTS          4          /* Number of points that will be selected 
+                                       and overwritten */ 
+int main (void)
+{
+
+   hid_t   file, dataset;           /* File and dataset identifiers */
+   hid_t   mid1, mid2, fid;         /* Dataspace identifiers */
+   hsize_t dim1[] = {MSPACE1_DIM};  /* Dimension size of the first dataset 
+                                       (in memory) */ 
+   hsize_t dim2[] = {MSPACE2_DIM};  /* Dimension size of the second dataset
+                                       (in memory */ 
+   hsize_t fdim[] = {FSPACE_DIM1, FSPACE_DIM2}; 
+                                    /* Dimension sizes of the dataset (on disk) */
+
+   hssize_t start[2]; /* Start of hyperslab */
+   hsize_t stride[2]; /* Stride of hyperslab */
+   hsize_t count[2];  /* Block count */
+   hsize_t block[2];  /* Block sizes */
+
+   hssize_t coord[NPOINTS][FSPACE_RANK]; /* Array to store selected points 
+                                            from the file dataspace */ 
+   herr_t  ret;
+   uint    i,j;
+   int     matrix[MSPACE_DIM1][MSPACE_DIM2];
+   int     vector[MSPACE1_DIM];
+   int     values[] = {53, 59, 61, 67};  /* New values to be written */
+
+   /*
+    * Buffers' initialization.
+    */
+   vector[0] = vector[MSPACE1_DIM - 1] = -1;
+   for (i = 1; i < MSPACE1_DIM - 1; i++) vector[i] = i;
+
+   for (i = 0; i < MSPACE_DIM1; i++) {
+       for (j = 0; j < MSPACE_DIM2; j++)
+       matrix[i][j] = 0;
+    }
+
+    /*
+     * Create a file.
+     */
+    file = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+
+    /* 
+     * Create dataspace for the dataset in the file.
+     */
+    fid = H5Screate_simple(FSPACE_RANK, fdim, NULL);
+
+    /*
+     * Create dataset and write it into the file.
+     */
+    dataset = H5Dcreate(file, "Matrix in file", H5T_NATIVE_INT, fid, H5P_DEFAULT);
+    ret = H5Dwrite(dataset, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, matrix);
+
+    /*
+     * Select hyperslab for the dataset in the file, using 3x2 blocks, 
+     * (4,3) stride and (2,4) count starting at the position (0,1).
+     */
+    start[0]  = 0; start[1]  = 1;
+    stride[0] = 4; stride[1] = 3;
+    count[0]  = 2; count[1]  = 4;    
+    block[0]  = 3; block[1]  = 2;
+    ret = H5Sselect_hyperslab(fid, H5S_SELECT_SET, start, stride, count, block);
+
+    /*
+     * Create dataspace for the first dataset.
+     */
+    mid1 = H5Screate_simple(MSPACE1_RANK, dim1, NULL);
+
+    /*
+     * Select hyperslab. 
+     * We will use 48 elements of the vector buffer starting at the second element.
+     * Selected elements are 1 2 3 . . . 48
+     */
+    start[0]  = 1;
+    stride[0] = 1;
+    count[0]  = 48;
+    block[0]  = 1;
+    ret = H5Sselect_hyperslab(mid1, H5S_SELECT_SET, start, stride, count, block);
+ 
+    /*
+     * Write selection from the vector buffer to the dataset in the file.
+     *
+     * File dataset should look like this:       
+     *                    0  1  2  0  3  4  0  5  6  0  7  8 
+     *                    0  9 10  0 11 12  0 13 14  0 15 16
+     *                    0 17 18  0 19 20  0 21 22  0 23 24
+     *                    0  0  0  0  0  0  0  0  0  0  0  0
+     *                    0 25 26  0 27 28  0 29 30  0 31 32
+     *                    0 33 34  0 35 36  0 37 38  0 39 40
+     *                    0 41 42  0 43 44  0 45 46  0 47 48
+     *                    0  0  0  0  0  0  0  0  0  0  0  0
+     */
+     ret = H5Dwrite(dataset, H5T_NATIVE_INT, mid1, fid, H5P_DEFAULT, vector);
+
+    /*
+     * Reset the selection for the file dataspace fid.
+     */
+    ret = H5Sselect_none(fid);
+
+    /*
+     * Create dataspace for the second dataset.
+     */
+    mid2 = H5Screate_simple(MSPACE2_RANK, dim2, NULL);
+
+    /*
+     * Select sequence of NPOINTS points in the file dataspace.
+     */
+    coord[0][0] = 0; coord[0][1] = 0;
+    coord[1][0] = 3; coord[1][1] = 3;
+    coord[2][0] = 3; coord[2][1] = 5;
+    coord[3][0] = 5; coord[3][1] = 6;
+
+    ret = H5Sselect_elements(fid, H5S_SELECT_SET, NPOINTS, 
+                             (const hssize_t **)coord);
+
+    /*
+     * Write new selection of points to the dataset.
+     */
+    ret = H5Dwrite(dataset, H5T_NATIVE_INT, mid2, fid, H5P_DEFAULT, values);   
+
+    /*
+     * File dataset should look like this:     
+     *                   53  1  2  0  3  4  0  5  6  0  7  8 
+     *                    0  9 10  0 11 12  0 13 14  0 15 16
+     *                    0 17 18  0 19 20  0 21 22  0 23 24
+     *                    0  0  0 59  0 61  0  0  0  0  0  0
+     *                    0 25 26  0 27 28  0 29 30  0 31 32
+     *                    0 33 34  0 35 36 67 37 38  0 39 40
+     *                    0 41 42  0 43 44  0 45 46  0 47 48
+     *                    0  0  0  0  0  0  0  0  0  0  0  0
+     *                                        
+     */
+   
+    /*
+     * Close memory file and memory dataspaces.
+     */
+    ret = H5Sclose(mid1); 
+    ret = H5Sclose(mid2); 
+    ret = H5Sclose(fid); 
+ 
+    /*
+     * Close dataset.
+     */
+    ret = H5Dclose(dataset);
+
+    /*
+     * Close the file.
+     */
+    ret = H5Fclose(file);
+
+    /*
+     * Open the file.
+     */
+    file = H5Fopen(FILE, H5F_ACC_RDONLY, H5P_DEFAULT);
+
+    /*
+     * Open the dataset.
+     */
+    dataset = dataset = H5Dopen(file,"Matrix in file");
+
+    /*
+     * Read data back to the buffer matrix.
+     */
+    ret = H5Dread(dataset, H5T_NATIVE_INT, H5S_ALL, H5S_ALL,
+                  H5P_DEFAULT, matrix);
+
+    /*
+     * Display the result.
+     */
+    for (i=0; i < MSPACE_DIM1; i++) {
+        for(j=0; j < MSPACE_DIM2; j++) printf("%3d  ", matrix[i][j]);
+        printf("\n");
+    }
+
+    return 0;
+}
+

+ + + + +

(Return to TOC) + + +

Example 4. Working with compound datatypes.

This example shows how to create a compound datatype, write an array which has the compound datatype to the file, and read back subsets of fields. +

+
+/*
+ * This example shows how to create a compound datatype,
+ * write an array which has the compound datatype to the file,
+ * and read back fields' subsets.
+ */
+
+#include "hdf5.h"
+
+#define FILE          "SDScompound.h5"
+#define DATASETNAME   "ArrayOfStructures"
+#define LENGTH        10
+#define RANK          1
+
+int
+main(void)
+{
+
+    /* First structure  and dataset*/
+    typedef struct s1_t {
+	int    a;
+	float  b;
+	double c; 
+    } s1_t;
+    s1_t       s1[LENGTH];
+    hid_t      s1_tid;     /* File datatype identifier */
+
+    /* Second structure (subset of s1_t)  and dataset*/
+    typedef struct s2_t {
+	double c;
+	int    a;
+    } s2_t;
+    s2_t       s2[LENGTH];
+    hid_t      s2_tid;    /* Memory datatype handle */
+
+    /* Third "structure" ( will be used to read float field of s1) */
+    hid_t      s3_tid;   /* Memory datatype handle */
+    float      s3[LENGTH];
+
+    int        i;
+    hid_t      file, dataset, space; /* Handles */
+    herr_t     status;
+    hsize_t    dim[] = {LENGTH};   /* Dataspace dimensions */
+
+
+    /*
+     * Initialize the data
+     */
+    for (i = 0; i< LENGTH; i++) {
+        s1[i].a = i;
+        s1[i].b = i*i;
+        s1[i].c = 1./(i+1);
+    }
+
+    /*
+     * Create the data space.
+     */
+    space = H5Screate_simple(RANK, dim, NULL);
+
+    /*
+     * Create the file.
+     */
+    file = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+
+    /*
+     * Create the memory datatype. 
+     */
+    s1_tid = H5Tcreate (H5T_COMPOUND, sizeof(s1_t));
+    H5Tinsert(s1_tid, "a_name", HOFFSET(s1_t, a), H5T_NATIVE_INT);
+    H5Tinsert(s1_tid, "c_name", HOFFSET(s1_t, c), H5T_NATIVE_DOUBLE);
+    H5Tinsert(s1_tid, "b_name", HOFFSET(s1_t, b), H5T_NATIVE_FLOAT);
+
+    /* 
+     * Create the dataset.
+     */
+    dataset = H5Dcreate(file, DATASETNAME, s1_tid, space, H5P_DEFAULT);
+
+    /*
+     * Wtite data to the dataset; 
+     */
+    status = H5Dwrite(dataset, s1_tid, H5S_ALL, H5S_ALL, H5P_DEFAULT, s1);
+
+    /*
+     * Release resources
+     */
+    H5Tclose(s1_tid);
+    H5Sclose(space);
+    H5Dclose(dataset);
+    H5Fclose(file);
+ 
+    /*
+     * Open the file and the dataset.
+     */
+    file = H5Fopen(FILE, H5F_ACC_RDONLY, H5P_DEFAULT);
+ 
+    dataset = H5Dopen(file, DATASETNAME);
+
+    /* 
+     * Create a datatype for s2
+     */
+    s2_tid = H5Tcreate(H5T_COMPOUND, sizeof(s2_t));
+
+    H5Tinsert(s2_tid, "c_name", HOFFSET(s2_t, c), H5T_NATIVE_DOUBLE);
+    H5Tinsert(s2_tid, "a_name", HOFFSET(s2_t, a), H5T_NATIVE_INT);
+
+    /*
+     * Read two fields c and a from s1 dataset. Fields in the file
+     * are found by their names "c_name" and "a_name".
+     */
+    status = H5Dread(dataset, s2_tid, H5S_ALL, H5S_ALL, H5P_DEFAULT, s2);
+
+    /*
+     * Display the fields
+     */
+    printf("\n");
+    printf("Field c : \n");
+    for( i = 0; i < LENGTH; i++) printf("%.4f ", s2[i].c);
+    printf("\n");
+
+    printf("\n");
+    printf("Field a : \n");
+    for( i = 0; i < LENGTH; i++) printf("%d ", s2[i].a);
+    printf("\n");
+
+    /* 
+     * Create a datatype for s3.
+     */
+    s3_tid = H5Tcreate(H5T_COMPOUND, sizeof(float));
+
+    status = H5Tinsert(s3_tid, "b_name", 0, H5T_NATIVE_FLOAT);
+
+    /*
+     * Read field b from s1 dataset. Field in the file is found by its name.
+     */
+    status = H5Dread(dataset, s3_tid, H5S_ALL, H5S_ALL, H5P_DEFAULT, s3);
+
+    /*
+     * Display the field
+     */
+    printf("\n");
+    printf("Field b : \n");
+    for( i = 0; i < LENGTH; i++) printf("%.4f ", s3[i]);
+    printf("\n");
+
+    /*
+     * Release resources
+     */
+    H5Tclose(s2_tid);
+    H5Tclose(s3_tid);
+    H5Dclose(dataset);
+    H5Fclose(file);
+
+    return 0;
+}
+

+ + + + +

(Return to TOC) + + +

Example 5. Creating and writing an extendible dataset.

This example shows how to create a 3x3 extendible dataset, to extend the dataset to 10x3, then to extend it again to 10x5. +

+
+/*  
+ *   This example shows how to work with extendible dataset.
+ *   In the current version of the library dataset MUST be
+ *   chunked.
+ *   
+ */
+ 
+#include "hdf5.h"
+
+#define FILE        "SDSextendible.h5"
+#define DATASETNAME "ExtendibleArray" 
+#define RANK         2
+#define NX     10
+#define NY     5 
+
+int
+main (void)
+{
+    hid_t       file;                          /* handles */
+    hid_t       dataspace, dataset;  
+    hid_t       filespace;                   
+    hid_t       cparms;                     
+    hsize_t      dims[2]  = { 3, 3};            /*
+						 * dataset dimensions				
+						 * at the creation time
+						 */
+    hsize_t      dims1[2] = { 3, 3};            /* data1 dimensions */ 
+    hsize_t      dims2[2] = { 7, 1};            /* data2 dimensions */  
+    hsize_t      dims3[2] = { 2, 2};            /* data3 dimensions */ 
+
+    hsize_t      maxdims[2] = {H5S_UNLIMITED, H5S_UNLIMITED};
+    hsize_t      chunk_dims[2] ={2, 5};
+    hsize_t      size[2];
+    hssize_t     offset[2];
+
+    herr_t      status;                             
+
+    int         data1[3][3] = { {1, 1, 1},       /* data to write */
+				{1, 1, 1},
+				{1, 1, 1} };      
+
+    int         data2[7]    = { 2, 2, 2, 2, 2, 2, 2};
+
+    int         data3[2][2] = { {3, 3},
+				{3, 3} };
+
+    /*
+     * Create the data space with unlimited dimensions. 
+     */
+    dataspace = H5Screate_simple(RANK, dims, maxdims); 
+
+    /*
+     * Create a new file. If file exists its contents will be overwritten.
+     */
+    file = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+
+    /* 
+     * Modify dataset creation properties, i.e. enable chunking.
+     */
+    cparms = H5Pcreate (H5P_DATASET_CREATE);
+    status = H5Pset_chunk( cparms, RANK, chunk_dims);
+
+    /*
+     * Create a new dataset within the file using cparms
+     * creation properties.
+     */
+    dataset = H5Dcreate(file, DATASETNAME, H5T_NATIVE_INT, dataspace,
+			cparms);
+
+    /*
+     * Extend the dataset. This call assures that dataset is at least 3 x 3.
+     */
+    size[0]   = 3; 
+    size[1]   = 3; 
+    status = H5Dextend (dataset, size);
+
+    /*
+     * Select a hyperslab.
+     */
+    filespace = H5Dget_space (dataset);
+    offset[0] = 0;
+    offset[1] = 0;
+    status = H5Sselect_hyperslab(filespace, H5S_SELECT_SET, offset, NULL,
+				 dims1, NULL);  
+
+    /*
+     * Write the data to the hyperslab.
+     */
+    status = H5Dwrite(dataset, H5T_NATIVE_INT, dataspace, filespace,
+		      H5P_DEFAULT, data1);
+
+    /*
+     * Extend the dataset. Dataset becomes 10 x 3.
+     */
+    dims[0]   = dims1[0] + dims2[0];
+    size[0]   = dims[0];  
+    size[1]   = dims[1]; 
+    status = H5Dextend (dataset, size);
+
+    /*
+     * Select a hyperslab.
+     */
+    filespace = H5Dget_space (dataset);
+    offset[0] = 3;
+    offset[1] = 0;
+    status = H5Sselect_hyperslab(filespace, H5S_SELECT_SET, offset, NULL,
+				 dims2, NULL);  
+
+    /*
+     * Define memory space
+     */
+    dataspace = H5Screate_simple(RANK, dims2, NULL); 
+
+    /*
+     * Write the data to the hyperslab.
+     */
+    status = H5Dwrite(dataset, H5T_NATIVE_INT, dataspace, filespace,
+		      H5P_DEFAULT, data2);
+
+    /*
+     * Extend the dataset. Dataset becomes 10 x 5.
+     */
+    dims[1]   = dims1[1] + dims3[1];
+    size[0]   = dims[0];  
+    size[1]   = dims[1]; 
+    status = H5Dextend (dataset, size);
+
+    /*
+     * Select a hyperslab
+     */
+    filespace = H5Dget_space (dataset);
+    offset[0] = 0;
+    offset[1] = 3;
+    status = H5Sselect_hyperslab(filespace, H5S_SELECT_SET, offset, NULL, 
+				 dims3, NULL);  
+
+    /*
+     * Define memory space.
+     */
+    dataspace = H5Screate_simple(RANK, dims3, NULL); 
+
+    /*
+     * Write the data to the hyperslab.
+     */
+    status = H5Dwrite(dataset, H5T_NATIVE_INT, dataspace, filespace,
+		      H5P_DEFAULT, data3);
+
+    /*
+     * Resulting dataset
+     * 
+     *	 3 3 3 2 2
+     *	 3 3 3 2 2
+     *	 3 3 3 0 0
+     *	 2 0 0 0 0
+     *	 2 0 0 0 0
+     *	 2 0 0 0 0
+     *	 2 0 0 0 0
+     *	 2 0 0 0 0
+     *	 2 0 0 0 0
+     *	 2 0 0 0 0
+     */
+    /*
+     * Close/release resources.
+     */
+    H5Dclose(dataset);
+    H5Sclose(dataspace);
+    H5Sclose(filespace);
+    H5Fclose(file);
+
+    return 0;
+}     
+

+ + + + +

(Return to TOC) + + +

Example 6. Reading data.

This example shows how to read information the chunked dataset written by Example 5. +

+
+/*  
+ *   This example shows how to read data from a chunked dataset.
+ *   We will read from the file created by h5_extend_write.c 
+ */
+ 
+#include "hdf5.h"
+
+#define FILE        "SDSextendible.h5"
+#define DATASETNAME "ExtendibleArray" 
+#define RANK         2
+#define RANKC        1
+#define NX           10
+#define NY           5 
+
+int
+main (void)
+{
+    hid_t       file;                        /* handles */
+    hid_t       dataset;  
+    hid_t       filespace;                   
+    hid_t       memspace;                  
+    hid_t       cparms;                   
+    hsize_t     dims[2];                     /* dataset and chunk dimensions*/ 
+    hsize_t     chunk_dims[2];
+    hsize_t     col_dims[1];
+    hsize_t     count[2];
+    hssize_t    offset[2];
+
+    herr_t      status, status_n;                             
+
+    int         data_out[NX][NY];  /* buffer for dataset to be read */
+    int         chunk_out[2][5];   /* buffer for chunk to be read */
+    int         column[10];        /* buffer for column to be read */
+    int         rank, rank_chunk;
+    hsize_t	i, j;
+    
+
+ 
+    /*
+     * Open the file and the dataset.
+     */
+    file = H5Fopen(FILE, H5F_ACC_RDONLY, H5P_DEFAULT);
+    dataset = H5Dopen(file, DATASETNAME);
+ 
+    /*
+     * Get dataset rank and dimension.
+     */
+
+    filespace = H5Dget_space(dataset);    /* Get filespace handle first. */
+    rank      = H5Sget_simple_extent_ndims(filespace);
+    status_n  = H5Sget_simple_extent_dims(filespace, dims, NULL);
+    printf("dataset rank %d, dimensions %lu x %lu\n",
+	   rank, (unsigned long)(dims[0]), (unsigned long)(dims[1]));
+
+    /*
+     * Get creation properties list.
+     */
+    cparms = H5Dget_create_plist(dataset); /* Get properties handle first. */
+
+    /* 
+     * Check if dataset is chunked.
+     */
+    if (H5D_CHUNKED == H5Pget_layout(cparms))  {
+
+	/*
+	 * Get chunking information: rank and dimensions
+	 */
+	rank_chunk = H5Pget_chunk(cparms, 2, chunk_dims);
+	printf("chunk rank %d, dimensions %lu x %lu\n", rank_chunk,
+	       (unsigned long)(chunk_dims[0]), (unsigned long)(chunk_dims[1]));
+    }
+ 
+    /*
+     * Define the memory space to read dataset.
+     */
+    memspace = H5Screate_simple(RANK,dims,NULL);
+ 
+    /*
+     * Read dataset back and display.
+     */
+    status = H5Dread(dataset, H5T_NATIVE_INT, memspace, filespace,
+		     H5P_DEFAULT, data_out);
+    printf("\n");
+    printf("Dataset: \n");
+    for (j = 0; j < dims[0]; j++) {
+	for (i = 0; i < dims[1]; i++) printf("%d ", data_out[j][i]);
+	printf("\n");
+    }     
+
+    /*
+     *	    dataset rank 2, dimensions 10 x 5 
+     *	    chunk rank 2, dimensions 2 x 5 
+
+     *	    Dataset:
+     *	    1 1 1 3 3 
+     *	    1 1 1 3 3 
+     *	    1 1 1 0 0 
+     *	    2 0 0 0 0 
+     *	    2 0 0 0 0 
+     *	    2 0 0 0 0 
+     *	    2 0 0 0 0 
+     *	    2 0 0 0 0 
+     *	    2 0 0 0 0 
+     *	    2 0 0 0 0 
+     */
+
+    /*
+     * Read the third column from the dataset.
+     * First define memory dataspace, then define hyperslab
+     * and read it into column array.
+     */
+    col_dims[0] = 10;
+    memspace =  H5Screate_simple(RANKC, col_dims, NULL);
+
+    /*
+     * Define the column (hyperslab) to read.
+     */
+    offset[0] = 0;
+    offset[1] = 2;
+    count[0]  = 10;
+    count[1]  = 1;
+    status = H5Sselect_hyperslab(filespace, H5S_SELECT_SET, offset, NULL,
+				 count, NULL);
+    status = H5Dread(dataset, H5T_NATIVE_INT, memspace, filespace,
+		     H5P_DEFAULT, column);
+    printf("\n");
+    printf("Third column: \n");
+    for (i = 0; i < 10; i++) {
+	printf("%d \n", column[i]);
+    }
+
+    /*
+     *	    Third column: 
+     *	    1 
+     *	    1 
+     *	    1 
+     *	    0 
+     *	    0 
+     *	    0 
+     *	    0 
+     *	    0 
+     *	    0 
+     *	    0 
+     */
+
+    /*
+     * Define the memory space to read a chunk.
+     */
+    memspace = H5Screate_simple(rank_chunk,chunk_dims,NULL);
+
+    /*
+     * Define chunk in the file (hyperslab) to read.
+     */
+    offset[0] = 2;
+    offset[1] = 0;
+    count[0]  = chunk_dims[0];
+    count[1]  = chunk_dims[1];
+    status = H5Sselect_hyperslab(filespace, H5S_SELECT_SET, offset, NULL, 
+				 count, NULL);
+
+    /*
+     * Read chunk back and display.
+     */
+    status = H5Dread(dataset, H5T_NATIVE_INT, memspace, filespace,
+		     H5P_DEFAULT, chunk_out);
+    printf("\n");
+    printf("Chunk: \n");
+    for (j = 0; j < chunk_dims[0]; j++) {
+	for (i = 0; i < chunk_dims[1]; i++) printf("%d ", chunk_out[j][i]);
+	printf("\n");
+    }     
+    /*
+     *	 Chunk: 
+     *	 1 1 1 0 0 
+     *	 2 0 0 0 0 
+     */
+
+    /*
+     * Close/release resources.
+     */
+    H5Pclose(cparms);
+    H5Dclose(dataset);
+    H5Sclose(filespace);
+    H5Sclose(memspace);
+    H5Fclose(file);
+
+    return 0;
+)
+
+

+ + + + +

(Return to TOC) + + +

Example 7. Creating groups.

This example shows how to create and access a group in an +HDF5 file and to place a dataset within this group. +It also illustrates the usage of the H5Giterate, +H5Glink, and H5Gunlink functions. + +

+
+/*
+ * This example creates a group in the file and dataset in the group. 
+ * Hard link to the group object is created and the dataset is accessed
+ * under different names. 
+ * Iterator function is used to find the object names in the root group.
+ */ 
+
+
+#include "hdf5.h"
+
+
+#define FILE    "group.h5"
+#define RANK    2
+
+ 
+herr_t file_info(hid_t loc_id, const char *name, void *opdata);
+                                     /* Operator function */
+int
+main(void)
+{
+
+    hid_t    file;
+    hid_t    grp;
+    hid_t    dataset, dataspace;
+    hid_t    plist; 
+
+    herr_t   status;
+    hsize_t  dims[2];
+    hsize_t  cdims[2];
+ 
+    int      idx;
+
+    /*
+     * Create a file.
+     */
+    file = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+
+    /*
+     * Create a group in the file. 
+     */
+    grp = H5Gcreate(file, "/Data", 0);
+
+    /*
+     * Create dataset "Compressed Data" in the group using absolute
+     * name. Dataset creation property list is modified to use 
+     * GZIP compression with the compression effort set to 6. 
+     * Note that compression can be used only when dataset is chunked. 
+     */
+    dims[0] = 1000;
+    dims[1] = 20;
+    cdims[0] = 20;
+    cdims[1] = 20;
+    dataspace = H5Screate_simple(RANK, dims, NULL);
+    plist     = H5Pcreate(H5P_DATASET_CREATE);
+                H5Pset_chunk(plist, 2, cdims);
+                H5Pset_deflate( plist, 6); 
+    dataset = H5Dcreate(file, "/Data/Compressed_Data", H5T_NATIVE_INT, 
+                        dataspace, plist); 
+ 
+    /* 
+     * Close the dataset and the file.
+     */
+    H5Sclose(dataspace);
+    H5Dclose(dataset);
+    H5Fclose(file);
+
+    /*
+     * Now reopen the file and group in the file. 
+     */
+    file = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT);
+    grp  = H5Gopen(file, "Data");
+
+    /* 
+     * Access "Compressed_Data" dataset in the group. 
+     */
+    dataset = H5Dopen(grp, "Compressed_Data");
+    if( dataset < 0) printf(" Dataset is not found. \n");
+    printf("\"/Data/Compressed_Data\" dataset is open \n");
+
+    /*
+     * Close the dataset.
+     */
+    status = H5Dclose(dataset);
+
+    /*
+     * Create hard link to the Data group.
+     */
+    status = H5Glink(file, H5G_LINK_HARD, "Data", "Data_new");
+
+    /* 
+     * We can access "Compressed_Data" dataset using created
+     * hard link "Data_new". 
+     */
+    dataset = H5Dopen(file, "/Data_new/Compressed_Data");
+    if( dataset < 0) printf(" Dataset is not found. \n");
+    printf("\"/Data_new/Compressed_Data\" dataset is open \n");
+
+    /*
+     * Close the dataset.
+     */
+    status = H5Dclose(dataset);
+
+    /* 
+     * Use iterator to see the names of the objects in the file
+     * root directory.
+     */
+    idx = H5Giterate(file, "/", NULL, file_info, NULL);
+
+    /*
+     * Unlink  name "Data" and use iterator to see the names
+     * of the objects in the file root direvtory.
+     */
+    if (H5Gunlink(file, "Data") < 0)  
+      printf(" H5Gunlink failed \n");
+    else  
+      printf("\"Data\" is unlinked \n");
+
+    idx = H5Giterate(file, "/", NULL, file_info, NULL);
+    
+
+    /*
+     * Close the file.
+     */
+     
+    status = H5Fclose(file);
+
+    return 0;
+}
+/*
+ * Operator function.
+ */
+herr_t
+file_info(hid_t loc_id, const char *name, void *opdata)
+{
+    hid_t grp;
+    /*
+     * Open the group using its name.
+     */
+    grp = H5Gopen(loc_id, name);
+ 
+    /*
+     * Display group name.
+     */
+    printf("\n");
+    printf("Name : ");
+    puts(name);
+    
+    H5Gclose(grp);
+    return 0;
+ }
+

+ + + + +

(Return to TOC) + + +

Example 8. Writing and reading attributes.

This example shows how to create HDF5 attributes, to attach them to a dataset, and to read through all of the attributes of a dataset. + +

+
+/* 
+ *  This program illustrates the usage of the H5A Interface functions.
+ *  It creates and writes a dataset, and then creates and writes array,
+ *  scalar, and string attributes of the dataset. 
+ *  Program reopens the file, attaches to the scalar attribute using
+ *  attribute name and reads and displays its value. Then index of the
+ *  third attribute is used to read and display attribute values.
+ *  The H5Aiterate function is used to iterate through the dataset attributes,
+ *  and display their names. The function is also reads and displays the values 
+ *  of the array attribute. 
+ */ 
+ 
+#include 
+#include 
+
+#define FILE "Attributes.h5"
+
+#define RANK  1   /* Rank and size of the dataset  */ 
+#define SIZE  7
+
+#define ARANK  2   /* Rank and dimension sizes of the first dataset attribute */
+#define ADIM1  2
+#define ADIM2  3 
+#define ANAME  "Float attribute"      /* Name of the array attribute */
+#define ANAMES "Character attribute" /* Name of the string attribute */
+
+herr_t attr_info(hid_t loc_id, const char *name, void *opdata); 
+                                     /* Operator function */
+
+int 
+main (void)
+{
+
+   hid_t   file, dataset;       /* File and dataset identifiers */
+   
+   hid_t   fid;                 /* Dataspace identifier */
+   hid_t   attr1, attr2, attr3; /* Attribute identifiers */
+   hid_t   attr;
+   hid_t   aid1, aid2, aid3;    /* Attribute dataspace identifiers */ 
+   hid_t   atype;               /* Attribute type */
+
+   hsize_t fdim[] = {SIZE};
+   hsize_t adim[] = {ADIM1, ADIM2};  /* Dimensions of the first attribute  */
+   
+   float matrix[ADIM1][ADIM2]; /* Attribute data */ 
+
+   herr_t  ret;                /* Return value */
+   uint    i,j;                /* Counters */
+   int     idx;                /* Attribute index */
+   char    string_out[80];     /* Buffer to read string attribute back */
+   int     point_out;          /* Buffer to read scalar attribute back */
+
+   /*
+    * Data initialization.
+    */
+   int vector[] = {1, 2, 3, 4, 5, 6, 7};  /* Dataset data */
+   int point = 1;                         /* Value of the scalar attribute */ 
+   char string[] = "ABCD";                /* Value of the string attribute */
+
+   
+   for (i=0; i < ADIM1; i++) {            /* Values of the array attribute */
+       for (j=0; j < ADIM2; j++)
+       matrix[i][j] = -1.;
+   }
+
+   /*
+    * Create a file.
+    */
+   file = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+
+   /* 
+    * Create the dataspace for the dataset in the file.
+    */
+   fid = H5Screate(H5S_SIMPLE);
+   ret = H5Sset_extent_simple(fid, RANK, fdim, NULL);
+
+   /*
+    * Create the dataset in the file.
+    */
+   dataset = H5Dcreate(file, "Dataset", H5T_NATIVE_INT, fid, H5P_DEFAULT);
+
+   /*
+    * Write data to the dataset.
+    */
+   ret = H5Dwrite(dataset, H5T_NATIVE_INT, H5S_ALL , H5S_ALL, H5P_DEFAULT, vector);
+
+   /*
+    * Create dataspace for the first attribute. 
+    */
+   aid1 = H5Screate(H5S_SIMPLE);
+   ret  = H5Sset_extent_simple(aid1, ARANK, adim, NULL);
+
+   /*
+    * Create array attribute.
+    */
+   attr1 = H5Acreate(dataset, ANAME, H5T_NATIVE_FLOAT, aid1, H5P_DEFAULT);
+
+   /*
+    * Write array attribute.
+    */
+   ret = H5Awrite(attr1, H5T_NATIVE_FLOAT, matrix);
+
+   /*
+    * Create scalar attribute.
+    */
+   aid2  = H5Screate(H5S_SCALAR);
+   attr2 = H5Acreate(dataset, "Integer attribute", H5T_NATIVE_INT, aid2,
+                     H5P_DEFAULT);
+
+   /*
+    * Write scalar attribute.
+    */
+   ret = H5Awrite(attr2, H5T_NATIVE_INT, &point); 
+
+   /*
+    * Create string attribute.
+    */
+   aid3  = H5Screate(H5S_SCALAR);
+   atype = H5Tcopy(H5T_C_S1);
+           H5Tset_size(atype, 4);
+   attr3 = H5Acreate(dataset, ANAMES, atype, aid3, H5P_DEFAULT);
+
+   /*
+    * Write string attribute.
+    */
+   ret = H5Awrite(attr3, atype, string); 
+
+   /*
+    * Close attribute and file dataspaces.
+    */
+   ret = H5Sclose(aid1); 
+   ret = H5Sclose(aid2); 
+   ret = H5Sclose(aid3); 
+   ret = H5Sclose(fid); 
+
+   /*
+    * Close the attributes.
+    */ 
+   ret = H5Aclose(attr1);
+   ret = H5Aclose(attr2);
+   ret = H5Aclose(attr3);
+ 
+   /*
+    * Close the dataset.
+    */
+   ret = H5Dclose(dataset);
+
+   /*
+    * Close the file.
+    */
+   ret = H5Fclose(file);
+
+   /*
+    * Reopen the file.
+    */
+   file = H5Fopen(FILE, H5F_ACC_RDONLY, H5P_DEFAULT);
+
+   /*
+    * Open the dataset.
+    */
+   dataset = H5Dopen(file,"Dataset");
+
+   /*
+    * Attach to the scalar attribute using attribute name, then read and 
+    * display its value.
+    */
+   attr = H5Aopen_name(dataset,"Integer attribute");
+   ret  = H5Aread(attr, H5T_NATIVE_INT, &point_out);
+   printf("The value of the attribute \"Integer attribute\" is %d \n", point_out); 
+   ret =  H5Aclose(attr);
+
+   /*
+    * Attach to the string attribute using its index, then read and display the value.
+    */
+   attr  = H5Aopen_idx(dataset, 2);
+   atype = H5Tcopy(H5T_C_S1);
+           H5Tset_size(atype, 4);
+   ret   = H5Aread(attr, atype, string_out);
+   printf("The value of the attribute with the index 2 is %s \n", string_out);
+   ret   = H5Aclose(attr);
+   ret   = H5Tclose(atype);
+
+   /*
+    * Get attribute info using iteration function. 
+    */
+   idx = H5Aiterate(dataset, NULL, attr_info, NULL);
+
+   /*
+    * Close the dataset and the file.
+    */
+   H5Dclose(dataset);
+   H5Fclose(file);
+
+   return 0;  
+}
+
+/*
+ * Operator function.
+ */
+herr_t 
+attr_info(hid_t loc_id, const char *name, void *opdata)
+{
+    hid_t attr, atype, aspace;  /* Attribute, datatype and dataspace identifiers */
+    int   rank;
+    hsize_t sdim[64]; 
+    herr_t ret;
+    int i;
+    size_t npoints;             /* Number of elements in the array attribute. */ 
+    float *float_array;         /* Pointer to the array attribute. */
+    /*
+     * Open the attribute using its name.
+     */    
+    attr = H5Aopen_name(loc_id, name);
+
+    /*
+     * Display attribute name.
+     */
+    printf("\n");
+    printf("Name : ");
+    puts(name);
+
+    /* 
+     * Get attribute datatype, dataspace, rank, and dimensions.
+     */
+    atype  = H5Aget_type(attr);
+    aspace = H5Aget_space(attr);
+    rank = H5Sget_simple_extent_ndims(aspace);
+    ret = H5Sget_simple_extent_dims(aspace, sdim, NULL);
+
+    /*
+     *  Display rank and dimension sizes for the array attribute.
+     */
+
+    if(rank > 0) {
+    printf("Rank : %d \n", rank); 
+    printf("Dimension sizes : ");
+    for (i=0; i< rank; i++) printf("%d ", (int)sdim[i]);
+    printf("\n");
+    }
+
+    /*
+     * Read array attribute and display its type and values.
+     */
+
+    if (H5T_FLOAT == H5Tget_class(atype)) {
+    printf("Type : FLOAT \n"); 
+    npoints = H5Sget_simple_extent_npoints(aspace);
+    float_array = (float *)malloc(sizeof(float)*(int)npoints); 
+    ret = H5Aread(attr, atype, float_array);
+    printf("Values : ");
+    for( i = 0; i < (int)npoints; i++) printf("%f ", float_array[i]); 
+    printf("\n");
+    free(float_array);
+    }
+
+    /*
+     * Release all identifiers.
+     */
+    H5Tclose(atype);
+    H5Sclose(aspace);
+    H5Aclose(attr);
+
+    return 0;
+}
+

+ + + +

(Return to TOC) + + +

Example 9. Creating and storing references to objects.

+This example creates a group and two datasets and a named datatype +in the group. References to these four objects are stored in the dataset +in the root group. + +

+
+#include <hdf5.h>
+
+#define FILE1   "trefer1.h5"
+
+/* 1-D dataset with fixed dimensions */
+#define SPACE1_NAME  "Space1"
+#define SPACE1_RANK	1
+#define SPACE1_DIM1	4
+
+/* 2-D dataset with fixed dimensions */
+#define SPACE2_NAME  "Space2"
+#define SPACE2_RANK	2
+#define SPACE2_DIM1	10
+#define SPACE2_DIM2	10
+
+int 
+main(void) {
+    hid_t		fid1;		/* HDF5 File IDs		*/
+    hid_t		dataset;	/* Dataset ID			*/
+    hid_t		group;      /* Group ID             */
+    hid_t		sid1;       /* Dataspace ID			*/
+    hid_t		tid1;       /* Datatype ID			*/
+    hsize_t		dims1[] = {SPACE1_DIM1};
+    hobj_ref_t      *wbuf;      /* buffer to write to disk */
+    int       *tu32;      /* Temporary pointer to int data */
+    int        i;          /* counting variables */
+    const char *write_comment="Foo!"; /* Comments for group */
+    herr_t		ret;		/* Generic return value		*/
+
+/* Compound datatype */
+typedef struct s1_t {
+    unsigned int a;
+    unsigned int b;
+    float c;
+} s1_t;
+
+    /* Allocate write buffers */
+    wbuf=(hobj_ref_t *)malloc(sizeof(hobj_ref_t)*SPACE1_DIM1);
+    tu32=malloc(sizeof(int)*SPACE1_DIM1);
+
+    /* Create file */
+    fid1 = H5Fcreate(FILE1, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+
+    /* Create dataspace for datasets */
+    sid1 = H5Screate_simple(SPACE1_RANK, dims1, NULL);
+
+    /* Create a group */
+    group=H5Gcreate(fid1,"Group1",-1);
+
+    /* Set group's comment */
+    ret=H5Gset_comment(group,".",write_comment);
+
+    /* Create a dataset (inside Group1) */
+    dataset=H5Dcreate(group,"Dataset1",H5T_STD_U32LE,sid1,H5P_DEFAULT);
+
+    for(i=0; i < SPACE1_DIM1; i++)
+        tu32[i] = i*3;
+
+    /* Write selection to disk */
+    ret=H5Dwrite(dataset,H5T_NATIVE_INT,H5S_ALL,H5S_ALL,H5P_DEFAULT,tu32);
+
+    /* Close Dataset */
+    ret = H5Dclose(dataset);
+
+    /* Create another dataset (inside Group1) */
+    dataset=H5Dcreate(group,"Dataset2",H5T_NATIVE_UCHAR,sid1,H5P_DEFAULT);
+
+    /* Close Dataset */
+    ret = H5Dclose(dataset);
+
+    /* Create a datatype to refer to */
+    tid1 = H5Tcreate (H5T_COMPOUND, sizeof(s1_t));
+
+    /* Insert fields */
+    ret=H5Tinsert (tid1, "a", HOFFSET(s1_t,a), H5T_NATIVE_INT);
+
+    ret=H5Tinsert (tid1, "b", HOFFSET(s1_t,b), H5T_NATIVE_INT);
+
+    ret=H5Tinsert (tid1, "c", HOFFSET(s1_t,c), H5T_NATIVE_FLOAT);
+
+    /* Save datatype for later */
+    ret=H5Tcommit (group, "Datatype1", tid1);
+
+    /* Close datatype */
+    ret = H5Tclose(tid1);
+
+    /* Close group */
+    ret = H5Gclose(group);
+
+    /* Create a dataset to store references */
+    dataset=H5Dcreate(fid1,"Dataset3",H5T_STD_REF_OBJ,sid1,H5P_DEFAULT);
+
+    /* Create reference to dataset */
+    ret = H5Rcreate(&wbuf[0],fid1,"/Group1/Dataset1",H5R_OBJECT,-1);
+
+    /* Create reference to dataset */
+    ret = H5Rcreate(&wbuf[1],fid1,"/Group1/Dataset2",H5R_OBJECT,-1);
+
+    /* Create reference to group */
+    ret = H5Rcreate(&wbuf[2],fid1,"/Group1",H5R_OBJECT,-1);
+
+    /* Create reference to named datatype */
+    ret = H5Rcreate(&wbuf[3],fid1,"/Group1/Datatype1",H5R_OBJECT,-1);
+
+    /* Write selection to disk */
+    ret=H5Dwrite(dataset,H5T_STD_REF_OBJ,H5S_ALL,H5S_ALL,H5P_DEFAULT,wbuf);
+
+    /* Close disk dataspace */
+    ret = H5Sclose(sid1);
+    
+    /* Close Dataset */
+    ret = H5Dclose(dataset);
+
+    /* Close file */
+    ret = H5Fclose(fid1);
+    free(wbuf);
+    free(tu32);
+    return 0;
+}
+
+

+ + + + +

(Return to TOC) + + +

Example 10. Reading references to objects.

+This example opens and reads dataset Dataset3 from +the file created in Example 9. Then the program dereferences the references +to dataset Dataset1, the group and the named datatype, +and opens those objects. +The program reads and displays the dataset's data, the group's comment, and +the number of members of the compound datatype. + + +

+
+#include <stdlib.h>
+#include <hdf5.h>
+
+#define FILE1   "trefer1.h5"
+
+/* dataset with fixed dimensions */
+#define SPACE1_NAME  "Space1"
+#define SPACE1_RANK	1
+#define SPACE1_DIM1	4
+
+int 
+main(void)
+{
+    hid_t		fid1;		/* HDF5 File IDs		*/
+    hid_t		dataset,	/* Dataset ID			*/
+                dset2;      /* Dereferenced dataset ID */
+    hid_t		group;      /* Group ID             */
+    hid_t		sid1;       /* Dataspace ID			*/
+    hid_t		tid1;       /* Datatype ID			*/
+    hobj_ref_t      *rbuf;      /* buffer to read from disk */
+    int                *tu32;      /* temp. buffer read from disk */
+    int        i;          /* counting variables */
+    char read_comment[10];
+    herr_t		ret;		/* Generic return value		*/
+
+    /* Allocate read buffers */
+    rbuf = malloc(sizeof(hobj_ref_t)*SPACE1_DIM1);
+    tu32 = malloc(sizeof(int)*SPACE1_DIM1);
+
+    /* Open the file */
+    fid1 = H5Fopen(FILE1, H5F_ACC_RDWR, H5P_DEFAULT);
+
+    /* Open the dataset */
+    dataset=H5Dopen(fid1,"/Dataset3");
+
+    /* Read selection from disk */
+    ret=H5Dread(dataset,H5T_STD_REF_OBJ,H5S_ALL,H5S_ALL,H5P_DEFAULT,rbuf);
+
+    /* Open dataset object */
+    dset2 = H5Rdereference(dataset,H5R_OBJECT,&rbuf[0]);
+
+    /* Check information in referenced dataset */
+    sid1 = H5Dget_space(dset2);
+
+    ret=H5Sget_simple_extent_npoints(sid1);
+
+    /* Read from disk */
+    ret=H5Dread(dset2,H5T_NATIVE_INT,H5S_ALL,H5S_ALL,H5P_DEFAULT,tu32);
+    printf("Dataset data : \n");
+     for (i=0; i < SPACE1_DIM1 ; i++) printf (" %d ", tu32[i]);
+    printf("\n");
+    printf("\n");
+
+    /* Close dereferenced Dataset */
+    ret = H5Dclose(dset2);
+
+    /* Open group object */
+    group = H5Rdereference(dataset,H5R_OBJECT,&rbuf[2]);
+
+    /* Get group's comment */
+    ret=H5Gget_comment(group,".",10,read_comment);
+    printf("Group comment is %s \n", read_comment);
+    printf(" \n");
+    /* Close group */
+    ret = H5Gclose(group);
+
+    /* Open datatype object */
+    tid1 = H5Rdereference(dataset,H5R_OBJECT,&rbuf[3]);
+
+    /* Verify correct datatype */
+    {
+        H5T_class_t tclass;
+
+        tclass= H5Tget_class(tid1);
+        if ((tclass == H5T_COMPOUND))
+           printf ("Number of compound datatype members is %d \n", H5Tget_nmembers(tid1)); 
+    printf(" \n");
+    }
+
+    /* Close datatype */
+    ret = H5Tclose(tid1);
+
+    /* Close Dataset */
+    ret = H5Dclose(dataset);
+
+    /* Close file */
+    ret = H5Fclose(fid1);
+
+    /* Free memory buffers */
+    free(rbuf);
+    free(tu32);
+    return 0;
+}   
+
+

+ + + +

(Return to TOC) + + +

Example 11. Creating and writing a reference to a region.

+ +This example creates a dataset in the file. Then it creates a dataset +to store references to the dataset regions (selections). +The first selection is a 6 x 6 hyperslab. +The second selection is a point selection in the same dataset. +References to both selections are created and stored in the buffer, +and then written to the dataset in the file. + +

+#include <stdlib.h>
+#include <hdf5.h>
+
+#define FILE2	"trefer2.h5"
+#define SPACE1_NAME  "Space1"
+#define SPACE1_RANK     1
+#define SPACE1_DIM1     4
+
+/* Dataset with fixed dimensions */
+#define SPACE2_NAME  "Space2"
+#define SPACE2_RANK	2
+#define SPACE2_DIM1	10
+#define SPACE2_DIM2	10
+
+/* Element selection information */
+#define POINT1_NPOINTS 10
+
+int
+main(void)
+{
+    hid_t		fid1;		/* HDF5 File IDs		*/
+    hid_t		dset1,	/* Dataset ID			*/
+                dset2;      /* Dereferenced dataset ID */
+    hid_t		sid1,       /* Dataspace ID	#1		*/
+                sid2;       /* Dataspace ID	#2		*/
+    hsize_t		dims1[] = {SPACE1_DIM1},
+            	dims2[] = {SPACE2_DIM1, SPACE2_DIM2};
+    hssize_t	start[SPACE2_RANK];     /* Starting location of hyperslab */
+    hsize_t		stride[SPACE2_RANK];    /* Stride of hyperslab */
+    hsize_t		count[SPACE2_RANK];     /* Element count of hyperslab */
+    hsize_t		block[SPACE2_RANK];     /* Block size of hyperslab */
+    hssize_t	coord1[POINT1_NPOINTS][SPACE2_RANK]; 
+                                    /* Coordinates for point selection */
+    hdset_reg_ref_t      *wbuf;      /* buffer to write to disk */
+    int     *dwbuf;      /* Buffer for writing numeric data to disk */
+    int        i;          /* counting variables */
+    herr_t		ret;		/* Generic return value		*/
+
+
+    /* Allocate write & read buffers */
+    wbuf=calloc(sizeof(hdset_reg_ref_t), SPACE1_DIM1);
+    dwbuf=malloc(sizeof(int)*SPACE2_DIM1*SPACE2_DIM2);
+
+    /* Create file */
+    fid1 = H5Fcreate(FILE2, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+
+    /* Create dataspace for datasets */
+    sid2 = H5Screate_simple(SPACE2_RANK, dims2, NULL);
+
+    /* Create a dataset */
+    dset2=H5Dcreate(fid1,"Dataset2",H5T_STD_U8LE,sid2,H5P_DEFAULT);
+
+    for(i=0; i < SPACE2_DIM1*SPACE2_DIM2; i++)
+        dwbuf[i]=i*3;
+
+    /* Write selection to disk */
+    ret=H5Dwrite(dset2,H5T_NATIVE_INT,H5S_ALL,H5S_ALL,H5P_DEFAULT,dwbuf);
+
+    /* Close Dataset */
+    ret = H5Dclose(dset2);
+
+    /* Create dataspace for the reference dataset */
+    sid1 = H5Screate_simple(SPACE1_RANK, dims1, NULL);
+
+    /* Create a dataset */
+    dset1=H5Dcreate(fid1,"Dataset1",H5T_STD_REF_DSETREG,sid1,H5P_DEFAULT);
+
+    /* Create references */
+
+    /* Select 6x6 hyperslab for first reference */
+    start[0]=2; start[1]=2;
+    stride[0]=1; stride[1]=1;
+    count[0]=6; count[1]=6;
+    block[0]=1; block[1]=1;
+    ret = H5Sselect_hyperslab(sid2,H5S_SELECT_SET,start,stride,count,block);
+
+    /* Store first dataset region */
+    ret = H5Rcreate(&wbuf[0],fid1,"/Dataset2",H5R_DATASET_REGION,sid2);
+
+    /* Select sequence of ten points for second reference */
+    coord1[0][0]=6; coord1[0][1]=9;
+    coord1[1][0]=2; coord1[1][1]=2;
+    coord1[2][0]=8; coord1[2][1]=4;
+    coord1[3][0]=1; coord1[3][1]=6;
+    coord1[4][0]=2; coord1[4][1]=8;
+    coord1[5][0]=3; coord1[5][1]=2;
+    coord1[6][0]=0; coord1[6][1]=4;
+    coord1[7][0]=9; coord1[7][1]=0;
+    coord1[8][0]=7; coord1[8][1]=1;
+    coord1[9][0]=3; coord1[9][1]=3;
+    ret = H5Sselect_elements(sid2,H5S_SELECT_SET,POINT1_NPOINTS,(const hssize_t **)coord1);
+
+    /* Store second dataset region */
+    ret = H5Rcreate(&wbuf[1],fid1,"/Dataset2",H5R_DATASET_REGION,sid2);
+
+    /* Write selection to disk */
+    ret=H5Dwrite(dset1,H5T_STD_REF_DSETREG,H5S_ALL,H5S_ALL,H5P_DEFAULT,wbuf);
+
+    /* Close all objects */
+    ret = H5Sclose(sid1);
+    ret = H5Dclose(dset1);
+    ret = H5Sclose(sid2);
+    
+    /* Close file */
+    ret = H5Fclose(fid1);
+
+    free(wbuf);
+    free(dwbuf);
+    return 0;
+}   
+
+

+ + + +

(Return to TOC) + + +

Example 12. Reading a reference to a region.

+ +This example reads a dataset containing dataset region references. +It reads data from the dereferenced dataset and displays the number of +elements and raw data. Then it reads two selections: +a hyperslab selection and a point selection. The program queries a +number of points in the hyperslab and the coordinates and displays them. +Then it queries a number of selected points and their coordinates and +displays the information. + +

+   
+#include <stdlib.h>
+#include <hdf5.h>
+
+#define FILE2	"trefer2.h5"
+#define NPOINTS 10
+ 
+/* 1-D dataset with fixed dimensions */
+#define SPACE1_NAME  "Space1"
+#define SPACE1_RANK	1
+#define SPACE1_DIM1	4
+
+/* 2-D dataset with fixed dimensions */
+#define SPACE2_NAME  "Space2"
+#define SPACE2_RANK	2
+#define SPACE2_DIM1	10
+#define SPACE2_DIM2	10
+
+int 
+main(void)
+{
+    hid_t		fid1;		/* HDF5 File IDs		*/
+    hid_t		dset1,	/* Dataset ID			*/
+                dset2;      /* Dereferenced dataset ID */
+    hid_t		sid1,       /* Dataspace ID	#1		*/
+                sid2;       /* Dataspace ID	#2		*/
+    hsize_t *   coords;             /* Coordinate buffer */
+    hsize_t		low[SPACE2_RANK];   /* Selection bounds */
+    hsize_t		high[SPACE2_RANK];     /* Selection bounds */
+    hdset_reg_ref_t      *rbuf;      /* buffer to to read disk */
+    int    *drbuf;      /* Buffer for reading numeric data from disk */
+    int        i, j;          /* counting variables */
+    herr_t		ret;		/* Generic return value		*/
+
+    /* Output message about test being performed */
+
+    /* Allocate write & read buffers */
+    rbuf=malloc(sizeof(hdset_reg_ref_t)*SPACE1_DIM1);
+    drbuf=calloc(sizeof(int),SPACE2_DIM1*SPACE2_DIM2);
+
+    /* Open the file */
+    fid1 = H5Fopen(FILE2, H5F_ACC_RDWR, H5P_DEFAULT);
+
+    /* Open the dataset */
+    dset1=H5Dopen(fid1,"/Dataset1");
+
+    /* Read selection from disk */
+    ret=H5Dread(dset1,H5T_STD_REF_DSETREG,H5S_ALL,H5S_ALL,H5P_DEFAULT,rbuf);
+
+    /* Try to open objects */
+    dset2 = H5Rdereference(dset1,H5R_DATASET_REGION,&rbuf[0]);
+
+    /* Check information in referenced dataset */
+    sid1 = H5Dget_space(dset2);
+
+    ret=H5Sget_simple_extent_npoints(sid1);
+    printf(" Number of elements in the dataset is : %d\n",ret);
+
+    /* Read from disk */
+    ret=H5Dread(dset2,H5T_NATIVE_INT,H5S_ALL,H5S_ALL,H5P_DEFAULT,drbuf);
+
+    for(i=0; i < SPACE2_DIM1; i++) {
+        for (j=0; j < SPACE2_DIM2; j++) printf (" %d ", drbuf[i*SPACE2_DIM2+j]);
+        printf("\n"); }
+
+    /* Get the hyperslab selection */
+    sid2=H5Rget_region(dset1,H5R_DATASET_REGION,&rbuf[0]);
+
+    /* Verify correct hyperslab selected */
+    ret = H5Sget_select_npoints(sid2);
+    printf(" Number of elements in the hyperslab is : %d \n", ret);
+    ret = H5Sget_select_hyper_nblocks(sid2);
+    coords=malloc(ret*SPACE2_RANK*sizeof(hsize_t)*2); /* allocate space for the hyperslab blocks */
+    ret = H5Sget_select_hyper_blocklist(sid2,0,ret,coords);
+    printf(" Hyperslab coordinates are : \n");
+    printf (" ( %lu , %lu ) ( %lu , %lu ) \n", \
+(unsigned long)coords[0],(unsigned long)coords[1],(unsigned long)coords[2],(unsigned long)coords[3]); 
+    free(coords);
+    ret = H5Sget_select_bounds(sid2,low,high);
+
+    /* Close region space */
+    ret = H5Sclose(sid2);
+
+    /* Get the element selection */
+    sid2=H5Rget_region(dset1,H5R_DATASET_REGION,&rbuf[1]);
+
+    /* Verify correct elements selected */
+    ret = H5Sget_select_elem_npoints(sid2);
+    printf(" Number of selected elements is : %d\n", ret);
+
+    /* Allocate space for the element points */
+    coords= malloc(ret*SPACE2_RANK*sizeof(hsize_t)); 
+    ret = H5Sget_select_elem_pointlist(sid2,0,ret,coords);
+    printf(" Coordinates of selected elements are : \n");
+    for (i=0; i < 2*NPOINTS; i=i+2) 
+         printf(" ( %lu , %lu ) \n", (unsigned long)coords[i],(unsigned long)coords[i+1]); 
+          
+    free(coords);
+    ret = H5Sget_select_bounds(sid2,low,high);
+
+    /* Close region space */
+    ret = H5Sclose(sid2);
+
+    /* Close first space */
+    ret = H5Sclose(sid1);
+
+    /* Close dereferenced Dataset */
+    ret = H5Dclose(dset2);
+
+    /* Close Dataset */
+    ret = H5Dclose(dset1);
+
+    /* Close file */
+    ret = H5Fclose(fid1);
+
+    /* Free memory buffers */
+    free(rbuf);
+    free(drbuf);
+    return 0;
+}   
+
+

+ + +

(Return to TOC) + + +

+ + + + +

+Introduction to HDF5
+HDF5 User Guide + +

+HDF5 Reference Manual
+Other HDF5 documents and links +

+ +

+ + +

+HDF Help Desk +
+Last modified: 30 January 2001 +
+Describes HDF5 Release 1.4, February 2001 + +

+Copyright +

+ + + + -- cgit v0.12