diff options
Diffstat (limited to 'doc/html/Tutor/select.html')
| -rw-r--r-- | doc/html/Tutor/select.html | 319 |
1 files changed, 90 insertions, 229 deletions
diff --git a/doc/html/Tutor/select.html b/doc/html/Tutor/select.html index 76ef846..2ea4119 100644 --- a/doc/html/Tutor/select.html +++ b/doc/html/Tutor/select.html @@ -1,5 +1,5 @@ <HTML><HEAD> -<TITLE>HDF5 Tutorial - Selections using H5Sselect_hyperslab +<TITLE>HDF5 Tutorial - Hyperslab Selections </TITLE> </HEAD> @@ -13,7 +13,7 @@ width=78 height=27 alt="NCSA"><P></A> [ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ] <H1> -<BIG><BIG><BIG><FONT COLOR="#c101cd">Selections using H5Sselect_hyperslab</FONT> +<BIG><BIG><BIG><FONT COLOR="#c101cd">Hyperslab Selections</FONT> </BIG></BIG></BIG></H1> <hr noshade size=1> @@ -34,18 +34,21 @@ width=78 height=27 alt="NCSA"><P></A> <HR> <A NAME="def"> <H2>Selecting a Portion of a Dataspace</H2> -Hyperslabs are portions of datasets. A hyperslab selection can be a logically contiguous collection of points in a dataspace, or it +Hyperslabs are portions of datasets. A hyperslab selection can be a +logically contiguous collection of points in a dataspace, or it can be a regular pattern of points or blocks in a dataspace. -You can select a hyperslab to write to/read from with the function -H5Sselect_hyperslab. +You can select a hyperslab to write to or read from with the function +<CODE>H5Sselect_hyperslab</CODE> / <CODE>h5sselect_hyperslab_f</CODE>. <P> <H2> Programming Example</H2> <A NAME="desc"> <H3><U>Description</U></H3> -This example creates a 5 x 6 integer array in a -file called sds.h5. It selects a 3 x 4 hyperslab from the dataset, -as follows (Dimension 0 is offset by 1 and Dimension 1 is offset by 2): +This example creates a 5 x 6 integer array in a file called <code>sds.h5</code> +(<code>sdsf.h5</code> in FORTRAN). It +selects a 3 x 4 hyperslab from the dataset as follows (Dimension 0 is +offset by 1 and Dimension 1 is offset by 2): <P> +<B>5 x 6 array:</B> <TABLE BORDER CELLSPACING=1 CELLPADDING=7 WIDTH=172> <TR><TD WIDTH="17%" VALIGN="TOP"> </TD> <TD WIDTH="17%" VALIGN="TOP"> </TD> @@ -171,245 +174,100 @@ follows (with Dimension 0 offset by 3): </TR> </TABLE> <P> -[ <A HREF="examples/h5_hyperslab.c">Download h5_hyperslab.c</A> ] -<PRE> -/************************************************************ - - This example shows how to write and read a hyperslab. It - is derived from the h5_read.c and h5_write.c examples in - the "Introduction to HDF5". - - ************************************************************/ - -#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 - -#define X 5 /* dataset dimensions */ -#define Y 6 - -int -main (void) -{ - hsize_t dimsf[2]; /* dataset dimensions */ - int data[X][Y]; /* data to write */ - - /* - * Data and output buffer initialization. - */ - hid_t file, dataset; /* handles */ - hid_t dataspace; - hid_t memspace; - 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; - - - -/********************************************************* - This writes data to the HDF5 file. - *********************************************************/ - - /* - * Data and output buffer initialization. - */ - for (j = 0; j < X; j++) { - for (i = 0; i < Y; 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, - * the default file creation properties, and the 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] = X; - dimsf[1] = Y; - dataspace = H5Screate_simple (RANK, dimsf, NULL); - - /* - * Create a new dataset within the file using defined dataspace and - * default dataset creation properties. - */ - dataset = H5Dcreate (file, DATASETNAME, H5T_STD_I32BE, 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); - H5Dclose (dataset); - H5Fclose (file); - - -/************************************************************* - - This reads the hyperslab from the sds.h5 file just - created, into a 2-dimensional plane of the 3-dimensional - array. - - ************************************************************/ - - 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); - - dataspace = H5Dget_space (dataset); /* dataspace handle */ - rank = H5Sget_simple_extent_ndims (dataspace); - status_n = H5Sget_simple_extent_dims (dataspace, dims_out, NULL); - printf("\nRank: %d\nDimensions: %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); - printf ("Data:\n "); - for (j = 0; j < NX; j++) { - for (i = 0; i < NY; i++) printf("%d ", data_out[j][i][0]); - printf("\n "); - } - 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 and release resources. - */ - H5Dclose (dataset); - H5Sclose (dataspace); - H5Sclose (memspace); - H5Fclose (file); +To obtain the example, download: +<UL> +[ <A HREF="examples/h5_hyperslab.c">C example</A> ] + - <code>h5_hyperslab.c</code><BR> +[ <A HREF="examples/hyperslab.f90">FORTRAN example</A> ] + - <code>hyperslab.f90</code><BR> +[ <A HREF="examples/java/HyperSlab.java">Java example</A> ] + - <code>HyperSlab.java</code> +</UL> +<B>NOTE:</B> To download a tar file of the examples, including a Makefile, +please go to the <A HREF="references.html">References</A> page. +<P> -} -</PRE> <A NAME="rem"> <H3><U>Remarks</U></H3> <UL> -<LI>H5Sselect_hyperslab selects a hyperslab region to add to the current -selected region for a specified dataspace. -<PRE> - herr_t H5Sselect_hyperslab (hid_t space_id, H5S_seloper_t op, - const hssize_t *start, const hsize_t *stride, - const hsize_t *count, const hsize_t *block ) -</PRE> +<LI><CODE>H5Sselect_hyperslab</CODE> / <CODE>h5sselect_hyperslab_f</CODE> +selects a hyperslab region to +add to the current selected region for a specified dataspace. +<P> +<I><B>C</B></I>: +<pre> + herr_t H5Sselect_hyperslab (hid_t space_id, H5S_seloper_t operator, + const hssize_t *start, const hsize_t *stride, + const hsize_t *count, const hsize_t *block ) +</pre> +<P> +<I><B>FORTRAN</B></I>: +<pre> + h5sselect_hyperslab_f (space_id, operator, start, count, & + hdferr, stride, block) + + space_id IN: INTEGER(HID_T) + operator IN: INTEGER + start IN: INTEGER(HSSIZE_T), DIMENSION(*) + count IN: INTEGER(HSIZE_T), DIMENSION(*) + hdferr OUT: INTEGER + stride IN: INTEGER(HSIZE_T), DIMENSION(*), OPTIONAL + block IN: INTEGER(HSIZE_T), DIMENSION(*), OPTIONAL +</pre> +<P> <UL> -<LI>The first parameter, <I>space_id</I>, is the dataspace identifier for the +<LI>The parameter <I>space_id</I> is the dataspace identifier for the specified dataspace. -<LI>The second parameter, <I>op</I>, can only be set to H5S_SELECT_SET - in the current release. It replaces the existing selection with the - parameters from this call. Overlapping blocks are not supported. -<LI>The <I>start</I> array determines the starting coordinates of the hyperslab to select. +<P> +<LI>The parameter <I>operator</I> can be set to one of the following: + <dir><DL> + <dt><CODE>H5S_SELECT_SET</CODE> (<CODE>H5S_SELECT_SET_F</CODE> in FORTRAN) + <dd>Replace the existing selection with the parameters from this call. + Overlapping blocks are not supported with this operator. + + <dt><CODE>H5S_SELECT_OR</CODE> (<CODE>H5S_SELECT_OR_F</CODE> in FORTRAN) + <dd>Add the new selection to the existing selection. + </DL></dir> + +<P> +<LI>The <I>start</I> array determines the starting coordinates of the +hyperslab to select. +<P> <LI>The <I>stride</I> array indicates which elements along a dimension are to be selected. +<P> <LI>The <I>count</I> array determines how many positions to select from the dataspace in each dimension. +<P> <LI>The <I>block</I> array determines the size of the element block selected by the dataspace. +<P> +<LI>In C, a non-negative value is returned if successful, and a negative +value otherwise. In FORTRAN, the return value is returned in <I>hdferr</I>: +0 if successful and -1 otherwise. </UL> <P> The <I>start</I>, <I>stride</I>, <I>count</I>, and <I>block</I> arrays must be the same size as the rank of the dataspace. <P> -<LI>This example introduces the following H5Dget_* functions: -<UL> - <B>H5Dget_space:</B> returns an identifier for a copy of the dataspace - of a dataset.<BR> - <B>H5Dget_type:</B> returns an identifier for a copy of the data type - of a dataset.<BR> -</UL> +<LI>The examples introduce the following call: +<dir><dl> + <dt><code>H5Dget_space / h5dget_space_f:</code> + <dd>Returns an identifier for a copy of the dataspace of a dataset.<P> +</dl></dir> +<LI>The C example also introduces the following calls: +<dir><dl> + <dt><code>H5Sget_simple_extent_dims:</code> + <dd>Returns the size and maximum size of each dimension of a dataspace. + <dt><code>H5Sget_simple_extent_ndims:</code> + <dd>Determines the dimensionality (or rank) of a dataspace. +</dl></dir> <P> -<LI>This example introduces the following H5Sget_* functions used to -obtain information about selections: -<UL> - <B>H5Sget_simple_extent_dims:</B> returns the size and maximum sizes - of each dimension of a dataspace.<BR> - <B>H5Sget_simple_extent_ndims:</B> determines the dimensionality - (or rank) of a dataspace. <BR> +The FORTRAN example does not use these calls, though they +are available as <CODE>h5sget_simple_extent_dims_f</CODE> and +<CODE>h5sget_simple_extent_ndims_f</CODE>. + </UL> </UL> </UL> @@ -439,8 +297,11 @@ obtain information about selections: <!-- <A HREF="helpdesk.mail.html"> --> <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> hdfhelp@ncsa.uiuc.edu</A> -<BR> <H6>Last Modified: August 27, 1999</H6><BR> +<br> +Describes HDF5 Release 1.2.2, June 2000 +<BR> <H6>Last Modified: April 5, 2000</H6><BR> <!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu --> +<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu --> </FONT> <BR> <!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> --> |