<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>C++ Object Persistence with ODB</title>
<meta name="copyright" content="© 2009-2013 Code Synthesis Tools CC"/>
<meta name="keywords" content="odb,c++,object,persistence,ORM,relational,database,RDBMS,ODBMS,OODBMS"/>
<meta name="description" content="C++ Object Persistence with ODB"/>
<meta name="revision" content="2.3"/>
<meta name="version" content="2.3.0"/>
<!--
If you make changes to this document, follow these stylistic rules
for consistency.
- Don't use 'object' for instances of non-persistent classes. Use
'instance' instead.
- Each overloaded function should still be referred to as function.
When saying that a function is overloaded, use term 'version',
for example The persist() function has two overloaded versions.
Don't use version to refer to individual functions, use function
instead. The same holds for constructors.
- Use 'object id' and 'object's identifier'. But not other combinations
of the two.
@@ Check that parts TOCs are up to date.
-->
<link rel="stylesheet" type="text/css" href="default.css" />
<style type="text/css">
pre {
padding : 0 0 0 0em;
margin : 0em 0em 0em 0;
font-size : 102%
}
body {
min-width: 48em;
}
h1 {
font-weight: bold;
font-size: 200%;
line-height: 1.2em;
}
h2 {
font-weight : bold;
font-size : 150%;
padding-top : 0.8em;
}
h3 {
font-size : 140%;
padding-top : 0.8em;
}
/* Force page break for both PDF and HTML (when printing). */
hr.page-break {
height: 0;
width: 0;
border: 0;
visibility: hidden;
page-break-after: always;
}
/* Adjust indentation for three levels. */
#container {
max-width: 48em;
}
#content {
padding: 0 0.1em 0 4em;
/*background-color: red;*/
}
#content h1 {
margin-left: -2.06em;
}
#content h2 {
margin-left: -1.33em;
}
/* Title page */
#titlepage {
padding: 2em 0 1em 0;
border-bottom: 1px solid black;
}
#titlepage .title {
font-weight: bold;
font-size: 200%;
text-align: center;
padding: 1em 0 2em 0;
}
#titlepage p {
padding-bottom: 1em;
}
#titlepage #revision {
padding-bottom: 0em;
}
/* Lists */
ul.list li, ol.list li {
padding-top : 0.3em;
padding-bottom : 0.3em;
}
div.img {
text-align: center;
padding: 2em 0 2em 0;
}
/* */
dl dt {
padding : 0.8em 0 0 0;
}
/* TOC */
table.toc {
border-style : none;
border-collapse : separate;
border-spacing : 0;
margin : 0.2em 0 0.2em 0;
padding : 0 0 0 0;
}
table.toc tr {
padding : 0 0 0 0;
margin : 0 0 0 0;
}
table.toc * td, table.toc * th {
border-style : none;
margin : 0 0 0 0;
vertical-align : top;
}
table.toc * th {
font-weight : normal;
padding : 0em 0.1em 0em 0;
text-align : left;
white-space : nowrap;
}
table.toc * table.toc th {
padding-left : 1em;
}
table.toc * td {
padding : 0em 0 0em 0.7em;
text-align : left;
}
/* operators table */
#operators {
margin: 2em 0 2em 0;
border-collapse : collapse;
border : 1px solid;
border-color : #000000;
font-size : 11px;
line-height : 14px;
}
#operators th, #operators td {
border: 1px solid;
padding : 0.9em 0.9em 0.7em 0.9em;
}
#operators th {
background : #cde8f6;
}
#operators td {
text-align: left;
}
/* scenarios table */
.scenarios {
margin: 2em 0 2em 0;
border-collapse : collapse;
border : 1px solid;
border-color : #000000;
font-size : 11px;
line-height : 14px;
}
.scenarios th, .scenarios td {
border: 1px solid;
padding : 0.9em 0.9em 0.7em 0.9em;
}
.scenarios th {
background : #cde8f6;
}
.scenarios td {
text-align: left;
}
/* specifiers table */
.specifiers {
margin: 2em 0 2em 0;
border-collapse : collapse;
border : 1px solid;
border-color : #000000;
font-size : 11px;
line-height : 14px;
}
.specifiers th, .specifiers td {
border: 1px solid;
padding : 0.9em 0.9em 0.7em 0.9em;
}
.specifiers th {
background : #cde8f6;
}
.specifiers td {
text-align: left;
}
/* mapping table */
#mapping {
margin: 2em 0 2em 0;
border-collapse : collapse;
border : 1px solid;
border-color : #000000;
font-size : 11px;
line-height : 14px;
}
#mapping th, #mapping td {
border: 1px solid;
padding : 0.9em 0.9em 0.7em 0.9em;
}
#mapping th {
background : #cde8f6;
}
#mapping td {
text-align: left;
}
</style>
</head>
<body>
<div id="container">
<div id="content">
<div class="noprint">
<div id="titlepage">
<div class="title">C++ Object Persistence with ODB</div>
<p>Copyright © 2009-2013 Code Synthesis Tools CC</p>
<p>Permission is granted to copy, distribute and/or modify this
document under the terms of the
<a href="http://www.codesynthesis.com/licenses/fdl-1.3.txt">GNU Free
Documentation License, version 1.3</a>; with no Invariant Sections,
no Front-Cover Texts and no Back-Cover Texts.</p>
<!-- REMEMBER TO CHANGE VERSIONS IN THE META TAGS ABOVE! -->
<p id="revision">Revision 2.3, October 2013</p>
<p>This revision of the manual describes ODB 2.3.0 and is available
in the following formats:
<a href="http://www.codesynthesis.com/products/odb/doc/manual.xhtml">XHTML</a>,
<a href="http://www.codesynthesis.com/products/odb/doc/odb-manual.pdf">PDF</a>, and
<a href="http://www.codesynthesis.com/products/odb/doc/odb-manual.ps">PostScript</a>.</p>
</div>
<hr class="page-break"/>
<h1>Table of Contents</h1>
<table class="toc">
<tr>
<th></th><td><a href="#0">Preface</a>
<table class="toc">
<tr><th></th><td><a href="#0.1">About This Document</a></td></tr>
<tr><th></th><td><a href="#0.2">More Information</a></td></tr>
</table>
</td>
</tr>
<tr>
<th colspan="2"><a href="#I">PART I OBJECT-RELATIONAL MAPPING</a></th>
</tr>
<tr>
<th>1</th><td><a href="#1">Introduction</a>
<table class="toc">
<tr><th>1.1</th><td><a href="#1.1">Architecture and Workflow</a></td></tr>
<tr><th>1.2</th><td><a href="#1.2">Benefits</a></td></tr>
<tr><th>1.3</th><td><a href="#1.3">Supported C++ Standards</a></td></tr>
</table>
</td>
</tr>
<tr>
<th>2</th><td><a href="#2">Hello World Example</a>
<table class="toc">
<tr><th>2.1</th><td><a href="#2.1">Declaring Persistent Classes</a></td></tr>
<tr><th>2.2</th><td><a href="#2.2">Generating Database Support Code</a></td></tr>
<tr><th>2.3</th><td><a href="#2.3">Compiling and Running</a></td></tr>
<tr><th>2.4</th><td><a href="#2.4">Making Objects Persistent</a></td></tr>
<tr><th>2.5</th><td><a href="#2.5">Querying the Database for Objects</a></td></tr>
<tr><th>2.6</th><td><a href="#2.6">Updating Persistent Objects</a></td></tr>
<tr><th>2.7</th><td><a href="#2.7">Defining and Using Views</a></td></tr>
<tr><th>2.8</th><td><a href="#2.8">Deleting Persistent Objects</a></td></tr>
<tr><th>2.9</th><td><a href="#2.9">Changing Persistent Classes</a></td></tr>
<tr><th>2.10</th><td><a href="#2.10">Accessing Multiple Databases</a></td></tr>
<tr><th>2.11</th><td><a href="#2.11">Summary</a></td></tr>
</table>
</td>
</tr>
<tr>
<th>3</th><td><a href="#3">Working with Persistent Objects</a>
<table class="toc">
<tr><th>3.1</th><td><a href="#3.1">Concepts and Terminology</a></td></tr>
<tr><th>3.2</th><td><a href="#3.2">Declaring Persistent Objects and Values</a></td></tr>
<tr><th>3.3</th><td><a href="#3.3">Object and View Pointers</a></td></tr>
<tr><th>3.4</th><td><a href="#3.4">Database</a></td></tr>
<tr><th>3.5</th><td><a href="#3.5">Transactions</a></td></tr>
<tr><th>3.6</th><td><a href="#3.6">Connections</a></td></tr>
<tr><th>3.7</th><td><a href="#3.7">Error Handling and Recovery</a></td></tr>
<tr><th>3.8</th><td><a href="#3.8">Making Objects Persistent</a></td></tr>
<tr><th>3.9</th><td><a href="#3.9">Loading Persistent Objects</a></td></tr>
<tr><th>3.10</th><td><a href="#3.10">Updating Persistent Objects</a></td></tr>
<tr><th>3.11</th><td><a href="#3.11">Deleting Persistent Objects</a></td></tr>
<tr><th>3.12</th><td><a href="#3.12">Executing Native SQL Statements</a></td></tr>
<tr><th>3.13</th><td><a href="#3.13">Tracing SQL Statement Execution</a></td></tr>
<tr><th>3.14</th><td><a href="#3.14">ODB Exceptions</a></td></tr>
</table>
</td>
</tr>
<tr>
<th>4</th><td><a href="#4">Querying the Database</a>
<table class="toc">
<tr><th>4.1</th><td><a href="#4.1">ODB Query Language</a></td></tr>
<tr><th>4.2</th><td><a href="#4.2">Parameter Binding</a></td></tr>
<tr><th>4.3</th><td><a href="#4.3">Executing a Query</a></td></tr>
<tr><th>4.4</th><td><a href="#4.4">Query Result</a></td></tr>
<tr><th>4.5</th><td><a href="#4.5">Prepared Queries</a></td></tr>
</table>
</td>
</tr>
<tr>
<th>5</th><td><a href="#5">Containers</a>
<table class="toc">
<tr><th>5.1</th><td><a href="#5.1">Ordered Containers</a></td></tr>
<tr><th>5.2</th><td><a href="#5.2">Set and Multiset Containers</a></td></tr>
<tr><th>5.3</th><td><a href="#5.3">Map and Multimap Containers</a></td></tr>
<tr>
<th>5.4</th><td><a href="#5.4">Change-Tracking Containers</a>
<table class="toc">
<tr><th>5.4.1</th><td><a href="#5.4.1">Change-Tracking <code>vector</code></a></td></tr>
</table>
</td>
</tr>
<tr><th>5.5</th><td><a href="#5.5">Using Custom Containers</a></td></tr>
</table>
</td>
</tr>
<tr>
<th>6</th><td><a href="#6">Relationships</a>
<table class="toc">
<tr>
<th>6.1</th><td><a href="#6.1">Unidirectional Relationships</a>
<table class="toc">
<tr><th>6.1.1</th><td><a href="#6.1.1">To-One Relationships</a></td></tr>
<tr><th>6.1.2</th><td><a href="#6.1.2">To-Many Relationships</a></td></tr>
</table>
</td>
</tr>
<tr>
<th>6.2</th><td><a href="#6.2">Bidirectional Relationships</a>
<table class="toc">
<tr><th>6.2.1</th><td><a href="#6.2.1">One-to-One Relationships</a></td></tr>
<tr><th>6.2.2</th><td><a href="#6.2.2">One-to-Many Relationships</a></td></tr>
<tr><th>6.2.3</th><td><a href="#6.2.3">Many-to-Many Relationships</a></td></tr>
</table>
</td>
</tr>
<tr><th>6.3</th><td><a href="#6.3">Circular Relationships</a></td></tr>
<tr><th>6.4</th><td><a href="#6.4">Lazy Pointers</a></td></tr>
<tr><th>6.5</th><td><a href="#6.5">Using Custom Smart Pointers</a></td></tr>
</table>
</td>
</tr>
<tr>
<th>7</th><td><a href="#7">Value Types</a>
<table class="toc">
<tr><th>7.1</th><td><a href="#7.1">Simple Value Types</a></td></tr>
<tr>
<th>7.2</th><td><a href="#7.2">Composite Value Types</a>
<table<
| 