hdf images hdf images

HDF5 Tutorial:   Advanced Topics
Properties (HDF5 1.6)

Contents:


Description

As defined in the Introductory Topics, a property is a characteristic or feature associated with an HDF5 object, and all HDF5 objects have default properties which handle the most common needs.

The default properties can be modified by use of the Property List interface and function parameters.

The Property List API allows a user to take advantage of the more powerful features in HDF5. In HDF5 1.6, it supports unusual cases when:

There is a programming model for working with property lists in HDF5.

In Summary:

Properties are features of HDF5 objects, that can be changed by use of the Property List API and function parameters.

Property lists provide a mechanism for adding functionality to HDF5 calls without increasing the number of arguments used for a given call.

The Property List API supports unusual cases when creating and accessing HDF5 objects.

Programming Model

Default properties are specified by simply passing in H5P_DEFAULT (C) / H5P_DEFAULT_F (F90) for the property list parameter in those functions for which properties can be changed.

The programming model for changing a property list is as follows:

File Creation Property List

The File Creation property list, H5P_FILE_CREATE, is specified by the third parameter to H5Fcreate and is used to control the file metadata which is maintained in the super block of the file.

Following are some properties you can change with the File Creation property list:

For a complete list of File Creation properties, refer to the Property List Interface in the HDF5 Reference Manual.


Using the Default File Creation Property List

To use a default File Creation property list with H5Fcreate, you would specify H5P_DEFAULT (C) or H5P_DEFAULT_F (F90) for the third parameter, as is highlighted below (in C):

   file_id = H5Fcreate ("file.h5", H5_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);

Some defaults are:

User Block Size 0
Byte Size of offsets and lengths used to address objects Same as sizeof (hsize_t) in the library (normally 8 bytes)
Size of parameters controlling the symbol table nodes 16
Size of parameters controlling B-trees for indexing chunked datasets 32

Modifying the File Creation Property List

To modify the File Creation property list follow these steps:

The following example shows how to modify the File Creation property list to create a file with 64-bit object offsets and lengths. Note that it follows the programming model:

      [ C program ] - h5_filessize.c
      [ F90 program ] - filesetsize.f90

File Access Property List

The File Access property list, H5P_FILE_ACCESS, is specified by a parameter to the following functions, and is used to control different methods of performing I/O (unbuffered, buffered, memory, parallel with MPI I/O, data alignment) on files:
   hid_t H5Fcreate (const char *name, unsigned flags, hid_t create_id, \
                    hid_t access_id )
   hid_t H5Fopen(const char *name, unsigned flags, hid_t access_id  )
Use of File Access property functions can affect performance:

The File Access property list also can modify the usage of the low-level I/O libraries and physical storage:

  1. It can be used to define low level I/O libraries, such as MPI I/O for parallel access (see the Parallel HDF5 Tutorial) and STDIO vs. SEC2.

  2. It can be used to access the Virtual File Layer (VFL), a public API for writing I/O drivers.
    If using the VFL layer, a file does not have to be a file; it can be mapped to multiple files, memory, a network protocol, etc.

    The VFL API allows users to design and implement their own mapping between the HDF5 format address space and storage, with each mapping being a separate file driver:

  3. It can be used to modify the physical storage of an HDF5 file to create:

    • A memory driver (HDF5 file in the application's memory).

    • A stream driver (HDF5 file written to a socket).

    • A Family of Files (using H5Pset_fapl_family).
      This property is useful when an HDF5 file cannot fit on a filesystem. It can be divided into equal sized pieces with the maximum size that will fit on that filesystem. A family member size must be a power of two.

    • Split files (using H5Pset_fapl_split).
      An HDF5 file can be split into two files, one with just metadata, the other with just data:

For a complete list of File Access properties, refer to Chapter 2.7 in the HDF5 User's Guide.

Using the Default File Access Property List

To use a default File Access property list with H5Fcreate or H5Fopen, you would specify H5P_DEFAULT (C) or H5P_DEFAULT_F (F90) for the access_id parameter. Examples (in C) are:
   file_id = H5Fcreate (FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
   file_id = H5Fopen (FILE, H5F_ACC_RDWR, H5P_DEFAULT);
Default Sizes are:

Metadata and Raw Data Chunk Cache 4MB, 1MB
Metadata Block Size 2048
Maximum Size of Data Sieve Buffer 64KB
File Close Degree H5F_CLOSE_WEAK (for all, except parallel, which is H5F_CLOSE_SEMI)

Modifying the Default File Access Property List

To modify the File Access property list, follow these steps:

Following is an example of using the H5P_FILE_ACCESS property list for creating HDF5 files with the metadata and data split into different files:
      [ C program ] - h5split.c
      [ F90 program ] - dsetsplit.f90

Following is an example of using the H5P_FILE_ACCESS property list to create a family of files:
      [ C program ] - h5family.c
      [ F90 program ] - dsetfamily.f90

Dataset Creation Property List

The Dataset Creation property list, H5P_DATASET_CREATE, is a parameter to the H5Dcreate (C) / h5dcreate_f (F90) call. It is used to control information on how raw data is organized on disk:
   hid_t H5Dcreate (hid_t loc_id, const char *name, hid_t type_id, \
                    hid_t space_id, hid_t create_plist_id  )
Following is a list of the properties that are affected by the Dataset Creation Property List. They are not mutually exclusive of each other: An explanation of these properties follows: