MOAB: Mesh Oriented datABase  (version 5.3.1)
mhdf_public.h
Go to the documentation of this file.
00001 #ifndef MHDF_PUBLIC_H
00002 #define MHDF_PUBLIC_H
00003 
00004 #include <H5Tpublic.h>
00005 
00006 #ifdef __cplusplus
00007   extern "C" {
00008 #endif
00009 
00010 
00011 #define MHDF_MESSAGE_BUFFER_LEN 160
00012 
00013 /** \brief Struct used to return error status. */
00014 typedef struct struct_mhdf_Status { char message[MHDF_MESSAGE_BUFFER_LEN]; } mhdf_Status;
00015 /* another name/alias/typedef for mhdf_Status*/
00016 typedef mhdf_Status MHDF_Status;
00017 
00018 /** \brief Return 1 if passed status object indicates an error.  Zero otherwise. */
00019 int
00020 mhdf_isError( mhdf_Status const* );
00021 
00022 /** \brief Get the error message given a status object.  */
00023 const char*
00024 mhdf_message( mhdf_Status const* );
00025 
00026 /*@}*/
00027 
00028 /**
00029  *\defgroup mhdf_type Common element type names.
00030  */
00031 /*@{*/
00032 
00033 /** \brief Name to use for edge element */
00034 #define mhdf_EDGE_TYPE_NAME        "Edge"
00035 /** \brief Name to use for triangle element */
00036 #define mhdf_TRI_TYPE_NAME         "Tri"
00037 /** \brief Name to use for quadrilateral element */
00038 #define mhdf_QUAD_TYPE_NAME        "Quad"
00039 /** \brief Name to use for general polygon element */
00040 #define mhdf_POLYGON_TYPE_NAME     "Polygon"
00041 /** \brief Name to use for tetrahedral element */
00042 #define mhdf_TET_TYPE_NAME         "Tet"
00043 /** \brief Name to use for quad-based pyramid element */
00044 #define mhdf_PYRAMID_TYPE_NAME     "Pyramid"
00045 /** \brief Name to use for triangular prism element */
00046 #define mhdf_PRISM_TYPE_NAME       "Prism"
00047 /** \brief Name to use for knife element */
00048 #define mdhf_KNIFE_TYPE_NAME       "Knife"
00049 /** \brief Name to use for quad-sided hexahedral element */
00050 #define mdhf_HEX_TYPE_NAME         "Hex"
00051 /** \brief Name to use for general polyhedron specified as a arbitrary-length list of faces */
00052 #define mhdf_POLYHEDRON_TYPE_NAME  "Polyhedron"
00053 /** \brief Name to use for hexagonal-based pyramid */
00054 #define mhdf_SEPTAHEDRON_TYPE_NAME "Septahedron"
00055 
00056 /*@}*/
00057 
00058 /** \brief Enum for tag data type class
00059  *
00060  * Enumerates known types for tag data
00061  */
00062 typedef enum mhdf_TagDataType {
00063   mhdf_OPAQUE = 0, /**< Opaque/unknown type */
00064   mhdf_INTEGER,    /**< Integer type */
00065   mhdf_FLOAT,      /**< Floating point value */
00066   mhdf_BITFIELD,   /**< Bit field */
00067   mhdf_BOOLEAN,    /**< Boolean values stored as one byte each */
00068   mhdf_ENTITY_ID   /**< Global ID referencing another entity in file */
00069 } MHDF_TagDataType;
00070 
00071 /**\brief Type used when creating index tables
00072  *
00073  * The data type used by mhdf_create* functions that create tables
00074  * if indices (e.g. mhdf_createSetMeta, mhdf_createVarLenTag, etc.).
00075  */
00076 typedef long mhdf_index_t;
00077 
00078 
00079 /*@}*/
00080 
00081 /**
00082  *\defgroup mhdf_file File operations
00083  */
00084 /*@{*/
00085 
00086 /** \brief Opaque handle to an open file */
00087 typedef void* mhdf_FileHandle;
00088 /* another name/alias/typedef for mhdf_FileHandle*/
00089 typedef mhdf_FileHandle MHDF_FileHandle;
00090 
00091 
00092 /* Top level file operations */
00093 
00094 /** \brief Create a new file.
00095  *
00096  * Create a new HDF mesh file.  This handle must be closed with
00097  * <code>mhdf_closeFile</code> to avoid resource loss.
00098  *
00099  * \param filename   The path and name of the file to create
00100  * \param overwrite  If zero, will fail if the specified file
00101  *                   already exists.  If non-zero, will overwrite
00102  *                   an existing file.
00103  * \param elem_type_list The list of element types that will be stored
00104  *                   in the file.  If the element name exits as a pre-
00105  *                   defined constant (\ref mhdf_type), that constant
00106  *                   should be used.  If a constant does not exist for
00107  *                   the type, a similar naming pattern should be used
00108  *                   (accepted name for type, first character uppercase,
00109  *                   subsequent characters lowercase.)  The element type
00110  *                   index passed to \ref mhdf_addElement is then an
00111  *                   index into this list.  The array may contain
00112  *                   null entries to allow the caller some control over
00113  *                   the assigned indices without creating dummy types
00114  *                   which may confuse readers.
00115  * \param elem_type_list_len The length of <code>elem_type_list</code>.
00116  * \param id_type    Type to use when creating datasets containing file IDs
00117  * \param status     Passed back status of API call.
00118  * \return An opaque handle to the file.
00119  */
00120 mhdf_FileHandle
00121 mhdf_createFile( const char* filename,
00122                  int overwrite,
00123                  const char** elem_type_list,
00124                  size_t elem_type_list_len,
00125                  hid_t id_type,
00126                  mhdf_Status* status );
00127 
00128 /** \brief Open an existing file.
00129  *
00130  * Open an existing HDF mesh file.  This handle must be closed with
00131  * <code>mhdf_closeFile</code> to avoid resource loss.
00132  *
00133  * \param filename   The path and name of the file to open
00134  * \param writable  If non-zero, open read-write.  Otherwise read-only.
00135  * \param status     Passed back status of API call.
00136  * \param max_id     Used to pass back the maximum global ID used in the
00137  *                   file.  Provided as an indication to the caller of the
00138  *                   size of the mesh.  This parameter is optional.  NULL
00139  *                   may be passed.
00140  * \param id_type    Type to use when creating datasets containing file IDs
00141  * \return An opaque handle to the file.
00142  */
00143 mhdf_FileHandle
00144 mhdf_openFile( const char* filename,
00145                int writable,
00146                unsigned long* max_id,
00147                hid_t id_type,
00148                mhdf_Status* status );
00149 
00150 /** \brief Open an existing file with options.
00151  *
00152  * Open an existing HDF mesh file.  This handle must be closed with
00153  * <code>mhdf_closeFile</code> to avoid resource loss.  This function
00154  * allows the calling application to specify the HDF5 access property
00155  * list that is passed to the HDF5 H5Fopen API.  If this is passed as
00156  * H5P_DEFAULT, the behavior is the same as \ref mhdf_openFile .
00157  * This argument is typically used to specify a parallel context for
00158  * for writing the file in parallel.
00159  *
00160  * \param filename   The path and name of the file to open
00161  * \param writable  If non-zero, open read-write.  Otherwise read-only.
00162  * \param status     Passed back status of API call.
00163  * \param max_id     Used to pass back the maximum global ID used in the
00164  *                   file.  Provided as an indication to the caller of the
00165  *                   size of the mesh.  This parameter is optional.  NULL
00166  *                   may be passed.
00167  * \param options    The HDF5 access property list to use when opening
00168  *                   the file.  See the HDF5 documentation for H5Fopen.
00169  * \param id_type    Type to use when creating datasets containing file IDs
00170  * \return An opaque handle to the file.
00171  */
00172 mhdf_FileHandle
00173 mhdf_openFileWithOpt( const char* filename,
00174                       int writable,
00175                       unsigned long* max_id,
00176                       hid_t id_type,
00177                       hid_t options,
00178                       mhdf_Status* status );
00179 
00180 /**\brief Get number of open HDF5 objects from file */
00181 int
00182 mhdf_countOpenHandles( mhdf_FileHandle h );
00183 
00184 /** Data common to sets, nodes, and each element type */
00185 typedef struct mhdf_EntDesc {
00186   long start_id;           /**< First file ID for table of data */
00187   long count;              /**< Number of entities in table */
00188   int vals_per_ent;        /**< Connectivity length for elems, dimension for verts, unused for sets, -1 for variable length poly* data */
00189   int* dense_tag_indices;  /**< Indices into mhdf_FileDesc::tags for each tag for which dense data is present for these entities */
00190   int num_dense_tags;      /**< Length of dense_tag_indices */
00191 } MHDF_EntDesc;
00192 /** Struct describing a tag */
00193 typedef struct mhdf_TagDesc {
00194   const char* name;           /**< Tag name */
00195   enum mhdf_TagDataType type; /**< Data type */
00196   int size;                   /**< Tag size (num of data type) */
00197   int bytes;                  /**< Tag size (number of bytes) */
00198   int storage;                /**< MOAB tag type (dense or sparse) */
00199   int have_sparse;            /**< Have sparse id/data pairs in file */
00200   void* default_value;        /**< Default value, NULL if none. */
00201   int default_value_size;
00202   void* global_value;         /**< Global value, NULL if none. */
00203   int global_value_size;
00204   int* dense_elem_indices;    /**< Array of indices indicating element types for which dense
00205                                    data is stored.  -2 for sets, -1 for nodes. */
00206   int num_dense_indices;
00207 } MHDF_TagDesc;
00208 typedef struct mhdf_ElemDesc {
00209   const char* handle;       /**< String table identifier */
00210   const char* type;         /**< String type designator */
00211   int have_adj;             /**< File contains adjacency data for this element group */
00212   struct mhdf_EntDesc desc;
00213 } MHDF_ElemDesc;
00214 typedef struct mhdf_FileDesc {
00215   struct mhdf_EntDesc nodes;
00216   struct mhdf_EntDesc sets;
00217   int have_set_contents;
00218   int have_set_children;
00219   int have_set_parents;
00220   struct mhdf_ElemDesc* elems; /**< Array of element table descriptions */
00221   int num_elem_desc;
00222   struct mhdf_TagDesc* tags;   /**< Array of tag descriptions */
00223   int num_tag_desc;
00224   int * numEntSets ; /* used to be [4] */
00225   /*int num_parts; will look specifically for number of sets with PARALLEL_PARTITION tags*/
00226   /* int num_mats; will look specifically for number of sets with MATERIAL_SET tags*/
00227   /*int num_neumann; will look specifically for number of sets with NEUMANN_SET tags*/
00228   /*int num_diri; will look specifically for number of sets with DIRICHLET_SET tags*/
00229   int **defTagsEntSets; /* we may need to add geometry_dimension tags */
00230   int **defTagsVals ;
00231   size_t total_size;           /**< Size of memory block containing all struct data */
00232   unsigned char* offset;       /**< Unused, may be used by application */
00233 } MHDF_FileDesc;
00234 
00235 /** \brief Get summary of data tables contained within file.
00236  *
00237  * Returned struct, including all pointed-to data, is allocated in a
00238  * single contiguous block of memory with a size equal to 'total_size'.
00239  * Caller is responsible for freeing the returned struct FileDesc pointer
00240  * (and *only* that pointer, not pointers nexted within the struct!).
00241  * Caller may copy (e.g. MPI_BCast) entire struct as one contiguous block,
00242  * assuming all nested pointers in the copy are updated to the correct
00243  * relative offset from the beginning of the struct.
00244  */
00245 MHDF_FileDesc *
00246 mhdf_getFileSummary( mhdf_FileHandle file_handle,
00247                      hid_t file_id_type,
00248                      mhdf_Status* status, int extraSetInfo);
00249 
00250 /**\brief Fix nested pointers for copied/moved FileDesc struct
00251  *
00252  * This is a utility method to facility copying/moving/communicating
00253  * struct FileDesc instances.  The structure and all data it references
00254  * are allocated in a single contiguous block of memory of size
00255  * FileDesc::total_size.  As such, the struct can be copied with a single
00256  * memcpy, packed into a single network packet, communicated with a single
00257  * MPI call, etc.  However, the pointers contained within the struct will
00258  * not be valid in the copied instance (they will still point into the
00259  * original instance.)  Given a pointer to the copied struct and the address
00260  * of the original struct, this function will updated all contained pointers.
00261  */
00262 void
00263 mhdf_fixFileDesc( struct mhdf_FileDesc* copy_ptr, const struct mhdf_FileDesc* orig_addr );
00264 
00265 /** \brief Close the file
00266  * \param handle     The file to close.
00267  * \param status     Passed back status of API call.
00268  */
00269 void
00270 mhdf_closeFile( mhdf_FileHandle handle,
00271                 mhdf_Status* status );
00272 
00273 /**\brief Check for open handles in file
00274  **/
00275 
00276 #ifdef __cplusplus
00277 } /* extern "C" */
00278 #endif
00279 
00280 
00281 #endif /* MHDF_PUBLIC_H*/
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines