NAME: dbphot PURPOSE: Add or update observation entries in the photometry data base. DESCRIPTION: Opens data table in the phot data base and adds observations. Normally some or all of the observations already in the database for the same RefID will be deleted. This 'cleaning', controlled by keyword, can cover all of the RefID, or all observations for the RefID matching the input set by a) object name and filter or (b) jd. Dbphot can also be used to delete entries only. CATEGORY: Photometry CALLING SEQUENCE: dbphot, refid,obj,jdobs,filstr,mag,magerr INPUTS: refid - String (up to 20 chars) which identifies an observing run. It corresponds to the value of the RefID field in the db table. All data added to or removed from the database in a call will pertain to this id, which must be a non-null string. obj - String or string array giving the object(s) names. A null string will engender a NULL value for the data base ObjName field. An object name may not exceed 20 characters in length. jdobs - JD time of observation or array of times, which is either a string of Gregorian date and time suitable for jdparse, or a double JD number. Jd values less than or equal to zero, or empty string, will engender a NULL value for the data base jd field. Note: null jd often validly applies to catalog entries. filstr - String (up to 10 chars) or string array giving the filter(s) names. mag - Array of reduced magnitudes. magerr - Array of reduced magnitude errors (one sigma). OPTIONAL INPUT PARAMETERS: KEYWORD INPUT PARAMETERS: BAD - Array of bad flags, integers, by default all zero. CLEANBYJD - Flag, if set, all previous entries in the data base with this RefID and an exact match to any of the jdobs input values will be deleted. If set, CLEANBYOBJFIL, NOCLEAN and CLEANBYREFID must be unset. CLEANBYOBJFIL - Flag, if set, all previous entries in the data base with this RefID and an exact match to any of the filter, objname and color input value combinations will be deleted. If COLOR is not specified then the match is to object, filter and the color '-'. If this keyword is set, CLEANBYJD, NOCLEAN and CLEANBYREFID must be unset. CLEANBYREFID - Flag, if set, all previous entries in the data base with this RefID will be deleted. If set, CLEANBYJD, NOCLEAN and CLEANBYOBJFIL must be unset. CLEANONLY - Flag, if set, only the removal of previous entries as depicted above will be done and the input entries will not be added. It is still necessary to specify one or more input values and all the usual restrictions will be in effect. COLOR - String, represents color against which the magnitudes were reduced (if applicable). This is a scalar applied to all values, and placed in the Color column of the data table. Normally it is of the form (filter1-filter2), like 'B-V'. If unspecified, or a null string is used, it will be defaulted to '-'. DATABASE - String, name of photometry MYSQL database, by default 'phot' If keyword TABLE specifies a database via the '.' notation, DATABASE is ignored. DECL - Scalar or array of double precision dec values in radians, or strings in sexagesimal format suitable for decparse. If not specified, or empty string, a NULL value will be used for the ra and decl columns in database. NOCLEAN - Flag, if set, no previous values will be cleaned from the db. If set, CLEANBYJD, CLEANBYOBJFIL and CLEANBYREFID must be unset. RA - Scalar or array of double precision ra values in radians, or strings in sexagesimal format suitable for raparse. If not specified, or empty string or 0.0, a NULL value will be used for the ra and decl columns in database. SILENT - Flag, if set, dbphot prints no non-error output. It is ignored if TEST set. TABLE - String, name of photometry table, by default 'data' If the string is of the form 'a.b' then a is taken to be the name of the database and b is the tablename. Note that if neither TABLE nor DATABASE is specified the photometry table is located at 'phot.data' TEST - Flag, if set, the data base will not change, but the cmds that would have been generated will be printed. It queries the db to list which existing entries would have been removed. VERBOSE - Flag, if set prints verbose debug output- in particular, what TEST prints, but does perform all the database operations. OUTPUTS: KEYWORD OUTPUT PARAMETERS: NREMOV - Set to number of previous data rows removed, or, if TEST set, would be removed. COMMON BLOCKS: SIDE EFFECTS: DBPHOT removes all existing db entries for refid, instrument, objects, filters, and jd according to the *CLEAN* flags. As many data base entries will be added as there are elements in the mag array unless CLEANONLY is specified. Specifying both CLEANONLY and NOCLEAN is a no-op but can be useful for validating an input set to DBPHOT. RESTRICTIONS: The number of elements in the mag and magerr arrays must be equal. The number of elements in the obj, jdobs, filstr, bad and RA,DECL (if specified) arrays must also be the same. However, if a scalar is specified for jdobs, filstr, obj, bad, RA or DECL, this is a legal case and the value is replicated for all entries. It is legal for RA and DECL to be unspecified, or obj to specified as a null string, however, for each observation, there must be a specified value for either obj or RA,DECL. It is legal to specify both obj and ra,decl for an observation but it is not ordinarily done. If one of ra and decl is specified for an observatory, they will be both posted as NULL. If bad is unspecified, a bad flag value of 0 is replicated for all entries. One and only one of the flags NOCLEAN, CLEANBYREFID, CLEANBYOBJFIL and CLEANBYJD must be specified. CLEANBYJD requires that all values of jdobs be non-null. CLEANBYOBJFIL requires that all values of obj and filstr be non-null. Be aware that if you are following the practice of removing all bad data from your input prior to calling DBPHOT (and thus not using BAD), you will need to call DBPHOT with /CLEANONLY if and when all your data are marked bad to make sure the previous db entries are scrubbed. This routine only works with the photometry 'data' table- the reference table is not modified or examined. PROCEDURE: MODIFICATION HISTORY: 2006/08/10, Written by Peter L. Collins, Lowell Observatory 2006/09/26, PLC, add support and keyword for INSTRUMENT field in database- phot.data. 2006/12/05, PLC, add support for RefID field in the data table, which replaces the former Rundate and Instrument fields. Also RA and DEC are available as keyword inputs. Richer set of supported formats, defaults and validity checks. 2006/12/09, PLC, test for inaccessible data base via openmysql and length checking on RefID, obj, and filstr. 2006/12/27, PLC, rationalization of data base keywords, and recoding of VERBOSE keyword. 2007/01/12, PLC, add CLEANONLY keyword. 2007/01/23, PLC, add COLOR keyword (with change to database table to add Color column). Tweak add/delete prints to reflect clean flags.