Index: trunk/psModules/src/config/pmConfig.h =================================================================== --- trunk/psModules/src/config/pmConfig.h (revision 9411) +++ trunk/psModules/src/config/pmConfig.h (revision 9579) @@ -1,8 +1,8 @@ /** @file pmConfig.h * - * @author PAP, IfA + * @author Paul Price, IfA * - * @version $Revision: 1.14 $ $Name: not supported by cvs2svn $ - * @date $Date: 2006-10-09 20:19:25 $ + * @version $Revision: 1.15 $ $Name: not supported by cvs2svn $ + * @date $Date: 2006-10-14 03:54:51 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -12,109 +12,107 @@ #define PM_CONFIG_H -#include "pslib.h" +#include -// What recipe sources have been read so far? +/// Sources for recipes. +/// +/// Defines what recipe sources have been read. This allows us to read recipes from different sources as they +/// become available. For example, we may not have access to the camera configuration until we have read a +/// FITS file. We allow symbolic links, which means the user can specify on the command-line the name of a +/// recipe that's defined elsewhere, instead of typing the entire filename. This structure is private to +/// psModules --- there is no need for the user to know about it. typedef enum { - P_PM_RECIPE_SOURCE_NONE = 0x00, // None yet - P_PM_RECIPE_SOURCE_SITE = 0x01, // Site configuration - P_PM_RECIPE_SOURCE_CAMERA = 0x02, // Camera configuration - P_PM_RECIPE_SOURCE_CL = 0x04, // Command-line - P_PM_RECIPE_SOURCE_SYMBOLIC = 0x14, // Symbolic link, specified on command-line - P_PM_RECIPE_SOURCE_ALL = 0xff // All sources + P_PM_RECIPE_SOURCE_NONE = 0x00, ///< None yet + P_PM_RECIPE_SOURCE_SITE = 0x01, ///< Site configuration + P_PM_RECIPE_SOURCE_CAMERA = 0x02, ///< Camera configuration + P_PM_RECIPE_SOURCE_CL = 0x04, ///< Command-line + P_PM_RECIPE_SOURCE_SYMBOLIC = 0x14, ///< Symbolic link, specified on command-line + P_PM_RECIPE_SOURCE_ALL = 0xff ///< All sources } p_pmRecipeSource; -// Configuration information +/// Configuration information +/// +/// This structure stores the configuration information: the site, camera and recipe configuration, the +/// command-line arguments, the pmFPAfiles used, and the database handle. typedef struct { - psMetadata *site; // Site configuration - psMetadata *camera; // Camera specification - const char *cameraName; // Camera name - psMetadata *recipes; // Recipes for processing - psMetadata *arguments; // Processed command-line arguments - psMetadata *files; // pmFPAfiles used for analysis - psDB *database; // Database handle - int *argc; // Number of command-line arguments - char **argv; // Command-line arguments (raw version) + psMetadata *site; ///< Site configuration + psMetadata *camera; ///< Camera specification + const char *cameraName; ///< Camera name + psMetadata *recipes; ///< Recipes for processing + psMetadata *arguments; ///< Processed command-line arguments + psMetadata *files; ///< pmFPAfiles used for analysis + psDB *database; ///< Database handle + int *argc; ///< Number of command-line arguments + char **argv; ///< Command-line arguments (raw version) // Private members - p_pmRecipeSource recipesRead; // Which recipe sources have been read - psMetadata *recipesSource; // Where each recipe came from + p_pmRecipeSource recipesRead; ///< Which recipe sources have been read + psMetadata *recipesSource; ///< Where each recipe came from } pmConfig; -pmConfig *pmConfigAlloc(int *argc, // Number of command-line arguments - char **argv // Command-line arguments +/// Allocator for pmConfig +pmConfig *pmConfigAlloc(int *argc, /// Number of command-line arguments + char **argv /// Command-line arguments ); -void pmConfigSet(const char *path); // set the configPath +/// Set configuration information +/// +/// The search path for the configuration files is a local static variable, set by this function. +void pmConfigSet(const char *path ///< Search paths for configuration files; colon-delimited directories + ); -// Free static variables +/// Free memory used in the configuration system void pmConfigDone(void); -/** pmConfigRead - * - * pmConfigRead shall load the site configuration (according to the above rule - * for determining the source). The camera configuration shall also be loaded if - * it is specified on the command line (argc, argv); otherwise it shall be set to - * NULL. The recipe shall also be loaded from the command line (if specified) or, - * if the camera configuration has been loaded, from the camera configuration and - * recipe specification therein (see below). In dealing with the command line - * parameters, the functions shall use the appropriate functions in psLib to - * retrieve and remove the relevant options from the argument list; this - * simplifies assignment of the mandatory arguments, since all the optional - * command line arguments are removed leaving only the mandatory arguments. The - * following psLib setups shall also be performed if they are specified in the - * site configuration: - * - */ -pmConfig *pmConfigRead( - int *argc, - char **argv); +/// Read configuration information from the command line. +/// +/// pmConfigRead loads the site configuration (the file name is specified by "-site SITE_FILE" on the +/// command-line, the PS_SITE environment variable, or it is $HOME/.ipprc). The camera configuration is +/// loaded if it is specified on the command line ("-camera CAMERA_FILE"). Recipes specified on the command +/// line ("-recipe RECIPE_NAME RECIPE_SOURCE") are also loaded. These command-line arguments are removed from +/// from the command-line, to simplify parsing. The psLib setups are also performed if specified in the site +/// configuration. +pmConfig *pmConfigRead(int *argc, ///< Number of command-line arguments + char **argv ///< Array of command-line arguments + ); -/** we need this elsewhere; make it public **/ -bool readConfig( - psMetadata **config, // Config to output - const char *name, // Name of file - const char *description // Description of file -); +/// Read a configuration file +/// +/// Read a metadata configuration file into the supplied metadata. Produce an error and return false if +/// there's a problem. +bool pmConfigFileRead(psMetadata **config, ///< Config to output + const char *name, ///< Name of file + const char *description ///< Description of file + ); -/** pmConfigValidateCamera - * - * This function, used by pmConfigCameraFromHeader, shall return true if the - * FITS header matches the rule contained in the camera configuration (see - * x2.2.2.3); otherwise it shall return false. - * - */ -bool pmConfigValidateCameraFormat( - const psMetadata *cameraFormat, - const psMetadata *header); +/// Validate a header against the camera format +/// +/// Given a FITS header (the PHU header), check it against the RULE metadata contained within the camera +/// format; return true if it matches. +bool pmConfigValidateCameraFormat(const psMetadata *cameraFormat, ///< Camera format containing the RULE + const psMetadata *header // FITS header for the PHU + ); +/// Determine the camera format (and camera if unknown) from examining the header +/// +/// Given a FITS header, check it against all known cameras (unless we already know which camera, from +/// pmConfigRead) and all known formats for those cameras in order to identify which is appropriate. The +/// first matching format is accepted; further matches produce warnings. The accepted camera is saved in the +/// configuration. The accepted format is returned. +psMetadata *pmConfigCameraFormatFromHeader(pmConfig *config, ///< The configuration + const psMetadata *header ///< The FITS header + ); -/** pmConfigCameraFromHeader - * - * pmConfigCameraFromHeader shall load the camera configuration based on the - * contents of the FITS header, using the list of known cameras contained in the - * site configuration. If more than one camera matches the FITS header, a warning - * shall be generated and the first matching camera returned. - * - */ -psMetadata *pmConfigCameraFormatFromHeader( - pmConfig *config, // The configuration - const psMetadata *header // The FITS header -); +/// Return the camera configuration specified by name +/// +/// Given a camera name, returns the camera configuration metadata. +psMetadata *pmConfigCameraByName(pmConfig *config, ///< The configuration + const char *cameraName ///< The camera name header + ); - -// find the camera given the name -psMetadata *pmConfigCameraByName( - pmConfig *config, // The configuration - const char *cameraName // The camera name header -); - -/** pmConfigRecipeFromCamera - * - * pmConfigRecipeFromCamera shall load the recipes from the list of known recipes contained in the camera - * configuration. - * - */ -bool pmConfigReadRecipes(pmConfig *config // Configuration +/// Read recipes +/// +/// Attempt to read recipes from the sources that are available but have not already been read. +bool pmConfigReadRecipes(pmConfig *config ///< Configuration ); @@ -126,7 +124,10 @@ * */ -psDB *pmConfigDB( - pmConfig *config // Configuration -); +/// Setup the database +/// +/// Initialise the database connection using the DBSERVER, DBNAME, DBUSER, DBPASSWORD values provided in the +/// site configuration. Stores the database handle in the configuration, and also returns it. +psDB *pmConfigDB(pmConfig *config ///< Configuration + ); /** pmConfigConformHeader @@ -134,11 +135,33 @@ * Make the supplied header conform to the nominated camera format. */ -bool pmConfigConformHeader(psMetadata *header, // Header to conform - const psMetadata *format // Camera format + +/// Make the supplied header conform to the nominated camera format. +/// +/// Given a FITS header, make it conform to the RULE in the specified camera format. This is useful for +/// switching between formats, or generating fake data that must be recognised by +/// pmConfigCameraFormatFromHeader. +bool pmConfigConformHeader(psMetadata *header, ///< Header to conform + const psMetadata *format ///< Camera format ); +/// Read the command-line for files (or a text file containing a list of files) +/// +/// Given the 'file' and 'list' arguments (e.g., "-file" and "-list"), find the arguments associated with +/// these words and interpret them as lists of files. Return an array of the resulting filenames. +psArray *pmConfigFileSets(pmConfig *config, ///< Configuration, containing command-line arguments + const char *file, ///< CL argument specifying a filename + const char *list ///< CL argument specifying a text file with a list of filenames + ); -psArray *pmConfigFileSets(pmConfig *config, char *file, char *list); -bool pmConfigFileSetsMD (psMetadata *metadata, pmConfig *config, char *name, char *file, char *list); +/// Stuff associated files from the command-line into a metadata +/// +/// Calls pmConfigFileSets to parse the command line for filenames (or a list which provides filenames), and +/// stuffs the array of filenames into the metadata under "name". +bool pmConfigFileSetsMD(psMetadata *metadata, ///< Metadata into which to stuff the array + pmConfig *config, ///< Configuration (which command-line arguments) + const char *name, ///< Name for array in the metadata + const char *file, ///< CL argument specifying a filename + const char *list ///< CL argument specifying a text file with a list of filenames + );