diff options
Diffstat (limited to 'doc/html/Intro')
| -rw-r--r-- | doc/html/Intro/IntroExamples.html | 2111 |
1 files changed, 2111 insertions, 0 deletions
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 @@ +<HTML> +<HEAD> +<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252"> +<META NAME="Generator" CONTENT="Microsoft Word 97"> +<TITLE>Introduction to HDF5</TITLE> +</HEAD> +<BODY LINK="#0000ff" VLINK="#800080" bgcolor="#FFFFFF"> + + + +<hr> +<center> +<table border=0 width=98%> +<tr><td valign=top align=left> +Introduction to HDF5 <br> +<a href="../H5.user.html">HDF5 User Guide</a> +<!-- +<a href="../Glossary.html">Glossary</a><br> +--> +</td> +<td valign=top align=right> +<a href="../RM_H5Front.html">HDF5 Reference Manual</a> <br> +<a href="../index.html">Other HDF5 documents and links</a> +</td></tr> +</table> +</center> +<hr> + + +<h1 ALIGN="CENTER">Introduction to HDF5 -- Example Codes</h1></a> + + +<a name="IEx-TOC"> +<hr> +<center> +<table border=0 width=90%> +<tr><th colspan=3>Table of Contents</th></tr></a> +<tr><td valign=top align=left width=42%> + + <font size=-1> +     + <A href="#CreateExample">1: Creating and writing a + dataset</A><br> +     + <A href="#CheckAndReadExample">2. Reading a hyperslab</A><br> +     + <A href="#WriteSelected">3. Writing selected data</A><br> +     + <A href="#Compound">4. Working with compound datatypes</A><br> +     + <A href="#CreateExtendWrite">5. Creating and writing an extendible</a> <br> +     +     + <A href="#CreateExtendWrite">dataset</A><br> +     + <A href="#ReadExtended">6. Reading data</A><br> +     + <A href="#CreateGroups">7. Creating groups</A><br> + </font> + +</td><td width=6%> </td><td valign=top align=left width=42%> + + <font size=-1> +     + <A href="#ReadWriteAttributes">8. Writing and reading + attributes</A><br> +     + <a href="#CreateWriteRefObj">9. Creating and writing references</a><br> +     +     + <a href="#CreateWriteRefObj">to objects</a><br> +     + <a href="#ReadRefObj">10. Reading references to objects</a><br> +     + <a href="#CreateWriteRefReg">11. Creating and writing references</a><br> +     +     + <a href="#CreateWriteRefReg">to dataset regions</a><br> +     + <a href="#ReadRefReg">12. Reading references to dataset</a><br> +     +     + <a href="#ReadRefReg">regions</a> + </font> +</td></tr> +</table> +</center> +<p> + +<hr> + + + +<H4><A NAME="CreateExample">Example 1: How to create a homogeneous multi-dimensional dataset</A> and write it to a file.</A></H4> +<P>This example creates a 2-dimensional HDF 5 dataset of little endian 32-bit integers. +<PRE> +<!-- Insert Example 1, h5_write.c, here. --> +/* + * This example writes data to the 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 + +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; +} +</pre> + + + + +<P> +<p align=right><font size=-1><a href="#IEx-TOC">(Return to TOC)</a></font> + + +<A NAME="CheckAndReadExample"> </a> +<H4><A NAME="_Toc429885326">Example 2.</A> How to read a hyperslab from file into memory.</A></H4> +<P>This example reads a hyperslab from a 2-d HDF5 dataset into a 3-d dataset in memory. +<PRE> +<!-- Insert Example 2, h5_read.c, here. --> +/* + * 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; +} +</pre> + + + + + +<P> +<p align=right><font size=-1><a href="#IEx-TOC">(Return to TOC)</a></font> + + +<H4><A NAME="_Toc429885331"><A NAME="WriteSelected"></A>Example 3. Writing selected data from memory to a file.</A></H4> +<P>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. + +<pre> +<!-- Insert Example 3, h5_select.c, here. --> +/* + * 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 <hdf5.h> + +#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; +} +</pre> + + + + +<P> +<p align=right><font size=-1><a href="#IEx-TOC">(Return to TOC)</a></font> + + +<H4><A NAME="Compound"><A NAME="_Toc429885327"></A>Example 4. Working with compound datatypes.</A></H4> +<P>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. +<PRE> +<!-- Insert Example 4, h5_compound.c, here. --> +/* + * 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; +} +</pre> + + + + +<P> +<p align=right><font size=-1><a href="#IEx-TOC">(Return to TOC)</a></font> + + +<H4><A NAME="CreateExtendWrite"><A NAME="_Toc429885328"></A>Example 5. Creating and writing an extendible dataset.</A></H4> +<P>This example shows how to create a 3x3 extendible dataset, to extend the dataset to 10x3, then to extend it again to 10x5. +<PRE> +<!-- Insert Example 5, h5_extend_write.c, here. --> +/* + * 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; +} +</pre> + + + + +<P> +<p align=right><font size=-1><a href="#IEx-TOC">(Return to TOC)</a></font> + + +<H4><A NAME="ReadExtended"><A NAME="_Toc429885329"></A>Example 6. Reading data.</A></H4> +<P>This example shows how to read information the chunked dataset written by <A HREF="#CreateExtendWrite">Example 5</A>. +<PRE> +<!-- Insert Example 6, h5_chunk_read.c, here. --> +/* + * 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; +) + +</pre> + + + + +<P> +<p align=right><font size=-1><a href="#IEx-TOC">(Return to TOC)</a></font> + + +<H4><A NAME="CreateGroups"><A NAME="_Toc429885330"></A>Example 7. Creating groups.</A></H4> +<P>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 <code>H5Giterate</code>, +<code>H5Glink</code>, and <code>H5Gunlink</code> functions. + +<PRE> +<!-- Insert Example 7, h5_group.c, here. --> +/* + * 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; + } +</pre> + + + + +<P> +<p align=right><font size=-1><a href="#IEx-TOC">(Return to TOC)</a></font> + + +<H4><A NAME="_Toc429885332"><A NAME="ReadWriteAttributes">Example 8</A>. Writing and reading attributes.</A></H4> +<P>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. + +<pre> +<!-- Insert Example 8, h5_attribute.c, here. --> +/* + * 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 <stdlib.h> +#include <hdf5.h> + +#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; +} +</pre> + + + +<P> +<p align=right><font size=-1><a href="#IEx-TOC">(Return to TOC)</a></font> + + +<H4><A NAME="CreateWriteRefObj">Example 9</A>. Creating and storing references to objects.</A></H4> +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. + +<PRE> + +#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; +} + +</PRE> + + + + +<P> +<p align=right><font size=-1><a href="#IEx-TOC">(Return to TOC)</a></font> + + +<H4><A NAME="ReadRefObj">Example 10</A>. Reading references to objects.</A></H4> +This example opens and reads dataset <code>Dataset3</code> from +the file created in Example 9. Then the program dereferences the references +to dataset <code>Dataset1</code>, 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. + + +<PRE> + +#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; +} + +</PRE> + + + +<P> +<p align=right><font size=-1><a href="#IEx-TOC">(Return to TOC)</a></font> + + +<H4><A NAME="CreateWriteRefReg">Example 11</A>. Creating and writing a reference to a region.</A></H4> + +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. + +<pre> +#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; +} + +</pre> + + + +<P> +<p align=right><font size=-1><a href="#IEx-TOC">(Return to TOC)</a></font> + + +<H4><A NAME="ReadRefReg">Example 12</A>. Reading a reference to a region.</A></H4> + +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. + +<PRE> + +#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; +} + +</PRE> + + +<P> +<p align=right><font size=-1><a href="#IEx-TOC">(Return to TOC)</a></font> + + +<hr> +<center> +<table border=0 width=98%> +<tr><td valign=top align=left> +Introduction to HDF5 <br> +<a href="../H5.user.html">HDF5 User Guide</a> +<!-- +<a href="../Glossary.html">Glossary</a><br> +--> +</td> +<td valign=top align=right> +<a href="../RM_H5Front.html">HDF5 Reference Manual</a> <br> +<a href="../index.html">Other HDF5 documents and links</a> +</td></tr> +</table> +</center> +<hr> + + +<address> +<table width=100% border=0> +<tr><td align=left valign=top> +<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> +<br> +Last modified: 30 January 2001 +<br> +Describes HDF5 Release 1.4, February 2001 + +</td><td align=right valign=top> +<a href="Copyright.html">Copyright</a> +</td></tr> +</table> + + +</BODY> +</HTML> |