|Pro*PL/I Supplement to the Oracle Precompilers Guide
Part Number A87540-01
This chapter provides the basic information you need to invoke the Pro*PL/I Precompiler.
To run the Pro*PL/I Precompiler, you issue the following command:
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
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
is equivalent to
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.
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:
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
the value is a string literal that specifies a filename. But for the option
the value is numeric.
Some options take Boolean values, and you can represent these with the strings yes or no. For example, the option
The option value is always separated from the option name by an equals sign, with no whitespace around the equals sign.
Many of the options have default values. The default value of an option is determined by:
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.
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
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
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
prints the current default value for the MAXOPENCURSORS option.
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.
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
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.
Note: You cannot nest configuration files. This means that CONFIG= is not a valid option inside a configuration file.
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.
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).
DBMS=NATIVE | V6 | V7
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:
If you precompile using the DBMS=V6 option, and connect to an Oracle7 database, then a Data Definition Language statement such as
creates the table using the VARCHAR2 (variable-length) datatype, as if the CREATE TABLE statement had been
Specifies whether your program observes Oracle practices or complies with the current ANSI/ISO SQL standards.
MODE=ANSI | ANSI13 | ANSI14 |ISO | ORACLE
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:
All the precompiler options can be entered on the command line; some can also be entered inline (within the source file).
Separate each option with one or more spaces.
For example, you might enter
You enter options inline by coding EXEC Oracle statements, using the following syntax:
For example, you might code
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.
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:
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.
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.
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.
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.