/*
 * hdf5doc.txt
 * documentation for the yorick hdf5 plugin
 *
 * $Id: hdf5doc.txt,v 1.1.1.1 2007/12/27 15:10:25 frigaut Exp $
 *
 * Author: Francois Rigaut.
 * Written 2004
 * last revision/addition: 2007dec26
 *
 * Copyright (c) 2003, Francois RIGAUT (frigaut@gemini.edu, Gemini
 * Observatory, 670 N A'Ohoku Place, HILO HI-96720).
 *
 * This program is free software; you can redistribute it and/or  modify it
 * under the terms of the GNU General Public License  as  published  by the
 * Free Software Foundation; either version 2 of the License,  or  (at your
 * option) any later version.
 *
 * This program is distributed in the hope  that  it  will  be  useful, but
 * WITHOUT  ANY   WARRANTY;   without   even   the   implied   warranty  of
 * MERCHANTABILITY or  FITNESS  FOR  A  PARTICULAR  PURPOSE.   See  the GNU
 * General Public License for more details (to receive a  copy  of  the GNU
 * General Public License, write to the Free Software Foundation, Inc., 675
 * Mass Ave, Cambridge, MA 02139, USA).
 *
 * $Log: hdf5doc.txt,v $
 * Revision 1.1.1.1  2007/12/27 15:10:25  frigaut
 * Initial Import - yorick-hdf5
 *
 */

                    HDF5 yorick plugin documentation
                    ================================

                    ********************************
                    ******* DRAFT 2005dec11 ********
                    ********************************

1. Overview

This plugin uses libhdf5, version 1.6.4 or greater. It will probably
work with slightly lesser version, but I haven't tested it. The
current version avilable from the NSCA site is (dec2005) is 1.6.5.

This plugin provide a minimal interface to HDF5 (Hierarchical Data
Format 5). I am not going to expand on HDF5 here. Suffice to say that
this format provides a way to store heterogeneous data in a single
file entity. The data are stored under a hierarchical directory
structure (hence the name), like:

/header
/header/date
/header/time
/header/author
/2005mar25/data/raw/time_vector
/2005mar25/data/raw/entropy
etc...

A directory (e.g. /header) is called a "Group".
A scalar/vector/array of numbers/strings is called "Dataset".

One can also set and store attribute to groups or datasets.

Here is an example of a file as dumped by the h5info function:

> h5info,"data.h5",att=1
/2005mar04                       GROUP   
                                 ATTRIB(0): Temp on this date             
                                 ATTRIB(1): cups of coffee                
/2005mar04/comments              DATASET   STRING  DIMSOF()=[1,2]
/2005mar04/data                  DATASET   DOUBLE  DIMSOF()=[1,100]
/2005mar04/dewpoint              DATASET   DOUBLE  SCALAR
/2005mar04/time                  DATASET   DOUBLE  DIMSOF()=[1,100]
                                 ATTRIB(0): Units                         
                                 ATTRIB(1): Units2                        
/2005mar05                       GROUP   
/2005mar05/name with blanks      DATASET   DOUBLE  SCALAR
/HL                              HARDLINK -> /2005mar04
/bestdata                        SOFTLINK -> /2005mar04
>                                      

which is, I believe, pretty much self-explanatory. Note the hardlink
and softlink references at the end (which are what they say they are:
links to other groups in this file).



2. FUNCTION API

As of v0.6, there are only a handfull of functions, but they should
provide most of the functionality to save regular datas (with the
exception of structure and pointers). These functions are:


  DATA I/O:
     h5read(fname,target)                     return data
     h5write,fname,fullpath,data,zip=         write data
     h5open(filename,mode)                    return file handle
     h5close(filename)                        close file

   INFO, GROUP LINKING:
     h5info,fname,target,att=                 print out file info/structure
     h5link(fname,group,group2link2,linktype) link datasets
     h5delete,fname,object                    delete data

   ATTRIBUTE I/O:
     h5awrite(fname,object,aname,attdata)     write an object attribute
     h5aread(fname,object,aname)              read an object attribute
     h5adelete,fname,object,aname             delete an object attribute

   MISC:
     h5list_open                              list open files
     h5version                                return linhdf5 version
     
   ERROR RECOVERY
     h5off                                    close all reference to the
                                              h5 library (clean up).

Each function is detailled below:


2.1 Data I/O:

2.1.1 h5open

fd = h5open(filename,mode);

Opens file "filename" in mode "mode".
mode can be "r" (read-only), "w" (write-only) or "a" (append).

This function returns a file descriptor fd that can be used until released by a call to h5close. fd can be used with h5read and h5open (see below).

Warning: when a file is opened with h5open, it will have to be explicitely closed with h5close. If a file is open in read-only and one try to reopen it in write-only, it will cause a error (and vice-versa)


2.1.2 h5write

h5write,filename,fullpath_to_dataset,data,zip=,mode=

write "data" as object "fullpath" in file "fname".

fname can be either a string (filename) or a file descriptor returned
by h5open.

The scalar string fullpath contains the full path to the dataset
(/full/path/dataname).

"data" are the data. Any yorick type is valid and will be saved as
such.
 
zip is a long 0-9. if set, data will be compressed (the larger the
number, the more compression, and the larger the compression time).

mode can be set here (when fname is a string). Use "a" it to append
data to an existing file. Default is to overwrite ("w").

2.1.3 h5read

result = h5read(filename,dataset)

return the data pointed to by the scalar string "dataset" in file
"filename". 

2.1.4 h5close

h5close,file

Close all references to the file pointed at by "file". File can either
be a scalar string or a file descriptor (as the one returned by
h5open()).


to be continued...
