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.