3 Running the Pro*PL/1 Precompiler

Default Values

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

• a value built in to the precompiler

• a value set in the Pro*PL/1 system configuration file

• a value set in a Pro*PL/1 user configuration file

• a value set in an inline specification

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. Then, 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. For more information see the section "Configuration Files" on page "Configuration Files".

Some options, such as USERID, do not have a precompiler default. For more information, see the Oracle Database Programmer's Guide to the Oracle Precompilers.

propli ?

propli CONFIG=my_config_file.cfg ?

propli MAXOPENCURSORS=?

Case Sensitivity

In general, you can use either uppercase or lowercase for command-line 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*PL/1 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 one option, with its associated value or values. For example, a configuration file might 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 system. The name of the system configuration file is pccpli.cfg.. The location of the file is operating system specific. On most UNIX systems, the file specification is usually located in $ORACLE_HOME/propli/pccpli.cfg.

Each Pro*PL/1 user can have one or more user configuration files. The name of the configuration file must be specified using the CONFIG= command-line option.

Scope of Options

The options specified when you precompile a given Pro*PL/1 source file affect only the code generated from that file; they have no effect on other modules that may be linked in to form the final program. For example, if you specify MAXLITERAL for file A but not for file B, SQL statements in file A run with the specified MAXLITERAL value, but SQL statements in file B run with the default value.

There is one exception to this rule: the MAXOPENCURSORS value that is in effect when a connection to a database is made, stays in effect for the life of that connection.

An option setting stays in effect until the end-of-file unless you respecify the option. For more information on other options, see the Oracle Database Programmer's Guide to the Oracle Precompilers.

DBMS

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

Syntax

DBMS=NATIVE | V6 | V7

Default

NATIVE

Usage Notes

Can be entered only on the command line.

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=V6, or DBMS=V7, Oracle follows the rules of Oracle Version 6 or Oracle database version 7, respectively. A summary of the differences between DBMS=V6 and DBMS=V7 follows:

• When DBMS=V6, Oracle treats string literals like variable-length character values. However, when DBMS=V7, Oracle treats string literals like fixed-length character values, and CHAR semantics change slightly to comply with the current SQL standard.

• When DBMS=V6, Oracle treats local CHAR variables in a PL/SQL block like variable-length character values. When DBMS=V7, however, Oracle treats the CHAR variables like SQL standard, fixed-length character values.

• When DBMS=V6, Oracle treats the return value of the function USER like a variable-length character value. However, when DBMS=V7, Oracle treats the return value of USER like a SQL standard, fixed-length character value.

• When DBMS=V6, if you process a multirow query that calls a SQL group function such as AVG or COUNT, the function is called at OPEN time. When DBMS=V7, however, the function is called at FETCH time. At OPEN time or FETCH time, if the function call fails, Oracle issues an error message immediately. Thus, the DBMS value affects error reporting slightly.

• When DBMS=V6, no error is returned if a SELECT or FETCH statement selects a null, and there is no indicator variable associated with the output host variable. When DBMS=V7, SELECTing or FETCHing a null column or expression into a host variable that has no associated indicator variable causes an error (SQLSTATE is "22002"; SQLCODE is -01405).

• When DBMS=V6, a DESCRIBE operation of a fixed-length string (in Dynamic SQL Method 4) returns datatype code 1. When DBMS=V7, the DESCRIBE operation returns datatype code 96.

• When DBMS=V6, PCTINCREASE is allowed for rollback segments. When DBMS=V7, PCTINCREASE is not allowed for rollback segments.

• When DBMS=V6, illegal MAXEXTENTS storage parameters are allowed. They are not allowed when DBMS=V7.

• When DBMS=V6, constraints (except NOT NULL) are not enabled. When DBMS=V7, all Oracle database version 7 constraints are enabled.

If you precompile using the DBMS=V6 option, and connect to an Oracle database version 7 database, then a data definition language statement such as

CREATE TABLE T1 (COL1 CHAR(10)) 

creates the table using the VARCHAR2 (variable-length) datatype, as if the CREATE TABLE statement had been

CREATE TABLE T1 (COL1 VARCHAR2(10)) 

MODE

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

Syntax

MODE=ANSI | ANSI13 | ANSI14 |ISO | ORACLE

Default

ORACLE

Usage Notes

Can be entered only on the command line.

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 standard, and the following changes go into effect:

• CHAR column values, USER pseudocolumn values, character host values, and quoted literals are treated like ANSI fixed-length character strings. And, ANSI-compliant blank-padding semantics are used when you assign, compare, INSERT, UPDATE, SELECT, or FETCH such values.

• 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 cannot SELECT or FETCH nulls into a host variable not associated with an indicator variable.

• If you declare SQLSTATE, then you must declare SQLSTATE as DCL SQLSTATE CHAR(5);.

• Declaring the SQLCA is optional. You need not include the SQLCA.

• No error message is issued if Oracle assigns a truncated column value to an output host variable.

• The "no data found" Oracle error code returned to SQLCODE becomes +100 instead of +1403. The error message text does not change.

Entering Options

All the precompiler options can be entered on the command line; some can also be entered inline (within the source file).

... [option_name=value] [option_name=value] ...

Separate each option with one or more spaces.

For example, you might enter

... ERRORS=yes LTYPE=long MODE=ANSI13

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

EXEC Oracle OPTION (option_name=value);

For example, you might code

EXEC Oracle OPTION (AREASIZE=4); 

An option entered inline overrides the same option entered on the command line. The scope of an inline option is positional, not logical. ("Positional" means that it takes effect for all statements that follow it in the source file, regardless of the flow of control of the program logic.)

An inline option setting stays in effect until overridden by another EXEC Oracle OPTION directive that sets the same option name.

Special PL/1 Options

The Pro*PL/1 Precompiler supports LMARGIN and RMARGIN controls that enable you to specify the left and right margins of the input source file. Using these controls makes it possible to support the card image format required by some compilers.

By default, the left and right margins on all IBM systems are set to 2 and 72 respectively. On all non-IBM systems, the default setting for the left margin is 1, and the default setting for the right margin is the record length of the input file. To change these defaults (to 5 and 75, for example), specify LMARGIN and RMARGIN on the command line as follows:

LMARGIN=5 RMARGIN=75

Restrictions

All references to an explicit cursor must be in the same program file. You cannot perform operations on a cursor that was declared in a different module. See the Oracle Database Programmer's Guide to the Oracle Precompilers, Chapter 4, for more information about cursors.

Also, any program file that contains SQL statements must have a SQLCA that is in the scope of the local SQL statements.