Pro*COBOL Precompiler Programmer's Guide
Release 8.0

A58232-01

Library

Product

Contents

Index

Prev Next

7
Running the Pro*COBOL Precompiler

This chapter details the requirements for running the Pro*COBOL. You learn

The Pro*COBOL Command

To run the Oracle Pro*COBOL Precompiler, you issue the command

procob

The location of Pro*COBOL differs from system to system. Typically, your system manager or DBA defines environment variables, logicals, or aliases or uses other operating system-specific means to make the Pro*COBOL executable accessible.

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

procob INAME=test

precompiles the file test.pco in the current directory, since Pro*COBOL assumes that the filename extension is.pco. You need not use a file extension when specifying INAME unless the extension is nonstandard.

Input and output filenames need not be accompanied by their respective option names, INAME and ONAME. When the option names are not specified, Pro*COBOL assumes that the first filename specified on the command line is the input filename and that the second filename is the output filename.

Thus, the command

procob MODE=ANSI myfile.pco myfile.cob

is equivalent to

procob MODE=ANSI INAME=myfile.pco ONAME=myfile.cob



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*COBOL executable itself, always follow the case conventions used by the operating system on which it is executed.

What Occurs during Precompilation?

During precompilation, Pro*COBOL generates COBOL code that replaces the SQL statements embedded in your host program. The generated code includes data structures that contain the datatype, length, and address of each host variable, 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: Pro*COBOL does not generate calls to Oracle Call Interface (OCI) routines.

Pro*COBOL can issue warnings and error messages. These messages have the prefix PCC-, and are described in Oracle8 Error Messages.

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, use the following syntax:

<option_name>=<value>

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

The option value is always separated from the option name by an equal sign, leave no whitespace around the equal sign, because spaces delimit individual options. For example, you might specify the option AUTO_CONNECT on the command line as follows:

... AUTO_CONNECT=YES

You can abbreviate the names of options if the abbreviation is unambiguous. For example, you cannot use the abbreviation MAX because it might stand for MAXLITERAL or MAXOPENCURSORS.

A handy reference to the Pro*COBOL options is available online. To see the online display, enter the Pro*COBOL command, with no arguments, at your operating system prompt:

procob

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.

Precedence of Option Values

Option values are determined by the following, in order of increasing precedence:

For example, the option MAXOPENCURSORS specifies the maximum number of cached open cursors. The built-in Pro*COBOL default value for this option is 10. However, if MAXOPENCURSORS=32 is specified in the system configuration file, the value 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. Finally, an inline specification takes precedence over all preceding defaults. For more information, see "Configuration Files" on page 7-6 and "Entering Options" on page 7-7.

Macro and Micro Options

Pro*COBOL has two options, DBMS and MODE, that existed before release 8.0, and that also control several functions at once. These are known as macro options. Some newer options, such as END_OF_FETCH, control only one function and are known as micro options. When setting a macro and a micro option, you must remember that macro options have precedence over micro options, if, and only if, the macro option is at a higher level of precedence than the micro option, as listed in the section "Precedence of Option Values" on page 7-4. This behavior is a change from releases of Pro*COBOL prior to 8.0.

For example, the default for MODE is ORACLE, and for END_OF_FETCH is 1403. If you specify MODE=ANSI in the user configuration file, Pro*COBOL will return a value of 100 at the end of fetch, overriding the default END_OF_FETCH value of 1403. If you specify both MODE=ANSI and END_OF_FETCH=1403 in the configuration file, then 1403 will be returned. If you specify MODE=ANSI in your configuration file and END_OF_FETCH=1403 on the command line, 1403 will be returned.

The following table lists the values of micro options set by the macro option values:

Macro Option   Micro Option  

MODE=ANSI | ISO

 

CLOSE_ON_COMMIT=YES

DECLARE_SECTION=YES

END_OF_FETCH=100

 

MODE=ANSI14 | ANSI13 | ISO14 | ISO13

 

CLOSE_ON_COMMIT=NO

DECLARE_SECTION=YES

END_OF_FETCH=100

 

MODE=ORACLE

 

CLOSE_ON_COMMIT=NO

DECLARE_SECTION=NO

END_OF_FETCH=1403

 

DBMS=V6

 

UNSAFE_NULL=YES

 

DBMS=NATIVE | V7 | V8

 

UNSAFE_NULL=NO

 

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

procob?

the complete option set, along with current values, is displayed on your terminal. In this case, the values are those built into Pro*COBOL, overridden by any values in the system configuration file. But if you issue the following command

procob CONFIG=my_config_file.cfg?

and there is a file named my_config_file.cfg in the current directory, the options from the my_config_file.cfg file are listed with the other default values. Values in the user configuration file supply missing values, and they supersede values built into Pro*COBOL and values specified in the system configuration file.

You can also determine the current value of a single option by simply specifying the option name followed by "=?" as in

procob MAXOPENCURSORS=?



Note: With some operating systems and user shells, such as UNIX C shell, the "?" may need to be preceded by an "escape" character, such as a back-slash (\). For example, instead of "procob?," you might need to use "procob \?" to list the Pro*COBOL option settings.

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, (UNIX for example) you must specify filename values, including the name of Pro*COBOL 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

to set values for the FIPS and MODE options.

There is a single system configuration file for each system. The name of the system configuration file is

pcbcfg.cfg

The location of the file is operating system-specific. On most UNIX systems, the Pro*COBOL configuration file is usually located in the $ORACLE_HOME/precomp/admin directory, where $ORACLE_HOME is the environment variable for the database software.

Note that before release 8.0 of Pro*COBOL, the configuration file was called pccob.cfg.

The Pro*COBOL user can have one or more user configuration files. The name of the configuration file must be specified using the CONFIG command-line option. For more information, see "Determining Current Values" on page 7-5.

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

Entering Options

All Pro*COBOL options can be entered on the command line or (except CONFIG) from a configuration file. Many options can also be entered inline. During a given run, Pro*COBOL can accept options from all three sources.

On the Command Line

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

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

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

... ERRORS=no LTYPE=short 

Inline

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

     EXEC ORACLE OPTION (option_name=value) END-EXEC. 

For example, you might code the following statement:

     EXEC ORACLE OPTION (RELEASE_CURSOR=YES) END-EXEC. 

An option entered inline overrides the same option entered on the command line.

Advantages

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

Specifying options inline is also helpful if your operating system limits the number of characters you can enter on the command line, and you can store inline options in configuration files, which are discussed in the next section.

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:

     EXEC SQL BEGIN DECLARE SECTION END-EXEC. 
         01 EMP-NAME    PIC X(20) VARYING.
         01 EMP-NUMBER  PIC S9(4) COMP VALUE ZERO.
         01 SALARY      PIC S9(5)V99 COMP-3 VALUE ZERO.
         01 DEPT-NUMBER PIC S9(4) COMP VALUE ZERO.
     EXEC SQL END DECLARE SECTION END-EXEC. 
     ... 
     EXEC SQL WHENEVER NOT FOUND GOTO NO-MORE END-EXEC. 
     ...
     EXEC ORACLE OPTION (HOLD_CURSOR=NO)END-EXEC. 
     ...
     EXEC SQL DECLARE EMP-CURSOR CURSOR FOR 
        SELECT EMPNO, DEPTNO FROM EMP 
     END-EXEC.
     EXEC SQL OPEN EMP-CURSOR END-EXEC.
  
     DISPLAY 'Employee Number  Dept'.
     DISPLAY '---------------  ----'.
     PERFORM
         EXEC SQL
           FETCH EMP-CURSOR INTO :EMP-NUMBER, :DEPT-NUMBER
         END-EXEC 
         DISPLAY EMP-NUMBER, DEPT-NUMBER END-EXEC
     END-PERFORM. 

 NO-MORE.
         EXEC SQL WHENEVER NOT FOUND CONTINUE END-EXEC. 
     PERFORM
         DISPLAY 'Employee number? ' 
         ACCEPT EMP-NUMBER 
         IF EMP-NUMBER IS NOT = 0 
             EXEC ORACLE OPTION (HOLD_CURSOR=YES) END-EXEC 
             EXEC SQL SELECT ENAME, SAL 
                 INTO :EMP-NAME, :SALARY 
                 FROM EMP 
                 WHERE EMPNO = :EMP-NUMBER 
                 DISPLAY 'Salary for ', EMP-NAME, ' is ', SALARY
             END-EXEC 
         END-IF
     END-PERFORM. 
 NEXT-PARA.
     ... 

Scope of Options

A precompilation unit is a file containing COBOL 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 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. However, the MAXOPENCURSORS setting that is in effect when you connect to Oracle stays in effect for the life of that connection.

The scope of an inline option is positional, not logical. That is, an inline option affects SQL statements that follow it in the source file, not in the flow of program logic. An option setting stays in effect until the end-of-file unless you re-specify the option.

Quick Reference

Table 7-2 is a quick reference to the Pro*COBOL options. Options marked with an asterisk can be entered inline.

Another handy reference is available online. To see the online display, just enter the Pro*COBOL command without options at your operating system prompt. The display gives the name, syntax, default value, and purpose of each option.

Note: There are some platform-specific options. For example, on byte-swapped platforms the option COMP5 governs the use of certain COMPUTATIONAL items. Check your system-specific Oracle manuals.

Table 7-2 Option List
Syntax   Default   Specifies ...  

ASACC={YES|NO}

 

NO

 

If YES, use ASA carriage control for listing

 

ASSUME_SQLCODE={YES|NO}

 

NO

 

If YES, assume SQLCODE variable exists

 

AUTO_CONNECT={YES|NO}

 

NO

 

If YES, allow automatic connect to ops$ accounts

 

CLOSE_ON_COMMIT

 

NO

 

If YES, close all cursors on COMMIT

 

CONFIG=filename

 

 

Specifies name of user-defined configuration file

 

DATE_FORMAT

 

LOCAL

 

Specifies date string format

 

DBMS={NATIVE|V7|V8}

 

NATIVE

 

Version-specific behavior of Oracle at precompile time

 

DECLARE_SECTION

 

NO

 

If YES, DECLARE SECTION is required.

 

DEFINE=symbol *

 

 

Define a symbol used in conditional precompilation

 

END_OF_FETCH

 

1403

 

End-of-fetch SQLCODE value

 

ERRORS={YES|NO} *

 

YES

 

If YES, display errors on the terminal

 

FIPS={YES|NO}

 

NO

 

If YES, ANSI/ISO extensions are flagged

 

FORMAT={ANSI|TERMINAL}

 

ANSI

 

Format of input file COBOL statements

 

HOLD_CURSOR={YES|NO}*

 

NO

 

If YES, hold OraCursor (do not re-assign)

 

HOST={COBOL|COB74}

 

COBOL

 

COBOL version used in input file (COBOL 85 or COBOL 74)

 

[INAME=]filename

 

 

Name of input file

 

INCLUDE=path*

 

 

Pathname for EXEC SQL INCLUDE files

 

IRECLEN=integer

 

80

 

Record length of input file

 

LITDELIM={APOST|QUOTE}

 

QUOTE

 

Delimiters for COBOL strings

 

LNAME=filename

 

 

Name of listing file

 

LRECLEN=integer

 

132

 

Record length of listing file

 

LTYPE={LONG|SHORT|NONE} *

 

LONG

 

Type of listing

 

MAXLITERAL=integer *

 

platform-specific

 

Maximum length of strings

 

MAXOPENCURSORS=integer *

 

10

 

Maximum number of OraCursors cached (1)

 

MODE={ORACLE|ANSI|ANSI14|ANSI13}

 

ORACLE

 

If ANSI, follow the ANSI/ISO SQL standard

 

NLS_LOCAL={YES|NO}

 

NO

 

If YES, use NCHAR semantics of previous Pro*COBOL releases

 

[ONAME=]filename

 

 

Name of output file

 

ORACA={YES|NO}*

 

NO

 

If YES, use ORACA communications area

 

ORECLEN=integer

 

80

 

Record length of output file

 

PAGELEN=integer

 

66

 

Lines per page in listing

 

PICX

 

CHARF

 

Datatype of PIC X COBOL variables

 

RELEASE_CURSOR={YES|NO} *

 

NO

 

If YES, release OraCursor after execute

 

SELECT_ERROR={YES|NO}*

 

YES

 

If YES, generate FOUND error on SELECT

 

SQLCHECK={FULL|SYNTAX|LIMITED|NONE}*

 

SYNTAX

 

SQL checking level

 

UNSAFE_NULL={YES|NO}

 

NO

 

If YES, unsafe null fetches are allowed (disables the ORA-01405 message)

 

USERID=username/password

 

 

Oracle username and password

 

VARCHAR={YES|NO}

 

NO

 

If YES, accept user-defined VARCHAR group items

 

XREF={YES|NO}*

 

YES

 

If YES, generate symbol cross references in listing

 

Using Pro*COBOL Options

This section is organized for easy reference. It lists Pro*COBOL 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. Unless the usage notes say otherwise, the option can be entered on the command line, inline, or from a configuration file.

ASACC

Purpose

Specifies whether the listing file follows the ASA convention of using the first column in each line for carriage control.

Syntax

ASACC={YES|NO}

Default

NO

Usage Notes

Cannot be entered inline.

ASSUME_SQLCODE

Purpose

Instructs Pro*COBOL to presume that SQLCODE is declared whether or not it is declared in the program, or of the proper type.

Syntax

ASSUME_SQLCODE={YES|NO}

Default

NO

Usage Notes

Cannot be entered inline.

When DECLARE_SECTION=YES and ASSUME_SQLCODE=YES, SQLCODE can be declared outside a Declare Section.

When DECLARE_SECTION=YES and ASSUME_SQLCODE=NO, SQLCODE is recognized as the status variable if and only if at least one of the following criteria is satisfied:

When ASSUME_SQLCODE=YES,and when SQLSTATE and/or SQLCA are declared as status variables, Pro*COBOL presumes SQLCODE is declared whether or not it is declared or of the proper type.

AUTO_CONNECT

Purpose

Specifies whether your program connects automatically to the default user account.

Syntax

AUTO_CONNECT={YES|NO}

Default

NO

Usage Notes

Cannot be entered inline.

When AUTO_CONNECT=YES, as soon as Pro*COBOL encounters an executable SQL statement, your program tries to log on to Oracle automatically with the userid

<prefix><username> 

where prefix is the value of the Oracle initialization parameter OS_AUTHENT_PREFIX (the default value is OPS$) and username is your operating system user or task name. In this case, you cannot override the default value for MAXOPENCURORS (10), even if you specify a different value on the command line.

When AUTO_CONNECT=NO (the default), you must use the CONNECT statement to logon to Oracle.

CLOSE_ON_COMMIT

Purpose

Specifies whether or not all cursors declared without the WITH HOLD clause are closed on commit.

Syntax

CLOSE_ON_COMMIT={YES | NO}

Default

NO

Usage Notes

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

This option will only have an effect when a cursor is not coded using the WITH HOLD clause in a DECLARE CURSOR statement, since that will override both the new option and the existing behavior which is associated with the MODE option. If MODE is specified at a higher level than CLOSE_ON_COMMIT, then MODE takes precedence. For example, the defaults are MODE=ORACLE and CLOSE_ON_COMMIT=NO. If the user specifies MODE=ANSI on the command line, then any cursors not using the WITH HOLD clause will be closed on commit.

Issuing a COMMIT or ROLLBACK closes all explicit cursors. (When MODE={ANSI13|ORACLE}, a commit or rollback closes only cursors referenced in a CURRENT OF clause.)

For a further discussion of the precedence of this option see "Macro and Micro Options" on page 7-4.

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.

Pro*COBOL can use a configuration file containing preset command-line options. However, you can specify any of several alternative files, called user configuration files. For more information, see "Configuration Files" on page 7-6.

You cannot nest configuration files. Therefore, you cannot specify the option CONFIG in a configuration file.

DATE_FORMAT

Purpose

Species the string format in which dates are returned.

Syntax

DATE_FORMAT={ISO | USA | EUR | JIS | LOCAL | 'fmt' (default LOCAL)

Default

LOCAL

Usage Notes

Can only be entered on the command line or in a configuration file. The date strings are shown in the following table:

Table 7-3 Formats for Date Strings
Format Name   Abbreviation   Date Format  

International Standards Organization

 

ISO

 

yyyy-mm-dd

 

USA standard

 

USA

 

mm/dd/yyyy

 

European standard

 

EUR

 

dd.mm.yyyy

 

Japanese Industrial Standard

 

JIS

 

yyyy-mm-dd

 

installation-defined

 

LOCAL

 

Any installation-defined form.

 

`fmt' is a date format model, such as 'Month dd, yyyy'. See the Oracle8 SQL Reference for the list of date format model elements.

There is one restriction on the use of the DATE_FORMAT option: All compilation units to be linked together must use the same DATE_FORMAT value. An error occurs when there is a mismatch in the values of DATE_FORMAT across compilation units

DBMS

Purpose

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

Syntax

DBMS={NATIVE|V7| V8}

Default

NATIVE

Usage Notes

Cannot be entered inline.

With the DBMS option you control the version-specific behavior of Oracle. When DBMS=NATIVE (the default), Oracle follows the semantic and syntactic rules of the native version of Oracle.

Table 7-4 shows how the compatible DBMS and MODE settings interact. All other combinations are incompatible or not recommended.

Table 7-4 How DBMS and MODE Interact

Situation

 

DBMS=V7 or V8

MODE=ANSI

 

DBMS=V7 or V8

MODE=ORACLE

 

fetch truncated values without using indicator variables

 

no error but

SQLWARN(2) is set

 

no error but

SQLWARN(2) is set

 

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 multi-row query is called

 

FETCH time

 

FETCH time

 

declare SQLCA structure

 

optional

 

required

 

declare SQLCODE or SQLSTATE status variable

 

required

 

optional but Oracle ignores

 

external datatype code DESCRIBE returns (dynamic SQL Method 4)

 

96

 

96

 

integrity constraints

 

enabled

 

enabled

 

PCTINCREASE for rollback segments

 

not allowed

 

not allowed

 

MAXEXTENTS storage parameters

 

not allowed

 

not allowed

 

Notes:

1. Includes ANSI13.

2. Includes ANSI14 and ANSI13.

DECLARE_SECTION

Purpose

Specifies whether or not only declarations in a Declare Section are allowed as host variables.

Syntax

DECLARE_SECTION={YES | NO}

Default

NO

Usage Notes

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

When MODE=ORACLE, use of the BEGIN DECLARE SECTION and END DECLARE SECTION statements are optional, starting with release 8.0 of Pro*COBOL. The DECLARE_SECTION option is provided for backward compatibility with previous releases. DECLARE_SECTION is a micro option of MODE. For a discussion of precedence of this option, see "Macro and Micro Options" on page 7-4.

DEFINE

Purpose

Specifies a user-defined symbol that is used to include or exclude portions of source code during a conditional precompilation. For more information, see "Conditional Precompilations" on page 7-39.

Syntax

DEFINE=symbol

Default

None

Usage Notes

If you enter DEFINE inline, the EXEC ORACLE statement takes the following form:

EXEC ORACLE DEFINE <symbol> END-EXEC.

END_OF_FETCH

Purpose

Specifies which SQLCODE value is returned when an END-OF-FETCH condition occurs after execution of a SQL statement.

Syntax

END_OF_FETCH={100 | 1403}

Default

1403

Usage Notes

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

If you specify MODE=ANSI in a configuration file, Pro*COBOL returns the SQLCODE value 100 at the END_OF_FETCH, overriding the default END_OF_FETCH=1403. If you specify MODE=ANSI and END_OF_FETCH=1403 in the configuration file, then Pro*COBOL will return the SQLCODE value 1403 at the END_OF_FETCH. If you specify MODE=ANSI in the configuration file and END_OF_FETCH=1403 on the command line, Pro*COBOL will again return the SQLCODE value 1403 at the END_OF_FETCH.

END_OF_FETCH is a micro option of MODE. For further discussion, see "Macro and Micro Options" on page 7-4.

ERRORS

Purpose

Specifies whether Pro*COBOL error messages are sent to the terminal and listing file or only to the listing file.

Syntax

ERRORS={YES|NO}

Default

YES

Usage Notes

When ERRORS=YES, error messages are sent to the terminal and listing file.

When ERRORS=NO, error messages are sent only to the listing file.

FIPS

Purpose

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

Syntax

FIPS={YES|NO}

Default

NO

Usage Notes

When FIPS=YES, the FIPS Flagger issues warning (not error) messages if you use an Oracle extension to the ANSI/ISO embedded SQL standard (SQL92) or use a SQL92 feature in a nonconforming manner.

The following extensions to ANSI/ISO SQL are flagged at precompile time:

FORMAT

Purpose

Specifies the format of COBOL input lines.

Syntax

FORMAT={ANSI|TERMINAL}

Default

ANSI

Usage Notes

Cannot be entered inline.

The format of input lines is system-dependent. Check your system-specific Oracle manuals.

When FORMAT=ANSI, the format of input lines conforms as much as possible to the current ANSI standard for COBOL. When FORMAT=TERMINAL, input lines start with column 7. Example code in this book is in TERMINAL format. See "Coding Area" on page 3-2 for a more complete description.

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

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

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, Pro*COBOL 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; Pro*COBOL 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 re-parse 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 opening 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 4-11.

HOST

Purpose

Specifies the host language to be used.

Syntax

HOST={COB74|COBOL}

Default

COBOL

Usage Notes

Cannot be entered inline.

COB74 refers to the 1974 version of ANSI-approved COBOL. COBOL refers to the 1985 version. Other values might be available on your platform.

INAME

Purpose

Specifies the name of the input file.

Syntax

INAME=filename

Default

None

Usage Notes

Cannot be entered inline.

When specifying the name of your input file on the command line, the keyword INAME is optional. For example, in Pro*COBOL, you can specify myprog.pco instead of INAME=myprog.pco.

Pro*COBOL assumes the standard input file extension, pco. So, you need not use a file extension when specifying INAME unless the extension is nonstandard. For Pro*COBOL, if you use a nonstandard input file extension when specifying INAME, you must also specify HOST.

INCLUDE

Purpose

Specifies a directory path for EXEC SQL INCLUDE files. It only applies to operating systems that use directories.

Syntax

INCLUDE=path

Default

Current directory

Usage Notes

Typically, you use INCLUDE to specify a directory path for the SQLCA and ORACA files. Pro*COBOL searches first in the current directory, then in the directory specified by INCLUDE, and finally in a directory for standard INCLUDE files. Hence, you need not specify a directory path for standard files such as the SQLCA and ORACA.

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

... INCLUDE=<path1> INCLUDE=<path2> ... 

Pro*COBOL searches first in the current directory, then in the directory named by path1, then in the directory named by path2, and finally in the directory for standard INCLUDE files.

Remember, Pro*COBOL looks for a file in the current directory first-even if you specify a directory path. So, if the file you want to INCLUDE resides in another directory, make sure no file with the same name resides in the current directory.

The syntax for specifying a directory path is system-specific. Follow the conventions of your operating system.

IRECLEN

Purpose

Specifies the record length of the input file.

Syntax

IRECLEN=integer

Default

80

Usage Notes

Cannot be entered inline.

The value you specify for IRECLEN should not exceed the value of ORECLEN. The maximum value allowed is system-dependent.

LITDELIM

Purpose

The LITDELIM option specifies the delimiters for string constants and literals in the COBOL code generated by Pro*COBOL.

Syntax

LITDELIM={APOST|QUOTE}

Default

QUOTE

Usage Notes

When LITDELIM=APOST, Pro*COBOL uses apostrophes when generating COBOL code. If you specify LITDELIM=QUOTE, quotation marks are used, as in

     CALL "SQLROL" USING SQL-TMP0. 

In SQL statements, you must use quotation marks to delimit identifiers containing special or lowercase characters, as in

     EXEC SQL CREATE TABLE "Emp2" END-EXEC. 

but you must use apostrophes to delimit string constants, as in

     EXEC SQL SELECT ENAME FROM EMP WHERE JOB = 'CLERK' END-EXEC.

Regardless of which delimiters are used in the Pro*COBOL source file, Pro*COBOL generates the delimiters specified by the LITDELIM value.

LNAME

Purpose

Specifies a non-default name for the listing file.

Syntax

LNAME=filename

Default

input.LIS, where input is the base name of the input file.

Usage Notes

Cannot be entered inline.

By default, the listing file is written to the current directory.

LRECLEN

Purpose

Specifies the record length of the listing file.

Syntax

LRECLEN=integer

Default

132

Usage Notes

Cannot be entered inline.

The value of LRECLEN can range from 80 through 255. If you specify a value below the range, 80 is used instead. If you specify a value above the range, 255 is used instead. LRECLEN should exceed IRECLEN by at least 8 to allow for the insertion of line numbers.

LTYPE

Purpose

Specifies the listing type.

Syntax

LTYPE={LONG|SHORT|NONE}

Default

LONG

Usage Notes

Cannot be entered inline.

LTYPE=LONG

 

input lines appear in the listing file.

 

LTYPE=SHORT

 

input lines do not appear in the listing file.

 

LTYPE=NONE

 

no listing file is created.

 

MAXLITERAL

Purpose

Specifies the maximum length of string literals generated by Pro*COBOL so that compiler limits are not exceeded. For example, if your compiler cannot handle string literals longer than 132 characters, you can specify MAXLITERAL=132 on the command line.

Syntax

MAXLITERAL=integer

Default

The default is 256.

Usage Notes

The maximum value of MAXLITERAL is compiler-dependent. The default value is language-dependent, but you might have to specify a lower value. For example, some COBOL compilers cannot handle string literals longer than 132 characters, so you would specify MAXLITERAL=132.

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

You can enter MAXLITERAL inline but your program can set its value just once, and the EXEC ORACLE statement must precede the first EXEC SQL statement. Otherwise, Pro*COBOL issues a warning message, ignores the extra or misplaced EXEC ORACLE statement, and continues processing.

MAXOPENCURSORS

Purpose

Specifies the number of concurrently open cursors that Pro*COBOL tries to keep cached.

Syntax

MAXOPENCURSORS=integer

Default

10

Usage Notes

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

When precompiling separately, use MAXOPENCURSORS as described in "Separate Precompilations" on page 7-41.

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. To avoid a "maximum open cursors exceeded" Oracle error, MAXOPENCURSORS must be lower than OPEN_CURSORS by at least 6.

As your program's need for concurrently open cursors grows, you might want to re-specify 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 SQL standard.

Syntax

MODE={ANSI|ISO|ANSI14|ISO14|ANSI13|ISO13|ORACLE}

Default

ORACLE

Usage Notes

Cannot be entered inline.

The following pairs of MODE values are equivalent: ANSI and ISO, ANSI14 and ISO14, ANSI13 and ISO13.

When MODE=ORACLE (the default), your embedded SQL program observes Oracle practices.

When MODE={ANSI14|ANSI13}, your program complies closely with the current ANSI SQL standard.

When MODE=ANSI, your program complies fully with the ANSI standard and the following changes go into effect:

When MODE={ANSI|ANSI14}, a 4-byte integer variable named SQLCODE or a 5-byte character variable named SQLSTATE must be declared. For more information, see "Error Handling Alternatives" on page 9-2.

Table 7-4 shows how the MODE and DBMS settings interact. Other combinations are incompatible or are not recommended.

NLS_LOCAL

Purpose

The NLS_LOCAL option determines whether NLS character conversions are performed by the Pro*COBOL runtime library or by the Oracle Server.

Syntax

NLS_LOCAL={YES|NO}

Default

NO

Usage Notes

Cannot be entered inline.

When NLS_LOCAL=YES, the runtime library (SQLLIB) locally performs blank-padding and blank-stripping for host variables that have multi-byte NLS datatypes. Continue to use this value only for Pro*COBOL applications written for previous releases that have not been updated for Oracle8.

When NLS_LOCAL=NO, blank-padding and blank-stripping operations are performed by the Oracle Server for host variables that have multi-byte NLS datatypes. Use for all new Oracle8, or later, applications.

ONAME

Purpose

Specifies the name of the output file.

Syntax

ONAME=filename

Default

System-dependent

Usage Notes

Cannot be entered inline.

Use this option to specify the name of the output file, where the name differs from that of the input file. For example, if you issue

procob INAME=my_test

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

procob INAME=my_test ONAME=my_test_1.cob 

Note that you should add the .cob extension to files specified using ONAME. There is no default extension with the ONAME option.

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

When ORACA=YES, you must place the INCLUDE ORACA statement in your program.

ORECLEN

Purpose

Specifies the record length of the output file.

Syntax

ORECLEN=integer

Default

80

Usage Notes

Cannot be entered inline.

The value you specify for ORECLEN should equal or exceed the value of IRECLEN. The maximum value allowed is system-dependent.

PAGELEN

Purpose

Specifies the number of lines per physical page of the listing file.

Syntax

PAGELEN=integer

Default

66

Usage Notes

Cannot be entered inline. The maximum value allowed is system-dependent.

PICX

Purpose

Specifies the default datatype of PIC X variables.

Syntax

PICX={CHARF | VARCHAR2}

Default

CHARF

Usage Notes

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

Starting in Pro*COBOL 8.0, the default datatype of PIC X, N, or G variables is changed from VARCHAR2 to CHARF. PICX is provided for backward compatibility.

This new default behavior is consistent with the normal COBOL move semantics. Note that this is a change in behavior for the case where you are inserting a PIC X variable (with MODE=ORACLE) into a VARCHAR2 column. Any trailing blanks which had formerly been trimmed will be preserved. Note also, that the new default lessens the occurrence of the following anomaly: Using a PIC X bind variable initialized with trailing blanks in a WHERE clause would never match a value with the same number of trailing blanks which was stored in a char column because the bind variable's trailing blanks were stripped before the comparison.

When PICX=VARCHAR2, Oracle treats local CHAR variables in a PL/SQL block like variable-length character values. When PICX=CHARF, however, Oracle treats the CHAR variables like ANSI-compliant, fixed-length character values.

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

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

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, Pro*COBOL 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. Pro*COBOL 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 re-parse 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 opening 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 4-11.

SELECT_ERROR

Purpose

Specifies whether your program generates an error when a single-row 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

When SELECT_ERROR=YES, an error is generated if a single-row select returns too many rows or an array select returns more rows than the host array can accommodate.

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. To ensure a specific ordering of rows, 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 if you are selecting into an array. When SELECT_ERROR=YES, whether or not you use ORDER BY, an error is generated if too many rows are returned.

SQLCHECK

Purpose

Specifies the type and extent of syntactic and semantic checking.

Syntax

SQLCHECK={SEMANTICS|FULL|SYNTAX|LIMITED|NONE}

Default

SYNTAX

Usage Notes

The values SEMANTICS and FULL are equivalent, as are the values SYNTAX and LIMITED.

Pro*COBOL can help you debug a program by checking the syntax and semantics of embedded SQL statements and PL/SQL blocks. Any errors found are reported at precompile time.

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=NONE on the command line, you cannot specify SQLCHECK=SYNTAX inline.

If SQLCHECK=SYNTAX|SEMANTICS, Pro*COBOL generates an error when PL/SQL reserved words are used in SQL statements, even though the SQL statements are not themselves PL/SQL. If a PL/SQL reserved word must be used as an identifier, you can enclose it in double-quotes.

When SQLCHECK=SEMANTICS, Pro*COBOL checks the syntax and semantics of

However, Pro*COBOL checks only the syntax of remote data manipulation statements (those using the AT db_name clause).

Pro*COBOL gets the information for a semantic check from embedded DECLARE TABLE statements or, if you specify the option USERID, 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 information cannot be found in the data dictionary, you must use DECLARE TABLE statements to supply the missing information. During precompilation, a DECLARE TABLE definition overrides a data dictionary definition if they conflict.

Specify SQLCHECK=SEMANTICS when precompiling new programs. If you embed PL/SQL blocks in a host program, you must specify SQLCHECK=SEMANTICS and the option USERID.

When SQLCHECK=SYNTAX, Pro*COBOL checks the syntax of

No semantic checking is done. DECLARE TABLE statements are ignored and PL/SQL blocks are not allowed. When checking data manipulation statements, Pro*COBOL uses Oracle8 syntax rules, which are downwardly compatible. Specify SQLCHECK=SYNTAX when migrating your precompiled programs.

When SQLCHECK=NONE, no syntactic or semantic checking is done. DECLARE TABLE statements are ignored and PL/SQL blocks are not allowed. Specify SQLCHECK=NONE if your program

Table 7-6 summarizes the checking done by SQLCHECK. For more information about syntactic and semantic checking, see Appendix E, "Syntactic and Semantic Checking".

  SQLCHECK=SEMANTICS   SQLCHECK=SYNTAX   SQLCHECK=NONE  

 

Syntax

 

Semantics

 

Syntax

 

Semantics

 

Syntax

 

Semantics

 

DML

 

X

 

X

 

X

 

 

 

 

Remote DML

 

X

 

 

X

 

 

 

 

PL/SQL

 

X

 

X

 

 

 

 

 

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

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.

When UNSAFE_NULL=YES, 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 UNSAFE_NULL=NO, 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 ORA-01405).

USERID

Purpose

Specifies an Oracle username and password.

Syntax

USERID=username/password

Default

None

Usage Notes

Cannot be entered inline.

Do not specify this option when using the automatic logon feature, which accepts your Oracle username prefixed with the value of the Oracle initialization parameter OS_AUTHENT_PREFIX.

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

VARCHAR

Purpose

The VARCHAR option instructs Pro*COBOL to treat the COBOL group item described in Chapter 5, "Using Embedded SQL" as a VARCHAR datatype.

Syntax

VARCHAR={YES|NO}

Default

NO

Usage Notes

Cannot be entered inline.

When VARCHAR=YES, the implicit group item described in Chapter 5, "Using Embedded SQL" is accepted as an Oracle8 VARCHAR external datatype with a length field and a string field.

When VARCHAR=NO, Pro*COBOL does not accept the implicit group items as VARCHAR external datatypes.

XREF

Purpose

Specifies whether a cross-reference section is included in the listing file.

Syntax

XREF={YES|NO}

Default

YES

Usage Notes

When XREF=YES, cross references are included for host variables, cursor names, and statement names. The cross references show where each object is defined and referenced in your program.

When XREF=NO, the cross-reference section is not included.

Conditional Precompilations

Conditional precompilation includes (or excludes) sections of code in your host program based on certain conditions. For example, you might want to include one section of code when precompiling under UNIX and another section when precompiling under VMS. Conditional precompilation 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 host-language statements as well as EXEC SQL statements in these sections. The following statements let you exercise conditional control over precompilation:

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

All EXEC ORACLE statements must be terminated with the statement terminator for your host language. For example, in Pro*COBOL, a conditional statement must be terminated with END-EXEC.

An Example

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

     EXEC ORACLE IFDEF SITE2 END-EXEC. 
     EXEC SQL SELECT DNAME 
        INTO :DEPT-NAME 
        FROM DEPT 
        WHERE DEPTNO = :DEPT-NUMBER
     EXEC ORACLE ENDIF END-EXEC. 

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

     EXEC ORACLE IFDEF OUTER END-EXEC. 
     EXEC ORACLE IFDEF INNER END-EXEC. 
     ... 
     EXEC ORACLE ENDIF END-EXEC. 
     EXEC ORACLE ENDIF END-EXEC. 

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

Defining Symbols

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

     EXEC ORACLE DEFINE symbol END-EXEC.

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.

Some port-specific symbols are predefined for you when the Oracle Precompilers are installed on your system. For example, predefined operating system symbols include CMS, MVS, MS-DOS, UNIX, and VMS.

Separate Precompilations

You can precompile several COBOL program modules separately, then link them into one executable program. This supports modular programming, which is required when the functional components of a program are written and debugged by different programmers. The individual program modules need not be written in the same language.

Guidelines

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 it for another program module, 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 globally in one of the program modules.

Using a Single DATE_FORMAT

You must use the same format string for DATE in each program module.

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 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 get an executable program, you must compile the source file(s) produced by Pro*COBOL, then link the resulting object module with any modules needed from SQLLIB and system-specific Oracle libraries. Also, if you are embedding OCI calls, make sure to link in the OCI runtime library (OCILIB).

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 you might have problems. Check with Oracle Customer Support to see if the software is supported.

Compiling and linking are system-dependent. For example, on some systems, you must turn off compiler optimization when compiling a host language program. For instructions, see your system-specific Oracle manuals.




Prev

Next
Oracle
Copyright © 1997 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index