[svn-r467] Restructuring documentation.

1 files changed, 347 insertions, 0 deletions

diff --git a/doc/html/h5s.examples b/doc/html/h5s.examples
new file mode 100644
index 0000000..e7a479f
--- /dev/null
+++ b/doc/html/h5s.examples
@@ -0,0 +1,347 @@
+Example 1: Create a simple fixed size 3-D dataspace in memory and on disk and
+    copy the entire dataset to disk.
+
+{
+    hid_t file;                     /* File ID */
+    hid_t dataset;                  /* Dataset ID */
+    hid_t mem_space, file_space;    /* Dataspaces for memory and the file */
+    uint8 *buf;                     /* Buffer for data */
+    hsize_t curr_dims[3]={3,4,5};   /* Dimensions of the dataset */
+
+    /* Create file */
+    file = H5Fcreate("example1.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+
+    /* Create dataspace for dataset in the file */
+    /* Selection for dataspace defaults to entire space */
+    file_space=H5Screate(H5S_SIMPLE);
+
+    /* Set the extent & type of the dataset's dataspace */
+    H5Sset_extent_simple(file_space,3,curr_dims,curr_dims);
+
+    /* Create the dataspace for the dataset in memory */
+    /* Selection for dataspace defaults to entire space */
+    mem_space=H5Screate(H5S_SIMPLE);
+
+    /* Set the extent & type of the memory dataspace */
+    H5Sset_extent_simple(mem_space,3,curr_dims,curr_dims);
+
+    /* Create the dataset on disk */
+    dataset=H5Dcreate(file,"Dataset",H5T_NATIVE_UINT8,file_space,H5P_DEFAULT);
+
+    /* Write the dataset to the file */
+    H5Dwrite(dataset,H5T_NATIVE_UINT8,mem_space,file_space,H5P_DEFAULT,buf);
+
+    /* Close dataspaces */
+    H5Sclose(mem_space);
+    H5Sclose(file_space);
+
+    /* Close dataset & file */
+    H5Dclose(dataset);
+    H5Fclose(file);
+}
+
+
+Example 2: Create a simple fixed size 3-D dataspace in memory and on disk and
+    copy a hyperslab to disk.  The hyperslab blocks are packed and
+    contiguous in memory, but are scattered when written to the dataset
+    on disk.
+
+{
+    hid_t file;                     /* File ID */
+    hid_t dataset;                  /* Dataset ID */
+    hid_t mem_space, file_space;    /* Dataspaces for memory and the file */
+    uint8 *buf;                     /* Buffer for data */
+    hssize_t start[3]={3,4,5};      /* Start of hyperslab */
+    hsize_t stride[3]={1,2,2};      /* Stride for hyperslab */
+    hsize_t count[3]={3,3,3};       /* Hyperslab block count in each dimension */
+    hsize_t block[3]={2,2,2};       /* Hyperslab block size in each dimension */
+    hsize_t curr_dims[3]={13,14,15};   /* Dimensions of the dataset */
+
+    /* Create file */
+    file = H5Fcreate("example2.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+
+    /* Create dataspace for dataset in the file */
+    /* Selection for dataspace defaults to entire space */
+    file_space=H5Screate(H5S_SIMPLE);
+
+    /* Set the extent & type of the dataset's dataspace */
+    H5Sset_extent_simple(file_space,3,curr_dims,curr_dims);
+
+    /* Set the hyperslab selection for a file dataspace */
+    H5Sselect_hyperslab(file_space,H5S_SELECT_SET,start,stride,count,block);
+
+    /* Create the dataspace for the dataset in memory */
+    /* Selection for dataspace defaults to entire space */
+    mem_space=H5Screate(H5S_SIMPLE);
+
+    /* Set the extent & type of the memory dataspace */
+    /* Compute the memory dimensions based on the hyperslab blocks to write */
+    for(i=0; i<3; i++)
+        curr_dims[i]=count[i]*block[i];
+    H5Sset_extent_simple(mem_space,3,curr_dims,curr_dims);
+
+    /* Create the dataset on disk */
+    dataset=H5Dcreate(file,"Dataset",H5T_NATIVE_UINT8,file_space,H5P_DEFAULT);
+
+    /* Write the hyperslab to the file */
+    H5Dwrite(dataset,H5T_NATIVE_UINT8,mem_space,file_space,H5P_DEFAULT,buf);
+
+    /* Close dataspaces */
+    H5Sclose(mem_space);
+    H5Sclose(file_space);
+
+    /* Close dataset & file */
+    H5Dclose(dataset);
+    H5Fclose(file);
+}
+
+
+Example 3: Create a simple fixed size 3-D dataspace in memory and on disk and
+    copy a specific selection of points (with a particular order) to
+    disk.  The memory and file dataspaces are different sizes, but the number
+    of points selected are the same.
+
+{
+    hid_t file;                     /* File ID */
+    hid_t dataset;                  /* Dataset ID */
+    hid_t mem_space, file_space;    /* Dataspaces for memory and the file */
+    uint8 *buf;                     /* Buffer for data */
+    hsize_t elements[5][3];         /* Dataspace elements selected */
+    hsize_t curr_dims[3]={13,14,15};   /* Dimensions of the dataset */
+
+    /* Create file */
+    file = H5Fcreate("example3.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+
+    /* Create dataspace for dataset in the file */
+    /* Selection for dataspace defaults to entire space */
+    file_space=H5Screate(H5S_SIMPLE);
+
+    /* Set the extent & type of the dataset's dataspace */
+    H5Sset_extent_simple(file_space,3,curr_dims,curr_dims);
+
+    /* Set the elements for the selection in the file dataspace */
+    elements[0]={0,2,4};            /* Yes, I know this won't compile.. :-) */
+    elements[1]={3,4,1};
+    elements[2]={9,8,3};
+    elements[3]={7,2,0};
+    elements[4]={6,5,8};
+    H5Sselect_elements(file_space,H5S_SELECT_SET,5,elements);
+
+    /* Create the dataspace for the dataset in memory */
+    /* Selection for dataspace defaults to entire space */
+    mem_space=H5Screate(H5S_SIMPLE);
+
+    /* Set the extent & type of the memory dataspace */
+    curr_dims={23,15,18};           /* This won't compile either :-) */
+    H5Sset_extent_simple(mem_space,3,curr_dims,curr_dims);
+
+    /* Set the elements for the selection in the file dataspace */
+    elements[0]={9,2,1};
+    elements[1]={13,1,12};
+    elements[2]={4,1,7};
+    elements[3]={0,12,0};
+    elements[4]={20,10,17};
+    H5Sselect_elements(mem_space,H5S_SELECT_SET,5,elements);
+
+    /* Create the dataset on disk */
+    dataset=H5Dcreate(file,"Dataset",H5T_NATIVE_UINT8,file_space,H5P_DEFAULT);
+
+    /* Write the hyperslab to the file */
+    H5Dwrite(dataset,H5T_NATIVE_UINT8,mem_space,file_space,H5P_DEFAULT,buf);
+
+    /* Close dataspaces */
+    H5Sclose(mem_space);
+    H5Sclose(file_space);
+
+    /* Close dataset & file */
+    H5Dclose(dataset);
+    H5Fclose(file);
+}
+
+
+Example 4: Create a simple fixed size 3-D dataspace in memory and on disk and
+    build up selection hyperslab selections to copy from memory to disk.  The
+    selection is the same for both dataspaces, but a different offset is used,
+    to illustrate the selection offsets.  
+
+{
+    hid_t file;                     /* File ID */
+    hid_t dataset;                  /* Dataset ID */
+    hid_t mem_space, file_space;    /* Dataspaces for memory and the file */
+    uint8 *buf;                     /* Buffer for data */
+    hssize_t start[3];              /* Start of hyperslab */
+    hsize_t stride[3];              /* Stride for hyperslab */
+    hsize_t count[3];               /* Hyperslab block count in each dimension */
+    hsize_t block[3];               /* Hyperslab block size in each dimension */
+    hssize_t offset[3];             /* Selection offset */
+    hsize_t curr_dims[3]={13,14,15};   /* Dimensions of the dataset */
+
+    /* Create file */
+    file = H5Fcreate("example4.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+
+    /* Create dataspace for dataset in the file */
+    /* Selection for dataspace defaults to entire space */
+    file_space=H5Screate(H5S_SIMPLE);
+
+    /* Set the extent & type of the dataset's dataspace */
+    H5Sset_extent_simple(file_space,3,curr_dims,curr_dims);
+
+    /* Build up the selection with a series of hyperslab selections */
+    start={0,2,4};            /* Again, this won't compile.. :-) */
+    stride={1,1,1};
+    count={6,5,8};
+    block={1,1,1};
+    
+    /* Set the first selection, union the rest in */
+    H5Sselect_hyperslab(file_space,H5S_SELECT_SET,start,stride,count,block);
+
+    /* initialize the second hyperslab */
+    start={10,9,1};            /* Again, this won't compile.. :-) */
+    stride={1,1,1};
+    count={2,3,10};
+    block={1,1,1};
+
+    /* Union the second hyperslab into the file dataspace's selection */
+    H5Sselect_hyperslab(file_space,H5S_SELECT_UNION,start,stride,count,block);
+
+    /* initialize the third hyperslab */
+    start={3,10,5};            /* Again, this won't compile.. :-) */
+    stride={1,1,1};
+    count={8,2,6};
+    block={1,1,1};
+
+    /* Union the final hyperslab into the file dataspace's selection */
+    H5Sselect_hyperslab(file_space,H5S_SELECT_UNION,start,stride,count,block);
+
+    /* Create the dataspace for the dataset in memory */
+    /* Selection for dataspace defaults to entire space */
+    mem_space=H5Screate(H5S_SIMPLE);
+
+    /* Set the extent & type of the memory dataspace */
+    curr_dims={23,15,18};           /* This won't compile either :-) */
+    H5Sset_extent_simple(mem_space,3,curr_dims,curr_dims);
+
+    /* Copy the selection from the file dataspace */
+    H5Sselect_op(mem_space,H5S_SELECT_COPY,file_space);
+
+    /* Adjust the offset of the selection in the memory dataspace */
+    offset={1,1,1};
+    H5Soffset_simple(mem_space,offset);
+
+    /* Create the dataset on disk */
+    dataset=H5Dcreate(file,"Dataset",H5T_NATIVE_UINT8,file_space,H5P_DEFAULT);
+
+    /* Write the hyperslab to the file */
+    H5Dwrite(dataset,H5T_NATIVE_UINT8,mem_space,file_space,H5P_DEFAULT,buf);
+
+    /* Close dataspaces */
+    H5Sclose(mem_space);
+    H5Sclose(file_space);
+
+    /* Close dataset & file */
+    H5Dclose(dataset);
+    H5Fclose(file);
+}
+
+
+Example 5: Same as example 1 (create a simple fixed size 3-D dataspace in memory and on disk and
+    copy the entire dataset to disk), except that the selection order is changed
+    for the memory dataspace, to change between FORTRAN and C array ordering.
+
+{
+    hid_t file;                     /* File ID */
+    hid_t dataset;                  /* Dataset ID */
+    hid_t mem_space, file_space;    /* Dataspaces for memory and the file */
+    uint8 *buf;                     /* Buffer for data */
+    hsize_t order[3];               /* Dimension ordering for selection */
+    hsize_t curr_dims[3]={3,4,5};   /* Dimensions of the dataset */
+
+    /* Create file */
+    file = H5Fcreate("example5.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+
+    /* Create dataspace for dataset in the file */
+    /* Selection for dataspace defaults to entire space and C array order */
+    file_space=H5Screate(H5S_SIMPLE);
+
+    /* Set the extent & type of the dataset's dataspace */
+    H5Sset_extent_simple(file_space,3,curr_dims,curr_dims);
+
+    /* Create the dataspace for the dataset in memory */
+    /* Selection for dataspace defaults to entire space and C array order */
+    mem_space=H5Screate(H5S_SIMPLE);
+
+    /* Set the extent & type of the memory dataspace */
+    H5Sset_extent_simple(mem_space,3,curr_dims,curr_dims);
+
+    /* Change selection ordering to FORTRAN order for memory dataspace */
+    order={0,1,2};
+    H5Sselect_order(mem_space,order);
+
+    /* Create the dataset on disk */
+    dataset=H5Dcreate(file,"Dataset",H5T_NATIVE_UINT8,file_space,H5P_DEFAULT);
+
+    /* Write the dataset to the file */
+    H5Dwrite(dataset,H5T_NATIVE_UINT8,mem_space,file_space,H5P_DEFAULT,buf);
+
+    /* Close dataspaces */
+    H5Sclose(mem_space);
+    H5Sclose(file_space);
+
+    /* Close dataset & file */
+    H5Dclose(dataset);
+    H5Fclose(file);
+}
+
+
+Example 6:  Create a stored dataspace on disk and use the H5Ssubspace function
+    create a dataspace located within that space.
+
+{
+    hid_t file;                     /* File ID */
+    hid_t space1, space2;           /* Dataspace IDs */
+    hssize_t start[3];              /* Start of hyperslab */
+    hsize_t count[3];               /* Hyperslab block count in each dimension */
+    hsize_t curr_dims[3]={13,14,15};/* Dimensions of the dataset */
+
+    /* Create file */
+    file = H5Fcreate("example6.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+
+    /* Create dataspace #1 */
+    space1=H5Screate(H5S_SIMPLE);
+
+    /* Set the extent & type of dataspace #1 */
+    H5Sset_extent_simple(space1,3,curr_dims,curr_dims);
+
+    /* Store dataspace #1 on disk */
+    H5Scommit(file,"/Dataspaces/Dataspace #1",space1);
+
+    /* Select a contiguous hyperslab in dataspace #1 to create dataspace #2 with */
+    start={0,2,4};
+    count={6,5,8};
+    
+    /* 
+     *  Use stride and block set to NULL to get contiguous, single element sized
+     * hyperslab.  The stride and block parameters could also be set to all
+     * 1's, but this is simpler and easier.
+     */
+    H5Sselect_hyperslab(space1,H5S_SELECT_SET,start,NULL,count,NULL);
+
+    /* Create dataspace #2 as a dataspace located within dataspace #1 */
+    space2=H5Ssubspace(space1);
+
+    /* Store dataspace #2 on disk also */
+    H5Scommit(file,"/Dataspaces/Dataspace #2",space2);
+
+    /* 
+     * space1 & space2 can be used to create datasets, etc.  Any datasets
+     * created with space2 can have their dataspace queried to find the parent
+     * dataspace and the location within the parent dataspace
+     */
+
+    /* Close dataspaces */
+    H5Sclose(space1);
+    H5Sclose(space2);
+
+    /* Close file */
+    H5Fclose(file);
+}