rdm-compile

Database Schema Compiler Utility

Synopsis

rdm-compile [OPTION]… schemaname.sdl

Description

rdm-compile is a command-line utility that compiles a database definition into a platform-agnostic binary catalog file. It can optionally generate C and C++ source and header files that can be included in an application. The generated files will always be written to the current working directory even if the input file was specified with a path. This behavior makes it possible to use the tool in an out-of-source build environment.

Using file names or literals with embedded spaces, special characters, or something that can conflict with C/C++ reserved words or content in system header files may result in generated files that will fail to compile on one or more platforms.

Options

Short options can be combined into one string starting with a single '-'. Mandatory arguments to long options are mandatory for short options too. Long option arguments can also be specified in a separate argument.

-h, --help	Display this usage information
--version	Display the version information
-q, --quiet	Quiet mode. No information will be displayed

-x, --cpp-api	Generate C++ API files
-X, --cpp	Generate C++ files (used in conjunction with the --catalog option).
--include-prefix=path	Prefix for RaimaDB include directory. This option only affects the generated source/header filies when '--cpp-api' is specified.
--include-path=path	Full path location of the RaimaDB include directory. This option only affects the generated doxygen file when '--cpp-api' is specified.
--lc-cpp-methods	Use lower case for part of C++ method names derived from the schema
--mc-enums	Match the case of enumerations with that of the table, column, key and reference names used in the DDL file (See Match-Case Enumerations below).
-a, --catalog	Generate internal catalog C/H files
-s, --c-structs	Generate database header file. This file is not necessary if an application only uses SQL to access the database.
--lc-struct-members	Use lower case for 'struct' members in the generated C-struct file
--uc-struct-members	Use upper case for 'struct' members in the generated C-struct file
--namespace=namespace	Prefix 'namespace' to the schemaname for all generated files
--use-guards	Add #ifdef guards to structures generated from user-defined data types. This option only affects the header file generated with '--c-structs'
--key-ex	Generate EX classes with constructors for key 'structs'
--no-cpp-constructors	Do not generate CPP constructors to initialize default values in the table structures in the generated header files
schemaname.sdl	Name of SQL DDL Script file

The schemaname is used as a part of the generated files names for C/C++ files. You should avoid using characters that may be invalid for these file names when naming the schemaname.sdl file. See Schema, Table, Column and Database Naming for more information on naming.

Usage Examples

The usage examples assume that bookshop.sdl contains the following table definition:

CREATE TABLE author (
    last_name CHAR(13) PRIMARY KEY,
    full_name CHAR(25),
    gender CHAR(1),
    yr_born SMALLINT,
    yr_died SMALLINT,
    short_bio VARCHAR(216),
    KEY yob_gender_key(yr_born, gender)
);

Compiling an RaimaDB database catalog

You can run rdm-compile to compile a database definition file into an RaimaDB database catalog file.

$ rdm-compile bookshop.sdl

An RaimaDB database catalog file named bookshop.cat will be created as the result.

Generating source and header files

A number of command-line options are provided with rdm-compile to generate source and header files that can be included or embedded in an application.

$ rdm-compile --c-structs --catalog bookshop.sdl

The header file, bookshop_structs.h, will contain the structure definition of the database. The catalog source header files, bookshop_cat.c and bookshop_cat.h, will contain the text definition of the database catalog and its entry point.

Comments

Database Header File (--c-structs)

The --c-structs option generates C structures and enumerators for communicating with the C/C++ API. By default, the unquoted identifiers generated from the schema definition will be forced to uppercase. Quoted identifiers will maintain case in the generated structure members. Refer to the Identifiers section for more detail about identifiers.

The --lc-struct-members option will change the default of the unquoted member identifiers to lowercase. Likewise, the --uc-struct-members option will force the unquoted identifiers to be uppercase (which is the default behavior).

The associated enumerators will be uppercase unless the following --mc-enums is used.

Match-Case Enum Option (--mc-enums)

Enabling the "--mc-enums" option generates table, column, key and reference enumerations in the case that matches that of the corresponding tables, columns, keys and references. For instance, a table declared as follows:

CREATE TABLE SignalControl ( ... );

will have the following enumerations:

TABLE_SIGNALCONTROL

It may look incorrect as SignalControl is not uppercase. Keep in mind that RaimaDB treats identifiers as uppercase by default. Therefore, the name of the signalcontrol table is internally converted to SIGNALCONTROL. The corresponding enumeration will match that.

In order to use lowercase letters in an identifier, you need to use quoted identifiers, which are identifiers enclosed in double quotation marks. Unlike (non-quoted) identifiers, RaimaDB treats the quoted identifiers as is. For instance:

CREATE TABLE "SignalControl"

will generate the following enumeration with --mc-enums.

TABLE_SignalControl

Ifdef guards (--use-guards)

Enabling the "--use-guards" option adds an ifdef guard around any structure generated from a user-defined data type: namely, ENUM and structure types. This allows the identical structure to be shared across multiple databases. The value of the ifdef guard is generated based on the name and elements. It means two different data types that have the same name but different elements will generate a compile error if both are included in the same source.

For example, the following are the CREATE ENUM statement:

CREATE ENUM colour AS (no_colour, red, green, blue);

and the generated structure with the "--use-guard" option enabled:

/** \brief type declaration for enum COLOUR */
#if !defined(RDM_ENUM_COLOUR_E64D0BC8754FC9DC3130DFD94816D6FD25CDB190)
#define RDM_ENUM_COLOUR_E64D0BC8754FC9DC3130DFD94816D6FD25CDB190
typedef enum
{
    NO_COLOUR,
    RED,
    GREEN,
    BLUE
} COLOUR;
#endif /* RDM_ENUM_COLOUR_E64D0BC8754FC9DC3130DFD94816D6FD25CDB190 */