aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2011-07-24 16:11:08 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2011-07-24 16:11:08 +0200
commit8a288c54e5d1a5aacc115515f335ed6224e34459 (patch)
treedc2748866490957b341f45860312d442c082a629
parent319def6da0c6d17c29f66c0ea5837a58988a67d7 (diff)
Document default and options pragmas
-rw-r--r--doc/manual.xhtml759
1 files changed, 603 insertions, 156 deletions
diff --git a/doc/manual.xhtml b/doc/manual.xhtml
index bb505e2..0b60ab2 100644
--- a/doc/manual.xhtml
+++ b/doc/manual.xhtml
@@ -424,15 +424,21 @@ for consistency.
<tr><th>10.2.1</th><td><a href="#10.2.1"><code>type</code></a></td></tr>
<tr><th>10.2.2</th><td><a href="#10.2.2"><code>id_type</code></a></td></tr>
<tr><th>10.2.3</th><td><a href="#10.2.3"><code>null</code>/<code>not_null</code></a></td></tr>
- <tr><th>10.2.4</th><td><a href="#10.2.4"><code>unordered</code></a></td></tr>
- <tr><th>10.2.5</th><td><a href="#10.2.5"><code>index_type</code></a></td></tr>
- <tr><th>10.2.6</th><td><a href="#10.2.6"><code>key_type</code></a></td></tr>
- <tr><th>10.2.7</th><td><a href="#10.2.7"><code>value_type</code></a></td></tr>
- <tr><th>10.2.8</th><td><a href="#10.2.8"><code>value_null</code>/<code>value_not_null</code></a></td></tr>
- <tr><th>10.2.9</th><td><a href="#10.2.9"><code>id_column</code></a></td></tr>
- <tr><th>10.2.10</th><td><a href="#10.2.10"><code>index_column</code></a></td></tr>
- <tr><th>10.2.11</th><td><a href="#10.2.11"><code>key_column</code></a></td></tr>
- <tr><th>10.2.12</th><td><a href="#10.2.12"><code>value_column</code></a></td></tr>
+ <tr><th>10.2.4</th><td><a href="#10.2.4"><code>default</code></a></td></tr>
+ <tr><th>10.2.5</th><td><a href="#10.2.5"><code>options</code></a></td></tr>
+ <tr><th>10.2.6</th><td><a href="#10.2.6"><code>unordered</code></a></td></tr>
+ <tr><th>10.2.7</th><td><a href="#10.2.7"><code>index_type</code></a></td></tr>
+ <tr><th>10.2.8</th><td><a href="#10.2.8"><code>key_type</code></a></td></tr>
+ <tr><th>10.2.9</th><td><a href="#10.2.9"><code>value_type</code></a></td></tr>
+ <tr><th>10.2.10</th><td><a href="#10.2.10"><code>value_null</code>/<code>value_not_null</code></a></td></tr>
+ <tr><th>10.2.11</th><td><a href="#10.2.11"><code>id_options</code></a></td></tr>
+ <tr><th>10.2.12</th><td><a href="#10.2.12"><code>index_options</code></a></td></tr>
+ <tr><th>10.2.13</th><td><a href="#10.2.13"><code>key_options</code></a></td></tr>
+ <tr><th>10.2.14</th><td><a href="#10.2.14"><code>value_options</code></a></td></tr>
+ <tr><th>10.2.15</th><td><a href="#10.2.15"><code>id_column</code></a></td></tr>
+ <tr><th>10.2.16</th><td><a href="#10.2.16"><code>index_column</code></a></td></tr>
+ <tr><th>10.2.17</th><td><a href="#10.2.17"><code>key_column</code></a></td></tr>
+ <tr><th>10.2.18</th><td><a href="#10.2.18"><code>value_column</code></a></td></tr>
</table>
</td>
</tr>
@@ -443,19 +449,25 @@ for consistency.
<tr><th>10.3.2</th><td><a href="#10.3.2"><code>auto</code></a></td></tr>
<tr><th>10.3.3</th><td><a href="#10.3.3"><code>type</code></a></td></tr>
<tr><th>10.3.4</th><td><a href="#10.3.4"><code>null</code>/<code>not_null</code></a></td></tr>
- <tr><th>10.3.5</th><td><a href="#10.3.5"><code>column</code></a></td></tr>
- <tr><th>10.3.6</th><td><a href="#10.3.6"><code>transient</code></a></td></tr>
- <tr><th>10.3.7</th><td><a href="#10.3.7"><code>inverse</code></a></td></tr>
- <tr><th>10.3.8</th><td><a href="#10.3.8"><code>unordered</code></a></td></tr>
- <tr><th>10.3.9</th><td><a href="#10.3.9"><code>table</code></a></td></tr>
- <tr><th>10.3.10</th><td><a href="#10.3.10"><code>index_type</code></a></td></tr>
- <tr><th>10.3.11</th><td><a href="#10.3.11"><code>key_type</code></a></td></tr>
- <tr><th>10.3.12</th><td><a href="#10.3.12"><code>value_type</code></a></td></tr>
- <tr><th>10.3.13</th><td><a href="#10.3.13"><code>value_null</code>/<code>value_not_null</code></a></td></tr>
- <tr><th>10.3.14</th><td><a href="#10.3.14"><code>id_column</code></a></td></tr>
- <tr><th>10.3.15</th><td><a href="#10.3.15"><code>index_column</code></a></td></tr>
- <tr><th>10.3.16</th><td><a href="#10.3.16"><code>key_column</code></a></td></tr>
- <tr><th>10.3.17</th><td><a href="#10.3.17"><code>value_column</code></a></td></tr>
+ <tr><th>10.3.5</th><td><a href="#10.3.5"><code>default</code></a></td></tr>
+ <tr><th>10.3.6</th><td><a href="#10.3.6"><code>options</code></a></td></tr>
+ <tr><th>10.3.7</th><td><a href="#10.3.7"><code>column</code></a></td></tr>
+ <tr><th>10.3.8</th><td><a href="#10.3.8"><code>transient</code></a></td></tr>
+ <tr><th>10.3.9</th><td><a href="#10.3.9"><code>inverse</code></a></td></tr>
+ <tr><th>10.3.10</th><td><a href="#10.3.10"><code>unordered</code></a></td></tr>
+ <tr><th>10.3.11</th><td><a href="#10.3.11"><code>table</code></a></td></tr>
+ <tr><th>10.3.12</th><td><a href="#10.3.12"><code>index_type</code></a></td></tr>
+ <tr><th>10.3.13</th><td><a href="#10.3.13"><code>key_type</code></a></td></tr>
+ <tr><th>10.3.14</th><td><a href="#10.3.14"><code>value_type</code></a></td></tr>
+ <tr><th>10.3.15</th><td><a href="#10.3.15"><code>value_null</code>/<code>value_not_null</code></a></td></tr>
+ <tr><th>10.3.16</th><td><a href="#10.3.16"><code>id_options</code></a></td></tr>
+ <tr><th>10.3.17</th><td><a href="#10.3.17"><code>index_options</code></a></td></tr>
+ <tr><th>10.3.18</th><td><a href="#10.3.18"><code>key_options</code></a></td></tr>
+ <tr><th>10.3.19</th><td><a href="#10.3.19"><code>value_options</code></a></td></tr>
+ <tr><th>10.3.20</th><td><a href="#10.3.20"><code>id_column</code></a></td></tr>
+ <tr><th>10.3.21</th><td><a href="#10.3.21"><code>index_column</code></a></td></tr>
+ <tr><th>10.3.22</th><td><a href="#10.3.22"><code>key_column</code></a></td></tr>
+ <tr><th>10.3.23</th><td><a href="#10.3.23"><code>value_column</code></a></td></tr>
</table>
</td>
</tr>
@@ -3634,8 +3646,8 @@ private:
the order information. In the example above, for instance, the order
of person's nicknames is probably not important. To instruct the ODB
compiler to ignore the order in ordered containers we can use the
- <code>db&nbsp;unordered</code> pragma (<a href="#10.2.4">Section 10.2.4,
- "<code>unordered</code>"</a>, <a href="#10.3.8">Section 10.3.8,
+ <code>db&nbsp;unordered</code> pragma (<a href="#10.2.6">Section 10.2.6,
+ "<code>unordered</code>"</a>, <a href="#10.3.10">Section 10.3.10,
"<code>unordered</code>"</a>). For example:</p>
<pre class="c++">
@@ -3888,8 +3900,8 @@ class employee
use the <code>not_null</code> pragma (<a href="#10.3.4">Section
10.3.4, "<code>null</code>/<code>not_null</code>"</a>) for
single object pointers and the <code>value_not_null</code> pragma
- (<a href="#10.3.13">Section
- 10.3.13, "<code>value_null</code>/<code>value_not_null</code>"</a>)
+ (<a href="#10.3.15">Section
+ 10.3.15, "<code>value_null</code>/<code>value_not_null</code>"</a>)
for containers of object pointers. For example:</p>
<pre class="c++">
@@ -4246,7 +4258,7 @@ CREATE TABLE employee (
of these references.</p>
<p>To eliminate redundant database schema references we can use the
- <code>inverse</code> pragma (<a href="#10.3.7">Section 10.3.7,
+ <code>inverse</code> pragma (<a href="#10.3.9">Section 10.3.9,
"<code>inverse</code>"</a>) which tells the ODB compiler that
a pointer is the inverse side of a bidirectional relationship.
Either side of a relationship can be made inverse. For example:</p>
@@ -4290,7 +4302,7 @@ CREATE TABLE employee (
pointer. Also note that an ordered container (<a href="#5.1">Section
5.1, "Ordered Containers"</a>) of pointers that is an inverse side
of a bidirectional relationship is always treated as unordered
- (<a href="#10.3.8">Section 10.3.8, "<code>unordered</code>"</a>)
+ (<a href="#10.3.10">Section 10.3.10, "<code>unordered</code>"</a>)
because the contents of such a container are implicitly built from
the direct side of the relationship which does not contain the
element order (index).</p>
@@ -4972,8 +4984,8 @@ t.commit ();
<p>Customizing a column name for a data member of a simple value
type is straightforward: we simply specify the desired name with
- the <code>db&nbsp;column</code> pragma (<a href="#10.3.5">Section
- 10.3.5, "<code>column</code>"</a>). For composite value
+ the <code>db&nbsp;column</code> pragma (<a href="#10.3.7">Section
+ 10.3.7, "<code>column</code>"</a>). For composite value
types things are slightly more complex since they are mapped to
multiple columns. Consider the following example:</p>
@@ -5074,9 +5086,9 @@ CREATE TABLE person (
<p>The same principle applies when a composite value type is used
as an element of a container, except that instead of
<code>db&nbsp;column</code>, either the <code>db&nbsp;value_column</code>
- (<a href="#10.3.17">Section 10.3.17, "<code>value_column</code>"</a>) or
+ (<a href="#10.3.23">Section 10.3.23, "<code>value_column</code>"</a>) or
<code>db&nbsp;key_column</code>
- (<a href="#10.3.16">Section 10.3.16, "<code>key_column</code>"</a>)
+ (<a href="#10.3.22">Section 10.3.22, "<code>key_column</code>"</a>)
pragmas are used to specify the column prefix.</p>
<p>When a composite value type contains a container, an extra table
@@ -5120,8 +5132,8 @@ CREATE TABLE person (
</pre>
<p>To customize the container table name we can use the
- <code>db&nbsp;table</code> pragma (<a href="#10.3.9">Section
- 10.3.9, "<code>table</code>"</a>), for example:</p>
+ <code>db&nbsp;table</code> pragma (<a href="#10.3.11">Section
+ 10.3.11, "<code>table</code>"</a>), for example:</p>
<pre class="c++">
#pragma db value
@@ -6044,57 +6056,93 @@ private:
</tr>
<tr>
+ <td><code>default</code></td>
+ <td>default value for a value type</td>
+ <td><a href="#10.2.4">10.2.4</a></td>
+ </tr>
+
+ <tr>
+ <td><code>options</code></td>
+ <td>database options for a value type</td>
+ <td><a href="#10.2.5">10.2.5</a></td>
+ </tr>
+
+ <tr>
<td><code>unordered</code></td>
<td>ordered container should be stored unordered</td>
- <td><a href="#10.2.4">10.2.4</a></td>
+ <td><a href="#10.2.6">10.2.6</a></td>
</tr>
<tr>
<td><code>index_type</code></td>
<td>database type for a container's index type</td>
- <td><a href="#10.2.5">10.2.5</a></td>
+ <td><a href="#10.2.7">10.2.7</a></td>
</tr>
<tr>
<td><code>key_type</code></td>
<td>database type for a container's key type</td>
- <td><a href="#10.2.6">10.2.6</a></td>
+ <td><a href="#10.2.8">10.2.8</a></td>
</tr>
<tr>
<td><code>value_type</code></td>
<td>database type for a container's value type</td>
- <td><a href="#10.2.7">10.2.7</a></td>
+ <td><a href="#10.2.9">10.2.9</a></td>
</tr>
<tr>
<td><code>value_null</code>/<code>value_not_null</code></td>
<td>container's value can/cannot be <code>NULL</code></td>
- <td><a href="#10.2.8">10.2.8</a></td>
+ <td><a href="#10.2.10">10.2.10</a></td>
+ </tr>
+
+ <tr>
+ <td><code>id_options</code></td>
+ <td>database options for a container's id column</td>
+ <td><a href="#10.2.11">10.2.11</a></td>
+ </tr>
+
+ <tr>
+ <td><code>index_options</code></td>
+ <td>database options for a container's index column</td>
+ <td><a href="#10.2.12">10.2.12</a></td>
+ </tr>
+
+ <tr>
+ <td><code>key_options</code></td>
+ <td>database options for a container's key column</td>
+ <td><a href="#10.2.13">10.2.13</a></td>
+ </tr>
+
+ <tr>
+ <td><code>value_options</code></td>
+ <td>database options for a container's value column</td>
+ <td><a href="#10.2.14">10.2.14</a></td>
</tr>
<tr>
<td><code>id_column</code></td>
- <td>column name for a container's table object id</td>
- <td><a href="#10.2.9">10.2.9</a></td>
+ <td>column name for a container's object id</td>
+ <td><a href="#10.2.15">10.2.15</a></td>
</tr>
<tr>
<td><code>index_column</code></td>
- <td>column name for a container's table index</td>
- <td><a href="#10.2.10">10.2.10</a></td>
+ <td>column name for a container's index</td>
+ <td><a href="#10.2.16">10.2.16</a></td>
</tr>
<tr>
<td><code>key_column</code></td>
- <td>column name for a container's table key</td>
- <td><a href="#10.2.11">10.2.11</a></td>
+ <td>column name for a container's key</td>
+ <td><a href="#10.2.17">10.2.17</a></td>
</tr>
<tr>
<td><code>value_column</code></td>
- <td>column name for a container's table value</td>
- <td><a href="#10.2.12">10.2.12</a></td>
+ <td>column name for a container's value</td>
+ <td><a href="#10.2.18">10.2.18</a></td>
</tr>
</table>
@@ -6106,8 +6154,9 @@ private:
is the scope. A particular value type specifier applies to all the
members of this value type that don't have a pre-member version
of the specifier, while the member specifier always applies only
- to a single member. In other words, member specifiers take precedence
- over parameters specified with value specifiers.</p>
+ to a single member. Also, with a few exceptions, member specifiers
+ take precedence over and override parameters specified with value
+ specifiers.</p>
<h3><a name="10.2.1">10.2.1 <code>type</code></a></h3>
@@ -6261,7 +6310,52 @@ typedef shared_ptr&lt;person> person_ptr;
for the object pointers, refer to <a href="#6">Chapter 6,
"Relationships"</a>.</p>
- <h3><a name="10.2.4">10.2.4 <code>unordered</code></a></h3>
+ <h3><a name="10.2.4">10.2.4 <code>default</code></a></h3>
+
+ <p>The <code>default</code> specifier specifies the database default value
+ that should be used for data members of this type. For example:</p>
+
+ <pre class="c++">
+#pragma db value(std::string) default("")
+
+#pragma db object
+class person
+{
+ ...
+
+ std::string name_; // Mapped to TEXT NOT NULL DEFAULT ''.
+};
+ </pre>
+
+ <p>The semantics of the <code>default</code> specifier for a value type
+ are similar to those of the <code>default</code> specifier for a
+ data member (<a href="#10.3.5">Section 10.3.5,
+ "<code>default</code>"</a>).</p>
+
+ <h3><a name="10.2.5">10.2.5 <code>options</code></a></h3>
+
+ <p>The <code>options</code> specifier specifies additional column
+ definition options that should be used for data members of this
+ type. For example:</p>
+
+ <pre class="c++">
+#pragma db value(std::string) options("COLLATE binary")
+
+#pragma db object
+class person
+{
+ ...
+
+ std::string name_; // Mapped to TEXT NOT NULL COLLATE binary.
+};
+ </pre>
+
+ <p>The semantics of the <code>options</code> specifier for a value type
+ are similar to those of the <code>options</code> specifier for a
+ data member (<a href="#10.3.6">Section 10.3.6,
+ "<code>options</code>"</a>).</p>
+
+ <h3><a name="10.2.6">10.2.6 <code>unordered</code></a></h3>
<p>The <code>unordered</code> specifier specifies that the ordered
container should be stored unordered in the database. The database
@@ -6278,12 +6372,12 @@ typedef std::vector&lt;std::string> names;
storage in the database, refer to <a href="#5.1">Section 5.1,
"Ordered Containers"</a>.</p>
- <h3><a name="10.2.5">10.2.5 <code>index_type</code></a></h3>
+ <h3><a name="10.2.7">10.2.7 <code>index_type</code></a></h3>
<p>The <code>index_type</code> specifier specifies the native
database type that should be used for an ordered container's
index column. The semantics of <code>index_type</code>
- are similar to that of the <code>type</code> specifier
+ are similar to those of the <code>type</code> specifier
(<a href="#10.2.1">Section 10.2.1, "<code>type</code>"</a>). The native
database type is expected to be an integer type. For example:</p>
@@ -6292,12 +6386,12 @@ typedef std::vector&lt;std::string> names;
#pragma db value(names) index_type("SMALLINT UNSIGNED")
</pre>
- <h3><a name="10.2.6">10.2.6 <code>key_type</code></a></h3>
+ <h3><a name="10.2.8">10.2.8 <code>key_type</code></a></h3>
<p>The <code>key_type</code> specifier specifies the native
database type that should be used for a map container's
key column. The semantics of <code>key_type</code>
- are similar to that of the <code>type</code> specifier
+ are similar to those of the <code>type</code> specifier
(<a href="#10.2.1">Section 10.2.1, "<code>type</code>"</a>). For
example:</p>
@@ -6306,12 +6400,12 @@ typedef std::map&lt;unsigned short, float> age_weight_map;
#pragma db value(age_weight_map) key_type("INT UNSIGNED")
</pre>
- <h3><a name="10.2.7">10.2.7 <code>value_type</code></a></h3>
+ <h3><a name="10.2.9">10.2.9 <code>value_type</code></a></h3>
<p>The <code>value_type</code> specifier specifies the native
database type that should be used for a container's
value column. The semantics of <code>value_type</code>
- are similar to that of the <code>type</code> specifier
+ are similar to those of the <code>type</code> specifier
(<a href="#10.2.1">Section 10.2.1, "<code>type</code>"</a>). For
example:</p>
@@ -6321,16 +6415,16 @@ typedef std::vector&lt;std::string> names;
</pre>
<p>The <code>value_null</code> and <code>value_not_null</code>
- (<a href="#10.2.8">Section 10.2.8,
+ (<a href="#10.2.10">Section 10.2.10,
"<code>value_null</code>/<code>value_not_null</code>"</a>) specifiers
can be used to control the NULL semantics of a value column.</p>
- <h3><a name="10.2.8">10.2.8 <code>value_null</code>/<code>value_not_null</code></a></h3>
+ <h3><a name="10.2.10">10.2.10 <code>value_null</code>/<code>value_not_null</code></a></h3>
<p>The <code>value_null</code> and <code>value_not_null</code> specifiers
specify that a container type's element value can or cannot be
<code>NULL</code>, respectively. The semantics of <code>value_null</code>
- and <code>value_not_null</code> are similar to that of the
+ and <code>value_not_null</code> are similar to those of the
<code>null</code> and <code>not_null</code> specifiers
(<a href="#10.2.3">Section 10.2.3, "<code>null</code>/<code>not_null</code>"</a>).
For example:</p>
@@ -6350,9 +6444,78 @@ typedef std::vector&lt;shared_ptr&lt;account> > accounts;
<p>For set and multiset containers (<a href="#5.2">Section 5.2, "Set and
Multiset Containers"</a>) the element value is automatically treated
- as not alowing a <code>NULL</code> value.</p>
+ as not allowing a <code>NULL</code> value.</p>
+
- <h3><a name="10.2.9">10.2.9 <code>id_column</code></a></h3>
+ <h3><a name="10.2.11">10.2.11 <code>id_options</code></a></h3>
+
+ <p>The <code>id_options</code> specifier specifies additional
+ column definition options that should be used for a container's
+ id column. For example:</p>
+
+ <pre class="c++">
+typedef std::vector&lt;std::string> nicknames;
+#pragma db value(nicknames) id_options("COLLATE binary")
+ </pre>
+
+ <p>The semantics of the <code>id_options</code> specifier for a container
+ type are similar to those of the <code>id_options</code> specifier for
+ a container data member (<a href="#10.3.16">Section 10.3.16,
+ "<code>id_options</code>"</a>).</p>
+
+
+ <h3><a name="10.2.12">10.2.12 <code>index_options</code></a></h3>
+
+ <p>The <code>index_options</code> specifier specifies additional
+ column definition options that should be used for a container's
+ index column. For example:</p>
+
+ <pre class="c++">
+typedef std::vector&lt;std::string> nicknames;
+#pragma db value(nicknames) index_options("ZEROFILL")
+ </pre>
+
+ <p>The semantics of the <code>index_options</code> specifier for a container
+ type are similar to those of the <code>index_options</code> specifier for
+ a container data member (<a href="#10.3.17">Section 10.3.17,
+ "<code>index_options</code>"</a>).</p>
+
+
+ <h3><a name="10.2.13">10.2.13 <code>key_options</code></a></h3>
+
+ <p>The <code>key_options</code> specifier specifies additional
+ column definition options that should be used for a container's
+ key column. For example:</p>
+
+ <pre class="c++">
+typedef std::map&lt;std::string, std::string> properties;
+#pragma db value(properties) key_options("COLLATE binary")
+ </pre>
+
+ <p>The semantics of the <code>key_options</code> specifier for a container
+ type are similar to those of the <code>key_options</code> specifier for
+ a container data member (<a href="#10.3.18">Section 10.3.18,
+ "<code>key_options</code>"</a>).</p>
+
+
+ <h3><a name="10.2.14">10.2.14 <code>value_options</code></a></h3>
+
+ <p>The <code>value_options</code> specifier specifies additional
+ column definition options that should be used for a container's
+ value column. For example:</p>
+
+ <pre class="c++">
+typedef std::set&lt;std::string> nicknames;
+#pragma db value(nicknames) value_options("COLLATE binary")
+ </pre>
+
+ <p>The semantics of the <code>value_options</code> specifier for a container
+ type are similar to those of the <code>value_options</code> specifier for
+ a container data member (<a href="#10.3.19">Section 10.3.19,
+ "<code>value_options</code>"</a>).</p>
+
+
+ <h3><a name="10.2.15">10.2.15 <code>id_column</code></a></h3>
<p>The <code>id_column</code> specifier specifies the column
name that should be used to store the object id in a
@@ -6366,7 +6529,7 @@ typedef std::vector&lt;std::string> names;
<p>If the column name is not specified, then <code>object_id</code>
is used by default.</p>
- <h3><a name="10.2.10">10.2.10 <code>index_column</code></a></h3>
+ <h3><a name="10.2.16">10.2.16 <code>index_column</code></a></h3>
<p>The <code>index_column</code> specifier specifies the column
name that should be used to store the element index in an
@@ -6380,7 +6543,7 @@ typedef std::vector&lt;std::string> names;
<p>If the column name is not specified, then <code>index</code>
is used by default.</p>
- <h3><a name="10.2.11">10.2.11 <code>key_column</code></a></h3>
+ <h3><a name="10.2.17">10.2.17 <code>key_column</code></a></h3>
<p>The <code>key_column</code> specifier specifies the column
name that should be used to store the key in a map
@@ -6394,7 +6557,7 @@ typedef std::map&lt;unsigned short, float> age_weight_map;
<p>If the column name is not specified, then <code>key</code>
is used by default.</p>
- <h3><a name="10.2.12">10.2.12 <code>value_column</code></a></h3>
+ <h3><a name="10.2.18">10.2.18 <code>value_column</code></a></h3>
<p>The <code>value_column</code> specifier specifies the column
name that should be used to store the element value in a
@@ -6440,93 +6603,128 @@ typedef std::map&lt;unsigned short, float> age_weight_map;
<tr>
<td><code>type</code></td>
- <td>database type for member</td>
+ <td>database type for a member</td>
<td><a href="#10.3.3">10.3.3</a></td>
</tr>
<tr>
<td><code>null</code>/<code>not_null</code></td>
- <td>member can/cannot be NULL</td>
+ <td>member can/cannot be <code>NULL</code></td>
<td><a href="#10.3.4">10.3.4</a></td>
</tr>
<tr>
- <td><code>column</code></td>
- <td>column name for member</td>
+ <td><code>default</code></td>
+ <td>default value for a member</td>
<td><a href="#10.3.5">10.3.5</a></td>
</tr>
<tr>
+ <td><code>options</code></td>
+ <td>database options for a member</td>
+ <td><a href="#10.3.6">10.3.6</a></td>
+ </tr>
+
+ <tr>
+ <td><code>column</code></td>
+ <td>column name for a member</td>
+ <td><a href="#10.3.7">10.3.7</a></td>
+ </tr>
+
+ <tr>
<td><code>transient</code></td>
<td>member is not stored in the database</td>
- <td><a href="#10.3.6">10.3.6</a></td>
+ <td><a href="#10.3.8">10.3.8</a></td>
</tr>
<tr>
<td><code>inverse</code></td>
<td>member is an inverse side of a bidirectional relationship</td>
- <td><a href="#10.3.7">10.3.7</a></td>
+ <td><a href="#10.3.9">10.3.9</a></td>
</tr>
<tr>
<td><code>unordered</code></td>
<td>ordered container should be stored unordered</td>
- <td><a href="#10.3.8">10.3.8</a></td>
+ <td><a href="#10.3.10">10.3.10</a></td>
</tr>
<tr>
<td><code>table</code></td>
<td>table name for a container</td>
- <td><a href="#10.3.9">10.3.9</a></td>
+ <td><a href="#10.3.11">10.3.11</a></td>
</tr>
-
<tr>
<td><code>index_type</code></td>
<td>database type for a container's index type</td>
- <td><a href="#10.3.10">10.3.10</a></td>
+ <td><a href="#10.3.12">10.3.12</a></td>
</tr>
<tr>
<td><code>key_type</code></td>
<td>database type for a container's key type</td>
- <td><a href="#10.3.11">10.3.11</a></td>
+ <td><a href="#10.3.13">10.3.13</a></td>
</tr>
<tr>
<td><code>value_type</code></td>
<td>database type for a container's value type</td>
- <td><a href="#10.3.12">10.3.12</a></td>
+ <td><a href="#10.3.14">10.3.14</a></td>
</tr>
<tr>
<td><code>value_null</code>/<code>value_not_null</code></td>
- <td>container's value can/cannot be NULL</td>
- <td><a href="#10.3.13">10.3.13</a></td>
+ <td>container's value can/cannot be <code>NULL</code></td>
+ <td><a href="#10.3.15">10.3.15</a></td>
+ </tr>
+
+ <tr>
+ <td><code>id_options</code></td>
+ <td>database options for a container's id column</td>
+ <td><a href="#10.3.16">10.3.16</a></td>
+ </tr>
+
+ <tr>
+ <td><code>index_options</code></td>
+ <td>database options for a container's index column</td>
+ <td><a href="#10.3.17">10.3.17</a></td>
+ </tr>
+
+ <tr>
+ <td><code>key_options</code></td>
+ <td>database options for a container's key column</td>
+ <td><a href="#10.3.18">10.3.18</a></td>
+ </tr>
+
+ <tr>
+ <td><code>value_options</code></td>
+ <td>database options for a container's value column</td>
+ <td><a href="#10.3.19">10.3.19</a></td>
</tr>
<tr>
<td><code>id_column</code></td>
<td>column name for a container's object id</td>
- <td><a href="#10.3.14">10.3.14</a></td>
+ <td><a href="#10.3.20">10.3.20</a></td>
</tr>
<tr>
<td><code>index_column</code></td>
<td>column name for a container's index</td>
- <td><a href="#10.3.15">10.3.15</a></td>
+ <td><a href="#10.3.21">10.3.21</a></td>
</tr>
<tr>
<td><code>key_column</code></td>
<td>column name for a container's key</td>
- <td><a href="#10.3.16">10.3.16</a></td>
+ <td><a href="#10.3.22">10.3.22</a></td>
</tr>
<tr>
<td><code>value_column</code></td>
<td>column name for a container's value</td>
- <td><a href="#10.3.17">10.3.17</a></td>
+ <td><a href="#10.3.23">10.3.23</a></td>
</tr>
</table>
@@ -6538,8 +6736,9 @@ typedef std::map&lt;unsigned short, float> age_weight_map;
is the scope. A particular value type specifier applies to all the
members of this value type that don't have a pre-member version
of the specifier, while the member specifier always applies only
- to a single member. In other words, member specifiers take precedence
- over parameters specified with value specifiers.</p>
+ to a single member. Also, with a few exceptions, member specifiers
+ take precedence over and override parameters specified with value
+ specifiers.</p>
<h3><a name="10.3.1">10.3.1 <code>id</code></a></h3>
@@ -6608,53 +6807,6 @@ class person
10.3.4, "<code>null</code>/<code>not_null</code>"</a>) specifiers
can be used to control the NULL semantics of a data member.</p>
- <h3><a name="10.3.5">10.3.5 <code>column</code></a></h3>
-
- <p>The <code>column</code> specifier specifies the column name
- that should be used to store a data member in a relational database.
- For example:</p>
-
- <pre class="c++">
-#pragma db object
-class person
-{
- ...
-
- #pragma db id column("person_id")
- unsigned long id_;
-};
- </pre>
-
- <p>For a member of a composite value type, the <code>column</code> specifier
- specifies the column name prefix. Refer to <a href="#7.1">Section 7.1,
- "Composite Value Column and Table Names"</a> for details.</p>
-
- <p>If the column name is not specified, it is derived from the member
- name by removing the common data member name decorations, such as leading
- and trailing underscores, the <code>m_</code> prefix, etc.</p>
-
- <h3><a name="10.3.6">10.3.6 <code>transient</code></a></h3>
-
- <p>The <code>transient</code> specifier instructs the ODB compiler
- not to store a data member in the database. For example:</p>
-
- <pre class="c++">
-#pragma db object
-class person
-{
- ...
-
- date born_;
-
- #pragma db transient
- unsigned short age_; // Computed from born_.
-};
- </pre>
-
- <p>This pragma is usually used on computed members, pointers and
- references that are only meaningful in the application's
- memory, as well as utility members such as mutexes, etc.</p>
-
<h3><a name="10.3.4">10.3.4 <code>null</code>/<code>not_null</code></a></h3>
<p>The <code>null</code> and <code>not_null</code> specifiers specify that
@@ -6708,7 +6860,215 @@ class account
for the object pointers, refer to <a href="#6">Chapter 6,
"Relationships"</a>.</p>
- <h3><a name="10.3.7">10.3.7 <code>inverse</code></a></h3>
+ <h3><a name="10.3.5">10.3.5 <code>default</code></a></h3>
+
+ <p>The <code>default</code> specifier specifies the database default value
+ that should be used for a data member. For example:</p>
+
+ <pre class="c++">
+#pragma db object
+class person
+{
+ ...
+
+ #pragma db default(-1)
+ int age_; // Mapped to INT NOT NULL DEFAULT -1.
+};
+ </pre>
+
+ <p>A default value can be the special <code>null</code> keyword,
+ a <code>bool</code> literal (<code>true</code> or <code>false</code>),
+ an integer literal, a floating point literal, a string literal, or
+ an enumerator name. If you need to specify a default value that is
+ an expression, for example an SQL function call, then you can use
+ the <code>options</code> specifier (<a href="#10.3.6">Section
+ 10.3.6, "<code>options</code>"</a>) instead. For example:</p>
+
+ <pre class="c++">
+enum gender {male, female, undisclosed};
+
+#pragma db object
+class person
+{
+ ...
+
+ #pragma db default(null)
+ nullable&lt;std::string> middle_; // DEFAULT NULL
+
+ #pragma db default(false)
+ bool married_; // DEFAULT 0/FALSE
+
+ #pragma db default(0.0)
+ float weight_; // DEFAULT 0.0
+
+ #pragma db default("Mr")
+ string title_; // DEFAULT 'Mr'
+
+ #pragma db default(undisclosed)
+ gender gender_; // DEFAULT 2/'undisclosed'
+
+ #pragma db options("DEFAULT CURRENT_TIMESTAMP()")
+ date timestamp_; // DEFAULT CURRENT_TIMESTAMP()
+};
+ </pre>
+
+ <p>Default values specified as enumerators are only supported for
+ members that are mapped to an <code>ENUM</code> or an integer
+ type in the database, which is the case for the automatic
+ mapping of C++ enums to suitable database types as performed
+ by the ODB compiler. If you have mapped a C++ enum to another
+ database type, then you should use a literal corresponding
+ to that type to specify the default value. For example:</p>
+
+ <pre class="c++">
+enum gender {male, female, undisclosed};
+#pragma db value(gender) type("VARCHAR(11)")
+
+#pragma db object
+class person
+{
+ ...
+
+ #pragma db default("undisclosed")
+ gender gender_; // DEFAULT 'undisclosed'
+};
+ </pre>
+
+ <p>A default value can also be specified on the per-type basis
+ (<a href="#10.2.4">Section 10.2.4, "<code>default</code>"</a>).
+ An empty <code>default</code> specifier can be used to reset
+ a default value that was previously specified on the per-type
+ basis. For example:</p>
+
+ <pre class="c++">
+#pragma db value(std::string) default("")
+
+#pragma db object
+class person
+{
+ ...
+
+ #pragma db default()
+ std::string name_; // No default value.
+};
+ </pre>
+
+ <p>A data member containing the object id (<a href="#10.3.1">Section
+ 10.3.1, "<code>id</code>"</a> ) is automatically treated as not
+ having a default value even if its type specifies a default value.</p>
+
+ <p>Note also that default values do not affect the generated C++ code
+ in any way. In particular, no automatic initialization of data members
+ with their default values is performed at any point. If you need such
+ an initialization, you will need to implement it yourself, for example,
+ in your persistent class constructors. The default values only
+ affect the generated database schemas and, in the context of ODB,
+ are primarily useful for schema evolution.</p>
+
+
+ <h3><a name="10.3.6">10.3.6 <code>options</code></a></h3>
+
+ <p>The <code>options</code> specifier specifies additional column
+ definition options that should be used for a data member. For
+ example:</p>
+
+ <pre class="c++">
+#pragma db object
+class person
+{
+ ...
+
+ #pragma db options("UNIQUE")
+ std::string email_; // Mapped to TEXT NOT NULL UNIQUE.
+};
+ </pre>
+
+ <p>Options can also be specified on the per-type basis
+ (<a href="#10.2.5">Section 10.2.5, "<code>options</code>"</a>).
+ By default, options are accumulating. That is, the ODB compiler
+ first adds all the options specified for a value type followed
+ by all the options specified for a data member. To clear the
+ accumulated options at any point in this sequence you can use
+ an empty <code>options</code> specifier. For example:</p>
+
+ <pre class="c++">
+#pragma db value(std::string) options("COLLATE binary")
+
+#pragma db object
+class person
+{
+ ...
+
+ std::string first_; // TEXT NOT NULL COLLATE binary
+
+ #pragma db options("UNIQUE")
+ std::string last_; // TEXT NOT NULL COLLATE binary UNIQUE
+
+ #pragma db options()
+ std::string title_; // TEXT NOT NULL
+
+ #pragma db options() options("UNIQUE")
+ std::string email_; // TEXT NOT NULL UNIQUE
+};
+ </pre>
+
+ <p>ODB provides dedicated specifiers for specifying column types
+ (<a href="#10.3.3">Section 10.3.3, "<code>type</code>"</a>),
+ <code>NULL</code> constraints (<a href="#10.3.4">Section 10.3.4,
+ "<code>null</code>/<code>not_null</code>"</a>), and default
+ values (<a href="#10.3.5">Section 10.3.5, "<code>default</code>"</a>).
+ For ODB to function correctly these specifiers should always be
+ used instead of the opaque <code>options</code> specifier for
+ these components of a column definition.</p>
+
+ <h3><a name="10.3.7">10.3.7 <code>column</code></a></h3>
+
+ <p>The <code>column</code> specifier specifies the column name
+ that should be used to store a data member in a relational database.
+ For example:</p>
+
+ <pre class="c++">
+#pragma db object
+class person
+{
+ ...
+
+ #pragma db id column("person_id")
+ unsigned long id_;
+};
+ </pre>
+
+ <p>For a member of a composite value type, the <code>column</code> specifier
+ specifies the column name prefix. Refer to <a href="#7.1">Section 7.1,
+ "Composite Value Column and Table Names"</a> for details.</p>
+
+ <p>If the column name is not specified, it is derived from the member
+ name by removing the common data member name decorations, such as leading
+ and trailing underscores, the <code>m_</code> prefix, etc.</p>
+
+ <h3><a name="10.3.8">10.3.8 <code>transient</code></a></h3>
+
+ <p>The <code>transient</code> specifier instructs the ODB compiler
+ not to store a data member in the database. For example:</p>
+
+ <pre class="c++">
+#pragma db object
+class person
+{
+ ...
+
+ date born_;
+
+ #pragma db transient
+ unsigned short age_; // Computed from born_.
+};
+ </pre>
+
+ <p>This pragma is usually used on computed members, pointers and
+ references that are only meaningful in the application's
+ memory, as well as utility members such as mutexes, etc.</p>
+
+ <h3><a name="10.3.9">10.3.9 <code>inverse</code></a></h3>
<p>The <code>inverse</code> specifier specifies that a data member of
an object pointer or a container of object pointers type is an
@@ -6746,12 +7106,12 @@ class person
relationship information. Only ordered and set containers can be used
for inverse members. If an inverse member is of an ordered container
type, it is automatically marked as unordered
- (<a href="#10.3.8">Section 10.3.8, "<code>unordered</code>"</a>).</p>
+ (<a href="#10.3.10">Section 10.3.10, "<code>unordered</code>"</a>).</p>
<p>For a more detailed discussion of inverse members, refer to
<a href="#6.2">Section 6.2, "Bidirectional Relationships"</a>.</p>
- <h3><a name="10.3.8">10.3.8 <code>unordered</code></a></h3>
+ <h3><a name="10.3.10">10.3.10 <code>unordered</code></a></h3>
<p>The <code>unordered</code> specifier specifies that a member of
an ordered container type should be stored unordered in the database.
@@ -6774,7 +7134,7 @@ class person
storage in the database, refer to <a href="#5.1">Section 5.1,
"Ordered Containers"</a>.</p>
- <h3><a name="10.3.9">10.3.9 <code>table</code></a></h3>
+ <h3><a name="10.3.11">10.3.11 <code>table</code></a></h3>
<p>The <code>table</code> specifier specifies the table name that should
be used to store the contents of a container member. For example:</p>
@@ -6804,12 +7164,12 @@ class person
to <a href="#7.1">Section 7.1, "Composite Value Column and Table
Names"</a> for details.</p>
- <h3><a name="10.3.10">10.3.10 <code>index_type</code></a></h3>
+ <h3><a name="10.3.12">10.3.12 <code>index_type</code></a></h3>
<p>The <code>index_type</code> specifier specifies the native
database type that should be used for an ordered container's
index column of a data member. The semantics of <code>index_type</code>
- are similar to that of the <code>type</code> specifier
+ are similar to those of the <code>type</code> specifier
(<a href="#10.3.3">Section 10.3.3, "<code>type</code>"</a>). The native
database type is expected to be an integer type. For example:</p>
@@ -6824,12 +7184,12 @@ class person
};
</pre>
- <h3><a name="10.3.11">10.3.11 <code>key_type</code></a></h3>
+ <h3><a name="10.3.13">10.3.13 <code>key_type</code></a></h3>
<p>The <code>key_type</code> specifier specifies the native
database type that should be used for a map container's
key column of a data member. The semantics of <code>key_type</code>
- are similar to that of the <code>type</code> specifier
+ are similar to those of the <code>type</code> specifier
(<a href="#10.3.3">Section 10.3.3, "<code>type</code>"</a>). For
example:</p>
@@ -6844,12 +7204,12 @@ class person
};
</pre>
- <h3><a name="10.3.12">10.3.12 <code>value_type</code></a></h3>
+ <h3><a name="10.3.14">10.3.14 <code>value_type</code></a></h3>
<p>The <code>value_type</code> specifier specifies the native
database type that should be used for a container's
value column of a data member. The semantics of <code>value_type</code>
- are similar to that of the <code>type</code> specifier
+ are similar to those of the <code>type</code> specifier
(<a href="#10.3.3">Section 10.3.3, "<code>type</code>"</a>). For
example:</p>
@@ -6865,17 +7225,17 @@ class person
</pre>
<p>The <code>value_null</code> and <code>value_not_null</code>
- (<a href="#10.3.13">Section 10.3.13,
+ (<a href="#10.3.15">Section 10.3.15,
"<code>value_null</code>/<code>value_not_null</code>"</a>) specifiers
can be used to control the NULL semantics of a value column.</p>
- <h3><a name="10.3.13">10.3.13 <code>value_null</code>/<code>value_not_null</code></a></h3>
+ <h3><a name="10.3.15">10.3.15 <code>value_null</code>/<code>value_not_null</code></a></h3>
<p>The <code>value_null</code> and <code>value_not_null</code> specifiers
specify that a container's element value for a data member can or
cannot be <code>NULL</code>, respectively. The semantics of
<code>value_null</code> and <code>value_not_null</code> are similar
- to that of the <code>null</code> and <code>not_null</code> specifiers
+ to those of the <code>null</code> and <code>not_null</code> specifiers
(<a href="#10.3.4">Section 10.3.4, "<code>null</code>/<code>not_null</code>"</a>).
For example:</p>
@@ -6902,14 +7262,101 @@ class account
Multiset Containers"</a>) the element value is automatically treated
as not allowing a <code>NULL</code> value.</p>
- <h3><a name="10.3.14">10.3.14 <code>id_column</code></a></h3>
+ <h3><a name="10.3.16">10.3.16 <code>id_options</code></a></h3>
+
+ <p>The <code>id_options</code> specifier specifies additional
+ column definition options that should be used for a container's
+ id column of a data member. For example:</p>
+
+ <pre class="c++">
+#pragma db object
+class person
+{
+ ...
+
+ #pragma db id options("COLLATE binary")
+ std::string name_;
+
+ #pragma db id_options("COLLATE binary")
+ std::vector&lt;std::string> nicknames_;
+};
+ </pre>
+
+ <p>The semantics of <code>id_options</code> are similar to those
+ of the <code>options</code> specifier (<a href="#10.3.6">Section
+ 10.3.6, "<code>options</code>"</a>).</p>
+
+ <h3><a name="10.3.17">10.3.17 <code>index_options</code></a></h3>
+
+ <p>The <code>index_options</code> specifier specifies additional
+ column definition options that should be used for a container's
+ index column of a data member. For example:</p>
+
+ <pre class="c++">
+#pragma db object
+class person
+{
+ ...
+
+ #pragma db index_options("ZEROFILL")
+ std::vector&lt;std::string> nicknames_;
+};
+ </pre>
+
+ <p>The semantics of <code>index_options</code> are similar to those
+ of the <code>options</code> specifier (<a href="#10.3.6">Section
+ 10.3.6, "<code>options</code>"</a>).</p>
+
+ <h3><a name="10.3.18">10.3.18 <code>key_options</code></a></h3>
+
+ <p>The <code>key_options</code> specifier specifies additional
+ column definition options that should be used for a container's
+ key column of a data member. For example:</p>
+
+ <pre class="c++">
+#pragma db object
+class person
+{
+ ...
+
+ #pragma db key_options("COLLATE binary")
+ std::map&lt;std::string, std::string> properties_;
+};
+ </pre>
+
+ <p>The semantics of <code>key_options</code> are similar to those
+ of the <code>options</code> specifier (<a href="#10.3.6">Section
+ 10.3.6, "<code>options</code>"</a>).</p>
+
+ <h3><a name="10.3.19">10.3.19 <code>value_options</code></a></h3>
+
+ <p>The <code>value_options</code> specifier specifies additional
+ column definition options that should be used for a container's
+ value column of a data member. For example:</p>
+
+ <pre class="c++">
+#pragma db object
+class person
+{
+ ...
+
+ #pragma db value_options("COLLATE binary")
+ std::set&lt;std::string> nicknames_;
+};
+ </pre>
+
+ <p>The semantics of <code>value_options</code> are similar to those
+ of the <code>options</code> specifier (<a href="#10.3.6">Section
+ 10.3.6, "<code>options</code>"</a>).</p>
+
+ <h3><a name="10.3.20">10.3.20 <code>id_column</code></a></h3>
<p>The <code>id_column</code> specifier specifies the column
name that should be used to store the object id in a
container's table for a data member. The semantics of
- <code>id_column</code> are similar to that of the
+ <code>id_column</code> are similar to those of the
<code>column</code> specifier
- (<a href="#10.3.5">Section 10.3.5, "<code>column</code>"</a>).
+ (<a href="#10.3.7">Section 10.3.7, "<code>column</code>"</a>).
For example:</p>
<pre class="c++">
@@ -6926,14 +7373,14 @@ class person
<p>If the column name is not specified, then <code>object_id</code>
is used by default.</p>
- <h3><a name="10.3.15">10.3.15 <code>index_column</code></a></h3>
+ <h3><a name="10.3.21">10.3.21 <code>index_column</code></a></h3>
<p>The <code>index_column</code> specifier specifies the column
name that should be used to store the element index in an
ordered container's table for a data member. The semantics of
- <code>index_column</code> are similar to that of the
+ <code>index_column</code> are similar to those of the
<code>column</code> specifier
- (<a href="#10.3.5">Section 10.3.5, "<code>column</code>"</a>).
+ (<a href="#10.3.7">Section 10.3.7, "<code>column</code>"</a>).
For example:</p>
<pre class="c++">
@@ -6950,14 +7397,14 @@ class person
<p>If the column name is not specified, then <code>index</code>
is used by default.</p>
- <h3><a name="10.3.16">10.3.16 <code>key_column</code></a></h3>
+ <h3><a name="10.3.22">10.3.22 <code>key_column</code></a></h3>
<p>The <code>key_column</code> specifier specifies the column
name that should be used to store the key in a map
container's table for a data member. The semantics of
- <code>key_column</code> are similar to that of the
+ <code>key_column</code> are similar to those of the
<code>column</code> specifier
- (<a href="#10.3.5">Section 10.3.5, "<code>column</code>"</a>).
+ (<a href="#10.3.7">Section 10.3.7, "<code>column</code>"</a>).
For example:</p>
<pre class="c++">
@@ -6974,14 +7421,14 @@ class person
<p>If the column name is not specified, then <code>key</code>
is used by default.</p>
- <h3><a name="10.3.17">10.3.17 <code>value_column</code></a></h3>
+ <h3><a name="10.3.23">10.3.23 <code>value_column</code></a></h3>
<p>The <code>value_column</code> specifier specifies the column
name that should be used to store the element value in a
container's table for a data member. The semantics of
- <code>value_column</code> are similar to that of the
+ <code>value_column</code> are similar to those of the
<code>column</code> specifier
- (<a href="#10.3.5">Section 10.3.5, "<code>column</code>"</a>).
+ (<a href="#10.3.7">Section 10.3.7, "<code>column</code>"</a>).
For example:</p>
<pre class="c++">