doc: Add section about using benchmarks for tests

to the README.md of the backend_odbc plugin
- explain why only basic unit tests are present
- add --help arguement to the benchmark_mountpoint
- update documentation

benchmarks/mountpoint.c

@@ -33,10 +33,25 @@ char * metaValueFormat = "metav%zu";
 char * metaValueModifiedFormat = "memod%zu";
 
 
+static void printHelp (void)
+{
+	puts ("Optional arguments:");
+	puts ("-c or --key-count <number of keys>: Specify the number of keys to benchmark.");
+	puts ("-H or --harmonize-names");
+	puts ("-h or --help: display this help");
+	puts ("-s or --single-keysets: Store each key in its own KeySet for Benchmark 1");
+	puts ("-m or --with-meta: include benchmarks for metadata, for the most reliable results it is recommended to run the tests for "
+	      "metadata separately (see -M)");
+	puts ("-M or --only-meta: only run benchmarks for metadata");
+	puts ("-v or --verbose: more detailed output");
+	exit (EXIT_SUCCESS);
+}
+
 static bool processCommandLineArguments (int argc, char ** argv)
 {
 	struct option long_options[] = { { "key-count", required_argument, 0, 'c' },
-					 { "harmonize-names", no_argument, 0, 'h' },
+					 { "harmonize-names", no_argument, 0, 'H' },
+					 { "help", no_argument, 0, 'h' },
 					 { "single-keysets", no_argument, 0, 's' },
 					 { "with-meta", no_argument, 0, 'm' },
 					 { "only-meta", no_argument, 0, 'M' },
@@ -67,6 +82,9 @@ static bool processCommandLineArguments (int argc, char ** argv)
 			break;
 		}
 		case 'h':
+			printHelp ();
+			break;
+		case 'H':
 			harmonizeKeys = true;
 			keyNameFormat = "key%08zu";
 			keyValueFormat = "value%08zu";
@@ -88,7 +106,8 @@ static bool processCommandLineArguments (int argc, char ** argv)
 			verbose = true;
 			break;
 		default:
-			break;
+			fprintf (stderr, "The specified argument %c is not valid!", c);
+			printHelp ();
 		}
 	}
 
@@ -105,7 +124,8 @@ int main (int argc, char ** argv)
 
 	if (argc < 2)
 	{
-		fprintf (stderr, "Usage: %s [options] <parentKey>\n", argv[0]);
+		fprintf (stderr, "Usage: %s [options] <parentKey>\n\n", argv[0]);
+		printHelp ();
 		return EXIT_FAILURE;
 	}
 

src/plugins/backend_odbc/README.md

@@ -97,3 +97,32 @@ For unmounting, there is no new command necessary.
 Just use the well-known `kdb umount <mountpoint>`, exactly like for the file-based backend.
 
 For more information about the ODBC backend, there is a tutorial available at [/doc/tutorials/odbc-backend.md](/doc/tutorials/odbc-backend.md).
+
+## Testing and Benchmarking
+
+There are no dedicated unit tests that actually store, read or delete data from
+an ODBC data source.
+The reason is, that with the current concept, a valid ODBC data source
+definition (for unixODBC in `/etc/unixODBC/odbc.ini`) must be present.
+We don't want to write to such an important system file that can influence other
+applications. It would also be cumbersome if we require the user to set up a
+specific ODBC configuration before running the tests .
+
+However, for basic functionality testing and performance evaluation,
+you can create a valid ODBC mountpoint yourself using `kdb mountOdbc`
+and then run the benchmark which is implemented in [/benchmarks/mountpoint.c](/benchmarks/mountpoint.c)
+for the created mountpoint.
+This approach makes it possible to test and benchmark any valid mountpoint in the KDB.
+So different backends and plugins with different configurations can be tested and benchmarked.
+Just create a mountpoint with the backends, plugins and configuration that you want and run
+the benchmark with e.g. `bin/benchmark_mountpoint <MP path>/benchmark` for this mountpoint.
+
+A short example that shows creating a new ODBC mountpoint and running benchmarks for KeySets and metadata:
+
+```sh
+bin/kdb mountOdbc Selektra "" "" elektraKeys keyName keyValue metaKeys keyName metaKeyName metaKeyValue "" user:/odbcSqlite
+bin/benchmark_mountpoint -c 1000 user:/odbcSqlite
+bin/benchmark_mountpoint -Mc 1000 user:/odbcSqlite
+```
+
+More information about benchmarking is available at [/benchmarks/README.md](/benchmarks/README.md).

src/plugins/backend_odbc/backend_odbc_helpers.c

@@ -728,9 +728,9 @@ void clearDsConfig (struct dataSourceConfig * dsConfig, bool freeStrings)
  * @param freeDsConfigStrings only considered, if @p freeDsConfig is 'true', then it specifies if the strings
  * 	inside the dataSourceConfig struct should be freed too.
  *
- * @retval 'false' if a NULL pointer was passed for @p sharedData or an error was reported by ODBC when trying to disconnect or free
+ * @retval false if a NULL pointer was passed for @p sharedData or an error was reported by ODBC when trying to disconnect or free
  * 	the handles.
- * @retval 'true' otherwise.
+ * @retval true otherwise.
  */
 bool clearOdbcSharedData (struct odbcSharedData * sharedData, bool freeDsConfig, bool freeDsConfigStrings)
 {
@@ -779,7 +779,14 @@ bool clearOdbcSharedData (struct odbcSharedData * sharedData, bool freeDsConfig,
 }
 
 
-/* Close the connection and free handles for connection and environment */
+/**
+ * @brief Close the connection and free handles for connection and environment
+ * @param plugin The plugin that contains the odbcSharedData struct which should be cleared
+ * @param[out] errorKey Used to add warnings.
+ *
+ * @retval true if the plugin data was NULL or the ODBC handles could be freed successfully
+ * @retval false if an error occurred
+ */
 bool freeSharedHandles (Plugin * plugin, Key * errorKey)
 {
 	struct odbcSharedData * sharedData = elektraPluginGetData (plugin);