[ HDF5 Tutorial Top ]

Property Lists

The property list interface provides a mechanism for adding functionality to HDF5 calls, without increasing the number of arguments used for a given call.

A property list is a collection of values which can be passed to various HDF5 functions to control features that are typically unimportant or whose default values are usually used (by specifying H5P_DEFAULT / H5P_DEFAULT_F).

It supports unusual cases when:

Creating Files
Accessing Files
Creating Datasets
Reading or Writing Data

Creating Files

The File Creation property list, H5P_FILE_CREATE, applies to H5Fcreate() only and is used to control the file metadata which is maintained in the super block of the file. The parameters that can be modified are: user-block size, offset and length sizes, symbol table parameters, and index storage parameters.

The following example shows how to create a file with 64-bit object offsets and lengths:

        hid_t create_plist;
        hid_t file_id;

        create_plist = H5Pcreate(H5P_FILE_CREATE);
        H5Pset_sizes(create_plist, 8, 8);

        file_id = H5Fcreate("test.h5", H5F_ACC_TRUNC,
                             create_plist, H5P_DEFAULT);
        .
        .
        .
        H5Fclose(file_id);

Accessing Files

The File Access property list, H5P_FILE_ACCESS, applies to H5Fcreate() and H5Fopen() and is used to control different methods of performing I/O on files. The different types of I/O are: unbuffered I/O, buffered I/O, memory I/O, parallel files using MPI I/O, and data alignment.

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

Creating Datasets

The Dataset Creation property list, H5P_DATASET_CREATE, applies to H5Dcreate() and controls information on how raw data is organized on disk and how the raw data is compressed. The dataset API partitions these terms by layout, compression, and external storage:

Layout:
- H5D_CHUNKED: The data is large and can be extended in any dimension. It is partitioned into chunks so each chunk is the same logical size. Following is an example that uses the H5P_DATASET_CREATE property list to create a chunked and extendible dataset:
  [ C program ] - h5_extend.c
Compression: (gzip compression)
External Storage Properties: The data must be contiguous to be stored externally. It allows you to store the data in one or more non-HDF5 files. Following is an example of using the H5P_DATASET_CREATE property list to create a dataset in an external file:
[ C program ] - h5_crtextd.c

Reading or Writing Data

The Data Transfer property list, H5P_DATASET_XFER, is used to control various aspects of I/O, such as caching hints or collective I/O information.

The following code sets the maximum size for the type conversion buffer and background buffer:

   plist_xfer = H5Pcreate (H5P_DATASET_XFER);
   H5Pset_buffer(plist_xfer, (hsize_t)NX*NY*NZ, NULL, NULL);
   status = H5Dread (dataset, H5T_NATIVE_UCHAR, memspace, dataspace,
                      plist_xfer);

The National Center for Supercomputing Applications
University of Illinois at Urbana-Champaign

hdfhelp@ncsa.uiuc.edu

Property Lists

Creating Files

Accessing Files

Creating Datasets

Reading or Writing Data

Last Modified: June 22, 2001