[svn-r229] New examples have been created in the examples directory:

    h5_write.c    - stores INT array as INT32 little endian dataset in the HDF5 file.

    h5_read.c     - gets info about the dataset;
                    reads hyperslab from the dataset in the file into
                    2-dim slice of the 3 dimensional array.

    h5_compund.c  - creates compound dataset and writes it to the file;
                    reads subsets of the dataset.

    h5_extend_write.c - writes extendable dataset.

    h5_extend_read.c  - gets info about the dataset;
                        reads dataset and one of the chunks.

5 files changed, 652 insertions, 0 deletions

diff --git a/examples/h5_compound.c b/examples/h5_compound.c
new file mode 100644
index 0000000..a5ad77b
--- /dev/null
+++ b/examples/h5_compound.c
@@ -0,0 +1,155 @@
+/*
+ * This example shows how to create a compound data type,
+ * write an array which has the compound data type to the file,
+ * and read back fields' subsets.
+ */
+
+#include "hdf5.h"
+
+#define FILE          "SDScompound.h5"
+#define DATASETNAME   "ArrayOfStructures"
+#define LENGTH        10
+#define RANK          1
+
+main()
+
+{
+
+   
+/* 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 hadle */
+
+/* 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, datatype, dataset, space; /* Handles */
+herr_t     status;
+size_t     dim[] = {LENGTH};   /* Dataspace dimensions */
+
+H5T_class_t class;
+size_t     size;
+
+/*
+ * 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 = H5Pcreate_simple(RANK, dim, NULL);
+
+/*
+ * Create the file.
+ */
+file = H5Fcreate(FILE, H5ACC_OVERWRITE, H5C_DEFAULT, H5C_DEFAULT);
+
+/*
+ * Create the memory data type. 
+ */
+s1_tid = H5Tcreate (H5T_COMPOUND, sizeof(s1_t));
+status = H5Tinsert(s1_tid, "a_name", HPOFFSET(s1, a), H5T_NATIVE_INT);
+status = H5Tinsert(s1_tid, "c_name", HPOFFSET(s1, c), H5T_NATIVE_DOUBLE);
+status = H5Tinsert(s1_tid, "b_name", HPOFFSET(s1, b), H5T_NATIVE_FLOAT);
+
+/* 
+ * Create the dataset.
+ */
+dataset = H5Dcreate(file, DATASETNAME, s1_tid, space, H5C_DEFAULT);
+
+/*
+ * Wtite data to the dataset; 
+ */
+status = H5Dwrite(dataset, s1_tid, H5P_ALL, H5P_ALL, H5C_DEFAULT, s1);
+
+/*
+ * Release resources
+ */
+H5Tclose(s1_tid);
+H5Pclose(space);
+H5Dclose(dataset);
+H5Fclose(file);
+ 
+/*
+ * Open the file and the dataset.
+ */
+file = H5Fopen(FILE, H5ACC_DEFAULT, H5C_DEFAULT);
+ 
+dataset = H5Dopen(file, DATASETNAME);
+
+/* 
+ * Create a data type for s2
+ */
+s2_tid = H5Tcreate(H5T_COMPOUND, sizeof(s2_t));
+
+status = H5Tinsert(s2_tid, "c_name", HPOFFSET(s2, c), H5T_NATIVE_DOUBLE);
+status = H5Tinsert(s2_tid, "a_name", HPOFFSET(s2, a), H5T_NATIVE_INT);
+
+/*
+ * Read two fields c and a from s1 dataset. Fields iin the file
+ * are found by their names "c_name" and "a_name".
+ */
+status = H5Dread(dataset, s2_tid, H5P_ALL, H5P_ALL, H5C_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 data type 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, H5P_ALL, H5P_ALL, H5C_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);
+H5Pclose(space);
+H5Fclose(file);
+}
diff --git a/examples/h5_extend_read.c b/examples/h5_extend_read.c
new file mode 100644
index 0000000..6965722
--- /dev/null
+++ b/examples/h5_extend_read.c
@@ -0,0 +1,141 @@
+/*  
+ *   This example shows how to work with extendable dataset.
+ *   In the current version of the library dataset MUST be
+ *   chunked.
+ *   
+ */
+ 
+#include "hdf5.h"
+
+#define FILE        "SDSextendable.h5"
+#define DATASETNAME "ExtendableArray" 
+#define RANK         2
+#define NX     10
+#define NY     5 
+
+main ()
+{
+   hid_t       file;                        /* handles */
+   hid_t       datatype, dataset;  
+   hid_t       filespace;                   
+   hid_t       memspace;                  
+   hid_t       cparms;                   
+   H5T_class_t class;                       /* data type class */
+   size_t      elem_size;                   /* size of the data element
+                                               stored in file */ 
+   size_t      dims[2];                     /* dataset and chunk dimensions */ 
+   size_t      chunk_dims[2];
+
+   size_t      size[2];
+   size_t      count[2];
+   int         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         i, j, rank, rank_chunk;
+
+ 
+/*
+ * Open the file and the dataset.
+ */
+file = H5Fopen(FILE, H5ACC_DEFAULT, H5C_DEFAULT);
+dataset = H5Dopen(file, DATASETNAME);
+ 
+/*
+ * Get dataset rank and dimension.
+ */
+ 
+filespace = H5Dget_space(dataset);    /* Get filespace handle first. */
+rank      = H5Pget_ndims(filespace);
+status_n  = H5Pget_dims(filespace, dims);
+printf("dataset rank %d, dimensions %d x %d \n", rank, dims[0], dims[1]);
+
+/*
+ * Get creation properties.
+ */
+cparms = H5Dget_create_parms(dataset); /* Get properties handle first. */
+
+/*
+ * Get chunking information: rank and dimensions
+ */
+rank_chunk = H5Cget_chunk(cparms, 2, chunk_dims);
+printf("chunk rank %d, dimensions %d x %d \n", rank_chunk,
+        chunk_dims[0], chunk_dims[1]);
+ 
+ 
+/*
+ * Define the memory filespace to read dataset.
+ */
+memspace = H5Pcreate_simple(RANK,dims,NULL);
+ 
+/*
+ * Read dataset back and display.
+ */
+status = H5Dread(dataset, H5T_NATIVE_INT, memspace, filespace,
+                 H5C_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 
+*/
+
+/*
+ * Define the memory filespace to read a chunk.
+ */
+memspace = H5Pcreate_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 = H5Pset_hyperslab(filespace, offset, count, NULL);
+
+/*
+ * Read chunk back and display.
+ */
+status = H5Dread(dataset, H5T_NATIVE_INT, memspace, filespace,
+                 H5C_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.
+ */
+H5Dclose(dataset);
+H5Pclose(filespace);
+H5Pclose(memspace);
+H5Fclose(file);
+
+}     
diff --git a/examples/h5_extend_write.c b/examples/h5_extend_write.c
new file mode 100644
index 0000000..fca6ebc
--- /dev/null
+++ b/examples/h5_extend_write.c
@@ -0,0 +1,150 @@
+/*  
+ *   This example shows how to work with extendable dataset.
+ *   In the current version of the library dataset MUST be
+ *   chunked.
+ *   
+ */
+ 
+#include "hdf5.h"
+
+#define FILE        "SDSextendable.h5"
+#define DATASETNAME "ExtendableArray" 
+#define RANK         2
+#define NX     10
+#define NY     5 
+
+main ()
+{
+   hid_t       file;                          /* handles */
+   hid_t       datatype, dataspace, dataset;  
+   hid_t       filespace;                   
+   hid_t       cparms;                     
+   size_t      dims[2]  = { 3, 3};            /* dataset dimensions
+                                                 at the creation time  */ 
+   size_t      dims1[2] = { 3, 3};            /* data1 dimensions */ 
+   size_t      dims2[2] = { 7, 1};            /* data2 dimensions */  
+   size_t      dims3[2] = { 2, 2};            /* data3 dimensions */ 
+
+   size_t      maxdims[2] = {H5P_UNLIMITED, H5P_UNLIMITED};
+   size_t      chunk_dims[2] ={2, 5};
+   size_t      size[2];
+   int         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 ulimited dimensions. 
+ */
+dataspace = H5Pcreate_simple(RANK, dims, maxdims); 
+
+/*
+ * Create a new file. If file exists its contents will be overwritten.
+ */
+file = H5Fcreate(FILE, H5ACC_OVERWRITE, H5C_DEFAULT, H5C_DEFAULT);
+
+/* 
+ * Modify dataset creation properties, i.e. enable chunking.
+ */
+cparms = H5Ccreate (H5C_DATASET_CREATE);
+status = H5Cset_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 = H5Pset_hyperslab(filespace, offset, dims1, NULL);  
+
+/*
+ * Write the data to the hyperslab.
+ */
+status = H5Dwrite(dataset, H5T_NATIVE_INT, dataspace, filespace,
+                  H5C_DEFAULT, data1);
+
+/*
+ * Extend the dataset. Dataset becomes 7 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 = H5Pset_hyperslab(filespace, offset, dims2, NULL);  
+
+/*
+ * Define memory space
+ */
+dataspace = H5Pcreate_simple(RANK, dims2, NULL); 
+
+/*
+ * Write the data to the hyperslab.
+ */
+status = H5Dwrite(dataset, H5T_NATIVE_INT, dataspace, filespace,
+                  H5C_DEFAULT, data2);
+
+/*
+ * Extend the dataset. Dataset becomes 7 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 = H5Pset_hyperslab(filespace, offset, dims3, NULL);  
+
+/*
+ * Define memory space.
+ */
+dataspace = H5Pcreate_simple(RANK, dims3, NULL); 
+
+/*
+ * Write the data to the hyperslab.
+ */
+status = H5Dwrite(dataset, H5T_NATIVE_INT, dataspace, filespace,
+                  H5C_DEFAULT, data3);
+
+/*
+ * Close/release resources.
+ */
+H5Dclose(dataset);
+H5Pclose(dataspace);
+H5Pclose(filespace);
+H5Fclose(file);
+
+}     
diff --git a/examples/h5_read.c b/examples/h5_read.c
new file mode 100644
index 0000000..99e1801
--- /dev/null
+++ b/examples/h5_read.c
@@ -0,0 +1,128 @@
+/*  
+ *   This example reads hyperslab from the SDS.h5 file 
+ *   created by h5_write.c program into two-dimensional
+ *   plane of the tree-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
+
+main ()
+{
+   hid_t       file, dataset;         /* handles */
+   hid_t       datatype, dataspace;   
+   hid_t       memspace; 
+   H5T_class_t class;                 /* data type class */
+   H5T_order_t order;                 /* data order */
+   size_t      size;                  /* size of the data element
+                                         stored in file */ 
+   size_t      dimsm[3];              /* memory space dimensions */
+   size_t      dims_out[2];           /* dataset dimensions */      
+   herr_t      status;                             
+
+   int         data_out[NX][NY][NZ ]; /* output buffer */
+   
+   size_t      count[2];              /* size of the hyperslab in the file */
+   int         offset[2];             /* hyperslab offset in the file */
+   size_t      count_out[3];          /* size of the hyperslab in memory */
+   int         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, H5ACC_DEFAULT, H5C_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      = H5Pget_ndims(dataspace);
+status_n  = H5Pget_dims(dataspace, dims_out);
+printf("rank %d, dimensions %d x %d \n", rank, dims_out[0], dims_out[1]);
+
+/* 
+ * Define hyperslab in the datatset. 
+ */
+offset[0] = 1;
+offset[1] = 2;
+count[0]  = NX_SUB;
+count[1]  = NY_SUB;
+status = H5Pset_hyperslab(dataspace, offset, count, NULL);
+
+/*
+ * Define the memory dataspace.
+ */
+dimsm[0] = NX;
+dimsm[1] = NY;
+dimsm[2] = NZ ;
+memspace = H5Pcreate_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 = H5Pset_hyperslab(memspace, offset_out, 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,
+                 H5C_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);
+H5Pclose(dataspace);
+H5Pclose(memspace);
+H5Fclose(file);
+
+}     
diff --git a/examples/h5_write.c b/examples/h5_write.c
new file mode 100644
index 0000000..5a8a39d
--- /dev/null
+++ b/examples/h5_write.c
@@ -0,0 +1,78 @@
+/*  
+ *  This example writes data to HDF5 file.
+ *  Data conversion is performed during write operation.  
+ */
+ 
+#include "hdf5.h"
+
+#define FILE        "SDS.h5"
+#define DATASETNAME "IntArray" 
+#define NX     5                      /* dataset dimensions */
+#define NY     6
+#define RANK   2
+
+main ()
+{
+   hid_t       file, dataset;         /* file and dataset handles */
+   hid_t       datatype, dataspace;   /* handles */
+   size_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 H5ACC_OVERWRITE access,
+ * default file creation properties, and default file
+ * access properties.
+ */
+file = H5Fcreate(FILE, H5ACC_DEFAULT, H5C_DEFAULT, H5C_DEFAULT);
+
+/*
+ * Describe the size of the array and create the data space for fixed
+ * size dataset. 
+ */
+dimsf[0] = NX;
+dimsf[1] = NY;
+dataspace = H5Pcreate_simple(RANK, dimsf, NULL); 
+
+/* 
+ * Define datatype for the data in the file.
+ * We will store liitle endian INT32 numbers.
+ */
+datatype = H5Tcopy(H5T_NATIVE_INT32);
+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,
+                    H5C_DEFAULT);
+
+/*
+ * Write the data to the dataset using default transfer properties.
+ */
+status = H5Dwrite(dataset, H5T_NATIVE_INT, H5P_ALL, H5P_ALL,
+                  H5C_DEFAULT, data);
+
+/*
+ * Close/release resources.
+ */
+H5Dclose(dataset);
+H5Pclose(dataspace);
+H5Fclose(file);
+ 
+}