3
Running the Pro*PL/I Precompiler

This chapter provides the basic information you need to invoke the Pro*PL/I Precompiler.

Precompiler Command

To run the Pro*PL/I Precompiler, you issue the following command:

propli

The location of the precompiler differs from system to system. The system or database administrator defines environment variables, logicals, or aliases, or uses other operating-system-specific means to make the Pro*PL/I executable accessible.

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

propli INAME=test_propli

precompiles the file test_propli.ppl in the current directory, since the precompiler assumes that the filename extension is .ppl. You need not use the use a file extension when specifying INAME unless the extension is nonstandard. The INAME options 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

propli myfile

is equivalent to

propli INAME=myfile

Note: Option names, and option values that do not name specific operating-system 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. Filenames, including the name of the Pro*PL/I Precompiler executable itself always follow the case conventions used by your operating system.

Precompiler Options

Many useful options are available at precompile time. They let you control how resources are used, how errors are reported, how input and output are formatted, and how cursors are managed. To specify a precompiler option, you use the following syntax:

option_name=value

See Chapter 11 of the Programmer's Guide to the Oracle Precompilers for a list of precompiler options. The list gives the purpose, syntax, default value, and usage notes for each option.

A handy reference to the precompiler options is available online. To see the online display, enter the precompiler command with no arguments at your operating system prompt. The display gives the name, syntax, default value, and purpose of each option. Options marked with an asterisk (*) can be specified inline as well as on the command line.

The value of an option is a string literal, which can 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=20

the value is numeric.

Some options take Boolean values, and you can represent these with the strings yes or no. For example, the option

... SELECT_ERROR=YES

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 default value of an option is determined by:

• a value built in to the precompiler
• a value set in the Pro*PL/I system configuration file
• a value set in a Pro*PL/I 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 Programmer's Guide to the Oracle Precompilers.

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

propli ?

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

propli CONFIG=my_config_file.cfg ?

and there is a file named my_config_file.cfg in the current director, the options are listed. Values in the user configuration file supply missing values, and supersede values built-in to the Pro*PL/I precompiler, or values specified in the system configuration file.

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

propli MAXOPENCURSORS=?

prints the current default value for the MAXOPENCURSORS option.

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/I 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/I 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/I 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 Programmer's Guide to the Oracle Precompilers.

DBMS

Purpose

Specifies whether Oracle follows the semantic and syntactic rules of Oracle Version 6, Oracle7, 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 Oracle7, 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 Oracle7 constraints are enabled.

If you precompile using the DBMS=V6 option, and connect to an Oracle7 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

Purpose

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/I Options

The Pro*PL/I Precompiler supports LMARGIN and RMARGIN controls that allow 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

Doing Conditional Precompilations

Conditional precompilation includes (or excludes) sections of code in your Pro*PL/I program based on certain conditions. For example, you may want to include one section of code when precompiling under the VM operating system and another section when precompiling under VMS. Conditional precompilation lets you write programs that can run in different environments. For more information, see Chapter 11 of the Programmer's Guide to the Oracle Precompilers.

Doing Separate Precompilations

With the Pro*PL/I Precompiler you can precompile several program files separately, then link them into one executable program. This allows modular programming--required when the functional components of a program are written and debugged by different programmers.

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

Compiling and Linking

To produce an executable program, you must compile the PL/I output files produced by the precompiler, then link the resulting object modules with the Oracle runtime library, SQLLIB.

Compiling and linking are system dependent. For instructions, see the Oracle installation or user's guide for your system.