cpre

Description

cpre precompiles a C source program to produce target, listing, and isql files. This utility is available in the $SYBASE/$SYBASE_OCS/bin directory.

The precompilers 64-bit applications are cpre64 and cpre_r64. The cpre64 precompiler is the non-reentrant precompiler, and the cpre_r64 is the reentrant version. You can use these precompilers on any 64-bit platform supported for Open Client and Open Server

Syntax

cpre
     [-Ccompiler] 
     [-Ddatabase_name]
     [-Ffips_level]
     [-G[isql_file_name]] 
     [-H]
     [-Iinclude_path_name]... 
     [-Jcharset_locale_name] 
     [-Ksyntax_level]
     [-L[listing_file_name]]
     [-Ninterface_file_name]
     [-Otarget_file_name] 
     [-Ppassword] 
     [-Sserver_name] 
     [-Ttag_id] 
     [-Uuser_id] 
     [-Vversion_number] 
     [-Zlanguage_locale_name]
    [-a] [-b] [-c] [-d] [-e] [-f] [-h] [-l] [-m] [-p] [-r] [-s] [-u] [-v] [-w] [-x] [-y]
    filename[.ext]

You can use either a slash (/) or a dash (-) to specify options; for example, cpre -l and cpre /l are equivalent.

Parameters

-C compiler: Specifies the target host language compiler values, such as “ANSI_C”, which is an ANSI C compiler.

-D database_name: Specifies the name of the database to parse against. Use this option to check SQL semantics at precompile time. If you also specify -G, use database command is added to the beginning of the filename.sql file. If you do not use this option, the precompiler uses the default database on the Adaptive Server.

-F fips_level: Checks for the specified conformance level. Currently, the precompiler can check for SQL89 or SQL92E.

-G isql_file_name: Generates stored procedures for appropriate SQL statements and saves them to a file for input to the database through isql. isql_file_name is optional. If you have multiple input files, you may use -G, but you cannot specify an argument.

If you have multiple input files or do not specify the argument, the default target file names are the input file names with the extension .isql either appended, or replacing any existing input file name extension.

Also, see option -T tag_id to specify tag IDs for stored procedures.

If you do not use the -G option, no stored procedures are generated.

-H: Generates code with failover capability.

-I include_path_name: Specifies a directory complete with the path name, where Embedded SQL searches for include files. You can specify this option any number of times. Embedded SQL searches the directories in command line order. If you do not use this option, the default is the /include directory of the Sybase release directory and the current working directory.

-J charset_locale_name: Specifies the character set of the source file that is being precompiled. The option’s value must be a locale name that corresponds to an entry in the locales file. If you do not specify -J, the precompiler interprets the source file as being in the precompiler’s default character set.

To determine which character set to use as the default, the precompiler looks for a locale name. CS-Library searches for the information in this order:

LC_ALL

LANG

If LC_ALL is defined, CS-Library uses its value as the locale name. If LC_ALL is not defined but LANG is defined, CS-Library uses its value as the locale name. If none of these locale values are defined, CS-Library uses a locale name of “default.”

The precompiler looks up the locale name in the locales file and uses the character set associated with the locale name as the default character set.

-K syntax_level: Specifies the level of syntax checking to perform:

none (default)

syntax

semantic

If you use either SYNTAX or SEMANTIC, you must also specify the -U, -P, -S, and -D options so Embedded SQL can connect to your Adaptive Server.

If you do not use this option, the precompiler does not connect to a server or perform SQL syntax checking of the input file beyond what is required to generate the target file.

-L listing_file_name: Generates one or more listing files. listing_file_name, which is an optional argument, is a version of the input file that numbers each line, and includes any applicable error messages. If you have multiple input files, you may use -L, but you cannot specify an argument.

If you have multiple input files or do not specify the argument, the default listing file names are the input file names with the extension .lis either appended, or replacing any existing input file name extension.

If you do not use this option, no listing file is generated.

-N interface_file_name: Specifies the interface file name, interfaces, to the precompiler.

-O target_file_name: Specifies the target or output file name. If you have multiple input files, you cannot use this option; default target names are assigned—the input file name with the extension .cbl either appended, or replacing any existing input file name extension.

-P password (used with option -Uuser_id): Specifies an Adaptive Server password for SQL syntax checking at precompile time. Using -P without an argument, or with the keyword NULL as an argument, specifies a null (““) password. If you use option -Uuser_id without using -P, the precompiler prompts you to enter a password. Must be used with the -G flag.

-S server_name: Specifies the name of the Adaptive Server for SQL syntax checking at precompile time. If you do not use this option, the default Adaptive Server name is taken from the DSQUERY environment variable. If DSQUERY is not set, SYBASE is used as the name of the server.

-T tag_id (used with option -G): Specifies a tag ID (up to 3 characters) to append to the end of the generated stored procedure group name.

For example, if you enter -T dbg as part of your command, generated stored procedures are assigned the name of the input file with the tag ID dbg appended: program_dbg;1, program_dbg;2, and so on.

Programmers can use tag IDs to test changes to an existing application without destroying the existing generated stored procedures, which may be in use.

If you do not use this option, no tag ID is added to the stored procedure name.

-U user_id: Specifies the Adaptive Server user ID. This option allows you to check SQL syntax at precompile time. It causes the precompiler to pass SQL statements to the server for parsing only. If the server detects syntax errors, the errors are reported and no code is generated. If you are not using -Ppassword, this option prompts you to enter a password.

Also see -K, -P, -S, and -D options.

-V version_number: Specifies the Client-Library version number. For COBOL, the version number must match one of the values from cobpub.cbl. If you do not use this option, the default is the most recent version of Client-Library available with the precompiler (CS_VERSION_155 for Open Client and Open Server version 15.5).

-Z language_locale_name: Specifies the language and character set that the precompiler uses for messages. If you do not specify -Z, the precompiler uses its default language and character set for messages.

To determine which language and character set to use as its default for messages, the precompiler performs the following, in order:

Looks for a locale name. CS-Library searches for the information first in LC_ALL, then in LANG. If neither of these locale values are defined, CS-Library uses a locale name of “default.”

Looks up the locale name in the locales.dat file available in $SYBASE/locales directory to determine which language and character set are associated with it.

Loads localized messages and character set information appropriate to the language and character set determined in step 2.

@options_file: Can be used to specify a file containing any of the above command-line arguments. The precompiler reads the arguments contained in this file in addition to any arguments already specified. If the file specified with @options_file contains names of the files to precompile, place the argument at the end of the command line.

-a: Allows cursors to remain open across transactions. If you do not use this option, cursors behave as though set close on endtran on were in effect. This behavior is ANSI-compatible. See the Adaptive Server Enterprise Reference Manual for information about cursors and transactions.

-b: Disables rebinding of host variable addresses typically used in fetch statements. If you do not use this option, a rebind occurs on every fetch statement unless you specify otherwise in your Embedded SQL/C program.

The -b option differs in the 11.1 and 10.x versions of the Embedded SQL precompilers:

For the 11.1 and later versions of cpre, the norebind attribute applies to all fetch statements of a cursor for which the declaration was precompiled with the /b option.

For the 10.0 and earlier versions of cpre, the norebind attribute applies to all fetch statements in each Embedded SQL source file precompiled with /b, regardless of where the cursors were declared.

-c: Turns on the debugging feature of Client-Library by generating calls to ct_debug.

This option is useful during application development but should be turned off for final application delivery. The application must be linked and run with the libraries located in the $SYBASE/$SYBASE_OCS/devlib directory of the Sybase release directory.

-d: Turns off delimited identifiers (identifiers delimited by double quotes) and allows quoted strings in SQL statements to be treated as character literals.

-e: When processing an exec sql connect statement, directs Client-Library to use the external configuration file to configure the connection. Also see the /x option and CS_CONFIG_BY_SERVERNAME property in the Open Client Client-Library/C Reference Manual.

Without this option, the precompiler generates Client-Library function calls to configure the connection. See the Open Client Client-Library/C Reference Manual for information about the external configuration file

-f: Turns on the FIPS flagger for ANSI FIPS compliance checking.

-h: Generates thread-safe code.

-l: Turns off generation of #line directives.

-m: Runs the application in Sybase auto-commit mode, which means that transactions are not chained. Explicit begin and end transactions are required, or every statement is immediately committed. If you do not specify this option, the application runs in ANSI-style chained transaction mode.

-p: Generates a separate command handle for each SQL statement in the module that has input host variables, and enables sticky binds on each command handle. This option improves performance of repeatedly executed commands with input parameters at the cost of increased storage space usage and longer first executions of each such command.

Applications that rely on inserting empty strings instead of NULL strings when the host string variable is empty do not work if the -p option is turned on. The persistent bind implementation prevents Embedded SQL from circumventing Client-Library protocol (which inserts NULL strings).

-r: Disables repeatable reads. If you do not use this option, a set transaction isolation level 3 statement, which executes during connect statements, is generated. The default isolation level is 1.

-s: Includes static function declarations.

-u: Disables ANSI binds.

-v: Displays the precompiler version information only (without precompiling).

-w: Turns off display of warning messages.

-x: Uses external configuration files. See the CS_EXTERNAL_CONFIG property described in the Open Client Client-Library/C Reference Manual, and the INITIALIZE_APPLICATION statement described in the Open Client Embedded SQL/C Programmers Guide.

-y: Supports S_TEXT and CS_IMAGE datatypes so they can be used as input host variables. At runtime, data is directly included into the character string sent to the server. Only static SQL statements are supported; use of text and image as input parameters to dynamic SQL is not supported. This substitution of arguments into command strings is performed only if the -y command line option is used.

filename[.ext]: Specifies the input file name of the ESQL/C source program. The file name format and length can be anything that complies with the applicable rules.

Examples

Example 1

Runs the precompiler (ANSI-compliant):

    cpre program.pc

Example 2

Runs the precompiler with generated stored procedures and FIPS flagging (ANSI-compliant):

cpre -G -f program1.pc

Example 3

Runs the precompiler for input file with cursors open across transactions (not ANSI-compliant):

    cpre -a program1.pc

Example 4

Displays the precompiler version information only:

    cpre -v

Example 5

Runs the precompiler with the highest level of SQL checking:

 cpre -K SEMANTIC -Uuser_id -Ppassword -Sserver_name -Dpubs2 example1.pc

Usage

The cpre command defaults are set up for ANSI standard behavior.
The -a, -c, -f, -m, -r, and -V options affect only the connect statement. If your source file does not contain a connect statement, or if you use -e or -x , these options have no effect.
Options work with or without a space before the argument. For example, either of these formats works:

-T dbg or -T dbg
The precompiler can handle multiple input files. However, you cannot use the option -O target_file_name, but must accept the default target file names (see “Target file” above). If you use -G[isql_file_name], you cannot specify an argument; the default isql file names are first_input_file.sql, second_input_file.sql, and so on. If you use option -L[listing_file_name], you cannot specify an argument; the default listing file names are first_input_file.lis, second_input_file.lis, and so on.
By default, cpre generate calls to ct_options that enable ANSI-style binding of indicator variables (CS_ANSI_BINDS). If indicator variables for nullable host variables (columns) are not available, Client-Library generates a fatal runtime error and aborts the application in use. You can avoid these issues by using -u with cpre. You can also disable ANSI binds by setting CS_ANSI_BINDS to cs_false in the ocs.cfg file.

Developing an application

This section lists the steps most commonly used in developing an Embedded SQL application. You may need to adapt this process to meet your own requirements. Perform these steps at the DOS command prompt.

Run the precompiler with options -c, -Ddatabase_name, -Ppassword, -Sserver_name, -K[ SYNTAX| SEMANTIC], and -Uuser_id for syntax checking and debugging. Do not use -G[isql_file_name]. Compile and link the program to make sure the syntax is correct.
Make all necessary corrections. Run the precompiler with options -Ddatabase_name, -G[isql_file_name], and -Ttag_id to generate stored procedures with tag IDs for a test program. Compile and link the test program. Load the stored procedures using:
```
    isql -Ppassword -Sserver_name -Uuser_id -Gisql_file_name
```
Run tests on your program.
Run the precompiler with options -Ddatabase_name and -G[isql_file_name] (but without option -T) on the corrected version of the program. Compile and link the program. Load the stored procedures using:
```
 isql -Ppassword -Sserver_name -Uuser_id -Gisql_file_name
```
The final distribution program is ready to run.

How precompilers determine the names of their servers

You can connect with an Adaptive Server at precompile time, which allows you to do additional syntax checking at that time. The precompiler determines the name of its server in one of three ways:

Using the -S option on the cpre command line
Setting the DSQUERY variable
Using the default value, “SYBASE”

The -S option overrides the value set by DSQUERY.

To specify a server on the precompile command line, use:

cpre -Usa -P -Sserver_name

As an alternative, you can omit the server name from the connection call or statement, and server_name will take its value from the runtime value of the DSQUERY environment variable. If the application user has not set DSQUERY, the runtime value for the server name defaults to “SYBASE.” See the Open Client and Open Server Configuration Guide for UNIX for more information about DSQUERY.

cpre defaults

Table A-6 lists the options and defaults for the cpre and cobpre utilities:

**Table A-6: cpre and cobpre defaults**
Option	Default if option not used
-C compiler	The mf_byte compiler for COBOL. ANSI-C for C.
-D database_name	The default database on Adaptive Server.
-F fips_level	(No FIPS flags available.)
-G [isql_file_name]	No stored procedures are generated.
-I include_path_name	Default directory is the /include directory of the Sybase release directory.
-J charset_locale_name	[platform-specific]
-K [syntax \| semantic \| none]	If neither syntax nor semantic is selected, the default setting is “None.”
-L [listing_file_name]	No listing file is generated.
-N interface_file_name	The interfaces file in the Sybase release directory.
-O target_file_name	The default target file name is the input file name with the extension .cbl or .c appended (or replacing any input file name extension).
-P password	You are not prompted for a password unless you use -Uuser_id.
-S server_name	The default Adaptive Server name is taken from the DSQUERY environment variable.
-T tag_id	No tag IDs are added to the stored procedure names generated with -G.
-U *user_id*	None.
-V *version_number*	CS_VERSION_125 for version 12.5.x CS_VERSION_150 for version 15.0 CS_VERSION_155 for version 15.5
-Z language_locale_name	[platform/environment specific]