Compiling Directly via the CCL Compiler

This section describes the CCL compiler, and how to invoke it on different platforms.

The CCL compiler is a separate program, which can be invoked by the user. The name of the program is c8_compiler (or c8_compiler.exe on Microsoft Windows) and it is stored in the directory sybasec8/server/bin. Before invoking the compiler, make sure that your PATH environment variable includes this directory.

On UNIX-like operating systems, you can set the path with a command similar to:


PATH=$PATH:/home/<user>/sybasec8/server/bin

where "/home/<user>" is replaced by the name of the directory under which the product was installed.

On Microsoft Windows, you can set the path with a command similar to:


PATH=%PATH%;C:\Program Files\SybaseC8\Server\bin

To compile a CCL program, the compiler must be on the same computer as the CCL source code and the output directory in which you want the resulting .ccx file stored. This does not have to be the same computer as the server is running on.

The general form of the command is


c8_compiler InputFile OutputFile

for example


c8_compiler /home/jsmith/foo.ccp /home/jsmith/foo.ccx

Once you have compiled the file, you can start to run it.

The most common case is that you will compile a .ccp file (a project), which can refer to other query modules and to schema files (.ccs files). In some cases, however, you may compile just a single schema file (.ccs). Schema files, as well as project files, must be compiled before they can be used. For example, if you are writing an adapter that needs to read schema information from a file with the SybaseC8SchemaReadFromFile(filename) function, specify the name of the .ccx file that you created by compiling the schema file.

The compiler recognizes several command-line parameters. If you execute the c8_compiler command with the command line parameter -h or --help, or without any parameters, the compiler will return a usage message listing the valid parameters.

The output of the compiler (assuming that there are no errors) is stored in another XML file; by convention, this file has an extension of .ccx. There is only one .ccx file created for each compilation, regardless of how many schema files and submodules are included.

The Sybase CEP CCL Compiler is a stand-alone program that is invoked from the command line:


c8_compiler options InputFile OutputFile

Where InputFile is the full path and name of a project file, schema file, or plain-text CCL file, and OutputFile is the full path and name of the compiled file you want created.

The following table lists valid parameters for options:

--binding=name=value

Sets the specified module parameter, including stream bindings, to the specified value (more information is provided later in this page). Applies to the module identified with - module, when InputFile is a plain-text CCL file. You can repeat this option as needed to specify the value for multiple module parameters.

--debug

Compiles the debug version of the program.

--guaranteed-delivery=true | false

Enables or disables guaranteed delivery for the project. Defaults to false. Guaranteed delivery guarantees that every row is received by its destination at least once, as long as the software components are running.

--guaranteed-delivery:maximum-age=age

Sets the maximum age, in microseconds, for messages in the guaranteed delivery queue. Messages that exceed this age are removed from the queue without being delivered. Specifying zero for this value sets no limit on the age of messages in the queue (note that this can potentially exhaust available memory). Defaults to 10 minutes. Only valid if guaranteed delivery is enabled.

--guaranteed-delivery:maximum-queue-size=number

Sets the maximum number of messages allowed in the guaranteed delivery queue. Messages that exceed this number are removed from the queue without being delivered. Defaults to zero, which sets no limit on the size of the queue (note that this can potentially exhaust available memory). Only valid if guaranteed delivery is enabled.

--help

Prints a help message.

--import:search-folder=dir

Specifies a directory the compiler should look in for files imported by the project. You can repeat this option as needed to specify additional directories. See "Importing" later in this page for more information.

--instances=N

The number of instances of this program to be spawned on the server.

--max-errror-count=n

Sets the maximum number of errors allowed to n. The compiler will exit if it reaches this limit.

--module=name

Loads the specified module (the main module) from InputFile, which must be a plain-text CCL file. Required when InputFile is a plain-text CCL file.

--name=progname

Sets the output program's name to progname. This name must be unique within a workspace. In most cases, the program name is the same as the name of the source file (minus the .ccp extension). However, if you want to load the same query module more than once within the same workspace, then each instance of the query module must have a unique name.

--no-repository

Use the system root folder as the repository folder.

--optimize:shortcut_and_or=true | false

If set to true, the compiler will use "shortcut" evaluation of expressions that contain AND and OR operators (more information is provided later in this page). If set to false, the compiler will not use shortcut evaluation. The default is true.

--optimize:remove_internal_streams=true | false

If set to true, the compiler removes internal streams (data streams used strictly within a project or query module). Setting this to true means that you won't be able to view the internal streams with Sybase CEP Studio. The default value is false.

--optimize:filter_asap=true | false

If set to true, the compiler will evaluate WHERE and HAVING conditions as early as possible. (This usually maximizes performance.) The default value is true.

--optimize:fold_primitives=true | false

If set to true, the compiler eliminates redundant primitives (more information is provided later in this page). If set to false, elimination of primitives is not done. The default is true. rarely used.

--persistence=true | false

Enables or disables persistence for the project. If set to true, saves to disk state information about the module, including messages. Allows the project to recover after a system failure. Defaults to false. Note that enabling persistence can have a significant negative impact on performance.

--persistence:commit-interval=value

Sets how frequently, in microseconds, Sybase CEP Server should save project state information to disk. Defaults to one second. Only valid if persistence is enabled.

--playback_rate=N

Sets the accelerated playback multiplier to N. Use when input streams are set to use message timestamp and you wish to process the data faster than would otherwise happen based on the message timestamps. Useful for testing or for processing historical data.

--repository=pathname

Sets the repository root folder to pathname. The compiler uses the repository path name as the root for relative paths, such as to find project and module files. Note that if you omit this parameter, the compiled project references the absolute path to the source files. If you want to connect to the running project using on a computer other than the one on which you compile the project, the absolute path can cause an error when Sybase CEP Studio attempts to locate the source files, unless the directory structure is duplicated on both computers.

--repository-only

Prevents the compiler from accessing files outside the directory specified with the repository parameter. Attempts to import files outside the repository generate an error message. Note that the compiler compares paths for imported files against the path to the specified repository without accessing the file system.

--restart-on-failure=true | false

If set to true, automatically restarts the project (but not any attached adapters) after any fatal error. Defaults to false.

--synchronization=inorder |outoforder | useservertimestamp

Specifies the type of synchronization to use for the project: use the timestamp contained in each message, which must arrive in order (inorder); use the timestamp contained in each message, which can arrive out of order (outoforder); or use the timestamp of Sybase CEP Server when each message arrives (useservertimestamp). Defaults to inorder.

--synchronization:maximum-delay=value

Sets the maximum time, in microseconds, that should wait after each arriving row before sequencing incoming rows from multiple sources. Defaults to one second.

--synchronization:out-of-order-delay=value

Sets the maximum time, in microseconds, that Sybase CEP Server should wait after each arriving row before sequencing incoming rows arriving out of order. Defaults to one second. Only valid if synchronization is set to outoforder.

--version

Prints version information.

--warn:indexes=true | false

If set to true, then the compiler warns when indexes are not used. If the flag is set to false, the compiler does not issue a warning when indexes are not used. The default is false. (Indexes are used to speed up access within large windows.)

--warn:deprecation=true | false

If set to true, then the compiler issues warnings if deprecated parts of the language are used. If set to false, no such warnings are issued. The default is true.

--warn:implicit_conversions=true | false

If set to true, then the compiler issues warnings if implicit data type conversions are used. Ifset to false, no such warnings are issued. The default is true.

--warn:source_without_input=true | false

If true, issues a warning for any named windows or input streams that receive no input from within the window and act as input for other streams or windows. If you specify debug =true, then all named windows act as input to a debug stream for viewing within . Defaults to true.

--warn:ignore-all=true | false

Some operations, such as RegisterQuery, will fail if compilation of the query results in any warnings, even if there are no errors. To force registerQuery to run the query even if there are compiler warnings, set this option to true.

--warn:supress-all=true | false

If true, issue no warnings. Defaults to false.

--workspace=name

Sets the output program's workspace name to name.
Note:

The Sybase CEP CCL compiler can only be invoked as a stand-alone process.

Parent topic: Compile a Project or a Schema File

OutputFile

When the compiler compiles a CCL file, it stores the result in a .ccx file. This command-line option allows you to specify the path and name of the file that you want the output written to. When you want to run the program, you will need to specify the location of this .ccx file.

Binding

The binding (-b) option allows you to specify values for both parameters and stream bindings. Consider the following CCL code:

create parameter integer Addend;
create input stream StreamIn schema ( Value integer );
create output stream StreamOut schema ( Value integer );
insert into StreamOut select Value + $Addend from StreamIn;

The following command sets the value of the parameter Addend to 42, binds StreamIn to the stream named Sink in the project SrcProj, and binds StreamOut to the stream named Source in the project OtherProj:

c8_compiler \
   -b=Addend=42 \
   -b=StreamIn=ccl://localhost:6789/Stream/SrcProj/Sink \
   -b=StreamOut=ccl://localhost:6789/Stream/OtherProj/Source \
   file.ccl

Importing

If your project imports other files, the compiler searches for those files using two search lists: the command-line search list, composed of all the directories specified with the import:search-folder option, and the project-file search list, as specified in 's compiler options setting and stored in the project file.

The compiler resolves the path to any file that you import with a relative name by searching the following directories, in order, until it locates the file:

  1. The directory containing the file that initiated the lookup.
  2. Each directory in the command-line search list relative to the compiler's working directory.
  3. Each item in the project-file search list relative to the project directory (the directory containing the .ccp file or top-level .ccl file).
  4. The project directory itself .
  5. Each item in the project-file search list relative to the repository folder (as specified with the repository option).
  6. The repository folder itself.

    For example, if a project includes the following statements:

    import 'x1.ccl'; 
import 'x2.ccl'; 
import 'x3.ccl'; 
import 'x4.ccl'; 
import 'x5.ccl'; 
import 'x6.ccl';

    Use the following commands to compile the project:

    cd $ROOT/cwd 
c8_compiler -r=$ROOT/repo -I=cmd-lib $ROOT/repo/proj/proj.ccp

    Assuming that the project-file search list as set in Sybase CEP Studio for this project includes proj-lib, and given the following list of files, the compiler will use the ones highlighted in bold:

    
$ROOT/repo/proj/modules/x1.ccl
  
$ROOT/cwd/cmd-lib/x1.ccl
 
$ROOT/cwd/cmd-lib/x2.ccl
 
$ROOT/repo/proj/proj-lib/x1.ccl 
$ROOT/repo/proj/proj-lib/x2.ccl
 
$ROOT/repo/proj/proj-lib/x3.ccl
 
$ROOT/repo/proj/x1.ccl 
$ROOT/repo/proj/x2.ccl 
$ROOT/repo/proj/x3.ccl
 
$ROOT/repo/proj/x4.ccl
 
$ROOT/repo/proj-lib/x1.ccl 
$ROOT/repo/proj-lib/x2.ccl 
$ROOT/repo/proj-lib/x3.ccl 
$ROOT/repo/proj-lib/x4.ccl
 
$ROOT/repo/proj-lib/x5.ccl
 
$ROOT/repo/x1.ccl 
$ROOT/repo/x2.ccl 
$ROOT/repo/x3.ccl 
$ROOT/repo/x4.ccl 
$ROOT/repo/x5.ccl
 
$ROOT/repo/x6.ccl

Primitive Folding

Primitives are instructions that are generated by the compiler and executed by the engine. In some cases, compiling source code (CCL statements) may generate some redundant primitives. Primitive folding merges redundant primitives, decreasing code size and increasing performance.

Shortcutting

Shortcutting AND and OR operators means that the server stops evaluating an expression as soon as the server can determine the result of the expression. For example, if an expression is "boolCol1 AND boolCol2", and if boolCol1 = false, then it is impossible for "boolCol1 AND boolCol2" to be true, so the server can return FALSE without evaluating the rest of the expression.

In most cases, shortcutting expression evaluation increases performance without changing results. However, there may be cases where you want the entire expression evaluated even if the result can be determined earlier. For example, suppose that you have a WHERE clause that looks like the following:

WHERE boolCol1 AND MyBooleanUDF1(col3)

If you want MyUDF1() to be called for every row (perhaps because the UDF sends information elsewhere or saves information that you'll need later), regardless of the result of the expression, then you should not turn on shortcut evaluation.

In some cases you can re-write expressions to allow shortcut expression evaluation without failing to call every function that should be called. For example, in the simple case shown above, you can simply reverse the order of the operands and then enable shortcut evaluation.

WHERE MyBooleanUDF1(col3) AND boolCol1