cobpre; cpre

Description

cpre precompiles a C source program to produce target, listing, and isql files.

cobpre precompiles a COBOL source program to produce target, listing, and isql files.

Syntax

cobpre|cpre [-a] [-b] [-c] [-d]
	[-e] [-f] [-l] [-m] [-p (cpre)] [-q (cobbre)]
	[-r][-s (cpre)] [-t (cobpre)] [-v] [-w] [-x] [-y] 
	[-Ccompiler] 
	[-Ddatabase_name]
	[-Ffips_level] 
	[-G[isql_file_name]]
	[-H[server_name]] 
	[-Iinclude_directory]... 
	[-Jlocale_for_charset] 
	[-Ksyntax_level] 
	[-L[listing_file_name]]
	[-Ninterfaces_file_name]
	[-Otarget_file_name] 
	[-P[password]] 
	[-Sserver_name] 
	[-Ttag_id] 
	[-Vversion_number] 
	-Zlocale_for_messages]
	[@file_name]
 program[.ext] [program[.ext]]...  Parameters

Parameters

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

-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.0.x versions of the Embedded SQL precompilers:

For the 11.1 versions of cpre, the norebind attribute applies to all fetch statements of a cursor whose declaration was precompiled with the -b option.
For the 10.0.x versions of cpre, the norebind attribute applied to all fetch statements in each Embedded SQL source file precompiled with -b, regardless of where the cursors were declared.

-c: turns on the Client-Library debugging feature. When the -c option is used, Client-Library generates calls to ct_debug. This option is useful during application development but should be turned off for final application delivery.

-d: indicates that delimited identifiers will not be used. The application can send character data to the server in double quotes (“ “).

-e: when processing an exec sql connect statement, directs Client Library to use the external configuration file to configure the connection. Without this option, the precompiler generates Client Library function calls to configure the connection. Refer to the Open Client Client-Library/C Reference Manual for information about the external configuration file and the CS_CONFIG_BY_SERVERNAME property.

-f: checks that the SQL contained in the ESQL source file is ANSI SQL-89 compliant. If the user provides a SQL Server name and valid user name/password combination, the precompiler will connect to the server and pass all static SQL to the server for standards compliance checking. -f generates code enabling the server to continue checking the SQL for compliance while an application is being run.

-l: turns off generation of #line directives.

-m: runs the application in Sybase auto-commit mode. Auto-commit mode 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 persistent binds on each command handle. This option improves performance of repeatedly executed commands with input parameters but at the cost of increased storage space and slightly slower response on the first iteration 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).

-q: generates code with double quotes (") rather than a single quote(’).

-r: disables repeatable reads. If you do not use this option, a set transaction isolation level 3 statement is generated and will be executed during connect statements.

-s: includes static function declarations in the precompiled file.

-t: specifies that the input source file is in terminal-mode format (HP Tru64 UNIX).

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

-w: disables display of precompiler warning and informational messages to the screen or a listing file.

-x: instructs Client-Library to use external configuration files. See the CS_EXTERNAL_CONFIG property described in the Open Client Client-Library Reference Manual and the INITIALIZE_APPLICATION statement described in the Embedded SQL Reference Manual.

-y: supports CS_TEXT and CS_IMAGE datatypes so they can be used as input host variables. At runtime, the 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 only performed if the -y command line option is used.

-Ccompiler

specifies the target host language compiler.

cpre – Possible values are “ansi_c” for ANSI standard C and “kr_c” for Kernighan and Ritchie C. If you do not use this option, ansi_c is used as the default target host language compiler.

cobpre – mf_byte — MicroFocus COBOL compiler with byte-aligned data. If you set the precompiler with this argument, you must set the MicroFocus COBOL compiler with the -C NOIBMCOMP argument.

mf_word — MicroFocus COBOL compiler with word-aligned data. If you set the precompiler with this argument, you must set the MicroFocus COBOL compiler with the -C IBMCOMP argument. If you do not use this option, mf_byte is used as the default compiler.

-Ddatabase_name: specifies the name of the database to parse against. Use this option when you want to do SQL semantic checking at precompile time. If -G is specified, a use database command will be added to the beginning of the filename.sql file. If you do not use this option, the precompiler uses your default database on the Adaptive Server.

-Ffips_level: checks that the SQL contained in the Embedded SQL source file is ANSI SQL-89 or SQL-92E compliant. The user must provide an Adaptive Server name and a valid user name/password combination for the precompiler to connect to the server. The -F option generates code enabling the server to continue checking the SQL for compliance while an application is being run. Valid values are SQL89 or SQL92E.

-G[isql_file_name] (optional)

generates stored procedures for appropriate SQL statements and saves them to an isql file. You must execute isql on the isql file to load the stored procedure. 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 name(s) will be the input file name(s) with the extension “.sql” appended (or replacing any input file name extension). Also, see option -Ttag_id to specify tag identification for stored procedures. If you do not use the -G option, no stored procedures are generated.

-H[server_name] (optional): invokes the HA failover option. The secondary server is used if the primary server fails. The command line argument parser reads the -H flag, stores the failover server name, and generates the necessary CT-Lib statements to implement HA failover. To use this option, the secondary server must be up and running and correctly listed in the interfaces file as an HA failover server.

-Iinclude_directory: specifies a directory where Embedded SQL will search for include files. You may specify this option any number of times. Embedded SQL searches the directories in their command line order. If you do not use this option, the default include directories are $SYBASE/include and the current working directory.

-Jlocale_for_charset

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 its default, the precompiler looks for a locale name. The precompiler searches for the following environment variables in the following order:

LC_ALL
LANG

If LC_ALL is defined, the precompiler uses its value as the locale name. If LC_ALL is not defined but LANG is defined, the precompiler uses its value as the locale name.

If neither LC_ALL nor LANG is defined, the precompiler uses a locale name of “default.”

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

-Ksyntax_level

specifies the level of syntax checking to perform. The choices are:

NONE

No checking (no Adaptive Server is required during precompiling).
SYNTAX

Syntax is checked by Adaptive Server during precompiling but does not require databases objects referred to by Embedded SQL statements to be present.
SEMANTIC

Embedded SQL statements checked for syntactic and semantic correctness—database objects referred to by statements must be present. Semantic checking is not performed on statements that include input host variables of type CS_TEXT or CS_IMAGE, regardless of command line options.

-L[listing_file_name] (argument is optional)

generates one or more listing files. A listing file is a version of the input file with each line numbered and followed by any applicable error message. 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 name(s) will be the input file name(s) with the extension “.lis” appended (or replacing any input file name extension). If you do not use this option, no listing file is generated.

-Ninterfaces_file_name: specifies an interfaces file name to the precompiler. If you do not use this option, the default interfaces file $SYBASE/interfaces is used.

-Otarget_file_name

specifies the target or output file name. You cannot use this option if there are multiple input files (default target file names will be assigned). If you do not use this option, the default target file name will be the input file name with:

cpre – the extension .c appended (replacing any input file name extension).

cobpre – the extension .cbl appended (or replacing any input file name extension).

-P[password] (used with option -Uuser_id; argument is optional): specifies an Adaptive Server password for SQL syntax checking at precompile time. -P without an argument or with the key word NULL specifies a null (““) password. If you use option -Uuser_id but do not use -P, the precompiler prompts you to enter a password.

-Sserver_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.

-Ttag_id (used with option -G)

specifies a tag identification (up to 3 characters) to append to the end of the generated stored procedure group name.

For example, if you type -Tdbg as part of your command, your generated stored procedures will be given the name of the input file with the tag identification dbg appended: program_dbg;1, program_dbg;2, and so on.

Programmers can use tag identification 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 identification is added to the stored procedure name.

-Uuser_id

specifies the Adaptive Server user identification.

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 use the -U option but not -P[password], Embedded SQL prompts you to enter a password.

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.

-Vversion_number

specifies the Client-Library version number:

cpre – the version number must be CS_VERSION_100 or higher and the value must exactly match one of the legal values of the version number argument to the ct_init function. (See the Open Client Client-Library Reference Manual for information about the ct_init function.

cobpre – 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_110 for Open Client and Open Server version 11.1).

-Zlocale_for_messages

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:

Looks for a locale name. The precompiler searches for the following environment variables in the following order:
- LC_ALL
- LANG:
  - If LC_ALL is defined, the precompiler uses its value as the locale name. If LC_ALL is not defined but LANG is defined, the precompiler uses its value as the locale name.
  - If neither LC_ALL nor LANG is defined, the precompiler uses a locale name of “default.”
Looks up the locale name in the locales file, and uses the language and character set associated with it as the default for messages.

program[.ext] [program[.ext]] . . .: is the input file name(s) of the Embedded SQL/C source program. You can enter as many input file names as you wish. The file name format and length can be anything you wish as long as it does not violate any operating system rules. See “Comments” following for information about target files and multiple input files.

@file_name: 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 @file_name contains names of the files to precompile, place the argument at the end of the command line.

Examples

Example 1

Run the precompiler (ANSI-compliant):
```
    cobpre | cpre program.pco|.pc 
```
Run the precompiler with generated stored procedures and FIPS flagging (ANSI-compliant):
```
    cobpre | cpre -G -f program1.pco|.pc program2.pco|.pc
```
Run the precompiler for two input files with cursors open across transactions (not ANSI compliant):
```
    cobpre | cpre -a program1.pco|.pc program2.pco|.pc
```
Display the precompiler version information only:
```
    cobpre | cpre -v
```

Usage

DCE precomiler versions

Versions of the precompiler executables are provided for use on machines where DCE is installed.

You can run the regular executables on DCE machines, but they will not be able to connect to servers if DCE is configured as the default directory service for Sybase client applications. (The default directory service is determined by the setup of the $SYBASE/install/libtcl.cfg file. See the Open Client and Open Server Configuration Guide for UNIX for details).

Optional arguments

If you use -G[isql_file_name], -L[listing_file_name], or -P[password] without specifying an argument, another option or the keyword NULL or double quotes (““) must follow on the command line. You cannot follow these options with an input file name. If you do, the precompiler will mistake the input file name for the option argument.
ANSI standards

The cobpre | cpre command defaults are set up for ANSI standard behavior.
The -a, -c, -d, -f, -m, and -r options affect only the connect statement. If your source file does not contain a connect statement or you use the -x option, these options have no effect.
Target file

cpre – The default target file name is program.c. If you have only one input file, you may use option -Otarget_file_name to specify a target file name. If you have multiple input files, the default target files will be named first_input_file.c, second_input_file.c, and so on.

cobpre – The default target file name is the input file name with the extension “.cbl” (for Micro Focus COBOL) appended (or replacing any input file name extension). If you have only one input file, you may use option -Otarget_file_name to specify a target file name. If you have multiple input files, the default target files will be named first_input_file.cbl, second_input_file.cbl, and so on.
Option format

Options will work with or without a space before the argument. For example, either of these options will work:
```
    -Tdbg
```
or
```
    -T dbg 
```
Multiple input files

The precompiler can handle multiple input files. However, you cannot use the option -Otarget_file_name; you must accept the default target file names (see “Target file” above). If you use option -G[isql_file_name], you may not specify an argument; the default isql file names will be first_input_file.sql, second_input_file.sql, and so on. If you use option -L[listing_file_name], you may not specify an argument; the default listing file names will be first_input_file.lis, second_input_file.lis, and so on.

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.

Run the precompiler with options -c, -Ddatabase_name, -P[password], -Sserver_name, 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, -P[password], -Sserver_name, -Uuser_id, -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 with this command:
```
    isql -P[password] -Sserver_name -Uuser_id \
         <isql_file_name
```
Run tests on your program.
Run the precompiler with options -Ddatabase_name , -P[password], -Sserver_name, -Uuser_id, 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 with this command:
```
    isql -P[password] -Sserver_name -Uuser_id \
         <isql_file_name
```
The final distribution program is ready to run.

cobpre | cpre defaults

The following table lists the options and defaults for the cobpre and cpre utilities:

**Table A-6: Defaults and options for cobpre and cpre defaults**
Option	Default if option not used
-Ccompiler	cpre – The ansi_c compiler cobpre – The mf_byte compiler.
-Ddatabase_name	The default database on Adaptive Server.
-G[isql_file_name]	No stored procedures are generated.
-H[server_name]	Failover server name that is used if the primary server fails.
-Iinclude_directory	Default directory is $SYBASE/include.
-Jlocale_for_charset	Platform-specific.
-L[listing_file_name]	No listing file is generated.
-Otarget_file_name	The default target filename is the input filename with the extension .c (for cpre) or .cbl (for cobpre) appended (or replacing any input filename extension).
-Ninterfaces_file_name	The $SYBASE/interfaces file.
-P[password]	You are prompted for a password unless you use -Uuser_id.
-Sserver_name	The default Adaptive Server name is taken from the DSQUERY environment variable.
-Ttag_id	No tag IDs are added to the stored procedure names (generated with -G).
-Uuser_id	The precompiler does not connect to an Adaptive Server or do syntax-checking beyond what is required to generate the target file.
-Vversion_number	CS_VERSION_110 for version 11.1.
-Zlocale_for_messages	Platform/environment specific.