psMetadataConfig.h

Go to the documentation of this file.

/** @file  psMetadataConfig.h
 *
 *  @brief Contains metadata input/output functions.
 *
 *  This file defines functions to read and write metadata to/from an external file.
 *
 *  @ingroup Metadata
 *
 *  @author Ross Harman, MHPCC
 *  @author Robert DeSonia, MHPCC
 *
 *  @version $Revision: 1.20 $ $Name: rel12 $
 *  @date $Date: 2006/05/30 22:18:39 $
 *
 *  Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii
 */
#ifndef PS_METADATACONFIG_H
#define PS_METADATACONFIG_H

/// @addtogroup Metadata
/// @{

/** A metadata data structure used in parsing arrays.
 *
 *  Contains array information and the metadata storage location.
*/
typedef struct
{
    psArray*    nonUniqueKeyArray;     ///< non-unique key names
    psArray*    typeArray;             ///< array of user defined types
    psArray*    templateArray;         ///< array of user type templates
    psMetadata* metadata;              ///< metadata container
    char*       name;                  ///< name of key
}
p_psParseLevelInfo;

/** Allocates a p_psParseLevelInfo structure
 *
 *  @return p_psParseLevelInfo* :   new p_psParseLevelInfo struct
 */
p_psParseLevelInfo* p_psParseLevelInfoAlloc(void);

/** Print metadata item to file.
 *
 *  Metadata items may be printed to an open file descriptor based on a
 *  provided format. The format is a sprintf format statement with exactly
 *  one % formatting command. If the metadata item type is a numeric type,
 *  this formatting command must also be numeric, and the type conversion
 *  performed to the value to match the format type. If the metadata type is
 *  a string, the fromatting command must also be for a string. If the
 *  metadata type is any other data type, printing is not allowed.
 *
 * @return psMetadataItem* : Pointer metadata item.
 */
bool psMetadataItemPrint(
    FILE * fd,                         ///< Pointer to file to write metadata item.
    const char *format,                ///< Format to print metadata item.
    const psMetadataItem* item         ///< Metadata item to print.
);

/** Read metadata configuration file.
 *
 *  Loads pre-defined settings by parsing a configuration file into a psMetadata structure.
 *
 *  @return psMetadata* : Resulting metadata from read.
 */
psMetadata* psMetadataConfigParse(
    psMetadata* md,                    ///< Resulting metadata from read.
    unsigned int *nFail,               ///< Number of failed lines.
    const char *filename,              ///< Name of file to read.
    bool overwrite                     ///< Allow overwrite of duplicate specifications.
);

/** Converts a psMetadata structure (including any nested psMetadata) into a
 *  configuration file formatted string.
 *
 *  A NULL shall be returned on error.
 *  @return psString:       a Configuration File formatted string.
 */
psString psMetadataConfigFormat(
    psMetadata *md                     ///< The metadata to convert
);

/** Converts a psMetadata structure (including any nested psMetadata) into a
 *  configuration file formatted string that is written out to filename.
 *
 *  @return bool:       True if successful, otherwise false.
 */
bool psMetadataConfigWrite(
    psMetadata *md,                    ///< The metadata to convert
    const char *filename               ///< Name of file to write
);

/// @}

#endif // #ifndef PS_METADATAIO_H

---