HDF5.0使用简介_chinese

国家卫星气象中心（NSMC）
HDF5.0 使用简介
HDF5.0 使用简介

国家卫星气象中心（NSMC）
HDF5.0 使用简介
目
录
1、介绍（Introduction）.............................................................................................................1 2、HDF5 文件组织（File Organization）..................................................................................1 3、HDF5 应用程序接口（API）......................................................................................................2 4、创建 HDF5 文件（Creating an HDF5 File）.........................................................................3 4.1 什么是 HDF5 文件? ...........................................................................................................3 4.2 程序例子（Programming Example）................................................................................4 4.2.1 描述（Description）..........................................................................................4 4.2.2 备注（Remarks）..................................................................................................5 4.2.3 文件内容（File Contents）..............................................................................6 4.2.4 DDL 中的文件定义（File Definition in DDL） ............................................7 5、创建数据集（Creating a Dataset）.....................................................................................7 5.1 什么是数据集（What is a Dataset）..........................................................................7 5.2 数据类型（Datatypes）..........................................................................................7 5.3 数据集和数据空间（Datasets and Dataspaces） ..............................................9 5.4 数据集创建特性列表（Dataset Creation Property Lists） ..........................9 5.2 程序例子（Programming Example）............................................................................10 5.2.1 描述（Description）........................................................................................10 5.2.2 备注（Remarks）................................................................................................11 5.2.3 文件内容（File Contents）............................................................................12 5.2.4 DDL 中的数据集定义（Dataset Definition in DDL） ................................13 6、创建一个群组（Creating a Group）...................................................................................14 6.1 什么是群组（What is a Group）?..............................................................................14 6.2 程序例子（Programming Example）............................................................................15 6.2.1 描述（Description）........................................................................................15 6.2.2 备注（Remarks）................................................................................................15 6.2.3 文件内容（File Contents）............................................................................16 7、创建属性（Creating an Attribute）.................................................................................17 7.1 什么是属性（Attribute）?..........................................................................................17

国家卫星气象中心（NSMC）
HDF5.0 使用简介
7.1.1 创建一个属性（Creating an attribute） ....................................................17 7.1.2 读/写属性（Reading/Writing an attribute） ............................................18 7.2 编程例子（Programming Example）............................................................................18 7.2.1 描述（Description）........................................................................................18 7.2.2 备注（Remarks）................................................................................................19 7.2.3 文件内容（File Contents）............................................................................21 7.2.4 DDL 中的属性定义（Attribute Definition in DDL） ................................22 8、读出和写入数据集（Reading from and Writing to a Dataset） .................................22 8.1 读出和写入数据集（Reading from and Writing to a Dataset） ........................22 8.2 编程例子（Programming Example）............................................................................23 8.2.1 描述（Description）........................................................................................23 8.2.2 备注（Remarks）................................................................................................24 8.2.3 文件内容（File Contents）............................................................................27 9、复合数据类型（Compound Datatypes）...............................................................................28 9.1 创建复合数据类型（Creating Compound Datatypes） ............................................28 9.2 程序例子（Programming Example）............................................................................29 9.2.1 描述（Description）........................................................................................29 9.2.2 备注（Remarks）................................................................................................29 9.2.3 文件内容（File Contents）............................................................................30

国家卫星气象中心（NSMC）
HDF5.0 使用简介
说明:
本教材不包含编译例程所需的软件。
Introductory Topics Introduction HDF5 File Organization The HDF5 API Create an HDF5 File Create Dataset Dataset Read/Write Create Attribute Create Group Create Group - Abs/Rel Create Dataset in Group [ Questions ] [ Answers ]
Advanced Topics Property Lists Compound Datatypes Hyperslab Selection Point Selection References to Objects
Parallel HDF5 Design Overview Parallel Programming Create/Access File Create/Access Dataset Write/Read Hyperslabs
High Level APIs
Other Tutorial Examples Utilities: h5ls/h5dump
References to Regions - by Contiguous Hyperslab Extendible Datasets Mounting Files Group Iteration
- by Regularly Spaced Data References - by Pattern - by Chunk

国家卫星气象中心（NSMC）
HDF5.0 使用简介
1、介绍（INTRODUCTION）欢迎使用由 HDF 用户支持组提供的 HDF5 使用教材 HDF5 是用于存储科学数据的一种文件格式和库文件。它被设计并实现满足科学数据存 储不断增加和数据处理不断变化的需求， 为了充分利用当今计算机系统的能力和特点， 克服 HDF4.x 的不足。HDF5 有一个强大和灵活的数据模块，支持管理的文件大于 2 GB（HDF4.x 管理文件的极限），并且还支持并行 I/O。设计时考虑了安全线程并将在不久的将来实现此 功能。为了便于简单了解 HDF5 的数据模式、库函数和工具，请参看存放于 URL 地址 （36ab5058804d2b160b4ec08e/HDF5/papers/HDF5_overview/index.htm）里的幻灯片。 本使用教材涵盖了基本的 HDF5 数据对象和文件结构，HDF5 程序模块、创建和修改数 据对象的 API 功能。还将介绍用于存取 HDF5 文件的一些有用的工具。
本教材使用的程序例子以及编译它们的 Makefile 在 ./examples/子目录里。为了使用 Makefile 文件,用户也许不得不编辑和更新编译器和编译器选项，以及发布的 HDF5 的目录 路径。Java 程序例子在./examples/ 目录下的名为 java/子目录里。Java/目录有一个 Makefile 文件和运行 java 程序的脚本文件（shell scripts）。 对于其它 HDF5 程序的程序例子，请参看 References 里的指示标记。 希望这个程序例子和用法说明入门能帮助用户很方便地使用 HDF5。 任何意见和建议直接发给：hdfhelp@36ab5058804d2b160b4ec08e.
2、HDF5 文件组织（FILE ORGANIZATION）一个 HDF5 文件就是一个由两种基本数据对象（groups and datasets）存放多种科学数 据的容器：? ?
HDF5 group: 包含 0 个或多个 HDF5 对象以及支持元数据（metadata）的一个群组结 构。 HDF5 dataset: 数据元素的一个多维数组以及支持元数据（metadata）
任何 HDF5 的群组或数据集或许都有一个对应的属性列表。HDF5 属性是一个用户自定义的 HDF5 结构，能为 HDF5 对象提供附加信息。
-1-

国家卫星气象中心（NSMC）
HDF5.0 使用简介
使用群组和数据集时在许多方面类似于使用 UNIX 的目录和文件。 HDF5 文件里的对象经常通 过它的绝对路径来引用。 / signifies the root group. /foo signifies a member of the root group called foo. /foo/zoo signifies a member of the group foo, which in turn is a member of the root group.
3、HDF5 应用程序接口（API）HDF5 函数库提供几个应用程序接口（API）。这些 API 提供用于创建、存取、处理 HDF5 文件和对象的例程。 库函数本身是由 C 程序实现的。为了便于 FORTRAN90 和 Java 程序员的工作，HDF5 包装 的外壳函数也已经用这些语言开发出来了。到写此用户教材时，用 C++包装的外壳函数正在 开发中。本教材只涉及 C 和 FORTRAN 的外壳包装函数。 HDF5 库中所有 C 的例程都有一个前缀形式 H5*开始，这里的*是一个或两个大写字母， 表明有关函数操作对象的类型。 FORTRAN 外壳包装是以子程序由 h5 开始和_f 结束的。 而 API 列表如下： 描述 库函数：H5 函数的通用目的
API H5
H5A 注解(Annotation)接口：属性存取(access)和操作例程 H5D 数据集接口：数据集存取和操作接口 H5E 错误接口：错误处理例程 H5F 文件接口：文件存取例程 H5G 群组接口：群组创建和运行例程 H5I 标识号接口：标识号例程
H5P 特性（Property）列表接口：对象特性列表操作例程 H5R 引用接口：引用例程 H5S 数据大小接口：数据大小定义和存取例程 H5T 数据类型接口：数据类型创建和操作例程 H5Z 压缩接口：压缩例程-2-

国家卫星气象中心（NSMC）
HDF5.0 使用简介
4、创建 HDF5 文件（CREATING4.1 什么是 HDF5 文件?
AN
HDF5 FILE）
HDF5 是一个含有科学数据和支持元数据的二进制文件。 HDF5 文件存储对象的基本类型， 即群组和数据集，将在本教材的其它章节讨论。 要创建一个文件，应用程序必须指定一个文件名、文件存取模式、文件创建特性列表、 和文件存取特性列表。?
文件存取模式（File access mode） ：: 当创建一个文件时，假如此文件已经存在，文件存取模式就会指定要发生的动作：o
H5F_ACC_TRUNC 说明如果此文件已经存在， 当前的内容将被删除以便应用程 序可以用新数据重新写此文件。 H5F_ACC_EXCL 说明如果此文件存在，打开则会失败。 如果此文件不存在，则文件的存取参数被忽略。 在所有情况下，对于一个成功创建的文件，应用程序都可以对这个文件进行 读写存取。
o o o
注意对于打开已经存在的文件有两种不同的存取模式：o o
H5F_ACC_RDONLY 说明应用程序只有读取而没有写入任何数据的权利。 H5F_ACC_RDWR 说明应用程序有读写的权利。
更详细的信息请参见《HDF 用户指南》里的 The File Interface (H5F)小节和《HDF5 参考手册》中的 H5F: File Interface 小节。?
文件创建特性列表（File creation property list） ： 文件创建特性列表常被用于控制文件的元数据。文件的元数据包含有关用户块的大 小、HDF5 库使用的不同文件数据结构大小等。此教材中，缺省的文件创建特性列表 是 H5P_DEFAULT。 用户块（user-block）是被 HDF5 库忽略的位于文件开始的固定长度的数据块。用户 块可以用于存放任何数据或对应用有用的信息。 更详细的内容请参见《HDF 用户指南》中的 The File Interface (H5F) 小节。
?
文件存取特性列表（File access property list） ：
-3-

国家卫星气象中心（NSMC）
HDF5.0 使用简介
文件存取特性列表通常被用来控制对文件 I/O 表现采取不同的方法。本教材使用的 缺省文件存取特性列表是 H5P_DEFAULT。 详情见《HDF 用户指南》中的 The File Interface (H5F) 小节。 创建和关闭一个 HDF5 文件的步骤如下： 1. 如果需要，指定文件创建和存取特性列表。 2. 创建文件。 3. 如需要，关闭文件和关闭特性列表 要创建一个 HDF5 文件，调用程序必须包含调用创建和关闭文件。如下例：
C:file_id = H5Fcreate (filename, access_mode, create_id, access_id); status = H5Fclose (file_id);
FORTRAN:CALL h5fcreate_f (filename, access_mode, file_id, hdferr, & creation_prp=create_id, access_prp=access_id)
orCALL h5fcreate_f (filename, access_mode, file_id, hdferr) CALL h5fclose_f (file_id, hdferr) 在 FORTRAN 程序中，文件创建特性列表 creation_prp、和文件存取特性列表 access_prp， 是可选参数；如果使用了缺省值，它们可以被忽略。
4.2 程序例子（Programming Example） 4.2.1 描述（Description）下面的例子表明如何创建和关闭一个 HDF5 文件。用 C 创建一个名为 file.h5 的文件， 和用 FORTRAN 创建 filef.h5 文件，然后关闭它。 [ C Example ] -- h5_crtfile.c [ FORTRAN Example ] -- fileexample.f90
注意: 要下载一个 tar 文件， 包括所有程序例子和一个 Makefile， 请转到 References。
-4-

国家卫星气象中心（NSMC）
HDF5.0 使用简介
4.2.2 备注（Remarks）? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? o
对 C： 头文件 hdf5.h 包括定义和声明， 使用 HDF5 库的任何程序必须把它包括进来。 对 FORTRAN： 模块 HDF5 包含定义和声明，任何使用 HDF5 库的程序必须用它。 H5Fcreate/h5fcreate_f 创建一个 HDF5 文件和返回文件标号。 C: hid_t H5Fcreate (const char *name, unsigned access_mode, hid_t creation_prp, hid_t access_prp) FORTRAN: h5fcreate_f (name, access_mode, file_id, hdferr, creation_prp, access_prp) name access_flag CHARACTER(LEN=*) INTEGER (Valid values: H5F_ACC_RDWR_F, H5F_ACC_RDONLY_F, H5F_ACC_TRUNC_F, H5F_ACC_EXCL_F, INTEGER(HID_T) INTEGER (Valid values: 0 on success and -1 on failure) INTEGER(HID_T), OPTIONAL (Default value: H5P_DEFAULT_F) INTEGER(HID_T), OPTIONAL (Default value: H5P_DEFAULT_F)
H5F_ACC_DEBUG_F) file_id hdferr creation_prp access_prp
? ? ? ?
name 参数指定要创建的文件名。 o 存 取 模 式 参 数 指 明 文 件 模 式 。 假 如 文 件 已 经 存 在 ， H5F_ACC_TRUNC (H5F_ACC_TRUNC_F in FORTRAN)将截取一个文件。 o creation_prp 参数说明文件创建列表。对于 C 语言，用 H5P_DEFAULT 表示 使用了缺省的文件创建列表。这个选项在 FORTRAN 中是可选的；假如没有此 项，缺省的文件创建列表 H5P_DEFAULT_F, 就被使用。 o access_prp 参数说明文件存取特性列表。对于 C 语言，用 H5P_DEFAULT 表 明缺省文件创建特性列表被使用。 此项在 FORTRAN 中是可选的； 如果被忽略， 缺省的文件创建特性列表 H5P_DEFAULT_F, 就被使用。 o 对于 C，如果成功则返回文件标识号，否则返回一个负数。对于 FORTRAN， 文件标识号是通过 file_id 的参数里返回的。如果调用成功，hdferr 返回 一个 0（零）值。否则在将返回一个-1 值。 当一个文件不再被程序存取，H5Fclose/h5fclose_f 必须被调用来释放被这个文件 使用的资源。这个调用是强制性的。 C: herr_t H5Fclose (hid_t file_id)
-5-

国家卫星气象中心（NSMC）
HDF5.0 使用简介
? ? ?
FORTRAN:h5fclose_f(file_id, hdferr) 当一个文件被创建时，根下群组（root group）就被自动创建。 每个文件都有一个 根下群组，群组的路径名通常都是“/” 。
4.2.3 文件内容（File Contents）HDF 开发组已经开发出了检查 HDF5 文件内容的工具。本教材中使用的工具是 HDF5 dumper、h5dump，可以把文件内容显示成可读的形式。根据 HDF5 DDL 语法，h5dump 的输 出形式是有格式的 ASCII 码。 DDL in BNF for HDF5 中使用 Backus-Naur 格式定义了语法。 在 查看文件内容，键入命令： h5dump 图 4.1 使用一个直接图表来表示文件 file.h5 (filef.h5) 的内容。本教材中的直接图表用 椭圆表示 HDF5 的群组，用长方形表示数据集。箭头表示内容的包含方向。 Fig. 4.1
file.h5 (filef.h5) 文件的内容
图 4.2 是文件 file.h5 的文本描述，与 h5dump 生成的一样。HDF5 文件调用了含有一 个群组的 file.h5 的文件，或调用根下的群组。 Fig. 4.2
file.h5 in DDL
HDF5 "file.h5" { GROUP "/" { } }
-6-

国家卫星气象中心（NSMC）
HDF5.0 使用简介
4.2.4 DDL 中的文件定义（File Definition in DDL）图 4.3 是创建 HDF5 文件时简化了的 DDL 文件定义。为了简明，本教材使用了一个简化 的 DDL。更完整和更严格的 DDL 在《HDF 用户指南》的 DDL in BNF for HDF5 小节里。 Fig. 4.3
HDF5 文件定义
DDL 中使用了下面的符号定义：
::= | *
定义为 tname 名的记号 或 的 0 次或多次产生
用于文件定义而简化的 DDL 如下： ::= HDF5 "" { } ::= GROUP "/" { * * } ::= ::= |
5、创建数据集（CREATING
A
DATASET）
5.1 什么是数据集（What is a Dataset）数据集是数据元素的多维数组，同时有支持元数据的能力。要创建一个数据集，应用程 序必须指明数据集的位置、数据集的名字、数据类型和数组的数据大小，以及数据集的创建 特性列表。
5.2 数据类型（Datatypes）数据类型是数据类型特性的集合，它能被存放在磁盘里，作为一个整体，为数据转换的 目标或来源提供完整的数据类型信息。
-7-

国家卫星气象中心（NSMC）
HDF5.0 使用简介
HDF5 里有两种数据类型：元数据类型（atomic）and 复合数据类型（compound）。 元 数据类型在 API 的层面上是不能分解成更小的数据类型单位它包括整型（integer）, 浮点 型（float）, 日期和时间（date and time）, 字串（string）, 比特域（bitfield）, 和 非透明（opaque）数据类型。复合数据类型是一个或多个元数据类型（和/或这些数据类型 小的数组）的集合。 图 5.1 表明了 HDF5 数据类型。图 5.2a 和图 5.2b 列出了一些 HDF5 预定义的元数据类 型。本教材中，只考虑了 HDF5 的预定义整型。关于更详细的数据类型，请参见《HDF5 用户 指南》中 The Datatype Interface (H5T) 小节。 Fig 5.1
HDF5 datatypes
+-- integer +-- floating point +---- atomic ----+-- date and time | HDF5 datatypes --| | | +---- compound +-- character string +-- bitfield +-- opaque
Fig. 5.2a datatypes Datatype
Examples of HDF5 predefined Fig. 5.2b datatypes Description
Examples of HDF5 predefined native
Four-byte, little-endian, signed, H5T_STD_I32LE two's complement integerH5T_STD_U16BE
Native Datatype C:H5T_NATIVE_INT H5T_NATIVE_FLOAT H5T_NATIVE_CHAR
Corresponding C FORTRAN Type
or
int float char double
Two-byte, big-endian, unsigned integer IEEE
Four-byte, H5T_IEEE_F32BE big-endian, floating point Eight-byte, H5T_IEEE_F64LE little-endian, floating pointH5T_C_S1
H5T_NATIVE_DOUBLE
H5T_NATIVE_LDOUBLE long double
IEEE
FORTRAN:H5T_NATIVE_INT H5T_NATIVE_REAL H5T_NATIVE_DOUBLE H5T_NATIVE_CHAR
integer real double precision character
One-byte, null-terminated string of eight-bit characters
-8-

国家卫星气象中心（NSMC）
HDF5.0 使用简介
5.3 数据集和数据空间（Datasets and Dataspaces）数据空间描述了数据数组的维度。 数据空间或者是数据点的有规则的 N 维数组 （称为简 单数据空间） ，或者由其它方式组成的更加通用的数据集合（称为复杂数据空间） 。图 5.3 显示了数据空间。本教材中，只考虑简单数据空间。 Fig 5.3
HDF5 dataspaces
+-- simple HDF5 dataspaces --| +-- complex 数据集的维数可以是固定的（非变化） ，或者是可变的（可扩展） 。数据空间也可以描述一个 数据集的一部分，这就使得对选取的数据集进行局部 I/O 操作成为可能。
5.4 数据集创建特性列表（Dataset Creation Property Lists）创建一个数据集时，HDF5 允许用户指定原始数据在磁盘上如何组织和/或压缩。这个信 息存放在数据集创建特性列表中， 并传递给数据集接口。 磁盘上的这个原始数据集能被连续 存放（与内存管理中的线性方式相同） 、分成大块（chunks）存放、外部存放等。本教材中， 缺省的数据集创建特性列表是连续的非压缩方式。 更详细的关于数据集创建特性列表， 参见 《HDF5 用户指南》中的 The Dataset Interface (H5D) 小节。 在 HDF5 中，数据类型和数据空间是独立的对象，它们分别由任何有关的数据集创建。 因为这点，数据集的创建需要数据类型和数据空间的定义。本教材中，使用了 HDF5 预定义 的数据类型(integer)和仅考虑简单的数据空间。今后，只有数据空间对象的创建才是必须 的。 要创建一个空的数据集（不写数据），参照如下步骤: 1. Obtain the location identifier where the dataset is to be created. 2. Define the dataset characteristics and the dataset creation property list.o o o
Define a datatype. Define a dataspace. Specify the dataset creation property list.
3. Create the dataset. 4. Close the datatype, the dataspace, and the property list if necessary. 5. Close the dataset. 要创建一个简单的数据空间，调用程序必须调用创建和关闭此数据集。见如下例程：-9-

国家卫星气象中心（NSMC）
HDF5.0 使用简介
C:space_id = H5Screate_simple (rank, dims, maxdims); status = H5Sclose (space_id );
FORTRAN:CALL h5screate_simple_f (rank, dims, space_id, hdferr, maxdims=max_dims)
orCALL h5screate_simple_f (rank, dims, space_id, hdferr) CALL h5sclose_f (space_id, hdferr) 要创建一个简单的数据集，调用程序必须调用创建和关闭此数据集。见如下例程：
C: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);
FORTRAN:CALL h5dcreate_f (loc_id, name, type_id, space_id, dset_id, & hdferr, creation_prp=creat_plist_id)
orCALL h5dcreate_f (loc_id, name, type_id, space_id, dset_id, hdferr) CALL h5dclose_f (dset_id, hdferr) 假如在 FORTRAN 中要使用预定义的数据类型， 必须调用对这个预定义的数据类型的初始 化和终止访问： CALL h5open_f (hdferr) CALL h5close_f (hdferr) h5open_f 必须在调用其它 HDF5 子程序库函数之前调用； h5close_f 则必须在调用其它 HDF5 子程序库函数之后调用。参见下面程序例子对这些调用的说明。
5.2 程序例子（Programming Example） 5.2.1 描述（Description）下面例子表示怎样创建一个空的数据集。 它用 C 创建了一个名为的 dset.h5 用 FORTRAN （ 则为 dsetf.h5)，定义了数据集的数据空间，创建了一个 4 x 6 整型数组的数据集，然后关 闭数据空间、数据集和文件。
- 10 -

国家卫星气象中心（NSMC）
HDF5.0 使用简介
[ C Example ] -- h5_crtdat.c [ Fortran Example ] -- dsetexample.f90 NOTE: To download a tar file of the examples, including a Makefile, please go to the References page of this tutorial.
5.2.2 备注（Remarks）? ? ? ? ? ? ? ? ? ? ? ? ? o o o
H5Screate_simple/h5screate_simple_f 创建一个新的简单数据空间并返回一个数 据空间标识号。
C:hid_t H5Screate_simple (int rank, const hsize_t * dims, const hsize_t * maxdims)
FORTRAN:h5screate_simple_f (rank, dims, space_id, hdferr, maxdims) rank dims(*) space_id hdferr INTEGER INTEGER(HSIZE_T) INTEGER(HID_T) INTEGER (Valid values: 0 on success and -1 on failure) maxdims(*) INTEGER(HSIZE_T), OPTIONAL
rank 参数指定秩（rank） ，即数据集维数的个数。 dims 参数指定数据集的大小。The maxdims 参数指定数据集大小的上限。如果在 C 里此参数为 NULL（或 在 FORTRAN 没有被指定） ，上限与由 dim 参数指定的维数大小相同。 假如成功，在 C 中此函数返回数据空间标识号；否则返回一个负数。对于 FORTRAN，数据空间标识号（dataspace identifier）由 space_id 参数返回。 如果调用成功则在 hdferr 中返回 0，否则返回-1。
o
? ? ? ? ? ? ? ? ? ?
H5Dcreate/h5dcreate_f 在指定位置创建一个数据集并返回数据集标识号 （dataset identifier） 。
C:hid_t H5Dcreate (hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t creation_prp)
FORTRAN:h5dcreate_f (loc_id, name, type_id, space_id, dset_id, & hdferr, creation_prp) loc_id name INTEGER(HID_T) CHARACTER(LEN=*)
- 11 -

国家卫星气象中心（NSMC）
HDF5.0 使用简介
? ? ? ? ? ? o o o o o
type_id space_id dset_id hdferr
INTEGER(HID_T) INTEGER(HID_T) INTEGER(HID_T) INTEGER (Valid values: 0 on success and -1 on failure)
creation_prp INTEGER(HID_T), OPTIONAL
loc_id 参数是位置标识号（location identifier） 。 name 参数是要创建的数据集名。 type_id 参数指定的数据类型标识号（datatype identifier） 。 space_id 参数是数据空间标识号（dataspace identifier） 。 creation_prp 参 数 指 定 数 据 集 创 建 属 性 列 表 。 H5P_DEFAULT （ C ） 和H5P_DEFAULT_F （FORTRAN）指定缺省的数据集创建属性列表。在 FORTRAN 这个参数是可选项； 如果省略了， 那么缺省的数据集创建属性列表 （default dataset creation property list）就被使用。
o
如果成功，C 函数返回数据集标识号（dataset identifier）否则返回一个 负数。FORTRAN 在 dset_id 中调用返回的数据集标识号。如成功在 hdferr 返回 0，否则返回-1。
? ?
H5Dcreate/h5dcreate_f 创建一个空的数组并把数据初始化为 0。 当数据集不再被程序存取，When a dataset is no longer accessed by a program, H5Dclose/h5dclose_f 必须被调用来释放由此数据集占用的资源。这种调用是强制 性的。
? ? ? ? ? ? ? ?
C:hid_t H5Dclose (hid_t dset_id)
FORTRAN:h5dclose_f (dset_id, hdferr) dset_id INTEGER(HID_T) hdferr INTEGER (Valid values: 0 on success and -1 on failure)
5.2.3 文件内容（File Contents）文件 dset.h5 的内容(dsetf.h5 for FORTRAN) 如图 a 5.4 and 图 5.5a and 5.5b. Figure 5.4 Contents of dset.h5 ( dsetf.h5)
- 12 -

国家卫星气象中心（NSMC）
HDF5.0 使用简介
Figure 5.5a
dset.h5 in DDL
Figure 5.5b
dsetf.h5 in DDL
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 } } } }
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 } } } }
Note in Figures 5.5a and 5.5b that H5T_STD_I32BE, a 32-bit Big Endian integer, is an HDF atomic datatype.
5.2.4 DDL 中的数据集定义（Dataset Definition in DDL）下面是简单的 DDL 数据集定义： Fig. 5.6
HDF5 Dataset Definition
::= DATASET "" { * }- 13 -

国家卫星气象中心（NSMC）
HDF5.0 使用简介
::= DATATYPE { } ::= DATASPACE { SIMPLE / } ::=
6、创建一个群组（CREATING
A
GROUP）
6.1 什么是群组（What is a Group）?一个 HDF5 群组是一个包含 0 个或多个 HDF5 对象的结构。 HDF5 的两个基本对象是群组和 数据集。要创建一个群组，调用程序必须有： 1. 获取要创建群组的位置标识号（location identifier） 。 2. 创建群组。 3. 关闭群组。 要创建一个群组，程序必须调用 H5Gcreate/h5gcreate_f。要关闭这个群组，函数 H5Gclose/h5gclose_f 必须被调用。例如：
C:group_id = H5Gcreate (loc_id, name, size_hint); status = H5Gclose (group_id);
FORTRAN:CALL h5gcreate_f (loc_id, name, group_id, error, size_hint=size)
orCALL h5gcreate_f (loc_id, name, group_id, error)
CALL h5gclose_f (group_id, error)
- 14 -

国家卫星气象中心（NSMC）
HDF5.0 使用简介
6.2 程序例子（Programming Example） 6.2.1 描述（Description）下面的例子说明怎样创建和关闭一个群组。它创建一个名为 group.h5 (groupf.h5 for FORTRAN)的文件， 在根下 （root） 创建一个名为 MyGroup 的群组， 然后关闭这个群组和文件。 [ C Example ] - h5_crtgrp.c [ FORTRAN Example ] - groupexample.f90 NOTE: To download a tar file of the examples, including a Makefile, please go to the References page.
6.2.2 备注（Remarks）?
H5Gcreate/h5gcreate_f 创建一个新的空群组，名为 MyGroup 位于根下(root)， 并 返回一个群组标识号。
C:hid_t H5Gcreate (hid_t loc_id, const char *name, size_t size_hint)
FORTRAN:h5gcreate_f (loc_id, name, group_id, hdferr, size_hint) loc_id name group_id hdferr INTEGER(HID_T) CHARACTER(LEN=*) INTEGER(HID_T) INTEGER (Possible values: 0 on success and -1 on failure) size_hint INTEGER(SIZE_T), OPTIONAL (Default value: OBJECT_NAMELEN_DEFAULT_F)
o o o
loc_id 参数指明要创建的群组位置。 name 参数指明要创建的群组名字。 size_hint 指定保留多少文件空间（file space）给要存储群组中将出现的名字。假如提供了一个非正值（non-positive value） ，则会使用缺省大小 的空间（default size） 。由于库函数能动态改变名字堆栈（name heap） ， 因此可经常传递一个 0 值。- 15 -

国家卫星气象中心（NSMC）
HDF5.0 使用简介
o
对于 FORTRAN，例程的返回值在 hdferr 中被传递：0 表示成功，-1 表示失 败。 群组标识号在 group_id 里被传递回来。 group identifier is passed The back in. 对于 C，如果成功函数就返回一个有效的群组标识号，否则返回 一个负数。
?
H5Gclose/h5gclose_f 关闭取组。这个调用是不可缺少的。
C:herr_t H5Gclose (hid_t group_id)
FORTRAN:h5gclose_f (group_id, hdferr) group_id INTEGER(HID_T) hdferr INTEGER (Possible values: 0 on success and -1 on failure)
6.2.3 文件内容（File Contents）group.h5 的内容和群组的定义显示如下。and the definition of the group are shown below. (The FORTRAN 程序创建一个名为 groupf.h5 的 HDF 文件，在文件 groupf.h5 里的第 一行显示了作为结果的 DDL。) Fig. 8.1 group.h5. The Contents of Fig. 8.2
group.h5 in DDL
HDF5 "group.h5" { GROUP "/" { GROUP "MyGroup" { } } }
- 16 -

国家卫星气象中心（NSMC）
HDF5.0 使用简介
7、创建属性（CREATING
AN
ATTRIBUTE）
7.1 什么是属性（Attribute）?属性是一些小的数据集，这些数据集可用来描述与此有关对象的本性（nature）和/或 用法（intended usage）。本节将介绍怎样创建、读、写一个属性。
7.1.1 创建一个属性（Creating an attribute）创建一个属性与创建一个数据集相同。 要创建一个属性， 应用程序必须指定关于这个属 性的对象、属性数据的数据类型和数据空间、以及属性创建特性列表（attribute creation property list）。 创建一个属性的步骤如下： 1. 获得与这个属性有关的对象标号（object identifier） 2. 定义属性的特征（characteristics）和指定属性创建特性列表。o o o
定义数据类型。 定义数据空间。 指定属性创建特性列表。
3. 创建属性。 4. 如果需要，关闭属性和数据类型、数据空间和属性创建特性列表。 要创建和关闭一个属性，调用程序必须使用 H5Acreate/h5acreate_f 和 H5Aclose/h5aclose_f. 例如:
C:attr_id = H5Acreate (dset_id, attr_name, type_id, space_id, creation_prp); status = H5Aclose (attr_id);
FORTRAN:CALL h5acreate_f (dset_id, attr_nam, type_id, space_id, attr_id, & hdferr, creation_prp=creat_plist_id)
orCALL h5acreate_f (dset_id, attr_nam, type_id, space_id, attr_id, hdferr) CALL h5aclose_f (attr_id, hdferr)
- 17 -