.TH "h5jam" 1
.SH NAME
h5jam \- Add a user block to a HDF5 file
.SH SYNOPSIS
.B h5jam 
.B -u
.I user_block
.B -i
.I in_file.h5
.RB [ -o
.IR out_file.h5 ]
.RB [ --clobber ]
.SH DESCRIPTION
.B h5jam
concatenates a
.I user_block
file and an HDF5 file to create an HDF5 file with a user block. The user
block can be either binary or text. The output file is padded so that the
HDF5 header begins on byte 512, 1024, etc.. (See the HDF5 File Format.)
.P
If
.I out_file.h5
is given, a new file is created with the
.I user_block
followed by the contents of
.IR in_file.h5 .
In this case,
.I infile.h5
is unchanged.
.P
If
.I out_file.h5
is not specified, the
.I user_block
is added to
.IR in_file.h5 .  
.P
If
.I in_file.h5
already has a user block, the contents of
.I user_block
will be added to the end of the existing user block, and the file shifted to
the next boundary. If 
.B --clobber
is set, any existing user block will be overwritten. 
.SH EXAMPLE USAGE
Create new file,
.IR newfile.h5 ,
with the text in file
.I mytext.txt
as the user block for the HDF5 file
.IR file.h5 .
.P
	h5jam -u mytext.txt -i file.h5 -o newfile.h5
.P
Add text in file 
.I mytext.txt
to front of HDF5 dataset, 
.IR file.h5 .
.P
	h5jam -u mytext.txt -i file.h5 
.P
Overwrite the user block (if any) in
.I file.h5
with the contents of
.IR mytext.txt .
.P
	h5jam -u mytext.txt -i file.h5 --clobber
.SH RETURN VALUE
.B h5jam
returns the size of the output file, or -1 if an error occurs.
.SH CAVEATS
This tool copies all the data (sequentially) in the file(s) to new
offsets. For a large file, this copy will take a long time.
.P
The most efficient way to create a user block is to create the
file with a user block (see
.BR H5Pset_user_block ),
and write the user block data into that space from a program.
.P
The user block is completely opaque to the HDF5 library and
to the
.B h5jam
and
.B h5unjam
tools.  The user block is simply read or written as a string of bytes,
which could be text or any kind of binary data.  It is up to the user 
to know what the contents of the user block means and how to process it.
.P
When the user block is extracted, all the data is
written to the output, including any padding or
unwritten data.
.P
This tool moves the HDF5 file through byte copies,
i.e., it does not read or interpret the HDF5
objects.
.SH "SEE ALSO"
\&\fIh5dump\fR\|(1), \fIh5ls\fR\|(1), \fIh5diff\fR\|(1),
\&\fIh5import\fR\|(1), \fIgif2h5\fR\|(1), \fIh52gif\fR\|(1),
\fIh5perf\fR\|(1), \fIh5unjam\fR\|(1).