Update files according to mbgtools-lx-4.2.14.2.1

mbgctrl now supports new parameter COLDBOOT.
mbgsetsystime now really sets the Windows system time.
Requires dkwin-3.08 or newer.

11 files changed, 262 insertions, 158 deletions

diff --git a/mbgcmptime/mbgcmptime.c b/mbgcmptime/mbgcmptime.c
index 2b614d9..24483c9 100644
--- a/mbgcmptime/mbgcmptime.c
+++ b/mbgcmptime/mbgcmptime.c
@@ -1,7 +1,7 @@
 
 /**************************************************************************
  *
- *  $Id: mbgcmptime.c 1.3 2018/11/15 12:39:28Z martin REL_M $
+ *  $Id: mbgcmptime.c 1.4 2018/12/14 12:51:29Z martin REL_M $
  *
  *  Description:
  *    Main file for mbgcmptime program which compares the time on 2 devices
@@ -11,7 +11,10 @@
  *
  * -----------------------------------------------------------------------
  *  $Log: mbgcmptime.c $
- *  Revision 1.3  2018/11/15 12:39:28Z  martin
+ *  Revision 1.4  2018/12/14 12:51:29Z  martin
+ *  Fixed evaluation of device specification parameters.
+ *  Improved error handling.
+ *  Revision 1.3  2018/11/15 12:39:28  martin
  *  Individual MBG_MICRO_VERSION codes are now obsolete.
  *  Revision 1.2  2018/08/08 09:01:45  martin
  *  New option -a to compensate an initial offset automatically.
@@ -68,7 +71,7 @@ static const char *log_fn;
 
 MBG_PC_CYCLES_FREQUENCY cyc_freq;  // must not be static!
 
-static const char *ref_device_name;
+static const char *ref_dev_param;
 static MBG_DEV_HANDLE dh_ref;
 static PCPS_DEV dev_info_ref;
 
@@ -296,14 +299,15 @@ void usage( void )
 
   printf( "\nExamples:\n\n" );
   printf(
-    "Run once and compare the time from both /dev/mbgclock1 and /dev/mbgclock2\n"
-    "to the time from /dev/mbgclock0:\n\n"
-    "  %s -i /dev/mbgclock0 /dev/mbgclock1 /dev/mbgclock2\n\n", pname
+    "Run once and compare the time from the 2 devices with indexes 1 and 2\n"
+    "to the time from reference device with index 0:\n\n"
+    "  %s -i 0 1 2\n\n", pname
   );
   printf(
-    "Run continuously in 1 s intervals and compare the time from /dev/mbgclock1\n"
-    "to the time from /dev/mbgclock0:\n\n"
-    "  %s -s 1 -i /dev/mbgclock0 /dev/mbgclock1\n\n", pname
+    "Run continuously in 1 s intervals and compare the time from %s\n"
+    "to the time from reference device %s:\n\n"
+    "  %s -s 1 -i %s %s\n\n", EXAMPLE_DEV_NAME_2, EXAMPLE_DEV_NAME_1,
+    pname, EXAMPLE_DEV_NAME_1, EXAMPLE_DEV_NAME_2
   );
 
 }  // usage
@@ -312,6 +316,7 @@ void usage( void )
 
 int main( int argc, char *argv[] )
 {
+  MBG_DEV_FN ref_dev_fn;
   int rc;
   int c;
 
@@ -331,7 +336,7 @@ int main( int argc, char *argv[] )
         break;
 
       case 'i':
-        ref_device_name = optarg;
+        ref_dev_param = optarg;
         break;
 
       case 'l':
@@ -383,6 +388,13 @@ int main( int argc, char *argv[] )
     }
   }
 
+  if ( ref_dev_param == NULL )
+  {
+    // No ref device specified.
+    fprintf( stderr, "A reference device has to be specified using the -i parameter.\n\n" );
+    must_print_usage = 1;
+  }
+
   if ( must_print_usage )
   {
     usage();
@@ -402,7 +414,6 @@ int main( int argc, char *argv[] )
   if ( quiet )  // make stdout unbuffered
     setvbuf( stdout, NULL, _IONBF, 0 );
 
-
   if ( log_fn )
   {
     // Create new or truncate existing log file.
@@ -412,32 +423,38 @@ int main( int argc, char *argv[] )
       fclose( fp );
   }
 
-  if ( ref_device_name )
+  // We don't call mbg_open_device_by_param_chk() here since we
+  // want to print our own error message in case of failure.
+  rc = mbg_open_device_by_param( &dh_ref, ref_dev_param, 0,
+                                 ref_dev_fn, sizeof( ref_dev_fn ) );
+
+  if ( mbg_rc_is_error( rc ) )
   {
-    #if defined( MBG_TGT_WIN32 )
-      dh_ref = mbg_open_device_by_name( ref_device_name, MBG_MATCH_MODEL );
-    #else // if defined( MBG_TGT_POSIX )
-      dh_ref = open( ref_device_name, O_RDONLY );
-    #endif
+    fprintf( stderr, "** Failed to open ref device %s: %s.\n",
+             ref_dev_param,  mbg_strerror( rc ) );
+    goto out;
+  }
 
-    if ( dh_ref < 0 )
-    {
-      fprintf( stderr, "** Failed to open ref device %s, exiting.\n", ref_device_name );
-      exit( EXIT_FAILURE );
-    }
+  #if defined( DEBUG )
+    fprintf( stderr, "Ref device %s (%s) opened successfully.\n",
+             ref_dev_param, ref_dev_fn );
+  #endif
 
-    #if defined( DEBUG )
-      fprintf( stderr, "Ref device %s opened successfully.\n", ref_device_name );
-    #endif
+  mbg_get_device_info( dh_ref, &dev_info_ref );
 
-    mbg_get_device_info( dh_ref, &dev_info_ref );
-    //##+++ TODO: error checking
+  if ( mbg_rc_is_error( rc ) )
+  {
+    fprintf( stderr, "** Failed to get device info for ref device %s: %s.\n",
+                     ref_dev_param, mbg_strerror( rc ) );
+    goto out_close;
   }
 
   // Handle each of the specified devices.
   rc = mbg_handle_devices( argc, argv, optind, do_mbgcmptime, 0 );
 
+out_close:
   mbg_close_device( &dh_ref );
 
+out:
   return mbg_rc_is_success( rc ) ? MBG_EXIT_CODE_SUCCESS : MBG_EXIT_CODE_FAIL;
 }
diff --git a/mbgctrl/mbgctrl.c b/mbgctrl/mbgctrl.c
index 23eeec1..4c3c8bc 100644
--- a/mbgctrl/mbgctrl.c
+++ b/mbgctrl/mbgctrl.c
@@ -1,7 +1,7 @@
 
 /**************************************************************************
  *
- *  $Id: mbgctrl.c 1.26 2018/12/11 12:07:50Z martin REL_M $
+ *  $Id: mbgctrl.c 1.27 2018/12/14 12:49:49Z martin REL_M $
  *
  *  Description:
  *    Main file for mbgctrl program which sends commands and
@@ -9,7 +9,11 @@
  *
  * -----------------------------------------------------------------------
  *  $Log: mbgctrl.c $
- *  Revision 1.26  2018/12/11 12:07:50Z  martin
+ *  Revision 1.27  2018/12/14 12:49:49Z  martin
+ *  Introduced new command COLDBOOT.
+ *  Use new function mbg_open_device_by_param_chk().
+ *  Fixed compiler warnings and doxygen comment.
+ *  Revision 1.26  2018/12/11 12:07:50  martin
  *  Fixed compiler warnings on Windows.
  *  Revision 1.25  2018/11/15 12:12:37Z  martin
  *  Individual MBG_MICRO_VERSION codes are now obsolete.
@@ -869,7 +873,7 @@ static /*HDR*/
  * @brief Lookup a parameter in an argument list and check if a colon is appended
  *
  * @param arg  An argument list of the form: "name:val,name:val,..."
- * @param s    A parameter name searched for in the argument list
+ * @param id   A parameter name searched for in the argument list
  * @param p    A pointer to a (char *) which is set to the beginning
  *             of the value part of a parameter string
  *
@@ -1310,7 +1314,7 @@ static /*HDR*/
 int ip4_check_parm( const char *s, IP4_INFO *p )
 {
   size_t l = strlen( p->name );
-  size_t n;
+  int n;
 
   if ( strncmp( s, p->name, l ) != 0 )
     return 0;  // parameter does not match
@@ -1325,9 +1329,9 @@ int ip4_check_parm( const char *s, IP4_INFO *p )
   if ( n < 0 )
     goto fail;  // parameter syntax error: failed to convert numeric address
 
-  n += l;
+  l += n;
 
-  return _int_from_size_t( n );
+  return _int_from_size_t( l );
 
 fail:
   return MBG_ERR_CFG;
@@ -2689,7 +2693,8 @@ void usage( MBG_DEV_HANDLE dh, PCPS_DEV *p_dev, RECEIVER_INFO *p_ri,
   printf( "Usage:  %s cmd [dev]\n"
           "\n"
           "where cmd can be one of the following:\n"
-          "  BOOT             set GPS clock to boot mode\n"
+          "  BOOT             set GPS clock to warm boot mode, sat info is kept\n"
+          "  COLDBOOT         set GPS clock to cold boot mode, all sat info is cleared\n"
           "  GPSPOS=x.x,y.y,z set GPS position to (lat,lon,alt)\n",
           pname
         );
@@ -2912,6 +2917,19 @@ int check_cmd_line( int argc, char *argv[], MBG_DEV_HANDLE dh, const PCPS_DEV *p
       continue;
     }
 
+    if ( strcmp( argv[i], "COLDBOOT" ) == 0 )
+    {
+      if ( p_dev )
+      {
+        if ( _pcps_is_gps( p_dev ) )
+          rc = send_gps_cmd( dh, PC_GPS_CMD_INIT_SYS );
+        else
+          err_msg( p_dev, no_gps_cmd );
+      }
+      continue;
+    }
+
+
     if ( strcmp( argv[i], "BOOT" ) == 0 )
     {
       if ( p_dev )
@@ -3407,8 +3425,8 @@ int main( int argc, char *argv[] )
   // pass a device handle, so commands are not evaluated.
   check_cmd_line( argc, argv, dh, NULL, &ri, &rpcfg );
 
-  rc = mbg_open_device_by_param( &dh, dev_name, 0, 0,
-               tmp_dev_fn, sizeof( tmp_dev_fn ), 0 );
+  rc = mbg_open_device_by_param_chk( &dh, dev_name, 0, tmp_dev_fn,
+                                     sizeof( tmp_dev_fn ) );
 
   if ( mbg_rc_is_error( rc ) )
     goto fail;
diff --git a/mbglib/common/timeutil.c b/mbglib/common/timeutil.c
index 3c40ad2..4d13f4f 100644
--- a/mbglib/common/timeutil.c
+++ b/mbglib/common/timeutil.c
@@ -1,7 +1,7 @@
 
 /**************************************************************************
  *
- *  $Id: timeutil.c 1.8 2018/12/11 15:02:57Z martin REL_M $
+ *  $Id: timeutil.c 1.9 2018/12/18 11:00:48Z martin REL_M $
  *
  *  Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
  *
@@ -10,6 +10,8 @@
  *
  * -----------------------------------------------------------------------
  *  $Log: timeutil.c $
+ *  Revision 1.9  2018/12/18 11:00:48Z  martin
+ *  Implemented setting time on Windows.
  *  Revision 1.8  2018/12/11 15:02:57Z  martin
  *  Cast to avoid build error on Windows.
  *  Revision 1.7  2018/01/30 09:51:35Z  martin
@@ -104,12 +106,11 @@ int mbg_clock_gettime( clockid_t clock_id, struct timespec *tp )
       int rc = timespec_get( tp, TIME_UTC );
       return ( rc == 0 ) ? -1 : 0;
     #else
-      #define EPOCH_HNS     116444736000000000i64
       FILETIME ft;
       unsigned __int64 tmp;
       gstaft_fnc( &ft );
       tmp = ( (__int64) ft.dwHighDateTime << 32 ) | ft.dwLowDateTime;
-      tmp -= EPOCH_HNS;   // convert to Unix epoch
+      tmp -= FILETIME_1970;   // convert to Unix epoch
       tmp *= 100;         // convert to nanoseconds
       tp->tv_sec = (time_t) ( tmp / NSEC_PER_SEC );
       tp->tv_nsec = (long) ( tmp % NSEC_PER_SEC );
@@ -128,31 +129,30 @@ int mbg_clock_settime( clockid_t clock_id, const struct timespec *tp )
 {
   if ( clock_id == CLOCK_REALTIME )
   {
-#if 0  // ### TODO FIXME This needs to be implemented.
-    #if defined( TIME_UTC )  // C11 / VS2015+
-      int rc = timespec_get( res, TIME_UTC );  // TODO Check this code
-      return ( rc == 0 ) ? -1 : 0   // rc == 0 means error
-    #else
-      #define EPOCH_HNS     116444736000000000i64
+    SYSTEMTIME st;
+    union
+    {
       FILETIME ft;
-      unsigned __int64 tmp;
-      gstaft_fnc( &ft );
-      tmp = ( (__int64) ft.dwHighDateTime << 32 ) | ft.dwLowDateTime;
-      tmp -= EPOCH_HNS;   // convert to Unix epoch
-      tmp *= 100;         // convert to nanoseconds
-      res->tv_sec = ( tmp / NSEC_PER_SEC );
-      res->tv_nsec = ( tmp % NSEC_PER_SEC );
-      return 0;
-    #endif
-#endif
+      ULONGLONG ull;
+    } t;
 
-    return 0;  // FIXME this is actually not true
-  }
-  else
-    return -1;    // TODO this is e.g. in case of CLOCK_MONOTONIC, we could use QPC then.
+    t.ull = FILETIME_1970 +
+      (ULONGLONG) tp->tv_sec * HNS_PER_SEC +
+      (ULONGLONG) tp->tv_nsec / 100;
 
-}  // mbg_clock_settime
+    if ( !FileTimeToSystemTime( &t.ft, &st ) )
+      goto fail;  // GetLastError() returns the error code
 
+    if ( !SetSystemTime( &st ) )
+      goto fail;  // GetLastError() returns the error code
+
+    return 0;
+}
+
+fail:
+  return -1;    // TODO this is e.g. in case of CLOCK_MONOTONIC, we could use QPC then.
+
+}  // mbg_clock_settime
 
 
 bool force_legacy_gstaft;
diff --git a/mbglib/common/toolutil.c b/mbglib/common/toolutil.c
index 7e4bd46..e0e05f1 100644
--- a/mbglib/common/toolutil.c
+++ b/mbglib/common/toolutil.c
@@ -1,7 +1,7 @@
 
 /**************************************************************************
  *
- *  $Id: toolutil.c 1.8 2018/11/15 12:20:44Z martin REL_M $
+ *  $Id: toolutil.c 1.9 2018/12/14 13:13:46Z martin REL_M $
  *
  *  Description:
  *    Common functions which can be used with Meinberg command line
@@ -9,7 +9,14 @@
  *
  * -----------------------------------------------------------------------
  *  $Log: toolutil.c $
- *  Revision 1.8  2018/11/15 12:20:44Z  martin
+ *  Revision 1.9  2018/12/14 13:13:46Z  martin
+ *  Cleaned up mbg_open_device_by_param(), removed obsolete
+ *  parameters, and removed all printing by this function.
+ *  New function mbg_open_device_by_param_chk() which actually
+ *  calls mbg_open_device_by_param() and prints a message to stderr
+ *  if the call failed.
+ *  Updated some comments.
+ *  Revision 1.8  2018/11/15 12:20:44  martin
  *  Individual MBG_MICRO_VERSION codes are now obsolete.
  *  Revision 1.7  2018/07/03 14:47:31  martin
  *  Print a message if an old card with 20 ms timing bug is detected.
@@ -446,10 +453,27 @@ int chk_get_num_devices( void )
 
 
 /*HDR*/
-int mbg_open_device_by_param( MBG_DEV_HANDLE *p_dh, const char *dev_param_str,
-                              int dev_idx, int devices_specified,
-                              char *dev_name_buffer, size_t dev_name_buffer_size,
-                              int chk_dev_flags )
+/**
+ * @brief Try to open a device using a parameter string or device index.
+ *
+ * @param[out]  p_dh           Address of a device handle variable to be set on success.
+ * @param[in]   dev_param_str  An optional device specification string. This can be:
+ *                             - A device file name, if the operating system supports this. See ::MBG_DEV_FN.
+ *                             - A device model name like "GPS180PEX", eventually with the serial number
+ *                               appended after an underscore, as in "GPS180PEX_029511026220".
+ *                               See ::MBG_DEV_NAME.
+ *                             - A device index number as string, e.g "0" or "3".
+ *                             - NULL, in which case @p dev_idx has to be a valid device index number.
+ * @param[in]   dev_idx               A device index number which is used if @p dev_param_str is NULL.
+ * @param[out]  dev_name_buffer       A string buffer to which a device name can be written, see ::MBG_DEV_FN.
+ * @param[in]   dev_name_buffer_size  The size of the @p dev_name_buffer buffer
+ *
+ * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES
+ *
+ * @see ::mbg_open_device_by_param
+ */
+int mbg_open_device_by_param( MBG_DEV_HANDLE *p_dh, const char *dev_param_str, int dev_idx,
+                              char *dev_name_buffer, size_t dev_name_buffer_size )
 {
   MBG_DEV_HANDLE dh = MBG_INVALID_DEV_HANDLE;
   int devices_found;
@@ -463,13 +487,6 @@ int mbg_open_device_by_param( MBG_DEV_HANDLE *p_dh, const char *dev_param_str,
   if ( dev_param_str )
   {
     // A device parameter string has been specified.
-    // This can be:
-    //  - A device file name, see ::MBG_DEV_FN
-    //  - A device model name like "GPS180PEX", eventually with the serial number
-    //    appended after an underscore, as in "GPS180PEX_029511026220".
-    //    See ::MBG_DEV_NAME.
-    //  - A device index number as string, e.g "0" or "3".
-
     char *endptr;
     long l;
 
@@ -479,7 +496,7 @@ int mbg_open_device_by_param( MBG_DEV_HANDLE *p_dh, const char *dev_param_str,
       {
         snprintf_safe( dev_name_buffer, dev_name_buffer_size, "%s", dev_param_str );
         dh = mbg_open_device_by_dev_fn( dev_param_str );
-        goto out_chk;
+        goto has_tried_to_open;
       }
     #endif
 
@@ -512,87 +529,92 @@ int mbg_open_device_by_param( MBG_DEV_HANDLE *p_dh, const char *dev_param_str,
     // with serial number appended.
     snprintf_safe( dev_name_buffer, dev_name_buffer_size, "%s", dev_param_str );
     dh = mbg_open_device_by_name( dev_param_str, MBG_MATCH_MODEL );
-    goto out_chk;
+    goto has_tried_to_open;
   }
 
 
-  // No device has been specified on the command line.
-
-#if 0 // TODO
-  if ( chk_dev_flags & CHK_DEV_WITHOUT_DEV )
-  {
-    // TODO Check if this branch is useful
-    // We have been called without a device to be used.
-    // This may be useful e.g. if we just want to print
-    // some general usage information.
-    if ( fnc )
-    {
-      *p_dh = MBG_INVALID_DEV_HANDLE;
-      rc = fnc( *p_dh, NULL );
-    }
-    else
-    {
-      // TODO Should we report an error if we have been called
-      // without callback function and without device?
-    }
-    goto out;
-  }
-#endif
-
+  // We get here directly if dev_param_str is NULL.
 
 open_dev_with_idx:
+  // Try to open the device with the index number which has been derived
+  // from dev_param_str, or has been passed directly by the caller.
+  // First check if the device index is in a valid range.
   devices_found = chk_get_num_devices();
 
-  if ( devices_found == 0 )  // no device found
-  {
-    // Don't continue without any device, unless
-    // explicitly requested to do so.
-    if ( !( chk_dev_flags & CHK_DEV_WITHOUT_DEV ) )
-      return MBG_ERR_NO_DEV;
+  if ( devices_found == 0 )       // no device found
+    return MBG_ERR_NO_DEV;
 
-    // We may continue even if no device is available,
-    // but have to process the callback loop only once.
-    devices_found = 1;
-  }
+  if ( dev_idx >= devices_found )  // device index exceeds max
+    return MBG_ERR_NO_DEV;
 
-  // Unless explicitly requested to handle all devices
-  // we have found, we only handle the first one.
-  if ( !( chk_dev_flags & CHK_DEV_ALL_DEVICES ) )
-    devices_found = 1;
-
-
-  // Try to open the device with the specified index number.
   mbg_dev_fn_from_dev_idx( dev_name_buffer, (int) dev_name_buffer_size, dev_idx );
   dh = mbg_open_device( dev_idx );
 
-out_chk:
-  // Now check if the "open" function we've just called before
-  // was successful.
-  if ( dh == MBG_INVALID_DEV_HANDLE )
+
+has_tried_to_open:
+  // We get here immediately after one of the "open" functions has been called,
+  // so retrieve an error code to be returned if that function failed.
+  rc = ( dh == MBG_INVALID_DEV_HANDLE ) ? mbg_get_last_error( NULL ) : MBG_SUCCESS;
+
+out:
+  // Save the returned handle, which can be MBG_INVALID_DEV_HANDLE.
+  *p_dh = dh;
+
+  return rc;
+
+}  // mbg_open_device_by_param
+
+
+
+/*HDR*/
+/**
+ * @brief Try to open a device and print a message in case of error.
+ *
+ * Call ::mbg_open_device_by_param to try to open a device,
+ * and print an error message to stderr if the call fails.
+ *
+ * @param[out]  p_dh           Address of a device handle variable to be set on success.
+ * @param[in]   dev_param_str  An optional device specification string. This can be:
+ *                             - A device file name, if the operating system supports this. See ::MBG_DEV_FN.
+ *                             - A device model name like "GPS180PEX", eventually with the serial number
+ *                               appended after an underscore, as in "GPS180PEX_029511026220".
+ *                               See ::MBG_DEV_NAME.
+ *                             - A device index number as string, e.g "0" or "3".
+ *                             - NULL, in which case @p dev_idx has to be a valid device index number.
+ * @param[in]   dev_idx               A device index number which is used if @p dev_param_str is NULL.
+ * @param[out]  dev_name_buffer       A string buffer to which a device name can be written, see ::MBG_DEV_FN.
+ * @param[in]   dev_name_buffer_size  The size of the @p dev_name_buffer buffer
+ *
+ * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES
+ *
+ * @see ::mbg_open_device_by_param
+ */
+int mbg_open_device_by_param_chk( MBG_DEV_HANDLE *p_dh, const char *dev_param_str, int dev_idx,
+                                  char *dev_name_buffer, size_t dev_name_buffer_size )
+{
+  int rc = mbg_open_device_by_param( p_dh, dev_param_str, dev_idx,
+                                     dev_name_buffer, dev_name_buffer_size );
+  if ( mbg_rc_is_error( rc ) )
   {
     char msg[256];
     int n = 0;
-    rc  = mbg_get_last_error( NULL );
-
     n = snprintf_safe( msg, sizeof( msg ), "** Failed to open device" );
 
     if ( dev_name_buffer[0] )  // string not empty
       n += snprintf_safe( &msg[n], sizeof( msg ) - n, " %s", dev_name_buffer );
+    else
+      if ( dev_param_str )     // parameter string has been specified
+        n += snprintf_safe( &msg[n], sizeof( msg ) - n, " %s", dev_param_str );
+      else                     // device index number
+        n += snprintf_safe( &msg[n], sizeof( msg ) - n, " %i", dev_idx );
 
     n += snprintf_safe( &msg[n], sizeof( msg ) - n, ": %s", mbg_strerror( rc ) );
     fprintf( stderr, "%s\n\n", msg );
-    goto out;
   }
 
-  rc = MBG_SUCCESS;
-
-
-out:
-  *p_dh = dh;
-
   return rc;
 
-}  // mbg_open_device_by_param
+}  // mbg_open_device_by_param_chk
 
 
 
@@ -645,8 +667,8 @@ int mbg_handle_devices( int argc, char *argv[], int optind,
     {
       dev_param_str = argv[i];
 
-      rc = mbg_open_device_by_param( &dh, dev_param_str, 0, devices_specified,
-                                     tmp_dev_fn, sizeof( tmp_dev_fn ), chk_dev_flags );
+      rc = mbg_open_device_by_param_chk( &dh, dev_param_str, 0,
+                                         tmp_dev_fn, sizeof( tmp_dev_fn ) );
 
       if ( mbg_rc_is_success( rc ) )
         rc = mbg_handle_device( dh, ( devices_specified > 1 ) ? tmp_dev_fn : NULL, fnc );
@@ -707,8 +729,7 @@ int mbg_handle_devices( int argc, char *argv[], int optind,
 
   for ( i = 0; i < devices_found; i++ )
   {
-    rc = mbg_open_device_by_param( &dh, NULL, i, 0, tmp_dev_fn,
-                                   sizeof( tmp_dev_fn ), chk_dev_flags );
+    rc = mbg_open_device_by_param_chk( &dh, NULL, i, tmp_dev_fn, sizeof( tmp_dev_fn ) );
 
     if ( mbg_rc_is_success( rc ) )
       rc = mbg_handle_device( dh, ( devices_found > 1 ) ? tmp_dev_fn : NULL, fnc );
diff --git a/mbglib/common/toolutil.h b/mbglib/common/toolutil.h
index 60a48ae..8d75797 100644
--- a/mbglib/common/toolutil.h
+++ b/mbglib/common/toolutil.h
@@ -1,7 +1,7 @@
 
 /**************************************************************************
  *
- *  $Id: toolutil.h 1.6 2018/11/15 12:21:10Z martin REL_M $
+ *  $Id: toolutil.h 1.7 2018/12/14 13:14:52Z martin REL_M $
  *
  *  Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
  *
@@ -10,7 +10,9 @@
  *
  * -----------------------------------------------------------------------
  *  $Log: toolutil.h $
- *  Revision 1.6  2018/11/15 12:21:10Z  martin
+ *  Revision 1.7  2018/12/14 13:14:52Z  martin
+ *  Updated function prototypes.
+ *  Revision 1.6  2018/11/15 12:21:10  martin
  *  Updated function prototypes.
  *  Revision 1.5  2018/06/25 13:47:45  martin
  *  Updated function prototypes.
@@ -177,7 +179,6 @@ enum MBG_EXIT_CODES
  * @param[out]  s              Address of a string buffer to be filled.
  * @param[in]   max_len        Size of the string buffer.
  * @param[in]   pname          The program name.
- * @param[in]   micro_version  Micro version code for the application.
  * @param[in]   first_year     First copyright year.
  * @param[in]   last_year      Last copyright year.
  *
@@ -189,7 +190,6 @@ enum MBG_EXIT_CODES
  * @brief Print program info to console
  *
  * @param[in]   pname          The program name.
- * @param[in]   micro_version  Micro version code for the application.
  * @param[in]   first_year     First copyright year.
  * @param[in]   last_year      Last copyright year.
  */
@@ -263,7 +263,51 @@ enum MBG_EXIT_CODES
  */
  int chk_get_num_devices( void ) ;
 
- int mbg_open_device_by_param( MBG_DEV_HANDLE *p_dh, const char *dev_param_str, int dev_idx, int devices_specified, char *dev_name_buffer, size_t dev_name_buffer_size, int chk_dev_flags ) ;
+ /**
+ * @brief Try to open a device using a parameter string or device index.
+ *
+ * @param[out]  p_dh           Address of a device handle variable to be set on success.
+ * @param[in]   dev_param_str  An optional device specification string. This can be:
+ *                             - A device file name, if the operating system supports this. See ::MBG_DEV_FN.
+ *                             - A device model name like "GPS180PEX", eventually with the serial number
+ *                               appended after an underscore, as in "GPS180PEX_029511026220".
+ *                               See ::MBG_DEV_NAME.
+ *                             - A device index number as string, e.g "0" or "3".
+ *                             - NULL, in which case @p dev_idx has to be a valid device index number.
+ * @param[in]   dev_idx               A device index number which is used if @p dev_param_str is NULL.
+ * @param[out]  dev_name_buffer       A string buffer to which a device name can be written, see ::MBG_DEV_FN.
+ * @param[in]   dev_name_buffer_size  The size of the @p dev_name_buffer buffer
+ *
+ * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES
+ *
+ * @see ::mbg_open_device_by_param
+ */
+ int mbg_open_device_by_param( MBG_DEV_HANDLE *p_dh, const char *dev_param_str, int dev_idx, char *dev_name_buffer, size_t dev_name_buffer_size ) ;
+
+ /**
+ * @brief Try to open a device and print a message in case of error.
+ *
+ * Call ::mbg_open_device_by_param to try to open a device,
+ * and print an error message to stderr if the call fails.
+ *
+ * @param[out]  p_dh           Address of a device handle variable to be set on success.
+ * @param[in]   dev_param_str  An optional device specification string. This can be:
+ *                             - A device file name, if the operating system supports this. See ::MBG_DEV_FN.
+ *                             - A device model name like "GPS180PEX", eventually with the serial number
+ *                               appended after an underscore, as in "GPS180PEX_029511026220".
+ *                               See ::MBG_DEV_NAME.
+ *                             - A device index number as string, e.g "0" or "3".
+ *                             - NULL, in which case @p dev_idx has to be a valid device index number.
+ * @param[in]   dev_idx               A device index number which is used if @p dev_param_str is NULL.
+ * @param[out]  dev_name_buffer       A string buffer to which a device name can be written, see ::MBG_DEV_FN.
+ * @param[in]   dev_name_buffer_size  The size of the @p dev_name_buffer buffer
+ *
+ * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES
+ *
+ * @see ::mbg_open_device_by_param
+ */
+ int mbg_open_device_by_param_chk( MBG_DEV_HANDLE *p_dh, const char *dev_param_str, int dev_idx, char *dev_name_buffer, size_t dev_name_buffer_size ) ;
+
  /**
  * @brief Main action handler that can be called by utility programs
  *
diff --git a/mbgtcrcal/mbgtcrcal.c b/mbgtcrcal/mbgtcrcal.c
index f25c913..da4dd5b 100644
--- a/mbgtcrcal/mbgtcrcal.c
+++ b/mbgtcrcal/mbgtcrcal.c
@@ -1,7 +1,7 @@
 
 /**************************************************************************
  *
- *  $Id: mbgtcrcal.c 1.12 2018/12/11 16:15:39Z martin REL_M $
+ *  $Id: mbgtcrcal.c 1.13 2018/12/14 13:04:53Z martin REL_M $
  *
  *  Description:
  *    Main file for mbgtcrcal program which can be used to calibrate
@@ -9,7 +9,10 @@
  *
  * -----------------------------------------------------------------------
  *  $Log: mbgtcrcal.c $
- *  Revision 1.12  2018/12/11 16:15:39Z  martin
+ *  Revision 1.13  2018/12/14 13:04:53Z  martin
+ *  Unified usage output.
+ *  Use predefined macros to check return codes.
+ *  Revision 1.12  2018/12/11 16:15:39  martin
  *  Fixed compiler warning on Windows.
  *  Revision 1.11  2018/12/11 11:57:32Z  martin
  *  Fixed compiler warnings on Windows.
@@ -132,7 +135,7 @@ int do_mbgtcrcal( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev )
   // read the current IRIG input configuration
   rc = mbg_get_irig_rx_info( dh, &irig_rx_info );
 
-  if ( rc != MBG_SUCCESS )
+  if ( mbg_rc_is_error( rc ) )
   {
     printf( "** Failed to read IRIG RX configuration, rc: %i\n", rc );
     goto done;
@@ -171,13 +174,13 @@ int do_mbgtcrcal( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev )
   #if defined( DEBUG )
     printf( "mbg_get_cal_rec_irig_rx_num_rec() returned %i", rc );
 
-    if ( rc == MBG_SUCCESS )
+    if ( mbg_rc_is_success( rc ) )
       printf( ", irig_rx_num_rec: %i", num_rec );
 
     printf( "\n" );
   #endif
 
-  if ( rc != MBG_SUCCESS )
+  if ( mbg_rc_is_error( rc ) )
   {
     printf( "** Failed to read number of IRIG RX calibration records, rc: %i\n", rc );
     goto done;
@@ -226,7 +229,7 @@ int do_mbgtcrcal( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev )
 
     rc = mbg_get_cal_rec_irig_rx_comp( dh, idx, p );
 
-    if ( rc != MBG_SUCCESS )
+    if ( mbg_rc_is_error( rc ) )
     {
       printf( "** Failed to read IRIG RX calibration record #%i. rc = %i\n", idx, rc );
       goto done;
@@ -268,7 +271,7 @@ int do_mbgtcrcal( MBG_DEV_HANDLE dh, const PCPS_DEV *p_dev )
 
   rc = mbg_set_cal_rec_irig_rx_comp( dh, p );
 
-  if ( rc != MBG_SUCCESS )
+  if ( mbg_rc_is_error( rc ) )
   {
     printf( "** Failed to save new IRIG calibration setting for group %s.\n",
             irig_comp_names[curr_group_idx] );
@@ -300,17 +303,16 @@ void usage( void )
   mbg_print_help_options();
   mbg_print_opt_info( "-c val", "set calibration value \'val\'" );
   mbg_print_opt_info( "-v", "increase verbosity" );
-  puts( "" );
+  mbg_print_device_options();
 
+  puts( "" );
   printf( "Example usage:\n"
           "\n"
+          "%s                   print current settings of the default device\n"
+          "%s [dev]             print current settings of specific device [dev]\n"
           "%s -c 10             compensate +10.0 us on default device\n"
           "%s -c -12.1 [dev]    compensate -12.1 us on specific device [dev]\n"
-          "\n"
-          "where [dev] can be e.g. \"%s\" or \"%s\", depending on the installed card(s)\n",
-          pname, pname,  EXAMPLE_DEV_NAME_1_TCR, EXAMPLE_DEV_NAME_2 );
-  puts( "" );
-
+          "\n", pname, pname, pname, pname );
   printf( "New settings become effective for a group of IRIG codes with similar characteristics\n"
           "to which the currently configured IRIG RX code belongs. Calibration values are\n"
           "in microseconds, with 0.1 us resolution, in the range +/-%s us.\n",
diff --git a/mbgversion.h b/mbgversion.h
index 1e122c8..9a957fb 100644
--- a/mbgversion.h
+++ b/mbgversion.h
@@ -1,7 +1,7 @@
 
 /**************************************************************************
  *
- *  $Id: mbgversion.h 1.10 2018/08/07 13:15:33Z martin REL_M $
+ *  $Id: mbgversion.h 1.11 2018/12/13 15:39:00Z martin REL_M $
  *
  *  Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
  *
@@ -10,7 +10,9 @@
  *
  * -----------------------------------------------------------------------
  *  $Log: mbgversion.h $
- *  Revision 1.10  2018/08/07 13:15:33Z  martin
+ *  Revision 1.11  2018/12/13 15:39:00Z  martin
+ *  New version code 4.2.1.
+ *  Revision 1.10  2018/08/07 13:15:33  martin
  *  Cleaned up version definitions.
  *  Revision 1.9  2018/06/25 15:53:14  martin
  *  New version code 4.2.0.
@@ -46,7 +48,7 @@
 
 #define MBG_MAJOR_VERSION_CODE          4
 #define MBG_MINOR_VERSION_CODE          2
-#define MBG_MICRO_VERSION_CODE          0
+#define MBG_MICRO_VERSION_CODE          1
 
 #if defined( MBG_TGT_WIN32 )
   #define MBG_BUILD_VERSION_CODE        1
diff --git a/vc6/mbgcmptime/mbgcmptime.dsp b/vc6/mbgcmptime/mbgcmptime.dsp
index d1c2b2f..4bb0ebc 100644
--- a/vc6/mbgcmptime/mbgcmptime.dsp
+++ b/vc6/mbgcmptime/mbgcmptime.dsp
@@ -103,7 +103,7 @@ SOURCE=..\..\mbglib\common\lan_util.c
 # End Source File
 # Begin Source File
 
-SOURCE=..\..\test\mbgcmptime\mbgcmptime.c
+SOURCE=..\..\mbgcmptime\mbgcmptime.c
 # End Source File
 # Begin Source File
 
diff --git a/vc6/mbgtcrcal/mbgtcrcal.dsp b/vc6/mbgtcrcal/mbgtcrcal.dsp
index 00ee173..d03d51d 100644
--- a/vc6/mbgtcrcal/mbgtcrcal.dsp
+++ b/vc6/mbgtcrcal/mbgtcrcal.dsp
@@ -95,7 +95,7 @@ SOURCE=..\..\mbglib\common\mbgerror.c
 # End Source File
 # Begin Source File
 
-SOURCE=..\..\test\mbgtcrcal\mbgtcrcal.c
+SOURCE=..\..\mbgtcrcal\mbgtcrcal.c
 # End Source File
 # Begin Source File
 
diff --git a/vs2008/mbgcmptime/mbgcmptime.vcproj b/vs2008/mbgcmptime/mbgcmptime.vcproj
index 9488455..a25b4e6 100644
--- a/vs2008/mbgcmptime/mbgcmptime.vcproj
+++ b/vs2008/mbgcmptime/mbgcmptime.vcproj
@@ -335,7 +335,7 @@
 				>
 			</File>
 			<File
-				RelativePath="..\..\test\mbgcmptime\mbgcmptime.c"
+				RelativePath="..\..\mbgcmptime\mbgcmptime.c"
 				>
 			</File>
 			<File
diff --git a/vs2008/mbgtcrcal/mbgtcrcal.vcproj b/vs2008/mbgtcrcal/mbgtcrcal.vcproj
index 440d2f4..d58f190 100644
--- a/vs2008/mbgtcrcal/mbgtcrcal.vcproj
+++ b/vs2008/mbgtcrcal/mbgtcrcal.vcproj
@@ -339,7 +339,7 @@
 				>
 			</File>
 			<File
-				RelativePath="..\..\test\mbgtcrcal\mbgtcrcal.c"
+				RelativePath="..\..\mbgtcrcal\mbgtcrcal.c"
 				>
 			</File>
 			<File