Index: /trunk/psModules/src/camera/pmFPAfileDefine.c =================================================================== --- /trunk/psModules/src/camera/pmFPAfileDefine.c (revision 9578) +++ /trunk/psModules/src/camera/pmFPAfileDefine.c (revision 9579) @@ -266,5 +266,5 @@ return NULL; } - readConfig (&file->format, formatFile, formatName); + pmConfigFileRead(&file->format, formatFile, formatName); psFree (words); } Index: /trunk/psModules/src/config/pmConfig.c =================================================================== --- /trunk/psModules/src/config/pmConfig.c (revision 9578) +++ /trunk/psModules/src/config/pmConfig.c (revision 9579) @@ -1,8 +1,9 @@ /** @file pmConfig.h * - * @author PAP, IfA + * @author PAP (IfA) + * @author EAM (IfA) * - * @version $Revision: 1.47 $ $Name: not supported by cvs2svn $ - * @date $Date: 2006-10-13 21:15:45 $ + * @version $Revision: 1.48 $ $Name: not supported by cvs2svn $ + * @date $Date: 2006-10-14 03:54:51 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -28,5 +29,5 @@ #define PS_DEFAULT_SITE ".ipprc" // Default site config file -static psArray *configPath = NULL; +static psArray *configPath = NULL; // Search path for configuration files static void configFree(pmConfig *config) @@ -79,19 +80,9 @@ } - -/** readConfig - * - * This function attempts to open the file specified in the parameter list - * parse it into metadata, then return it as a psMetaData table. - * - */ -bool readConfig( - psMetadata **config, // Config to output - const char *name, // Name of file - const char *description) // Description of file -{ - assert(config); - assert(name && strlen(name) > 0); - assert(description && strlen(description) > 0); +bool pmConfigFileRead(psMetadata **config, const char *name, const char *description) +{ + PS_ASSERT_METADATA_NON_NULL(*config, false); + PS_ASSERT_STRING_NON_EMPTY(name, false); + PS_ASSERT_STRING_NON_EMPTY(description, false); char *realName = NULL; @@ -167,17 +158,5 @@ -/****************************************************************************** -pmConfigRead(**site, **camera, **recipe, *argc, **argv, char *recipeName) - -XXX: The log/trace command line options (as processed by psArgumentVerbosity) -must take precedence override the values set here. This must be, somehow, -coded. - -XXX: Must load camera and recipe configuration if specified in the command - line. - *****************************************************************************/ -pmConfig *pmConfigRead( - int *argc, - char **argv) +pmConfig *pmConfigRead(int *argc, char **argv) { PS_ASSERT_PTR_NON_NULL(argc, NULL); @@ -236,5 +215,5 @@ // - if (!readConfig(&config->site, siteName, "site")) { + if (!pmConfigFileRead(&config->site, siteName, "site")) { psFree(config); return NULL; @@ -289,5 +268,5 @@ } - readConfig(&config->camera, cameraFile, "camera"); + pmConfigFileRead(&config->camera, cameraFile, "camera"); psArgumentRemove(argNum, config->argc, config->argv); } @@ -387,5 +366,6 @@ continue; } - psTrace("psModules.config", 7, "Setting trace level for %s to %d\n", traceItem->name, traceItem->data.S32); + psTrace("psModules.config", 7, "Setting trace level for %s to %d\n", traceItem->name, + traceItem->data.S32); psTraceSetLevel(traceItem->name, traceItem->data.S32); } @@ -437,7 +417,5 @@ -bool pmConfigValidateCameraFormat( - const psMetadata *cameraFormat, - const psMetadata *header) +bool pmConfigValidateCameraFormat(const psMetadata *cameraFormat, const psMetadata *header) { PS_ASSERT_PTR_NON_NULL(cameraFormat, false); @@ -478,4 +456,5 @@ +// Given a camera and a header, see if any of the camera formats match the header static bool formatFromHeader(psMetadata **format, // Format to return psMetadata *camera, // Camera configuration @@ -510,5 +489,5 @@ psTrace("psModules.config", 5, "Reading camera format for %s...\n", formatsItem->name); psMetadata *testFormat = NULL; // Format to test against what we've got - if (!readConfig(&testFormat, formatsItem->data.V, formatsItem->name)) { + if (!pmConfigFileRead(&testFormat, formatsItem->data.V, formatsItem->name)) { psLogMsg(__func__, PS_LOG_WARN, "Trouble reading reading camera format %s --- ignored.\n", formatsItem->name); @@ -535,10 +514,6 @@ } -// Work out what camera we have, based on the FITS header and a set of rules specified in the IPP -// configuration; return the camera configuration and format -psMetadata *pmConfigCameraFormatFromHeader( - pmConfig *config, // The configuration - const psMetadata *header // The FITS header -) + +psMetadata *pmConfigCameraFormatFromHeader(pmConfig *config, const psMetadata *header) { PS_ASSERT_PTR_NON_NULL(config, NULL); @@ -561,5 +536,6 @@ while ((camerasItem = psMetadataGetAndIncrement(camerasIter))) { // Open the camera information - psTrace("psModules.config", 3, "Inspecting camera %s (%s)\n", camerasItem->name, camerasItem->comment); + psTrace("psModules.config", 3, "Inspecting camera %s (%s)\n", camerasItem->name, + camerasItem->comment); if (camerasItem->type != PS_DATA_STRING) { psLogMsg(__func__, PS_LOG_WARN, "Camera configuration for %s in CAMERAS is not of type STR " @@ -571,5 +547,5 @@ psMetadata *testCamera = NULL; // Camera to test against what we've got: - if (!readConfig(&testCamera, camerasItem->data.V, camerasItem->name)) { + if (!pmConfigFileRead(&testCamera, camerasItem->data.V, camerasItem->name)) { psLogMsg(__func__, PS_LOG_WARN, "Trouble reading reading camera configuration %s --- " "ignored.\n", camerasItem->name); @@ -607,11 +583,8 @@ // Return the requested camera configuration -psMetadata *pmConfigCameraByName( - pmConfig *config, // The configuration - const char *cameraName // The camera name header -) -{ - PS_ASSERT_PTR_NON_NULL(cameraName, NULL); +psMetadata *pmConfigCameraByName(pmConfig *config, const char *cameraName) +{ PS_ASSERT_PTR_NON_NULL(config, NULL); + PS_ASSERT_STRING_NON_EMPTY(cameraName, NULL); psMetadata *cameras = psMetadataLookupMetadata(NULL, config->site, "CAMERAS"); @@ -629,5 +602,5 @@ psMetadata *camera = NULL; // Camera to test against what we've got: - if (!readConfig(&camera, cameraPath, cameraName)) { + if (!pmConfigFileRead(&camera, cameraPath, cameraName)) { psLogMsg(__func__, PS_LOG_WARN, "Trouble reading reading camera configuration %s", cameraName); psFree(camera); @@ -695,5 +668,5 @@ // Read the recipe psMetadata *recipe = NULL; // Recipe from file - if (readConfig(&recipe, fileItem->data.V, "recipe")) { + if (pmConfigFileRead(&recipe, fileItem->data.V, "recipe")) { psMetadataAdd(config->recipes, PS_LIST_TAIL, fileItem->name, PS_DATA_METADATA | PS_META_REPLACE, fileItem->comment, recipe); @@ -738,6 +711,5 @@ -bool pmConfigReadRecipes(pmConfig *config - ) +bool pmConfigReadRecipes(pmConfig *config) { PS_ASSERT_PTR_NON_NULL(config, false); @@ -794,5 +766,6 @@ // Is the source a symbolic reference? - psMetadata *extant = psMetadataLookupMetadata(&mdok, config->recipes, recipeSource); // Does it exist? + psMetadata *extant = psMetadataLookupMetadata(&mdok, config->recipes, + recipeSource); // Does it exist? if (mdok && extant) { psString comment = psStringCopy("Recipe added from command line as symbolic link to "); @@ -808,5 +781,5 @@ // The source is a file psMetadata *recipe = NULL; // Recipe from file - if (readConfig(&recipe, recipeSource, "recipe")) { + if (pmConfigFileRead(&recipe, recipeSource, "recipe")) { psString comment = psStringCopy("Recipe added at command line from "); psStringAppend(&comment, "%s", recipeSource); @@ -837,15 +810,6 @@ } -/****************************************************************************** -pmConfigDB(*site) - -XXX: this should allow the option of having NO database server, if chosen by config -XXX: What should we use for the Database namespace in the call to psDBInit()? -This is currently NULL. - *****************************************************************************/ - -psDB *pmConfigDB( - pmConfig *config // Configuration -) + +psDB *pmConfigDB(pmConfig *config) { PS_ASSERT_PTR_NON_NULL(config, NULL); @@ -869,19 +833,19 @@ psString dbName = psMetadataLookupStr(&mdStatus04, config->site, "DBNAME"); psS32 dbPort = psMetadataLookupS32(&mdStatus05, config->site, "DBPORT"); - if (!mdStatus05) + if (!mdStatus05) { dbPort = 0; - if (!(mdStatus01 & mdStatus02 & mdStatus03 & mdStatus04)) { - psLogMsg(__func__, PS_LOG_WARN, "Could not determine database server name, userID, and password from site metadata.\n"); - return(NULL); - } - - return(psDBInit(dbServer, dbUsername, dbPassword, dbName, dbPort)); + } + if (!(mdStatus01 && mdStatus02 && mdStatus03 && mdStatus04)) { + psLogMsg(__func__, PS_LOG_WARN, + "Could not determine database server, name, user, and password from site metadata.\n"); + return NULL; + } + + return psDBInit(dbServer, dbUsername, dbPassword, dbName, dbPort); #endif } -bool pmConfigConformHeader(psMetadata *header, // Header to conform - const psMetadata *format // Camera format - ) +bool pmConfigConformHeader(psMetadata *header, const psMetadata *format) { PS_ASSERT_PTR_NON_NULL(header, false); @@ -907,7 +871,5 @@ } -// given the 'file' and 'list' words, 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, char *file, char *list) +psArray *pmConfigFileSets(pmConfig *config, const char *file, const char *list) { PS_ASSERT_PTR_NON_NULL(config, NULL); @@ -915,8 +877,6 @@ PS_ASSERT_INT_NONNEGATIVE(*config->argc, NULL); PS_ASSERT_PTR_NON_NULL(config->argv, NULL); - PS_ASSERT_PTR_NON_NULL(file, NULL); - PS_ASSERT_INT_POSITIVE(strlen(file), NULL); - PS_ASSERT_PTR_NON_NULL(list, NULL); - PS_ASSERT_INT_POSITIVE(strlen(list), NULL); + PS_ASSERT_STRING_NON_EMPTY(file, NULL); + PS_ASSERT_STRING_NON_EMPTY(list, NULL); int Narg; @@ -990,14 +950,12 @@ } -bool pmConfigFileSetsMD (psMetadata *metadata, pmConfig *config, char *name, char *file, char *list) +bool pmConfigFileSetsMD(psMetadata *metadata, pmConfig *config, const char *name, + const char *file, const char *list) { PS_ASSERT_PTR_NON_NULL(metadata, false); PS_ASSERT_PTR_NON_NULL(config, false); - PS_ASSERT_PTR_NON_NULL(name, false); - PS_ASSERT_INT_POSITIVE(strlen(name), false); - PS_ASSERT_PTR_NON_NULL(file, false); - PS_ASSERT_INT_POSITIVE(strlen(file), false); - PS_ASSERT_PTR_NON_NULL(list, false); - PS_ASSERT_INT_POSITIVE(strlen(list), false); + PS_ASSERT_STRING_NON_EMPTY(name, NULL); + PS_ASSERT_STRING_NON_EMPTY(file, NULL); + PS_ASSERT_STRING_NON_EMPTY(list, NULL); psErrorClear(); // pmConfigFileSets may or may not call psError, so Index: /trunk/psModules/src/config/pmConfig.h =================================================================== --- /trunk/psModules/src/config/pmConfig.h (revision 9578) +++ /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 + );