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.

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:

• It is declared with exactly the right datatype.

• Pro*COBOL finds no other status variable. If Pro*COBOL finds a SQLSTATE declaration (of exactly the right type of course), or finds an include of a SQLCA, then it will not presume SQLCODE is declared.

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.

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.

Purpose

Specifies the character set form used by PIC X variables used in select, insert, or update statements.

Syntax

CHARSET_PICX={NCHAR_CHARSET | DB_CHARSET }

Default

DB_CHARSET

Usage Notes

Can be used on the command line or in a configuration file, but not inline.

If CHARSET_PICX = NCHAR_CHARSET, the PIC X bind or define buffer is converted according to the server-side National Character Set. Possible performance impact might be seen when target column is CHAR. Similarly, if CHARSET_PICX = DB_CHARSET, the PIC X bind or define buffer is converted according to server-side Database Character Set. There can be some data loss when target column is NCHAR.

Purpose

Specifies the character set form used by PIC N variables used in select, insert, or update statements.

Syntax

CHARSET_PICN={NCHAR_CHARSET | DB_CHARSET }

Default

NCHAR_CHARSET

Usage Notes

Can be used on the command line or in a configuration file, but not inline.

If CHARSET_PICN = DB_CHARSET, the PIC N bind or define buffer is converted according to the server-side Database Character Set. There can be some data loss when target column is NCHAR. Similarly, if CHARSET_PICN = NCHAR_CHARSET, the PIC N bind or define buffer is converted according to server-side National Character Set. Possible performance impact might be seen when target column is CHAR.

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.

When CLOSE_ON_COMMIT=NO (when MODE=ORACLE), issuing a COMMIT or ROLLBACK will close only cursors that are declared using the FOR UPDATE clause or are referenced in a CURRENT OF clause. Other cursors are not affected by the COMMIT or ROLLBACK statement, remain open, if they are open already. However, when CLOSE_ON_COMMIT=YES (when MODE=ANSI), issuing a COMMIT or ROLLBACK closes all cursors.

For a further discussion of the precedence of this option see “Macro and Micro Options”.

Purpose

Specifies that the SQL99 syntax for SELECT, INSERT, DELETE, UPDATE and body of the cursor in a DECLARE CURSOR statement will be supported.

Syntax

COMMON_PARSER={YES | NO}

Default

NO

Usage Notes

Can be entered in the command line.

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 “Entering Precompiler Options”.

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

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:

'fmt' is a date format model, such as "Month dd, yyyy". See “Datetime Format Elements” 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

Purpose

Based on this option, the precompiler activates the additional array insert/select syntax.

Syntax

DB2_ARRAY={YES |NO}

Default

NO

Usage Notes

If this option is set to NO, the Oracle precompiler syntax is supported, otherwise the DB2 insert/select array syntax is supported.

Purpose

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

Syntax

DBMS={V7 | V8 | NATIVE}

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.

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.

This option allows the user to specify MODE=ORACLE together with DECLARE_SECTION=YES to get the same effect that previous releases provided when using MODE=ORACLE alone. (Only variables declared inside the DECLARE statements are allowed as host variables.) For a discussion of precedence of this option, see “Precedence of Option Values”.

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”

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.

Purpose

This micro option of MODE specifies the descriptor behavior in dynamic SQL Method 4.

Syntax

DYNAMIC={ORACLE | ANSI}

Default

ORACLE

Usage Notes

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

See the DYNAMIC option settings in “ANSI Dynamic SQL Precompiler Options”.

Purpose

This micro option of MODE 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.

END_OF_FETCH is a micro option of MODE. For further discussion, see “Macro and Micro Options”.

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, which has a higher precedence than your configuration file, Pro*COBOL will again return the SQLCODE value 1403 at the END_OF_FETCH.

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.

Purpose

Denotes the unique identifier for the generated Cobol file. The generated files contain a unique number associated with the "SQLCTX" variable. The file_id option can be used to set the value of the SQLCTX variable. The option is useful while precompiling multiple source files, so that the user can ensure unique SQLCTX values associated with the different generated files.

Syntax

FILE_ID=Range is 0 to 65535

Default

0

Usage Notes

The file_id option can be used to directly assign values to "SQLCTX" variable in the generated Cobol file.

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 Entry level of SQL-92 or use a feature of Entry level SQL-92 in a nonconforming manner.

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

• 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, COMP-3, NUMBER, RAW, LONG RAW, VARRAW, ROWID, and VARCHAR datatypes

• ORACLE OPTION statement for specifying runtime options

• EXEC TOOLS 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 and STOP 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...DO labels and of host variables in the INTO clause

Purpose

Specifies the format of COBOL statements.

Syntax

FORMAT={ANSI | TERMINAL | VARIABLE}

Default

ANSI

Usage Notes

Cannot be entered inline.

The format of input lines is system-dependent. Check your system-specific Oracle manuals, or your COBOL compiler.

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 can start in column 1. Example code in this book is in TERMINAL format. Use FORMAT=VARIABLE to allow Flexible B Area Length. See “Coding Areas” for a more complete description.

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 “Performance Tuning”.

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

For information showing how the HOLD_CURSOR and RELEASE_CURSOR options interact, see “Performance Tuning”.

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.

Purpose

Controls whether an implicit savepoint is taken prior to the start of a new batched insert.

Syntax

implicit_svpt={YES|NO}

Default

NO

Usage Notes

If yes, a savepoint is taken prior to the start of a new batch of rows. If an error occurs on the insert, an implicit "rollback to savepoint" is executed. This option exists for DB2 compatibility, the obvious downside being the extra round-trip.

If no, there is no implicit savepoint taken. If an error occurs on the buffered insert, then it is reported back to the application, but no rollback is executed.

Purpose

Specifies the name of the input file.

Syntax

INAME=filename

Default

None

Usage Notes

Cannot be entered inline.

All input file names must be unique at precompilation time.

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.

You need not use a file extension when specifying INAME unless the extension is nonstandard. On the UNIX platform, Pro*COBOL assumes the default input file extension pco.

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

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.

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.

Note: Pro*COBOL looks for a file in the current directory first—even if you specify a directory path. Therefore, 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.

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.

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.

Purpose

Specifies a nondefault name for the listing file.

Syntax

LNAME=filename

Default

Input

Usage Notes

Cannot be entered inline.

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

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 132. If you specify a value below the range, 80 is used instead. If you specify a value above the range, an error occurs. LRECLEN should exceed IRECLEN by at least 8 to allow for the insertion of line numbers.

Purpose

Specifies the listing type.

Syntax

LTYPE={LONG | SHORT | NONE}

Default

LONG

Usage Notes

Cannot be entered inline.

Purpose

Controls the number of rows that need to be buffered before executing the INSERT statement.

Syntax

max_row_insert={0...1000}

Default

0

Usage Notes

Any number greater than zero enables buffered insert feature and buffers that many rows before executing the INSERT statement.

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

1024

Usage Notes

The maximum value of MAXLITERAL is compiler-dependent. The default value is language-dependent, but you may 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.

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 “Performance Tuning”.

When precompiling separately, use MAXOPENCURSORS as described in “Separate Precompilations”.

MAXOPENCURSORS specifies the initial size of the SQLLIB cursor cache.

When an implicit statement is executed and HOLD_CURSOR=NO, or an explicit cursor is closed, the cursor entry is marked as reusable. If this statement is issued again and the cursor entry has not been used for another statement, it is reused.

If a new cursor is needed and the number of cursors allocated is less than MAXOPENCURSORS, then the next one in the cache is allocated. Once MAXOPENCCURSORS has been exceeded, Oracle first tries to reuse a previous entry. If there are no free entries, then an additional cache entry is allocated. Oracle continues to do this until the program runs out of memory or the database parameter OPEN_CURSORS is exceeded.

During normal processing, when using HOLD_CURSOR=NO and RELEASE_CURSOR=NO (the default), it is advisable to set MAXOPENCURSORS to no more than 6 less than the database parameter OPEN_CURSORS to allow for the cursors used by the data dictionary to process statements.

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.

Purpose

This macro option 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:

• You cannot open a cursor that is already open or CLOSE a cursor that is already closed. (When MODE=ORACLE, you can reOPEN an open cursor to avoid re-parsing.)

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

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

Purpose

Indicates whether GLOBAL clauses in nested programs are to be generated. If the compiler supports nested programs, use YES as the value of NESTED.

Syntax

NESTED={YES | NO}

Default

YES

Usage Notes

Cannot be entered inline.

Purpose

The NLS_LOCAL option determines whether Globalization Support (formerly called 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.

This option is for use when passing National Character Set variables to and from the server.

When NLS_LOCAL=YES, the runtime library (SQLLIB) locally performs blank-padding and blank-stripping for host variables that have multibyte Globalization Support datatypes. Continue to use this value only for Pro*COBOL applications written for releases before releases 8.0.

When NLS_LOCAL=YES, because dynamic SQL statements are not processed at precompile time, this option has no effect on dynamic SQL statements.

Also, when NLS_LOCAL=YES, columns storing multibyte Globalization Support data cannot be used in embedded data definition language (DDL) statements. This restriction cannot be enforced when precompiling, so the use of these column types within embedded DDL statements results in an execution error rather than a precompile error.

When NLS_LOCAL=NO, blank-padding and blank-stripping operations are performed by the Oracle Server for host variables that have multibyte Globalization Support datatypes. Use for all new release 8.0, or later, applications.

The environment variable NLS_NCHAR specifies the character set used for National Character Set data. (NCHAR, NVARCHAR2, NCLOB). If it is not specified, the character set defined or defined indirectly by NLS_LANG will be used. See “Setting Up a Globalization Support Environment” for details.

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.

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.

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.

Purpose

Indicates that the outline SQL file needs to be generated for the SQL statements.

Syntax

outline={yes | no | category_name}

Default

no

Usage Notes

The outline SQL file should be in the DEFAULT category if the value is yes and the generated outline format is

DEFAULT_<filename>_<filetype>_<sequence_no>

If the category name is mentioned, then the SQL file should be generated in the category mentioned. The generated outline format for this is

<category_name>_<filename>_<filetype>_<sequence_no>

The outline SQL file is not generated if the value is no.

Semantic check should be full when this option is turned on, which means option sqlcheck=full/semantics. If sqlcheck=syntax/limited/none, then error will be generated.

Purpose

Controls the generation of the outline names.

Syntax

outlnprefix={none | prefix_name}

Default

no

Usage Notes

If outlnprefix=prefix_name, then the outline format

<category_name>_<filename>_<filetype>

is replaced with <prefix_name> for the outline names.

If the length of the outline name exceeds 128 bytes, then this option is helpful for the user who can just specify the prefix name.

If outlnprefix=none, then the outline names are generated by the system. The generated format is

<category_name>_<filename>_<filetype>_<sequence_no>

Semantic check should be full when this option is turned on, which means option sqlcheck=full/semantics. If sqlcheck=syntax/limited/none, and/or outline=false, then error will be generated.

Purpose

Specifies the number of lines for each physical page of the listing file.

Syntax

PAGELEN=integer

Default

66

Usage Notes

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

Purpose

Maintains platform endianness (little endian for Linux and Windows; big endian for Solaris) in PIC N variables.

Syntax

picn_endian={BIG | OS}

Default

BIG

Usage Notes

If picn_endian=big, then PIC N variables are bound with character set ID AL16UTF16.

If picn_endian=os then PIC N variables are bound with character set ID UCS2.

The default value for this option is "big" to preserve the current behavior. This option is ignored if NLS_NCHAR is not AL16UTF16.

Character set form for PIC N variables can be set by using the existing Pro*Cobol command line option: charset_picn={nchar_charset | db_charset}

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 was 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. See “Default for PIC X” for an extensive discussion.

Purpose

Creates a SQL Plan Baseline by specifying the module name.

Syntax

PLAN_BASELINE={module_name | YES | NO}

Default

NO

Usage Notes

The module name will become a part of the unique plan name generated by appending the filename, file type, and sequence number.

Purpose

Ensures that the plan name does not exceed 128 bytes.

Syntax

PLAN_PREFIX={prefix_name | none}

Default

none

Usage Notes

It is an optional command. The default is none which means that no prefix name is used, and if the plan name exceeds 128 bytes an error message is generated.

Purpose

Executes the generated SQL file.

Syntax

PLAN_RUN={YES | NO}

Default

NO

Usage Notes

If the PLAN_RUN option is not set then the generated SQL file is not executed.

Purpose

Specifies whether or not the created plan baseline is fixed or non-fixed.

Syntax

PLAN_FIXED={ YES | NO }

Default

YES

Usage Notes

When set to NO, a non-fixed Plan Baseline is created.

Purpose

Enables the use of the Plan Baseline that is created.

Syntax

PLAN_ENABLED={ YES | NO }

Default

YES

Usage Notes

When set to the default, YES, the created Plan Baseline is used for plan selection. When set to NO, the Plan Baseline is created, but is not used until enabled manually.

Purpose

Use this option to speed up queries by pre-fetching the number of rows that can be accommodated in the specified memory.

Syntax

MEMFORPREFETCH=integer

Default

No value set.

Usage Notes

This option can be used in configuration file or on the command line. The value of the integer is used for execution of all queries using explicit cursors, subject to the rules of precedence.

When used inline it must be placed before OPEN statements with explicit cursors. Then the number of rows pre-fetched when that OPEN is done is determined by the last in-line MEMFORPREFETCH option in effect.

The MEMFORPREFETCH default is no-value-is-set. To turn off prefetching, use MEMFORPREFETCH=0 on the command line.

Prefetching is turned off when LONG or LOB columns are being accessed. MEMFORPREFETCH is used to enhance the performance of single row fetches. MEMFORPREFETCH values have no effect when doing array fetches, regardless of which value is assigned.

There is no single perfect prefetch memory value that can be used to assist all the fetches in an application.

Therefore, when using the MEMFORPREFETCH option, you should test different values to give a general improvement across all statements in the program. Note that if certain statements need to be tuned individually, the MEMFORPREFETCH option can be specified inline using EXEC ORACLE OPTION. Note that this will affect all fetch statements that follow the command in your program. Select the appropriate prefetch memory to enhance the performance of any particular FETCH statement. To achieve this individual prefetch count, you should use the inline prefetch option rather than from the command line.

Purpose

Use this option to speed up queries by pre-fetching a given number of rows.

Syntax

PREFETCH=integer

Default

1

Usage Notes

Can be used in a configuration file or on the command-line. The value of the integer is used for execution of all queries using explicit cursors, subject to the rules of precedence.

When used in-line it must be placed before OPEN statements with explicit cursors. Then the number of rows pre-fetched when that OPEN is done is determined by the last in-line PREFETCH option in effect.

The PREFETCH default is 1. To turn off prefetching, use PREFETCH=0 on the command line.

Prefetching is turned off when LONG or LOB columns are being accessed. PREFETCH is used to enhance the performance of single row fetches. PREFETCH values have no effect when doing array fetches, regardless of which value is assigned.

There is no single perfect prefetch number that can be used to assist all the fetches in an application.

Therefore, when using the PREFETCH option, you should test different values to give a general improvement across all statements in the program. Note that if certain statements need to be tuned individually, the PREFETCH option can be specified in line using EXEC ORACLE OPTION. Note that this will affect all fetch statements that follow the command in your program. Select the appropriate prefetch number to enhance the performance of any particular FETCH statement. To achieve this individual prefetch count, you should use the inline prefetch option. (Rather than from the command line.)

The maximum value is 9999. See “The PREFETCH Precompiler Option” for further discussion.

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 .

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, 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. For information showing how these two options interact, see “Performance Tuning”.

Purpose

Provides the developer with the option of executing "create outline" statements either by using precompiler or by the developer manually at a later time.

Syntax

runoutline={yes | no}

Default

no

Usage Notes

If runoutline=yes, then the generated 'create outline' statements are executed by the precompiler/translator at the end of a successful precompilation.

The outline option should be set to true or category_name when runoutline is used. Semantic check should be full when this option is turned on, which means option sqlcheck=full/semantics. If sqlcheck=syntax/limited/none, then error will be generated.

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

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.

Purpose

Specifies the type and extent of syntactic and semantic checking..

When SQLCHECK=SEMANTICS or FULL, the SQL statements are packaged/bundled into an IDL objects using a generic grammar during parsing. The generic grammar will not try to understand the SQL syntax, it can only identify the host variables, indicator variables, and the possible SQL identifiers. During the semantic phase, the validity of the host and indicator variables are checked in the same manner it is now being done for SQL. The semantics like the table name ,column names,types will be checked in the same way it is now being handled for SQL.

The new unified parser:

1. Precompiles all the existing precompiler applications.

2. Supports the following SQL statements completely (all clauses of these SQL statements):

   1. SELELCT statement

   2. INSERT statement

   3. DELETE statement

   4. UPDATE statement

   5. Body of the cursor in a DECLARE CURSOR statement

Syntax

SQLCHECK={SEMANTICS | FULL | SYNTAX | LIMITED}

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 or on the command line, or both inline and 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.

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

• Data manipulation statements such as INSERT and UPDATE

• PL/SQL blocks

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=SEMANTICS or FULL, the SQL statements are first locally parsed. The verification of the host and indicator variables, and checking for the validity of SQL identifiers is done by using embedded DECLARE TABLE statement or by connecting to server when userid is specified in command line. Now the parsing is done twice when SQLCHECK = SEMANTICS or FULL once by the precompiler and once by the PL/SQL. When a new syntax is made available by SQL, the precompiler fails on the new syntax before calling PL/SQL interfaces if the local SQL grammar is not updated to accept the new syntax.

When SQLCHECK=SYNTAX, Pro*COBOL checks the syntax of data manipulation statements. The SQL statements are locally parsed. With this command line option, the precompiler does not verify the table name or column names. When SQLCHECK=SYNTAX, the syntax of the SQL statements is checked by using the client side SQL interface.

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 Oracle syntax rules, which are downwardly compatible. Specify SQLCHECK=SYNTAX when migrating your precompiled programs.

Table 14-5 summarizes the checking done by SQLCHECK. For more information about syntactic and semantic checking, see “Syntactic and Semantic Checking”.

Restrictions of Unified Parser

The restrictions of unified parser for Pro*COBOL are:

• Pro*COBOL does not support variables without a ':' (colon).

• Define tables cannot be used. In CSF mode, plsql fails when declare table statement is passed to plsql.

• The following example fails if sqlcheck=syntax and common_parser=yes is used:

  select ename into :empname from emp@dblink;
  

  In earlier versions, only local parsing is done when sqlcheck=syntax is used. But now when sqlcheck=syntax and common_parser=yes, the statement is just bundled and sent to pcisyn(). PLSQL fails if connection is not there when dblinks are used.

  The above statement can be precompiled with:

  sqlcheck=full userid=<userid> common_parser=yes
  

• Error handling for insert does not follow the usual sequence. Consider the following statement where XYZ is a group item.

  insert into emp (empno, ename) values (:XYZ)
  

  PLSQL does not allow group items or structures while doing syntax check for insert statements (restriction from PLSQL.). It expects that the group item be broken into the individual elements for inserts. So the precompiler should expand the above statement to insert into emp (empno, ename) values (:b1,:b2) in the syntax phase itself.

  This expansion is not possible in syntax phase. Therefore, pcisyn() is not called in syntax phase of precompiler the way it is done for other statements. The statement is deferred till semantic phase of precompiler for insert statement only. The net effect is that the error messages might not be following the usual sequence. For example:

  EXEC SQL insert into emp (empno, ename) alues (:XYZ) END-EXEC.
                                           ^^^^^ syntax error at 'alues'
   EXEC SQL select ename into :empname fro emp END-EXEC.  
                                       ^^^ syntax error at 'fro'
  

  Ideally error sequence should be as follows:

  syntax error at 'alues' in INSERT
  syntax error at 'fro' in SELECT
  

  Because of the restrictions discussed earlier, the error sequence will be:

  syntax error at 'fro' in SELECT
  syntax error at 'alues' in INSERT
  

  Note:

  The line numbers will be there in the reported errors. Therefore, Pro*Cobol programmers can identify the line very easily, even though it is not in the order used in the program.

Purpose

Denotes the Statement cache size for the dynamic SQL statements.

Syntax

STMT_CACHE = Range is 0 to 65535

Default

0

Usage Notes

The stmt_cache option can be set to hold the anticipated number of distinct dynamic SQL statements in the application.

Purpose

This micro option of MODE specifies whether ANSI or Oracle datatype codes are used in ANSI dynamic SQL method 4. Its setting is the same as the setting of MODE option.

Syntax

TYPE_CODE={ORACLE | ANSI}

Default

ORACLE

Usage Notes

Cannot be entered inline.

See the possible option settings in “TYPE_CODE Option Settings”.

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.

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

Purpose

Specifies an Oracle username and password.

Syntax

USERID=username/password[@dbname]

Default

None

Usage Notes

Cannot be entered inline.

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. The database alias is optional. Do not enter the brackets.

Purpose

The VARCHAR option instructs Pro*COBOL to treat the COBOL group item described in “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 “Embedded SQL” is accepted as a 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.

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.