src/utils_db_query.c

   1 /**
   2  * collectd - src/utils_db_query.c
   3  * Copyright (C) 2008,2009  Florian octo Forster
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License as published by the
   7  * Free Software Foundation; only version 2 of the License is applicable.
   8  *
   9  * This program is distributed in the hope that it will be useful, but
  10  * WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License along
  15  * with this program; if not, write to the Free Software Foundation, Inc.,
  16  * 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
  17  *
  18  * Authors:
  19  *   Florian octo Forster <octo at verplant.org>
  20  **/
  21
  22 #include "collectd.h"
  23 #include "common.h"
  24 #include "plugin.h"
  25 #include "configfile.h"
  26 #include "utils_db_query.h"
  27
  28 /*
  29  * Data types
  30  */
  31 struct udb_result_s; /* {{{ */
  32 typedef struct udb_result_s udb_result_t;
  33 struct udb_result_s
  34 {
  35   char    *type;
  36   char    *instance_prefix;
  37   char   **instances;
  38   size_t   instances_num;
  39   char   **values;
  40   size_t   values_num;
  41
  42   udb_result_t *next;
  43 }; /* }}} */
  44
  45 struct udb_query_s /* {{{ */
  46 {
  47   char *name;
  48   char *statement;
  49   void *user_data;
  50
  51   unsigned int min_version;
  52   unsigned int max_version;
  53
  54   udb_result_t *results;
  55 }; /* }}} */
  56
  57 struct udb_result_preparation_area_s /* {{{ */
  58 {
  59   const   data_set_t *ds;
  60   size_t *instances_pos;
  61   size_t *values_pos;
  62   char  **instances_buffer;
  63   char  **values_buffer;
  64
  65   struct udb_result_preparation_area_s *next;
  66 }; /* }}} */
  67 typedef struct udb_result_preparation_area_s udb_result_preparation_area_t;
  68
  69 struct udb_query_preparation_area_s /* {{{ */
  70 {
  71   size_t column_num;
  72   char *host;
  73   char *plugin;
  74   char *db_name;
  75
  76   cdtime_t interval;
  77
  78   udb_result_preparation_area_t *result_prep_areas;
  79 }; /* }}} */
  80
  81 /*
  82  * Config Private functions
  83  */
  84 static int udb_config_set_string (char **ret_string, /* {{{ */
  85     oconfig_item_t *ci)
  86 {
  87   char *string;
  88
  89   if ((ci->values_num != 1)
  90       || (ci->values[0].type != OCONFIG_TYPE_STRING))
  91   {
  92     WARNING ("db query utils: The `%s' config option "
  93         "needs exactly one string argument.", ci->key);
  94     return (-1);
  95   }
  96
  97   string = strdup (ci->values[0].value.string);
  98   if (string == NULL)
  99   {
 100     ERROR ("db query utils: strdup failed.");
 101     return (-1);
 102   }
 103
 104   if (*ret_string != NULL)
 105     free (*ret_string);
 106   *ret_string = string;
 107
 108   return (0);
 109 } /* }}} int udb_config_set_string */
 110
 111 static int udb_config_add_string (char ***ret_array, /* {{{ */
 112     size_t *ret_array_len, oconfig_item_t *ci)
 113 {
 114   char **array;
 115   size_t array_len;
 116   int i;
 117
 118   if (ci->values_num < 1)
 119   {
 120     WARNING ("db query utils: The `%s' config option "
 121         "needs at least one argument.", ci->key);
 122     return (-1);
 123   }
 124
 125   for (i = 0; i < ci->values_num; i++)
 126   {
 127     if (ci->values[i].type != OCONFIG_TYPE_STRING)
 128     {
 129       WARNING ("db query utils: Argument %i to the `%s' option "
 130           "is not a string.", i + 1, ci->key);
 131       return (-1);
 132     }
 133   }
 134
 135   array_len = *ret_array_len;
 136   array = (char **) realloc (*ret_array,
 137       sizeof (char *) * (array_len + ci->values_num));
 138   if (array == NULL)
 139   {
 140     ERROR ("db query utils: realloc failed.");
 141     return (-1);
 142   }
 143   *ret_array = array;
 144
 145   for (i = 0; i < ci->values_num; i++)
 146   {
 147     array[array_len] = strdup (ci->values[i].value.string);
 148     if (array[array_len] == NULL)
 149     {
 150       ERROR ("db query utils: strdup failed.");
 151       *ret_array_len = array_len;
 152       return (-1);
 153     }
 154     array_len++;
 155   }
 156
 157   *ret_array_len = array_len;
 158   return (0);
 159 } /* }}} int udb_config_add_string */
 160
 161 static int udb_config_set_uint (unsigned int *ret_value, /* {{{ */
 162     oconfig_item_t *ci)
 163 {
 164   double tmp;
 165
 166   if ((ci->values_num != 1)
 167       || (ci->values[0].type != OCONFIG_TYPE_NUMBER))
 168   {
 169     WARNING ("db query utils: The `%s' config option "
 170         "needs exactly one numeric argument.", ci->key);
 171     return (-1);
 172   }
 173
 174   tmp = ci->values[0].value.number;
 175   if ((tmp < 0.0) || (tmp > ((double) UINT_MAX)))
 176     return (-ERANGE);
 177
 178   *ret_value = (unsigned int) (tmp + .5);
 179   return (0);
 180 } /* }}} int udb_config_set_uint */
 181
 182 /*
 183  * Result private functions
 184  */
 185 static int udb_result_submit (udb_result_t *r, /* {{{ */
 186     udb_result_preparation_area_t *r_area,
 187     udb_query_t const *q, udb_query_preparation_area_t *q_area)
 188 {
 189   value_list_t vl = VALUE_LIST_INIT;
 190   size_t i;
 191
 192   assert (r != NULL);
 193   assert (r_area->ds != NULL);
 194   assert (((size_t) r_area->ds->ds_num) == r->values_num);
 195
 196   vl.values = (value_t *) calloc (r_area->ds->ds_num, sizeof (value_t));
 197   if (vl.values == NULL)
 198   {
 199     ERROR ("db query utils: malloc failed.");
 200     return (-1);
 201   }
 202   vl.values_len = r_area->ds->ds_num;
 203
 204   for (i = 0; i < r->values_num; i++)
 205   {
 206     char *value_str = r_area->values_buffer[i];
 207
 208     if (0 != parse_value (value_str, &vl.values[i], r_area->ds->ds[i].type))
 209     {
 210       ERROR ("db query utils: udb_result_submit: Parsing `%s' as %s failed.",
 211           value_str, DS_TYPE_TO_STRING (r_area->ds->ds[i].type));
 212       errno = EINVAL;
 213       return (-1);
 214     }
 215   }
 216
 217   if (q_area->interval > 0)
 218     vl.interval = q_area->interval;
 219
 220   sstrncpy (vl.host, q_area->host, sizeof (vl.host));
 221   sstrncpy (vl.plugin, q_area->plugin, sizeof (vl.plugin));
 222   sstrncpy (vl.plugin_instance, q_area->db_name, sizeof (vl.plugin_instance));
 223   sstrncpy (vl.type, r->type, sizeof (vl.type));
 224
 225   /* Set vl.type_instance {{{ */
 226   if (r->instances_num <= 0)
 227   {
 228     if (r->instance_prefix == NULL)
 229       vl.type_instance[0] = 0;
 230     else
 231       sstrncpy (vl.type_instance, r->instance_prefix,
 232           sizeof (vl.type_instance));
 233   }
 234   else /* if ((r->instances_num > 0) */
 235   {
 236     if (r->instance_prefix == NULL)
 237     {
 238       strjoin (vl.type_instance, sizeof (vl.type_instance),
 239           r_area->instances_buffer, r->instances_num, "-");
 240     }
 241     else
 242     {
 243       char tmp[DATA_MAX_NAME_LEN];
 244
 245       strjoin (tmp, sizeof (tmp), r_area->instances_buffer,
 246           r->instances_num, "-");
 247       tmp[sizeof (tmp) - 1] = 0;
 248
 249       snprintf (vl.type_instance, sizeof (vl.type_instance), "%s-%s",
 250           r->instance_prefix, tmp);
 251     }
 252   }
 253   vl.type_instance[sizeof (vl.type_instance) - 1] = 0;
 254   /* }}} */
 255
 256   plugin_dispatch_values (&vl);
 257
 258   sfree (vl.values);
 259   return (0);
 260 } /* }}} void udb_result_submit */
 261
 262 static void udb_result_finish_result (udb_result_t const *r, /* {{{ */
 263     udb_result_preparation_area_t *prep_area)
 264 {
 265   if ((r == NULL) || (prep_area == NULL))
 266     return;
 267
 268   prep_area->ds = NULL;
 269   sfree (prep_area->instances_pos);
 270   sfree (prep_area->values_pos);
 271   sfree (prep_area->instances_buffer);
 272   sfree (prep_area->values_buffer);
 273 } /* }}} void udb_result_finish_result */
 274
 275 static int udb_result_handle_result (udb_result_t *r, /* {{{ */
 276     udb_query_preparation_area_t *q_area,
 277     udb_result_preparation_area_t *r_area,
 278     udb_query_t const *q, char **column_values)
 279 {
 280   size_t i;
 281
 282   assert (r && q_area && r_area);
 283
 284   for (i = 0; i < r->instances_num; i++)
 285     r_area->instances_buffer[i] = column_values[r_area->instances_pos[i]];
 286
 287   for (i = 0; i < r->values_num; i++)
 288     r_area->values_buffer[i] = column_values[r_area->values_pos[i]];
 289
 290   return udb_result_submit (r, r_area, q, q_area);
 291 } /* }}} int udb_result_handle_result */
 292
 293 static int udb_result_prepare_result (udb_result_t const *r, /* {{{ */
 294     udb_result_preparation_area_t *prep_area,
 295     char **column_names, size_t column_num)
 296 {
 297   size_t i;
 298
 299   if ((r == NULL) || (prep_area == NULL))
 300     return (-EINVAL);
 301
 302 #define BAIL_OUT(status) \
 303   prep_area->ds = NULL; \
 304   sfree (prep_area->instances_pos); \
 305   sfree (prep_area->values_pos); \
 306   sfree (prep_area->instances_buffer); \
 307   sfree (prep_area->values_buffer); \
 308   return (status)
 309
 310   /* Make sure previous preparations are cleaned up. */
 311   udb_result_finish_result (r, prep_area);
 312   prep_area->instances_pos = NULL;
 313   prep_area->values_pos = NULL;
 314
 315   /* Read `ds' and check number of values {{{ */
 316   prep_area->ds = plugin_get_ds (r->type);
 317   if (prep_area->ds == NULL)
 318   {
 319     ERROR ("db query utils: udb_result_prepare_result: Type `%s' is not "
 320         "known by the daemon. See types.db(5) for details.",
 321         r->type);
 322     BAIL_OUT (-1);
 323   }
 324
 325   if (((size_t) prep_area->ds->ds_num) != r->values_num)
 326   {
 327     ERROR ("db query utils: udb_result_prepare_result: The type `%s' "
 328         "requires exactly %i value%s, but the configuration specifies %zu.",
 329         r->type,
 330         prep_area->ds->ds_num, (prep_area->ds->ds_num == 1) ? "" : "s",
 331         r->values_num);
 332     BAIL_OUT (-1);
 333   }
 334   /* }}} */
 335
 336   /* Allocate r->instances_pos, r->values_pos, r->instances_buffer, and
 337    * r->values_buffer {{{ */
 338   if (r->instances_num > 0)
 339   {
 340     prep_area->instances_pos
 341       = (size_t *) calloc (r->instances_num, sizeof (size_t));
 342     if (prep_area->instances_pos == NULL)
 343     {
 344       ERROR ("db query utils: udb_result_prepare_result: malloc failed.");
 345       BAIL_OUT (-ENOMEM);
 346     }
 347
 348     prep_area->instances_buffer
 349       = (char **) calloc (r->instances_num, sizeof (char *));
 350     if (prep_area->instances_buffer == NULL)
 351     {
 352       ERROR ("db query utils: udb_result_prepare_result: malloc failed.");
 353       BAIL_OUT (-ENOMEM);
 354     }
 355   } /* if (r->instances_num > 0) */
 356
 357   prep_area->values_pos
 358     = (size_t *) calloc (r->values_num, sizeof (size_t));
 359   if (prep_area->values_pos == NULL)
 360   {
 361     ERROR ("db query utils: udb_result_prepare_result: malloc failed.");
 362     BAIL_OUT (-ENOMEM);
 363   }
 364
 365   prep_area->values_buffer
 366     = (char **) calloc (r->values_num, sizeof (char *));
 367   if (prep_area->values_buffer == NULL)
 368   {
 369     ERROR ("db query utils: udb_result_prepare_result: malloc failed.");
 370     BAIL_OUT (-ENOMEM);
 371   }
 372   /* }}} */
 373
 374   /* Determine the position of the instance columns {{{ */
 375   for (i = 0; i < r->instances_num; i++)
 376   {
 377     size_t j;
 378
 379     for (j = 0; j < column_num; j++)
 380     {
 381       if (strcasecmp (r->instances[i], column_names[j]) == 0)
 382       {
 383         prep_area->instances_pos[i] = j;
 384         break;
 385       }
 386     }
 387
 388     if (j >= column_num)
 389     {
 390       ERROR ("db query utils: udb_result_prepare_result: "
 391           "Column `%s' could not be found.",
 392           r->instances[i]);
 393       BAIL_OUT (-ENOENT);
 394     }
 395   } /* }}} for (i = 0; i < r->instances_num; i++) */
 396
 397   /* Determine the position of the value columns {{{ */
 398   for (i = 0; i < r->values_num; i++)
 399   {
 400     size_t j;
 401
 402     for (j = 0; j < column_num; j++)
 403     {
 404       if (strcasecmp (r->values[i], column_names[j]) == 0)
 405       {
 406         prep_area->values_pos[i] = j;
 407         break;
 408       }
 409     }
 410
 411     if (j >= column_num)
 412     {
 413       ERROR ("db query utils: udb_result_prepare_result: "
 414           "Column `%s' could not be found.",
 415           r->values[i]);
 416       BAIL_OUT (-ENOENT);
 417     }
 418   } /* }}} for (i = 0; i < r->values_num; i++) */
 419
 420 #undef BAIL_OUT
 421   return (0);
 422 } /* }}} int udb_result_prepare_result */
 423
 424 static void udb_result_free (udb_result_t *r) /* {{{ */
 425 {
 426   size_t i;
 427
 428   if (r == NULL)
 429     return;
 430
 431   sfree (r->type);
 432
 433   for (i = 0; i < r->instances_num; i++)
 434     sfree (r->instances[i]);
 435   sfree (r->instances);
 436
 437   for (i = 0; i < r->values_num; i++)
 438     sfree (r->values[i]);
 439   sfree (r->values);
 440
 441   udb_result_free (r->next);
 442
 443   sfree (r);
 444 } /* }}} void udb_result_free */
 445
 446 static int udb_result_create (const char *query_name, /* {{{ */
 447     udb_result_t **r_head, oconfig_item_t *ci)
 448 {
 449   udb_result_t *r;
 450   int status;
 451   int i;
 452
 453   if (ci->values_num != 0)
 454   {
 455     WARNING ("db query utils: The `Result' block doesn't accept "
 456         "any arguments. Ignoring %i argument%s.",
 457         ci->values_num, (ci->values_num == 1) ? "" : "s");
 458   }
 459
 460   r = (udb_result_t *) malloc (sizeof (*r));
 461   if (r == NULL)
 462   {
 463     ERROR ("db query utils: malloc failed.");
 464     return (-1);
 465   }
 466   memset (r, 0, sizeof (*r));
 467   r->type = NULL;
 468   r->instance_prefix = NULL;
 469   r->instances = NULL;
 470   r->values = NULL;
 471   r->next = NULL;
 472
 473   /* Fill the `udb_result_t' structure.. */
 474   status = 0;
 475   for (i = 0; i < ci->children_num; i++)
 476   {
 477     oconfig_item_t *child = ci->children + i;
 478
 479     if (strcasecmp ("Type", child->key) == 0)
 480       status = udb_config_set_string (&r->type, child);
 481     else if (strcasecmp ("InstancePrefix", child->key) == 0)
 482       status = udb_config_set_string (&r->instance_prefix, child);
 483     else if (strcasecmp ("InstancesFrom", child->key) == 0)
 484       status = udb_config_add_string (&r->instances, &r->instances_num, child);
 485     else if (strcasecmp ("ValuesFrom", child->key) == 0)
 486       status = udb_config_add_string (&r->values, &r->values_num, child);
 487     else
 488     {
 489       WARNING ("db query utils: Query `%s': Option `%s' not allowed here.",
 490           query_name, child->key);
 491       status = -1;
 492     }
 493
 494     if (status != 0)
 495       break;
 496   }
 497
 498   /* Check that all necessary options have been given. */
 499   while (status == 0)
 500   {
 501     if (r->type == NULL)
 502     {
 503       WARNING ("db query utils: `Type' not given for "
 504           "result in query `%s'", query_name);
 505       status = -1;
 506     }
 507     if (r->values == NULL)
 508     {
 509       WARNING ("db query utils: `ValuesFrom' not given for "
 510           "result in query `%s'", query_name);
 511       status = -1;
 512     }
 513
 514     break;
 515   } /* while (status == 0) */
 516
 517   if (status != 0)
 518   {
 519     udb_result_free (r);
 520     return (-1);
 521   }
 522
 523   /* If all went well, add this result to the list of results. */
 524   if (*r_head == NULL)
 525   {
 526     *r_head = r;
 527   }
 528   else
 529   {
 530     udb_result_t *last;
 531
 532     last = *r_head;
 533     while (last->next != NULL)
 534       last = last->next;
 535
 536     last->next = r;
 537   }
 538
 539   return (0);
 540 } /* }}} int udb_result_create */
 541
 542 /*
 543  * Query private functions
 544  */
 545 void udb_query_free_one (udb_query_t *q) /* {{{ */
 546 {
 547   if (q == NULL)
 548     return;
 549
 550   sfree (q->name);
 551   sfree (q->statement);
 552
 553   udb_result_free (q->results);
 554
 555   sfree (q);
 556 } /* }}} void udb_query_free_one */
 557
 558 /*
 559  * Query public functions
 560  */
 561 int udb_query_create (udb_query_t ***ret_query_list, /* {{{ */
 562     size_t *ret_query_list_len, oconfig_item_t *ci,
 563     udb_query_create_callback_t cb)
 564 {
 565   udb_query_t **query_list;
 566   size_t        query_list_len;
 567
 568   udb_query_t *q;
 569   int status;
 570   int i;
 571
 572   if ((ret_query_list == NULL) || (ret_query_list_len == NULL))
 573     return (-EINVAL);
 574   query_list     = *ret_query_list;
 575   query_list_len = *ret_query_list_len;
 576
 577   if ((ci->values_num != 1)
 578       || (ci->values[0].type != OCONFIG_TYPE_STRING))
 579   {
 580     WARNING ("db query utils: The `Query' block "
 581         "needs exactly one string argument.");
 582     return (-1);
 583   }
 584
 585   q = (udb_query_t *) malloc (sizeof (*q));
 586   if (q == NULL)
 587   {
 588     ERROR ("db query utils: malloc failed.");
 589     return (-1);
 590   }
 591   memset (q, 0, sizeof (*q));
 592   q->min_version = 0;
 593   q->max_version = UINT_MAX;
 594
 595   status = udb_config_set_string (&q->name, ci);
 596   if (status != 0)
 597   {
 598     sfree (q);
 599     return (status);
 600   }
 601
 602   /* Fill the `udb_query_t' structure.. */
 603   for (i = 0; i < ci->children_num; i++)
 604   {
 605     oconfig_item_t *child = ci->children + i;
 606
 607     if (strcasecmp ("Statement", child->key) == 0)
 608       status = udb_config_set_string (&q->statement, child);
 609     else if (strcasecmp ("Result", child->key) == 0)
 610       status = udb_result_create (q->name, &q->results, child);
 611     else if (strcasecmp ("MinVersion", child->key) == 0)
 612       status = udb_config_set_uint (&q->min_version, child);
 613     else if (strcasecmp ("MaxVersion", child->key) == 0)
 614       status = udb_config_set_uint (&q->max_version, child);
 615
 616     /* Call custom callbacks */
 617     else if (cb != NULL)
 618     {
 619       status = (*cb) (q, child);
 620       if (status != 0)
 621       {
 622         WARNING ("db query utils: The configuration callback failed "
 623             "to handle `%s'.", child->key);
 624       }
 625     }
 626     else
 627     {
 628       WARNING ("db query utils: Query `%s': Option `%s' not allowed here.",
 629           q->name, child->key);
 630       status = -1;
 631     }
 632
 633     if (status != 0)
 634       break;
 635   }
 636
 637   /* Check that all necessary options have been given. */
 638   if (status == 0)
 639   {
 640     if (q->statement == NULL)
 641     {
 642       WARNING ("db query utils: Query `%s': No `Statement' given.", q->name);
 643       status = -1;
 644     }
 645     if (q->results == NULL)
 646     {
 647       WARNING ("db query utils: Query `%s': No (valid) `Result' block given.",
 648           q->name);
 649       status = -1;
 650     }
 651   } /* if (status == 0) */
 652
 653   /* If all went well, add this query to the list of queries within the
 654    * database structure. */
 655   if (status == 0)
 656   {
 657     udb_query_t **temp;
 658
 659     temp = (udb_query_t **) realloc (query_list,
 660         sizeof (*query_list) * (query_list_len + 1));
 661     if (temp == NULL)
 662     {
 663       ERROR ("db query utils: realloc failed");
 664       status = -1;
 665     }
 666     else
 667     {
 668       query_list = temp;
 669       query_list[query_list_len] = q;
 670       query_list_len++;
 671     }
 672   }
 673
 674   if (status != 0)
 675   {
 676     udb_query_free_one (q);
 677     return (-1);
 678   }
 679
 680   *ret_query_list     = query_list;
 681   *ret_query_list_len = query_list_len;
 682
 683   return (0);
 684 } /* }}} int udb_query_create */
 685
 686 void udb_query_free (udb_query_t **query_list, size_t query_list_len) /* {{{ */
 687 {
 688   size_t i;
 689
 690   if (query_list == NULL)
 691     return;
 692
 693   for (i = 0; i < query_list_len; i++)
 694     udb_query_free_one (query_list[i]);
 695
 696   sfree (query_list);
 697 } /* }}} void udb_query_free */
 698
 699 int udb_query_pick_from_list_by_name (const char *name, /* {{{ */
 700     udb_query_t **src_list, size_t src_list_len,
 701     udb_query_t ***dst_list, size_t *dst_list_len)
 702 {
 703   size_t i;
 704   int num_added;
 705
 706   if ((name == NULL) || (src_list == NULL) || (dst_list == NULL)
 707       || (dst_list_len == NULL))
 708   {
 709     ERROR ("db query utils: udb_query_pick_from_list_by_name: "
 710         "Invalid argument.");
 711     return (-EINVAL);
 712   }
 713
 714   num_added = 0;
 715   for (i = 0; i < src_list_len; i++)
 716   {
 717     udb_query_t **tmp_list;
 718     size_t tmp_list_len;
 719
 720     if (strcasecmp (name, src_list[i]->name) != 0)
 721       continue;
 722
 723     tmp_list_len = *dst_list_len;
 724     tmp_list = (udb_query_t **) realloc (*dst_list, (tmp_list_len + 1)
 725         * sizeof (udb_query_t *));
 726     if (tmp_list == NULL)
 727     {
 728       ERROR ("db query utils: realloc failed.");
 729       return (-ENOMEM);
 730     }
 731
 732     tmp_list[tmp_list_len] = src_list[i];
 733     tmp_list_len++;
 734
 735     *dst_list = tmp_list;
 736     *dst_list_len = tmp_list_len;
 737
 738     num_added++;
 739   } /* for (i = 0; i < src_list_len; i++) */
 740
 741   if (num_added <= 0)
 742   {
 743     ERROR ("db query utils: Cannot find query `%s'. Make sure the <Query> "
 744         "block is above the database definition!",
 745         name);
 746     return (-ENOENT);
 747   }
 748   else
 749   {
 750     DEBUG ("db query utils: Added %i versions of query `%s'.",
 751         num_added, name);
 752   }
 753
 754   return (0);
 755 } /* }}} int udb_query_pick_from_list_by_name */
 756
 757 int udb_query_pick_from_list (oconfig_item_t *ci, /* {{{ */
 758     udb_query_t **src_list, size_t src_list_len,
 759     udb_query_t ***dst_list, size_t *dst_list_len)
 760 {
 761   const char *name;
 762
 763   if ((ci == NULL) || (src_list == NULL) || (dst_list == NULL)
 764       || (dst_list_len == NULL))
 765   {
 766     ERROR ("db query utils: udb_query_pick_from_list: "
 767         "Invalid argument.");
 768     return (-EINVAL);
 769   }
 770
 771   if ((ci->values_num != 1)
 772       || (ci->values[0].type != OCONFIG_TYPE_STRING))
 773   {
 774     ERROR ("db query utils: The `%s' config option "
 775         "needs exactly one string argument.", ci->key);
 776     return (-1);
 777   }
 778   name = ci->values[0].value.string;
 779
 780   return (udb_query_pick_from_list_by_name (name,
 781         src_list, src_list_len,
 782         dst_list, dst_list_len));
 783 } /* }}} int udb_query_pick_from_list */
 784
 785 const char *udb_query_get_name (udb_query_t *q) /* {{{ */
 786 {
 787   if (q == NULL)
 788     return (NULL);
 789
 790   return (q->name);
 791 } /* }}} const char *udb_query_get_name */
 792
 793 const char *udb_query_get_statement (udb_query_t *q) /* {{{ */
 794 {
 795   if (q == NULL)
 796     return (NULL);
 797
 798   return (q->statement);
 799 } /* }}} const char *udb_query_get_statement */
 800
 801 void udb_query_set_user_data (udb_query_t *q, void *user_data) /* {{{ */
 802 {
 803   if (q == NULL)
 804     return;
 805
 806   q->user_data = user_data;
 807 } /* }}} void udb_query_set_user_data */
 808
 809 void *udb_query_get_user_data (udb_query_t *q) /* {{{ */
 810 {
 811   if (q == NULL)
 812     return (NULL);
 813
 814   return (q->user_data);
 815 } /* }}} void *udb_query_get_user_data */
 816
 817 int udb_query_check_version (udb_query_t *q, unsigned int version) /* {{{ */
 818 {
 819   if (q == NULL)
 820     return (-EINVAL);
 821
 822   if ((version < q->min_version) || (version > q->max_version))
 823     return (0);
 824
 825   return (1);
 826 } /* }}} int udb_query_check_version */
 827
 828 void udb_query_finish_result (udb_query_t const *q, /* {{{ */
 829     udb_query_preparation_area_t *prep_area)
 830 {
 831   udb_result_preparation_area_t *r_area;
 832   udb_result_t *r;
 833
 834   if ((q == NULL) || (prep_area == NULL))
 835     return;
 836
 837   prep_area->column_num = 0;
 838   sfree (prep_area->host);
 839   sfree (prep_area->plugin);
 840   sfree (prep_area->db_name);
 841
 842   prep_area->interval = 0;
 843
 844   for (r = q->results, r_area = prep_area->result_prep_areas;
 845       r != NULL; r = r->next, r_area = r_area->next)
 846   {
 847     /* this may happen during error conditions of the caller */
 848     if (r_area == NULL)
 849       break;
 850     udb_result_finish_result (r, r_area);
 851   }
 852 } /* }}} void udb_query_finish_result */
 853
 854 int udb_query_handle_result (udb_query_t const *q, /* {{{ */
 855     udb_query_preparation_area_t *prep_area, char **column_values)
 856 {
 857   udb_result_preparation_area_t *r_area;
 858   udb_result_t *r;
 859   int success;
 860   int status;
 861
 862   if ((q == NULL) || (prep_area == NULL))
 863     return (-EINVAL);
 864
 865   if ((prep_area->column_num < 1) || (prep_area->host == NULL)
 866       || (prep_area->plugin == NULL) || (prep_area->db_name == NULL))
 867   {
 868     ERROR ("db query utils: Query `%s': Query is not prepared; "
 869         "can't handle result.", q->name);
 870     return (-EINVAL);
 871   }
 872
 873 #if defined(COLLECT_DEBUG) && COLLECT_DEBUG /* {{{ */
 874   do
 875   {
 876     size_t i;
 877
 878     for (i = 0; i < prep_area->column_num; i++)
 879     {
 880       DEBUG ("db query utils: udb_query_handle_result (%s, %s): "
 881           "column[%zu] = %s;",
 882           prep_area->db_name, q->name, i, column_values[i]);
 883     }
 884   } while (0);
 885 #endif /* }}} */
 886
 887   success = 0;
 888   for (r = q->results, r_area = prep_area->result_prep_areas;
 889       r != NULL; r = r->next, r_area = r_area->next)
 890   {
 891     status = udb_result_handle_result (r, prep_area, r_area,
 892         q, column_values);
 893     if (status == 0)
 894       success++;
 895   }
 896
 897   if (success == 0)
 898   {
 899     ERROR ("db query utils: udb_query_handle_result (%s, %s): "
 900         "All results failed.", prep_area->db_name, q->name);
 901     return (-1);
 902   }
 903
 904   return (0);
 905 } /* }}} int udb_query_handle_result */
 906
 907 int udb_query_prepare_result (udb_query_t const *q, /* {{{ */
 908     udb_query_preparation_area_t *prep_area,
 909     const char *host, const char *plugin, const char *db_name,
 910     char **column_names, size_t column_num, cdtime_t interval)
 911 {
 912   udb_result_preparation_area_t *r_area;
 913   udb_result_t *r;
 914   int status;
 915
 916   if ((q == NULL) || (prep_area == NULL))
 917     return (-EINVAL);
 918
 919   udb_query_finish_result (q, prep_area);
 920
 921   prep_area->column_num = column_num;
 922   prep_area->host = strdup (host);
 923   prep_area->plugin = strdup (plugin);
 924   prep_area->db_name = strdup (db_name);
 925
 926   prep_area->interval = interval;
 927
 928   if ((prep_area->host == NULL) || (prep_area->plugin == NULL)
 929       || (prep_area->db_name == NULL))
 930   {
 931     ERROR ("db query utils: Query `%s': Prepare failed: Out of memory.", q->name);
 932     udb_query_finish_result (q, prep_area);
 933     return (-ENOMEM);
 934   }
 935
 936 #if defined(COLLECT_DEBUG) && COLLECT_DEBUG
 937   do
 938   {
 939     size_t i;
 940
 941     for (i = 0; i < column_num; i++)
 942     {
 943       DEBUG ("db query utils: udb_query_prepare_result: "
 944           "query = %s; column[%zu] = %s;",
 945           q->name, i, column_names[i]);
 946     }
 947   } while (0);
 948 #endif
 949
 950   for (r = q->results, r_area = prep_area->result_prep_areas;
 951       r != NULL; r = r->next, r_area = r_area->next)
 952   {
 953     if (! r_area)
 954     {
 955       ERROR ("db query utils: Query `%s': Invalid number of result "
 956           "preparation areas.", q->name);
 957       udb_query_finish_result (q, prep_area);
 958       return (-EINVAL);
 959     }
 960
 961     status = udb_result_prepare_result (r, r_area, column_names, column_num);
 962     if (status != 0)
 963     {
 964       udb_query_finish_result (q, prep_area);
 965       return (status);
 966     }
 967   }
 968
 969   return (0);
 970 } /* }}} int udb_query_prepare_result */
 971
 972 udb_query_preparation_area_t *
 973 udb_query_allocate_preparation_area (udb_query_t *q) /* {{{ */
 974 {
 975   udb_query_preparation_area_t   *q_area;
 976   udb_result_preparation_area_t **next_r_area;
 977   udb_result_t *r;
 978
 979   q_area = (udb_query_preparation_area_t *)malloc (sizeof (*q_area));
 980   if (q_area == NULL)
 981     return NULL;
 982
 983   memset (q_area, 0, sizeof (*q_area));
 984
 985   next_r_area = &q_area->result_prep_areas;
 986   for (r = q->results; r != NULL; r = r->next)
 987   {
 988     udb_result_preparation_area_t *r_area;
 989
 990     r_area = (udb_result_preparation_area_t *)malloc (sizeof (*r_area));
 991     if (r_area == NULL)
 992     {
 993       for (r_area = q_area->result_prep_areas;
 994           r_area != NULL; r_area = r_area->next)
 995       {
 996         free (r_area);
 997       }
 998       free (q_area);
 999       return NULL;
1000     }
1001
1002     memset (r_area, 0, sizeof (*r_area));
1003
1004     *next_r_area = r_area;
1005     next_r_area  = &r_area->next;
1006   }
1007
1008   return (q_area);
1009 } /* }}} udb_query_preparation_area_t *udb_query_allocate_preparation_area */
1010
1011 void
1012 udb_query_delete_preparation_area (udb_query_preparation_area_t *q_area) /* {{{ */
1013 {
1014   udb_result_preparation_area_t *r_area;
1015
1016   if (q_area == NULL)
1017     return;
1018
1019   r_area = q_area->result_prep_areas;
1020   while (r_area != NULL)
1021   {
1022     udb_result_preparation_area_t *area = r_area;
1023
1024     r_area = r_area->next;
1025
1026     sfree (area->instances_pos);
1027     sfree (area->values_pos);
1028     sfree (area->instances_buffer);
1029     sfree (area->values_buffer);
1030     free (area);
1031   }
1032
1033   sfree (q_area->host);
1034   sfree (q_area->plugin);
1035   sfree (q_area->db_name);
1036
1037   free (q_area);
1038 } /* }}} void udb_query_delete_preparation_area */
1039
1040 /* vim: set sw=2 sts=2 et fdm=marker : */