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.1.1.1 $ $Name:  $
 *  @date $Date: 2005/09/14 20:42:48 $
 *
 *  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 header.
 *
 *  Read a metadata header from file. If the file is not found, an error is
 *  reported.
 *
 *  @return psMetadata* : Pointer to resulting metadata.
 */
psMetadata* psMetadataReadHeader(
    psMetadata* output,                ///< Resulting metadata from read.
    char *extName,                     ///< File name extension string.
    psS32 extNum,                      ///< File name extension number. Starts at 1.
    char *fileName                     ///< Name of file to read.
);

/** 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

---