QUICK_START

   1 This document describes the steps which have to be performed in order
   2 to create and use an osl table. The code sniplets in this section
   3 are taken from the file `osltar.c` in the source distribution.
   4
   5 The complete API reference is contained in the file `osl.h.`
   6
   7 Define an enum that assigns descriptive names to the columns
   8 of your table. Example:
   9
  10 <pre>
  11         enum osltar_columns {
  12                 OTC_NAME,
  13                 OTC_DATA,
  14                 NUM_OT_COLUMNS
  15         };
  16 </pre>
  17
  18 The last element is is useful because the number of columns of your
  19 table must be specified later, see below.
  20
  21 Define an array of struct osl_column_description, one array member
  22 per column:
  23
  24 <pre>
  25         struct osl_column_description tar_table_cols[] = {
  26                 [OTC_NAME] = {
  27                         .storage_type = OSL_MAPPED_STORAGE,
  28                         .storage_flags = OSL_RBTREE | OSL_UNIQUE,
  29                         .name = "filename",
  30                         .compare_function = string_compare,
  31                 },
  32                 [OTC_DATA] = {
  33                         .storage_type = OSL_MAPPED_STORAGE,
  34                         .name = "data",
  35                 },
  36         };
  37 </pre>
  38
  39 Three different storage types are available which may be selected
  40 on a per-column basis: `OSL_DISK_STORAGE`, `OSL_MAPPED_STORAGE`, and
  41 `OSL_NO_STORAGE`.
  42
  43 For columns of type `OSL_MAPPED_STORAGE` and `OSL_NO_STORAGE` an
  44 optional rbtree is maintained by the osl library which allows to
  45 quickly lookup rows by cell content. Whether or not an rbtree should
  46 be used must be specified in the `storage_flags` field which should
  47 contain the bitwise or of suitable `osl_storage_flags`.
  48
  49 If a column has an associated rbtree, i.e. if the `OSL_RBTREE` flag
  50 is set in the storage flags for the column, the `compare_function`
  51 field must be initialized to point to a function of type
  52 `osl_compare_func`. In this example, `string_compare()` is used,
  53 which is just a wrapper for `strcmp()` that interprets osl objects
  54 as C-strings and calls `strcmp()` on the object data.
  55
  56 Define a struct `osl_table_description` and initialize it with
  57 the number of columns of your table and the column descriptions:
  58
  59 <pre>
  60         struct osl_table_description tar_table_desc = {
  61                 .name = "tar_table",
  62                 .num_columns = NUM_OT_COLUMNS,
  63                 .column_descriptions = tar_table_cols,
  64                 .dir = "/tmp/osltest"
  65         };
  66 </pre>
  67
  68 Create the table by calling `osl_create_table()`:
  69
  70 <pre>
  71         ret = osl_create_table(&tar_table_desc);
  72 </pre>
  73
  74 Open the newly created table by calling `osl_open_table()`:
  75
  76 <pre>
  77         struct osl_table *table;
  78         ret = osl_open_table(&tar_table_desc, &table);
  79 </pre>
  80
  81 To add a new row to the table, you must define an array of struct
  82 osl_object of length `NUM_OT_COLUMNS` which holds the contents of
  83 the new row. Note that an osl object is just a blob: It consists of
  84 a data pointer and a size value. Once the array has been initialized,
  85 pass it to `osl_add_row()` together with the table handle obtained from
  86 `osl_open_table()`:
  87
  88 <pre>
  89         struct osl_object objs[NUM_OT_COLUMNS];
  90         /* ...init the array... */
  91         ret = osl_add_row(table, objs);
  92 </pre>
  93
  94 Close the table with `osl_close_table()`.
  95
  96 <pre>
  97         osl_close_table(table, OSL_MARK_CLEAN);
  98 </pre>
  99
 100 The storage type of both columns of the table in this example is
 101 `OSL_MAPPED_STORAGE`, so you can later open the table again and
 102 retrieve its contents:
 103
 104 <pre>
 105         ret = osl_get_row(table, OTC_NAME, &obj, &row);
 106         if (ret < 0) {
 107                 fprintf(stderr, "osl_get_row(%s): %s\n", name,
 108                         osl_strerror(-ret));
 109                 return ret;
 110         }
 111         ret = osl_get_object(table, row, OTC_DATA, &obj);
 112 </pre>
 113
 114 The call to `osl_get_row()` uses the rbtree of the `OTC_NAME`
 115 column to find the row whose object in the `OTC_NAME` column
 116 matches the given object `obj`. If a row was found, it is
 117 passed to `osl_get_object()` which returns the object of
 118 the `OTC_DATA` column of this row.
 119
 120 This concludes the quick start document. Of course, libosl contains
 121 many more public functions than those used above. For details on the
 122 C-API, look at the file `osl.h` which contains the declarations of
 123 all public functions and the complete documentation of the public
 124 part of the library.
 125
 126 The "examples" subdirectory of the source distribution
 127 contains the full code of the above example and another
 128 small program which illustrates the use of columns of type
 129 `OSL_NO_STORAGE`. Larger applications using libosl are <a
 130 href="http://people.tuebingen.mpg.de/maan/paraslash/">paraslash</a>,
 131 a network audio streaming system, and <a
 132 href="http://people.tuebingen.mpg.de/maan/adu/">adu</a>, the advanced
 133 disk usage tool.