UltraLite User's Guide
  UltraLite Reference

The UltraLite generator

Function 

The UltraLite generator, using the Analyzer classes, implements your application database and generates additional C/C++ or Java source files, which must be compiled and linked into your application.

Syntax 

ulgen [ switches ] [ project [ output-filename ] ]

Description 

The UltraLite generator creates code that you compile and make part of an UltraLite application. Its output is based on the schema of the Adaptive Server Anywhere reference database and the specific SQL statements or tables that you use in your embedded SQL source files.

You must ensure that all your statements and tables are defined in the dbo.ul_statement table before running the generator. You do this as follows:

• In embedded SQL, run the SQL preprocessor on each file.

• In the C/C++ API and Java, add statements to the database using ul_add_statement, and/or define publications in the database.

In this table, statements are associated with projects. By specifying a project name on the generator command line, you determine which statements are included in your generated database.

You can include multiple projects, and also mix projects with a publication, on the generator command line. You must run the generator only once for each generated database.

If you do not specify an output file name, the generated code is written to a file with a name of project. It is recommended that you specify an output file name using the -f command-line switch.

Customizing UltraLite generator operations    The UltraLite analyzer provides hooks that you can use to customize the code generation process. These hooks are stored procedure names. If you supply stored procedures with the following names, the UltraLite analyzer invokes them before and after the analysis process:

• sp_hook_ulgen_begin( )

• sp_hook_ulgen_end( )

These hooks are defined in the reference database and are used only during the analyzer analysis phase. The hooks can be created as follows:

CREATE PROCEDURE sp_hook_ulgen_begin ()
BEGIN
// actions here
END
CREATE PROCEDURE sp_hook_ulgen_end ()
BEGIN
// actions here
END

Switches 

project    The project name determines the set of statements that are to be included in the generated database. For a more precise specification of the filename, use the -j option.

output-filename    The name for the generated file, without extension. For a more precise specification of the filename, use the -f option.

In Java, this name is also the database name, which you must supply on connection.

-a    If you are developing a Java application, the names of the SQL statements in the project are used as constants in your application. By convention, constants are upper case, with underscore characters between words. The -a option makes the names of SQL statements fit this convention by uppercasing the characters and inserting an underscore whenever an uppercase character in the original name is found if not already preceded by an underscore or an uppercase character. For example, a statement named MyStatement becomes MY_STATEMENT, and a statement named AStatement becomes ASTATEMENT.

The generated names have spaces and non-alphanumeric characters replaced with an underscore, regardless of whether -a is used.

-c connection-string    The connection string must give the generator permission to read and modify your reference database. This parameter is required.

-e    The SQL strings in the generated database are replaced by smaller, generated strings. This option is useful when you are trying to reduce the footprint of a database with a lot of statements.

-f filename    This is the recommended way to specify the output file. Do not specify an extension.

-g    Suppress the display of warning messages. Error messages are still displayed.

The UltraLite generator provides warnings to indicate that some generated code may, under some circumstances, cause problems. For example, it generates a warning for SQL statements that include temporary tables.

-i    By default, generated classes are written as top-level non-public classes except for the main database class. If you use -i, the generated classes are written as inner classes. If you use this option, you must use a Java compiler that can correctly compile inner classes.

-j project-name    This is the recommended way to specify the project. You can specify multiple projects using this switch as follows:

ulgen -j project1 -j project2 ...

-l type    Log the execution plan for queries in the application. These plans can be viewed in Interactive SQL. The types available are:

• xml    Description in XML format. Use the Interactive SQL File > Open command to display the plan.

• short    Brief description of the plan in a file named <statement>.txt. The content is that generated by the EXPLANATION function

• long    Detailed description of the plan in a file named <statement>.txt. The content is that generated by the PLAN function.

-m version    Specify the version name for generated synchronization scripts. The generated synchronization scripts can be used in a MobiLink consolidated database for simple synchronization.

-o table-name,...    Specify the order in which tables are uploaded during synchronization. This option can be used to avoid referential integrity errors during upload. Each table to be uploaded must be specified exactly once. The option cannot be used when there are circular foreign key relationships among the tables.

-p package-name    A package name for generated files when generating Java output.

-q    Do not display output messages.

-r filename    The file containing the trusted root certificates used for secure synchronization using Certicom security software.

The generator embeds these trusted roots into the UltraLite application. When the application receives a certificate chain from a MobiLink synchronization server, it checks if its root is among the trusted roots, and only accepts a connection if it is.

The generator checks the expiry dates of all the certificates in the trusted root certificate file and issues the following warning for any certificate that expires in less than 6 months (180 days):

Warning: Certificate will expire in %1 days"

The generator issues a Certificate has expired error for any certificate that has already expired.

For more information, see Synchronization parameters, and Transport-Layer Security.

-s filename    Generate an interface that contains the SQL statements as constants. This option is for use with Java only. The interface file has a format similar to the following example:

package com.sybase.test;
public interface EmpTestSQL {
    String EMPLOYEE = "select emp_fname, emp_lname
      from employee where emp_id = ?";
    String UPDATE_EMPLOYEE = "update employee
      set emp_fname = ?, emp_lname = ?
      where emp_id = ?";
}

Do not supply the .java extension in filename. The -a option controls the case of the statement names.

-t target    Specifies the kind and extension of the generated file.

• If you are using Java, you must use a target of java. If you are using embedded SQL or the C++ API, you can use a target of either c or c++. Which one you choose decides the extension of the file name, and has nothing to do with whether you are using the C++ API or embedded SQL.

• If you specify c++, the following files are generated:

  • filename.cpp    The code for the generated API.

  • filename.h    A header file. You do not need to look at this file.

  • filename.hpp    The C++ API definition for your application.

• If you specify a target of c, filename.c is generated.

-u pub-name    If you are generating a C++ API for a publication, specify the publication name with the -u switch.

-v pub-name    Specifies a publication to synchronize. If you do not use publications to define which changes are to be synchronized, all changes are synchronized.

If columns or tables specified in publications are not referenced by SQL statements in your application, they are not included in the UltraLite database.

To specify multiple publications, repeat the -v option. For example:

ulgen -v pub1 -v pub2 ...

The maximum number of publications is 32.

For more information, see Designing synchronization for UltraLite applications.

-x    This option is intended for use in situations where the file containing the generated code is too large for the C/C++ compiler to compile.

This switch causes the UltraLite generator to produce more and smaller files. When -x is used, the UltraLite generater writes out one C/C++ file for the database and one for each SQL statement.

This switch has no effect when generating Java code.