Add MSF_SPLITISVERSION flag to control using the splitversion value

Author: chad-earthscope

ChangeLog

@@ -1,3 +1,7 @@
+2025.297:
+  - Add MSF_SPLITISVERSION flag to control using the splitversion value as the
+  version instead the record publication version for mstl3_addmsr() and variants.
+
 2025.267: v3.1.9
   - Add mstl3_pack_ppupdate_flushidle() for packing idle streams in combination
   with the use of MSF_PPUPDATETIME during trace list additions.

fileutils.c

@@ -506,8 +506,7 @@ _ms3_readmsr_impl (MS3FileParam **ppmsfp, MS3Record **ppmsr, const char *mspath,
  *
  * @param[in] mspath File or URL to read
  *
- * @param[in] flags Flags used to control parsing, see @ref
- * control-flags
+ * @param[in] flags Flags used to control parsing, see @ref control-flags
  *
  * @param[in] verbose Controls verbosity, 0 means no diagnostic output
  *
@@ -662,7 +661,12 @@ ms3_readtracelist_timewin (MS3TraceList **ppmstl, const char *mspath, const MS3T
  * @param[in] tolerance Tolerance function pointers as ::MS3Tolerance
  * @param[in] selections Pointer to ::MS3Selections for limiting data
  * @param[in] splitversion Flag to control splitting of version/quality
- * @param[in] flags Flags to control reading, see ms3_readmsr_selection()
+ * @param[in] flags
+ * @parblock
+ *  - \c ::MSF_RECORDLIST : Build a ::MS3RecordList for each ::MS3TraceSeg
+ *  - Flags supported by msr3_parse()
+ *  - Flags supported by mstl3_addmsr()
+ * @endparblock
  * @param[in] verbose Controls verbosity, 0 means no diagnostic output
  *
  * @returns ::MS_NOERROR and populates an ::MS3TraceList struct at *ppmstl

libmseed.h

@@ -1559,6 +1559,8 @@ extern void *libmseed_memory_prealloc (void *ptr, size_t size, size_t *currentsi
 #define MSF_MAINTAINMSTL 0x0200 //!< [TraceList] Do not modify a trace list when packing
 #define MSF_PPUPDATETIME                                                                           \
   0x0400 //!< [TraceList] Store update time (as nstime_t) at ::MS3TraceSeg.prvtptr
+#define MSF_SPLITISVERSION \
+  0x0800 //!< [TraceList] Use the splitversion value as version instead of record version
 /** @} */
 
 #ifdef __cplusplus

test/test-tracelist.c

@@ -220,3 +220,31 @@ TEST (tracelist, read_ppupdatetime)
 
   mstl3_free (&mstl, 1);
 }
+
+TEST (tracelist, read_splitisversion)
+{
+  MS3TraceList *mstl = NULL;
+  MS3TraceID *id     = NULL;
+  uint32_t flags;
+  int rv;
+
+  char *path = "data/testdata-oneseries-mixedlengths-mixedorder.mseed3";
+
+  /* Set bit flag to use the value of splitversion as the version
+   * instead of the record publication version. */
+  flags = MSF_SPLITISVERSION;
+
+  rv = ms3_readtracelist (&mstl, path, NULL, 99, flags, 0);
+
+  CHECK (rv == MS_NOERROR, "ms3_readtracelist() did not return expected MS_NOERROR");
+  REQUIRE (mstl != NULL, "ms3_readtracelist() did not populate 'mstl'");
+  CHECK (mstl->numtraceids == 1, "mstl->numtraceids is not expected 1");
+
+  id = mstl->traces.next[0];
+
+  REQUIRE (id != NULL, "mstl->traces.next[0] is not populated");
+
+  CHECK (id->pubversion == 99, "id->pubversion is not expected 99");
+
+  mstl3_free (&mstl, 1);
+}

tracelist.c

@@ -285,7 +285,6 @@ _mstl3_addmsr_impl (MS3TraceList *mstl, const MS3Record *msr, MS3RecordPtr **ppr
                     int8_t splitversion, int8_t autoheal, uint32_t flags,
                     const MS3Tolerance *tolerance)
 {
-  (void)flags; /* Unused */
   MS3TraceID *id = NULL;
   MS3TraceID *previd[MSTRACEID_SKIPLIST_HEIGHT] = {NULL};
 
@@ -320,8 +319,12 @@ _mstl3_addmsr_impl (MS3TraceList *mstl, const MS3Record *msr, MS3RecordPtr **ppr
     return NULL;
   }
 
+  /* If splitversion is true and MSF_SPLITISVERSION is set in flags, use splitversion
+   * as the version, otherwise use msr->pubversion */
+  int8_t pubversion = (flags & MSF_SPLITISVERSION) ? splitversion : msr->pubversion;
+
   /* Search for matching trace ID */
-  id = mstl3_findID (mstl, msr->sid, (splitversion) ? msr->pubversion : 0, previd);
+  id = mstl3_findID (mstl, msr->sid, (splitversion) ? pubversion : 0, previd);
 
   /* If no matching ID was found create new MS3TraceID and MS3TraceSeg entries */
   if (!id)
@@ -335,7 +338,7 @@ _mstl3_addmsr_impl (MS3TraceList *mstl, const MS3Record *msr, MS3RecordPtr **ppr
 
     /* Populate MS3TraceID */
     memcpy (id->sid, msr->sid, sizeof (id->sid));
-    id->pubversion = msr->pubversion;
+    id->pubversion = pubversion;
     id->earliest = msr->starttime;
     id->latest = endtime;
     id->numsegments = 1;
@@ -627,8 +630,8 @@ _mstl3_addmsr_impl (MS3TraceList *mstl, const MS3Record *msr, MS3RecordPtr **ppr
     } /* End of searching segment list */
 
     /* Track largest publication version */
-    if (msr->pubversion > id->pubversion)
-      id->pubversion = msr->pubversion;
+    if (pubversion > id->pubversion)
+      id->pubversion = pubversion;
 
     /* Track earliest and latest times */
     if (msr->starttime < id->earliest)
@@ -707,7 +710,7 @@ _mstl3_addmsr_impl (MS3TraceList *mstl, const MS3Record *msr, MS3RecordPtr **ppr
   }
 
   return seg;
-} /* End of mstl3_addmsr_recordptr() */
+} /* End of _mstl3_addmsr_impl() */
 
 /** ************************************************************************
  * @brief Add data coverage from an ::MS3Record to a ::MS3TraceList
@@ -745,12 +748,18 @@ _mstl3_addmsr_impl (MS3TraceList *mstl, const MS3Record *msr, MS3RecordPtr **ppr
  * @param[in] msr ::MS3Record containing the data to add to list
  * @param[in] splitversion Flag to control splitting of version/quality
  * @param[in] autoheal Flag to control automatic merging of segments
- * @param[in] flags Flags to control optional functionality (unused)
+ * @param[in] flags Flags to control optional functionality
+ * @parblock
+ *  - \c ::MSF_PPUPDATETIME : Store update time (as nstime_t) at ::MS3TraceSeg.prvtptr
+ *  - \c ::MSF_SPLITISVERSION : Use \a splitversion as the version, otherwise use msr->pubversion
+ * @endparblock
  * @param[in] tolerance Tolerance function pointers as ::MS3Tolerance
  *
  * @returns a pointer to the ::MS3TraceSeg updated or NULL on error.
  *
- * \sa mstl3_addmsr_recordptr() \sa mstl3_readbuffer() \sa ms3_readtracelist()
+ * \sa mstl3_addmsr_recordptr()
+ * \sa mstl3_readbuffer()
+ * \sa ms3_readtracelist()
  *
  * \ref MessageOnError - this function logs a message on error
  ***************************************************************************/