.TH H5CONVERT 1 "2008 November 21"
.UC 4
.SH NAME
h5convert \- Conversion of files written with hdf5 yorick plugin pre
v0.6.2 to "fixed" format of v0.6.2 and higher
.SH SYNOPSIS
.TP 3
h5convert [-p -v# -f -h] files
.SH DESCRIPTION
.I h5convert
is a shell utility to convert files that were
generated with the HDF5 yorick plugin v<0.6.2 to the new, fixed
format used in v>=0.6.2.

-p   perform in-place conversion (output file name = input file name)

-f   force conversion of files generated with version>0.6.2

-v#  verbose:  -v0:silent  -v1:files  -v2:files and contents

-h   Print out short help

Files generated with v<0.6.2, if read with the hdf5 plugin v>=0.6.2,
will lead to messed up multi-dimensional arrays. To avoid that, you
should convert your files with h5convert. The plugin version >= 0.6.2
now stamp the file with a "generated by" string ("/" group attribute)
which identifies the yorick plugin version. As a sefaguard, h5convert
will refuse to process (convert) these files, so you can batch
process directories, or even apply h5convert to files if you are not
sure they have been converted (important exceptions, see below).

WARNING: do not try to convert files
generated by external HDF resources, as they will be converted while
they should not!  Also, these files may include data type and object
type not yet implemented in the plugin, in which case it will trigger
an error and the file may result corrupted. You have been warned.

The pre-v0.6.2 bug consisted in an inversion of the dimension vector
of multi-dimensional arrays, such as, for instance, a 2x3 array
appeared to hdf5 utilities (frm HDF group, e.g. h5dump) as a 3x2
array, but with the elements untransposed, e.g.:

Written by yorick:
  1   2   3
  4   5   6

Read by h5dump:
  1   2
  3   4
  5   6

If you are not using HDF group utilities, or more generally, you are
only using hdf5 files within yorick (read/write), thus bug did not
affect you. However, you should still process all your h5 files if you
upgrade to the plugin version v>=0.6.2 (recommended).

.PP
.SH AUTHOR
.PP
Francois Rigaut, Gemini Observatory
.PP
.SH BUGS
This is a patch for a previous bug. Beware: the flag "-p" will rename
the converted file to the original name when done. Beware! This should
be safe, but I haven't tested all possible scenario (i.e. objects
type). This will erase your original data. I encourage you to check
this conversion function on a few files before using this option.  In
particular, do not try to convert files generated by external HDF
resources, as they will be converted while they should not!  Also,
these files may include data type and object type not yet implemented
in the plugin, in which case it will trigger an error and the file may
result corrupted. You have been warned.
.SH SEE ALSO
yorick(1)