Pro*C/C++ Precompiler Programmer's Guide Release 8.0 A58233-01 |
Library | Product | Contents | Index

# 9
Running the Pro*C/C++ Precompiler

This chapter tells you how to run the Pro*C/C++ precompiler, and describes the extensive set of precompiler options in detail.

Topics are:

- The Precompiler Command
- Precompiler Options
- What Occurs during Precompilation?
- Scope of Options
- Entering Options
- Using the Precompiler Options
- Conditional Precompilations
- Guidelines for Precompiling Separately
- Compiling and Linking

## The Precompiler Command

To run the Pro*C/C++ precompiler, you issue the following command:

    proc ...

The location of the precompiler differs from system to system. The system or database administrator usually defines logicals or aliases, or uses other system-specific means to make the Pro*C/C++ executable accessible.

The INAME= argument specifies the source file to be precompiled. For example, the command

    proc INAME=test_proc

precompiles the file test_proc.pc in the current directory, since the precompiler assumes that the filename extension is .pc. The INAME option does not have to be the first option on the command line, but if it is, you can omit the option specification. So, the command

    proc myfile

is equivalent to

    proc INAME=myfile

    Note: The option names, and option values that do not name specific OS objects, such as filenames, are not case-sensitive. In the examples in this guide, option names are written in upper case, and option values are usually in lower case. When you enter filenames, including the name of the Pro*C/C++ precompiler executable itself, always follow the case conventions used by your operating system.

## Precompiler Options

Many useful options are available at precompile time. They enable you to control how resources are used, how errors are reported, how input and output are formatted, and how cursors are managed.

The value of an option is a string literal, which represent text or numeric values. For example, for the option

    ...  INAME=my_test

the value is a string literal that specifies a filename. But for the option MAXOPENCURSORS

    ...MAXOPENCURSORS=20

the value is numeric.

Some options take Boolean values, and you can represent these with the strings yes or no, true or false, or with the integer literals 1 or 0 respectively. For example, the option

    ...  SELECT_ERROR=yes

is equivalent to

    ...  SELECT_ERROR=true

or

    ...  SELECT_ERROR=1

all of which mean that SELECT errors should be flagged at run time.

The option value is always separated from the option name by an equals sign, with no whitespace around the equals sign.

### Default Values

Many of the options have default values. The value of an option is determined by:

- a value built in to the precompiler
- a value set in the Pro*C/C++ system configuration file
- a value set in a Pro*C/C++ user configuration file
- a value set in the command line
- a value set inline

For example, the option MAXOPENCURSORS specifies the maximum number of cached open cursors. The built-in precompiler default value for this option is 10. However, if MAXOPENCURSORS=32 is specified in the system configuration file, the default now becomes 32. The user configuration file could set it to yet another value, which then overrides the system configuration value. If this option is set on the command line, the new command-line value takes precedence over the precompiler default, the system configuration file specification, and the user configuration file specification.

Finally, an inline specification takes precedence over all preceding defaults. See the section "Configuration Files" on page 9-5 for more information about configuration files.

Some options, such as USERID, do not have a precompiler default value. The built-in default values for options that do have them are listed in Table 9-1 , and in "Using the Precompiler Options" on page 9-10.

Attention: Check your system-specific documentation for the precompiler default values; they may be changed for your platform.

#### Determining Current Values

You can interactively determine the current value for one or more options by using a question mark on the command line. For example, if you issue the command

    proc ?

the complete set of options, along with their current values, is printed to your terminal. (On a UNIX system running the C shell, escape the `?' with a backslash.) In this case, the values are those built into the precompiler, overridden by any values in the system configuration file. But if you issue the command

    proc config=my_config_file.h ?

and there is a file named my_config_file.h in the current directory, all options are listed. Values in the user configuration file supply missing values, and supersede values built-in to the Pro*C/C++ precompiler, or values specified in the system configuration file.

Note that a configuration file must have only one option per line. Any other options entered after the first are ignored.

You can also determine the current value of a single option, by simply specifying that option name, followed by =?. For example:

    proc maxopencursors=?

prints the current default value for the MAXOPENCURSORS option.

Entering:

    proc

will give a short summary which resembles Table 9-1 .

### Case Sensitivity

In general, you can use either uppercase or lowercase for precompiler option names and values. However, if your operating system is case sensitive, like UNIX, you must specify filename values, including the name of the Pro*C/C++ executable, using the correct combination of upper and lowercase letters.

### Configuration Files

A configuration file is a text file that contains precompiler options. Each record (line) in the file contains only one option, with its associated value or values. Any options entered on a line after the first option are ignored. A configuration file can contain the lines

    FIPS=YES
    MODE=ANSI
    CODE=ANSI_C

to set defaults for the FIPS, MODE, and CODE options.

There is a single system configuration file for each Oracle installation. The name of the system configuration file is pcscfg.cfg. The location of the file is system specific.

Each Pro*C/C++ user can have one or more private configuration files. The name of the configuration file must be specified using the CONFIG= precompiler option. See "Using the Precompiler Options" on page 9-10.

  Note: You cannot nest configuration files. This means that CONFIG= is not a valid option inside a configuration file.

## What Occurs during Precompilation?

During precompilation, Pro*C/C++ generates C or C++ code that replaces the SQL statements embedded in your host program. The generated code contains data structures that indicate the datatype, length, and address of host variables, as well as other information required by the Oracle runtime library, SQLLIB. The generated code also contains the calls to SQLLIB routines that perform the embedded SQL operations.

  Note: The precompiler does not generate calls to Oracle Call Interface (OCI) routines.

The precompiler can issue warnings and error messages. These messages have the prefix PCC-, and are described in the Oracle8 Error Messages manual.

Table 9-1 is a quick reference to the major precompiler options. It summarizes the section "Using the Precompiler Options" on page 9-10. The options that are accepted, but do not have any affect, are not included in this table.

## Scope of Options

A precompilation unit is a file containing C code and one or more embedded SQL statements. The options specified for a given precompilation unit affect only that unit; they have no effect on other units. For example, if you specify HOLD_CURSOR=YES and RELEASE_CURSOR=YES for unit A, but not for unit B, SQL statements in unit A run with these HOLD_CURSOR and RELEASE_CURSOR values, but SQL statements in unit B run with the default values.

##### Table 9-1 Precompiler Options

Syntax | Default | Specifics
--- | --- | ---
AUTO_CONNECT=YES|NO | NO | Automatic OPS$ logon
CHAR_MAP=VARCHAR2|CHARZ|STRING|CHARF | CHARZ | mapping of character arrays and strings
CODE=ANSI_C | KR_C | CPP | KR_C | kind of C code generated
COMP_CHARSET= MULTI_BYTE|SINGLE_BYTE | MULTI_BYTE | the character set type the C/C++ compiler supports
CONFIG=<filename> | none | user's private configuration file
CPP_SUFFIX=<extension> | none | specify the default filename extension for output files
DBMS= V7 | NATIVE | NATIVE | compatibility (Oracle7, or the database version to which you are connected at precompile time)
DEFINE=<name> | none | define a name for use by the Pro*C/C++ precompiler
DEF_SQLCODE=YES|NO | NO | generate a macro to #define SQLCODE
DURATION | TRANSACTION | set pin duration for objects in the cache
ERRORS=YES | NO | YES | where to direct error messages (NO means only to listing file, and not to terminal)
ERRTYPE | none | name of the listing file for intype file error messages
FIPS=NONE | SQL89 | SQL2 | none | whether to flag ANSI/ISO non-compliance
HOLD_CURSOR=YES |NO | NO | how cursor cache handles SQL statement
INAME=<filename> | none | name of the input file
INCLUDE=<pathname> | none | directory path for EXEC SQL INCLUDE or #include statements
INTYPE=<filename> | none | name of the input file for type information
LINES=YES | NO | NO | whether #line directives are generated
LNAME=<filename> | none | name of listing file
LTYPE=NONE|SHORT| LONG | SHORT | type of listing file to be generated, if any
MAXLITERAL=10..1024 | 1024 | maximum length (bytes) of string literals in generated C code
MAXOPENCURSORS=5..255 | 10 | number of concurrent cached open cursors
MODE=ANSI|ISO|ORACLE | ORACLE | ANSI/ISO or Oracle behavior
NLS_CHAR=(<var1>, ..., <varn>) | none | specify NLS character variables
NLS_LOCAL=YES|NO | NO | control NLS character semantics
OBJECTS=YES|NO | YES | support object types
ONAME=<filename> | NONE | name of the output (code) file
ORACA=YES|NO | NO | whether to use the ORACA
PAGELEN | 80 | the page length of the listing file
PARSE=NONE | PARTIAL | FULL | FULL | whether Pro*C/C++ parses (with a C parser) the .pc source.
RELEASE_CURSOR=YES|NO | NO | control release of cursors from cursor cache
SELECT_ERROR=YES|NO | YES | flagging of SELECT errors
SQLCHECK=SEMANTICS|SYNTAX | SYNTAX | kind of precompile time SQL checking
SYS_INCLUDE=<pathname> | none | directory where system header files, such as iostream.h, are found
THREADS=YES|NO | NO | indicates a multi-threaded application
UNSAFE_NULL=YES|NO | NO | UNSAFE_NULL=YES disables the ORA-01405 message
USERID=<username>/<password> | none | username/password[@dbname] connect string
VARCHAR=YES|NO | NO | allow the use of implicit VARCHAR structures
VERSION | RECENT | which version of an object is to be returned

## Entering Options

You can enter any precompiler option in the command line. Many can also be entered inline in the precompiler program source file, using the EXEC ORACLE OPTION statement.

### On the Command Line

You enter precompiler options in the command line using the following syntax:

    ... [OPTION_NAME=value] [OPTION_NAME=value] ...

Separate each option=value specification with one or more spaces. For example, you might enter the following:

    ... CODE=ANSI_C MODE=ANSI

### Inline

You enter options inline by coding EXEC ORACLE statements, using the following syntax:

    EXEC ORACLE OPTION (OPTION_NAME=value);

For example, you might code the following:

    EXEC ORACLE OPTION (RELEASE_CURSOR=yes);

#### Uses for EXEC ORACLE

The EXEC ORACLE feature is especially useful for changing option values during precompilation. For example, you might want to change HOLD_CURSOR and RELEASE_CURSOR on a statement-by-statement basis. Appendix C, "Performance Tuning" shows you how to optimize runtime performance using inline options.

Specifying options inline or in a configuration file is also helpful if your operating system limits the number of characters you can enter on the command line.

#### Scope of EXEC ORACLE

An EXEC ORACLE statement stays in effect until textually superseded by another EXEC ORACLE statement specifying the same option. In the following example, HOLD_CURSOR=NO stays in effect until superseded by HOLD_CURSOR=YES:

    char emp_name[20];
    int  emp_number, dept_number;
    float salary;

    EXEC SQL WHENEVER NOT FOUND DO break;
    EXEC ORACLE OPTION (HOLD_CURSOR=NO);

    EXEC SQL DECLARE emp_cursor CURSOR FOR
    SELECT empno, deptno FROM emp;

    EXEC SQL OPEN emp_cursor;
    printf(
    "Employee Number  Department\n--------------------------\n");
    for (;;)
    {
       EXEC SQL FETCH emp_cursor INTO :emp_number, :dept_number;
       printf("%d\t%d\n", emp_number, dept_number);
    }

    EXEC SQL WHENEVER NOT FOUND CONTINUE;
    for (;;)
    {
       printf("Employee number: ");
       scanf("%d", &emp_number);
       if (emp_number == 0)
          break;
       EXEC ORACLE OPTION (HOLD_CURSOR=YES);
       EXEC SQL SELECT ename, sal
          INTO :emp_name, :salary
          FROM emp WHERE empno = :emp_number;
       printf("Salary for %s is %6.2f.\n", emp_name, salary);

## Using the Precompiler Options

This section is organized for easy reference. It lists the precompiler options alphabetically, and for each option gives its purpose, syntax, and default value. Usage notes that help you understand how the option works are also provided.

### AUTO_CONNECT

#### Purpose

Allows automatic connection to the OPS$ account.

#### Syntax

AUTO_CONNECT={YES | NO}

#### Default

NO

#### Usage Notes

Can be entered only on the command line or in a configuration file.

If AUTO_CONNECT=YES, and the application is not already connected to a database when it processes the first executable SQL statement, it attempts to connect using the userid

    OPS$<username>

where username is your current operating system user or task name and OPS$username is a valid Oracle userid.

When AUTO_CONNECT=NO, you must use the CONNECT statement in your program to connect to Oracle.

### CHAR_MAP

#### Purpose

Specifies the default mapping of C host variables of type char or char[n], and pointers to them, into SQL.

#### Syntax

CHAR_MAP={VARCHAR2 | CHARZ | STRING | CHARF}

#### Default

CHARZ

#### Usage Note

Before Oracle8, you had to declare char or char[n] host variables as CHAR, using the SQL DECLARE statement.The external datatypes VARCHAR2 and CHARZ were the default character mappings of Oracle7.

See "National Language Support" on page 4-2 for a table of CHAR_MAP settings, descriptions of the datatype, and where they are the default. An example of usage of CHAR_MAP in Pro*C/C++ is found in "Inline Usage of the CHAR_MAP Option" on page 3-51.

### CODE

#### Purpose

Specifies the format of C function prototypes generated by the Pro*C/C++ precompiler. (A function prototype declares a function and the datatypes of its arguments.) The precompiler generates function prototypes for SQL library routines, so that your C compiler can resolve external references. The CODE option lets you control the prototyping.

#### Syntax

CODE={ANSI_C|KR_C | CPP}

#### Default

KR_C

#### Usage Notes

Can be entered on the command line, but not inline.

ANSI C standard X3.159-1989 provides for function prototyping. When CODE=ANSI_C, Pro*C/C++ generates full function prototypes, which conform to the ANSI C standard. An example follows:

    extern void sqlora(long *, void *);

The precompiler can also generate other ANSI-approved constructs such as the const type qualifier.

When CODE=KR_C (the default), the precompiler Comments out the argument lists of generated function prototypes, as shown here:

    extern void sqlora(/*_ long *, void * _*/);

So, specify CODE=KR_C if your C compiler is not compliant with the X3.159 standard.

When CODE=CPP, the precompiler generates C++ compatible code.

### COMP_CHARSET

#### Purpose

Indicates to the Pro*C/C++ Precompiler whether multi-byte character sets are (or are not) supported by the compiler to be used. It is intended for use by developers working in a multi-byte client-side environment (for example, when NLS_LANG is set to a multi-byte character set).

#### Syntax

COMP_CHARSET={MULTI_BYTE|SINGLE_BYTE}

#### Default

MULTI_BYTE

#### Usage Notes

Can be entered only on the command line.

With COMP_CHARSET=MULTI_BYTE (default), Pro*C/C++ generates C code that is to be compiled by a compiler that supports multi-byte NLS character sets.

With COMP_CHARSET=SINGLE_BYTE, Pro*C/C++ generates C code for single-byte compilers that addresses a complication that may arise from the ASCII equivalent of a backslash (\) character in the second byte of a double-byte character in a multi-byte string. In this case, the backslash (\) character is "escaped" with another backslash character preceding it.

  Note: The need for this feature is common when developing in a Shift-JIS environment with older C compilers.

This option has no effect when NLS_LANG is set to a single-byte character set.

### CONFIG

#### Purpose

Specifies the name of a user configuration file.

#### Syntax

CONFIG=<filename>

#### Default

None

#### Usage Notes

Can be entered only on the command line.

This option is the only way you can inform Pro*C/C++ of the name and location of user configuration files.

### CPP_SUFFIX

#### Purpose

The CPP_SUFFIX option allows you to specify the filename extension that the precompiler appends to the C++ output file generated when the CODE=CPP option is specified.

#### Syntax

CPP_SUFFIX=<filename extension>

#### Default

System-specific.

#### Usage Notes

Most C compilers expect a default extension of ".c" for their input files. Different C++ compilers, however, can expect different filename extensions. The CPP_SUFFIX option allows you to specify the filename extension that the precompiler generates. The value of this option is a string, without the quotes or the period. For example, CPP_SUFFIX=cc, or CPP_SUFFIX=C.

### DBMS

#### Purpose

Specifies whether Oracle follows the semantic and syntactic rules of Oracle8, Oracle7, or the native version of Oracle (that is, the version to which the application is connected).

#### Syntax

DBMS={NATIVE|V7|V6_CHAR|V8}

#### Default

NATIVE

#### Usage Notes

Can be entered only on the command line, or in a configuration file.

The DBMS option lets you control the version-specific behavior of Oracle. When DBMS=NATIVE (the default), Oracle follows the semantic and syntactic rules of the database version to which the application is connected.

When DBMS=V8, or DBMS=V7, Oracle follows the respective rules for Oracle8 (which remain the same as for Oracle7). V6_CHAR is deprecated in Oracle8 and its functionality is provided by the precompiler option CHAR_MAP (which see on "CHAR_MAP" on page 9-10).

##### Table 9-2 How DBMS and MODE Interact

Situation | DBMS=V7|V8 MODE=ANSI | DBMS=V7|V8 MODE=ORACLE
"no data found" warning code | +100 | +1403
fetch nulls without using indicator variables | error -1405 | error -1405
fetch truncated values without using indicator variables | no error but SQLWARN(2) is set | no error but SQLWARN(2) is set
cursors closed by COMMIT or ROLLBACK | all explicit | CURRENT OF only
open an already OPENed cursor | error -2117 | no error
close an already CLOSEd cursor | error -2114 | no error
SQL group function ignores nulls | no warning | no warning
when SQL group function in multirow query is called | FETCH time | FETCH time
declare SQLCA structure | optional | required
declare SQLCODE or SQLSTATE status variable | required | optional but Oracle ignores
integrity constraints | enabled | enabled
PCTINCREASE for rollback segments | not allowed | not allowed
MAXEXTENTS storage parameters | not allowed | not allowed

### DEF_SQLCODE

#### Purpose

Controls whether the Pro*C/C++ precompiler generates #define's

for SQLCODE.

#### Syntax

DEF_SQLCODE={NO|YES}

#### Default

NO

#### Usage Notes

Can be used only on the command line or in a configuration file.

When DEF_SQLCODE=YES, the precompiler defines SQLCODE in the generated source code as follows:

    #define SQLCODE sqlca.sqlcode

You can then use SQLCODE to check the results of executable SQL statement. The DEF_SQLCODE option is supplied for compliance with standards that require the use of SQLCODE.

In addition, you must also include the SQLCA using one of the following entries in your source code:

    #include <sqlca.h>

or

    EXEC SQL INCLUDE SQLCA;

If the SQLCA is not included, using this option causes a precompile time error.

### DEFINE

#### Purpose

Defines a name that can be used in #ifdef and #ifndef Pro*C/C++ precompiler directives. The defined name can also be used by the EXEC ORACLE IFDEF and EXEC ORACLE IFNDEF statements.

#### Syntax

DEFINE=name

#### Default

None

#### Usage Notes

Can be entered on the command line or inline. You can only use DEFINE to define a name-you cannot define macros with it. For example, the following use of define is not valid:

    proc my_prog DEFINE=LEN=20

Using DEFINE in the correct way, you could do

    proc my_prog DEFINE=XYZZY

And then in my_prog.pc, code

    #ifdef XYZZY
    ...
    #else
    ...
    #endif

Or, you could just as well code

    EXEC ORACLE IFDEF XYZZY;
    ...
    EXEC ORACLE ELSE;
    ...
    EXEC ORACLE ENDIF;

The following example is invalid:

    #define XYZZY
    ...
    EXEC ORACLE IFDEF XYZZY
    ...
    EXEC ORACLE ENDIF;

EXEC ORACLE conditional statements are valid only if the macro is defined using EXEC ORACLE DEFINE or the DEFINE option.

If you define a name using DEFINE=, and then conditionally include (or exclude) a code section using the Pro*C/C++ precompiler #ifdef (or #ifndef) directives, you must also make sure that the name is defined when you run the C compiler. For example, for UNIX cc, you must use the -D option to define the name for the C compiler.

### DURATION

#### Purpose

Sets the pin duration used by subsequent EXEC SQL OBJECT CREATE and EXEC SQL OBJECT DEREF statements. Objects in the cache are implicitly unpinned at the end of the duration.

#### Syntax

DURATION={TRANSACTION|SESSION}

#### Default

TRANSACTION

#### Usage Notes

Can be entered inline by use of the EXEC ORACLE OPTION statement.

TRANSACTION means that objects are implicitly unpinned when the transaction completes.

SESSION means that objects are implicitly unpinned when the connection is terminated.

### ERRORS

#### Purpose

Specifies whether error messages are sent to the terminal as well as the listing file (YES), or just to the listing file (NO).

#### Syntax

ERRORS={YES|NO}

#### Default

YES

#### Usage Notes

Can be entered only on the command line, or in a configuration file.

### ERRTYPE

#### Purpose

Specifies an output file in which errors generated in processing type files are written. If omitted, errors are output to the screen. (See more about "INTYPE" on page 9-23.)

#### Syntax

ERRTYPE=<filename>

#### Default

None

#### Usage Notes

Only one error file will be produced. If multiple values are entered, the last one is used by the precompiler.

### FIPS

#### Purpose

Specifies whether extensions to ANSI SQL are flagged (by the FIPS Flagger). An extension is any SQL element that violates ANSI format or syntax rules, except privilege enforcement rules.

#### Syntax

FIPS={NONE|SQL89|SQL2|YES|NO}

#### Default

None

#### Usage Notes

Can be entered inline or on the command line.

When FIPS=YES, the FIPS Flagger is enabled, and warning (not error) messages are issued if you use an Oracle extension to ANSI SQL, or use an ANSI SQL feature in a nonconforming manner. Extensions to ANSI SQL that are flagged at precompile time include the following:

- array interface including the FOR clause
- SQLCA, ORACA, and SQLDA data structures
- dynamic SQL including the DESCRIBE statement
- embedded PL/SQL blocks
- automatic datatype conversion
- DATE, NUMBER, RAW, LONGRAW, VARRAW, ROWID, VARCHAR2, and VARCHAR datatypes
- pointer host variables
- Oracle OPTION statement for specifying runtime options
- IAF statements in user exits
- CONNECT statement
- TYPE and VAR datatype equivalencing statements
- AT <db_name> clause
- DECLARE...DATABASE, ...STATEMENT, and ...TABLE statements
- SQLWARNING condition in WHENEVER statement
- DO function_name() and DO break actions in
- WHENEVER statement
- COMMENT and FORCE TRANSACTION clauses in
- COMMIT statement
- FORCE TRANSACTION and TO SAVEPOINT clauses in ROLLBACK statement
- RELEASE parameter in COMMIT and ROLLBACK statements
- optional colon-prefixing of WHENEVER...GOTO labels, and of host variables in the INTO clause

### HOLD_CURSOR

#### Purpose

Specifies how the cursors for SQL statements and PL/SQL blocks are handled in the cursor cache.

#### Syntax

HOLD_CURSOR={YES|NO}

#### Default

NO

#### Usage Notes

Can be entered inline or on the command line.

You can use HOLD_CURSOR to improve the performance of your program. For more information, see Appendix C

When a SQL data manipulation statement is executed, its associated cursor is linked to an entry in the cursor cache. The cursor cache entry is in turn linked to an Oracle private SQL area, which stores information needed to process the statement. HOLD_CURSOR controls what happens to the link between the cursor and cursor cache.

When HOLD_CURSOR=NO, after Oracle executes the SQL statement and the cursor is closed, the precompiler marks the link as reusable. The link is reused as soon as the cursor cache entry to which it points is needed for another SQL statement. This frees memory allocated to the private SQL area and releases parse locks.

When HOLD_CURSOR=YES and RELEASE_CURSOR=NO, the link is maintained; the precompiler does not reuse it. This is useful for SQL statements that are executed often because it speeds up subsequent executions. There is no need to reparse the statement or allocate memory for an Oracle private SQL area.

For inline use with implicit cursors, set HOLD_CURSOR before executing the SQL statement. For inline use with explicit cursors, set HOLD_CURSOR before CLOSEing the cursor.

Note that RELEASE_CURSOR=YES overrides HOLD_CURSOR=YES and that HOLD_CURSOR=NO overrides RELEASE_CURSOR=NO. For information showing how these two options interact, see Table 0-2 .

### INAME

#### Purpose

Specifies the name of the input file.

#### Syntax

INAME=<path and filename>

#### Default

None

#### Usage Notes

Can be entered only on the command line.

You can omit the filename extension if it is .pc. If the input filename is the first option on the command line, you can omit the INAME= part of the option. For example:

    proc sample1 MODE=ansi

to precompile the file sample1.pc, using ANSI mode. This command is the same as

    proc INAME=sample1 MODE=ansi

### INCLUDE

#### Purpose

Specifies a directory path for files included using the #include or EXEC SQL INCLUDE directives.

#### Syntax

INCLUDE=pathname or INCLUDE=(path_1,path_2,...,path_n)

#### Default

Current directory and paths built into Pro*C/C++.

#### Usage Notes

Can be entered inline or on the command line.

You use INCLUDE to specify a directory path for included files. The precompiler searches directories in the following order:

1. the current directory
2. the system directory specified in a SYS_INCLUDE precompiler option
3. the directories specified by the INCLUDE option, in the order they are entered
4. the built-in directories for standard header files

You normally do not need to specify a directory path for Oracle-specific header files such as sqlca.h and sqlda.h.

  Note: If you specify an Oracle-specific filename without an extension for inclusion, Pro*C/C++ assumes an extension of .h. So,included files should have an extension, even if it is not .h.

  For all other header files, the precompiler does not assume a .h extension.

You must still use INCLUDE to specify directory paths for non-standard files, unless they are stored in the current directory. You can specify more than one path on the command line, as follows:

    ... INCLUDE=path_1 INCLUDE=path_2 ...

    Warning:  If the file you want to include resides in another directory, make sure that there is no file with the same name in the current directory.

The syntax for specifying a directory path using the INCLUDE option is system specific. Follow the conventions used for your operating system

### INTYPE

#### Purpose

Specifies one or more OTT-generated type files (only needed if Object types are used in the application).

#### Syntax

INTYPE=(file_1,file_2,...,file_n)

#### Default

None

#### Usage Notes

There will be one type file for each Object type in the Pro*C/C++ code.

### LINES

#### Purpose

Specifies whether the Pro*C/C++ precompiler adds #line preprocessor directives to its output file.

#### Syntax

LINES={YES|NO}

#### Default

NO

#### Usage Notes

Can be entered only on the command line.

The LINES option helps with debugging. When LINES=YES, the Pro*C/C++ precompiler adds #line preprocessor directives to its output file.

Normally, your C compiler increments its line count after each input line is processed. The #line directives force the compiler to reset its input line counter so that lines of precompiler-generated code are not counted. Moreover, when the name of the input file changes, the next #line directive specifies the new filename.

The C compiler uses the line numbers and filenames to show the location of errors. Thus, error messages issued by the C compiler always refer to your original source files, not the modified source file.

When LINES=NO (the default), the precompiler adds no #line directives to its output file.

  Note: In "Directives Ignored" on page 3-3, it is stated that the Pro*C/C++ precompiler does not support the #line directive. This means that you cannot directly code #line directives in the precompiler source. But you can still use the LINES= option to have the precompiler insert #line directives for you.

### LNAME

#### Purpose

Specifies the name of the listing file.

#### Syntax

LNAME=<filename>

#### Default

None

#### Usage Notes

Can be entered only on the command line.

The default filename extension for the listing file is .lis.

### LTYPE

#### Purpose

Specifies the type of listing file generated.

#### Syntax

LTYPE={NONE|SHORT|LONG}

#### Default

SHORT

#### Usage Notes

Can be entered on the command line or in a configuration file.

When a listing file is generated, the LONG format is the default. With LTYPE=LONG specified, all of the source code is listed as it is parsed and messages listed as they are generated. In addition, the Pro*C/C++ options currently in effect are listed.

With LTYPE=SHORT specified, only the generated messages are listed-no source code-with line references to the source file to help you locate the code that generated the message condition.

With LTYPE=NONE specified, no list file is produced unless the LNAME option explicitly specifies a name for a list file. Under the latter condition, the list file is generated with LTYPE=LONG assumed.

### MAXLITERAL

#### Purpose

Specifies the maximum length of string literals generated by the precompiler, so that compiler limits are not exceeded.

#### Syntax

MAXLITERAL=integer, range is 10 to 1024

#### Default

1024

#### Usage Notes

Cannot be entered inline.

The maximum value of MAXLITERAL is compiler dependent. For example, some C compilers cannot handle string literals longer than 512 characters, so you would specify MAXLITERAL=512.

Strings that exceed the length specified by MAXLITERAL are divided during precompilation, then recombined (concatenated) at run time.

### MAXOPENCURSORS

#### Purpose

Specifies the number of concurrently open cursors that the precompiler tries to keep cached.

#### Syntax

MAXOPENCURSORS=integer

#### Default

10

#### Usage Notes

Can be entered inline or on the command line.

You can use MAXOPENCURSORS to improve the performance of your program. For more information, see Appendix C.

When precompiling separately, use MAXOPENCURSORS as described in "Guidelines for Precompiling Separately" on page 9-40.

MAXOPENCURSORS specifies the initial size of the SQLLIB cursor cache. If a new cursor is needed, and there are no free cache entries, Oracle tries to reuse an entry. Its success depends on the values of HOLD_CURSOR and RELEASE_CURSOR, and, for explicit cursors, on the status of the cursor itself. Oracle allocates an additional cache entry if it cannot find one to reuse.

If necessary, Oracle keeps allocating additional cache entries until it runs out of memory or reaches the limit set by OPEN_CURSORS. MAXOPENCURSORS must be lower than OPEN_CURSORS by at least 6 to avoid a "maximum open cursors exceeded" Oracle error.

As your program's need for concurrently open cursors grows, you might want to respecify MAXOPENCURSORS to match the need. A value of 45 to 50 is not uncommon, but remember that each cursor requires another private SQL area in the user process memory space. The default value of 10 is adequate for most programs.

### MODE

#### Purpose

Specifies whether your program observes Oracle practices or complies with the current ANSI/ISO SQL standards.

#### Syntax

MODE={ANSI|ISO|ORACLE}

#### Default

ORACLE

#### Usage Notes

Can be entered only on the command line or in a configuration file.

ISO is a synonym for ANSI.

When MODE=ORACLE (the default), your embedded SQL program observes Oracle practices. When MODE=ANSI, your program complies fully with the ANSI SQL standard, and the following changes go into effect:

- Issuing a COMMIT or ROLLBACK closes all explicit cursors.
- You cannot OPEN an already open cursor or CLOSE an already closed cursor. (When MODE=ORACLE, you can reOPEN an open cursor to avoid reparsing.)
- You must declare a either a long variable named SQLCODE or a char SQLSTATE[6] variable (uppercase is required for both variables) that is in scope of every EXEC SQL statement. The same SQLCODE or SQLSTATE variable need not be used in each case; that is, the variable need not be global.
- Declaring the SQLCA is optional. You need not include the SQLCA.
- The "no data found" Oracle warning code returned to SQLCODE becomes +100 instead of +1403. The message text does not change.

### NLS_CHAR

#### Purpose

Specifies which C host character variables are treated by the precompiler as National Language Support (NLS) multi-byte character variables.

#### Syntax

NLS_CHAR=varname or NLS_CHAR=(var_1,var_2,...,var_n)

#### Default

None.

#### Usage Notes

Can be entered only on the command line, or in a configuration file.

This option allows you to specify at precompile time a list of the names of one or more host variables that the precompiler must treat as National Language character variables. You can specify only C char variables or Pro*C/C++ VARCHARs using this option.

If you specify in the option list a variable that is not declared in your program, then the precompiler generates no error.

### NLS_LOCAL

#### Purpose

Determines whether NLS character conversions are performed by the precompiler runtime library, SQLLIB, or by the Oracle8 Server.

#### Syntax

NLS_LOCAL={NO|YES}

#### Default

NO

#### Usage Notes

When set to YES, local multi-byte support is provided by Pro*C/C++ and the SQLLIB library. The option NLS_CHAR must be used to indicate which C host variables are multi-byte. When set to NO, Pro*C/C++ will use the Oracle8 server support for multi-byte objects. Set to NO for all new applications.

Can be entered only on the command line, or in a configuration file.

### OBJECTS

#### Purpose

Requests support for Object types in Oracle8.

#### Syntax

OBJECTS={YES | NO}

#### Default

YES

#### Usage Notes

Can only be entered in the command line.

### ONAME

#### Purpose

Specifies the name of the output file. The output file is the C code file that the precompiler generates.

#### Syntax

ONAME=<path and filename>

#### Default

INAME with an extension determined by CPP_SUFFIX.

#### Usage Notes

Can be entered only on the command line. Use this option to specify the full pathname of the output file, where the pathname differs from that of the input (.pc) file. For example, if you issue the command:

    proc iname=my_test

the default output filename is my_test.c. If you want the output filename to be my_test_1.c, issue the command

    proc iname=my_test oname=my_test_1.c

Note that you should add the .c extension to files specified using ONAME.

The default extension with the ONAME option is platform-specific, but you can override it using the CODE and CPP_SUFFIX options. When CODE=KR_C or ANSI_C, the extension is c. When CODE=CPP, you can use the CPP_SUFFIX option to override the platform-specific default.

  Attention: Oracle recommends that you not let the output filename default, but rather name it explicitly using ONAME.

### ORACA

#### Purpose

Specifies whether a program can use the Oracle Communications Area (ORACA).

#### Syntax

ORACA={YES|NO}

#### Default

NO

#### Usage Notes

Can be entered inline or on the command line.

When ORACA=YES, you must place either the EXEC SQL INCLUDE ORACA or #include oraca.h statement in your program.

### PARSE

#### Purpose

Specifies the way that the Pro*C/C++ precompiler parses the source file.

#### Syntax

PARSE={FULL|PARTIAL|NONE}

#### Default

FULL

#### Usage Notes

To generate C++ compatible code, the PARSE option must be either NONE or PARTIAL. If PARSE=FULL, the C parser is used, and it does not understand C++ constructs, such as classes, in your code.

See "Parsing Code" on page 7-4 for more information on the PARSE option.

With PARSE=FULL or PARSE=PARTIAL Pro*C/C++ fully supports C preprocessor directives, such as #define, #ifdef, and so on. However, with PARSE=NONE conditional preprocessing is supported by EXEC ORACLE statements as described in "Conditional Precompilations" on page 9-39.

Note that some platforms have the default value of PARSE as other than FULL. See your system-dependent documentation.

### RELEASE_CURSOR

#### Purpose

Specifies how the cursors for SQL statements and PL/SQL blocks are handled in the cursor cache.

#### Syntax

RELEASE_CURSOR={YES|NO}

#### Default

NO

#### Usage Notes

Can be entered inline or on the command line.

You can use RELEASE_CURSOR to improve the performance of your program. For more information, see Appendix C.

When a SQL data manipulation statement is executed, its associated cursor is linked to an entry in the cursor cache. The cursor cache entry is in turn linked to an Oracle private SQL area, which stores information needed to process the statement. RELEASE_CURSOR controls what happens to the link between the cursor cache and private SQL area.

When RELEASE_CURSOR=YES, after Oracle executes the SQL statement and the cursor is closed, the precompiler immediately removes the link. This frees memory allocated to the private SQL area and releases parse locks. To make sure that associated resources are freed when you CLOSE a cursor, you must specify RELEASE_CURSOR=YES.

When RELEASE_CURSOR=NO and HOLD_CURSOR=YES, the link is maintained. The precompiler does not reuse the link unless the number of open cursors exceeds the value of MAXOPENCURSORS. This is useful for SQL statements that are executed often because it speeds up subsequent executions. There is no need to reparse the statement or allocate memory for an Oracle private SQL area.

For inline use with implicit cursors, set RELEASE_CURSOR before executing the SQL statement. For inline use with explicit cursors, set RELEASE_CURSOR before CLOSEing the cursor.

Note that RELEASE_CURSOR=YES overrides HOLD_CURSOR=YES and that HOLD_CURSOR=NO overrides RELEASE_CURSOR=NO. For a table showing how these two options interact, see Appendix C.

### SELECT_ERROR

#### Purpose

Specifies whether your program generates an error when a SELECT statement returns more than one row, or more rows than a host array can accommodate.

#### Syntax

SELECT_ERROR={YES|NO}

#### Default

YES

#### Usage Notes

Can be entered inline or on the command line.

When SELECT_ERROR=YES, an error is generated when a single-row SELECT returns too many rows, or when an array SELECT returns more rows than the host array can accommodate. The result of the SELECT is indeterminate.

When SELECT_ERROR=NO, no error is generated when a single-row SELECT returns too many rows, or when an array SELECT returns more rows than the host array can accommodate.

Whether you specify YES or NO, a random row is selected from the table. The only way to ensure a specific ordering of rows is to use the ORDER BY clause in your SELECT statement. When SELECT_ERROR=NO and you use ORDER BY, Oracle returns the first row, or the first n rows when you are SELECTing into an array. When SELECT_ERROR=YES, whether or not you use ORDER BY, an error is generated when too many rows are returned.

### SQLCHECK

#### Purpose

Specifies the type and extent of syntactic and semantic checking.

#### Syntax

SQLCHECK={SEMANTICS|FULL|SYNTAX

#### Default

SYNTAX

#### Usage Notes

Can be entered inline or the command line.

The Pro*C/C++ precompiler can help you debug a program by checking the syntax and semantics of embedded SQL statements and PL/SQL blocks. You control the level of checking by entering the SQLCHECK option inline and/or on the command line. However, the level of checking you specify inline cannot be higher than the level you specify (or accept by default) on the command line. For example, if you specify SQLCHECK=SYNTAX on the command line, you cannot specify SQLCHECK=SEMANTICS inline.

##### SQLCHECK=SEMANTICS|FULL

The precompiler checks the syntax and semantics of

- data manipulation statements such as INSERT and UPDATE
- PL/SQL blocks
- host variable datatypes

However, only syntactic checking is done on data manipulation statements or PL/SQL blocks that use the AT db_name clause. No syntax or semantics checking is performed on DDL statements, such as CREATE and ALTER.

Any errors found are reported at precompile time.

The precompiler gets information needed for a semantic check by using embedded DECLARE TABLE statements, or if you specify the USERID option on the command line, by connecting to Oracle and accessing the data dictionary. You need not connect to Oracle if every table referenced in a data manipulation statement or PL/SQL block is defined in a DECLARE TABLE statement.

If you connect to Oracle, but some needed information cannot be found in the data dictionary, you must use DECLARE TABLE statements to supply the missing information. A DECLARE TABLE definition overrides a data dictionary definition if they conflict.

If you embed PL/SQL blocks in a host program, you must specify SQLCHECK=SEMANTICS and the USERID option as well.

##### SQLCHECK=SYNTAX

The precompiler checks the syntax of

- declarative SQL statements (such as EXEC SQL WHENEVER...)
- Data Manipulation Language statements
- host variables and host variable datatypes

and any errors found are reported at precompile time.

But no semantic checking is done. DECLARE TABLE statements are ignored, and PL/SQL blocks are not allowed.

Specifying the SYNTAX value generates a usable output (code) file, however semantic errors can still occur at runtime.

See Appendix D, "Syntactic and Semantic Checking" for more information.

### SYS_INCLUDE

#### Purpose

Specifies the location of system header files.

#### Syntax

SYS_INCLUDE=<pathname>

#### Default

System-specific.

#### Usage Notes

Pro*C/C++ searches for standard system header files, such as stdio.h, in standard locations that are platform specific. For example, on almost all UNIX systems, the file stdio.h has the full pathname /usr/include/stdio.h.

But C++ compilers can have system header files, such as stdio.h, that are not in the standard system locations. You can use the SYS_INCLUDE command line option to specify a list of directory paths that Pro*C/C++ searches to look for system header files. For example:

    SYS_INCLUDE=(/usr/lang/SC2.0.1/include,/usr/lang/SC2.1.1/include)

The search path that you specify using SYS_INCLUDE overrides the default header location

If PARSE=NONE, the value specified in SYS_INCLUDE is irrelevant for the precompilation, since there is no need for Pro*C/C++ to include system header files in the precompilation. (You must, of course, still include Oracle-specific headers, such as sqlca.h. and system header files, with #include directives for pre-processing by the compiler.)

The precompiler searches directories in the following order:

1. the current directory
2. the system directory specified in the SYS_INCLUDE precompiler option
3. the directories specified by the INCLUDE option, in the order entered
4. the built-in directory for standard header files

Because of step 3, you normally do not need to specify a directory path for standard header files such as sqlca.h and sqlda.h.

### THREADS

#### Purpose

When THREADS=YES, the precompiler searches for context declarations.

#### Syntax

THREADS={YES|NO}

#### Default

NO

#### Usage Notes

Cannot be entered inline.

This precompiler option is required for any program that requires multi-threaded support.

With THREADS=YES, the precompiler generates an error if no EXEC SQL CONTEXT USE directive is encountered before the first context is visible and an executable SQL statement is found. For more information, see "Developing Multi-threaded Applications" on page 4-37.

### UNSAFE_NULL

#### Purpose

Specifying UNSAFE_NULL=YES prevents generation of ORA-01405 messages when fetching NULLs without using indicator variables.

#### Syntax

UNSAFE_NULL={YES|NO}

#### Default

NO

#### Usage Notes

Cannot be entered inline.

The UNSAFE_NULL=YES is allowed only when MODE=ORACLE and DBMS=V7 or V6_CHAR.

The UNSAFE_NULL option has no effect on host variables in an embedded PL/SQL block. You must use indicator variables to avoid ORA-01405 errors.

### USERID

#### Purpose

Specifies an Oracle username and password.

#### Syntax

USERID=username/password

#### Default

None

#### Usage Notes

Can be entered only on the command line.

Do not specify this option when using the automatic connect feature, which accepts your Oracle username prefixed with OPS$. The actual value of the "OPS$" string is set as a parameter in the INIT.ORA file.

When SQLCHECK=SEMANTICS, if you want the precompiler to get needed information by connecting to Oracle and accessing the data dictionary, you must also specify USERID.

### VARCHAR

#### Purpose

Instructs the Pro*C/C++ precompiler to interpret some structs as VARCHAR host variables.

#### Syntax

VARCHAR={NO|YES}

#### Default

NO

#### Usage Notes

Can be entered only on the command line.

When VARCHAR=YES, a C struct that you code as

    struct {
        short <len>;
        char  <arr>[n];
    } name;

is interpreted by the precompiler as a VARCHAR[n] host variable.

### VERSION

#### Purpose

Determines which version of the object will be returned by the EXEC SQL OBJECT DEREF statement.

#### Syntax

VERSION={RECENT|LATEST|ANY}

#### Default

RECENT

#### Usage Notes

Can be entered inline by use of the EXEC ORACLE OPTION statement.

RECENT means that if the object has been selected into the object cache in the current transaction, then that object is returned. For transactions running in serializable mode, this option has the same effect as LATEST without incurring as many network roundtrips. Most applications should use RECENT.

LATEST means that if the object does not reside in the object cache, it is retrieved from the database. If It does reside in the object cache, it is refreshed from the server. Use LATEST with caution because it incurs the greatest number of network roundtrips. Use LATEST only when it is imperative that the object cache is kept as coherent as possible with the server buffer cache

ANY means that if the object already resides in the object cache, return that object. If not, retrieve the object from the server. ANY incurs the fewest network roundtrips. Use in applications that access read-only objects or when a user will have exclusive access to the objects.

## Conditional Precompilations

Conditional precompilation includes (or excludes) sections of code in your C program based on certain conditions. For example, you might want to include one section of code when precompiling under UNIX and another when precompiling under VMS. Conditional precompiling lets you write programs that can run in different environments.

Conditional sections of code are marked by statements that define the environment and actions to take. You can code C statements as well as EXEC SQL statements in these sections. The following statements let you exercise conditional control over precompilation:

    EXEC ORACLE DEFINE symbol;    -- define a symbol
    EXEC ORACLE IFDEF symbol;     -- if symbol is defined
    EXEC ORACLE IFNDEF symbol;    -- if symbol is not defined
    EXEC ORACLE ELSE;             -- otherwise
    EXEC ORACLE ENDIF;            -- end this control block

All EXEC ORACLE statements must be terminated with a semi-colon.

### Defining Symbols

You can define a symbol in two ways. Either include the statement

    EXEC ORACLE DEFINE symbol;

in your host program or define the symbol on the command line using the syntax

    ... INAME=filename ... DEFINE=symbol

where symbol is not case-sensitive.

  Warning: The #define preprocesssor directive is not the same as the EXEC ORACLE DEFINE command

Some port-specific symbols are predefined for you when the Pro*C/C++ precompiler is installed on your system. For example, predefined operating system symbols include CMS, MVS, MS-DOS, UNIX, and VMS.

### An Example

In the following example, the SELECT statement is precompiled only when the symbol site2 is defined:

    EXEC ORACLE IFDEF site2;
        EXEC SQL SELECT DNAME
            INTO :dept_name
            FROM DEPT
            WHERE DEPTNO = :dept_number;
    EXEC ORACLE ENDIF;

Blocks of conditions can be nested as shown in the following example:

    EXEC ORACLE IFDEF outer;
        EXEC ORACLE IFDEF inner;
        ...
        EXEC ORACLE ENDIF;
    EXEC ORACLE ENDIF;

You can "Comment out" C or embedded SQL code by placing it between IFDEF and ENDIF and not defining the symbol.

## Guidelines for Precompiling Separately

The following guidelines will help you avoid some common problems.

#### Referencing Cursors

Cursor names are SQL identifiers, whose scope is the precompilation unit. Hence, cursor operations cannot span precompilation units (files). That is, you cannot DECLARE a cursor in one file, and OPEN or FETCH from it in another file. So, when doing a separate precompilation, make sure all definitions and references to a given cursor are in one file.

#### Specifying MAXOPENCURSORS

When you precompile the program module that CONNECTs to Oracle, specify a value for MAXOPENCURSORS that is high enough for any of the program modules. If you use MAXOPENCURSORS for another program module, one that does not do a CONNECT, then that value for MAXOPENCURSORS is ignored. Only the value in effect for the CONNECT is used at run time.

#### Using a Single SQLCA

If you want to use just one SQLCA, you must declare it as global in one of the program modules and as external in the other modules. Use the extern storage class, and the following define in your code:

    #define SQLCA_STORAGE_CLASS extern

which tells the precompiler to look for the SQLCA in another program module. Unless you declare the SQLCA as external, each program module uses its own local SQLCA.

Note: All source files in an application must be uniquely named.

## Compiling and Linking

To get an executable program, you must compile the output .c source files produced by the precompiler, then link the resulting object modules with modules needed from SQLLIB and system-specific Oracle libraries. If you are mixing precompiler code and OCI calls, be sure to also link in the OCI runtime library (liboci.a on UNIX systems).

The linker resolves symbolic references in the object modules. If these references conflict, the link fails. This can happen when you try to link third-party software into a precompiled program. Not all third-party software is compatible with Oracle. So, linking your program shared might cause an obscure problem. In some cases, linking stand-alone or two-task might solve the problem.

Compiling and linking are system dependent. On most platforms, example makefiles or batch files are supplied that you can use to precompile, compile, and link a Pro*C/C++ application. See your system-specific Oracle documentation.

Prev | Next
| Copyright © 1997 Oracle Corporation. All Rights Reserved. |
Library | Product | Contents | Index