Appendix 1: Command Line Options

CQL has a variety of command line options but many of them are only interesting for cql development. Nonetheless this is a comprehensive list:

With No Options

  • CQL reads its input and echos it back as normalized SQL
  • this only validates that the input can be parsed
  • note CQL is often used after the c pre-processor is run so this kind of invocation is typical:
cc -E -x c foo.sql | cql [args]

--in file

  • reads the given file for the input instead of stdin
  • the input should probably have already been run through the C pre-processor as above
  • returns non-zero if the file fails to parse

Example:

cql --in test.sql

--sem

  • performs semantic analysis on the input file ONLY
  • the return code is zero if there are no errors

Example:

cql --in sem_test.sql --sem

--print

  • may be combined with --sem (semantic info will be included)
  • prints the internal AST to stdout instead of echoing the inputs Example
cql --in sem_test.sql --sem --print >sem_ast.out

--dot

  • prints the internal AST to stdout in DOT format for graph visualization
  • this is really only interesting for small graphs for discussion as it rapidly gets insane

Example:

cql --dot --in dottest.sql

--cg output1 output2 ...

  • any number of output files may be needed for a particular result type, two is common
  • the return code is zero if there are no errors
  • any --cg option implies --sem

Example:

cql --in foo.sql --cg foo.h foo.c

--nolines ...

  • Suppress the # directives for lines. Useful if you need to debug the C code.

Example:

cql --in test.sql --nolines --cg foo.h foo.c

--generate_copy ...

  • Generate a C copy function for the resultset. Most of the stored procedures don't need to generate this thats why is optional.

Example:

cql --in test.sql --cg foo.h foo.c --generate_copy

--global_proc name

  • any loose SQL statements not in a stored proc are gathered and put into a procedure of the given name
  • when generating a schema migrate script the global proc name is used as a prefix on all of the artifacts so that there can be several independent migrations linked into a single executable

--compress

  • for use with the C result type, (or any similar types added to the runtime array in your compiler)
  • string literals for the SQL are broken into "fragments" the DML is then represented by an array of fragments
  • since DML is often very similar there is a lot of token sharing possible
  • the original string is recreated at runtime from the fragments and then executed
  • comments show the original string inline for easier debugging and searching

NOTE: different result types require a different number of output files with different meanings

--test

  • some of the output types can include extra diagnostics if --test is included
  • that often makes the outputs badly formed so this is generally good for humans only

--java_package_name

  • used by java code generators when they output a class. Allows to specify the name of package the class will be a part of

--java_assembly_query_classname

  • Fully qualified name of the parent class for the Java assembly. Used by java code generators when they output an extension fragment class.

--c_include_namespace

  • for the C codegen runtimes, it determines the header namespace (as in #include <namespace/file.h) that the headers will have to be referred when included from other sources.

--objc_c_include_path

  • for ObjC codegen runtimes that need to refer to the generated C code, this represents the header of the C generated code that will be used during inclusion from the ObjC file

Result Types (--rt *)

These are the various outputs the compiler can produce.

--rt c

  • requires two output files (foo.h and foo.c)
  • this is the standard C compilation of the sql file

--rt objc

  • objective C wrappers for result sets produced by the stored procedures in the input
  • these depend on the output of a standard codegen run so this is additive
  • requires one output file (foo.h)

--rt java

  • java wrappers for result sets produced by the stored procedures in the input
  • these depend on the output of a standard codegen run so this is additive
  • requires one output file (foo.java)

--rt schema

  • produces the canonical schema for the given input files
  • stored procedures etc. are removed
  • whitespace etc. is removed
  • suitable for use to create the next or first "previous" schema for schema validation
  • requires one output file

--rt schema_upgrade

  • produces a CQL schema upgrade script (one file) which can then be compiled with CQL itself
  • see the section on schema upgrade/migration
  • requires one output file (foo.sql)
--include_regions a b c
  • the indicated regions will be declared
  • used with --rt schema_upgrade or --rt schema
  • in the upgrade case excluded regions will not be themselves upgraded, but may be referred, to by things that are being upgraded
--exclude_regions x y z
  • the indicated regions will still be declared but the upgrade code will be suppressed, the presumption being that a different script already upgrades x y z
  • used with --rt schema_upgrade

--rt json_schema

  • produces JSON output suitable for consumption by downstream codegen like the android mlite system
  • the JSON includes a definition of the various entities in the input
  • see the section on JSON output for details
Last updated on by Raoul Foaleng