Precompilation of embedded SQL applications with the PRECOMPILE command

After you create the source files for an embedded SQL application, you must precompile each host language file containing SQL statements with the PREP command, using the options specific to the host language. The precompiler converts SQL statements contained in the source file to comments, and generates the Db2® runtime API calls for those statements.

You must always precompile a source file against a specific database, even if eventually you do not use the database with the application. In practice, you can use a test database for development, and after you fully test the application, you can bind its bind file to one or more production databases. This practice is known as deferred binding.

Restriction: Running an embedded application on an older client version than the client where precompilation occurred is not supported, regardless of where the application was compiled. For example, it is not supported to precompile an embedded application on a Db2 V9.5 client and then attempt to run the application on a Db2 V9.1 client.
If your application uses a code page that is not the same as your database code page, you need to consider which code page to use when precompiling.

If your application uses user-defined functions (UDFs) or user-defined distinct types (UDTs), you might need to use the FUNCPATH parameter when you precompile your application. This parameter specifies the function path that is used to resolve UDFs and UDTs for applications containing static SQL. If FUNCPATH is not specified, the default function path is SYSIBM, SYSFUN, USER, where USER refers to the current user ID.

Before precompiling an application you must connect to a server, either implicitly or explicitly. Although you precompile application programs at the client workstation and the precompiler generates modified source and messages on the client, the precompiler uses the server connection to perform some of the validation.

The precompiler also creates the information the database manager needs to process the SQL statements against a database. This information is stored in a package, in a bind file, or in both, depending on the precompiler options selected.

A typical example of using the precompiler follows. To precompile a C embedded SQL source file called filename.sqc, you can issue the following command to create a C source file with the default name filename.c and a bind file with the default name filename.bnd:

   DB2 PREP filename.sqc BINDFILE
Restriction: The byte order mark (BOM) with UTF-8 for a C embedded SQL source file is not supported.
The precompiler generates up to four types of output:
Modified Source
This file is the new version of the original source file after the precompiler converts the SQL statements into Db2 runtime API calls. It is given the appropriate host language extension.
Package
If you use the PACKAGE parameter (the default), or do not specify any of the BINDFILE, SYNTAX, or SQLFLAG parameters, the package is stored in the connected database. The package contains all the information required to issue the static SQL statements of a particular source file against this database only. Unless you specify a different name with the PACKAGE USING parameter, the precompiler forms the package name from the first 8 characters of the source file name.

If you use the PACKAGE parameter without SQLERROR CONTINUE, the database used during the precompile process must contain all of the database objects referenced by the static SQL statements in the source file. For example, you cannot precompile a SELECT statement unless the table it references exists in the database.

With the VERSION parameter, the bind file (if the BINDFILE parameter is used) and the package (either if bound at PREP time or if bound separately) is designated with a particular version identifier. Many versions of packages with the same name and creator can exist at once.

Bind File
If you use the BINDFILE parameter, the precompiler creates a bind file (with extension .bnd) that contains the data required to create a package. This file can be used later with the BIND command to bind the application to one or more databases. If you specify BINDFILE and do not specify the PACKAGE parameter, binding is deferred until you invoke the BIND command. Note that for the command line processor (CLP), the default for PREP does not specify the BINDFILE parameter. Thus, if you are using the CLP and want the binding to be deferred, you need to specify the BINDFILE parameter.

Specifying SQLERROR CONTINUE creates a package, even if errors occur when binding SQL statements. Those statements that fail to bind for authorization or existence reasons can be incrementally bound at execution time if VALIDATE RUN is also specified. Any attempt to issue them at run time generates an error.

Message File
If you use the MESSAGES parameter, the precompiler redirects messages to the indicated file. These messages include warning and error messages that describe problems encountered during precompilation. If the source file does not precompile successfully, use the warning and error messages to determine the problem, correct the source file, and then attempt to precompile the source file again. If you do not use the MESSAGES parameter, precompilation messages are written to the standard output.