1ODB(1) General Commands Manual ODB(1)
2
6 odb - object-relational mapping (ORM) compiler for C++
7
9 odb [ options ] file [ file... ]
10
12 Given a set of C++ classes in a header file, odb generates C++ code
13 that allows you to persist, query, and update objects of these classes
14 in a relational database (RDBMS). The relational database that the gen‐
15 erated code should target is specified with the required --database
16 option (see below).
17 For an input file in the form name.hxx (other file extensions can be
20 used instead of .hxx), in the single-database mode (the default), the
21 generated C++ files by default have the following names: name-odb.hxx
22 (header file), name-odb.ixx (inline file), and name-odb.cxx (source
23 file). Additionally, if the --generate-schema option is specified and
24 the sql schema format is requested (see --schema-format), the name.sql
25 database schema file is generated. If the separate schema format is
26 requested, the database creation code is generated into the separate
27 name-schema.cxx file.
28 In the multi-database mode (see the --multi-database option below), the
31 generated files corresponding to the common database have the same
32 names as in the single-database mode. For other databases, the file
33 names include the database name: name-odb-db.hxx, name-odb-db.ixx,
34 name-odb-db.cxx, name-db.sql, and name-schema-db.cxx (where db is the
35 database name).
36
38 --help Print usage information and exit.
39 --version
42 Print version and exit.
43 -I dir Add dir to the beginning of the list of directories to be
46 searched for included header files.
47 -D name[=def]
50 Define macro name with definition def. If definition is omitted,
51 define name to be 1.
52 -U name
55 Cancel any previous definitions of macro name, either built-in
56 or provided with the -D option.
57 --database|-d db
60 Generate code for the db database. Valid values are mssql,
61 mysql, oracle, pgsql, sqlite, and common (multi-database mode
62 only).
63 --multi-database|-m type
66 Enable multi-database support and specify its type. Valid values
67 for this option are static and dynamic.
68 In the multi-database mode, options that determine the kind (for
70 example, --schema-format), names (for example, --odb-file-suf‐
71 fix), or content (for example, prologue and epilogue options) of
72 the output files can be prefixed with the database name followed
73 by a colon, for example, mysql:value. This restricts the value
74 of such an option to only apply to generated files corresponding
75 to this database.
76 --default-database db
79 When static multi-database support is used, specify the database
80 that should be made the default. When dynamic multi-database
81 support is used, common is always made the default database.
82 --generate-query|-q
85 Generate query support code. Without this support you cannot use
86 views and can only load objects via their ids.
87 --generate-prepared
90 Generate prepared query execution support code.
91 --omit-unprepared
94 Omit un-prepared (once-off) query execution support code.
95 --generate-session|-e
98 Generate session support code. With this option session support
99 will be enabled by default for all the persistent classes except
100 those for which it was explicitly disabled using the db session
101 pragma.
102 --generate-schema|-s
105 Generate the database schema. The database schema contains SQL
106 statements that create database tables necessary to store per‐
107 sistent classes defined in the file being compiled. Note that by
108 applying this schema, all the existing information stored in
109 such tables will be lost.
110 Depending on the database being used (--database option), the
112 schema is generated either as a standalone SQL file or embedded
113 into the generated C++ code. By default the SQL file is gener‐
114 ated for the MySQL, PostgreSQL, Oracle, and Microsoft SQL Server
115 databases and the schema is embedded into the C++ code for the
116 SQLite database. Use the --schema-format option to alter the
117 default schema format.
118 If database schema evolution support is enabled (that is, the
120 object model version is specified), then this option also trig‐
121 gers the generation of database schema migration statements,
122 again either as standalong SQL files or embedded into the gener‐
123 ated C++ code. You can suppress the generation of schema migra‐
124 tion statements by specifying the --suppress-migration option.
125 --generate-schema-only
128 Generate only the database schema. Note that this option is only
129 valid when generating schema as a standalone SQL file (see
130 --schema-format for details).
131 --suppress-migration
134 Suppress the generation of database schema migration statements.
135 --suppress-schema-version
138 Suppress the generation of schema version table. If you specify
139 this option then you are also expected to manually specify the
140 database schema version and migration state at runtime using the
141 odb::database::schema_version() function.
142 --schema-version-table name
145 Specify the alternative schema version table name instead of the
146 default schema_version. If you specify this option then you are
147 also expected to manually specify the schema version table name
148 at runtime using the odb::database::schema_version_table() func‐
149 tion. The table name can be qualified.
150 --schema-format format
153 Generate the database schema in the specified format. Pass sql
154 as format to generate the database schema as a standalone SQL
155 file or pass embedded to embed the schema into the generated C++
156 code. The separate value is similar to embedded except the
157 schema creation code is generated into a separate C++ file
158 (name-schema.cxx by default). This value is primarily useful if
159 you want to place the schema creation functionality into a sepa‐
160 rate program or library. Repeat this option to generate the same
161 database schema in multiple formats.
162 --omit-drop
165 Omit DROP statements from the generated database schema.
166 --omit-create
169 Omit CREATE statements from the generated database schema.
170 --schema-name name
173 Use name as the database schema name. Schema names are primarily
174 used to distinguish between multiple embedded schemas in the
175 schema catalog. They are not to be confused with database
176 schemas (database namespaces) which are specified with the
177 --schema option. If this option is not specified, the empty
178 name, which is the default schema name, is used.
179 --fkeys-deferrable-mode m
182 Use constraint checking mode m in foreign keys generated for
183 object relationships. Valid values for this option are
184 not_deferrable, immediate, and deferred (default). MySQL and SQL
185 Server do not support deferrable foreign keys and for these
186 databases such keys are generated commented out. Other foreign
187 keys generated by the ODB compiler (such as the ones used to
188 support containers and polymorphic hierarchies) are always gen‐
189 erated as not deferrable.
190 Note also that if you use either not_deferrable or immediate
192 mode, then the order in which you persist, update, and erase
193 objects within a transaction becomes important.
194 --default-pointer ptr
197 Use ptr as the default pointer for persistent objects and views.
198 Objects and views that do not have a pointer assigned with the
199 db pointer pragma will use this pointer by default. The value of
200 this option can be * which denotes the raw pointer and is the
201 default, or qualified name of a smart pointer class template,
202 for example, std::auto_ptr. In the latter case, the ODB compiler
203 constructs the object or view pointer by adding a single tem‐
204 plate argument of the object or view type to the qualified name,
205 for example std::auto_ptr<object>. The ODB runtime uses object
206 and view pointers to return, and, in case of objects, pass and
207 cache dynamically allocated instances of object and view types.
208 Except for the raw pointer and the standard smart pointers
210 defined in the <memory> header file, you are expected to include
211 the definition of the default pointer at the beginning of the
212 generated header file. There are two common ways to achieve
213 this: you can either include the necessary header in the file
214 being compiled or you can use the --hxx-prologue option to add
215 the necessary #include directive to the generated code.
216 --session-type type
219 Use type as the alternative session type instead of the default
220 odb::session. This option can be used to specify a custom ses‐
221 sion implementation to be use by the persistent classes. Note
222 that you will also need to include the definition of the custom
223 session type into the generated header file. This is normally
224 achieved with the --hxx-prologue* options.
225 --profile|-p name
228 Specify a profile that should be used during compilation. A pro‐
229 file is an options file. The ODB compiler first looks for a
230 database-specific version with the name constructed by appending
231 the -database.options suffix to name, where database is the
232 database name as specified with the --database option. If this
233 file is not found, then the ODB compiler looks for a database-
234 independant version with the name constructed by appending just
235 the .options suffix.
236 The profile options files are searched for in the same set of
238 directories as C++ headers included with the #include <...>
239 directive (built-in paths plus those specified with the -I
240 options). The options file is first searched for in the direc‐
241 tory itself and then in its odb/ subdirectory.
242 For the format of the options file refer to the --options-file
244 option below. You can repeat this option to specify more than
245 one profile.
246 --at-once
249 Generate code for all the input files as well as for all the
250 files that they include at once. The result is a single set of
251 source/schema files that contain all the generated code. If more
252 than one input file is specified together with this option, then
253 the --input-name option must also be specified in order to pro‐
254 vide the base name for the output files. In this case, the
255 directory part of such a base name is used as the location of
256 the combined file. This can be important for the #include direc‐
257 tive resolution.
258 --schema schema
261 Specify a database schema (database namespace) that should be
262 assigned to the persistent classes in the file being compiled.
263 Database schemas are not to be confused with database schema
264 names (schema catalog names) which are specified with the
265 --schema-name option.
266 --export-symbol symbol
269 Insert symbol in places where DLL export/import control state‐
270 ments (__declspec(dllexport/dllimport)) are necessary. See also
271 the --extern-symbol option below.
272 --extern-symbol symbol
275 If symbol is defined, insert it in places where a template
276 instantiation must be declared extern. This option is normally
277 used together with --export-symbol when both multi-database sup‐
278 port and queries are enabled.
279 --std version
282 Specify the C++ standard that should be used during compilation.
283 Valid values are c++98 (default), c++11, and c++14.
284 --warn-hard-add
287 Warn about hard-added data members.
288 --warn-hard-delete
291 Warn about hard-deleted data members and persistent classes.
292 --warn-hard
295 Warn about both hard-added and hard-deleted data members and
296 persistent classes.
297 --output-dir|-o dir
300 Write the generated files to dir instead of the current direc‐
301 tory.
302 --input-name name
305 Use name instead of the input file to derive the names of the
306 generated files. If the --at-once option is specified, then the
307 directory part of name is used as the location of the combined
308 file. Refer to the --at-once option for details.
309 --changelog file
312 Read/write changelog from/to file instead of the default
313 changelog file. The default changelog file name is derived from
314 the input file name and it is placed into the same directory as
315 the input file. Note that the --output-dir option does not
316 affect the changelog file location. In other words, by default,
317 the changelog file is treated as another input rather than out‐
318 put even though the ODB compiler may modify it. Use the
319 --changelog-in and --changelog-out options to specify different
320 input and output chaneglog files.
321 --changelog-in file
324 Read changelog from file instead of the default changelog file.
325 If this option is specified, then you must also specify the out‐
326 put chanegelog file with --changelog-out.
327 --changelog-out file
330 Write changelog to file instead of the default changelog file.
331 If this option is specified, then you must also specify the
332 input chanegelog file with --changelog-in.
333 --changelog-dir dir
336 Use dir instead of the input file directory as the changelog
337 file directory. This directory is also added to changelog files
338 specified with the --changelog, --changelog-in, and --changelog-
339 in options unless they are absolute paths.
340 --init-changelog
343 Force re-initialization of the changelog even if one exists (all
344 the existing change history will be lost). This option is pri‐
345 marily useful for automated testing.
346 --odb-file-suffix suffix
349 Use suffix to construct the names of the generated C++ files. In
350 the single-database mode the default value for this option is
351 -odb. In the multi-database mode it is -odb for the files corre‐
352 sponding to the common database and -odb-db (where db is the
353 database name) for other databases.
354 --sql-file-suffix suffix
357 Use suffix to construct the name of the generated schema SQL
358 file. In the single-database mode by default no suffix is used.
359 In the multi-database mode the default value for this option is
360 -db (where db is the database name).
361 --schema-file-suffix suffix
364 Use suffix to construct the name of the generated schema C++
365 source file. In the single-database mode the default value for
366 this option is -schema. In the multi-database mode it is
367 -schema-db (where db is the database name). See the --schema-
368 format option for details.
369 --changelog-file-suffix sfx
372 Use sfx to construct the name of the changelog file. In the sin‐
373 gle-database mode by default no suffix is used. In the multi-
374 database mode the default value for this option is -db (where db
375 is the database name).
376 --hxx-suffix suffix
379 Use suffix instead of the default .hxx to construct the name of
380 the generated C++ header file.
381 --ixx-suffix suffix
384 Use suffix instead of the default .ixx to construct the name of
385 the generated C++ inline file.
386 --cxx-suffix suffix
389 Use suffix instead of the default .cxx to construct the name of
390 the generated C++ source file.
391 --sql-suffix suffix
394 Use suffix instead of the default .sql to construct the name of
395 the generated database schema file.
396 --changelog-suffix suffix
399 Use suffix instead of the default .xml to construct the name of
400 the changelog file.
401 --hxx-prologue text
404 Insert text at the beginning of the generated C++ header file.
405 --ixx-prologue text
408 Insert text at the beginning of the generated C++ inline file.
409 --cxx-prologue text
412 Insert text at the beginning of the generated C++ source file.
413 --schema-prologue text
416 Insert text at the beginning of the generated schema C++ source
417 file.
418 --sql-prologue text
421 Insert text at the beginning of the generated database schema
422 file.
423 --migration-prologue text
426 Insert text at the beginning of the generated database migration
427 file.
428 --sql-interlude text
431 Insert text after all the DROP and before any CREATE statements
432 in the generated database schema file.
433 --hxx-epilogue text
436 Insert text at the end of the generated C++ header file.
437 --ixx-epilogue text
440 Insert text at the end of the generated C++ inline file.
441 --cxx-epilogue text
444 Insert text at the end of the generated C++ source file.
445 --schema-epilogue text
448 Insert text at the end of the generated schema C++ source file.
449 --sql-epilogue text
452 Insert text at the end of the generated database schema file.
453 --migration-epilogue text
456 Insert text at the end of the generated database migration file.
457 --hxx-prologue-file file
460 Insert the content of file at the beginning of the generated C++
461 header file.
462 --ixx-prologue-file file
465 Insert the content of file at the beginning of the generated C++
466 inline file.
467 --cxx-prologue-file file
470 Insert the content of file at the beginning of the generated C++
471 source file.
472 --schema-prologue-file file
475 Insert the content of file at the beginning of the generated
476 schema C++ source file.
477 --sql-prologue-file file
480 Insert the content of file at the beginning of the generated
481 database schema file.
482 --migration-prologue-file f
485 Insert the content of file f at the beginning of the generated
486 database migration file.
487 --sql-interlude-file file
490 Insert the content of file after all the DROP and before any
491 CREATE statements in the generated database schema file.
492 --hxx-epilogue-file file
495 Insert the content of file at the end of the generated C++
496 header file.
497 --ixx-epilogue-file file
500 Insert the content of file at the end of the generated C++
501 inline file.
502 --cxx-epilogue-file file
505 Insert the content of file at the end of the generated C++
506 source file.
507 --schema-epilogue-file file
510 Insert the content of file at the end of the generated schema
511 C++ source file.
512 --sql-epilogue-file file
515 Insert the content of file at the end of the generated database
516 schema file.
517 --migration-epilogue-file f
520 Insert the content of file f at the end of the generated data‐
521 base migration file.
522 --odb-prologue text
525 Compile text before the input header file. This option allows
526 you to add additional declarations, such as custom traits spe‐
527 cializations, to the ODB compilation process.
528 --odb-prologue-file file
531 Compile file contents before the input header file. Prologue
532 files are compiled after all the prologue text fragments (--odb-
533 prologue option).
534 --odb-epilogue text
537 Compile text after the input header file. This option allows you
538 to add additional declarations, such as custom traits special‐
539 izations, to the ODB compilation process.
540 --odb-epilogue-file file
543 Compile file contents after the input header file. Epilogue
544 files are compiled after all the epilogue text fragments (--odb-
545 epilogue option).
546 --table-prefix prefix
549 Add prefix to table names and, for databases that have global
550 index and/or foreign key names, to those names as well. The pre‐
551 fix is added to both names that were specified with the db table
552 and db index pragmas and those that were automatically derived
553 from class and data member names. If you require a separator,
554 such as an underscore, between the prefix and the name, then you
555 should include it into the prefix value.
556 --index-suffix suffix
559 Use suffix instead of the default _i to construct index names.
560 The suffix is only added to names that were automatically
561 derived from data member names. If you require a separator, such
562 as an underscore, between the name and the suffix, then you
563 should include it into the suffix value.
564 --fkey-suffix suffix
567 Use suffix instead of the default _fk to construct foreign key
568 names. If you require a separator, such as an underscore,
569 between the name and the suffix, then you should include it into
570 the suffix value.
571 --sequence-suffix suffix
574 Use suffix instead of the default _seq to construct sequence
575 names. If you require a separator, such as an underscore,
576 between the name and the suffix, then you should include it into
577 the suffix value.
578 --sql-name-case case
581 Convert all automatically-derived SQL names to upper or lower
582 case. Valid values for this option are upper and lower.
583 --table-regex regex
586 Add regex to the list of regular expressions that is used to
587 transform automatically-derived table names. See the SQL NAME
588 TRANSFORMATIONS section below for details.
589 --column-regex regex
592 Add regex to the list of regular expressions that is used to
593 transform automatically-derived column names. See the SQL NAME
594 TRANSFORMATIONS section below for details.
595 --index-regex regex
598 Add regex to the list of regular expressions that is used to
599 transform automatically-derived index names. See the SQL NAME
600 TRANSFORMATIONS section below for details.
601 --fkey-regex regex
604 Add regex to the list of regular expressions that is used to
605 transform automatically-derived foreign key names. See the SQL
606 NAME TRANSFORMATIONS section below for details.
607 --sequence-regex regex
610 Add regex to the list of regular expressions that is used to
611 transform automatically-derived sequence names. See the SQL NAME
612 TRANSFORMATIONS section below for details.
613 --statement-regex regex
616 Add regex to the list of regular expressions that is used to
617 transform automatically-derived prepared statement names. See
618 the SQL NAME TRANSFORMATIONS section below for details.
619 --sql-name-regex regex
622 Add regex to the list of regular expressions that is used to
623 transform all automatically-derived SQL names. See the SQL NAME
624 TRANSFORMATIONS section below for details.
625 --sql-name-regex-trace
628 Trace the process of applying regular expressions specified with
629 the SQL name --*-regex options. Use this option to find out why
630 your regular expressions don't do what you expected them to do.
631 --accessor-regex regex
634 Add regex to the list of regular expressions used to transform
635 data member names to function names when searching for a suit‐
636 able accessor function. The argument to this option is a Perl-
637 like regular expression in the form /pattern/replacement/. Any
638 character can be used as a delimiter instead of / and the delim‐
639 iter can be escaped inside pattern and replacement with a back‐
640 slash (\). You can specify multiple regular expressions by
641 repeating this option.
642 All the regular expressions are tried in the order specified and
644 the first expression that produces a suitable accessor function
645 is used. Each expression is tried twice: first with the actual
646 member name and then with the member's public name which is
647 obtained by removing the common member name decorations, such as
648 leading and trailing underscores, the m_ prefix, etc. The ODB
649 compiler also includes a number of built-in expressions for com‐
650 monly used accessor names, such as get_foo, getFoo, getfoo, and
651 just foo. The built-in expressions are tried last.
652 As an example, the following expression transforms data members
654 with public names in the form foo to accessor names in the form
655 GetFoo:
656 /(.+)/Get\u$1/
658 See also the REGEX AND SHELL QUOTING section below.
660 --accessor-regex-trace
663 Trace the process of applying regular expressions specified with
664 the --accessor-regex option. Use this option to find out why
665 your regular expressions don't do what you expected them to do.
666 --modifier-regex regex
669 Add regex to the list of regular expressions used to transform
670 data member names to function names when searching for a suit‐
671 able modifier function. The argument to this option is a Perl-
672 like regular expression in the form /pattern/replacement/. Any
673 character can be used as a delimiter instead of / and the delim‐
674 iter can be escaped inside pattern and replacement with a back‐
675 slash (\). You can specify multiple regular expressions by
676 repeating this option.
677 All the regular expressions are tried in the order specified and
679 the first expression that produces a suitable modifier function
680 is used. Each expression is tried twice: first with the actual
681 member name and then with the member's public name which is
682 obtained by removing the common member name decorations, such as
683 leading and trailing underscores, the m_ prefix, etc. The ODB
684 compiler also includes a number of built-in expressions for com‐
685 monly used modifier names, such as set_foo, setFoo, setfoo, and
686 just foo. The built-in expressions are tried last.
687 As an example, the following expression transforms data members
689 with public names in the form foo to modifier names in the form
690 SetFoo:
691 /(.+)/Set\u$1/
693 See also the REGEX AND SHELL QUOTING section below.
695 --modifier-regex-trace
698 Trace the process of applying regular expressions specified with
699 the --modifier-regex option. Use this option to find out why
700 your regular expressions don't do what you expected them to do.
701 --include-with-brackets
704 Use angle brackets (<>) instead of quotes ("") in the generated
705 #include directives.
706 --include-prefix prefix
709 Add prefix to the generated #include directive paths.
710 --include-regex regex
713 Add regex to the list of regular expressions used to transform
714 generated #include directive paths. The argument to this option
715 is a Perl-like regular expression in the form /pattern/replace‐
716 ment/. Any character can be used as a delimiter instead of / and
717 the delimiter can be escaped inside pattern and replacement with
718 a backslash (\). You can specify multiple regular expressions by
719 repeating this option. All the regular expressions are tried in
720 the order specified and the first expression that matches is
721 used.
722 As an example, the following expression transforms include paths
724 in the form foo/bar-odb.h to paths in the form foo/gener‐
725 ated/bar-odb.h:
726 %foo/(.+)-odb.h%foo/generated/$1-odb.h%
728 See also the REGEX AND SHELL QUOTING section below.
730 --include-regex-trace
733 Trace the process of applying regular expressions specified with
734 the --include-regex option. Use this option to find out why your
735 regular expressions don't do what you expected them to do.
736 --guard-prefix prefix
739 Add prefix to the generated header inclusion guards. The prefix
740 is transformed to upper case and characters that are illegal in
741 a preprocessor macro name are replaced with underscores.
742 --show-sloc
745 Print the number of generated physical source lines of code
746 (SLOC).
747 --sloc-limit num
750 Check that the number of generated physical source lines of code
751 (SLOC) does not exceed num.
752 --options-file file
755 Read additional options from file with each option appearing on
756 a separate line optionally followed by space and an option
757 value. Empty lines and lines starting with # are ignored. Option
758 values can be enclosed in double (") or single (') quotes to
759 preserve leading and trailing whitespaces as well as to specify
760 empty values. If the value itself contains trailing or leading
761 quotes, enclose it with an extra pair of quotes, for example
762 '"x"'. Non-leading and non-trailing quotes are interpreted as
763 being part of the option value.
764 The semantics of providing options in a file is equivalent to
766 providing the same set of options in the same order on the com‐
767 mand line at the point where the --options-file option is speci‐
768 fied except that the shell escaping and quoting is not required.
769 You can repeat this option to specify more than one options
770 file.
771 -x option
774 Pass option to the underlying C++ compiler (g++). The option
775 value that doesn't start with - is considered the g++ executable
776 name.
777 -v Print the commands executed to run the stages of compilation.
780 --trace
783 Trace the compilation process.
784 --mysql-engine engine
787 Use engine instead of the default InnoDB in the generated data‐
788 base schema file. For more information on the storage engine
789 options see the MySQL documentation. If you would like to use
790 the database-default engine, pass default as the value for this
791 option.
792 --sqlite-override-null
795 Make all columns in the generated database schema allow NULL
796 values. This is primarily useful in schema migration since
797 SQLite does not support dropping of columns. By making all col‐
798 umns NULL we can later "delete" them by setting their values to
799 NULL. Note that this option overrides even the not_null pragma.
800 --sqlite-lax-auto-id
803 Do not force monotonically increasing automatically-assigned
804 object ids. In this mode the generated database schema omits the
805 AUTOINCREMENT keyword which results in faster object persistence
806 but may lead to automatically-assigned ids not being in a
807 strictly ascending order. Refer to the SQLite documentation for
808 details.
809 --pgsql-server-version ver
812 Specify the minimum PostgreSQL server version with which the
813 generated C++ code and schema will be used. This information is
814 used to enable version-specific optimizations and workarounds in
815 the generated C++ code and schema. The version must be in the
816 major.minor form, for example, 9.1. If this option is not speci‐
817 fied, then 7.4 or later is assumed.
818 --oracle-client-version ver
821 Specify the minimum Oracle client library (OCI) version with
822 which the generated C++ code will be linked. This information is
823 used to enable version-specific optimizations and workarounds in
824 the generated C++ code. The version must be in the major.minor
825 form, for example, 11.2. If this option is not specified, then
826 10.1 or later is assumed.
827 --oracle-warn-truncation
830 Warn about SQL names that are longer than 30 characters and are
831 therefore truncated. Note that during database schema generation
832 (--generate-schema) ODB detects when such truncations lead to
833 name conflicts and issues diagnostics even without this option
834 specified.
835 --mssql-server-version ver
838 Specify the minimum SQL Server server version with which the
839 generated C++ code and schema will be used. This information is
840 used to enable version-specific optimizations and workarounds in
841 the generated C++ code and schema. The version must be in the
842 major.minor form, for example, 9.0 (SQL Server 2005), 10.5
843 (2008R2), or 11.0 (2012). If this option is not specified, then
844 10.0 (SQL Server 2008) or later is assumed.
845 --mssql-short-limit size
848 Specify the short data size limit. If a character, national
849 character, or binary data type has a maximum length (in bytes)
850 less than or equal to this limit, then it is treated as short
851 data, otherwise it is long data. For short data ODB pre-allo‐
852 cates an intermediate buffer of the maximum size and binds it
853 directly to a parameter or result column. This way the underly‐
854 ing API (ODBC) can read/write directly from/to this buffer. In
855 the case of long data, the data is read/written in chunks using
856 the SQLGetData()/SQLPutData() ODBC functions. While the long
857 data approach reduces the amount of memory used by the applica‐
858 tion, it may require greater CPU resources. The default short
859 data limit is 1024 bytes. When setting a custom short data
860 limit, make sure that it is sufficiently large so that no object
861 id in the application is treated as long data.
862
865 The ODB compiler provides a number of mechanisms for transforming auto‐
866 matically-derived SQL names, such as tables, columns, etc., to match a
867 specific naming convention. At the higher level, we can add a prefix to
868 global names (tables and, for some databases, indexes and/or foreign
869 keys) with the --table-prefix option. Similarly, we can specify custom
870 suffixes for automatically-derived index (--index-suffix; default is
871 _i), foreign key (--fkey-suffix; default is _fk), and sequence
872 (--sequence-suffix; default is _seq) names. Finally, we can also con‐
873 vert all the names to upper or lower case with the --sql-name-case
874 option (valid values are upper and lower).
875 At the lower level we can specify a set of regular expressions to
877 implement arbitrary transformations of the automatically-derived SQL
878 names. If we want a particular regular expression only to apply to a
879 specific name, for example, table or column, then we use one of the
880 --kind-regex options, where kind can be table, column, index, fkey,
881 sequence, or statement. On the other hand, if we want our regular
882 expressions to apply to all SQL names, then we use the --sql-name-regex
883 option.
884 The interaction between the higher and lower level transformations is
886 as follows. Prefixes and suffixes are added first. Then the regular
887 expression transformations are applied. Finally, if requested, the name
888 is converted to upper or lower case. Note also that all of these trans‐
889 formations except for --table-prefix only apply to automatically-
890 derived names. In other words, if a table, column, etc., name was
891 explicitly specified with a pragma, then it is used as is, without
892 applying any (except for the table prefix) transformations.
893 The value for the --*-regex options is a Perl-like regular expression
895 in the form /pattern/replacement/. Any character can be used as a
896 delimiter instead of / and the delimiter can be escaped inside pattern
897 and replacement with a backslash (\). You can also specify multiple
898 regular expressions by repeating these options.
899 All the regular expressions are tried in the order specified with the
901 name-specific expressions (for example, --table-regex) tried first fol‐
902 lowed by the generic expressions (--sql-name-regex). The first expres‐
903 sion that matches is used.
904 As an example, consider a regular expression that transforms a class
906 name in the form CFoo to a table name in the form FOO:
907 --table-regex '/C(.+)/\U$1/'
909 As a more interesting example, consider the transformation of class
911 names that follow the upper camel case convention (for example, FooBar)
912 to table names that follow the underscore-separated, all upper case
913 convention (for example, FOO_BAR). For this case we have to use sepa‐
914 rate expressions to handle one-word, two-word, etc., names:
915 --table-regex '/([A-z][a-z]+)/\U$1/'
917 --table-regex '/([A-z][a-z]+)([A-z][a-z]+)/\U$1_$2/'
919 See also the REGEX AND SHELL QUOTING section below.
921
923 When entering a regular expression argument in the shell command line
924 it is often necessary to use quoting (enclosing the argument in " " or
925 ' ') in order to prevent the shell from interpreting certain charac‐
926 ters, for example, spaces as argument separators and $ as variable
927 expansions.
928 Unfortunately it is hard to achieve this in a manner that is portable
930 across POSIX shells, such as those found on GNU/Linux and UNIX, and
931 Windows shell. For example, if you use " " for quoting you will get a
932 wrong result with POSIX shells if your expression contains $. The stan‐
933 dard way of dealing with this on POSIX systems is to use ' ' instead.
934 Unfortunately, Windows shell does not remove ' ' from arguments when
935 they are passed to applications. As a result you may have to use ' '
936 for POSIX and " " for Windows ($ is not treated as a special character
937 on Windows).
938 Alternatively, you can save regular expression options into a file, one
940 option per line, and use this file with the --options-file option. With
941 this approach you don't need to worry about shell quoting.
942
944 If the input file is not valid C++, odb will issue diagnostic messages
945 to STDERR and exit with non-zero exit code.
946
948 Send bug reports to the odb-users@codesynthesis.com mailing list.
949
951 Copyright (c) 2009-2015 Code Synthesis Tools CC.
952 Permission is granted to copy, distribute and/or modify this document
954 under the terms of the GNU Free Documentation License, version 1.2;
955 with no Invariant Sections, no Front-Cover Texts and no Back-Cover
956 Texts. Copy of the license can be obtained from http://www.codesynthe‐
957 sis.com/licenses/fdl-1.3.txt
958ODB 2.4.0 February 2015 ODB(1)