From: hades <hades>
Date: Sun, 10 Sep 2000 09:41:00 +0000 (+0000)
Subject: *** empty log message ***
X-Git-Url: https://jspc29.x-matter.uni-frankfurt.de/git/?a=commitdiff_plain;h=99006f3f9610f709a3c648b458693754ccf75c2f;p=daqdata.git

*** empty log message ***
---

diff --git a/allParam/README b/allParam/README
index 3567fd8..0ee2580 100644
--- a/allParam/README
+++ b/allParam/README
@@ -66,7 +66,133 @@ the change of LIBPATH and INCPATH in the Makefiles is straight forward.
 3. How to use the param libraries
 ---------------------------------
 
+  The param libraries provide four functions to access parmeters from different
+sources:
+- Param_getStringArray() retrieves an array of strings,
+- Param_getIntArray() makes a conversion to unsigned long integers (if all
+  elements of the retrieved array can be converted properly; to decide this,
+  the c-function strtoul(3) is used)
+- Param_getString() and
+- Param_getInt() are aliases that retrieve only a scalar value (the first
+  element of an array)
+All functions have a return value that indicates the success (0) or failure
+of the action, all functions need to get a pointer to user-supplied space
+for the result and all funtions put the number of elements returned into a
+user-supplied integer field. Additionally all functions need a pointer to an
+invoked Param structure and name and idx to identify the Parameter that should
+be returned.
+  In case of a failure, one can also retrieve the last error message from the
+parameter source when looking into Param_getErrStr().
+  At first you have to invoke a new Param structure and call the constructor
+of it via
+#include <param.h>
+...
+{
+	Param *param;
+	param = malloc(sizeof(Param));
+	if(param != 0) {
+		if(conParam(param) != 0) {
+			sprintf(stderr, "conParam() for param failed.\n"); 
+			exit(-1);
+		}
+	} else {
+		sprintf(stderr, "malloc() for param failed.\n"); 
+		exit(-1);
+	}
+}
+...
+{
+	desParam(param);
+	free param;
+}
+Here also shown is the deletion of the Param structure. Then you can
+immediately start retieving values. Note, that a not found parameter does not
+result in an -1 return value but only in the number 0 of returned rows. So
+check the returned rows all the time before you use the result. The content of
+the reserved space is not defined beyond the retrieved values. Note that
+returned strings may have a length of PARAM_MAX_VALUE_LEN and prepare enought
+space for them. Here some examples (one for each function):
 
+/* Param_getString */
+	const char *name = "testname";
+	const char *idx1 = "teststring";
+	char values[PARAM_MAX_VALUE_LEN];
+	int row;
+	if(Param_getString(param, name, idx1, &row, values) != 0) {
+		sprintf(stderr, "%s : Param_getString() failed: %s",
+			argv[0], Param_getErrStr(param));
+			exit (-1);
+	} else if(row == 0) {
+		sprintf(stderr, "%s(%s) not found.\n", name, idx1);
+	} else {
+		printf("%s(%s): %s\n", name, idx1, values);
+	}
+
+/* Param_getInt */
+	const char *idx2 = "testint";
+	unsigned long int valuei;
+	if(Param_getInt(param, name, idx2, &row, &valuei) != 0) {
+		sprintf(stderr, "%s : Param_getString() failed: %s",
+			argv[0], Param_getErrStr(param));
+			exit (-1);
+	} else if(row == 0) {
+		sprintf(stderr, "%s(%s) not found.\n", name, idx2);
+		exit (-1);
+	} else {
+		printf("%s(%s) : %s\n", name, idx2, valuei);
+	}
+
+/* Param_getStringArray */
+	const char *idx3 = "teststringarray";
+	char *valuesa[LEN];
+	int maxrows = LEN;
+	int rows;
+	int i;
+	for (i = 0 ; i < maxrows ; i++) {
+		valuesa[i] = malloc(PARAM_MAX_VALUE_LEN * sizeof(char));
+		if(valuesa[i] == 0) {
+			sprintf(stderr, "malloc() for value failed.\n"); 
+			exit(-1);
+		}
+	}
+	if(Param_getStringArray(param, name, idx3, maxrows, &rows, valuesa) != 0) {
+		sprintf(stderr, "%s : Param_getString() failed: %s",
+			argv[0], Param_getErrStr(param));
+			exit (-1);
+	} else if(row == 0) {
+		sprintf(stderr, "%s(%s) not found.\n", name, idx3);
+		exit (-1);
+	} else {
+		for (i = 0 ; i < maxrows ; i++) {
+			printf("%s(%s %d) : %s\n", name, idx3, i, valuesa[i]);
+			free(valuesa[i]);
+		}
+	}
+
+/* Param_getIntArray */
+	const char *idx4 = "testintarray";
+	unsigned long int valueia[LEN];
+	if(Param_getIntArray(param, name, idx4, maxrows, &rows, valueia) != 0) {
+		sprintf(stderr, "%s : Param_getString() failed: %s",
+			argv[0], Param_getErrStr(param));
+			exit (-1);
+	} else if(rows == 0) {
+		sprintf(stderr, "%s(%s) not found.\n", name, idx4);
+		exit (-1);
+	} else {
+		for (i = 0 ; i < maxrows ; i++) {
+			printf("%s(%s %d) : %d\n", name, idx4, i, valueia[i]);
+		}
+	}
+
+  Note that the returned number of elements is the minimum of 'maxrows'
+specified and the number of elements found in the parameter source. If those
+two differ, you have do decide what to do, no error return value is set and
+no error message supplied. This is due to the fact that you often don't know
+the exact number of result elements but only a upper limit for that. On the
+other hand if you want to retrieve an integer array and only one of the
+values seems to be no integer (according to strtoul(3)), the return value is
+-1 and the content of the supplied array (valueia in our example) is undefined.
 
 4. Known bugs and further developement perspectives
 ---------------------------------------------------
@@ -74,6 +200,8 @@ the change of LIBPATH and INCPATH in the Makefiles is straight forward.
 - The treatment of values out of bounds (e.g. strings longer than the foreseen
   PARAM_MAX_NAME_LEN and PARAM_MAX_VALUE_LEN) is not checked in the testsuite
   yet.
+- As a fifth data type, blobs (binary large objects) should be supported in the
+  future.
 
 Please send bug reports to