IPP Software Navigation Tools IPP Links Communication Pan-STARRS Links

Ignore:
Timestamp:
Oct 13, 2006, 5:54:51 PM (20 years ago)
Author:
Paul Price
Message:

Adding documentation for pmConfig.h. Cleaning up pmConfig.c. Renamed readConfig to pmConfigFileRead (since it's public, it should have a pm name).

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/psModules/src/config/pmConfig.h

    r9411 r9579  
    11/** @file  pmConfig.h
    22 *
    3  *  @author PAP, IfA
     3 *  @author Paul Price, IfA
    44 *
    5  *  @version $Revision: 1.14 $ $Name: not supported by cvs2svn $
    6  *  @date $Date: 2006-10-09 20:19:25 $
     5 *  @version $Revision: 1.15 $ $Name: not supported by cvs2svn $
     6 *  @date $Date: 2006-10-14 03:54:51 $
    77 *
    88 *  Copyright 2004 Maui High Performance Computing Center, University of Hawaii
    … …  
    1212#define PM_CONFIG_H
    1313
    14 #include "pslib.h"
     14#include <pslib.h>
    1515
    16 // What recipe sources have been read so far?
     16/// Sources for recipes.
     17///
     18/// Defines what recipe sources have been read.  This allows us to read recipes from different sources as they
     19/// become available.  For example, we may not have access to the camera configuration until we have read a
     20/// FITS file.  We allow symbolic links, which means the user can specify on the command-line the name of a
     21/// recipe that's defined elsewhere, instead of typing the entire filename.  This structure is private to
     22/// psModules --- there is no need for the user to know about it.
    1723typedef enum {
    18     P_PM_RECIPE_SOURCE_NONE        = 0x00, // None yet
    19     P_PM_RECIPE_SOURCE_SITE        = 0x01, // Site configuration
    20     P_PM_RECIPE_SOURCE_CAMERA      = 0x02, // Camera configuration
    21     P_PM_RECIPE_SOURCE_CL          = 0x04, // Command-line
    22     P_PM_RECIPE_SOURCE_SYMBOLIC    = 0x14, // Symbolic link, specified on command-line
    23     P_PM_RECIPE_SOURCE_ALL         = 0xff  // All sources
     24    P_PM_RECIPE_SOURCE_NONE        = 0x00, ///< None yet
     25    P_PM_RECIPE_SOURCE_SITE        = 0x01, ///< Site configuration
     26    P_PM_RECIPE_SOURCE_CAMERA      = 0x02, ///< Camera configuration
     27    P_PM_RECIPE_SOURCE_CL          = 0x04, ///< Command-line
     28    P_PM_RECIPE_SOURCE_SYMBOLIC    = 0x14, ///< Symbolic link, specified on command-line
     29    P_PM_RECIPE_SOURCE_ALL         = 0xff  ///< All sources
    2430} p_pmRecipeSource;
    2531
    26 // Configuration information
     32/// Configuration information
     33///
     34/// This structure stores the configuration information: the site, camera and recipe configuration, the
     35/// command-line arguments, the pmFPAfiles used, and the database handle.
    2736typedef struct
    2837{
    29     psMetadata *site;                   // Site configuration
    30     psMetadata *camera;                 // Camera specification
    31     const char *cameraName;             // Camera name
    32     psMetadata *recipes;                // Recipes for processing
    33     psMetadata *arguments;              // Processed command-line arguments
    34     psMetadata *files;                  // pmFPAfiles used for analysis
    35     psDB *database;                     // Database handle
    36     int *argc;                          // Number of command-line arguments
    37     char **argv;                        // Command-line arguments (raw version)
     38    psMetadata *site;                   ///< Site configuration
     39    psMetadata *camera;                 ///< Camera specification
     40    const char *cameraName;             ///< Camera name
     41    psMetadata *recipes;                ///< Recipes for processing
     42    psMetadata *arguments;              ///< Processed command-line arguments
     43    psMetadata *files;                  ///< pmFPAfiles used for analysis
     44    psDB *database;                     ///< Database handle
     45    int *argc;                          ///< Number of command-line arguments
     46    char **argv;                        ///< Command-line arguments (raw version)
    3847    // Private members
    39     p_pmRecipeSource recipesRead;       // Which recipe sources have been read
    40     psMetadata *recipesSource;          // Where each recipe came from
     48    p_pmRecipeSource recipesRead;       ///< Which recipe sources have been read
     49    psMetadata *recipesSource;          ///< Where each recipe came from
    4150}
    4251pmConfig;
    4352
    44 pmConfig *pmConfigAlloc(int *argc,      // Number of command-line arguments
    45                         char **argv     // Command-line arguments
     53/// Allocator for pmConfig
     54pmConfig *pmConfigAlloc(int *argc,      /// Number of command-line arguments
     55                        char **argv     /// Command-line arguments
    4656                       );
    4757
    48 void pmConfigSet(const char *path); // set the configPath
     58/// Set configuration information
     59///
     60/// The search path for the configuration files is a local static variable, set by this function.
     61void pmConfigSet(const char *path ///< Search paths for configuration files; colon-delimited directories
     62                );
    4963
    50 // Free static variables
     64/// Free memory used in the configuration system
    5165void pmConfigDone(void);
    5266
    53 /** pmConfigRead
    54  *
    55  * pmConfigRead shall load the site configuration (according to the above rule
    56  * for determining the source). The camera configuration shall also be loaded if
    57  * it is specified on the command line (argc, argv); otherwise it shall be set to
    58  * NULL. The recipe shall also be loaded from the command line (if specified) or,
    59  * if the camera configuration has been loaded, from the camera configuration and
    60  * recipe specification therein (see below). In dealing with the command line
    61  * parameters, the functions shall use the appropriate functions in psLib to
    62  * retrieve and remove the relevant options from the argument list; this
    63  * simplifies assignment of the mandatory arguments, since all the optional
    64  * command line arguments are removed leaving only the mandatory arguments. The
    65  * following psLib setups shall also be performed if they are specified in the
    66  * site configuration:
    67  *
    68  */
    69 pmConfig *pmConfigRead(
    70     int *argc,
    71     char **argv);
     67/// Read configuration information from the command line.
     68///
     69/// pmConfigRead loads the site configuration (the file name is specified by "-site SITE_FILE" on the
     70/// command-line, the PS_SITE environment variable, or it is $HOME/.ipprc).  The camera configuration is
     71/// loaded if it is specified on the command line ("-camera CAMERA_FILE"). Recipes specified on the command
     72/// line ("-recipe RECIPE_NAME RECIPE_SOURCE") are also loaded.  These command-line arguments are removed from
     73/// from the command-line, to simplify parsing.  The psLib setups are also performed if specified in the site
     74/// configuration.
     75pmConfig *pmConfigRead(int *argc,       ///< Number of command-line arguments
     76                       char **argv      ///< Array of command-line arguments
     77                      );
    7278
    73 /** we need this elsewhere; make it public **/
    74 bool readConfig(
    75     psMetadata **config,                // Config to output
    76     const char *name,                   // Name of file
    77     const char *description             // Description of file
    78 );
     79/// Read a configuration file
     80///
     81/// Read a metadata configuration file into the supplied metadata.  Produce an error and return false if
     82/// there's a problem.
     83bool pmConfigFileRead(psMetadata **config, ///< Config to output
     84                      const char *name, ///< Name of file
     85                      const char *description ///< Description of file
     86                     );
    7987
    80 /** pmConfigValidateCamera
    81  *
    82  * This function, used by pmConfigCameraFromHeader, shall return true if the
    83  * FITS header matches the rule contained in the camera configuration (see
    84  * x2.2.2.3); otherwise it shall return false.
    85  *
    86  */
    87 bool pmConfigValidateCameraFormat(
    88     const psMetadata *cameraFormat,
    89     const psMetadata *header);
     88/// Validate a header against the camera format
     89///
     90/// Given a FITS header (the PHU header), check it against the RULE metadata contained within the camera
     91/// format; return true if it matches.
     92bool pmConfigValidateCameraFormat(const psMetadata *cameraFormat, ///< Camera format containing the RULE
     93                                  const psMetadata *header // FITS header for the PHU
     94                                 );
    9095
     96/// Determine the camera format (and camera if unknown) from examining the header
     97///
     98/// Given a FITS header, check it against all known cameras (unless we already know which camera, from
     99/// pmConfigRead) and all known formats for those cameras in order to identify which is appropriate.  The
     100/// first matching format is accepted; further matches produce warnings.  The accepted camera is saved in the
     101/// configuration.  The accepted format is returned.
     102psMetadata *pmConfigCameraFormatFromHeader(pmConfig *config, ///< The configuration
     103        const psMetadata *header ///< The FITS header
     104                                          );
    91105
    92 /** pmConfigCameraFromHeader
    93  *
    94  * pmConfigCameraFromHeader shall load the camera configuration based on the
    95  * contents of the FITS header, using the list of known cameras contained in the
    96  * site configuration. If more than one camera matches the FITS header, a warning
    97  * shall be generated and the first matching camera returned.
    98  *
    99  */
    100 psMetadata *pmConfigCameraFormatFromHeader(
    101     pmConfig *config,                   // The configuration
    102     const psMetadata *header           // The FITS header
    103 );
     106/// Return the camera configuration specified by name
     107///
     108/// Given a camera name, returns the camera configuration metadata.
     109psMetadata *pmConfigCameraByName(pmConfig *config, ///< The configuration
     110                                 const char *cameraName ///< The camera name header
     111                                );
    104112
    105 
    106 // find the camera given the name
    107 psMetadata *pmConfigCameraByName(
    108     pmConfig *config,                   // The configuration
    109     const char *cameraName                      // The camera name header
    110 );
    111 
    112 /** pmConfigRecipeFromCamera
    113  *
    114  * pmConfigRecipeFromCamera shall load the recipes from the list of known recipes contained in the camera
    115  * configuration.
    116  *
    117  */
    118 bool pmConfigReadRecipes(pmConfig *config // Configuration
     113/// Read recipes
     114///
     115/// Attempt to read recipes from the sources that are available but have not already been read.
     116bool pmConfigReadRecipes(pmConfig *config ///< Configuration
    119117                        );
    120118
    … …  
    126124 *
    127125 */
    128 psDB *pmConfigDB(
    129     pmConfig *config                    // Configuration
    130 );
     126/// Setup the database
     127///
     128/// Initialise the database connection using the DBSERVER, DBNAME, DBUSER, DBPASSWORD values provided in the
     129/// site configuration.  Stores the database handle in the configuration, and also returns it.
     130psDB *pmConfigDB(pmConfig *config       ///< Configuration
     131                );
    131132
    132133/** pmConfigConformHeader
    … …  
    134135 * Make the supplied header conform to the nominated camera format.
    135136 */
    136 bool pmConfigConformHeader(psMetadata *header, // Header to conform
    137                            const psMetadata *format // Camera format
     137
     138/// Make the supplied header conform to the nominated camera format.
     139///
     140/// Given a FITS header, make it conform to the RULE in the specified camera format.  This is useful for
     141/// switching between formats, or generating fake data that must be recognised by
     142/// pmConfigCameraFormatFromHeader.
     143bool pmConfigConformHeader(psMetadata *header, ///< Header to conform
     144                           const psMetadata *format ///< Camera format
    138145                          );
    139146
     147/// Read the command-line for files (or a text file containing a list of files)
     148///
     149/// Given the 'file' and 'list' arguments (e.g., "-file" and "-list"), find the arguments associated with
     150/// these words and interpret them as lists of files.  Return an array of the resulting filenames.
     151psArray *pmConfigFileSets(pmConfig *config, ///< Configuration, containing command-line arguments
     152                          const char *file, ///< CL argument specifying a filename
     153                          const char *list ///< CL argument specifying a text file with a list of filenames
     154                         );
    140155
    141 psArray *pmConfigFileSets(pmConfig *config, char *file, char *list);
    142 bool pmConfigFileSetsMD (psMetadata *metadata, pmConfig *config, char *name, char *file, char *list);
     156/// Stuff associated files from the command-line into a metadata
     157///
     158/// Calls pmConfigFileSets to parse the command line for filenames (or a list which provides filenames), and
     159/// stuffs the array of filenames into the metadata under "name".
     160bool pmConfigFileSetsMD(psMetadata *metadata, ///< Metadata into which to stuff the array
     161                        pmConfig *config, ///< Configuration (which command-line arguments)
     162                        const char *name, ///< Name for array in the metadata
     163                        const char *file, ///< CL argument specifying a filename
     164                        const char *list ///< CL argument specifying a text file with a list of filenames
     165                       );
    143166
    144167
Note: See TracChangeset for help on using the changeset viewer.