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
---------------------------------------------------
- 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
jspc29 / daqdata.git / commitdiff