cobpre precompiles a COBOL source program to produce target, listing, and isql files. This utility is available in the $SYBASE/$SYBASE_OCS/bin directory.
64-bit applications
The precompilers for 64-bit applications are cobpre64 and cobpre_r64.
The cobpre64 precompiler
is the non-reentrant precompiler, and the cobpre_r64 is the
reentrant version.
cobpre
[-Ccompiler]
[-Ddatabase_name]
[-Ffips_level]
[-G[isql_file_name]]
[-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]
[@ options_file]
[-a] [-b] [-c] [-d] [-e] [-f] [-l] [-m] [-r] [-s] [-u] [-v] [-w] [-x] [-y]
filename[.ext]
Options can be flagged using either a slash (/)
or a dash (-);therefore,
cobpre -l and cobpre /l are equivalent.
Specifies the target host language compiler values, such as:
“mf_byte” – Micro Focus COBOL with byte-aligned data (-C NOIBMCOMP).
“mf_word” – Micro Focus COBOL with word-aligned data (-C IBMCOMP).
Specifies the name of the database to parse against. Use this option when you want to check SQL semantics 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.
Checks for the specified conformance level. Currently, the precompiler can check for SQL89 or SQL92E.
Generates stored procedures for appropriate SQL statements and saves them to a file for input to the database through isql. 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 .isql appended (or replacing any input file name extension).
Also, see option -Ttag_id to specify tag IDs for stored procedures.
If you do not use the -G option, no stored procedures are generated.
Specifies a directory complete with the path name, where Embedded SQL will search 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.
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 the following 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.dat file and uses the character set associated with the locale name as the default character set.
Specifies the level of syntax checking to perform. The choices are:
NONE
SYNTAX
SEMANTIC
NONE is the default value. If you use either SYNTAX or SEMANTIC, you must also specify the -U, -P, -S, and -D options so that 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.
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.
Turns on security feature. Sets B1 secure labels.
Specifies the configuration file name, interfaces to the precompiler.
Specifies the target or output file name. If you have multiple input files, you may not use this option (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 the extension .cbl appended (or replacing any input file name extension).
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.
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, then SYBASE is used as the name of the server.
Specifies a tag ID (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 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.
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 option -Ppassword, this option prompts you to enter a password.
Also, see -K, -P, -S, and -D options.
Specifies the Client-Library version number. This 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_150 for Open Client and Open Server version 15.0).
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 in the following 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.”
Looks up the locale name in the locales.dat file 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.
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.
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.
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 as follows:
For the 11.1 and later versions of cobpre, the norebind attribute applies to all fetch statements of a cursor whose declaration was precompiled with the -b option.
For the 10.0 and later versions of cobpre, the norebind attribute applied to all fetch statements in each Embedded SQL source file precompiled with -b, regardless of where the cursors were declared.
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. For this option to work properly, the application must be linked and run with the libraries and DLLs located in the %SYBASE%\%SYBASE_OCS\devlib directory of the Sybase release directory.
Turns off delimited identifiers (identifiers delimited by double quotes) and allows quoted strings in SQL statements to be treated as character literals.
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. Refer to the Open Client Client-Library/C Reference Manual for information about the external configuration file
Turns on the FIPS flagger for ANSI FIPS compliance checking.
Turns off generation of #line directives.
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.
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.
Includes static function declarations.
Disables ANSI binds.
Displays the precompiler version information only (without precompiling).
Turns off display of warning messages.
Uses external configuration files. See 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.
Supports S_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.
Specifies the input file name of the ESQL/C source program. The file name format and length can be anything you want as long as it does not violate any rules.
Run the precompiler (ANSI-compliant):
cobpre program.pco
Run the precompiler with generated stored procedures and FIPS flagging (ANSI-compliant):
cobpre -G -f program1.pco
Run the precompiler for input file with cursors open across transactions (not ANSI-compliant):
cobpre -a program1.pco
Display the precompiler version information only:
cobpre -v
Run the precompiler with the highest level of SQL checking:
cobpre -K SEMANTIC -Uuser_id -Ppassword -Sserver_name \ -Dpubs2 example1.pco
The cobpre| command defaults are set up for ANSI standard behavior.
Target file: 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 -O target_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, etc.
Option format: Options will work with or without a space before the argument. For example, either of these formats will work:
-Tdbg or -T dbg
The precompiler can handle multiple input files. However, you may not use the option -O target_file_name, but must accept the default target file names (see “Target file” above). If you use option -G[isql_file_name], you cannot 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 cannot specify an argument; the default listing file names will be first_input_file.lis, second_input_file.lis, and so on.
By default, cobpre 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 run-time error and aborts the application in use. You can avoid these issues by using -u with cobpre. You may also disable ANSI binds by setting CS_ANSI_BINDS to cs_false in the ocs.cfg file.
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. These steps must be performed at the DOS command prompt.
Run the precompiler with options -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 with this command:
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 with this command:
isql -Ppassword -Sserver_name -Uuser_id -Gisql_file_name
The final distribution program is ready to run.
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 or cobpre command line
Setting the DSQUERY variable
Using the default value, “SYBASE”
The -S option overrides the value set by DSQUERY.
Following is the syntax for choosing a server on the precompile command line:
cobpre -Usa -P -Sserver_name
As an alternative, you can leave the server name out of 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 on DSQUERY.
See Table A-5 for a list of options and defaults for the for the cpre and cobpre utilities.
