diff options
Diffstat (limited to 'doc/pregenerated/odb.xhtml')
| -rw-r--r-- | doc/pregenerated/odb.xhtml | 978 |
1 files changed, 978 insertions, 0 deletions
diff --git a/doc/pregenerated/odb.xhtml b/doc/pregenerated/odb.xhtml new file mode 100644 index 0000000..0a9785c --- /dev/null +++ b/doc/pregenerated/odb.xhtml @@ -0,0 +1,978 @@ +<!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="© 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<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><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 + <...></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 (<>) 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>" "</b></code> or + <code><b>' '</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>" "</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>' '</b></code> instead. + Unfortunately, Windows shell does not remove <code><b>' '</b></code> + from arguments when they are passed to applications. As a result you + may have to use <code><b>' '</b></code> for POSIX and + <code><b>" "</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 © 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> |