diff options
Diffstat (limited to 'doc/html/Tutor/crtdat.html')
| -rw-r--r-- | doc/html/Tutor/crtdat.html | 437 |
1 files changed, 299 insertions, 138 deletions
diff --git a/doc/html/Tutor/crtdat.html b/doc/html/Tutor/crtdat.html index cb07ccd..867a089 100644 --- a/doc/html/Tutor/crtdat.html +++ b/doc/html/Tutor/crtdat.html @@ -36,68 +36,132 @@ width=78 height=27 alt="NCSA"><P></A> <P> A dataset is a multidimensional array of data elements, together with supporting metadata. To create a dataset, the application program must specify -the location to create the dataset, the dataset name, the data type and space -of the data array, and the dataset creation properties. +the location at which to create the dataset, the dataset name, the datatype +and dataspace of the data array, and the dataset creation property list. <P> - <H3> Data Types</H3> - A data type is a collection of data type properties, all of which can + <H3> Datatypes</H3> + A datatype is a collection of datatype properties, all of which can be stored on disk, and which when taken as a whole, provide complete - information for data conversion to or from that data type. + information for data conversion to or from that datatype. <P> - There are two categories of data types in HDF5: atomic and compound data - types. An atomic type is a type which cannot be decomposed into smaller - units at the API level. A compound data type is a collection of one or more - atomic types or small arrays of such types. + There are two categories of datatypes in HDF5: atomic and compound + datatypes. An <i>atomic datatype</i> is a datatype which cannot be + decomposed into smaller datatype units at the API level. + These include the integer, float, date and time, string, bitfield, and + opaque datatypes. + A <i>compound datatype</i> is a collection of one or more + atomic datatypes and/or small arrays of such datatypes. <P> - Atomic types include integer, float, date and time, string, bit field, and - opaque. Figure 5.1 shows the HDF5 data types. Some of the HDF5 predefined - atomic data types are listed in Figure 5.2. In this tutorial, we consider - only - HDF5 predefined integers. For information on data types, see the HDF5 - User's Guide. + Figure 5.1 shows the HDF5 datatypes. Some of the HDF5 predefined + atomic datatypes are listed in Figures 5.2a and 5.2b. + In this tutorial, we consider only HDF5 predefined integers. + For further information on datatypes, see + <a href="../Datatypes.html">The Datatype Interface (H5T)</a> in the + <cite>HDF5 User's Guide</cite>. <P> - <B>Fig 5.1</B> <I>HDF5 data types</I> + <B>Fig 5.1</B> <I>HDF5 datatypes</I> <PRE> +-- integer +-- floating point +---- atomic ----+-- date and time | +-- character string - HDF5 datatypes --| +-- bit field + HDF5 datatypes --| +-- bitfield | +-- opaque | +---- compound </PRE> - <B>Fig. 5.2</B> <I>Examples of HDF5 predefined data types</I> -<table width="52%" border="1" cellpadding="4"> + +<table width="100%" border="0" cellpadding="4"> +<tr><td valign=top> + + <B>Fig. 5.2a</B> <I>Examples of HDF5 predefined datatypes</I> + +<table width="95%" border="1" cellpadding="0"> <tr bgcolor="#ffcc99" bordercolor="#FFFFFF"> - <td width="20%"><b>Data Type</b></td> + <td width="20%"><b>Datatype</b></td> <td width="80%"><b>Description</b></td> </tr> <tr bordercolor="#FFFFFF"> - <td bgcolor="#99cccc" width="20%">H5T_STD_I32LE</td> - <td width="80%">Four-byte, little-endian, signed two's complement integer</td> + <td bgcolor="#99cccc" width="20%"><code>H5T_STD_I32LE</code></td> + <td width="80%">Four-byte, little-endian, signed, two's complement integer</td> </tr> <tr bordercolor="#FFFFFF"> - <td bgcolor="#99cccc" width="20%">H5T_STD_U16BE</td> + <td bgcolor="#99cccc" width="20%"><code>H5T_STD_U16BE</code></td> <td width="80%">Two-byte, big-endian, unsigned integer</td> </tr> <tr bordercolor="#FFFFFF"> - <td bgcolor="#99cccc" width="20%">H5T_IEEE_F32BE</td> + <td bgcolor="#99cccc" width="20%"><code>H5T_IEEE_F32BE</code></td> <td width="80%">Four-byte, big-endian, IEEE floating point</td> </tr> <tr bordercolor="#FFFFFF"> - <td bgcolor="#99cccc" width="20%">H5T_IEEE_F64LE</td> + <td bgcolor="#99cccc" width="20%"><code>H5T_IEEE_F64LE</code></td> <td width="80%">Eight-byte, little-endian, IEEE floating point</td> </tr> <tr bordercolor="#FFFFFF"> - <td bgcolor="#99cccc" width="20%">H5T_C_S1</td> + <td bgcolor="#99cccc" width="20%"><code>H5T_C_S1</code></td> <td width="80%">One-byte, null-terminated string of eight-bit characters</td> </tr> </table> - <H3>Dataspaces</H3> +</td><td valign=top> + + <B>Fig. 5.2b</B> <I>Examples of HDF5 predefined native datatypes</I> +<table width="95%" border="1" cellpadding="4"> + <tr bgcolor="#ffcc99" bordercolor="#FFFFFF"> + <td width="20%"><b>Native Datatype</b></td> + <td width="80%"><b>Corresponding C or FORTRAN Type</b></td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><B>C:</B></td> + <td width="80%"> </td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><code>H5T_NATIVE_INT</code></td> + <td width="80%">int</td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><code>H5T_NATIVE_FLOAT</code></td> + <td width="80%">float</td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><code>H5T_NATIVE_CHAR</code></td> + <td width="80%">char</td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><code>H5T_NATIVE_DOUBLE</code></td> + <td width="80%">double</td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><code>H5T_NATIVE_LDOUBLE</code></td> + <td width="80%">long double</td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><B>FORTRAN:</B></td> + <td width="80%"> </td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><code>H5T_NATIVE_INT</code></td> + <td width="80%">integer</td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><code>H5T_NATIVE_REAL</code></td> + <td width="80%">real</td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><code>H5T_NATIVE_DOUBLE</code></td> + <td width="80%">double precision</td> + </tr> + <tr bordercolor="#FFFFFF"> + <td bgcolor="#99cccc" width="20%"><code>H5T_NATIVE_CHAR</code></td> + <td width="80%">character</td> + </tr> +</table> + +</table> + + <H3> Datasets and Dataspaces</H3> A dataspace describes the dimensionality of the data array. A dataspace is either a regular N-dimensional array of data points, called a simple @@ -114,27 +178,29 @@ of the data array, and the dataset creation properties. </PRE> The dimensions of a dataset can be fixed (unchanging), or they may be - unlimited, which means that they are extendible. A dataspace can also - describe portions of a dataset, making it possible to do partial I/O + unlimited, which means that they are extensible. A dataspace can also + describe a portion of a dataset, making it possible to do partial I/O operations on selections. - <h3>Dataset creation properties</H3> + <h3>Dataset Creation Property Lists</H3> - When creating a dataset, HDF5 allows users to specify how raw data is - organized on disk and how the raw data is compressed. This information is + When creating a dataset, HDF5 allows the user to specify how raw data is + organized and/or compressed on disk. This information is stored in a dataset creation property list and passed to the dataset interface. The raw data on disk can be stored contiguously (in the same - linear way that it is organized in memory), partitioned into chunks and - stored externally, etc. In this tutorial, we use the default creation - property list; that is, no compression and - contiguous storage layout is used. For more information about the creation - properties, see the HDF5 User's Guide. + linear way that it is organized in memory), partitioned into chunks, + stored externally, etc. In this tutorial, we use the + default dataset creation property list; that is, contiguous storage layout + and no compression are used. For more information about + dataset creation property lists, + see <a href="../Datasets.html">The Dataset Interface (H5D)</a> + in the <cite>HDF5 User's Guide</cite>. <P> -In HDF5, data types and spaces are independent objects, which are created -separately from any dataset that they might be attached to. Because of this the -creation of a dataset requires definitions of data type and dataspace. -In this tutorial, we use HDF5 predefined data types (integer) and consider +In HDF5, datatypes and dataspaces are independent objects which are created +separately from any dataset that they might be attached to. Because of this, +the creation of a dataset requires definition of the datatype and dataspace. +In this tutorial, we use HDF5 predefined datatypes (integer) and consider only simple dataspaces. Hence, only the creation of dataspace objects is needed. <P> @@ -142,158 +208,250 @@ needed. To create an empty dataset (no data written) the following steps need to be taken: <OL> -<LI> Obtain the location id where the dataset is to be created. -<LI> Define the dataset characteristics and creation properties. +<LI> Obtain the location identifier where the dataset is to be created. +<LI> Define the dataset characteristics and the dataset creation property list. <UL> - <LI> define a data type - <LI> define a dataspace - <LI> specify dataset creation properties + <LI> Define a datatype. + <LI> Define a dataspace. + <LI> Specify the dataset creation property list. </UL> <LI> Create the dataset. -<LI> Close the data type, dataspace, and the property list if necessary. +<LI> Close the datatype, the dataspace, and the property list if necessary. <LI> Close the dataset. </OL> -To create a simple dataspace, the calling program must contain the following -calls: +To create a simple dataspace, the calling program must contain a +call to create and close the dataspace. For example: +<P> +<I>C</I>: +<PRE> + space_id = H5Screate_simple (rank, dims, maxdims); + status = H5Sclose (space_id ); +</PRE> +<I>FORTRAN</I>: <PRE> - dataspace_id = H5Screate_simple(rank, dims, maxdims); - H5Sclose(dataspace_id ); + CALL h5screate_simple_f (rank, dims, space_id, hdferr, maxdims=max_dims) + <i>or</i> + CALL h5screate_simple_f (rank, dims, space_id, hdferr) + + CALL h5sclose_f (space_id, hdferr) </PRE> -To create a dataset, the calling program must contain the following calls: +To create a dataset, the calling program must contain calls to create +and close the dataset. For example: +<P> +<I>C</I>: <PRE> - dataset_id = H5Dcreate(hid_t loc_id, const char *name, hid_t type_id, - hid_t space_id, hid_t create_plist_id); - H5Dclose (dataset_id); + dset_id = H5Dcreate (hid_t loc_id, const char *name, hid_t type_id, + hid_t space_id, hid_t creation_prp); + status = H5Dclose (dset_id); </PRE> +<I>FORTRAN</I>: +<PRE> + CALL h5dcreate_f (loc_id, name, type_id, space_id, dset_id, & + hdferr, creation_prp=creat_plist_id) + <i>or</i> + CALL h5dcreate_f (loc_id, name, type_id, space_id, dset_id, hdferr) + CALL h5dclose_f (dset_id, hdferr) +</PRE> +If using the pre-defined datatypes in FORTRAN, then a call must +be made to initialize and terminate access to the pre-defined datatypes: +<PRE> + CALL h5init_types_f (hdferr) + CALL h5close_types_f (hdferr) +</PRE> +<code>h5init_types_f</code> must be called before any HDF5 library +subroutine calls are made; +<code>h5close_types_f</code> must be called after the final HDF5 library +subroutine call. +See the programming example below for an illustration of the use of +these calls. <P> <H2> Programming Example</H2> <A NAME="desc"> <H3><U>Description</U></H3> The following example shows how to create an empty dataset. -It creates a file called 'dset.h5', defines the dataset dataspace, creates a +It creates a file called <code>dset.h5</code> in the C version +(<code>dsetf.h5</code> in Fortran), defines the dataset dataspace, creates a dataset which is a 4x6 integer array, and then closes the dataspace, the dataset, and the file. <BR> -[ <A HREF="examples/h5_crtdat.c">Download h5_crtdat.c</A> ] -<PRE> -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -#include <hdf5.h> -#define FILE "dset.h5" - -main() { - - hid_t file_id, dataset_id, dataspace_id; /* identifiers */ - hsize_t dims[2]; - herr_t status; - - /* Create a new file using default properties. */ - file_id = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); - - /* Create the data - space for the dataset. */ - dims[0] = 4; - dims[1] = 6; - dataspace_id = H5Screate_simple(2, dims, NULL); - - /* Create the dataset. */ - dataset_id = H5Dcreate(file_id, "/dset", H5T_STD_I32BE, dataspace_id, - H5P_DEFAULT); - - /* End access to the dataset and release resources used by it. */ - status = H5Dclose(dataset_id); - - /* Terminate access to the data space. */ - status = H5Sclose(dataspace_id); +<UL> +[ <A HREF="examples/h5_crtdat.c">C Example</A> ] + -- <code>h5_crtdat.c</code><BR> +[ <A HREF="examples/dsetexample.f90">Fortran Example</A> ] + -- <code>dsetexample.f90</code><BR> +[ <A HREF="examples/java/CreateDataset.java">Java Example</A> ] + -- <code>CreateDataset.java</code> +</UL> - /* Close the file. */ - status = H5Fclose(file_id); -} -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -</PRE> +<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 of this tutorial. <A NAME="rem"> <H3><U>Remarks</U></H3> <UL> -<LI> H5Screate_simple creates a new simple data space and returns a data space - identifier. +<LI><code>H5Screate_simple</code>/<code>h5screate_simple_f</code> +creates a new simple dataspace and returns a dataspace identifier. <PRE> +<I>C</I>: hid_t H5Screate_simple (int rank, const hsize_t * dims, const hsize_t * maxdims) +<I>FORTRAN</I>: + h5screate_simple_f (rank, dims, space_id, hdferr, maxdims) + + rank INTEGER + dims(*) INTEGER(HSIZE_T) + space_id INTEGER(HID_T) + hdferr INTEGER + (Valid values: 0 on success and -1 on failure) + maxdims(*) INTEGER(HSIZE_T), OPTIONAL </PRE> <UL> - <LI> The first parameter specifies the rank of the dataset. - - <LI> The second parameter specifies the size of the dataset. - - <LI> The third parameter is for the upper limit on the size of the dataset. - If it is NULL, the upper limit is the same as the dimension - sizes specified by the second parameter. + <LI> The <I>rank</I> parameter specifies the rank, i.e., the number of + dimensions, of the dataset. + + <LI> The <I>dims</I> parameter specifies the size of the dataset. + + <LI>The <I>maxdims</I> parameter specifies the upper limit on the + size of the dataset. + If this parameter is NULL in C (or not specified in FORTRAN), + then the upper limit is the same as the dimension + sizes specified by the <I>dims</I> parameter. + <LI>The function returns the dataspace identifier in C if successful; + otherwise it returns a negative value. + In FORTRAN, the dataspace identifier + is returned in the <I>space_id</I> parameter. If the call is successul + then a 0 is returned in <I>hdferr</I>; otherwise a -1 is returned. </UL> <P> -<LI> H5Dcreate creates a dataset at the specified location and returns a - dataset identifier. +<LI><code>H5Dcreate</code>/<code>h5dcreate_f</code> creates a dataset +at the specified location and returns a dataset identifier. <PRE> +<I>C</I>: hid_t H5Dcreate (hid_t loc_id, const char *name, hid_t type_id, - hid_t space_id, hid_t create_plist_id) + hid_t space_id, hid_t creation_prp) +<I>FORTRAN</I>: + h5dcreate_f (loc_id, name, type_id, space_id, dset_id, & + hdferr, creation_prp) + + loc_id INTEGER(HID_T) + name CHARACTER(LEN=*) + type_id INTEGER(HID_T) + space_id INTEGER(HID_T) + dset_id INTEGER(HID_T) + hdferr INTEGER + (Valid values: 0 on success and -1 on failure) + creation_prp INTEGER(HID_T), OPTIONAL </PRE> <UL> - <LI> The first parameter is the location identifier. + <LI> The <I>loc_id</I> parameter is the location identifier. +<P> + <LI> The <I>name</I> parameter is the name of the dataset to create. - <LI> The second parameter is the name of the dataset to create. +<P> + <LI> The <I>type_id</I> parameter specifies the datatype identifier. - <LI> The third parameter is the data type identifier. H5T_STD_I32BE, a - 32-bit Big Endian integer, is an HDF atomic data type. +<P> + <LI> The <I>space_id</I> parameter is the dataspace identifier. - <LI> The fourth parameter is the data space identifier. +<P> + <LI> The <I>creation_prp</I> parameter specifies the + dataset creation property list. + <code>H5P_DEFAULT</code> in C and <code>H5P_DEFAULT_F</code> in FORTRAN + specify the default dataset creation property list. + This parameter is optional in FORTRAN; if it is omitted, + the default dataset creation property list will be used. +<P> + <LI> The C function returns the dataset identifier if successful and + a negative value otherwise. The FORTRAN call returns the + dataset identifier in <I>dset_id</I>. If it is successful, then 0 is + returned in <I>hdferr</I>; otherwise a -1 is returned. - <LI> The last parameter specifies the dataset creation property list. - H5P_DEFAULT specifies the default dataset creation property list. </UL> <P> -<LI>H5Dcreate creates an empty array and initializes the data to 0. +<LI><code>H5Dcreate</code>/<code>h5dcreate_f</code> creates an empty array +and initializes the data to 0. <P> -<LI> When a dataset is no longer accessed by a program, H5Dclose must be -called to release the resource used by the dataset. This call is mandatory. +<LI> When a dataset is no longer accessed by a program, +<code>H5Dclose</code>/<code>h5dclose_f</code> must be called to release +the resource used by the dataset. This call is mandatory. <PRE> - hid_t H5Dclose (hid_t dataset_id) +<I>C</I>: + hid_t H5Dclose (hid_t dset_id) +<I>FORTRAN</I>: + h5dclose_f (dset_id, hdferr) + + dset_id INTEGER(HID_T) + hdferr INTEGER + (Valid values: 0 on success and -1 on failure) </PRE> </UL> <A NAME="fc"> <H3><U>File Contents</U></H3> -The file contents of 'dset.h5' are shown is <B>Figure 5.4</B> and <B>Figure 5.5</B>. -<table width="73%" border="1" cellspacing="4" bordercolor="#FFFFFF"> +The contents of the file <code>dset.h5</code> (<code>dsetf.h5</code> +for FORTRAN) are shown in <B>Figure 5.4</B> and <B>Figures 5.5a </B> +and <B>5.5b</B>. +<P> +<table border="0"> +<tr align=left><td> +<B>Figure 5.4</B> <I>Contents of <code>dset.h5</code> ( <code>dsetf.h5</code>)</i> +</td></tr><tr align=center><td> +<IMG src="img002.gif"> </PRE> +</td></tr></table> + +<table width="100%" border="1" cellspacing="4" bordercolor="#FFFFFF"> <tr bordercolor="#FFFFFF"> - <td width="37%"><b>Figure 5.4</b> <i>The Contents of 'dset.h5'</i> - </td> - <td width="63%"><b>Figure 5.5</b> <i>'dset.h5' in DDL</i> </td> + <td width="50%"><b>Figure 5.5a</b> <i><code>dset.h5</code> in DDL</i> </td> + <td width="50%"><b>Figure 5.5b</b> <i><code>dsetf.h5</code> in DDL</i> </td> </tr> <tr bordercolor="#000000"> -<!-- <td width="37%"><IMG src="dseth5.jpg" width="206" height="333"></td> --> - <td width="37%"><IMG src="img002.gif"></td> - <td width="63%"> - <pre> HDF5 "dset.h5" { - GROUP "/" { - DATASET "dset" { - DATATYPE { H5T_STD_I32BE } - DATASPACE { SIMPLE ( 4, 6 ) / ( 4, 6 ) } - DATA { - 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0 - } - } + <td width="35%"> + <PRE> +HDF5 "dset.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 4, 6 ) / ( 4, 6 ) } + DATA { + 0, 0, 0, 0, 0, 0, + 0, 0, 0, 0, 0, 0, + 0, 0, 0, 0, 0, 0, + 0, 0, 0, 0, 0, 0 } + } +} +} +</PRE> + </td> + <td width="35%"> + <pre> +HDF5 "dsetf.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 6, 4 ) / ( 6, 4 ) } + DATA { + 0, 0, 0, 0, + 0, 0, 0, 0, + 0, 0, 0, 0, + 0, 0, 0, 0, + 0, 0, 0, 0, + 0, 0, 0, 0 } + } +} +} </pre> </td> </tr> </table> +<p> +Note in Figures 5.5a and 5.5b that +<code>H5T_STD_I32BE</code>, a 32-bit Big Endian integer, +is an HDF atomic datatype. <A NAME="ddl"> @@ -302,12 +460,12 @@ The following is the simplified DDL dataset definition: <P> <B>Fig. 5.6</B> <I>HDF5 Dataset Definition</I> <PRE> - <dataset> ::= DATASET "<dataset_name>" { <data type> + <dataset> ::= DATASET "<dataset_name>" { <datatype> <dataspace> <data> <dataset_attribute>* } - <data type> ::= DATATYPE { <atomic_type> } + <datatype> ::= DATATYPE { <atomic_type> } <dataspace> ::= DATASPACE { SIMPLE <current_dims> / <max_dims> } @@ -329,8 +487,11 @@ The following is the simplified DDL dataset definition: <!-- <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"> --> |