RFC:  A Tool To Fiddle with HDF5 User Blocks
Robert E. McGrath
June 30, 2004

Overview

HDF5 files may have arbitrary user data at the front of the file.  At this time, there are no tools to put or get such a user block for an exiting file.

This RFC presents a proposal for some new utilities to add, show, and remove the user block from an existing HDF5 file.  These tools can be used with any HDF5 file.

The fundamental algorithm is to create a file that contains:

  1. the user block data (can be anything, text or binary)
  2. pads to 512, 1024, etc.
  3. the HDF5 file
This is a simple concatination, except that the HDF5 header block must be at one of the required offsets.

Removing a user block reversese this operation.

Server variations of this operation are described below.  These differ in how the files are managed.  There are, no doubt, many other permutations.

If we can decide on one or more of these variations, it will only take a few days to implement them.  Most of the time will be needed to try to create tests!




Tool Name: jam
                      unjam
Syntax:
jam user_block hdf5_file out_file.h5
jam -h
unjam hdf5_file user_block out_file.h5
unjam -h
h5put_user_block user_block hdf5_file
h5put_user_block -h

h5get_user_block hdf5_file
h5get_user_block -h

Purpose:
Add user block to front of an HDF5 file, to create a new concatenated file. Get user block from file.
Split user block and HDF5 file into two files.

Description:
jam  concatenates a file and and HDF5 file to create an HDF5 file with a user block. The user block can be any test (binary or text).  The output file is padded so that the HDF5 header begins on byte 512, 1024, etc..  See the HDF5 File Format.

unjam splits an HDF5 file, writing the user block to a file and the HDF5 file to an HDF5 file with a header at byte 0 (i.e., with no user block).

h5put_user_block  adds user_block to the fron of the HDF5 file, hdf5_file.  The user block can be any test (binary or text).  The output file is padded so that the HDF5 header begins on byte 512, 1024, etc..  See the HDF5 File Format.

h5get_user_block  prints the user block, if any, to stdout.  Note that the user block may be any data (not just text), and may include padding or junk bytes up to the beginning of the HDF5 header block.  


See Also: