Provided by: odb_2.4.0-16_amd64 bug

NAME

       odb - object-relational mapping (ORM) compiler for C++

SYNOPSIS

       odb [ options ] file [ file...  ]

DESCRIPTION

       Given  a  set  of  C++ classes in a header file, odb 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
       --database option (see below).

       For an input file in the form name.hxx (other file  extensions  can  be  used  instead  of
       .hxx),  in the single-database mode (the default), the generated C++ files by default have
       the following names: name-odb.hxx (header file), name-odb.ixx  (inline  file),  and  name-
       odb.cxx  (source file). Additionally, if the --generate-schema option is specified and the
       sql schema format is requested (see --schema-format), the name.sql database schema file is
       generated.  If  the  separate  schema  format  is requested, the database creation code is
       generated into the separate name-schema.cxx file.

       In the multi-database mode (see the --multi-database option below),  the  generated  files
       corresponding  to  the common database have the same names as in the single-database mode.
       For other databases, the file names include the database name: name-odb-db.hxx,  name-odb-
       db.ixx,  name-odb-db.cxx,  name-db.sql,  and  name-schema-db.cxx (where db is the database
       name).

OPTIONS

       --help Print usage information and exit.

       --version
              Print version and exit.

       -I dir Add dir to the beginning of the list of directories to  be  searched  for  included
              header files.

       -D name[=def]
              Define  macro name with definition def. If definition is omitted, define name to be
              1.

       -U name
              Cancel any previous definitions of macro name, either built-in or provided with the
              -D option.

       --database|-d db
              Generate  code  for  the db database. Valid values are mssql, mysql, oracle, pgsql,
              sqlite, and common (multi-database mode only).

       --multi-database|-m type
              Enable multi-database support and specify its type. Valid values  for  this  option
              are static and dynamic.

              In the multi-database mode, options that determine the kind (for example, --schema-
              format), names (for example, --odb-file-suffix), 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, mysql:value. This restricts the value of such  an
              option to only apply to generated files corresponding to this database.

       --default-database db
              When  static  multi-database  support  is used, specify the database that should be
              made the default. When dynamic multi-database support is  used,  common  is  always
              made the default database.

       --generate-query|-q
              Generate query support code. Without this support you cannot use views and can only
              load objects via their ids.

       --generate-prepared
              Generate prepared query execution support code.

       --omit-unprepared
              Omit un-prepared (once-off) query execution support code.

       --generate-session|-e
              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 db session pragma.

       --generate-schema|-s
              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.

              Depending  on  the database being used (--database 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 --schema-format option to alter the default schema format.

              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 --suppress-migration option.

       --generate-schema-only
              Generate  only  the  database  schema.  Note  that  this  option is only valid when
              generating schema as a standalone SQL file (see --schema-format for details).

       --suppress-migration
              Suppress the generation of database schema migration statements.

       --suppress-schema-version
              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 odb::database::schema_version() function.

       --schema-version-table name
              Specify  the  alternative  schema  version  table  name  instead  of  the   default
              schema_version.  If  you specify this option then you are also expected to manually
              specify   the   schema    version    table    name    at    runtime    using    the
              odb::database::schema_version_table() function. The table name can be qualified.

       --schema-format format
              Generate  the  database  schema  in  the  specified  format.  Pass sql as format to
              generate the database schema as a standalone SQL file or pass embedded to embed the
              schema  into  the  generated  C++  code.  The separate value is similar to embedded
              except the schema creation code is  generated  into  a  separate  C++  file  (name-
              schema.cxx  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.

       --omit-drop
              Omit DROP statements from the generated database schema.

       --omit-create
              Omit CREATE statements from the generated database schema.

       --schema-name name
              Use  name  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 --schema option. If this option is not specified, the empty name, which is  the
              default schema name, is used.

       --fkeys-deferrable-mode m
              Use  constraint checking mode m in foreign keys generated for object relationships.
              Valid values for this option are not_deferrable, immediate, and deferred (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.

              Note also that if you use either not_deferrable or immediate mode, then  the  order
              in  which  you  persist,  update,  and  erase  objects within a transaction becomes
              important.

       --default-pointer ptr
              Use ptr as the default pointer for persistent objects and views.  Objects and views
              that  do  not  have  a  pointer  assigned  with the db pointer pragma will use this
              pointer by default. The value of this option can be * which denotes the raw pointer
              and  is  the  default,  or  qualified  name  of a smart pointer class template, for
              example, std::auto_ptr. 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 std::auto_ptr<object>.  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.

              Except for the raw pointer and the standard smart pointers defined in the  <memory>
              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 --hxx-prologue option to add the necessary #include  directive  to  the
              generated code.

       --session-type type
              Use  type as the alternative session type instead of the default odb::session. 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 --hxx-prologue* options.

       --profile|-p name
              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 -database.options suffix to name, where database is
              the database name as specified with the --database 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 .options suffix.

              The profile options files are searched for in the same set of  directories  as  C++
              headers  included  with  the  #include  <...>  directive (built-in paths plus those
              specified with the -I options). The options file  is  first  searched  for  in  the
              directory itself and then in its odb/ subdirectory.

              For  the  format  of the options file refer to the --options-file option below. You
              can repeat this option to specify more than one profile.

       --at-once
              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 --input-name 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
              #include directive resolution.

       --schema schema
              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 --schema-name option.

       --export-symbol symbol
              Insert    symbol   in   places   where   DLL   export/import   control   statements
              (__declspec(dllexport/dllimport))  are  necessary.  See  also  the  --extern-symbol
              option below.

       --extern-symbol symbol
              If  symbol  is  defined, insert it in places where a template instantiation must be
              declared extern. This option is normally used together  with  --export-symbol  when
              both multi-database support and queries are enabled.

       --std version
              Specify  the  C++ standard that should be used during compilation. Valid values are
              c++98 (default), c++11, and c++14.

       --warn-hard-add
              Warn about hard-added data members.

       --warn-hard-delete
              Warn about hard-deleted data members and persistent classes.

       --warn-hard
              Warn about both hard-added and hard-deleted data members and persistent classes.

       --output-dir|-o dir
              Write the generated files to dir instead of the current directory.

       --input-name name
              Use name instead of the input file to derive the names of the generated  files.  If
              the  --at-once  option is specified, then the directory part of name is used as the
              location of the combined file.  Refer to the --at-once option for details.

       --changelog file
              Read/write changelog from/to file  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 --output-dir  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  --changelog-in  and  --changelog-out options to specify
              different input and output chaneglog files.

       --changelog-in file
              Read changelog from file instead of the default changelog file. If this  option  is
              specified,  then you must also specify the output chanegelog file with --changelog-
              out.

       --changelog-out file
              Write changelog to file instead of the default changelog file. If  this  option  is
              specified,  then  you must also specify the input chanegelog file with --changelog-
              in.

       --changelog-dir dir
              Use dir instead of the input file directory as the changelog file  directory.  This
              directory  is  also  added  to  changelog  files  specified  with  the --changelog,
              --changelog-in, and --changelog-in options unless they are absolute paths.

       --init-changelog
              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.

       --odb-file-suffix suffix
              Use suffix to construct the names of  the  generated  C++  files.  In  the  single-
              database mode the default value for this option is -odb. In the multi-database mode
              it is -odb for the files corresponding to the common database and -odb-db (where db
              is the database name) for other databases.

       --sql-file-suffix suffix
              Use  suffix  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 -db (where db is the database name).

       --schema-file-suffix suffix
              Use  suffix  to  construct the name of the generated schema C++ source file. In the
              single-database mode the default value for this option is -schema.  In  the  multi-
              database  mode  it is -schema-db (where db is the database name). See the --schema-
              format option for details.

       --changelog-file-suffix sfx
              Use sfx 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 -db (where db is the database name).

       --hxx-suffix suffix
              Use suffix instead of the default .hxx to construct the name of the  generated  C++
              header file.

       --ixx-suffix suffix
              Use  suffix  instead of the default .ixx to construct the name of the generated C++
              inline file.

       --cxx-suffix suffix
              Use suffix instead of the default .cxx to construct the name of the  generated  C++
              source file.

       --sql-suffix suffix
              Use  suffix  instead  of  the  default  .sql to construct the name of the generated
              database schema file.

       --changelog-suffix suffix
              Use suffix instead of the default .xml to construct the name of the changelog file.

       --hxx-prologue text
              Insert text at the beginning of the generated C++ header file.

       --ixx-prologue text
              Insert text at the beginning of the generated C++ inline file.

       --cxx-prologue text
              Insert text at the beginning of the generated C++ source file.

       --schema-prologue text
              Insert text at the beginning of the generated schema C++ source file.

       --sql-prologue text
              Insert text at the beginning of the generated database schema file.

       --migration-prologue text
              Insert text at the beginning of the generated database migration file.

       --sql-interlude text
              Insert text after all the DROP and before any CREATE statements  in  the  generated
              database schema file.

       --hxx-epilogue text
              Insert text at the end of the generated C++ header file.

       --ixx-epilogue text
              Insert text at the end of the generated C++ inline file.

       --cxx-epilogue text
              Insert text at the end of the generated C++ source file.

       --schema-epilogue text
              Insert text at the end of the generated schema C++ source file.

       --sql-epilogue text
              Insert text at the end of the generated database schema file.

       --migration-epilogue text
              Insert text at the end of the generated database migration file.

       --hxx-prologue-file file
              Insert the content of file at the beginning of the generated C++ header file.

       --ixx-prologue-file file
              Insert the content of file at the beginning of the generated C++ inline file.

       --cxx-prologue-file file
              Insert the content of file at the beginning of the generated C++ source file.

       --schema-prologue-file file
              Insert  the  content  of  file  at the beginning of the generated schema C++ source
              file.

       --sql-prologue-file file
              Insert the content of file at the beginning of the generated database schema file.

       --migration-prologue-file f
              Insert the content of file f at the beginning of the generated  database  migration
              file.

       --sql-interlude-file file
              Insert  the  content of file after all the DROP and before any CREATE statements in
              the generated database schema file.

       --hxx-epilogue-file file
              Insert the content of file at the end of the generated C++ header file.

       --ixx-epilogue-file file
              Insert the content of file at the end of the generated C++ inline file.

       --cxx-epilogue-file file
              Insert the content of file at the end of the generated C++ source file.

       --schema-epilogue-file file
              Insert the content of file at the end of the generated schema C++ source file.

       --sql-epilogue-file file
              Insert the content of file at the end of the generated database schema file.

       --migration-epilogue-file f
              Insert the content of file f at the end of the generated database migration file.

       --odb-prologue text
              Compile text before the input header file. This option allows you to add additional
              declarations,  such  as  custom  traits  specializations,  to  the  ODB compilation
              process.

       --odb-prologue-file file
              Compile file contents before the input header file.  Prologue  files  are  compiled
              after all the prologue text fragments (--odb-prologue option).

       --odb-epilogue text
              Compile  text after the input header file. This option allows you to add additional
              declarations, such  as  custom  traits  specializations,  to  the  ODB  compilation
              process.

       --odb-epilogue-file file
              Compile  file  contents  after  the  input header file. Epilogue files are compiled
              after all the epilogue text fragments (--odb-epilogue option).

       --table-prefix prefix
              Add prefix 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 db table and db index 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.

       --index-suffix suffix
              Use  suffix instead of the default _i 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.

       --fkey-suffix suffix
              Use suffix instead of the default _fk  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.

       --sequence-suffix suffix
              Use suffix instead of the default _seq 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.

       --sql-name-case case
              Convert all automatically-derived SQL names to upper or lower  case.  Valid  values
              for this option are  upper and lower.

       --table-regex regex
              Add   regex  to  the  list  of  regular  expressions  that  is  used  to  transform
              automatically-derived table names. See the SQL NAME TRANSFORMATIONS  section  below
              for details.

       --column-regex regex
              Add   regex  to  the  list  of  regular  expressions  that  is  used  to  transform
              automatically-derived column names. See the SQL NAME TRANSFORMATIONS section  below
              for details.

       --index-regex regex
              Add   regex  to  the  list  of  regular  expressions  that  is  used  to  transform
              automatically-derived index names. See the SQL NAME TRANSFORMATIONS  section  below
              for details.

       --fkey-regex regex
              Add   regex  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.

       --sequence-regex regex
              Add   regex  to  the  list  of  regular  expressions  that  is  used  to  transform
              automatically-derived sequence names. See  the  SQL  NAME  TRANSFORMATIONS  section
              below for details.

       --statement-regex regex
              Add   regex  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.

       --sql-name-regex regex
              Add  regex  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.

       --sql-name-regex-trace
              Trace  the  process  of  applying  regular  expressions specified with the SQL name
              --*-regex options. Use this option to find out why your regular  expressions  don't
              do what you expected them to do.

       --accessor-regex regex
              Add regex 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 /pattern/replacement/.
              Any character can be used as a delimiter instead of /  and  the  delimiter  can  be
              escaped  inside  pattern  and  replacement  with  a  backslash (\). 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  produces a suitable accessor function is used. Each expression is
              tried twice: first with the actual member name and then with  the  member's  public
              name  which  is  obtained  by  removing the common member name decorations, such as
              leading and trailing underscores,  the  m_  prefix,  etc.  The  ODB  compiler  also
              includes a number of built-in expressions for commonly used accessor names, such as
              get_foo, getFoo, getfoo, and just foo. The built-in expressions are tried last.

              As an example, the following expression transforms data members with  public  names
              in the form foo to accessor names in the form GetFoo:

              /(.+)/Get\u$1/

              See also the REGEX AND SHELL QUOTING section below.

       --accessor-regex-trace
              Trace  the  process  of applying regular expressions specified with the --accessor-
              regex option. Use this option to find out why your  regular  expressions  don't  do
              what you expected them to do.

       --modifier-regex regex
              Add regex 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 /pattern/replacement/.
              Any character can be used as a delimiter instead of /  and  the  delimiter  can  be
              escaped  inside  pattern  and  replacement  with  a  backslash (\). 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  produces a suitable modifier function is used. Each expression is
              tried twice: first with the actual member name and then with  the  member's  public
              name  which  is  obtained  by  removing the common member name decorations, such as
              leading and trailing underscores,  the  m_  prefix,  etc.  The  ODB  compiler  also
              includes a number of built-in expressions for commonly used modifier names, such as
              set_foo, setFoo, setfoo, and just foo. The built-in expressions are tried last.

              As an example, the following expression transforms data members with  public  names
              in the form foo to modifier names in the form SetFoo:

              /(.+)/Set\u$1/

              See also the REGEX AND SHELL QUOTING section below.

       --modifier-regex-trace
              Trace  the  process  of applying regular expressions specified with the --modifier-
              regex option. Use this option to find out why your  regular  expressions  don't  do
              what you expected them to do.

       --include-with-brackets
              Use  angle  brackets  (<>)  instead  of  quotes  ("")  in  the  generated  #include
              directives.

       --include-prefix prefix
              Add prefix to the generated #include directive paths.

       --include-regex regex
              Add regex to the list of regular expressions used to transform  generated  #include
              directive  paths.  The argument to this option is a Perl-like regular expression in
              the form /pattern/replacement/. Any character can be used as a delimiter instead of
              /  and the delimiter can be escaped inside pattern and replacement with a backslash
              (\). 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.

              As an example, the following  expression  transforms  include  paths  in  the  form
              foo/bar-odb.h to paths in the form foo/generated/bar-odb.h:

              %foo/(.+)-odb.h%foo/generated/$1-odb.h%

              See also the REGEX AND SHELL QUOTING section below.

       --include-regex-trace
              Trace  the  process  of  applying regular expressions specified with the --include-
              regex option. Use this option to find out why your  regular  expressions  don't  do
              what you expected them to do.

       --guard-prefix prefix
              Add  prefix  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.

       --show-sloc
              Print the number of generated physical source lines of code (SLOC).

       --sloc-limit num
              Check  that  the  number of generated physical source lines of code (SLOC) does not
              exceed num.

       --options-file file
              Read additional options from file with each option appearing  on  a  separate  line
              optionally  followed  by  space and an option value. Empty lines and lines starting
              with # are ignored. Option values can be enclosed  in  double  (")  or  single  (')
              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 '"x"'. Non-leading and non-trailing quotes are
              interpreted as being part of the option value.

              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
              --options-file option is specified except that the shell escaping  and  quoting  is
              not required. You can repeat this option to specify more than one options file.

       -x option
              Pass  option  to  the  underlying C++ compiler (g++). The option value that doesn't
              start with - is considered the g++ executable name.

       -v     Print the commands executed to run the stages of compilation.

       --trace
              Trace the compilation process.

       --mysql-engine engine
              Use engine instead of the default InnoDB 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 default as the value  for  this
              option.

       --sqlite-override-null
              Make  all  columns  in  the  generated  database schema allow NULL values.  This is
              primarily useful in schema migration since SQLite  does  not  support  dropping  of
              columns.  By  making  all  columns NULL we can later "delete" them by setting their
              values to NULL. Note that this option overrides even the not_null pragma.

       --sqlite-lax-auto-id
              Do not force monotonically increasing automatically-assigned object  ids.  In  this
              mode the generated database schema omits the AUTOINCREMENT 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.

       --pgsql-server-version ver
              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 major.minor form, for example, 9.1. If this option is not specified,
              then 7.4 or later is assumed.

       --oracle-client-version ver
              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 major.minor form, for example, 11.2. If this option is not specified, then 10.1
              or later is assumed.

       --oracle-warn-truncation
              Warn  about  SQL  names  that  are  longer  than  30  characters  and are therefore
              truncated. Note that during  database  schema  generation  (--generate-schema)  ODB
              detects  when  such  truncations lead to name conflicts and issues diagnostics even
              without this option specified.

       --mssql-server-version ver
              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 major.minor form, for example, 9.0 (SQL Server 2005), 10.5 (2008R2),
              or 11.0 (2012). If this option is not specified, then 10.0  (SQL  Server  2008)  or
              later is assumed.

       --mssql-short-limit size
              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  short  data,  otherwise  it  is long data. 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 SQLGetData()/SQLPutData() 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.

SQL NAME TRANSFORMATIONS

       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 --table-prefix option.  Similarly,  we  can  specify  custom
       suffixes  for  automatically-derived  index  (--index-suffix;  default is _i), foreign key
       (--fkey-suffix; default is _fk), and sequence (--sequence-suffix; default is _seq)  names.
       Finally, we can also convert all the names to upper or lower case with the --sql-name-case
       option (valid values are upper and lower).

       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  --kind-regex  options, where kind can be table, column, index, fkey, sequence, or
       statement.  On the other hand, if we want our regular expressions  to  apply  to  all  SQL
       names, then we use the --sql-name-regex option.

       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 --table-prefix 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.

       The value for the --*-regex  options  is  a  Perl-like  regular  expression  in  the  form
       /pattern/replacement/.   Any  character  can  be  used as a delimiter instead of / and the
       delimiter can be escaped inside pattern and replacement with a  backslash  (\).   You  can
       also specify multiple regular expressions by repeating these options.

       All  the  regular  expressions  are  tried  in  the order specified with the name-specific
       expressions (for example, --table-regex) tried first followed by the  generic  expressions
       (--sql-name-regex).  The first expression that matches is used.

       As an example, consider a regular expression that transforms a class name in the form CFoo
       to a table name in the form FOO:

       --table-regex '/C(.+)/\U$1/'

       As a more interesting example, consider the transformation of class names that follow  the
       upper  camel  case  convention  (for  example,  FooBar)  to  table  names  that follow the
       underscore-separated, all upper case convention (for example, FOO_BAR).  For this case  we
       have to use separate expressions to handle one-word, two-word, etc., names:

       --table-regex '/([A-z][a-z]+)/\U$1/'

       --table-regex '/([A-z][a-z]+)([A-z][a-z]+)/\U$1_$2/'

       See also the REGEX AND SHELL QUOTING section below.

REGEX AND SHELL QUOTING

       When  entering  a  regular  expression  argument  in  the  shell  command line it is often
       necessary to use quoting (enclosing the argument in " " or ' ') in order  to  prevent  the
       shell from interpreting certain characters, for example, spaces as argument separators and
       $ as variable expansions.

       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 " "
       for quoting you will get a wrong result with POSIX shells if your expression  contains  $.
       The  standard  way  of  dealing  with  this  on  POSIX  systems  is  to  use  ' ' instead.
       Unfortunately, Windows shell does not remove ' '  from arguments when they are  passed  to
       applications.  As a result you may have to use ' ' for POSIX and " " for Windows ($ is not
       treated as a special character on Windows).

       Alternatively, you can save regular expression options into a file, one option  per  line,
       and  use  this  file  with the --options-file option. With this approach you don't need to
       worry about shell quoting.

DIAGNOSTICS

       If the input file is not valid C++, odb will issue diagnostic messages to STDERR and  exit
       with non-zero exit code.

BUGS

       Send bug reports to the odb-users@codesynthesis.com mailing list.

COPYRIGHT

       Copyright (c) 2009-2015 Code Synthesis Tools CC.

       Permission  is  granted to copy, distribute and/or modify this document under the terms of
       the GNU Free Documentation License, version 1.2; with no  Invariant  Sections,  no  Front-
       Cover  Texts  and  no  Back-Cover  Texts.  Copy  of  the  license  can  be  obtained  from
       http://www.codesynthesis.com/licenses/fdl-1.3.txt