MOAB: Mesh Oriented datABase  (version 5.3.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 /**
00315  *\defgroup mhdf_status Error handling
00316  */
00317 /*@{*/
00318 
00319 /**
00320  *\defgroup mhdf_group Element group handle
00321  */
00322 /*@{*/
00323 
00324 
00325 /** \brief Get an mhdf_ElemHandle object for the node data.  
00326  *
00327  * \return A special element group handle used when specifying adjacency or
00328  * tag data for nodes. 
00329  */
00330 const char*
00331 mhdf_node_type_handle(void);
00332 
00333 
00334 /** \brief Return a special element group handle used to specify the set group.
00335  *
00336  *  \return A special element group handle used to specify the set group
00337  *  for reading/writing tag data on sets.
00338  */
00339 const char*
00340 mhdf_set_type_handle(void);
00341 
00342 #define MHDF_INDEX_TYPE H5T_NATIVE_LONG
00343 
00344 /** \brief Given an element type Id, get the name. 
00345  * Fails if buffer is not of sufficient size.
00346  * \param file_handle The file.
00347  * \param type_index The type index.  Corresponds to indices into
00348  *                   the element type list passed to \ref mhdf_createFile.
00349  * \param buffer     The buffer into which to copy the name.
00350  * \param buffer_size The length of <code>buffer</code>.
00351  * \param status     Passed back status of API call.
00352  */
00353 void
00354 mhdf_getElemName( mhdf_FileHandle file_handle,
00355                   unsigned int type_index,
00356                   char* buffer, size_t buffer_size, 
00357                   mhdf_Status* status );
00358 
00359 int
00360 mhdf_checkOpenHandles( mhdf_FileHandle handle, mhdf_Status* status );
00361 
00362 /** \brief Common close function for all data handle types.
00363  *
00364  * Close an hid_t-type handle returned from any of the following
00365  * functions.  Any hid_t passed-back or returned must be closed via
00366  * this function to avoid resource loss.
00367  *
00368  * \param file   The file the object pointed to by the passed data
00369  *               handled exists int.
00370  * \param handle The data object to close.
00371  * \param status     Passed back status of API call.
00372  */
00373 void
00374 mhdf_closeData( mhdf_FileHandle file,
00375                 hid_t handle,
00376                 mhdf_Status* status );
00377 
00378 /**\brief Get start ID that will be assigned to next created dataset
00379  *
00380  * Get the first_id parameter that will be returned from the next
00381  * call to any of mhdf_createNodeCoords, mhdf_createConnectivity, 
00382  * mhdf_createPolyConnectivity, or mhdf_createSetMeta
00383  */
00384 void
00385 mhdf_getNextStartId( mhdf_FileHandle file,
00386                      mhdf_index_t* start_id_out,
00387                      mhdf_Status* status );
00388 
00389 /** \brief Write 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  * \param file       The file.
00395  * \param strings    An array of null-terminated strings.
00396  * \param num_strings The length of <code>strings</code>
00397  * \param status     Passed back status of API call.
00398  */
00399 void
00400 mhdf_writeHistory( mhdf_FileHandle file, 
00401                    const char** strings, 
00402                    int num_strings, 
00403                    mhdf_Status* status );
00404 
00405 /** \brief Read the file history as a list of strings.
00406  *
00407  * Each entry is composed of four strings:
00408  * application, version, date, and time.
00409  *
00410  * Strings and array are allocated with <code>malloc</code>.  Caller must
00411  * release them by calling <code>free</code>
00412  *
00413  * \param file       The file.
00414  * \param num_records_out  The length of the returned array.
00415  * \param status     Passed back status of API call.
00416  * \return An array of null-terminates strings.
00417  */
00418 char**
00419 mhdf_readHistory( mhdf_FileHandle file,
00420                   int* num_records_out, 
00421                   mhdf_Status* status );
00422 /*@}*/
00423 /**
00424  *\defgroup mhdf_node Node coordinate data.
00425  */
00426 /*@{*/
00427 
00428 /* Node Coordinates */
00429 
00430 int
00431 mhdf_haveNodes( mhdf_FileHandle file_handle, mhdf_Status* status );
00432                 
00433 
00434 /** \brief Create new table for node coordinate data 
00435  *
00436  * \param file_handle  The file.
00437  * \param dimension    Number of coordinate values per node.
00438  * \param num_nodes    The number of nodes the table will contain.
00439  * \param first_node_id_out  Nodes are assigned IDs sequentially in the
00440  *             order they occur in the table, where the ID of the first
00441  *             node in the table is this passed-back value.
00442  * \param status     Passed back status of API call.
00443  * \return An HDF5 handle to the coordinate table.
00444  */
00445 hid_t
00446 mhdf_createNodeCoords( mhdf_FileHandle file_handle,
00447                        int dimension,
00448                        long num_nodes,
00449                        long* first_node_id_out,
00450                        mhdf_Status* status );
00451 
00452 /** \brief Open table containing node coordinate data 
00453  *
00454  * \param file_handle       The file.
00455  * \param dimension_out    Number of coordinate values per node.
00456  * \param num_nodes_out    The number of nodes the table contains.
00457  * \param first_node_id_out  Nodes are assigned IDs sequentially in the
00458  *             order they occur in the table, where the ID of the first
00459  *             node in the table is this passed-back value.
00460  * \param status     Passed back status of API call.
00461  * \return An HDF5 handle to the coordinate table.
00462  */
00463 hid_t
00464 mhdf_openNodeCoords( mhdf_FileHandle file_handle,
00465                      long* num_nodes_out,
00466                      int* dimension_out,
00467                      long* first_node_id_out,
00468                      mhdf_Status* status );
00469 
00470 hid_t
00471 mhdf_openNodeCoordsSimple( mhdf_FileHandle file_handle, mhdf_Status* status );
00472 
00473 /** \brief Write node coordinate data
00474  *
00475  * Write interleaved coordinate data for a block of nodes
00476  *
00477  * \param data_handle  Handle returned from <code>mhdf_createNodeCoords</code>
00478  *                     or <code>mhdf_openNodeCoords</code>.
00479  * \param offset       Table row (node index) at which to start writing.
00480  * \param count        Number of rows (number of nodes) to write.
00481  * \param coords       Interleaved node coordinate data.
00482  * \param status     Passed back status of API call.
00483  */
00484 void
00485 mhdf_writeNodeCoords( hid_t data_handle,
00486                       long offset,
00487                       long count,
00488                       const double* coords,
00489                       mhdf_Status* status );
00490 void
00491 mhdf_writeNodeCoordsWithOpt( hid_t data_handle,
00492                       long offset,
00493                       long count,
00494                       const double* coords,
00495                       hid_t write_prop,
00496                       mhdf_Status* status );
00497 
00498 /** \brief Write node coordinate data
00499  *
00500  * Write a single coordinate value (e.g. the 'x' coordinate) for a 
00501  * block of nodes.
00502  *
00503  * \param data_handle  Handle returned from <code>mhdf_createNodeCoords</code>
00504  *                     or <code>mhdf_openNodeCoords</code>.
00505  * \param offset       Table row (node index) at which to start writing.
00506  * \param count        Number of rows (number of nodes) to write.
00507  * \param dimension    The coordinate to write (0->x, 1->y, ...)
00508  * \param coords       Coordinate list.
00509  * \param status     Passed back status of API call.
00510  */
00511 void
00512 mhdf_writeNodeCoord( hid_t data_handle,
00513                      long offset,
00514                      long count,
00515                      int dimension,
00516                      const double* coords,
00517                      mhdf_Status* status );
00518 void
00519 mhdf_writeNodeCoordWithOpt( hid_t data_handle,
00520                      long offset,
00521                      long count,
00522                      int dimension,
00523                      const double* coords,
00524                      hid_t write_prop,
00525                      mhdf_Status* status );
00526 
00527 /** \brief Read node coordinate data
00528  *
00529  * Read interleaved coordinate data for a block of nodes
00530  *
00531  * \param data_handle  Handle returned from <code>mhdf_createNodeCoords</code>
00532  *                     or <code>mhdf_openNodeCoords</code>.
00533  * \param offset       Table row (node index) at which to start reading.
00534  * \param count        Number of rows (number of nodes) to read.
00535  * \param coordinates  Buffer in which to write node coordinate data.
00536  * \param status       Passed back status of API call.
00537  */
00538 void
00539 mhdf_readNodeCoords( hid_t data_handle,
00540                      long offset,
00541                      long count,
00542                      double* coordinates,
00543                      mhdf_Status* status );
00544 void
00545 mhdf_readNodeCoordsWithOpt( hid_t data_handle,
00546                      long offset,
00547                      long count,
00548                      double* coordinates,
00549                      hid_t read_prop,
00550                      mhdf_Status* status );
00551 
00552 
00553 /** \brief Read node coordinate data
00554  *
00555  * Read a single coordinate value (e.g. the 'x' coordinate) for a 
00556  * block of nodes.
00557  *
00558  * \param data_handle  Handle returned from <code>mhdf_createNodeCoords</code>
00559  *                     or <code>mhdf_openNodeCoords</code>.
00560  * \param offset       Table row (node index) at which to start reading.
00561  * \param count        Number of rows (number of nodes) to read.
00562  * \param dimension    The coordinate to read (0->x, 1->y, ...)
00563  * \param coords       Buffer in which to write node coordinate data.
00564  * \param status     Passed back status of API call.
00565  */
00566 void
00567 mhdf_readNodeCoord( hid_t data_handle,
00568                     long offset,
00569                     long count,
00570                     int dimension,
00571                     double* coords,
00572                     mhdf_Status* status );
00573 void
00574 mhdf_readNodeCoordWithOpt( hid_t data_handle,
00575                     long offset,
00576                     long count,
00577                     int dimension,
00578                     double* coords,
00579                     hid_t read_prop,
00580                     mhdf_Status* status );
00581 
00582 /*@}*/
00583 /**
00584  *\defgroup mhdf_conn Element connectivity data.
00585  */
00586 /*@{*/
00587 
00588 /* Element Connectivity */
00589 
00590 /** \brief Add a new table of element data to the file.
00591  *
00592  * Add a element group to the file. 
00593  * An element group is the data for a block of elements with the same 
00594  * TSTT type and same number of nodes in their connectivity data.
00595  * (e.g. all the MBHEX20 elements).  This function is also
00596  * used to create the groups for general polygon data and
00597  * general polyhedron data.  The requirement that all elements
00598  * have the same number of nodes in their connectivity does not
00599  * apply for poly(gons|hedra).
00600  *
00601  * \param file_handle  File in which to create the element type.
00602  * \param elem_handle  The name to use for the element data.  This
00603  *                     name is used as an identifier to reference the
00604  *                     data for this element type later.  The selected
00605  *                     name also appears explicitly in the file and 
00606  *                     therefore should be something
00607  *                     descriptive of the element type such as the
00608  *                     'base type' and number of nodes (e.g. "Hex20").
00609  * \param named_elem_type An index into the list of named element types
00610  *                     passed to \ref mhdf_createFile .
00611  * \param status     Passed back status of API call.
00612  */
00613 void
00614 mhdf_addElement( mhdf_FileHandle file_handle,
00615                  const char* elem_handle,
00616                  unsigned int named_elem_type,
00617                  mhdf_Status* status );
00618 
00619 /** \brief Get the list of element groups in the file.
00620  *
00621  * Get the list of element groups in the file.
00622  * An element group is the data for a block of elements with the same 
00623  * TSTT type and same number of nodes in their connectivity data.
00624  * (e.g. all the MBHEX20 elements).  This function is also
00625  * used to retrieve the groups for general polygon data and
00626  * general polyhedron data.  The requirement that all elements
00627  * have the same number of nodes in their connectivity does not
00628  * apply for poly(gons|hedra).
00629  *
00630  * \param  file_handle   The file.
00631  * \param  count_out     Memory location at which to store the
00632  *                       length of the returned array.
00633  * \param  status        Passed back status of API call.
00634  * \return               An array of pointers to element group
00635  *                       names.  This array is allocated as a 
00636  *                       single memory block and should be freed
00637  *                       with <em>one</em> call to free().
00638  */
00639 char**
00640 mhdf_getElemHandles( mhdf_FileHandle file_handle,
00641                      unsigned int* count_out,
00642                      mhdf_Status* status );
00643 
00644 /** 
00645  * \brief Get the element type name for a given element group handle.
00646  *
00647  * Fails if name is longer than <code>buf_len</code>.
00648  *
00649  * \param file_handle The file.
00650  * \param elem_handle One of the group names passed back from 
00651  *                    \ref mhdf_getElemHandles
00652  * \param buffer      A buffer to copy the name into.
00653  * \param buf_len     The length of <code>buffer</code>.
00654  * \param status      Passed back status of API call.
00655  */
00656 void
00657 mhdf_getElemTypeName( mhdf_FileHandle file_handle,
00658                       const char* elem_handle,
00659                       char* buffer, size_t buf_len,
00660                       mhdf_Status* status );
00661 
00662 /** \brief Check if an element group contains polygon or polyhedron
00663  *
00664  * Check if an element group contains general polygon or polyhedrons
00665  * rather than typically fixed-connectivity elements.  
00666  *
00667  * \param file_handle The file.
00668  * \param elem_handle The element group.
00669  * \param status      Passed back status of API call.
00670  * \return Zero if normal fixed-connectivity element data.  Non-zero if
00671  *         poly(gon/hedron) general-connectivity data.
00672  */
00673 int
00674 mhdf_isPolyElement( mhdf_FileHandle file_handle,
00675                     const char* elem_handle,
00676                     mhdf_Status* status );
00677 
00678 /** \brief Create connectivity table for an element group
00679  * 
00680  * Create fixed-connectivity data for an element group.
00681  * Do NOT use this function for poly(gon/hedron) data.
00682  *
00683  * \param file_handle  The file.
00684  * \param elem_handle  The element group.
00685  * \param num_nodes_per_elem The number of nodes in the connectivity data
00686  *                     for each element.
00687  * \param num_elements The number of elements to be written to the table.
00688  * \param first_elem_id_out Elements are assigned global IDs in 
00689  *                     sequential blocks where the block is the table in
00690  *                     which their connectivity data is written and the 
00691  *                     sequence is the sequence in which they are written
00692  *                     in that table.  The global ID for the first element
00693  *                     in this group is passed back at this address.  The
00694  *                     global IDs for all other elements in the table are
00695  *                     assigned in the sequence in which they are written
00696  *                     in the table.
00697  * \param status      Passed back status of API call.
00698  * \return The HDF5 handle to the connectivity data.
00699  */
00700 hid_t 
00701 mhdf_createConnectivity( mhdf_FileHandle file_handle,
00702                          const char* elem_handle,
00703                          int num_nodes_per_elem,
00704                          long num_elements,
00705                          long* first_elem_id_out,
00706                          mhdf_Status* status );
00707 
00708 
00709 /** \brief Open connectivity table for an element group
00710  * 
00711  * Open fixed-connectivity data for an element group.
00712  * Do NOT use this function for poly(gon/hedron) data.  Use
00713  * <code>mhdf_isPolyElement</code> or <code>mhdf_getTsttElemType</code>
00714  * to check if the data is poly(gon|hedron) data before calling this
00715  * function to open the data.
00716  *
00717  * \param file_handle  The file.
00718  * \param elem_handle  The element group.
00719  * \param num_nodes_per_elem_out Used to pass back the number of nodes
00720  *                     in each element.
00721  * \param num_elements_out Pass back the number of elements in the table.
00722  * \param first_elem_id_out Elements are assigned global IDs in 
00723  *                     sequential blocks where the block is the table in
00724  *                     which their connectivity data is written and the 
00725  *                     sequence is the sequence in which they are written
00726  *                     in that table.  The global ID for the first element
00727  *                     in this group is passed back at this address.  The
00728  *                     global IDs for all other elements in the table are
00729  *                     assigned in the sequence in which they are written
00730  *                     in the table.
00731  * \param status      Passed back status of API call.
00732  * \return The HDF5 handle to the connectivity data.
00733  */
00734 hid_t
00735 mhdf_openConnectivity( mhdf_FileHandle file_handle,
00736                        const char* elem_handle,
00737                        int* num_nodes_per_elem_out,
00738                        long* num_elements_out,
00739                        long* first_elem_id_out,
00740                        mhdf_Status* status );
00741 
00742 hid_t
00743 mhdf_openConnectivitySimple( mhdf_FileHandle file_handle, 
00744                              const char* elem_handle,
00745                              mhdf_Status* status );
00746                              
00747 
00748 /** \brief Write element coordinate data
00749  *
00750  * Write interleaved fixed-connectivity element data for a block of elements.
00751  * Note: Do not use this for polygon or polyhedron data. 
00752  *
00753  * \param data_handle  Handle returned from <code>mhdf_createConnectivity</code>
00754  *                     or <code>mhdf_openConnectivity</code>.
00755  * \param offset       Table row (element index) at which to start writing.
00756  * \param count        Number of rows (number of elements) to write.
00757  * \param hdf_integer_type The type of the integer data in node_id_list.
00758  *                     Typically <code>H5T_NATIVE_INT</code> or
00759  *                     <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
00760  *                     The HDF class of this type object <em>must</em> be H5T_INTEGER
00761  * \param node_id_list Interleaved connectivity data specified as global node IDs.
00762  * \param status       Passed back status of API call.
00763  */
00764 void
00765 mhdf_writeConnectivity( hid_t data_handle,
00766                         long offset,
00767                         long count,
00768                         hid_t hdf_integer_type,
00769                         const void* node_id_list,
00770                         mhdf_Status* status );
00771 void
00772 mhdf_writeConnectivityWithOpt( hid_t data_handle,
00773                         long offset,
00774                         long count,
00775                         hid_t hdf_integer_type,
00776                         const void* node_id_list,
00777                         hid_t write_prop,
00778                         mhdf_Status* status );
00779 
00780 /** \brief Read element coordinate data
00781  *
00782  * Read interleaved fixed-connectivity element data for a block of elements.
00783  * Note: Do not use this for polygon or polyhedron data. 
00784  *
00785  * \param data_handle  Handle returned from <code>mhdf_createConnectivity</code>
00786  *                     or <code>mhdf_openConnectivity</code>.
00787  * \param offset       Table row (element index) at which to start read.
00788  * \param count        Number of rows (number of elements) to read.
00789  * \param hdf_integer_type The type of the integer data in node_id_list.
00790  *                     Typically <code>H5T_NATIVE_INT</code> or
00791  *                     <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
00792  *                     The HDF class of this type object <em>must</em> be H5T_INTEGER
00793  * \param node_id_list Pointer to memory at which to write interleaved
00794  *                     connectivity data specified as global node IDs.
00795  * \param status       Passed back status of API call.
00796  */
00797 void 
00798 mhdf_readConnectivity( hid_t data_handle,
00799                        long offset,
00800                        long count,
00801                        hid_t hdf_integer_type,
00802                        void* node_id_list,
00803                        mhdf_Status* status );
00804 void 
00805 mhdf_readConnectivityWithOpt( hid_t data_handle,
00806                        long offset,
00807                        long count,
00808                        hid_t hdf_integer_type,
00809                        void* node_id_list,
00810                        hid_t read_prop,
00811                        mhdf_Status* status );
00812 
00813 /* Poly(gon|hedra) */
00814 
00815 
00816 /** \brief Create a new table for polygon or polyhedron connectivity data.
00817  *
00818  * Poly (polygon or polyhedron) connectivity is stored as two lists.
00819  * One list is the concatenation of the the connectivity data for
00820  * all the polys in the group.  The other contains one value per
00821  * poly where that value is the index of the last entry in the
00822  * connectivity of the corresponding poly.  The ID
00823  * list for polygons contains global node IDs.  The ID list for polyhedra
00824  * contains the global IDs of faces (either polygons or 2D fixed-connectivity
00825  * elements.)
00826  *
00827  * \param file_handle  The file to write.
00828  * \param elem_handle  The element group.
00829  * \param num_poly     The total number number of polygons or polyhedra to
00830  *                     be written in the table.
00831  * \param data_list_length The total number of values to be written to the
00832  *                     table (the number of polys plus the sum of the number
00833  *                     of entities in each poly's connectivity data.)
00834  * \param first_id_out Elements are assigned global IDs in 
00835  *                     sequential blocks where the block is the table in
00836  *                     which their connectivity data is written and the 
00837  *                     sequence is the sequence in which they are written
00838  *                     in that table.  The global ID for the first element
00839  *                     in this group is passed back at this address.  The
00840  *                     global IDs for all other elements in the table are
00841  *                     assigned in the sequence in which they are written
00842  *                     in the table.
00843  * \param idx_and_id_handles_out The handles for the index list and
00844  *                     connectivity list, respectively.
00845  * \param status       Passed back status of API call.
00846  */
00847 void
00848 mhdf_createPolyConnectivity( mhdf_FileHandle file_handle,
00849                              const char* elem_handle,
00850                              long num_poly,
00851                              long data_list_length,
00852                              long* first_id_out,
00853                              hid_t idx_and_id_handles_out[2],
00854                              mhdf_Status* status );
00855 
00856 /** \brief Open a table of polygon or polyhedron connectivity data.
00857  *
00858  * Poly (polygon or polyhedron) connectivity is stored as two lists.
00859  * One list is the concatenation of the the connectivity data for
00860  * all the polys in the group.  The other contains one value per
00861  * poly where that value is the index of the last entry in the
00862  * connectivity of the corresponding poly.  The ID
00863  * list for polygons contains global node IDs.  The ID list for polyhedra
00864  * contains the global IDs of faces (either polygons or 2D fixed-connectivity
00865  * elements.)
00866  *
00867  * \param file_handle  The file to write.
00868  * \param elem_handle  The element group.
00869  * \param num_poly_out The total number number of polygons or polyhedra to
00870  *                     be written in the table.
00871  * \param data_list_length_out The total number of values to be written to the
00872  *                     table (the number of polys plus the sum of the number
00873  *                     of entities in each poly's connectivity data.)
00874  * \param first_id_out Elements are assigned global IDs in 
00875  *                     sequential blocks where the block is the table in
00876  *                     which their connectivity data is written and the 
00877  *                     sequence is the sequence in which they are written
00878  *                     in that table.  The global ID for the first element
00879  *                     in this group is passed back at this address.  The
00880  *                     global IDs for all other elements in the table are
00881  *                     assigned in the sequence in which they are written
00882  *                     in the table.
00883  * \param idx_and_id_handles_out The handles for the index list and
00884  *                     connectivity list, respectively.
00885  * \param status       Passed back status of API call.
00886  */
00887 void
00888 mhdf_openPolyConnectivity( mhdf_FileHandle file_handle,
00889                            const char* elem_handle,
00890                            long* num_poly_out,
00891                            long* data_list_length_out,
00892                            long* first_id_out,
00893                            hid_t idx_and_id_handles_out[2],
00894                            mhdf_Status* status );
00895 
00896 /** \brief Write polygon or polyhedron index data.
00897  *
00898  * Poly (polygon or polyhedron) connectivity is stored as two lists.
00899  * One list is the concatenation of the the connectivity data for
00900  * all the polys in the group.  The other contains one value per
00901  * poly where that value is the index of the last entry in the
00902  * connectivity of the corresponding poly.  The ID
00903  * list for polygons contains global node IDs.  The ID list for polyhedra
00904  * contains the global IDs of faces (either polygons or 2D fixed-connectivity
00905  * elements.)
00906  *
00907  * This function writes the index list.
00908  *
00909  * \param poly_handle  The handle returned from 
00910  *                     <code>mhdf_createPolyConnectivity</code> or
00911  *                     <code>mhdf_openPolyConnectivity</code>.
00912  * \param offset       The offset in the table at which to write.  The
00913  *                     offset is in terms of the integer values in the table,
00914  *                     not the count of polys.
00915  * \param count        The size of the integer list to write.
00916  * \param hdf_integer_type The type of the integer data in <code>id_list</code>.
00917  *                     Typically <code>H5T_NATIVE_INT</code> or
00918  *                     <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
00919  *                     The HDF class of this type object <em>must</em> be H5T_INTEGER
00920  * \param index_list   The index list for the polys.
00921  * \param status       Passed back status of API call.
00922  */
00923 void
00924 mhdf_writePolyConnIndices( hid_t poly_handle,
00925                            long offset,
00926                            long count,
00927                            hid_t hdf_integer_type,
00928                            const void* index_list,
00929                            mhdf_Status* status );
00930 void
00931 mhdf_writePolyConnIndicesWithOpt( hid_t poly_handle,
00932                            long offset,
00933                            long count,
00934                            hid_t hdf_integer_type,
00935                            const void* index_list,
00936                            hid_t write_prop,
00937                            mhdf_Status* status );
00938 
00939 /** \brief Write polygon or polyhedron connectivity data.
00940  *
00941  * Poly (polygon or polyhedron) connectivity is stored as two lists.
00942  * One list is the concatenation of the the connectivity data for
00943  * all the polys in the group.  The other contains one value per
00944  * poly where that value is the index of the last entry in the
00945  * connectivity of the corresponding poly.  The ID
00946  * list for polygons contains global node IDs.  The ID list for polyhedra
00947  * contains the global IDs of faces (either polygons or 2D fixed-connectivity
00948  * elements.)
00949  *
00950  * This function writes the connectivity/ID list.
00951  *
00952  * \param poly_handle  The handle returned from 
00953  *                     <code>mhdf_createPolyConnectivity</code> or
00954  *                     <code>mhdf_openPolyConnectivity</code>.
00955  * \param offset       The offset in the table at which to write.  The
00956  *                     offset is in terms of the integer values in the table,
00957  *                     not the count of polys.
00958  * \param count        The size of the integer list to write.
00959  * \param hdf_integer_type The type of the integer data in <code>id_list</code>.
00960  *                     Typically <code>H5T_NATIVE_INT</code> or
00961  *                     <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
00962  *                     The HDF class of this type object <em>must</em> be H5T_INTEGER
00963  * \param id_list      The count/global ID list specifying the connectivity 
00964  *                     of the polys.
00965  * \param status       Passed back status of API call.
00966  */
00967 void
00968 mhdf_writePolyConnIDs( hid_t poly_handle,
00969                        long offset,
00970                        long count,
00971                        hid_t hdf_integer_type,
00972                        const void* id_list,
00973                        mhdf_Status* status );
00974 void
00975 mhdf_writePolyConnIDsWithOpt( hid_t poly_handle,
00976                        long offset,
00977                        long count,
00978                        hid_t hdf_integer_type,
00979                        const void* id_list,
00980                        hid_t write_prop,
00981                        mhdf_Status* status );
00982 
00983 /** \brief Read polygon or polyhedron index data.
00984  *
00985  * Poly (polygon or polyhedron) connectivity is stored as two lists.
00986  * One list is the concatenation of the the connectivity data for
00987  * all the polys in the group.  The other contains one value per
00988  * poly where that value is the index of the last entry in the
00989  * connectivity of the corresponding poly.  The ID
00990  * list for polygons contains global node IDs.  The ID list for polyhedra
00991  * contains the global IDs of faces (either polygons or 2D fixed-connectivity
00992  * elements.)
00993  *
00994  * \param poly_handle  The handle returned from 
00995  *                     <code>mhdf_createPolyConnectivity</code> or
00996  *                     <code>mhdf_openPolyConnectivity</code>.
00997  * \param offset       The offset in the table at which to read.  The
00998  *                     offset is in terms of the integer values in the table,
00999  *                     not the count of polys.
01000  * \param count        The size of the integer list to read.
01001  * \param hdf_integer_type The type of the integer data as written into memory.
01002  *                     Typically <code>H5T_NATIVE_INT</code> or
01003  *                     <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
01004  *                     The HDF class of this type object <em>must</em> be H5T_INTEGER
01005  * \param index_list   The memory location at which to write the indices.
01006  * \param status       Passed back status of API call.
01007  */
01008 void 
01009 mhdf_readPolyConnIndices( hid_t poly_handle,
01010                           long offset,
01011                           long count,
01012                           hid_t hdf_integer_type,
01013                           void* index_list,
01014                           mhdf_Status* status );
01015 void 
01016 mhdf_readPolyConnIndicesWithOpt( hid_t poly_handle,
01017                           long offset,
01018                           long count,
01019                           hid_t hdf_integer_type,
01020                           void* index_list,
01021                           hid_t read_prop,
01022                           mhdf_Status* status );
01023 
01024 /** \brief Read polygon or polyhedron connectivity data.
01025  *
01026  * Poly (polygon or polyhedron) connectivity is stored as two lists.
01027  * One list is the concatenation of the the connectivity data for
01028  * all the polys in the group.  The other contains one value per
01029  * poly where that value is the index of the last entry in the
01030  * connectivity of the corresponding poly.  The ID
01031  * list for polygons contains global node IDs.  The ID list for polyhedra
01032  * contains the global IDs of faces (either polygons or 2D fixed-connectivity
01033  * elements.)
01034  *
01035  * \param poly_handle  The handle returned from 
01036  *                     <code>mhdf_createPolyConnectivity</code> or
01037  *                     <code>mhdf_openPolyConnectivity</code>.
01038  * \param offset       The offset in the table at which to read.  The
01039  *                     offset is in terms of the integer values in the table,
01040  *                     not the count of polys.
01041  * \param count        The size of the integer list to read.
01042  * \param hdf_integer_type The type of the integer data as written into memory.
01043  *                     Typically <code>H5T_NATIVE_INT</code> or
01044  *                     <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
01045  *                     The HDF class of this type object <em>must</em> be H5T_INTEGER
01046  * \param id_list      The memory location at which to write the connectivity data.
01047  * \param status       Passed back status of API call.
01048  */
01049 void 
01050 mhdf_readPolyConnIDs( hid_t poly_handle,
01051                       long offset,
01052                       long count,
01053                       hid_t hdf_integer_type,
01054                       void* id_list,
01055                       mhdf_Status* status );
01056 void 
01057 mhdf_readPolyConnIDsWithOpt( hid_t poly_handle,
01058                       long offset,
01059                       long count,
01060                       hid_t hdf_integer_type,
01061                       void* id_list,
01062                       hid_t read_prop,
01063                       mhdf_Status* status );
01064 /*@}*/
01065 /**
01066  *\defgroup mhdf_adj Adjacency data.
01067  *
01068  * Adjacency data is formated as a sequence of integer groups where
01069  * the first entry in each group is the ID of the element for which
01070  * adjacencies are being specified, the second value is the count of
01071  * adjacent entities, and the remainder of the group is the list of
01072  * IDs of the adjacent entities.
01073  */
01074 /*@{*/
01075                      
01076 
01077 /** \brief Create adjacency data table for nodes, elements, polys, etc. 
01078  * 
01079  * Create file object for adjacency data for a nodes or a specified
01080  * element group.
01081  *
01082  * Adjacency data is formated as a sequence of integer groups where
01083  * the first entry in each group is the ID of the element for which
01084  * adjacencies are being specified, the second value is the count of
01085  * adjacent entities, and the remainder of the group is the list of
01086  * IDs of the adjacent entities.
01087  *
01088  * \param file_handle The file.
01089  * \param elem_handle The element group (or the result of
01090  *                    <code>mhdf_node_type_handle</code> for nodes) for
01091  *                    which the adjacency data is to be specified.
01092  * \param adj_list_size The total number of integer values contained
01093  *                    in the adjacency data for the specified element group.
01094  * \param status       Passed back status of API call.
01095  * \return The HDF5 handle to the connectivity data.
01096  */
01097 hid_t
01098 mhdf_createAdjacency( mhdf_FileHandle file_handle,
01099                       const char* elem_handle,
01100                       long adj_list_size,
01101                       mhdf_Status* status );
01102 
01103 /** \brief Check if adjacency data is present in the file for the specified
01104  *  element group.
01105  *
01106  * \param file         The file.
01107  * \param elem_handle  A handle to an element group.  
01108  * \param status       Passed back status of API call.
01109  */
01110 int
01111 mhdf_haveAdjacency( mhdf_FileHandle file,
01112                     const char* elem_handle,
01113                     mhdf_Status* status );
01114 
01115 /** \brief Open adjacency data table for nodes, elements, polys, etc. 
01116  * 
01117  * Open the file object containing adjacency data for a nodes or a specified
01118  * element group.
01119  *
01120  * Adjacency data is formated as a sequence of integer groups where
01121  * the first entry in each group is the ID of the element for which
01122  * adjacencies are being specified, the second value is the count of
01123  * adjacent entities, and the remainder of the group is the list of
01124  * IDs of the adjacent entities.
01125  *
01126  * \param file_handle The file.
01127  * \param elem_handle The element group (or the result of
01128  *                    <code>mhdf_node_type_handle</code> for nodes) for
01129  *                    which the adjacency data is to be specified.
01130  * \param adj_list_size The total number of integer values contained
01131  *                    in the adjacency data for the specified element group.
01132  * \param status       Passed back status of API call.
01133  * \return The HDF5 handle to the connectivity data.
01134  */
01135 hid_t
01136 mhdf_openAdjacency( mhdf_FileHandle file_handle,
01137                     const char* elem_handle,
01138                     long* adj_list_size,
01139                     mhdf_Status* status );
01140 
01141 /** \brief Write node/element adjacency data
01142  *
01143  * Write adjacency data.
01144  *
01145  * Adjacency data is formated as a sequence of integer groups where
01146  * the first entry in each group is the ID of the element for which
01147  * adjacencies are being specified, the second value is the count of
01148  * adjacent entities, and the remainder of the group is the list of
01149  * IDs of the adjacent entities.
01150  *
01151  * \param data_handle  Handle returned from <code>mhdf_createAdjacency</code>
01152  *                     or <code>mhdf_openAdjacency</code>.
01153  * \param offset       List position at which to start writing.  Offset is
01154  *                     from the count if integer values written, NOT a count
01155  *                     of the number of elements for which adjacency data
01156  *                     is written.
01157  * \param count        Number of integer values to write.
01158  * \param hdf_integer_type The type of the integer data in <code>adj_list_data</code>.
01159  *                     Typically <code>H5T_NATIVE_INT</code> or
01160  *                     <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
01161  *                     The HDF class of this type object <em>must</em> be H5T_INTEGER
01162  * \param adj_list_data Adjacency data to write.
01163  * \param status       Passed back status of API call.
01164  */
01165 void
01166 mhdf_writeAdjacency( hid_t data_handle,
01167                      long offset,
01168                      long count,
01169                      hid_t hdf_integer_type,
01170                      const void* adj_list_data,
01171                      mhdf_Status* status );
01172 void
01173 mhdf_writeAdjacencyWithOpt( hid_t data_handle,
01174                      long offset,
01175                      long count,
01176                      hid_t hdf_integer_type,
01177                      const void* adj_list_data,
01178                      hid_t write_prop,
01179                      mhdf_Status* status );
01180 
01181 /** \brief Read node/element adjacency data
01182  *
01183  * Read adjacency data.
01184  *
01185  * Adjacency data is formated as a sequence of integer groups where
01186  * the first entry in each group is the ID of the element for which
01187  * adjacencies are being specified, the second value is the count of
01188  * adjacent entities, and the remainder of the group is the list of
01189  * IDs of the adjacent entities.
01190  *
01191  * \param data_handle  Handle returned from <code>mhdf_createAdjacency</code>
01192  *                     or <code>mhdf_openAdjacency</code>.
01193  * \param offset       List position at which to start reading.  Offset is
01194  *                     from the count if integer values written, NOT a count
01195  *                     of the number of elements for which adjacency data
01196  *                     is written.
01197  * \param count        Number of integer values to reading.
01198  * \param hdf_integer_type The type of the integer data in <code>adj_list_data_out</code>.
01199  *                     Typically <code>H5T_NATIVE_INT</code> or
01200  *                     <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
01201  *                     The HDF class of this type object <em>must</em> be H5T_INTEGER
01202  * \param adj_list_data_out Pointer to memory at which to write adjacency data.
01203  * \param status       Passed back status of API call.
01204  */
01205 void
01206 mhdf_readAdjacency( hid_t data_handle,
01207                     long offset,
01208                     long count,
01209                     hid_t hdf_integer_type,
01210                     void* adj_list_data_out,
01211                     mhdf_Status* status );
01212 void
01213 mhdf_readAdjacencyWithOpt( hid_t data_handle,
01214                     long offset,
01215                     long count,
01216                     hid_t hdf_integer_type,
01217                     void* adj_list_data_out,
01218                     hid_t read_prop,
01219                     mhdf_Status* status );
01220 
01221 /*@}*/
01222 
01223 /**
01224  *\defgroup mhdf_set Meshset data.
01225  *
01226  * Meshset data is divided into three groups of data.  The set-list/meta-information table,
01227  * the set contents table and the set children table.  Each is written and read independently.
01228  *
01229  * The set list table contains one row for each set.  Each row contains four values:
01230  * {content list end index, child list end index, parent list end index, and flags}.  The flags 
01231  * value is a collection of bits with
01232  * values defined in \ref mhdf_set_flag .  The all the flags except \ref mhdf_SET_RANGE_BIT are
01233  * saved properties of the mesh data and are not relevant to the actual file in any way.  The
01234  * \ref mhdf_SET_RANGE_BIT flag is a toggle for how the meshset contents (not children) are saved.
01235  * It is an internal property of the file format and should not be passed on to the mesh database.
01236  * The content list end index and child list end index are the indices of the last entry for the
01237  * set in the contents and children tables respectively.  In the case where a set has either no
01238  * children or no contents, the last index of should be the same as the last index of the previous
01239  * set in the table, or -1 for the first set in the table.  Thus the first index is always one
01240  * greater than the last index of the previous set.  If the first index, calculated as one greater
01241  * that the last index of the previous set is greater than the last index of the current set, then
01242  * there are no values in the corresponding contents or children table for that set.
01243  *
01244  * The set contents table is a vector of integer global IDs that is the concatenation of the contents
01245  * data for all of the mesh sets.  The values are stored corresponding to the order of the sets
01246  * in the set list table.  Depending on the value of \ref mhdf_SET_RANGE_BIT in the flags field of
01247  * the set list table, the contents for a specific set may be stored in one of two formats.  If the
01248  * flag is set, the contents list is a list of pairs where each pair is a starting global Id and a 
01249  * count.  For each pair, the set contains the range of global Ids beginning at the start value. 
01250  * If the \ref mhdf_SET_RANGE_BIT flag is not set, the meshset contents are a simple list of global Ids.
01251  *
01252  * The meshset child table is a vector of integer global IDs.  It is a concatenation of the child
01253  * lists for all the mesh sets, in the order the sets occur in the meshset list table.  The values
01254  * are always simple lists.  The child table may never contain ranges of IDs.
01255  */
01256 /*@{*/
01257 
01258 
01259 /**
01260  *\defgroup mhdf_set_flag Set flag bits
01261  */
01262 /*@{*/
01263 
01264 /** \brief Make entities in set aware of owning set (MOAB-specific?)*/
01265 #define mhdf_SET_OWNER_BIT 0x1  
01266 /** \brief Set cannot contain duplicates */ 
01267 #define mhdf_SET_UNIQUE_BIT 0x2  
01268 /** \brief Set order is preserved */
01269 #define mhdf_SET_ORDER_BIT 0x4  
01270 
01271 /** \brief The bit specifying set storage format.
01272  *
01273  * If this bit is set, then the contents of a set (not the children) 
01274  * is written as set of ranges, where each range is of the form
01275  * {global start id, count}.  For such a range, the set contains the
01276  * <code>count</code> entities with sequential global IDs beginning
01277  * with the specified start ID.  If this bit is not set in the set flags,
01278  * the contents of the set are stored as a simple list of global IDs.
01279  */
01280 #define mhdf_SET_RANGE_BIT 0x8
01281 
01282 /*@}*/
01283 
01284 /** \brief Create table holding list of meshsets and their properties.
01285  * 
01286  * The set table contains description of sets, but not contents or
01287  * children.  The table is a <code>n x 4</code> matrix of values.  
01288  * One row for each of <code>n</code> sets.  Each row contains the end index
01289  * for the set in the contents table, the end index for the set in the children
01290  * table, the end index for the set in the parents table, and the set flags, 
01291  * respectively. The \ref mhdf_SET_RANGE_BIT
01292  * bit in the flags specifies the format of the contents list for each set.
01293  * See a description of the \ref mhdf_SET_RANGE_BIT flag for a description
01294  * of the two possible data formats.  The index values in the first two columns
01295  * of the table are the index of the <em>last</em> value for the set in the corresponding
01296  * contents and children lists.  The first index is always one greater than the last index
01297  * for the previous set in the table.  The first index of the first set in the table is
01298  * implicitly zero.  A special value of -1 in the appropriate column should be used to 
01299  * indicate that the first set contains no contents or has no children.  For any other set,
01300  * if the last index for the set is the same as that of the previous set, it has no data
01301  * in the corresponding list. 
01302  *
01303  *\param file_handle  The file.
01304  *\param num_sets     The number of sets in the table.
01305  *\param first_set_id_out  The global ID that will be assigned to the first
01306  *                    set in the table.  All subsequent sets in the table
01307  *                    will be assigned sequential global IDs.
01308  * \param status       Passed back status of API call.
01309  *\return The handle to the set meta-data table.  
01310  */
01311 hid_t
01312 mhdf_createSetMeta( mhdf_FileHandle file_handle,
01313                     long num_sets,
01314                     long* first_set_id_out,
01315                     mhdf_Status* status );
01316 
01317 /** \brief Check if file contains any sets
01318  *
01319  *\param file               The file.
01320  *\param have_set_data_out  If non-null set to 1 if file contains table
01321  *                          of set contents, zero otherwise.
01322  *\param have_set_child_out If non-null set to 1 if file contains table
01323  *                          of set children, zero otherwise.
01324  *\param have_set_parents_out If non-null set to 1 if file contains table
01325  *                          of set parents, zero otherwise.
01326  * \param status       Passed back status of API call.
01327  *\return Zero if the file does not contain any sets, one if it does.
01328  */
01329 int
01330 mhdf_haveSets( mhdf_FileHandle file,
01331                int* have_set_data_out,
01332                int* have_set_child_out,
01333                int* have_set_parents_out,
01334                mhdf_Status* status );
01335 
01336 /** \brief Open table holding list of meshsets and their properties.
01337  * 
01338  * Open set list.  
01339  * See \ref mhdf_createSetMeta or \ref mhdf_set for a description of this data.
01340  *
01341  *\param file_handle  The file.
01342  *\param num_sets_out The number of sets in the table.
01343  *\param first_set_id_out  The global ID that will of the first
01344  *                    set in the table.  All subsequent sets in the table
01345  *                    have sequential global IDs.
01346  * \param status       Passed back status of API call.
01347  *\return The handle to the set meta-data table.  
01348  */
01349 hid_t
01350 mhdf_openSetMeta( mhdf_FileHandle file_handle,
01351                   long* num_sets_out,
01352                   long* first_set_id_out,
01353                   mhdf_Status* status );
01354 
01355 hid_t
01356 mhdf_openSetMetaSimple( mhdf_FileHandle file_handle, mhdf_Status* status );
01357 
01358 /** \brief Read list of sets and meta-information about sets.
01359  *
01360  * Read set descriptions.  See \ref mhdf_createSetMeta or \ref mhdf_set 
01361  * for a description of this data.
01362  *
01363  *\param data_handle The handle returned from \ref mhdf_createSetMeta or
01364  *                   \ref mhdf_openSetMeta.
01365  *\param offset      The offset (set index) to begin reading at.
01366  *\param count       The number of rows (sets, integer triples) to read.
01367  *\param hdf_integer_type The type of the integer data in <code>set_desc_data</code>.
01368  *                   Typically <code>H5T_NATIVE_INT</code> or
01369  *                   <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
01370  *                   The HDF class of this type object <em>must</em> be H5T_INTEGER
01371  * \param status       Passed back status of API call.
01372  *\param set_desc_data The memory location at which to write the data.
01373  */
01374 void
01375 mhdf_readSetMeta( hid_t data_handle,
01376                   long offset,
01377                   long count,
01378                   hid_t hdf_integer_type,
01379                   void* set_desc_data,  
01380                   mhdf_Status* status );
01381 void
01382 mhdf_readSetMetaWithOpt( hid_t data_handle,
01383                   long offset,
01384                   long count,
01385                   hid_t hdf_integer_type,
01386                   void* set_desc_data,  
01387                   hid_t read_prop,
01388                   mhdf_Status* status );
01389 
01390 /** \brief Read only the flags portion of the set description table
01391  *
01392  * Read flags for each set from the set description table.
01393  * See \ref mhdf_createSetMeta for a description of this data.
01394  *\param data_handle The handle returned from mdhf_createSetMeta or mhdf_openSetMeta
01395  *\param offset      The offset (set index) at which to begin reading.
01396  *\param count       The number of values (number of sets) to read.
01397  *\param hdf_integer_type The integer type of the input array 'set_flag_data'.
01398  *\param set_flag_data Array of integers.
01399  *\param status      Location at which to store status of API call.
01400  */
01401 void
01402 mhdf_readSetFlags( hid_t data_handle,
01403                    long offset,
01404                    long count,
01405                    hid_t hdf_integer_type,
01406                    void* set_flag_data,
01407                    mhdf_Status* status );
01408 void
01409 mhdf_readSetFlagsWithOpt( hid_t data_handle,
01410                    long offset,
01411                    long count,
01412                    hid_t hdf_integer_type,
01413                    void* set_flag_data,
01414                    hid_t read_prop,
01415                    mhdf_Status* status );
01416 
01417 
01418 /** \brief Read only the content end indices portion of the set description table
01419  *
01420  * For each set, read the last index of that set's data in the set
01421  * contents table. 
01422  *
01423  * NOTE: This is a signed value.  Any sets w/out contents that occur
01424  *       first in the list will have an end index of -1.
01425  * 
01426  *\param data_handle The handle returned from mdhf_createSetMeta or mhdf_openSetMeta
01427  *\param offset      The offset (set index) at which to begin reading.
01428  *\param count       The number of values (number of sets) to read.
01429  *\param hdf_integer_type The integer type of the input array 'set_flag_data'.
01430  *\param end_indices_out Array of indices.
01431  *\param status      Location at which to store status of API call.
01432  */
01433 void
01434 mhdf_readSetContentEndIndices( hid_t data_handle,
01435                                long offset,
01436                                long count,
01437                                hid_t hdf_integer_type,
01438                                void* end_indices_out,
01439                                mhdf_Status* status );
01440 void
01441 mhdf_readSetContentEndIndicesWithOpt( hid_t data_handle,
01442                                long offset,
01443                                long count,
01444                                hid_t hdf_integer_type,
01445                                void* end_indices_out,
01446                                hid_t read_prop,
01447                                mhdf_Status* status );
01448 
01449 /** \brief Read only the child end indices portion of the set description table
01450  *
01451  * For each set, read the last index of that set's data in the set
01452  * children table. 
01453  *
01454  * NOTE: This is a signed value.  Any sets w/out contents that occur
01455  *       first in the list will have an end index of -1.
01456  * 
01457  *\param data_handle The handle returned from mdhf_createSetMeta or mhdf_openSetMeta
01458  *\param offset      The offset (set index) at which to begin reading.
01459  *\param count       The number of values (number of sets) to read.
01460  *\param hdf_integer_type The integer type of the input array 'set_flag_data'.
01461  *\param end_indices_out Array of indices.
01462  *\param status      Location at which to store status of API call.
01463  */
01464 void
01465 mhdf_readSetChildEndIndices( hid_t data_handle,
01466                              long offset,
01467                              long count,
01468                              hid_t hdf_integer_type,
01469                              void* end_indices_out,
01470                              mhdf_Status* status );
01471 void
01472 mhdf_readSetChildEndIndicesWithOpt( hid_t data_handle,
01473                              long offset,
01474                              long count,
01475                              hid_t hdf_integer_type,
01476                              void* end_indices_out,
01477                              hid_t read_prop,
01478                              mhdf_Status* status );
01479 
01480 /** \brief Read only the parent end indices portion of the set description table
01481  *
01482  * For each set, read the last index of that set's data in the set
01483  * parents table. 
01484  *
01485  * NOTE: This is a signed value.  Any sets w/out contents that occur
01486  *       first in the list will have an end index of -1.
01487  * 
01488  *\param data_handle The handle returned from mdhf_createSetMeta or mhdf_openSetMeta
01489  *\param offset      The offset (set index) at which to begin reading.
01490  *\param count       The number of values (number of sets) to read.
01491  *\param hdf_integer_type The integer type of the input array 'set_flag_data'.
01492  *\param end_indices_out Array of indices.
01493  *\param status      Location at which to store status of API call.
01494  */
01495 void
01496 mhdf_readSetParentEndIndices( hid_t data_handle,
01497                               long offset,
01498                               long count,
01499                               hid_t hdf_integer_type,
01500                               void* end_indices_out,
01501                               mhdf_Status* status );
01502 void
01503 mhdf_readSetParentEndIndicesWithOpt( hid_t data_handle,
01504                               long offset,
01505                               long count,
01506                               hid_t hdf_integer_type,
01507                               void* end_indices_out,
01508                               hid_t read_prop,
01509                               mhdf_Status* status );
01510 
01511 
01512 /** \brief Write list of sets and meta-information about sets.
01513  *
01514  * Write set descriptions.  See \ref mhdf_createSetMeta or \ref mhdf_set for a 
01515  * description of the data format.
01516  *
01517  *\param data_handle The handle returned from \ref mhdf_createSetMeta or
01518  *                   \ref mhdf_openSetMeta.
01519  *\param offset      The offset (set index) to begin writing at.
01520  *\param count       The number of rows (sets, integer triples) to write.
01521  *\param hdf_integer_type The type of the integer data in <code>set_desc_data</code>.
01522  *                   Typically <code>H5T_NATIVE_INT</code> or
01523  *                   <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
01524  *                   The HDF class of this type object <em>must</em> be H5T_INTEGER
01525  *\param set_desc_data The data to write.
01526  * \param status       Passed back status of API call.
01527  */
01528 void
01529 mhdf_writeSetMeta( hid_t data_handle,
01530                    long offset,
01531                    long count,
01532                    hid_t hdf_integer_type,
01533                    const void* set_desc_data,  
01534                    mhdf_Status* status );
01535 void
01536 mhdf_writeSetMetaWithOpt( hid_t data_handle,
01537                    long offset,
01538                    long count,
01539                    hid_t hdf_integer_type,
01540                    const void* set_desc_data,  
01541                    hid_t write_prop,
01542                    mhdf_Status* status );
01543 
01544 /** \brief Create file object to hold list of meshset contents. 
01545  *
01546  * Create set contents data object.
01547  * The format of this data is a vector of integer values which is the
01548  * concatenation of the contents list for all the meshsets.  The length
01549  * and format of the data for each set is stored in the set meta table.
01550  * See \ref mhdf_createSetMeta and \ref mhdf_SET_RANGE_BIT for a 
01551  * description of that data.
01552  *
01553  *\param file_handle The file.
01554  *\param data_list_size The total length (number of integer values) to
01555  *                   be written for all the sets.
01556  *\param status      Passed back status of API call.
01557  *\return A handle to the table.
01558  */
01559 hid_t
01560 mhdf_createSetData( mhdf_FileHandle file_handle,
01561                     long data_list_size,
01562                     mhdf_Status* status );
01563 
01564 /** \brief Open the file object for the meshset contents. 
01565  *
01566  * Open set contents data object.
01567  * The format of this data is a vector of integer values which is the
01568  * concatenation of the contents list for all the meshsets.  The length
01569  * and format of the data for each set is stored in the set meta table.
01570  * See \ref mhdf_createSetMeta and \ref mhdf_SET_RANGE_BIT for a 
01571  * description of that data.
01572  *
01573  *\param file_handle        The file.
01574  *\param data_list_size_out The length of the table.
01575  *\param status             Passed back status of API call.
01576  *\return                   A handle to the table.
01577  */
01578 hid_t
01579 mhdf_openSetData( mhdf_FileHandle file_handle,
01580                   long* data_list_size_out,
01581                   mhdf_Status* status );
01582 
01583 /** \brief Write set contents.
01584  *
01585  * Write data specifying entities contained in sets.
01586  * The format of this data is a vector of integer values which is the
01587  * concatenation of the contents list for all the meshsets.  The length
01588  * and format of the data for each set is stored in the set meta table.
01589  * See \ref mhdf_createSetMeta and \ref mhdf_SET_RANGE_BIT for a 
01590  * description of that data.
01591  *
01592  *\param set_handle   The handle returned from \ref mhdf_createSetData
01593  *                    or \ref mhdf_openSetData .
01594  *\param offset       The position at which to write into the integer vector.
01595  *\param count        The number of values to write into the data vector.
01596  *\param hdf_integer_type The type of the integer data in <code>set_data</code>.
01597  *                   Typically <code>H5T_NATIVE_INT</code> or
01598  *                   <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
01599  *                   The HDF class of this type object <em>must</em> be H5T_INTEGER
01600  *\param set_data    The data to write.
01601  *\param status      Passed back status of API call.
01602  */
01603 void
01604 mhdf_writeSetData( hid_t set_handle,
01605                    long offset,
01606                    long count,
01607                    hid_t hdf_integer_type,
01608                    const void* set_data,
01609                    mhdf_Status* status );
01610 void
01611 mhdf_writeSetDataWithOpt( hid_t set_handle,
01612                    long offset,
01613                    long count,
01614                    hid_t hdf_integer_type,
01615                    const void* set_data,
01616                    hid_t write_prop,
01617                    mhdf_Status* status );
01618 
01619 /** \brief Read set contents.
01620  *
01621  * Read data specifying entities contained in sets.
01622  * The format of this data is a vector of integer values which is the
01623  * concatenation of the contents list for all the meshsets.  The length
01624  * and format of the data for each set is stored in the set meta table.
01625  * See \ref mhdf_createSetMeta and \ref mhdf_SET_RANGE_BIT for a 
01626  * description of that data.
01627  *
01628  *\param set_handle   The handle returned from \ref mhdf_createSetData
01629  *                    or \ref mhdf_openSetData .
01630  *\param offset       The position at which to read from the integer vector.
01631  *\param count        The number of values to read from the data vector.
01632  *\param hdf_integer_type The type of the integer data in <code>set_data</code>.
01633  *                   Typically <code>H5T_NATIVE_INT</code> or
01634  *                   <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
01635  *                   The HDF class of this type object <em>must</em> be H5T_INTEGER
01636  *\param set_data    A pointer to memory at which to store the read data.
01637  *\param status      Passed back status of API call.
01638  */
01639 void
01640 mhdf_readSetData( hid_t set_handle,
01641                   long offset,
01642                   long count,
01643                   hid_t hdf_integer_type,
01644                   void* set_data,
01645                   mhdf_Status* status );
01646 void
01647 mhdf_readSetDataWithOpt( hid_t set_handle,
01648                   long offset,
01649                   long count,
01650                   hid_t hdf_integer_type,
01651                   void* set_data,
01652                   hid_t read_prop,
01653                   mhdf_Status* status );
01654 
01655 /** \brief Create file object for storing the set child list 
01656  *
01657  * Create a data group for the list of set children.  
01658  * The format of this data is the concatenation of the lists of
01659  * global IDs of child sets for each set.  The order of the sets and
01660  * the number of children for each set is contained in the set meta table.
01661  * (See \ref mhdf_createSetMeta ).
01662  *
01663  *\param file_handle      The file
01664  *\param child_list_size  The total length of the data (the sum of the 
01665  *                        number of children for each set.)
01666  *\param status           Passed back status of API call.
01667  *\return A handle to the data object in the file.
01668  */
01669 hid_t
01670 mhdf_createSetChildren( mhdf_FileHandle file_handle,
01671                         long child_list_size,
01672                         mhdf_Status* status );
01673 
01674 /** \brief Open the file object containing the set child list 
01675  *
01676  * Open the data group containing the list of set children.  
01677  * See \ref mhdf_createSetChildren and \ref mhdf_createSetMeta for 
01678  * a description of this data.
01679  *
01680  *\param file_handle      The file
01681  *\param child_list_size  The total length of the data (the sum of the 
01682  *                        number of children for each set.)
01683  *\param status           Passed back status of API call.
01684  *\return A handle to the data object in the file.
01685  */
01686 hid_t
01687 mhdf_openSetChildren( mhdf_FileHandle file_handle,
01688                       long* child_list_size,
01689                       mhdf_Status* status );
01690 
01691 /** \brief Create file object for storing the set parent list 
01692  *
01693  * Create a data group for the list of set parents.  
01694  * The format of this data is the concatenation of the lists of
01695  * global IDs of parent sets for each set.  The order of the sets and
01696  * the number of parents for each set is contained in the set meta table.
01697  * (See \ref mhdf_createSetMeta ).
01698  *
01699  *\param file_handle       The file
01700  *\param parent_list_size  The total length of the data (the sum of the 
01701  *                         number of parents for each set.)
01702  *\param status            Passed back status of API call.
01703  *\return A handle to the data object in the file.
01704  */
01705 hid_t
01706 mhdf_createSetParents( mhdf_FileHandle file_handle,
01707                        long parent_list_size,
01708                        mhdf_Status* status );
01709 
01710 /** \brief Open the file object containing the set parent list 
01711  *
01712  * Open the data group containing the list of set parents.  
01713  * See \ref mhdf_createSetParents and \ref mhdf_createSetMeta for 
01714  * a description of this data.
01715  *
01716  *\param file_handle       The file
01717  *\param parent_list_size  The total length of the data (the sum of the 
01718  *                         number of parents for each set.)
01719  *\param status            Passed back status of API call.
01720  *\return A handle to the data object in the file.
01721  */
01722 hid_t
01723 mhdf_openSetParents( mhdf_FileHandle file_handle,
01724                      long* parent_list_size,
01725                      mhdf_Status* status );
01726 
01727 /** \brief Write set parent/child list
01728  *
01729  * Write the list of parent or child IDs for sets.
01730  * See \ref mhdf_createSetChildren and \ref mhdf_createSetMeta for 
01731  * a description of this data.
01732  * 
01733  *\param data_handle The value returned from \ref mhdf_createSetChildren
01734  *                   or \ref mhdf_openSetChildren.
01735  *\param offset      The offset into the list of global IDs.
01736  *\param count       The number of global IDs to write.
01737  *\param hdf_integer_type The type of the integer data in <code>child_id_list</code>.
01738  *                   Typically <code>H5T_NATIVE_INT</code> or
01739  *                   <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
01740  *                   The HDF class of this type object <em>must</em> be H5T_INTEGER
01741  *\param id_list     The data to write.
01742  *\param status      Passed back status of API call.
01743  */
01744 void
01745 mhdf_writeSetParentsChildren( hid_t data_handle,
01746                               long offset,
01747                               long count,
01748                               hid_t hdf_integer_type,
01749                               const void* id_list,
01750                               mhdf_Status* status );
01751 void
01752 mhdf_writeSetParentsChildrenWithOpt( hid_t data_handle,
01753                               long offset,
01754                               long count,
01755                               hid_t hdf_integer_type,
01756                               const void* id_list,
01757                               hid_t write_prop,
01758                               mhdf_Status* status );
01759 
01760 /** \brief Read set parent/child list
01761  *
01762  * Read from the list of parent or child IDs for sets.
01763  * See \ref mhdf_createSetChildren and \ref mhdf_createSetMeta for 
01764  * a description of this data.
01765  * 
01766  *\param data_handle The value returned from \ref mhdf_createSetChildren
01767  *                   or \ref mhdf_openSetChildren.
01768  *\param offset      The offset into the list of global IDs.
01769  *\param count       The number of global IDs to read.
01770  *\param hdf_integer_type The type of the integer data in <code>child_id_list</code>.
01771  *                   Typically <code>H5T_NATIVE_INT</code> or
01772  *                   <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
01773  *                   The HDF class of this type object <em>must</em> be H5T_INTEGER
01774  *\param id_list     Pointer to memory in which to the read data.
01775  *\param status      Passed back status of API call.
01776  */
01777 void
01778 mhdf_readSetParentsChildren( hid_t data_handle,
01779                              long offset,
01780                              long count,
01781                              hid_t hdf_integer_type,
01782                              void* id_list,
01783                              mhdf_Status* status );
01784 void
01785 mhdf_readSetParentsChildrenWithOpt( hid_t data_handle,
01786                              long offset,
01787                              long count,
01788                              hid_t hdf_integer_type,
01789                              void* id_list,
01790                              hid_t read_prop,
01791                              mhdf_Status* status );
01792 
01793 /*@}*/
01794 
01795 /**
01796  *\defgroup mhdf_tag Tag data.
01797  *
01798  * The data for each tag can be stored in two places/formats:  sparse and/or
01799  * dense.  The data may be stored in both, but there should not be redundant 
01800  * values for the same entity.  
01801  *
01802  * Dense tag data is stored as multiple tables of tag values, one for each
01803  * element group.  (Note:  special \ref mhdf_ElemHandle values are available
01804  * for accessing dense tag data on nodes or meshsets via the \ref mhdf_node_type_handle
01805  * and \ref mhdf_set_type_handle functions.)  Each dense tag table should contain
01806  * the same number of entries as the element connectivity table.  The tag values 
01807  * are associated with the corresponding element in the connectivity table.
01808  *
01809  * Sparse tag data is stored as a global table pair for each tag type.  The first
01810  * if the pair of tables is a list of Global IDs.  The second is the corresponding
01811  * tag value for each entity in the ID list.
01812  */
01813 /*@{*/
01814 
01815 
01816 /**
01817  *\defgroup mhdf_tag_flag Tag type values   (MOAB-specific)
01818  */
01819 /*@{*/
01820 
01821 /** \brief Was dense tag data in mesh database */
01822 #define mhdf_DENSE_TYPE   2 
01823 /** \brief Was sparse tag data in mesh database */
01824 #define mhdf_SPARSE_TYPE  1 
01825 /** \brief Was bit-field tag data in mesh database */
01826 #define mhdf_BIT_TYPE     0 
01827 /** \brief Unused */
01828 #define mhdf_MESH_TYPE    3 
01829 
01830 /*@}*/
01831 
01832 /** \brief Make type native-endian.
01833  *
01834  * Given an atomic HDF5 data type, return the built-in type
01835  * that matches the class of the passed type and is the specified
01836  * size. 
01837  *
01838  * This function is provided to allow converting the stored tag
01839  * type in a file to the preferred type for it's representation 
01840  * in memory when reading tag values.
01841  *
01842  * This function works only for atomic types.  The returned type
01843  * will be a pre-defined HDF5 object and does not need to be
01844  * closed/released.
01845  *
01846  *\param input_type   The type to convert.
01847  *\param size         The desired size in bytes.
01848  *\param status       Passed back status of API call.
01849  *\return             The converted type.
01850  */
01851 hid_t
01852 mhdf_getNativeType( hid_t input_type,
01853                     int size,
01854                     mhdf_Status* status );
01855 
01856 /** \brief Add a tag to the file
01857  *
01858  * Add a new tag to the file.  This function must be called
01859  * to define the tag characteristics before values for the
01860  * tag can be written.
01861  *
01862  *\param file_handle    The file
01863  *\param tag_name       The tag name
01864  *\param tag_type       The tag type.
01865  *\param size           If tag_type == mhdf_BITFIELD, the number of
01866  *                      bits.  If tag_type == mhdf_OPAQUE, the size
01867  *                      of the opaque type in bytes.  Otherwise the
01868  *                      length of the array of tag_type entities associated
01869  *                      with each mesh entity, or 1 for a scalar value.
01870  *\param storage        MOAB storage type (dense, sparse, etc.)
01871  *\param default_value  Default value for tag, or NULL if none.
01872  *\param global_value   Global value for tag, or NULL if none.
01873  *\param hdf_type       If non-zero, assumed to be a user-specified type
01874  *                      for opaque data.  Ignored if tag_type is not
01875  *                      mhdf_OPAQUE.
01876  *\param hdf_base_type  Ignored if hdf_type is non-zero.  If hdf_type is
01877  *                      zero and this type is non-zero, it is used either
01878  *                      as the type or as the base type for an array type for 
01879  *                      default_value and global_value, respectively.  Typically
01880  *                      used to specify the input data type for mhdf_ENTITY_ID
01881  *                      tags.  
01882  */
01883 void
01884 mhdf_createTag( mhdf_FileHandle file_handle,
01885                 const char* tag_name,
01886                 enum mhdf_TagDataType tag_type,
01887                 int size,
01888                 int storage,
01889                 const void* default_value,
01890                 const void* global_value,
01891                 hid_t hdf_type,
01892                 hid_t mhdf_base_type,
01893                 mhdf_Status* status );
01894 
01895 /**\brief Get handle to HDF5 type object for tag data */
01896 hid_t
01897 mhdf_getTagDataType( mhdf_FileHandle file_handle, 
01898                      const char* tag_name, 
01899                      mhdf_Status* status );
01900 
01901 
01902 /** \brief Add variable-length tag to file
01903  *
01904  * Add a new tag to the file.  This function must be called
01905  * to define the tag characteristics before values for the
01906  * tag can be written.  Use this function if the tag values
01907  * are not fixed-length.
01908  *
01909  *\param file_handle    The file
01910  *\param tag_name       The tag name
01911  *\param tag_type       The tag type.
01912  *\param storage        MOAB storage type (dense, sparse, etc.)
01913  *\param default_value  Default value for tag, or NULL if none.
01914  *\param default_value_length Length of default value.
01915  *\param global_value   Global value for tag, or NULL if none.
01916  *\param global_value_length Length of global value.
01917  *\param hdf_type       If non-zero, assumed to be a user-specified type
01918  *                      for opaque data.  Ignored if tag_type is not
01919  *                      mhdf_OPAQUE.
01920  *\param hdf_base_type  Ignored if hdf_type is non-zero.  If hdf_type is
01921  *                      zero and this type is non-zero, it is used either
01922  *                      as the type or as the base type for an array type for 
01923  *                      default_value and global_value, respectively.  Typically
01924  *                      used to specify the input data type for mhdf_ENTITY_ID
01925  *                      tags.  
01926  */
01927 void
01928 mhdf_createVarLenTag( mhdf_FileHandle file_handle,
01929                       const char* tag_name,
01930                       enum mhdf_TagDataType tag_type,
01931                       int storage,
01932                       const void* default_value,
01933                       int default_value_length,
01934                       const void* global_value,
01935                       int global_value_length,
01936                       hid_t hdf_type,
01937                       hid_t hdf_base_type,
01938                       mhdf_Status* status );
01939                 
01940 
01941 /** \brief Get the number of tags in the file.
01942  *
01943  *\param file_handle   The file.
01944  *\param status        Passed back status of API call.
01945  *\return The number of tags.
01946  */
01947 int
01948 mhdf_getNumberTags( mhdf_FileHandle file_handle,
01949                     mhdf_Status* status );
01950 
01951 /** \brief Get the name for each tag defined in the file.
01952  *
01953  *\param file_handle   The file.
01954  *\param num_names_out The length of the returned array of strings.
01955  *\param status        Passed back status of API call.
01956  *\return An array of null-terminated strings.  The array
01957  *        and each string is allocated with <code>malloc</code>.
01958  *        The caller should release this memory by calling 
01959  *        <code>free</code> for each string and the array.
01960  */                 
01961 char**
01962 mhdf_getTagNames( mhdf_FileHandle file_handle,
01963                   int* num_names_out,
01964                   mhdf_Status* status );
01965 
01966 /** \brief Get the description of a specified tag.
01967  *
01968  * Get everything about a tag except the actual values.
01969  *
01970  *\param file_handle      The file.
01971  *\param tag_name         The name of the tag to retrieve the data for.
01972  *\param class_out        The TSTT class of the tag data.
01973  *\param size_out         Depends on value of class_out:
01974  *                        - mhdf_OPAQUE  - size of opaque data in bytes
01975  *                        - mhdf_BITFIELD - number of bits
01976  *                        - if data is fixed-length array, length of array
01977  *                        - if data is single value, 1
01978  *                        - if data is a variable-length array, -1
01979  *\param tstt_storage_out The value of the TSTT enum for storage (dense, sparse, etc.)
01980  *\param have_default_out Non-zero if file contains a default value for the tag. 
01981  *                        Length of default value if variable-lenth tag.
01982  *\param have_global_out  Non-zero if the file contains a global/mesh value for the tag.
01983  *\param have_sparse_out  Non-zero if the file contains a sparse data table for this tag.
01984  */
01985 void
01986 mhdf_getTagInfo( mhdf_FileHandle file_handle,
01987                  const char* tag_name,
01988                  enum mhdf_TagDataType* class_out,
01989                  int* size_out,
01990                  int* tstt_storage_out,
01991                  int* have_default_out,
01992                  int* have_global_out,
01993                  int* have_sparse_out,
01994                  mhdf_Status* status );
01995                  
01996 
01997 
01998 /** \brief Get the default and global values of the tag.
01999  *
02000  *\param file_handle      The file.
02001  *\param tag_name         The tag name.
02002  *\param output_data_type The HDF5 type for the memory into which the
02003  *                        tag data is to be written.  If zero, then 
02004  *                        the value(s) will be read as opaque data.
02005  *\param default_value    Memory location at which to write the default
02006  *                        value of the tag.
02007  *\param global_value     If the tag has a global value, the memory location
02008  *                        at which to write that value.
02009  *\param status           Passed back status of API call.
02010  */
02011 void
02012 mhdf_getTagValues( mhdf_FileHandle file_handle,
02013                    const char* tag_name,
02014                    hid_t output_data_type,
02015                    void* default_value,
02016                    void* global_value,
02017                    mhdf_Status* status );
02018 
02019 /** \brief Check if the file contains dense tag data for the specified tag and element group.
02020  *
02021  * Check if there is dense tag data for a given element type for the specified
02022  * tag.  
02023  *
02024  *\param file_handle  The file.
02025  *\param tag_name     The tag.
02026  *\param elem_group   The element group handle, or the return value of
02027  *                    \ref mhdf_node_type_handle or \ref mhdf_set_type_handle
02028  *                    for nodes or sets respectively.
02029  *\param status       Passed back status of API call.
02030  *\return Non-zero if file contains specified data.  Zero otherwise.
02031  */
02032 int
02033 mhdf_haveDenseTag( mhdf_FileHandle file_handle,
02034                    const char* tag_name,
02035                    const char* elem_group,
02036                    mhdf_Status* status );
02037 
02038 /** \brief Create an object to hold dense tag values for a given element group.
02039  *
02040  *\param file_handle  The file.
02041  *\param tag_name     The tag.
02042  *\param elem_group   The element group handle, or the return value of
02043  *                    \ref mhdf_node_type_handle or \ref mhdf_set_type_handle
02044  *                    for nodes or sets respectively.
02045  *\param num_values   The number of tag values to be written.  Must be
02046  *                    The same as the number of elements in the group. 
02047  *                    Specified here to allow tag values to be written
02048  *                    before node coordinates, element connectivity or meshsets.
02049  *\param status       Passed back status of API call.
02050  *\return             Handle to data object in file.
02051  */
02052 hid_t
02053 mhdf_createDenseTagData( mhdf_FileHandle file_handle,
02054                          const char* tag_name,
02055                          const char* elem_group,
02056                          long num_values,
02057                          mhdf_Status* status );
02058 
02059 /** \brief Open the object containing dense tag values for a given element group.
02060  *
02061  *\param file_handle    The file.
02062  *\param tag_name       The tag.
02063  *\param elem_group     The element group handle, or the return value of
02064  *                      \ref mhdf_node_type_handle or \ref mhdf_set_type_handle
02065  *                      for nodes or sets respectively.
02066  *\param num_values_out The number of tag values to be written.  Must be
02067  *                      The same as the number of elements in the group. 
02068  *\param status         Passed back status of API call.
02069  *\return               Handle to data object in file.
02070  */
02071 hid_t
02072 mhdf_openDenseTagData( mhdf_FileHandle file_handle,
02073                        const char* tag_name,
02074                        const char* elem_group,
02075                        long* num_values_out,
02076                        mhdf_Status* status );
02077 
02078 /** \brief Create file objects to store sparse tag data 
02079  *
02080  * Create the file objects to store all sparse data for a given tag in.  The 
02081  * sparse data is stored in a pair of objects.  The first is a vector of
02082  * global IDs.  The second is a vector of tag values for each entity specified
02083  * in the list of global IDs.
02084  *
02085  *\param file_handle    The file.
02086  *\param tag_name       The tag.
02087  *\param num_values     The number of tag values to be written.
02088  *\param entities_and_values_out The handles to the file objects.
02089  *                      The first is the vector of global IDs.  The second
02090  *                      is the list of corresponding tag values.  
02091  *\param status         Passed back status of API call.
02092  */
02093 void
02094 mhdf_createSparseTagData( mhdf_FileHandle file_handle,
02095                           const char* tag_name,
02096                           long num_values,
02097                           hid_t entities_and_values_out[2],
02098                           mhdf_Status* status );
02099 
02100 /** \brief Create file objects to store (sparse) variable-length tag data 
02101  *
02102  * Create the file objects to store all sparse data for a given tag in.  The 
02103  * sparse data is stored in a pair of objects.  The first is a vector of
02104  * global IDs.  The second is a vector of tag values for each entity specified
02105  * in the list of global IDs.
02106  *
02107  *\param file_handle    The file.
02108  *\param tag_name       The tag.
02109  *\param num_entities   The number of entities for which tag values are to be stored
02110  *\param num_values     The total number of scalar values to be written (the
02111  *                      total number of bytes of data for all tags for opaque
02112  *                      data.)
02113  *\param entities_and_values_out The handles to the file objects.
02114  *                      The first is the vector of global IDs.  The second
02115  *                      is the list of corresponding tag values.  The third
02116  *                      is the handle to the index table.
02117  *\param status         Passed back status of API call.
02118  */
02119 void
02120 mhdf_createVarLenTagData( mhdf_FileHandle file_handle,
02121                           const char* tag_name,
02122                           long num_entities,
02123                           long num_values,
02124                           hid_t entities_and_values_out[3],
02125                           mhdf_Status* status );
02126 
02127 /** \brief Create file objects to read sparse tag data 
02128  *
02129  * Open the file objects containing all sparse data for a given tag in.  The 
02130  * sparse data is stored in a pair of objects.  The first is a vector of
02131  * global IDs.  The second is a vector of tag values for each entity specified
02132  * in the list of global IDs.  For variable-length tags, a third table
02133  * containing end offsets for each tag value is returned in the third
02134  * position of the output hid_t array (see mhdf_readSparseTagIndices.)
02135  *
02136  *\param file_handle    The file.
02137  *\param tag_name       The tag.
02138  *\param num_entity_out The number of entities for which there are tag values.
02139  *\param num_values_out The number of data values.  For fixed-length tags,
02140  *                      this is the same as num_entity_out.  For
02141  *                      variable-length tags, it is the total number of
02142  *                      values in the data table.
02143  *\param entities_and_values_out The handles to the pair of file objects.
02144  *                      The first is the vector of global IDs.  The second
02145  *                      is the list of corresponding tag values.  The third
02146  *                      is the handle to the index table, iff the tag is 
02147  *                      variable-length.  If the tag is fixed-length, this
02148  *                      value is not set.
02149  *\param status         Passed back status of API call.
02150  */
02151 void
02152 mhdf_openSparseTagData( mhdf_FileHandle file_handle,
02153                         const char* tag_name,
02154                         long* num_entity_out,
02155                         long* num_values_out,
02156                         hid_t entities_and_values_out[3],
02157                         mhdf_Status* status );
02158 
02159 /** \brief Write Global ID list for sparse tag data
02160  *
02161  *\param id_handle   The first handle passed back from either
02162  *                   \ref mhdf_createSparseTagData or 
02163  *                   \ref mhdf_openSparseTagData.
02164  *\param offset      The offset at which to begin writing.
02165  *\param count       The number of global IDs to write.
02166  *\param hdf_integer_type The type of the integer data in <code>id_list</code>.
02167  *                   Typically <code>H5T_NATIVE_INT</code> or
02168  *                   <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
02169  *                   The HDF class of this type object <em>must</em> be H5T_INTEGER
02170  *\param id_list     The list of global IDs to write.
02171  *\param status      Passed back status of API call.
02172  */
02173 void
02174 mhdf_writeSparseTagEntities( hid_t id_handle,
02175                              long offset,
02176                              long count,
02177                              hid_t hdf_integer_type,
02178                              const void* id_list,
02179                              mhdf_Status* status );
02180 void
02181 mhdf_writeSparseTagEntitiesWithOpt( hid_t id_handle,
02182                              long offset,
02183                              long count,
02184                              hid_t hdf_integer_type,
02185                              const void* id_list,
02186                              hid_t write_prop,
02187                              mhdf_Status* status );
02188 
02189 
02190 
02191 /** \brief Write tag values
02192  *
02193  *\param value_handle  The second handle passed back from either
02194  *                     \ref mhdf_createSparseTagData or 
02195  *                     \ref mhdf_openSparseTagData; or the handle
02196  *                     returned by \ref mhdf_createDenseTagData or
02197  *                     \ref mhdf_openDenseTagData.
02198  *\param offset        The offset at which to begin writing.
02199  *\param count         The number of tag values to write.
02200  *\param hdf_tag_data_type The type of the data in memory.  
02201  *                     It must be possible for the HDF library to convert
02202  *                     between this type and the type the tag data is stored
02203  *                     as.  
02204  *\param tag_data      The list of tag values to write.
02205  *\param status        Passed back status of API call.
02206  */
02207 void
02208 mhdf_writeTagValues( hid_t value_handle,
02209                      long offset,
02210                      long count,
02211                      hid_t hdf_tag_data_type,
02212                      const void* tag_data,
02213                      mhdf_Status* status );
02214 void
02215 mhdf_writeTagValuesWithOpt( hid_t value_handle,
02216                      long offset,
02217                      long count,
02218                      hid_t hdf_tag_data_type,
02219                      const void* tag_data,
02220                      hid_t write_prop,
02221                      mhdf_Status* status );
02222 
02223 /**\brief Write sparse tag end indices for variable-length tag data
02224  *
02225  * Write sparse tag end indices for variable-length tag data.
02226  * Each value in the list is the *last* index (zero-based) into the tag
02227  * data for the corresponding entity.
02228  *
02229  *\param tag_handle   handle to the data object to write to.
02230  *\param offset       The offset into the table at which to begin writting
02231  *\param count        The number of values to write.
02232  *\param hdf_integer_type  The type of the values pointed to by end_indices 
02233  *                    (must be an integer type).
02234  *\param end_indices  The values to store in the table.
02235  *\param status       Output: API result.
02236  */
02237 void 
02238 mhdf_writeSparseTagIndices( hid_t tag_handle,
02239                             long offset,
02240                             long count,
02241                             hid_t hdf_integer_type,
02242                             const void* end_indices,
02243                             mhdf_Status* status );
02244 void 
02245 mhdf_writeSparseTagIndicesWithOpt( hid_t tag_handle,
02246                             long offset,
02247                             long count,
02248                             hid_t hdf_integer_type,
02249                             const void* end_indices,
02250                             hid_t write_prop,
02251                             mhdf_Status* status );
02252 
02253 /** \brief Read Global ID list for sparse tag data
02254  *
02255  *\param id_handle  The first handle passed back from either
02256  *                  \ref mhdf_createSparseTagData or 
02257  *                  \ref mhdf_openSparseTagData.
02258  *\param offset     The offset at which to begin reading.
02259  *\param count      The number of global IDs to read.
02260  *\param hdf_integer_type The type of the integer data in <code>id_list</code>.
02261  *                   Typically <code>H5T_NATIVE_INT</code> or
02262  *                   <code>N5T_NATIVE_LONG</code> as defined in <i>H5Tpublic.h</i>.
02263  *                   The HDF class of this type object <em>must</em> be H5T_INTEGER
02264  *\param id_list     The memory location at which to store the global IDs.
02265  *\param status      Passed back status of API call.
02266  */
02267 void
02268 mhdf_readSparseTagEntities( hid_t id_handle,
02269                             long offset,
02270                             long count,
02271                             hid_t hdf_integer_type,
02272                             void* id_list,
02273                             mhdf_Status* status );
02274 void
02275 mhdf_readSparseTagEntitiesWithOpt( hid_t id_handle,
02276                             long offset,
02277                             long count,
02278                             hid_t hdf_integer_type,
02279                             void* id_list,
02280                             hid_t read_prop,
02281                             mhdf_Status* status );
02282 
02283 /** \brief Read tag values
02284  *
02285  *\param value_handle  The second handle passed back from either
02286  *                     \ref mhdf_createSparseTagData or 
02287  *                     \ref mhdf_openSparseTagData; or the handle
02288  *                     returned by \ref mhdf_createDenseTagData or
02289  *                     \ref mhdf_openDenseTagData.
02290  *\param offset     The offset at which to begin reading.
02291  *\param count      The number of tag values to read.
02292  *\param hdf_type   The type of the data in memory.  If this is specified,
02293  *                  it must be possible for the HDF library to convert
02294  *                  between this type and the type the tag data is stored
02295  *                  as.  If zero, the values will be read as opaque data.
02296  *\param memory     Memory location at which to store tag values.
02297  *\param status     Passed back status of API call.
02298  */
02299 void
02300 mhdf_readTagValues( hid_t value_handle,
02301                     long offset,
02302                     long count,
02303                     hid_t hdf_type,
02304                     void* memory,
02305                     mhdf_Status* status );
02306 void
02307 mhdf_readTagValuesWithOpt( hid_t value_handle,
02308                     long offset,
02309                     long count,
02310                     hid_t hdf_type,
02311                     void* memory,
02312                     hid_t read_prop,
02313                     mhdf_Status* status );
02314 
02315 
02316 /**\brief Read sparse tag end indices for variable-length tag data
02317  *
02318  * Read sparse tag end indices for variable-length tag data.
02319  * Each value in the list is the *last* index (zero-based) into the tag
02320  * data for the corresponding entity.
02321  *
02322  *\param tag_handle   handle to the data object to read from.
02323  *\param offset       The offset into the table at which to begin reading
02324  *\param count        The number of values to read.
02325  *\param hdf_integer_type  The type of the values pointed to by end_indices 
02326  *                    (must be an integer type).
02327  *\param end_indices  Memory in which to store the data read from the table.
02328  *\param status       Output: API result.
02329  */
02330 void 
02331 mhdf_readSparseTagIndices( hid_t tag_handle,
02332                            long offset,
02333                            long count,
02334                            hid_t hdf_integer_type,
02335                            void* end_indices,
02336                            mhdf_Status* status );
02337 void 
02338 mhdf_readSparseTagIndicesWithOpt( hid_t tag_handle,
02339                            long offset,
02340                            long count,
02341                            hid_t hdf_integer_type,
02342                            void* end_indices,
02343                            hid_t read_prop,
02344                            mhdf_Status* status );
02345 
02346 /*@}*/
02347 
02348 
02349 /*@}*/
02350 
02351 
02352 #ifdef __cplusplus
02353 } /* extern "C" */
02354 #endif
02355 
02356 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines