summaryrefslogtreecommitdiff
path: root/doc/pregenerated/odb.xhtml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/pregenerated/odb.xhtml')
-rw-r--r--doc/pregenerated/odb.xhtml978
1 files changed, 0 insertions, 978 deletions
diff --git a/doc/pregenerated/odb.xhtml b/doc/pregenerated/odb.xhtml
deleted file mode 100644
index 0a9785c..0000000
--- a/doc/pregenerated/odb.xhtml
+++ /dev/null
@@ -1,978 +0,0 @@
-<!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>ODB 2.4.0 Compiler Command Line Manual</title>
-
- <meta name="copyright" content="&#169; 2009-2023 Code Synthesis Tools CC"/>
- <meta name="keywords" content="odb,object,relational,mapping,compiler,c++"/>
- <meta name="description" content="ODB Compiler Command Line Manual"/>
-
- <link rel="stylesheet" type="text/css" href="default.css" />
-
-<style type="text/css">
-
- #synopsis {
- list-style-type: none;
- }
-
- #synopsis li {
- padding-top : 0.0em;
- padding-bottom : 0.0em;
- }
-
- .options {
- margin: 1em 0 1em 0;
- }
-
- .options dt {
- margin: 1em 0 0 0;
- }
-
- .options dd {
- margin: .1em 0 0 4.5em;
- }
-
-</style>
-</head>
-
-<body>
-<div id="container">
- <div id="content">
-
- <h1>NAME</h1>
-
- <p>odb - object-relational mapping (ORM) compiler for C++</p>
-
- <h1>SYNOPSIS</h1>
-
- <dl id="synopsis">
- <dt><code><b>odb</b> [<i>options</i>] <i>file</i> [<i>file</i>...]</code></dt>
- </dl>
-
- <h1>DESCRIPTION</h1>
-
- <p>Given a set of C++ classes in a header file, <code><b>odb</b></code>
- generates C++ code that allows you to persist, query, and update objects
- of these classes in a relational database (RDBMS). The relational
- database that the generated code should target is specified with the
- required <code><b>--database</b></code> option (see below).</p>
-
- <p>For an input file in the form <code><b>name.hxx</b></code> (other
- file extensions can be used instead of <code><b>.hxx</b></code>),
- in the single-database mode (the default), the generated C++ files
- by default have the following names:
- <code><b>name-odb.hxx</b></code> (header file),
- <code><b>name-odb.ixx</b></code> (inline file), and
- <code><b>name-odb.cxx</b></code> (source file).
-
- Additionally, if the <code><b>--generate-schema</b></code> option is
- specified and the <code><b>sql</b></code> schema format is requested (see
- <code><b>--schema-format</b></code>), the <code><b>name.sql</b></code>
- database schema file is generated. If the <code><b>separate</b></code>
- schema format is requested, the database creation code is generated
- into the separate <code><b>name-schema.cxx</b></code> file.</p>
-
- <p>In the multi-database mode (see the <code><b>--multi-database</b></code>
- option below), the generated files corresponding to the
- <code><b>common</b></code> database have the same names as in the
- single-database mode. For other databases, the file names include
- the database name:
- <code><b>name-odb-</b><i>db</i><b>.hxx</b></code>,
- <code><b>name-odb-</b><i>db</i><b>.ixx</b></code>,
- <code><b>name-odb-</b><i>db</i><b>.cxx</b></code>,
- <code><b>name-</b><i>db</i><b>.sql</b></code>, and
- <code><b>name-schema-</b><i>db</i><b>.cxx</b></code>
- (where <code><i>db</i></code> is the database name).</p>
-
- <h1>OPTIONS</h1>
- <dl class="options">
- <dt><code><b>--help</b></code></dt>
- <dd>Print usage information and exit.</dd>
-
- <dt><code><b>--version</b></code></dt>
- <dd>Print version and exit.</dd>
-
- <dt><code><b>-I</b></code> <code><i>dir</i></code></dt>
- <dd>Add <code><i>dir</i></code> to the beginning of the list of
- directories to be searched for included header files.</dd>
-
- <dt><code><b>-D</b></code> <code><i>name</i></code>[=<code><i>def</i></code>]</dt>
- <dd>Define macro <code><i>name</i></code> with definition
- <code><i>def</i></code>. If definition is omitted, define
- <code><i>name</i></code> to be 1.</dd>
-
- <dt><code><b>-U</b></code> <code><i>name</i></code></dt>
- <dd>Cancel any previous definitions of macro <code><i>name</i></code>,
- either built-in or provided with the <code><b>-D</b></code> option.</dd>
-
- <dt><code><b>--database</b></code>|<code><b>-d</b></code> <code><i>db</i></code></dt>
- <dd>Generate code for the <code><i>db</i></code> database. Valid values
- are <code><b>mssql</b></code>, <code><b>mysql</b></code>,
- <code><b>oracle</b></code>, <code><b>pgsql</b></code>,
- <code><b>sqlite</b></code>, and <code><b>common</b></code> (multi-database
- mode only).</dd>
-
- <dt><code><b>--multi-database</b></code>|<code><b>-m</b></code> <code><i>type</i></code></dt>
- <dd>Enable multi-database support and specify its type. Valid values for
- this option are <code><b>static</b></code> and
- <code><b>dynamic</b></code>.
-
- <p>In the multi-database mode, options that determine the kind (for
- example, <code><b>--schema-format</b></code>), names (for example,
- <code><b>--odb-file-suffix</b></code>), or content (for example, prologue
- and epilogue options) of the output files can be prefixed with the
- database name followed by a colon, for example,
- <code><b>mysql:value</b></code>. This restricts the value of such an
- option to only apply to generated files corresponding to this
- database.</p></dd>
-
- <dt><code><b>--default-database</b></code> <code><i>db</i></code></dt>
- <dd>When static multi-database support is used, specify the database that
- should be made the default. When dynamic multi-database support is used,
- <code><b>common</b></code> is always made the default database.</dd>
-
- <dt><code><b>--generate-query</b></code>|<code><b>-q</b></code></dt>
- <dd>Generate query support code. Without this support you cannot use views
- and can only load objects via their ids.</dd>
-
- <dt><code><b>--generate-prepared</b></code></dt>
- <dd>Generate prepared query execution support code.</dd>
-
- <dt><code><b>--omit-unprepared</b></code></dt>
- <dd>Omit un-prepared (once-off) query execution support code.</dd>
-
- <dt><code><b>--generate-session</b></code>|<code><b>-e</b></code></dt>
- <dd>Generate session support code. With this option session support will
- be enabled by default for all the persistent classes except those for
- which it was explicitly disabled using the <code><b>db session</b></code>
- pragma.</dd>
-
- <dt><code><b>--generate-schema</b></code>|<code><b>-s</b></code></dt>
- <dd>Generate the database schema. The database schema contains SQL
- statements that create database tables necessary to store persistent
- classes defined in the file being compiled. Note that by applying this
- schema, all the existing information stored in such tables will be lost.
-
- <p>Depending on the database being used (<code><b>--database</b></code>
- option), the schema is generated either as a standalone SQL file or
- embedded into the generated C++ code. By default the SQL file is generated
- for the MySQL, PostgreSQL, Oracle, and Microsoft SQL Server databases and
- the schema is embedded into the C++ code for the SQLite database. Use the
- <code><b>--schema-format</b></code> option to alter the default schema
- format.</p>
-
- <p>If database schema evolution support is enabled (that is, the object
- model version is specified), then this option also triggers the generation
- of database schema migration statements, again either as standalong SQL
- files or embedded into the generated C++ code. You can suppress the
- generation of schema migration statements by specifying the
- <code><b>--suppress-migration</b></code> option.</p></dd>
-
- <dt><code><b>--generate-schema-only</b></code></dt>
- <dd>Generate only the database schema. Note that this option is only valid
- when generating schema as a standalone SQL file (see
- <code><b>--schema-format</b></code> for details).</dd>
-
- <dt><code><b>--suppress-migration</b></code></dt>
- <dd>Suppress the generation of database schema migration statements.</dd>
-
- <dt><code><b>--suppress-schema-version</b></code></dt>
- <dd>Suppress the generation of schema version table. If you specify this
- option then you are also expected to manually specify the database schema
- version and migration state at runtime using the
- <code><b>odb::database::schema_version()</b></code> function.</dd>
-
- <dt><code><b>--schema-version-table</b></code> <code><i>name</i></code></dt>
- <dd>Specify the alternative schema version table name instead of the
- default <code><b>schema_version</b></code>. If you specify this option
- then you are also expected to manually specify the schema version table
- name at runtime using the
- <code><b>odb::database::schema_version_table()</b></code> function. The
- table name can be qualified.</dd>
-
- <dt><code><b>--schema-format</b></code> <code><i>format</i></code></dt>
- <dd>Generate the database schema in the specified format. Pass
- <code><b>sql</b></code> as <code><i>format</i></code> to generate the
- database schema as a standalone SQL file or pass
- <code><b>embedded</b></code> to embed the schema into the generated C++
- code. The <code><b>separate</b></code> value is similar to
- <code><b>embedded</b></code> except the schema creation code is generated
- into a separate C++ file (<code><b>name-schema.cxx</b></code> by default).
- This value is primarily useful if you want to place the schema creation
- functionality into a separate program or library. Repeat this option to
- generate the same database schema in multiple formats.</dd>
-
- <dt><code><b>--omit-drop</b></code></dt>
- <dd>Omit <code><b>DROP</b></code> statements from the generated database
- schema.</dd>
-
- <dt><code><b>--omit-create</b></code></dt>
- <dd>Omit <code><b>CREATE</b></code> statements from the generated database
- schema.</dd>
-
- <dt><code><b>--schema-name</b></code> <code><i>name</i></code></dt>
- <dd>Use <code><i>name</i></code> as the database schema name. Schema names
- are primarily used to distinguish between multiple embedded schemas in the
- schema catalog. They are not to be confused with database schemas
- (database namespaces) which are specified with the
- <code><b>--schema</b></code> option. If this option is not specified, the
- empty name, which is the default schema name, is used.</dd>
-
- <dt><code><b>--fkeys-deferrable-mode</b></code> <code><i>m</i></code></dt>
- <dd>Use constraint checking mode <code><i>m</i></code> in foreign keys
- generated for object relationships. Valid values for this option are
- <code><b>not_deferrable</b></code>, <code><b>immediate</b></code>, and
- <code><b>deferred</b></code> (default). MySQL and SQL Server do not
- support deferrable foreign keys and for these databases such keys are
- generated commented out. Other foreign keys generated by the ODB compiler
- (such as the ones used to support containers and polymorphic hierarchies)
- are always generated as not deferrable.
-
- <p>Note also that if you use either <code><b>not_deferrable</b></code> or
- <code><b>immediate</b></code> mode, then the order in which you persist,
- update, and erase objects within a transaction becomes important.</p></dd>
-
- <dt><code><b>--default-pointer</b></code> <code><i>ptr</i></code></dt>
- <dd>Use <code><i>ptr</i></code> as the default pointer for persistent
- objects and views. Objects and views that do not have a pointer assigned
- with the <code><b>db pointer</b></code> pragma will use this pointer by
- default. The value of this option can be '<code><b>*</b></code>' which
- denotes the raw pointer and is the default, or qualified name of a smart
- pointer class template, for example, <code><b>std::shared_ptr</b></code>.
- In the latter case, the ODB compiler constructs the object or view pointer
- by adding a single template argument of the object or view type to the
- qualified name, for example
- <code><b>std::shared_ptr&lt;object></b></code>. The ODB runtime uses
- object and view pointers to return, and, in case of objects, pass and
- cache dynamically allocated instances of object and view types.
-
- <p>Except for the raw pointer and the standard smart pointers defined in
- the <code><b>&lt;memory></b></code> header file, you are expected to
- include the definition of the default pointer at the beginning of the
- generated header file. There are two common ways to achieve this: you can
- either include the necessary header in the file being compiled or you can
- use the <code><b>--hxx-prologue</b></code> option to add the necessary
- <code><b>#include</b></code> directive to the generated code.</p></dd>
-
- <dt><code><b>--session-type</b></code> <code><i>type</i></code></dt>
- <dd>Use <code><i>type</i></code> as the alternative session type instead
- of the default <code><b>odb::session</b></code>. This option can be used
- to specify a custom session implementation to be use by the persistent
- classes. Note that you will also need to include the definition of the
- custom session type into the generated header file. This is normally
- achieved with the <code><b>--hxx-prologue*</b></code> options.</dd>
-
- <dt><code><b>--profile</b></code>|<code><b>-p</b></code> <code><i>name</i></code></dt>
- <dd>Specify a profile that should be used during compilation. A profile is
- an options file. The ODB compiler first looks for a database-specific
- version with the name constructed by appending the
- <code><b>-</b></code><code><i>database</i></code><code><b>.options</b></code>
- suffix to <code><i>name</i></code>, where <code><i>database</i></code> is
- the database name as specified with the <code><b>--database</b></code>
- option. If this file is not found, then the ODB compiler looks for a
- database-independant version with the name constructed by appending just
- the <code><b>.options</b></code> suffix.
-
- <p>The profile options files are searched for in the same set of
- directories as C++ headers included with the <code><b>#include
- &lt;...></b></code> directive (built-in paths plus those specified with
- the <code><b>-I</b></code> options). The options file is first searched
- for in the directory itself and then in its <code><b>odb/</b></code>
- subdirectory.</p>
-
- <p>For the format of the options file refer to the
- <code><b>--options-file</b></code> option below. You can repeat this
- option to specify more than one profile.</p></dd>
-
- <dt><code><b>--at-once</b></code></dt>
- <dd>Generate code for all the input files as well as for all the files
- that they include at once. The result is a single set of source/schema
- files that contain all the generated code. If more than one input file is
- specified together with this option, then the
- <code><b>--input-name</b></code> option must also be specified in order to
- provide the base name for the output files. In this case, the directory
- part of such a base name is used as the location of the combined file.
- This can be important for the <code><b>#include</b></code> directive
- resolution.</dd>
-
- <dt><code><b>--schema</b></code> <code><i>schema</i></code></dt>
- <dd>Specify a database schema (database namespace) that should be assigned
- to the persistent classes in the file being compiled. Database schemas are
- not to be confused with database schema names (schema catalog names) which
- are specified with the <code><b>--schema-name</b></code> option.</dd>
-
- <dt><code><b>--export-symbol</b></code> <code><i>symbol</i></code></dt>
- <dd>Insert <code><i>symbol</i></code> in places where DLL export/import
- control statements (<code><b>__declspec(dllexport/dllimport)</b></code>)
- are necessary. See also the <code><b>--extern-symbol</b></code> option
- below.</dd>
-
- <dt><code><b>--extern-symbol</b></code> <code><i>symbol</i></code></dt>
- <dd>If <code><i>symbol</i></code> is defined, insert it in places where a
- template instantiation must be declared <code><b>extern</b></code>. This
- option is normally used together with <code><b>--export-symbol</b></code>
- when both multi-database support and queries are enabled.</dd>
-
- <dt><code><b>--std</b></code> <code><i>version</i></code></dt>
- <dd>Specify the C++ standard that should be used during compilation. Valid
- values are <code><b>c++98</b></code> (default), <code><b>c++11</b></code>,
- <code><b>c++14</b></code>, <code><b>c++17</b></code>, and
- <code><b>c++20</b></code>.</dd>
-
- <dt><code><b>--warn-hard-add</b></code></dt>
- <dd>Warn about hard-added data members.</dd>
-
- <dt><code><b>--warn-hard-delete</b></code></dt>
- <dd>Warn about hard-deleted data members and persistent classes.</dd>
-
- <dt><code><b>--warn-hard</b></code></dt>
- <dd>Warn about both hard-added and hard-deleted data members and
- persistent classes.</dd>
-
- <dt><code><b>--output-dir</b></code>|<code><b>-o</b></code> <code><i>dir</i></code></dt>
- <dd>Write the generated files to <code><i>dir</i></code> instead of the
- current directory.</dd>
-
- <dt><code><b>--input-name</b></code> <code><i>name</i></code></dt>
- <dd>Use <code><i>name</i></code> instead of the input file to derive the
- names of the generated files. If the <code><b>--at-once</b></code> option
- is specified, then the directory part of <code><i>name</i></code> is used
- as the location of the combined file. Refer to the
- <code><b>--at-once</b></code> option for details.</dd>
-
- <dt><code><b>--changelog</b></code> <code><i>file</i></code></dt>
- <dd>Read/write changelog from/to <code><i>file</i></code> instead of the
- default changelog file. The default changelog file name is derived from
- the input file name and it is placed into the same directory as the input
- file. Note that the <code><b>--output-dir</b></code> option does not
- affect the changelog file location. In other words, by default, the
- changelog file is treated as another input rather than output even though
- the ODB compiler may modify it. Use the <code><b>--changelog-in</b></code>
- and <code><b>--changelog-out</b></code> options to specify different input
- and output chaneglog files.</dd>
-
- <dt><code><b>--changelog-in</b></code> <code><i>file</i></code></dt>
- <dd>Read changelog from <code><i>file</i></code> instead of the default
- changelog file. If this option is specified, then you must also specify
- the output chanegelog file with <code><b>--changelog-out</b></code>.</dd>
-
- <dt><code><b>--changelog-out</b></code> <code><i>file</i></code></dt>
- <dd>Write changelog to <code><i>file</i></code> instead of the default
- changelog file. If this option is specified, then you must also specify
- the input chanegelog file with <code><b>--changelog-in</b></code>.</dd>
-
- <dt><code><b>--changelog-dir</b></code> <code><i>dir</i></code></dt>
- <dd>Use <code><i>dir</i></code> instead of the input file directory as the
- changelog file directory. This directory is also added to changelog files
- specified with the <code><b>--changelog</b></code>,
- <code><b>--changelog-in</b></code>, and <code><b>--changelog-in</b></code>
- options unless they are absolute paths.</dd>
-
- <dt><code><b>--init-changelog</b></code></dt>
- <dd>Force re-initialization of the changelog even if one exists (all the
- existing change history will be lost). This option is primarily useful for
- automated testing.</dd>
-
- <dt><code><b>--odb-file-suffix</b></code> <code><i>suffix</i></code></dt>
- <dd>Use <code><i>suffix</i></code> to construct the names of the generated
- C++ files. In the single-database mode the default value for this option
- is <code><b>-odb</b></code>. In the multi-database mode it is
- <code><b>-odb</b></code> for the files corresponding to the
- <code><b>common</b></code> database and <code><b>-odb-</b><i>db</i></code>
- (where <code><i>db</i></code> is the database name) for other
- databases.</dd>
-
- <dt><code><b>--sql-file-suffix</b></code> <code><i>suffix</i></code></dt>
- <dd>Use <code><i>suffix</i></code> to construct the name of the generated
- schema SQL file. In the single-database mode by default no suffix is used.
- In the multi-database mode the default value for this option is
- <code><b>-</b><i>db</i></code> (where <code><i>db</i></code> is the
- database name).</dd>
-
- <dt><code><b>--schema-file-suffix</b></code> <code><i>suffix</i></code></dt>
- <dd>Use <code><i>suffix</i></code> to construct the name of the generated
- schema C++ source file. In the single-database mode the default value for
- this option is <code><b>-schema</b></code>. In the multi-database mode it
- is <code><b>-schema-</b><i>db</i></code> (where <code><i>db</i></code> is
- the database name). See the <code><b>--schema-format</b></code> option for
- details.</dd>
-
- <dt><code><b>--changelog-file-suffix</b></code> <code><i>sfx</i></code></dt>
- <dd>Use <code><i>sfx</i></code> to construct the name of the changelog
- file. In the single-database mode by default no suffix is used. In the
- multi-database mode the default value for this option is
- <code><b>-</b><i>db</i></code> (where <code><i>db</i></code> is the
- database name).</dd>
-
- <dt><code><b>--hxx-suffix</b></code> <code><i>suffix</i></code></dt>
- <dd>Use <code><i>suffix</i></code> instead of the default
- <code><b>.hxx</b></code> to construct the name of the generated C++ header
- file.</dd>
-
- <dt><code><b>--ixx-suffix</b></code> <code><i>suffix</i></code></dt>
- <dd>Use <code><i>suffix</i></code> instead of the default
- <code><b>.ixx</b></code> to construct the name of the generated C++ inline
- file.</dd>
-
- <dt><code><b>--cxx-suffix</b></code> <code><i>suffix</i></code></dt>
- <dd>Use <code><i>suffix</i></code> instead of the default
- <code><b>.cxx</b></code> to construct the name of the generated C++ source
- file.</dd>
-
- <dt><code><b>--sql-suffix</b></code> <code><i>suffix</i></code></dt>
- <dd>Use <code><i>suffix</i></code> instead of the default
- <code><b>.sql</b></code> to construct the name of the generated database
- schema file.</dd>
-
- <dt><code><b>--changelog-suffix</b></code> <code><i>suffix</i></code></dt>
- <dd>Use <code><i>suffix</i></code> instead of the default
- <code><b>.xml</b></code> to construct the name of the changelog file.</dd>
-
- <dt><code><b>--hxx-prologue</b></code> <code><i>text</i></code></dt>
- <dd>Insert <code><i>text</i></code> at the beginning of the generated C++
- header file.</dd>
-
- <dt><code><b>--ixx-prologue</b></code> <code><i>text</i></code></dt>
- <dd>Insert <code><i>text</i></code> at the beginning of the generated C++
- inline file.</dd>
-
- <dt><code><b>--cxx-prologue</b></code> <code><i>text</i></code></dt>
- <dd>Insert <code><i>text</i></code> at the beginning of the generated C++
- source file.</dd>
-
- <dt><code><b>--schema-prologue</b></code> <code><i>text</i></code></dt>
- <dd>Insert <code><i>text</i></code> at the beginning of the generated
- schema C++ source file.</dd>
-
- <dt><code><b>--sql-prologue</b></code> <code><i>text</i></code></dt>
- <dd>Insert <code><i>text</i></code> at the beginning of the generated
- database schema file.</dd>
-
- <dt><code><b>--migration-prologue</b></code> <code><i>text</i></code></dt>
- <dd>Insert <code><i>text</i></code> at the beginning of the generated
- database migration file.</dd>
-
- <dt><code><b>--sql-interlude</b></code> <code><i>text</i></code></dt>
- <dd>Insert <code><i>text</i></code> after all the <code><b>DROP</b></code>
- and before any <code><b>CREATE</b></code> statements in the generated
- database schema file.</dd>
-
- <dt><code><b>--hxx-epilogue</b></code> <code><i>text</i></code></dt>
- <dd>Insert <code><i>text</i></code> at the end of the generated C++ header
- file.</dd>
-
- <dt><code><b>--ixx-epilogue</b></code> <code><i>text</i></code></dt>
- <dd>Insert <code><i>text</i></code> at the end of the generated C++ inline
- file.</dd>
-
- <dt><code><b>--cxx-epilogue</b></code> <code><i>text</i></code></dt>
- <dd>Insert <code><i>text</i></code> at the end of the generated C++ source
- file.</dd>
-
- <dt><code><b>--schema-epilogue</b></code> <code><i>text</i></code></dt>
- <dd>Insert <code><i>text</i></code> at the end of the generated schema C++
- source file.</dd>
-
- <dt><code><b>--sql-epilogue</b></code> <code><i>text</i></code></dt>
- <dd>Insert <code><i>text</i></code> at the end of the generated database
- schema file.</dd>
-
- <dt><code><b>--migration-epilogue</b></code> <code><i>text</i></code></dt>
- <dd>Insert <code><i>text</i></code> at the end of the generated database
- migration file.</dd>
-
- <dt><code><b>--hxx-prologue-file</b></code> <code><i>file</i></code></dt>
- <dd>Insert the content of <code><i>file</i></code> at the beginning of the
- generated C++ header file.</dd>
-
- <dt><code><b>--ixx-prologue-file</b></code> <code><i>file</i></code></dt>
- <dd>Insert the content of <code><i>file</i></code> at the beginning of the
- generated C++ inline file.</dd>
-
- <dt><code><b>--cxx-prologue-file</b></code> <code><i>file</i></code></dt>
- <dd>Insert the content of <code><i>file</i></code> at the beginning of the
- generated C++ source file.</dd>
-
- <dt><code><b>--schema-prologue-file</b></code> <code><i>file</i></code></dt>
- <dd>Insert the content of <code><i>file</i></code> at the beginning of the
- generated schema C++ source file.</dd>
-
- <dt><code><b>--sql-prologue-file</b></code> <code><i>file</i></code></dt>
- <dd>Insert the content of <code><i>file</i></code> at the beginning of the
- generated database schema file.</dd>
-
- <dt><code><b>--migration-prologue-file</b></code> <code><i>f</i></code></dt>
- <dd>Insert the content of file <code><i>f</i></code> at the beginning of
- the generated database migration file.</dd>
-
- <dt><code><b>--sql-interlude-file</b></code> <code><i>file</i></code></dt>
- <dd>Insert the content of <code><i>file</i></code> after all the
- <code><b>DROP</b></code> and before any <code><b>CREATE</b></code>
- statements in the generated database schema file.</dd>
-
- <dt><code><b>--hxx-epilogue-file</b></code> <code><i>file</i></code></dt>
- <dd>Insert the content of <code><i>file</i></code> at the end of the
- generated C++ header file.</dd>
-
- <dt><code><b>--ixx-epilogue-file</b></code> <code><i>file</i></code></dt>
- <dd>Insert the content of <code><i>file</i></code> at the end of the
- generated C++ inline file.</dd>
-
- <dt><code><b>--cxx-epilogue-file</b></code> <code><i>file</i></code></dt>
- <dd>Insert the content of <code><i>file</i></code> at the end of the
- generated C++ source file.</dd>
-
- <dt><code><b>--schema-epilogue-file</b></code> <code><i>file</i></code></dt>
- <dd>Insert the content of <code><i>file</i></code> at the end of the
- generated schema C++ source file.</dd>
-
- <dt><code><b>--sql-epilogue-file</b></code> <code><i>file</i></code></dt>
- <dd>Insert the content of <code><i>file</i></code> at the end of the
- generated database schema file.</dd>
-
- <dt><code><b>--migration-epilogue-file</b></code> <code><i>f</i></code></dt>
- <dd>Insert the content of file <code><i>f</i></code> at the end of the
- generated database migration file.</dd>
-
- <dt><code><b>--odb-prologue</b></code> <code><i>text</i></code></dt>
- <dd>Compile <code><i>text</i></code> before the input header file. This
- option allows you to add additional declarations, such as custom traits
- specializations, to the ODB compilation process.</dd>
-
- <dt><code><b>--odb-prologue-file</b></code> <code><i>file</i></code></dt>
- <dd>Compile <code><i>file</i></code> contents before the input header
- file. Prologue files are compiled after all the prologue text fragments
- (<code><b>--odb-prologue</b></code> option).</dd>
-
- <dt><code><b>--odb-epilogue</b></code> <code><i>text</i></code></dt>
- <dd>Compile <code><i>text</i></code> after the input header file. This
- option allows you to add additional declarations, such as custom traits
- specializations, to the ODB compilation process.</dd>
-
- <dt><code><b>--odb-epilogue-file</b></code> <code><i>file</i></code></dt>
- <dd>Compile <code><i>file</i></code> contents after the input header file.
- Epilogue files are compiled after all the epilogue text fragments
- (<code><b>--odb-epilogue</b></code> option).</dd>
-
- <dt><code><b>--table-prefix</b></code> <code><i>prefix</i></code></dt>
- <dd>Add <code><i>prefix</i></code> to table names and, for databases that
- have global index and/or foreign key names, to those names as well. The
- prefix is added to both names that were specified with the <code><b>db
- table</b></code> and <code><b>db index</b></code> pragmas and those that
- were automatically derived from class and data member names. If you
- require a separator, such as an underscore, between the prefix and the
- name, then you should include it into the prefix value.</dd>
-
- <dt><code><b>--index-suffix</b></code> <code><i>suffix</i></code></dt>
- <dd>Use <code><i>suffix</i></code> instead of the default
- <code><b>_i</b></code> to construct index names. The suffix is only added
- to names that were automatically derived from data member names. If you
- require a separator, such as an underscore, between the name and the
- suffix, then you should include it into the suffix value.</dd>
-
- <dt><code><b>--fkey-suffix</b></code> <code><i>suffix</i></code></dt>
- <dd>Use <code><i>suffix</i></code> instead of the default
- <code><b>_fk</b></code> to construct foreign key names. If you require a
- separator, such as an underscore, between the name and the suffix, then
- you should include it into the suffix value.</dd>
-
- <dt><code><b>--sequence-suffix</b></code> <code><i>suffix</i></code></dt>
- <dd>Use <code><i>suffix</i></code> instead of the default
- <code><b>_seq</b></code> to construct sequence names. If you require a
- separator, such as an underscore, between the name and the suffix, then
- you should include it into the suffix value.</dd>
-
- <dt><code><b>--sql-name-case</b></code> <code><i>case</i></code></dt>
- <dd>Convert all automatically-derived SQL names to upper or lower case.
- Valid values for this option are <code><b>upper</b></code> and
- <code><b>lower</b></code>.</dd>
-
- <dt><code><b>--table-regex</b></code> <code><i>regex</i></code></dt>
- <dd>Add <code><i>regex</i></code> to the list of regular expressions that
- is used to transform automatically-derived table names. See the SQL NAME
- TRANSFORMATIONS section below for details.</dd>
-
- <dt><code><b>--column-regex</b></code> <code><i>regex</i></code></dt>
- <dd>Add <code><i>regex</i></code> to the list of regular expressions that
- is used to transform automatically-derived column names. See the SQL NAME
- TRANSFORMATIONS section below for details.</dd>
-
- <dt><code><b>--index-regex</b></code> <code><i>regex</i></code></dt>
- <dd>Add <code><i>regex</i></code> to the list of regular expressions that
- is used to transform automatically-derived index names. See the SQL NAME
- TRANSFORMATIONS section below for details.</dd>
-
- <dt><code><b>--fkey-regex</b></code> <code><i>regex</i></code></dt>
- <dd>Add <code><i>regex</i></code> to the list of regular expressions that
- is used to transform automatically-derived foreign key names. See the SQL
- NAME TRANSFORMATIONS section below for details.</dd>
-
- <dt><code><b>--sequence-regex</b></code> <code><i>regex</i></code></dt>
- <dd>Add <code><i>regex</i></code> to the list of regular expressions that
- is used to transform automatically-derived sequence names. See the SQL
- NAME TRANSFORMATIONS section below for details.</dd>
-
- <dt><code><b>--statement-regex</b></code> <code><i>regex</i></code></dt>
- <dd>Add <code><i>regex</i></code> to the list of regular expressions that
- is used to transform automatically-derived prepared statement names. See
- the SQL NAME TRANSFORMATIONS section below for details.</dd>
-
- <dt><code><b>--sql-name-regex</b></code> <code><i>regex</i></code></dt>
- <dd>Add <code><i>regex</i></code> to the list of regular expressions that
- is used to transform all automatically-derived SQL names. See the SQL NAME
- TRANSFORMATIONS section below for details.</dd>
-
- <dt><code><b>--sql-name-regex-trace</b></code></dt>
- <dd>Trace the process of applying regular expressions specified with the
- SQL name <code><b>--*-regex</b></code> options. Use this option to find
- out why your regular expressions don't do what you expected them to
- do.</dd>
-
- <dt><code><b>--accessor-regex</b></code> <code><i>regex</i></code></dt>
- <dd>Add <code><i>regex</i></code> to the list of regular expressions used
- to transform data member names to function names when searching for a
- suitable accessor function. The argument to this option is a Perl-like
- regular expression in the form
- <code><b>/</b><i>pattern</i><b>/</b><i>replacement</i><b>/</b></code>. Any
- character can be used as a delimiter instead of '<code><b>/</b></code>'
- and the delimiter can be escaped inside <code><i>pattern</i></code> and
- <code><i>replacement</i></code> with a backslash (<code><b>\</b></code>).
- You can specify multiple regular expressions by repeating this option.
-
- <p>All the regular expressions are tried in the order specified and the
- first expression that produces a suitable accessor function is used. Each
- expression is tried twice: first with the actual member name and then with
- the member's <i>public name</i> which is obtained by removing the common
- member name decorations, such as leading and trailing underscores, the
- <code><b>m_</b></code> prefix, etc. The ODB compiler also includes a
- number of built-in expressions for commonly used accessor names, such as
- <code><b>get_foo</b></code>, <code><b>getFoo</b></code>,
- <code><b>getfoo</b></code>, and just <code><b>foo</b></code>. The built-in
- expressions are tried last.</p>
-
- <p>As an example, the following expression transforms data members with
- public names in the form <code><b>foo</b></code> to accessor names in the
- form <code><b>GetFoo</b></code>:</p>
-
- <p class="code"><code><b>/(.+)/Get\u$1/</b></code></p>
-
- <p>See also the REGEX AND SHELL QUOTING section below.</p></dd>
-
- <dt><code><b>--accessor-regex-trace</b></code></dt>
- <dd>Trace the process of applying regular expressions specified with the
- <code><b>--accessor-regex</b></code> option. Use this option to find out
- why your regular expressions don't do what you expected them to do.</dd>
-
- <dt><code><b>--modifier-regex</b></code> <code><i>regex</i></code></dt>
- <dd>Add <code><i>regex</i></code> to the list of regular expressions used
- to transform data member names to function names when searching for a
- suitable modifier function. The argument to this option is a Perl-like
- regular expression in the form
- <code><b>/</b><i>pattern</i><b>/</b><i>replacement</i><b>/</b></code>. Any
- character can be used as a delimiter instead of '<code><b>/</b></code>'
- and the delimiter can be escaped inside <code><i>pattern</i></code> and
- <code><i>replacement</i></code> with a backslash (<code><b>\</b></code>).
- You can specify multiple regular expressions by repeating this option.
-
- <p>All the regular expressions are tried in the order specified and the
- first expression that produces a suitable modifier function is used. Each
- expression is tried twice: first with the actual member name and then with
- the member's <i>public name</i> which is obtained by removing the common
- member name decorations, such as leading and trailing underscores, the
- <code><b>m_</b></code> prefix, etc. The ODB compiler also includes a
- number of built-in expressions for commonly used modifier names, such as
- <code><b>set_foo</b></code>, <code><b>setFoo</b></code>,
- <code><b>setfoo</b></code>, and just <code><b>foo</b></code>. The built-in
- expressions are tried last.</p>
-
- <p>As an example, the following expression transforms data members with
- public names in the form <code><b>foo</b></code> to modifier names in the
- form <code><b>SetFoo</b></code>:</p>
-
- <p class="code"><code><b>/(.+)/Set\u$1/</b></code></p>
-
- <p>See also the REGEX AND SHELL QUOTING section below.</p></dd>
-
- <dt><code><b>--modifier-regex-trace</b></code></dt>
- <dd>Trace the process of applying regular expressions specified with the
- <code><b>--modifier-regex</b></code> option. Use this option to find out
- why your regular expressions don't do what you expected them to do.</dd>
-
- <dt><code><b>--include-with-brackets</b></code></dt>
- <dd>Use angle brackets (&lt;>) instead of quotes ("") in the generated
- <code><b>#include</b></code> directives.</dd>
-
- <dt><code><b>--include-prefix</b></code> <code><i>prefix</i></code></dt>
- <dd>Add <code><i>prefix</i></code> to the generated
- <code><b>#include</b></code> directive paths.</dd>
-
- <dt><code><b>--include-regex</b></code> <code><i>regex</i></code></dt>
- <dd>Add <code><i>regex</i></code> to the list of regular expressions used
- to transform generated <code><b>#include</b></code> directive paths. The
- argument to this option is a Perl-like regular expression in the form
- <code><b>/</b><i>pattern</i><b>/</b><i>replacement</i><b>/</b></code>. Any
- character can be used as a delimiter instead of '<code><b>/</b></code>'
- and the delimiter can be escaped inside <code><i>pattern</i></code> and
- <code><i>replacement</i></code> with a backslash (<code><b>\</b></code>).
- You can specify multiple regular expressions by repeating this option. All
- the regular expressions are tried in the order specified and the first
- expression that matches is used.
-
- <p>As an example, the following expression transforms include paths in the
- form <code><b>foo/bar-odb.h</b></code> to paths in the form
- <code><b>foo/generated/bar-odb.h</b></code>:</p>
-
- <p
- class="code"><code><b>%foo/(.+)-odb.h%foo/generated/$1-odb.h%</b></code></p>
-
- <p>See also the REGEX AND SHELL QUOTING section below.</p></dd>
-
- <dt><code><b>--include-regex-trace</b></code></dt>
- <dd>Trace the process of applying regular expressions specified with the
- <code><b>--include-regex</b></code> option. Use this option to find out
- why your regular expressions don't do what you expected them to do.</dd>
-
- <dt><code><b>--guard-prefix</b></code> <code><i>prefix</i></code></dt>
- <dd>Add <code><i>prefix</i></code> to the generated header inclusion
- guards. The prefix is transformed to upper case and characters that are
- illegal in a preprocessor macro name are replaced with underscores.</dd>
-
- <dt><code><b>--show-sloc</b></code></dt>
- <dd>Print the number of generated physical source lines of code
- (SLOC).</dd>
-
- <dt><code><b>--sloc-limit</b></code> <code><i>num</i></code></dt>
- <dd>Check that the number of generated physical source lines of code
- (SLOC) does not exceed <code><i>num</i></code>.</dd>
-
- <dt><code><b>--options-file</b></code> <code><i>file</i></code></dt>
- <dd>Read additional options from <code><i>file</i></code>. Each option
- should appear on a separate line optionally followed by space or equal
- sign (<code><b>=</b></code>) and an option value. Empty lines and lines
- starting with <code><b>#</b></code> are ignored. Option values can be
- enclosed in double (<code><b>"</b></code>) or single
- (<code><b>'</b></code>) quotes to preserve leading and trailing
- whitespaces as well as to specify empty values. If the value itself
- contains trailing or leading quotes, enclose it with an extra pair of
- quotes, for example <code><b>'"x"'</b></code>. Non-leading and
- non-trailing quotes are interpreted as being part of the option value.
-
- <p>The semantics of providing options in a file is equivalent to providing
- the same set of options in the same order on the command line at the point
- where the <code><b>--options-file</b></code> option is specified except
- that the shell escaping and quoting is not required. Repeat this option to
- specify more than one options file.</p></dd>
-
- <dt><code><b>-x</b></code> <code><i>option</i></code></dt>
- <dd>Pass <code><i>option</i></code> to the underlying C++ compiler
- (<code><b>g++</b></code>). The <code><i>option</i></code> value that
- doesn't start with '<code><b>-</b></code>' is considered the
- <code><b>g++</b></code> executable name.</dd>
-
- <dt><code><b>-v</b></code></dt>
- <dd>Print the commands executed to run the stages of compilation.</dd>
-
- <dt><code><b>--trace</b></code></dt>
- <dd>Trace the compilation process.</dd>
-
- <dt><code><b>--mysql-engine</b></code> <code><i>engine</i></code></dt>
- <dd>Use <code><i>engine</i></code> instead of the default
- <code><b>InnoDB</b></code> in the generated database schema file. For more
- information on the storage engine options see the MySQL documentation. If
- you would like to use the database-default engine, pass
- <code><b>default</b></code> as the value for this option.</dd>
-
- <dt><code><b>--sqlite-override-null</b></code></dt>
- <dd>Make all columns in the generated database schema allow
- <code><b>NULL</b></code> values. This is primarily useful in schema
- migration since SQLite does not support dropping of columns. By making all
- columns <code><b>NULL</b></code> we can later "delete" them by setting
- their values to <code><b>NULL</b></code>. Note that this option overrides
- even the <code><b>not_null</b></code> pragma.</dd>
-
- <dt><code><b>--sqlite-lax-auto-id</b></code></dt>
- <dd>Do not force monotonically increasing automatically-assigned object
- ids. In this mode the generated database schema omits the
- <code><b>AUTOINCREMENT</b></code> keyword which results in faster object
- persistence but may lead to automatically-assigned ids not being in a
- strictly ascending order. Refer to the SQLite documentation for
- details.</dd>
-
- <dt><code><b>--pgsql-server-version</b></code> <code><i>ver</i></code></dt>
- <dd>Specify the minimum PostgreSQL server version with which the generated
- C++ code and schema will be used. This information is used to enable
- version-specific optimizations and workarounds in the generated C++ code
- and schema. The version must be in the
- <code><i>major</i><b>.</b><i>minor</i></code> form, for example,
- <code><b>9.1</b></code>. If this option is not specified, then
- <code><b>7.4</b></code> or later is assumed.</dd>
-
- <dt><code><b>--oracle-client-version</b></code> <code><i>ver</i></code></dt>
- <dd>Specify the minimum Oracle client library (OCI) version with which the
- generated C++ code will be linked. This information is used to enable
- version-specific optimizations and workarounds in the generated C++ code.
- The version must be in the <code><i>major</i><b>.</b><i>minor</i></code>
- form, for example, <code><b>11.2</b></code>. If this option is not
- specified, then <code><b>10.1</b></code> or later is assumed.</dd>
-
- <dt><code><b>--oracle-warn-truncation</b></code></dt>
- <dd>Warn about SQL names that are longer than 30 characters and are
- therefore truncated. Note that during database schema generation
- (<code><b>--generate-schema</b></code>) ODB detects when such truncations
- lead to name conflicts and issues diagnostics even without this option
- specified.</dd>
-
- <dt><code><b>--mssql-server-version</b></code> <code><i>ver</i></code></dt>
- <dd>Specify the minimum SQL Server server version with which the generated
- C++ code and schema will be used. This information is used to enable
- version-specific optimizations and workarounds in the generated C++ code
- and schema. The version must be in the
- <code><i>major</i><b>.</b><i>minor</i></code> form, for example,
- <code><b>9.0</b></code> (SQL Server 2005), <code><b>10.5</b></code>
- (2008R2), or <code><b>11.0</b></code> (2012). If this option is not
- specified, then <code><b>10.0</b></code> (SQL Server 2008) or later is
- assumed.</dd>
-
- <dt><code><b>--mssql-short-limit</b></code> <code><i>size</i></code></dt>
- <dd>Specify the short data size limit. If a character, national character,
- or binary data type has a maximum length (in bytes) less than or equal to
- this limit, then it is treated as <i>short data</i>, otherwise it is
- <i>long data</i>. For short data ODB pre-allocates an intermediate buffer
- of the maximum size and binds it directly to a parameter or result column.
- This way the underlying API (ODBC) can read/write directly from/to this
- buffer. In the case of long data, the data is read/written in chunks using
- the <code><b>SQLGetData()</b></code>/<code><b>SQLPutData()</b></code> ODBC
- functions. While the long data approach reduces the amount of memory used
- by the application, it may require greater CPU resources. The default
- short data limit is 1024 bytes. When setting a custom short data limit,
- make sure that it is sufficiently large so that no object id in the
- application is treated as long data.</dd>
- </dl>
-
- <h1>SQL NAME TRANSFORMATIONS</h1>
-
- <p>The ODB compiler provides a number of mechanisms for transforming
- automatically-derived SQL names, such as tables, columns, etc.,
- to match a specific naming convention. At the higher level, we can
- add a prefix to global names (tables and, for some databases,
- indexes and/or foreign keys) with the <code><b>--table-prefix</b></code>
- option. Similarly, we can specify custom suffixes for
- automatically-derived
- index (<code><b>--index-suffix</b></code>; default is <code><b>_i</b></code>),
- foreign key (<code><b>--fkey-suffix</b></code>; default is <code><b>_fk</b></code>), and
- sequence (<code><b>--sequence-suffix</b></code>; default is <code><b>_seq</b></code>)
- names. Finally, we can also convert all the names to upper or lower
- case with the <code><b>--sql-name-case</b></code> option (valid values
- are <code><b>upper</b></code> and <code><b>lower</b></code>).</p>
-
- <p>At the lower level we can specify a set of regular expressions to
- implement arbitrary transformations of the automatically-derived SQL
- names. If we want a particular regular expression only to apply to
- a specific name, for example, table or column, then we use one of the
- <code><b>--</b><i>kind</i><b>-regex</b></code> options, where
- <code><i>kind</i></code> can be <code><b>table</b></code>,
- <code><b>column</b></code>, <code><b>index</b></code>,
- <code><b>fkey</b></code>, <code><b>sequence</b></code>, or
- <code><b>statement</b></code>. On the other hand, if we want our
- regular expressions to apply to all SQL names, then we use the
- <code><b>--sql-name-regex</b></code> option.</p>
-
- <p>The interaction between the higher and lower level transformations
- is as follows. Prefixes and suffixes are added first. Then the
- regular expression transformations are applied. Finally, if requested,
- the name is converted to upper or lower case. Note also that all of
- these transformations except for <code><b>--table-prefix</b></code>
- only apply to automatically-derived names. In other words, if a table,
- column, etc., name was explicitly specified with a pragma, then it
- is used as is, without applying any (except for the table prefix)
- transformations.</p>
-
- <p>The value for the <code><b>--*-regex</b></code> options is a Perl-like
- regular expression in the form
- <code><b>/</b><i>pattern</i><b>/</b><i>replacement</i><b>/</b></code>.
- Any character can be used as a delimiter instead of <code><b>/</b></code>
- and the delimiter can be escaped inside <code><i>pattern</i></code> and
- <code><i>replacement</i></code> with a backslash (<code><b>\</b></code>).
- You can also specify multiple regular expressions by repeating these
- options.</p>
-
- <p>All the regular expressions are tried in the order specified with the
- name-specific expressions (for example, <code><b>--table-regex</b></code>)
- tried first followed by the generic expressions
- (<code><b>--sql-name-regex</b></code>). The first expression that
- matches is used.</p>
-
- <p>As an example, consider a regular expression that transforms a class
- name in the form <code><b>CFoo</b></code> to a table name in the
- form <code><b>FOO</b></code>:</p>
-
- <p><code><b>--table-regex '/C(.+)/\U$1/'</b></code></p>
-
- <p>As a more interesting example, consider the transformation of class
- names that follow the upper camel case convention (for example,
- <code><b>FooBar</b></code>) to table names that follow the
- underscore-separated, all upper case convention (for example,
- <code><b>FOO_BAR</b></code>). For this case we have to use
- separate expressions to handle one-word, two-word, etc.,
- names:</p>
-
- <p><code><b>--table-regex '/([A-z][a-z]+)/\U$1/'</b></code></p>
- <p><code><b>--table-regex '/([A-z][a-z]+)([A-z][a-z]+)/\U$1_$2/'</b></code></p>
-
- <p>See also the REGEX AND SHELL QUOTING section below.</p>
-
- <h1>REGEX AND SHELL QUOTING</h1>
-
- <p>When entering a regular expression argument in the shell
- command line it is often necessary to use quoting (enclosing
- the argument in <code><b>"&nbsp;"</b></code> or
- <code><b>'&nbsp;'</b></code>) in order to prevent the shell
- from interpreting certain characters, for example, spaces as
- argument separators and <code><b>$</b></code> as variable
- expansions.</p>
-
- <p>Unfortunately it is hard to achieve this in a manner that is
- portable across POSIX shells, such as those found on
- GNU/Linux and UNIX, and Windows shell. For example, if you
- use <code><b>"&nbsp;"</b></code> for quoting you will get a
- wrong result with POSIX shells if your expression contains
- <code><b>$</b></code>. The standard way of dealing with this
- on POSIX systems is to use <code><b>'&nbsp;'</b></code> instead.
- Unfortunately, Windows shell does not remove <code><b>'&nbsp;'</b></code>
- from arguments when they are passed to applications. As a result you
- may have to use <code><b>'&nbsp;'</b></code> for POSIX and
- <code><b>"&nbsp;"</b></code> for Windows (<code><b>$</b></code> is
- not treated as a special character on Windows).</p>
-
- <p>Alternatively, you can save regular expression options into
- a file, one option per line, and use this file with the
- <code><b>--options-file</b></code> option. With this approach
- you don't need to worry about shell quoting.</p>
-
- <h1>DIAGNOSTICS</h1>
-
- <p>If the input file is not valid C++, <code><b>odb</b></code>
- will issue diagnostic messages to STDERR and exit with non-zero exit
- code.</p>
-
- <h1>BUGS</h1>
-
- <p>Send bug reports to the
- <a href="mailto:odb-users@codesynthesis.com">odb-users@codesynthesis.com</a> mailing list.</p>
-
- </div>
- <div id="footer">
- Copyright &#169; 2009-2023 Code Synthesis Tools CC.
-
- <div id="terms">
- Permission is granted to copy, distribute and/or modify this
- document under the terms of the
- <a href="http://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.
- </div>
- </div>
-</div>
-</body>
-</html>