MOAB: Mesh Oriented datABase  (version 5.4.1)
mhdf.h
Go to the documentation of this file.
00001 /**
00002  * MOAB, a Mesh-Oriented datABase, is a software component for creating,
00003  * storing and accessing finite element mesh data.
00004  * 
00005  * Copyright 2004 Sandia Corporation.  Under the terms of Contract
00006  * DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government
00007  * retains certain rights in this software.
00008  * 
00009  * This library is free software; you can redistribute it and/or
00010  * modify it under the terms of the GNU Lesser General Public
00011  * License as published by the Free Software Foundation; either
00012  * version 2.1 of the License, or (at your option) any later version.
00013  * 
00014  */
00015 
00016 #ifndef MHDF_H
00017 #define MHDF_H
00018 
00019 #include "moab/mhdf_public.h"
00020 
00021 #ifdef __cplusplus
00022 extern "C" {
00023 #endif
00024 
00025 /** \page h5mmain H5M File Format API
00026  *
00027  *\section Intro   Introduction
00028  *
00029  * MOAB's native file format is based on the HDF5 file format.  
00030  * The most common file extension used for such files is .h5m.
00031  * A .h5m file can be identified by the top-level \c tstt group
00032  * in the HDF5 file.
00033  *
00034  * The API implemented by this library is a wrapper on top of the
00035  * underlying HDF5 library.  It provides the following features:
00036  * - Enforces and hides MOAB's expected file layout 
00037  * - Provides a slightly higher-level API
00038  * - Provides some backwards compatibility for file layout changes
00039  *
00040  *
00041  *\section Overview   H5M File Layout
00042  *
00043  * The H5M file format relies on the use of a unique entity ID space for
00044  * all vertices, elements, and entity sets stored in the file.  This
00045  * ID space is defined by the application.  IDs must be unique over all
00046  * entity types (a vertex and an entity set may not have the same ID.)
00047  * The IDs must be positive (non-zero) integer values.  
00048  * There are no other requirements imposed by the format on the ID space.
00049  *
00050  * Elements, with the exception of polyhedra, are defined by a list of 
00051  * vertex IDs.  Polyhedra are defined by a list of face IDs.  Entity sets 
00052  * have a list of contained entity IDs, and lists of parent and child 
00053  * entity set IDs.  The set contents may include any valid entity ID,
00054  * including other sets.  The parent and child lists are expected to
00055  * contain only entity IDs corresponding to other entity sets.  A zero
00056  * entity ID may be used in some contexts (tag data with the mhdf_ENTITY_ID
00057  * property) to indicate a 'null' value,
00058  *
00059  * Element types are defined by the combination of a topology identifier (e.g. 
00060  * hexahedral topology) and the number of nodes in the element.  
00061  *
00062  *
00063  *\section Root   The tstt Group
00064  *
00065  * All file data is stored in the \c tstt group in the HDF5 root group.
00066  * The \c tstt group may have an optional scalar integer attribute 
00067  * named \c max_id .  This attribute, if present, should contain the
00068  * value of the largest entity ID used internally to the file.  It can
00069  * be used to verify that the code reading the file is using an integer
00070  * type of sufficient size to accommodate the entity IDs.
00071  *
00072  * The \c tstt group contains four sub-groups, a datatype object, and a 
00073  * dataset object.  The four sub-groups are: \c nodes, \c elements,
00074  * \c sets, and \c tags.  The dataset is named \c history .
00075  *
00076  * The \c elemtypes datatype is an enumeration of the elem topologies
00077  * used in the file.  The element topologies understood by MOAB are:
00078  * - \c Edge
00079  * - \c Tri
00080  * - \c Quad
00081  * - \c Polygon
00082  * - \c Tet
00083  * - \c Pyramid
00084  * - \c Prism
00085  * - \c Knife
00086  * - \c Hex
00087  * - \c Polyhedron
00088  * 
00089  *
00090  *\section History   The history DataSet
00091  *
00092  * The \c history DataSet is a list of variable-length strings with
00093  * application-defined meaning.  
00094  *
00095  *\section Nodes   The nodes Group
00096  *
00097  *
00098  * The \c nodes group contains a single DataSet and an optional
00099  * subgroup.  The \c tags subgroup is described in the 
00100  * \ref Dense "section on dense tag storage".  
00101  *
00102  * The \c coordinates
00103  * DataSet contains the coordinates of all vertices in the mesh.
00104  * The DataSet should contain floating point values and have a dimensions
00105  * \f$ n \times d \f$, where \c n is the number of vertices and \c d
00106  * is the number of coordinate values for each vertex.
00107  *
00108  * The \c coordinates DataSet must have an integer attribute named \c start_id .
00109  * The vertices are then defined to have IDs beginning with this value
00110  * and increasing sequentially in the order that they are defined in the
00111  * \c coordinates table.
00112  *
00113  *
00114  *\section Elements   The elements Group
00115  *
00116  * The \c elements group contains an application-defined number of 
00117  * subgroups.  Each subgroup defines one or more mesh elements that
00118  * have the same topology and length of connectivity (number of nodes
00119  * for any topology other than \c Polyhedron.)  The names of the subgroups
00120  * are application defined.  MOAB uses a combination of the element
00121  * topology name and connectivity length (e.g. "Hex8".).  
00122  *
00123  * Each subgroup must have an attribute named \c element_type that 
00124  * contains one of the enumerated element topology values defined 
00125  * in the \c elemtypes datatype described in a \ref Root "previous section".
00126  *
00127  * Each subgroup contains a single DataSet named \c connectivity and an 
00128  * optional subgroup named \c tags.  The \c tags subgroup is described in the 
00129  * \ref Dense "section on dense tag storage". 
00130  *
00131  * The \c connectivity DataSet is an \f$ n \times m \f$ array of integer
00132  * values.  The DataSet contains one row for each of the \c n contained
00133  * elements, where the connectivity of each element contains \c m IDs.  For
00134  * all element types supported by MOAB, with the exception of polyhedra,
00135  * the element connectivity list is expected to contain only IDs 
00136  * corresponding to nodes.  
00137  *
00138  * Each element \c connectivity DataSet must have an integer attribute 
00139  * named \c start_id .  The elements defined in the connectivity table
00140  * are defined to have IDs beginning with this value and increasing
00141  * sequentially in the order that they are defined in the table.
00142  *
00143  *
00144  *\section Sets   The sets Group
00145  *
00146  * The \c sets group contains the definitions of any entity sets stored
00147  * in the file.  It contains 1 to 4 DataSets and the optional \c tags 
00148  * subgroup.  The \c contents, \c parents, and \c children data sets
00149  * are one dimensional arrays containing the concatenation of the
00150  * corresponding lists for all of the sets represented in the file.
00151  *
00152  * The \c lists DataSet is a \f$ n \times 4 \f$ table, having one
00153  * row of four integer values for each set.  The first three values
00154  * for each set are the indices into the \c contents, \c children, 
00155  * and \c parents DataSets, respectively, at which the \em last value
00156  * for set is stored.  The contents, child, and parent lists for
00157  * sets are stored in the corresponding datasets in the same order as
00158  * the sets are listed in the \c lists DataSet, such that the index of
00159  * the first value in one of those tables is one greater than the 
00160  * corresponding end index in the \em previous row of the table.  The
00161  * number of content entries, parents, or children for a given set can
00162  * be calculated as the difference between the corresponding end index
00163  * entry for the current set and the same entry in the previous row 
00164  * of the table.  If the first set in the \c lists DataSet had no parent
00165  * sets, then the corresponding index in the third column of the table
00166  * would be \c -1.  If it had one parent, the index would be \c 0.  If it
00167  * had two parents, the index would be \c 1, as the first parent would be
00168  * stored at position 0 of the \c parents DataSet and the second at position
00169  * 1.
00170  *
00171  * The fourth column of the \c lists DataSet is a series of bit flags
00172  * defining some properties of the sets.  The four bit values currently
00173  * defined are:
00174  *  - 0x1 owner
00175  *  - 0x2 unique
00176  *  - 0x4 ordered
00177  *  - 0x8 range compressed
00178  *
00179  * The fourth (most significant) bit indicates that, in the \c contents 
00180  * data set, that the contents list for the corresponding set is stored
00181  * using a single range compression.  Rather than storing the IDs of the
00182  * contained entities individually, each ID \c i is followed by a count 
00183  * \c n indicating that the set contains the contiguous range of IDs
00184  * \f$ [i, i+n-1] \f$.
00185  *
00186  * The three least significant bits specify intended properties of the
00187  * set and are unrelated to how the set data is stored in the file.  These
00188  * properties, described briefly from least significant bit to most 
00189  * significant are: contained entities should track set membership;
00190  * the set should contain each entity only once (strict set); and
00191  * that the order of the entries in the set should be preserved.  
00192  *
00193  * Similar to the \c nodes/coordinates and \c elements/.../connectivity
00194  * DataSets, the \c lists DataSet must have an integer attribute 
00195  * named \c start_id .  IDs are assigned to to sets in the order that
00196  * they occur in the \c lists table, beginning with the attribute value.
00197  *
00198  * The \c sets group may contain a subgroup names \c tags.  The \c tags 
00199  * subgroup is described in the \ref Dense "section on dense tag storage". 
00200  *
00201  * 
00202  * \section Tags   The tags Group
00203  *
00204  * The \c tags group contains a sub-group for each tag defined
00205  * in the file.  These sub-groups contain the definition of the
00206  * tag and may contain some or all of the tag values associated with
00207  * entities in the file.  However, it should be noted that tag values
00208  * may also be stored in the "dense" format as described in the 
00209  * \ref Dense "section on dense tag storage".
00210  *
00211  * Each sub-group of the \c tags group contains the definition for
00212  * a single tag.  The name of each sub-group is the name of the 
00213  * corresponding tag.  Non-printable characters, characters
00214  * prohibited in group names in the HDF5 file format, and the
00215  * backslash ('\') character are encoded
00216  * in the name string by a backslash ('\') character followed by
00217  * the ASCII value of the character expressed as a pair of hexadecimal
00218  * digits.  Thus the backslash character would be represented as \c \5C .
00219  * Each tag group should also contain a comment which contains the
00220  * unencoded tag name.
00221  *
00222  * The tag sub-group may have any or all of the following four attributes:
00223  * \c default, \c global, \c is_handle, and \c variable_length.  
00224  * The \c default attribute, if present,
00225  * must contain a single tag value that is to be considered the 'default'
00226  * value of the tag.  The \c global attribute, if present, must contain a
00227  * single tag value that is the value of the tag as set on the mesh instance
00228  * (MOAB terminology) or root set (ITAPS terminology.)  The presence of the
00229  * \c is_handle attribute (the value, if any, is meaningless) indicates
00230  * that the tag values are to be considered entity IDs.  After reading the
00231  * file, the reader should map any such tag values to whatever mechanism
00232  * it uses to reference the corresponding entities read from the file.
00233  * The presence of the \c variable_length attribute indicates that each 
00234  * tag value is a variable-length array.  The reader should rely on the
00235  * presence of this attribute rather than the presence of the \c var_indices
00236  * DataSet discussed below because the file may contain the definition of
00237  * a variable length tag without containing any values for that tag.  In such
00238  * a case, the \c var_indices DataSet will not be present.
00239  *
00240  * Each tag sub-group will contain a committed type object named \c type .
00241  * This type must be the type instance used by the \c global and \c default
00242  * attributes discussed above and any tag value data sets.  For fixed-length
00243  * tag data, the tag types understood by MOAB are:
00244  *  - opaque data
00245  *  - a single floating point value
00246  *  - a single integer value
00247  *  - a bit field
00248  *  - an array of floating point values
00249  *  - an array of integer values
00250  * Any other data types will be treated as opaque data.
00251  * For Variable-length tag data, MOAB expects the \c type object to be
00252  * one of:
00253  *  - opaque data
00254  *  - a single floating point value
00255  *  - a single integer value
00256  *
00257  * For fixed-length tags, the tag sub-group may contain 'sparse' formatted
00258  * tag data, which is comprised of two data sets: \c id_list and \c values.
00259  * Both data sets must be 1-dimensional arrays of the same length.  The 
00260  * \c id_list data set contains a list of entity IDs and the \c values 
00261  * data set contains a list of corresponding tag values.  The data stored in
00262  * the \c values table must be of type \c type.  Fixed-length tag values
00263  * may also be stored in the "dense" format as described in the 
00264  * \ref Dense "section on dense tag storage".  A mixture of both sparse-
00265  * and dense-formatted tag values may be present for a single tag.
00266  *
00267  * For variable-length tags the tag values, if any, are always stored
00268  * in the tag sub-group of the \c tags group and are represented by
00269  * three one-dimensional data sets: \c id_list, \c var_indices, and \c values.  
00270  * Similar to the fixed-length sparse-formatted tag data, the \c id_list
00271  * contains the IDs of the entities for which tag values are defined.
00272  * The \c values dataset contains the concatenation of the tag values
00273  * for each of the entities referenced by ID in the \c id_list table, 
00274  * in the order that the entities are referenced in the \c id_list table.
00275  * The \c var_indices table contains an index into the \c values data set
00276  * for each entity in \c id_list.  The index indicates the position of
00277  * the \em last tag value for the entity in \c values.  The index of
00278  * the first value is one greater than the 
00279  * corresponding end index for the \em entry in \c var_indices.  The
00280  * number of tag values for a given entity can
00281  * be calculated as the difference between the corresponding end index
00282  * entry for the current entity and the previous value in the \c var_indices
00283  * dataset.  
00284  *
00285  *
00286  * \section Dense   The tags Sub-Groups
00287  *
00288  * Data for fixed-length tags may also be stored in the \c tags sub-group
00289  * of the \c nodes, \c sets, and subgroups of the \c elements group.  
00290  * Values for given tag are stored in a dataset within the \c tags sub-group
00291  * that has the following properties:
00292  *  - The name must be the same as that of the tag definition in the main 
00293  *      \c tags group
00294  *  - The type of the data set must be the committed type object stored
00295  *      as \c /tstt/tags/<tagname>/type .
00296  *  - The data set must have the same length as the data set in the
00297  *    parent group with the \c start_id attribute.  
00298  *
00299  * If dense-formatted data is specified for any entity in the group, then
00300  * it must be specified for every entity in the group.  The table is 
00301  * expected to contain one value for each entity in the corresponding 
00302  * primary definition table (\c /tstt/nodes/coordinates , 
00303  * \c /tstt/elements/<name>/connectivity , or \c /tstt/sets/list), in the
00304  * same order as the entities in that primary definition table.
00305  * 
00306  */
00307 
00308 /**
00309  *\defgroup mhdf MHDF API for reading/writing MOAB-format HDF5 mesh files.
00310  */
00311 /*@{*/
00312 
00313 /**
00314  *\defgroup mhdf_status Error handling
00315  */
00316 /*@{*/
00317 
00318 /**
00319  *\defgroup mhdf_group Element group handle
00320  */
00321 /*@{*/
00322 
00323 /** \brief Get an mhdf_ElemHandle object for the node data.  
00324  *
00325  * \return A special element group handle used when specifying adjacency or
00326  * tag data for nodes. 
00327  */
00328 const char* mhdf_node_type_handle( void );
00329 
00330 /** \brief Return a special element group handle used to specify the set group.
00331  *
00332  *  \return A special element group handle used to specify the set group
00333  *  for reading/writing tag data on sets.
00334  */
00335 const char* mhdf_set_type_handle( void );
00336 
00337 #define MHDF_INDEX_TYPE H5T_NATIVE_LONG
00338 
00339 /** \brief Given an element type Id, get the name. 
00340  * Fails if buffer is not of sufficient size.
00341  * \param file_handle The file.
00342  * \param type_index The type index.  Corresponds to indices into
00343  *                   the element type list passed to \ref mhdf_createFile.
00344  * \param buffer     The buffer into which to copy the name.
00345  * \param buffer_size The length of <code>buffer</code>.
00346  * \param status     Passed back status of API call.
00347  */
00348 void mhdf_getElemName( mhdf_FileHandle file_handle,
00349                        unsigned int type_index,
00350                        char* buffer,
00351                        size_t buffer_size,
00352                        mhdf_Status* status );
00353 
00354 int mhdf_checkOpenHandles( mhdf_FileHandle handle, mhdf_Status* status );
00355 
00356 /** \brief Common close function for all data handle types.
00357  *
00358  * Close an hid_t-type handle returned from any of the following
00359  * functions.  Any hid_t passed-back or returned must be closed via
00360  * this function to avoid resource loss.
00361  *
00362  * \param file   The file the object pointed to by the passed data
00363  *               handled exists int.
00364  * \param handle The data object to close.
00365  * \param status     Passed back status of API call.
00366  */
00367 void mhdf_closeData( mhdf_FileHandle file, hid_t handle, mhdf_Status* status );
00368 
00369 /**\brief Get start ID that will be assigned to next created dataset
00370  *
00371  * Get the first_id parameter that will be returned from the next
00372  * call to any of mhdf_createNodeCoords, mhdf_createConnectivity, 
00373  * mhdf_createPolyConnectivity, or mhdf_createSetMeta
00374  */
00375 void mhdf_getNextStartId( mhdf_FileHandle file, mhdf_index_t* start_id_out, mhdf_Status* status );
00376 
00377 /** \brief Write the file history as a list of strings.
00378  *
00379  * Each entry is composed of four strings:
00380  * application, version, date, and time.
00381  *
00382  * \param file       The file.
00383  * \param strings    An array of null-terminated strings.
00384  * \param num_strings The length of <code>strings</code>
00385  * \param status     Passed back status of API call.
00386  */
00387 void mhdf_writeHistory( mhdf_FileHandle file, const char** strings, int num_strings, mhdf_Status* status );
00388 
00389 /** \brief Read the file history as a list of strings.
00390  *
00391  * Each entry is composed of four strings:
00392  * application, version, date, and time.
00393  *
00394  * Strings and array are allocated with <code>malloc</code>.  Caller must
00395  * release them by calling <code>free</code>
00396  *
00397  * \param file       The file.
00398  * \param num_records_out  The length of the returned array.
00399  * \param status     Passed back status of API call.
00400  * \return An array of null-terminates strings.
00401  */
00402 char** mhdf_readHistory( mhdf_FileHandle file, int* num_records_out, mhdf_Status* status );
00403 /*@}*/
00404 /**
00405  *\defgroup mhdf_node Node coordinate data.
00406  */
00407 /*@{*/
00408 
00409 /* Node Coordinates */
00410 
00411 int mhdf_haveNodes( mhdf_FileHandle file_handle, mhdf_Status* status );
00412 
00413 /** \brief Create new table for node coordinate data 
00414  *
00415  * \param file_handle  The file.
00416  * \param dimension    Number of coordinate values per node.
00417  * \param num_nodes    The number of nodes the table will contain.
00418  * \param first_node_id_out  Nodes are assigned IDs sequentially in the
00419  *             order they occur in the table, where the ID of the first
00420  *             node in the table is this passed-back value.
00421  * \param status     Passed back status of API call.
00422  * \return An HDF5 handle to the coordinate table.
00423  */
00424 hid_t mhdf_createNodeCoords( mhdf_FileHandle file_handle,
00425                              int dimension,
00426                              long num_nodes,
00427                              long* first_node_id_out,
00428                              mhdf_Status* status );
00429 
00430 /** \brief Open table containing node coordinate data 
00431  *
00432  * \param file_handle       The file.
00433  * \param dimension_out    Number of coordinate values per node.
00434  * \param num_nodes_out    The number of nodes the table contains.
00435  * \param first_node_id_out  Nodes are assigned IDs sequentially in the
00436  *             order they occur in the table, where the ID of the first
00437  *             node in the table is this passed-back value.
00438  * \param status     Passed back status of API call.
00439  * \return An HDF5 handle to the coordinate table.
00440  */
00441 hid_t mhdf_openNodeCoords( mhdf_FileHandle file_handle,
00442                            long* num_nodes_out,
00443                            int* dimension_out,
00444                            long* first_node_id_out,
00445                            mhdf_Status* status );
00446 
00447 hid_t mhdf_openNodeCoordsSimple( mhdf_FileHandle file_handle, mhdf_Status* status );
00448 
00449 /** \brief Write node coordinate data
00450  *
00451  * Write interleaved coordinate data for a block of nodes
00452  *
00453  * \param data_handle  Handle returned from <code>mhdf_createNodeCoords</code>
00454  *                     or <code>mhdf_openNodeCoords</code>.
00455  * \param offset       Table row (node index) at which to start writing.
00456  * \param count        Number of rows (number of nodes) to write.
00457  * \param coords       Interleaved node coordinate data.
00458  * \param status     Passed back status of API call.
00459  */
00460 void mhdf_writeNodeCoords( hid_t data_handle, long offset, long count, const double* coords, mhdf_Status* status );
00461 void mhdf_writeNodeCoordsWithOpt( hid_t data_handle,
00462                                   long offset,
00463                                   long count,
00464                                   const double* coords,
00465                                   hid_t write_prop,
00466                                   mhdf_Status* status );
00467 
00468 /** \brief Write node coordinate data
00469  *
00470  * Write a single coordinate value (e.g. the 'x' coordinate) for a 
00471  * block of nodes.
00472  *
00473  * \param data_handle  Handle returned from <code>mhdf_createNodeCoords</code>
00474  *                     or <code>mhdf_openNodeCoords</code>.
00475  * \param offset       Table row (node index) at which to start writing.
00476  * \param count        Number of rows (number of nodes) to write.
00477  * \param dimension    The coordinate to write (0->x, 1->y, ...)
00478  * \param coords       Coordinate list.
00479  * \param status     Passed back status of API call.
00480  */
00481 void mhdf_writeNodeCoord( hid_t data_handle,
00482                           long offset,
00483                           long count,
00484                           int dimension,
00485                           const double* coords,
00486                           mhdf_Status* status );
00487 void mhdf_writeNodeCoordWithOpt( hid_t data_handle,
00488                                  long offset,
00489                                  long count,
00490                                  int dimension,
00491                                  const double* coords,
00492                                  hid_t write_prop,
00493                                  mhdf_Status* status );
00494 
00495 /** \brief Read node coordinate data
00496  *
00497  * Read interleaved coordinate data for a block of nodes
00498  *
00499  * \param data_handle  Handle returned from <code>mhdf_createNodeCoords</code>
00500  *                     or <code>mhdf_openNodeCoords</code>.
00501  * \param offset       Table row (node index) at which to start reading.
00502  * \param count        Number of rows (number of nodes) to read.
00503  * \param coordinates  Buffer in which to write node coordinate data.
00504  * \param status       Passed back status of API call.
00505  */
00506 void mhdf_readNodeCoords( hid_t data_handle, long offset, long count, double* coordinates, mhdf_Status* status );
00507 void mhdf_readNodeCoordsWithOpt( hid_t data_handle,
00508                                  long offset,
00509                                  long count,
00510                                  double* coordinates,
00511                                  hid_t read_prop,
00512                                  mhdf_Status* status );
00513 
00514 /** \brief Read node coordinate data
00515  *
00516  * Read a single coordinate value (e.g. the 'x' coordinate) for a 
00517  * block of nodes.
00518  *
00519  * \param data_handle  Handle returned from <code>mhdf_createNodeCoords</code>
00520  *                     or <code>mhdf_openNodeCoords</code>.
00521  * \param offset       Table row (node index) at which to start reading.
00522  * \param count        Number of rows (number of nodes) to read.
00523  * \param dimension    The coordinate to read (0->x, 1->y, ...)
00524  * \param coords       Buffer in which to write node coordinate data.
00525  * \param status     Passed back status of API call.
00526  */
00527 void mhdf_readNodeCoord( hid_t data_handle,
00528                          long offset,
00529                          long count,
00530                          int dimension,
00531                          double* coords,
00532                          mhdf_Status* status );
00533 void mhdf_readNodeCoordWithOpt( hid_t data_handle,
00534                                 long offset,
00535                                 long count,
00536                                 int dimension,
00537                                 double* coords,
00538                                 hid_t read_prop,
00539                                 mhdf_Status* status );
00540 
00541 /*@}*/
00542 /**
00543  *\defgroup mhdf_conn Element connectivity data.
00544  */
00545 /*@{*/
00546 
00547 /* Element Connectivity */
00548 
00549 /** \brief Add a new table of element data to the file.
00550  *
00551  * Add a element group to the file. 
00552  * An element group is the data for a block of elements with the same 
00553  * TSTT type and same number of nodes in their connectivity data.
00554  * (e.g. all the MBHEX20 elements).  This function is also
00555  * used to create the groups for general polygon data and
00556  * general polyhedron data.  The requirement that all elements
00557  * have the same number of nodes in their connectivity does not
00558  * apply for poly(gons|hedra).
00559  *
00560  * \param file_handle  File in which to create the element type.
00561  * \param elem_handle  The name to use for the element data.  This
00562  *                     name is used as an identifier to reference the
00563  *                     data for this element type later.  The selected
00564  *                     name also appears explicitly in the file and 
00565  *                     therefore should be something
00566  *                     descriptive of the element type such as the
00567  *                     'base type' and number of nodes (e.g. "Hex20").
00568  * \param named_elem_type An index into the list of named element types
00569  *                     passed to \ref mhdf_createFile .
00570  * \param status     Passed back status of API call.
00571  */
00572 void mhdf_addElement( mhdf_FileHandle file_handle,
00573                       const char* elem_handle,
00574                       unsigned int named_elem_type,
00575                       mhdf_Status* status );
00576 
00577 /** \brief Get the list of element groups in the file.
00578  *
00579  * Get the list of element groups in the file.
00580  * An element group is the data for a block of elements with the same 
00581  * TSTT type and same number of nodes in their connectivity data.
00582  * (e.g. all the MBHEX20 elements).  This function is also
00583  * used to retrieve the groups for general polygon data and
00584  * general polyhedron data.  The requirement that all elements
00585  * have the same number of nodes in their connectivity does not
00586  * apply for poly(gons|hedra).
00587  *
00588  * \param  file_handle   The file.
00589  * \param  count_out     Memory location at which to store the
00590  *                       length of the returned array.
00591  * \param  status        Passed back status of API call.
00592  * \return               An array of pointers to element group
00593  *                       names.  This array is allocated as a 
00594  *                       single memory block and should be freed
00595  *                       with <em>one</em> call to free().
00596  */
00597 char** mhdf_getElemHandles( mhdf_FileHandle file_handle, unsigned int* count_out, mhdf_Status* status );
00598 
00599 /** 
00600  * \brief Get the element type name for a given element group handle.
00601  *
00602  * Fails if name is longer than <code>buf_len</code>.
00603  *
00604  * \param file_handle The file.
00605  * \param elem_handle One of the group names passed back from 
00606  *                    \ref mhdf_getElemHandles
00607  * \param buffer      A buffer to copy the name into.
00608  * \param buf_len     The length of <code>buffer</code>.
00609  * \param status      Passed back status of API call.
00610  */
00611 void mhdf_getElemTypeName( mhdf_FileHandle file_handle,
00612                            const char* elem_handle,
00613                            char* buffer,
00614                            size_t buf_len,
00615                            mhdf_Status* status );
00616 
00617 /** \brief Check if an element group contains polygon or polyhedron
00618  *
00619  * Check if an element group contains general polygon or polyhedrons
00620  * rather than typically fixed-connectivity elements.  
00621  *
00622  * \param file_handle The file.
00623  * \param elem_handle The element group.
00624  * \param status      Passed back status of API call.
00625  * \return Zero if normal fixed-connectivity element data.  Non-zero if
00626  *         poly(gon/hedron) general-connectivity data.
00627  */
00628 int mhdf_isPolyElement( mhdf_FileHandle file_handle, const char* elem_handle, mhdf_Status* status );
00629 
00630 /** \brief Create connectivity table for an element group
00631  * 
00632  * Create fixed-connectivity data for an element group.
00633  * Do NOT use this function for poly(gon/hedron) data.
00634  *
00635  * \param file_handle  The file.
00636  * \param elem_handle  The element group.
00637  * \param num_nodes_per_elem The number of nodes in the connectivity data
00638  *                     for each element.
00639  * \param num_elements The number of elements to be written to the table.
00640  * \param first_elem_id_out Elements are assigned global IDs in 
00641  *                     sequential blocks where the block is the table in
00642  *                     which their connectivity data is written and the 
00643  *                     sequence is the sequence in which they are written
00644  *                     in that table.  The global ID for the first element
00645  *                     in this group is passed back at this address.  The
00646  *                     global IDs for all other elements in the table are
00647  *                     assigned in the sequence in which they are written
00648  *                     in the table.
00649  * \param status      Passed back status of API call.
00650  * \return The HDF5 handle to the connectivity data.
00651  */
00652 hid_t mhdf_createConnectivity( mhdf_FileHandle file_handle,
00653                                const char* elem_handle,
00654                                int num_nodes_per_elem,
00655                                long num_elements,
00656                                long* first_elem_id_out,
00657                                mhdf_Status* status );
00658 
00659 /** \brief Open connectivity table for an element group
00660  * 
00661  * Open fixed-connectivity data for an element group.
00662  * Do NOT use this function for poly(gon/hedron) data.  Use
00663  * <code>mhdf_isPolyElement</code> or <code>mhdf_getTsttElemType</code>
00664  * to check if the data is poly(gon|hedron) data before calling this
00665  * function to open the data.
00666  *
00667  * \param file_handle  The file.
00668  * \param elem_handle  The element group.
00669  * \param num_nodes_per_elem_out Used to pass back the number of nodes
00670  *                     in each element.
00671  * \param num_elements_out Pass back the number of elements in the table.
00672  * \param first_elem_id_out Elements are assigned global IDs in 
00673  *                     sequential blocks where the block is the table in
00674  *                     which their connectivity data is written and the 
00675  *                     sequence is the sequence in which they are written
00676  *                     in that table.  The global ID for the first element
00677  *                     in this group is passed back at this address.  The
00678  *                     global IDs for all other elements in the table are
00679  *                     assigned in the sequence in which they are written
00680  *                     in the table.
00681  * \param status      Passed back status of API call.
00682  * \return The HDF5 handle to the connectivity data.
00683  */
00684 hid_t mhdf_openConnectivity( mhdf_FileHandle file_handle,
00685                              const char* elem_handle,
00686                              int* num_nodes_per_elem_out,
00687                              long* num_elements_out,
00688                              long* first_elem_id_out,
00689                              mhdf_Status* status );
00690 
00691 hid_t mhdf_openConnectivitySimple( mhdf_FileHandle file_handle, const char* elem_handle, mhdf_Status* status );
00692 
00693 /** \brief Write element coordinate data
00694  *
00695  * Write interleaved fixed-connectivity element data for a block of elements.
00696  * Note: Do not use this for polygon or polyhedron data. 
00697  *
00698  * \param data_handle  Handle returned from <code>mhdf_createConnectivity</code>
00699  *                     or <code>mhdf_openConnectivity</code>.
00700  * \param offset       Table row (element index) at which to start writing.
00701  * \param count        Number of rows (number of elements) to write.
00702  * \param hdf_integer_type The type of the integer data in node_id_list.
00703  *                     Typically <code>H5T_NATIVE_INT</code> or
00704  *                     <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
00705  *                     The HDF class of this type object <em>must</em> be H5T_INTEGER
00706  * \param node_id_list Interleaved connectivity data specified as global node IDs.
00707  * \param status       Passed back status of API call.
00708  */
00709 void mhdf_writeConnectivity( hid_t data_handle,
00710                              long offset,
00711                              long count,
00712                              hid_t hdf_integer_type,
00713                              const void* node_id_list,
00714                              mhdf_Status* status );
00715 void mhdf_writeConnectivityWithOpt( hid_t data_handle,
00716                                     long offset,
00717                                     long count,
00718                                     hid_t hdf_integer_type,
00719                                     const void* node_id_list,
00720                                     hid_t write_prop,
00721                                     mhdf_Status* status );
00722 
00723 /** \brief Read element coordinate data
00724  *
00725  * Read interleaved fixed-connectivity element data for a block of elements.
00726  * Note: Do not use this for polygon or polyhedron data. 
00727  *
00728  * \param data_handle  Handle returned from <code>mhdf_createConnectivity</code>
00729  *                     or <code>mhdf_openConnectivity</code>.
00730  * \param offset       Table row (element index) at which to start read.
00731  * \param count        Number of rows (number of elements) to read.
00732  * \param hdf_integer_type The type of the integer data in node_id_list.
00733  *                     Typically <code>H5T_NATIVE_INT</code> or
00734  *                     <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
00735  *                     The HDF class of this type object <em>must</em> be H5T_INTEGER
00736  * \param node_id_list Pointer to memory at which to write interleaved
00737  *                     connectivity data specified as global node IDs.
00738  * \param status       Passed back status of API call.
00739  */
00740 void mhdf_readConnectivity( hid_t data_handle,
00741                             long offset,
00742                             long count,
00743                             hid_t hdf_integer_type,
00744                             void* node_id_list,
00745                             mhdf_Status* status );
00746 void mhdf_readConnectivityWithOpt( hid_t data_handle,
00747                                    long offset,
00748                                    long count,
00749                                    hid_t hdf_integer_type,
00750                                    void* node_id_list,
00751                                    hid_t read_prop,
00752                                    mhdf_Status* status );
00753 
00754 /* Poly(gon|hedra) */
00755 
00756 /** \brief Create a new table for polygon or polyhedron connectivity data.
00757  *
00758  * Poly (polygon or polyhedron) connectivity is stored as two lists.
00759  * One list is the concatenation of the the connectivity data for
00760  * all the polys in the group.  The other contains one value per
00761  * poly where that value is the index of the last entry in the
00762  * connectivity of the corresponding poly.  The ID
00763  * list for polygons contains global node IDs.  The ID list for polyhedra
00764  * contains the global IDs of faces (either polygons or 2D fixed-connectivity
00765  * elements.)
00766  *
00767  * \param file_handle  The file to write.
00768  * \param elem_handle  The element group.
00769  * \param num_poly     The total number number of polygons or polyhedra to
00770  *                     be written in the table.
00771  * \param data_list_length The total number of values to be written to the
00772  *                     table (the number of polys plus the sum of the number
00773  *                     of entities in each poly's connectivity data.)
00774  * \param first_id_out Elements are assigned global IDs in 
00775  *                     sequential blocks where the block is the table in
00776  *                     which their connectivity data is written and the 
00777  *                     sequence is the sequence in which they are written
00778  *                     in that table.  The global ID for the first element
00779  *                     in this group is passed back at this address.  The
00780  *                     global IDs for all other elements in the table are
00781  *                     assigned in the sequence in which they are written
00782  *                     in the table.
00783  * \param idx_and_id_handles_out The handles for the index list and
00784  *                     connectivity list, respectively.
00785  * \param status       Passed back status of API call.
00786  */
00787 void mhdf_createPolyConnectivity( mhdf_FileHandle file_handle,
00788                                   const char* elem_handle,
00789                                   long num_poly,
00790                                   long data_list_length,
00791                                   long* first_id_out,
00792                                   hid_t idx_and_id_handles_out[2],
00793                                   mhdf_Status* status );
00794 
00795 /** \brief Open a table of polygon or polyhedron connectivity data.
00796  *
00797  * Poly (polygon or polyhedron) connectivity is stored as two lists.
00798  * One list is the concatenation of the the connectivity data for
00799  * all the polys in the group.  The other contains one value per
00800  * poly where that value is the index of the last entry in the
00801  * connectivity of the corresponding poly.  The ID
00802  * list for polygons contains global node IDs.  The ID list for polyhedra
00803  * contains the global IDs of faces (either polygons or 2D fixed-connectivity
00804  * elements.)
00805  *
00806  * \param file_handle  The file to write.
00807  * \param elem_handle  The element group.
00808  * \param num_poly_out The total number number of polygons or polyhedra to
00809  *                     be written in the table.
00810  * \param data_list_length_out The total number of values to be written to the
00811  *                     table (the number of polys plus the sum of the number
00812  *                     of entities in each poly's connectivity data.)
00813  * \param first_id_out Elements are assigned global IDs in 
00814  *                     sequential blocks where the block is the table in
00815  *                     which their connectivity data is written and the 
00816  *                     sequence is the sequence in which they are written
00817  *                     in that table.  The global ID for the first element
00818  *                     in this group is passed back at this address.  The
00819  *                     global IDs for all other elements in the table are
00820  *                     assigned in the sequence in which they are written
00821  *                     in the table.
00822  * \param idx_and_id_handles_out The handles for the index list and
00823  *                     connectivity list, respectively.
00824  * \param status       Passed back status of API call.
00825  */
00826 void mhdf_openPolyConnectivity( mhdf_FileHandle file_handle,
00827                                 const char* elem_handle,
00828                                 long* num_poly_out,
00829                                 long* data_list_length_out,
00830                                 long* first_id_out,
00831                                 hid_t idx_and_id_handles_out[2],
00832                                 mhdf_Status* status );
00833 
00834 /** \brief Write polygon or polyhedron index data.
00835  *
00836  * Poly (polygon or polyhedron) connectivity is stored as two lists.
00837  * One list is the concatenation of the the connectivity data for
00838  * all the polys in the group.  The other contains one value per
00839  * poly where that value is the index of the last entry in the
00840  * connectivity of the corresponding poly.  The ID
00841  * list for polygons contains global node IDs.  The ID list for polyhedra
00842  * contains the global IDs of faces (either polygons or 2D fixed-connectivity
00843  * elements.)
00844  *
00845  * This function writes the index list.
00846  *
00847  * \param poly_handle  The handle returned from 
00848  *                     <code>mhdf_createPolyConnectivity</code> or
00849  *                     <code>mhdf_openPolyConnectivity</code>.
00850  * \param offset       The offset in the table at which to write.  The
00851  *                     offset is in terms of the integer values in the table,
00852  *                     not the count of polys.
00853  * \param count        The size of the integer list to write.
00854  * \param hdf_integer_type The type of the integer data in <code>id_list</code>.
00855  *                     Typically <code>H5T_NATIVE_INT</code> or
00856  *                     <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
00857  *                     The HDF class of this type object <em>must</em> be H5T_INTEGER
00858  * \param index_list   The index list for the polys.
00859  * \param status       Passed back status of API call.
00860  */
00861 void mhdf_writePolyConnIndices( hid_t poly_handle,
00862                                 long offset,
00863                                 long count,
00864                                 hid_t hdf_integer_type,
00865                                 const void* index_list,
00866                                 mhdf_Status* status );
00867 void mhdf_writePolyConnIndicesWithOpt( hid_t poly_handle,
00868                                        long offset,
00869                                        long count,
00870                                        hid_t hdf_integer_type,
00871                                        const void* index_list,
00872                                        hid_t write_prop,
00873                                        mhdf_Status* status );
00874 
00875 /** \brief Write polygon or polyhedron connectivity data.
00876  *
00877  * Poly (polygon or polyhedron) connectivity is stored as two lists.
00878  * One list is the concatenation of the the connectivity data for
00879  * all the polys in the group.  The other contains one value per
00880  * poly where that value is the index of the last entry in the
00881  * connectivity of the corresponding poly.  The ID
00882  * list for polygons contains global node IDs.  The ID list for polyhedra
00883  * contains the global IDs of faces (either polygons or 2D fixed-connectivity
00884  * elements.)
00885  *
00886  * This function writes the connectivity/ID list.
00887  *
00888  * \param poly_handle  The handle returned from 
00889  *                     <code>mhdf_createPolyConnectivity</code> or
00890  *                     <code>mhdf_openPolyConnectivity</code>.
00891  * \param offset       The offset in the table at which to write.  The
00892  *                     offset is in terms of the integer values in the table,
00893  *                     not the count of polys.
00894  * \param count        The size of the integer list to write.
00895  * \param hdf_integer_type The type of the integer data in <code>id_list</code>.
00896  *                     Typically <code>H5T_NATIVE_INT</code> or
00897  *                     <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
00898  *                     The HDF class of this type object <em>must</em> be H5T_INTEGER
00899  * \param id_list      The count/global ID list specifying the connectivity 
00900  *                     of the polys.
00901  * \param status       Passed back status of API call.
00902  */
00903 void mhdf_writePolyConnIDs( hid_t poly_handle,
00904                             long offset,
00905                             long count,
00906                             hid_t hdf_integer_type,
00907                             const void* id_list,
00908                             mhdf_Status* status );
00909 void mhdf_writePolyConnIDsWithOpt( hid_t poly_handle,
00910                                    long offset,
00911                                    long count,
00912                                    hid_t hdf_integer_type,
00913                                    const void* id_list,
00914                                    hid_t write_prop,
00915                                    mhdf_Status* status );
00916 
00917 /** \brief Read polygon or polyhedron index data.
00918  *
00919  * Poly (polygon or polyhedron) connectivity is stored as two lists.
00920  * One list is the concatenation of the the connectivity data for
00921  * all the polys in the group.  The other contains one value per
00922  * poly where that value is the index of the last entry in the
00923  * connectivity of the corresponding poly.  The ID
00924  * list for polygons contains global node IDs.  The ID list for polyhedra
00925  * contains the global IDs of faces (either polygons or 2D fixed-connectivity
00926  * elements.)
00927  *
00928  * \param poly_handle  The handle returned from 
00929  *                     <code>mhdf_createPolyConnectivity</code> or
00930  *                     <code>mhdf_openPolyConnectivity</code>.
00931  * \param offset       The offset in the table at which to read.  The
00932  *                     offset is in terms of the integer values in the table,
00933  *                     not the count of polys.
00934  * \param count        The size of the integer list to read.
00935  * \param hdf_integer_type The type of the integer data as written into memory.
00936  *                     Typically <code>H5T_NATIVE_INT</code> or
00937  *                     <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
00938  *                     The HDF class of this type object <em>must</em> be H5T_INTEGER
00939  * \param index_list   The memory location at which to write the indices.
00940  * \param status       Passed back status of API call.
00941  */
00942 void mhdf_readPolyConnIndices( hid_t poly_handle,
00943                                long offset,
00944                                long count,
00945                                hid_t hdf_integer_type,
00946                                void* index_list,
00947                                mhdf_Status* status );
00948 void mhdf_readPolyConnIndicesWithOpt( hid_t poly_handle,
00949                                       long offset,
00950                                       long count,
00951                                       hid_t hdf_integer_type,
00952                                       void* index_list,
00953                                       hid_t read_prop,
00954                                       mhdf_Status* status );
00955 
00956 /** \brief Read polygon or polyhedron connectivity data.
00957  *
00958  * Poly (polygon or polyhedron) connectivity is stored as two lists.
00959  * One list is the concatenation of the the connectivity data for
00960  * all the polys in the group.  The other contains one value per
00961  * poly where that value is the index of the last entry in the
00962  * connectivity of the corresponding poly.  The ID
00963  * list for polygons contains global node IDs.  The ID list for polyhedra
00964  * contains the global IDs of faces (either polygons or 2D fixed-connectivity
00965  * elements.)
00966  *
00967  * \param poly_handle  The handle returned from 
00968  *                     <code>mhdf_createPolyConnectivity</code> or
00969  *                     <code>mhdf_openPolyConnectivity</code>.
00970  * \param offset       The offset in the table at which to read.  The
00971  *                     offset is in terms of the integer values in the table,
00972  *                     not the count of polys.
00973  * \param count        The size of the integer list to read.
00974  * \param hdf_integer_type The type of the integer data as written into memory.
00975  *                     Typically <code>H5T_NATIVE_INT</code> or
00976  *                     <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
00977  *                     The HDF class of this type object <em>must</em> be H5T_INTEGER
00978  * \param id_list      The memory location at which to write the connectivity data.
00979  * \param status       Passed back status of API call.
00980  */
00981 void mhdf_readPolyConnIDs( hid_t poly_handle,
00982                            long offset,
00983                            long count,
00984                            hid_t hdf_integer_type,
00985                            void* id_list,
00986                            mhdf_Status* status );
00987 void mhdf_readPolyConnIDsWithOpt( hid_t poly_handle,
00988                                   long offset,
00989                                   long count,
00990                                   hid_t hdf_integer_type,
00991                                   void* id_list,
00992                                   hid_t read_prop,
00993                                   mhdf_Status* status );
00994 /*@}*/
00995 /**
00996  *\defgroup mhdf_adj Adjacency data.
00997  *
00998  * Adjacency data is formated as a sequence of integer groups where
00999  * the first entry in each group is the ID of the element for which
01000  * adjacencies are being specified, the second value is the count of
01001  * adjacent entities, and the remainder of the group is the list of
01002  * IDs of the adjacent entities.
01003  */
01004 /*@{*/
01005 
01006 /** \brief Create adjacency data table for nodes, elements, polys, etc. 
01007  * 
01008  * Create file object for adjacency data for a nodes or a specified
01009  * element group.
01010  *
01011  * Adjacency data is formated as a sequence of integer groups where
01012  * the first entry in each group is the ID of the element for which
01013  * adjacencies are being specified, the second value is the count of
01014  * adjacent entities, and the remainder of the group is the list of
01015  * IDs of the adjacent entities.
01016  *
01017  * \param file_handle The file.
01018  * \param elem_handle The element group (or the result of
01019  *                    <code>mhdf_node_type_handle</code> for nodes) for
01020  *                    which the adjacency data is to be specified.
01021  * \param adj_list_size The total number of integer values contained
01022  *                    in the adjacency data for the specified element group.
01023  * \param status       Passed back status of API call.
01024  * \return The HDF5 handle to the connectivity data.
01025  */
01026 hid_t mhdf_createAdjacency( mhdf_FileHandle file_handle,
01027                             const char* elem_handle,
01028                             long adj_list_size,
01029                             mhdf_Status* status );
01030 
01031 /** \brief Check if adjacency data is present in the file for the specified
01032  *  element group.
01033  *
01034  * \param file         The file.
01035  * \param elem_handle  A handle to an element group.  
01036  * \param status       Passed back status of API call.
01037  */
01038 int mhdf_haveAdjacency( mhdf_FileHandle file, const char* elem_handle, mhdf_Status* status );
01039 
01040 /** \brief Open adjacency data table for nodes, elements, polys, etc. 
01041  * 
01042  * Open the file object containing adjacency data for a nodes or a specified
01043  * element group.
01044  *
01045  * Adjacency data is formated as a sequence of integer groups where
01046  * the first entry in each group is the ID of the element for which
01047  * adjacencies are being specified, the second value is the count of
01048  * adjacent entities, and the remainder of the group is the list of
01049  * IDs of the adjacent entities.
01050  *
01051  * \param file_handle The file.
01052  * \param elem_handle The element group (or the result of
01053  *                    <code>mhdf_node_type_handle</code> for nodes) for
01054  *                    which the adjacency data is to be specified.
01055  * \param adj_list_size The total number of integer values contained
01056  *                    in the adjacency data for the specified element group.
01057  * \param status       Passed back status of API call.
01058  * \return The HDF5 handle to the connectivity data.
01059  */
01060 hid_t mhdf_openAdjacency( mhdf_FileHandle file_handle,
01061                           const char* elem_handle,
01062                           long* adj_list_size,
01063                           mhdf_Status* status );
01064 
01065 /** \brief Write node/element adjacency data
01066  *
01067  * Write adjacency data.
01068  *
01069  * Adjacency data is formated as a sequence of integer groups where
01070  * the first entry in each group is the ID of the element for which
01071  * adjacencies are being specified, the second value is the count of
01072  * adjacent entities, and the remainder of the group is the list of
01073  * IDs of the adjacent entities.
01074  *
01075  * \param data_handle  Handle returned from <code>mhdf_createAdjacency</code>
01076  *                     or <code>mhdf_openAdjacency</code>.
01077  * \param offset       List position at which to start writing.  Offset is
01078  *                     from the count if integer values written, NOT a count
01079  *                     of the number of elements for which adjacency data
01080  *                     is written.
01081  * \param count        Number of integer values to write.
01082  * \param hdf_integer_type The type of the integer data in <code>adj_list_data</code>.
01083  *                     Typically <code>H5T_NATIVE_INT</code> or
01084  *                     <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
01085  *                     The HDF class of this type object <em>must</em> be H5T_INTEGER
01086  * \param adj_list_data Adjacency data to write.
01087  * \param status       Passed back status of API call.
01088  */
01089 void mhdf_writeAdjacency( hid_t data_handle,
01090                           long offset,
01091                           long count,
01092                           hid_t hdf_integer_type,
01093                           const void* adj_list_data,
01094                           mhdf_Status* status );
01095 void mhdf_writeAdjacencyWithOpt( hid_t data_handle,
01096                                  long offset,
01097                                  long count,
01098                                  hid_t hdf_integer_type,
01099                                  const void* adj_list_data,
01100                                  hid_t write_prop,
01101                                  mhdf_Status* status );
01102 
01103 /** \brief Read node/element adjacency data
01104  *
01105  * Read adjacency data.
01106  *
01107  * Adjacency data is formated as a sequence of integer groups where
01108  * the first entry in each group is the ID of the element for which
01109  * adjacencies are being specified, the second value is the count of
01110  * adjacent entities, and the remainder of the group is the list of
01111  * IDs of the adjacent entities.
01112  *
01113  * \param data_handle  Handle returned from <code>mhdf_createAdjacency</code>
01114  *                     or <code>mhdf_openAdjacency</code>.
01115  * \param offset       List position at which to start reading.  Offset is
01116  *                     from the count if integer values written, NOT a count
01117  *                     of the number of elements for which adjacency data
01118  *                     is written.
01119  * \param count        Number of integer values to reading.
01120  * \param hdf_integer_type The type of the integer data in <code>adj_list_data_out</code>.
01121  *                     Typically <code>H5T_NATIVE_INT</code> or
01122  *                     <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
01123  *                     The HDF class of this type object <em>must</em> be H5T_INTEGER
01124  * \param adj_list_data_out Pointer to memory at which to write adjacency data.
01125  * \param status       Passed back status of API call.
01126  */
01127 void mhdf_readAdjacency( hid_t data_handle,
01128                          long offset,
01129                          long count,
01130                          hid_t hdf_integer_type,
01131                          void* adj_list_data_out,
01132                          mhdf_Status* status );
01133 void mhdf_readAdjacencyWithOpt( hid_t data_handle,
01134                                 long offset,
01135                                 long count,
01136                                 hid_t hdf_integer_type,
01137                                 void* adj_list_data_out,
01138                                 hid_t read_prop,
01139                                 mhdf_Status* status );
01140 
01141 /*@}*/
01142 
01143 /**
01144  *\defgroup mhdf_set Meshset data.
01145  *
01146  * Meshset data is divided into three groups of data.  The set-list/meta-information table,
01147  * the set contents table and the set children table.  Each is written and read independently.
01148  *
01149  * The set list table contains one row for each set.  Each row contains four values:
01150  * {content list end index, child list end index, parent list end index, and flags}.  The flags 
01151  * value is a collection of bits with
01152  * values defined in \ref mhdf_set_flag .  The all the flags except \ref mhdf_SET_RANGE_BIT are
01153  * saved properties of the mesh data and are not relevant to the actual file in any way.  The
01154  * \ref mhdf_SET_RANGE_BIT flag is a toggle for how the meshset contents (not children) are saved.
01155  * It is an internal property of the file format and should not be passed on to the mesh database.
01156  * The content list end index and child list end index are the indices of the last entry for the
01157  * set in the contents and children tables respectively.  In the case where a set has either no
01158  * children or no contents, the last index of should be the same as the last index of the previous
01159  * set in the table, or -1 for the first set in the table.  Thus the first index is always one
01160  * greater than the last index of the previous set.  If the first index, calculated as one greater
01161  * that the last index of the previous set is greater than the last index of the current set, then
01162  * there are no values in the corresponding contents or children table for that set.
01163  *
01164  * The set contents table is a vector of integer global IDs that is the concatenation of the contents
01165  * data for all of the mesh sets.  The values are stored corresponding to the order of the sets
01166  * in the set list table.  Depending on the value of \ref mhdf_SET_RANGE_BIT in the flags field of
01167  * the set list table, the contents for a specific set may be stored in one of two formats.  If the
01168  * flag is set, the contents list is a list of pairs where each pair is a starting global Id and a 
01169  * count.  For each pair, the set contains the range of global Ids beginning at the start value. 
01170  * If the \ref mhdf_SET_RANGE_BIT flag is not set, the meshset contents are a simple list of global Ids.
01171  *
01172  * The meshset child table is a vector of integer global IDs.  It is a concatenation of the child
01173  * lists for all the mesh sets, in the order the sets occur in the meshset list table.  The values
01174  * are always simple lists.  The child table may never contain ranges of IDs.
01175  */
01176 /*@{*/
01177 
01178 /**
01179  *\defgroup mhdf_set_flag Set flag bits
01180  */
01181 /*@{*/
01182 
01183 /** \brief Make entities in set aware of owning set (MOAB-specific?)*/
01184 #define mhdf_SET_OWNER_BIT 0x1
01185 /** \brief Set cannot contain duplicates */
01186 #define mhdf_SET_UNIQUE_BIT 0x2
01187 /** \brief Set order is preserved */
01188 #define mhdf_SET_ORDER_BIT 0x4
01189 
01190 /** \brief The bit specifying set storage format.
01191  *
01192  * If this bit is set, then the contents of a set (not the children) 
01193  * is written as set of ranges, where each range is of the form
01194  * {global start id, count}.  For such a range, the set contains the
01195  * <code>count</code> entities with sequential global IDs beginning
01196  * with the specified start ID.  If this bit is not set in the set flags,
01197  * the contents of the set are stored as a simple list of global IDs.
01198  */
01199 #define mhdf_SET_RANGE_BIT 0x8
01200 
01201 /*@}*/
01202 
01203 /** \brief Create table holding list of meshsets and their properties.
01204  * 
01205  * The set table contains description of sets, but not contents or
01206  * children.  The table is a <code>n x 4</code> matrix of values.  
01207  * One row for each of <code>n</code> sets.  Each row contains the end index
01208  * for the set in the contents table, the end index for the set in the children
01209  * table, the end index for the set in the parents table, and the set flags, 
01210  * respectively. The \ref mhdf_SET_RANGE_BIT
01211  * bit in the flags specifies the format of the contents list for each set.
01212  * See a description of the \ref mhdf_SET_RANGE_BIT flag for a description
01213  * of the two possible data formats.  The index values in the first two columns
01214  * of the table are the index of the <em>last</em> value for the set in the corresponding
01215  * contents and children lists.  The first index is always one greater than the last index
01216  * for the previous set in the table.  The first index of the first set in the table is
01217  * implicitly zero.  A special value of -1 in the appropriate column should be used to 
01218  * indicate that the first set contains no contents or has no children.  For any other set,
01219  * if the last index for the set is the same as that of the previous set, it has no data
01220  * in the corresponding list. 
01221  *
01222  *\param file_handle  The file.
01223  *\param num_sets     The number of sets in the table.
01224  *\param first_set_id_out  The global ID that will be assigned to the first
01225  *                    set in the table.  All subsequent sets in the table
01226  *                    will be assigned sequential global IDs.
01227  * \param status       Passed back status of API call.
01228  *\return The handle to the set meta-data table.  
01229  */
01230 hid_t mhdf_createSetMeta( mhdf_FileHandle file_handle, long num_sets, long* first_set_id_out, mhdf_Status* status );
01231 
01232 /** \brief Check if file contains any sets
01233  *
01234  *\param file               The file.
01235  *\param have_set_data_out  If non-null set to 1 if file contains table
01236  *                          of set contents, zero otherwise.
01237  *\param have_set_child_out If non-null set to 1 if file contains table
01238  *                          of set children, zero otherwise.
01239  *\param have_set_parents_out If non-null set to 1 if file contains table
01240  *                          of set parents, zero otherwise.
01241  * \param status       Passed back status of API call.
01242  *\return Zero if the file does not contain any sets, one if it does.
01243  */
01244 int mhdf_haveSets( mhdf_FileHandle file,
01245                    int* have_set_data_out,
01246                    int* have_set_child_out,
01247                    int* have_set_parents_out,
01248                    mhdf_Status* status );
01249 
01250 /** \brief Open table holding list of meshsets and their properties.
01251  * 
01252  * Open set list.  
01253  * See \ref mhdf_createSetMeta or \ref mhdf_set for a description of this data.
01254  *
01255  *\param file_handle  The file.
01256  *\param num_sets_out The number of sets in the table.
01257  *\param first_set_id_out  The global ID that will of the first
01258  *                    set in the table.  All subsequent sets in the table
01259  *                    have sequential global IDs.
01260  * \param status       Passed back status of API call.
01261  *\return The handle to the set meta-data table.  
01262  */
01263 hid_t mhdf_openSetMeta( mhdf_FileHandle file_handle, long* num_sets_out, long* first_set_id_out, mhdf_Status* status );
01264 
01265 hid_t mhdf_openSetMetaSimple( mhdf_FileHandle file_handle, mhdf_Status* status );
01266 
01267 /** \brief Read list of sets and meta-information about sets.
01268  *
01269  * Read set descriptions.  See \ref mhdf_createSetMeta or \ref mhdf_set 
01270  * for a description of this data.
01271  *
01272  *\param data_handle The handle returned from \ref mhdf_createSetMeta or
01273  *                   \ref mhdf_openSetMeta.
01274  *\param offset      The offset (set index) to begin reading at.
01275  *\param count       The number of rows (sets, integer triples) to read.
01276  *\param hdf_integer_type The type of the integer data in <code>set_desc_data</code>.
01277  *                   Typically <code>H5T_NATIVE_INT</code> or
01278  *                   <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
01279  *                   The HDF class of this type object <em>must</em> be H5T_INTEGER
01280  * \param status       Passed back status of API call.
01281  *\param set_desc_data The memory location at which to write the data.
01282  */
01283 void mhdf_readSetMeta( hid_t data_handle,
01284                        long offset,
01285                        long count,
01286                        hid_t hdf_integer_type,
01287                        void* set_desc_data,
01288                        mhdf_Status* status );
01289 void mhdf_readSetMetaWithOpt( hid_t data_handle,
01290                               long offset,
01291                               long count,
01292                               hid_t hdf_integer_type,
01293                               void* set_desc_data,
01294                               hid_t read_prop,
01295                               mhdf_Status* status );
01296 
01297 /** \brief Read only the flags portion of the set description table
01298  *
01299  * Read flags for each set from the set description table.
01300  * See \ref mhdf_createSetMeta for a description of this data.
01301  *\param data_handle The handle returned from mdhf_createSetMeta or mhdf_openSetMeta
01302  *\param offset      The offset (set index) at which to begin reading.
01303  *\param count       The number of values (number of sets) to read.
01304  *\param hdf_integer_type The integer type of the input array 'set_flag_data'.
01305  *\param set_flag_data Array of integers.
01306  *\param status      Location at which to store status of API call.
01307  */
01308 void mhdf_readSetFlags( hid_t data_handle,
01309                         long offset,
01310                         long count,
01311                         hid_t hdf_integer_type,
01312                         void* set_flag_data,
01313                         mhdf_Status* status );
01314 void mhdf_readSetFlagsWithOpt( hid_t data_handle,
01315                                long offset,
01316                                long count,
01317                                hid_t hdf_integer_type,
01318                                void* set_flag_data,
01319                                hid_t read_prop,
01320                                mhdf_Status* status );
01321 
01322 /** \brief Read only the content end indices portion of the set description table
01323  *
01324  * For each set, read the last index of that set's data in the set
01325  * contents table. 
01326  *
01327  * NOTE: This is a signed value.  Any sets w/out contents that occur
01328  *       first in the list will have an end index of -1.
01329  * 
01330  *\param data_handle The handle returned from mdhf_createSetMeta or mhdf_openSetMeta
01331  *\param offset      The offset (set index) at which to begin reading.
01332  *\param count       The number of values (number of sets) to read.
01333  *\param hdf_integer_type The integer type of the input array 'set_flag_data'.
01334  *\param end_indices_out Array of indices.
01335  *\param status      Location at which to store status of API call.
01336  */
01337 void mhdf_readSetContentEndIndices( hid_t data_handle,
01338                                     long offset,
01339                                     long count,
01340                                     hid_t hdf_integer_type,
01341                                     void* end_indices_out,
01342                                     mhdf_Status* status );
01343 void mhdf_readSetContentEndIndicesWithOpt( hid_t data_handle,
01344                                            long offset,
01345                                            long count,
01346                                            hid_t hdf_integer_type,
01347                                            void* end_indices_out,
01348                                            hid_t read_prop,
01349                                            mhdf_Status* status );
01350 
01351 /** \brief Read only the child end indices portion of the set description table
01352  *
01353  * For each set, read the last index of that set's data in the set
01354  * children table. 
01355  *
01356  * NOTE: This is a signed value.  Any sets w/out contents that occur
01357  *       first in the list will have an end index of -1.
01358  * 
01359  *\param data_handle The handle returned from mdhf_createSetMeta or mhdf_openSetMeta
01360  *\param offset      The offset (set index) at which to begin reading.
01361  *\param count       The number of values (number of sets) to read.
01362  *\param hdf_integer_type The integer type of the input array 'set_flag_data'.
01363  *\param end_indices_out Array of indices.
01364  *\param status      Location at which to store status of API call.
01365  */
01366 void mhdf_readSetChildEndIndices( hid_t data_handle,
01367                                   long offset,
01368                                   long count,
01369                                   hid_t hdf_integer_type,
01370                                   void* end_indices_out,
01371                                   mhdf_Status* status );
01372 void mhdf_readSetChildEndIndicesWithOpt( hid_t data_handle,
01373                                          long offset,
01374                                          long count,
01375                                          hid_t hdf_integer_type,
01376                                          void* end_indices_out,
01377                                          hid_t read_prop,
01378                                          mhdf_Status* status );
01379 
01380 /** \brief Read only the parent end indices portion of the set description table
01381  *
01382  * For each set, read the last index of that set's data in the set
01383  * parents table. 
01384  *
01385  * NOTE: This is a signed value.  Any sets w/out contents that occur
01386  *       first in the list will have an end index of -1.
01387  * 
01388  *\param data_handle The handle returned from mdhf_createSetMeta or mhdf_openSetMeta
01389  *\param offset      The offset (set index) at which to begin reading.
01390  *\param count       The number of values (number of sets) to read.
01391  *\param hdf_integer_type The integer type of the input array 'set_flag_data'.
01392  *\param end_indices_out Array of indices.
01393  *\param status      Location at which to store status of API call.
01394  */
01395 void mhdf_readSetParentEndIndices( hid_t data_handle,
01396                                    long offset,
01397                                    long count,
01398                                    hid_t hdf_integer_type,
01399                                    void* end_indices_out,
01400                                    mhdf_Status* status );
01401 void mhdf_readSetParentEndIndicesWithOpt( hid_t data_handle,
01402                                           long offset,
01403                                           long count,
01404                                           hid_t hdf_integer_type,
01405                                           void* end_indices_out,
01406                                           hid_t read_prop,
01407                                           mhdf_Status* status );
01408 
01409 /** \brief Write list of sets and meta-information about sets.
01410  *
01411  * Write set descriptions.  See \ref mhdf_createSetMeta or \ref mhdf_set for a 
01412  * description of the data format.
01413  *
01414  *\param data_handle The handle returned from \ref mhdf_createSetMeta or
01415  *                   \ref mhdf_openSetMeta.
01416  *\param offset      The offset (set index) to begin writing at.
01417  *\param count       The number of rows (sets, integer triples) to write.
01418  *\param hdf_integer_type The type of the integer data in <code>set_desc_data</code>.
01419  *                   Typically <code>H5T_NATIVE_INT</code> or
01420  *                   <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
01421  *                   The HDF class of this type object <em>must</em> be H5T_INTEGER
01422  *\param set_desc_data The data to write.
01423  * \param status       Passed back status of API call.
01424  */
01425 void mhdf_writeSetMeta( hid_t data_handle,
01426                         long offset,
01427                         long count,
01428                         hid_t hdf_integer_type,
01429                         const void* set_desc_data,
01430                         mhdf_Status* status );
01431 void mhdf_writeSetMetaWithOpt( hid_t data_handle,
01432                                long offset,
01433                                long count,
01434                                hid_t hdf_integer_type,
01435                                const void* set_desc_data,
01436                                hid_t write_prop,
01437                                mhdf_Status* status );
01438 
01439 /** \brief Create file object to hold list of meshset contents. 
01440  *
01441  * Create set contents data object.
01442  * The format of this data is a vector of integer values which is the
01443  * concatenation of the contents list for all the meshsets.  The length
01444  * and format of the data for each set is stored in the set meta table.
01445  * See \ref mhdf_createSetMeta and \ref mhdf_SET_RANGE_BIT for a 
01446  * description of that data.
01447  *
01448  *\param file_handle The file.
01449  *\param data_list_size The total length (number of integer values) to
01450  *                   be written for all the sets.
01451  *\param status      Passed back status of API call.
01452  *\return A handle to the table.
01453  */
01454 hid_t mhdf_createSetData( mhdf_FileHandle file_handle, long data_list_size, mhdf_Status* status );
01455 
01456 /** \brief Open the file object for the meshset contents. 
01457  *
01458  * Open set contents data object.
01459  * The format of this data is a vector of integer values which is the
01460  * concatenation of the contents list for all the meshsets.  The length
01461  * and format of the data for each set is stored in the set meta table.
01462  * See \ref mhdf_createSetMeta and \ref mhdf_SET_RANGE_BIT for a 
01463  * description of that data.
01464  *
01465  *\param file_handle        The file.
01466  *\param data_list_size_out The length of the table.
01467  *\param status             Passed back status of API call.
01468  *\return                   A handle to the table.
01469  */
01470 hid_t mhdf_openSetData( mhdf_FileHandle file_handle, long* data_list_size_out, mhdf_Status* status );
01471 
01472 /** \brief Write set contents.
01473  *
01474  * Write data specifying entities contained in sets.
01475  * The format of this data is a vector of integer values which is the
01476  * concatenation of the contents list for all the meshsets.  The length
01477  * and format of the data for each set is stored in the set meta table.
01478  * See \ref mhdf_createSetMeta and \ref mhdf_SET_RANGE_BIT for a 
01479  * description of that data.
01480  *
01481  *\param set_handle   The handle returned from \ref mhdf_createSetData
01482  *                    or \ref mhdf_openSetData .
01483  *\param offset       The position at which to write into the integer vector.
01484  *\param count        The number of values to write into the data vector.
01485  *\param hdf_integer_type The type of the integer data in <code>set_data</code>.
01486  *                   Typically <code>H5T_NATIVE_INT</code> or
01487  *                   <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
01488  *                   The HDF class of this type object <em>must</em> be H5T_INTEGER
01489  *\param set_data    The data to write.
01490  *\param status      Passed back status of API call.
01491  */
01492 void mhdf_writeSetData( hid_t set_handle,
01493                         long offset,
01494                         long count,
01495                         hid_t hdf_integer_type,
01496                         const void* set_data,
01497                         mhdf_Status* status );
01498 void mhdf_writeSetDataWithOpt( hid_t set_handle,
01499                                long offset,
01500                                long count,
01501                                hid_t hdf_integer_type,
01502                                const void* set_data,
01503                                hid_t write_prop,
01504                                mhdf_Status* status );
01505 
01506 /** \brief Read set contents.
01507  *
01508  * Read data specifying entities contained in sets.
01509  * The format of this data is a vector of integer values which is the
01510  * concatenation of the contents list for all the meshsets.  The length
01511  * and format of the data for each set is stored in the set meta table.
01512  * See \ref mhdf_createSetMeta and \ref mhdf_SET_RANGE_BIT for a 
01513  * description of that data.
01514  *
01515  *\param set_handle   The handle returned from \ref mhdf_createSetData
01516  *                    or \ref mhdf_openSetData .
01517  *\param offset       The position at which to read from the integer vector.
01518  *\param count        The number of values to read from the data vector.
01519  *\param hdf_integer_type The type of the integer data in <code>set_data</code>.
01520  *                   Typically <code>H5T_NATIVE_INT</code> or
01521  *                   <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
01522  *                   The HDF class of this type object <em>must</em> be H5T_INTEGER
01523  *\param set_data    A pointer to memory at which to store the read data.
01524  *\param status      Passed back status of API call.
01525  */
01526 void mhdf_readSetData( hid_t set_handle,
01527                        long offset,
01528                        long count,
01529                        hid_t hdf_integer_type,
01530                        void* set_data,
01531                        mhdf_Status* status );
01532 void mhdf_readSetDataWithOpt( hid_t set_handle,
01533                               long offset,
01534                               long count,
01535                               hid_t hdf_integer_type,
01536                               void* set_data,
01537                               hid_t read_prop,
01538                               mhdf_Status* status );
01539 
01540 /** \brief Create file object for storing the set child list 
01541  *
01542  * Create a data group for the list of set children.  
01543  * The format of this data is the concatenation of the lists of
01544  * global IDs of child sets for each set.  The order of the sets and
01545  * the number of children for each set is contained in the set meta table.
01546  * (See \ref mhdf_createSetMeta ).
01547  *
01548  *\param file_handle      The file
01549  *\param child_list_size  The total length of the data (the sum of the 
01550  *                        number of children for each set.)
01551  *\param status           Passed back status of API call.
01552  *\return A handle to the data object in the file.
01553  */
01554 hid_t mhdf_createSetChildren( mhdf_FileHandle file_handle, long child_list_size, mhdf_Status* status );
01555 
01556 /** \brief Open the file object containing the set child list 
01557  *
01558  * Open the data group containing the list of set children.  
01559  * See \ref mhdf_createSetChildren and \ref mhdf_createSetMeta for 
01560  * a description of this data.
01561  *
01562  *\param file_handle      The file
01563  *\param child_list_size  The total length of the data (the sum of the 
01564  *                        number of children for each set.)
01565  *\param status           Passed back status of API call.
01566  *\return A handle to the data object in the file.
01567  */
01568 hid_t mhdf_openSetChildren( mhdf_FileHandle file_handle, long* child_list_size, mhdf_Status* status );
01569 
01570 /** \brief Create file object for storing the set parent list 
01571  *
01572  * Create a data group for the list of set parents.  
01573  * The format of this data is the concatenation of the lists of
01574  * global IDs of parent sets for each set.  The order of the sets and
01575  * the number of parents for each set is contained in the set meta table.
01576  * (See \ref mhdf_createSetMeta ).
01577  *
01578  *\param file_handle       The file
01579  *\param parent_list_size  The total length of the data (the sum of the 
01580  *                         number of parents for each set.)
01581  *\param status            Passed back status of API call.
01582  *\return A handle to the data object in the file.
01583  */
01584 hid_t mhdf_createSetParents( mhdf_FileHandle file_handle, long parent_list_size, mhdf_Status* status );
01585 
01586 /** \brief Open the file object containing the set parent list 
01587  *
01588  * Open the data group containing the list of set parents.  
01589  * See \ref mhdf_createSetParents and \ref mhdf_createSetMeta for 
01590  * a description of this data.
01591  *
01592  *\param file_handle       The file
01593  *\param parent_list_size  The total length of the data (the sum of the 
01594  *                         number of parents for each set.)
01595  *\param status            Passed back status of API call.
01596  *\return A handle to the data object in the file.
01597  */
01598 hid_t mhdf_openSetParents( mhdf_FileHandle file_handle, long* parent_list_size, mhdf_Status* status );
01599 
01600 /** \brief Write set parent/child list
01601  *
01602  * Write the list of parent or child IDs for sets.
01603  * See \ref mhdf_createSetChildren and \ref mhdf_createSetMeta for 
01604  * a description of this data.
01605  * 
01606  *\param data_handle The value returned from \ref mhdf_createSetChildren
01607  *                   or \ref mhdf_openSetChildren.
01608  *\param offset      The offset into the list of global IDs.
01609  *\param count       The number of global IDs to write.
01610  *\param hdf_integer_type The type of the integer data in <code>child_id_list</code>.
01611  *                   Typically <code>H5T_NATIVE_INT</code> or
01612  *                   <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
01613  *                   The HDF class of this type object <em>must</em> be H5T_INTEGER
01614  *\param id_list     The data to write.
01615  *\param status      Passed back status of API call.
01616  */
01617 void mhdf_writeSetParentsChildren( hid_t data_handle,
01618                                    long offset,
01619                                    long count,
01620                                    hid_t hdf_integer_type,
01621                                    const void* id_list,
01622                                    mhdf_Status* status );
01623 void mhdf_writeSetParentsChildrenWithOpt( hid_t data_handle,
01624                                           long offset,
01625                                           long count,
01626                                           hid_t hdf_integer_type,
01627                                           const void* id_list,
01628                                           hid_t write_prop,
01629                                           mhdf_Status* status );
01630 
01631 /** \brief Read set parent/child list
01632  *
01633  * Read from the list of parent or child IDs for sets.
01634  * See \ref mhdf_createSetChildren and \ref mhdf_createSetMeta for 
01635  * a description of this data.
01636  * 
01637  *\param data_handle The value returned from \ref mhdf_createSetChildren
01638  *                   or \ref mhdf_openSetChildren.
01639  *\param offset      The offset into the list of global IDs.
01640  *\param count       The number of global IDs to read.
01641  *\param hdf_integer_type The type of the integer data in <code>child_id_list</code>.
01642  *                   Typically <code>H5T_NATIVE_INT</code> or
01643  *                   <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
01644  *                   The HDF class of this type object <em>must</em> be H5T_INTEGER
01645  *\param id_list     Pointer to memory in which to the read data.
01646  *\param status      Passed back status of API call.
01647  */
01648 void mhdf_readSetParentsChildren( hid_t data_handle,
01649                                   long offset,
01650                                   long count,
01651                                   hid_t hdf_integer_type,
01652                                   void* id_list,
01653                                   mhdf_Status* status );
01654 void mhdf_readSetParentsChildrenWithOpt( hid_t data_handle,
01655                                          long offset,
01656                                          long count,
01657                                          hid_t hdf_integer_type,
01658                                          void* id_list,
01659                                          hid_t read_prop,
01660                                          mhdf_Status* status );
01661 
01662 /*@}*/
01663 
01664 /**
01665  *\defgroup mhdf_tag Tag data.
01666  *
01667  * The data for each tag can be stored in two places/formats:  sparse and/or
01668  * dense.  The data may be stored in both, but there should not be redundant 
01669  * values for the same entity.  
01670  *
01671  * Dense tag data is stored as multiple tables of tag values, one for each
01672  * element group.  (Note:  special \ref mhdf_ElemHandle values are available
01673  * for accessing dense tag data on nodes or meshsets via the \ref mhdf_node_type_handle
01674  * and \ref mhdf_set_type_handle functions.)  Each dense tag table should contain
01675  * the same number of entries as the element connectivity table.  The tag values 
01676  * are associated with the corresponding element in the connectivity table.
01677  *
01678  * Sparse tag data is stored as a global table pair for each tag type.  The first
01679  * if the pair of tables is a list of Global IDs.  The second is the corresponding
01680  * tag value for each entity in the ID list.
01681  */
01682 /*@{*/
01683 
01684 /**
01685  *\defgroup mhdf_tag_flag Tag type values   (MOAB-specific)
01686  */
01687 /*@{*/
01688 
01689 /** \brief Was dense tag data in mesh database */
01690 #define mhdf_DENSE_TYPE 2
01691 /** \brief Was sparse tag data in mesh database */
01692 #define mhdf_SPARSE_TYPE 1
01693 /** \brief Was bit-field tag data in mesh database */
01694 #define mhdf_BIT_TYPE 0
01695 /** \brief Unused */
01696 #define mhdf_MESH_TYPE 3
01697 
01698 /*@}*/
01699 
01700 /** \brief Make type native-endian.
01701  *
01702  * Given an atomic HDF5 data type, return the built-in type
01703  * that matches the class of the passed type and is the specified
01704  * size. 
01705  *
01706  * This function is provided to allow converting the stored tag
01707  * type in a file to the preferred type for it's representation 
01708  * in memory when reading tag values.
01709  *
01710  * This function works only for atomic types.  The returned type
01711  * will be a pre-defined HDF5 object and does not need to be
01712  * closed/released.
01713  *
01714  *\param input_type   The type to convert.
01715  *\param size         The desired size in bytes.
01716  *\param status       Passed back status of API call.
01717  *\return             The converted type.
01718  */
01719 hid_t mhdf_getNativeType( hid_t input_type, int size, mhdf_Status* status );
01720 
01721 /** \brief Add a tag to the file
01722  *
01723  * Add a new tag to the file.  This function must be called
01724  * to define the tag characteristics before values for the
01725  * tag can be written.
01726  *
01727  *\param file_handle    The file
01728  *\param tag_name       The tag name
01729  *\param tag_type       The tag type.
01730  *\param size           If tag_type == mhdf_BITFIELD, the number of
01731  *                      bits.  If tag_type == mhdf_OPAQUE, the size
01732  *                      of the opaque type in bytes.  Otherwise the
01733  *                      length of the array of tag_type entities associated
01734  *                      with each mesh entity, or 1 for a scalar value.
01735  *\param storage        MOAB storage type (dense, sparse, etc.)
01736  *\param default_value  Default value for tag, or NULL if none.
01737  *\param global_value   Global value for tag, or NULL if none.
01738  *\param hdf_type       If non-zero, assumed to be a user-specified type
01739  *                      for opaque data.  Ignored if tag_type is not
01740  *                      mhdf_OPAQUE.
01741  *\param hdf_base_type  Ignored if hdf_type is non-zero.  If hdf_type is
01742  *                      zero and this type is non-zero, it is used either
01743  *                      as the type or as the base type for an array type for 
01744  *                      default_value and global_value, respectively.  Typically
01745  *                      used to specify the input data type for mhdf_ENTITY_ID
01746  *                      tags.  
01747  */
01748 void mhdf_createTag( mhdf_FileHandle file_handle,
01749                      const char* tag_name,
01750                      enum mhdf_TagDataType tag_type,
01751                      int size,
01752                      int storage,
01753                      const void* default_value,
01754                      const void* global_value,
01755                      hid_t hdf_type,
01756                      hid_t mhdf_base_type,
01757                      mhdf_Status* status );
01758 
01759 /**\brief Get handle to HDF5 type object for tag data */
01760 hid_t mhdf_getTagDataType( mhdf_FileHandle file_handle, const char* tag_name, mhdf_Status* status );
01761 
01762 /** \brief Add variable-length tag to file
01763  *
01764  * Add a new tag to the file.  This function must be called
01765  * to define the tag characteristics before values for the
01766  * tag can be written.  Use this function if the tag values
01767  * are not fixed-length.
01768  *
01769  *\param file_handle    The file
01770  *\param tag_name       The tag name
01771  *\param tag_type       The tag type.
01772  *\param storage        MOAB storage type (dense, sparse, etc.)
01773  *\param default_value  Default value for tag, or NULL if none.
01774  *\param default_value_length Length of default value.
01775  *\param global_value   Global value for tag, or NULL if none.
01776  *\param global_value_length Length of global value.
01777  *\param hdf_type       If non-zero, assumed to be a user-specified type
01778  *                      for opaque data.  Ignored if tag_type is not
01779  *                      mhdf_OPAQUE.
01780  *\param hdf_base_type  Ignored if hdf_type is non-zero.  If hdf_type is
01781  *                      zero and this type is non-zero, it is used either
01782  *                      as the type or as the base type for an array type for 
01783  *                      default_value and global_value, respectively.  Typically
01784  *                      used to specify the input data type for mhdf_ENTITY_ID
01785  *                      tags.  
01786  */
01787 void mhdf_createVarLenTag( mhdf_FileHandle file_handle,
01788                            const char* tag_name,
01789                            enum mhdf_TagDataType tag_type,
01790                            int storage,
01791                            const void* default_value,
01792                            int default_value_length,
01793                            const void* global_value,
01794                            int global_value_length,
01795                            hid_t hdf_type,
01796                            hid_t hdf_base_type,
01797                            mhdf_Status* status );
01798 
01799 /** \brief Get the number of tags in the file.
01800  *
01801  *\param file_handle   The file.
01802  *\param status        Passed back status of API call.
01803  *\return The number of tags.
01804  */
01805 int mhdf_getNumberTags( mhdf_FileHandle file_handle, mhdf_Status* status );
01806 
01807 /** \brief Get the name for each tag defined in the file.
01808  *
01809  *\param file_handle   The file.
01810  *\param num_names_out The length of the returned array of strings.
01811  *\param status        Passed back status of API call.
01812  *\return An array of null-terminated strings.  The array
01813  *        and each string is allocated with <code>malloc</code>.
01814  *        The caller should release this memory by calling 
01815  *        <code>free</code> for each string and the array.
01816  */
01817 char** mhdf_getTagNames( mhdf_FileHandle file_handle, int* num_names_out, mhdf_Status* status );
01818 
01819 /** \brief Get the description of a specified tag.
01820  *
01821  * Get everything about a tag except the actual values.
01822  *
01823  *\param file_handle      The file.
01824  *\param tag_name         The name of the tag to retrieve the data for.
01825  *\param class_out        The TSTT class of the tag data.
01826  *\param size_out         Depends on value of class_out:
01827  *                        - mhdf_OPAQUE  - size of opaque data in bytes
01828  *                        - mhdf_BITFIELD - number of bits
01829  *                        - if data is fixed-length array, length of array
01830  *                        - if data is single value, 1
01831  *                        - if data is a variable-length array, -1
01832  *\param tstt_storage_out The value of the TSTT enum for storage (dense, sparse, etc.)
01833  *\param have_default_out Non-zero if file contains a default value for the tag. 
01834  *                        Length of default value if variable-lenth tag.
01835  *\param have_global_out  Non-zero if the file contains a global/mesh value for the tag.
01836  *\param have_sparse_out  Non-zero if the file contains a sparse data table for this tag.
01837  */
01838 void mhdf_getTagInfo( mhdf_FileHandle file_handle,
01839                       const char* tag_name,
01840                       enum mhdf_TagDataType* class_out,
01841                       int* size_out,
01842                       int* tstt_storage_out,
01843                       int* have_default_out,
01844                       int* have_global_out,
01845                       int* have_sparse_out,
01846                       mhdf_Status* status );
01847 
01848 /** \brief Get the default and global values of the tag.
01849  *
01850  *\param file_handle      The file.
01851  *\param tag_name         The tag name.
01852  *\param output_data_type The HDF5 type for the memory into which the
01853  *                        tag data is to be written.  If zero, then 
01854  *                        the value(s) will be read as opaque data.
01855  *\param default_value    Memory location at which to write the default
01856  *                        value of the tag.
01857  *\param global_value     If the tag has a global value, the memory location
01858  *                        at which to write that value.
01859  *\param status           Passed back status of API call.
01860  */
01861 void mhdf_getTagValues( mhdf_FileHandle file_handle,
01862                         const char* tag_name,
01863                         hid_t output_data_type,
01864                         void* default_value,
01865                         void* global_value,
01866                         mhdf_Status* status );
01867 
01868 /** \brief Check if the file contains dense tag data for the specified tag and element group.
01869  *
01870  * Check if there is dense tag data for a given element type for the specified
01871  * tag.  
01872  *
01873  *\param file_handle  The file.
01874  *\param tag_name     The tag.
01875  *\param elem_group   The element group handle, or the return value of
01876  *                    \ref mhdf_node_type_handle or \ref mhdf_set_type_handle
01877  *                    for nodes or sets respectively.
01878  *\param status       Passed back status of API call.
01879  *\return Non-zero if file contains specified data.  Zero otherwise.
01880  */
01881 int mhdf_haveDenseTag( mhdf_FileHandle file_handle, const char* tag_name, const char* elem_group, mhdf_Status* status );
01882 
01883 /** \brief Create an object to hold dense tag values for a given element group.
01884  *
01885  *\param file_handle  The file.
01886  *\param tag_name     The tag.
01887  *\param elem_group   The element group handle, or the return value of
01888  *                    \ref mhdf_node_type_handle or \ref mhdf_set_type_handle
01889  *                    for nodes or sets respectively.
01890  *\param num_values   The number of tag values to be written.  Must be
01891  *                    The same as the number of elements in the group. 
01892  *                    Specified here to allow tag values to be written
01893  *                    before node coordinates, element connectivity or meshsets.
01894  *\param status       Passed back status of API call.
01895  *\return             Handle to data object in file.
01896  */
01897 hid_t mhdf_createDenseTagData( mhdf_FileHandle file_handle,
01898                                const char* tag_name,
01899                                const char* elem_group,
01900                                long num_values,
01901                                mhdf_Status* status );
01902 
01903 /** \brief Open the object containing dense tag values for a given element group.
01904  *
01905  *\param file_handle    The file.
01906  *\param tag_name       The tag.
01907  *\param elem_group     The element group handle, or the return value of
01908  *                      \ref mhdf_node_type_handle or \ref mhdf_set_type_handle
01909  *                      for nodes or sets respectively.
01910  *\param num_values_out The number of tag values to be written.  Must be
01911  *                      The same as the number of elements in the group. 
01912  *\param status         Passed back status of API call.
01913  *\return               Handle to data object in file.
01914  */
01915 hid_t mhdf_openDenseTagData( mhdf_FileHandle file_handle,
01916                              const char* tag_name,
01917                              const char* elem_group,
01918                              long* num_values_out,
01919                              mhdf_Status* status );
01920 
01921 /** \brief Create file objects to store sparse tag data 
01922  *
01923  * Create the file objects to store all sparse data for a given tag in.  The 
01924  * sparse data is stored in a pair of objects.  The first is a vector of
01925  * global IDs.  The second is a vector of tag values for each entity specified
01926  * in the list of global IDs.
01927  *
01928  *\param file_handle    The file.
01929  *\param tag_name       The tag.
01930  *\param num_values     The number of tag values to be written.
01931  *\param entities_and_values_out The handles to the file objects.
01932  *                      The first is the vector of global IDs.  The second
01933  *                      is the list of corresponding tag values.  
01934  *\param status         Passed back status of API call.
01935  */
01936 void mhdf_createSparseTagData( mhdf_FileHandle file_handle,
01937                                const char* tag_name,
01938                                long num_values,
01939                                hid_t entities_and_values_out[2],
01940                                mhdf_Status* status );
01941 
01942 /** \brief Create file objects to store (sparse) variable-length tag data 
01943  *
01944  * Create the file objects to store all sparse data for a given tag in.  The 
01945  * sparse data is stored in a pair of objects.  The first is a vector of
01946  * global IDs.  The second is a vector of tag values for each entity specified
01947  * in the list of global IDs.
01948  *
01949  *\param file_handle    The file.
01950  *\param tag_name       The tag.
01951  *\param num_entities   The number of entities for which tag values are to be stored
01952  *\param num_values     The total number of scalar values to be written (the
01953  *                      total number of bytes of data for all tags for opaque
01954  *                      data.)
01955  *\param entities_and_values_out The handles to the file objects.
01956  *                      The first is the vector of global IDs.  The second
01957  *                      is the list of corresponding tag values.  The third
01958  *                      is the handle to the index table.
01959  *\param status         Passed back status of API call.
01960  */
01961 void mhdf_createVarLenTagData( mhdf_FileHandle file_handle,
01962                                const char* tag_name,
01963                                long num_entities,
01964                                long num_values,
01965                                hid_t entities_and_values_out[3],
01966                                mhdf_Status* status );
01967 
01968 /** \brief Create file objects to read sparse tag data 
01969  *
01970  * Open the file objects containing all sparse data for a given tag in.  The 
01971  * sparse data is stored in a pair of objects.  The first is a vector of
01972  * global IDs.  The second is a vector of tag values for each entity specified
01973  * in the list of global IDs.  For variable-length tags, a third table
01974  * containing end offsets for each tag value is returned in the third
01975  * position of the output hid_t array (see mhdf_readSparseTagIndices.)
01976  *
01977  *\param file_handle    The file.
01978  *\param tag_name       The tag.
01979  *\param num_entity_out The number of entities for which there are tag values.
01980  *\param num_values_out The number of data values.  For fixed-length tags,
01981  *                      this is the same as num_entity_out.  For
01982  *                      variable-length tags, it is the total number of
01983  *                      values in the data table.
01984  *\param entities_and_values_out The handles to the pair of file objects.
01985  *                      The first is the vector of global IDs.  The second
01986  *                      is the list of corresponding tag values.  The third
01987  *                      is the handle to the index table, iff the tag is 
01988  *                      variable-length.  If the tag is fixed-length, this
01989  *                      value is not set.
01990  *\param status         Passed back status of API call.
01991  */
01992 void mhdf_openSparseTagData( mhdf_FileHandle file_handle,
01993                              const char* tag_name,
01994                              long* num_entity_out,
01995                              long* num_values_out,
01996                              hid_t entities_and_values_out[3],
01997                              mhdf_Status* status );
01998 
01999 /** \brief Write Global ID list for sparse tag data
02000  *
02001  *\param id_handle   The first handle passed back from either
02002  *                   \ref mhdf_createSparseTagData or 
02003  *                   \ref mhdf_openSparseTagData.
02004  *\param offset      The offset at which to begin writing.
02005  *\param count       The number of global IDs to write.
02006  *\param hdf_integer_type The type of the integer data in <code>id_list</code>.
02007  *                   Typically <code>H5T_NATIVE_INT</code> or
02008  *                   <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
02009  *                   The HDF class of this type object <em>must</em> be H5T_INTEGER
02010  *\param id_list     The list of global IDs to write.
02011  *\param status      Passed back status of API call.
02012  */
02013 void mhdf_writeSparseTagEntities( hid_t id_handle,
02014                                   long offset,
02015                                   long count,
02016                                   hid_t hdf_integer_type,
02017                                   const void* id_list,
02018                                   mhdf_Status* status );
02019 void mhdf_writeSparseTagEntitiesWithOpt( hid_t id_handle,
02020                                          long offset,
02021                                          long count,
02022                                          hid_t hdf_integer_type,
02023                                          const void* id_list,
02024                                          hid_t write_prop,
02025                                          mhdf_Status* status );
02026 
02027 /** \brief Write tag values
02028  *
02029  *\param value_handle  The second handle passed back from either
02030  *                     \ref mhdf_createSparseTagData or 
02031  *                     \ref mhdf_openSparseTagData; or the handle
02032  *                     returned by \ref mhdf_createDenseTagData or
02033  *                     \ref mhdf_openDenseTagData.
02034  *\param offset        The offset at which to begin writing.
02035  *\param count         The number of tag values to write.
02036  *\param hdf_tag_data_type The type of the data in memory.  
02037  *                     It must be possible for the HDF library to convert
02038  *                     between this type and the type the tag data is stored
02039  *                     as.  
02040  *\param tag_data      The list of tag values to write.
02041  *\param status        Passed back status of API call.
02042  */
02043 void mhdf_writeTagValues( hid_t value_handle,
02044                           long offset,
02045                           long count,
02046                           hid_t hdf_tag_data_type,
02047                           const void* tag_data,
02048                           mhdf_Status* status );
02049 void mhdf_writeTagValuesWithOpt( hid_t value_handle,
02050                                  long offset,
02051                                  long count,
02052                                  hid_t hdf_tag_data_type,
02053                                  const void* tag_data,
02054                                  hid_t write_prop,
02055                                  mhdf_Status* status );
02056 
02057 /**\brief Write sparse tag end indices for variable-length tag data
02058  *
02059  * Write sparse tag end indices for variable-length tag data.
02060  * Each value in the list is the *last* index (zero-based) into the tag
02061  * data for the corresponding entity.
02062  *
02063  *\param tag_handle   handle to the data object to write to.
02064  *\param offset       The offset into the table at which to begin writting
02065  *\param count        The number of values to write.
02066  *\param hdf_integer_type  The type of the values pointed to by end_indices 
02067  *                    (must be an integer type).
02068  *\param end_indices  The values to store in the table.
02069  *\param status       Output: API result.
02070  */
02071 void mhdf_writeSparseTagIndices( hid_t tag_handle,
02072                                  long offset,
02073                                  long count,
02074                                  hid_t hdf_integer_type,
02075                                  const void* end_indices,
02076                                  mhdf_Status* status );
02077 void mhdf_writeSparseTagIndicesWithOpt( hid_t tag_handle,
02078                                         long offset,
02079                                         long count,
02080                                         hid_t hdf_integer_type,
02081                                         const void* end_indices,
02082                                         hid_t write_prop,
02083                                         mhdf_Status* status );
02084 
02085 /** \brief Read Global ID list for sparse tag data
02086  *
02087  *\param id_handle  The first handle passed back from either
02088  *                  \ref mhdf_createSparseTagData or 
02089  *                  \ref mhdf_openSparseTagData.
02090  *\param offset     The offset at which to begin reading.
02091  *\param count      The number of global IDs to read.
02092  *\param hdf_integer_type The type of the integer data in <code>id_list</code>.
02093  *                   Typically <code>H5T_NATIVE_INT</code> or
02094  *                   <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
02095  *                   The HDF class of this type object <em>must</em> be H5T_INTEGER
02096  *\param id_list     The memory location at which to store the global IDs.
02097  *\param status      Passed back status of API call.
02098  */
02099 void mhdf_readSparseTagEntities( hid_t id_handle,
02100                                  long offset,
02101                                  long count,
02102                                  hid_t hdf_integer_type,
02103                                  void* id_list,
02104                                  mhdf_Status* status );
02105 void mhdf_readSparseTagEntitiesWithOpt( hid_t id_handle,
02106                                         long offset,
02107                                         long count,
02108                                         hid_t hdf_integer_type,
02109                                         void* id_list,
02110                                         hid_t read_prop,
02111                                         mhdf_Status* status );
02112 
02113 /** \brief Read tag values
02114  *
02115  *\param value_handle  The second handle passed back from either
02116  *                     \ref mhdf_createSparseTagData or 
02117  *                     \ref mhdf_openSparseTagData; or the handle
02118  *                     returned by \ref mhdf_createDenseTagData or
02119  *                     \ref mhdf_openDenseTagData.
02120  *\param offset     The offset at which to begin reading.
02121  *\param count      The number of tag values to read.
02122  *\param hdf_type   The type of the data in memory.  If this is specified,
02123  *                  it must be possible for the HDF library to convert
02124  *                  between this type and the type the tag data is stored
02125  *                  as.  If zero, the values will be read as opaque data.
02126  *\param memory     Memory location at which to store tag values.
02127  *\param status     Passed back status of API call.
02128  */
02129 void mhdf_readTagValues( hid_t value_handle,
02130                          long offset,
02131                          long count,
02132                          hid_t hdf_type,
02133                          void* memory,
02134                          mhdf_Status* status );
02135 void mhdf_readTagValuesWithOpt( hid_t value_handle,
02136                                 long offset,
02137                                 long count,
02138                                 hid_t hdf_type,
02139                                 void* memory,
02140                                 hid_t read_prop,
02141                                 mhdf_Status* status );
02142 
02143 /**\brief Read sparse tag end indices for variable-length tag data
02144  *
02145  * Read sparse tag end indices for variable-length tag data.
02146  * Each value in the list is the *last* index (zero-based) into the tag
02147  * data for the corresponding entity.
02148  *
02149  *\param tag_handle   handle to the data object to read from.
02150  *\param offset       The offset into the table at which to begin reading
02151  *\param count        The number of values to read.
02152  *\param hdf_integer_type  The type of the values pointed to by end_indices 
02153  *                    (must be an integer type).
02154  *\param end_indices  Memory in which to store the data read from the table.
02155  *\param status       Output: API result.
02156  */
02157 void mhdf_readSparseTagIndices( hid_t tag_handle,
02158                                 long offset,
02159                                 long count,
02160                                 hid_t hdf_integer_type,
02161                                 void* end_indices,
02162                                 mhdf_Status* status );
02163 void mhdf_readSparseTagIndicesWithOpt( hid_t tag_handle,
02164                                        long offset,
02165                                        long count,
02166                                        hid_t hdf_integer_type,
02167                                        void* end_indices,
02168                                        hid_t read_prop,
02169                                        mhdf_Status* status );
02170 
02171 /*@}*/
02172 
02173 /*@}*/
02174 
02175 #ifdef __cplusplus
02176 } /* extern "C" */
02177 #endif
02178 
02179 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines