libdatrwxx [MERGE] provide recent version of master

Merge branch 'master' into 24-libdatrwxx-miniseed-format-specification

CHANGELOG

@@ -3,11 +3,16 @@ this is <CHANGELOG>
 Recent development in Seitosh (bug fixes, new features, etc)
 ------------------------------------------------------------
 
-12.07.2016 (fcc2520e9): libdatrwxx: new error message format
+12.07.2016 (fcc2520e9): libdatrwxx: - new error message format
+                                    - fix: usec field in mseed can carry sign
 
-   Let libdatrwxx output more user-friendly error messages. These messages can
-   contain more detailed and comprehensive information regarding the cause of
-   the error message and can provide hints how to handle the situation.
+  Let libdatrwxx output more user-friendly error messages. These messages can
+  contain more detailed and comprehensive information regarding the cause of
+  the error message and can provide hints how to handle the situation.
+
+  Evaluate usec field in [1001] Data Extension Blockette as a value which may
+  be negative. Introduce a consistency check to test for usec being in the
+  range specified by SEED V2.4 Manual (August 2012, page 124).
 
 06.07.2016 (4342d3a79): libdatrwxx provides new format modifiers
 

src/libs/libdatrwxx/mseed.h

@@ -33,6 +33,7 @@
  *  - 08/05/2014   V1.3   Add field for timing tolerance value
  *  - 22/07/2014   V1.4   thof: support new format modifier: estimateNframes
  *  - 05/07/2016   V1.5   thof: provide consistency check control flags
+ *  - 12/07/2016   V1.6   thof: provide usec consistency check
  * 
  * ============================================================================
  */
@@ -41,7 +42,7 @@
 #ifndef DATRW_MSEED_H_VERSION
 
 #define DATRW_MSEED_H_VERSION \
-  "DATRW_MSEED_H   V1.5"
+  "DATRW_MSEED_H   V1.6"
 
 #include<datrwxx/datread.h>
 
@@ -84,7 +85,8 @@ namespace datrw {
       ConsistencyChecks(const bool& fatal, const bool& check):
         nframes(fatal, check), 
         nsamples(fatal, check), 
-        data(fatal, check) { }
+        data(fatal, check),
+        usec(fatal, check) { }
       /*! \brief Check for consistent number of frames.
        *
        * Number of frames to be expected is provided in the header in
@@ -116,6 +118,19 @@ namespace datrw {
        * first data frame of the record.
        */
       ConsistencyCheckControl data;
+      /*! \brief Check for usec field being in specified range.
+       *
+       * On page 124 of "SEED Reference Manual, Standard for the Exchange of
+       * Earthquake Data, SEED Format Version 2.4, August, 2012" with
+       * respect to [1001] Data Extension Blockette (8 bytes):
+       *
+       * > field 4: BYTE: µsec has the data start time down to the
+       * >   microsecond. The SEED format handles down to 100µsecs. This
+       * >   field is an offset from that value. The recommended value is
+       * >   from -50 to +49µsecs. At the users option, this value may be
+       * >   from 0 to +99µsecs. 
+       */
+      ConsistencyCheckControl usec;
     }; // struct ConsistencyChecks
 
     /*----------------------------------------------------------------------*/

src/libs/libdatrwxx/mseed/imseedstream.cc

@@ -37,11 +37,12 @@
  *  - 22/07/2014   V1.6   thof: support new format modifier: estimateNframes
  *  - 05/07/2016   V1.7   thof: evaluate format modifiers to adjust
  *                        consistency checks
+ *  - 12/07/2016   V1.8   thof: provide usec consistency check
  * 
  * ============================================================================
  */
 #define DATRW_IMSEEDSTREAM_CC_VERSION \
-  "DATRW_IMSEEDSTREAM_CC   V1.7"
+  "DATRW_IMSEEDSTREAM_CC   V1.8"
 
 #include <datrwxx/util.h>
 #include <datrwxx/mseed.h>
@@ -107,6 +108,8 @@ namespace datrw {
         =!(all||(checks.find(mseed::key::nsamples)!=std::string::npos));
       Mchecks.data.fatal
         =!(all||(checks.find(mseed::key::data)!=std::string::npos));
+      Mchecks.usec.fatal
+        =!(all||(checks.find(mseed::key::usec)!=std::string::npos));
     }
 
     // note: flags have opposite meaning compared to subformat flags
@@ -120,6 +123,8 @@ namespace datrw {
         =!(all||(checks.find(mseed::key::nsamples)!=std::string::npos));
       Mchecks.data.docheck
         =!(all||(checks.find(mseed::key::data)!=std::string::npos));
+      Mchecks.usec.docheck
+        =!(all||(checks.find(mseed::key::usec)!=std::string::npos));
     }
 
     DATRW_assert_modifiers_are_recognized(subformat, 

src/libs/libdatrwxx/mseed/imseedstream_help.cc

@@ -28,11 +28,12 @@
  *
  * REVISIONS and CHANGES 
  *  - 05/07/2016   V1.0   Thomas Forbriger
+ *  - 12/07/2016   V1.1   thof: new consistency check ID "usec"
  * 
  * ============================================================================
  */
 #define DATRW_IMSEEDSTREAM_HELP_CC_VERSION \
-  "DATRW_IMSEEDSTREAM_HELP_CC   V1.0"
+  "DATRW_IMSEEDSTREAM_HELP_CC   V1.1"
 
 #include <datrwxx/mseed.h>
 #include <datrwxx/formatmodifier.h>
@@ -154,6 +155,11 @@ namespace datrw {
       mh << "is compared against the value of the reverse\n";
       mh << "integration constant as provided in the first data\n";
       mh << "frame of the record. Both must be identical.\n";
+      mh(key::usec)
+        << "The SEED Reference Manual (Version 2.4, August, 2012, page 124)\n";
+      mh << "specifies the usec field in [1001] Data Extension Blockette:\n";
+      mh << "The recommended value is from -50 to +49 usecs. At the users\n";
+      mh << "option, this value may be from 0 to +99 usecs.\n";
       mh(key::all)
         << "Select all consistency checks\n";
       os << "Consistency checks will be selected upon a substring match\n"

src/libs/libdatrwxx/mseed/mseed_keywords.cc

@@ -27,11 +27,12 @@
  *
  * REVISIONS and CHANGES 
  *  - 05/07/2016   V1.0   Thomas Forbriger
+ *  - 12/07/2016   V1.1   add usec consistency check
  * 
  * ============================================================================
  */
 #define DATRW_MSEED_KEYWORDS_CC_VERSION \
-  "DATRW_MSEED_KEYWORDS_CC   V1.0"
+  "DATRW_MSEED_KEYWORDS_CC   V1.1"
 
 #include <datrwxx/mseed_keywords.h>
 
@@ -48,6 +49,7 @@ namespace datrw {
     const char* const key::nframes="nframes";
     const char* const key::nsamples="nsamples";
     const char* const key::data="data";
+    const char* const key::usec="usec";
     const char* const key::all="all";
 
   } // namespace mseed

src/libs/libdatrwxx/mseed/mseed_keywords.h

@@ -27,6 +27,7 @@
  *
  * REVISIONS and CHANGES 
  *  - 05/07/2016   V1.0   Thomas Forbriger
+ *  - 12/07/2016   V1.1   add usec consistency check
  * 
  * ============================================================================
  */
@@ -35,7 +36,7 @@
 #ifndef DATRW_MSEED_KEYWORDS_H_VERSION
 
 #define DATRW_MSEED_KEYWORDS_H_VERSION \
-  "DATRW_MSEED_KEYWORDS_H   V1.0"
+  "DATRW_MSEED_KEYWORDS_H   V1.1"
 
 namespace datrw {
 
@@ -64,6 +65,7 @@ namespace datrw {
       extern const char* const nframes;
       extern const char* const nsamples;
       extern const char* const data;
+      extern const char* const usec;
       extern const char* const all;
       /**@}*/
 

src/libs/libdatrwxx/mseed/mseedread_mseedrecord_other.cc

@@ -29,11 +29,12 @@
  *
  * REVISIONS and CHANGES 
  *  - 23/06/2016   V1.0   Thomas Forbriger
+ *  - 12/07/2016   V1.1   thof: uniquely specify sign of correction
  * 
  * ============================================================================
  */
 #define DATRW_MSEEDREAD_MSEEDRECORD_OTHER_CC_VERSION \
-  "DATRW_MSEEDREAD_MSEEDRECORD_OTHER_CC   V1.0"
+  "DATRW_MSEEDREAD_MSEEDRECORD_OTHER_CC   V1.1"
 
 #include <datrwxx/mseedread.h>
 #include<aff/subarray.h>
@@ -77,27 +78,35 @@ namespace datrw {
         libtime::TRelativeTime corr(0,0,0,0,0,100);
         //long int tcorr=this->recordheader().tcorr;
         int tcorr=this->recordheader().tcorr;
-        if (tcorr > 0)
+        if (tcorr >= 0)
         {
           retval += (corr * tcorr);
         }
         else
         {
+          // result of multiplication of libtime::TAbsoluteTime with
+          // any value (also negative) provides a positive result;
+          // swap sign just to make things clear
+          tcorr *= -1;
           retval -= (corr * tcorr);
         }
       }
       if (this->hasblockette1001())
       {
-        const int& tcorr=this->blockette1001().iusec();
+        int tcorr=this->blockette1001().iusec();
         if (tcorr != 0)
         {
           libtime::TRelativeTime corr(0,0,0,0,0,1);
-          if (tcorr > 0)
+          if (tcorr >= 0)
           {
             retval += (corr * tcorr);
           }
           else
           {
+            // result of multiplication of libtime::TAbsoluteTime with
+            // any value (also negative) provides a positive result;
+            // swap sign just to make things clear
+            tcorr *= -1;
             retval -= (corr * tcorr);
           }
         }

src/libs/libdatrwxx/mseed/mseedread_mseedrecord_read.cc

@@ -41,11 +41,13 @@
  *                        - make correct use of new DATRW_nonfatal_assert
  *  - 11/07/2016   V1.4   thof:
  *                        - improve error messages in consistency checks
+ *  - 12/07/2016   V1.5   thof:
+ *                        - add consistency check for usec value
  * 
  * ============================================================================
  */
 #define DATRW_MSEEDREAD_MSEEDRECORD_READ_CC_VERSION \
-  "DATRW_MSEEDREAD_MSEEDRECORD_READ_CC   V1.4"
+  "DATRW_MSEEDREAD_MSEEDRECORD_READ_CC   V1.5"
 
 #include <string>
 #include <cstring>
@@ -243,6 +245,36 @@ namespace datrw {
           + std::string(key::skipcheck) + "\"\n"
           "if you like to ignore this inconsistency");
 
+        /* Check for usec field being in specified range
+         * ---------------------------------------------
+         *
+         * On page 124 of "SEED Reference Manual, Standard for the Exchange of
+         * Earthquake Data, SEED Format Version 2.4, August, 2012" with
+         * respect to [1001] Data Extension Blockette (8 bytes):
+         *
+         * > field 4: BYTE: µsec has the data start time down to the
+         * >   microsecond. The SEED format handles down to 100µsecs. This
+         * >   field is an offset from that value. The recommended value is
+         * >   from -50 to +49µsecs. At the users option, this value may be
+         * >   from 0 to +99µsecs. 
+         */
+        if (Mhasblockette1001 && Mchecks.usec.docheck)
+        {
+          DATRW_nonfatal_assert(Mdebug.inconsistencies_are_not_fatal
+                                || (!Mchecks.usec.fatal),
+                                (Mblockette1001.iusec()>=-50)
+                                && (Mblockette1001.iusec()<=99),
+            "usec-value in MiniSEED record is out of specified range\n"
+            "consistency check \"" << key::nsamples << "\" complains:\n"
+            "usec-value in [1001] Data Extension Blockette: " 
+            << DATRW_value(Mblockette1001.iusec()) << "\n"
+            "specified range SEED Reference Manual, "
+            "Version 2.4, August, 2012 (page 124):\n" 
+            "The recommended value is from -50 to +49 usecs.\n"
+            "At the users option, this value may be from 0 to +99 usecs.\n"
+            << CHintToFormatModifiers);
+        }
+
         /* Check for consistent number of samples.
          * ---------------------------------------
          *

src/libs/libdatrwxx/mseed/seedstructs.h

@@ -32,6 +32,11 @@
  *                        implementation dependent size
  *  - 09/05/2006   V1.2   introduced Steim 2 code
  *                        SteimFrame now does all that Steim1Reader did
+ *  - 12/07/2016   V1.3   thof:
+ *                        - fix [1001] Data Extension Blockette
+ *                          field 4 (usec) explicitely is signed an can be
+ *                          negative (see SEED V2.4 Manual, August 2012, page
+ *                          124)
  * 
  * ============================================================================
  */
@@ -40,7 +45,7 @@
 #ifndef DATRW_SEEDSTRUCTS_H_VERSION
 
 #define DATRW_SEEDSTRUCTS_H_VERSION \
-  "DATRW_SEEDSTRUCTS_H   V1.2"
+  "DATRW_SEEDSTRUCTS_H   V1.3"
 
 namespace datrw {
 
@@ -373,10 +378,10 @@ namespace datrw {
         void swap();
         DataRecordBlocketteHeader blocketteheader;
         unsigned char tquality;  //!< Timing quality
-        unsigned char usec;      //!< microseconds
+        char usec;      //!< microseconds
         unsigned char reserved;  //!< reserved
         unsigned char fcount;    //!< frame count
-        unsigned int iusec() const { return(this->usec); }
+        int iusec() const { return(this->usec); }
         unsigned int itquality() const { return(this->tquality); }
         unsigned int ifcount() const { return(this->fcount); }
       }; // DataExtensionBlockette