3.1.1 UNIX

1. gzip(including zlib), version 1.1.0 or higher
2. tar
3. make, GNU Make version 3.7x or higher (or compatible) all of which are available from . GNU C (and Fortran) compilers can also be retrieved from this site.

3.1.2 Windows NT

3.1.3 Mac

3.1.4 VMS

3.2.1 UNIX

/usr/local/src % tar xvzf hlhdf_r0.34.tgz

/usr/local/src/hlhdf % ./configure -help

/usr/local/src/hlhdf % make

3.2.2 Windows NT

1. Start a new project by selecting "File - New - Projects - Win32 Static Library". Add appropriate Project name (hlhdf) and Location in this same window. No precompiled headers or MFC support is needed.
2. Tools - Options - Directories. Make sure you add the path to the HDF5 header files.
3. Project - Add to Project - Files. Go to where the source and header files for HL-HDF are located and add them all.
4. Project - Settings - \C{}/\Cpp{}. Set appropriate warning level and optimization.
5. Build - Build hlhdf.lib

3.3.1 UNIX

/usr/local/src/hlhdf/test % make

/usr/local/src/hlhdf/test % testRaveObject read

/usr/local/src/hlhdf/test % testRaveObject write

3.3.2 Windows NT

1. Start a new project by selecting "File - New - Projects - Win32 Console Application". Add appropriate Project name (test) and Location in this same window. Then select "An empty project".
2. Tools - Options - Directories. Add paths to the HL-HDF header files and the newly build library hlhdf.lib. Make sure the paths to the HDF5 headers and library are there as well.
3. Project - Add to Project - Files. Go to where test_raveobject.c is located and add it.
4. Project - Settings - \C{}/\Cpp{}. Set appropriate warning level and optimization.
5. Project - Settings - Link - Object/library modules. Add hlhdf.lib hdf5.lib zlib.lib in this order to the beginning of this list.
6. Build - Build test.exe
7. Open a DOS console and change to the directory containing test.exe. Execute test write to create an HDF test file. Execute test read to query the contents of this file. If this works, then you can be confident that your HL-HDF library works.

3.4.1 UNIX

/usr/local/src/hlhdf % make install

3.4.2 Windows NT

3.5.1 Red Hat Linux 6.2

3.5.2 Red Hat Linux 5.2

3.5.3 Sun

3.5.4 DEC Alpha

3.5.5 HP-UX

3.5.6 SGI

CFLAGS= -woff 1174,1429,1209,1196,1685 -woff 799,803,835 -Wl,-woff,47,-woff,84,-woff,85,-woff,134
           

3.5.7 Cray T3E

3.5.8 Cray C90

3.5.9 Mac

3.5.10 Windows NT

4.2.1 Datatype

4.2.2 Attribute

4.2.3 Reference

4.2.4 Dataset

4.2.5 Group

4.2.6 Node

4.2.7 Scalar

4.2.8 Atomic

4.3.1 hid_t

4.3.2 herr_t

4.3.3 hsize_t

4.3.4 HL_Type

UNDEFINED_ID=-1 
ATTRIBUTE_ID=0
GROUP_ID=1
DATASET_ID=2
TYPE_ID=3
REFERENCE_ID=4
          

4.3.5 HL_DataType

DTYPE_UNDEFINED_ID=-1
HL_SIMPLE=0
HL_ARRAY=1
          

4.3.6 HL_NodeMark

NMARK_ORIGINAL=0
NMARK_CHANGED=1
NMARK_SELECT=2
          

4.3.7 HL_Node

typedef struct HL_Node {
   HL_Type type;           /* the type of node */
   char name[256];         /* the node's name */
   int ndims;              /* the number of dimensions in the array */
   hsize_t dims[4];        /* the dimensions of each of ndims */
   unsigned char* data;    /* actual data (fixed type) */
   unsigned char* rawdata; /* actual raw data, machine dependent */
   char format[64];        /* the string representation of the data type */
   hid_t typeId;           /* reference to HDF's internal type management */
   size_t dSize;           /* size of one value in data (fixed type) */
   size_t rdSize;          /* size of one value in raw data, machine dependent */
   HL_DataType dataType;   /* identifies whether data is single or an array */
   hid_t hdfId;            /* like typeId: for internal use */
   HL_NodeMark mark;       /* is this node marked? */
   HL_CompoundTypeDescription* compoundDescription; /* a list of compound
type descriptions*/
} HL_Node;
           

4.3.8 HL_NodeList

typedef struct {
   char filename[256];  /* a file string */
   char tmp_name[512];  /* temporary names for internal use */
   int nNodes;          /* the number of nodes in the list */
   int nAllocNodes;     /* the number of allocated nodes in the list; internal */
   HL_Node** nodes;     /* the nodes themselves */
} HL_NodeList;
          

4.3.9 HL_CompoundTypeAttribute

typedef struct {
   char attrname[256];  /* the Attribute's name */
   size_t offset;       /* the offset to where the data begins */
   char format[256];    /* the string representation of the atomic data type */
   int ndims;           /* the number of dimensions in the array */
   size_t dims[4];      /* the dimensions of each of ndims */
} HL_CompoundTypeAttribute;
          

4.3.10 HL_CompoundTypeDescription

typedef struct {
   char typename[256];          /* the list's name */
   unsigned long objno[2];      /* markers used to tag nodes in the list */
   size_t size;                 /* size of this data type */
   int nAttrs;                  /* the number of attributes in the list */
   int nAllocAttrs;             /* the number of allocated attributes */
   HL_CompoundTypeAttribute** attrs; /* the attributes themselves */
} HL_CompoundTypeDescription;
          

5.1.1 initHlHdf

Initiates the HL-HDF functions. This call must be made before anything else is done. Returns nothing.

5.1.2 disableErrorReporting

Deactivates HDF5 debugging. Returns nothing.

5.1.3 enableErrorReporting

Activates HDF5 debugging. Returns nothing.

5.1.4 debugHlHdf

Sets the debug mode. flag can be 0 (no debugging), 1 (debug only HL-HDF), or 2 (debug HL-HDF and HDF5). Returns nothing.

5.1.5 isHdf5File

Checks whether filename is an HDF5 file. Returns 1 if it is and 0 otherwise.

5.1.6 openHlHdfFile

Opens an HDF5 file. Arguments: filename: String containing the files name. how: What mode that should be used for opening the file, can be 'r' (read only), 'w' (write only) or 'rw' (read and write). Returns the hid_t reference upon success otherwise -1.

5.1.7 createHlHdfFile

Creates an HDF5 file filename, if the file already exists it will be truncated. filename is the name of the file to be created. Returns the hid_t reference upon success otherwise -1.

5.1.8 closeHlHdfFile

Closes the HDF5 file with the hid_t reference file_id. Returns a value greater or equal to 0 upon success otherwise a negative value.

5.1.9 getFixedType

Translates from the datatype specified by type to a native datatype. Returns the native datatype hid_t upon success, or a negative value on failure.

5.1.10 translateCharToDatatype

Creates an HDF5 datatype hid_t from the string representation dataType. dataType can be one of: char, schar, uchar, short, ushort, int, uint, long, ulong, llong, ullong, float, double, hsize, hssize, herr or hbool. Returns a value < 0 upon failure, otherwise a hid_t reference to the new type.

5.1.11 getTypeNameString

Translates the HDF5 type type to an HDF5 string representation of the datatype. The returned string can be one of: H5T_STD_I8BE, H5T_STD_I8LE, H5T_STD_I16BE, H5T_STD_I16LE, H5T_STD_I32BE, H5T_STD_I32LE, H5T_STD_I64BE, H5T_STD_I64LE, H5T_STD_U8BE, H5T_STD_U8LE, H5T_STD_U16BE, H5T_STD_U16LE, H5T_STD_U32BE, H5T_STD_U32LE, H5T_STD_U64BE, H5T_STD_U64LE, H5T_NATIVE_SCHAR, H5T_NATIVE_UCHAR, H5T_NATIVE_SHORT, H5T_NATIVE_USHORT, H5T_NATIVE_INT, H5T_NATIVE_UINT, H5T_NATIVE_LONG, H5T_NATIVE_ULONG, H5T_NATIVE_LLONG, H5T_NATIVE_ULLONG, H5T_IEEE_F32BE, H5T_IEEE_F32LE, H5T_IEEE_F64BE, H5T_IEEE_F64LE, H5T_NATIVE_FLOAT, H5T_NATIVE_DOUBLE, H5T_NATIVE_LDOUBLE, H5T_STRING or H5T_COMPOUND. Returns the string representation upon success, otherwise NULL.

5.1.12 getFormatNameString

Translates the HDF5 type type to a HL-HDF string representation of the datatype. The returned string can be one of dataType can be one of char, schar, uchar, short, ushort, int, uint, long, ulong, llong, ullong, float, double, hsize, hssize, herr, hbool, string or compound. Returns the string representation upon success, otherwise NULL.

5.1.13 getStringPadName

Returns a string representation of the type type's padding. The returned string can be one of H5T_STR_NULLTERM, H5T_STR_NULLPAD, H5T_STR_SPACEPAD or ILLEGAL STRPAD. Returns the string representation upon success, otherwise NULL.

5.1.14 getStringCsetName

Returns a string representation of the type type's character set. The returned string can be one of H5T_CSET_ASCII or UNKNOWN CHARACTER SET. Returns the string representation upon success, otherwise NULL.

5.1.15 getStringCtypeName

Returns a string representation of the type type's character type. The returned string can be one of H5T_C_S1, H5T_FORTRAN_S1 or UNKNOWN CHARACTER TYPE. Returns the string representation upon success, otherwise NULL.

5.1.16 whatSizeIsHdfFormat

Calculates the size in bytes that the specified type takes. The attribute format can be one of char, schar, uchar, short, ushort, int, uint, long, ulong, llong, ullong, float, double, hsize, hssize, herr or hbool. Returns the size in bytes if successful or -1 in case of failure.

5.1.17 isFormatSupported

Checks wether the string type format is recognized. format can be one of char, schar, uchar, short, ushort, int, uint, long, ulong, llong, ullong, float, double, hsize, hssize, herr or hbool. Returns 1 if the format is supported, otherwise 0.

5.1.18 newHL_Node

Defines a new, empty node of undefined type. name is a string used to identify the node. Returns the node if successful or NULL upon failure.

5.1.19 newHL_NodeList

Creates an empty HL node list which can be filled with an arbitrary number of nodes. Returns the node list if successful or NULL upon failure.

5.1.20 freeHL_Node

Frees a node from memory. The node is given as the only argument. Returns nothing.

5.1.21 freeHL_NodeList

Frees a complete node list from memory, along with all the nodes contained in it. The node list is given as the only argument. Returns nothing.

5.1.22 newHL_Group

Creates an empty HL node of Group type. name is a string used to identify the node. Returns the node if successful or NULL upon failure.

5.1.23 newHL_Attribute

Creates an empty HL node of Attribute type. name is a string used to identify the node. Returns the node if successful or NULL upon failure.

5.1.24 newHL_Reference

Creates an empty HL node of Reference type. name is a string used to identify the node. Returns the node if successful or NULL upon failure.

5.1.25 newHL_Dataset

Creates an empty HL node of Dataset type. name is a string used to identify the node. Returns the node if successful or NULL upon failure.

5.1.26 newHL_Datatype

Creates an empty HL node of Datatype type. name is a string used to identify the node. Returns the node if successful or NULL upon failure.

5.1.27 newHL_CompoundTypeAttribute

5.1.28 newHL_CompoundTypeDescription

Creates a list containing HL_CompoundTypeAttributes. Returns the compound type list if successful or NULL upon failure.

5.1.29 freeHL_CompoundTypeAttribute

Frees a given compound type attribute from memory. The only argument is the HL_CompoundTypeAttribute to be freed. Returns nothing.

5.1.30 freeHL_CompoundTypeDescription

Frees the compound type list, along with all its members, from memory. The only argument is the HL_CompoundTypeDescription to be freed. Returns nothing.

5.1.31 addNode

Appends a node to (the end of) a node list. Note: If this operation is successful the responsibility for releasing the memory of the node node is taken by the nodelist, so do not release the node afterwards. Arguments: nodelist: The node list. node: The node to append to nodelist. Returns 1 if successful and 0 otherwise.

5.1.32 getNode

Provides a reference to a node from a node list. Note: A reference to the node is returned, so do not release the node when finished with the node. Arguments: nodelist: The node list. nodeName: A string identifying the node to extract. Returns (a reference to) the node if it is found, and NULL if not.

5.1.33 setScalarValue

Writes a scalar value to a node. Scalar values are individual atomic words. Arguments: node: The node in which to write the value. sz: Size of the data type. value: The value to write. fmt: String representation of the data format, for example "short", "signed int" or "double". typid: Reference to used data type. Must be set manually if using a compound data type, otherwise set it to -1. Returns 1 if successful and 0 otherwise.

5.1.34 setArrayValue

Writes an array to a node. Arguments: node: The node in which to write the array. sz: Size of the data type. ndims: The number of dimensions of the array, which may range from 0 to 4. dims: The dimensions of each of ndims. value: The array to write. fmt: String representation of the data format. typid: Reference to used data type. Must be set manually if using a compound data type, otherwise set it to -1. Returns 1 if successful and 0 otherwise.

5.1.35 extractParentChildName

Seperates the last node (the child) in a node name consisting of several nodes (the parent). For example, for a node name given as /group1/group2/group3, this function will set /group1/group2 as the parent and group3 as the child. Arguments: node: The node under scrutiny. parent: A string to hold the parent's node name. child: A string to hold the child's node name. Returns 1 if successful and 0 otherwise.

5.1.36 commitDatatype

If a compound type has been created and there is a wish to have this node "named", then use this function for marking this node to be committed. See the HDF5 documentation for a more detailed description on what "committed" means. Arguments: node: A Datatype node to mark. testStruct_hid: The HDF5 hid_t reference to the datatype. Returns 1 if successful and 0 otherwise.

5.1.37 scanNodeList

Prints the names in a node list to the terminal. The only argument is the node list. Returns nothing.

5.1.38 findCompoundTypeDescription

5.1.39 scanCompoundTypeDescription

Prints to the terminal the names of all nodes in the typelist list of compound nodes. Returns nothing.

5.3.1 readHL_NodeListFrom

Recursively reads the HDF5 file filename from the group fromPath and builds a list of nodes with corresponding names. I.e. no data will be read at this step, just the nodetypes and names will be determined. Returns an HL_NodeList pointer upon success, otherwise NULL.

5.3.2 readHL_NodeList

Recursively read the HDF5 file filename from the root group and builds a list of nodes with corresponding names. I.e. no data will be read at this step, just the nodetypes and names will be determined. Returns an HL_NodeList pointer upon success, otherwise NULL.

5.3.3 selectNode

Marks the node with name name in the nodelist for retrival. Returns 1 upon success, otherwise 0.

5.3.4 selectAllNodes

Marks all nodes in the nodelist for retrival. Returns 1 upon success, otherwise 0.

5.3.5 fetchMarkedNodes

Reads all nodes in the nodelist that has been marked for retrival. Returns 1 upon success, otherwise 0.

5.3.6 fillAttributeNode

Fills the attribute node node with data and dimensions from the file referenced by file_id. Returns 1 upon success, otherwise 0.

5.3.7 fillReferenceNode

Fills the reference node node with data from the file referenced by file_id. The data field in the node will be filled with a string that specifies the name of the referenced node. Returns 1 upon success, otherwise 0.

5.3.8 fillDatasetNode

Fills the dataset node node with data and dimensions from the file referenced by file_id. Returns 1 upon success, otherwise 0.

5.3.9 fillGroupNode

Fills the group node node with data from the file referenced by file_id. Returns 1 upon success, otherwise 0.

5.3.10 fillTypeNode

Fills the type node node with data from the file referenced by file_id. Returns 1 upon success, otherwise 0.

5.3.11 fillNodeWithData

Fills the node node with data from the file referenced by file_id. Returns 1 upon success, otherwise 0.

5.3.12 buildTypeDescriptionFromTypeHid

Builds a compound type description from the type type_id reference. \\ Returns a HL_CompoundTypeDescription pointer upon success, otherwise NULL.

5.3.13 locateNameForReference

This is a helper function for locating the name of an object that is referenced by ref in the file file_id. Returns a pointer to a string upon success, otherwise NULL.

5.4.1 commitType

Commits a datatype. See the HDF5 documentation for more detailed descriptions on what "committed" means. Arguments: loc_id: Where should the datatype be placed. name: What should the datatype be called. type_id: The hid_t reference to the datatype. Returns a negative value upon failure, otherwise the operation was successful.

5.4.2 createStringType

Creates a HDF5 string type of length length. Returns a negative value upon failure, otherwise a hid_t reference to the datatype.

5.4.3 setTypeSize

Changes the size of the datatype referenced by type_id to the size theSize. Returns a negative value upon failure, otherwise the operation was successful.

5.4.4 closeType

Closes the datatype referenced by type_id. Returns a negative value upon failure, otherwise the operation was successful.

5.4.5 writeScalarDataAttribute

Writes a scalar value to an HDF5 file. Arguments: loc_id: The group or dataset the attribute should be written to. type_id: The datatype of the attribute. name: The name that should be used for the attribute. buf: The data that should be written. Returns 0 upon success, otherwise -1.

5.4.6 writeScalarDataAttribute_fmt

Writes a scalar value to an HDF5 file. Arguments: loc_id: The group or dataset the attribute should be written to. fmt: A string describing the format of the datatype, e.g. char, short, ... name: The name that should be used for the attribute. buf: The data that should be written. Returns 0 upon success, otherwise -1.

5.4.7 writeSimpleDataAttribute

5.4.8 writeSimpleDataAttribute_fmt

5.4.9 createSimpleDataset

5.4.10 createSimpleDataset_fmt

5.4.11 closeDataset

Closes the dataset referenced by loc_id. Returns a negative value upon failiure, otherwise the operation was successful.

5.4.12 createCompoundType

Creates a compound type with the size size. Returns a negative value upon failiure, otherwise a hid_t reference.

5.4.13 addAttributeToCompoundType

Adds an scalar attribute to a compound type. Arguments: loc_id: The type the attribute should be appended to, name: The name of the attribute. offset: At what offset in the data does this attribute begin. type_id: The datatype of the attribute. Returns a negative value upon failure, otherwise the operation was successful.

5.4.14 addAttributeToCompoundType_fmt

Adds an scalar attribute to a compound type. Arguments: loc_id: The type the attribute should be appended to. name: The name of the attribute. offset: At what offset in the data does this attribute begin. fmt: A string describing the format of the datatype, e.g. char, short, ... Returns a negative value upon failure, otherwise the operation was successful.

5.4.15 addArrayToCompoundType

Adds an array attribute to a compound type. Arguments: loc_id: The type the attribute should be appended to. name: The name of the attribute. offset: At what offset in the data does this attribute begin. ndims: The rank of the data to be written, between 0-4. dims: The dimensions of the data, a pointer to ndims number of hsize_t values. type_id: The datatype of the attribute. Returns a negative value upon failiure, otherwise the operation was successful.

5.4.16 addArrayToCompoundType_fmt

5.4.17 createGroup

Creates a group in an HDF5 file. Arguments: loc_id: The group or file reference the group should be written to. groupname: The name of the group to be written. comment: A comment of the group, if NULL, no comment will be added to the group. Returns a negative value on failure, otherwise a hid_t reference.

5.4.18 closeGroup

Closes a group referenced by loc_id. Returns a negative value upon failure, otherwise the operation was successful.

5.4.19 createReference

Creates a reference from name in object loc_id to the object with the name targetname which must be a complete path in the file file_id. For example, to create a reference from PALETTE to the dataset /GRP/PALETTE one should write createReference(loc_id,file_id,"PALETTE","/GRP/PALETTE"). loc_id: The object where the reference name should be created. file_id: The file the reference should be created in. name: The name of the reference to be created. targetname: The referenced object, must be a complete path. Note that the referenced object must always be created before creating a reference to it. Returns 0 upon success, otherwise -1

5.4.20 doWriteHdf5Attribute

5.4.21 doWriteHdf5Group

5.4.22 doWriteHdf5Dataset

5.4.23 doCommitHdf5Datatype

5.4.24 writeNodeList

Writes a nodelist in HDF5 format. Arguments: nodelist: The nodelist to be written. doCompress: The compression level that should be used on the datasets, betwen 0-9 where 0 is no compression and 9 is highest compression. Returns 1 upon success, otherwise 0.

5.5.1 doAppendHdf5Attribute

5.5.2 doAppendHdf5Group

5.5.3 doAppendHdf5Dataset

5.5.4 updateNodeList

5.6.1 newGroup

Creates a new group named name and attaches this group to the parentGroup. If the parentGroup is NULL, then the created group will be the root group. Returns the new group upon success or NULL upon failure.

5.6.2 newDataset

Creates a new dataset named name and attaches this dataset to the parentGroup. Returns the new dataset upon success or NULL upon failiure.

5.6.3 newNameListType

Creates a new type object. Returns the allocated type upon success or NULL upon failure.

5.6.4 newAttribute

Creates a new attribute with the name name, if name is NULL, then the attribute will be nameless. Returns the allocated attribute upon success or NULL upon failure.

5.6.5 newCompoundAttribute

Creates a new compound attribute definition with the name name, if name is NULL, then the attribute will be nameless. Returns the allocated compound attribute definition upon success or NULL upon failure.

5.6.6 createCompoundFromType

Translates an NameListType_t instance to a compound attribute definition instance and then gives the compound attribute definition the name name. Returns the allocated compound attribute definition upon success or NULL upon failure.

5.6.7 addCompoundAttributeToType

Adds the compound attribute definition compoundAttr to the name list type newType. Returns a value $\geq$ 0 upon success, otherwise -1.

5.6.8 addAttributeToGroup

Adds the attribute attr to the group group. Returns 0 upon success otherwise -1.

5.6.9 addAttributeToDataset

Adds the attribute attr to the dataset dset. Returns 0 upon success otherwise -1.

5.6.10 freeCompoundAttribute

Deallocates the compound attribute definition attr. Returns nothing.

5.6.11 freeAttribute

Deallocates the attribute attr. Returns nothing.

5.6.12 freeNameListType

Deallocates the name list type type. Returns nothing.

5.6.13 freeInternalDataset

Deallocates the internals for the dataset dset. Returns nothing.

5.6.14 freeDataset

Deallocates the dataset dset. Returns nothing.

5.6.15 addTypeToLocalGroup

Adds the type type to the local list of types in the group group. Returns a value $\geq$ 0 upon success otherwise -1.

5.6.16 addTypeToGlobalGroup

Adds the type type to the global list of types in the group group. Returns a value $\geq$ 0 upon success otherwise -1.

5.6.17 doesTypeExistInGlobalGroup

Searches the global list of types in the group grp if any occurence of the objno exists. Arguments: grp: The group that should be searched in. objno: An list of two unsigned long's. Returns the index number in the global list if an occurance was found otherwise -1.

5.6.18 doesTypeExistInLocalGroup

Searches the local list of types in the group grp if any occurence of the objno exists. Arguments: grp: The group that should be searched in. objno: A list of two unsigned long's. Returns the index number in the local list if an occurance was found otherwise -1.

5.6.19 removeTypeFromLocalGroup

Removes the type with a matching objno from the group group's list of local types and returns the type. Arguments: group: The group that should be searched. objno: A list of two unsigned long's. Returns the type with a matching object number if it was found, otherwise NULL

5.6.20 removeTypeFromGlobalGroup

Removes the type with a matching objno from the group group's list of global types and returns the type. Arguments: group: The group that should be searched. objno: A list of two unsigned long's. Returns the type with a matching object number if it was found, otherwise NULL

5.6.21 displayDataBuffer

Displays the data in a format similar to the one produced when using h5dump distributed with the HDF5 distribution. Arguments: data: A pointer to the data. fmt: The hlhdf string representation of the dataformat. ndims: The rank of the data. dims: The dimensions of the data. typeSize: The size of each value. offs: The number of blanks that should be padded before the data. addNewline: If a linebreak should be added or not, 1 means add linebreak. Returns nothing.

5.6.22 displayCompoundDataset

Displays a compound dataset in a format similar to the one produced when using h5dump distributed with the HDF5 distribution. Arguments: data: The data pointer. type: The compound type definition. ndims: The rank of the data. dims: The dimensions of the data. offs: The number of blanks that should be padded before the data. Returns nothing

5.6.23 displayCompoundAttributeDef

Displays one attribute in a compound attribute in a format similar to the one produced when using h5dump distributed with the HDF5 distribution. Arguments: def: The compound attribute definition. offs: The number of blanks that should be padded before the data. Returns nothing

5.6.24 displayType

Displays one datatype in a format similar to the one produced when using h5dump distributed with the HDF5 distribution. Arguments: type: The datatype to display. offs: The number of blanks that should be padded before the data. Returns nothing.

5.6.25 displayAttribute

Displays one attribute in a format similar to the one produced when using h5dump distributed with the HDF5 distribution. Arguments: attr: The attribute to display. offs: The number of blanks that should be padded before the data. Returns nothing.

5.6.26 displayDataset

Displays one dataset in a format similar to the one produced when using h5dump distributed with the HDF5 distribution. Arguments: dset: The dataset to display. offs: The number of blanks that should be padded before the data. Returns nothing.

5.6.27 displayGroup

Displays one group in a format similar to the one produced when using h5dump distributed with the HDF5 distribution. This function will recursively go through all sub-groups belonging to this group. Arguments: grp: The group to display. offs: The number of blanks that should be padded before the data. Returns nothing.

5.6.28 readHlHdfFile

Recursively reads a complete HDF5 file with name filename and builds a complete tree structure. Returns a pointer to a NameListGroup_t instance upon success, otherwise NULL.

5.6.29 readHlHdfFileFrom

Recursively reads an HDF5 file with name filename from the group from and builds a complete tree structure. Returns a pointer to a NameListGroup_t instance upon success, otherwise NULL.

5.6.30 read_hlhdf_free

Frees a HDF5 tree structure that has been read by using either readHlHdfFile or readHlHdfFileFrom. Be aware that this function must be used if one of the two functions above was used since it knows how the tree structure was built. Returns nothing.

8.3.1 nodelist

8.3.2 node

Sets a scalar value in the node instance. itemSize is used for specifying the size of the value in bytes. It is not necessary to specify unless a compound type is set. data is the data to be set in the node. typename is the string representation of the datatype, for example int, string, compound, \ldots lhid is the hid_t reference to the datatype, is not nessecary to specify unless a compound type is set.

NOTE: If the data to be set is of compound type, then the data should be of string type.
NOTE: If the node is a Reference node, the data should be set as a string type, where the data is the name of the referenced node.

Sets an array value in the node instance. itemSize is used for specifying the size of the value in bytes. It is not nessecary to specify unless a compound type is set. dims is a list of dimensions of the data. data is the data to be set in the node. typename is the string representation of the datatype, for example int, string, compound, \ldots lhid is the hid_t reference to the datatype, is not nessecary to specify unless a compound type should be set.

NOTE: If the data to be set is of compound type, the data should be of string type.

Marks a TYPE_ID node to be committed. datatype is the hid_t reference to the datatype.

Returns the name of the node instance.

Returns the type of the node instance.

Returns a list of the dimensions of the node instance

Returns the string representation of the node's datatype.

Returns the fixed data of the node instance.

NOTE: If the data is of compound type, the data will be returned as a string.

Returns the raw data of the node instance.
NOTE: If the data is of compound type, the data will be returned as a string.

Returns a dictionary with all attributes in the compund attribute, it only works if the node instance is a compound attribute.

8.4.1 Writing a simple HDF5 file

import _pyhl
from Numeric import *

# Create an empty node list instance
aList = _pyhl.nodelist()

# Create an group called info
aNode = _pyhl.node(_pyhl.GROUP_ID,"/info")

# Add the node to the nodelist
# Remember that the nodelist takes responsibility
aList.addNode(aNode)

# Insert the attribute xscale in the group "/info"
aNode = _pyhl.node(_pyhl.ATTRIBUTE_ID,"/info/xscale")

# Set the value to a double with value 10.0
# Note the -1's that has been used since the data not is compaound
aNode.setScalarValue(-1,10.0,"double",-1)
aList.addNode(aNode)

# Similar for yscale,xsize and ysize
aNode = _pyhl.node(_pyhl.ATTRIBUTE_ID,"/info/yscale")
aNode.setScalarValue(-1,20.0,"double",-1)
aList.addNode(aNode)
aNode = _pyhl.node(_pyhl.ATTRIBUTE_ID,"/info/xsize")
aNode.setScalarValue(-1,10,"int",-1)
aList.addNode(aNode)
aNode = _pyhl.node(_pyhl.ATTRIBUTE_ID,"/info/ysize")
aNode.setScalarValue(-1,10,"int",-1)
aList.addNode(aNode)

# Add a description
aNode = _pyhl.node(_pyhl.ATTRIBUTE_ID,"/info/description")
aNode.setScalarValue(-1,"This is a simple example","string",-1)
aList.addNode(aNode)

# Add an array of data
myArray = arange(100)
myArray = array(myArray.astype('i'),'i')
myArray = reshape(myArray,(10,10))
aNode = _pyhl.node(_pyhl.DATASET_ID,"/data")

# Set the data as an array, note the list with [10,10] which
# Indicates that it is an array of 10x10 items
aNode.setArrayValue(-1,[10,10],myArray,"int",-1)
aList.addNode(aNode)

# And now just write the file as "simple_test.hdf" with
# Compression level 9 (highest compression)
aList.write("simple_test.hdf",9)
          

HDF5 "simple_test.hdf" {
GROUP "/" {
   DATASET "data" {
      DATATYPE { H5T_STD_I32LE }
      DATASPACE { SIMPLE ( 10, 10 ) / ( 10, 10 ) }
      DATA {
         0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
         10, 11, 12, 13, 14, 15, 16, 17, 18, 19,
         20, 21, 22, 23, 24, 25, 26, 27, 28, 29,
         30, 31, 32, 33, 34, 35, 36, 37, 38, 39,
         40, 41, 42, 43, 44, 45, 46, 47, 48, 49,
         50, 51, 52, 53, 54, 55, 56, 57, 58, 59,
         60, 61, 62, 63, 64, 65, 66, 67, 68, 69,
         70, 71, 72, 73, 74, 75, 76, 77, 78, 79,
         80, 81, 82, 83, 84, 85, 86, 87, 88, 89,
         90, 91, 92, 93, 94, 95, 96, 97, 98, 99
      }
   }
   GROUP "info" {
      ATTRIBUTE "xscale" {
         DATATYPE { H5T_IEEE_F64LE }
         DATASPACE { SCALAR }
         DATA {
            10
         }
      }
      ATTRIBUTE "yscale" {
         DATATYPE { H5T_IEEE_F64LE }
         DATASPACE { SCALAR }
         DATA {
            20
         }
      }
      ATTRIBUTE "xsize" {
         DATATYPE { H5T_STD_I32LE }
         DATASPACE { SCALAR }
         DATA {
            10
         }
      }
      ATTRIBUTE "ysize" {
         DATATYPE { H5T_STD_I32LE }
         DATASPACE { SCALAR }
         DATA {
            10
         }
      }
      ATTRIBUTE "description" {
         DATATYPE {
            { STRSIZE 25;
              STRPAD H5T_STR_NULLTERM;
              CSET H5T_CSET_ASCII;
              CTYPE H5T_C_S1;
            }
         }
         DATASPACE { SCALAR }
         DATA {
            "This is a simple example"
         }
      }
   }
}
}
          

8.4.2 Writing an HDF5 file containing a compound datatype

import _pyhl
import _rave_info_type

# Create the rave info HDF5 type
typedef = _rave_info_type.type()

# Create the rave info HDF5 object
obj = _rave_info_type.object()

# Set the values
obj.xsize=10
obj.ysize=10
obj.xscale=150.0
obj.yscale=150.0

aList = _pyhl.nodelist()

# Create a datatype node
aNode = _pyhl.node(_pyhl.TYPE_ID,"/MyDatatype")

# Make the datatype named
aNode.commit(typedef.hid())
aList.addNode(aNode)

# Create an attribute containing the compound type
aNode = _pyhl.node(_pyhl.ATTRIBUTE_ID,"/myCompoundAttribute")

# Note that I use both itemSize and lhid
# Also note how I translate the compound object to a string
aNode.setScalarValue(typedef.size(),obj.tostring(),"compound",typedef.hid())
aList.addNode(aNode)

# Better create a dataset also with the compound type
obj.xsize=1
obj.ysize=1
aNode = _pyhl.node(_pyhl.DATASET_ID,"/myCompoundDataset")

# I use setArrayValue instead
aNode.setArrayValue(typedef.size(),[1],obj.tostring(),"compound",typedef.hid())
aList.addNode(aNode)

# And finally write the HDF5 file.
aList.write("compound_test.hdf")
          

HDF5 "compound_test.hdf" {
GROUP "/" {
   ATTRIBUTE "myCompoundAttribute" {
      DATATYPE {
         H5T_STD_I32LE "xsize";
         H5T_STD_I32LE "ysize";
         H5T_IEEE_F64LE "xscale";
         H5T_IEEE_F64LE "yscale";
      }
      DATASPACE { SCALAR }
      DATA {
         {
            [ 10 ],
            [ 10 ],
            [ 150 ],
            [ 150 ]
         }
      }
   }
   DATATYPE "MyDatatype" {
      H5T_STD_I32LE "xsize";
      H5T_STD_I32LE "ysize";
      H5T_IEEE_F64LE "xscale";
      H5T_IEEE_F64LE "yscale";
   }
   DATASET "myCompoundDataset" {
      DATATYPE {
         "/MyDatatype"
      }
      DATASPACE { SIMPLE ( 1 ) / ( 1 ) }
      DATA {
         {
            [ 1 ],
            [ 1 ],
            [ 150 ],
            [ 150 ]
         }
      }
   }
}
}
          

8.4.3 Reading a simple HDF5 file

# Read the file
aList = _pyhl.read_nodelist("simple_test.hdf")

# Select individual nodes, instead of all of them
aList.selectNode("/info/xscale")
aList.selectNode("/info/yscale")
aList.selectNode("/data")

# Fetch the data for selected nodes
aList.fetch()

# Print the data
aNode = aList.getNode("/info/xscale")
print "XSCALE=" + `aNode.data()`
aNode = aList.getNode("/info/yscale")
print "YSCALE=" + `aNode.data()`
aNode = aList.getNode("/data")
print "DATA=" + `aNode.data()`
          

8.4.4 Reading an HDF5 file containing a compound type

import _pyhl
import _rave_info_type

# There is no meaning creating the type
obj = _rave_info_type.object()
aList = _pyhl.read_nodelist("compound_test.hdf")

# Select everything for retrival
aList.selectAll()
aList.fetch()
aNode = aList.getNode("/myCompoundAttribute")

# Translate from the string representation to object
obj.fromstring(aNode.rawdata())

# Display the values
print "XSIZE="+`obj.xsize`
print "YSIZE="+`obj.ysize`
print "XSCALE="+`obj.xscale`
print "YSCALE="+`obj.yscale`
          

8.4.5 Reading an HDF5 file containing a compound type (alterntive)

import _pyhl
import _rave_info_type

# There is no meaning creating the type
obj = _rave_info_type.object()
aList = _pyhl.read_nodelist("compound_test.hdf")

# Select everything for retrival
aList.selectAll()
aList.fetch()
aNode = aList.getNode("/myCompoundAttribute")

# Translate from the string representation to object
cdescr = obj.compound_data()
obj.xsize = cdescr["xsize"]
obj.ysize = cdescr["ysize"]
obj.xscale = cdescr["xscale"]
obj.yscale = cdescr["yscale"]

# Display the values
print "XSIZE="+`obj.xsize`
print "YSIZE="+`obj.ysize`
print "XSCALE="+`obj.xscale`
print "YSCALE="+`obj.yscale`
          

8.4.6 Creating a HDF5 image with a reference

import _pyhl
from Numeric import *

# Function for creating a dummy palette
def createPalette():
  a=zeros((256,3),'b')
  for i in range(0,256):
    a[i][0]=i
  return a

# Function for creating a dummy image}

def createImage():
  a=zeros((256,256),'b')
    for i in range(0,256):
      for j in range(0,256):
        a[i][j] = i
  return a

# Function for the HDF5 file
def create_test_image():
  a=_pyhl.nodelist()

  # First create the palette}

  b=_pyhl.node(_pyhl.DATASET_ID,"/PALETTE")
  c=createPalette()
  b.setArrayValue(1,[256,3],c,"uchar",-1)
  a.addNode(b)
  b=_pyhl.node(_pyhl.ATTRIBUTE_ID,"/PALETTE/CLASS")
  b.setScalarValue(-1,"PALETTE","string",-1)
  a.addNode(b)
  b=_pyhl.node(_pyhl.ATTRIBUTE_ID,"/PALETTE/PAL_VERSION")
  b.setScalarValue(-1,"1.2","string",-1)
  a.addNode(b)
  b=_pyhl.node(_pyhl.ATTRIBUTE_ID,"/PALETTE/PAL_COLORMODEL")
  b.setScalarValue(-1,"RGB","string",-1)
  a.addNode(b)
  b=_pyhl.node(_pyhl.ATTRIBUTE_ID,"/PALETTE/PAL_TYPE")
  b.setScalarValue(-1,"STANDARD8","string",-1)
  a.addNode(b)

  # Now create the image to display}

  b=_pyhl.node(_pyhl.DATASET_ID,"/IMAGE1")
  c=createImage()
  b.setArrayValue(1,[256,256],c,"uchar",-1)
  a.addNode(b)
  b=_pyhl.node(_pyhl.ATTRIBUTE_ID,"/IMAGE1/CLASS")
  b.setScalarValue(-1,"IMAGE","string",-1)
  a.addNode(b)
  b=_pyhl.node(_pyhl.ATTRIBUTE_ID,"/IMAGE1/IMAGE_VERSION")
  b.setScalarValue(-1,"1.2","string",-1)
  a.addNode(b)

  # Finally insert the reference}

  b=_pyhl.node(_pyhl.REFERENCE_ID,"/IMAGE1/PALETTE")
  b.setScalarValue(-1,"/PALETTE","string",-1)
  a.addNode(b)

  a.write("ahewrittenimage.hdf")

# The main function}
if __name__=="__main__"
  create_test_image()