<?xml version="1.0"?>
<!DOCTYPE rdbms SYSTEM "./rdbmsDescrip.dtd" >
<rdbms dbs="calib" >
<table name="metaData" 
   comment="metadata table for LAT calibrations" version="v2r1">
  <!-- define columns -->
  <col name="ser_no" >    <!-- value of name is an ID -->
     <!-- typename attribute is required. Allowed values
          come from a fixed set, more or less subset of 
          SQL types 
       -->
    <src null="false">
       <from agent="auto_increment" />
    </src>
    <type typename="mediumint">
       <!-- The restriction element is optional.  can also indicate
            min and/or max, required enum set, or recommended enum set 
        -->
       <restriction>          
         <nonnegative />   
       </restriction>
    </type>
    <comment>This is the primary key, automatically set when a 
          row is inserted.</comment>
  </col>

  <col name="instrument" >
     <src  null="false">  <!-- i.e. this is a required field -->
       <from agent="client" />
     </src>
     <type typename="varchar" size="16">
       <restriction>
         <enum use="prefer" values="LAT EM miniTower"/>
       </restriction>
     </type>
     <comment>Instrument on which calibration occurred.  Standard
        calibration software is only guaranteed to work with
        instruments from the recommended set.
     </comment>
  </col>

  <col name="calib_type" >
     <src null="false">  <!-- i.e. this is a required field -->
       <from agent="client" />
     </src>
     <type typename="varchar" size="20">
       <restriction>
         <enum use="prefer" values=
 "TKR_DeadChan TKR_HotChan CAL_Ped CAL_MuSlope Test_Gen" />
       </restriction>
     </type>
     <comment>Calibration type.  Standard
        calibration software is only guaranteed to work with
        those on the recommended list.
     </comment>
  </col>

  <col name="flavor" >
    <src null="false">
      <default value="vanilla" />
    </src>
    <type typename="varchar" size="30">
      <restriction>
        <enum use="prefer" values="vanilla ideal" />
      </restriction>
    </type>
    <comment>Normal production calibrations will be "vanilla".
             "ideal" is commonly used for simulations
    </comment>
  </col>

  <col name="data_fmt" >
    <src null="false" >
      <from agent="client" />
    </src>
    <type typename="varchar" size="10">
      <restriction>
        <enum use="prefer" values="XML" />
      </restriction>
    </type>
    <comment>For now only XML format is supported</comment>
  </col>

  <col name="data_size" >
    <src null="true" >
      <from agent="client" />
    </src>
    <type typename="int" size="11" >
      <restriction>
        <nonnegative />
      </restriction>
    </type>
    <comment>
      Field is optional.  If supplied, must be non-negative integer
    </comment>
  </col>

  <col name="vstart" >
    <!-- combination of following attributes on <input> element
      means that client is expected to supply a value, but  
      MySQL will use NULL (which for datetime translates to current
      time) in case no value is supplied
     -->
    <src  null="true" > 
      <from agent="client" />
    </src>
    <type typename="datetime">
      <restriction>
        <interval min="1970-1-1" max="2037-12-31"/>
      </restriction>
    </type>
    <comment>Start of period for which calibration is valid</comment>
  </col>

  <col name="vend" >
    <!-- If no value is supplied, calibration is marked as being
      valid until the last possible time
     -->
    <src null="true"> 
      <default value="2037-12-31" />
    </src>
    <type typename="datetime">
      <restriction>
        <interval min="1970-1-1" max="2037-12-31"/>
      </restriction>
    </type>
    <comment>End of period for which calibration is valid</comment>
  </col>

  <col name="enter_time" >
    <!-- field is nullable in a non-standard fashion.  It never really
         contains null; however when it is left unspecified rdbms will
         fill it with current time
     -->
    <src null="true">
      <from agent="rdbms"  />         
    </src>
    <type typename="timestamp" size="14" />
    <comment>Time the row is entered into database.  Client is
      not allowed to set it
    </comment>
  </col>

  <col name="locale" >
    <!-- Should it be required rather than defaulted? -->
    <src null="false" > 
      <default value="orbit" />
    </src>
    <type typename="varchar" size="12">
      <restriction>
        <enum use="prefer" values="orbit SLAC NRL CERN" />
      </restriction>
    </type>
    <comment>Where the data was taken.  May be used "as is" or may
        be input to some procedure, such as a root macro or analysis job.
    </comment>
  </col>


  <col name="fmt_version" >
    <!-- optional; client specifies if anyone does -->
    <src null="true">
      <from agent="client"  />
    </src>
    <type typename="varchar" size="12" />
    <!-- might add restriction which is a pattern definition, e.g.
         Vnnn.Rnnn.Pnnn
     -->
    <comment>Optional place to specify what version of data format was
             used for this data set, so that consumers can decide 
             how or whether to read it
    </comment>
  </col>

  <col name="completion" >
    <src null="false" >
      <from agent="client"  />
    </src>
    <type typename="enum">
      <restriction>
        <enum use="require" values="OK INC ABORT" />
      </restriction>
    </type>
    <comment>Every calibration must be marked with one of these
      completion states.  "OK" just means the procedure completed,
      not necessarily that the results were any good.
    </comment>
  </col>      

  <col name="proc_level" >
    <src null="false" >
      <default value="TEST" />
    </src>
    <type typename="enum">
      <restriction>
        <enum use="require" values="PROD TEST DEV SUPSED" />
      </restriction>
    </type>
    <comment>
      Is this calibration to be taken seriously (i.e., PROD)? Ideally,
      only one calibration of a given calib_type, flavor, etc.,
      covering a particular instant should be PROD at a time.
    </comment>
  </col>

  <col name="prod_start" >
    <src null="true">
      <from agent="client" />
    </src>
    <type typename="datetime" >
      <restriction>
        <interval min="1970-1-1" max="2037-12-31"/>
      </restriction>
    </type>
    <comment>
      Date when this calibration was declared to be PROD (if it ever was)
    </comment>
  </col>

  <col name="prod_end" >
    <src  null="true" >
      <from agent="client" />
    </src>
    <type typename="datetime" >
      <restriction>
        <interval min="1970-1-1" max="2037-12-31"/>
      </restriction>
    </type>
    <comment>
      Date, if any, when this calibration ceased being called PROD
    </comment>
  </col>

  <col name="creator" >
    <src  null="true">
      <from agent="service" />
    </src>
    <!-- could maybe cut down size -->
    <type typename="varchar" size="255" />
    <comment> program, script or whatever adding the row is responsible 
         for filling in this field with something identifying it 
    </comment>
  </col>

  <col name="uid" >
    <src null="false" >
      <from agent="service"  />
    </src>
    <type typename="varchar" size="12" />
    <comment>Service creating the row should determine user id invoking
             it and put it in this field.
    </comment>
  </col>

  <col name="data_ident" >
    <src null="false" >
      <from agent="client" />
    </src>
    <type typename="varchar" size="255">
      <restriction>
        <file />
      </restriction>
    </type>
    <comment>Typically complete path and filename for the calibration 
     data.  May include one or more environment variables written with 
     delimiters
      $(...), e.g. a plausible data_ident might be
                  $(CALIBUTILROOT)/xml/Cal/CalMuSlope_LAT.xml

        [maybe should change to using standard unix delimiters
            ${..} ? Or does it matter, since Windows does it differently?]
    </comment>
  </col>

  <col name="input_desc" >
    <src null="true" >
      <from agent="client" />
    </src>
    <type typename="varchar" size="255" />
    <comment>Optional comments about input to calibration algorithm</comment>
  </col>

  <col name="notes" >
    <src null="true" >
      <from agent="client" />
    </src>
    <type typename="varchar" size="255" />
    <comment>Optional comments about anything at all</comment>
  </col>

  <!-- define keys, indices -->
  <primary col="ser_no" />

  <index name="typical_search"
         cols="completion instrument calib_type flavor proc_level" />

  <!-- define extra constraints -->
  <assert case="changeRow">
    <compare name="lessThan" args="vstart vend" />
  </assert>

  <assert case="changeRow">
    <or>
      <compare name="null" args="prod_start" />
      <compare name="null" args="prod_end" />
      <compare name="lessThan" args="prod_start prod_end" />
    </or>
  </assert>

<!-- Other MySQL functions and operators to consider implementing
     for use here

    IN   (an enumerated set), NOT IN

  -->

   
</table>
</rdbms>